1 76991ad5 2021-12-02 op .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
  2 76991ad5 2021-12-02 op .\"
  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.
  6 76991ad5 2021-12-02 op .\"
  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.
 14 76991ad5 2021-12-02 op .\"
 15 76991ad5 2021-12-02 op .Dd $Mdocdate: December 02 2021$
 16 76991ad5 2021-12-02 op .Dt NINEPSCRIPT 5
 17 76991ad5 2021-12-02 op .Os
 18 76991ad5 2021-12-02 op .Sh NAME
 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
 22 76991ad5 2021-12-02 op .Nm
 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
 26 76991ad5 2021-12-02 op .Xr kamid 8 .
 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.
 30 76991ad5 2021-12-02 op .Pp
 31 76991ad5 2021-12-02 op Additional files can be included with the
 32 76991ad5 2021-12-02 op .Ic include
 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"
 36 76991ad5 2021-12-02 op .Ed
 37 76991ad5 2021-12-02 op .Pp
 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.
 40 76991ad5 2021-12-02 op .Pp
 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
 45 76991ad5 2021-12-02 op .It literal
 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
 48 76991ad5 2021-12-02 op .Sq like this
 49 76991ad5 2021-12-02 op or
 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.
 53 76991ad5 2021-12-02 op The syntax is
 54 76991ad5 2021-12-02 op .Bd -literal -offset Ds
 55 76991ad5 2021-12-02 op .Ar routine Ns Po Ar arguments... Pc
 56 76991ad5 2021-12-02 op .Ed
 57 76991ad5 2021-12-02 op .Pp
 58 76991ad5 2021-12-02 op The
 59 76991ad5 2021-12-02 op .Ql ...
 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
 65 76991ad5 2021-12-02 op a variable
 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
 69 76991ad5 2021-12-02 op scope.
 70 76991ad5 2021-12-02 op .It comparison
 71 76991ad5 2021-12-02 op The syntax is
 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
 74 76991ad5 2021-12-02 op .Sq equal
 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
 77 76991ad5 2021-12-02 op value
 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.
 80 76991ad5 2021-12-02 op .It cast
 81 76991ad5 2021-12-02 op convert one value to another type.
 82 76991ad5 2021-12-02 op The syntax is
 83 76991ad5 2021-12-02 op .Ql Ar expression : Ns Ar type
 84 76991ad5 2021-12-02 op where type is one of
 85 76991ad5 2021-12-02 op .Sq u8 ,
 86 76991ad5 2021-12-02 op .Sq u16 ,
 87 76991ad5 2021-12-02 op .Sq u32
 88 76991ad5 2021-12-02 op or
 89 76991ad5 2021-12-02 op .Sq str .
 90 76991ad5 2021-12-02 op .It field access
 91 76991ad5 2021-12-02 op Access a field of a complex object.
 92 76991ad5 2021-12-02 op The syntax is
 93 76991ad5 2021-12-02 op .Ql Ar object . Ns Ar field .
 94 76991ad5 2021-12-02 op See the
 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.
 97 76991ad5 2021-12-02 op .El
 98 76991ad5 2021-12-02 op .Pp
 99 76991ad5 2021-12-02 op An expression is considered to be
100 76991ad5 2021-12-02 op .Dq false
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
103 76991ad5 2021-12-02 op .Dq true .
104 76991ad5 2021-12-02 op .Pp
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
108 76991ad5 2021-12-02 op Declare
109 76991ad5 2021-12-02 op .Ar identifier
110 76991ad5 2021-12-02 op to be a constant that evaluates to
111 76991ad5 2021-12-02 op .Ar value .
112 76991ad5 2021-12-02 op .Ar value
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
115 76991ad5 2021-12-02 op syntax:
116 76991ad5 2021-12-02 op .Bd -literal -offset Ds
117 76991ad5 2021-12-02 op .Ic const (
118 76991ad5 2021-12-02 op 	foo = 5
119 76991ad5 2021-12-02 op 	bar = 7
120 76991ad5 2021-12-02 op )
121 76991ad5 2021-12-02 op .Ed
122 76991ad5 2021-12-02 op .Pp
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
128 76991ad5 2021-12-02 op .Ar name
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
132 76991ad5 2021-12-02 op .Ar code
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
137 76991ad5 2021-12-02 op .Ic testing
138 76991ad5 2021-12-02 op body.
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.
141 76991ad5 2021-12-02 op .Ar reason
142 76991ad5 2021-12-02 op is what the test block is about and
143 76991ad5 2021-12-02 op .Ar path
144 76991ad5 2021-12-02 op is the path to the root directory where the test will be executed.
145 76991ad5 2021-12-02 op .Ar reason
146 76991ad5 2021-12-02 op and
147 76991ad5 2021-12-02 op .Ar path
148 76991ad5 2021-12-02 op must be string literals.
149 76991ad5 2021-12-02 op .El
150 76991ad5 2021-12-02 op .Pp
151 76991ad5 2021-12-02 op Inside a
152 76991ad5 2021-12-02 op .Ic proc
153 76991ad5 2021-12-02 op or
154 76991ad5 2021-12-02 op .Ic testing
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
159 76991ad5 2021-12-02 op .Ar variable
160 76991ad5 2021-12-02 op to the value yielded by
161 76991ad5 2021-12-02 op .Ar expression .
162 76991ad5 2021-12-02 op The
163 76991ad5 2021-12-02 op .Ar variable
164 76991ad5 2021-12-02 op lifetime last from this declaration until the end of the current
165 76991ad5 2021-12-02 op block.
166 76991ad5 2021-12-02 op .It Ar procedure Ns Pq Ar arguments ...
167 76991ad5 2021-12-02 op Execute
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
172 76991ad5 2021-12-02 op Evaluate
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
177 76991ad5 2021-12-02 op .Ic assert
178 76991ad5 2021-12-02 op block using the following syntax:
179 76991ad5 2021-12-02 op .Bd -literal -offset Ds
180 76991ad5 2021-12-02 op .Ic assert (
181 76991ad5 2021-12-02 op 	expression_1
182 76991ad5 2021-12-02 op 	expression_2
183 76991ad5 2021-12-02 op 	...
184 76991ad5 2021-12-02 op 	expression_n
185 76991ad5 2021-12-02 op )
186 76991ad5 2021-12-02 op .Ed
187 76991ad5 2021-12-02 op .Pp
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
192 76991ad5 2021-12-02 op Evaluate
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.
198 76991ad5 2021-12-02 op .Ar reason
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.
203 76991ad5 2021-12-02 op .El
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
206 76991ad5 2021-12-02 op interpreter:
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
215 76991ad5 2021-12-02 op .Ic iota
216 76991ad5 2021-12-02 op is intended to be used to provide the tag for
217 76991ad5 2021-12-02 op .Ic send
218 76991ad5 2021-12-02 op and 255 is the special
219 76991ad5 2021-12-02 op .Sq NOTAG
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
223 76991ad5 2021-12-02 op newline.
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.
226 76991ad5 2021-12-02 op A
227 76991ad5 2021-12-02 op .Dv Terror
228 76991ad5 2021-12-02 op doesn't stop the execution of the test, rather, an error object is
229 76991ad5 2021-12-02 op returned.
230 76991ad5 2021-12-02 op See
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
235 76991ad5 2021-12-02 op .Ar type
236 76991ad5 2021-12-02 op and
237 76991ad5 2021-12-02 op .Ar tag .
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.
244 76991ad5 2021-12-02 op .El
245 76991ad5 2021-12-02 op .Sh OBJECTS AND FIELDS
246 76991ad5 2021-12-02 op List of objects and fields...
247 76991ad5 2021-12-02 op .Sh SEE ALSO
248 76991ad5 2021-12-02 op .Xr 9p 7 ,
249 76991ad5 2021-12-02 op .Xr kamid 8 ,
250 76991ad5 2021-12-02 op .Xr ninepscript 8
251 76991ad5 2021-12-02 op .Sh AUTHORS
252 76991ad5 2021-12-02 op .An -nosplit
253 76991ad5 2021-12-02 op .Nm
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
256 76991ad5 2021-12-02 op for the
257 76991ad5 2021-12-02 op .Xr kamid 8
258 76991ad5 2021-12-02 op daemon regression suite.