Cleanup and document core APIs in C, JS, and Python.

packages/python/parser.py

@@ -1,35 +1,63 @@
 from typing import TypedDict
 
+# Holds the parsed information from each line.
 class LineData(TypedDict):
-  line: str
+  # Which character is being used for indentation. Avoids having to specify it on each terrace_parse_line call.
   indent: str
+  # How many indent characters are present in the current line before the first non-indent character.
   level: int
+  # The number of characters before the start of the line's "head" section.
+  # (Normally the same as `level`)
   offsetHead: int
+  # The number of characters before the start of the line's "tail" section.
   offsetTail: int
 
-def createLineData(line: str = '', indent: str = ' ') -> LineData:
-  return { "line": line, "indent": indent, "level": 0, "offsetHead": 0, "offsetTail": 0 }
+def createLineData(indent: str = ' ') -> LineData:
+  """
+  Initialize a LineData instance with default values.
 
-def parseLine(lineData: LineData) -> LineData:
-  # if ((typeof lineData !== 'object' || !lineData) || typeof lineData.level !== 'number') throw new Error(`'lineData' must be an object with string line and numeric level properties`)
-  # if (typeof lineData.indent !== 'string' || lineData.indent.length === 0 || lineData.indent.length > 1) throw new Error(`'lineData.indent' must be a single-character string`)
-  # if (typeof lineData.line !== 'string') throw new Error(`'lineData.line' must be a string`)
+  Parameters
+  ----------
+  indent : str
+    The character to use for indenting lines. ONLY ONE CHARACTER IS CURRENTLY PERMITTED.
+  Returns
+  -------
+  LineData
+    A LineData dict with the specified indent character and all other values initialized to 0.
+  """
+  return { "indent": indent, "level": 0, "offsetHead": 0, "offsetTail": 0 }
 
-  level = 0
+def parseLine(line: str, lineData: LineData):
+  """
+  Core Terrace parser function, sets level, offsetHead, and offsetTail in a LineData object based on the current line.
+  Note that this is a C-style function, lineData is treated as a reference and mutated in-place.
 
-  # Repeat previous level for blank lines.
-  if len(lineData['line']) == 0:
-    lineData['level'] = lineData['level']
+  Parameters
+  ----------
+  line : str
+    A string containing a line to parse. Shouldn't end with a newline.
+  lineData: LineData
+    A LineData dict to store information about the current line in. **Mutated in-place!**
+  """
+
+  # Blank lines have no characters, the newline should be stripped off.
+  # Special case handling for these allows them to be parsed quickly.
+  if len(line) == 0:
+    # Empty lines are treated as having the same level as the previous line, so lineData.line is not updated.
     lineData['offsetHead'] = 0
     lineData['offsetTail'] = 0
   else:
-    while level < len(lineData['line']) and lineData['line'][level] == lineData['indent'] and level <= lineData['level'] + 1:
+    # Count the number of indent characters in the current line.
+    level = 0
+    while level < len(line) and line[level] == lineData['indent']:
       level += 1
     lineData['level'] = level
+
+    # Set offsetHead and offsetTail to level to start with.
+    # offsetHead should always be equal to level, and offsetTail will always be equal to or greater than level.
     lineData['offsetHead'] = level
     lineData['offsetTail'] = level
 
-    while lineData['offsetTail'] < len(lineData['line']) and lineData['line'][lineData['offsetTail']] != ' ':
-      lineData['offsetTail'] += 1
-
-  return lineData
+    # Increment offsetTail until we encounter a space character (start of tail) or reach EOL (no tail present).
+    while lineData['offsetTail'] < len(line) and line[lineData['offsetTail']] != ' ':
+      lineData['offsetTail'] += 1