stylist.source

Manages source code in various flavours.

Classes

`CPreProcessor`(source)	Strips out preprocessor directives.
`CSource`(text)	Holds a C/C++ source file as both a text block and parse tree.
`FilePipe`(parser, *preprocessors)	Holds the chain of objects needed to understand a particular file extension.
`FortranPreProcessor`(source)	Strips out preprocessor directives.
`FortranSource`(text)	Holds a Fortran source file as both a text block and parse tree.
`PFUnitProcessor`(source)	Strips out pFUnit directives.
`PlainText`(text)	Holds a plain text file as though it were source.
`SourceFactory`()	Manages the handling of source file.
`SourceFileReader`(source_file)	Reads text source from a file.
`SourceStringReader`(source_string)	Reads text source from a string.
`SourceText`()	Handles source code at the text level.
`SourceTree`(text)	Abstract parent of all actual language files.
`TextProcessor`(source)	Preprocessor decorators inherit from this.

class stylist.source.CPreProcessor(source)

Bases: TextProcessor

Strips out preprocessor directives.

It is assumed that you want to syntax check all the Source so all conditional directives such as #ifdef are stripped out.

Parameters:: source (SourceText) – The source to be preprocessed.

static get_name()

Gets the name of the processing stage.

Return type:: str

get_text()

Return type:: str
Returns:: Source as text with preprocessor directives removed.

class stylist.source.CSource(text)

Bases: SourceTree

Holds a C/C++ source file as both a text block and parse tree.

Todo

This is just a stub to illustrate how it would be done. It is not useable.

Parameters:: text (SourceText) – Source as text.

static get_name()

Gets the name of the source tree type.

Return type:: str

get_tree(): Gets a parse-tree representation of the source file.

get_tree_error()

Gets any errors raised while building the parse tree.

Return type:: Optional[str]

class stylist.source.FilePipe(parser, *preprocessors)

Bases: object

Holds the chain of objects needed to understand a particular file extension.

Parameters:

parser (Type[SourceTree]) – Underlying language parser.
preprocessors (Type[TextProcessor]) – Any preprocessors to apply before parsing.

class stylist.source.FortranPreProcessor(source)

Bases: TextProcessor

Strips out preprocessor directives.

It is assumed that you want to syntax check all the Source so all conditional directives such as #ifdef are stripped out.

Parameters:: source (SourceText) – The source to be preprocessed.

static get_name()

Gets the name of the processing stage.

Return type:: str

get_text()

Return type:: str
Returns:: Source as text with preprocessor directives removed.

class stylist.source.FortranSource(text)

Bases: SourceTree

Holds a Fortran source file as both a text block and parse tree.

Parameters:: text (SourceText) – Source as text.

find_all(find_node, root=None)

Gets all instances of the specified parse element below the root.

The search descends the tree but that descent is terminated by a match.

Parameters:

find_node (Type[Base]) – Parse tree node class to seek.
root (Optional[Base]) – Point in parse tree to start. If unspecified implies the whole tree.

Return type:

Generator[Base, None, None]

Returns:

Matching nodes.

Todo

This functionality might be provided by fparser at some point.

get_first_statement(root=None)

Gets the first “statement” part of the syntax tree or part thereof.

Parameters:: root (Optional[Block]) – Point in parse tree to start. If unspecified implies the whole tree.
Return type:: StmtBase

static get_name()

Gets the name of the source tree type.

Return type:: str

get_tree()

Return type:: Optional[Program]
Returns:: Program unit object.

get_tree_error()

Gets any errors raised while building the parse tree.

Return type:: Optional[str]

path(path, root=None)

Gets the tree nodes at the given path.

The path describes a route through the parse tree.

Parameters:

path (Union[Iterable, str]) – a series of a node names either as a Python list object or a ‘/’ separated string.
root (Optional[Block]) – Starting point in the parse tree. If unspecified implies the whole tree.

Return type:

List[Base]

Returns:

Tree nodes found.

Todo

This functionality might be provided by fparser at some point.

static print_tree(root, indent=0)

Dumps a textual representation of the tree to standard out. Intended for debug use.

Parameters:

root (Base) – Point in parse tree to dump.
indent (int) – Spaces to prefix each line with.

Return type:

None

class stylist.source.PFUnitProcessor(source)

Bases: TextProcessor

Strips out pFUnit directives.

Parameters:: source (SourceText) – The source to be preprocessed.

static get_name()

Gets the name of the processing stage.

Return type:: str

get_text()

Return type:: str
Returns:: Source as text with preprocessor directives removed.

class stylist.source.PlainText(text)

Bases: SourceTree

Holds a plain text file as though it were source.

Parameters:: text (SourceText) – Source as text.

static get_name()

Gets the name of the source tree type.

Return type:: str

get_tree()

Return type:: Generator[str, None, None]
Returns:: File content line by line.

get_tree_error()

Gets any errors raised while building the parse tree.

Return type:: Optional[str]

class stylist.source.SourceFactory

Bases: object

Manages the handling of source file. Knows what chains of objects are needed to handle each file extension.

It is hard to lay down hard and fast rules about what should go in the default list of extensions. Language standards do not generally specify an extension since that is an OS level concept. Some filesystems do not use extensions at all.

The default list is kept short and the two goals are “correctness” and “typicality”.

Correctness means not including a slew of extensions just because they happen to be used. Stick to ones which are “correct” in that they are well thought out.

For instance it is not uncommon for people to use all sorts of extensions for Fortran which encodes the version of the language they are using. This is a poor idea as it leads to a proliferation of extension for no obvious gain. A file with an .f03 extension may be coded using only Fortran 95 features.

Instead we follow the convention that .f90 means “free format” source while .f continues to mean “fixed format”.

On the other hand typicality means including the most commonly used extensions. That is why both .cc and .cpp are listed for C++ source. Although .cc is the closest there is to an “official” extension .cpp is much more common.

If your particular application needs to support some odd-ball extensions then it can use the add_extension(...) call.

classmethod add_extension(extension, pipe)

Adds a mapping between source file extension and source handling classes.

Parameters:

extension (str) – File extension which identifies this chain.
source – Underlying language parser.
preprocessors – All preprocessors to apply before parsing.

Return type:

None

classmethod get_extensions()

Gets the file extensions recognised by the read_file() method.

Return type:: Iterable[str]

classmethod read_file(source_file)

Creates a Source object from a file.

The file extension is used to determine the source type so this will not work on file-like objects which do not have a filename.

Return type:: SourceTree

class stylist.source.SourceFileReader(source_file)

Bases: SourceText

Reads text source from a file.

Parameters:: source_file (Union[TextIO, Path]) – The file to examine.

get_text()

Gets the source file as a string.

Return type:: str

class stylist.source.SourceStringReader(source_string)

Bases: SourceText

Reads text source from a string.

Parameters:: source_string (str) – The source.

get_text()

Gets the source file as a string.

Return type:: str

class stylist.source.SourceText

Bases: ABC

Handles source code at the text level. Makes use of the decorator pattern to perform text level preprocessing.

abstract get_text()

Gets the source file as a string.

Return type:: str

class stylist.source.SourceTree(text)

Bases: ABC

Abstract parent of all actual language files.

Parameters:: text (SourceText) – Source as text.

abstract static get_name()

Gets the name of the source tree type.

Return type:: str

get_text()

Return type:: str
Returns:: Original source text.

abstract get_tree(): Gets a parse-tree representation of the source file.

abstract get_tree_error()

Gets any errors raised while building the parse tree.

Return type:: Optional[str]

class stylist.source.TextProcessor(source)

Bases: SourceText, ABC

Preprocessor decorators inherit from this. This is part of the decorator pattern.

Parameters:: source (SourceText) – The source to be preprocessed.

abstract static get_name()

Gets the name of the processing stage.

Return type:: str