
                ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
                ▓                                ▓█
                ▓  RPP - Redcode Preprocessor    ▓█
                ▓  --------------------------    ▓█
                ▓  V1.12 (c) 1990 Stefan Strack  ▓█
                ▓       ss9557@albnyvms.bitnet   ▓█
                ▓       ss9557@leah.albany.edu   ▓█
                ▓       stst@cs.albany.edu       ▓█
                ▓                                ▓█
                ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓█
                 ██████████████████████████████████

RPP.EXE is Public Domain and part of my CoreWar Plus release. I disclaim all
warranties and liabilities of any sort. Comments to the above addresses are
welcome.

--------------------
INTRODUCTION

RPP is a language preprocessor that makes writing Redcode programs for
CoreWar easy. Programming in Redcode with its PC-relative addressing mode can
be cumbersome and prone to errors. RPP, however, can translate absolute
addressing by instruction labels and EQU symbol definitions into PC-relative 
references. The *.RED files produced by RPP can be run by CORE, the CoreWar
integrated environment (see CORE.HLP), or with any other implementation that 
follows A.K.Dewdney's original specifications of the game. For example, you 
can program DWARF as:

rem This file has to be preprocessed
          equ Bomb #0
Start:    ; This is where we start
          mov Bomb @Target
          add #5 Target
          jmp Start
Target:   dat 1

RPP will produce the following output file:

     ; THIS IS WHERE WE START
     MOV #0 @3
     ADD #5 2
     JMP -2
     DAT 1

The first version is both easier to write and understand. This is especially
obvious for large and complex programs (compare e.g. RELAY.RPP to RELAY.RED).

--------------------
OPERATION

The Redcode Preprocessor (RPP.EXE) is invoked by typing RPP at the DOS prompt
or from the MARS main menu in CORE.EXE. RPP will prompt for an input file;
<Return> will let you pick a file from a *.RPP directory listing. The
Preprocessor will suggest a default output file by appending .RED to the
input file name.  RPP will process address labels and constant definitions
(EQU) in the input file to produce a *.RED file readable by CORE.EXE.

--------------------
EQUates

The EQU (Equate) statement defines a name for a list of symbols used in the 
following code. RPP will replace every occurence of the first argument of EQU 
in the code with what follows after the first argument. EQU is similar to the 
#define preprocessor directive in C. The list of symbols to be substituted 
may contain other EQUated names. E.g.:

        equ numberlines (last first - 1 +)

This statement defines the name 'numberlines' as the following
expression in reverse-polish notation (see RPN Expressions). This expression
calculates the number of lines in a program assuming that the first and last
line carry the labels 'first' and 'last', respectively.

        equ bomb mov #bombconts ^target
        equ bombconts 0
        equ bombincr 5
        equ bombstart (target start - 1 +)

These EQUates expand the code

start:  bomb
        add #bomincr target
        jmp start
target: dat bombstart

into

        MOV #0 ^3
        ADD #5 2
        JMP -2
        DAT 4

EQUates can appear at any place in the source and are effective until
overridden by the next EQUate linking the same name to a new symbol list.

--------------------
LABELS

RPP labels are used to refer to addresses directly, rather than relative to
the program counter as in standard Redcode. Labels can be numerals, character
strings or any combination of digits and characters excluding:
     @ $ # < > ^ / \ , ;

Every label must end with a colon, but the colon is ommitted when the label
is referenced by an instruction. Labels can be on a separate line or on the
same line with an instruction. You can have more than one label per 
instruction. E.g.:

LAST_INSTR:ENDLESS: JMP ENDLESS

is the same as

ENDLESS:
         JMP ENDLESS    LAST_INSTR:

--------------------
RPN EXPRESSIONS

A parenthesized list of symbols that are separated by spaces, tabs or commata
is evaluated as a mathematical expression in reverse-polish notation (RPN).
The symbol list may, after EQU-substitution and label-referencing, contain
integers and the operators + - * / %, where / denotes integer division and %
is the modulo operator. The RPN calculator substitutes an expression with the
integer value it evaluates to. E.g.

        (3,1,+)                         =>   3 + 1
        (spacing spacing 10 % -)        =>   spacing - (spacing mod 10)

--------------------
REMARKS

RPP will pass standard Redcode semi-colon (;) comments unmodified; so they
will appear in the resulting *.RED file. RPP also allows a special REM
comment that will be filtered out. REM must be a separate word and can be on
its own line or following an instruction. REM, like ;, comments out until the
end of the line.

--------------------
NOP

NOP (No-Operation) is a pseudo instruction that can be used to reference a
label outside the actual program code. Consider for example an instruction
that writes to the address immediately before the beginning of the program:

        mov #0 @addr ; first instruction of program
        mov #12 -2   ; second instruction writes before first
        :

If you wanted to use a label instead of "-2" you could code the awkward:

        jmp start
before: dat 0
start:  mov #0 @addr
        mov #12 before
        :

which results in a longer and slower Redcode program. Alternatively, you can
use NOP as a temporary instruction that is only used for label reference
calculations and will not appear in the final *.RED file:

before: nop
        mov #0 @addr
        mov #12 before
        :

You can add any number of labeled or unlabeled NOP instructions before or
after the program body, but not within the program, since this would mess up
all internal label references.

--------------------
ERROR MESSAGES

When processing a program, the following error messages may occur:

Error: self-referential EQU X
        The EQUate name X occurs in the symbol list to be substituted. RPP
        does not catch circular references (EQUates that refer to each
        other).

Error: ambiguous label X
        The same label X marks several instructions.

RPN calculator error: cannot evaluate X
        The RPN calculator has encountered the unknown symbol X in an
        expression.

RPN calculator error: empty stack
        Usually means that too many operators follow too few integers. Every
        operator pops two integers off the stack and pushes the result back
        onto the stack.

--------------------
MISCELLANEOUS

* RPP is not case-sensitive.
* OPcodes and arguments may be separated by spaces, tabs or commata.
* RPP does not check for correct Redcode syntax (this is left to the CoreWar
  interpreter).
* Labels and symbols may be prefaced with addressing-mode characters
  ( # $ @ < > ^ \ /).
* EQUates have precendence over labels, i.e. all EQUates are substituted
  before label references are calculated. It is hence possible to EQUate
  labels.
* RPN expressions are evaluated after all EQUates have been substituted and
  all labels have been referenced.
