logicuit 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51ce3fab568abef949848bf4f1cb8c8dbe3f0f80da773b9f6f48ea374e21c376
-  data.tar.gz: 787d8ae4a61d770bba76612b5a7ffffbee750dfe0d645dae4a89c57e130ecdc1
+  metadata.gz: 7ab72694854386c09ba2b86561b6f71f96ea150cbc75384cac6b367a1ef77678
+  data.tar.gz: 033acc2d10c17e90f32dae9af915e92fd81064c88ff8174842821676b5d11fa4
 SHA512:
-  metadata.gz: 28dcfd69c6f889c27283f46928dabcf178ba0113609f36895ab4e10642e36eff631070573946b5d5c7dd4ab06180d7b5649e524d855c977ab361d20675ece5b6
-  data.tar.gz: 4b253121ffffc6d0f06e53f07c23bde1bc371c91b2217ba91cfe46fd134376b0c2c0dac7146afad73d12f02a8a7fc1d0ad1242c85a11888a1b00434a63c5ceaf
+  metadata.gz: f7468f876cf9c462bd2b39b170c309fd9d35408c2dae2d45c7229376254c0d9d8586573fd607f046ddee1d226fb5f6137e8c722dee1e9d36735d204605be5ed2
+  data.tar.gz: 021dc78f8bc9bc7f62b12572d9ec553f916ff66fac568268c8502c9de46d9b836ba14c49a042f33ebec517eccea9661489e92628c6c1cbf64d96f90a3b046ce4

data/.rubocop.yml

@@ -8,6 +8,9 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
 
+Layout/LeadingCommentSpace:
+  Enabled: false
+
 Layout/LineLength:
   Enabled: false
 
@@ -31,6 +34,4 @@ Metrics:
 
 plugins:
   - rubocop-minitest
-
-require:
   - rubocop-rake

data/README.md

@@ -1,9 +1,51 @@
 # 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)
+- [Truth Table Verification](#truth-table-verification)
+- [Demo: Ramen Timer](#demo-ramen-timer)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -25,13 +67,13 @@ You can define inputs, outputs, and even a visual diagram — all within a Ruby
 
 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 }
+  outputs y: -> { a & b }
 
   diagram <<~DIAGRAM
     (A)-|   |
@@ -49,6 +91,19 @@ This defines:
 - one output (`y`) that returns the logical AND of the inputs,
 - and an ASCII diagram that shows the structure of the gate.
 
+### About signals and logical operations
+
+Inputs and outputs in Logicuit are not plain booleans — they are instances of the `Logicuit::Signals::Signal` class.
+The `Signal` class provides methods like `&`, `|`, and `!` to represent logical AND, OR, and NOT operations, respectively.
+
+For example:
+
+```ruby
+outputs y: -> { (a & b) | !a }
+```
+
+This allows logic expressions to look natural and circuit-like while supporting chaining and composition.
+
 ### Interactive execution
 
 When you call `run`, the simulator enters an interactive mode.
@@ -77,7 +132,7 @@ This approach gives you more control and expressiveness when building complex ci
 
 Here's an example of a 2-to-1 multiplexer:
 
-```
+```ruby
 require "logicuit"
 
 class MyMultiplexer < Logicuit::DSL
@@ -125,7 +180,7 @@ This allows the code to resemble the actual structure of the circuit, making it
 
 For example:
 
-```
+```ruby
 a >> not_gate.a
 not_gate.y >> and_gate1.b
 ```
@@ -156,14 +211,14 @@ Logicuit provides a convenient way to express these kinds of connections using s
 
 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]
 ```
 
@@ -173,7 +228,7 @@ The array on the right-hand side is treated as a signal group, and the connectio
 
 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
@@ -182,7 +237,7 @@ pc.qd >> rom.a3
 
 is equivalent to:
 
-```
+```ruby
 pc[:qa, :qb, :qc, :qd] >> rom[:a0, :a1, :a2, :a3]
 ```
 
@@ -196,7 +251,7 @@ What if you want to connect signals from multiple different components as a sing
 
 You can use `Logicuit::ArrayAsSignalGroup`, which adds signal group behavior to arrays:
 
-```
+```ruby
 using Logicuit::ArrayAsSignalGroup
 
 assembling do
@@ -212,7 +267,7 @@ In addition to combinational circuits, Logicuit also supports sequential circuit
 
 For example, here’s a D flip-flop:
 
-```
+```ruby
 require "logicuit"
 
 class MyDFlipFlop < Logicuit::DSL
@@ -261,7 +316,7 @@ The number of elapsed ticks is shown as `tick: N`.
 
 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)
 ```
 
@@ -271,7 +326,7 @@ 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)
 ```
 
@@ -283,7 +338,7 @@ You can build sequential circuits out of smaller components using the `assemblin
 
 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
@@ -336,12 +391,104 @@ If your circuit contains one or more sequential components (such as D flip-flops
 
 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.
 
+## Truth Table Verification
+
+You can attach a truth table to your circuit class using the `#truth_table`. The truth table should be written in Markdown table format.
+
+```ruby
+require "logicuit"
+
+class MyAndGate < Logicuit::DSL
+  inputs :a, :b
+
+  outputs y: -> { a & b }
+
+  diagram <<~DIAGRAM
+    (A)-|   |
+        |AND|-(Y)
+    (B)-|   |
+  DIAGRAM
+
+  truth_table <<~TRUTH_TABLE
+    | A | B | Y |
+    | - | - | - |
+    | 0 | 0 | 0 |
+    | 1 | 0 | 0 |
+    | 0 | 1 | 0 |
+    | 1 | 1 | 1 |
+  TRUTH_TABLE
+end
+
+MyAndGate.verify_against_truth_table
+```
+
+The `#verify_against_truth_table` method evaluates the circuit for each row of the truth table and checks whether the outputs match the expected values.
+
+If the behavior of the circuit doesn't match the truth table, you'll see an error like this:
+
+```
+MyAndGate.new(0, 1).y should be 0 (RuntimeError)
+```
+
+This feature is useful for validating your logic circuits against formal truth tables as part of development or testing workflows.
+
+### Verifying sequential circuits
+
+Sequential circuits can also be verified using truth tables. When verifying a sequential circuit, the symbol `^` represents the rising edge of the clock.
+
+Here’s an example for a D flip-flop:
+
+```ruby
+class MyDFlipFlop < Logicuit::DSL
+  inputs :d, clock: :ck
+
+  outputs q: -> { d }
+
+  diagram <<~DIAGRAM
+    (D)--|   |--(Q)
+         |DFF|
+    (CK)-|>  |
+  DIAGRAM
+
+  truth_table <<~TRUTH_TABLE
+    | CK | D | Q |
+    | -- | - | - |
+    |  ^ | 0 | 0 |
+    |  ^ | 1 | 1 |
+  TRUTH_TABLE
+end
+
+MyDFlipFlop.verify_against_truth_table
+```
+
+In this table:
+
+- The `CK` column uses `^` to indicate a clock tick.
+- The circuit is initialized with the given inputs, then the clock is ticked once.
+- The outputs are evaluated immediately after the tick and compared against the expected values.
+
+This mechanism makes it easy to specify and verify the behavior of memory elements and registers.
+
+## 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 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/Rakefile

@@ -9,4 +9,15 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[test rubocop]
+require "steep/rake_task"
+Steep::RakeTask.new do |t|
+  t.check.severity_level = :error
+  t.watch.verbose
+end
+
+desc "Generate rbs files from inline comments"
+task "rbs-inline" do
+  sh "rbs-inline --output lib"
+end
+
+task default: %i[test rubocop rbs-inline steep]

data/Steepfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+target :app do
+  check "lib"
+  signature "sig"
+end

data/lib/logicuit/array_as_signal_group.rb

@@ -6,7 +6,7 @@ module Logicuit
   module ArrayAsSignalGroup
     refine Array do
       def >>(other)
-        Signals::SignalGroup.new(*self).connects_to(other)
+        Signals::SignalGroup.new(*self).connects_to(other) # steep:ignore
       end
     end
   end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Combinational
@@ -43,10 +45,12 @@ module Logicuit
               +-----------------|   |
         DIAGRAM
 
+        attr_reader :cin, :a, :b, :s, :c #: Signals::Signal
+
         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) }
+        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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Combinational
@@ -17,6 +19,8 @@ module Logicuit
           (B2)--|    |--------+  (B3)--|    |---(C)
         DIAGRAM
 
+        attr_reader :cin, :a0, :b0, :a1, :b1, :a2, :b2, :a3, :b3, :s0, :s1, :s2, :s3, :c #: Signals::Signal
+
         inputs :cin, :a0, :b0, :a1, :b1, :a2, :b2, :a3, :b3
 
         outputs :s0, :s1, :s2, :s3, :c
@@ -25,6 +29,8 @@ module Logicuit
           [[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
+            next full_addr.c if a.nil? || b.nil? || s.nil? # avoid rbs error and rubocop error...
+
             c >> full_addr.cin
             a >> full_addr.a
             b >> full_addr.b

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Combinational
@@ -15,6 +17,8 @@ module Logicuit
               +---|   |
         DIAGRAM
 
+        attr_reader :a, :b, :c, :s #: Signals::Signal
+
         inputs :a, :b
 
         outputs :c, :s

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Combinational
@@ -15,9 +17,11 @@ module Logicuit
           (A)--+-------|   |
         DIAGRAM
 
+        attr_reader :c0, :c1, :a, :y #: Signals::Signal
+
         inputs :c0, :c1, :a
 
-        outputs y: -> { (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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Combinational
@@ -27,9 +29,11 @@ module Logicuit
           (A)----+-|NOT|---+
         DIAGRAM
 
+        attr_reader :c0, :c1, :c2, :c3, :b, :a, :y #: Signals::Signal
+
         inputs :c0, :c1, :c2, :c3, :b, :a
 
-        outputs y: -> { (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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Sequential
@@ -11,6 +13,8 @@ module Logicuit
           (CK)-|>  |
         DIAGRAM
 
+        attr_reader :d, :q #: Signals::Signal
+
         inputs :d, clock: :ck
 
         outputs q: -> { d }

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Sequential
@@ -17,6 +19,8 @@ module Logicuit
                             (A)--|   |
         DIAGRAM
 
+        attr_reader :a, :y #: Signals::Signal
+
         inputs :a, clock: :ck
 
         outputs :y

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Sequential
@@ -13,6 +15,8 @@ module Logicuit
           (LD)--|  |
         DIAGRAM
 
+        attr_reader :a, :b, :c, :d, :ld, :qa, :qb, :qc, :qd #: Signals::Signal
+
         inputs :a, :b, :c, :d, :ld, clock: :ck
 
         outputs :qa, :qb, :qc, :qd
@@ -21,13 +25,15 @@ module Logicuit
           # inputs :cin, :a0, :b0, :a1, :b1, :a2, :b2, :a3, :b3
           fadd = Combinational::FullAdder4bit.new(0, 0, 1, 0, 0, 0, 0, 0, 0)
 
-          [[a, qa, :a0, :s0], [b, qb, :a1, :s1], [c, qc, :a2, :s2],
-           [d, qd, :a3, :s3]].each do |input, output, fadd_in, fadd_out|
+          [[a, qa, fadd.a0, fadd.s0], [b, qb, fadd.a1, fadd.s1], [c, qc, fadd.a2, fadd.s2],
+           [d, qd, fadd.a3, fadd.s3]].each do |input, output, fadd_in, fadd_out|
+            next if input.nil? || output.nil? || fadd_in.nil? || fadd_out.nil?
+
             dff = Sequential::DFlipFlop.new
             mux = Combinational::Multiplexer2to1.new
             input >> mux.c0
-            dff.q >> fadd.send(fadd_in)
-            fadd.send(fadd_out) >> mux.c1
+            dff.q >> fadd_in
+            fadd_out >> mux.c1
             ld    >> mux.a
             mux.y >> dff.d
             dff.q >> output

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Sequential
@@ -28,12 +30,16 @@ module Logicuit
           (LD)--+     (CK)--+
         DIAGRAM
 
+        attr_reader :a, :b, :c, :d, :ld, :qa, :qb, :qc, :qd #: Signals::Signal
+
         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|
+            next if input.nil? || output.nil?
+
             dff = Sequential::DFlipFlop.new
             mux = Combinational::Multiplexer2to1.new
             input >> mux.c0

data/lib/logicuit/circuits/td4/cpu.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Td4
@@ -7,16 +9,23 @@ module Logicuit
       class Cpu < DSL
         using Logicuit::ArrayAsSignalGroup
 
+        attr_reader :in0, :in1, :in2, :in3, :led1, :led2, :led3, :led4
+
         inputs :in0, :in1, :in2, :in3, clock: :ck
 
         outputs :led1, :led2, :led3, :led4
 
         assembling do
-          register_a, register_b, register_c = (:a..:c).map { Sequential::Register4bit.new }
+          register_a = Sequential::Register4bit.new
+          register_b = Sequential::Register4bit.new
+          register_c = Sequential::Register4bit.new
           pc = Sequential::ProgramCounter.new
           rom = Rom.new
           dec = Decoder.new
-          mux0, mux1, mux2, mux3 = (0..3).map { Combinational::Multiplexer4to1.new }
+          mux0 = Combinational::Multiplexer4to1.new
+          mux1 = Combinational::Multiplexer4to1.new
+          mux2 = Combinational::Multiplexer4to1.new
+          mux3 = Combinational::Multiplexer4to1.new
           alu = Combinational::FullAdder4bit.new
           dff = Sequential::DFlipFlop.new
 

data/lib/logicuit/circuits/td4/decoder.rb

@@ -1,18 +1,22 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Td4
       # Decoder class
       class Decoder < DSL
+        attr_reader :op3, :op2, :op1, :op0, :c_flag, :sel_b, :sel_a, :ld0, :ld1, :ld2, :ld3 #: Signals::Signal
+
         inputs :op3, :op2, :op1, :op0, :c_flag
 
         outputs sel_b: -> { op1 },
-                sel_a: -> { op3 || op0 },
-                ld0: -> { op3 || op2 },
-                ld1: -> { op3 || !op2 },
-                ld2: -> { !op3 || op2 },
-                ld3: -> { !op3 || !op2 || (!op0 && c_flag) }
+                sel_a: -> { op3 | op0 },
+                ld0: -> { op3 | op2 },
+                ld1: -> { op3 | !op2 },
+                ld2: -> { !op3 | op2 },
+                ld3: -> { !op3 | !op2 | (!op0 & c_flag) }
 
         truth_table <<~TRUTH_TABLE
           | OP3 | OP2 | OP1 | OP0 | C_FLAG | SEL_B | SEL_A | LD0 | LD1 | LD2 | LD3 |

data/lib/logicuit/circuits/td4/rom.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Circuits
     module Td4
       # Timer
       class Rom < DSL
+        attr_reader :a3, :a2, :a1, :a0, :d7, :d6, :d5, :d4, :d3, :d2, :d1, :d0 #: Signals::Signal
+
         inputs :a3, :a2, :a1, :a0
 
         outputs :d7, :d6, :d5, :d4, :d3, :d2, :d1, :d0
@@ -12,7 +16,7 @@ module Logicuit
         def evaluate
           return unless initialized
 
-          output = case "#{a3}#{a2}#{a1}#{a0}"
+          output = case self[:a3, :a2, :a1, :a0].to_s
                    in "0000" then "10110111"
                    in "0001" then "00000001"
                    in "0010" then "11100001"
@@ -30,9 +34,7 @@ module Logicuit
                    in "1110" then "10111000"
                    in "1111" then "11111111"
                    end
-          output.split("").zip([d7, d6, d5, d4, d3, d2, d1, d0]).each do |v, o|
-            v == "1" ? o.on : o.off
-          end
+          self[:d7, :d6, :d5, :d4, :d3, :d2, :d1, :d0].set output
         end
 
         truth_table <<~TRUTH_TABLE