Mercurial > ~dholland > hg > ag > index.cgi
view 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 source
<!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>