Mercurial > ~dholland > hg > ag > index.cgi
diff doc/misc/html/examples/dsl.html @ 0:13d2b8934445
Import AnaGram (near-)release tree into Mercurial.
| author | David A. Holland |
|---|---|
| date | Sat, 22 Dec 2007 17:52:45 -0500 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/misc/html/examples/dsl.html Sat Dec 22 17:52:45 2007 -0500 @@ -0,0 +1,445 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> +<TITLE>DOS Script Language</TITLE> +</HEAD> + + +<BODY BGCOLOR="#ffffff" BACKGROUND="tilbl6h.gif" + TEXT="#000000" LINK="#0033CC" + VLINK="#CC0033" ALINK="#CC0099"> + +<P> +<IMG ALIGN="right" SRC="../images/agrsl6c.gif" ALT="AnaGram" + WIDTH=124 HEIGHT=30 > +<BR CLEAR="all"> +Back to <A HREF="../index.html">Index</A> +<P> +<IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> + +<H1>DOS Script Language </H1> + +<IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> +<H2>Introduction</H2> +<P> + DSL is a script language, written in AnaGram, which provides + powerful extensions to the batch processing facilities + available with DOS batch files. +<P> + DSL was built in large part by combining components from + other grammars. Although the grammar for DOS command lines + and for screen displays was written explicitly for DSL, just + about everything else was borrowed from other grammars. +<P> + DSL has been tested using Borland C++, V4.52, and Watcom C++, + V10.6. #ifdef statements have been used where necessary to + support both compilers. V10.6 can be used to produce either + 16 or 32 bit executables. If you use Watcom, be sure to + specify a stack size of at least 16K bytes. +<P> + DSL cannot be used with Microsoft Visual C++, since MSVC V1.5 + does not support templates and V4.x and subsequent releases do + not support DOS. +<P> +<!-- not yet true + DSL has been arranged so it will compile under Unix, but it + will not run in any useful fashion. +--> +<P> + DSL was written as part of the AnaGram 1.x installer; it is + now obsolete but retains certain features of interest. +<P> + + <H2> Features of DSL </H2> +<UL> +<LI> DOS command line interpreter with substitutable + parameters, redirection and pipelines. </LI> +<LI> Screen builder for interactive parameter specification. </LI> +<LI> String and integer variables, expressions and comparisons </LI> +<LI> DOS for statement. </LI> +<LI> Nested if and while statements. </LI> +</UL> +<P> + +<H2> Screen Description </H2> + The screen description syntax allows you to specify the + size, location, and colors of windows plus two kinds of data + entry fields: data fields and buttons. +<P> + A data field description consists of a prompt, an + explanation, a variable name for the data, and a default + value expression. The expression is evaluated for the + default value of the data whenever the screen is refreshed. + This means it can be modified as data entry is proceeding, + based on fresh information. +<P> + A button description consists of a prompt, an explanation, + and an action field. The action field consists of any + sequence of DOS commands enclosed in brackets. Each command + should be on a new line. +<P> + + +<H2> Variables and Constants </H2> + DSL has three types of variables: undeclared, integer, and + string variables. +<P> + Undeclared variables may be used in DOS commands and screen + descriptions. They may appear on the left side of assignment + statements. The names of undeclared variables are simple + "literals", that is, sequences of characters drawn from the + set "text char". If an undeclared variable does not have a + value assigned to it, either by an assignment statement or + by its use in a screen, it will be taken literally. +<P> + Integer and string variables must be declared. They may be + used in expressions and comparisons. In particular they may + be used in if statements and while statements. +<P> + DSL supports 32 bit integer arithmetic using essentially the + expression logic in C with a slight modification for string + comparison. Integer constants may be decimal, octal, + hexadecimal or character constants, using the C conventions. +<P> + Beside simple "literals", DSL supports "string literals" + which follow the rules for string literals in C, and + parenthesized literals. Parenthesized literals are enclosed + in parentheses and may contain any characters whatsoever, + the only restriction being that any nested parentheses must + balance. When a parenthesized literal is evaluated, the outer + parentheses are stripped. +<P> + + +<H2> Theory of Operation </H2> + DSL is a purely interpretive program. In some circumstances, + statements and commands are executed as they are scanned. In + other cases, where execution is to be delayed or is + conditional, they are simply passed over on first scan and + then copied. DSL then calls itself recursively to execute + the copy when it is appropriate. +<P> + Note that if the parser you build from <tt>dsl.syn</tt> is called + without any arguments, it looks for a script with the same + name as the executable. Thus, to make an install program + that picks up the install script without any arguments, you + simply rename <tt>dsl.exe</tt> to <tt>install.exe</tt>. Then + when you run it + without any arguments it will run the <tt>install.dsl</tt> script. +<P> + DSL makes extensive use of a number of simple data + structures defined in the <tt>oldclasslib</tt> directory of + the AnaGram distribution. The most important + of these are the string accumulators, the string + dictionaries, and the stacks. +<P> +<P> + The remainder of this document provides a brief overview of + the principal data structures used by DSL and the most + important nonterminal tokens in the DSL grammar. +<P> + +<H2> Stacks </H2> + <H4>as</H4> + This is a stack of pointers to actions which have been + identified in the parse. An action is a block of commands + enclosed in braces {}. The action pointer records a + pointer to the beginning of the action, as well as the line + and column number where the action begins. The use of a stack + allows nested actions. + + <H4>is</H4> + This is a stack of integers. Its only use is for recording + string concatenation sequences, where the integers stacked + are the string dictionary indices of the items to be + concatenated. + + <H4>ps</H4> + This stack accumulates pointers to the parameter strings for + a call to a DOS function. +<P> + +<H2> Symbol Table </H2> + Three data structures are used to gather and maintain + symbol table information. The first is a string accumulator, + sa, which is used for temporary storage for all strings that + are recognized by the parser. The string dictionary, sd, is + used to identify strings. The array st contains specific + information about strings indexed in sd. +<P> + +<H2> Nonterminal Tokens </H2> + <H4> action text </H4> + "action text" is any sequence of commands enclosed in + balanced braces. action text may be used in most contexts + where a string value is expected. In these situations, the + enclosed commands are executed, the content of stdout is + captured as a string, and is returned as the value of the + action text. For example, {DIR} returns a string containing + the file directory for the current directory. +<P> + <H4> action text head </H4> + "action text head" is simply action text up to the + terminating right brace. +<P> + <H4> assignment </H4> + Normally, an identifier on the left, an expression on the + right, the kind of expression depending on the identifier. + Note that using the '@' operator you can modify characters + inside a string. +<P> + <H4> built_in name </H4> + Note that there are a number of arithmetic functions built + into DSL. +<P> + <H4> button line </H4> + A button line is a line on a screen display that controls + the further execution of the script. The description of the + button line requires a label, an explanation, and an action + to be performed when the button is selected. +<P> + <H4> character constant </H4> + Follows the same rules as in C. +<P> + <H4> command </H4> + This is the syntax for a DOS command line, allowing + redirected input and output and piped commands. +<P> + <H4> command sequence </H4> + A command sequence is any sequence of statements and + if statements that ends with a statement. +<P> + <H4> comment </H4> + This is an ordinary C-style comment. +<P> + <H4> comment head </H4> + The beginning of a comment. Normally everything but the + terminating <CODE> */ </CODE>. If a nested comment is found, the rule + "comment head, comment" should reduce to "comment head" if it + is desired that comments nest. If this rule reduces to + "comment", the terminating <CODE> */ </CODE> of the nested comment will + serve to terminate the outer level comment as well, and + comments will not nest. See the discussion in + AnaGram\SBB.DOC or in Appendix D, <A href="sbb-doc.html">Syntactic Building + Blocks</A>, in the AnaGram User's Guide. +<P> + <H4> conditional exp </H4> + This is the standard C expression logic modified as follows: + Integer arithmetic only; string comparison allowed; no + auto-increment or auto-decrement operators. +<P> + <H4> declaration </H4> + Three kinds of declarations: actions can be used like DOS + commands. The definition lists substitutable arguments which + can be supplied at execution time. +<P> + Variables which are declared to be strings or ints must + satisfy the usual naming conventions of program variables in + order to avoid confusion in the expression logic. + +<P> + <H4> eol </H4> + eol is a newline character, optionally preceded by a C++ + style comment beginning with //. eol is not included in "ws" + because it is used as a statement terminator. +<P> + <H4> execution block </H4> + A sequence of DOS commands enclosed within braces. The + difference between an execution block and "action text" is + that the commands in an execution block are performed as + they are encountered, while "action text" is saved up for + later execution. +<P> + <H4> for statement </H4> + Modeled on the for statement in the DOS batch language + rather than on the for statement in C. +<P> + <H4> formula </H4> + A sequence of "words", joined by concatenation operators + ('#'). When the formula is evaluated, the words are + identified in the string dictionary, and their values are + concatenated. If a word has no entry in the dictionary its + literal value is used. Formulas are used in the + specification of the fields in a query line. +<P> + <H4> identifier </H4> + A DOS command +<P> + <H4> if condition </H4> + The keyword if and a conditional expression within + parentheses. +<P> + <H4> if sequence </H4> + An if sequence is any direct sequence of statements and if + statements that ends with an if statement. The difference + between an "if sequence" and a "command sequence" is that an + else clause may follow the "if sequence". +<P> + <H4> if statement </H4> + An "if condition" followed by "action text". Note that a + simple statement is not allowed. +<P> + <H4> integer constant </H4> + Follows the same rules as an integer constant in C, allowing + decimal, octal and hex constants. +<P> + <H4> integer variable </H4> + An variable that has been declared with an "int" statement. +<P> + <H4> literal </H4> + A "literal" is any sequence of characters that does not + include white space; parentheses, brackets, or braces; + quotation marks or newline characters; redirection or pipe + operators, or '#' or '='. Essentially, a "literal" is + anything that would make sense on a DOS command line. +<P> + <H4> literals </H4> + A sequence of instances of "literal" separated by white + space. This sequence is used only in the definition of a + named action. The first literal is the name of the action. + Subsequent literals are the local names of the substituble + parameters. +<P> + <H4> name </H4> + Used for int and string variables. The conventional rules + for variable names in programming language are used. +<P> + <H4> parameter string </H4> + parameter string is essentially the same as "string", except + that any of the concatenated strings may be action text, + that is the result of executing a DOS command and capturing + stdout. +<P> + <H4> parameter word </H4> + parameter word is essentially the same as "word", except + that it may also be action text, that is, the result of + executing a DOS command and capturing stdout. +<P> + <H4> parameters </H4> + The parameters for a DOS command +<P> + <H4> paren string </H4> + A parenthesized string is any sequence of characters within + parentheses, with the only restriction that any nested + parentheses must balance. When evaluated, the outer set of + parentheses is stripped. Parenthesized strings are for use + in DOS command lines in those situations where the + restrictions on "literal" are excessively onerous. +<P> + <H4> piped command </H4> + A "piped command", here, is any DOS command, for which + stdout must be captured and redirected. +<P> + <H4> primary exp </H4> + These are the basic elements of expressions. Note that you + may use the '@' operator to extract a character from a + string. You need not use parentheses on the right if you use + a simple index variable or integer constant. If you wish to + use a more complex expression, you must use parentheses. +<P> + <H4> query line </H4> + This is the description of a line on a screen into which the + user is invited to enter some data. The description requires + four elements: the variable into which the data is to be + stored, the default value for the data, a prompt which + identifies the data, and an explanation field which provides + a fuller explanation of the data required. +<P> + After data has been entered for a particular query line, all + elements of other query lines are reevaluated in case their + defaults have been defined in terms of the data entered. +<P> + <H4> screen description </H4> + A sequence of screen items enclosed in braces. A screen + description is executed as it is read. If you wish to + describe a screen for later use, incorporate it in an + "action declaration". +<P> + A screen description requires a number of "screen items". + These items consist of the title, the color specifications, + the size and location of the window, and a number of query + lines and button lines. +<P> + The layout of the screen is done automatically. +<P> + + <H4> script file </H4> + This is the grammar token. It describes the entire script + file. +<P> + <H4> statement </H4> + Statements include DOS commands plus declarations, + assignment statements, control statements and screen + descriptions. Note the repetition of the while statement. + This stratagem allows a very simple implementation of + looping logic. +<P> + <H4> string </H4> + "string" is a concatenation of "word"s, using the + concatenation operator, '#'. +<P> + <H4> string exp </H4> + Syntactically the same as "string", except that the + primitive elements are different. +<P> + <H4> string literal </H4> + Follows exactly the same rules as string literals in C. +<P> + <H4> string primary </H4> + Note that you may use '@' to extract a substring from a + string. +<P> + <H4> string variable </H4> + A variable that has been declared with a "string" + declaration. +<P> + <H4> undeclared variable </H4> + A variable that has not been declared, but has been defined + only by its use. +<P> + <H4> while statement </H4> + Like the C while statement except that the scope of the + while statement must be contained within braces. The braces + are mandatory. +<P> + <H4> word </H4> + One or more "words" can be concatenated using the '#' + operator to create a "string". The command identifer in a + DOS command line is determine by evaluating such a string. + The "formula" used for the default values in screens is also + a sequence of one or more "words", joined by '#', with the + difference that the actual evaluation of the string is + deferred until the screen is displayed, and then is + recalculated after each field is entered. +<P> + Note that "subscripts" are allowed. +<P> + <H4> ws </H4> + ws (white space) consists of blanks, tabs and nested C-style + comments. +</P> + +<BR> + +<IMG ALIGN="bottom" SRC="../images/rbline6j.gif" ALT="----------------------" + WIDTH=1010 HEIGHT=2 > +<P> +<IMG ALIGN="right" SRC="../images/pslrb6d.gif" ALT="Parsifal Software" + WIDTH=181 HEIGHT=25> +<BR CLEAR="right"> +<P> +Back to <A HREF="../index.html">Index</A> +<P> +<ADDRESS><FONT SIZE="-1"> + AnaGram parser generator - examples<BR> + DOS Script Language <BR> + Copyright © 1993-1999, Parsifal Software. <BR> + All Rights Reserved.<BR> +</FONT></ADDRESS> + +</BODY> +</HTML>