
Instructions for PPL Version 7(30)

These instructions consist of 5 parts:


PART 1.	List of files you should have received.

PART 2.	Putting your new PPL together.

PART 3.	System requirements for PPL.

    A.	    Teletype mode.
    B.	    Necessary files.

PART 4.	News.

    A.	    New Features.
	1.	Continuation lines, comments, NEWLINE.
	2.	Intra-line editing.
	3.	Reading in the same function twice.
	4.	Writing after purging.
	5.	File Input/Output for Fancy Data Types.
	6.	Displaying a range.
	7.	The PPL Compiler.
	8.	Previously unimplemented functions.
    B.	    Bugs Fixed.
	1.	String comparisons.
	2.	Double power.
	3.	EOF when appropriate.
	4.	Pointing out syntax errors.
	5.	BOOL files.
	6.	Keep typing!
    C.	    Corrections to the PPL User's Manual.
    D.	    Summary of differences between PPL-11 and PPL-10.

PART 5.	Special note on the PPL Compiler.

PART 1.	List of files you should have received.

	DECtape BOUT1:

		comp2.p11	frmtio.p11	numbrs.p11
		other.p11	usrfn.p11

	DECtape BOUT2:

		comp1.p11	gcol.p11	lexbas.p11
		lexaux.p11	modes.p11	parser.p11
		values.p11

	DECtape BOUT3:

		bascio.p11	ched.p11	fileio.p11
		nocomp.p11	subrs.p11	toperr.p11

	DECtape MACSRS:

		errors.m11	fp.m11		gbltbl.m11
		hcbls.m11	idbegin.m11	messag.m11
		nmfns.m11	pplend.m11	pplhd.m11
		sponge.m11	sponge1.m11	sponge2.m11
		srsend.m11	support.m11	sysfun.m11
		table1.m11	table2.m11	trans.m11
		xched.m11	xfileio.m11	xfrmtio.m11
		xlexaux.m11	xmodes.m11	xnocomp.m11
		xparser.m11	xtoperr.m11	xtrans.m11
		xuserfn.m11

	DECtape AUXFIL:

		makeppl		loadppl1	loadppl2
		convert		renumber.ppl	iversonian.ppl
		matrix.ppl	matrix.doc	meter.ppl
		meter.doc	turing.ppl	turing.doc
		dump.ppl	equal.ppl	wumpus.ppl
		ark.ppl		news.ppl	oldnews.ppl

PART 2.	Putting your new PPL together.


	Step 1.	Read ALL the instructions.

	Step 2.	Copy the .p11 files, the .m11 files, makeppl, loadppl1,
		and loadppl2 into one directory.

	Step 3. (Optional) Modify the files idbegin.m11, sysfun.m11,
		and/or table2.m11 to interface better with your system.

	Step 4.	Execute the commandfile makeppl.

		Note: In assembling messag.m11, there will be 1 "error"
		which will print the total number of messages.
		In assembling hcbls.m11, there will be an error in
		assembling the instruction
			mov	sp,-(sp)
		If you get any other errors, there's a problem.

	Step 5.	Copy the produced files (ppl.out, ppl2.out, and ppl.err)
		to the appropriate places.

	Step 6.	On New Year's Eve, be sure to edit the file pplhd.m11
		to tell PPL what year it is, and when Daylight Savings
		Time is in effect.  Otherwise, the DATE function will be
		erroneous.

	Step 7.	Go back to Step 4.

PART 3.	System requirements for PPL.

	A. Teletype mode.

	The PPL you have received will set the 40000 (octal) bit of the
	tty status.

	In Harvard Unix, this allows the following characters to reach PPL:
		<RUBOUT>	Delete the previous character typed (even if the
				previous character was a break character).
		<CONTROL-U>	Delete the entire statement so far typed (even
				if that statement extends over continuation
				lines or past an <ESCAPE>).
		<CONTROL-R>	Retype the prompt given by PPL, then retype the
				user's input (possibly extending over several
				continuation lines).
		<CONTROL-G>	If you are editing a PPL program,
				and PPL has just prompted you with a
				line prompt, then this deletes that line from
				the program, otherwise <CONTROL-G> is
				equivalent to <CONTROL-U>.
		<ESCAPE>	Enter the intra-line editor.

		If your system will not send those as break characters,
		then take the file idbegin.m11 and remove the statement
			harv = 1
		N.B. Setting it to 0 will not help.

		You might then instruct the users to type <ESCAPE>
		followed by <CONTROL-D>, which will send the <ESCAPE>
		character to PPL immediately.  Or, they can type "\"
		<Special-char> <NEWLINE>, for any of the above <Special-char>s.

	B. Necessary files:

	File		Where Defined		What for
			File		Label
	------------	----------------------	------------------------
	/bin/ppl	table2.m11	pgname	When the user types
							erase()
						PPL exec's this file
						to restart PPL.
	/etc/ppl.err	sysfun.m11	errfil	PPL looks up almost all
						error messages here.
	/lib/ppl/news.ppl
			sysfun.m11	libnews	If this file exists, PPL
						will start every user 
						session by mentioning the
						existence and currency of
						this file.
	/lib/ppl/iversonian.ppl
			messag.m11	ivmsg	If anyone ever tries
						to use the iversonian
						function, PPL requests that
						they read in this file.
	/lib/ppl/renumber.ppl
			messag.m11	rnmsg	Similarly, if someone
						tries to use the renumber
						function, they are told
						to read this in.

	In addition, the compiler requires the following files:

	/lib/ppl/ppl2.out
			sysfun.m11	fppl2	The compiler.
	/bin/macro	table2.m11	macnm	The assembler.
	/bin/linker	table2.m11	lnknm	The linker.
	/sys/ppl/srsend.m11
			table2.m11	fsrsend	Assembled with the
						user's functions.
	/sys/ppl/---.obj   table2.m11	f---	The various and sundry
	    (Where --- is each of the 42 .obj's)modules that comprise PPL.

	If you change the location of srsend.m11 or *.obj to a directory
	other than /sys/ppl/, be sure that the pathname is not more than
	one character longer than /sys/ppl/.  Otherwise, the length
	of the argument list for the linker will be too long for Unix
	to handle.  This problem will not long remain (See PART 5).

PART 4. News.

	A. New Features.

	    1. Continuation lines, comments, NEWLINE

		PPL now makes no distinction between <RETURN> and 
		<LINEFEED>.  Old program text files will not work unless
		modified.  A TECO macro is provided, in the file convert,
		that makes the necessary changes:

			To indicate the start of a continuation line,
			one now types:

				% <RETURN>     (with no space in between)

			Comments are no longer continued across continuation
			lines; one must type "..." at the start of each
			continuation line of a comment.

		It is now IMPORTANT to watch out for lines that end in a
		"%", for they will cause an unintentional continuation
		line (with the "%" being ignored) unless some character
		(preferably a printing character) is placed after the "%".

		The variable newline is now a string of 1 character, namely
		a <LINEFEED> (ASCII decimal 10).  That same <LINEFEED>
		character can be typed in (as a character constant or as part
		of a string constant) as the 2-character sequence:

			% <LINEFEED>    (with no space in between)

	    2. Intra-line editing.

		The intra-line editor, also known as the "character editor"
		or "advanced text editor", described in section 4.7 of
		the PPL User's Manual, is now available.  See your manual
		for details, and note the following:

		a. A <CONTROL-C> may be typed to cancel editing.  Then
		you can try again:

			If you were editing a direct statement, type:

				<ESCAPE>    (Must be first character on line)

			If you were editing a function, first re-enter
			automatic sequencing mode by typing:

				$function[2]	... to correct line 2

			(PPL types:)

			   [2]

			And you cleverly retort with:

				<ESCAPE>

			to enjoy further editing.

		b. There are 2 ways to leave the intra-line editor:

		   Typing <NEWLINE> will return the user to exactly where
		   (s)he was before entering the intra-line editor: as though
		   the original line were typed correctly and terminated with
		   <NEWLINE>.  (Exception: the user may have been editing a
		   function, and could have changed the current statement
		   line while in the intra-line editor.)

		   Typing "$" (dollar-sign) will exit the intra-line editor
		   and close the function being edited.  However, if the
		   function contains syntax errors, then these errors are
		   displayed and the function is not closed.  This gives
		   the user a chance to <CONTROL-C> his/her way back to
		   the state of affairs before the function was opened
		   for editing.

		C. The "invisible" character pointer, which is moved about
		   by the FIND command, is now visible.  It prints as
		   the character "^", unless you change the value of the
		   global variable char.pointer to be something else.

	    3. Reading in the same function twice.

		It is now possible to read in the same function from
		two different files.  To allow this, type:
			allow.duplicates
			read("blurfo")
		and PPL will print warning messages:
		  matrix: old data definition unchanged
		  init: superceding old function
		To disallow this feature, type:
			disallow.duplicates

	    4. Writing after purging.

		If you purge a function, you will not be allowed to
		WRITE your programs out to a file.  (This is for your
		own protection.) If you feel you must, type:
			allow.write
		and you are then allowed.  To re-protect yourself, type:
			disallow.write

	    5. File Input/Output for Fancy Data Types.

		It is now possible to open files for input or output in
		data types other than the basic types (INT, REAL, DBL, BOOL,
		and CHAR).  The only restrictions are:
			1. The data type must not have "itself" as a
			   "sub-type".  For example, TUPLE has GENERAL as a
			   sub-type, and GENERAL includes the possibility of
			   a TUPLE, so you can't make a file of TUPLE's.
			2. The data type must not have NONE (the type of NULL)
			   as a sub-type.  For example, you can't open a file
			   for ATOMIC data objects.
		However, any other data type is OK.

		With files of non-basic types, the POSITION function can
		take only 0 as its second argument.

		Outputting a data object to a file does not preserve any
		sharing relationships that might have existed in the object.

	    6. Displaying a range.

		You can display a bunch of lines in a function by typing:
			?f[0:2]
			$f(n)
		   [1]	if n= 0 then return 1
		   [2]	if -(n==int) then "argument must be integral";return

	    7. The PPL Compiler.

		PPL now has a compiler.  It translates your functions into
		machine language, making them faster and giving you more
		room for data objects.  It gives you a machine language
		program called CPPL.  CPPL is just like PPL, except that
		it has your functions compiled in, and it doesn't let
		you define new functions, data definitions, or operators.
		Normally it also excludes file i/o, formatted output,
		transcendental functions, and the intra-line editor.

		The compile function takes 0 or more arguments, which
		must be strings of the form:
			"include=io"	  Include file I/O
			"include=format"  Include formatted output
			"include=trans"	  Include transcendental functions
			"include=ched"	  Include character editor
			"sr=blurfo"	  Names your source file blurfo.m11
			"object=pig"	  Names your object file pig.out
			"map"		  Gives you a core map
		(Note: Only the first two letters are significant.)
		The compiler produces a machine language program
		normally called cppl.out and an environment file called
		cppl.env.  To run your new compiled PPL, type at shell level:
			cppl.out cppl.env
		The compiler is known to have quite a few bugs in it.

	    8. Previously unimplemented functions.

		The PPL User's Manual lists several functions as being
		available only in PPL-10.  With the notable exception of
		the printstr and formatstr functions (and the less notable
		exceptions of background, foreground, getbyte, putbyte,
		and the special functions for the ARDS terminal), all of
		these are now available.  Note the following, though:

		In PPL-10, the execute function can process a string of
		2 or more continuation lines.  In PPL-11, text after a
		<NEWLINE> character is ignored.

		In PPL-10, the identical function returns TRUE for two
		equal atomic values.  In PPL-11, TRUE is returned only if
		they share the same machine location.

		The iversonian and renumber functions are now available as
		library functions, not as built-in functions.

	B. Bugs Fixed.

	    1. String comparisons.

		The <= and => operators now work properly on STRINGs.
		All upper-case letters are considered alphabetically earlier
		than any lower-case letters.

	    2. Double power.

		The ^ operator now works correctly for DBLs.

	    3. EOF when appropriate.

		If you read in from an empty file, you get eof right away.
		You used to be able to do inbyte once before getting eof.
		Also, if you use the position function to get past the end
		of a file, you always get eof.

	    4. Pointing out syntax errors.

		The ^ pointer underneath a syntax error is now positioned
		more nearly correctly, taking into account tabs and
		continuation lines in the faulty statement.  Moreover, if
		the error occured in a statement having continuation lines,
		the ^ is followed by a number indicating on which
		continuation line the error occurred:
			a_b; b_c; d_4  e_3;		%<NEWLINE>
			f_0; g_0
				(PPL retypes:)
			a_b; b_c; d_4  e_3;		%
			f_0; g_0
				       ^1---syntax error

	    5. BOOL files.

		It is now possible to do input from a file of BOOLs.
		Since no one reported it, it is very likely that no one
		ever makes a file of BOOLs anyway, but if anyone tried,
		they noticed that you simply couldn't read them in.

	    6. Keep typing!

		There is now no limit on the length of a PPL statement.

	C. Corrections to the PPL User's Manual.

	Page	Section	Correction
	----	-------	----------
	  3	 1.4	"Louis Lasher" should be spelled "Lew Lasher"
						-- L. L.
	 24	 3.6	The manual does not make it clear that comments
		 3.7	do not extend from one continuation line to the
			next.  It is, in fact, possible to place a comment
			(terminated with % <NEWLINE>) between any 2 lexemes.
			Also, the 500-character limit for a PPL statement
			does not exist in PPL-11.
	 33	 4.7.1	In specifying a range for a "character-editor"
			command, one types [1:5], NEVER [1,5].
	 51	 6.3	The operator-related functions are now available.
	 68	 7.1	Backtrace is now available.
	 68	 7.2	All the environmental inquiry functions are
			available, as is the class function and its
			family.  There is an additional class (and
			predicate) called compiled.fn (guess why?).
	 74	 7.5	Execute is now available, but in PPL-11, text
			after a <NEWLINE> character is ignored.
	 79	 7.9	In line 4, NULL appears instead of NONE.
	 81	 7.10	Additionally, the user can change the prompt used
			in the character editor (edit.prompt) and the
			symbol used to show the current character position
			(char.pointer).
	 81	 7.11	Getchar is now available.
	 93	App. A	Most of the "11" subscripts should be
			removed.
			The exec function always returns a boolean
			value: TRUE if the called program exited
			"normally" (I.E. with exit status 0) and FALSE
			otherwise.
			The functions allow.write, disallow.write,
			allow.duplicates, and disallow.duplicates
			should be included.

	D. Summary of differences between PPL-11 and PPL -10.

	1. PPL-10 has the functions printstr, formatstr, mstring, putbyte,
	   getbyte, sendchar, background, foreground, and the special functions
	   for the ARDS terminal; PPL-11 does not (although it has image.out,
	   which is pretty similar to sendchar).

	2. PPL-10 allows user-defined variadic functions; PPL-11 does not.

	3. PPL-11 has the intra-line editor described in section 4.7 of
	   the PPL User's Manual; PPL-10 has a character-by-character editor
	   (See Appendix H-4 in the manual.)

	4. PPL-11 has a compiler.

	5. In PPL-11, continuation lines are signalled by %<NEWLINE>; in
	   PPL-10, by <LINEFEED>.  Furthermore, in PPL-11, a comment ends
	   at the %<NEWLINE>; in PPL-10, a comment always extends across all
	   continuation lines.

	6. In PPL-11, it is possible to display a range of lines of a function;
	   not in PPL-10.

	7. In PPL-10, statements cannot be longer than 500 characters, in
	   PPL-11 there is "no limit".

	8. In PPL-10, strings can be used in place of data types or functions
	   in the functions make, unary, and binary.

	9. In PPL-10, the function logout logs the user out.  In PPL-11, it
	   simply tells the user how to logout.

       10. PPL-10 allows file I/O in non-standard byte sizes.  PPL-11 does
	   not, but allows I/O in "almost any" data type.

       11. PPL-11 has the functions exec, purge, stacks, image.out,
	   protocol, (dis)allow.write, (dis)allow.duplicates, mstring,
	   abs, tan, and log; PPL-10 does not.

       12. PPL-10 allows REALs or DBLs as arguments to the functions
	   and and or (sic); PPL-11 does not.

       13. The functions read, execute, and identical work slightly
	   differently in the two versions.

       14. If you type
		class(3)
	   PPL-10 will return the null string and PPL-11 will return
	   "variable".  But class(a), where a is a local variable, works
	   properly only in PPL-11.

       15. In PPL-11, the argument to the random function is ignored.

PART 5. Special note on the PPL Compiler.

The PPL compiler was written in 1975-1976 by Alfred Z. Spector.  Although
the compiler has not been thoroughly debugged yet, it is possible to
compile some large programs, with a speed improvement of up to a factor of
4.  Moreover, by removing the user's programs from data space, there is
more room for data objects.  The compiler can also be used to demonstrate
the concept of compilation to beginning students in computer science.

Since PPL is a rather large program, the code to do compilation would not
fit into the available instruction space.  Therefore, the compiler resides
in a seperate version of PPL (called PPL2) which is stripped of certain
modules (e.g. the parser module) which are not needed during compilation.

When a user types
	compile()
PPL invokes the standard UNIX sequence (Fork, Wait, Exec) to call PPL2.
PPL2 produces MACRO-11 code (in a file called cppl.m11), calls the
assembler, and then links together a new version of PPL, including the
newly assembled object module, excluding certain other modules.
PPL2 dies and the waiting PPL (after checking the exit status of the
child process) then Exec's the newly linked cppl.out.  Data is transmitted
from one process to another by PPL environments.  Therefore, the user
must type
	cppl.out cppl.env
to run his/her compiled PPL programs.

Since we are well aware that the compiler has bugs, don't send us news of any.
Later versions of PPL will have compilers that have fewer bugs and produce
better code.  In addition, they will have most of the object modules
"pre-linked", so that there will not be such a wait for linking together cppl.

If you decide to live without the PPL compiler, then you don't need the
following files:

	loadppl2
	comp1.p11	comp2.p11
	sponge.m11	sponge2.m11
	xched.m11	xfileio.m11	xfrmtio.m11
	xlexaux.m11	xmodes.m11	xnocomp.m11
	xparser.m11	xtoperr.m11	xtrans.m11
	xuserfn.m11
