lc3spec 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 702d428ff4102c7ad87b31a65490bbee2e07af52
-  data.tar.gz: a96200247b660e91c42642b8a085bd7609fccf23
+  metadata.gz: 5f5b656483154d73d7f647eab19d47e71b190eb4
+  data.tar.gz: 047edfaf5379bacca219828cac075a2c7c94dd7a
 SHA512:
-  metadata.gz: 22cf5b67474d74a44a70ec88c9f87062009963176bce69968311446598ac2bcdecd0331fa3289eb4f6482152ace6bf618ba511161b2109cd4f7e6c272f8a8a7f
-  data.tar.gz: 300ce687d57e631811f47c636fcd35492358c306a90afd9df8ac938c7f6b7478eeb97d9cd713a639d2775badc7bace67cead4c68215801ed27d8e4c44bb6138e
+  metadata.gz: 5b4128a0a93a20af60494639a03365a6a83e6cd4b8ba034e809494980a06a76ddc8cebf1fcabd8fb03b0c433346602a30ddcf13ba2f902019822edbb238beb24
+  data.tar.gz: 0921354e30fd9779f6bd694e29fccc8d0ab83676dedd92e9c1e97f46e6942bbec44affa380374ed07f7c1ed407a7a1cb1293a9ace383461b3d065428e3d17f56

data/README.md

@@ -28,10 +28,6 @@ set registers R0, R1, R2, R3, and R4 to 0, 1, 2, 3, and 4, respectively:
 We can write a spec, spec.rb, to test it:
 
 ```ruby
-#!/usr/bin/env ruby
-
-require 'lc3spec'
-
 test 'Register Expectations' do
   file 'regs'
   set_breakpoint 'TRAP_HALT'
@@ -45,7 +41,7 @@ test 'Register Expectations' do
 end
 ```
 
-Running with `ruby spec.rb`:
+Running with `lc3spec spec.rb`:
 
 ```
 Register Expectations [FAIL]
@@ -77,18 +73,14 @@ end
 
 There are currently two supported options:
 
-* :output - filename or file to write output to, default is $stdout
-* :keep_score - whether or not to display score for each test. If false,
+* `:output` - filename or file to write output to, default is `$stdout`
+* `:keep_score` - whether or not to display score for each test. If false,
   only `[OK]` or `[FAIL]` are displayed, if true, a fractional score
   is displayed, e.g., `0/1` or `4/4`
 
 An example:
 
 ```ruby
-#!/usr/bin/env ruby
-
-require 'lc3spec'
-
 configure do
   set :output, 'feedback.txt'
   set :keep_score, true
@@ -137,6 +129,7 @@ gem install lc3spec
 
 * Documentation
 * Tests
+* Better expectations, e.g., for arrays or strings in memory
 
 # Bugs
 

data/Rakefile

@@ -0,0 +1,6 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+task :test => :spec

data/lib/lc3spec/helpers.rb

@@ -8,10 +8,12 @@ module LC3Spec
         if number =~ /^(?:x|0x|X|0X)?([0-9A-Fa-f]{1,4})$/
           "x#{$1.rjust(4, '0').upcase}"
         else
-          raise "Unable to normalize number: #{number}"
+          raise ArgumentError, "Unable to normalize number: #{number}"
         end
       when Fixnum
         "x#{([number].pack('s>*')).unpack('H*').first.upcase}"
+      else
+        raise ArgumentError, "Expecting String or Fixnum, got #{number.class}"
       end
     end
 
@@ -29,10 +31,12 @@ module LC3Spec
 
           [num_part].pack('H*').unpack('s>*').first
         else
-          raise "Unable to normalize number: #{number}"
+          raise ArgumentError, "Unable to normalize number: #{number}"
         end
       when Fixnum
         number
+      else
+        raise ArgumentError, "Expecting String or Fixnum, got #{number.class}"
       end
     end
 

data/lib/lc3spec/lc3.rb

@@ -40,20 +40,36 @@ class LC3
     initialize_lc3sim
   end
 
+  # Get the value of a register
+  #
+  # @param [Symbol] reg the register, one of :R0 through :R7,
+  #   :PC, :IR, :PSR, or :CC
+  # @return [String, nil] the register value in hex format (e.g., 'x0000') or
+  #   nil if the register does not exist.
   def get_register(reg)
     reg = reg.to_s.upcase.to_sym  # Ruby 1.8 doesn't support Symbol#upcase
     @registers[reg]
   end
 
+  # Set the value of a register
+  #
+  # @param (see #get_register)
+  # @param [String] val the register value in hex format (e.g., 'xF1D0')
+  # @raise [ArgumentError] if the register is invalid or the value is nil,
+  # @return [self]
   def set_register(reg, val)
-    reg = reg.to_s.upcase # Don't use ! version because it doesn't work for symbols
+    reg = reg.upcase
 
     unless @registers.keys.include? reg.to_sym
-      raise "Invalid register: #{reg.to_s}"
+      raise ArgumentError, "Invalid register: #{reg.to_s}"
     end
 
     if val.nil?
-      raise "Invalid register value for #{reg.to_s}: #{val}"
+      raise ArgumentError, "Invalid register value for #{reg.to_s}: #{val}"
+    end
+
+    if reg.to_sym == :CC and not ['POSITIVE', 'NEGATIVE', 'ZERO'].include? val
+      raise ArgumentError, "CC can only be set to NEGATIVE, ZERO, or POSITIVE"
     end
 
     @io.puts "register #{reg.to_s} #{normalize_to_s(val)}"
@@ -62,21 +78,37 @@ class LC3
       msg = @io.readline
       parse_msg msg.strip
 
-      break if msg =~ /^TOCODE/
+      break if msg =~ /^ERR|TOCODE/
     end
 
     self
   end
 
+  # Return value in memory at the given address or label
+  #
+  # @param [String] addr an address in hex format (e.g., 'xADD4') or a label
+  # @raise [ArgumentError] if the argument is not a existing label or is an
+  #   invalid address
+  # @return [String] the value in memory in hex format
   def get_memory(addr)
     if addr.respond_to?(:upcase)
-      label_addr = get_address(addr)
-      addr = label_addr unless label_addr.nil?
+      label_addr = get_address(addr.upcase)
+
+      return @memory[label_addr] unless label_addr.nil?
     end
 
-    @memory[normalize_to_i(addr)]
+    @memory[normalize_to_s(addr)]
   end
 
+  # Set memory at the given address or label
+  #
+  # If val is a label, mem[addr] will be set to the address of val
+  #
+  # @param [String] addr an address or a label
+  # @param [String] val a value or a label
+  # @raise [ArgumentError] if addr is not an existing label, addr is an
+  #   invalid address, val is not an existing label, or val is invalid
+  # @return [self]
   def set_memory(addr, val)
     # addr may be memory address or label
 
@@ -88,7 +120,15 @@ class LC3
       addr = normalize_to_s(addr)
     end
 
-    @io.puts("memory #{addr} #{normalize_to_s(val)}")
+    # Value can be a label too
+    if val.respond_to?(:upcase) and @labels.include?(val.upcase.to_s)
+      # Is a label
+    else
+      # Is a value
+      val = normalize_to_s(val)
+    end
+
+    @io.puts("memory #{addr} #{val}")
 
     loop do
       msg = @io.readline
@@ -100,10 +140,21 @@ class LC3
     self
   end
 
+  # Get the address of a label
+  #
+  # @param [String] label
+  # @return [String, nil] the address of the label, or nil if the label does
+  #   not exist
   def get_address(label)
     @labels[label.upcase.to_s]
   end
 
+  # Load a file given a path
+  #
+  # @param [String] filename the path of a file to load into lc3sim. The
+  #   argument should have .obj extension or no extension at all, in which
+  #   case .obj is assumed
+  # @return [self]
   def file(filename)
     @io.puts "file #{filename}"
 
@@ -129,6 +180,9 @@ class LC3
     self
   end
 
+  # Execute one instruction
+  #
+  # @return [self]
   def step
     @io.puts 'step'
 
@@ -137,6 +191,9 @@ class LC3
     self
   end
 
+  # Execute instructions until halt or breakpoint
+  #
+  # @return [self]
   def continue
     @io.puts 'continue'
 
@@ -145,6 +202,11 @@ class LC3
     self
   end
 
+  # Set a breakpoint at an address or label
+  #
+  # @param (see #get_memory)
+  # @raise (see #get_memory)
+  # @return [self]
   def set_breakpoint(addr)
     addr = addr.upcase.to_s if addr.respond_to? :upcase
     if @labels.include? addr
@@ -163,6 +225,11 @@ class LC3
     self
   end
 
+  # Clear a breakpoint at an address or label
+  #
+  # @param (see #set_breakpoint)
+  # @raise (see #set_breakpoint)
+  # @return [self]
   def clear_breakpoint(addr)
     if addr == :all
       @io.puts 'break clear all'
@@ -187,30 +254,84 @@ class LC3
     self
   end
 
+  # Clear all breakpoints
+  #
+  # @return [self]
   def clear_breakpoints
     clear_breakpoint :all
   end
 
+  # Return output from the LC-3
+  #
+  # The LC-3 welcome messages and halt messages are stripped from the output,
+  # so that it can easily compared to expected output.
+  #
+  # WARNING: This is potentially buggy as there is no signal from lc3sim when
+  # the output is ready, so this function just waits until output appears and
+  # reads what is available. This may not work if the output is very long.
+  #
+  # @return [String] the output from the LC-3, or an empty string
+  #   if there is no output
   def get_output
     out = ''
 
+    # Do something to wait for output to be ready
+    set_register(:PSR, @registers[:PSR])
+
     # There is no signal that tells the GUI that output is ready...
     # FIXME: This is a bug waiting to happen
-    retries = 10
-    until @output.ready?
-      sleep(0.1)
-
-      retries -= 1
-      break if retries <= 0
-    end
-
-    while @output.ready?
-      out << @output.readpartial(1024)
+    catch(:done) do
+      loop do
+        retries = 5
+        until @output.ready?
+          sleep(0.1)
+
+          retries -= 1
+          throw :done if retries <= 0
+        end
+
+        while @output.ready?
+          out << @output.readpartial(1024)
+        end
+      end
     end
 
     out.gsub("\n\n--- halting the LC-3 ---\n\n", '')
   end
 
+  # Close open file descriptors for communicating with lc3sim
+  #
+  # @return [nil]
+  def close
+    @io.close
+    @output.close
+    @server.close
+  end
+
+  # Return a string containing a human-readable representation of the current
+  #   state of the LC-3
+  #
+  # @return [String]
+  def inspect
+    registers = @registers.map { |k, v| "#{k}=#{v}" }.join(' ')
+
+    addr_to_label = @labels.invert
+
+    memory_header = "%18s ADDR  VALUE" % "label"
+    memory = @memory.map do |addr, value|
+      "%18s %s %s" % [(addr_to_label[addr] or ''), addr, value]
+    end.join("\n")
+
+    #[memory_header, memory, registers].join("\n")
+    registers
+  end
+
+  # def to_s
+  #   @registers.map { |k, v| "#{k}=#{v}" }.join(' ')
+  # end
+
+  private
+
   def initialize_lc3sim
     # Start lc3sim instance
     @io = IO.popen(%w(lc3sim -gui), 'r+')
@@ -244,32 +365,6 @@ class LC3
     end
   end
 
-  def close
-    @output.close
-    @server.close
-  end
-
-  def inspect
-    registers = @registers.map { |k, v| "#{k}=#{v}" }.join(' ')
-
-    addr_to_label = @labels.invert
-
-    memory_header = "%18s ADDR  VALUE" % "label"
-    memory = @memory.map do |addr, value|
-      "%18s %s %s" % [(addr_to_label[addr] or ''),
-                      normalize_to_s(addr), value]
-    end.join("\n")
-
-    #[memory_header, memory, registers].join("\n")
-    registers
-  end
-
-  # def to_s
-  #   @registers.map { |k, v| "#{k}=#{v}" }.join(' ')
-  # end
-
-  private
-
   def parse_until_print_registers
     loop do
       msg = @io.readline
@@ -296,23 +391,21 @@ class LC3
     when 'BCLEAR'
     when 'BREAK'
     when 'CODE', 'CODEP'  # Line of code
-      # Address
-      addr = tokens.shift.to_i - 1
+      # Numeric address
+      num_addr = tokens.shift.to_i - 1
 
       # Note: if there is a breakpoint at the current address, the last
-      # token.shift produces a string like "12289B". Luckily, #to_i just
-      # ignores the B at the end.
+      # token.shift produces a string like "12289B". Luckily, to_i just
+      # reads whatever it can and discards the rest.
 
       # Label, if present
-      if tokens.first != "x%04X" % addr
-        label = tokens.shift.upcase
+      label = tokens.first != "x%04X" % num_addr ? tokens.shift.upcase : nil
 
-        # Don't overwrite label if one already exists
-        @labels[label] ||= addr
-      end
+      # hex address
+      addr = tokens.shift
 
-      # Discard hex address
-      tokens.shift
+      # Insert label, but don't overwrite if it already exists
+      @labels[label] ||= addr if not label.nil?
 
       # Value
       val = tokens.shift

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lc3spec
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Chun Yang
@@ -9,7 +9,21 @@ autorequire:
 bindir: bin
 cert_chain: []
 date: 2013-02-27 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: DSL for testing LC-3 assembly programs
 email: x@cyang.info
 executables:
@@ -30,6 +44,7 @@ files:
 - bin/lc3spec
 - LICENSE
 - README.md
+- Rakefile
 homepage: http://github.com/chunyang/lc3spec
 licenses:
 - MIT