add extended sigil:( to save stack comments, d:describe

FossilOrigin-Name: dc80974119af1d3120f710c6c37be0616d2003233bffe4389ca82f9fe3d611d9

Configuration.mk

@@ -72,6 +72,7 @@ ENABLED += -DENABLE_IOCTL
 DEVICES ?=
 DEVICES += interface/ll.retro
 DEVICES += interface/dedup.retro
+DEVICES += interface/stack-comments.retro
 DEVICES += interface/sources.retro
 DEVICES += interface/devices.retro
 DEVICES += interface/floatingpoint.retro

RELEASE-NOTES

@@ -35,6 +35,9 @@
   - `s:temp` now truncates strings longer than `TempStringMax`
   - `s:filter` now truncates strings longer than `TempStringMax`
   - added new `d:stack` field for storing a stack comment
+  - `sigil:(` extended to store stack comments (with a form of
+    `(:comment)`
+  - add `d:describe`
 
 - library
 

interface/clock.retro

@@ -9,19 +9,19 @@ system clock.
     dup n:negative? [ drop 'Error:_clock_device_not_found s:put nl ] if;
     io:invoke ;
 
-:clock:timestamp  (-n) #0 clock:operation ;
+:clock:timestamp  (:-n) #0 clock:operation ;
-:clock:day        (-n) #1 clock:operation ;
+:clock:day        (:-n) #1 clock:operation ;
-:clock:month      (-n) #2 clock:operation ;
+:clock:month      (:-n) #2 clock:operation ;
-:clock:year       (-n) #3 clock:operation ;
+:clock:year       (:-n) #3 clock:operation ;
-:clock:hour       (-n) #4 clock:operation ;
+:clock:hour       (:-n) #4 clock:operation ;
-:clock:minute     (-n) #5 clock:operation ;
+:clock:minute     (:-n) #5 clock:operation ;
-:clock:second     (-n) #6 clock:operation ;
+:clock:second     (:-n) #6 clock:operation ;
-:clock:utc:day    (-n) #7 clock:operation ;
+:clock:utc:day    (:-n) #7 clock:operation ;
-:clock:utc:month  (-n) #8 clock:operation ;
+:clock:utc:month  (:-n) #8 clock:operation ;
-:clock:utc:year   (-n) #9 clock:operation ;
+:clock:utc:year   (:-n) #9 clock:operation ;
-:clock:utc:hour   (-n) #10 clock:operation ;
+:clock:utc:hour   (:-n) #10 clock:operation ;
-:clock:utc:minute (-n) #11 clock:operation ;
+:clock:utc:minute (:-n) #11 clock:operation ;
-:clock:utc:second (-n) #12 clock:operation ;
+:clock:utc:second (:-n) #12 clock:operation ;
 ~~~
 
 ## d:source

interface/rng.retro

@@ -5,7 +5,7 @@ part of the VM I/O extensions to allow implementors to use the
 best approach on their host system.
 
 ~~~
-:n:random (-n)
+:n:random (:-n)
   DEVICE:RNG io:scan-for
     dup n:negative? [ drop 'Error:_RNG_device_not_found s:put nl ] if;
     io:invoke ;

interface/stack-comments.retro

@@ -0,0 +1,24 @@
+Add stack comments to existing words (from retro.muri,
+retro.forth, interface/ll.retro, and interface/dedup.retro).
+Words defined in the others will make use of the extended
+comment format this introduces to add them inline.
+
+~~~
+{{
+  :save (s-)  n:inc s:chop here swap s:keep &drop compile:call #2 + d:last.name n:dec store ;
+  :stack-comment? (s-sf) dup #0 s:fetch $: eq? ;
+---reveal---
+  :sigil:(
+    stack-comment? [ compiling? &save &drop choose ] &drop choose ;
+  immediate
+}}
+
+:d:describe (:s-)
+  d:lookup nl
+  dup 'Name:____ s:put d:name s:put nl
+  dup 'Address:_ s:put d:xt fetch n:put nl
+  dup 'Class:___ s:put d:class fetch n:put nl
+  dup 'Source:__ s:put d:source fetch dup n:-zero? &s:put &drop choose nl
+  dup 'Stack:___ s:put d:stack fetch dup n:-zero? &s:put &drop choose nl
+  drop ;
+~~~