3 files changed, 21 insertions(+), 5 deletions(-)

M fs/doc/dict.txt
M fs/doc/usage.txt
M fs/xcomp/bootlo.fs

@@ 362,6 362,8 @@ alias      "x y" -- Find word "x" in system dictionary and create entry "y" of
                     type "alias" pointing to it.
 realias    w t --   Make target word "t" into an alias to word "w".
 S"         x" --    *IC* Yield string literal with contents "x".
+S[         --       *IC* Begin building a string. See doc/usage
+]S         --       Finish building a string.
 
 chain      w1 w2 -- w
   Defines (to "here") and returns a new word that calls w1, then w2. w1 or w2

@@ 47,8 47,8 @@ Dusk has no DEC/HEX mode. Number literals are parsed using a prefix system.
 ## Strings
 
 A string is an address to an area in memory starting with a length byte followed
-by that many characters. When we refer to a "string", we refer to that address.
-For example, this code will yield a "hello" string to PS (Parameter Stack):
+by that many bytes. When we refer to a "string", we refer to that address.  For
+example, this code will yield a "hello" string to PS (Parameter Stack):
 
 here 5 c, 'h' c, 'e' c, 'l' c, 'l' c, 'o' c,
 


@@ 56,6 56,9 @@ The code above is the equivalent of:
 
 S" hello"
 
+Strings in Dusk are not limited to textual data and can refer to binary data.
+It only refers to the "first byte length followed by that much data" structure.
+
 ## String literals
 
 When a string literal word such as S" ." or ," is used, the following content


@@ 72,6 75,16 @@ character:
 Any other character following the '\' results in that character being parsed as-
 is, the preceding '\' being ignored.
 
+## The S[ string builder
+
+You can also build a string at compile time by executing arbitrary code. This
+is done through the S[ words, which writes down the length byte placeholder and
+then drops to intepret mode in the same way "[" does. When this mode is closed
+by "]S", string length is calculated and written down. Example:
+
+    : foo S[ $68 c, $65 c, $6c dup c, c, $6f c, ]S ;
+    foo stype \ prints "hello"
+
 ## Coroutines
 
 Coroutines are two routines that intertwine at the top of RS. Generally,

@@ 261,9 261,10 @@ create _repl    LF  c, CR  c, 0   c,
   then then ;
 : ," begin "< dup -1 <> while c, repeat drop ;
 code (s) r@ W>A, W) 8b) @, 1 W+n, RSP) +, rdrop W<>A, branchA,
-: S" ( comp: -- ) ( not-comp: -- str )
-  compiling if compile (s) else here then
-  here 1 allot here ," here -^ ( 'len len ) swap c! ; immediate
+: _S compiling if compile (s) else here then here 1 allot here ;
+: S[ _S [compile] [ ; immediate
+: ]S ( str -- ) here -^ ( 'len len ) swap c! ;
+: S" _S ," [compile] ]S ; immediate
 : ."
   compiling if [compile] S" compile stype else
     begin "< dup 0>= while emit repeat drop then ; immediate