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 76991ad5 2021-12-02 op .Ql Ar expression Cm == Ar expression
73 76991ad5 2021-12-02 op and yields a true value if the two expressions are considered to be
75 76991ad5 2021-12-02 op or a false value otherwise.
76 76991ad5 2021-12-02 op Two values are equal if they are both number and represent the same
78 76991ad5 2021-12-02 op .Pq regardless of the size
79 76991ad5 2021-12-02 op or if they're both the same string.
81 76991ad5 2021-12-02 op convert one value to another type.
83 76991ad5 2021-12-02 op .Ql Ar expression : Ns Ar type
84 76991ad5 2021-12-02 op where type is one of
90 76991ad5 2021-12-02 op .It field access
91 76991ad5 2021-12-02 op Access a field of a complex object.
93 76991ad5 2021-12-02 op .Ql Ar object . Ns Ar field .
95 76991ad5 2021-12-02 op .Sx OBJECTS AND FIELDS
96 76991ad5 2021-12-02 op section for the description of objects types and fields allowed.
99 76991ad5 2021-12-02 op An expression is considered to be
101 76991ad5 2021-12-02 op if evaluates to a number and its value is zero.
102 76991ad5 2021-12-02 op Otherwise, it's considered to be
105 76991ad5 2021-12-02 op The top-level declarations are:
106 76991ad5 2021-12-02 op .Bl -tag -width Ds
107 76991ad5 2021-12-02 op .It Ic const Ar identifier No = Ar value
109 76991ad5 2021-12-02 op .Ar identifier
110 76991ad5 2021-12-02 op to be a constant that evaluates to
113 76991ad5 2021-12-02 op must be a literal or a cast from a literal.
114 76991ad5 2021-12-02 op Multiple constant can be declared at the same time using the following
116 76991ad5 2021-12-02 op .Bd -literal -offset Ds
123 76991ad5 2021-12-02 op Note that newlines are mandatory after an
124 76991ad5 2021-12-02 op .Ar identifier No = Ar value
125 76991ad5 2021-12-02 op line in this case.
126 76991ad5 2021-12-02 op .It Ic proc Ar name Ns Po Ar arguments ... Pc Brq code ...
127 76991ad5 2021-12-02 op Define a routine called
129 76991ad5 2021-12-02 op that accepts the comma-separated list of
130 76991ad5 2021-12-02 op .Ar arguments .
131 76991ad5 2021-12-02 op When a routine is called, its
133 76991ad5 2021-12-02 op gets evaluated in a lexical scope where
134 76991ad5 2021-12-02 op .Ar arguments
135 76991ad5 2021-12-02 op are defined to the value passed by the caller.
136 76991ad5 2021-12-02 op A routine may be called only within another routine body or inside a
139 76991ad5 2021-12-02 op .It Ic testing Ar reason Ic dir Ar path Brq code ...
140 76991ad5 2021-12-02 op Define a test case.
142 76991ad5 2021-12-02 op is what the test block is about and
144 76991ad5 2021-12-02 op is the path to the root directory where the test will be executed.
148 76991ad5 2021-12-02 op must be string literals.
155 76991ad5 2021-12-02 op code block the following instructions are allowed:
156 76991ad5 2021-12-02 op .Bl -tag -width Ds
157 76991ad5 2021-12-02 op .It Ar variable Cm = Ar expression
158 76991ad5 2021-12-02 op Set a local lexical
160 76991ad5 2021-12-02 op to the value yielded by
161 76991ad5 2021-12-02 op .Ar expression .
164 76991ad5 2021-12-02 op lifetime last from this declaration until the end of the current
166 76991ad5 2021-12-02 op .It Ar procedure Ns Pq Ar arguments ...
168 76991ad5 2021-12-02 op .Ar procedure
169 76991ad5 2021-12-02 op with the given
170 76991ad5 2021-12-02 op .Ar arguments .
171 76991ad5 2021-12-02 op .It Ic assert Ar expression
173 76991ad5 2021-12-02 op .Ar expression
174 76991ad5 2021-12-02 op and if it not yields a true-ish value terminate the current running
175 76991ad5 2021-12-02 op test and mark it as failed.
176 76991ad5 2021-12-02 op Multiple assertion can be done in one single
178 76991ad5 2021-12-02 op block using the following syntax:
179 76991ad5 2021-12-02 op .Bd -literal -offset Ds
188 76991ad5 2021-12-02 op Note that newlines are mandatory after every
189 76991ad5 2021-12-02 op .Ar expression
190 76991ad5 2021-12-02 op in this case.
191 76991ad5 2021-12-02 op .It Ic should-fail Ar expression Op : Ar reason
193 76991ad5 2021-12-02 op .Ar expression
194 76991ad5 2021-12-02 op and continue only if the evaluation produced an error.
195 76991ad5 2021-12-02 op If the execution of
196 76991ad5 2021-12-02 op .Ar expression
197 76991ad5 2021-12-02 op is successful, terminate the current test.
199 76991ad5 2021-12-02 op is optional and, if present, must be a literal string.
200 76991ad5 2021-12-02 op It is similar to the
201 76991ad5 2021-12-02 op .Sq try-catch
202 76991ad5 2021-12-02 op statement of other programming languages.
204 76991ad5 2021-12-02 op .Sh BUILT IN FUNCTIONS
205 76991ad5 2021-12-02 op These functions are built into the language and provided by the
207 76991ad5 2021-12-02 op .Bl -tag -width Ds
208 76991ad5 2021-12-02 op .It Ic debug Ns Po Ar arg, ... Pc
209 76991ad5 2021-12-02 op Print the argument list separated by a space and followed by a newline
210 76991ad5 2021-12-02 op if the interpreter runs with the verbose flag set.
211 76991ad5 2021-12-02 op .It Ic iota Ns Pq
212 76991ad5 2021-12-02 op Return distinct u16 integer every time it's called.
213 76991ad5 2021-12-02 op Starts at zero and goes up to 254 to then wrap around to zero again.
214 76991ad5 2021-12-02 op 255 is skipped because
216 76991ad5 2021-12-02 op is intended to be used to provide the tag for
218 76991ad5 2021-12-02 op and 255 is the special
220 76991ad5 2021-12-02 op value in 9P200.
221 76991ad5 2021-12-02 op .It Ic print Ns Po Ar arg, ... Pc
222 76991ad5 2021-12-02 op Print the argument list separated by a space and followed by a
224 76991ad5 2021-12-02 op .It Ic recv Ns Pq
225 76991ad5 2021-12-02 op Receive a message from the server and return it as an object.
228 76991ad5 2021-12-02 op doesn't stop the execution of the test, rather, an error object is
231 76991ad5 2021-12-02 op .Sx OBJECTS AND FIELDS
232 76991ad5 2021-12-02 op for the complete list of objects.
233 76991ad5 2021-12-02 op .It Ic send Ns Po Ar type, tag, ... Pc
234 76991ad5 2021-12-02 op Send a 9P message with the given
238 76991ad5 2021-12-02 op Other arguments, if given, are packed into the message and sent as
239 76991ad5 2021-12-02 op well, respecting the given order.
240 76991ad5 2021-12-02 op The overall length of the message is computed automatically.
241 76991ad5 2021-12-02 op .It Ic skip Ns Pq
242 76991ad5 2021-12-02 op Terminate the execution of the current test suite immediately.
243 76991ad5 2021-12-02 op The test won't be counted as passed nor failed, but as skipped.
245 76991ad5 2021-12-02 op .Sh OBJECTS AND FIELDS
246 76991ad5 2021-12-02 op List of objects and fields...
249 76991ad5 2021-12-02 op .Xr kamid 8 ,
250 76991ad5 2021-12-02 op .Xr ninepscript 8
254 76991ad5 2021-12-02 op was designed and implemented by
255 76991ad5 2021-12-02 op .An Omar Polo Aq Mt op@omarpolo.com
258 76991ad5 2021-12-02 op daemon regression suite.