1 .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
2 .\"
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.
6 .\"
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.
14 .\"
15 .Dd $Mdocdate: December 02 2021$
16 .Dt NINEPSCRIPT 5
17 .Os
18 .Sh NAME
19 .Nm ninepscript
20 .Nd kamid regress test scripting language
21 .Sh DESCRIPTION
22 .Nm
23 is a custom DSL
24 .Pq domain specific language
25 used to write the regression suite of
26 .Xr kamid 8 .
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.
30 .Pp
31 Additional files can be included with the
32 .Ic include
33 keyword, for example
34 .Bd -literal -offset Ds
35 include "lib.9ps"
36 .Ed
37 .Pp
38 Comments can be placed anywhere, start with the # character and extend
39 until the end of the line.
40 .Pp
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
45 .It literal
46 a bare number or string.
47 A string is a sequence of characters enclosed in single or double quotes
48 .Sq like this
49 or
50 .Dq like this .
51 .It routine call
52 Evaluate the routine code and return the value computed by it.
53 The syntax is
54 .Bd -literal -offset Ds
55 .Ar routine Ns Po Ar arguments... Pc
56 .Ed
57 .Pp
58 The
59 .Ql ...
60 special syntax expands to the list of variable arguments of the
61 current routine.
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
65 a variable
66 .Pq or constant
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
69 scope.
70 .It comparison
71 The syntax is
72 .Bd -literal -offset Ds
73 .Ar expression Cm == Ar expression
74 .Ar expression Cm <= Ar expression
75 .Ed
76 .Pp
77 and yields a true value if the two expressions are considered to be
78 respectively
79 .Sq equal
80 or
81 .Sq lesser equal ,
82 a false value otherwise.
83 Two values are equal if they are both number and represent the same
84 value
85 .Pq regardless of the size
86 or if they're both the same string.
87 .It cast
88 convert one value to another type.
89 The syntax is
90 .Ql Ar expression : Ns Ar type
91 where type is one of
92 .Sq u8 ,
93 .Sq u16 ,
94 .Sq u32
95 or
96 .Sq str .
97 .It field access
98 Access a field of a complex object.
99 The syntax is
100 .Ql Ar object . Ns Ar field .
101 See the
102 .Sx OBJECTS AND FIELDS
103 section for the description of objects types and fields allowed.
104 .El
105 .Pp
106 An expression is considered to be
107 .Dq false
108 if evaluates to a number and its value is zero.
109 Otherwise, it's considered to be
110 .Dq true .
111 .Pp
112 The top-level declarations are:
113 .Bl -tag -width Ds
114 .It Ic const Ar identifier No = Ar value
115 Declare
116 .Ar identifier
117 to be a constant that evaluates to
118 .Ar value .
119 .Ar value
120 must be a literal or a cast from a literal.
121 Multiple constant can be declared at the same time using the following
122 syntax:
123 .Bd -literal -offset Ds
124 .Ic const (
125 	foo = 5
126 	bar = 7
127 )
128 .Ed
129 .Pp
130 Note that newlines are mandatory after an
131 .Ar identifier No = Ar value
132 line in this case.
133 .It Ic proc Ar name Ns Po Ar arguments ... Pc Brq code ...
134 Define a routine called
135 .Ar name
136 that accepts the comma-separated list of
137 .Ar arguments .
138 When a routine is called, its
139 .Ar code
140 gets evaluated in a lexical scope where
141 .Ar arguments
142 are defined to the value passed by the caller.
143 A routine may be called only within another routine body or inside a
144 .Ic testing
145 body.
146 .It Ic testing Ar reason Ic dir Ar path Brq code ...
147 Define a test case.
148 .Ar reason
149 is what the test block is about and
150 .Ar path
151 is the path to the root directory where the test will be executed.
152 .Ar reason
153 and
154 .Ar path
155 must be string literals.
156 .El
157 .Pp
158 Inside a
159 .Ic proc
160 or
161 .Ic testing
162 code block the following instructions are allowed:
163 .Bl -tag -width Ds
164 .It Ar variable Cm = Ar expression
165 Set a local lexical
166 .Ar variable
167 to the value yielded by
168 .Ar expression .
169 The
170 .Ar variable
171 lifetime last from this declaration until the end of the current
172 block.
173 .It Ar procedure Ns Pq Ar arguments ...
174 Execute
175 .Ar procedure
176 with the given
177 .Ar arguments .
178 .It Ic assert Ar comparison
179 Evaluate
180 .Ar comparison
181 and if it not yields a true-ish value terminate the current running
182 test and mark it as failed.
183 Multiple assertion can be done in one single
184 .Ic assert
185 block using the following syntax:
186 .Bd -literal -offset Ds
187 .Ic assert (
188 	comparison_1
189 	comparison_2
190 	...
191 	comparison_n
192 )
193 .Ed
194 .Pp
195 Note that newlines are mandatory after every
196 .Ar comparison
197 in this case.
198 .It Ic should-fail Ar expression Op : Ar reason
199 Evaluate
200 .Ar expression
201 and continue only if the evaluation produced an error.
202 If the execution of
203 .Ar expression
204 is successful, terminate the current test.
205 .Ar reason
206 is optional and, if present, must be a literal string.
207 It is similar to the
208 .Sq try-catch
209 statement of other programming languages.
210 .El
211 .Sh BUILT IN FUNCTIONS
212 These functions are built into the language and provided by the
213 interpreter:
214 .Bl -tag -width Ds
215 .It Ic debug Ns Po Ar arg, ... Pc
216 Print the argument list separated by a space and followed by a newline
217 if the interpreter runs with the verbose flag set.
218 .It Ic iota Ns Pq
219 Return distinct u16 integer every time it's called.
220 Starts at zero and goes up to 254 to then wrap around to zero again.
221 255 is skipped because
222 .Ic iota
223 is intended to be used to provide the tag for
224 .Ic send
225 and 255 is the special
226 .Sq NOTAG
227 value in 9P200.
228 .It Ic print Ns Po Ar arg, ... Pc
229 Print the argument list separated by a space and followed by a
230 newline.
231 .It Ic recv Ns Pq
232 Receive a message from the server and return it as an object.
233 A
234 .Dv Terror
235 doesn't stop the execution of the test, rather, an error object is
236 returned.
237 See
238 .Sx OBJECTS AND FIELDS
239 for the complete list of objects.
240 .It Ic send Ns Po Ar type, tag, ... Pc
241 Send a 9P message with the given
242 .Ar type
243 and
244 .Ar tag .
245 Other arguments, if given, are packed into the message and sent as
246 well, respecting the given order.
247 The overall length of the message is computed automatically.
248 .It Ic skip Ns Pq
249 Terminate the execution of the current test suite immediately.
250 The test won't be counted as passed nor failed, but as skipped.
251 .El
252 .Sh OBJECTS AND FIELDS
253 List of objects and fields...
254 .Sh SEE ALSO
255 .Xr 9p 7 ,
256 .Xr kamid 8 ,
257 .Xr ninepscript 8
258 .Sh AUTHORS
259 .An -nosplit
260 .Nm
261 was designed and implemented by
262 .An Omar Polo Aq Mt op@omarpolo.com
263 for the
264 .Xr kamid 8
265 daemon regression suite.