add comments to ongiong NFA implementation

fcore/search-list/nfa.sml

@@ -11,11 +11,30 @@ struct
   | ONE_OR_MORE of regex * state
   | GROUP of regex * state
 
-  val groupLevel = 1
+  structure NfaMatch =
-  val postfixLevel = 2
+  struct
-  val concatLevel = 3
+    (* test to see if NFA matches.
-  val altLevel = 4
+     * Algorithm: Walk down to the leaves/subnodes of the regex tree
-
+     * and check if the current chr turns the leaf valid. 
+     *
+     * When we hit a concatenation node, we check if the list's hd
+     * matches the same char. 
+     * If it is valid and we have reached the last list element, 
+     * then the whole concatenation is valid and we mark it as such.
+     * If it is valid while we still have other nodes to test,
+     * we filter the hd and the next loop with the next chr
+     * checks the node's tl. 
+     * If it isn't valid, then we mark the whole concatenation as invalid.
+     *
+     * When we hit an alternation node, we check each list element at once
+     * to see if any of them are valid. 
+     * We filter out the nodes in the alternation list that turn out to be
+     * invalid.
+     * At the end of the alternation loop, we check if all nodes are valid
+     * and then mark the alternation as valid if so.
+     * This helps us to implement "maximal munch", 
+     * retrieving the maximum match instead of any other.
+     * *)
     local
       fun loop (tl, maxValid) =
         case tl of
@@ -113,7 +132,8 @@ struct
         | ALTERNATION (lst, UNTESTED) => rebuildAlternation (lst, chr, idx, [])
         | ALTERNATION (_, state) => (nfa, state)
 
-      | _ => raise Fail "nfa.sml 69: not char literal or concat or alternation"
+        | _ =>
+            raise Fail "nfa.sml 69: not char literal or concat or alternation"
 
       fun loop (pos, str, nfa, origNfa, startPos) =
         if pos = String.size str then
@@ -125,13 +145,28 @@ struct
           in
             case state of
               VALID _ => true
-          | INVALID => loop (startPos + 1, str, origNfa, origNfa, startPos + 1)
+            | INVALID =>
+                (* backtrack to another position in the string
+                 * to see if the NFA matches that portion of the string *)
+                loop (startPos + 1, str, origNfa, origNfa, startPos + 1)
             | UNTESTED => loop (pos + 1, str, nfa, origNfa, startPos)
           end
     in
       fun hasAnyMatch (str, nfa) =
         loop (0, str, nfa, nfa, 0)
     end
+  end
+
+  structure ParseNfa =
+  struct
+    (* parsing through precedence climbing algorithm.
+     * Todo: return a a `regex option`, and use bounds-checking
+     * to ensure we don't raise an exception. *)
+
+    val groupLevel = 1
+    val postfixLevel = 2
+    val concatLevel = 3
+    val altLevel = 4
 
     local
       fun loop (pos, str, openParens, closeParens) =
@@ -148,7 +183,7 @@ struct
       fun getRightParenIdx (pos, str) = loop (pos, str, 1, 0)
     end
 
-  fun helpClimb (pos, str, lhs, level) =
+    fun climb (pos, str, lhs, level) =
       if pos = String.size str then
         (pos, lhs)
       else
@@ -162,11 +197,12 @@ struct
                 val groupEndIdx = getRightParenIdx (pos + 1, str)
                 val substr = String.substring
                   (str, pos + 1, groupEndIdx - pos - 1)
-              val rhs = climb substr
+                val rhs = parse substr
                 val rhs = GROUP (rhs, UNTESTED)
-              val result = CONCAT ([(lhs, UNTESTED), (rhs, UNTESTED)], UNTESTED)
+                val result = CONCAT
+                  ([(lhs, UNTESTED), (rhs, UNTESTED)], UNTESTED)
               in
-              helpClimb (groupEndIdx + 1, str, result, groupLevel)
+                climb (groupEndIdx + 1, str, result, groupLevel)
               end
         | #"|" =>
             if level < altLevel then
@@ -175,7 +211,7 @@ struct
               let
                 val chr = String.sub (str, pos + 1)
                 val chr = CHAR_LITERAL (chr, UNTESTED)
-              val (pos, rhs) = helpClimb (pos + 2, str, chr, altLevel)
+                val (pos, rhs) = climb (pos + 2, str, chr, altLevel)
                 val result =
                   case rhs of
                     ALTERNATION (lst, state) =>
@@ -190,21 +226,21 @@ struct
               (pos, lhs)
             else
               let val lhs = ZERO_OR_ONE (lhs, UNTESTED)
-            in helpClimb (pos + 1, str, lhs, postfixLevel)
+              in climb (pos + 1, str, lhs, postfixLevel)
               end
         | #"*" =>
             if level < postfixLevel then
               (pos, lhs)
             else
               let val lhs = ZERO_OR_MORE (lhs, UNTESTED)
-            in helpClimb (pos + 1, str, lhs, postfixLevel)
+              in climb (pos + 1, str, lhs, postfixLevel)
               end
         | #"+" =>
             if level < postfixLevel then
               (pos, lhs)
             else
               let val lhs = ONE_OR_MORE (lhs, UNTESTED)
-            in helpClimb (pos + 1, str, lhs, postfixLevel)
+              in climb (pos + 1, str, lhs, postfixLevel)
               end
         | chr =>
             if level < concatLevel then
@@ -212,7 +248,7 @@ struct
             else
               let
                 val chr = CHAR_LITERAL (chr, UNTESTED)
-              val (pos, rhs) = helpClimb (pos + 1, str, chr, concatLevel)
+                val (pos, rhs) = climb (pos + 1, str, chr, concatLevel)
                 val result =
                   case rhs of
                     CONCAT (lst, _) => CONCAT ((lhs, UNTESTED) :: lst, UNTESTED)
@@ -225,11 +261,11 @@ struct
       if pos = String.size str then
         ast
       else
-      let val (pos, ast) = helpClimb (pos, str, ast, altLevel)
+        let val (pos, ast) = climb (pos, str, ast, altLevel)
         in loop (pos, str, ast)
         end
 
-  and climb str =
+    and parse str =
       let
         val chr = String.sub (str, 0)
         val chr = CHAR_LITERAL (chr, UNTESTED)
@@ -237,3 +273,7 @@ struct
         loop (1, str, chr)
       end
   end
+
+  val parse = ParseNfa.parse
+  val hasAnyMatch = NfaMatch.hasAnyMatch
+end