stylist.source — Stylist 0.3.dev1 documentation

# 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.
`FortranPreProcessor`(source) | Strips out preprocessor directives.
`FortranSource`(text) | Holds a Fortran source file as both a text block and parse tree.
`MetaCPreProcessor`(name, bases, namespace, ...) | Identifies the C preprocessor.
`MetaCSource`(name, bases, namespace, **kwargs) | Identifies C source.
`MetaFortranPreProcessor`(name, bases, ...) | Identifies the Fortran preprocessor.
`MetaFortranSource`(name, bases, namespace, ...) | Identifies Fortran source.
`MetaPFUnitProcessor`(name, bases, namespace, ...) | Identifies the pFUnit preprocessor.
`MetaPlainText`(name, bases, namespace, **kwargs) | Identifies plain text.
`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 source files.
`TextProcessor`(source) | Preprocessor decorators inherit from this.

class stylist.source.CPreProcessor(source)

  Bases: `stylist.source.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.

  get_text()
    Return type

      `str`

    Returns

      Source as text with preprocessor directives removed.

class stylist.source.CSource(text)

  Bases: `stylist.source.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.

  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.FortranPreProcessor(source)

  Bases: `stylist.source.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.

  get_text()
    Return type

      `str`

    Returns

      Source as text with preprocessor directives removed.

class stylist.source.FortranSource(text)

  Bases: `stylist.source.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`

  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.MetaCPreProcessor(name, bases, namespace, **kwargs)

  Bases: `abc.ABCMeta`

  Identifies the C preprocessor.

class stylist.source.MetaCSource(name, bases, namespace, **kwargs)

  Bases: `abc.ABCMeta`

  Identifies C source.

class stylist.source.MetaFortranPreProcessor(name, bases, namespace, **kwargs)

  Bases: `abc.ABCMeta`

  Identifies the Fortran preprocessor.

class stylist.source.MetaFortranSource(name, bases, namespace, **kwargs)

  Bases: `abc.ABCMeta`

  Identifies Fortran source.

class stylist.source.MetaPFUnitProcessor(name, bases, namespace, **kwargs)

  Bases: `abc.ABCMeta`

  Identifies the pFUnit preprocessor.

class stylist.source.MetaPlainText(name, bases, namespace, **kwargs)

  Bases: `abc.ABCMeta`

  Identifies plain text.

class stylist.source.PFUnitProcessor(source)

  Bases: `stylist.source.TextProcessor`

  Strips out pFUnit directives.

  Parameters

    source (`SourceText`) – The source to be preprocessed.

  get_text()
    Return type

      `str`

    Returns

      Source as text with preprocessor directives removed.

class stylist.source.PlainText(text)

  Bases: `stylist.source.SourceTree`

  Holds a plain text file as though it were source.

  Parameters

    text (`SourceText`) – Source as text.

  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, source, *preprocessors)

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

    Parameters

      - extension (`str`) – File extension which identifies this chain.

      - source (`Type`[`SourceTree`]) – Underlying language parser.

      - preprocessors (`Type`[`TextProcessor`]) – 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: `stylist.source.SourceText`

  Reads text source from a file.

  Parameters

    source_file (`Union`[`IO`[`str`], `str`]) – The file to examine.

  get_text()

    Gets the source file as a string.

    Return type

      `str`

class stylist.source.SourceStringReader(source_string)

  Bases: `stylist.source.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: `object`

  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: `object`

  Abstract parent of all actual language source files.

  Parameters

    text (`SourceText`) – Source as text.

  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: `stylist.source.SourceText`

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

  Parameters

    source (`SourceText`) – The source to be preprocessed.