fparser.api
===========

.. py:module:: fparser.api

.. autoapi-nested-parse::

   Public API for Fortran parser.

   Module content
   --------------



Attributes
----------

.. autoapisummary::

   fparser.api.__autodoc__


Functions
---------

.. autoapisummary::

   fparser.api.get_reader
   fparser.api.parse
   fparser.api.walk


Module Contents
---------------

.. py:data:: __autodoc__
   :value: ['get_reader', 'parse', 'walk']


.. py:function:: get_reader(source, isfree=None, isstrict=None, include_dirs=None, source_only=None, ignore_comments=True, process_directives: bool = False)

   Returns Fortran reader instance.

   If ``source`` is a C filename then the functions searches for comment
   lines starting with ``/*f2py`` and reads following lines as PYF file
   content until a line ``*/`` is found.

   :param str source: Specify a string or filename containing Fortran code.
   :param bool isfree: True if Fortran is free format
   :param bool isstrict: True if we are to strictly enforce free/fixed format
   :param list include_dirs: Specify a list of include directories. The
                             default list (when include_dirs=None) contains
                             the current working directory and the directory
                             of ``source``.
   :param list source_only: Specify a list of Fortran file names that are
                            searched when the ``USE`` statement is
                            encountered.
   :param bool ignore_comments: Whether or not to ignore (and discard)
                                comments when parsing the source.
   :param process_directives: whether or not to process directives as
        specialised Directive nodes. Default is False (in which case
        directives are left as comments). This option overrides the
        ignore_comments input.

   :returns: a reader instance
   :rtype: :py:class:`fparser.common.readfortran.FortranReader`


.. py:function:: parse(source, isfree=None, isstrict=None, include_dirs=None, source_only=None, ignore_comments=True, analyze=True, clear_cache=True)

   Parse input and return Statement tree. Raises an AnalyzeError if the
   parser can not parse the Fortran code.

   :param str source: Specify a string or filename containing Fortran code.
   :param bool isfree: Whether the Fortran source is free-format.
   :param bool isstrict: Whether we are to strictly enforce the `isfree`
                         setting.
   :param list include_dirs: Specify a list of include directories. The
                             default list (when include_dirs=None) contains
                             the current working directory and the directory
                             of ``filename``.
   :param list source_only: A list of Fortran file names that are searched
                            when the ``USE`` statement is encountered.
   :param bool ignore_comments: When True then discard all comment lines in
                                the Fortran code.
   :param bool analyze: When True then apply analyze() method on the Fortran
                        code tree.
   :param bool clear_cache: Whether or not to wipe the parser cache prior
                            to parsing. Necessary when a new tree object
                            is required, even if the Fortran to be parsed has
                            been seen before.

   :returns: Abstract Syntax Tree of Fortran source.
   :rtype: :py:class:`fparser.api.BeginSource`


.. py:function:: walk(stmt, depth=-1, _initial_depth=None)

   Generate Fortran statements by walking the stmt tree until given depth.

   For each block statement in stmt, the walk functions yields a
   tuple ``(statement, depth)`` where ``depth`` is the depth of tree
   stucture for statement.

   Parameters
   ----------
   stmt : Statement
   depth : int
     If depth is positive then walk in the tree until given depth.
     If depth is negative then walk the whole tree.

   Returns
   -------
   generator

   Examples
   --------

     ::

       from fparser import api
       source_str = '''
       subroutine foo
         integer i, r
         do i=1,100
           r = r + i
         end do
       end
       '''
       tree = api.parse(source_str)
       for stmt, depth in api.walk(tree):
           print depth, stmt.item

     that will print::

       1 line #2'subroutine foo'
       2 line #3'integer i, r'
       2 line #4'do i=1,100'
       3 line #5'r = r + i'
       2 line #6'end do'
       1 line #7'end'