f2pygen.py

# -----------------------------------------------------------------------------
# BSD 3-Clause License
#
# Copyright (c) 2017-2024 and Technology Facilities Council.
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice, this
#   list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright notice,
#   this list of conditions and the following disclaimer in the documentation
#   and/or other materials provided with the distribution.
#
# * Neither the name of the copyright holder nor the names of its
#   contributors may be used to endorse or promote products derived from
#   this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
# -----------------------------------------------------------------------------
# Authors R. W. Ford, A. R. Porter and S. Siso, STFC Daresbury Lab
# Modified: A. B. G. Chalk and N. Nobre, STFC Daresbury Lab
 
''' Fortran code-generation library. This wraps the f2py fortran parser to
    provide routines which can be used to generate fortran code. '''
 
import abc
from fparser.common.readfortran import FortranStringReader
from fparser.common.sourceinfo import FortranFormat
from fparser.one.statements import Comment, Case
from fparser.one.block_statements import SelectCase, SelectType, EndSelect
from fparser.one.parsefortran import FortranParser
# This alias is useful to refer to parts of fparser.one later but
# cannot be used for imports (as that involves looking for the
# specified name in sys.modules).
from fparser import one as fparser1
from psyclone.configuration import Config
from psyclone.errors import InternalError
 
# Module-wide utility methods
 
 
def bubble_up_type(obj):
    '''
    Checks whether the supplied object must be bubbled-up (e.g. from
    within DO loops).
 
    :returns: True if the supplied object is of a type which must be \
              bubbled-up and False otherwise.
    '''
    return isinstance(obj, (UseGen, BaseDeclGen))
 
 
def index_of_object(alist, obj):
    '''Effectively implements list.index(obj) but returns the index of
    the first item in the list that *is* the supplied object (rather than
    comparing values) '''
    for idx, body in enumerate(alist):
        if body is obj:
            return idx
    raise Exception(f"Object {obj} not found in list")
 
 
# This section subclasses the f2py comment class so that we can
# reason about directives
 
 
class Directive(Comment):
    '''
    Base class for directives so we can reason about them when walking
    the tree. Sub-classes the fparser1 Comment class.
 
    :param root: the parent node in the AST to which we are adding the \
                 directive
    :type root: subclass of :py:class:`fparser.common.base_classes.Statement`
    :param line: the fparser object which we will manipulate to create \
                 the desired directive.
    :type line: :py:class:`fparser.common.readfortran.Comment`
    :param str position: e.g. 'begin' or 'end' (language specific)
    :param str dir_type: the type of directive that this is (e.g. \
                         'parallel do')
    '''
    def __init__(self, root, line, position, dir_type):
        if dir_type not in self._types:
            raise RuntimeError(f"Error, unrecognised directive type "
                               f"'{dir_type}'. Should be one of {self._types}")
        if position not in self._positions:
            raise RuntimeError(f"Error, unrecognised position '{position}'. "
                               f"Should be one of {self._positions}")
        self._my_type_my_type = dir_type
        self._position_position = position
        Comment.__init__(self, root, line)
 
    @property
    def type(self):
        '''
        :returns: the type of this Directive.
        :rtype: str
        '''
        return self._my_type_my_type
 
    @property
    def position(self):
        '''
        :returns: the position of this Directive ('begin' or 'end').
        :rtype: str
        '''
        return self._position_position
 
 
class OMPDirective(Directive):
    '''
    Subclass Directive for OpenMP directives so we can reason about
    them when walking the tree.
 
    :param root: the parent node in the AST to which we are adding the \
                 directive.
    :type root: subclass of :py:class:`fparser.common.base_classes.Statement`
    :param line: the fparser object which we will manipulate to create \
                 the desired directive.
    :type line: :py:class:`fparser.common.readfortran.Comment`
    :param str position: e.g. 'begin' or 'end' (language specific).
    :param str dir_type: the type of directive that this is (e.g. \
                         'parallel do').
    '''
    def __init__(self, root, line, position, dir_type):
        self._types_types = ["parallel do", "parallel", "do", "master", "single",
                       "taskloop", "taskwait", "declare"]
        self._positions_positions = ["begin", "end"]
 
        super(OMPDirective, self).__init__(root, line, position, dir_type)
 
 
class ACCDirective(Directive):
    '''
    Subclass Directive for OpenACC directives so we can reason about them
    when walking the tree.
 
    :param root: the parent node in the AST to which we are adding the \
                 directive.
    :type root: subclass of :py:class:`fparser.common.base_classes.Statement`
    :param line: the fparser object which we will manipulate to create \
                 the desired directive.
    :type line: :py:class:`fparser.common.readfortran.Comment`
    :param str position: e.g. 'begin' or 'end' (language specific).
    :param str dir_type: the type of directive that this is (e.g. \
                         'loop').
    '''
    def __init__(self, root, line, position, dir_type):
        self._types_types = ["parallel", "kernels", "enter data", "loop", "routine"]
        self._positions_positions = ["begin", "end"]
 
        super(ACCDirective, self).__init__(root, line, position, dir_type)
 
 
# This section provides new classes which provide a relatively high
# level interface to creating code and adding code to an existing ast
 
 
class BaseGen():
    ''' The base class for all classes that are responsible for generating
    distinct code elements (modules, subroutines, do loops etc.) '''
    def __init__(self, parent, root):
        self._parent_parent = parent
        self._root_root = root
        self._children_children = []
 
    @property
    def parent(self):
        ''' Returns the parent of this object '''
        return self._parent_parent
 
    @property
    def children(self):
        ''' Returns the list of children of this object '''
        return self._children_children
 
    @property
    def root(self):
        ''' Returns the root of the tree containing this object '''
        return self._root_root
 
    def add(self, new_object, position=None):
        '''Adds a new object to the tree. The actual position is determined by
        the position argument. Note, there are two trees, the first is
        the f2pygen object tree, the other is the f2py generated code
        tree. These are similar but different. At the moment we
        specify where to add things in terms of the f2pygen tree
        (which is a higher level api) but we also insert into the f2py
        tree at exactly the same location which needs to be sorted out
        at some point.
 
        '''
 
        # By default the position is 'append'. We set it up this way for
        # safety because in python, default arguments are instantiated
        # as objects at the time of definition. If this object is
        # subsequently modified then the value of the default argument
        # is modified for subsequent calls of this routine.
        if position is None:
            position = ["append"]
 
        if position[0] == "auto":
            raise Exception("Error: BaseGen:add: auto option must be "
                            "implemented by the sub class!")
        options = ["append", "first", "after", "before", "insert",
                   "before_index", "after_index"]
        if position[0] not in options:
            raise Exception(f"Error: BaseGen:add: supported positions are "
                            f"{options} but found {position[0]}")
        if position[0] == "append":
            self.rootroot.content.append(new_object.root)
        elif position[0] == "first":
            self.rootroot.content.insert(0, new_object.root)
        elif position[0] == "insert":
            index = position[1]
            self.rootroot.content.insert(index, new_object.root)
        elif position[0] == "after":
            idx = index_of_object(self.rootroot.content, position[1])
            self.rootroot.content.insert(idx+1, new_object.root)
        elif position[0] == "after_index":
            self.rootroot.content.insert(position[1]+1, new_object.root)
        elif position[0] == "before_index":
            self.rootroot.content.insert(position[1], new_object.root)
        elif position[0] == "before":
            try:
                idx = index_of_object(self.rootroot.content, position[1])
            except Exception as err:
                print(str(err))
                raise RuntimeError(
                    "Failed to find supplied object in existing content - "
                    "is it a child of the parent?")
            self.rootroot.content.insert(idx, new_object.root)
        else:
            raise Exception("Error: BaseGen:add: internal error, should "
                            "not get to here")
        self.childrenchildren.append(new_object)
 
    def previous_loop(self):
        ''' Returns the *last* occurrence of a loop in the list of
        siblings of this node '''
        from fparser.one.block_statements import Do
        for sibling in reversed(self.rootroot.content):
            if isinstance(sibling, Do):
                return sibling
        raise RuntimeError("Error, no loop found - there is no previous loop")
 
    def last_declaration(self):
        '''Returns the *last* occurrence of a Declaration in the list of
            siblings of this node
 
        '''
        from fparser.one.typedecl_statements import TypeDeclarationStatement
        for sibling in reversed(self.rootroot.content):
            if isinstance(sibling, TypeDeclarationStatement):
                return sibling
 
        raise RuntimeError("Error, no variable declarations found")
 
    def start_parent_loop(self, debug=False):
        ''' Searches for the outer-most loop containing this object. Returns
        the index of that line in the content of the parent. '''
        from fparser.one.block_statements import Do
        if debug:
            print("Entered before_parent_loop")
            print(f"The type of the current node is {type(self.root)}")
            print(("If the current node is a Do loop then move up to the "
                   "top of the do loop nest"))
 
        # First off, check that we do actually have an enclosing Do loop
        current = self.rootroot
        while not isinstance(current, Do) and getattr(current, 'parent', None):
            current = current.parent
        if not isinstance(current, Do):
            raise RuntimeError("This node has no enclosing Do loop")
 
        current = self.rootroot
        local_current = self
        while isinstance(current.parent, Do):
            if debug:
                print("Parent is a do loop so moving to the parent")
            current = current.parent
            local_current = local_current.parent
        if debug:
            print("The type of the current node is now " + str(type(current)))
            print("The type of parent is " + str(type(current.parent)))
            print("Finding the loops position in its parent ...")
        index = current.parent.content.index(current)
        if debug:
            print("The loop's index is ", index)
        parent = current.parent
        local_current = local_current.parent
        if debug:
            print("The type of the object at the index is " +
                  str(type(parent.content[index])))
            print("If preceding node is a directive then move back one")
        if index == 0:
            if debug:
                print("current index is 0 so finish")
        elif isinstance(parent.content[index-1], Directive):
            if debug:
                print(
                    f"preceding node is a directive so find out what type ..."
                    f"\n type is {parent.content[index-1].position}"
                    f"\n diretive is {parent.content[index-1]}")
            if parent.content[index-1].position == "begin":
                if debug:
                    print("type of directive is begin so move back one")
                index -= 1
            else:
                if debug:
                    print("directive type is not begin so finish")
        else:
            if debug:
                print("preceding node is not a directive so finish")
        if debug:
            print("type of final location ", type(parent.content[index]))
            print("code for final location ", str(parent.content[index]))
        return local_current, parent.content[index]
 
 
class ProgUnitGen(BaseGen):
    ''' Functionality relevant to program units (currently modules,
    subroutines)'''
    def __init__(self, parent, sub):
        BaseGen.__init__(self, parent, sub)
 
    def add(self, content, position=None, bubble_up=False):
        '''
        Specialise the add method to provide module- and subroutine-
        -specific intelligent adding of use statements, implicit
        none statements and declarations if the position argument
        is set to auto (which is the default).
 
        :param content: the Node (or sub-tree of Nodes) to add in to \
                        the AST.
        :type content: :py:class:`psyclone.f2pygen.BaseGen`
        :param list position: where to insert the node. One of "append", \
                              "first", "insert", "after", "after_index", \
                              "before_index", "before" or "auto". For the \
                              *_index options, the second element of the \
                              list holds the integer index.
        :param bool bubble_up: whether or not object (content) is in the \
                               process of being bubbled-up.
        '''
        # By default the position is 'auto'. We set it up this way for
        # safety because in python, default arguments are instantiated
        # as objects at the time of definition. If this object is
        # subsequently modified then the value of the default argument
        # is modified for subsequent calls of this routine.
        if position is None:
            position = ["auto"]
 
        # For an object to be added to another we require that they
        # share a common ancestor. This means that the added object must
        # have the current object or one of its ancestors as an ancestor.
        # Loop over the ancestors of this object (starting with itself)
        self_ancestor = self.rootroot
        while self_ancestor:
            # Loop over the ancestors of the object being added
            obj_parent = content.root.parent
            while (obj_parent != self_ancestor and
                   getattr(obj_parent, 'parent', None)):
                obj_parent = obj_parent.parent
            if obj_parent == self_ancestor:
                break
            # Object being added is not an ancestor of the current
            # self_ancestor so move one level back up the tree and
            # try again
            if getattr(self_ancestor, 'parent', None):
                self_ancestor = self_ancestor.parent
            else:
                break
 
        if obj_parent != self_ancestor:
            raise RuntimeError(
                f"Cannot add '{content}' to '{self}' because it is not a "
                f"descendant of it or of any of its ancestors.")
 
        if bubble_up:
            # If content has been passed on (is being bubbled up) then change
            # its parent to be this object
            content.root.parent = self.rootroot
 
        if position[0] != "auto":
            # position[0] is not 'auto' so the baseclass can deal with it
            BaseGen.add(self, content, position)
        else:
            # position[0] == "auto" so insert in a context sensitive way
            if isinstance(content, BaseDeclGen):
 
                if isinstance(content, (DeclGen, CharDeclGen)):
                    # have I already been declared?
                    for child in self._children_children:
                        if isinstance(child, (DeclGen, CharDeclGen)):
                            # is this declaration the same type as me?
                            if child.root.name == content.root.name:
                                # we are modifying the list so we need
                                # to iterate over a copy
                                for var_name in content.root.entity_decls[:]:
                                    for child_name in child.root.entity_decls:
                                        if var_name.lower() == \
                                           child_name.lower():
                                            content.root.entity_decls.\
                                                remove(var_name)
                                            if not content.root.entity_decls:
                                                # return as all variables in
                                                # this declaration already
                                                # exist
                                                return
                if isinstance(content, TypeDeclGen):
                    # have I already been declared?
                    for child in self._children_children:
                        if isinstance(child, TypeDeclGen):
                            # is this declaration the same type as me?
                            if child.root.selector[1] == \
                               content.root.selector[1]:
                                # we are modifying the list so we need
                                # to iterate over a copy
                                for var_name in content.root.entity_decls[:]:
                                    for child_name in child.root.entity_decls:
                                        if var_name.lower() == \
                                           child_name.lower():
                                            content.root.entity_decls.\
                                                remove(var_name)
                                            if not content.root.entity_decls:
                                                # return as all variables in
                                                # this declaration already
                                                # exist
                                                return
 
                index = 0
                # skip over any use statements
                index = self._skip_use_and_comments_skip_use_and_comments(index)
                # skip over implicit none if it exists
                index = self._skip_imp_none_and_comments_skip_imp_none_and_comments(index)
                # skip over any declarations which have an intent
                try:
                    intent = True
                    while intent:
                        intent = False
                        for attr in self.rootroot.content[index].attrspec:
                            if attr.find("intent") == 0:
                                intent = True
                                index += 1
                                break
                except AttributeError:
                    pass
            elif isinstance(content.root, fparser1.statements.Use):
                # have I already been declared?
                for child in self._children_children:
                    if isinstance(child, UseGen):
                        if child.root.name == content.root.name:
                            # found an existing use with the same name
                            if not child.root.isonly and not \
                               content.root.isonly:
                                # both are generic use statements so
                                # skip this declaration
                                return
                            if child.root.isonly and not content.root.isonly:
                                # new use is generic and existing use
                                # is specific so we can safely add
                                pass
                            if not child.root.isonly and content.root.isonly:
                                # existing use is generic and new use
                                # is specific so we can skip this
                                # declaration
                                return
                            if child.root.isonly and content.root.isonly:
                                # we are modifying the list so we need
                                # to iterate over a copy
                                for new_name in content.root.items[:]:
                                    for existing_name in child.root.items:
                                        if existing_name.lower() == \
                                           new_name.lower():
                                            content.root.items.remove(new_name)
                                            if not content.root.items:
                                                return
                index = 0
            elif isinstance(content, ImplicitNoneGen):
                # does implicit none already exist?
                for child in self._children_children:
                    if isinstance(child, ImplicitNoneGen):
                        return
                # skip over any use statements
                index = 0
                index = self._skip_use_and_comments_skip_use_and_comments(index)
            else:
                index = len(self.rootroot.content) - 1
            self.rootroot.content.insert(index, content.root)
            self._children_children.append(content)
 
    def _skip_use_and_comments(self, index):
        ''' skip over any use statements and comments in the ast '''
        while isinstance(self.rootroot.content[index],
                         fparser1.statements.Use) or\
            isinstance(self.rootroot.content[index],
                       fparser1.statements.Comment):
            index += 1
        # now roll back to previous Use
        while isinstance(self.rootroot.content[index-1],
                         fparser1.statements.Comment):
            index -= 1
        return index
 
    def _skip_imp_none_and_comments(self, index):
        ''' skip over an implicit none statement if it exists and any
        comments before it '''
        end_index = index
        while isinstance(self.rootroot.content[index],
                         fparser1.typedecl_statements.Implicit) or\
            isinstance(self.rootroot.content[index],
                       fparser1.statements.Comment):
            if isinstance(self.rootroot.content[index],
                          fparser1.typedecl_statements.Implicit):
                end_index = index + 1
                break
            else:
                index = index + 1
        return end_index
 
 
class PSyIRGen(BaseGen):
    ''' Create a Fortran block of code that comes from a given PSyIR tree.
 
    :param parent: node in AST to which we are adding the PSyIR block.
    :type parent: :py:class:`psyclone.f2pygen.BaseGen`
    :param content: the PSyIR tree we are adding.
    :type content: :py:class:`psyclone.psyir.nodes.Node`
 
    '''
 
    def __init__(self, parent, content):
        # Import FortranWriter here to avoid circular-dependency
        # pylint: disable=import-outside-toplevel
        from psyclone.psyir.backend.fortran import FortranWriter
        # We need the Config object in order to see whether or not to disable
        # the validation performed in the PSyIR backend.
        config = Config.get()
 
        # Use the PSyIR Fortran backend to generate Fortran code of the
        # supplied PSyIR tree and pass the resulting code to the fparser1
        # Fortran parser.
        fortran_writer = FortranWriter(
            check_global_constraints=config.backend_checks_enabled)
        reader = FortranStringReader(fortran_writer(content),
                                     ignore_comments=False)
        # Set reader as free form, strict
        reader.set_format(FortranFormat(True, True))
        fparser1_parser = FortranParser(reader, ignore_comments=False)
        fparser1_parser.parse()
 
        # If the fparser content is larger than 1, add all the nodes but
        # the last one as siblings of self. This is done because self
        # can only represent one node.
        for fparser_node in fparser1_parser.block.content[:-1]:
            f2pygen_node = BaseGen(parent, fparser_node)
            f2pygen_node.root.parent = parent.root
            parent.add(f2pygen_node)
 
        # Update this f2pygen node to be equivalent to the last of the
        # fparser nodes that represent the provided content.
        BaseGen.__init__(self, parent, fparser1_parser.block.content[-1])
        self.rootroot.parent = parent.root
 
 
class ModuleGen(ProgUnitGen):
    ''' create a fortran module '''
    def __init__(self, name="", contains=True, implicitnone=True):
        from fparser import api
 
        code = '''\
module vanilla
'''
        if contains:
            code += '''\
contains
'''
        code += '''\
end module vanilla
'''
        tree = api.parse(code, ignore_comments=False)
        module = tree.content[0]
        module.name = name
        endmod = module.content[len(module.content)-1]
        endmod.name = name
        ProgUnitGen.__init__(self, None, module)
        if implicitnone:
            self.addaddadd(ImplicitNoneGen(self))
 
    def add_raw_subroutine(self, content):
        ''' adds a subroutine to the module that is a raw f2py parse object.
            This is used for inlining kernel subroutines into a module.
        '''
        from psyclone.parse.kernel import KernelProcedure
        if not isinstance(content, KernelProcedure):
            raise Exception(
                "Expecting a KernelProcedure type but received " +
                str(type(content)))
        content.ast.parent = self.rootroot
        # add content after any existing subroutines
        index = len(self.rootroot.content) - 1
        self.rootroot.content.insert(index, content.ast)
 
 
class CommentGen(BaseGen):
    ''' Create a Fortran Comment '''
    def __init__(self, parent, content):
        '''
        :param parent: node in AST to which to add the Comment as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param str content: the content of the comment
        '''
        reader = FortranStringReader("! content\n", ignore_comments=False)
        reader.set_format(FortranFormat(True, True))  # free form, strict
        subline = reader.next()
 
        my_comment = Comment(parent.root, subline)
        my_comment.content = content
 
        BaseGen.__init__(self, parent, my_comment)
 
 
class DirectiveGen(BaseGen):
    '''
    Class for creating a Fortran directive, e.g. OpenMP or OpenACC.
 
    :param parent: node in AST to which to add directive as a child.
    :type parent: :py:class:`psyclone.f2pygen.BaseGen`
    :param str language: the type of directive (e.g. OMP or ACC).
    :param str position: "end" if this is the end of a directive block.
    :param str directive_type: the directive itself (e.g. "PARALLEL DO").
    :param str content: any additional arguments to add to the directive \
                        (e.g. "PRIVATE(ji)").
 
    :raises RuntimeError: if an unrecognised directive language is specified.
    '''
    def __init__(self, parent, language, position, directive_type, content=""):
        self._supported_languages_supported_languages = ["omp", "acc"]
        self._language_language = language
        self._directive_type_directive_type = directive_type
 
        reader = FortranStringReader("! content\n", ignore_comments=False)
        reader.set_format(FortranFormat(True, True))  # free form, strict
        subline = reader.next()
 
        if language == "omp":
            my_comment = OMPDirective(parent.root, subline, position,
                                      directive_type)
            my_comment.content = "$omp"
        elif language == "acc":
            my_comment = ACCDirective(parent.root, subline, position,
                                      directive_type)
            my_comment.content = "$acc"
        else:
            raise RuntimeError(
                f"Error, unsupported directive language. Expecting one of "
                f"{self._supported_languages} but found '{language}'")
        if position == "end":
            my_comment.content += " end"
        my_comment.content += " " + directive_type
        if content != "":
            my_comment.content += " " + content
 
        BaseGen.__init__(self, parent, my_comment)
 
 
class ImplicitNoneGen(BaseGen):
    ''' Generate a Fortran 'implicit none' statement '''
    def __init__(self, parent):
        '''
        :param parent: node in AST to which to add 'implicit none' as a child
        :type parent: :py:class:`psyclone.f2pygen.ModuleGen` or
                      :py:class:`psyclone.f2pygen.SubroutineGen`
 
        :raises Exception: if `parent` is not a ModuleGen or SubroutineGen
        '''
        if not isinstance(parent, ModuleGen) and not isinstance(parent,
                                                                SubroutineGen):
            raise Exception(
                f"The parent of ImplicitNoneGen must be a module or a "
                f"subroutine, but found {type(parent)}")
        reader = FortranStringReader("IMPLICIT NONE\n")
        reader.set_format(FortranFormat(True, True))  # free form, strict
        subline = reader.next()
 
        from fparser.one.typedecl_statements import Implicit
        my_imp_none = Implicit(parent.root, subline)
 
        BaseGen.__init__(self, parent, my_imp_none)
 
 
class SubroutineGen(ProgUnitGen):
    ''' Generate a Fortran subroutine '''
    def __init__(self, parent, name="", args=None, implicitnone=False):
        '''
        :param parent: node in AST to which to add Subroutine as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param str name: name of the Fortran subroutine
        :param list args: list of arguments accepted by the subroutine
        :param bool implicitnone: whether or not we should specify
                                  "implicit none" for the body of this
                                  subroutine
        '''
        reader = FortranStringReader(
            "subroutine vanilla(vanilla_arg)\nend subroutine")
        reader.set_format(FortranFormat(True, True))  # free form, strict
        subline = reader.next()
        endsubline = reader.next()
 
        from fparser.one.block_statements import Subroutine, EndSubroutine
        self._sub_sub = Subroutine(parent.root, subline)
        self._sub_sub.name = name
        if args is None:
            args = []
        self._sub_sub.args = args
        endsub = EndSubroutine(self._sub_sub, endsubline)
        self._sub_sub.content.append(endsub)
        ProgUnitGen.__init__(self, parent, self._sub_sub)
        if implicitnone:
            self.addaddadd(ImplicitNoneGen(self))
 
    @property
    def args(self):
        ''' Returns the list of arguments of this subroutine '''
        return self._sub_sub.args
 
    @args.setter
    def args(self, namelist):
        ''' sets the subroutine arguments to the values in the list provide.'''
        self._sub_sub.args = namelist
 
 
class CallGen(BaseGen):
    ''' Generates a Fortran call of a subroutine '''
    def __init__(self, parent, name="", args=None):
        '''
        :param parent: node in AST to which to add CallGen as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param str name: the name of the routine to call
        :param list args: list of arguments to pass to the call
        '''
        reader = FortranStringReader("call vanilla(vanilla_arg)")
        reader.set_format(FortranFormat(True, True))  # free form, strict
        myline = reader.next()
 
        from fparser.one.block_statements import Call
        self._call_call = Call(parent.root, myline)
        self._call_call.designator = name
        if args is None:
            args = []
        self._call_call.items = args
 
        BaseGen.__init__(self, parent, self._call_call)
 
 
class UseGen(BaseGen):
    ''' Generate a Fortran use statement '''
    def __init__(self, parent, name="", only=False, funcnames=None):
        '''
        :param parent: node in AST to which to add UseGen as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param str name: name of the module to USE
        :param bool only: whether this USE has an ONLY clause
        :param list funcnames: list of names to follow ONLY clause
        '''
        reader = FortranStringReader("use kern,only : func1_kern=>func1")
        reader.set_format(FortranFormat(True, True))  # free form, strict
        myline = reader.next()
        root = parent.root
        from fparser.one.block_statements import Use
        use = Use(root, myline)
        use.name = name
        use.isonly = only
        if funcnames is None:
            funcnames = []
            use.isonly = False
        local_funcnames = funcnames[:]
        use.items = local_funcnames
        BaseGen.__init__(self, parent, use)
 
 
def adduse(name, parent, only=False, funcnames=None):
    '''
    Adds a use statement with the specified name to the supplied object.
    This routine is required when modifying an existing AST (e.g. when
    modifying a kernel). The classes are used when creating an AST from
    scratch (for the PSy layer).
 
    :param str name: name of module to USE
    :param parent: node in fparser1 AST to which to add this USE as a child
    :type parent: :py:class:`fparser.one.block_statements.*`
    :param bool only: whether this USE has an "ONLY" clause
    :param list funcnames: list of quantities to follow the "ONLY" clause
 
    :returns: an fparser1 Use object
    :rtype: :py:class:`fparser.one.block_statements.Use`
    '''
    reader = FortranStringReader("use kern,only : func1_kern=>func1")
    reader.set_format(FortranFormat(True, True))  # free form, strict
    myline = reader.next()
 
    # find an appropriate place to add in our use statement
    while not isinstance(parent, (fparser1.block_statements.Program,
                                  fparser1.block_statements.Module,
                                  fparser1.block_statements.Subroutine)):
        parent = parent.parent
    use = fparser1.block_statements.Use(parent, myline)
    use.name = name
    use.isonly = only
    if funcnames is None:
        funcnames = []
        use.isonly = False
    use.items = funcnames
 
    parent.content.insert(0, use)
    return use
 
 
class AllocateGen(BaseGen):
    ''' Generates a Fortran allocate statement '''
    def __init__(self, parent, content, mold=None):
        '''
        :param parent: node to which to add this ALLOCATE as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param content: string or list of variables to allocate
        :type content: list of strings or a single string
        :param mold: A string to be used as the 'mold' parameter of ALLOCATE.
        :type mold: str or None.
 
        :raises RuntimeError: if `content` is not of correct type
        '''
        reader = FortranStringReader("allocate(dummy)")
        reader.set_format(FortranFormat(True, False))  # free form, strict
        myline = reader.next()
        self._decl_decl = fparser1.statements.Allocate(parent.root, myline)
        if isinstance(content, str):
            self._decl_decl.items = [content]
        elif isinstance(content, list):
            self._decl_decl.items = content
        else:
            raise RuntimeError(
                f"AllocateGen expected the content argument to be a str or"
                f" a list, but found {type(content)}")
        if mold:
            self._decl_decl.items.append(f"mold={mold}")
        BaseGen.__init__(self, parent, self._decl_decl)
 
 
class DeallocateGen(BaseGen):
    ''' Generates a Fortran deallocate statement '''
    def __init__(self, parent, content):
        '''
        :param parent: node to which to add this DEALLOCATE as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param content: string or list of variables to deallocate
        :type content: list of strings or a single string
 
        :raises RuntimeError: if `content` is not of correct type
        '''
        reader = FortranStringReader("deallocate(dummy)")
        reader.set_format(FortranFormat(True, False))  # free form, strict
        myline = reader.next()
        self._decl_decl = fparser1.statements.Deallocate(parent.root, myline)
        if isinstance(content, str):
            self._decl_decl.items = [content]
        elif isinstance(content, list):
            self._decl_decl.items = content
        else:
            raise RuntimeError(
                f"DeallocateGen expected the content argument to be a str"
                f" or a list, but found {type(content)}")
        BaseGen.__init__(self, parent, self._decl_decl)
 
 
class BaseDeclGen(BaseGen, metaclass=abc.ABCMeta):
    '''
    Abstract base class for all types of Fortran declaration. Uses the
    abc module so it cannot be instantiated.
 
    :param parent: node to which to add this declaration as a child.
    :type parent: :py:class:`psyclone.f2pygen.BaseGen`
    :param str datatype: the (intrinsic) type for this declaration.
    :param list entity_decls: list of variable names to declare.
    :param str intent: the INTENT attribute of this declaration.
    :param bool pointer: whether or not this is a pointer declaration.
    :param str dimension: the DIMENSION specifier (i.e. the xx in \
                          DIMENSION(xx)).
    :param bool allocatable: whether this declaration is for an \
                             ALLOCATABLE quantity.
    :param bool save: whether this declaration has the SAVE attribute.
    :param bool target: whether this declaration has the TARGET attribute.
    :param initial_values: initial value to give each variable.
    :type initial_values: list of str with same no. of elements as entity_decls
    :param bool private: whether this declaration has the PRIVATE attribute \
                         (default is False).
 
    :raises RuntimeError: if no variable names are specified.
    :raises RuntimeError: if the wrong number or type of initial values are \
                          supplied.
    :raises RuntimeError: if initial values are supplied for a quantity that \
                          is allocatable or has INTENT(in).
    :raises NotImplementedError: if initial values are supplied for array \
                                 variables (dimension != "").
 
    '''
    _decl = None  # Will hold the declaration object created by sub-class
 
    def __init__(self, parent, datatype="", entity_decls=None, intent="",
                 pointer=False, dimension="", allocatable=False,
                 save=False, target=False, initial_values=None, private=False):
        if entity_decls is None:
            raise RuntimeError(
                "Cannot create a variable declaration without specifying the "
                "name(s) of the variable(s)")
 
        # If initial values have been supplied then check that there
        # are the right number of them and that they are consistent
        # with the type of the variable(s) being declared.
        if initial_values:
            if len(initial_values) != len(entity_decls):
                raise RuntimeError(
                    f"f2pygen.DeclGen.init: number of initial values supplied "
                    f"({len(initial_values)}) does not match the number of "
                    f"variables to be declared ({len(entity_decls)}: "
                    f"{entity_decls})")
            if allocatable:
                raise RuntimeError(
                    f"Cannot specify initial values for variable(s) "
                    f"{entity_decls} because they have the 'allocatable' "
                    f"attribute.")
            if dimension:
                raise NotImplementedError(
                    "Specifying initial values for array declarations is not "
                    "currently supported.")
            if intent.lower() == "in":
                raise RuntimeError(
                    f"Cannot assign (initial) values to variable(s) "
                    f"{entity_decls} as they have INTENT(in).")
            # Call sub-class-provided implementation to check actual
            # values provided.
            self._check_initial_values_check_initial_values(datatype, initial_values)
 
        # Store the list of variable names
        self._names_names = entity_decls[:]
 
        # Make a copy of entity_decls as we may modify it
        local_entity_decls = entity_decls[:]
        if initial_values:
            # Create a list of 2-tuples
            value_pairs = zip(local_entity_decls, initial_values)
            # Construct an assignment from each tuple
            self._decl_decl.entity_decls = ["=".join(_) for _ in value_pairs]
        else:
            self._decl_decl.entity_decls = local_entity_decls
 
        # Construct the list of attributes
        my_attrspec = []
        if intent != "":
            my_attrspec.append(f"intent({intent})")
        if pointer:
            my_attrspec.append("pointer")
        if target:
            my_attrspec.append("target")
        if allocatable:
            my_attrspec.append("allocatable")
        if save:
            my_attrspec.append("save")
        if private:
            my_attrspec.append("private")
        if dimension != "":
            my_attrspec.append(f"dimension({dimension})")
        self._decl_decl.attrspec = my_attrspec
 
        super(BaseDeclGen, self).__init__(parent, self._decl_decl)
 
    @property
    def names(self):
        '''
        :returns: the names of the variables being declared.
        :rtype: list of str.
        '''
        return self._names_names
 
    @property
    def root(self):
        '''
        :returns: the associated Type object.
        :rtype: \
        :py:class:`fparser.one.typedecl_statements.TypeDeclarationStatement`.
        '''
        return self._decl_decl
 
    @abc.abstractmethod
    def _check_initial_values(self, dtype, values):
        '''
        Check that the supplied values are consistent with the requested
        data type. This method must be overridden in any sub-class of
        BaseDeclGen and is called by the BaseDeclGen constructor.
 
        :param str dtype: Fortran type.
        :param list values: list of values as strings.
        :raises RuntimeError: if the supplied values are not consistent \
                              with the specified data type or are not \
                              supported.
        '''
 
 
class DeclGen(BaseDeclGen):
    '''Generates a Fortran declaration for variables of various intrinsic
    types (integer, real and logical). For character variables
    CharDeclGen should be used.
 
    :param parent: node to which to add this declaration as a child.
    :type parent: :py:class:`psyclone.f2pygen.BaseGen`
    :param str datatype: the (intrinsic) type for this declaration.
    :param list entity_decls: list of variable names to declare.
    :param str intent: the INTENT attribute of this declaration.
    :param bool pointer: whether or not this is a pointer declaration.
    :param str kind: the KIND attribute to use for this declaration.
    :param str dimension: the DIMENSION specifier (i.e. the xx in \
                          DIMENSION(xx)).
    :param bool allocatable: whether this declaration is for an \
                             ALLOCATABLE quantity.
    :param bool save: whether this declaration has the SAVE attribute.
    :param bool target: whether this declaration has the TARGET attribute.
    :param initial_values: initial value to give each variable.
    :type initial_values: list of str with same no. of elements as \
                          entity_decls
    :param bool private: whether this declaration has the PRIVATE attribute \
                         (default is False).
 
    :raises RuntimeError: if datatype is not one of DeclGen.SUPPORTED_TYPES.
 
    '''
    # The Fortran intrinsic types supported by this class
    SUPPORTED_TYPES = ["integer", "real", "logical"]
 
    def __init__(self, parent, datatype="", entity_decls=None, intent="",
                 pointer=False, kind="", dimension="", allocatable=False,
                 save=False, target=False, initial_values=None, private=False):
 
        dtype = datatype.lower()
        if dtype not in self.SUPPORTED_TYPESSUPPORTED_TYPES:
            raise RuntimeError(
                f"f2pygen.DeclGen.init: Only {self.SUPPORTED_TYPES} types are "
                f"currently supported and you specified '{datatype}'")
 
        fort_fmt = FortranFormat(True, False)  # free form, strict
        if dtype == "integer":
            reader = FortranStringReader("integer :: vanilla")
            reader.set_format(fort_fmt)
            myline = reader.next()
            self._decl_decl_decl = fparser1.typedecl_statements.Integer(parent.root,
                                                              myline)
        elif dtype == "real":
            reader = FortranStringReader("real :: vanilla")
            reader.set_format(fort_fmt)
            myline = reader.next()
            self._decl_decl_decl = fparser1.typedecl_statements.Real(parent.root, myline)
        elif dtype == "logical":
            reader = FortranStringReader("logical :: vanilla")
            reader.set_format(fort_fmt)
            myline = reader.next()
            self._decl_decl_decl = fparser1.typedecl_statements.Logical(parent.root,
                                                              myline)
        else:
            # Defensive programming in case SUPPORTED_TYPES is added to
            # but not handled here
            raise InternalError(
                f"Type '{dtype}' is in DeclGen.SUPPORTED_TYPES "
                f"but not handled by constructor.")
 
        # Add any kind-selector
        if kind:
            self._decl_decl_decl.selector = ('', kind)
 
        super(DeclGen, self).__init__(parent=parent, datatype=datatype,
                                      entity_decls=entity_decls,
                                      intent=intent, pointer=pointer,
                                      dimension=dimension,
                                      allocatable=allocatable, save=save,
                                      target=target,
                                      initial_values=initial_values,
                                      private=private)
 
    def _check_initial_values(self, dtype, values):
        '''
        Check that the supplied values are consistent with the requested
        data type. Note that this checking is fairly basic and does not
        support a number of valid Fortran forms (e.g. arithmetic expressions
        involving constants or parameters).
 
        :param str dtype: Fortran intrinsic type.
        :param list values: list of values as strings.
        :raises RuntimeError: if the supplied values are not consistent \
                              with the specified data type or are not \
                              supported.
        '''
        from fparser.two.pattern_tools import abs_name, \
            abs_logical_literal_constant, abs_signed_int_literal_constant, \
            abs_signed_real_literal_constant
        if dtype == "logical":
            # Can be .true., .false. or a valid Fortran variable name
            for val in values:
                if not abs_logical_literal_constant.match(val) and \
                   not abs_name.match(val):
                    raise RuntimeError(
                        f"Initial value of '{val}' for a logical variable is "
                        f"invalid or unsupported")
        elif dtype == "integer":
            # Can be a an integer expression or a valid Fortran variable name
            for val in values:
                if not abs_signed_int_literal_constant.match(val) and \
                   not abs_name.match(val):
                    raise RuntimeError(
                        f"Initial value of '{val}' for an integer variable is "
                        f"invalid or unsupported")
        elif dtype == "real":
            # Can be a floating-point expression or a valid Fortran name
            for val in values:
                if not abs_signed_real_literal_constant.match(val) and \
                   not abs_name.match(val):
                    raise RuntimeError(
                        f"Initial value of '{val}' for a real variable is "
                        f"invalid or unsupported")
        else:
            # We should never get to here because we check that the type
            # is supported before calling this routine.
            raise InternalError(
                f"unsupported type '{dtype}' - should be "
                f"one of {DeclGen.SUPPORTED_TYPES}")
 
 
class CharDeclGen(BaseDeclGen):
    '''
    Generates a Fortran declaration for character variables.
 
    :param parent: node to which to add this declaration as a child.
    :type parent: :py:class:`psyclone.f2pygen.BaseGen`.
    :param list entity_decls: list of variable names to declare.
    :param str intent: the INTENT attribute of this declaration.
    :param bool pointer: whether or not this is a pointer declaration.
    :param str kind: the KIND attribute to use for this declaration.
    :param str dimension: the DIMENSION specifier (i.e. the xx in \
                          DIMENSION(xx)).
    :param bool allocatable: whether this declaration is for an \
                             ALLOCATABLE quantity.
    :param bool save: whether this declaration has the SAVE attribute.
    :param bool target: whether this declaration has the TARGET attribute.
    :param str length: expression to use for the (len=xx) selector.
    :param initial_values: list of initial values, one for each variable. \
        Each of these can be either a variable name or a literal, quoted \
        string (e.g. "'hello'"). Default is None.
    :type initial_values: list of str with same no. of elements as entity_decls
    :param bool private: whether this declaration has the PRIVATE attribute.
 
    '''
    def __init__(self, parent, entity_decls=None, intent="",
                 pointer=False, kind="", dimension="", allocatable=False,
                 save=False, target=False, length="", initial_values=None,
                 private=False):
 
        reader = FortranStringReader(
            "character(len=vanilla_len) :: vanilla")
        reader.set_format(FortranFormat(True, False))
        myline = reader.next()
        self._decl_decl_decl = fparser1.typedecl_statements.Character(parent.root,
                                                            myline)
        # Add character- and kind-selectors
        self._decl_decl_decl.selector = (length, kind)
 
        super(CharDeclGen, self).__init__(parent=parent,
                                          datatype="character",
                                          entity_decls=entity_decls,
                                          intent=intent, pointer=pointer,
                                          dimension=dimension,
                                          allocatable=allocatable, save=save,
                                          target=target,
                                          initial_values=initial_values,
                                          private=private)
 
    def _check_initial_values(self, _, values):
        '''
        Check that initial values provided for a Character declaration are
        valid.
        :param _: for consistency with base-class interface.
        :param list values: list of strings containing initial values.
        :raises RuntimeError: if any of the supplied initial values is not \
                              valid for a Character declaration.
        '''
        from fparser.two.pattern_tools import abs_name
        # Can be a quoted string or a valid Fortran name
        # TODO it would be nice if fparser.two.pattern_tools provided
        # e.g. abs_character_literal_constant
        for val in values:
            if not abs_name.match(val):
                if not ((val.startswith("'") and val.endswith("'")) or
                        (val.startswith('"') and val.endswith('"'))):
                    raise RuntimeError(
                        f"Initial value of '{val}' for a character variable "
                        f"is invalid or unsupported")
 
 
class TypeDeclGen(BaseDeclGen):
    '''
    Generates a Fortran declaration for variables of a derived type.
 
    :param parent: node to which to add this declaration as a child.
    :type parent: :py:class:`psyclone.f2pygen.BaseGen`
    :param str datatype: the type for this declaration.
    :param list entity_decls: list of variable names to declare.
    :param str intent: the INTENT attribute of this declaration.
    :param bool pointer: whether or not this is a pointer declaration.
    :param str dimension: the DIMENSION specifier (i.e. the xx in \
                          DIMENSION(xx)).
    :param bool allocatable: whether this declaration is for an \
                             ALLOCATABLE quantity.
    :param bool save: whether this declaration has the SAVE attribute.
    :param bool target: whether this declaration has the TARGET attribute.
    :param bool is_class: whether this is a class rather than type declaration.
    :param bool private: whether or not this declaration has the PRIVATE \
                         attribute. (Defaults to False.)
    '''
    def __init__(self, parent, datatype="", entity_decls=None, intent="",
                 pointer=False, dimension="", allocatable=False,
                 save=False, target=False, is_class=False, private=False):
        if is_class:
            reader = FortranStringReader("class(vanillatype) :: vanilla")
        else:
            reader = FortranStringReader("type(vanillatype) :: vanilla")
        reader.set_format(FortranFormat(True, False))  # free form, strict
        myline = reader.next()
        if is_class:
            self._decl_decl_decl = fparser1.typedecl_statements.Class(parent.root,
                                                            myline)
        else:
            self._decl_decl_decl = fparser1.typedecl_statements.Type(parent.root, myline)
        self._decl_decl_decl.selector = ('', datatype)
 
        super(TypeDeclGen, self).__init__(parent=parent, datatype=datatype,
                                          entity_decls=entity_decls,
                                          intent=intent, pointer=pointer,
                                          dimension=dimension,
                                          allocatable=allocatable, save=save,
                                          target=target, private=private)
 
    def _check_initial_values(self, _type, _values):
        '''
        Simply here to override abstract method in base class. It is an
        error if we ever call it because we don't support initial values for
        declarations of derived types.
 
        :param str _type: the type of the Fortran variable to be declared.
        :param list _values: list of str containing initialisation \
                             values/expressions.
        :raises InternalError: because specifying initial values for \
                               variables of derived type is not supported.
        '''
        raise InternalError(
            "This method should not have been called because initial values "
            "for derived-type declarations are not supported.")
 
 
class TypeCase(Case):
    ''' Generate a Fortran SELECT CASE statement '''
    # TODO can this whole class be deleted?
    def tofortran(self, isfix=None):
        tab = self.get_indent_tab(isfix=isfix)
        type_str = 'TYPE IS'
        if self.items:
            item_list = []
            for item in self.items:
                item_list.append((' : '.join(item)).strip())
            type_str += f" ( {(', '.join(item_list))} )"
        else:
            type_str = 'CLASS DEFAULT'
        if self.name:
            type_str += ' ' + self.name
        return tab + type_str
 
 
class SelectionGen(BaseGen):
    ''' Generate a Fortran SELECT block '''
    # TODO can this whole class be deleted?
 
    def __init__(self, parent, expr="UNSET", typeselect=False):
        '''
        Construct a SelectionGen for creating a SELECT block
 
        :param parent: node to which to add this select block as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param str expr: the CASE expression
        :param bool typeselect: whether or not this is a SELECT TYPE rather
                                than a SELECT CASE
        '''
        self._typeselect_typeselect = typeselect
        reader = FortranStringReader(
            "SELECT CASE (x)\nCASE (1)\nCASE DEFAULT\nEND SELECT")
        reader.set_format(FortranFormat(True, True))  # free form, strict
        select_line = reader.next()
        self._case_line_case_line = reader.next()
        self._case_default_line_case_default_line = reader.next()
        end_select_line = reader.next()
        if self._typeselect_typeselect:
            select = SelectType(parent.root, select_line)
        else:
            select = SelectCase(parent.root, select_line)
        endselect = EndSelect(select, end_select_line)
        select.expr = expr
        select.content.append(endselect)
        BaseGen.__init__(self, parent, select)
 
    def addcase(self, casenames, content=None):
        ''' Add a case to this select block '''
        if content is None:
            content = []
        if self._typeselect_typeselect:
            case = TypeCase(self.rootroot, self._case_line_case_line)
        else:
            case = Case(self.rootroot, self._case_line_case_line)
        case.items = [casenames]
        self.rootroot.content.insert(0, case)
        idx = 0
        for stmt in content:
            idx += 1
            self.rootroot.content.insert(idx, stmt.root)
 
    def adddefault(self):
        ''' Add the default case to this select block '''
        if self._typeselect_typeselect:
            case_default = TypeCase(self.rootroot, self._case_default_line_case_default_line)
        else:
            case_default = Case(self.rootroot, self._case_default_line_case_default_line)
        self.rootroot.content.insert(len(self.rootroot.content)-1, case_default)
 
 
class DoGen(BaseGen):
    ''' Create a Fortran Do loop '''
    def __init__(self, parent, variable_name, start, end, step=None):
        '''
        :param parent: the node to which to add this do loop as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param str variable_name: the name of the loop variable
        :param str start: start value for Do loop
        :param str end: upper-limit of Do loop
        :param str step: increment to use in Do loop
        '''
        reader = FortranStringReader("do i=1,n\nend do")
        reader.set_format(FortranFormat(True, True))  # free form, strict
        doline = reader.next()
        enddoline = reader.next()
        dogen = fparser1.block_statements.Do(parent.root, doline)
        dogen.loopcontrol = variable_name + "=" + start + "," + end
        if step is not None:
            dogen.loopcontrol = dogen.loopcontrol + "," + step
        enddo = fparser1.block_statements.EndDo(dogen, enddoline)
        dogen.content.append(enddo)
 
        BaseGen.__init__(self, parent, dogen)
 
    def add(self, content, position=None, bubble_up=False):
        if position is None:
            position = ["auto"]
 
        if position[0] == "auto" and bubble_up:  # pragma: no cover
            # There's currently no case where a bubbled-up statement
            # will live within a do loop so bubble it up again.
            self.parentparent.add(content, bubble_up=True)
            return
 
        if position[0] == "auto" or position[0] == "append":
            if (position[0] == "auto" and
                    bubble_up_type(content)):  # pragma: no cover
                # use and declaration statements cannot appear in a do loop
                # so pass on to parent
                self.parentparent.add(content, bubble_up=True)
                return
            else:
                # append at the end of the loop. This is not a simple
                # append as the last element in the loop is the "end
                # do" so we insert at the penultimate location
                BaseGen.add(self, content,
                            position=["insert", len(self.rootroot.content)-1])
        else:
            BaseGen.add(self, content, position=position)
 
 
class IfThenGen(BaseGen):
    ''' Generate a fortran if, then, end if statement. '''
 
    def __init__(self, parent, clause):
        '''
        :param parent: Node to which to add this IfThen as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param str clause: the condition, xx, to evaluate in the if(xx)then
        '''
        reader = FortranStringReader("if (dummy) then\nend if")
        reader.set_format(FortranFormat(True, True))  # free form, strict
        ifthenline = reader.next()
        endifline = reader.next()
 
        my_if = fparser1.block_statements.IfThen(parent.root, ifthenline)
        my_if.expr = clause
        my_endif = fparser1.block_statements.EndIfThen(my_if, endifline)
        my_if.content.append(my_endif)
 
        BaseGen.__init__(self, parent, my_if)
 
    def add(self, content, position=None):
        if position is None:
            position = ["auto"]
        if position[0] == "auto" or position[0] == "append":
            if position[0] == "auto" and bubble_up_type(content):
                # use and declaration statements cannot appear in an if
                # block so pass on (bubble-up) to parent
                self.parentparent.add(content, bubble_up=True)
            else:
                # append at the end of the loop. This is not a simple
                # append as the last element in the if is the "end if"
                # so we insert at the penultimate location
                BaseGen.add(self, content,
                            position=["insert", len(self.rootroot.content)-1])
        else:
            BaseGen.add(self, content, position=position)
 
 
class AssignGen(BaseGen):
    ''' Generates a Fortran statement where a value is assigned to a
        variable quantity '''
 
    def __init__(self, parent, lhs="", rhs="", pointer=False):
        '''
        :param parent: the node to which to add this assignment as a child
        :type parent: :py:class:`psyclone.f2pygen.BaseGen`
        :param str lhs: the LHS of the assignment expression
        :param str rhs: the RHS of the assignment expression
        :param bool pointer: whether or not this is a pointer assignment
        '''
        if pointer:
            reader = FortranStringReader("lhs=>rhs")
        else:
            reader = FortranStringReader("lhs=rhs")
        reader.set_format(FortranFormat(True, True))  # free form, strict
        myline = reader.next()
        if pointer:
            self._assign_assign = fparser1.statements.PointerAssignment(parent.root,
                                                                 myline)
        else:
            self._assign_assign = fparser1.statements.Assignment(parent.root, myline)
        self._assign_assign.expr = rhs
        self._assign_assign.variable = lhs
        BaseGen.__init__(self, parent, self._assign_assign)