logicle 0.1.0

data/.gitignore

@@ -0,0 +1,13 @@
+# emacs
+*~
+\#*\#
+
+# Ruby / Rubygems
+*.gem
+
+# Bundler
+.bundle
+vendor/bundle
+
+# Misc
+*.gml

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org/"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,8 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES

data/README.md

@@ -0,0 +1,43 @@
+# Academic Exercise: Digital Logic Simulator
+
+_written by Gregory Brown for Mendicant University core skills session #9_
+
+I had a lot of fun coming up with the ["All Wired Up" PuzzleNode problem](http://puzzlenode.com/puzzles/18) 
+that was part of this session's entrance 
+exam. At the time I was writing it, I had thought about building a more 
+generally useful tool for playing around with simulated digital circuits, 
+but then I quickly got too busy to look into it further.
+
+Then, I started playing Minecraft and my interest in circuitry simulations was
+reignited! The game has a [full circuitry system](http://www.minecraftwiki.net/wiki/Redstone_circuits) for doing all sorts of fun logical
+processing based on the most primitive inputs. But Minecraft is much better
+as a game than as a learning environment, and it can be a very frustrating
+and tedious environment to try to study circuitry in. I want a tool that
+doesn't make me afraid of being attacked by zombies while I build my logic
+gates!
+
+In this exercise, I would like you to build a tool that makes exploring
+digital circuitry fun and interesting. The summary below provides some
+suggestions on what things in particular I have in mind, but everyone
+should be able to come up with their own unique take on the idea without
+too much overlap.
+
+## Exercise Summary
+
+- You should create a tool that makes exploring and learning about
+  logical circuitry fun and interesting.
+- You can use the "All Wired Up" problem and MineCraft's Redstone circuits
+  as an inspiration, but be sure to have some fresh ideas of your own.
+- You should be able to build modular gates that can be re-used in other circuits.
+- The way you handle input and output visualization is completely up to 
+  you
+- Your tool should be easy to work with for someone who wants to explore circuitry but is not necessarily a programmer.
+- It should be possible to assign inputs, evaluate the circuits, and then inspect their outputs.
+- Some sort of friendly debugging process and tools would be nice to have.
+
+## Submission Guidelines
+
+If you plan to work on this exercise, you should fork this repository 
+and push code early and often during the course. The course 
+guidelines PDF explains the submission process in detail, but please 
+contact an instructor if you have any questions.

data/Rakefile

@@ -0,0 +1,11 @@
+require "rake/testtask"
+
+
+task :default => "test"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/*_test.rb"]
+  t.verbose = true
+end
+

data/bin/logicle

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+require "logicle"
+
+
+USAGE_MESSAGE = "logicle <CIRCUIT FILE TO SOLVE> "
+
+
+# Exit with usage message if user forgets to provide an input file.
+Kernel.abort(USAGE_MESSAGE) if ARGV.length == 0
+
+
+# Capture inputs from the command line.
+circuit_file = ARGV.shift
+
+
+# Instantiate the Logicle::Simulator instance.
+simulator = Logicle::Simulator.new(circuit_file)
+puts "Loaded main circuit from file: #{ circuit_file }"
+
+
+# Prompt the user to enter states for each of the switch inputs.
+switches = simulator.inputs
+puts "The circuit to be solved requires #{ switches.count } input values (on/off)."
+
+switches.each_with_index do |switch, index|
+  $stdout.printf("Switch %d on? (Y/n):>> ", index + 1)
+  input = $stdin.gets.chomp.downcase.chars.first
+  case input
+  when "y"
+    switch.type = :on
+  when "n"
+    switch.type = :off
+  else
+    puts "Invalid input!"
+    redo
+  end
+end
+
+
+# Evaluate the circuit.
+simulator.evaluate
+bulbs = simulator.outputs
+
+
+# Print out the bulb states.
+bulbs.each_with_index do |bulb, i|
+  puts "Bulb \##{ i + 1 }:  #{ bulb.state ? "on" : "off" }"
+end
+
+
+# Ask the user to save the result file.
+$stdout.write "Save output? (y/N): "
+save_output_flag = $stdin.gets.chomp
+
+if save_output_flag =~ /\Ay/i
+  output_filename = File.realdirpath(circuit_file).sub(/\.tgf\Z/, "_solved.tgf")
+  simulator.save(output_filename)
+end

data/examples/simple.tgf

@@ -0,0 +1,14 @@
+1 NOT
+2 AND
+3 OR
+4 SWITCH
+5 SWITCH
+6 SWITCH
+7 BULB
+#
+4 1
+5 2
+6 2
+2 3
+1 3
+3 7

data/examples/simple_solved.tgf

@@ -0,0 +1,14 @@
+1 NOT (OFF)
+2 AND (ON)
+3 OR (ON)
+4 SWITCH (ON)
+5 SWITCH (ON)
+6 SWITCH (ON)
+7 BULB (ON)
+#
+4 1
+5 2
+6 2
+2 3
+1 3
+3 7

data/lib/logicle.rb

@@ -0,0 +1,20 @@
+require_relative "logicle/version"
+require_relative "logicle/logicle"
+require_relative "logicle/simulator"
+require_relative "logicle/tgf_reader"
+require_relative "logicle/tgf_writer"
+
+require_relative "logicle/node"
+require_relative "logicle/digraph"
+
+module Logicle
+
+  # Raised when trying to create an edge in the graph to or from an unknown node
+  class UnknownNodeError < StandardError; end
+
+  # Raised in case of error while reading an input file 
+  class ParseError < StandardError; end
+
+  # Raised when trying to create a node with an unknown type.
+  class UnknownNodeTypeError < StandardError; end
+end

data/lib/logicle/digraph.rb

@@ -0,0 +1,53 @@
+module Logicle
+  class Digraph
+    attr_reader :nodes, :edges
+
+    def initialize
+      @nodes, @edges = {}, {}
+    end
+
+    def evaluate
+      outputs.each_value do |output|
+        output.state
+      end
+    end
+
+    def inputs
+      @nodes.select { |id, node| node.switch? }
+    end
+
+    def outputs
+      @nodes.select { |id, node| node.bulb? }
+    end
+
+    def add_node(id, node_type)
+      @nodes[id] = Node.new(id, node_type)
+    end
+
+    def add_edge(start_id, end_id)
+      start_node, end_node = @nodes[start_id], @nodes[end_id]
+
+      if start_node && end_node 
+        end_node.append_input(start_node)
+        @edges[start_id] = end_id
+        true
+      else
+        raise_unknown_nodes(start_id => start_node, end_id => end_node)
+      end
+    end
+
+    private
+    def raise_unknown_nodes(node_map={})
+      bad_node_ids = node_map.select { |id, node| node.nil? }.keys 
+
+      case bad_node_ids.count
+      when 0
+        return
+      when 1
+        raise UnknownNodeError, "Invalid node id: #{ bad_node_ids[0] }"
+      else
+        raise UnknownNodeError, "Invalid node ids: #{ bad_node_ids.join(", ") }"
+      end
+    end
+  end
+end

data/lib/logicle/logicle.rb

@@ -0,0 +1,3 @@
+module Logicle
+  FILE_SUFFIX = ".tgf"
+end

data/lib/logicle/node.rb

@@ -0,0 +1,65 @@
+module Logicle
+  class Node
+    LOGIC_OPERATIONS = {
+      switch: Proc.new { |args| nil },
+      bulb:   Proc.new { |args| args[0].state },
+      on:     Proc.new { |args| true },
+      off:    Proc.new { |args| false },
+      not:    Proc.new { |args| !args[0].state },
+      and:    Proc.new { |args| args[0].state & args[1].state },
+      or:     Proc.new { |args| args[0].state | args[1].state },
+      nand:   Proc.new { |args| !args[0].state | !args[1].state },
+      nor:    Proc.new { |args| !args[0].state & !args[1].state },
+      xor:    Proc.new { |args| args[0].state ^ args[1].state },
+      xnor:   Proc.new { |args| !(args[0].state ^ args[1].state) }
+    }
+
+    attr_reader   :id, :type, :inputs
+
+    def initialize(id, type)
+      @id = id
+      @type = validate_type(type)
+      @inputs = []
+    end
+
+    def bulb?
+      @type == :bulb
+    end
+
+    def switch?
+      @type == :switch
+    end
+
+    def type=(new_type)
+      @type = validate_type(new_type)
+    end
+
+    def append_inputs(*nodes)
+      @inputs += nodes
+    end
+    alias_method :append_input, :append_inputs
+
+    def clear_inputs
+      @inputs = []
+      @state = nil
+    end
+
+    def state
+      @state ||= evaluate
+    end
+
+    private
+    def validate_type(type)
+      if LOGIC_OPERATIONS.keys.include?(type)
+        type
+      else
+        raise UnknownNodeTypeError, "Unknown node type: '#{ type }'"
+      end
+    end
+
+    def evaluate
+      operation = LOGIC_OPERATIONS[@type]
+      operation.call(@inputs)
+    end
+  end
+end

data/lib/logicle/simulator.rb

@@ -0,0 +1,35 @@
+module Logicle
+  class Simulator
+    attr_reader  :circuit
+
+    def initialize(*circuits)
+      @circuit = load(circuits.shift)
+      unless circuits.empty?
+        @sub_circuits = circuits.map { |circuit_file| load(circuit_file) }
+      end
+    end
+
+    def inputs
+      @circuit.inputs.values
+    end
+
+    def outputs
+      @circuit.outputs.values
+    end
+
+    def evaluate
+      @circuit.evaluate
+    end
+
+    def save(output_file)
+      writer = TgfWriter.new(output_file, @circuit)
+      writer.write
+    end
+
+    private
+    def load(circuit_file)
+      reader = TgfReader.new(circuit_file)
+      @circuit = reader.parse
+    end
+  end
+end

data/lib/logicle/tgf_reader.rb

@@ -0,0 +1,52 @@
+module Logicle
+  class TgfReader
+    def initialize(input)
+      if File.exists?(input)
+        @contents = File.readlines(input)    # read file for TGF content
+      else
+        @contents = input.lines              # use string param as TGF content
+      end
+    end
+
+    def parse
+      @circuit = Digraph.new
+      still_reading_nodes = true
+
+      @contents.each do |line|
+        line.chomp!
+
+        if line =~ /\A#/
+          still_reading_nodes = false
+        elsif still_reading_nodes
+          node_directive(line)
+        else
+          edge_directive(line)
+        end
+      end
+
+      @circuit
+    end
+
+    private
+    def node_directive(text)
+      if text =~ /\A(\d+)\s+(.*)\Z/
+        id, label = $1, $2
+        @circuit.add_node(id, label.downcase.to_sym)
+      else
+        raise ParseError, "Unable to parse TGF node directive: '#{ text }'"
+      end
+    rescue UnknownNodeTypeError
+      raise ParseError, "Unknown node type in directive: '#{ label }'"
+    end
+
+    def edge_directive(text)
+      if text =~ /\A(\d+)\s+(\d+)\Z/
+        start, finish = $1, $2
+        @circuit.add_edge(start, finish)
+      else
+        raise ParseError, "Unable to parse TGF edge directive: '#{ text }'"
+      end
+    end
+  end
+end
+

data/lib/logicle/tgf_writer.rb

@@ -0,0 +1,38 @@
+module Logicle
+  class TgfWriter
+    def initialize(filename, circuit)
+      @output_file = File.open(filename, "w")
+      @circuit = circuit
+    end
+
+    def write
+      @circuit.nodes.values.each { |node| write_node(node) }
+
+      write_separator
+
+      @circuit.edges.each { |start, finish| write_edge(start, finish) }
+    end
+
+    private
+    def write_node(node)
+      id = node.id
+      type = case node.type
+      when :on, :off 
+        "SWITCH"
+      else 
+         node.type.to_s.upcase
+      end
+      state = node.state ? "ON" : "OFF"
+
+      @output_file.puts "#{ id } #{ type } (#{ state })"
+    end
+
+    def write_separator
+      @output_file.puts "#"
+    end
+
+    def write_edge(start_id, end_id)
+      @output_file.puts "#{ start_id } #{ end_id }"
+    end
+  end
+end

data/lib/logicle/version.rb

@@ -0,0 +1,3 @@
+module Logicle
+  VERSION = "0.1.0"
+end

data/logicle.gemspec

@@ -0,0 +1,23 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "logicle/version"
+
+Gem::Specification.new do |s|
+  s.name        = "logicle"
+  s.version     = Logicle::VERSION
+  s.authors     = ["Chris kottom"]
+  s.email       = "chris@chriskottom.com"
+  s.homepage    = ""
+  s.summary     = %q{A simulator for playing with digital circuit logic}
+  s.description = %q{Logicle is a simulator for testing and solving simple circuits composed of basic logical elements. The program reads and writes its inputs and outputs using the GML protocol.}
+
+  s.rubyforge_project = "logicle"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = ["logicle"]
+  s.require_paths = ["lib", "vendor"]
+
+  # specify any dependencies here; for example:
+  # s.add_development_dependency "rspec"
+  # s.add_runtime_dependency "rest-client"
+end

data/test/digraph_test.rb

@@ -0,0 +1,34 @@
+require_relative "test_helper"
+
+require "test/unit"
+
+
+class DigraphTest < Test::Unit::TestCase
+  include TestHelper
+
+  def test_add_node
+    start_node_count = digraph.instance_variable_get(:@nodes).count
+    digraph.add_node(1, :and)
+    assert_equal(start_node_count + 1, 
+                 digraph.instance_variable_get(:@nodes).count)
+  end
+
+  def test_add_edge
+    start_edge_count = digraph.instance_variable_get(:@edges).count
+    digraph.add_node(1, :and)
+    digraph.add_node(2, :or)
+    digraph.add_edge(1, 2)
+    assert_equal(start_edge_count + 1,
+                 digraph.instance_variable_get(:@edges).count)
+
+    nodes = digraph.instance_variable_get(:@nodes) 
+    assert(nodes[2].inputs.include?(nodes[1]))
+  end
+
+  def test_add_edge_with_unknown_node
+    assert_raises(Logicle::UnknownNodeError) do
+      digraph.add_node(1, :and)
+      digraph.add_edge(1, 2)
+    end
+  end
+end

data/test/logicle_test.rb

@@ -0,0 +1,8 @@
+require_relative "test_helper"
+
+require "test/unit"
+
+
+class LogicleTest < Test::Unit::TestCase
+
+end

data/test/node_test.rb

@@ -0,0 +1,92 @@
+require_relative "test_helper"
+
+require "test/unit"
+
+
+class NodeTest < Test::Unit::TestCase
+  include TestHelper
+
+  def test_on_node
+    assert_equal(true, node(:on).state)
+  end
+
+  def test_off_node
+    assert_equal(false, node(:off).state)
+  end
+
+  def test_not_node
+    not_node = node(:not)
+    on_node = node(:on)
+    off_node = node(:off)
+
+    assert_node_state_for_inputs(false, not_node, on_node)
+    assert_node_state_for_inputs(true, not_node, off_node)
+  end
+
+  def test_and_node
+    and_node = node(:and)
+    on_node = node(:on)
+    off_node = node(:off)
+
+    assert_node_state_for_inputs(true, and_node, on_node, on_node)
+    assert_node_state_for_inputs(false, and_node, on_node, off_node)
+    assert_node_state_for_inputs(false, and_node, off_node, on_node)
+    assert_node_state_for_inputs(false, and_node, off_node, off_node)
+  end
+
+  def test_or_node
+    or_node = node(:or)
+    on_node = node(:on)
+    off_node = node(:off)
+
+    assert_node_state_for_inputs(true, or_node, on_node, on_node)
+    assert_node_state_for_inputs(true, or_node, on_node, off_node)
+    assert_node_state_for_inputs(true, or_node, off_node, on_node)
+    assert_node_state_for_inputs(false, or_node, off_node, off_node)
+  end
+
+  def test_nand_node
+    nand_node = node(:nand)
+    on_node = node(:on)
+    off_node = node(:off)
+
+    assert_node_state_for_inputs(false, nand_node, on_node, on_node)
+    assert_node_state_for_inputs(true, nand_node, on_node, off_node)
+    assert_node_state_for_inputs(true, nand_node, off_node, on_node)
+    assert_node_state_for_inputs(true, nand_node, off_node, off_node)
+  end
+
+  def test_nor_node
+    nor_node = node(:nor)
+    on_node = node(:on)
+    off_node = node(:off)
+
+    assert_node_state_for_inputs(false, nor_node, on_node, on_node)
+    assert_node_state_for_inputs(false, nor_node, on_node, off_node)
+    assert_node_state_for_inputs(false, nor_node, off_node, on_node)
+    assert_node_state_for_inputs(true, nor_node, off_node, off_node)
+  end
+
+  def test_xor_node
+    xor_node = node(:xor)
+    on_node = node(:on)
+    off_node = node(:off)
+
+    assert_node_state_for_inputs(false, xor_node, on_node, on_node)
+    assert_node_state_for_inputs(true, xor_node, on_node, off_node)
+    assert_node_state_for_inputs(true, xor_node, off_node, on_node)
+    assert_node_state_for_inputs(false, xor_node, off_node, off_node)
+  end
+
+  def test_xnor_node
+    xnor_node = node(:xnor)
+    on_node = node(:on)
+    off_node = node(:off)
+
+    assert_node_state_for_inputs(true, xnor_node, on_node, on_node)
+    assert_node_state_for_inputs(false, xnor_node, on_node, off_node)
+    assert_node_state_for_inputs(false, xnor_node, off_node, on_node)
+    assert_node_state_for_inputs(true, xnor_node, off_node, off_node)
+  end
+
+end

data/test/simple.tgf

@@ -0,0 +1,14 @@
+1 NOT
+2 AND
+3 OR
+4 SWITCH
+5 SWITCH
+6 SWITCH
+7 BULB
+#
+4 1
+5 2
+6 2
+2 3
+1 3
+3 7

data/test/test_helper.rb

@@ -0,0 +1,40 @@
+require_relative "../lib/logicle.rb"
+
+module TestHelper
+  def node(type, id=1)
+    Logicle::Node.new(id, type)
+  end
+
+  def digraph
+    @digraph ||= Logicle::Digraph.new
+  end
+
+  def assert_node_state_for_inputs(value, target_node, *inputs)
+    target_node.clear_inputs
+    target_node.append_inputs(*inputs)
+    assert_equal(value, target_node.state)
+  end
+
+  def tgf_reader(input=tgf_content)
+    @tgf_reader ||= Logicle::TgfReader.new(input)
+  end
+
+  def tgf_content
+    @tgf_content ||= <<-TGF.gsub(/^\s+/, "")
+      1 NOT
+      2 AND
+      3 OR
+      4 SWITCH
+      5 SWITCH
+      6 SWITCH
+      7 BULB
+      #
+      4 1
+      5 2
+      6 2
+      2 3
+      1 3
+      3 7
+      TGF
+  end
+end

data/test/tgf_reader_test.rb

@@ -0,0 +1,46 @@
+require_relative "test_helper"
+
+require "test/unit"
+
+
+class TgfReaderTest < Test::Unit::TestCase
+  include TestHelper
+
+  def test_initialization_with_filename
+    filename = File.join(File.dirname(__FILE__), "simple.tgf")
+    file_content = File.readlines(filename)
+
+    assert_equal(file_content,
+                 tgf_reader(filename).instance_variable_get(:@contents))
+  end
+
+  def test_initialization_with_string
+    assert_equal(tgf_content.lines.to_a,
+                 tgf_reader.instance_variable_get(:@contents).to_a)
+  end
+
+  def test_parsing
+    circuit = tgf_reader.parse
+
+    node_lines, edge_lines = tgf_content.split(/#\s*\n/)
+
+    assert_equal(node_lines.chomp.lines.count,
+                 circuit.instance_variable_get(:@nodes).count)
+    assert_equal(edge_lines.lines.count,
+                 circuit.instance_variable_get(:@edges).count)
+  end
+
+  def test_parsing_with_bad_node_type
+    content = "0 FOO\n" << tgf_content
+    assert_raises(Logicle::ParseError) do
+      tgf_reader(content).parse
+    end
+  end
+
+  def test_parsing_with_bad_edge
+    content = tgf_content << "\n10000 100001"
+    assert_raises(Logicle::ParseError) do
+      tgf_reader(content).parse
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: logicle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Chris kottom
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-09-24 00:00:00.000000000Z
+dependencies: []
+description: Logicle is a simulator for testing and solving simple circuits composed
+  of basic logical elements. The program reads and writes its inputs and outputs using
+  the GML protocol.
+email: chris@chriskottom.com
+executables:
+- logicle
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/logicle
+- examples/simple.tgf
+- examples/simple_solved.tgf
+- lib/logicle.rb
+- lib/logicle/digraph.rb
+- lib/logicle/logicle.rb
+- lib/logicle/node.rb
+- lib/logicle/simulator.rb
+- lib/logicle/tgf_reader.rb
+- lib/logicle/tgf_writer.rb
+- lib/logicle/version.rb
+- logicle.gemspec
+- test/digraph_test.rb
+- test/logicle_test.rb
+- test/node_test.rb
+- test/simple.tgf
+- test/test_helper.rb
+- test/tgf_reader_test.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+- vendor
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: logicle
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A simulator for playing with digital circuit logic
+test_files: []