Program Structure — Stylist 0.3.dev1 documentation

# Program Structure

There are two concepts important to Stylist’s function: Rules and Styles.

A rule is a single check which may be made against a piece of source code. e.g. Has the implicit keyword been specified in all appropriate places?

A style, on the other hand, is a set of rules of interest to a particular group of developers. For instance the LFRic style includes the “missing implicit” rule and the “trailing white space rule.”

## Rules

The abstract base of all rules is `stylist.rule.Rule`. Classes derived from this implement an `stylist.rule.Rule.examine()` method which is passed a `stylist.source.SourceText` object. This allows the source to be treated as a plain text file.

Rules relating to Fortran source may be found in the `stylist.fortran` module. An abstract `stylist.fortran.FortranRule` is provided which requires an `stylist.fortran.FortranRule.examine_fortran()` method which is passed a `stylist.source.FortranSource` object. Thus the rule may examine the Fortran parse tree.

### Writing a New Text Rule

Just sub-class `stylist.rule.Rule` and implement the `stylist.rule.Rule.examine()` method. Use the `stylist.source.SourceText.get_text()` method on the passed `stylist.source.SourceText` object to obtain the text of the source file.

The “trailing white space” rule gives an example of using RegEx on the source text. Meanwhile the “Fortran characterset” rule shows a more elaborate text rule which implements a state-machine to test validity.

### Writing a Fortran Rule

An abstract `stylist.rule.FortranRule` is provided, any new rule should inherit from this and implement the `stlist.rule.FortranRule.examine_fortran()` method. Use the `stylist.source.FortranSource.get_tree()` method to obtain an fparser2 parse tree.

The `stylist.source.FortranSource` class also provides some methods for traversing the parse tree. It is expected that this functionality will eventually become available through fparser2 and so will be removed from stylist.

### Documenting the Rule

Don’t forget to add your new rule to the user documentation. This is a slightly clunky process involving adding some boilerplate to documentation/source/user-manual/rule-list.rst.

## Styles

Styles are defined in stylist/style.py and derive from the abstract Style class. They tend to contain only a constructor which defines a list of rules and passes it up to their parent. Extending an Existing Style

Just add an instance of the rule you want to add to the appropriate list. You may need to import the module it lives in, or not if it is already there.

For instance:

> class LFRicStyle(Style):

>   ‘’’ LFRic project’s list of rules. ‘’’ def __init__(self):

>   > rules = [stylist.fortran.FortranCharacterset(),

>   >   stylist.rule.TrailingWhitespace(),

- stylist.fortran.MissingImplicit(‘none’)

- stylist.fortran.MissingImplicit(‘none’),

- stylist.fortran.MissingOnly(ignore=[‘pfunit_mod’, ‘xios’])]

> super(LFRicStyle, self).__init__(rules)

Adding a New Style

As intimated above, this a simple matter of creating a new class inheriting from the Style parent.

class SpecialStyle(Style):

  ‘’’ LFRic project’s list of rules. ‘’’ def __init__(self):

  > rules = [stylist.fortran.FortranCharacterset(),

  >   stylist.rule.TrailingWhitespace(), stylist.fortran.MissingImplicit(‘none’)]

  > super(SpecialStyle, self).__init__(rules)

With that in place function process(…) in __main__.py needs to be updated. The new style can either replace LFRicStyle or be run in addition.

> def process(candidates: List[str]) -> List[Issue]:

>   ‘’’ Examines files for style compliance.

>   Any directories specified will be descended looking for files to examine. ‘’’

- styles = [LFRicStyle()]

- styles = [LFRicStyle(), SpecialStyle()] …

Future Work

Obviously having the styles hardcoded like this is not desirable. It is okay for initial development, to get things going, but eventually we would want to move to a more flexible approach.

Tickets #8, #13 and #14 cover this work.