git @ Cat's Eye Technologies Falderal / 928d615
Update spec for Falderal Literate Test Format version 0.8. Cat's Eye Technologies 6 years ago
1 changed file(s) with 43 addition(s) and 23 deletion(s). Raw diff Collapse all Expand all
55 Status
66 ======
77
8 This document is a *draft*. It is nominally "version 0.7" because it
9 describes something that version 0.7 of `Test.Falderal` mostly implements.
8 This document is a *draft*. It is nominally "version 0.8" because it
9 describes something that version 0.8 of `Test.Falderal` mostly implements.
1010 We will deign to note which sections of this document the current released
1111 version of `Test.Falderal` implements, and which it does not. However,
1212 this document is a work in progress, subject to change, and subject to get
3030 ======
3131
3232 Lines which have special meaning to the Falderal Literate Test Format
33 always begin (in the leftmost column) with a series of special characters,
34 called an //introducer//. The introducers which have meaning to the
35 Falderal Literate Test Format are as follows:
33 always begin with an indent of four (4) spaces from the leftmost column
34 followed immediately by a series of distinguished characters, called an
35 _introducer_. The introducers which have meaning to the Falderal Literate
36 Test Format are as follows:
3637
3738 * `->` (hyphen, greater-than sign): pragma
3839 * `| ` (vertical bar, space): input text
6970 used for the characters in it. An implementation of Falderal is not
7071 expected to be able to handle any coding other than UTF-8, however,
7172 this pragma is included for the benefit of text editors and other tools,
72 to indicate that the document is in fact in UTF-8 encoding. It is
73 generally stripped from documents formatted from the Falderal file,
74 perhaps replaced by an equivalent directive for the particular format.
73 to indicate that the document is in fact in UTF-8 encoding.
7574
7675 Example:
7776
9392
9493 Note that the Functionality-definitions given in a Falderal file should
9594 not be considered exhaustive, or even requisite, by a tool. The tool may
96 accept additional definitions of the name of a functionality, from an
97 external source such as the command line or a configuration file, and may
98 be instructed to ignore certain Functionality-definitions in a Falderal
99 file (if, for example, certain implementation are not currently available
100 or of interest to the user.) Indeed, the functionality referred to by a
101 _functionality-name_ in a Tests-for pragma need not be defined by any
95 accept additional definitions of a functionality, referencing it by its
96 name, from an external source such as the command line or a configuration
97 file, and may be instructed to ignore certain Functionality-definitions in
98 a Falderal file (if, for example, certain implementation are not currently
99 available or of interest to the user.) Indeed, the functionality referred
100 to by a _functionality-name_ in a Tests-for pragma need not be defined by any
102101 Functionality-definition pragma in the same Falderal file, and this
103102 situation requires the functionality to be specified to the tool in some
104103 other manner.
119118
120119 For shell commands, the _functionality-specifier_ is in the format
121120 `"command arg1 arg2 ... argn"`. Any line of legal Bourne shell syntax may
122 be used, so pipes, redirection, etc., are supported.
121 be used, so pipes, redirection, etc., are supported. Note that the double
122 quotation mark characters used to enclosed the command have meaning only to
123 the Falderal format — they are not part of the command, are not passed to the
124 shell, and do not require double quotation mark characters that are enclosed
125 by them to be escaped with a backslash.
123126
124127 Certain subsequences, called _variables_, if present in the command string,
125128 will be expanded before execution, and will alter how the command reads the
126129 text of the test and produces its output, to be compared with the expected
127130 output.
128131
132 ### `%(test-file)` ###
133
129134 The variable `%(test-file)` will be replaced by the name of a file which
130 contains the text of the test. This may be a temporary files created
131 solely for this purpose. The variable `%(test-text)` will be replaced by
132 the actual text of the test. It is assumed that `%(test-text)` will appear
133 inside single quotes in the command string, so any single quotes in the
134 text of the test will be escaped. If neither of these variables appear in
135 contains the text of the test. This may be a temporary file created
136 solely for this purpose by the Falderal implementation.
137
138 ### `%(test-text)` ###
139
140 The variable `%(test-text)` will be replaced by the actual text of the test.
141 It is assumed that `%(test-text)` will appear inside single quotes in the
142 command string, so any single quotes in the text of the test will be escaped
143 by the Falderal implementation by preceding them with backslashes.
144
145 If neither of the variables `%(test-file)` nor `%(test-text)` appear in
135146 the command string, the test text will be provided on the standard input of
136147 the shell command.
148
149 ### `%(output-file)` ###
137150
138151 The variable `%(output-file)` will be replaced by the name of a file
139152 (temporary file) to which the test results will be written. If it does
181194
182195 Each section of input text should be followed immediately by either a
183196 section of expected output or expected error output. It may also be
184 preceded by a paragraph of text; this paragraph should be displayed along
185 with the input text and expected text, in a test report.
197 preceded by a paragraph of text; the intent of the Falderal Literate
198 Test Format is that this text should describe the test, or rather, the
199 aspect of the behaviour of the system that the test is meant to check.
200 It is therefore reasonably that this text should be displayed along
201 with the contents (input text and expected text) of the test, in, for
202 example, a test result report.
186203
187204 Discussion
188205 ==========
189206
190 (This section is non-normative, and possibly out-of-date.)
207 (This section is non-normative.)
208
209 Typically, a file in Falderal Literate Test Format will also be in
210 Markdown format.
191211
192212 The format of the lines which comprise the Falderal Literate Test Format
193213 was chosen to not conflict with many other common text formats (including