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