create a new magic-comment command that mutates a previous entry

this allows the length of a metadata entry to be adjusted after it's created, which simplifies the implementation of instructions that might vary in length

Force-Push: yes
Change-Id: I0889dc8b5a4f19adbb1f8ec0d5733a0310457766

1 files changed, 60 insertions, 4 deletions

diff --git a/transform.e b/transform.e
index dd417a3..0e38d90 100644
--- a/transform.e
+++ b/transform.e
@@ -2790,6 +2790,24 @@ allocate-transformation-state s" transformation-state" variable
     0 pack64 drop
   } { drop drop drop drop } if-else ;
 
+~ (length adjustment --)
+: adjust-latest-hex-output-metadata-entry-length
+  transformation-state transformation-state-output-metadata @
+  hex-output-metadata-first-entry
+  dup @ {
+    { dup hex-output-metadata-next-entry @ }
+    { hex-output-metadata-next-entry } while
+
+    hex-output-metadata-entry-data-length dup @ 3roll + swap !
+  } {
+    drop
+
+    ~   If we get here, that's a problem. Emit an error message to make sure
+    ~ it's easy to diagnose.
+    ." No pre-existing metadata entry to adjust." newline
+    crash
+  } if-else ;
+
 ~   This is the followup to zero-hex-output-metadata, above. Once we do have
 ~ the label-loop buffer, we need to create some default entries. This is
 ~ called in the first label-loop iteration by hex-allocate-replacement, and
@@ -2962,18 +2980,28 @@ allocate-transformation-state s" transformation-state" variable
   transformation-state transformation-state-output-metadata @
   hex-output-metadata-indentation-depth ! ;
 
+~   Metadata entries are post-processed before they're output, in order to
+~ make the structure of the output code simpler. The post-processing won't
+~ happen until output actually occurs, which is important for operations that
+~ modify entries in-place.
+~
+~   Any time output is performed, all existing entries are post-processed.
+~ Therefore, the post-processing is required to be idempotent, and is.
 : postprocess-metadata-entries
   transformation-state transformation-state-output-metadata @
   hex-output-metadata-first-entry
   { dup @ } {
     ~ (entry pointer)
 
+    ~ Is the entry a suffix comment with a non-zero data length?
     dup hex-output-metadata-entry-type @
     hex-output-metadata-entry-type-suffix-comment =
     over hex-output-metadata-entry-data-length @ 0 != && {
       ~ (entry pointer)
       dup dup
 
+      ~   Find all the remaining entries, and the final terminator, and slide
+      ~ them forward by the length of one entry.
       { dup @ } { hex-output-metadata-next-entry } while 8 +
       ~ (entry pointer, entry pointer, entry array end pointer)
       swap -
@@ -2984,11 +3012,16 @@ allocate-transformation-state s" transformation-state" variable
       memmove
       ~ (entry pointer)
 
+      ~   Now we have the original entry at the original location, and a copy
+      ~ of it at the next location. We modify the original one in-place to
+      ~ turn it into a fresh-line entry...
       dup hex-output-metadata-entry-type
       hex-output-metadata-entry-type-fresh-line swap !
 
       dup hex-output-metadata-entry-data-length 0 swap !
 
+      ~   ... then we modify the next entry in-place to set its location to
+      ~ the end of the data instead of the beginning, and its length to zero.
       dup hex-output-metadata-next-entry
       ~ (entry pointer, next entry pointer)
 
@@ -2996,6 +3029,11 @@ allocate-transformation-state s" transformation-state" variable
       over hex-output-metadata-entry-data-start @ +
       over hex-output-metadata-entry-data-start !
       hex-output-metadata-entry-data-length 0 swap !
+
+      ~   This rule won't fire again on the fresh-line entry because it's of a
+      ~ different type, and it won't fire on the modified suffix-comment entry
+      ~ because its data length is zero. There's no other rules either, so our
+      ~ idempotence requirement is satisfied.
     } if
 
     hex-output-metadata-next-entry
@@ -3790,6 +3828,15 @@ allocate-transformation-state s" transformation-state" variable
   swap
   ~ (data start, string pointer)
 
+  ~   If the output wouldn't go in the label-loop buffer, don't do any of
+  ~ this.
+  ~
+  ~   That may seem spurious, but remember, the same assembly instructions
+  ~ are used for compiling the final binary and defining words within the
+  ~ compiler. In particular, "variable" will hit this, and there are surely
+  ~ others.
+  over is-in-label-loop-buffer not { drop drop exit } if
+
   ~   Copy the first space-separated word of the comment body into scratch
   ~ space to see if it's a special instruction. To minimize interference with
   ~ the program under transformation, we use the outer log's scratch space
@@ -3815,41 +3862,50 @@ allocate-transformation-state s" transformation-state" variable
   } if-else
   ~ (data start, data length, adjusted string pointer)
 
-  ~   The first word wasn't special, so proceed to look for whole-line special
-  ~ instructions.
+  ~   Now look for instruction keywords. These keywords are expected to be the
+  ~ entire line, except that a length field can come before them.
+  dup s" adjust-length" stringcmp 0 = {
+    ~ Modify the most recent entry by adjusting its length.
+    drop swap drop adjust-latest-hex-output-metadata-entry-length
+    exit
+  } if
 
   dup s" fresh-line" stringcmp 0 = {
+    ~ Create a new fresh-line entry.
     drop hex-output-metadata-entry-type-fresh-line 0
     add-hex-output-metadata-entry
     exit
   } if
 
   dup s" blank-line" stringcmp 0 = {
+    ~ Create a new blank-line entry.
     drop hex-output-metadata-entry-type-blank-line 0
     add-hex-output-metadata-entry
     exit
   } if
 
   dup s" indent" stringcmp 0 = {
+    ~ Create a new indent entry with a positive indentation delta.
     drop hex-output-metadata-entry-type-indent 2
     add-hex-output-metadata-entry
     exit
   } if
 
   dup s" deindent" stringcmp 0 = {
+    ~ Create a new indent entry with a negative indentation delta.
     drop hex-output-metadata-entry-type-indent -2
     add-hex-output-metadata-entry
     exit
   } if
 
-  ~ If a nonzero length is specified, treat it as a suffix comment.
+  ~ If it has a nonzero length, create a new suffix-comment entry.
   over 0 != {
     hex-output-metadata-entry-type-suffix-comment swap
     add-hex-output-metadata-entry
     exit
   } if
 
-  ~ It's just an ordinary line comment.
+  ~ Create a new line-comment entry.
   hex-output-metadata-entry-type-line-comment swap
   add-hex-output-metadata-entry ;