RCONN@SIMTEL20.ARPA (Rick Conn) (09/06/86)
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 -------