ford.sourceform module

Contents

ford.sourceform module#

class ford.sourceform.Associations#

Bases: object

A class for storing associations. Associations are added and removed in batches, akin to how they are added, and fall out of scope in Fortran ASSOCIATE blocks.

add_batch(associations)#

adds a batch of associations to the associations dictionary

remove_last_batch()#

removes the last batch of associations

class ford.sourceform.ExternalBoundProcedure(name, url='', parent=None)#

Bases: FortranBoundProcedure

class ford.sourceform.ExternalFunction(name, url='', parent=None)#

Bases: FortranFunction

class ford.sourceform.ExternalInterface(name, url='', parent=None)#

Bases: FortranInterface

class ford.sourceform.ExternalModule(name, url='', parent=None)#

Bases: FortranModule

class ford.sourceform.ExternalProgram(name)#

Bases: FortranProgram

class ford.sourceform.ExternalSourceFile(name)#

Bases: FortranSourceFile

class ford.sourceform.ExternalSubmodule(name)#

Bases: FortranSubmodule

class ford.sourceform.ExternalSubroutine(name, url='', parent=None)#

Bases: FortranSubroutine

class ford.sourceform.ExternalType(name, url='', parent=None)#

Bases: FortranType

class ford.sourceform.ExternalVariable(name, url='', parent=None)#

Bases: FortranVariable

class ford.sourceform.FortranBase(source, first_line, parent=None, inherited_permission='public', strings=None)#

Bases: object

An object containing the data common to all of the classes used to represent Fortran data.

IS_SPOOF = False#
POINTS_TO_RE = re.compile('\\s*=>\\s*', re.IGNORECASE)#
SPLIT_RE = re.compile('\\s*,\\s*', re.IGNORECASE)#
property anchor: str#

Return a string suitable for an HTML anchor link

property children#

Iterator over all child entities

property filename: str#

Name of the file containing this entity

filter_display(collection)#

Remove items from collection if they shouldn’t be displayed

Return type:

List

find_child(name, entity=None)#

Find a child of this entity by name

Parameters:

  • name (str) – Name of child to look up

  • entity (Optional[str]) – The class of entity (module, function, and so on)

Returns:

Child if found, None if not

Return type:

Optional[FortranBase]

property full_url: str | None#

URL of this entity, including the base URL

get_dir()#
Return type:

Optional[str]

get_url()#

URL of this entity, relative to base URL

Return type:

Optional[str]

property ident: str#

Return a unique identifier for this object

iterator(*argv)#

Iterator returning any list of elements via attribute lookup in self

This iterator retains the order of the arguments

lines_description(total, total_all=0, obj=None)#
markdown(md)#

Process the documentation with Markdown to produce HTML.

pretty_obj = {'blockdata': 'block data units', 'interface': 'abstract interfaces', 'module': 'modules and submodules', 'proc': 'procedures', 'program': 'programs', 'sourcefile': 'source files', 'submodule': 'modules and submodules', 'type': 'derived types'}#
read_metadata()#

Read the metadata from an entity’s docstring

property routines#

Iterator returning all procedures

sort_components()#

Sorts components using the method specified in the object meta/project settings

Return type:

None

property source_file: FortranSourceFile#

Source file containing this entity

class ford.sourceform.FortranBlockData(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranContainer

An object representing a block-data unit. Now obsolete due to modules, block data units allowed variables held in common blocks to be initialized outside of an executing program unit.

correlate(project)#
process_attribs()#
prune()#
class ford.sourceform.FortranBoundProcedure(source, first_line, parent=None, inherited_permission='public', strings=None)#

Bases: FortranBase

An object representing a type-bound procedure, possibly overloaded.

property binding_type: str#

String representation of binding type

correlate(project)#
property full_declaration: str#

String representation of the full declaration line

property num_lines: int#
class ford.sourceform.FortranCodeUnit(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranContainer

A class on which programs, modules, functions, and subroutines are based.

correlate(project)#
Return type:

None

process_attribs()#

Attach standalone attributes to the correct object, and compute the list of public objects

Return type:

None

prune()#

Remove anything which shouldn’t be displayed.

class ford.sourceform.FortranCommon(source, first_line, parent=None, inherited_permission='public', strings=None)#

Bases: FortranBase

An object representing a common block. This is a legacy feature.

correlate(project)#
class ford.sourceform.FortranContainer(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranBase

A class on which any classes requiring further parsing are based.

ARITH_GOTO_RE = re.compile('go\\s*to\\s*\\([0-9,\\s]+\\)', re.IGNORECASE)#
ASSOCIATE_RE = re.compile('^(\\w+\\s*:)?         # Optional label\n        \\s*associate\\s*\\(       # Required associate statement\n        (?P<associations>.+)    # Associations\n        \\)\\s*$', re.IGNORECASE|re.VERBOSE)#
ATTRIB_RE = re.compile('^(asynchronous|allocatable|bind\\s*\\(.*\\)|data|dimension|external|intent\\s*\\(\\s*\\w+\\s*\\)|optional|parameter|pointer|private|protected|public|save|target|value|volatile)(?:\\s+|\\s*::\\s*)((/|, re.IGNORECASE)#
BLOCK_DATA_RE = re.compile('^block\\s*data\\s*(\\w+)?\\s*$', re.IGNORECASE)#
BLOCK_RE = re.compile('^(\\w+\\s*:)?\\s*block\\s*$', re.IGNORECASE)#
BOUNDPROC_RE = re.compile('^(?P<generic>generic|procedure)\\s*  # Required keyword\n        (?P<prototype>\\([^()]*\\))?\\s*           # Optional interface name\n        (?:,\\s*(?P<attributes>\\w[^:]*))?        # Optional lis, re.IGNORECASE|re.VERBOSE)#
CALL_RE = re.compile('(?P<call_chain>\n                (?:(?:\\s*\\w+\\s*(?:\\(\\))?\\s*%\\s*)+)? # Optional type component access\n                (?:\\w+\\s*\\(.*?\\))                   # Required function name\n       , re.IGNORECASE|re.VERBOSE)#
COMMON_RE = re.compile('^common(?:\\s*/\\s*(\\w+)\\s*/\\s*|\\s+)(\\w+.*)', re.IGNORECASE)#
COMMON_SPLIT_RE = re.compile('\\s*(/\\s*\\w+\\s*/)\\s*', re.IGNORECASE)#
END_RE = re.compile('^end\\s*(?:(module|submodule|subroutine|function|procedure|program|type|interface|enum|block\\sdata|block|associate)(?:\\s+(\\w.*))?)?$', re.IGNORECASE)#
ENUM_RE = re.compile('^enum\\s*,\\s*bind\\s*\\(.*\\)\\s*$', re.IGNORECASE)#
FINAL_RE = re.compile('^final\\s*::\\s*(\\w.*)', re.IGNORECASE)#
FORMAT_RE = re.compile('^[0-9]+\\s+format\\s+\\(.*\\)', re.IGNORECASE)#
FUNCTION_RE = re.compile('^(?:(?P<attributes>.+?)\\s*)?               # Optional attributes (including type)\n        function\\s+(?P<name>\\w+)\\s*                    # Required function name\n        (?P<arguments>\\([^()]*, re.IGNORECASE|re.VERBOSE)#
INTERFACE_RE = re.compile('^(abstract\\s+)?interface(?:\\s+(.+))?$', re.IGNORECASE)#
MODPROC_RE = re.compile('^(?P<module>module\\s+)?procedure\\s*(?:::|\\s)\\s*(?P<names>\\w.*)$', re.IGNORECASE)#
MODULE_RE = re.compile('^module(?:\\s+(?P<name>\\w+))?$', re.IGNORECASE)#
NAMELIST_RE = re.compile('namelist\\s*/(?P<name>\\w+)/\\s*(?P<vars>(?:\\w+,?\\s*)+)', re.IGNORECASE)#
PROGRAM_RE = re.compile('^program(?:\\s+(\\w+))?$', re.IGNORECASE)#
SUBCALL_RE = re.compile("\n        ^(?:if\\s*\\(.*\\)\\s*)?    # Optional 'if' statement\n        call\\s+                 # Required keyword\n        (?P<call_chain>\n            (?:.*%\\s*)?         # Optional type compone, re.IGNORECASE|re.VERBOSE)#
SUBMODULE_RE = re.compile("^submodule\\s*\n        \\(\\s*(?P<ancestor_module>\\w+)\\s*         # Non-optional ancestor module\n        (?::\\s*(?P<parent_submod>\\w+))?\\s*\\)  # Optional parent submodule\n        \\s*(?P<nam, re.IGNORECASE|re.VERBOSE)#
SUBROUTINE_RE = re.compile('^\\s*(?:(?P<attributes>.+?)\\s+)?     # Optional attributes\n        subroutine\\s+(?P<name>\\w+)\\s*           # Required subroutine name\n        (?P<arguments>\\([^()]*\\))?              # Optiona, re.IGNORECASE|re.VERBOSE)#
TYPE_RE = re.compile('^type(?:\\s+|\\s*(,.*)?::\\s*)((?!(?:is\\s*\\())\\w+)\\s*(\\([^()]*\\))?\\s*$', re.IGNORECASE)#
USE_RE = re.compile('^use(?:\\s*(?:,\\s*(?:non_)?intrinsic\\s*)?::\\s*|\\s+)(\\w+)\\s*($|,.*)', re.IGNORECASE)#
VARIABLE_STRING = '^(integer|real|double\\s*precision|character|complex|double\\s*complex|logical|type(?!\\s+is)|class(?!\\s+is|\\s+default)|procedure|enumerator{})\\s*((?:\\(|\\s\\w|[:,*]).*)$'#
doxy_dict: Dict[str, str]#
print_error(line, error, describe_object=True)#
Return type:

None

class ford.sourceform.FortranEnum(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranContainer

An object representing a Fortran enumeration. Contains the individual enumerators as variables.

class ford.sourceform.FortranFinalProc(name, parent, source=None)#

Bases: FortranBase

An object representing a finalization procedure for a derived type within Fortran.

correlate(project)#
class ford.sourceform.FortranFunction(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranProcedure

An object representing a Fortran function and holding all of said function’s contents.

proctype = 'Function'#
class ford.sourceform.FortranInterface(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranContainer

An interface block, including generic and abstract interfaces

subroutines#

External subroutines

Type:

list

functions#

External functions

Type:

list

modprocs#

Procedures defined in this scope

Type:

list

variables#

Procedure pointers and dummy procedures

Type:

list

generic#

True if this is a generic interface

Type:

bool

abstract#

True if this is an abstract interface

Type:

bool

correlate(project)#
get_dir()#
Return type:

Optional[str]

proctype = 'Interface'#
class ford.sourceform.FortranModule(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranCodeUnit

An object representing individual modules within your source code. These objects contains lists of all of the module’s contents, as well as its dependencies.

ONLY_RE = re.compile('^\\s*,\\s*only\\s*:\\s*(?=[^,])', re.IGNORECASE)#
RENAME_RE = re.compile('(\\w+)\\s*=>\\s*(\\w+)', re.IGNORECASE)#
get_used_entities(use_specs)#

Returns the entities which are imported by a use statement. These are contained in dicts.

class ford.sourceform.FortranModuleProcedureImplementation(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranCodeUnit

An object representing a the implementation of a Module Function or Module Subroutine in a submodule. The interface is represented separately by a FortranModuleProcedureInterface

module = True#
proctype = 'Module Procedure'#
class ford.sourceform.FortranModuleProcedureInterface(procedure, parent, doc_list)#

Bases: FortranInterface

The interface part of a FortranModuleProcedureImplementation

This should be created directly by a FortranInterface

Not to be confused with a FortranModuleProcedureReference which is merely a reference to a module procedure defined elsewhere, whereas a FortranModuleProcedureInterface is a complete interface to a module procedure

abstract = False#
generic = False#
obj = 'interface'#
proctype = 'Interface'#
class ford.sourceform.FortranModuleProcedureReference(name, parent=None, inherited_permission=None)#

Bases: FortranBase

Reference to a module procedure whose interface and implementation are both defined elsewhere

For example, this class represents the reference to fft_1d in a generic interface:

interface fft
    module procedure fft_1d
    module procedure fft_2d
end interface fft

while fft_1d itself may be represented by either a FortranSubroutine or FortranFunction, or by the combination of FortranModuleProcedureInterface and FortranModuleProcedureImplementation

obj = 'moduleprocedure'#
class ford.sourceform.FortranNamelist(source, first_line, parent=None, inherited_permission='public', strings=None)#

Bases: FortranBase

An object representing a Fortran namelist and holding all of said namelist’s contents

correlate(project)#
class ford.sourceform.FortranProcedure(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranCodeUnit

Base class for subroutines and functions for common functionality

get_dir()#
Return type:

Optional[str]

property ident: str#

Return a unique identifier for this object

property is_interface_procedure: bool#

Is this procedure just an interface?

property permission#

Permission (public/private) of this procedure

proctype = 'Unknown'#
class ford.sourceform.FortranProgram(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranCodeUnit

An object representing the main Fortran program.

class ford.sourceform.FortranSourceFile(filepath, settings, preprocessor=None, fixed=False, **kwargs)#

Bases: FortranContainer

An object representing individual files containing Fortran code. A project will consist of a list of these objects. In turn, SourceFile objects will contains lists of all of that file’s contents

blockdata: List[FortranBlockData]#
functions: List[FortranFunction]#
property markdownable_items#
modules: List[FortranModule]#
parent: FortranContainer | None#
programs: List[FortranProgram]#
submodules: List[FortranSubmodule]#
subroutines: List[FortranSubroutine]#
class ford.sourceform.FortranSpoof(name, parent=None, obj='ITEM')#

Bases: object

A dummy-type which is used to represent arguments, interfaces, type-bound procedures, etc. which lack a corresponding variable or implementation.

IS_SPOOF = True#
class ford.sourceform.FortranSubmodule(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranModule

get_dir()#
class ford.sourceform.FortranSubroutine(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranProcedure

An object representing a Fortran subroutine and holding all of said subroutine’s contents.

proctype = 'Subroutine'#
class ford.sourceform.FortranType(source, first_line, parent=None, inherited_permission='public', strings=[])#

Bases: FortranContainer

An object representing a Fortran derived type and holding all of said type’s components and type-bound procedures. It also contains information on the type’s inheritance.

correlate(project)#
prune()#

Remove anything which shouldn’t be displayed.

class ford.sourceform.FortranVariable(name, vartype, parent, attribs=[], intent='', optional=False, permission='public', parameter=False, kind=None, strlen=None, proto=None, doc=None, points=False, initial=None)#

Bases: FortranBase

An object representing a variable within Fortran.

correlate(project)#
property full_declaration#

Return the full type declaration, including attributes, dimensions, kind, and so on

property full_type#

Return the full type, including class, kind, len, and so on

class ford.sourceform.GenericSource(filename, settings)#

Bases: FortranBase

Represent a non-Fortran source file. The contents of the file will not be analyzed, but documentation can be extracted.

doc_alt_re: Pattern | None#
lines_description(total, total_all=0, obj=None)#
property markdownable_items#
parse_file(encoding='utf-8')#
class ford.sourceform.NameSelector#

Bases: object

Object which tracks what names have been provided for different entities in Fortran code. It will provide an identifier which is guaranteed to be unique. This identifier can then me used as a filename for the documentation of that entity.

get_name(item)#

Return the name for this item registered with this NameSelector. If no name has previously been registered, then generate a new one.

class ford.sourceform.ParsedType(vartype, rest, kind=None, strlen=None, proto=None)#

Bases: object

kind: str | None = None#
proto: None | str | List[str] = None#
rest: str#
strlen: str | None = None#
vartype: str#
ford.sourceform.create_doxy_dict(line)#

Create a dictionary of parameters with a name and comment

Return type:

dict

ford.sourceform.get_mod_procs(source, names, parent)#

Get module procedures from an interface

Return type:

List[FortranModuleProcedureReference]

ford.sourceform.implicit_type(name)#

Map names to implicit types

Return type:

str

ford.sourceform.line_to_variables(source, line, inherit_permission, parent)#

Returns a list of variables declared in the provided line of code. The line of code should be provided as a string.

ford.sourceform.parse_type(string, capture_strings, extra_vartypes)#

Gets variable type, kind, length, and/or derived-type attributes from a variable declaration.

Return type:

ParsedType

ford.sourceform.read_docstring(source, docmark)#

Read a contiguous docstring

Return type:

List[str]

ford.sourceform.remove_doxy(source)#

Remove doxygen comments with an @ identifier from main comment block.

Return type:

List[str]

ford.sourceform.remove_kind_suffix(literal, is_character=False)#

Return the literal without the kind suffix of a numerical literal, or the kind prefix of a character literal

ford.sourceform.remove_prefixes(string, prefix1, prefix2=None)#
Return type:

str

ford.sourceform.translate_doxy_meta(doc_list)#

Convert doxygen metadata into ford’s format

Return type:

list[str]

Translates Doxygen @see links to Ford’s [[]]

Return type:

list[str]

Contents