Mercurial > ~dholland > hg > ag > index.cgi

comparison doc/misc/html/examples/dsl.html @ 0:13d2b8934445

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import AnaGram (near-)release tree into Mercurial.
author David A. Holland
date Sat, 22 Dec 2007 17:52:45 -0500
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:13d2b8934445
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <HTML>
3 <HEAD>
4 <TITLE>DOS Script Language</TITLE>
5 </HEAD>
6
7
8 <BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif"
9 TEXT="#000000" LINK="#0033CC"
10 VLINK="#CC0033" ALINK="#CC0099">
11
12 <P>
13 <IMG ALIGN="right" SRC="../images/agrsl6c.gif" ALT="AnaGram"
14 WIDTH=124 HEIGHT=30 >
15 <BR CLEAR="all">
16 Back to <A HREF="../index.html">Index</A>
17 <P>
18 <IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------"
19 WIDTH=1010 HEIGHT=2 >
20 <P>
21
22 <H1>DOS Script Language </H1>
23
24 <IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------"
25 WIDTH=1010 HEIGHT=2 >
26 <P>
27 <H2>Introduction</H2>
28 <P>
29 DSL is a script language, written in AnaGram, which provides
30 powerful extensions to the batch processing facilities
31 available with DOS batch files.
32 <P>
33 DSL was built in large part by combining components from
34 other grammars. Although the grammar for DOS command lines
35 and for screen displays was written explicitly for DSL, just
36 about everything else was borrowed from other grammars.
37 <P>
38 DSL has been tested using Borland C++, V4.52, and Watcom C++,
39 V10.6. #ifdef statements have been used where necessary to
40 support both compilers. V10.6 can be used to produce either
41 16 or 32 bit executables. If you use Watcom, be sure to
42 specify a stack size of at least 16K bytes.
43 <P>
44 DSL cannot be used with Microsoft Visual C++, since MSVC V1.5
45 does not support templates and V4.x and subsequent releases do
46 not support DOS.
47 <P>
48 <!-- not yet true
49 DSL has been arranged so it will compile under Unix, but it
50 will not run in any useful fashion.
51 -->
52 <P>
53 DSL was written as part of the AnaGram 1.x installer; it is
54 now obsolete but retains certain features of interest.
55 <P>
56
57 <H2> Features of DSL </H2>
58 <UL>
59 <LI> DOS command line interpreter with substitutable
60 parameters, redirection and pipelines. </LI>
61 <LI> Screen builder for interactive parameter specification. </LI>
62 <LI> String and integer variables, expressions and comparisons </LI>
63 <LI> DOS for statement. </LI>
64 <LI> Nested if and while statements. </LI>
65 </UL>
66 <P>
67
68 <H2> Screen Description </H2>
69 The screen description syntax allows you to specify the
70 size, location, and colors of windows plus two kinds of data
71 entry fields: data fields and buttons.
72 <P>
73 A data field description consists of a prompt, an
74 explanation, a variable name for the data, and a default
75 value expression. The expression is evaluated for the
76 default value of the data whenever the screen is refreshed.
77 This means it can be modified as data entry is proceeding,
78 based on fresh information.
79 <P>
80 A button description consists of a prompt, an explanation,
81 and an action field. The action field consists of any
82 sequence of DOS commands enclosed in brackets. Each command
83 should be on a new line.
84 <P>
85
86
87 <H2> Variables and Constants </H2>
88 DSL has three types of variables: undeclared, integer, and
89 string variables.
90 <P>
91 Undeclared variables may be used in DOS commands and screen
92 descriptions. They may appear on the left side of assignment
93 statements. The names of undeclared variables are simple
94 "literals", that is, sequences of characters drawn from the
95 set "text char". If an undeclared variable does not have a
96 value assigned to it, either by an assignment statement or
97 by its use in a screen, it will be taken literally.
98 <P>
99 Integer and string variables must be declared. They may be
100 used in expressions and comparisons. In particular they may
101 be used in if statements and while statements.
102 <P>
103 DSL supports 32 bit integer arithmetic using essentially the
104 expression logic in C with a slight modification for string
105 comparison. Integer constants may be decimal, octal,
106 hexadecimal or character constants, using the C conventions.
107 <P>
108 Beside simple "literals", DSL supports "string literals"
109 which follow the rules for string literals in C, and
110 parenthesized literals. Parenthesized literals are enclosed
111 in parentheses and may contain any characters whatsoever,
112 the only restriction being that any nested parentheses must
113 balance. When a parenthesized literal is evaluated, the outer
114 parentheses are stripped.
115 <P>
116
117
118 <H2> Theory of Operation </H2>
119 DSL is a purely interpretive program. In some circumstances,
120 statements and commands are executed as they are scanned. In
121 other cases, where execution is to be delayed or is
122 conditional, they are simply passed over on first scan and
123 then copied. DSL then calls itself recursively to execute
124 the copy when it is appropriate.
125 <P>
126 Note that if the parser you build from <tt>dsl.syn</tt> is called
127 without any arguments, it looks for a script with the same
128 name as the executable. Thus, to make an install program
129 that picks up the install script without any arguments, you
130 simply rename <tt>dsl.exe</tt> to <tt>install.exe</tt>. Then
131 when you run it
132 without any arguments it will run the <tt>install.dsl</tt> script.
133 <P>
134 DSL makes extensive use of a number of simple data
135 structures defined in the <tt>oldclasslib</tt> directory of
136 the AnaGram distribution. The most important
137 of these are the string accumulators, the string
138 dictionaries, and the stacks.
139 <P>
140 <P>
141 The remainder of this document provides a brief overview of
142 the principal data structures used by DSL and the most
143 important nonterminal tokens in the DSL grammar.
144 <P>
145
146 <H2> Stacks </H2>
147 <H4>as</H4>
148 This is a stack of pointers to actions which have been
149 identified in the parse. An action is a block of commands
150 enclosed in braces {}. The action pointer records a
151 pointer to the beginning of the action, as well as the line
152 and column number where the action begins. The use of a stack
153 allows nested actions.
154
155 <H4>is</H4>
156 This is a stack of integers. Its only use is for recording
157 string concatenation sequences, where the integers stacked
158 are the string dictionary indices of the items to be
159 concatenated.
160
161 <H4>ps</H4>
162 This stack accumulates pointers to the parameter strings for
163 a call to a DOS function.
164 <P>
165
166 <H2> Symbol Table </H2>
167 Three data structures are used to gather and maintain
168 symbol table information. The first is a string accumulator,
169 sa, which is used for temporary storage for all strings that
170 are recognized by the parser. The string dictionary, sd, is
171 used to identify strings. The array st contains specific
172 information about strings indexed in sd.
173 <P>
174
175 <H2> Nonterminal Tokens </H2>
176 <H4> action text </H4>
177 "action text" is any sequence of commands enclosed in
178 balanced braces. action text may be used in most contexts
179 where a string value is expected. In these situations, the
180 enclosed commands are executed, the content of stdout is
181 captured as a string, and is returned as the value of the
182 action text. For example, {DIR} returns a string containing
183 the file directory for the current directory.
184 <P>
185 <H4> action text head </H4>
186 "action text head" is simply action text up to the
187 terminating right brace.
188 <P>
189 <H4> assignment </H4>
190 Normally, an identifier on the left, an expression on the
191 right, the kind of expression depending on the identifier.
192 Note that using the '@' operator you can modify characters
193 inside a string.
194 <P>
195 <H4> built_in name </H4>
196 Note that there are a number of arithmetic functions built
197 into DSL.
198 <P>
199 <H4> button line </H4>
200 A button line is a line on a screen display that controls
201 the further execution of the script. The description of the
202 button line requires a label, an explanation, and an action
203 to be performed when the button is selected.
204 <P>
205 <H4> character constant </H4>
206 Follows the same rules as in C.
207 <P>
208 <H4> command </H4>
209 This is the syntax for a DOS command line, allowing
210 redirected input and output and piped commands.
211 <P>
212 <H4> command sequence </H4>
213 A command sequence is any sequence of statements and
214 if statements that ends with a statement.
215 <P>
216 <H4> comment </H4>
217 This is an ordinary C-style comment.
218 <P>
219 <H4> comment head </H4>
220 The beginning of a comment. Normally everything but the
221 terminating <CODE> */ </CODE>. If a nested comment is found, the rule
222 "comment head, comment" should reduce to "comment head" if it
223 is desired that comments nest. If this rule reduces to
224 "comment", the terminating <CODE> */ </CODE> of the nested comment will
225 serve to terminate the outer level comment as well, and
226 comments will not nest. See the discussion in
227 AnaGram\SBB.DOC or in Appendix D, <A href="sbb-doc.html">Syntactic Building
228 Blocks</A>, in the AnaGram User's Guide.
229 <P>
230 <H4> conditional exp </H4>
231 This is the standard C expression logic modified as follows:
232 Integer arithmetic only; string comparison allowed; no
233 auto-increment or auto-decrement operators.
234 <P>
235 <H4> declaration </H4>
236 Three kinds of declarations: actions can be used like DOS
237 commands. The definition lists substitutable arguments which
238 can be supplied at execution time.
239 <P>
240 Variables which are declared to be strings or ints must
241 satisfy the usual naming conventions of program variables in
242 order to avoid confusion in the expression logic.
243
244 <P>
245 <H4> eol </H4>
246 eol is a newline character, optionally preceded by a C++
247 style comment beginning with //. eol is not included in "ws"
248 because it is used as a statement terminator.
249 <P>
250 <H4> execution block </H4>
251 A sequence of DOS commands enclosed within braces. The
252 difference between an execution block and "action text" is
253 that the commands in an execution block are performed as
254 they are encountered, while "action text" is saved up for
255 later execution.
256 <P>
257 <H4> for statement </H4>
258 Modeled on the for statement in the DOS batch language
259 rather than on the for statement in C.
260 <P>
261 <H4> formula </H4>
262 A sequence of "words", joined by concatenation operators
263 ('#'). When the formula is evaluated, the words are
264 identified in the string dictionary, and their values are
265 concatenated. If a word has no entry in the dictionary its
266 literal value is used. Formulas are used in the
267 specification of the fields in a query line.
268 <P>
269 <H4> identifier </H4>
270 A DOS command
271 <P>
272 <H4> if condition </H4>
273 The keyword if and a conditional expression within
274 parentheses.
275 <P>
276 <H4> if sequence </H4>
277 An if sequence is any direct sequence of statements and if
278 statements that ends with an if statement. The difference
279 between an "if sequence" and a "command sequence" is that an
280 else clause may follow the "if sequence".
281 <P>
282 <H4> if statement </H4>
283 An "if condition" followed by "action text". Note that a
284 simple statement is not allowed.
285 <P>
286 <H4> integer constant </H4>
287 Follows the same rules as an integer constant in C, allowing
288 decimal, octal and hex constants.
289 <P>
290 <H4> integer variable </H4>
291 An variable that has been declared with an "int" statement.
292 <P>
293 <H4> literal </H4>
294 A "literal" is any sequence of characters that does not
295 include white space; parentheses, brackets, or braces;
296 quotation marks or newline characters; redirection or pipe
297 operators, or '#' or '='. Essentially, a "literal" is
298 anything that would make sense on a DOS command line.
299 <P>
300 <H4> literals </H4>
301 A sequence of instances of "literal" separated by white
302 space. This sequence is used only in the definition of a
303 named action. The first literal is the name of the action.
304 Subsequent literals are the local names of the substituble
305 parameters.
306 <P>
307 <H4> name </H4>
308 Used for int and string variables. The conventional rules
309 for variable names in programming language are used.
310 <P>
311 <H4> parameter string </H4>
312 parameter string is essentially the same as "string", except
313 that any of the concatenated strings may be action text,
314 that is the result of executing a DOS command and capturing
315 stdout.
316 <P>
317 <H4> parameter word </H4>
318 parameter word is essentially the same as "word", except
319 that it may also be action text, that is, the result of
320 executing a DOS command and capturing stdout.
321 <P>
322 <H4> parameters </H4>
323 The parameters for a DOS command
324 <P>
325 <H4> paren string </H4>
326 A parenthesized string is any sequence of characters within
327 parentheses, with the only restriction that any nested
328 parentheses must balance. When evaluated, the outer set of
329 parentheses is stripped. Parenthesized strings are for use
330 in DOS command lines in those situations where the
331 restrictions on "literal" are excessively onerous.
332 <P>
333 <H4> piped command </H4>
334 A "piped command", here, is any DOS command, for which
335 stdout must be captured and redirected.
336 <P>
337 <H4> primary exp </H4>
338 These are the basic elements of expressions. Note that you
339 may use the '@' operator to extract a character from a
340 string. You need not use parentheses on the right if you use
341 a simple index variable or integer constant. If you wish to
342 use a more complex expression, you must use parentheses.
343 <P>
344 <H4> query line </H4>
345 This is the description of a line on a screen into which the
346 user is invited to enter some data. The description requires
347 four elements: the variable into which the data is to be
348 stored, the default value for the data, a prompt which
349 identifies the data, and an explanation field which provides
350 a fuller explanation of the data required.
351 <P>
352 After data has been entered for a particular query line, all
353 elements of other query lines are reevaluated in case their
354 defaults have been defined in terms of the data entered.
355 <P>
356 <H4> screen description </H4>
357 A sequence of screen items enclosed in braces. A screen
358 description is executed as it is read. If you wish to
359 describe a screen for later use, incorporate it in an
360 "action declaration".
361 <P>
362 A screen description requires a number of "screen items".
363 These items consist of the title, the color specifications,
364 the size and location of the window, and a number of query
365 lines and button lines.
366 <P>
367 The layout of the screen is done automatically.
368 <P>
369
370 <H4> script file </H4>
371 This is the grammar token. It describes the entire script
372 file.
373 <P>
374 <H4> statement </H4>
375 Statements include DOS commands plus declarations,
376 assignment statements, control statements and screen
377 descriptions. Note the repetition of the while statement.
378 This stratagem allows a very simple implementation of
379 looping logic.
380 <P>
381 <H4> string </H4>
382 "string" is a concatenation of "word"s, using the
383 concatenation operator, '#'.
384 <P>
385 <H4> string exp </H4>
386 Syntactically the same as "string", except that the
387 primitive elements are different.
388 <P>
389 <H4> string literal </H4>
390 Follows exactly the same rules as string literals in C.
391 <P>
392 <H4> string primary </H4>
393 Note that you may use '@' to extract a substring from a
394 string.
395 <P>
396 <H4> string variable </H4>
397 A variable that has been declared with a "string"
398 declaration.
399 <P>
400 <H4> undeclared variable </H4>
401 A variable that has not been declared, but has been defined
402 only by its use.
403 <P>
404 <H4> while statement </H4>
405 Like the C while statement except that the scope of the
406 while statement must be contained within braces. The braces
407 are mandatory.
408 <P>
409 <H4> word </H4>
410 One or more "words" can be concatenated using the '#'
411 operator to create a "string". The command identifer in a
412 DOS command line is determine by evaluating such a string.
413 The "formula" used for the default values in screens is also
414 a sequence of one or more "words", joined by '#', with the
415 difference that the actual evaluation of the string is
416 deferred until the screen is displayed, and then is
417 recalculated after each field is entered.
418 <P>
419 Note that "subscripts" are allowed.
420 <P>
421 <H4> ws </H4>
422 ws (white space) consists of blanks, tabs and nested C-style
423 comments.
424 </P>
425
426 <BR>
427
428 <IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------"
429 WIDTH=1010 HEIGHT=2 >
430 <P>
431 <IMG ALIGN="right" SRC="../images/pslrb6d.gif" ALT="Parsifal Software"
432 WIDTH=181 HEIGHT=25>
433 <BR CLEAR="right">
434 <P>
435 Back to <A HREF="../index.html">Index</A>
436 <P>
437 <ADDRESS><FONT SIZE="-1">
438 AnaGram parser generator - examples<BR>
439 DOS Script Language <BR>
440 Copyright &copy; 1993-1999, Parsifal Software. <BR>
441 All Rights Reserved.<BR>
442 </FONT></ADDRESS>
443
444 </BODY>
445 </HTML>