Commentary

src_v2/parser/parser_internals.nim

@@ -19,9 +19,11 @@ type parserFnT = proc(t0: Parser): ParserResult
 # -- Utilities
 
 proc isStreamCompleted*(parser: Parser): bool =
+  ## Check if the `parser` index is at/over the stream length.
   parser.state.position >= parser.state.stream.len - 1
 
 proc isStreamCompleted*(parserResult: ParserResult): bool =
+  ## Check if the `parserResult.state` index is at/over the stream length.
   parserResult.fold(
     err => false,
     isStreamCompleted,
@@ -30,6 +32,8 @@ proc isStreamCompleted*(parserResult: ParserResult): bool =
 # -- Parsing functions
 
 proc ch*(expectedChars: set[char]): parserFnT {.inline.} =
+  ## Create parser function with set of `expectedChar`.
+  ## When the parser has the character set at the following index return `ParserResult.ok`.
   return proc(parser: Parser): ParserResult =
     let state = parser.state
     let newIndex = state.position + 1
@@ -62,6 +66,8 @@ proc ch*(expectedChars: set[char]): parserFnT {.inline.} =
         ))
 
 proc ch*(expectedChar: char): parserFnT {.inline.} =
+  ## Creates parser function with `expectedChar`
+  ## When the parser has the character at the following index return `ParserResult.ok`
   return proc(parser: Parser): ParserResult =
     let state = parser.state
     let newIndex = state.position + 1
@@ -96,17 +102,19 @@ proc ch*(expectedChar: char): parserFnT {.inline.} =
 let anyCh* = ch(AllChars)
 let digit* = ch(Digits)
 
-proc str*(s: string): parserFnT {.inline.} =
+proc str*(expectedString: string): parserFnT {.inline.} =
+  ## Creates parser function with `expectedString`
+  ## When the parser has the string at the following index return `ParserResult.ok`
   return proc(parser: Parser): ParserResult =
     var p = parser.ok()
-    for c in s.items:
+    for c in expectedString.items:
       p = p.flatMap(ch(c))
     return p
 
 # -- Parsing API
 
 proc optional*(parserFn: parserFnT): parserFnT {.inline.} =
-  ## Parse characters and ignore failure
+  ## Create a
   return proc(parser: Parser): ParserResult =
     let newParser = parserFn(parser)