Allow specifying a default value to optional()

Fixes #65

Author: unode

docs/history.rst

@@ -9,6 +9,7 @@ History and release notes
 
 * Dropped support for Python < 3.6
 * Added :meth:`Parser.until`. Thanks `@mcdeoliveira <https://github.com/mcdeoliveira>`_!
+* `Parser.optional` now supports an optional default argument to be returned instead of ``None``.
 
 1.4.0 - 2021-11-15
 ------------------

docs/ref/methods_and_combinators.rst

@@ -130,17 +130,20 @@ can be used and manipulated as below.
 
    .. versionadded:: 2.0
 
-   .. method:: optional()
+   .. method:: optional([default=None])
 
       Returns a parser that expects the initial parser zero or once, and maps
-      the result to ``None`` in the case of no match.
+      the result to a given default value in the case of no match. If no default
+      value is given, ``None`` is used.
 
       .. code:: python
 
          >>> string('A').optional().parse('A')
          'A'
          >>> string('A').optional().parse('')
          None
+         >>> string('A').optional('Oops').parse('')
+         'Oops'
 
    .. method:: map(fn)
 

docs/tutorial.rst

@@ -296,7 +296,8 @@ failing the whole parse.
 multiples of the parser - including :meth:`Parser.many`, :meth:`Parser.times`,
 :meth:`Parser.at_most` and :meth:`Parser.at_least`. There is also
 :meth:`Parser.optional` which allows matching zero times (in which case the
-parser will return ``None``), or exactly once - just what we need in this case.
+parser will return the default value specified or ``None`` otherwise),
+or exactly once - just what we need in this case.
 
 We also need to do checking on the month and the day. We’ll take a shortcut and
 use the built-in ``datetime.date`` class to do the validation for us. However,

src/parsy/__init__.py

@@ -178,8 +178,8 @@ def at_most(self, n):
     def at_least(self, n):
         return self.times(n) + self.many()
 
-    def optional(self):
-        return self.times(0, 1).map(lambda v: v[0] if v else None)
+    def optional(self, default=None):
+        return self.times(0, 1).map(lambda v: v[0] if v else default)
 
     def until(self, other, min=0, max=float("inf"), consume_other=False):
         @Parser

tests/test_parsy.py

@@ -418,6 +418,9 @@ def test_optional(self):
         p = string("a").optional()
         self.assertEqual(p.parse("a"), "a")
         self.assertEqual(p.parse(""), None)
+        p = string("a").optional("b")
+        self.assertEqual(p.parse("a"), "a")
+        self.assertEqual(p.parse(""), "b")
 
     def test_sep_by(self):
         digit_list = digit.map(int).sep_by(string(","))