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