logicuit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6288d2da83c42993610ba8212db59a1296ebf4724355c83f0c63f8605a228b6
-  data.tar.gz: 7fcc0e76b0142332d46e93a8a841004de7943e8520ec196cf61c97253ab4321a
+  metadata.gz: 51ce3fab568abef949848bf4f1cb8c8dbe3f0f80da773b9f6f48ea374e21c376
+  data.tar.gz: 787d8ae4a61d770bba76612b5a7ffffbee750dfe0d645dae4a89c57e130ecdc1
 SHA512:
-  metadata.gz: 6208894fad9df2006468189d4285e4d1be8b0ce46b0cc8419dbe26dc22c25baab5a9901faf0d29f592fc36cdb3888144e7ff55ca640be6c00e7c9780e56f2748
-  data.tar.gz: 8050593dceea458a6275c9a90c638a4d01cbf23467103ea79756ff08a272585889e09a9beb802cae47b96158d8173744165311adfe671caf555f97d0d86d62a1
+  metadata.gz: 28dcfd69c6f889c27283f46928dabcf178ba0113609f36895ab4e10642e36eff631070573946b5d5c7dd4ab06180d7b5649e524d855c977ab361d20675ece5b6
+  data.tar.gz: 4b253121ffffc6d0f06e53f07c23bde1bc371c91b2217ba91cfe46fd134376b0c2c0dac7146afad73d12f02a8a7fc1d0ad1242c85a11888a1b00434a63c5ceaf

data/.rubocop.yml

@@ -14,6 +14,18 @@ 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
 

data/README.md

@@ -1,6 +1,8 @@
 # Logicuit
 
-logi(c cir)cuit -> logicuit
+From logic circuit to Logicuit — a playful portmanteau.
+
+A Ruby-based logic circuit simulator featuring an internal DSL for building circuits.
 
 ## Installation
 
@@ -16,50 +18,330 @@ 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:
+
+```
+require "logicuit"
+
+class MyAndGate < Logicuit::DSL
+  inputs :a, :b
 
-This is the code to create a Multiplexer with 2 inputs and 1 output:
+  outputs y: -> { a && b }
+
+  diagram <<~DIAGRAM
+    (A)-|   |
+        |AND|-(Y)
+    (B)-|   |
+  DIAGRAM
+end
 
+MyAndGate.run
 ```
-require 'logicuit'
 
-class Multiplexer2to1 < Logicuit::Base
-  tag :MY_MUX
+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:
+
+```
+(0)-|   |
+    |AND|-(0)
+(0)-|   |
+
+input: a,b?
+```
+
+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:
+
+```
+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:
+
+```
+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:
+
+```
+a >> xor_gate.a
+a >> and_gate.a
+```
+
+can be written more concisely as:
+
+```
+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.
+
+#### Many-to-many connections
 
-  define_inputs :c0, :c1, :a
+You can also connect multiple outputs to multiple inputs at once by using the [] method to access signals by name:
 
-  define_outputs y: ->(c0, c1, a) { (c0 && !a) || (c1 && a) }
+```
+pc.qa >> rom.a0
+pc.qb >> rom.a1
+pc.qc >> rom.a2
+pc.qd >> rom.a3
+```
+
+is equivalent to:
+
+```
+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:
+
+```
+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:
 
-Logicuit.run(:MY_MUX)
 ```
+require "logicuit"
+
+class MyDFlipFlop < Logicuit::DSL
+  inputs :d, clock: :ck
 
-you can execute a same circuit by the following as a one-liner:
+  outputs q: -> { d }
+
+  diagram <<~DIAGRAM
+    (D)--|   |--(Q)
+         |DFF|
+    (CK)-|>  |
+  DIAGRAM
+end
 
+MyDFlipFlop.run
 ```
-ruby -r ./lib/logicuit -e 'Logicuit.run(:mux)'
+
+#### 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
+
+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)-|>  |
 
-you can similarly execute other circuits with the following commands:
+tick: 2
+input: d?
+```
+
+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`:
+
+```
+MyDFlipFlop.run(hz: 10)
+```
+
+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:
+
+```
+MyDFlipFlop.run(hz: 0)
+```
+
+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 -r ./lib/logicuit -e 'Logicuit.run(:dff)'
+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
 ```
 
+#### 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 -r ./lib/logicuit -e 'Logicuit.run(:one_bit_cpu)'
+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.
+
 ## 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 |

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

@@ -4,36 +4,32 @@ module Logicuit
   module Circuits
     module Combinational
       # A Multiplexer with 4 inputs and 1 output
-      class Multiplexer4to1 < Base
-        tag :MUX4, :MUX4TO1
-
+      class Multiplexer4to1 < DSL
         diagram <<~DIAGRAM
-          (C0)---------------|
+          (C0)---------------|   |
                          +---|AND|---+
-                         | +-|       |
+                         | +-|   |   |
                          | |         |
-          (C1)---------------|       +-|
+          (C1)---------------|   |   +-|
                          +---|AND|-+   |
-                 +-----------|     +---|
+                 +-----------|   | +---|
                  |       | |           |OR|--(Y)
-          (C2)---------------|     +---|
+          (C2)---------------|   | +---|
                +-------------|AND|-+   |
-               | |       | +-|       +-|
+               | |       | +-|   |   +-|
                | |       | |         |
-          (C3)---------------|       |
+          (C3)---------------|   |   |
                +-------------|AND|---+
-               | +-----------|
+               | +-----------|   |
                | |       | |
           (B)--+---|NOT|-+ |
                  |         |
           (A)----+-|NOT|---+
         DIAGRAM
 
-        define_inputs :c0, :c1, :c2, :c3, :b, :a
+        inputs :c0, :c1, :c2, :c3, :b, :a
 
-        define_outputs y: lambda { |c0, c1, c2, c3, b, a|
-          (c0 && !b && !a) || (c1 && !b && a) || (c2 && b && !a) || (c3 && b && a)
-        }
+        outputs y: -> { (c0 && !b && !a) || (c1 && !b && a) || (c2 && b && !a) || (c3 && b && a) }
 
         truth_table <<~TRUTH_TABLE
           | B | A | C0 | C1 | C2 | C3 | Y |

data/lib/logicuit/circuits/sequential/d_flip_flop.rb

@@ -4,18 +4,16 @@ module Logicuit
   module Circuits
     module Sequential
       # D Flip-Flop
-      class DFlipFlop < Base
-        tag :DFF
-
+      class DFlipFlop < DSL
         diagram <<~DIAGRAM
           (D)--|   |--(Q)
                |DFF|
           (CK)-|>  |
         DIAGRAM
 
-        define_inputs :d, clock: :ck
+        inputs :d, clock: :ck
 
-        define_outputs q: ->(d) { d }
+        outputs q: -> { d }
 
         truth_table <<~TRUTH_TABLE
           | CK | D | Q |