1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
.. include:: ../global.inc
.. _decorators.files_re:
.. index::
pair: @files_re; Syntax
.. seealso::
* :ref:`Decorators <decorators>` for more decorators
########################
@files_re
########################
.. |tasks_or_file_names| replace:: `tasks_or_file_names`
.. _tasks_or_file_names: `decorators.files_re.tasks_or_file_names`_
.. |extra_parameters| replace:: `extra_parameters`
.. _extra_parameters: `decorators.files_re.extra_parameters`_
.. |output_pattern| replace:: `output_pattern`
.. _output_pattern: `decorators.files_re.output_pattern`_
.. |input_pattern| replace:: `input_pattern`
.. _input_pattern: `decorators.files_re.input_pattern`_
.. |matching_regex| replace:: `matching_regex`
.. _matching_regex: `decorators.files_re.matching_regex`_
*****************************************************************************************************************************************
*@files_re* (|tasks_or_file_names|_, |matching_regex|_, [|input_pattern|_], |output_pattern|_, [|extra_parameters|_,...])
*****************************************************************************************************************************************
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Legacy design now deprecated. We suggest using :ref:`@transform() <decorators.transform>` instead
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**Purpose:**
All singing, all dancing decorator which can do everything that :ref:`@merge() <decorators.merge>` and
:ref:`@transform() <decorators.transform>` can do.
Applies the task function to transform data from input to output files.
Output file names are determined from |tasks_or_file_names|_, i.e. from the output
of specified tasks, or a list of file names, using regular expression pattern substitutions.
Only out of date tasks (comparing input and output files) will be run.
**Example**:
::
from ruffus import *
#
# convert all files ending in ".1" into files ending in ".2"
#
@files_re('*.1', '(.*).1', r'\1.2')
def transform_func(infile, outfile):
open(outfile, "w").write(open(infile).read() + "\nconverted\n")
pipeline_run([task_re])
If the following files are present ``a.1``, ``b.1``, ``c.1``, this will result in the following function calls:
::
transform_func("a.1", "a.2")
transform_func("b.1", "b.2")
transform_func("c.1", "c.2")
**Parameters:**
.. _decorators.files_re.tasks_or_file_names:
* *tasks_or_file_names*
can be a:
#. Task / list of tasks (as in the example above).
File names are taken from the output of the specified task(s)
#. (Nested) list of file name strings.
File names containing ``*[]?`` will be expanded as a |glob|_ .
E.g.:``"a.*" => "a.1", "a.2"``
.. _decorators.files_re.matching_regex:
* *matching_regex*
a python regular expression string.
| See python `regular expression (re) <http://docs.python.org/library/re.html>`_ documentation for details of regular expression syntax
| Each output file name is created using regular expression substitution with |output_pattern|_
.. _decorators.files_re.input_pattern:
* *input_pattern*
Optionally specifies the resulting input file name(s).
.. _decorators.files_re.output_pattern:
* *output_pattern*
Specifies the resulting output file name(s).
.. _decorators.files_re.extra_parameters:
* [*extra_parameters, ...*]
Any extra parameters are passed to the task function.
| Regular expression substitution is first applied to (even nested) string parameters.
| Other data types are passed verbatim.
For example:
::
from ruffus import *
#
# convert all files ending in ".1" into files ending in ".2"
#
@files_re('*.1', '(.*).1', r'\1.2', [r'\1', 55], 17)
def transform_func(infile, outfile, extras, extra3):
extra1, extra2 = extras
open(outfile, "w").write(open(infile).read() + "\nconverted%s\n" % (extra1, extra2, extra3))
pipeline_run([transform_func])
If the following files are present ``a.1``, ``b.1``, ``c.1``, this will result in the following function calls:
::
transform_func("a.1", "a.2", ["a", 55], 17)
transform_func("b.1", "b.2", ["b", 55], 17)
transform_func("c.1", "c.2", ["c", 55], 17)
|
