Remove --prelude, reform and document --output-formats.

HISTORY.md

@@ -4,6 +4,8 @@ History of SixtyPical
 0.16
 ----
 
+*   Removed `--prelude` in favour of specifying both format and prelude
+    with a single option, `--output-format`.  Documentation for same.
 *   `or a, z`, `and a, z`, and `eor a, z` compile to zero-page operations
     if the address of z < 256.
 *   More thorough tests and justifications written for the case of

README.md

@@ -67,6 +67,7 @@ Documentation
 *   [Literate test suite for SixtyPical compilation](tests/SixtyPical%20Compilation.md)
 *   [Literate test suite for SixtyPical fallthru optimization](tests/SixtyPical%20Fallthru.md)
 *   [6502 Opcodes used/not used in SixtyPical](doc/6502%20Opcodes.md)
+*   [Output formats supported by `sixtypical`](doc/Output%20Formats.md)
 
 TODO
 ----

bin/sixtypical

@@ -81,36 +81,36 @@ def process_input_files(filenames, options):
 
     fh = sys.stdout
 
-    if options.origin.startswith('0x'):
-        start_addr = int(options.origin, 16)
-    else:
-        start_addr = int(options.origin, 10)
-
-    output_format = options.output_format
-
-    prelude = []
-    if options.prelude == 'c64':
-        output_format = 'prg'
+    if options.output_format == 'raw':
+        start_addr = 0x0000
+        prelude = []
+    elif options.output_format == 'prg':
+        start_addr = 0xc000
+        prelude = []
+    elif options.output_format == 'c64-basic-prg':
         start_addr = 0x0801
         prelude = [0x10, 0x08, 0xc9, 0x07, 0x9e, 0x32,
                    0x30, 0x36, 0x31, 0x00, 0x00, 0x00]
-    elif options.prelude == 'vic20':
-        output_format = 'prg'
+    elif options.output_format == 'vic20-basic-prg':
         start_addr = 0x1001
         prelude = [0x0b, 0x10, 0xc9, 0x07, 0x9e, 0x34,
                    0x31, 0x30, 0x39, 0x00, 0x00, 0x00]
-    elif options.prelude == 'atari2600':
-        output_format = 'crtbb'
+    elif options.output_format == 'atari2600-cart':
         start_addr = 0xf000
         prelude = [0x78, 0xd8, 0xa2, 0xff, 0x9a, 0xa9,
-                    0x00,0x95, 0x00, 0xca, 0xd0, 0xfb]
+                   0x00, 0x95, 0x00, 0xca, 0xd0, 0xfb]
+    else:
+        raise NotImplementedError("Unknown output format: {}".format(options.output_format))
 
-    elif options.prelude:
-        raise NotImplementedError("Unknown prelude: {}".format(options.prelude))
+    if options.origin is not None:
+        if options.origin.startswith('0x'):
+            start_addr = int(options.origin, 16)
+        else:
+            start_addr = int(options.origin, 10)
 
     # If we are outputting a .PRG, we output the load address first.
     # We don't use the Emitter for this b/c not part of addr space.
-    if output_format == 'prg':
+    if options.output_format in ('prg', 'c64-basic-prg', 'vic20-basic-prg'):
         fh.write(Word(start_addr).serialize(0))
 
     emitter = Emitter(start_addr)
@@ -121,7 +121,7 @@ def process_input_files(filenames, options):
 
     # If we are outputting a cartridge with boot and BRK address
     # at the end, pad to ROM size minus 4 bytes, and emit addresses.
-    if output_format == 'crtbb':
+    if options.output_format == 'atari2600-cart':
         emitter.pad_to_size(4096 - 4)
         emitter.emit(Word(start_addr))
         emitter.emit(Word(start_addr))
@@ -141,21 +141,15 @@ if __name__ == '__main__':
     )
 
     argparser.add_argument(
-        "--origin", type=str, default='0xc000',
+        "--origin", type=str, default=None,
         help="Location in memory where the `main` routine will be "
-        "located. Default: 0xc000."
+        "located. Default: depends on output format."
     )
     argparser.add_argument(
-        "--output-format", type=str, default='prg',
-        help="Executable format to produce. Options are: prg, crtbb. "
-             "Default: prg."
-    )
-    argparser.add_argument(
-        "--prelude", type=str,
-        help="Insert a snippet of code before the compiled program so that "
-             "it can be booted automatically on a particular platform. "
-             "Also sets the origin and format. "
-             "Options are: c64, vic20, atari2600."
+        "--output-format", type=str, default='raw',
+        help="Executable format to produce; also sets a default origin. "
+             "Options are: raw, prg, c64-basic-prg, vic20-basic-prg, atari2600-cart."
+             "Default: raw."
     )
 
     argparser.add_argument(

doc/Output Formats.md

@@ -0,0 +1,67 @@
+Output Formats
+==============
+
+`sixtypical` can generate an output file in a number of formats.
+
+### `raw`
+
+The file contains only the emitted bytes of the compiled SixtyPical
+program.
+
+The default origin is $0000; it is not unlikely you will want to
+override this.
+
+Note that the origin is not stored in the output file in this format;
+that information must be recorded separately.
+
+### `prg`
+
+The first two bytes of the file contain the origin address in
+little-endian format.  The remainder of the file is the emitted bytes
+of the compiled SixtyPical program, starting at that origin.
+
+The default origin is $C000; it is likely you will want to
+override this.
+
+This format coincides with Commodore's PRG format for disk files,
+thus its name.
+
+### `c64-basic-prg`
+
+The first few bytes of the file contain a short Commodore 2.0 BASIC
+program.  Directly after this is the emitted bytes of the compiled
+SixtyPical program.  The BASIC program contains a `SYS` to that code.
+
+The default origin is $0801; it is unlikely that you will want to
+override this.
+
+This format allows the PRG file to be loaded and run on a Commodore 64
+with
+
+    LOAD"FOO.PRG",8:RUN
+
+### `vic20-basic-prg`
+
+Exactly like `--c64-basic-prg` except intended for the Commodore VIC-20.
+
+The default origin is $1001; it is unlikely that you will want to
+override this.
+
+This format allows the PRG file to be loaded and run on a VIC-20 with
+
+    LOAD"FOO.PRG",8:RUN
+
+### `atari2600-cart`
+
+The file starts with a short machine-language prelude which is intended
+to initialize an Atari 2600 system, followed by the emitted bytes of the
+compiled SixtyPical program.
+
+The file is padded to 4096 bytes in length.  The padding is mostly
+zeroes, except for the final 4 bytes of the file, which consist of
+two addresses in little-endian format; both are the origin address.
+
+The default origin is $F000; it is unlikely you will want to
+override this.
+
+This is the format used by Atari 2600 cartridges.

tests/SixtyPical Compilation.md

@@ -7,7 +7,7 @@ SixtyPical to 6502 machine code.
 [Falderal]:     http://catseye.tc/node/Falderal
 
     -> Functionality "Compile SixtyPical program" is implemented by
-    -> shell command "bin/sixtypical --prelude=c64 --traceback %(test-body-file) >/tmp/foo && tests/appliances/bin/dcc6502-adapter </tmp/foo"
+    -> shell command "bin/sixtypical --output-format=c64-basic-prg --traceback %(test-body-file) >/tmp/foo && tests/appliances/bin/dcc6502-adapter </tmp/foo"
 
     -> Tests for functionality "Compile SixtyPical program"
 

tests/SixtyPical Fallthru.md

@@ -65,7 +65,7 @@ to pass these tests to be considered an implementation of SixtyPical.
     -> shell command "bin/sixtypical --optimize-fallthru --dump-fallthru-info --analyze-only --traceback %(test-body-file)"
 
     -> Functionality "Compile SixtyPical program with fallthru optimization" is implemented by
-    -> shell command "bin/sixtypical --prelude=c64 --optimize-fallthru --traceback %(test-body-file) >/tmp/foo && tests/appliances/bin/dcc6502-adapter </tmp/foo"
+    -> shell command "bin/sixtypical --output-format=c64-basic-prg --optimize-fallthru --traceback %(test-body-file) >/tmp/foo && tests/appliances/bin/dcc6502-adapter </tmp/foo"
 
     -> Tests for functionality "Dump fallthru info for SixtyPical program"
 

tests/appliances/bin/dcc6502-adapter

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-# script that allows the binary output of sixtypical --prelude=c64 --compile to be
+# script that allows the binary output of sixtypical --output-format=c64-basic-prg --compile to be
 # disassembled by https://github.com/tcarmelveilleux/dcc6502
 
 import sys