1 .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
3 .\" Permission to use, copy, modify, and distribute this software for any
4 .\" purpose with or without fee is hereby granted, provided that the above
5 .\" copyright notice and this permission notice appear in all copies.
7 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .Dd $Mdocdate: January 09 2022$
20 .Nd kamid regress test scripting language
24 .Pq domain specific language
25 used to write the regression suite of
27 it has a fairly simple and regular syntax that features constant
28 declarations, routines, test cases.
29 It does not support conditional or loops.
31 Additional files can be included with the
34 .Bd -literal -offset Ds
38 Comments can be placed anywhere, start with the # character and extend
39 until the end of the line.
41 An expression is a fundamental building block.
42 It is something that yields a value.
43 An expression may be either a:
44 .Bl -tag -width variable_reference
46 a bare number or string.
47 A string is a sequence of characters enclosed in single or double quotes
52 Evaluate the routine code and return the value computed by it.
54 .Bd -literal -offset Ds
55 .Ar routine Ns Po Ar arguments... Pc
60 special syntax expands to the list of variable arguments of the
62 Be aware that the implementation of the variable arguments is quirky
63 and has a lot of corner cases, use with care!
64 .It variable reference
67 reference is the name of a previously defined variable or constant.
68 It evaluates to the value of the variable or constant in the current
72 .Bd -literal -offset Ds
73 .Ar expression Cm == Ar expression
74 .Ar expression Cm <= Ar expression
77 and yields a true value if the two expressions are considered to be
82 a false value otherwise.
83 Two values are equal if they are both number and represent the same
85 .Pq regardless of the size
86 or if they're both the same string.
88 convert one value to another type.
90 .Ql Ar expression : Ns Ar type
98 Access a field of a complex object.
100 .Ql Ar object . Ns Ar field .
102 .Sx OBJECTS AND FIELDS
103 section for the description of objects types and fields allowed.
106 An expression is considered to be
108 if evaluates to a number and its value is zero.
109 Otherwise, it's considered to be
112 The top-level declarations are:
114 .It Ic const Ar identifier No = Ar value
117 to be a constant that evaluates to
120 must be a literal or a cast from a literal.
121 Multiple constant can be declared at the same time using the following
123 .Bd -literal -offset Ds
130 Note that newlines are mandatory after an
131 .Ar identifier No = Ar value
133 .It Ic proc Ar name Ns Po Ar arguments ... Pc Brq code ...
134 Define a routine called
136 that accepts the comma-separated list of
138 When a routine is called, its
140 gets evaluated in a lexical scope where
142 are defined to the value passed by the caller.
143 A routine may be called only within another routine body or inside a
146 .It Ic testing Ar reason Brq code ...
149 is what the test block is about and must be a string literal.
156 code block the following instructions are allowed:
158 .It Ar variable Cm = Ar expression
161 to the value yielded by
165 lifetime last from this declaration until the end of the current
167 .It Ar procedure Ns Pq Ar arguments ...
172 .It Ic assert Ar comparison
175 and if it not yields a true-ish value terminate the current running
176 test and mark it as failed.
177 Multiple assertion can be done in one single
179 block using the following syntax:
180 .Bd -literal -offset Ds
189 Note that newlines are mandatory after every
192 .It Ic should-fail Ar expression Op : Ar reason
195 and continue only if the evaluation produced an error.
198 is successful, terminate the current test.
200 is optional and, if present, must be a literal string.
203 statement of other programming languages.
205 .Sh BUILT IN FUNCTIONS
206 These functions are built into the language and provided by the
209 .It Ic debug Ns Po Ar arg, ... Pc
210 Print the argument list separated by a space and followed by a newline
211 if the interpreter runs with the verbose flag set.
213 Return distinct u16 integer every time it's called.
214 Starts at zero and goes up to 254 to then wrap around to zero again.
215 255 is skipped because
217 is intended to be used to provide the tag for
219 and 255 is the special
222 .It Ic print Ns Po Ar arg, ... Pc
223 Print the argument list separated by a space and followed by a
226 Receive a message from the server and return it as an object.
229 doesn't stop the execution of the test, rather, an error object is
232 .Sx OBJECTS AND FIELDS
233 for the complete list of objects.
234 .It Ic send Ns Po Ar type, tag, ... Pc
235 Send a 9P message with the given
239 Other arguments, if given, are packed into the message and sent as
240 well, respecting the given order.
241 The overall length of the message is computed automatically.
243 Terminate the execution of the current test suite immediately.
244 The test won't be counted as passed nor failed, but as skipped.
246 .Sh OBJECTS AND FIELDS
247 List of objects and fields...
255 was designed and implemented by
256 .An Omar Polo Aq Mt op@omarpolo.com
259 daemon regression suite.