INIT & MUDDLE'S INIT PACKAGE 

File: INIT	Node: Top	Next: Built-in	Up: (DIR)

    INIT is a new DDT INIT program which is much faster and
considerably more versatile than the old :INIT (now :OINIT).
    Basically, INIT will allow the user to print any text,
ask any true/false type question, and perform any of a wide
range of commands (including most useful file hacking commands).
In addition, the control structure of INIT allows for the use
of nested AND, OR, and PROG-type operations, using the various
commands as predicates.

* Menu: Table of Contents

* Order: Order
	All existing Commands and Special Characters

* Built-in Functions: PRE
	Predefined Functions for Mail-reading, file saving, etc.

* Commands: CMDS
	Format of INIT commands

* Nested Structures: NEST
	INIT's control structures and "expression format"

* Questions: QUE
	How INIT asks (and you answer) questions

* File names: FNMS
	How INIT handles File name defaulting

* Q-registers: QREGS
	Setting and reading variables

* Again and Return: AGNRET
	Non-local transfer of control

* Function Creation and Calling: FCNS
	Defining and calling your own functions

* Odds and Ends: ODDS

* MUDDLE's INIT Package: MUDINIT
	Writing and editing INIT programs in MUDDLE


File: INIT	Node: PRE	Next: CMDS	Up: Top

I. Built-in Functions

    As will become clear from reading the remainder of this
document, it is possible in INIT to define 'functions' which
perform specified operations (mostly on files).
    However, there are a few built in functions which may be
called by users which do some of the more commonly performed
rituals.  Functions in INIT are called with the APPLY command,
which is [@<name> <arg> <arg> .....], where name is a single
character function name (names other than A-Z are illegal).
Arguments to these functions (where applicable) must be strings
surrounded by double quotes.
    The following functions exist 'preloaded' into INIT:

  a. M -- simple mail command
	If a mail file exists, INIT will ask whether or not to
	print it.  If the answer is yes (Y or y), INIT will
	print the file and rename the MAIL file to <xuname> OMAIL.
	No arguments
  b. T -- teco safety file
	If a file named _<xuname> > exists, print
	'You have a TECO safety file.'
  	No arguments
  c. S -- hairy mail command (with Saving of files)
	If a mail fle exists, INIT will ask whether or not to
	print it.  If the answer is yes, INIT will print the
	file and ask whether or not to save it.  If the answer
	is yes, it will rename the mail file.  If no, it will append
	the mail file to VANISH;<xuname> OMAIL and delete the mail file.
	Two arguments (both optional)
	1. File where mail exists (default to <xuname>;<xuname> MAIL)
	2. File that mail should be renamed to (default to <xuname>;OMAIL >)

    Other preloaded functions may appear in the future.

File: INIT	Node: CMDS	Next: NEST	Previous: PRE	Up: TOP

II. Commands

    All INIT commands are single characters which are mnemonic
for the actions performed. 
    Some commands (e.g. O(utput) and Q(uestion)) take an optional
prefix (;) which alters the meaning of the command.
    Arguments to commands take one of the following formats:
	Type		Description
	"FILE"		File name within double quotes
	"FILE1,FILE2"	Two file names separated by a comma
	"STRING"	A character string within double quotes
	<name>		A single character
    With a few exceptions, all commands 'return' a value,
which is usually either 'true' or 'false'.  These values may
be used in conditional statements, as described below.
    A table of commands and arguments is Appendix I.

File: INIT	Node: NEST	Next: QUE	Previous: CMDS	Up: TOP

III. Nested Structures

    Nesting is accomplished by the use of square-brackets
delimiting sets of commands.
    The following structures (with descriptions) are allowed:
Command	Operation
[&	AND	Executes arguments until logical AND of results
		is 'false'.
[\	OR	Executes arguments until the logical OR of
		results is 'true'.
[?	COND	Executes the first argument (PROG) in which
		the first expression within that argument
		evaluates to 'true'.
[	PROG	Executes the arguments in turn
(	BIND	Executes arguments like PROG but cannot be AGAIN/RETURNed to
[*	REPEAT	Executes the arguments in turn, restarting
		from the beginning when finished.
[#	NOT	Logical NOT of the argument.

    The following three are included for completeness although
they are described more completely below.

[:	DEFINE	Define a function
[@	APPLY	Apply a function
[!	MAP	MAP down structures

Examples:
 a.   ... [& E"_SAFE_ MARC" O"You have a TECO safety file."] ...
       will print the message if the file _SAFE_ MARC exists.

 b.   ... [\ E"BETTER BEHERE" O"Important file is missing"] ...
       will print the message if the file BETTER BEHERE does not exist.

 c.   ... [\ E"FOO BAR" [O"Foo Bar is missing" L ...]] ...
       will do everything in the PROG if FOO BAR does not exist

 d.   ... [& Q"Print mail? " P"MARC MAIL"] ...
       will print MARC MAIL if the answer to the question is yes.

File: INIT	Node: QUE	Next: FNMS	Previous: NEST	Up: TOP

IV. Questions

    The facility exists in INIT for questions to be asked and
the answer used as the "value" of that command.  The default
acceptable answers are Y (y) and N (n).  Any other character
will cause INIT to repeatedly ask the same question until you
comply.  Using the % command, this default can be changed to
<space> and <rubout>.

File: INIT	Node: FNMS	Next: QREGS	Previous: QUE	Up: TOP

V. File Names

    INIT keeps its own file name defaults and updates them
with whatever is read from file name arguments.  The only
exception to this is that commands which take two file names
only set the default from the first one.
    The initial default is DSK:<XUNAME>;<XUNAME> MAIL.
    When nesting is done, the file name defaults are saved
and restored upon return to that level.
Examples:	
 a.    ... P"FOO BAR" ....
    	will set the defaults to FOO BAR, so that
	   .... W"" ...
	will print the creation date of FOO BAR.

 b.    ... [& E"FOO BAR" C",FOO COPY" W""]
	will initially set the defaults to FOO BAR and never reset
 	them (since the second file name doesn't set defaults).

 c.    ... [& E"FOO BAR" [& E"MUMBLE BAR" P""] P""]
	 will set the default to FOO BAR, push the defaults and reset
	 them to MUMBLE bar, and restore them when the second AND
	 returns.  Thus, the second P"" will print FOO BAR.

    Two special characters may be used within file name 
arguments.  These are:
    ^X (control-X) -- get the XUNAME
    ^U (control-U) -- get the UNAME
    Thus a file argument of "^X;^X MAIL" gets translated into
<XUNAME>;<XUNAME> MAIL.

File: INIT	Node: QREGS	Next: AGNRET	Previous: FNMS	Up: TOP

VI. Q-Registers

    The user may SET (:) and READ (=) the values of the
various Q-registers, which are labelled from A to Z.  In the
case of the SET operation, the Q-register will be set to the
value of the last executed command which returns a value.
The SET operation does not itself return a value.  The READ
operation will either return 'true' or 'false' depending
on the specification from the SET command.
Examples:
 a.    ... E"FOO BAR" :A ...
	SET A to the value of the EXIST command.
 b.    ... [? [=A .....] [+ .....]] ...
	do a COND using the READ value of A.

File: INIT	Node: AGNRET	Next: FCNS	Previous: QREGS	Up: TOP

VII. Again and Return

    The commands AGAIN (@<) and RETURN (@>) are commands which
allow one to restart or return from PROGs and REPEATs.  The AGAIN
command will cause processing to restart at the beginning of the
nearest PROG or REPEAT.  The RETURN command will cause evaluation
of the nearest PROG or REPEAT to stop.  Note that the only exit
from a REPEAT is with a RETURN.  Additionally, MAPFs can be RETURNed
from.  This is like MAPLEAVE in MUDDLE.

Example:
    ... .X [& D"FOO >" @X] ...
   	and
    ... [* [\ D"FOO >" @>]] ...
  are equivalent statements which delete all FOO >'s.

File: INIT	Node: FCNS	Next: ODDS	Previous: AGNRET	Up: TOP

VIII. Function Creation/Function Calls/MAPing

    The facility exists for the creation of 'function's which
can be applied to arguments (which are strings).
    The following commands perform these actions:

 a. [:  -- DEFINE
    The DEFINE command must be followed by the name of a Q-register
    which will be the name of the function.
    The rest of the structure to matching square brackets may be
    any group of legal INIT commands.

        Symbolic arguments are supplied numbers from 1-9 (i.e. the
    first-ninth arguments) and are used as arguments in the form
    !N (excl-N) where N is the number of the argument.
	With the exceptions of + and - (True and False), all arguments
    must be strings.  Arguments which are + and - must obviously
    be passed to something which can understand them.  I'm not sure,
    but I think the set is limited to the AND, OR, COND, ... type
    of construction.
        Optional arguments may be defaulted through the use of
    ;!N<argument> (semi-excl-N-argument).  In this case, <argument>
    will be used if the Nth argument is not given.

    Examples:
	[:A [? ([&E!1 ;O!2]) (+ ;O;!3"Zork!")]]
      defines a function, 'A', which takes (at least) two
      arguments.  If the first exists, it prints its second argument.
      Otherwise, it prints its third argument (which is optional, 
      defaulting to "Zork!").

  	[:A [? (;!1- O"Winnage") (O"Lossage")]]
      defines a function of any number of arguments.  If none are
      given, the ;!1- will default to false.  This is one use of
      passing a + or - as an argument.

 b. [@ -- APPLY
    The APPLY command must be followed by the name of a 'function'
    followed by the arguments to be applied to that function.
    Example: 
	[@A "FOO BAR" "FOO BAR EXISTS" "FOO BAR IS MISSING"]
      uses the function defined in the example above and calls it
      with three strings.  Extra arguments are ignored.  Attempts
      to reference arguments not supplied (unless optional and
      defaulted) is an ERROR.

  c. [! -- MAP
    The MAP command takes a structure (PROG/REPEAT/AND/OR, etc.) which
    may contain any number of commands to be executed and any number
    of additional arguments which must be BIND(LIST)s of string arguments.
    The MAPper will go down these latter BINDs in parallel supplying
    arguments to the BIND which was the first argument (MAP function).
    When any of the argument BINDs is empty, the MAP returns.
    MAPs can be RETURNed from with RETURN.

File: INIT	Node: ODDS	Previous: FCNS	Up: TOP

IX. Odds and Ends

    1. Spaces at top level within a AND/OR/PROG are ignored.
    2. Syntax errors are reported if possible.  More likely
	INIT will barf obscenely.
    3. Other error checking is fairly primitive and may
	improve in the future.

File: INIT	Node: ORDER	Up: TOP

Appendix I.

    The following commands have been implemented.  In the
following table, FILE (and FILE1 and FILE2) should be file
names (e.g. "MARC;FOO BAR") and where two file names are
required, they should be separated by a comma.  STRING
refers to any text surrounded by quotes.
    The returns column indicates what kind of values the
command may return (note that some commands always succeed).

Command	Description		Argument		Returns

 A	Append			"FILE1,FILE2"		T/F
 C	Copy			"FILE1,FILE2"		T/F
 D	Delete			"FILE"			T/F
 E	Exist			"FILE"			T/F
 F	File defaults		"FILE"			T
 G	Is console program?	"STRING"		T/F
;G	Is console program not?	"STRING"		T/F
 I	IMAGE to TTY		"FILE"			T/F
 J	Jump to new line (^PA)	<none>			T
 L	Line to TTY (i.e. CRLF)	<none>			T
 M	Make file (no dump bit)	"FILE"			T/F
 N	Name to TTY		"FILE"			T/F
 O	Output to TTY		"STRING"		T
;O	Output on new line	"STRING"		T
 P	Print file to TTY	"FILE"			T/F
;P	Print in paged mode	"FILE"			T/F
 Q	Question		"STRING"		T/F
;Q	Question on new line	"STRING"		T/F
 R	Rename			"FILE1,FILE2"		T/F
 S	SSVMOD			"STRING"		T
 T	TPL			"FILE"			T/F
 U	User name to TTY	<none>			T
 V	Valret			"STRING"		T
 W	When created		"FILE"			T/F

 +	NOOP			<none>			T
 -	NOOP			<none>			F

:	SET Q-register		<name>			<none>
=	READ Q-register		<name>			T/F

@<	AGAIN			<none>			<none>
@>	RETURN			<none>			<none>

!	Symbolic Argument	<number>		<string argument>

**Special Notes**

a. The ;P command prints a file in paged mode (a la :PR).  In
   this mode, INIT will --MORE-- after every control-L and
   control-underbar.  This mode is somewhat useful for printing
   mail files.
b. The ;O and ;Q commands do a ^PA first before printing the
   string/question.  This puts the question at the beginning
   of the line.
c. The V command has included an implicit control-W at the
   start and a :VP at the end (control-V + alt-P).  The 
   control-W can be defeated with a control-V at the start of
   the valret string.
d. The G command expects as argument the name of an IMLAC console
   program, ("SSV", "SST", "SSV37", "SST20", or whatever.  It evals
   to T if that is the program currently loaded into your IMLAC.
   ;G is T if your console program is NOT the one given.  Both are
   FALSE if your console is not an IMLAC.

**Special Characters**

(	BIND (= LIST)
[	PROG
[*	REPEAT
[?	COND
[&	AND
[\ 	OR
[#	NOT
[!	MAP
[@	APPLY
[:	DEFINE
] 	END (AND/OR/NOT/COND/REPEAT/PROG/MAP)
)	END (BIND)

^Q	Quote the next character
	**NOTE** All square brackets in strings must be quoted!
%	Use space/rubout instead of Y/N for questions

File: INIT	Node: MUDINIT	Up: TOP	Next: LOAD

MUDDLE's INIT package.

    The INIT package contains two basic programs which manhandle
DDT INIT files.  With these functions and EDIT, one can create
his calls to INIT without actually writing the sometimes obscene
JCL by hand.

* Menu:	How to load, edit and dump .DDT. (INIT) files in MUDDLE

* Loading INITs and MUDDLE translated INIT format: LOAD
	What your invocation of INIT looks like in MUDDLE

* Dumping your INIT: DUMP

* Difference between INIT forms and real MUDDLE: DIFFS


File: INIT	Node: LOAD	Next: DUMP	Previous: MUDINIT	Up: MUDINIT

I. <INIT-LOAD "OPTIONAL" <file name>>

    INIT-LOAD reads the file specified (or <SNAME>;.DDT. (INIT))
and attempts to find a call to INIT.  If it succeeds, it parses
the JCL into MUDDLE readable format.  Otherwise, it returns #FALSE ().
    The MUDDLE INIT format is similar to MUDDLE format in the use
of AND, OR, and NOT.  PROGs and RETURNs differ in that they do not
take an binding list.

    Other commands are given as calls to "functions" which start
with the letter of the INIT command followed by the argument
(if necessary).  
Example:
     The INIT JCL -  [&E"MARC MAIL" P"MARC MAIL" L [\ E"FOO BAR" O"BLETCH"]]
      is parsed to
     <AND <EXISTS "MARC MAIL">
	  <PRINT "MARC MAIL">
	  <LINE>
	  <OR <EXISTS "FOO BAR">
	      <OUTPUT "BLETCH">>>
    
    Any ATOM starting with the letter which is the name of the
command will work when editing INIT-LOAD FORMs.  For example, the
above example might as well be,
     
     <AND <EXCH "MARC MAIL">
	  <PRESTO-CHANGO "MARC MAIL">
	  <LOSE-LOSE>
	  <OR <EXCOMMUNICATE "FOO BAR">
	      <OMPHALOSKEPSIS "BLETCH">>>

    INIT-LOAD returns either #FALSE () if no call to INIT occurs
in the INIT file, or a FORM (as above).  This form becomes the
LVAL of the atom INIT (in ROOT).
    The form may be edited as necessary to create the proper init file.

File: INIT	Node: DUMP	Next: DIFFS	Previous: LOAD	Up: MUDINIT

II. <INIT-DUMP "OPTIONAL" <form> <file name>>

    The form defaults to .INIT and the file name defaults to
<SNAME>;.DDT. (INIT).
    INIT-DUMP takes any form and attempts to "unparse" it into
a INIT JCL format.
    If successful, it reconstructs the INIT file using this
"unparsed" JCL.

File: INIT	Node: DIFFS	Previous: DUMP	Up: MUDINIT

Differences between INIT FORMs and MUDDLE structures

a. PROG, REPEAT, and DEFINE do not take argument lists
b. MAPF does not take a final loop function and may be RETURNed from.
c. Symbolic arguments are specified <ARG <n>> where n is 1-9.
d. APPLY takes an ATOM (Q-register) instead of a function

**NOTE**
    
    INIT-DUMP must!!! follow an INIT-LOAD!!!
    It will not suffice to create a random form and try to INIT-DUMP
it.  This is tantamount to taking the back cover off your INIT package.
    If necessary, put a dummy :INIT in your INIT file first!
