spitewaste 0.1.001 → 0.1.006

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2124fde880a571c835efe1e74e397a0dea698786c69a62852c4ad8bd7e3ffe0
-  data.tar.gz: 0d40e036ca0d7f51ea617be600274088160a8159dc7e04f87af8429d29154fc4
+  metadata.gz: 17fcfab8a738ff0666343f1456c4608f0b721a7e8a1a1dc89887c18b258d538c
+  data.tar.gz: 7d923d804a932d6a055804a616ae6b518db37ca87006bf049ecd2a590477c10a
 SHA512:
-  metadata.gz: 8ca420c6896dba0743f70f27a6558178bfe6201fd821afd45594e11796a975ebd042eb6d65fda6b20221f40831d183e417aca2e7dd7c19edff16c4e99ea15135
-  data.tar.gz: 1699a938795047284088697c7c3d7f444e626b033f888080618d2d7350635a69dab37b63455cd6544740e747b2665f30df5c15d14c64bdb1a2f2755387cd4ff5
+  metadata.gz: c2b108463c434fed7f09d5a6b922c0363cf979ed9ba89a3bd731dba0436e7ed39da71d9ffc76ad1f8f3c9b5ba3ad58405bf9777443e8d3f116a4eb7001d4ba44
+  data.tar.gz: 07e9108b800fa22b36cf033b57eb6d8fdc5df3a73e3d19e2385093ea9a5dc4fc91bfddb23620ab4df6cbe28dc17f24a3ce86d3bb5c88b156b5ffc223184376c9

data/Gemfile

@@ -1,8 +1,3 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in spitewaste.gemspec
-
-gem 'rake', '~> 12.0'
-gem 'minitest', '~> 5.0'
-gem 'thor', '~> 1.0'
-gem 'oily_png' # TODO: optionalize?
+gemspec

data/LICENSE

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

data/README.md

@@ -1,7 +1,4 @@
-<p align="center">
-<img src="abc" /><br >
-"Code should be invisible." — someone, surely
-</p>
+<p align="center">"Code should be invisible." — someone, surely</p>
 
 # Spitewaste
 
@@ -21,7 +18,7 @@ Spitewaste is the pseudo-assembly language referred to throughout this document,
 
 **spw** is a command-line utility whose primary purpose is to "lower" Spitewaste programs to Whitespace for execution by some external interpreter, but it's capable of several (perhaps too many) other transformations; see `spw help convert` for further details. In addition to losslessly converting between various representations, spw can generate pretty pictures of Whitespace code syntax-highlighted in your favorite color scheme via `spw image`.
 
-Spitewaste is not [a Whitespace interpreter](collidedscope/spiceweight), but `spw exec` will convert its input to something your interpreter of choice should understand and ferry it along. Finally, `spw compile` will blindly translate Whitespace instructions to functionally equivalent C++ code and feed that into a compiler; the results aren't spectacular (compilers loathe `goto`), but it's fun to pretend Whitespace is a compiled language.
+Spitewaste is not [a Whitespace interpreter](../../../spiceweight), but `spw exec` will convert its input to something your interpreter of choice should understand and ferry it along. Finally, `spw compile` will blindly translate Whitespace instructions to functionally equivalent C++ code and feed that into a compiler; the results aren't spectacular (compilers loathe `goto`), but it's fun to pretend Whitespace is a compiled language.
 
 ## Where <sub>can I get it?</sub>
 

data/Rakefile

@@ -1,10 +1,83 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'json'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
-  t.libs << 'lib'
   t.test_files = FileList['test/*_test.rb']
 end
 
-task :default => :test
+task test: :docs
+
+desc 'Generate standard library documentation.'
+task :docs do |t|
+  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 docs, f }
+  end
+end
+
+def extract_docs path
+  docs = {}
+  buffer = ''
+
+  File.open(path).each_line do |line|
+    if line.strip.empty?
+      buffer.clear
+    elsif line[/^([^_]\S+):/]
+      docs[$1] = parse_doc buffer.dup unless buffer.empty?
+      buffer.clear
+    elsif line[/^;/]
+      buffer << line
+    end
+  end
+
+  docs
+end
+
+def strpack s
+  s.bytes.zip(0..).sum { |b, e| b * 128 ** e }
+end
+
+def parse_stack s
+  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
+
+StackRx = /(?<=\[)[^\]]*(?=\])/ # match [.*], but don't capture the brackets
+
+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
+  desc *= ?\n
+
+  cases = []
+  specs.scan(StackRx).each_slice 2 do |spec|
+    cases << spec.map { parse_stack _1 }
+  end if specs
+
+  {full: doc, desc: desc, effect: effect, cases: cases}
+end
+
+task default: :test

data/TUTORIAL.md

@@ -120,6 +120,6 @@ A standard library! Writing a Whitespace program from scratch can be a daunting
 
 ### Strings
 
-Pretty much every program needs strings, and Spitewaste has 'em! But how? Well, a string is ultimately just a sequence of bytes, and we can use the power of exponents to smush multiple numbers into a single value. If we had the numbers 3, 9, and 4, we could easily encode them as a single base-10 number: 3 × 10<sup>2</sup> + 9 × 10<sup>1</sup> + 4 × 10<sup>0</sup>. Strings in Spitewaste are similarly encoded, except backwards (as an implementation detail) and in base-128 rather than decimal.
+Pretty much every program needs strings, and Spitewaste has 'em! But how? Well, a string is ultimately just a sequence of bytes, and we can use the power of exponents to smush multiple numbers into a single value. If we had the numbers 3, 9, and 4, we could easily encode them as a single base-10 number: 3 × 10<sup>2</sup> + 9 × 10<sup>1</sup> + 4 × 10<sup>0</sup> = 394. Strings in Spitewaste are similarly encoded, except backwards (as an implementation detail) and in base-128 rather than decimal.
 
 When you say <code>push "ABC"</code>, the assembler transforms it into <code>push 1106241</code>, the value of: 67 ('C') × 128<sup>2</sup> + 66 × 128<sup>1</sup> + 65 × 128<sup>0</sup>. Whitespace interpreters SHOULD (and many do) support arbitrarily large integers, so we don't have to worry about these representations not fitting into 64 bits. Once we're able to pass strings around as individual values, a plethora of possibilities opens up, and the standard library contains many string functions to reflect this.

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/emitters/assembly.rb

@@ -1,7 +1,7 @@
 module Spitewaste
   class AssemblyEmitter < Emitter
     def emit io:
-      io.puts instructions.map { (_1 * ' ').rstrip }
+      io.puts instructions.map { |i| (i * ' ').rstrip }
     end
   end
 end

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