--optimize-fallthru and --dump-fallthru-info options.

HISTORY.md

@@ -10,8 +10,9 @@ History of SixtyPical
 *   Accessing zero-page with `ld` and `st` generates zero-page opcodes.
 *   A `byte` or `word` table can be initialized with a list of constants.
 *   Branching and repeating on the `n` flag is now supported.
-*   The `--dump-fallthru-map` option outputs a map, in JSON format, of
-    which routines can be "fallen through" to by other routines.
+*   The `--optimize-fallthru` option causes the program to be analyzed
+    for fallthru optimizations; `--dump-fallthru-info` option outputs the
+    information from this analysis phase, in JSON format, to stdout.
 *   Specifying multiple SixtyPical source files will produce a single
     compiled result from their combination.
 *   Rudimentary support for Atari 2600 prelude in a 4K cartridge image,

bin/sixtypical

@@ -58,15 +58,16 @@ def process_input_files(filenames, options):
     analyzer = Analyzer(debug=options.debug)
     analyzer.analyze_program(program)
 
-    if options.dump_fallthru_map:
-        import json
+    if options.optimize_fallthru:
         from sixtypical.fallthru import FallthruAnalyzer
 
         fa = FallthruAnalyzer(debug=options.debug)
         fa.analyze_program(program)
 
-        sys.stdout.write(json.dumps(fa.fallthru_map, indent=4, sort_keys=True))
-        sys.stdout.write("\n")
+        if options.dump_fallthru_info:
+            import json
+            sys.stdout.write(json.dumps(fa.fallthru_map, indent=4, sort_keys=True))
+            sys.stdout.write("\n")
 
     if options.analyze_only:
         return
@@ -156,14 +157,15 @@ if __name__ == '__main__':
         help="Only parse and analyze the program; do not compile it."
     )
     argparser.add_argument(
-        "--dump-fallthru-map",
+        "--optimize-fallthru",
         action="store_true",
-        help="Dump the fallthru map to stdout after analyzing the program."
+        help="Reorder the routines in the program to maximize the number of tail calls "
+             "that can be removed by having execution 'fall through' to the next routine."
     )
     argparser.add_argument(
-        "--dump-fallthru-ordering",
+        "--dump-fallthru-info",
         action="store_true",
-        help="Dump the fallthru ordering to stdout after analyzing the program."
+        help="Dump the fallthru map and ordering to stdout after analyzing the program."
     )
     argparser.add_argument(
         "--parse-only",

tests/SixtyPical Fallthru.md

@@ -51,10 +51,10 @@ When times comes to generate code, generate it in the order given by L.
 
 [Falderal]:     http://catseye.tc/node/Falderal
 
-    -> Functionality "Dump fallthru map of SixtyPical program" is implemented by
-    -> shell command "bin/sixtypical --analyze-only --dump-fallthru-map --traceback %(test-body-file)"
+    -> Functionality "Dump fallthru info for SixtyPical program" is implemented by
+    -> shell command "bin/sixtypical --optimize-fallthru --dump-fallthru-info --analyze-only --traceback %(test-body-file)"
 
-    -> Tests for functionality "Dump fallthru map of SixtyPical program"
+    -> Tests for functionality "Dump fallthru info for SixtyPical program"
 
 A single routine, obviously, falls through to nothing and has nothing fall
 through to it.