spitewaste 0.1.004 → 0.1.009

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e6953a0755edbb33708f3cdc1ebeb33cdb6a47c1f3d6335716d25f693dec56c
-  data.tar.gz: 130d57daadcee3de1a465e4be9b28bba16d70c4dafa87c59195696be06e49a7c
+  metadata.gz: 660c0022e893f3656cb3851b0bb3bddebe1df750555138a58dcd81339f11effd
+  data.tar.gz: d5d539641ca545525a26a6d357831baa1dcb95189a4023955d15b45142bf2dad
 SHA512:
-  metadata.gz: b1f2075fb27a9ecf5599365cf029bfeebacfda5208a5df357ea94de00465111f61d42cc58a5220e16de710dfe4c778acf911e65ab3d86459c7039cee37f011a6
-  data.tar.gz: ea2003b53fe38c7fa092b2c43c383706980009fd1efa54f5733e40937b180fd76ea08e973dd5e16835fab1854f075add855af1957357aeab391df0dab6945e92
+  metadata.gz: 28be3283bde45056b240eaba41f4b783a4b4e7bdacf8cfce02e052bf11f002c4e19beb9b101cf2c42638a1406de56f0b466503289a2596e457a4817442fa59f1
+  data.tar.gz: 57591a541274bef66a01828a2b719b4ec5b8091cb83e1cb488adf61041590cb84344db411cddbdd9d9f0dc16395b30cb59f6be397633c996a448262162d2c8c2

data/README.md

@@ -35,8 +35,8 @@ See `spw help` for guidance on invoking the command-line interface, and [this tu
 * {ws, wsa, asm} to {ws, wsa, asm}
 * all supported formats to C++ and PNG
 - [x] Execute all supported formats by converting to Whitespace and passing the results to a user-specified interpreter
-- [ ] Thoroughly document the standard library and make it searchable (eventually `spw docs`)
-- - [ ] using a doctest-like approach for free specs
+- [x] Thoroughly document the standard library and make it searchable (via `spw docs`)
+- - [x] using a doctest-like approach for free specs
 - [ ] Write a proper Spitewaste parser for better error reporting (and performance?)
 - [ ] Support user-specified aliases of the builtin mnemonics in case you wanna say `discard` instead of `pop`, etc.
 - [ ] Resolve missing identifiers by auto-importing the necessary standard library?

data/Rakefile

@@ -14,7 +14,8 @@ task :docs do |t|
   docs = {}
 
   Dir.chdir('lib/spitewaste/libspw') do |d|
-    %w[rational.spw array.spw stack.spw util.spw string.spw math.spw].each do |path|
+    Dir['*.spw'].each do |path|
+      next if path['random']
       lib = File.basename path, '.spw'
       docs[lib] = extract_docs path
     end
@@ -64,8 +65,8 @@ end
 StackRx = /(?<=\[)[^\]]*(?=\])/ # match [.*], but don't capture the brackets
 
 def parse_doc doc
-  # strip comment character and any implementation details
-  doc.gsub!(/; */, '').gsub!(/^!.+\n/, '')
+  # strip leading comment to margin and any implementation details (!)
+  doc.gsub!(/^; */, '').gsub!(/^!.+\n/, '')
 
   head, specs = doc.split "\n\n"
   *desc, effect = head.split ?\n

data/bin/spw

@@ -2,6 +2,7 @@
 
 require 'spitewaste/cli'
 require 'spitewaste/cli/asm'
+require 'spitewaste/cli/docs'
 require 'spitewaste/cli/exec'
 require 'spitewaste/cli/compile'
 require 'spitewaste/cli/convert'

data/lib/spitewaste.rb

@@ -1,3 +1,5 @@
+Warning[:experimental] = false
+
 module Spitewaste
   OPERATORS_M2T = { # mnemonic to tokens
     push:  "  ",       copy: " \t ",   slide: " \t\n",   label: "\n  ",

data/lib/spitewaste/assembler.rb

@@ -1,6 +1,6 @@
 module Spitewaste
   class Assembler
-    attr_reader :src, :parser, :instructions
+    attr_reader :parser
 
     def initialize program, **options
       format = options[:format]
@@ -9,7 +9,7 @@ module Spitewaste
         raise ArgumentError, "unknown format for parse: #{format}"
       end
 
-      @parser =
+      parser =
         case format
         when :whitespace
           WhitespaceParser
@@ -19,9 +19,9 @@ module Spitewaste
           SpitewasteParser
         end
 
-      parser = @parser.new(program, **options).tap &:parse
-      @instructions = parser.instructions
-      @src = parser.src if format == :spitewaste
+      @parser = parser.new(program, **options).tap &:parse
+      @src = @parser.src if format == :spitewaste
+      @instructions = @parser.instructions
     end
 
     def assemble! format:, io: STDOUT, **options
@@ -42,7 +42,52 @@ module Spitewaste
         else
           AssemblyEmitter
         end
-      emitter.new(format == :wsassembly ? @src : @instructions, **options).emit io: io
+
+      # Worthwhile optimizations can only be done if we have a symbol table.
+      optimize! if parser.respond_to? :symbol_table
+
+      src = format == :wsassembly ? @src : @instructions
+      emitter.new(src, **options).emit io: io
+    end
+
+    def optimize_constant_pow
+      pow = parser.symbol_table['pow']
+
+      case @instructions[@ip - 2, 3]
+      in [[:push, base], [:push, exp], [:call, ^pow]]
+        @instructions[@ip - 2, 3] = [[:push, base ** exp]]
+
+      in [[:push, base], [:dup, _], [:call, ^pow]]
+        @instructions[@ip - 2, 3] = [[:push, base ** base]]
+
+      else nil
+      end
+    end
+
+    def optimize_constant_strpack
+      strpack = parser.symbol_table['strpack']
+      return if @instructions[@ip] != [:call, strpack]
+
+      # grab all the instructions between `push 0` and this `call strpack`
+      start = @instructions[0, @ip].rindex [:push, 0]
+      between = @instructions[start + 1...@ip]
+
+      bytes = []
+      # optimization only applies if all of the intervening ops are pushes
+      return unless between.all? { |op, arg| op == :push && bytes << arg }
+
+      packed = bytes.reverse.zip(0..).sum { |b, e| b * 128 ** e }
+      @instructions[start..@ip] = [[:push, packed]]
+      @ip = start + 1
+    end
+
+    def optimize!
+      @ip = 0
+      while @instructions[@ip]
+        next @ip -= 1 if optimize_constant_pow
+        next if optimize_constant_strpack
+        @ip += 1
+      end
     end
 
     def try_elide_main

data/lib/spitewaste/cli.rb

@@ -11,29 +11,31 @@ class SpitewasteCLI < Thor
     exit 1
   end
 
-  # TODO: Figure out how to invoke a command from this class method.
-  def self.handle_no_command_error *args
-    exec $0, 'exec', *args
-  end
-
-  class_option :format,
-    desc: 'input format (in case auto-detection misguesses)',
-    aliases: '-f'
-
-  class_option :aliases,
-    desc: 'augment or override one or more of the default instruction mnemonics [WIP]',
-    banner: 'pop:drop...',
-    type: :array,
-    aliases: '-a'
-
-  class_option :coexist,
-    desc: <<DESC,
+  def self.shared_options
+    option :format,
+      desc: 'input format (in case auto-detection misguesses)',
+      aliases: '-f'
+
+    option :aliases,
+      desc: 'augment or override one or more of the default instruction mnemonics [WIP]',
+      banner: 'pop:drop...',
+      type: :array,
+      aliases: '-a'
+
+    option :coexist,
+      desc: <<DESC,
 allow multiple mnemonics to refer to the same instruction where possible [WIP]
 
 \e[1mNOTE: \e[0mIf --no-coexist (the default), aliases take precedence and render the original mnemonics invalid.
 DESC
-    type: :boolean,
-    aliases: '-x'
+      type: :boolean,
+      aliases: '-x'
+  end
+
+  # TODO: Figure out how to invoke a command from this class method.
+  def self.handle_no_command_error *args
+    exec $0, 'exec', *args
+  end
 
   def self.validate_format options
     if fmt = options[:format]&.to_sym and !VALID_FORMATS.include?(fmt)

data/lib/spitewaste/cli/asm.rb

@@ -3,6 +3,8 @@ class SpitewasteCLI
     'Generate plain Whitespace assembly from INPUT and write it to OUTPUT.'
   long_desc 'Mostly just a convenience wrapper around `spw convert in -o asm out`'
 
+  shared_options
+
   def asm input, output = '/dev/stdout'
     as = Spitewaste::Assembler.new File.read input
     File.open(output, ?w) { |of| as.assemble! format: :assembly, io: of }

data/lib/spitewaste/cli/compile.rb

@@ -39,6 +39,8 @@ DESC
     type: :boolean,
     aliases: '-k'
 
+  shared_options
+
   def compile file = nil
     fmt = SpitewasteCLI.validate_format options
 

data/lib/spitewaste/cli/convert.rb

@@ -21,6 +21,8 @@ DESC
 - use % to write to $HOME/.cache/spitewaste directory, where Spiceweight knows to look',
     aliases: '-s'
 
+  shared_options
+
   def convert input = '/dev/stdin', output = '/dev/stdout'
     ext = File.extname output
     Kernel.exec 'spw', 'image', input, output if ext == '.png'

data/lib/spitewaste/cli/docs.rb

@@ -0,0 +1,51 @@
+def bold  s; "\e[1m#{s}\e[0m" end
+def under s; "\e[4m#{s}\e[0m" end
+def hi    s; "\e[7m#{s}\e[0m" end
+
+DOCS = File.expand_path '../libspw/docs.json', __dir__
+
+class SpitewasteCLI
+  desc 'docs [OPTIONS] [TERMS...]',
+    'Search for matching terms in the documentation of the standard library.'
+
+  option :show_specs,
+    desc: 'display the in-situ specs showing correct outputs for given inputs',
+    type: :boolean,
+    default: false,
+    aliases: '-s'
+
+  option :match_all,
+    desc: 'require that all provided search terms match instead of 1+',
+    type: :boolean,
+    default: false,
+    aliases: '-m'
+
+  def docs *terms
+    abort "need at least one search term" if terms.empty?
+
+    docs = JSON.load File.read DOCS
+    found = []
+    min = options[:match_all] ? terms.size : 1
+
+    docs.each do |lib, fns|
+      fns.each do |fn, data|
+        full = "#{lib}/#{bold under fn} #{data['full']}"
+        ms = terms.count { |t| full[/#{t}/i] }
+        found << [lib, fn, full, ms] if ms >= min
+      end
+    end
+
+    abort "no matches for terms: #{terms}" if found.empty?
+
+    found.sort_by! { |v| -v[-1] }
+
+    IO.popen('less -R', 'w') do |io|
+      found.each do |lib, fn, full|
+        full.gsub! /#{terms * ?|}/i, &method(:hi)
+        desc, specs = full.split "\n\n"
+        io.puts "#{?- * 10}\n#{desc}\n\n"
+        io.puts specs if options[:show_specs]
+      end
+    end
+  end
+end

data/lib/spitewaste/cli/exec.rb

@@ -16,6 +16,8 @@ class SpitewasteCLI
 - use % to write to $HOME/.cache/spitewaste directory, where Spiceweight knows to look',
     aliases: '-s'
 
+  shared_options
+
   def exec input = '/dev/stdin'
     fmt = SpitewasteCLI.validate_format options
 

data/lib/spitewaste/cli/image.rb

@@ -41,6 +41,8 @@ DESC
     type: :numeric,
     aliases: '-l'
 
+  shared_options
+
   def image input, output = nil
     fmt = SpitewasteCLI.validate_format options
     output ||= Pathname.new(input).sub_ext '.png'

data/lib/spitewaste/libspw/array.spw

@@ -1,21 +1,57 @@
+;;; Pseudo-arrays
+
+; An "array" is really just a sequence of elements on the stack followed by
+; the number of elements, so care must be taken to ensure one knows what kind
+; of data is currently being operated on.
+
 import math  ; divmod, max, min, pos?
 import stack ; bury, dig, ncopy, nslide, roll
 import util  ; dec, die!, eq
 
 $amax = 1000
 
+; returns the sum of the array A
+; [A] => [sum]
+;
+; [3 1] => [3]
+; [4 3 2 1 4] => [10]
+; [-10 -5 7 5 10 5] => [7]
 arysum: reduce (add) ret
 
+; duplicates the array at the top of the stack
+; [A] => [A A]
+;
+; [1 2 3 3] => [1 2 3 3 1 2 3 3]
+; [7 50 10 2] => [7 50 10 2 50 10 2]
 arydup:
   dup $++ push -2 copy 1 store
   times (push -2 load $-- :ncopy) ret
 
+; removes the element at the end of the array A
+; [A] => [A']
+;
+; [10 1] => [0]
+; [1 2 3 4 4] => [1 2 3 3]
+; [7 10 20 30 3] => [7 10 20 2]
 arypop: slide 1 $-- ret
 
+; removes the element at the beginning of the array A
+; [A] => [A']
+;
+; [10 1] => [0]
+; [1 2 3 4 4] => [2 3 4 3]
+; [7 10 20 30 3] => [7 20 30 2]
 aryshift: dup :dig $-- ret
 
+; returns the concatenation of arrays A and B
+; [A B] => [A+B]
+;
+; [1 2 3 3 4 5 6 3] => [1 2 3 4 5 6 6]
+; [7 10 2 5 4 3 3] => [7 10 5 4 3 5]
 arycat: dup $++ :roll add ret
 
+;;;
+
 arypack:
   :arydup reduce (:max) $++ push -1 swap store
   $-- times (push -1 load mul add)
@@ -30,36 +66,43 @@ aryunpack:
 
 arylen: push $amax mod ret
 
-;;;
-
+; returns the index I of element E in array A (or -1 if not found)
+; [A E] => [I]
+;
+; [1 2 3 4 4 2] => [1]
+; [1 2 3 4 4 4] => [3]
+; [1 2 3 4 4 5] => [-1]
 aryindex: copy 1 ; two copies of length, one gets decremented, index is diff
-_aryindex_loop: ; [h n l]
-  dup jn _aryindex_notfound
+_aryindex_loop: dup jn _aryindex_notfound
   dup push 2 add :roll copy 2 :eq jz _aryindex_no
   copy 2 copy 1 sub swap $++ :nslide ret
-
 _aryindex_no: $-- jump _aryindex_loop
-
 _aryindex_notfound: slide 1 ret
 
-;;;
-
-; element at index i
-aryat: ; [a i]
+; returns the element E at index I in array A (or dies on out of bounds)
+; [A I] => [E]
+;
+; [1 2 3 4 4 0]  => [1]
+; [1 2 3 4 4 2]  => [3]
+; [1 2 3 4 4 -1] => [4]  negative index counts from the end
+aryat:
   dup jn _aryat_neg
   copy 1 swap sub dup :pos? jz _aryat_oob
   :roll swap $-- :nslide ret
-
 _aryat_neg: copy 1 add dup jn _aryat_oob jump aryat
-
 _aryat_oob: push "(aryat) index out of bounds!" :die!
 
+; returns the minimum and maximum elements of array A
+; [A] => [min max]
+;
+; [4 3 2 1 4] => [1 4]
+; [6 8 -3 4 0 5] => [-3 8]
+; [7 1] => [7 7]
 minmax:
-  :arydup reduce (:max)
-  push -1 swap store
+  :arydup reduce (:max) push -1 swap store
   reduce (:min) push -1 load ret
 
-;;;
+;;; TODO: make sort not atrociously inefficient
 
 sort: push -3 copy 1 store ; preserve length
 _sort_loop:
@@ -70,17 +113,25 @@ _sort_loop:
   push 0 copy 1 sub jn _sort_loop
   push 3 sub load ret
 
+; reverses the array A
+; [A] => [A']
+;
+; [1 2 3 3] => [3 2 1 3]
+; [7 1] => [7 1]
+; [5 4 3 2 1 5] => [1 2 3 4 5 5]
 aryrev: push -3 copy 1 store
 _aryrev_loop:
   swap copy 1 :bury $--
   push 0 copy 1 sub jn _aryrev_loop
   push 3 sub load ret
 
-;;;
-
+; returns the array A replicated N times
+; ! N must be greater than 1
+; [A N] => [A']
+;
+; [3 2 1 3 4] => [3 2 1 3 2 1 3 2 1 3 2 1 12]
 aryrep: push -1 swap push -3 copy 1 store store
 _aryrep_loop:
   push -1 dup :dec load jz _aryrep_done
   :arydup jump _aryrep_loop
-
 _aryrep_done: push -3 load $-- times (:arycat) ret

data/lib/spitewaste/libspw/bits.spw

@@ -1,74 +1,74 @@
-import math   ; ilog, pow
-import string ; strcat, strlen, strrev
-import util   ; bin, digits, itos
-
-; TODO: don't use strings for bitwise operations!
-
-; bitwise bitwise_and
-; ! clobbers heap address -1
-bitwise_and: ; [a b] => [a & b]
-  push -1 push 0 store ; empty string tally
-
-_bitwise_and_loop:
-  copy 1 copy 1 add jz _bitwise_done
-  copy 1 push 2 mod
-  copy 1 push 2 mod
-  add push 2 sub jz _bitwise_and_yes
-  push '0' jump _bitwise_and_update
-
-_bitwise_and_yes: push '1'
-_bitwise_and_update: :_bitwise_update jump _bitwise_and_loop
-
-_bitwise_update:
-  push -1 load swap :strcat
-  push -1 swap store
-  push 2 div swap push 2 div ret
-
-_bitwise_done: push -1 load :strrev :bin slide 2 ret
-
-; bitwise bitwise_or
-; ! clobbers heap address -1
-bitwise_or: ; [a b] => [a | b]
-  push -1 push 0 store ; empty string tally
-
-_bitwise_or_loop:
-  copy 1 copy 1 add jz _bitwise_done
-  copy 1 push 2 mod
-  copy 1 push 2 mod
-  add jz _bitwise_or_no
-  push '1' jump _bitwise_or_update
-
-_bitwise_or_no: push '0'
-_bitwise_or_update: :_bitwise_update jump _bitwise_or_loop
-
-; bitwise bitwise_xor
-; ! clobbers heap address -1
-bitwise_xor: ; [a b] => [a ^ b]
-  push -1 push 0 store ; empty string tally
-
-_bitwise_xor_loop:
-  copy 1 copy 1 add jz _bitwise_done
-  copy 1 push 2 mod
-  copy 1 push 2 mod
-  add push 1 sub jz _bitwise_xor_yes
-  push '0' jump _bitwise_xor_update
-
-_bitwise_xor_yes: push '1'
-_bitwise_xor_update: :_bitwise_update jump _bitwise_xor_loop
-
-; flip all bits in n ; [n]
-bitwise_not:
+import math ; ilog, pow
+import util ; digits
+
+; The bitwise operators all work very similarly, differing only in how they
+; map pairs of bits to 0 or 1. For AND, we simply multiply them. For OR, we
+; sum them, add 1, then divide by 2. For XOR, we only want 1 if they're neq.
+; We repeatedly halve the inputs while consuming bits and stop when at least
+; one of them becomes zero. For AND, the answer is in the accumulator and we
+; are done. For OR and XOR, it's likely the nonzero input still has bits to
+; contribute, so we also accumulate its product with the current power of 2.
+$bitfun(op, bit, done) {
+push -2,1,-1,0 store store
+_`op`_loop: push -1
+  copy 2 push 2 mod copy 2 push 2 mod `bit`
+  push -1 load swap push -2 load dup push 2 mul
+  push -2 swap store mul add store
+  push 2 div swap push 2 div
+  dup copy 2 mul jz _`op`_done swap jump _`op`_loop
+_`op`_done: `done` ret
+}
+
+; returns the bitwise AND of A and B
+; [A B] => [A & B]
+;
+; [65 47] => [1]    [83 25] => [17]
+; [40 64] => [0]    [74 59] => [10]
+; [31 18] => [18]   [86 32] => [0]
+; [93 79] => [77]   [11 79] => [11]
+band: $bitfun(band, mul, mul $-- load)
+
+; returns the bitwise OR of A and B
+; [A B] => [A | B]
+;
+; [66 51] => [115]   [64 4]  => [68]
+; [61 77] => [125]   [93 65] => [93]
+; [14 87] => [95]    [71 37] => [103]
+; [7 19]  => [23]    [38 92] => [126]
+bor: $bitfun(bor, add $++ push 2 div, add push -2 load mul push -1 load add)
+
+; returns the bitwise XOR of A and B
+; [A B] => [A ^ B]
+;
+; [4 14]  => [10]    [0 80]  => [80]
+; [51 5]  => [54]    [97 77] => [44]
+; [39 65] => [102]   [12 26] => [22]
+; [44 36] => [8]     [6 21]  => [19]
+bxor: $bitfun(bxor, :neq, add push -2 load mul push -1 load add)
+
+; returns the infinite-precision bitwise NOT of N by inverting all of its bits
+; [N] => [~N]
+;
+; [58] => [5]    [46] => [17]
+; [48] => [15]   [87] => [40]
+; [98] => [29]   [51] => [12]
+; [3]  => [0]    [42] => [21]
+bnot:
   dup push 0 swap push 1 add sub
   swap push 2 :ilog push 2 swap :pow mod ret
 
-;;;
-
-; number of set bits in n ; [n]
+; returns the number of bits in the binary representation of N
+; [N] => [# of bits]
+;
+; [0] => [0]   [1] => [1]
+; [7] => [3]   [8] => [4]
+; [255] => [8]
+blength: dup jz _blength_zero push 2 :ilog $++ ret
+_blength_zero: ret
+
+; returns the number of set bits in N
+; [N] => [popcount]
+;
+; [0] => [0]   [1] => [1]
+; [7] => [3]   [8] => [1]
 popcount: push 2 :digits reduce (add) ret
-
-;;;
-
-; most significant set bit in n, as a power of 2 ; [n]
-msb: dup jz _msb_zero
-  push 2 :itos :strlen $-- push 2 swap :pow ret
-_msb_zero: ret