tests/README_alternatives.md

   1 # Produces alternatives of text files
   2
   3 alterner.pl is a simple tool that use alternation directives in a text file to produce variations (alternatives) of this text file.
   4
   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.
   6
   7   [1]: http://sablecc.org
   8
   9 Principles of alterner.pl
  10 -------------------------
  11
  12 alterner works line by line and produces alternatives files where some lines are altered.
  13
  14 An line containing an alternation directive looks like
  15
  16     standard text //alt1 alternative text
  17
  18 where `//alt1` is the alternation directive (note there is no space between the `//` and the `alt` nor between the `alt` and the number).
  19
  20 Note: an alternation directive can also be terminated by a `//`.
  21 Eg.
  22
  23     standard text //alt1// alternative text
  24
  25 The first principle is that the alternation is produced by swapping the right part of the directive with its left part.
  26
  27 The basic idea behind alterner.pl is that if `//` marks the start of a comment for your input language then:
  28
  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`.
  31
  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:
  34
  35     this will disappear in the alternative //alt1
  36     //alt1 this will appear in the alternative
  37
  38
  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.
  41
  42 Example:
  43
  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
  47
  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.
  51
  52 Example:
  53
  54     base version //alt1 version of alternative 1 //alt2 version of alternative 2
  55
  56
  57 Lists and ranges
  58 ----------------
  59
  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).
  62
  63 Example:
  64
  65     base version //alt1,3 version of alternative 1 and 3
  66     base version //alt2-4 version of alternatives 2, 3 and 4
  67
  68 Lists and ranges can be used together and multiple alternatives can appears on a single line.
  69
  70     base //alt1,3-4 version for 1, 3, and 4 //alt2,5 version for 2 and 5
  71
  72
  73 Combinations
  74 ------------
  75
  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`.
  78
  79 Example:
  80
  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
  84
  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.
  87
  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:
  90
  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
  96
  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.
  99
 100 Usage of alterner.pl
 101 --------------------
 102
 103     alterner.pl [options] input-file.ext
 104
 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.
 110
 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.
 113
 114
 115 Options
 116 -------
 117
 118 * `-d` directory
 119
 120   Generate the alternatives in the specified directory.
 121   By default, the directory is `alt/`.
 122   Use `.` for the current directory.
 123
 124 * `--start` pattern
 125
 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.
 130
 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.
 133
 134 * `--end` pattern
 135
 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.
 140
 141   The principle of the end pattern is that:
 142
 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).
 145
 146 * `--altsep` separator
 147
 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 `.`.
 150
 151 Examples
 152 --------
 153
 154 Example with default options
 155
 156     $ cat example.txt
 157     foo //alt1 bar
 158     foo //alt1 bar //alt2 baz
 159
 160     $ alterner.pl example.txt
 161     alt/example.alt1.txt
 162     alt/example.alt2.txt
 163
 164     $ echo alt/example.alt1.txt
 165     bar //alt1 foo
 166     bar //alt2 baz //alt1 foo
 167
 168     $ echo alt/example.alt2.txt
 169     foo //alt1 bar
 170     baz //alt2 foo //alt1 bar
 171
 172
 173 Example with directives in C comments.
 174
 175     $ cat input-file.c
 176     base /*alt1 first /*alt2 second */
 177
 178     $ alterner.pl --start '/*' --end '*/' input-file.c
 179     alt/input-file.alt1.c
 180     alt/input-file.alt2.c
 181
 182     $ cat alt/input-file.alt1.c
 183     first /*alt2 second /*alt1 base */
 184
 185     $ cat alt/input-file.alt2.c
 186     second /*alt2 base /*alt1 first */
 187
 188
 189 Example with groups.
 190
 191     $ cat example.txt
 192     first //alt1 second //alt2 third
 193     first //2alt1 second
 194
 195     $ alterner.pl exaple.txt
 196     example.alt1.txt
 197     example.alt2.txt
 198     example.2alt1.txt
 199     example.alt1.2alt1.txt
 200     example.alt2.2alt1.txt