Clean up the English-language element code under dragonfly.language

- Fix errors in calendar.py and add docstrings.
- Add a new TwelveHourTime element class.
- Add license/copyright header to short_number.py.
- Fix some other minor issues.

Author: drmfinlay

dragonfly/language/en/__init__.py

@@ -22,4 +22,4 @@
 from .number       import    IntegerContent, DigitsContent
 from .short_number import    ShortIntegerContent
 from .calendar     import   (AbsoluteDate, RelativeDate, Date,
-                            MilitaryTime, Time)
+                             TwelveHourTime, MilitaryTime, Time)

dragonfly/language/en/calendar.py

@@ -65,33 +65,42 @@
 #---------------------------------------------------------------------------
 
 class Month(Choice):
+    """
+        Element allowing one of the twelve months of the year to be
+        recognized and used in an action.
+
+    """
 
     def __init__(self, name):
         Choice.__init__(self, name=name, choices=month_names)
 
 
 class Day(Choice):
+    """
+        Element allowing one of the days in a week to be recognized and
+        used in an action.
 
+    """
     def __init__(self, name):
         Choice.__init__(self, name=name, choices=day_names)
 
 
 class Year(Alternative):
+    """
+        Element allowing a specific calendar year to be recognized and used
+        in an action.
+
+        The years 1910 to 2099 may be recognized.
 
+    """
     alts = [
             IntegerRef("year", 2000, 2100),
             Compound(
                      spec="<century> <year>",
-                     extras=[Integer("century", 20, 21),
+                     extras=[Integer("century", 19, 21),
                              IntegerRef("year", 10, 100)],
                      value_func=lambda n, e: e["century"] * 100 + e["year"]
                     ),
-            Compound(
-                     spec="<century> <year>",
-                     extras=[Integer("century", 19, 20),
-                             IntegerRef("year", 1, 100)],
-                     value_func=lambda n, e: e["century"] * 100 + e["year"]
-                    ),
            ]
 
     def __init__(self, name):
@@ -101,6 +110,11 @@ def __init__(self, name):
 #---------------------------------------------------------------------------
 
 class AbsoluteDate(Compound):
+    """
+        Element allowing a date in the current year or in a specific year
+        to be recognized and used in an action.
+
+    """
 
     spec = "(<day> <month> | <month> <day>) [<year>]"
     extras = [IntegerRef("day", 1, 32), Month("month"), Year("year")]
@@ -128,6 +142,11 @@ def value(self, node):
 
 
 class RelativeDate(Alternative):
+    """
+        Element allowing a date relative to the current date to be
+        recognized and used in an action.
+
+    """
 
     class _DayOffset(Choice):
         def __init__(self):
@@ -144,7 +163,7 @@ def __init__(self):
         def value(self, node):
             value = Choice.value(self, node)
             n = node.get_child_by_name("n")
-            print("November:", n)
+            #print("November:", n)
             if n is not None:
                 value = value * n.value()
             return date.today() + timedelta(days=value)
@@ -164,7 +183,7 @@ def value(self, node):
             value = Choice.value(self, node)
             day = node.get_child_by_name("day").value()
             now = date.today().weekday()
-            print(value, day, now)
+            #print(value, day, now)
             if value == "last day":
                 if day < now:  day_offset = -now + day
                 else:          day_offset = -7 - now + day
@@ -187,6 +206,11 @@ def __init__(self, name):
 
 
 class Date(Alternative):
+    """
+        Element allowing either an absolute date or a relative date to be
+        recognized and used in an action.
+
+    """
 
     alts = [
             AbsoluteDate(None),
@@ -199,13 +223,25 @@ def __init__(self, name):
 
 #---------------------------------------------------------------------------
 
-class MilitaryTime(Compound):
+class TwelveHourTime(Compound):
+    """
+        Element allowing twelve-hour time to be recognized and used in an
+        action.
 
-    spec = "<hour> (hundred | (oh | zero) <min_1_10> | <min_10_60>)"
+        Examples: nine AM, one oh five PM, three thirty PM.
+
+    """
+
+    spec = "<hour> [(<zero> <min_1_10> | <min_10_60>)] <am_pm>"
     extras = [
-              Integer("hour", 0, 25),
+              Integer("zero", 0, 1),
+              Integer("hour", 1, 13),
               IntegerRef("min_1_10", 1, 10),
               IntegerRef("min_10_60", 10, 60),
+              Choice("am_pm", {
+                  "AM | a.m.": "AM",
+                  "PM | p.m.": "PM",
+              })
              ]
 
     def __init__(self, name):
@@ -214,6 +250,52 @@ def __init__(self, name):
 
     def value(self, node):
         hour = node.get_child_by_name("hour").value()
+        am_pm = node.get_child_by_name("am_pm").value()
+        if hour < 12:
+            if am_pm == "PM":
+                hour += 12
+        elif am_pm == "AM":
+            hour = 0
+        if node.has_child_with_name("min_1_10"):
+            minute = node.get_child_by_name("min_1_10").value()
+        elif node.has_child_with_name("min_10_60"):
+            minute = node.get_child_by_name("min_10_60").value()
+        else:
+            minute = 0
+        return time(hour, minute)
+
+
+class MilitaryTime(Compound):
+    """
+        Element allowing military time to be recognized and used in an
+        action.
+
+        Examples: zero hundred, oh eight hundred, seventeen hundred hours,
+        ten oh five, seventeen thirty.
+
+    """
+
+    spec = ("(<zero_oh> | <zero_oh> <hour_0_10> | <hour_10_24>)"
+            " (hundred | <zero_oh> <min_1_10> | <min_10_60>) [hours]")
+    extras = [
+              Integer("zero_oh", 0, 1),
+              Integer("hour_0_10", 1, 10),
+              Integer("hour_10_24", 10, 24),
+              IntegerRef("min_1_10", 1, 10),
+              IntegerRef("min_10_60", 10, 60),
+             ]
+
+    def __init__(self, name):
+        Compound.__init__(self, name=name, spec=self.spec,
+                          extras=self.extras)
+
+    def value(self, node):
+        if node.has_child_with_name("hour_0_10"):
+            hour = node.get_child_by_name("hour_0_10").value()
+        elif node.has_child_with_name("hour_10_24"):
+            hour = node.get_child_by_name("hour_10_24").value()
+        else:
+            hour = 0
         if node.has_child_with_name("min_1_10"):
             minute = node.get_child_by_name("min_1_10").value()
         elif node.has_child_with_name("min_10_60"):
@@ -224,8 +306,17 @@ def value(self, node):
 
 
 class Time(Alternative):
+    """
+        Element allowing the time of day to be recognized and used in an
+        action.
+
+        This allows speaking the twelve-hour time or twenty-four hour
+        military time.
+
+    """
 
     alts = [
+            TwelveHourTime(None),
             MilitaryTime(None),
            ]
 

dragonfly/language/en/short_number.py

@@ -1,9 +1,31 @@
+#
+# This file is part of Dragonfly.
+# (c) Copyright 2019, 2020 by Mike Roberts
+# Licensed under the LGPL.
+#
+#   Dragonfly is free software: you can redistribute it and/or modify it
+#   under the terms of the GNU Lesser General Public License as published
+#   by the Free Software Foundation, either version 3 of the License, or
+#   (at your option) any later version.
+#
+#   Dragonfly is distributed in the hope that it will be useful, but
+#   WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+#   Lesser General Public License for more details.
+#
+#   You should have received a copy of the GNU Lesser General Public
+#   License along with Dragonfly.  If not, see
+#   <http://www.gnu.org/licenses/>.
+#
 
-'''
+"""
 ShortIntegerRef
 ============================================================================
 
-:class:`ShortIntegerRef` is a modified version of :class:`IntegerRef` which allows for greater flexibility in the way that numbers may be pronounced, allowing for words like "hundred" to be dropped. This may be particularly useful when navigating files by line or page number.
+:class:`ShortIntegerRef` is a modified version of :class:`IntegerRef` which
+allows for greater flexibility in the way that numbers may be pronounced,
+allowing for words like \"hundred\" to be dropped.  This may be particularly
+useful when navigating files by line or page number.
 
 Some examples of allowed pronunciations:
 
@@ -32,12 +54,14 @@
 four thousand                         4000
 ================================     ======
 
-The class works in the same way as :class:`IntegerRef`, by adding the following as an extra.
+The class works in the same way as :class:`IntegerRef`, by adding the
+following as an extra:
 
 .. code:: python
 
-   ShortIntegerRef("name", 0, 1000),
-'''
+   ShortIntegerRef(\"name\", 0, 1000),
+
+"""
 
 from dragonfly.language.base.integer_internal  import (CollectionIntBuilder,
                                                        MagnitudeIntBuilder,