issue #129. tidied code and added documentation.

doc/developers_guide.rst

@@ -609,14 +609,33 @@ then there would be a one-to-one correspondance between the rules and
 rule hierarchy written on paper and the objects and object hierarchy
 returned by fparser2.
 
+Extensions
+++++++++++
+
+Compilers often support extensions to the Fortran standard. fparser2
+also does this in certain cases. The suggested way to support this in
+fparser2 is to add an appropriate name to the `EXTENSIONS` list in
+`utils.py` and then support this extension in the appropriate class if
+the name is found in the `EXTENSIONS` list. This will allow this list
+to be modified in the future (e.g. a `-std` option could force the
+compiler to throw out any non-standard Fortran).
+
+Currently this approach is only implemented for a formating extensions
+(see the `Position_Edit_Desc` class rule 1013 in `Fortran2003.py`) and
+any other extensions are always supported in fparser2 (e.g. support
+for `$` in names). At some point these need to be modified to use the
+new approach. The concept of extensions is expected to be eventually
+implemented as a configuration file rather than a static list.
+
 Utils
 +++++
 
 fparser2 includes a `utils.py` file. This file contains the base
 classes discussed in the :ref:`base-classes` section, the
 fparser2-specific exceptions discussion in the :ref:`exceptions`
-section and a tree-walk utility that can be used to traverse the AST
-produced by fparser2 for a valid Fortran program.
+section, a list of extensions (see previous section) and a tree-walk
+utility that can be used to traverse the AST produced by fparser2 for
+a valid Fortran program.
 
 .. note::
 

src/fparser/two/Fortran2003.py

@@ -566,7 +566,7 @@ def match(string):
         pattern_tools file.
 
         :param str string: the string to match with the pattern rule.
-        :returns: a tuple of size 1 containing a string with the \
+        :return: a tuple of size 1 containing a string with the \
         matched name if there is a match, or None if there is not.
         :rtype: (str) or None
 
@@ -7309,10 +7309,10 @@ def match(string):
 
         param str string: contains the Fortran that we are trying to
         match
-        :returns: `None` if there is no match, otherwise a `tuple` of \
-                  size 2 either containing a `string` which is one of \
-                  "T", "TL" or "TR", followed by an `N` class, or \
-                  containing an `N` class, or None, followed by an "X".
+        :return: `None` if there is no match, otherwise a `tuple` of \
+                 size 2 either containing a `string` which is one of \
+                 "T", "TL" or "TR", followed by an `N` class, or \
+                 containing an `N` class, or `None`, followed by an "X".
         :rtype: None, (str, class N), (class N, str) or (None, str)
 
         '''
@@ -7321,7 +7321,7 @@ def match(string):
             # empty input string
             return None
         if strip_string_upper[0] == 'T':
-            if not len(strip_string_upper)>1:
+            if not len(strip_string_upper) > 1:
                 # string is not long enough to be valid
                 return None
             if strip_string_upper[1] in 'LR':
@@ -7334,21 +7334,20 @@ def match(string):
                 start = strip_string_upper[0]
                 rest = strip_string_upper[1:].lstrip()
             # Note, if class N does not match it raises an exception
-            en = N(rest)
-            return start, en
+            number_obj = N(rest)
+            return start, number_obj
         if strip_string_upper[-1] == 'X':
             print (strip_string_upper)
             # We match *X
-            from utils import EXTENSIONS
+            from fparser.two.utils import EXTENSIONS
             if "x-format" in EXTENSIONS and len(strip_string_upper) == 1:
                 # The match just contains 'X' which is not valid
                 # fortran 2003 but is an accepted extension
                 return None, "X"
-            else:
-                # Note, if class N does not match it raises an
-                # exception
-                en = N(strip_string_upper[:-1].rstrip())
-                return en, 'X'
+            # Note, if class N does not match it raises an
+            # exception
+            number_obj = N(strip_string_upper[:-1].rstrip())
+            return number_obj, 'X'
         else:
             return None
 
@@ -7373,9 +7372,8 @@ def tostr(self):
                 "empty or None")
         if self.items[0]:
             return "{0}{1}".format(self.items[0], self.items[1])
-        else:
-            # This output is only required for the "x-format" extension.
-            return "{0}".format(self.items[1])
+        # This output is only required for the "x-format" extension.
+        return "{0}".format(self.items[1])
 
 
 class N(Base):  # R1014

src/fparser/two/tests/fortran2003/test_position_edit_desc_r1013.py

@@ -54,7 +54,7 @@ def test_invalid_descriptor():
 
 
 def test_valid_t_descriptor(f2003_create):
-    '''Test valid NT, NTL and NTR inputs provide the expected output'''
+    '''Test valid nT, nTL and nTR inputs provide the expected output'''
 
     for name in ["T", "TL", "TR"]:
         for descriptor in ["{0}1".format(name),
@@ -66,16 +66,16 @@ def test_valid_t_descriptor(f2003_create):
 
 
 def test_valid_x_descriptor(f2003_create):
-    '''Test valid NX inputs provide the expected output'''
+    '''Test valid nX inputs provide the expected output'''
 
     for descriptor in ["1X", "  1  X  ", "999X", "999x"]:
         result = Position_Edit_Desc(descriptor)
         assert str(result) == "".join(descriptor.split()).upper()
 
 
 def test_invalid_x_descriptor_noextension(f2003_create, monkeypatch):
-    '''Test that the X extension raises an exception if it is not named as
-    a valid extensions.
+    '''Test that the X extension to the standard raises an exception if it
+    is not named as a valid extension.
 
     '''
 
@@ -89,8 +89,8 @@ def test_invalid_x_descriptor_noextension(f2003_create, monkeypatch):
 
 
 def test_valid_x_descriptor_extension(f2003_create, monkeypatch):
-    '''Test that the X extension produces the expected output if it is
-    named as a valid extension.
+    '''Test that the X extension to the standard produces the expected
+    output if it is named as a valid extension.
 
     '''
 

src/fparser/two/utils.py

@@ -75,7 +75,7 @@
 from fparser.two import pattern_tools as pattern
 from fparser.common.readfortran import FortranReaderBase
 
-
+# A list of supported extensions to the standard(s)
 EXTENSIONS = ["x-format"]