base-lang 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 352641028b34da47dec624f8cb3e135e6c336e47f854931649104b0c9a29629c
+  data.tar.gz: 490c1fa4fd25ec278bf2dd12e67f0cecc1b53da7a3eee848daee81121ddbff4e
+SHA512:
+  metadata.gz: b7d1e64864df4c093c56c70c2d212013c926082e213f8aad86ead4120e2f3cb0da5df3153402fa0a70da5716723a71163a1172a23a6a577cee4e23e5337725ed
+  data.tar.gz: 054abcc979edead6e60520bba2926a7614899fe73e349f81418ac87b617829de6d196b98c85b7f8156fb27b727a3fc45c0641440a5d8cdbc1667b133be145d54

data/README.md

@@ -0,0 +1,124 @@
+# Base
+
+A simple stack-based assembly programming language and VM, made for learning.
+
+## Using it
+
+Enter a simple program:
+
+    # alphabet.base
+
+    .main
+      push "A"
+
+    .loop
+      # Print letter to the screen
+      duplicate
+      out
+
+      # Check whether we've reached Z yet
+      duplicate
+      push "Z"
+      subtract
+
+      # If we have, we're done
+      push done
+      betz
+
+      # Advance to the next letter and loop
+      push 1
+      add
+      push loop
+      jump
+
+    .done
+      # Program ends
+      discard
+      push "\n"
+      out
+      halt
+
+Run it:
+
+    % gem install base-lang
+
+    % base alphabet.base
+    ABCDEFGHIJKLMNOPQRSTUVWXYZ
+
+## Language
+
+All instructions take no arguments except the `push` instruction which takes the value to push to the stack.
+
+Values may be an integer, a single character in double quotes, a label, or the special text `ip` which refers to
+the current instruction pointer.
+
+Signed integers of arbitrary size can be used.  Memory locations start at 0 and by default to up to 1MB (1048575).
+
+operation | op code | stack impact | description
+-|-|-|-
+debug | 0 | | enters the debugger
+push (value or label) | 1, value | + | pushes the value onto the stack
+discard | 2 | - | discards the top entry on the stack
+duplicate | 3 | + | duplicates the top entry on the stack
+write | 4 | -- | writes the second entry on the stack to the memory location at the top entry on the stack
+read | 5 | -+ | reads from the memory location on the stack and puts the result on the stack
+add | 6 | --+ | adds the top two entries on the stack and puts the result on the stack
+subtract | 7 | --+ | subtracts the top entry on the stack from the second entry on the stack and puts the result on the stack
+jump | 8 | - | jumps to the location indicated by the top entry on the stack
+bltz | 9 | -- | jumps to the location indicated by the top entry on the stack if the second entry on the stack is less than 0
+bgtz | 10 | -- | jumps to the location indicated by the top entry on the stack if the second entry on the stack is greater than 0
+betz | 11 | -- | jumps to the location indicated by the top entry on the stack if the second entry on the stack is equal to 0
+bnetz | 12 | -- | jumps to the location indicated by the top entry on the stack if the second entry on the stack is not equal to 0
+out | 13 | - | outputs the top entry on the stack to stdout, interpreted as a unicode character
+halt | 13 | | halts the program
+
+## Compiler
+
+Any text including and after a `#` in the code is treated as a comment and ignored.
+
+### Labels and data
+
+You can use labels to mark a place in the code:
+
+    # infinite loop
+    .marker
+    push marker
+    jump
+
+`.main` is a special label. If specified, code execution will start at this point.
+
+You can also use labels to introduce data:
+
+    .three_bytes 1, 2, 3
+
+The data can also be a string, which is interpreted as a list of bytes, or a mix of the two
+
+    .message "Hello!", 10, 0
+
+### Macros
+
+Simple macros can be defined as a comma-separated list of operations (or other macros, as long as they don't recurse):
+
+   macro increment push 1, add
+
+   push "A"
+   increment
+   out # outputs a "B"
+
+You'll need to define a macro before you use it in your file.
+
+## Debugger
+
+Base has an integrated debugger that allows you to trace through your code, view memory and stack, and disassemble code.
+
+You can start it by calling `debug` in your program, or by running `base` with the `--debug` option in which case
+it'll start immediately on program startup.
+
+When in the debugger, type `h` for help.
+
+## Licence and contributing
+
+MIT licence.
+
+Feel free to contribute!  It's intentionally simple, so the intention isn't to add any more operations than what is
+there.

data/bin/base

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require_relative "../lib/base"
+
+options = {}
+OptionParser.new do |parser|
+  parser.banner = "Usage: base [options] filename.base"
+
+  parser.on("-d", "--debug", "Start debugger immediately") do
+    options[:debug] = true
+  end
+
+  parser.on("-c", "--compile", "Compile only and output program code") do
+    options[:compile] = true
+  end
+
+  parser.on("-h", "--help", "Prints this help") do
+    puts parser
+    exit 1
+  end
+end.parse!
+
+if ARGV.length != 1
+  $stderr.puts("one source file must be specified")
+  exit 1
+end
+
+begin
+  program = Base::Compiler.new.compile(ARGV[0])
+
+  if options[:compile]
+    puts program.join(",")
+  else
+    Base::VM.new(program, debug: options[:debug] || false).run
+  end
+
+rescue Base::Compiler::Error, Base::VM::Error => e
+  $stderr.puts("error: #{e.message}")
+end

data/lib/base/compiler.rb

@@ -0,0 +1,150 @@
+module Base
+  class Compiler
+    Error = Class.new(StandardError)
+
+    def initialize
+      @parsing = []
+      @memory = []
+      @labels = {}
+      @macros = {}
+    end
+
+    def compile(file)
+      lines = File.read(file).split("\n")
+      parse(lines)
+
+      main = @labels["main"] || 0
+      [main] + @memory
+    end
+
+    private
+
+    def parse(lines)
+      lines.each.with_index do |line, index|
+        begin
+          parse_line(line, index + 1)
+        rescue Error => e
+          raise Error, "#{e.message} on line #{index + 1}"
+        end
+      end
+
+      @parsing.each do |index, line_number|
+        begin
+          @memory[index] = parse_arg(@memory[index], index)
+        rescue Error => e
+          raise Error, "#{e.message} on line #{line_number}"
+        end
+      end
+    end
+
+    def parse_line(line, number, macro_entry = [])
+      line = line.gsub(/#(.+)/, '').strip
+      case line
+      when ""
+        nil
+
+      when /\A\.([a-z_][a-z0-9_]*)(?:\s+(.+))?\z/i
+        raise Error, "label already defined" if @labels[$1]
+        raise Error, "can't use 'ip' as a label name" if $1 == 'ip'
+        @labels[$1] = @memory.length
+        @memory += parse_static($2) if $2
+
+      when /\Apush\s+(.+)\z/
+        @memory += [VM::COMMANDS.index("push"), $1]
+        @parsing << [@memory.length - 1, number]
+
+      when /\Amacro\s+(\S+)\s+(.+)/
+        raise Error, "label already defined" if @macros[$1]
+        raise Error, "macros cannot replace base instructions" if VM::COMMANDS.member?($1)
+        @macros[$1] = $2.split(/\s*,\s*/)
+
+      else
+        if op_code = VM::COMMANDS.index(line)
+          @memory << op_code
+        elsif macro = @macros[line]
+          if macro_entry.include?(macro)
+            raise Error, "recursive call to macro #{macro}"
+          end
+
+          macro.each do |macro_line|
+            parse_line(macro_line, number, macro_entry + [macro])
+          end
+        else
+          raise Error, "unknown command '#{line}'"
+        end
+      end
+    end
+
+    def parse_arg(arg, location)
+      case arg
+      when '"\n"'
+        "\n".ord
+      when /\A"\\?([^"])"\z/
+        $1.ord
+      when "ip"
+        location - 1
+      when /\A(-?[0-9]+)\z/
+        $1.to_i
+      when /\A([a-z_][a-z0-9_]*)\z/i
+        @labels[$1] or raise Error, "no such label '#{$1}'"
+      else
+        raise Error, "unknown argument '#{arg}'"
+      end
+    end
+
+    def parse_static(arg)
+      chars = arg.chars
+      output = []
+      buffer = ""
+      state = :start
+
+      loop do
+        char = chars.shift
+        if char == "-" && state == :start
+          buffer = "-"
+          state == :number
+        elsif ("0".."9").include?(char) && [:start, :number].include?(state)
+          buffer += char
+          state = :number
+        else
+          if state == :number
+            output << buffer.to_i
+            buffer = ""
+            state = :start
+          end
+
+          if char.nil?
+            if state == :start
+              break output
+            else
+              raise Error, "invalid data"
+            end
+          end
+
+          if [',', ' '].include?(char) && state == :start
+            nil
+          elsif char == '"' && state == :start
+            state = :string
+          elsif char == '"' && state == :string
+            output += buffer.chars.map(&:ord)
+            buffer = ""
+            state = :start
+          elsif char == '\\' && state == :string
+            state = :escape
+          elsif state == :string
+            buffer << char
+          elsif state == :escape
+            if char == "n"
+              buffer << "\n"
+            else
+              buffer << char
+            end
+            state = :string
+          else
+            raise Error, "invalid data"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/base/debugger.rb

@@ -0,0 +1,87 @@
+module Base
+  class Debugger
+    attr_reader :vm
+
+    PUSH = VM::COMMANDS.index("push")
+
+    def initialize(vm)
+      @vm = vm
+    end
+
+    def debug
+      loop do
+        next_instruction = memory[ip] == PUSH ? "push #{memory[ip + 1]}" : VM::COMMANDS[memory[ip]] || "???"
+        puts "ip=#{ip} stack=#{stack.inner} #{next_instruction}"
+        print "> "
+
+        command = $stdin.gets&.strip
+        case command
+        when ""
+          nil
+        when "n"
+          return true
+        when "c", nil
+          return false
+        when "q"
+          exit
+        when /\Am(?:\s+([0-9]+))?(?:\s+([0-9]+))?/
+          memory_dump($1 && $1.to_i || 0, $2 && $2.to_i)
+        when /\Ad(?:\s+([0-9]+))?(?:\s+([0-9]+))?/
+          disassemble($1 && $1.to_i || ip, $2 && $2.to_i)
+        else
+          puts "n - next instruction"
+          puts "c - stop debugging and continue"
+          puts "m [start [length]] - dump memory"
+          puts "d [start [length]] - disassemble"
+          puts "q - quit"
+        end
+      end
+    end
+
+    private
+
+    def memory
+      vm.memory
+    end
+
+    def ip
+      vm.ip
+    end
+
+    def stack
+      vm.stack
+    end
+
+    def memory_dump(location, length)
+      data = memory[location..(length ? location + length - 1 : -1)]
+
+      data.each_slice(8).with_index.each do |slice, index|
+        print "%8d | " % (location + index * 8)
+        slice.each do |byte|
+          print "%4d " % byte
+        end
+        puts
+      end
+    end
+
+    def disassemble(location, length)
+      end_location = length ? location + length : memory.length
+
+      while location < end_location && memory[location]
+        initial_location = location
+        op_code = memory[location]
+
+        if op_code == PUSH
+          value = memory[location + 1]
+          instruction = "push #{value}"
+          location += 2
+        else
+          instruction = VM::COMMANDS[op_code] || "#{op_code}???"
+          location += 1
+        end
+
+        puts "%8d | %s" % [initial_location, instruction]
+      end
+    end
+  end
+end

data/lib/base/stack.rb

@@ -0,0 +1,25 @@
+module Base
+  class Stack
+    Error = Class.new(StandardError)
+
+    def initialize
+      @stack = []
+    end
+
+    def push(value)
+      @stack.push(value)
+    end
+
+    def pop
+      @stack.pop or raise Error, "pop requested on empty stack"
+    end
+
+    def empty?
+      @stack.empty?
+    end
+
+    def inner
+      @stack
+    end
+  end
+end

data/lib/base/vm.rb

@@ -0,0 +1,122 @@
+module Base
+  class VM
+    Error = Class.new(StandardError)
+
+    MAX_MEMORY = 1048576
+
+    attr_reader :ip, :stack, :memory
+
+    COMMANDS = %w(debug push discard duplicate write read add subtract jump bltz bgtz betz bnetz out halt)
+
+    def initialize(program, debug: false)
+      @ip = program.shift
+      @memory = program
+      @debug = debug
+      @stack = Stack.new
+    end
+
+    def run
+      loop do
+        raise Error, "IP reached end of memory" if memory[ip].nil?
+
+        @debug = Debugger.new(self).debug if @debug
+
+        begin
+          result = execute
+          break if result == :halt
+        rescue Error => e
+          $stderr.puts("error: #{e.message}")
+          @debug = true
+        end
+      end
+
+      raise Error, "warning: stack not empty at program termination, #{stack.inner}" unless @stack.empty?
+    end
+
+    private
+
+    def execute
+      case COMMANDS[memory[ip]]
+      when "debug"
+        @debug = true
+
+      when "halt"
+        return :halt
+
+      when "push"
+        @ip += 1
+        arg = memory[ip]
+        stack.push(arg)
+
+      when "discard"
+        stack.pop
+      when "duplicate"
+        value = stack.pop
+        stack.push(value)
+        stack.push(value)
+
+      when "write"
+        location = stack.pop
+        value = stack.pop
+        write(location, value)
+      when "read"
+        location = stack.pop
+        stack.push(read(location))
+
+      when "add"
+        a = stack.pop
+        b = stack.pop
+        stack.push(a + b)
+      when "subtract"
+        a = stack.pop
+        b = stack.pop
+        stack.push(b - a)
+
+      when "jump"
+        @ip = stack.pop - 1
+      when "bltz"
+        dest = stack.pop
+        test = stack.pop
+        @ip = dest - 1 if test < 0
+      when "bgtz"
+        dest = stack.pop
+        test = stack.pop
+        @ip = dest - 1 if test > 0
+      when "betz"
+        dest = stack.pop
+        test = stack.pop
+        @ip = dest - 1 if test == 0
+      when "bnetz"
+        dest = stack.pop
+        test = stack.pop
+        @ip = dest - 1 if test != 0
+
+      when "out"
+        print(stack.pop.chr)
+      else
+        raise Error, "invalid op code #{memory[ip]}"
+      end
+
+      @ip += 1
+    rescue Error, Stack::Error => e
+      raise Error, "#{e.message} at IP #{ip}"
+    end
+
+    private
+
+    def read(location)
+      validate_location(location)
+      memory[location] || 0
+    end
+
+    def write(location, value)
+      validate_location(location)
+      memory[location] = value
+    end
+
+    def validate_location(location)
+      raise Error, "locations must be non-negative" if location < 0
+      raise Error, "locations must be less than #{MAX_MEMORY}" if location >= MAX_MEMORY
+    end
+  end
+end

data/lib/base.rb

@@ -0,0 +1,4 @@
+require_relative 'base/stack'
+require_relative 'base/compiler'
+require_relative 'base/vm'
+require_relative 'base/debugger'

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: base-lang
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mog Nesbitt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-03-26 00:00:00.000000000 Z
+dependencies: []
+description: A simple stack-based assembly programming language and VM, made for learning.
+email: mog@seriousorange.com
+executables:
+- base
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/base
+- lib/base.rb
+- lib/base/compiler.rb
+- lib/base/debugger.rb
+- lib/base/stack.rb
+- lib/base/vm.rb
+homepage: https://github.com/mogest/base-lang
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: A simple assembly language, compiler and VM
+test_files: []