CP/M/CPM_CDROM.iso/simtel/cpmug/cpmug004.ark/ACT.DOC

Text File | 1984-04-29 | 16.0 KB | 487 lines

                                                  ACT version 31
                                1                     10/17/77


                Summary of Actor (ACT) functions



I_n_t_r_o_d_u_c_t_i_o_n_

ACT is a macro text interpreter which runs under a CP/M system
with more than 16K bytes of RAM.  ACT uses the same algorithm as
TRAC ("TRAC" is a registered trademark of Rockford Research
Institute) and a set of primitive functions which are similar to
those in the TRIX interpreter.  ACT also uses the special
characters @{|} in place of TRAC's #(,).  ACT has been used to
control jobs on a large time sharing system and to format
diskette files; it is generally too slow for efficient human
interaction.

Logically (but not necessarly psychologically), the syntax is
very simple.  Program and data are character strings which are
handled by the same rules.  There are three structures:

        {...}
       @{op|arg1|arg2|...|argn}
      @@{op|arg1|arg2|...|argn}

The first is a literal quote; the contents are passed on as the
value.  The second performs the indicated operation on the
argument strings and immediately rescannes the resulting value.
The last form performs the operation and passes the value to the
next higher level function.  Any op or argument may have any of
the three forms.  For more information on the scanning algorithm
see any of the published descriptions of TRAC.

There is a version of ACT which uses upper case letters for the
command names and the special characters ^[,]' instead of @{|}`.
Also, the meta-character is the exclaim (!).


R_e_f_e_r_e_n_c_e_s_

1. Moll, H; TRIX - An interactive, interpretive language for
   manipulating strings of characters.  Lawrence Livermore Lab
   report UCID-30100.

2. Moors, C. N.; TRAC, a Procedure describing Language for the
   Reactive Typewriter.  Comm. ACM 9, 3 (March, 1966)

3. Moors, C. N.; TRAC, A Text Handling Language.  Proc. ACM 20th
   Nat. Conf., Cleveland, August, 1965.

4. Wegner, Peter; Programming Languages, Information Structures,
   and Machine Organization.  McGraw-Hill Book Co., 1968.

                                                  ACT version 31
                                2                     10/17/77


                Summary of Actor (ACT) functions



E_x_e_c_u_t_e_ _l_i_n_e_


         act
         act <file-name>
         act <file-name> <options>

If a file name is given, then the ACT macros in the file are read
first; <file-name> has the general form "d:x.y".  The string @in
is initialized to the characters between "act " and the return.

As a special case, <options> may be the three characters ^hh,
where ^ is the caret (or up arrow), and hh is a hex page number.
Free storage is allocated from the end of the interpreter up to,
but not including, page hh or FBASE if ^hh is not given.


N_o_n_-_d_i_s_k_ _I_/_O_ _a_n_d_ _d_e_b_u_g_

@{rs|prompt}  "read string"
   Value is a line of input from the console (via CP/M call #10),
   or the next string from the input file.  Line-feed, return,
   and tab characters from the input file are ignored; a string
   is terminated by the meta-character (~) or by the end-of-file.
   Comments on the input file are enclosed within matching left
   quotes (`).  Input files generally do not end with the
   meta-character.

@{ps|a|a|...}  "print string"
   Each argument (after the "ps") is printed on a separate line;
   but there is no CR-LF after the last argument.

@{so|message}  "send to Octopus"
   The message is sent over the selected Octopus channel.
   Usually the message does not end with an Octopus end-message
   character.  The echo is lost.  (Note:  "Octopus" is the name
   of the LLL time sharing system.  The so and ro functions talk
   to Octopus over a serial interface as an ordinary terminal.
   Separate documentation illustrates how this hardware dependent
   function can be patched for different i/o ports.)

@{ro|x|s|f|eom}  "read Octopus"
   If the Octopus time-out is greater than zero, then a message
   terminator is sent.  This terminator either causes a previous
   "so" message to be delivered or a log-out in case there was no
   previous "so" and the terminator is a control-D.  Octopus
   output is then collected in the string @ro until the string x
   is encountered or until the time-out interval passes since the
   last character.  The value is s if x was found, otherwise f.
   If s and f are omitted, the value is null.  (Note this

                                                  ACT version 31
                                3                     10/17/77


                Summary of Actor (ACT) functions



   inconsistency with the functions gc and in.)  A null x will
   always fail to match.

   A non-null last argument (eom) will change the Octopus message
   terminator.  The argument eom must be the two hex characters
   which correspond to the terminator.  The terminator is
   initially a control-D.

@{io|x|x|...}  "input-output parameters"
   Each argument x is a letter (o,t,m) followed by an associated
   parameter:
         oa   selects Octopus channel a. (initial value)
         ob   selects Octopus channel b.
         tn   sets the Octopus time-out to n seconds.  E.g. t120.
         mc   redefines the meta-character to be the character c.
         p    print: terminal output is thru CP/M, "fw" applies.
         d    display: direct output, "fw" does not apply.
              Note: this option is hardware dependent.

@{fw|n}  "form width"
   The "print string" function will start a new line after n
   characters.  The initial form width is 80.  However, this does
   not apply if an @{io|p} is in effect.

@{tn}  "trace on"
   Turn the trace mode on and save the previous mode.  Note:  An
   @{io|d} is implicitly given so that the output will wrap
   around; see the fw function above.

@{tf}  "trace off"
   Restore the previous trace mode, up to eight levels.

@{nb}  "number of blocks"
   Value is the number of sixteen word free storage blocks.

@{fs|n|m}  "free storage"
   Free storage is augmented by the memory locations n up to but
   not including m; n and m are decimal and must be multiples of
   16.

@{vn}  "version number"
   Value is the ACT version number.





                                                  ACT version 31
                                4                     10/17/77


                Summary of Actor (ACT) functions



D_i_s_k_ _I_/_O_

@{of|file-name|n|s|f}  "open file"
   The file name has the general form "d:x.y".  If d is omitted,
   the system drive is selected; lower case characters in the
   name are mapped to upper case.  The number of the next record
   to read or write is set to n.  (Records are numbered
   sequentially starting at zero; each record consists of 128
   characters.)  If the open fails the value is f; otherwise the
   value is s.

   Since only one file can be open at a time, the record number
   of the crrrent file may need to be saved by @{rn}.  Also, a
   currently opened output file must be closed before another
   open.

@{mf|file-name|s|f}  "make file"
   If the named file can be created, the value is s; otherwise
   the value is f.  The current record number is set to zero.

@{cf|s|f}  "close file"
   The currently opened file is closed.  The value is f if there
   is a close error, otherwise s.

@{df}  "destroy file"
   The current file is destroyed.

@{rn}  "record number"
   The value is the record number of the next record to read or
   write.  This number applies to the currently opened file.

@{wf|string-name|x|s|f}  "write file"
   Characters from the named string, starting with the first, are
   written to the currently opened file.  If x is null, then the
   last partial record is not written; instead, the form pointer
   of the named string is left positioned at the remainder.  For
   example, the output for the next write could be constructed by
   @{ns|name|@@{in|name}<more output>}.

   If x is non-null, then the first character of x is used to pad
   out the remainder of the record and the record is written.  An
   entire record of pad characters is written if the previous
   output ended on a record boundary.

   The value is f if there is a write error, otherwise s.

@{rf|string-name|m|s|f}  "read file"
   The next m records are read from the currently opened file and
   appended to the named string.  The value is f if the physical
   end of file is reached, otherwise s.


                                                  ACT version 31
                                5                     10/17/77


                Summary of Actor (ACT) functions



@{rd}  "read dialect"
   The value is the text from the currently open file.  The file
   is read starting with the record set by the open file.  The
   input is processed in the same manner as described for the rs
   function.  Thus, one program can load another in the same way
   as is done when a file name is put on the execute line after
   "act".  Warning:  No of or mf commands can be executed until
   the file has been read.




C_o_n_t_r_o_l_ _a_n_d_ _d_e_l_a_y_

@{eq|a|b|s|b|s|...|b|s} or @{eq|a|b|s|b|s|...|f}  "equal"
   The value is the first s for which the preceeding b is equal
   to a, where "equal" means string equality.  If the last
   argument is not one of a "b-s" pair, then it provides an
   "else" value.

@{ge|n|m|s|f}  "greater than or equal to"
   The value is s if n is numericallly greater than or equal to
   m, otherwise the value is f.

@{nt|name|s|f}  "null test"
   The value is s if the named string is null, otherwise the
   value is f.

@{ex|x}   "exit"
   Clear the active and neutral strings; then set the active
   string to x.

@{st}  "stop"
   Return to CP/M.

@{zz|n}  "sleep"
   Sleep for n/10 seconds.




S_t_r_i_n_g_ _o_p_s_ _a_n_d_ _h_e_x_-_t_o_-_c_h_a_r_a_c_t_e_r_s_

@{ns|name|value|name|value|...}  "name string"
   Create one or more strings with the given values.

@{as|name|x|name|x|...}  "append string"
   Append the string x to the named string.


                                                  ACT version 31
                                6                     10/17/77


                Summary of Actor (ACT) functions



@{ss|name|arg|arg|...}  "segment string"
   Create arguments in the named string.

@{cl|name|arg|arg|...} or @{name|arg|arg|...}  "call"
   Return the named string, starting at the first character, with
   the actual arguments substituted for those corresponding
   substrings which were matched by a previous "segment string".

@{gc|name|n|s|f}  "get characters"  (4 or more arguments)
   Move the form pointer over n characters, or to the end of the
   form if there are fewer than n characters remaining.  The
   characters passed over are put into the string "@gc".  Return
   s if there are n characters after the form pointer in the
   named string, otherwise return f.

@{gc|name|n}  "get characters"  (3 arguments)
   Like gc with 4 or more arguments except that the value of @gc
   is also the value of this function.

@{gc|name}
   Return the total number of characters in the named form.

@{in|name|p|s|f}  "initial"  (4 or more arguments)
   Starting at the form pointer, search for the substring p.  The
   characters which are passed over in the search, up to but not
   including p, are put into the string "@in".  If p is found
   return s, otherwise return f.  The form pointer is left
   positioned after s, or at the end of the form.  Null p always
   fails.

@{in|name|p}  "initial"  (3 arguments)
   Like in with 4 or more arguments except that the value of @in
   is also the value of this function.

@{in|name}  "initial"  (2 arguments)
   Return the characters from the form pointer to the end of the
   form; also set @in to this value.  The form pointer is left
   past the end of the form.

@{cr|name}   "call restore"
   Move the form pointer of the named string to the beginning of
   the string.

@{dd|name|name|...}   "delete definitions"
   Delete the named strings.

@{pk|hex}   "pack"
   Return the characters whose hex values are given.


                                                  ACT version 31
                                7                     10/17/77


                Summary of Actor (ACT) functions



@{uk|x}  "unpack"
   Return the hex form of the string x.




A_r_i_t_h_m_e_t_i_c_

@{ad|n|n|...}   "add"
   Return the sum of the arguments.  Numbers are represented by
   signed decimal integers whose magnitude is less than 32768.

@{su|n|m}   "subtract"
   Return n-m.

@{ml|n|n|...}   "multiply"
   Return the product of the arguments.

@{dv|n|m}   "divide"
   Return n/m.

@{md|n|m}   "mod"
   Return n mod m.




S_p_e_c_i_a_l_ _s_t_r_i_n_g_s_

@cb   "console break"
   The value of this string is the last console break character.

@im   "idle macro"
   This macro is loaded whenever the active string is empty.  The
   initial value of @im is @{ps|@{rs|.}}, but @im may be changed
   at any time.





                                                  ACT version 31
                                8                     10/17/77


                Summary of Actor (ACT) functions



C_o_n_s_o_l_e_ _"_b_r_e_a_k_"_

   The last character of any console imput, other than
   for the @{rs} function, is saved in the string @cb.
   Moreover, if the input character is an ESC, then you
   will be prompted to type one of the letters t, n, or i
   which will turn the trace on (t), turn the trace off (n),
   or reload the idle macro (i).

   Console input will stop output, or cause an immediate
   return from the zz or ro functions.




G_e_n_e_r_a_t_i_n_g_ _a_ _C_O_M_ _f_i_l_e_ _w_i_t_h_ _a_ _p_r_e_l_o_a_d_e_d_ _A_C_T_ _p_r_o_g_r_a_m_

A COM file containing the ACT interpreter and a preloaded macro
file may be created as follows, assuming a 32K system.

1. Append something like the following to your macro file

         @{ns|@im|{
            @{fs|26368|29184}
            @{ns|@im|{@{ps|@{rs|.}}}}
            @{start}
         }}
         @{st}

   where "start" is the name of your top level macro.  Note that
   the fs function adds 6700 hex up to 7200 hex to the free
   storage list after the program is started (step 4).  Free
   storage normally extends to FBASE which is 7200 hex in a 32K
   system.

2. Load your program by typing

         act macro-file ^67

   where "^" is the caret, or up arrow.  Free storage will extend
   up to 6700 hex; if your program needs more space, then you
   need more than 32K to make a COM file.  The st function at the
   end of your file will return control to CP/M.

3. Make a COM file with the SAVE command

         save 103 code.com

4. Run the code by typing either of the following

         code

                                                  ACT version 31
                                9                     10/17/77


                Summary of Actor (ACT) functions



         code options

   The options will be in the string @in.




E_r_r_o_r_ _m_e_s_s_a_g_e_s_

DISK EOF:  The rs function is trying to read beyond the end of
   file.

FREE STORAGE IS EMPTY:  The combined storage required for named
   strings, string names, and active and neutral strings has
   exceeded the allocated memory.  At this point, the active and
   neutral strings are cleared and control given to the @im
   macro.  The second time this happens, control returns to CP/M.

NS STACK OVERFLOW:  The number of unprocessed arguments exceeds
   250.  The level of nesting or the number of arguments is
   excessive.  For example, the number of arguments for a ns
   should not get much over 200.