spitewaste 0.1.003 → 0.1.004

data/lib/spitewaste/libspw/stack.spw

@@ -1,77 +1,101 @@
+;;; Heavy-handed stack manipulation
+
+; These subrtouines do some pretty intricate stack-based operations, relying
+; heavily on clobbering the heap in order to maintain their "bookkeeping".
+; Many of them use heap addresses -10 and lower, unbounded, so they're only
+; meant to be used in a pinch or when there just isn't much of an alternative.
+
+import util ; dec
+
+; rolls the Ith element (counting from 0) to the top of the stack,
+; shifting the elements above it down by 1.
+; [I]
+;
+; [1 2 3 2] => [2 3 1]
+; [1 2 3 4 1] => [1 2 4 3]
+; [1 2 3 4 5 3] => [1 3 4 5 2]
 roll:
   push -10 dup store ; current heap index kept at -10
-
 _roll_keep: ; [n]
   dup jz _roll_remove
   push -10 :dec
   swap push -10 load swap store
   push 1 sub jump _roll_keep
-
 _roll_remove:
   push 10 sub load
   swap push -10 swap store
-
 _roll_restore: ; i
   dup load swap push 1 add
   dup push 10 add jz _roll_done
   jump _roll_restore
-
 _roll_done: load ret
 
-;;;
-
+; "buries" X in the stack at index I, counting from 0
+; [X I]
+;
+; [1 2 3 4 2] => [1 4 2 3] ; 2nd element of stack now 4
+; [1 2 3 4 5 8 5] => [8 1 2 3 4 5]
 bury:
   push -10 dup store ; current heap index kept at -10
   swap push -9 swap store ; preserve element to bury
-
 _bury_keep: ; [n]
   dup jz _bury_restore
   push -10 :dec
   swap push -10 load swap store
   push 1 sub jump _bury_keep
-
 _bury_restore:
   push 9 sub load
   push -10 load :_roll_restore pop ret
 
-;;;
 
+; "digs" out the Ith element of the stack and discards it
+; [I]
+;
+; [1 2 3 4 5 2] => [1 2 4 5]
+; [1 2 3 4 5 4] => [2 3 4 5]
 dig: :roll pop ret
 
-;;;
-
-to_a:
-  push -1 swap store
-  push -10 dup store
-
+; pops elements off the stack until it hits the specified sentinel value S,
+; pushing them to the resulting pseudo-array. It's often more convenient to
+; build up a collection in reverse order, and we often don't know in advance
+; how many elements we'll meet, but we do know to stop at the sentinel.
+; [S En ... E1 S] => [E1 ... En n]
+;
+; [-1 9 8 7 -1] => [7 8 9 3]
+; [0 'c' 'b' 'a' 0] => ['a' 'b' 'c' 3]
+to_a: push -1 swap store push -10 dup store
 _to_a_loop:
   dup push -1 load sub jz _to_a_sentinel
   push -10 dup :dec load
   swap store jump _to_a_loop
-
 _to_a_sentinel: pop push -10
-
 _to_a_restore:
   dup push -10 load sub jz _to_a_done
   push 1 sub dup load swap
   jump _to_a_restore
-
 _to_a_done: push -10 swap sub ret
 
-;;;
-
-; dynamic pop ; [n]
-npop:
-  dup jz _npop_done
-  swap pop push 1 sub jump npop
-
+; pops N elements off the top of the stack
+; [N]
+;
+; [1 2 3 4 5 3] => [1 2]
+; [1 2 3 4 0] => [1 2 3 4]
+npop: dup jz _npop_done swap pop push 1 sub jump npop
 _npop_done: pop ret
 
-; dynamic slide ; [n]
-nslide:
-  swap push -1 swap store
-  :npop push -1 load ret
-
+; slides N elements off the stack, as if the `slide` operator took an argument
+; [N]
+;
+; [1 2 3 4 5 2] => [1 2 5]
+; [1 2 3 4 1] => [1 2 4]
+nslide: swap push -1 swap store :npop push -1 load ret
+
+; copies the Nth element to the top of the stack; this does exactly what
+; a `copy N` instruction would do, but we don't always know N in advance
+; [N]
+;
+; [1 2 3 4 0] => [1 2 3 4 4] ; `copy 0` is just dup
+; [1 2 3 4 3] => [1 2 3 4 1]
 ncopy: push -10 dup store
 _ncopy_loop:
   dup jz _ncopy_save swap

data/lib/spitewaste/libspw/string.spw

@@ -1,104 +1,134 @@
-import math
 import case
+import math  ; divmod, ilog, max, pow
+import stack ; to_a
+import util  ; gt, lt, neq, range
 
 ;;; String packing and unpacking
 
 ; convert a 0-terminated string on the stack to a single base-128 integer
-strpack: push 0 ; tally
+; [0 ... c b a] => ["abc..."]
+;
+; [0 99 98 97] => ["abc"]
+; [0 99 98 97] => [1634657]
+; [0] => [0]
+strpack: push 0 ; accumulator
 _strpack_loop:
   swap dup jz _strpack_done
-  copy 1 push 128 mul add
-  slide 1
+  copy 1 push 128 mul add slide 1
   jump _strpack_loop
-
 _strpack_done: pop :strrev ret
 
 ; convert a single base-128 integer to a 0-terminated string on the stack
-strunpack:
-  :strrev push 0 swap ; terminator
-
+; ["abc..."] => [0 ... c b a]
+;
+; ["abc"] => [0 99 98 97]
+; [1634657] => [0 99 98 97]
+; [0] => [0]
+strunpack: :strrev push 0 swap ; terminator
 _strunpack_loop:
   dup jz _strunpack_done
   dup push 128 mod swap push 128 div
   jump _strunpack_loop
-
 _strunpack_done: pop ret
 
-;;;
-
-; takes a packed string and just returns it log128 to give the length
-strlen: push 128 :ilog ret
-
-;;;
+; returns the length of a packed string, which is just the
+; value itself log-128, +1 if the integer logarithm isn't exact.
+; [S] => [len(S)]
+;
+; [""] => [0]
+; ["abc"] => [3]
+; ["foobar"] => [6]
+strlen: dup push 128 :ilog swap push 128 mod push 0 :neq add ret
 
 ; takes two packed strings and returns their concatenation (as a packed string)
-strcat:
-  push 128 copy 2 :strlen :pow
-  mul add ret
-
-;;;
-
-; reverses a packed string in-place (heapless) [s] => [s.reverse]
-strrev: push 0 swap ; [tally string]
-
-_strrev_loop: ; [t s]
+; [S T] => [S+T]
+;
+; ["foo" ""] => ["foo"]
+; ["" "foo"] => ["foo"]
+; ["foo" "bar"] => ["foobar"]
+strcat: push 128 copy 2 :strlen :pow mul add ret
+
+; reverses a packed string "in-place"
+; [S] => [reverse(S)]
+;
+; ["foo"] => ["oof"]
+; ["bark"] => ["krab"]
+; ["ab"] => ["ba"]   ['a'] => ['a']   [""] => [""]
+strrev: push 0 swap
+_strrev_loop:
   dup jz _strrev_done
-  swap push 128 mul ; [s t]
+  swap push 128 mul
   copy 1 push 128 mod add
   swap push 128 div
   jump _strrev_loop
-
 _strrev_done: pop ret
 
-;;;
-
-; takes a packed string, a start index, and a length and returns the
+; takes a packed string S, a start index I, and a length L and returns the
 ; corresponding substring (simply by doing division with powers of 128; neat)
+; [S I L] => [substring]
+;
+; ["foobar" 0  6] => ["foobar"]
+; ["foobar" 1  4] => ["ooba"]
+; ["foobar" 1 10] => ["oobar"]
+; ["foobar" 5  1] => ['r']
+; ["foobar" 6  0] => [""]
 strslice:
   swap push 128 swap :pow
   copy 2 swap div
   swap push 128 swap :pow
   mod slide 1 ret
 
-;;;
-
-; index of substring t in string s ; [s t]
+; returns the index of substring T in string S (or -1 if not found)
+; [S T] => [index]
+;
+; ["foobar" 'o'] => [1]
+; ["foobar" "ob"] => [2]
+; ["foobar" ""] => [0]
+; ["foobar" "bar"] => [3]
+; ["foobar" "bark"] => [-1]
 strindex: swap push 0
-
 _strindex_loop: ; [t s i]
   copy 1 copy 3 :strlen push 0 swap :strslice
   copy 3 sub jz _strindex_found
-  push 1 add ; increment index
-  swap push 128 div dup jz _strindex_no
+  push 1 add swap push 128 div dup jz _strindex_no
   swap jump _strindex_loop
-
 _strindex_no: push -1 slide 3 ret
-
 _strindex_found: slide 2 ret
 
-;;;
-
+; returns the character at index I in string S
+; [S I] => [char]
+;
+; ["foobar" 1] => ['o']
+; ["foobar" 3] => ['b']
+; ["foobar" 5] => ['r']
+; ["foobar" 6] => [""]
 charat: push 1 :strslice ret
 
-;;;
-
-; 1 if the character at the top of the stack is alphabetical, 0 otherwise
+; returns 1 if the character at the top of the stack is
+; alphabetical (ASCII 65-90 or 97-122), 0 otherwise
+; [C] => [0/1]
+;
+; ['@'] => [0]   ['a'] => [1]
+; ['z'] => [1]   ['['] => [0]
+; ['`'] => [0]   ['A'] => [1]
+; ['Z'] => [1]   ['{'] => [0]
 isalpha:
   dup push 123 :lt jz _isalpha_no
   dup push 64 :gt jz _isalpha_no
   push 32 mod $-- push 32 mod push 26 :lt ret
 _isalpha_no: dup sub ret
 
-;;;
-
-; repeat a string s n times [s n]
+; returns string S replicated N times
+; [S N] => [S+S+...]
+;
+; ["abc" 1] => ["abc"]
+; ["abc" 2] => ["abcabc"]
+; ["abc" 0] => [""]
 strrep: push 0 swap
-_strrep_loop: ; [s t n]
+_strrep_loop:
   dup jz _strrep_done
   swap copy 2 :strcat
-  swap push 1 sub
-  jump _strrep_loop
-
+  swap push 1 sub jump _strrep_loop
 _strrep_done: swap slide 2 ret
 
 ;;; String alignment
@@ -107,19 +137,48 @@ _strrep_done: swap slide 2 ret
 ; we swap before calling strcat.
 _justc: swap copy 2 :strlen sub push 0 :max :strrep ret
 
-; Left-justify string s to width w with character c. [s w c]
+; left-justifies string S to width W with character C
+; [S W C] => [S, left-justified]
+;
+; ["foo" 5 'x'] => ["fooxx"]
+; ["foobar" 4 'x'] => ["foobar"]
+; ["" 3 'x'] => ["xxx"]
 ljustc: :_justc :strcat ret
 
-; Left-justify string s to width w with spaces. [s w]
+; left-justifies string S to width W with spaces
+; [S W] => [S, left-justified]
+;
+; ["foo" 5] => ["foo  "]
+; ["foobar" 4] => ["foobar"]
+; ["" 3] => [528416]
 ljust: push ' ' :ljustc ret
 
-; Right-justify string s to width w with character c. [s w c]
+; right-justifies string S to width W with character C
+; [S W C] => [S, right-justified]
+;
+; ["foo" 5 'x'] => ["xxfoo"]
+; ["foobar" 4 'x'] => ["foobar"]
+; ["" 3 'x'] => ["xxx"]
 rjustc: :_justc swap :strcat ret
 
-; Right-justify string s to width w with spaces. [s w]
+; right-justifies string S to width W with spaces
+; [S W C] => [S, right-justified]
+;
+; ["foo" 5] => ["  foo"]
+; ["foobar" 4] => ["foobar"]
+; ["" 3] => [528416]
 rjust: push ' ' :rjustc ret
 
-; Center string s to width w with character c. [s w c]
+; centers string S to width W with character C, favoring left alignment when
+; there's a parity mismatch (even-length string to odd width or vice versa)
+; ! TODO: This seems unnecessarily intricate, but perhaps just its nature.
+; [S W C] => [S, centered]
+;
+; ["abc" 7 'x']  => ["xxabcxx"]
+; ["abc" 6 'x']  => ["xabcxx"]
+; ["abcd" 6 'o'] => ["oabcdo"]
+; ["abcd" 7 'o'] => ["oabcdoo"]
+; ["abcd" 3 '!'] => ["abcd"]
 centerc:
   swap dup copy 3 :strlen sub
   push 0 :max push 2 div
@@ -130,22 +189,42 @@ centerc:
   copy 2 swap :strrep :strcat
   slide 2 ret
 
-; Center string s to width w with spaces. [s w]
+; centers string S to width W with spaces
+; [S W] => [S, centered]
+;
+; ["abc" 7] => ["  abc  "]
+; ["abc" 6] => [" abc  "]
+; ["abcd" 6] => [" abcd "]
+; ["abcd" 7] => [" abcd  "]
+; ["abcd" 3] => ["abcd"]
 center: push ' ' :centerc ret
 
 ;;;
 
-; remove the last character of a string
-strchop:
-  dup :strlen push 1 sub
-  push 0 swap :strslice ret
-
-; Split string s on delimiting character d.
-; ! clobbers heap addresses -1 and -2
-strsplit: ; [s d]
+; removes the last character of a string
+; [S] => [S.chop]
+;
+; ["foobar"] => ["fooba"]
+; ["abc"] => ["ab"]
+; ["a"] => [""]
+; ! [""] => ERROR TODO: Should just be a no-op.
+strchop: dup :strlen push 1 sub push 0 swap :strslice ret
+
+; splits string S on delimiting character C, leaving the resultant substrings
+; on the stack as a pseudo-array (length at top of stack)
+; ! TODO: permit string delimiter
+; ! clobbers heap addresses -1 (strlen), -2, and -3
+; [S C] => [A]
+;
+; ["fooxbar" 'x'] => ["foo" "bar" 2]
+; ["foobar" 'x'] => ["foobar" 1]
+; ["foo|bar|baz" '|'] => ["foo" "bar" "baz" 3]
+; ["foo,,bar" ','] => ["foo" "" "bar" 3]
+; ["/foo/bar/" '/'] => ["" "foo" "bar" "" 4]
+strsplit:
   push -3 push 1 store ; number of found substrings
   push -2 swap store ; stash delimiter to allow some stack juggling
-_strsplit_loop: ; [s]
+_strsplit_loop:
   dup dup push -2 load
   :strindex dup jn _strsplit_done ; done when index of delimiter is -1
   push 0 swap :strslice
@@ -154,80 +233,137 @@ _strsplit_loop: ; [s]
   swap push -3 swap push 1 add store ; update number of found
   push 1 add push 128 swap :pow div ; shrink haystack
   jump _strsplit_loop
-
 _strsplit_done: push 2 sub slide 1 load ret
 
-;;;
+; splits the string S on newlines
+lines: push 10 :strsplit ret
 
-; [...strs n delim]
-; ! clobbers heap address -2 (strlen uses -1)
+; joins the pseudo-array of strings A into string S with delimiter string D
+; ! clobbers heap address -2 (and strlen uses -1)
+; [A D] => [S]
+;
+; ["foo" "bar" 2 'x'] => ["fooxbar"]
+; ["foo" "bar" "baz" 3 '--'] => ["foo--bar--baz"]
+; ["foo" 1 "?!"] => ["foo"]
 strjoinc:
   dup :strlen pop ; get delimiter length into -1
   push -2 swap store
   map (push -2 load :strcat) ; add delimiter to all elements
   swap push 128 copy 1 :strlen
   push -2 load :strlen
-  sub :pow mod swap ; remove delimiter from last and flow
+  sub :pow mod swap ; remove delimiter from last and flow into strjoin
+
+; concatenates the pseudo-array of strings A into string S
+; [A] => [S]
+;
+; ["foo" 1] => ["foo"]
+; ["foo" "bar" 2] => ["foobar"]
+; ["foo" 'x' "bar" 'x' "baz" 5] => ["fooxbarxbaz"]
 strjoin: reduce (:strcat) ret
 
-;;;
-
-; return the number of ocurrences of character c in string s [s c]
+; returns the number of ocurrences of character C in string S
+; [S C] => [N]
+;
+; ["foobar" 'a'] => [1]
+; ["foobar" 'o'] => [2]
+; ["foobar" 'c'] => [0]
 strcountc: swap push 0 swap
-
-_strcountc_loop: ; c t s
+_strcountc_loop:
   dup jz _strcountc_done
   dup push 128 mod copy 3 sub jz _strcountc_yes
   push 128 div jump _strcountc_loop
-
 _strcountc_yes:
   swap push 1 add swap push 128 div
   jump _strcountc_loop
-
 _strcountc_done: swap slide 2 ret
 
-; number of ocurrences of all characters in string c [s c]
+; returns the total number of ocurrences of all characters in string T in string S
+; [S T] => [N]
 ; ! clobbers heap address -2
+;
+; ["foobar" 'o'] => [2]
+; ["foobar" "ob"] => [3]
+; ["foxboar" "box"] => [4]
+; ["eunoia" "aeiou"] => [5]
+; ["why" "aeiou"] => [0]
 strcount:
   swap push -2 swap store
   :strunpack push 0 :to_a
   map (push -2 load swap :strcountc)
   reduce (add) ret
 
-;;;
-
-; Convert all characters in src to the corresponding characters in dest.
+; translates all characters in A to the corresponding characters in B
+; in stirng S, ; similar to the `tr` utility in Unix. A and B must be
+; of the same length. TODO: make this smarter (ranges, length mismatch)
 ; ! clobbers heap addresses -1, -2, and -3
-strtrans: ; [string src dest]
+; [S A B] => [S]
+;
+; ["abcd" "abc" "xyz"] => ["xyzd"]
+; ["foobar" "oba" "ele"] => ["feeler"]
+; ["abcdcba" "abcd" "xyz|"] => ["xyz|zyx"]
+strtrans:
   push -3 swap store
   push -2 swap store
   dup :strlen push -1 swap store
   :strunpack push -1 load
-  map (:_strtrans) pop
-  :strpack ret
-
+  map (:_strtrans) pop :strpack ret
 _strtrans:
   dup push -2 load swap :strindex
   dup jn _strtrans_no
   push -3 load swap :charat
   slide 1 ret
-
 _strtrans_no: pop ret
 
+; expands the length-2 string S to contain the intervening ASCII characters
+; ! TODO: make this smarter; multiple ranges in one string
+; [S] => [S, expanded]
+;
+; ["CJ"] => ["CDEFGHIJ"]
+; ["DA"] => ["DE"] TODO: bug
+; ["af"] => ["abcdef"]
+; ["09"] => ["0123456789"]
+; ["(1"] => ["()*+,-./01"]
 strexpand:
   push 0 swap push 128 :divmod
   swap :range :strpack :strrev ret
 
-strsqueeze: push 0 swap ; [sentinel s]
+; "squeezes" runs of the same character in string S to just one occurrence
+; [S] => [S, squeezed]
+;
+; ["abc"] => ["abc"]
+; ["foobar"] => ["fobar"]
+; ["bookkeeper"] => ["bokeper"]
+; ["xxxxxxx"] => ["x"]
+strsqueeze: push 0 swap
 _strsqueeze_loop: ; [s]
   dup jz _strsqueeze_done
   push 128 :divmod dup copy 3 sub jz _strsqueeze_skip
   swap jump _strsqueeze_loop
-
 _strsqueeze_skip: pop jump _strsqueeze_loop
-
 _strsqueeze_done: pop :strpack :strrev ret
 
-strsum: :strunpack push 0 :to_a :arysum ret
-
-lines: push 10 :strsplit ret
+; returns the sum of the ordinal values of the characters in string S
+; [S] => [N]
+;
+; ["ABC"] => [198]
+; ["012"] => [147]
+; ["a"] => [97]
+; [""] => [] TODO: bug, should be 0
+strsum: :strunpack push 0 :to_a reduce (add) ret
+
+; rotates the string S to the left N times, wrapping
+; [S N]
+;
+; ["abc" 0] => ["abc"]
+; ["abcd" 1] => ["bcda"]
+; ["abcd" 5] => ["bcda"]
+; ["foodbar" 4] => ["barfood"]
+strrotl: push 128 swap copy 2 :strlen mod :pow :divmod :strcat ret
+
+; rotates the string S to the right N times, wrapping
+; [S N]
+;
+; ["abcd" 1] => ["dabc"]
+; ["abcd" 5] => ["dabc"]
+; ["foodbar" 3] => ["barfood"]
+strrotr: push 0 swap sub :strrotl ret