RomWBW/Source/Images/d_bp/u15/PPAL.DOC

;%BEGIN 0
;%Program: PPAL
;%Author: Richard Conn
;%Version:
VERS	equ	3
;%Date: 3 Sep 1986
;%Revision History:
;1. 1 Sep 86, Richard Conn
;	Initial beta-test release
;2. 3 Sep 86, Richard Conn
;	Fixed Z3INS compatability problem
;	Created LSy option to control colons after labels of MACRO, SET,
;		and EQU
;	Placed IF/ELSE/ENDIF at same indentation level
;	Change Iy option to IIy option
;	Added IMy option for MACRO/ENDM indentation
;	Added directives I+ and I- for manual increment and decrement of
;		indentation level
;	Fixed input line counting problem
;3. 5 Sep 86, Richard Conn
;	Added Field3 indentation options for EQU and SET (OE and OS)
;	Changed O directive to OC, OE, and OS
;	Added comment in directive processor
;%Invocation: PPAL file_list [directive_list]
;%Index: Pretty Assembler
;%Index: PPAL
;%Index: Pretty Printer
;%Description:
;	PPAL is a Pretty Printer for Assembly Language for the Z System.
;Its purpose is to reformat assembly language source programs in order to
;have all Z System programs conform to a standard structure.  PPAL is highly
;configurable, accepting directives from both the command line and the source
;code itself, so that PPAL may be used to format programs in different ways
;for a variety of standards.
;	Directives for specific configuration of the pretty printing process
;may be presented on the command line or within the body of the code in
;special comment lines, beginning with ";#".  The following directives are
;recognized.  In each general case (like, Au), the first letter indicates the
;directive name, and the following letters indicate types of characters which
;may be specified; specifically:
;		o - option chars specific to the directive
;		u - case indication, U for Upper-case, L for Lower-case,
;			X for unchanged
;		y - yes/no indication, Y for Yes, N for No, X for unchanged
;
;	;text - marks a comment in the directive line
;	Au - controls the case of operands (arguments)
;		AU makes non-quoted alphabetic argument characters upper-case
;		AL makes non-quoted alphabetic argument characters lower-case
;		AX leaves the case of argument characters unchanged
;	By - remove blank lines
;		BY (yes) turns on removal of blank lines
;		BN (no) turns off removal of blank lines
;		BX (unchanged) is the same as BN
;	Cou, Coy - comment line formatting (a comment line is a line beginning
;	    with a semicolon, as opposed to an embedded comment)
;		CWy controls removal of the space character after the
;		    semicolon
;			CWY (yes) removes the space after the semicolon if a
;			          space is present, else no change
;			CWN (no) inserts the space after the semicolon if no
;			         space is present, else no change
;			CWX (unchanged) makes no change
;		CFu controls case of the first character in the comment line
;			CFU makes the first character upper-case
;			CFL make the first character lower-case
;			CFX leaves the case of the first character unchanged
;		CAu controls case of all characters in the comment line
;		    except the first character if CFU or CFL is in effect
;			CAU makes all characters upper-case
;			CAL makes all characters lower-case
;			CAX leaves the case of all characters unchanged
;	Eou, Eoy - embedded comment formatting
;		ECy controls placement of the embedded comment if it begins
;		    after field4 (column 33)
;			ECY (yes) places embedded comments on the next line
;			ECN, ECX (no, unchanged) leaves embedded comments
;				on the same line
;		EWy controls removal of the space character after the
;		    semicolon
;			EWY (yes) removes the space after the semicolon if a
;			          space is present, else no change
;			EWN (no) inserts the space after the semicolon if no
;			         space is present, else no change
;			EWX (unchanged) makes no change
;		EFu controls case of the first character in the comment
;			EFU makes the first character upper-case
;			EFL make the first character lower-case
;			EFX leaves the case of the first character unchanged
;		EAu controls case of all characters in the comment
;		    except the first character if EFU or EFL is in effect
;			EAU makes all characters upper-case
;			EAL makes all characters lower-case
;			EAX leaves the case of all characters unchanged
;	Ioy - indent lines subordinate to IFs or MACROs
;		I+ increases the indentation level by 1 character
;		I- decreases the indentation level by 1 character (0 min)
;		IIy controls indentation for the IF/ELSE/ENDIF pseudo-ops
;			IIY causes all opcodes subordinate to an IF to be
;			     indented one character; each successive IF
;			     causes another indentation; ENDIF brings the
;			     indentation level out; ELSE temporarily brings
;			     the indentation level out for the ELSE pseudo-op
;			     only
;			IIN, IIX (no, unchanged) causes indentation under IFs
;			     to not take place
;		IMy controls indentation for the MACRO/ENDM pseudo-ops
;			IMY causes all opcodes subordinate to a MACRO to be
;			     indented one character; ENDM brings the
;			     indentation level out
;			IMN, IMX (no, unchanged) causes indentation under
;			     MACROs to not take place
;	Lou, Loy - control format of labels
;		LFu controls the case of the first character of a label
;			LFU makes the first character upper-case
;			LFL makes the first character lower-case
;			LFX leaves the case of the first character unchanged
;		LAu controls the case of all characters in a label except
;		    the first character if LFU or LFL is in effect
;			LAU makes all characters upper-case
;			LAL makes all characters lower-case
;			LAX leaves the case of all characters unchanged
;		LCy controls the presence of a colon after a normal label
;			LCY ensures that there is a colon after each label
;			LCN ensures that there is no colon after each label
;			LCX has no effect on a trailing colon; if one was
;			    present in the input, it is present in the output
;		LSy controls the presence of a colon after a special label,
;		    where a "special" label is a label in front of a MACRO,
;		    SET, or EQU pseudo-op
;			LSY ensures that there is a colon after a special label
;			LSN ensures that there is no colon after a spec label
;			LSX has no effect on a trailing colon; if one was
;			    present in the input, it is present in the output
;		LLy controls the presence of a new line following a label
;			LLY places a new line after a label
;			LLN, LLX does not place a new line after a label
;		L8y controls the presence of a new line following a label
;		    which is longer than 8 characters
;			L8Y places a new line after an 8+ character label
;			L8N, L8X does not place a new line after an 8+
;			         character label
;	Oou or Ooy - controls the appearance of opcodes
;		OCu - controls the case of opcodes
;			OCU makes opcodes upper-case
;			OCL makes opcodes lower-case
;			OCX leaves the case of opcodes unchanged
;		OEy - indent EQU opcode to Field 3 (col 17)?
;			OEY indents the EQU opcode to field3 (col 17)
;			OEN, OEX indents the EQU opcode to field2 (col 9)
;		OSy - indent SET opcode to Field 3 (col 17)?
;			OSY indents the SET opcode to field3 (col 17)
;			OSN, OSX indents the SET opcode to field2 (col 9)
;
;	In addition to the above directives, four predefined formats
;are available via the Fn directive, where 0 <= n <= 3.  The predefined
;formats are:
;		F0 - reset all directives to null
;			Remove blank lines (B):			No
;			Comment lines
;				First char (CF):		Unchanged
;				All chars (CA):			Unchanged
;				Remove Space after ; (CW):	Unchanged
;			Embedded comments
;				First char (EF):		Unchanged
;				All chars (EA):			Unchanged
;				Remove Space after ; (EW):	Unchanged
;				Next line if after col 33 (EC):	No
;			Indentation
;				of IFs (II):			No
;				of MACROs (IM):			No
;			Labels
;				First char (LF):		Unchanged
;				All chars (LA):			Unchanged
;				Colon after label (LC):		Unchanged
;				Colon after special label (LS):	Unchanged
;				Line after label (LL):		Unchanged
;				Line after 8+ char label (L8):	Unchanged
;			Opcodes
;				Opcode case (OC):		Unchanged
;				EQU indentation (OE):		Field2
;				SET indentation (OS):		Field2
;			Operand (argument) case (A):		Unchanged
;
;		F1 - Z System standard format
;			Remove blank lines (B):			No
;			Comment lines
;				First char (CF):		Unchanged
;				All chars (CA):			Unchanged
;				Remove Space after ; (CW):	Unchanged
;			Embedded comments
;				First char (EF):		Unchanged
;				All chars (EA):			Unchanged
;				Remove Space after ; (EW):	Yes
;				Next line if after col 33 (EC):	Yes
;			Indentation
;				of IFs (II):			Yes
;				of MACROs (IM):			Yes
;			Labels
;				First char (LF):		Unchanged
;				All chars (LA):			Upper
;				Colon after label (LC):		Yes
;				Colon after special label (LS):	No
;				Line after label (LL):		Yes
;				Line after 8+ char label (L8):	Yes
;			Opcodes
;				Opcode case (OC):		Unchanged
;				EQU indentation (OE):		Field2
;				SET indentation (OS):		Field2
;			Operand (argument) case (A):		Lower
;
;		F2 - special format
;			Remove blank lines (B):			Yes
;			Comment lines
;				First char (CF):		Unchanged
;				All chars (CA):			Unchanged
;				Remove Space after ; (CW):	Yes
;			Embedded comments
;				First char (EF):		Upper
;				All chars (EA):			Lower
;				Remove Space after ; (EW):	Yes
;				Next line if after col 33 (EC):	Yes
;			Indentation
;				of IFs (II):			Yes
;				of MACROs (IM):			Yes
;			Labels
;				First char (LF):		Upper
;				All chars (LA):			Lower
;				Colon after label (LC):		Yes
;				Colon after special label (LS):	No
;				Line after label (LL):		Yes
;				Line after 8+ char label (L8):	Yes
;			Opcodes
;				Opcode case (OC):		Unchanged
;				EQU indentation (OE):		Field2
;				SET idnentation (OS):		Field2
;			Operand (argument) case (A):		Lower
;
;		F3 - special format
;			Remove blank lines (B):			Yes
;			Comment lines
;				First char (CF):		Unchanged
;				All chars (CA):			Unchanged
;				Remove Space after ; (CW):	No
;			Embedded comments
;				First char (EF):		Upper
;				All chars (EA):			Lower
;				Remove Space after ; (EW):	Yes
;				Next line if after col 33 (EC):	Yes
;			Indentation
;				of IFs (II):			Yes
;				of MACROs (IM):			Yes
;			Labels
;				First char (LF):		Unchanged
;				All chars (LA):			Upper
;				Colon after label (LC):		Yes
;				Colon after special label (LS):	No
;				Line after label (LL):		Yes
;				Line after 8+ char label (L8):	Yes
;			Opcodes
;				Opcode case (OC):		Unchanged
;				EQU indentation (OE):		Field2
;				SET indentation (OS):		Field2
;			Operand (argument) case (A):		Upper
;
;	If no directives are given, the format F1 is selected.  F1 is always
;selected as the default format, and directives can be used to vary specific
;settings or all settings within this default.
;
;	Examples of various forms a label may take on:
;		Forms		AbCd	hello	EXEC
;		--------	----	-----	----
;		LFX, LAX	AbCd	hello	EXEC
;		LFU, LAX	AbCd	Hello	EXEC
;		LFL, LAX	abCd	hello	eXEC
;		LFX, LAU	ABCD	HELLO	EXEC
;		LFU, LAU	ABCD	HELLO	EXEC
;		LFL, LAU	aBCD	hELLO	eXEC
;		LFX, LAL	abcd	hello	exec
;		LFU, LAL	Abcd	Hello	Exec
;		LFL, LAL	abcd	hello	exec
;
;	Directives may be placed in any order with any or no delimiters:
;		"LFXLAU"	"LFX LAU"	"LFX,LAU"
;have the same meanings.  This applies to both command lines and comments:
;		PPAL file1,file2 LFX LAU
;		;#LFX, LAU
;	For directive in comments, the directive processing is terminated
;by either an end of line or a comment character:
;		;#LFX, LAU
;		;#LFX, LAU  ; All labels are upper-case
;	Note that allowing directives embedded in the files they are acting
;on allows one part of the file to take on one format and another part of the
;file to take on another format.
;
;Sample file before processing by PPAL:
;
;	; Sample file to illustrate PPAL
;		ext	cout,print
;
;	;#OEY  ; Indent EQUs to Col 17 (Field 3)
;
;	test	equ	1
;	numch	equ	26
;	fch	equ	'A'
;
;	;#OEN  ; Indent EQUs to Col 9 (Field 2)
;
;		mymac	macro
;		call	print
;		if	test
;		db	'This is a test'
;		else
;		db	'This is normal'
;		endif
;		db	'  ',0
;		endm
;
;		mymac
;		ld	b,numch
;		ld	a,fch
;	loop:	call	cout
;		inc	a
;		djnz	loop
;		ret
;		end
;
;Sample file after processing by PPAL:
;
;	; Sample file to illustrate PPAL
;		ext	cout,print
;
;	;#OEY  ; Indent EQUs to Col 17 (Field 3)
;
;	TEST		equ	1
;	NUMCH		equ	26
;	FCH		equ	'A'
;
;	;#OEN  ; Indent EQUs to Col 9 (Field 2)
;
;	MYMAC	macro
;		 call	print
;		 if	test
;		  db	'This is a test'
;		 else
;		  db	'This is normal'
;		 endif
;		 db	'  ',0
;		endm
;
;		mymac
;		ld	b,numch
;		ld	a,fch
;	LOOP:
;		call	cout
;		inc	a
;		djnz	loop
;		ret
;		end
;
;%END