hdl 1.0.1 → 1.0.2

data/README.md

@@ -2,6 +2,12 @@
 
 A parser and emulator for a minimalist [hardware description language](http://en.wikipedia.org/wiki/Hardware_description_language).
 
+HDL is a playground for building your own logic gates and interconnecting them. It's a good place to start if you're learning about boolean expressions and electronics. With a little patience, you could build some seriously powerful chips, from a ripple-carry adder, to a fully-blown arithmetic logic unit.
+
+The first step is to define a 'primitive'. This is a gate that acts as a truth table. On top of this you can build increasingly more complex chips. 'nand' and 'nor' are good choices because they are [universal logic gates](https://en.wikipedia.org/wiki/Logic_gate#Universal_logic_gates).
+
+Let's say you start by building a truth table for 'nand'. You could then derive logic gates for 'and' and 'or', and then an 'xor'. Now that you've padded out your toolset a bit, you could attempt to build a 'half_adder', then perhaps a 'full_adder'. You'd then have everything you need to build a 'ripple_carry_adder'.
+
 ## Chips
 
 Here's an example definition of a chip called 'and.hdl':
@@ -19,6 +25,24 @@ The equivalent circuit diagram is:
 
 !['and' gate from 'nand'](http://upload.wikimedia.org/wikipedia/commons/1/16/AND_from_NAND.svg)
 
+We declare that this chip has two inputs, namely 'a' and 'b' and a single output called 'out'.
+
+The chip is comprised of two 'nand' gates. Each assignment is a connection between the pins on this chip, to the pins on another chip. Let's take the first 'nand', for example:
+
+```ruby
+nand(a=a, b=b, out=x)
+```
+
+Here's how you might write this in English:
+
+* Connect the 'a' input of 'nand' to the 'a' input of this chip
+* Connect the 'b' input of 'nand' to the 'b' input of this chip
+* Connect the 'out' output of 'nand' to the intermediate pin 'x'
+
+The pins on the left of each assignment are for the 'foreign' chip. The pins on the right are for this chip.
+
+We're declaring an intermediate pin 'x' on the fly here. Intermediate pins allow you to interconnect things within your chip. In this case, 'x' is used for the second 'nand' expression.
+
 ## Tables
 
 The above chip references another chip called 'nand'.
@@ -39,6 +63,12 @@ outputs out
 
 If you'd prefer, you can use 'T' and 'F'.
 
+If you've ever worked with truth tables before, this should be straightforward. All we're doing here is listing what the output value should be for every possible set of inputs.
+
+In theory, you could write a truth table for any chip. However, it's much better to derive a chip from others. You should really focus on minimizing the number of primitive chips you depend on.
+
+If you get stuck trying to figure out how to derive your chip, you could always write it as a truth table and come back to it. You'd simply swap the truth table out with a schema definition once you've figured it out.
+
 ## Ruby
 
 Now that we've satisfied the 'nand' dependency, we can write some Ruby:
@@ -53,6 +83,10 @@ chip.evaluate(a: true, b: false)
 
 The 'nand' chip is automatically loaded when it is referenced.
 
+When we call 'evaluate', we're actually emulating the hardware of the chips. The 'and' chip will wire the given inputs into each 'nand', and ask them to evaluate.
+
+The second 'nand' will actually have to wait on the first because it depends on that intermediate pin 'x'. Once it's had its turn, it wires its output to the output of 'and' and we get our return value.
+
 ## Path
 
 By default, chips in the current directory will be discovered.
@@ -63,6 +97,8 @@ You can expand this search by adding to your path:
 HDL.path << "chips"
 ```
 
+This might be useful to group similar chips together, or to keep a hierarchy of dependencies in subdirectories.
+
 ## Parsing
 
 If you'd rather parse your chips directly in Ruby, you can do so with:
@@ -73,7 +109,7 @@ chip = HDL.parse(name, definition)
 
 This might be useful if you're storing definitions in a database.
 
-## Miscellaneous
+## Query methods
 
 Here are some useful methods for querying properties of chips:
 
@@ -113,9 +149,10 @@ chip.dependees # Chips that use this chip.
 
 I'm not an electronics engineer. If you are, you could probably build in all kinds of cool features and optimisations.
 
-Here a few features that might be in the pipeline:
+Here are a few features that might be in the pipeline:
 
-* Let me build a CNF expression for a chip
+* A bespoke test framework that uses tabular test files
+* Support for generating conjunctive normal form expressions
 * Query method for circuit fan-outs for chips
 * Evaluate and return outputs with internal pins
 * Support for buses, mostly for convenience

data/lib/hdl/base.rb

@@ -2,7 +2,7 @@ module HDL
   class << self
 
     def version
-      "1.0.1"
+      "1.0.2"
     end
 
     def path

data/lib/hdl/chip/schema_chip.rb

@@ -30,8 +30,10 @@ class HDL::SchemaChip < HDL::Chip
   end
 
   def evaluate(pins = {})
-    check_pins!(pins)
-    evaluator.evaluate(pins)
+    memoize(pins) do
+      check_pins!(pins)
+      evaluator.evaluate(pins)
+    end
   end
 
   private

data/lib/hdl/chip/table_chip.rb

@@ -18,10 +18,11 @@ class HDL::TableChip < HDL::Chip
   end
 
   def evaluate(pins = {})
-    check_pins!(pins)
-
-    row = find_row(pins)
-    select_outputs(row)
+    memoize(pins) do
+      check_pins!(pins)
+      row = find_row(pins)
+      select_outputs(row)
+    end
   end
 
   private

data/lib/hdl/chip.rb

@@ -38,4 +38,9 @@ class HDL::Chip
     end
   end
 
+  def memoize(pins, &block)
+    @memo ||= {}
+    @memo[pins] ||= yield
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: hdl
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: 
   segments: 
   - 1
   - 0
-  - 1
-  version: 1.0.1
+  - 2
+  version: 1.0.2
 platform: ruby
 authors: 
 - Chris Patuzzo
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-06-02 00:00:00 +01:00
+date: 2013-06-22 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency