logicuit 0.1.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43a3513f7c19e4125cca8f7ea6d242f06eecdf9bc7e48bc4afa11524f0cbce51
-  data.tar.gz: 5b301e47822f01ae50798cb40c636e07ef72f2557812451a69fb42327bb48f87
+  metadata.gz: 51ce3fab568abef949848bf4f1cb8c8dbe3f0f80da773b9f6f48ea374e21c376
+  data.tar.gz: 787d8ae4a61d770bba76612b5a7ffffbee750dfe0d645dae4a89c57e130ecdc1
 SHA512:
-  metadata.gz: 546e6f2dd4b6dbb76bf195da77f756391bccfa1e9606790f54a66131b60acae68f4fe1858b5915c03e8bfb47a96aea630d411db388d286b5fa208f862664301f
-  data.tar.gz: 26a33fc73deda4d50bb9bfd70ba9ddeeb13e83d379c0e97f3eacf4a8761f58c55a25f7d72f2267255d4ab437df676a80b4aea5a62424f9b6cf9315519f473270
+  metadata.gz: 28dcfd69c6f889c27283f46928dabcf178ba0113609f36895ab4e10642e36eff631070573946b5d5c7dd4ab06180d7b5649e524d855c977ab361d20675ece5b6
+  data.tar.gz: 4b253121ffffc6d0f06e53f07c23bde1bc371c91b2217ba91cfe46fd134376b0c2c0dac7146afad73d12f02a8a7fc1d0ad1242c85a11888a1b00434a63c5ceaf

data/.rubocop.yml

@@ -8,6 +8,29 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
-require:
+Layout/LineLength:
+  Enabled: false
+
+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,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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Logicuit
+  module Circuits
+    module Combinational
+      # FullAdder class
+      class FullAdder < DSL
+        diagram <<~DIAGRAM
+          (Cin)---+-|NOT|-----+
+                  |           |
+          (A)---+---|NOT|---+ |
+                | |         | |
+          (B)-+-----|NOT|-+ | +-|   |
+              | | |       | +---|AND|---+
+              +-----------------|   |   |
+              | | |       | | |         +-|  |
+              | | |       | | +-|   |     |  |
+              | +---------------|AND|-----|  |
+              | | |       +-----|   |     |  |
+              | | |       | | |           |OR|-(S)
+              | | +-------------|   |     |  |
+              | | |       | +---|AND|-----|  |
+              | | |       +-----|   |     |  |
+              | | |       | | |         +-|  |
+              | | +-------------|   |   |
+              | +---------------|AND|---+
+              +-----------------|   |
+              | | |       | | |
+              | | |       | | +-|   |
+              | +---------------|AND|---+
+              +-----------------|   |   |
+              | | |       | |           +-|  |
+              | | +-------------|   |     |  |
+              | | |       | +---|AND|-----|  |
+              +-----------------|   |     |  |
+              | | |       |               |OR|-(C)
+              | | +-------------|   |     |  |
+              | +---------------|AND|-----|  |
+              | | |       +-----|   |     |  |
+              | | |                     +-|  |
+              | | +-------------|   |   |
+              | +---------------|AND|---+
+              +-----------------|   |
+        DIAGRAM
+
+        inputs :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 |
+          | --- | - | - | - | - |
+          |   0 | 0 | 0 | 0 | 0 |
+          |   0 | 0 | 1 | 0 | 1 |
+          |   0 | 1 | 0 | 0 | 1 |
+          |   0 | 1 | 1 | 1 | 0 |
+          |   1 | 0 | 0 | 0 | 1 |
+          |   1 | 0 | 1 | 1 | 0 |
+          |   1 | 1 | 0 | 1 | 0 |
+          |   1 | 1 | 1 | 1 | 1 |
+        TRUTH_TABLE
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Logicuit
+  module Circuits
+    module Combinational
+      # FullAdder class
+      class FullAdder4bit < DSL
+        diagram <<~DIAGRAM
+          (Cin)-|    |--(S0)  +--------|    |--(S1)
+          (A0)--|FADD|        |  (A1)--|FADD|
+          (B0)--|    |--------+  (B1)--|    |--+
+                                               |
+             +---------------------------------+
+             |
+             +--|    |--(S2)  +--------|    |--(S3)
+          (A2)--|FADD|        |  (A3)--|FADD|
+          (B2)--|    |--------+  (B3)--|    |---(C)
+        DIAGRAM
+
+        inputs :cin, :a0, :b0, :a1, :b1, :a2, :b2, :a3, :b3
+
+        outputs :s0, :s1, :s2, :s3, :c
+
+        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
+            c >> full_addr.cin
+            a >> full_addr.a
+            b >> full_addr.b
+            full_addr.s >> s
+            full_addr.c
+          end >> c
+        end
+      end
+    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/{multiplexer2to1.rb → 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/{multiplexer4to1.rb → 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 |

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Logicuit
+  module Circuits
+    module Sequential
+      # 1 bit CPU with a Multiplexer
+      # Input A is H, MOV A,A
+      # Input A is L, NOT A
+      class OneBitCpu < DSL
+        diagram <<~DIAGRAM
+          +-----------------------------+
+          |                             |
+          +----|   |---+---------|   |  |
+               |DFF|   |         |   |  |
+          (CK)-|>  |   +--|NOT|--|MUX|--+--(Y)
+                                 |   |
+                            (A)--|   |
+        DIAGRAM
+
+        inputs :a, clock: :ck
+
+        outputs :y
+
+        assembling do
+          dff = Sequential::DFlipFlop.new
+          not_gate = Gates::Not.new
+          mux = Combinational::Multiplexer2to1.new
+
+          dff.q >> mux.c0
+          dff.q >> not_gate.a
+          not_gate.y >> mux.c1
+          a >> mux.a
+          mux.y >> dff.d
+          mux.y >> y
+        end
+      end
+    end
+  end
+end