Markup line documentation and test.

docs/index.rst

@@ -73,4 +73,6 @@ Functions and classes
 .. autoclass:: textparser.GrammarError
     :members:
 
+.. autofunction:: textparser.markup_line
+
 .. autofunction:: textparser.tokenize_init

tests/test_textparser.py

@@ -21,6 +21,7 @@
 from textparser import Forward
 from textparser import NoMatch
 from textparser import Not
+from textparser import markup_line
 
 
 def tokenize(items, add_eof_token=True):
@@ -982,6 +983,29 @@ def grammar(self):
         self.assertEqual(str(cm.exception),
                          'Invalid syntax at line 2, column 3: "34>>!<<56"')
 
+    def test_markup_line(self):
+        datas = [
+            (0, '>>!<<0', None),
+            (1, '0>>!<<', None),
+            (2, '>>!<<1234', None),
+            (4, '12>>!<<34', None),
+            (6, '1234>>!<<', None),
+            (7, '>>!<<56', None),
+            (8, '5>>!<<6', None),
+            (9, '56>>!<<', None),
+            (3, '1x234', 'x')
+        ]
+
+        for offset, line, marker in datas:
+            if marker is None:
+                text = markup_line('0\n1234\n56', offset)
+            else:
+                text = markup_line('0\n1234\n56',
+                                   offset,
+                                   marker=marker)
+
+            self.assertEqual(text, line)
+
 
 if __name__ == '__main__':
     unittest.main()

textparser.py

@@ -629,7 +629,17 @@ def choice(*patterns):
         return Choice(*patterns)
 
 
-def markup_line(text, offset):
+def markup_line(text, offset, marker='>>!<<'):
+    """Insert given marker `marker` at given offset `offset` into given
+    string `text`, and return the marked line.
+
+    .. code-block:: python
+
+       >>> markup_line('0\\n1234\\n56', 3)
+       1>>!<<234
+
+    """
+
     begin = text.rfind('\n', 0, offset)
     begin += 1
 
@@ -638,7 +648,7 @@ def markup_line(text, offset):
     if end == -1:
         end = len(text)
 
-    return text[begin:offset] + '>>!<<' + text[offset:end]
+    return text[begin:offset] + marker + text[offset:end]
 
 
 def line(text, offset):