Python extensions for Coccinelle
================================

Coccinelle embeds a python interpreter to support processing
matches using the full expressive power of python.

Scripting with python
---------------------

A python script part to a .cocci file must not be the first rule. A typical sample for searching for constantly sized arrays and its uses could be:

@ rule1 @ type T; identifier I; expression C, E; position p1, p2; @@
T I[C@p1];
<+... I[E@p2] ...+>
@ script:python @ x_mv << rule1.C; y_mv << rule1.E; x_pos << rule1.p1; y_pos << rule1.p2; @@
x = cocci.combine(x_mv, x_pos)
y = cocci.combine(y_mv, y_pos)
print x.location
print y.location

Here cocci is the interface class for interfacting with Coccinelle's OCaml core. It is part python and part OCaml code. The combine function ensures that the filename, line number and column number of the matches are registered with a meta-variable.

Controlling environments
------------------------

The python script will be called for each environment generated by
Coccinelle with matches to the previous rules. By default, the python
script keeps each environment unless otherwise is indicated in the script
using cocci.include_match(False).

As a short-cut for registering information that "belongs together", the
Output class also provides a register_match method that may be overridden
in derived classes. This method can be called like:
cocci.register_match(True, [(x, 'Array size'), (y, 'Array index
size')]). Here the True is automatically passed on to include_match (so one
could use False in order to drop the environment, but still print
information). In the GTK frontend, this will result in the "Array index
size" information being shown as a child node to the "Array size".

cocci.exit() simply aborts the treatment of the current file.  Previously
made changes do take effect.

Output methods for the python scripts
-------------------------------------

By default Coccinelle contains two output modes: a console-based output, and a GTK-based output. Which one is used is specified using the -pyoutput switch to spatch.

-pyoutput coccilib.output.Console   (this is the default)
-pyoutput coccilib.output.Gtk

The latter depends on pygtk2, and the dependency will not be evaluated until runtime.

Creating new python output classes
----------------------------------

If you have a need to tailor special output based on your python script, e.g. using register_match of existing scripts, you can do this by deriving from coccilib.output.Output and override the implementation of register_match(self, include, messages). The method expects that the first thing you call is "self.include_match(include)", but otherwise the details of the method is left up to you.

To use your custom output class, just specify it as an argument to -pyoutput. It needs to exist in the default python execution environment or in PYTHON_PATH.

Running spatch from a different directory than it is stored in
--------------------------------------------------------------

In order for spatch to be able to find coccilib, PYTHON_PATH must be set to include the directory in which spatch resides.
