spitewaste 0.1.003 → 0.1.008

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b4f49809a688762a3b50dab64b93163e493aa75a33d2565b9892ec5ad8c9bc0
-  data.tar.gz: 6a06768b5a4edcf18ca0948900effd3c3fb01fbdea2e2da8d29080036870614f
+  metadata.gz: 6477ee6d326bbb3fb166983df576812e8cb55b7ca4f484c69003491da676b5c9
+  data.tar.gz: db9ffe920b78a3439c2e9c20336f0f336f5bf24b6e6e6ba43b0d2de6f7cac44b
 SHA512:
-  metadata.gz: 99cc02efffe8e2ddecf76b1b8578c4eb5e3a6c96b0cf1d46d063b9268507120a718835822f906739962a0b36262ae08328c610db3b37b0a777b3ff84d5e2df02
-  data.tar.gz: fa3425ae1c074a9a34f78bf110a7d8bb645b15205bb78f68787060e61c018cf63925c2c32d67bbf5ab0d4552c37727555dfcdd384824af2b6087c665bf969233
+  metadata.gz: 95697bc3b0579a3e286c446bb1c6ada9a529ca239c18d285be290b063233a80ab90e01846e54469ecfc550669c46330d118fbd4e42381233a825effeb39554f2
+  data.tar.gz: 9bf01bb21a013d50721d2247d998d34e1660d9d4247224c54063ef11137059c734e40cdb6e3a412c619fe5df368e252272604a5229d7dcf01401c95cd5ed8b14

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

@@ -7,15 +7,21 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/*_test.rb']
 end
 
-desc "Generate standard library documentation."
+task test: :docs
+
+desc 'Generate standard library documentation.'
 task :docs do |t|
-  all_docs = {}
-  Dir['lib/spitewaste/libspw/math*'].each do |path|
-    lib = File.basename path, '.spw'
-    all_docs[lib] = extract_docs path
-  end
+  docs = {}
+
+  Dir.chdir('lib/spitewaste/libspw') do |d|
+    Dir['*.spw'].each do |path|
+      next if path['random']
+      lib = File.basename path, '.spw'
+      docs[lib] = extract_docs path
+    end
 
-  File.open('docs.json', ?w) { |f| JSON.dump all_docs, f }
+    File.open('docs.json', ?w) { |f| JSON.dump docs, f }
+  end
 end
 
 def extract_docs path
@@ -41,14 +47,26 @@ def strpack s
 end
 
 def parse_stack s
-  s.split.map { Integer(_1) rescue strpack _1.delete %('") }
+  s.scan(/"[^"]*"|\S+/).map { |v|
+    begin
+      Integer v
+    rescue
+      if v[/R\((-?\d+),(-?\d+)\)/]
+        n, d = $1.to_i, $2.to_i
+        s = (n<=>0) * (d<=>0)
+        (n.abs * 2**31 + d.abs) * 2 + (s == -1 ? 0 : 1)
+      else
+        strpack v.delete %('")
+      end
+    end
+  }
 end
 
-def parse_doc doc
-  StackRx = /(?<=\[)[^\]]+(?=\])/ # match [.+], but don't capture the brackets
+StackRx = /(?<=\[)[^\]]*(?=\])/ # match [.*], but don't capture the brackets
 
-  # strip comment character and any implementation details
-  doc.gsub!(/; */, '').gsub!(/^!.+\n/, '')
+def parse_doc doc
+  # 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

@@ -17,7 +17,7 @@ module Spitewaste
     black = program.size - white
 
     return :whitespace if white > black
-    program[/[^-\w\s]/] ? :spitewaste : :assembly # TODO: something more robust?
+    program[/import|[^-\w\s]/] ? :spitewaste : :assembly
   end
 end
 

data/lib/spitewaste/assembler.rb

@@ -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
+      @instructions = @parser.instructions
+      @src = @parser.src if format == :spitewaste
     end
 
     def assemble! format:, io: STDOUT, **options

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 = 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#{lib}/#{bold under fn} #{desc}\n\n"
+        io.puts specs if options[:show_specs]
+      end
+    end
+  end
+end

data/lib/spitewaste/cli/exec.rb

@@ -16,28 +16,27 @@ class SpitewasteCLI
 - use % to write to $HOME/.cache/spitewaste directory, where Spiceweight knows to look',
     aliases: '-s'
 
-  def exec file = '/dev/stdin'
+  shared_options
+
+  def exec input = '/dev/stdin'
     fmt = SpitewasteCLI.validate_format options
 
-    raise LoadError, "No such file '#{file}'", [] unless File.exists? file
+    raise LoadError, "No such file '#{input}'", [] unless File.exists? input
 
     opts = options.dup # options is frozen
     if opts[:symbol_file] == '%'
-      opts[:symbol_file] = SpitewasteCLI.make_cache_path file
+      opts[:symbol_file] = SpitewasteCLI.make_cache_path input
     end
 
-    path =
-      if File.extname(file) != '.ws'
-        io = Tempfile.new
-        as = Spitewaste::Assembler.new File.read(file), format: fmt, **opts
-        as.assemble! format: :whitespace, io: io
-        io.tap(&:close).path
-      else
-        file
-      end
+    if File.extname(input) != '.ws'
+      io = Tempfile.new
+      as = Spitewaste::Assembler.new File.read(input), format: fmt, **opts
+      as.assemble! format: :whitespace, io: io
+      input = io.tap(&:close).path
+    end
 
     cmd = options[:interpreter].split
-    cmd.map! { |c| c == '%' ? path : c }
+    cmd.map! { |c| c == '%' ? input : c }
     Kernel.exec *cmd
   end
 end

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,17 +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)
@@ -26,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
-
+_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:
@@ -66,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