One more round of tidying...

and being more clear about the meanings of variables

Author: rocky

mathics_scanner/prescanner.py

@@ -52,12 +52,11 @@ def replace_escape_sequences(self) -> str:
         Note: self.code is not modified.
         """
 
-        line_fragments = (
-            []
-        )  # line fragments to be joined before returning from this method.
-        self.fragment_start = (
-            self.pos
-        )  # start position of line fragment under consideration
+        # Line fragments to be joined before returning from this method.
+        line_fragments = []
+
+        # Fragment start position of line fragment under consideration.
+        self.fragment_start = self.pos
 
         def start_new_fragment(pos: int) -> None:
             """
@@ -71,14 +70,14 @@ def try_parse_base(start_shift: int, end_shift: int, base: int) -> None:
             See if characters self.pos+start_shift .. self.pos+end shift
             can be converted to an integer in base  ``base``.
 
-            If so, we append, the characters before the escape sequence without the
+            If so, we append the characters before the escape sequence without the
             escaping characters like ``\.`` or ``\:``.
 
-            We also append the converted integer to ``line_fragments``, and updated
+            We also append the converted integer to ``line_fragments``, and update
             position cursors for a new line fragment.
 
-            However, if the conversion fails, error messages are issued and nothing
-            is updated
+            However, if the conversion fails, then error messages are
+            issued and nothing is updated
             """
             start, end = self.pos + start_shift, self.pos + end_shift
             result = None
@@ -102,6 +101,10 @@ def try_parse_base(start_shift: int, end_shift: int, base: int) -> None:
                     "Syntax", "sntxb", self.code[self.pos :].rstrip("\n")
                 )
                 raise ScanError()
+
+            # Add text from prior line fragment as well
+            # as the escape sequence, a character, from the escape sequence
+            # that was just matched.
             line_fragments.append(self.code[start : self.pos])
             line_fragments.append(chr(result))
 
@@ -131,6 +134,9 @@ def try_parse_named_character(start_shift: int):
                     self.feeder.message("Syntax", "sntufn", named_character)
                     # stay in same line fragment
                 else:
+                    # Add text from prior line fragment as well
+                    # as the escape sequence, a character, from the escape sequence
+                    # just matched.
                     line_fragments.append(self.code[self.fragment_start : self.pos])
                     line_fragments.append(char)
                     start_new_fragment(i + 1)
@@ -180,7 +186,7 @@ def try_parse_named_character(start_shift: int):
             else:
                 self.pos += 1
 
-        # Close out final line fragment
+        # Add the final line fragment.
         line_fragments.append(self.code[self.fragment_start :])
 
         # produce and return the replacement string.

test/test_prescanner.py

@@ -6,100 +6,100 @@
 from mathics_scanner.feed import SingleLineFeeder
 
 
-def replace_escape_sequences(code):
-    prescanner = Prescanner(SingleLineFeeder(code))
+def replace_escape_sequences(mathics_text: str):
+    prescanner = Prescanner(SingleLineFeeder(mathics_text))
     return prescanner.replace_escape_sequences()
 
 
-def invalid(code):
+def assert_invalid(mathics_text: str):
     with pytest.raises(ScanError):
-        replace_escape_sequences(code)
+        replace_escape_sequences(mathics_text)
 
 
-def incomplete(code):
+def assert_incomplete(mathics_text: str):
     with pytest.raises(IncompleteSyntaxError):
-        replace_escape_sequences(code)
+        replace_escape_sequences(mathics_text)
 
 
-def equal(code, result):
-    assert replace_escape_sequences(code) == result
+def assert_equal(mathics_text: str, result: str):
+    assert replace_escape_sequences(mathics_text) == result
 
 
-def equal_length(code, length):
-    assert len(replace_escape_sequences(code)) == length
+def assert_equal_length(mathics_text: str, length):
+    assert len(replace_escape_sequences(mathics_text)) == length
 
 
 def test_named_characters():
-    equal(r"\[Theta]", "\u03B8")
-    equal(r"\[CapitalPi]", "\u03A0")
-    equal(r"\[Fake]", r"\[Fake]")
-    equal("z \\[Conjugate]", "z \uF3C8")
-    equal("z \\[Integral]", "z \u222b")
-    equal("z \\\\[Integral]", "z \\\\[Integral]")
-    equal("z \\\\\\[Integral]", "z \\\\\u222b")
-    equal("abc\\\\", "abc\\\\")
+    assert_equal(r"\[Theta]", "\u03B8")
+    assert_equal(r"\[CapitalPi]", "\u03A0")
+    assert_equal(r"\[Fake]", r"\[Fake]")
+    assert_equal("z \\[Conjugate]", "z \uF3C8")
+    assert_equal("z \\[Integral]", "z \u222b")
+    assert_equal("z \\\\[Integral]", "z \\\\[Integral]")
+    assert_equal("z \\\\\\[Integral]", "z \\\\\u222b")
+    assert_equal("abc\\\\", "abc\\\\")
 
 
 def test_text_lengths():
-    equal_length(r'"\[Integral]"', 3)
+    assert_equal_length(r'"\[Integral]"', 3)
     # Prescanner keep both slashes and quotes.
     # The tokenizer brings \\ into \ if it appears
     # inside a string.
-    equal_length(r'"\\[Integral]"', 14)
+    assert_equal_length(r'"\\[Integral]"', 14)
 
 
 def test_oct():
-    equal(r"\051", ")")
+    assert_equal(r"\051", ")")
 
 
 def test_hex_dot():
-    equal(r"\.30", "0")
+    assert_equal(r"\.30", "0")
 
 
 def test_hex_colon():
-    equal(r"\:0030", "0")
-    equal(r"\:03B8", "\u03B8")
-    equal(r"\:03b8", "\u03B8")
+    assert_equal(r"\:0030", "0")
+    assert_equal(r"\:03B8", "\u03B8")
+    assert_equal(r"\:03b8", "\u03B8")
 
 
 def test_hex_vbar():
-    equal(r"\|01D451", "\U0001D451")
+    assert_equal(r"\|01D451", "\U0001D451")
 
 
 def test_incomplete():
-    incomplete(r"\[")
-    incomplete(r"\[Theta")
+    assert_incomplete(r"\[")
+    assert_incomplete(r"\[Theta")
 
 
-def test_invalid_oct():
-    invalid(r"\093")
-    invalid(r"\01")
+def test_invalid_octal():
+    assert_invalid(r"\093")
+    assert_invalid(r"\01")
 
 
 def test_invalid_colon():
-    invalid(r"\:")
-    invalid(r"\:A")
-    invalid(r"\:01")
-    invalid(r"\:A1")
-    invalid(r"\:ak")
-    invalid(r"\:A10")
-    invalid(r"\:a1g")
-    invalid(r"\:A1g9")
-    invalid(r"\:01-2")
+    assert_invalid(r"\:")
+    assert_invalid(r"\:A")
+    assert_invalid(r"\:01")
+    assert_invalid(r"\:A1")
+    assert_invalid(r"\:ak")
+    assert_invalid(r"\:A10")
+    assert_invalid(r"\:a1g")
+    assert_invalid(r"\:A1g9")
+    assert_invalid(r"\:01-2")
 
 
 def test_invalid_dot():
-    invalid(r"\.")
-    invalid(r"\.0")
+    assert_invalid(r"\.")
+    assert_invalid(r"\.0")
 
 
 def test_combined():
-    equal(r"\:03B8\[Theta]\.30\052", "\u03B8\u03B80*")
+    assert_equal(r"\:03B8\[Theta]\.30\052", "\u03B8\u03B80*")
 
 
 def test_nested():
-    equal(r"\[Thet\141]", r"\[Thet\141]")
+    assert_equal(r"\[Thet\141]", r"\[Thet\141]")
 
 
 def test_trailing_backslash():
-    incomplete("x \\")
+    assert_incomplete("x \\")