Change the behaviour of Repetition and Integer max constructor arguments

Re: #394.

The *max* constructor arguments of the Repetition and Integer class-
es are now treated as inclusive, rather than inclusive.  This seems
more sensible and matches the treatment of the *min* argument.

For the Integer class, I have elected not to change the complex int-
ernal classes that do the most of the work.  They receive the value
*max + 1*.  This shouldn't matter, but I'm noting it here.

The Digits element class is affected by this change, as it is a sub-
class of Repetition.

Author: drmfinlay

dragonfly/grammar/elements_basic.py

@@ -570,8 +570,8 @@ class Repetition(Sequence):
            be recognized (inclusive); may be 0
          - *max* (*int*, default: *None*) --
            the maximum number of times that the child element must
-           be recognized (exclusive!); if *None*, the child element must be
-           recognized exactly *min* times (i.e. *max = min + 1*)
+           be recognized (inclusive); if *None*, the child element may be
+           recognized up to *min + 1* times (i.e. *max = min + 1*)
          - *name* (*str*, default: *None*) --
            the name of this element
          - *default* (*object*, default: *None*) --
@@ -585,11 +585,11 @@ class Repetition(Sequence):
         least *min* times and strictly less than *max* times.
 
         Examples:
-         - *Repetition(child, min=2, max=5)* -- child 2, 3, or 4 times
-         - *Repetition(child, min=0, max=3)* -- child 0, 1, or 2 times
-         - *Repetition(child, max=3)* -- child 1 or 2 times
-         - *Repetition(child, min=1, max=2)* -- child exactly once
-         - *Repetition(child, min=1)* -- child exactly once
+         - *Repetition(child, min=2, max=4)* -- child 2, 3, or 4 times
+         - *Repetition(child, min=0, max=2)* -- child 0, 1, or 2 times
+         - *Repetition(child, max=2)* -- child 1 or 2 times
+         - *Repetition(child, min=1, max=1)* -- child exactly once
+         - *Repetition(child, min=1)* -- child 1 or 2 times
          - *Repetition(child)* -- child exactly once
 
         If the *optimize* argument is set to *True*, the engine's compiler may
@@ -610,15 +610,15 @@ def __init__(self, child, min=1, max=None, name=None, default=None,
                             " ElementBase instance." % self)
         assert isinstance(min, six.integer_types)
         assert max is None or isinstance(max, six.integer_types)
-        assert max is None or min < max, "min must be less than max"
+        assert max is None or min <= max, "min must be less than or equal to max"
 
         self._child = child
         self._min = min
         if max is None: self._max = min + 1
         else:           self._max = max
         self._optimize = optimize
 
-        optional_length = self._max - self._min - 1
+        optional_length = self._max - self._min
         if optional_length > 0:
             element = Optional(child)
             for index in range(optional_length-1):
@@ -644,8 +644,8 @@ def __init__(self, child, min=1, max=None, name=None, default=None,
     max = property(
         lambda self: self._max,
         doc="The maximum number of times that the child element must be "
-        "recognized; if *None*, the child element must be "
-        "recognized exactly *min* times (i.e. *max = min + 1*). "
+        "recognized; if *None*, the child element may be "
+        "recognized up to *min + 1* times (i.e. *max = min + 1*). "
         "(Read-only)"
     )
 

dragonfly/language/base/integer.py

@@ -24,6 +24,8 @@
 
 """
 
+from six import integer_types
+
 from dragonfly.language.loader   import language
 from dragonfly.grammar.elements  import (Alternative, Sequence, Optional,
                                          Compound, ListRef, RuleWrap)
@@ -60,6 +62,15 @@ def __init__(self, name=None, min=None, max=None, default=None,
             self._set_content(language.IntegerContent)
         self._builders = self._content.builders
 
+        assert isinstance(min, integer_types), "min must be a number"
+        assert isinstance(max, integer_types), "max must be a number"
+        assert min <= max, "min must be less than or equal to max"
+
+        # Make the *max* argument behave inclusively.
+        # Note: This is an easier change than modifying the internal integer
+        #  classes.
+        max = max + 1
+
         self._min = min; self._max = max
         children = self._build_children(min, max)
         Alternative.__init__(self, children, name=name, default=default)

dragonfly/language/base/integer_internal.py

@@ -36,6 +36,11 @@
 
 #---------------------------------------------------------------------------
 # Numeric element builder classes.
+#
+# Note: The classes in this file treat the *max* argument as exclusive,
+#  meaning that build_element() methods will return element trees for
+#  recognizing integers up to max - 1.
+
 
 class IntBuilderBase(object):