GNU/POSIX style command line, huge code cleanup

1 files changed, 363 insertions, 4 deletions

diff --git a/README.md b/README.md
index 4e2edf4..53f6f4e 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,367 @@
-nesasm
+nesasm CE v3.0 - a 6502 assembler with specific NES support
 ======
 
-nesasm 2.51, from MagicKit, with some modifications by Bob Rost (see readme-original.txt)
+Just another modification of nesasm. Based on modification by Tim Hentenaar which is based on modification by Bob Rost which is based on modification of nesasm 2.51 from MagicKit.
 
-I downloaded this from somewhere and further modified it myself. It's not my assembler of choice, per se,
-but I figured I'd share it just for the hell of it.
+What's new in this modification?
+======
+* Support for much longer filenames and labels
+* Automatic generation of symbol files for FCEUX debugger
+* GNU/POSIX style command line options
+* It's possible to define all output filenames now
+* Code cleanup: all warnings are fixed, PCE code leftovers removed
+
+Usage
+======
+
+Usage: nesasm [OPTION...] <source.asm>
+
+  -f, --symbols[=PREFIX]     Create FCEUX symbol files
+  -l, --listing-level=#      Listing file output level (0-3)
+  -L, --listing-file=<file.lst>   Name of the listing file
+  -m, --macro-expansion      Force macro expansion in listing
+  -o, --output=<file.nes>    Name of the output file
+  -r, --raw                  Prevent adding a ROM header
+  -s, --segment-usage        Show (more) segment usage
+  -?, --help                 Give this help list
+      --usage                Give a short usage message
+
+
+        The assembler accepts only one input file 'infile' that will be
+        assembled  into ROM file (.NES extension) directly useable
+        by an emulator.
+
+        A listing file can also be generated (.LST extension) if the LIST
+        directive is encountered in the input file.
+
+        Here's a description of the different options:
+
+
+        Option  Description
+        ------  -----------
+
+         -o <file.nes>     Set output filename.
+
+         -L <file.lst>     Set list filename.
+
+         -f [prefix]       Enable generation of symbol files for FCEUX debugger
+
+         -s     Show segment usage. If one of those options is specified
+                the assembler will display information on the ROM bank
+                usage. Use '-s' to show basic information and '-ss' to
+                show more detailed information.
+
+         -l #   Control output of the listing file:
+
+                    0 - disable completely the listing file even if the
+                        LIST directive is used in the input file
+                    1 - minimun level; code produced by DB, DW and DEFCHR
+                        will not be dumped
+                    2 - normal level; only code produced by DEFCHR will not
+                        be dumped
+                    3 - maximun level; all the code is dumped in the
+                        listing file
+
+                The default level is level 2.
+
+         -m     Force macros expansion in the listing file, even if the
+                MLIST directive is not seen in the input file.
+
+         -r     Control the header generation. By default the assembler
+                always adds an header to the ROM file; unless '-raw' is
+                specified, in this case no ROM header is generated.
+
+
+    Include path
+    ------------
+
+        By default the assembler looks in the current directory when
+        loading an include file, but when it doesn't find the file it
+        then uses the environment variable 'NES_INCLUDE' to get a list
+        of include paths.
+
+
+    Symbols
+    -------
+
+        Two types of symbol are supported, global symbols and local
+        symbols. Local symbols are preceded by a dot '.' and are valid
+        only between two global symbols. A symbol can be followed by
+        a colon ':' but this is not necessary.
+
+
+    Expressions
+    -----------
+
+        The assembler supports very complex expressions. You can use
+        as many level of parenthesis as you want and spaces between
+        operators and numbers are possible.
+        
+        Numbers can be written in three bases : hexadecimal ($7F), 
+        binary (%0101) and decimal (48). Character values are also 
+        supported ('A').
+
+        All the usual operators are present :
+
+            +, -, *, /, %, ^, &, |, ~, <<, >>
+
+        As well as the comparison operators :
+
+            =, !=, !, <, >, <=, >=
+
+        For the priority, the same rules as C apply.
+
+        You can also use predefined or user-defined functions in
+        an expression.
+
+
+        Predefined functions
+        --------------------
+
+            HIGH()   - Returns the high byte of a value.
+
+            LOW()    - Returns the low byte.
+
+            BANK()   - Returns the bank index of a symbol. If no symbol,
+                       or more than one, are given, the function will 
+                       return an error.
+
+            PAGE()   - Returns the page index of a label. See above for
+                       errors.
+
+            SIZEOF() - Returns the size of a data element.
+
+
+        User-defined functions
+        ----------------------
+
+            User-defined functions are declared with the .FUNC directive,
+            for example:
+
+                SCR_ADDR .func (\1) + ((\2) << 5)
+
+            Up to nine arguments, \1 to \9, can be used.
+                                                    
+            To call a function simply enclose arguments within parenthesis
+            and separate them with a comma:
+
+                stw #SCR_ADDR(10,4)+$2000,<$20
+
+            User-defined functions can be very useful, one often needs to use
+            the same calculation again and again in expressions. Defining a
+            function will save you a lot of work, and reduce typo errors. :)
+
+            Note that function calls can be nested, you can call one function
+            from another without any problem, however, recursive calls will
+            produce an error.
+
+
+    Macros
+    ------
+
+        While functions are very useful to replace common expressions by
+        just a function call, macros are used to replace common groups
+        of instructions by a single line of code. 
+
+        You start a macro definition with:
+
+            label  .macro
+
+        Or you can also place the label after the '.macro' keyword, like
+        this:
+
+                   .macro label 
+
+        After follow the body of the macro, which is terminated by
+        the '.endm' directive.
+
+        As an example let's define a 'neg' macro to negate the accumulator.
+
+            neg    .macro
+                    eor   #$FF
+                    inc   A
+                   .endm
+
+        Macros can also have parameters. In the macro body, you refer to
+        a parameter by using the backslash character ('\') followed by
+        a digit. Nine parameters can be used, \1 to \9.
+
+        Here's another example:
+
+            add    .macro       ; add a value to register A
+                    clc         ; (handle carry flag)
+                    adc   \1+1
+                   .endm
+
+        Other 'special' parameters can be used, here's a list of all
+        the possible parameter you can use inside a macro:
+
+
+        Parameter  Description
+        ---------  -----------
+        \1  -  \9  Input parameter - up to nine can be used in a macro call
+
+        \#         Number of input parameters
+
+        \?1 - \?9  Returns 'type' of input parameter:
+                     ARG_NONE      (= 0) = No argument
+                     ARG_REG       (= 1) = register            -> A, X, Y
+                     ARG_IMMEDIATE (= 2) = Immediate data type -> #xx
+                     ARG_ABSOLUTE  (= 3) = Abosulte addressing -> label, $xxxx
+                     ARG_INDIRECT  (= 4) = Indirect addressing -> [label]
+                     ARG_STRING    (= 5) = String argument     -> "..."
+                     ARG_LABEL     (= 6) = Label argument      -> label
+
+        \@         Special parameter that returns a different number for
+                   each macro; can be used to define local symbols inside
+                   macros:
+
+                       abs    .macro
+                               lda   \1
+                               bpl   .x\@
+                               eor   #$FF
+                               inc   A
+                               sta   \1
+                       .x\@:
+                              .endm
+
+
+    Directives
+    ----------
+
+        LIST    - Enable the listing file generation. You can later stop
+                  temporarily the output with the NOLIST directive and
+                  restart it again with LIST.
+
+        NOLIST  - Stop the listing output.
+
+        MLIST   - Allow macro expansion in the listing file.
+
+        NOMLIST - Stop expanding macros in the listing file. This directive
+                  won't have any effect if you use the '-m' command line
+                  option.
+
+        OPT     - ...
+
+        EQU     - Assign a value to a symbol. The character '=' has
+                  the same function too.
+
+        BANK    - Select a 8KB ROM bank (0-127) and reset the location
+                  counter to the latest known position in this bank.
+
+        ORG     - Set the location of the program counter. The thirteen
+                  lower bits of the address inform the assembler about
+                  the offset in the ROM bank and the third upper bits
+                  represent the page index.
+
+        DB      - Store one or more data bytes at the current location.
+
+        DW      - Store data words.
+
+        BYTE    - Same as DB.
+
+        WORD    - Same as DW.
+
+        DS      - Reserve space at the current location. This space will
+                  be filled with zeroes if this directive is used in the
+                  CODE or DATA group.
+
+        RSSET   - Set the internal counter of the RS directive to 
+                  a specified value.
+
+        RS      - Assign a value to a symbol; a bit like EQU but here
+                  the value assigned is taken from an internal counter,
+                  and after the assignation this counter is increased
+                  by the amount specified in the RS directive.
+                  This is a very handy way of defining structure member
+                  offsets, here's a small example:
+
+                      ; C:
+                      ; --
+                      ; struct {
+                      ;    short p_x;
+                      ;    short p_y;
+                      ;    byte p_color;
+                      ; } pixel;
+                      ;
+                      ; ASM:
+                      ; ----
+
+                              .rsset $0  ; set the initial value of RS counter
+                      P_X     .rs 2
+                      P_Y     .rs 2
+                      P_COLOR .rs 1
+
+                  You can later use these symbols as offsets in a 'pixel'
+                  struct:
+
+                              ldy #P_COLOR
+                              lda [pixel_ptr],Y
+
+        MACRO   - Start a macro definition.
+
+        ENDM    - End a macro definition.
+
+        INCBIN  - Include a binary file at the current location. If the file
+                  is bigger than a ROM bank, as many successive banks as
+                  necessary will be used.
+
+        INCLUDE - Include a source file at the current location.
+                  Up to 7 levels are possible.
+
+        DEFCHR  - Define a character tile (8x8 pixels). The directive takes
+                  8 arguments (stored as 32-bit values of 8 nybbles each),
+                  one argument for each row of pixel data. This directive
+                  takes also care to reorganize the pixel data to the NES
+                  required bit format. Note that only color indexes 0 to 3
+                  can be used, as the NES tiles are only 4-color. An error
+                  will be generated if you try to use more colors.
+
+                      zero:   .defchr  $00111110,\
+                                       $01000011,\
+                                       $01000101,\
+                                       $01001001,\
+                                       $01010001,\
+                                       $01100001,\
+                                       $00111110,\
+                                       $00000000
+
+        ZP      - Select the Zero-Page section ($0000-$00FF).
+
+        BSS     - Select the RAM section ($0200-$07FF).
+
+        CODE    - Select the program code section.
+
+        DATA    - Select the program data section.
+
+                  Note: In ZP and BSS sections you can only allocate storage,
+                  ----  you can *not* store initial values.
+
+        IF      - Conditional assembly directive. This directive will evaluate
+                  the supplied expression and then turn conditional assembly
+                  on or off depending on the result. If the result is null
+                  conditional assembly is turned off, and on if the result is
+                  non null.
+        IFDEF
+        IFNDEF  - These directives allow conditional assembly depending on
+                  whether a label is defined or not.
+
+        ELSE    - Toggle conditional assembly on to off, or vice verca.
+
+        ENDIF   - Terminate the current level of conditional assembly.
+                  Report an error if the number of IF's and ENDIF's doesn't
+                  match.
+
+        FAIL    - When the assembler encounters this directive, it aborts
+                  the compilation. Can be used within a macro for argument
+                  error detection.
+
+        INESPRG - Specifies the number of 16k prg banks.
+
+        INESCHR - Specifies the number of 8k chr banks.
+
+        INESMAP - Specifies the NES mapper used.
+
+        INESMIR - Specifies VRAM mirroring of the banks. Refer to iNES header
+                  document (neshdr20.txt).