logicuit 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6288d2da83c42993610ba8212db59a1296ebf4724355c83f0c63f8605a228b6
-  data.tar.gz: 7fcc0e76b0142332d46e93a8a841004de7943e8520ec196cf61c97253ab4321a
+  metadata.gz: 1a2841e79a0daf8046710c6bd43d8862a3d9f28f482ab2b9cac2886b271f571f
+  data.tar.gz: 679b263308e15b0da229573bfd7be5cf02c8e65bd98fb01753874afb3fe56413
 SHA512:
-  metadata.gz: 6208894fad9df2006468189d4285e4d1be8b0ce46b0cc8419dbe26dc22c25baab5a9901faf0d29f592fc36cdb3888144e7ff55ca640be6c00e7c9780e56f2748
-  data.tar.gz: 8050593dceea458a6275c9a90c638a4d01cbf23467103ea79756ff08a272585889e09a9beb802cae47b96158d8173744165311adfe671caf555f97d0d86d62a1
+  metadata.gz: 3e942269a9b55dad3f7efff1d68935f431952d0c3276d7d290461dabe84230f6d6d1d0eb2f307b6dd375c2d3b1261c8e2e7c72f1faa17db0de576cee9c37c0da
+  data.tar.gz: 3f1428cced00eee1798ea56dc9cfb169eb041b40bfc514a729d1cd3d67ce4b05d93ea633a9290c3ac22432aa1bfeb384e8de20cee59a0e463c582bf82be61ea4

data/.rubocop.yml

@@ -14,11 +14,21 @@ Layout/LineLength:
 Style/NumericPredicate:
   Enabled: false
 
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+Style/SymbolProc:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Naming/MethodParameterName:
+  Enabled: false
+
 Metrics:
   Enabled: false
 
 plugins:
   - rubocop-minitest
-
-require:
   - rubocop-rake

data/README.md

@@ -1,6 +1,49 @@
 # Logicuit
 
-logi(c cir)cuit -> logicuit
+```
+                *******       *******       *******
+               *********     *********     *********
+              ***********   ***********   ***********
+               *********     *********     *********
+                *******       *******       *******
+
++-----------------------------------------------+       OUT 0111
+|                                               |       ADD A,0001
++--->|rg_a|(0111)----->|   |                    |       JNC 0001
+|    |1000|            |   |                    |       ADD A,0001
+|                      |   |                    |     > JNC 0011
++--->|rg_b|(0000)----->|   |----------->|   |---+       OUT 0110
+|    |0000|            |   |            |   |           ADD A,0001
+|                      |SEL|            |ALU|           JNC 0110
++--->| out|  |  in|--->|   |            |   |           ADD A,0001
+|    |0111|  |0000|    |   |  |  im|--->|   |--(0)      JNC 1000
+|                      |   |  |0011|                    OUT 0000
++--->|  pc|  (0000)--->|   |                            OUT 0100
+     |0100|                                             ADD A,0001
+                                                        JNC 1010
+                                                        OUT 1000
+                                                        JMP 1111
+
+tick: 48
+input: in0,in1,in2,in3?
+```
+
+From logic circuit to Logicuit — a playful portmanteau.
+
+A Ruby-based logic circuit simulator featuring an internal DSL for building circuits.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [DSL](#dsl)
+- [Interactive Execution](#interactive-execution)
+- [Assembling](#assembling)
+- [SignalGroup](#signalgroup)
+- [Sequential Circuits](#sequential-circuits)
+- [Demo: Ramen Timer](#demo-ramen-timer)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
@@ -16,50 +59,344 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install logicuit
 ```
 
-## Usage
+## DSL
+
+This library provides an internal DSL for defining logic circuits in a declarative and readable way.
+You can define inputs, outputs, and even a visual diagram — all within a Ruby class.
+
+Here is an example of a simple 2-input AND gate:
+
+```ruby
+require "logicuit"
+
+class MyAndGate < Logicuit::DSL
+  inputs :a, :b
+
+  outputs y: -> { a && b }
+
+  diagram <<~DIAGRAM
+    (A)-|   |
+        |AND|-(Y)
+    (B)-|   |
+  DIAGRAM
+end
+
+MyAndGate.run
+```
+
+This defines:
+
+- two inputs (`a` and `b`),
+- one output (`y`) that returns the logical AND of the inputs,
+- and an ASCII diagram that shows the structure of the gate.
+
+### Interactive execution
+
+When you call `run`, the simulator enters an interactive mode.
+
+At first, the circuit is evaluated with all inputs set to `0`, and drawn as an ASCII diagram:
 
-This is the code to create a Multiplexer with 2 inputs and 1 output:
+```
+(0)-|   |
+    |AND|-(0)
+(0)-|   |
 
+input: a,b?
 ```
-require 'logicuit'
 
-class Multiplexer2to1 < Logicuit::Base
-  tag :MY_MUX
+To interact with the circuit, just type the name of an input — for example, `a` — and press Enter.
+That input will toggle its value (`0 → 1` or `1 → 0`), and the diagram will be redrawn to reflect the new state.
+You can keep toggling inputs this way to observe how the circuit reacts in real time.
+
+To exit the simulator, simply press `Ctrl+C`.
+
+### Assembling circuits
+
+In addition to defining simple gates declaratively, Logicuit also lets you assemble circuits from reusable components using the `assembling` block.
+
+This approach gives you more control and expressiveness when building complex circuits.
+
+Here's an example of a 2-to-1 multiplexer:
+
+```ruby
+require "logicuit"
+
+class MyMultiplexer < Logicuit::DSL
+  inputs :c0, :c1, :a
+
+  outputs :y
+
+  assembling do
+    and_gate1 = Logicuit::Gates::And.new
+    and_gate2 = Logicuit::Gates::And.new
+    not_gate = Logicuit::Gates::Not.new
+    or_gate = Logicuit::Gates::Or.new
+
+    c0 >> and_gate1.a
+    a >> not_gate.a
+    not_gate.y >> and_gate1.b
+
+    c1 >> and_gate2.a
+    a >> and_gate2.b
+
+    and_gate1.y >> or_gate.a
+    and_gate2.y >> or_gate.b
+    or_gate.y >> y
+  end
 
   diagram <<~DIAGRAM
-    (C0)---------|
+    (C0)---------|   |
                  |AND|--+
-         +-|NOT|-|      +--|
+         +-|NOT|-|   |  +--|  |
          |                 |OR|--(Y)
-    (C1)---------|      +--|
+    (C1)---------|   |  +--|  |
          |       |AND|--+
-    (A)--+-------|
+    (A)--+-------|   |
   DIAGRAM
+end
+
+MyMultiplexer.run
+```
+
+### Connection syntax
+
+The `>>` operator is used to connect outputs to inputs, mimicking the direction of signal flow.
+
+This allows the code to resemble the actual structure of the circuit, making it more intuitive to follow.
+
+For example:
+
+```ruby
+a >> not_gate.a
+not_gate.y >> and_gate1.b
+```
+
+can be read as:
+
+*"Connect input `a` to the NOT gate's input. Then connect the NOT gate's output to one of the AND gate's inputs."*
+
+### Built-in gates
+
+Logicuit includes several built-in logic gates, which you can use as components:
+
+- `Logicuit::Gates::And`
+- `Logicuit::Gates::Or`
+- `Logicuit::Gates::Not`
+- `Logicuit::Gates::Nand`
+- `Logicuit::Gates::Xor`
+
+These gates expose their input and output pins as attributes (`a`, `b`, `y`, etc.), which can be freely connected using `>>`.
+
+### Signal groups
+
+When building larger circuits, it's common to connect one output to multiple inputs, or to connect multiple outputs to multiple inputs.
+
+Logicuit provides a convenient way to express these kinds of connections using signal groups.
+
+#### One-to-many connections
+
+These two lines:
+
+```ruby
+a >> xor_gate.a
+a >> and_gate.a
+```
+
+can be written more concisely as:
+
+```ruby
+a >> [xor_gate.a, and_gate.a]
+```
+
+The array on the right-hand side is treated as a signal group, and the connection is applied to each element.
 
-  define_inputs :c0, :c1, :a
+#### Many-to-many connections
 
-  define_outputs y: ->(c0, c1, a) { (c0 && !a) || (c1 && a) }
+You can also connect multiple outputs to multiple inputs at once by using the [] method to access signals by name:
+
+```ruby
+pc.qa >> rom.a0
+pc.qb >> rom.a1
+pc.qc >> rom.a2
+pc.qd >> rom.a3
+```
+
+is equivalent to:
+
+```ruby
+pc[:qa, :qb, :qc, :qd] >> rom[:a0, :a1, :a2, :a3]
+```
+
+This `#[](*keys)` method returns a `SignalGroup` object — a Logicuit abstraction that makes it easier to handle groups of signals together.
+
+> Note: The number of signals on both sides must match.
+
+#### Connecting from different sources
+
+What if you want to connect signals from multiple different components as a single group?
+
+You can use `Logicuit::ArrayAsSignalGroup`, which adds signal group behavior to arrays:
+
+```ruby
+using Logicuit::ArrayAsSignalGroup
+
+assembling do
+  [register_a.qa, register_b.qa, in0] >> mux0[:c0, :c1, :c2]
 end
+```
+
+This lets you treat a plain Ruby array as a `SignalGroup` and connect it to another group of inputs in one line.
+
+### Sequential circuits
+
+In addition to combinational circuits, Logicuit also supports sequential circuits — circuits whose output depends not only on the current inputs, but also on past inputs.
+
+For example, here’s a D flip-flop:
+
+```ruby
+require "logicuit"
+
+class MyDFlipFlop < Logicuit::DSL
+  inputs :d, clock: :ck
+
+  outputs q: -> { d }
+
+  diagram <<~DIAGRAM
+    (D)--|   |--(Q)
+         |DFF|
+    (CK)-|>  |
+  DIAGRAM
+end
+
+MyDFlipFlop.run
+```
+
+#### Defining a sequential circuit
+
+A circuit becomes sequential when the `inputs` declaration includes a keyword argument named `clock:`.
+You can assign any name to the clock signal — in the above example, it's `:ck` — but the presence of the `clock:` keyword is what tells Logicuit to treat the circuit as sequential.
+
+Once a clock is defined:
+
+- The `outputs` lambdas will be evaluated on each clock tick, not continuously.
+- A global singleton clock will drive the timing — you don’t need to define or manage the clock yourself.
+
+#### Interactive execution with a clock
 
-Logicuit.run(:MY_MUX)
+When a sequential circuit is run interactively, Logicuit enters clock mode. The clock ticks periodically, and the circuit is redrawn after each tick.
+
+```
+(0)--|   |--(0)
+     |DFF|
+(CK)-|>  |
+
+tick: 2
+input: d?
 ```
 
-you can execute a same circuit by the following as a one-liner:
+You can still toggle inputs as before (e.g., type `d` and press Enter), but updates take effect on the next tick.
+
+The number of elapsed ticks is shown as `tick: N`.
 
+#### Clock speed
+
+By default, the clock ticks at 1 Hz (once per second). You can change the frequency by passing the `hz:` option to `run`:
+
+```ruby
+MyDFlipFlop.run(hz: 10)
 ```
-ruby -r ./lib/logicuit -e 'Logicuit.run(:mux)'
+
+This will run the clock at 10 ticks per second — useful when simulating more complex circuits.
+
+If you want full control, you can set `hz: 0` to disable automatic ticking.
+
+In this mode, the clock only ticks when you press Enter, allowing you to step through the simulation manually:
+
+```ruby
+MyDFlipFlop.run(hz: 0)
 ```
 
-you can similarly execute other circuits with the following commands:
+This is useful for debugging or analyzing a circuit’s behavior step by step.
+
+#### Combining sequential circuits with `assembling`
+
+You can build sequential circuits out of smaller components using the `assembling` block, just like with combinational circuits.
+
+Here’s an example of a 4-bit register that stores its input when the load signal `ld` is not active:
+
+```ruby
+require "logicuit"
+
+class MyRegister4bit < Logicuit::DSL
+  inputs :a, :b, :c, :d, :ld, clock: :ck
+
+  outputs :qa, :qb, :qc, :qd
 
+  assembling do
+    [[a, qa], [b, qb], [c, qc], [d, qd]].each do |input, output|
+      dff = Logicuit::Circuits::Sequential::DFlipFlop.new
+      mux = Logicuit::Circuits::Combinational::Multiplexer2to1.new
+      input >> mux.c0
+      dff.q >> mux.c1
+      ld    >> mux.a
+      mux.y >> dff.d
+      dff.q >> output
+    end
+  end
+
+  diagram <<~DIAGRAM
+            +---------------------+
+            +-|   |               |
+    (A)-------|MUX|-------|DFF|---+---(QA)
+          +---|   |   +---|   |
+          |           |
+          | +---------------------+
+          | +-|   |   |           |
+    (B)-------|MUX|-------|DFF|---+---(QB)
+          +---|   |   +---|   |
+          |           |
+          | +---------------------+
+          | +-|   |   |           |
+    (C)-------|MUX|-------|DFF|---+---(QC)
+          +---|   |   +---|   |
+          |           |
+          | +---------------------+
+          | +-|   |   |           |
+    (D)-------|MUX|-------|DFF|---+---(QD)
+          +---|   |   +---|   |
+    (LD)--+     (CK)--+
+  DIAGRAM
+end
+
+MyRegister4bit.run
 ```
-ruby -r ./lib/logicuit -e 'Logicuit.run(:dff)'
+
+#### Sequential detection
+
+If your circuit contains one or more sequential components (such as D flip-flops), Logicuit will treat the entire circuit as sequential, as long as you declare a clock input using the `clock:` keyword in `inputs`.
+
+The clock signal is automatically connected to all internal sequential components. You don't need to wire it manually — just declare it at the top level:
+
+```ruby
+inputs ..., clock: :ck
 ```
 
+> Note: If you forget to declare a clock input, Logicuit won't know it's a sequential circuit — even if you include flip-flops internally. Always include `clock:` to enable timing.
+
+### Demo: Ramen Timer
+
+Logicuit comes with a simple demo circuit — a working 4-bit CPU based on the TD4 architecture described in the book [CPUの創りかた](https://www.amazon.co.jp/dp/4839909865).
+
+You can try it out by running:
+
 ```
-ruby -r ./lib/logicuit -e 'Logicuit.run(:one_bit_cpu)'
+ruby -r logicuit -e 'Logicuit::Circuits::Td4::Cpu.run'
 ```
 
+This launches a fully functional CPU simulation that counts down from a programmed value — perfect for timing your instant ramen 🍜
+
+The TD4 CPU is built entirely from logic gates and flip-flops, assembled using Logicuit’s DSL. It’s a great demonstration of how small components can be combined to create a complete digital system.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/logicuit/array_as_signal_group.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Logicuit module
+module Logicuit
+  # Treats Array#>> as SignalGroup#>> for the purpose of connecting signals
+  module ArrayAsSignalGroup
+    refine Array do
+      def >>(other)
+        Signals::SignalGroup.new(*self).connects_to(other)
+      end
+    end
+  end
+end

data/lib/logicuit/circuits/combinational/full_adder.rb

@@ -4,51 +4,49 @@ module Logicuit
   module Circuits
     module Combinational
       # FullAdder class
-      class FullAdder < Base
-        tag :FADD
-
+      class FullAdder < DSL
         diagram <<~DIAGRAM
           (Cin)---+-|NOT|-----+
                   |           |
           (A)---+---|NOT|---+ |
                 | |         | |
-          (B)-+-----|NOT|-+ | +-|
+          (B)-+-----|NOT|-+ | +-|   |
               | | |       | +---|AND|---+
-              +-----------------|       |
-              | | |       | | |         +-|
-              | | |       | | +-|         |
-              | +---------------|AND|-----|
-              | | |       +-----|         |
+              +-----------------|   |   |
+              | | |       | | |         +-|  |
+              | | |       | | +-|   |     |  |
+              | +---------------|AND|-----|  |
+              | | |       +-----|   |     |  |
               | | |       | | |           |OR|-(S)
-              | | +-------------|         |
-              | | |       | +---|AND|-----|
-              | | |       +-----|         |
-              | | |       | | |         +-|
-              | | +-------------|       |
+              | | +-------------|   |     |  |
+              | | |       | +---|AND|-----|  |
+              | | |       +-----|   |     |  |
+              | | |       | | |         +-|  |
+              | | +-------------|   |   |
               | +---------------|AND|---+
-              +-----------------|
+              +-----------------|   |
               | | |       | | |
-              | | |       | | +-|
+              | | |       | | +-|   |
               | +---------------|AND|---+
-              +-----------------|       |
-              | | |       | |           +-|
-              | | +-------------|         |
-              | | |       | +---|AND|-----|
-              +-----------------|         |
+              +-----------------|   |   |
+              | | |       | |           +-|  |
+              | | +-------------|   |     |  |
+              | | |       | +---|AND|-----|  |
+              +-----------------|   |     |  |
               | | |       |               |OR|-(C)
-              | | +-------------|         |
-              | +---------------|AND|-----|
-              | | |       +-----|         |
-              | | |                     +-|
-              | | +-------------|       |
+              | | +-------------|   |     |  |
+              | +---------------|AND|-----|  |
+              | | |       +-----|   |     |  |
+              | | |                     +-|  |
+              | | +-------------|   |   |
               | +---------------|AND|---+
-              +-----------------|
+              +-----------------|   |
         DIAGRAM
 
-        define_inputs :cin, :a, :b
+        inputs :cin, :a, :b
 
-        define_outputs s: ->(cin, a, b) { (!cin && !a && b) || (!cin && a && !b) || (cin && !a && !b) || (cin && a && b) },
-                       c: ->(cin, a, b) { (!cin && a && b) || (cin && !a && b) || (cin && a && !b) || (cin && a && b) }
+        outputs s: -> { (!cin && !a && b) || (!cin && a && !b) || (cin && !a && !b) || (cin && a && b) },
+                c: -> { (!cin && a && b) || (cin && !a && b) || (cin && a && !b) || (cin && a && b) }
 
         truth_table <<~TRUTH_TABLE
           | Cin | A | B | C | S |

data/lib/logicuit/circuits/combinational/full_adder_4bit.rb

@@ -4,39 +4,24 @@ module Logicuit
   module Circuits
     module Combinational
       # FullAdder class
-      class FullAdder4bit < Base
-        tag :FADD4
-
+      class FullAdder4bit < DSL
         diagram <<~DIAGRAM
-          (Cin)-|    |--(S0)
-          (A0)--|FADD|
-          (B0)--|    |--+
-                        |
-             +----------+
-             |
-             +--|    |--(S1)
-          (A1)--|FADD|
-          (B1)--|    |--+
-                        |
-             +----------+
+          (Cin)-|    |--(S0)  +--------|    |--(S1)
+          (A0)--|FADD|        |  (A1)--|FADD|
+          (B0)--|    |--------+  (B1)--|    |--+
+                                               |
+             +---------------------------------+
              |
-             +--|    |--(S2)
-          (A2)--|FADD|
-          (B2)--|    |--+
-                        |
-             +----------+
-             |
-             +--|    |--(S3)
-          (A3)--|FADD|
-          (B3)--|    |---(C)
-
+             +--|    |--(S2)  +--------|    |--(S3)
+          (A2)--|FADD|        |  (A3)--|FADD|
+          (B2)--|    |--------+  (B3)--|    |---(C)
         DIAGRAM
 
-        define_inputs :cin, :a0, :b0, :a1, :b1, :a2, :b2, :a3, :b3
+        inputs :cin, :a0, :b0, :a1, :b1, :a2, :b2, :a3, :b3
 
-        define_outputs :s0, :s1, :s2, :s3, :c
+        outputs :s0, :s1, :s2, :s3, :c
 
-        assembling do |cin, a0, b0, a1, b1, a2, b2, a3, b3, s0, s1, s2, s3, cout|
+        assembling do
           [[a0, b0, s0], [a1, b1, s1], [a2, b2, s2], [a3, b3, s3]].reduce(cin) do |c, sigs|
             a, b, s = sigs
             full_addr = Combinational::FullAdder.new
@@ -45,7 +30,7 @@ module Logicuit
             b >> full_addr.b
             full_addr.s >> s
             full_addr.c
-          end >> cout
+          end >> c
         end
       end
     end

data/lib/logicuit/circuits/combinational/half_adder.rb

@@ -4,24 +4,22 @@ module Logicuit
   module Circuits
     module Combinational
       # HalfAdder class
-      class HalfAdder < Base
-        tag :HADD
-
+      class HalfAdder < DSL
         diagram <<~DIAGRAM
-          (A)---+-|
+          (A)---+-|   |
                 | |XOR|-(S)
-          (B)-+---|
+          (B)-+---|   |
               | |
-              | +-|
+              | +-|   |
               |   |AND|-(C)
-              +---|
+              +---|   |
         DIAGRAM
 
-        define_inputs :a, :b
+        inputs :a, :b
 
-        define_outputs :c, :s
+        outputs :c, :s
 
-        assembling do |a, b, c, s|
+        assembling do
           xor_gate = Gates::Xor.new
           and_gate = Gates::And.new
 

data/lib/logicuit/circuits/combinational/multiplexer_2to1.rb

@@ -4,22 +4,20 @@ module Logicuit
   module Circuits
     module Combinational
       # A Multiplexer with 2 inputs and 1 output
-      class Multiplexer2to1 < Base
-        tag :MUX, :MUX2, :MUX2to1
-
+      class Multiplexer2to1 < DSL
         diagram <<~DIAGRAM
-          (C0)---------|
+          (C0)---------|   |
                        |AND|--+
-               +-|NOT|-|      +--|
+               +-|NOT|-|   |  +--|  |
                |                 |OR|--(Y)
-          (C1)---------|      +--|
+          (C1)---------|   |  +--|  |
                |       |AND|--+
-          (A)--+-------|
+          (A)--+-------|   |
         DIAGRAM
 
-        define_inputs :c0, :c1, :a
+        inputs :c0, :c1, :a
 
-        define_outputs y: ->(c0, c1, a) { (c0 && !a) || (c1 && a) }
+        outputs y: -> { (c0 && !a) || (c1 && a) }
 
         truth_table <<~TRUTH_TABLE
           | C0 | C1 | A | Y |