Preprocessor in Python — GromacsWrapper 0.6.1 documentation

# Preprocessor in Python

Author: | Evan Plaice, Oliver Beckstein
Licence: | MIT
Year: | 2010, 2011

The `preprocessor` module is derived from pypreprocessor (release 0.4.0) and can be used to transform ITP file that make use of C-preprocessor Directives such as

    #ifdef POSRES
    [ position_restraints ]
    ...
    ...
    #endif

To include the position restraints use the `Preprocessor`:

    PP = Preprocessor(filename="drug.itp", output="pp_drug.itp", POSRES=True)
    PP.parse()

To exclude them:

    PP = Preprocessor(filename="drug.itp", output="pp_drug.itp", POSRES=False)
    PP.parse()

(or simply omit `POSRES` from the argument list).

Once the file has been parsed, one can (1) write it out with the `Preprocessor.write()` method:

    PP.write("parsed.itp")

Or (2) create a `cStringIO.StringIO()` object from the in-memory parsed file with `Preprocessor.StringIO()`:::

    s = PP.StringIO()
    for line in s:
        print s,
    s.close()

Finally, there’s also a context manager for the `cStringIO` functionality, provided by `Preprocessor.open()`:

    with PP.open() as s:
       for line in s:
           print line,

## Directives

The directives understood are:

`#define VAR`

> Define the variable VAR; note that even `#define VAR 0` in the input file will have the effect of defining the variable. The `Preprocessor` constructor, however, will not define any VAR keyword that evaluates to `False`.

`#undef VAR`

> Undefines VAR.

`#ifdef VAR` ... `#else` ... `#endif`

> Conditional evaluation of content blocks. VAR can only be a simple variable name, and it is checked against a list of defined variable names.

`#exclude` ... `#endexclude`

> Content inside the exclude block is omitted from the processed file.

Note

Expansion of a defined VAR inside the file is not supported. VAR are *only used in the context of `#ifdef`/`#ifndef` directives.

## Classes

class `gromacs.fileformats.preprocessor.` `Preprocessor`(filename, output=None, **kwargs)

  CPP-style processing of files.

  The directives understood are:

  - `#define VAR`
  - `#undef VAR`
  - `#ifdef VAR` ... `#else` ... `#endif`
  - `#exclude` ... `#endexclude`

  Set up the preprocessor

  Arguments: | filename input file name
  Keywords: | output output file name, if `None` then a temporary file will be created for `write()`. clean leave at `True` (to remove any preprocessor directives and anything excluded through #ifdefs); use `False` for debugging, which simply prefixes excluded lines with “commentchar #” commentchar how to comment out lines, leave at the default for itp files [”;”] strip remove all empty lines and lines starting with commentchar (does not work with clean = `False`) [`False`] defines any other keywords VAR are interpreted as `#define VAR` statement if VAR evaluates to `True`.

  Changed in version 0.3.1: strip keyword added

  `StringIO`()

    Return a `cStringIO.StringIO()` instance of the buffer.

    The resulting instance can be treated as a read-only file containing the processed input from the last invocation of `parse()`.

  `buffer`

    String representation of the processed input file.

    See also

    `StringIO()` and `write()`

  `compare_defines_and_conditions`(defines, conditions)

    #ifdef directive

  `define`(define)

    #define directive

  `lexer`(line)

    evaluate line

    Returns: | `(squelch, metadata)`

  `open`(*args, **kwds)

    Open the processed file (in memory) for reading.

    Use as

        with preprocessor.open() as pp:
           for line in pp:
               print line,

    The method returns a `cStringIO.StringIO()` stream as provided by `StringIO()`.

  `parse`(**kwargs)

    parsing/processing

    kwargs are variables that are set (`#define VAR`) or unset (`#undef VAR`) at the beginning of the file. They are applied to all the defines that were provided to the constructor, and hence using VAR = `False` allows one to undefine some of these.

    This method only populates the output buffer and does not write an output file; use `write()` for that purpose.

  `raise_error`(directive)

    error handling

    Raises: | `SyntaxError`

  `search_defines`(define)

    Check if variable define has been defined.

  `undefine`(define)

    #undef directive

  `write`(filename=None)

    write out file

    If filename is `None` then the constructor default (output) is chosen. If filename is `False` or no output filename was set then a temporary file is created (and it is the user’s responsibility to clean up this file).

    Returns the filename of the file written.