Added INIT -- a helper program for LOGIN, LOGOUT, and other script files.

README.md

@@ -93,6 +93,7 @@ There's a [DDT cheat sheet](doc/DDT.md) for Unix users.
    - HSNAME, displays user's HSNAME.
    - HSNDEV, HSNAME device.
    - IDLE, list idle users.
+   - INIT, a helper program for LOGIN, LOGOUT, and other script files.
    - INLINE, reads line from TTY and adds to JCL (for DDT init files)
    - INQUIR, user account database.
    - INQUPD, processes INQUIR change requests.

build/build.tcl

@@ -715,6 +715,10 @@ respond "*" ":link .info.;its ttyvar,sysdoc;ttyvar >\r"
 respond "*" ":midas sys2;ts inline_sysen1;inline\r"
 expect ":KILL"
 
+# init
+respond "*" ":midas sys3;ts init_sysen2;init\r"
+expect ":KILL"
+
 # ndskdmp tape
 respond "*" ":link kshack;good ram,.;ram ram\r"
 respond "*" ":link kshack;ddt bin,.;@ ddt\r"

doc/info/init.4

@@ -0,0 +1,462 @@
+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!