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