DISCARD statement, tesets for this statement, and documentation

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__':

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}")

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.

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

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

shepherd/tests/testing_tests/discard_tests/instructions.shepherd

@@ -0,0 +1,2 @@
+TEST discard_server.shepherd
+TEST discard_client.shepherd