.. include:: ../global.inc
.. _decorators.split:
.. index::
pair: @split; Syntax
.. role:: raw-html(raw)
:format: html
:raw-html:``
.. role:: red
.. seealso::
* :ref:`@split ` in the **Ruffus** Manual
* :ref:`Decorators ` for more decorators
########################################################################
split
########################################################################
************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************
@split ( |input|_, |output|_, [|extras|_,...] )
************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************
.. |input| replace:: `input`
.. _input: `decorators.split.input`_
.. |extras| replace:: `extras`
.. _extras: `decorators.split.extras`_
.. |output| replace:: `output`
.. _output: `decorators.split.output`_
**Purpose:**
| Splits a single set of |input|_ into multiple |output|_, where the number of
|output|_ may not be known beforehand.
| Only out of date tasks (comparing |input|_ and |output|_ files) will be run
**Example**::
@split("big_file", '*.little_files')
def split_big_to_small(input_file, output_files):
print "input_file = %s" % input_file
print "output_file = %s" % output_file
.
will produce::
input_file = big_file
output_file = *.little_files
**Parameters:**
.. _decorators.split.input:
* **input** = *tasks_or_file_names*
can be a:
#. (Nested) list of file name strings (as in the example above).
| File names containing ``*[]?`` will be expanded as a |glob|_.
| E.g.:``"a.*" => "a.1", "a.2"``
#. Task / list of tasks.
File names are taken from the output of the specified task(s)
.. _decorators.split.output:
* **output** = *output*
Specifies the resulting output file name(s) after string substitution
Can include glob patterns (e.g. ``"*.txt"``)
| These are used **only** to check if the task is up to date.
| Normally you would use either a |glob|_ (e.g. ``*.little_files`` as above) or a "sentinel file"
to indicate that the task has completed successfully.
| You can of course do both:
::
@split("big_file", ["sentinel.file", "*.little_files"])
def split_big_to_small(input_file, output_files):
pass
.. _decorators.split.extras:
* **extras** = *extras*
Any extra parameters are passed verbatim to the task function
If you are using named parameters, these can be passed as a list, i.e. ``extras= [...]``
Any extra parameters are consumed by the task function and not forwarded further down the pipeline.
.. warning::
Deprecated since Ruffus v 2.5
:red:`@split( input, output, filter =` ``regex(...)``, ``add_inputs(...)`` | ``inputs(...)``, :red:`[|extras|_,...] )` is a synonym for :ref:`@subdivide `.