From ba26d7ca9b434bf8ebd2e76c0ce71fbf3b6062a8 Mon Sep 17 00:00:00 2001
From: Matthew Harrigan <betterthanbossfiredog5@gmail.com>
Date: Sun, 30 May 2021 11:14:43 -0700
Subject: [PATCH] DISCARD statement, tesets for this statement, and
 documentation

---
 shepherd/Tester.py                            | 19 ++++++++++++++++---
 shepherd/testing_script.py                    |  1 +
 shepherd/tests/TESTING_DOCS.md                |  8 ++++++++
 .../discard_tests/discard_client.shepherd     |  6 ++++++
 .../discard_tests/discard_server.shepherd     |  9 +++++++++
 .../discard_tests/instructions.shepherd       |  2 ++
 6 files changed, 42 insertions(+), 3 deletions(-)
 create mode 100644 shepherd/tests/testing_tests/discard_tests/discard_client.shepherd
 create mode 100644 shepherd/tests/testing_tests/discard_tests/discard_server.shepherd
 create mode 100644 shepherd/tests/testing_tests/discard_tests/instructions.shepherd

diff --git a/shepherd/Tester.py b/shepherd/Tester.py
index ec550924..ffd4944c 100644
--- a/shepherd/Tester.py
+++ b/shepherd/Tester.py
@@ -35,7 +35,7 @@ class (source).
 def parse_header(header):
     """
     A helper function that translates the headers in format
-    <LCM_targer>.<header> to the string representation stored in Utils.py.
+    <LCM_target>.<header> to the string representation stored in Utils.py.
     Enforces the syntax for referencing the header, as well as the existance of
     the header in Utils.py.
     """
@@ -369,7 +369,7 @@ def assert_function(expression):
 def sleep_function(expression):
     """
     The function that parses SLEEP statements.
-    Enforces syntax, and pauses the .shepherd interpreter for the specified
+    Enforces syntax and pauses the .shepherd interpreter for the specified
     number of seconds.
     """
     expression = remove_outer_spaces(expression)
@@ -381,6 +381,18 @@ def sleep_function(expression):
         raise Exception(f'expected a time afer after SLEEP, but got {expression}')
     time.sleep(amount)
 
+def discard_function(expression):
+    """
+    The function that parses DISCARD statements.
+    Enforces syntax and clears the LCM / YDL queue so that no outstanding requests
+    are processed.
+    """
+    global EVENTS
+    if expression != '':
+        raise Exception('expected nothing after DISCARD statement')
+    with EVENTS.mutex:
+        EVENTS.queue.clear()
+
 def read_function(line):
     """
     The function that parses READ statements.
@@ -716,7 +728,8 @@ def main():
             'FAIL': fail_function,
             'ASSERT': assert_function,
             '##': lambda line: None,
-            'SLEEP': sleep_function
+            'SLEEP': sleep_function,
+            'DISCARD': discard_function
             }
 
 if __name__ == '__main__':
diff --git a/shepherd/testing_script.py b/shepherd/testing_script.py
index 05a51851..c8c487ff 100644
--- a/shepherd/testing_script.py
+++ b/shepherd/testing_script.py
@@ -94,6 +94,7 @@ def start():
         # check for help flag
         if "-h" in sys.argv[1:] or "-help" in sys.argv[1:]:
             print("testing_script.py takes any number of the following arguments:")
+            print("leave args empty to run all tests.")
             print("  to run test groups:")
             for test_group in test_groups.keys():
                 print(f"    {test_group}")
diff --git a/shepherd/tests/TESTING_DOCS.md b/shepherd/tests/TESTING_DOCS.md
index 8a053eb5..a4da3a69 100644
--- a/shepherd/tests/TESTING_DOCS.md
+++ b/shepherd/tests/TESTING_DOCS.md
@@ -66,6 +66,14 @@ time may be a decimal, and is in terms of seconds. SLEEP may take a python expre
 
 Usage: `SLEEP <time / python expression>`
 
+### DISCARD
+
+The DISCARD statement clears the LCM / YDL of any messages that have been received so far, but have not been processed, ensuring that they will not
+be processed. This is helpful after a SLEEP statement, to ensure that any messages that were received during the sleep would be ignored, if that is
+the desired functionality.
+
+Usage: `DISCARD`
+
 ### IF
 
 The IF statement accepts a python conditional expression, which it evaluates. All normal python rules apply. The code following the IF statement will be executed only if the expression evaluates to True in python. The IF statement must be closed using and END statement.
diff --git a/shepherd/tests/testing_tests/discard_tests/discard_client.shepherd b/shepherd/tests/testing_tests/discard_tests/discard_client.shepherd
new file mode 100644
index 00000000..e6f2481b
--- /dev/null
+++ b/shepherd/tests/testing_tests/discard_tests/discard_client.shepherd
@@ -0,0 +1,6 @@
+READ LCM_TARGETS.SHEPHERD
+EMIT SCOREBOARD_HEADER.ALL_INFO TO LCM_TARGETS.SCOREBOARD
+SLEEP 3
+DISCARD
+WAIT SHEPHERD_HEADER.SETUP_MATCH FROM LCM_TARGETS.SHEPHERD WITH a = 'a'
+ASSERT a == 2
diff --git a/shepherd/tests/testing_tests/discard_tests/discard_server.shepherd b/shepherd/tests/testing_tests/discard_tests/discard_server.shepherd
new file mode 100644
index 00000000..4bc2f90a
--- /dev/null
+++ b/shepherd/tests/testing_tests/discard_tests/discard_server.shepherd
@@ -0,0 +1,9 @@
+READ LCM_TARGETS.SCOREBOARD
+WAIT SCOREBOARD_HEADER.ALL_INFO FROM LCM_TARGETS.SCOREBOARD
+RUN counter = 0
+WHILE counter < 10
+  EMIT SHEPHERD_HEADER.SETUP_MATCH TO LCM_TARGETS.SHEPHERD WITH 'a' = 1
+  RUN counter += 1
+END
+SLEEP 5
+EMIT SHEPHERD_HEADER.SETUP_MATCH TO LCM_TARGETS.SHEPHERD WITH 'a' = 2
diff --git a/shepherd/tests/testing_tests/discard_tests/instructions.shepherd b/shepherd/tests/testing_tests/discard_tests/instructions.shepherd
new file mode 100644
index 00000000..1f41a9c3
--- /dev/null
+++ b/shepherd/tests/testing_tests/discard_tests/instructions.shepherd
@@ -0,0 +1,2 @@
+TEST discard_server.shepherd
+TEST discard_client.shepherd