Date : Sat, 06 Sep 1986 13:42:02-MDT
From : Rick Conn <RCONN@SIMTEL20.ARPA>
Subject: Some info on PPAL
The following is the documentation now being used by PPAL's
(PPAL = Pretty Printer for Assembly Language) beta testers. I don't know
when or how PPAL will be released yet, but PPAL is working fine right now.
I ran it on all of Z3LIB the other day without any problems.
Rick
;%BEGIN 0
;%Program: PPAL
;%Author: Richard Conn
;%Version:
VERS equ 2
;%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
;%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
;
; 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
; Ou - controls the case of opcodes
; OU makes opcodes upper-case
; OL makes opcodes lower-case
; OX leaves the case of opcodes unchanged
;
; 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
; Opcode case (O): Unchanged
; 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
; Opcode case (O): Lower
; 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
; Opcode case (O): Lower
; 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
; Opcode case (O): Upper
; 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 embedded
;comments.
; PPAL file1,file2 LFX LAU
; ;#LFX, LAU
; 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
; mymac macro
; if debug ; this is a test
; call print
; db 'debug macro',0
; else
; call print
; db 'no debug macro',0
; endif
; endm
; loop:
; if debug
; if debug2
; call print; this is only a test
; db 'debug2',0
; else
; call print
; db 'debug',0
; endif
; else
; call print
; db 'not debug',0
; endif
; jp loop
; end
;
; Sample file after processing by PPAL:
;
; ; Sample file to illustrate PPAL
; MYMAC macro
; if debug ;this is a test
; call print
; db 'debug macro',0
; else
; call print
; db 'no debug macro',0
; endif
; endm
; LOOP:
; if debug
; if debug2
; call print ;this is only a test
; db 'debug2',0
; else
; call print
; db 'debug',0
; endif
; else
; call print
; db 'not debug',0
; endif
; jp loop
; end
;
;%END