`fparser.two.utils`

Base classes and exception handling for Fortran parser.

Module Contents

Classes

`ComparableMixin`	Mixin class to provide rich comparison operators.
`DynamicImport`	This class imports a set of fparser.two dependencies that can not
`Base`	Base class for Fortran 2003 syntax rules.
`ScopingRegionMixin`	Mixin class for use in all classes that represent a scoping region and
`BlockBase`	Base class for matching all block constructs:
`SequenceBase`	Match one or more fparser2 rules separated by a defined separator:
`UnaryOpBase`
`BinaryOpBase`
`SeparatorBase`
`KeywordValueBase`
`BracketBase`	bracket-base is left-bracket something right-bracket.
`NumberBase`
`CallBase`
`CALLBase`
`StringBase`
`STRINGBase`	STRINGBase matches an upper case version of the input string with
`StmtBase`
`EndStmtBase`
`WORDClsBase`	Base class to support situations where there is a keyword which is
`Type_Declaration_StmtBase`

Functions

`EXTENSIONS`()	returns: the list of extensions (to the Fortran standard) currently active.
`show_result`(func)	A decorator that enables the matching sequence to be debugged by outputting
`_set_parent`(parent_node, items)	Recursively set the parent of all of the elements
`isalnum`(c)
`walk`(node_list[, types, indent, debug])	Walk down the parse tree produced by fparser2. Returns a list of all
`get_child`(node, node_type)	Searches for the first, immediate child of the supplied node that is of

Attributes

`_EXTENSIONS`
`_SHOW_MATCH_RESULTS`
`di`

fparser.two.utils._EXTENSIONS = ['x-format'][source]

fparser.two.utils.EXTENSIONS()[source]

Returns:: the list of extensions (to the Fortran standard) currently active.
Return type:: list[str]

fparser.two.utils._SHOW_MATCH_RESULTS = False[source]

exception fparser.two.utils.FparserException(info)[source]

Bases: Exception

Base class exception for fparser. This allows an external tool to capture all exceptions if required.

Parameters:: info (str) – a string giving contextual error information.

exception fparser.two.utils.NoMatchError(info)[source]

Bases: FparserException

An exception indicating that a particular rule implemented by a class does not match the provided string. It does not necessary mean there is an error as another rule may match. This exception is used internally so should never be visible externally.

exception fparser.two.utils.FortranSyntaxError(reader, info)[source]

Bases: FparserException

An exception indicating that fparser believes the provided code to be invalid Fortran. Also returns information about the location of the error if that information is available.

Parameters:

reader (str or FortranReaderBase) – input string or reader where the error took place. This is used to provide line number and line content information.
info (str) – a string giving contextual error information.

exception fparser.two.utils.InternalError(info)[source]

Bases: FparserException

An exception indicating that an unexpected error has occured in the parser.

Parameters:: info (str) – a string giving contextual error information.

exception fparser.two.utils.InternalSyntaxError(info)[source]

Bases: FparserException

An exception indicating that a syntax error has been found by the parser. This is used instead of FortranSyntaxError when the reader object is not available.

fparser.two.utils.show_result(func)[source]

A decorator that enables the matching sequence to be debugged by outputting the result (to stdout) whenever a new node in the parse tree is successfully constructed.

Parameters:: func (function) – the functor that is being called.
Returns:: the supplied functor.
Return type:: function

class fparser.two.utils.ComparableMixin[source]

Mixin class to provide rich comparison operators.

This mixin provides a set of rich comparison operators. Each class using this mixin has to provide a _cmpkey() method that returns a key of objects that can be compared.

_compare(other, method)[source]

Call the method, if other is able to be used within it.

Parameters:

other (object) – The other object to compare with
method (LambdaType) – The method to call to compare self and other.

Returns:

NotImplemented, when the comparison for the given type combination can’t be performed.

Return type:

types.NotImplementedType

__lt__(other)[source]: Return self<value.

__le__(other)[source]: Return self<=value.

__eq__(other)[source]: Return self==value.

__ge__(other)[source]: Return self>=value.

__gt__(other)[source]: Return self>value.

__ne__(other)[source]: Return self!=value.

class fparser.two.utils.DynamicImport[source]

This class imports a set of fparser.two dependencies that can not be imported during the Python Import time because they have a circular dependency with this file.

They are imported once when the Fortran2003 is already processed by calling the import_now() method.

The alternative is to have the equivalent top-level imports in the Base.__new__ method, but this method is in the parser critical path and is best to keep expensive operations out of it.

static import_now()[source]: Execute the Import of Fortran2003 dependencies.

fparser.two.utils.di[source]

fparser.two.utils._set_parent(parent_node, items)[source]

Recursively set the parent of all of the elements in the list that are a sub-class of Base. (Recursive because sometimes the list of elements itself contains a list or tuple.)

Parameters:

parent_node (sub-class of fparser.two.utils.Base) – the parent of the nodes listed in items.
items (list or tuple of fparser.two.utils.Base or str or list or tuple or NoneType.) – list or tuple of nodes for which to set the parent.

class fparser.two.utils.Base(string, parent_cls=None)[source]

Bases: ComparableMixin

Base class for Fortran 2003 syntax rules.

All Base classes have the following attributes:

self.string - original argument to construct a class instance, its
              type is either str or FortranReaderBase.
self.item   - Line instance (holds label) or None.

Parameters:

cls (type) – the class of object to create.
string (str | fparser.common.readfortran.FortranReaderBase) – (source of) Fortran string to parse.
parent_cls (type) – the parent class of this object.

property children[source]

Return an iterable containing the immediate children of this node in the parse tree.

If this node represents an expression then its children are contained in a tuple which is immutable. Therefore, the manipulation of the children of such a node must be done by replacing the items property of the node directly rather than via the objects returned by this method.

Returns:: the immediate children of this node.
Return type:: list or tuple containing zero or more of fparser.two.utils.Base or NoneType or str

subclasses[source]

get_root()[source]

Gets the node at the root of the parse tree to which this node belongs.

Returns:: the node at the root of the parse tree.
Return type:: fparser.two.utils.Base

init(*items)[source]

Store the supplied list of nodes in the items list of this node.

Parameters:: items (tuple of fparser.two.utils.Base) – the children of this node.

torepr()[source]

__str__()[source]: Return str(self).

__repr__()[source]: Return repr(self).

_cmpkey()[source]: Provides a key of objects to be used for comparing.

tofortran(tab='', isfix=None)[source]

Produce the Fortran representation of this Comment.

Parameters:

tab (str) – characters to pre-pend to output.
isfix (bool) – whether or not this is fixed-format code.

Returns:

Fortran representation of this comment.

Return type:

str

restore_reader(reader)[source]

class fparser.two.utils.ScopingRegionMixin[source]

Mixin class for use in all classes that represent a scoping region and thus have an associated symbol table.

get_scope_name()[source]

Returns:: the name of this scoping region.
Return type:: str

class fparser.two.utils.BlockBase(string, parent_cls=None)[source]

Bases: Base

Base class for matching all block constructs:

<block-base> = [ <startcls> ]
                 [ <subcls> ]...
                 ...
                 [ <subcls> ]...
                 [ <endcls> ]

static match(startcls, subclasses, endcls, reader, match_labels=False, match_names=False, match_name_classes=(), enable_do_label_construct_hook=False, enable_if_construct_hook=False, enable_where_construct_hook=False, strict_order=False, strict_match_names=False)[source]

Checks whether the content in reader matches the given type of block statement (e.g. DO..END DO, IF…END IF etc.)

Parameters:

startcls (type) – the class marking the beginning of the block
subclasses (list) – list of classes that can be children of the block.
endcls (type) – the class marking the end of the block.
reader (str or instance of FortranReaderBase) – content to check for match.
match_labels (bool) – whether or not the statement terminating the block must have a label that matches the opening statement. Default is False.
match_names (bool) – TBD
match_name_classes (tuple) – TBD
enable_do_label_construct_hook (bool) – TBD
enable_if_construct_hook (bool) – TBD
enable_where_construct_hook (bool) – TBD
strict_order (bool) – whether to enforce the order of the given subclasses.
strict_match_names (bool) – if start name present, end name must exist and match.

Returns:

instance of startcls or None if no match is found

Return type:

startcls

init(content)[source]

Initialise the content attribute with the list of child nodes.

Parameters:: content (list of fparser.two.utils.Base or NoneType) – list of nodes that are children of this one.

_cmpkey()[source]: Provides a key of objects to be used for comparing.

tostr()[source]

torepr()[source]

tofortran(tab='', isfix=None)[source]

Create a string containing the Fortran representation of this class

Parameters:

tab (str) – indent to prefix to code.
isfix (bool) – whether or not to generate fixed-format code.

Returns:

Fortran representation of this class.

Return type:

str

restore_reader(reader)[source]

class fparser.two.utils.SequenceBase(string, parent_cls=None)[source]

Bases: Base

Match one or more fparser2 rules separated by a defined separator:

sequence-base is obj [sep obj ] ...

static match(separator, subcls, string)[source]

Match one or more ‘subcls’ fparser2 rules in the string ‘string’ separated by ‘separator’.

Parameters:

separator (str) – the separator used to split the supplied string.
subcls (subclass of fparser.two.utils.Base) – an fparser2 object representing the rule that should be matched.
string (str) – the input string to match.

Returns:

a tuple containing 1) the separator and 2) the matched objects in a tuple, or None if there is no match.

Return type:

Optional[(Str, fparser.two.utils.Base)]

Raises:

InternalError – if the separator or string arguments are not the expected type.
InternalError – if the separator is white space.

init(separator, items)[source]

Store the result of the match method if the match is successful.

Parameters:

separator (str) – the separator used to split the supplied string.
items (tuple(Subclass of fparser.two.utils.Base)) – a tuple containing the matched objects.

tostr()[source]

Returns:: The Fortran representation of this object as a string.
Return type:: str

torepr()[source]

Returns:: The Python representation of this object as a string.
Return type:: str

class fparser.two.utils.UnaryOpBase(string, parent_cls=None)[source]

Bases: Base

unary-op-base is unary-op rhs

tostr()[source]

static match(op_pattern, rhs_cls, string, exclude_op_pattern=None)[source]

class fparser.two.utils.BinaryOpBase(string, parent_cls=None)[source]

Bases: Base

binary-op-base is lhs op rhs

Splits the input text into text to the left of the matched operator and text to the right of the matched operator and tries to match the lhs text with the supplied lhs class rule and the rhs text with the supplied rhs class rule.

static match(lhs_cls, op_pattern, rhs_cls, string, right=True, exclude_op_pattern=None)[source]

Matches the binary-op-base rule.

If the operator defined by argument ‘op_pattern’ is found in the string provided in argument ‘string’ then the text to the left-hand-side of the operator is matched with the class rule provided in the ‘lhs_cls’ argument and the text to the right-hand-side of the operator is matched with the class rule provided in the ‘rhs_cls’ argument.

If the optional ‘right’ argument is set to true (the default) then, in the case where the pattern matches multiple times in the input string, the right-most match will be chosen. If the ‘right’ argument is set to false then the left-most match will be chosen.

if a pattern is provided to the optional ‘exclude_op_pattern’ argument then there will be no match if the pattern matched by the ‘op_pattern’ argument also matches this pattern. The default (None) does nothing.

Parameters:

lhs_cls (subclass of fparser.two.utils.Base) – an fparser2 object representing the rule that should be matched to the lhs text.
op_pattern (str or fparser.two.pattern_tools.Pattern) – the pattern to match.
rhs_cls (subclass of fparser.two.utils.Base) – an fparser2 object representing the rule that should be matched to the rhs text.
string (str) – the string to match with the pattern and lhs and rhs rules.
right (bool) – in the case where there are multiple matches to the pattern in the string this optional argument specifies whether the righmost pattern match should be chosen (True, the default) or whether the leftmost pattern should be chosen (False).
exclude_op_pattern (fparser.two.pattern_tools.Pattern) – optional argument which specifies a particular subpattern to exclude from the match. Defaults to None which means there is no subpattern.

Returns:

a tuple containing the matched lhs, the operator and the matched rhs of the input string or None if there is no match.

Return type:

(fparser.two.utils.Base, str, fparser.two.utils.Base) or NoneType

tostr()[source]

Return the string representation of this object. Uses join() which is efficient and can make a big performance difference for complex expressions.

Returns:: the string representation of this object.
Return type:: str

class fparser.two.utils.SeparatorBase(string, parent_cls=None)[source]

Bases: Base

separator-base is [ lhs ] : [ rhs ]

static match(lhs_cls, rhs_cls, string, require_lhs=False, require_rhs=False)[source]

tostr()[source]

class fparser.two.utils.KeywordValueBase(string, parent_cls=None)[source]

Bases: Base

keyword-value-base is [ lhs = ] rhs

where:

R215 keyword is name.

static match(lhs_cls, rhs_cls, string, require_lhs=True, upper_lhs=False)[source]

Attempts to match the supplied string with lhs_cls = rhs_cls. If lhs_cls is a str then it is compared with the content to the left of the first ‘=’ character in string. If that content is a valid Fortran name but does not match lhs_cls then the match fails, irrespective of the setting of require_lhs.

Parameters:

lhs_cls (names of classes deriving from :py:class:Base or str) – list, tuple or single value of classes to attempt to match LHS against (in order), or string containing keyword to match.
rhs_cls (name of a class deriving from :py:class:Base) – name of class to match RHS against.
string (str) – text to be matched.
require_lhs (bool) – whether the expression to be matched must contain a LHS that is assigned to.
upper_lhs (bool) – whether or not to convert the LHS of the matched expression to upper case.

Returns:

instances of the classes representing quantities on the LHS and RHS (LHS is optional) or None if no match is found.

Return type:

2-tuple of objects or NoneType

tostr()[source]

class fparser.two.utils.BracketBase(string, parent_cls=None)[source]

Bases: Base

bracket-base is left-bracket something right-bracket.

This class is able to cope with nested brackets as long as they are correctly nested. Brackets in strings are ignored.

The ‘something’ can be specified as being optional.

static match(brackets, cls, string, require_cls=True)[source]

A generic match method for all types of bracketed expressions.

Parameters:

brackets (str) – the format of the left and right brackets provided as a string, for example ‘()’
cls – the class to match the content within the brackets :type cls: subclass of fparser.two.utils.Base
string (str) – the content to match
require_cls (bool) – whether the class and associated content is mandatory (True) or optional (False). The default is True.

Returns:

None if there is no match, otherwise a tuple with the first and third entries being strings containing the left and right brackets respectively and the second entry being either None or an instance of the class provided as the second argument (cls).

Return type:

‘NoneType’, ( str, NoneType, str) or ( str, cls, str )

tostr()[source]

Raises:

InternalError – if the internal items list variable is not the expected size.
InternalError – if the first element of the internal items list is None or is an empty string.

class fparser.two.utils.NumberBase(string, parent_cls=None)[source]

Bases: Base

number-base is number [ _ kind-param ]

static match(number_pattern, string)[source]

tostr()[source]

_cmpkey()[source]: Provides a key of objects to be used for comparing.

class fparser.two.utils.CallBase(string, parent_cls=None)[source]

Bases: Base

call-base is lhs ( [ rhs ] )

static match(lhs_cls, rhs_cls, string, upper_lhs=False, require_rhs=False)[source]

Parameters:

lhs_cls (str | class) – the class to match with the lhs.
rhs_cls (str | class) – the class to match with the rhs.
string (str) – the string to attempt to match.
upper_lhs (bool) – whether or not to convert the lhs to uppercase before attempting the match.
require_rhs (bool) – whether the rhs (the part within parentheses) must be present.

Returns:

a tuple containing the lhs and rhs matches or None if there is no match.

Return type:

Optional[Tuple[fparser.two.utils.Base, Optional[fparser.two.utils.Base]]]

tostr()[source]

class fparser.two.utils.CALLBase(string, parent_cls=None)[source]

Bases: CallBase

CALL-base is LHS ( [ rhs ] )

static match(lhs_cls, rhs_cls, string, require_rhs=False)[source]

Parameters:

lhs_cls (str | class) – the class to match with the lhs.
rhs_cls (str | class) – the class to match with the rhs.
string (str) – the string to attempt to match.
upper_lhs (bool) – whether or not to convert the lhs to uppercase before attempting the match.
require_rhs (bool) – whether the rhs (the part within parentheses) must be present.

Returns:

a tuple containing the lhs and rhs matches or None if there is no match.

Return type:

Optional[Tuple[fparser.two.utils.Base, Optional[fparser.two.utils.Base]]]

class fparser.two.utils.StringBase(string, parent_cls=None)[source]

Bases: Base

string-base is xyz

static match(pattern, string)[source]

init(string)[source]

Store the supplied list of nodes in the items list of this node.

Parameters:: items (tuple of fparser.two.utils.Base) – the children of this node.

tostr()[source]

torepr()[source]

_cmpkey()[source]: Provides a key of objects to be used for comparing.

class fparser.two.utils.STRINGBase(string, parent_cls=None)[source]

Bases: StringBase

STRINGBase matches an upper case version of the input string with another a pattern (typically taken from pattern_tools.py) and returns the string in upper case if there is a match.

static match(my_pattern, string)[source]

Matches an input string with a specified pattern. Casts the string to upper case before performing a match and, if there is a match, returns the string in upper case.

The pattern can be a regular expression, a string, a list or a tuple. If the input pattern is a regular expression or a string, a direct equivalence is performed. If the input pattern is a list or a tuple, then all of the contents of the list or tuple are searched for a match (by recursing). The list or tuple may contain regular expressions, strings, lists or tuples. This functionality can be used to recurse down a tree of lists and or tuples until regular expressions or strings are found (at the leaves of the tree) on which to match. The patterns used to match in fparser can be found in patterns_tools.py. These make use of the pattern class, whose match method behaves like a regular expression. For example:

from fparser.two import pattern_tools pattern = pattern_tools.intrinsic_type_name result = STRINGBase.match(pattern, “logical”)

Parameters:

pattern (list, tuple, str or an re expression) – the pattern to match
string (str) – the string to match with the pattern

Returns:

None if there is no match, or a tuple containing the matched string in upper case.

Return type:

NoneType or ( str )

class fparser.two.utils.StmtBase(string, parent_cls=None)[source]

Bases: Base

[ [ label ] [ construct-name : ] ] stmt

Attributes:

item : readfortran.Line

tofortran(tab='', isfix=None)[source]

Produce the Fortran representation of this Comment.

Parameters:

tab (str) – characters to pre-pend to output.
isfix (bool) – whether or not this is fixed-format code.

Returns:

Fortran representation of this comment.

Return type:

str

get_end_label()[source]

class fparser.two.utils.EndStmtBase(string, parent_cls=None)[source]

Bases: StmtBase

end-stmt-base = END [ stmt [ stmt-name] ]

static match(stmt_type, stmt_name, string, require_stmt_type=False)[source]

Attempts to match the supplied string as a form of ‘END xxx’ statement.

Parameters:

stmt_type (str) – the type of end statement (e.g. “do”) that we attempt to match.
stmt_name (type) – a class which should be used to match against the name should this statement be named (e.g. end subroutine sub).
string (str) – the string to attempt to match.
require_stmt_type (bool) – whether or not the string must contain the type of the block that is ending.

Returns:

2-tuple containing the matched end-statement type (if any) and, optionally, an associated name or None if there is no match.

Return type:

Optional[ Tuple[Optional[str],

Optional[fparser.two.Fortran2003.Name]]]

init(stmt_type, stmt_name)[source]

Initialise this EndStmtBase object.

Parameters:

stmt_type (str) – the type of statement, e.g. ‘PROGRAM’.
stmt_name (fparser.two.Fortran2003.Name) – the name associated with the statement or None.

get_name()[source]

get_type()[source]

tostr()[source]

torepr()[source]

get_end_name()[source]

fparser.two.utils.isalnum(c)[source]

class fparser.two.utils.WORDClsBase(string, parent_cls=None)[source]

Bases: Base

Base class to support situations where there is a keyword which is optionally followed by further text, potentially separated by a double colon. For example:

'program fred', or 'import :: a,b'

WORD-cls is WORD [ [ :: ] cls ]

static match(keyword, cls, string, colons=False, require_cls=False)[source]

Checks whether the content in string matches the expected WORDClsBase format with ‘keyword’ providing the keyword, ‘cls’ providing the following text, ‘colons’ specifying whether an optional double colon is allowed as a separator between the keyword and cls and ‘require_cls’ specifying whether cls must have content or not.

Note, if the optional double colon is allowed and exists in the string then 1) cls must also have content i.e. it implies require_cls=True and 2) white space is not required between the keyword and the double colon and the double colon and cls.

The simplest form of keyword pattern is a string. However this method can also match more complex patterns as specified by the Pattern class in pattern_tools.py. As patterns can be built from combinations of other patterns (again see pattern_tool.py) this method also supports a hierarchy of lists and/or tuples of patterns.

Parameters:

keyword (fparser.two.pattern_tools.Pattern, str, tuple of str/Pattern/tuple/list or list of str/Pattern/tuple/list) – the pattern of the WORD to match. This can be a Pattern, string, list or tuple, with a list or tuple containing one or more Pattern, string, list or tuple.
cls (a subclass of fparser.two.utils.Base) – the class to match.
string (str) – Text that we are trying to match.
colons (bool) – whether a double colon is allowed as an optional separator between between WORD and cls.
require_cls (bool) – whether content for cls is required or not.

Returns:

None if there is no match or, if there is a match, a 2-tuple containing a string matching the ‘WORD’ and an instance of ‘cls’ (or None if an instance of cls is not required and not provided).

Return type:

Optional[Tupe[Str, Optional[Cls]]]

tostr()[source]

Convert the class into Fortran.

Returns:: String representation of this class without any optional double colon.
Return type:: str

tostr_a()[source]

Convert the class into Fortran, adding in the double colon.

Returns:: String representation of this class including an optional double colon.
Return type:: str

class fparser.two.utils.Type_Declaration_StmtBase(string, parent_cls=None)[source]

Bases: StmtBase

type-declaration-stmt is declaration-type-spec [ [ ,
    attr-spec ]... :: ] entity-decl-list

subclass_names = [][source]

use_names[source]

static match(decl_type_spec_cls, attr_spec_list_cls, entity_decl_list_cls, string)[source]

tostr()[source]

Returns:: the text representation of this node.
Return type:: str

fparser.two.utils.walk(node_list, types=None, indent=0, debug=False)[source]

Walk down the parse tree produced by fparser2. Returns a list of all nodes with the specified type(s).

Parameters:

node_list ((list of) :py:class:fparser.two.utils.Base) – node or list of nodes from which to walk.
types (type or tuple of types) – type or tuple of types of Node to return. (Default is to return all nodes.)
indent (int) – extent to which to indent debug output.
debug (bool) – whether or not to write textual representation of AST to stdout.

Returns:

a list of nodes

Return type:

list of fparser.two.utils.Base

fparser.two.utils.get_child(node, node_type)[source]

Searches for the first, immediate child of the supplied node that is of the specified type.

Parameters:

node (fparser.two.utils.Base) – the node whose children will be searched.
node_type (type) – the class of child node to search for.

Returns:

the first child node of type node_type that is encountered or None.

Return type:

fparser.two.utils.Base

fparser.two.utils

Module Contents

Classes

Functions

Attributes

`fparser.two.utils`