spitewaste 0.1.001

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c2124fde880a571c835efe1e74e397a0dea698786c69a62852c4ad8bd7e3ffe0
+  data.tar.gz: 0d40e036ca0d7f51ea617be600274088160a8159dc7e04f87af8429d29154fc4
+SHA512:
+  metadata.gz: 8ca420c6896dba0743f70f27a6558178bfe6201fd821afd45594e11796a975ebd042eb6d65fda6b20221f40831d183e417aca2e7dd7c19edff16c4e99ea15135
+  data.tar.gz: 1699a938795047284088697c7c3d7f444e626b033f888080618d2d7350635a69dab37b63455cd6544740e747b2665f30df5c15d14c64bdb1a2f2755387cd4ff5

data/Gemfile

@@ -0,0 +1,8 @@
+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?

data/README.md

@@ -0,0 +1,55 @@
+<p align="center">
+<img src="abc" /><br >
+"Code should be invisible." — someone, surely
+</p>
+
+# Spitewaste
+
+**Spitewaste** is a collection of tools with the noble goal of making your code disappear. Far too many CPU cycles are spent on displaying visible source code, and much too much ink has been spilled in the service of program printouts. We need a language whose only syntactic elements are space, tab, and newline; we need [Whitespace](https://en.wikipedia.org/wiki/Whitespace_(programming_language)).
+
+Of course, writing programs in *pure* Whitespace is a task beyond mere mortals, but it'd be great if we could at least transpile to that most ephemerally beautiful of languages. To that end, I've endeavored to make spiting the aforementioned wastefulness (get it?<b id="a1">[*](#f1)</b>) a little more tractable by laying a thin veneer of syntax and additional semantics over the Whitespace instruction set.
+
+~~Many~~ [Some](https://rosettacode.org/wiki/Category:Whitespace) programs have been written in "Whitespace assembly", but this is *Spitewaste* assembly: <p align="center"><img src="demo/factorial.png" /></p>
+
+Granted, that gets translated to [all this](demo/factorial.wsa) (which is just a nicer way of saying [this](demo/factorial.asm), though not nearly as nice as [*this*](demo/factorial-nicespace.png)), but that's the price paid for convenience. Besides, we're much less interested in the size of the code than we are in how many printable characters it ultimately contains, and the best possible score on that metric is zero.
+
+<b id="f1">*</b> <sup>Kidding, of course; it's so named because I wrote it in **spite** of it being a huge **waste** of... all the things.</sup> [↩](#a1)
+
+## What <sub>is it?</sub>
+
+Spitewaste is the pseudo-assembly language referred to throughout this document, as well as its accompanying standard library of useful subroutines ([`libspw`](lib/spitewaste/libspw)). The assembler that converts programs written in this language to pure Whitespace is also called Spitewaste, but the executable (and conventional extension) is `spw`.
+
+**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.
+
+## Where <sub>can I get it?</sub>
+
+The project is distributed as a Ruby gem, so you're just a `gem install spitewaste` away from being able to run Spitewaste programs and/or turn them into executable nothingness. The package includes the assembler (a Ruby module), the CLI that drives it (**`spw`**), as well as the standard library (`libspw`).
+
+## How <sub>do I use it?</sub>
+
+See `spw help` for guidance on invoking the command-line interface, and [this tutorial](TUTORIAL.md) for information regarding what Spitewaste offers over plain-old Whitespace assembly.
+
+## When <sub>will it do X?</sub>
+
+- [x] Convert from
+* Spitewaste to: Whitespace (ws), Whitespace assembly (wsa; just preprocessed spw), straight-line opcodes (asm)
+* {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
+- [ ] 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?
+- [ ] Run a program with several interpreters to compare output and performance?
+- [ ] Show inline opcodes with `spw image`?
+
+## Why <sub>is this a thing?</sub>
+
+Because it's fun, of course! Any useful knowledge gained along the way is just icing on the cake.
+
+## Who <sub>wants to help?</sub>
+
+The standard library currently sports just over a hundred "functions". A lot of them are pretty neat, but there's certainly room for many more. If you're up to it, I encourage you to learn just enough Spitewaste to be dangerous and contribute anything you feel is missing.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/*_test.rb']
+end
+
+task :default => :test

data/TUTORIAL.md

@@ -0,0 +1,125 @@
+For starters, note that Spitewaste is a strict superset of Whitespace (assembly) insofar as it doesn't add anything to the instruction set. That is, what we ultimately have to work with are a stack, a "heap" (hash, dictionary) of integer key-value pairs, and these 24 instructions:
+
+<table>
+  <tr>
+    <td colspan="2" align="center"><b>stack manipulation</b></td>
+  </tr>
+  <tr>
+    <td><code>push <em>n</em></code></td>
+    <td>Push the value <em>n</em> onto the stack.</td>
+  </tr>
+  <tr>
+    <td><code>pop</code></td>
+    <td>Remove the value at the top of the stack.</td>
+  </tr>
+  <tr>
+    <td><code>dup</code></td>
+    <td>Duplicate the value at the top of the stack.</td>
+  </tr>
+  <tr>
+    <td><code>swap</code></td>
+    <td>Swap the top two values of the stack.</td>
+  </tr>
+  <tr>
+    <td><code>copy <em>n</em></code></td>
+    <td>Place a copy of the <em>n</em>th value at the top of the stack.<br><code>copy 0</code> is a funny way to write <code>dup</code></td>
+  </tr>
+  <tr>
+    <td><code>slide <em>n</em></code></td>
+    <td>Remove <em>n</em> values from the top of the stack, but preserve the top.</td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center"><b>control flow</b></td>
+  </tr>
+  <tr>
+    <td><code>label <em>n</em></code></td>
+    <td>Mark a position in the program and name it <em>n</em>.</td>
+  </tr>
+  <tr>
+    <td><code>jump <em>n</em></code></td>
+    <td>Unconditionally jump to label <em>n</em>.
+  </tr>
+  <tr>
+    <td><code>jz <em>n</em></code></td>
+    <td>Pop the stack and jump to label <em>n</em> if the popped value was zero.
+  </tr>
+  <tr>
+    <td><code>jn <em>n</em></code></td>
+    <td>Pop the stack and jump to label <em>n</em> if the popped value was negative.
+  </tr>
+  <tr>
+    <td><code>call <em>n</em></code></td>
+    <td>Jump to label <em>n</em>, expecting it to <code>ret</code> in order to return to this call site.
+  </tr>
+  <tr>
+    <td><code>ret</code></td>
+    <td>Return to the most recent call site.</td>
+  </tr>
+  <tr>
+    <td><code>exit</code></td>
+    <td>Halt execution immediately.</td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center"><b>arithmetic</b></td>
+  </tr>
+  <tr>
+    <td><code>add</code></td>
+    <td>Pop the top two values of the stack and push their sum.</td>
+  </tr>
+  <tr>
+    <td><code>sub</code></td>
+    <td>Pop the top two values of the stack and push their difference.<br>The top gets subtracted, so <code>push 3 push 5 sub</code> leaves -2 on the stack.</td>
+  </tr>
+  <tr>
+    <td><code>mul</code></td>
+    <td>Pop the top two values of the stack and push their product.</td>
+  </tr>
+  <tr>
+    <td><code>div</code></td>
+    <td>Pop the top two values of the stack and push their quotient.<br><b>Note:</b> floored, truncating division so -5 / 2 == -3</td>
+  </tr>
+  <tr>
+    <td><code>mod</code></td>
+    <td>Pop the top two values of the stack and push their modulus.<br><b>Note:</b>-1 % 4 == 3</td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center"><b>heap access</b></td>
+  </tr>
+  <tr>
+    <td><code>store</code></td>
+    <td>Pop the value then the key and store the pair in the heap.<br><code>push 4 push 2 store</code> => <code>{4: 2}</code></td>
+  </tr>
+  <tr>
+    <td><code>load</code></td>
+    <td>Pop the key and push the associated heap value.<br><b>Note:</b> Undefined heap slots have an implicit value of 0.</td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center"><b>input/output</b></td>
+  </tr>
+  <tr>
+    <td><code>ichr</code></td>
+    <td>Read a character (byte) from <code>stdin</code>, pop a key from the top of the stack, <br>and store the byte in the heap at that key.</td>
+  </tr>
+  <tr>
+    <td><code>inum</code></td>
+    <td>Read a number from <code>stdin</code>, pop a key from the top of the stack, <br>and store the byte in the heap at that key.</td>
+  </tr>
+  <tr>
+    <td><code>ochr</code></td>
+    <td>Pop the top of the stack and print it (as a character) to <code>stdout</code>.</td>
+  </tr>
+  <tr>
+    <td><code>onum</code></td>
+    <td>Pop the top of the stack and print it (as a number) to <code>stdout</code>.</td>
+  </tr>
+</table>
+
+## What Spitewaste adds
+
+A standard library! Writing a Whitespace program from scratch can be a daunting endeavor. TODO: more here.
+
+### 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.
+
+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

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+require 'spitewaste/cli'
+require 'spitewaste/cli/asm'
+require 'spitewaste/cli/exec'
+require 'spitewaste/cli/compile'
+require 'spitewaste/cli/convert'
+require 'spitewaste/cli/image'
+
+SpitewasteCLI.start ARGV

data/demo/factorial.asm

@@ -0,0 +1,47 @@
+label 0
+push 6
+call 1
+onum
+exit
+label 1
+push 1
+swap
+call 4
+dup
+dup
+dup
+push 2
+sub
+jn 3
+pop
+push -9
+swap
+push 1
+sub
+store
+label 2
+mul
+push -9
+dup
+load
+push 1
+sub
+dup
+jz 3
+store
+jump 2
+label 3
+pop
+pop
+ret
+label 4
+copy 1
+push 1
+add
+swap
+copy 1
+copy 1
+sub
+jn 4
+pop
+ret

data/demo/factorial.wsa

@@ -0,0 +1,5 @@
+main: push 6 call factorial onum exit
+factorial: push 1 swap call range dup dup dup push 2 sub jn reduce_done_a pop push -9 swap push 1 sub store
+reduce_loop_a: mul push -9 dup load push 1 sub dup jz reduce_done_a store jump reduce_loop_a
+reduce_done_a: pop pop ret
+range: copy 1 push 1 add swap copy 1 copy 1 sub jn range pop ret 

data/lib/spitewaste.rb

@@ -0,0 +1,35 @@
+module Spitewaste
+  OPERATORS_M2T = { # mnemonic to tokens
+    push:  "  ",       copy: " \t ",   slide: " \t\n",   label: "\n  ",
+    call:  "\n \t",    jump: "\n \n",  jz:    "\n\t ",   jn:    "\n\t\t",
+    pop:   " \n\n",    dup:  " \n ",   swap:  " \n\t",   add:   "\t   ",
+    sub:   "\t  \t",   mul:  "\t  \n", div:   "\t \t ",  mod:   "\t \t\t",
+    store: "\t\t ",    load: "\t\t\t", ret:   "\n\t\n",  ichr:  "\t\n\t ",
+    inum:  "\t\n\t\t", ochr: "\t\n  ", onum:  "\t\n \t", exit:  "\n\n\n",
+    shell: "\t\n\n",   eval: "\n\n\t"
+  }
+  OPERATORS_T2M = OPERATORS_M2T.invert # tokens to mnemonic
+
+  module_function
+
+  def guess_format program
+    white = program.count "\s\t\n"
+    black = program.size - white
+
+    return :whitespace if white > black
+    program[/[^-\w\s]/] ? :spitewaste : :assembly # TODO: something more robust?
+  end
+end
+
+require 'spitewaste/assembler'
+
+require 'spitewaste/parsers/spitewaste'
+require 'spitewaste/parsers/whitespace'
+require 'spitewaste/parsers/assembly'
+
+require 'spitewaste/emitter'
+require 'spitewaste/emitters/whitespace'
+require 'spitewaste/emitters/assembly'
+require 'spitewaste/emitters/wsassembly'
+require 'spitewaste/emitters/codegen'
+require 'spitewaste/emitters/image'

data/lib/spitewaste/assembler.rb

@@ -0,0 +1,56 @@
+module Spitewaste
+  class Assembler
+    attr_reader :src, :parser, :instructions
+
+    def initialize program, **options
+      format = options[:format]
+      format ||= Spitewaste.guess_format program
+      unless %i[whitespace wsassembly assembly spitewaste].include? format
+        raise ArgumentError, "unknown format for parse: #{format}"
+      end
+
+      @parser =
+        case format
+        when :whitespace
+          WhitespaceParser
+        when :assembly
+          AssemblyParser
+        else # used for both Spitewaste and Whitespace assembly
+          SpitewasteParser
+        end
+
+      parser = @parser.new(program, **options).tap &:parse
+      @instructions = parser.instructions
+      @src = parser.src if format == :spitewaste
+    end
+
+    def assemble! format:, io: STDOUT, **options
+      unless %i[whitespace wsassembly assembly codegen image].include? format
+        raise ArgumentError, "unknown format for emit: #{format}"
+      end
+
+      emitter =
+        case format
+        when :whitespace
+          WhitespaceEmitter
+        when :wsassembly
+          WSAssemblyEmitter
+        when :codegen
+          CodegenEmitter
+        when :image
+          ImageEmitter
+        else
+          AssemblyEmitter
+        end
+      emitter.new(format == :wsassembly ? @src : @instructions, **options).emit io: io
+    end
+
+    def try_elide_main
+      if @instructions.first == [:label, 0]
+        @instructions.shift unless @instructions.any? { |op, arg|
+          arg == 0 && %i[jump jz jn call].include?(op)
+        }
+      end
+    end
+  end
+end

data/lib/spitewaste/cli.rb

@@ -0,0 +1,51 @@
+require 'spitewaste'
+require 'thor'
+require 'fileutils'
+require 'pathname'
+
+class SpitewasteCLI < Thor
+  VALID_FORMATS = %i[spw spitewaste ws whitespace wsa wsassembly asm assembly]
+  CACHE_DIR = File.expand_path '~/.cache/spitewaste'
+
+  def self.exit_on_failure?
+    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,
+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'
+
+  def self.validate_format options
+    if fmt = options[:format]&.to_sym and !VALID_FORMATS.include?(fmt)
+      raise ArgumentError, "invalid format '#{fmt}'", []
+    end
+
+    Hash[*VALID_FORMATS][fmt] || fmt # expand short names
+  end
+
+  def self.make_cache_path name
+    FileUtils.mkpath CACHE_DIR
+    base = File.basename File.expand_path(name).tr(?/, ?-), '.*'
+    File.join(CACHE_DIR, base[1..]) + '.json'
+  end
+end

data/lib/spitewaste/cli/asm.rb

@@ -0,0 +1,10 @@
+class SpitewasteCLI
+  desc 'asm INPUT [OUTPUT]',
+    '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`'
+
+  def asm input, output = '/dev/stdout'
+    as = Spitewaste::Assembler.new File.read input
+    File.open(output, ?w) { |of| as.assemble! format: :assembly, io: of }
+  end
+end

data/lib/spitewaste/cli/compile.rb

@@ -0,0 +1,60 @@
+require 'open3'
+require 'stringio'
+
+class SpitewasteCLI
+  desc 'compile [OPTIONS] FILE',
+    'Compile a Whitespace program to native machine instructions.'
+
+  long_desc <<-DESC
+Under the hood, this command simply converts the input program's Whitespace
+instructions to functionally equivalent C++ code and lets a modern compiler
+do all the heavy lifting. The results are still quite good, but you'll need
+a compiler and libgmpxx (arbitrary precision) for this to do the right thing.
+DESC
+
+  option :compiler,
+    banner: 'PROG',
+    desc: 'a C++ compiler',
+    default: 'c++',
+    aliases: '-c'
+
+  option :output,
+    banner: 'FILE',
+    desc: 'the name of the executable to produce
+(defaults to input without extension, or a.out if input is from stdin)',
+    aliases: '-o'
+
+  option :argv,
+    desc: 'additional flags to provide to the C++ compiler',
+    default: '-O3 -lgmp -lgmpxx',
+    aliases: '-v'
+
+  option :run,
+    desc: 'immediately invoke the resultant executable, then remove it',
+    type: :boolean,
+    aliases: '-r'
+
+  option :keep,
+    desc: "with --run, don't remove the executable",
+    type: :boolean,
+    aliases: '-k'
+
+  def compile file = nil
+    fmt = SpitewasteCLI.validate_format options
+
+    out = options[:output]
+    out ||= file ? File.basename(file, '.*') : 'a.out'
+    file ||= '/dev/stdin'
+
+    as = Spitewaste::Assembler.new File.read(file), format: fmt
+    as.assemble! format: :codegen, io: cpp = StringIO.new
+
+    cmd = "#{options[:compiler]} -x c++ -o #{out} #{options[:argv]} -"
+    Open3.capture2 cmd, stdin_data: cpp.string
+
+    if options[:run]
+      print `./#{out}`
+      File.delete out unless options[:keep]
+    end
+  end
+end