1 # Produces alternatives of text files
3 alterner.pl is a simple tool that use alternation directives in a text file to produce variations (alternatives) of this text file.
5 alterner.pl was primarily developed to help the generation of regression tests for [SableCC][1] but now it aims to be a more generic and versatile tool.
7 [1]: http://sablecc.org
9 Principles of alterner.pl
10 -------------------------
12 alterner works line by line and produces alternatives files where some lines are altered.
14 An line containing an alternation directive looks like
16 standard text //alt1 alternative text
18 where `//alt1` is the alternation directive (note there is no space between the `//` and the `alt` nor between the `alt` and the number).
20 Note: an alternation directive can also be terminated by a `//`.
23 standard text //alt1// alternative text
25 The first principle is that the alternation is produced by swapping the right part of the directive with its left part.
27 The basic idea behind alterner.pl is that if `//` marks the start of a comment for your input language then:
29 * if the file is used unmodified, the useful part of the line will be `standard text`;
30 * if the alternative version is used, the useful part of the line will be `alternative text`.
32 Neither the left or the right part is mandatory.
33 Therefore, directives are often used to make some lines appear or disappear in the alternatives:
35 this will disappear in the alternative //alt1
36 //alt1 this will appear in the alternative
39 The second principle is that there could be many alternatives generated for a single base file.
40 Each alternation directive is numbered (`//alt1`, `//alt2`, `//alt3`, etc.) and, for a given alternative, all the associated directives are applied together.
44 //alt1 this will appear in alternative 1
45 this will disappear in alternative 2 //alt2
46 this is in base and in alternative 2 //alt1 but this is in alternative 1
48 The last principle is that more than one directive can appear on a single line.
49 The first principle still apply: for a given alternative version, the left and right parts of the associated directives are swapped.
50 The trick is that the directives of other alternatives do not interfere.
54 base version //alt1 version of alternative 1 //alt2 version of alternative 2
60 A single directive can be associated to more than one alternative version.
61 Directives for multiple alternatives are declared with a list (separated with a comma) or with a range (indicated with a dash).
65 base version //alt1,3 version of alternative 1 and 3
66 base version //alt2-4 version of alternatives 2, 3 and 4
68 Lists and ranges can be used together and multiple alternatives can appears on a single line.
70 base //alt1,3-4 version for 1, 3, and 4 //alt2,5 version for 2 and 5
76 Each directive belong to a given group: either to the anonymous group (by default) or to a numbered group.
77 The number of the group is noted before the `alt`.
81 base version //1alt1 first alternative of the first group
82 base version //2alt1 first alternative of the second group
83 base version //2alt2 second alternative of the second group
85 alterner.pl also produces alternative files by combining the groups.
86 With two groups, is means that at least three alternative files are created: one with the first group, one with the second group, and one with both.
88 If there is more than one alternative by group, even more alternative files are created.
89 With the previous example, 5 alternative files are created:
91 * one with 1alt1 activated
92 * one with 2alt1 activated
93 * one with 2alt2 activated
94 * one with 1alt1 and 2alt1 activated
95 * one with 1alt1 and 2alt2 activated
97 Be careful with groups since the number of alternative file generated increase rapidly.
98 For instance, with 4 groups of 4 alternatives each, 624 alternative files are generated.
103 alterner.pl [options] input-file.ext
105 Produce alternatives of `input-file.ext` according to the alternation directives present in the file.
106 By default, alternatives are named `input-file.altX.ext` (where `X` is a number) and are generated in a `alt/` sub-directory.
107 If groups are used, the `altX` is replaced by `YaltX` (where `Y` is the number of the group) and the combination of multiple groups produce multiple `YaltX` (separated with dots).
108 If the directory does not exist, it is created.
109 The path of `input-file.ext` is not considered: only the base name of the file and its extension are used to name the alternatives.
111 alterner.pl also outputs the path of each generated alternative (a path by line).
112 This list can be used to know what are the generated alternatives.
120 Generate the alternatives in the specified directory.
121 By default, the directory is `alt/`.
122 Use `.` for the current directory.
126 Alternation directives start with the specified pattern.
127 This option is used to indicate what starts comments in the language.
128 By default, the start pattern is `//`.
129 For example, `--start '#'` means that the alternatives are `#alt1`, `#alt2`, etc.
131 Note: an alternation directive can also be terminated by the start pattern.
132 For example, `--start '#'` means that the alternatives can also be `#alt1#`, `#alt2#`, etc.
136 Lines with alternation directives end with the specified pattern.
137 This option is used to indicate what end comments in the language when multiline comments are used.
138 By default, the end pattern is the empty string.
139 For example, start with `/*` and end with `*/` for using alternatives in a C file.
141 The principle of the end pattern is that:
143 1. alternation directives are ignored if the end pattern is not present at the end of the line;
144 2. the end pattern is not swapped when a directive is applied (it means the end pattern stay at the end of the line).
146 * `--altsep` separator
148 Separator used in the name of the generated file betwen the basename of the original file and the alternative mark.
149 By default, it is `.`.
154 Example with default options
158 foo //alt1 bar //alt2 baz
160 $ alterner.pl example.txt
164 $ echo alt/example.alt1.txt
166 bar //alt2 baz //alt1 foo
168 $ echo alt/example.alt2.txt
170 baz //alt2 foo //alt1 bar
173 Example with directives in C comments.
176 base /*alt1 first /*alt2 second */
178 $ alterner.pl --start '/*' --end '*/' input-file.c
179 alt/input-file.alt1.c
180 alt/input-file.alt2.c
182 $ cat alt/input-file.alt1.c
183 first /*alt2 second /*alt1 base */
185 $ cat alt/input-file.alt2.c
186 second /*alt2 base /*alt1 first */
192 first //alt1 second //alt2 third
195 $ alterner.pl exaple.txt
199 example.alt1.2alt1.txt
200 example.alt2.2alt1.txt