From b1e4a36e36f377425edd4556b8150b7aba817a30 Mon Sep 17 00:00:00 2001
From: Florian Schroedl <flo.schroedl@gmail.com>
Date: Thu, 20 Jan 2022 17:00:00 +0100
Subject: [PATCH] Documentation

---
 src/org/org_text_delimiter.nim | 51 +++++++++++++++++++---------------
 1 file changed, 28 insertions(+), 23 deletions(-)

diff --git a/src/org/org_text_delimiter.nim b/src/org/org_text_delimiter.nim
index ef94b54..43d07b2 100644
--- a/src/org/org_text_delimiter.nim
+++ b/src/org/org_text_delimiter.nim
@@ -14,15 +14,15 @@ let parseBetweenDelimiter* = proc(start: (Parser -> ParserResult), stop: (Parser
   anyUntil(stop + whitespace) +
   ignore(start)
 
-let parseBetweenIdenticalDelimiter* = proc(delimiterParser: (Parser -> ParserResult)): (Parser -> ParserResult) {.closure.} =
+let parseBetweenPair* = proc(delimiterParser: (Parser -> ParserResult)): (Parser -> ParserResult) {.closure.} =
   parseBetweenDelimiter(delimiterParser, delimiterParser)
 
-let boldParser* = parseBetweenIdenticalDelimiter(ch('*'))
-let italicParser* = parseBetweenIdenticalDelimiter(ch('/'))
-let underlineParser* = parseBetweenIdenticalDelimiter(ch('_'))
-let verbatimParser* = parseBetweenIdenticalDelimiter(ch('='))
-let codeParser* = parseBetweenIdenticalDelimiter(ch('~'))
-let strikeThroughParser* = parseBetweenIdenticalDelimiter(ch('+'))
+let boldParser* = parseBetweenPair(ch('*'))
+let italicParser* = parseBetweenPair(ch('/'))
+let underlineParser* = parseBetweenPair(ch('_'))
+let verbatimParser* = parseBetweenPair(ch('='))
+let codeParser* = parseBetweenPair(ch('~'))
+let strikeThroughParser* = parseBetweenPair(ch('+'))
 
 type OrgBuilderT* = OrgElement
 type OrgBuilder* = Builder[OrgBuilderT]
@@ -78,43 +78,48 @@ proc parseText[T](
   builder: Builder[T],
   builderFns: seq[tuple[
     parserFn: Parser -> ParserResult,
-    tokenFoldFn: (seq[ParserToken], seq[T]) -> seq[T],
+    concatFn: (seq[ParserToken], seq[T]) -> seq[T],
   ]],
-  otherWiseFn: (seq[ParserToken]) -> seq[T],
-  stopFn = newline,
+  defaultBuilderFn: (seq[ParserToken]) -> seq[T],
+  stopAtParserFn = newline,
 ): BuilderResult[T] =
+  ## Parse remaining text in `builder` by going checking in the `builderFns` list for a sucessful `parserFn`.
+  ## The `ok` `parserFn` result will be merged into the `Builder[T].tree` by using the `concatFn`.
+  ## Otherwise continue taking any character until the `stopAtParserFn` condition is found.
+  ## Any non-matching tokens will be converted using the `defaultBuilderFn`.
   let (parser, tree) = builder
 
+  # Mutating accumulators
   var parserAcc: ParserResult = ParserResult.ok(parser)
   var builderAcc: Builder[T] = builder
 
-  while parserAcc.isOk() and parserAcc.flatMap(stopFn).isErr():
+  while parserAcc.isOk() and parserAcc.flatMap(stopAtParserFn).isErr():
     # Empty the parser tokens as we want to seperate them for the next parser in the sequence
     let emptyParser = parserAcc.map(emptyTokens)
 
-    # Find the first matching parser and convert it's tokens
-    # Otherwise leave the raw tokens
+    # Find the first matching parser and convert its tokens
     var found = false
     for builderFn in builderFns:
-      let (parserFn, tokenFoldFn) = builderFn
-      let parseResult = emptyParser.flatMap(parserFn)
+      let (parserFn, concatFn) = builderFn
 
+      let parseResult = emptyParser.flatMap(parserFn)
       if parseResult.isOk():
         let okParser = parseResult.unsafeGet()
 
-        let textTokens = parserAcc
+        # Convert all previous unmatched tokens via the `defaultBuilderTokens`
+        let defaultBuilderTokens = parserAcc
         .foldTokens(
           onError = _ => newSeq[T](),
-          onSuccess = otherWiseFn,
+          onSuccess = defaultBuilderFn,
         )
 
         found = true
         parserAcc = parseResult.map(emptyTokens)
         builderAcc = builder.initBuilder(
           okParser,
-          tokenFoldFn(
+          concatFn(
             okParser.tokens,
-            builderAcc[1] & textTokens,
+            builderAcc[1] & defaultBuilderTokens,
           ),
         )
         break
@@ -122,15 +127,15 @@ proc parseText[T](
     if not found:
       parserAcc = parserAcc.flatMap(anyCh)
 
-  let textTokens = parserAcc
+  let defaultBuilderTokens = parserAcc
   .foldTokens(
     onError = _ => newSeq[T](),
-    onSuccess = otherWiseFn,
+    onSuccess = defaultBuilderFn,
   )
 
   BuilderResult[T].ok(builder.initBuilder(
     builderAcc[0],
-    builderAcc[1] & textTokens,
+    builderAcc[1] & defaultBuilderTokens,
   ))
 
 proc makeRawTokenOrEmpty(xs: seq[ParserToken]): seq[OrgBuilderT] =
@@ -154,7 +159,7 @@ when isMainModule:
       (codeParser, makeOrgToken(makeCodeToken)),
       (strikeThroughParser, makeOrgToken(makeStrikeThroughToken)),
     ],
-    otherWiseFn = makeRawTokenOrEmpty,
+    defaultBuilderFn = makeRawTokenOrEmpty,
   ))
   # .foldBuilder(
   #   err => "",