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