docs/cocci-python.txt

   1 Python extensions for Coccinelle
   2 ================================
   3
   4 Coccinelle embeds a python interpreter to support processing
   5 matches using the full expressive power of python.
   6
   7 Scripting with python
   8 ---------------------
   9
  10 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:
  11
  12 @ rule1 @ type T; identifier I; expression C, E; position p1, p2; @@
  13 T I[C@p1];
  14 <+... I[E@p2] ...+>
  15 @ script:python @ x_mv << rule1.C; y_mv << rule1.E; x_pos << rule1.p1; y_pos << rule1.p2; @@
  16 x = cocci.combine(x_mv, x_pos)
  17 y = cocci.combine(y_mv, y_pos)
  18 print x.location
  19 print y.location
  20
  21 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.
  22
  23 Controlling environments
  24 ------------------------
  25
  26 The python script will be called for each environment generated by Coccinelle with matches to the previous rules. By default, the python script drops each environment unless otherwise is indicated in the script using cocci.include_match(True).
  27
  28 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".
  29
  30 Output methods for the python scripts
  31 -------------------------------------
  32
  33 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.
  34
  35 -pyoutput coccilib.output.Console   (this is the default)
  36 -pyoutput coccilib.output.Gtk
  37
  38 The latter depends on pygtk2, and the dependency will not be evaluated until runtime.
  39
  40 Creating new python output classes
  41 ----------------------------------
  42
  43 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.
  44
  45 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.
  46
  47 Running spatch from a different directory than it is stored in
  48 --------------------------------------------------------------
  49
  50 In order for spatch to be able to find coccilib, PYTHON_PATH must be set to include the directory in which spatch resides.