diff options
Diffstat (limited to 'doc/dev')
| -rw-r--r-- | doc/dev/index.rst | 21 | ||||
| -rw-r--r-- | doc/dev/processor.rst | 142 |
2 files changed, 146 insertions, 17 deletions
diff --git a/doc/dev/index.rst b/doc/dev/index.rst index 6cedacc..66bd679 100644 --- a/doc/dev/index.rst +++ b/doc/dev/index.rst @@ -62,11 +62,7 @@ The basic syntax of the patchtree CLI is as follows: .. code:: none - $ patchtree TARGET INPUT [INPUT ...] - -.. note:: - - The inputs are interpreted as globs. + $ patchtree TARGET [INPUT ...] By default, the resulting patch is written to the standard output. This behavior, along with many other default behaviors can be changed through the command-line arguments (see ``--help``) or the `configuration file <ptconfig_>`_. @@ -78,13 +74,10 @@ Writing patchset sources Each patchset source file is compared to the target source file of the same name, and the resulting diff is output in the clean patch. This means that the default behavior of files placed in the patchset is to add or replace any file in the target source tree. -Because most of the time only small adjustments have to be made to the target sources, patchtree uses so-called :ref:`processors <processors>`. +Because most of the time only small adjustments have to be made to the target sources, patchtree uses so-called processors. Every patchset source is first processed by 0 or more processors, which transform the input's content before it is compared to the target file's content. -These have access to the global :any:`Context` instance, the target file's content, and the (possibly processed) input's content. This mechanism allows you to describe changes *semantically* so they can apply to multiple versions of-- or variations in the target. -.. _processors: - Processors ========== @@ -100,16 +93,10 @@ For example: \_____________________________________/\__________/ target source file path processors -In the above example, the input is first processed by jinja, and the resulting file content is piped into Coccinelle as if a file with the output from jinja existed under the name ``ad_crypto.c#cocci``. +In the above example, the input is first processed by :ref:`jinja <process_jinja>`, and the resulting file content is piped into :ref:`Coccinelle <process_cocci>` as if a file with the output from jinja existed under the name ``ad_crypto.c#cocci``. Coccinelle will in this case output a modified copy of ``ad_crypto.c``, which will be compared to the original to produce the diff for this file. -All processors included with patchtree are listed below: - -.. toctree:: - :maxdepth: 1 - - processor.rst - +The processors included with patchtree are documented on the :ref:`processors` page. Custom processors can be created by inheriting from the base :any:`Process` class and registering through the `configuration file <ptconfig_>`_'s :any:`processors <Config.processors>` value. .. _ptconfig: diff --git a/doc/dev/processor.rst b/doc/dev/processor.rst index 077c2bf..0a19ab8 100644 --- a/doc/dev/processor.rst +++ b/doc/dev/processor.rst @@ -1,14 +1,156 @@ +.. _processors: + +########## +Processors +########## + +This page lists all built-in processor types along with descriptions of what they do and which options they take. +On this page, **output** refers to what the processor returns, while **input** refers to how the processor treats its input. +This input is either (a) the content of the patchset file for the first processor, or (b) the output received from the previous processor. +**Arguments** are any options explicitly given to the processor through the filename, e.g. ``filename#processor,arg,arg2=value,arg3#processor2``. +Note that some processors may take positional arguments, while others may use key/value based options instead. + +.. _process_id: + +******** Identity ******** +The identity processor is used to "touch" files or add arbitrary identifiers to patchset source filenames through its arguments. + +.. list-table:: + :stub-columns: 1 + + * - Class + - :any:`ProcessIdentity` + * - Identifier + - ``id`` + +Input + Ignored. + +Output + The *content* of the target file. + + .. note:: + + Changing the patchset input's mode *will* affect the target file mode! + +Arguments + Any arguments passed to this processor are ignored. + +.. _process_cocci: + +********** Coccinelle ********** +The Coccinelle processor uses Coccinelle to apply patch(es) in the SmPL (Semantic Patch Language) format. + +.. important:: + + In order to use this processor, Coccinelle must be installed and ``spatch`` must be available in ``$PATH``. + +.. list-table:: + :stub-columns: 1 + + * - Class + - :any:`ProcessCoccinelle` + * - Identifier + - ``cocci`` + +Input + Coccinelle's SmPL input. + +Output + The contents of the target file after being processed by Coccinelle (not the diff returned by Coccinelle). + +Arguments + Reserved. + +.. _process_jinja: + +************** Jinja template ************** +The Jinja processor passes the inputs through the Jinja2 templating engine. + +.. note:: + + Template variables are generated through the :any:`get_template_vars <ProcessJinja2.get_template_vars>` method. + This method returns an empty dict by default, and is meant to be implemented by implementing a custom class that derives from ProcessJinja2 and registering it through the :ref:`configuration file <ptconfig>`. + +.. list-table:: + :stub-columns: 1 + + * - Class + - :any:`ProcessJinja2` + * - Identifier + - ``jinja`` + +Input + Jinja template code. + +Output + The input after being processed by Jinja. + +Arguments + Reserved. + +.. _process_exe: + +********** Executable ********** +The executable processor runs the input as an executable, passes the target file to its standard input, and returns its standard output. + +.. list-table:: + :stub-columns: 1 + + * - Class + - :any:`ProcessExec` + * - Identifier + - ``exec`` + +Input + Executable script. + + .. important:: + + The executable must contain a shebang line to specify what interpreter to use. + +Output + Any content written to the standard output by the executable. + +Arguments + Reserved. + +.. _process_merge: + +***** Merge ***** + +The merge processor merges the input with the target file, such that changes are combined with the target instead of replacing the target. + +.. list-table:: + :stub-columns: 1 + + * - Class + - :any:`ProcessMerge` + * - Identifier + - ``merge`` + +Input + Content to merge. + +Output + Merged changes. + +Arguments (positional) + 1. Merge strategy: + + ``ignore`` + Appends all lines from the input to the output excluding any lines already present in the output. |