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.