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

<!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 &copy; 1993-1999, Parsifal Software. <BR>
                  All Rights Reserved.<BR>
</FONT></ADDRESS>

</BODY>
</HTML>
author	David A. Holland
date	Mon, 13 Jun 2022 00:06:39 -0400
parents	13d2b8934445
children