Implement definitions in checker.js (#470)

One problem with regexes is that by default they aren't
able to have named definitions like BNF.

Solve this by implementing "definitions". This only adds a few
more lines, but now we have a powerful way to create definitions,
while still being fast in execution.

Signed-off-by: David A. Wheeler <[email protected]>

Author: david-a-wheeler

docs/labs/checker.js

@@ -10,6 +10,7 @@ let correctRe = []; // Array of compiled regex of correct answer
 let expected = []; // Array of an expected (correct) answer
 let info = {}; // General info
 let hints = []; // Array of hint objects
+let page_definitions = {}; // Definitions used when preprocessing regexes
 
 // This array contains the default pattern preprocessing commands, in order.
 // We process every pattern through these (in order) to create a final regex
@@ -57,6 +58,18 @@ function trimNewlines(s) {
             .replace(/[\n\r]+$/, ''));
 }
 
+/**
+ * Apply all page_definitions to string s (which is presumably a regex
+ * in string form). These are simple text replacements.
+ */
+function processDefinitions(s) {
+    let result = s;
+    for (definition in page_definitions) {
+        result = result.replaceAll(definition, page_definitions[definition]);
+    };
+    return result;
+}
+
 /**
  * Escape unsafe HTML, e.g., & becomes &
  */
@@ -107,12 +120,16 @@ function showDebugOutput(debugOutput, alwaysAlert = true) {
 
 /**
  * Given take a regex string, preprocess it (using our array of
- * preprocessing regexes), and return a processed regex as a String.
+ * definitions and preprocessing regexes),
+ * and return a processed regex as a String.
  * @regexString - String to be converted into a compiled Regex
  * @fullMatch - require full match (insert "^" at beginning, "$" at end).
  */
 function processRegexToString(regexString, fullMatch = true) {
-    let processedRegexString = regexString;
+    // Replace all definitions. This makes regexes much easier to use,
+    // as we can now defined named fragments.
+    let processedRegexString = processDefinitions(regexString);
+    // Preprocess. This lets us define what whitespace etc. means.
     for (preprocessRegex of preprocessRegexes) {
         processedRegexString = processedRegexString.replace(
           preprocessRegex[0], preprocessRegex[1]
@@ -440,14 +457,21 @@ function processInfo(configurationInfo) {
 
     const allowedInfoFields = new Set([
         'hints', 'successes', 'failures', 'correct', 'expected',
-         'preprocessing', 'preprocessingTests', 'debug']);
+         'definitions', 'preprocessing', 'preprocessingTests', 'debug']);
     let usedFields = new Set(Object.keys(info));
     let forbiddenFields = setDifference(usedFields, allowedInfoFields);
     if (forbiddenFields.size != 0) {
         showDebugOutput(
             `Unknown field(s) in info: ` +
 	    Array.from(forbiddenFields).join(' '));
     }
+    if (info.definitions) {
+	for (let definition of info.definitions) {
+            // Preprocess with all existing definitions
+            newValue = trimNewlines(processDefinitions(definition.value));
+            page_definitions[definition.term] = newValue;
+	}
+    }
 
     // Set up pattern preprocessing, if set. ADVANCED USERS ONLY.
     // This must be done *before* we load & process any other patterns.

docs/labs/create_checker.md

@@ -558,6 +558,40 @@ lab and each different natural language.
 For each button you should set the `title` attribute for the
 given language.
 
+### Advanced use: Definitions
+
+Regular expressions make it easy to describe many patterns.
+However, it's sometimes useful to give certain sequences names, or
+use the same sequence in different circumstances.
+
+Checker allows you to define named terms, and then use them in a regular
+expression.
+This is done in the `definitions` section, which is a sequence
+of a `term` name and its corresponding `value`.
+Any use of the same term in a later definition or a regular expression
+will replaced by its current definition.
+Leading and trailing whitespace in the value is removed.
+
+Here's an example:
+
+~~~~yaml
+definitions:
+- term: RETURN0
+  value: |
+    return \s+ 0 ;
+- term: RETURN0
+  value: |
+    (RETURN0|\{ RETURN0 \})
+~~~~
+
+The first entry defines `RETURN0` as the value `\s+ 0 ;`
+so any future use of RETURN0 will be replaced by that.
+The next entry uses the *same* term name, and declares it to be
+`(RETURN0|\{ RETURN0 \})`.
+The result is that the new value for `RETURN0` will be
+`(\s+ 0 ;|\{ \s+ 0 ; \})` - enabling us to have
+an expression <i>optionally</i> surrounded by curly braces.
+
 ### Advanced use: Select preprocessing commands (e.g., for other languages)
 
 For most programming languages the default regex preprocessing

docs/labs/oob1.html

@@ -28,13 +28,13 @@
 \s*
   if \s+ \(
       (1 \+ 2 \+ 16|19) > s -> s3 -> rrec \. length \)
-  \s+ return \s+ 0 ;
+  \s+ RETURN0
 \s*
 </script>
 <script id="correct1" type="plain/text">
 \s*
   if \s+ \( (1 \+ 2|3) \+ payload \+ 16 > s -> s3 -> rrec \. length \)
-  \s+ return \s+ 0 ;
+  \s+ RETURN0
 \s*
 </script>
 <!--
@@ -57,6 +57,13 @@
 - absent: |
     \(
   text: Need "(...)" around the condition after an if statement.
+definitions:
+- term: RETURN0
+  value: |
+    return \s+ 0 ;
+- term: RETURN0
+  value: |
+    (RETURN0|\{ RETURN0 \})
 # - present: "import"
 #   text: Yes, many JavaScript implementations support an import statement.
 #     However, in this exercise we will use a require form. Please use that