logicuit 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a2841e79a0daf8046710c6bd43d8862a3d9f28f482ab2b9cac2886b271f571f
-  data.tar.gz: 679b263308e15b0da229573bfd7be5cf02c8e65bd98fb01753874afb3fe56413
+  metadata.gz: 7ab72694854386c09ba2b86561b6f71f96ea150cbc75384cac6b367a1ef77678
+  data.tar.gz: 033acc2d10c17e90f32dae9af915e92fd81064c88ff8174842821676b5d11fa4
 SHA512:
-  metadata.gz: 3e942269a9b55dad3f7efff1d68935f431952d0c3276d7d290461dabe84230f6d6d1d0eb2f307b6dd375c2d3b1261c8e2e7c72f1faa17db0de576cee9c37c0da
-  data.tar.gz: 3f1428cced00eee1798ea56dc9cfb169eb041b40bfc514a729d1cd3d67ce4b05d93ea633a9290c3ac22432aa1bfeb384e8de20cee59a0e463c582bf82be61ea4
+  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
 

data/README.md

@@ -40,6 +40,7 @@ A Ruby-based logic circuit simulator featuring an internal DSL for building circ
 - [Assembling](#assembling)
 - [SignalGroup](#signalgroup)
 - [Sequential Circuits](#sequential-circuits)
+- [Truth Table Verification](#truth-table-verification)
 - [Demo: Ramen Timer](#demo-ramen-timer)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -72,7 +73,7 @@ require "logicuit"
 class MyAndGate < Logicuit::DSL
   inputs :a, :b
 
-  outputs y: -> { a && b }
+  outputs y: -> { a & b }
 
   diagram <<~DIAGRAM
     (A)-|   |
@@ -90,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.
@@ -383,7 +397,85 @@ 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
+## 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).
 

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

data/lib/logicuit/dsl.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# steep:ignore:start
+
 # Logicuit module
 module Logicuit
   # base class for all gates and circuits
@@ -26,7 +28,9 @@ module Logicuit
 
     def self.inputs(*args, **kwargs)
       # define getter methods for inputs
-      attr_reader(*args)
+      args.each do |arg|
+        attr_reader(arg) unless instance_methods.include?(arg)
+      end
 
       # define initializer for inputs
       define_method(:inputs) do |*instance_method_args|
@@ -54,7 +58,9 @@ module Logicuit
 
     def self.outputs(*args, **kwargs)
       # define getter methods for outputs
-      attr_reader(*(args + kwargs.keys))
+      (args + kwargs.keys).each do |arg|
+        attr_reader(arg) unless instance_methods.include?(arg)
+      end
 
       # define initializer for outputs
       define_method(:outputs) do
@@ -71,19 +77,13 @@ module Logicuit
         return unless initialized
 
         kwargs.each do |output, evaluator|
-          signal = instance_variable_get("@#{output}")
-          e_args = if override_args.empty?
-                     @input_targets.map do |input|
-                       instance_variable_get("@#{input}").current
-                     end
-                   else
-                     override_args
-                   end
-          if @inputs_as_bool_struct.new(*e_args).instance_exec(&evaluator)
-            signal.on
-          else
-            signal.off
-          end
+          ret = if override_args.empty?
+                  instance_exec(&evaluator)
+                else
+                  o = @inputs_as_bool_struct.new(*override_args)
+                  o.instance_exec(&evaluator)
+                end
+          send(output).send(ret.current ? :on : :off)
         end
       end
     end
@@ -134,6 +134,8 @@ module Logicuit
           array = [values]
           while array.any? { _1.any? { |v| v == :any } }
             target_index = array.find_index { _1.any? { |v| v == :any } }
+            next if target_index.nil? # avoid rbs error...
+
             target = array[target_index]
             prop_index = target.find_index { |v| v == :any }
             array.delete_at(target_index)
@@ -168,9 +170,9 @@ module Logicuit
           if value.is_a?(Array) && value.first == :ref
             expected = previous_values[value.last]
 
-            raise "#{self}.new(#{args.join(", ")}).#{key} should be #{expected}" unless expected == subject.send(key).current
+            raise "#{self}.new(#{args.join(", ")}).#{key} should be #{expected ? 1 : 0}" unless expected == subject.send(key).current
           else
-            raise "#{self}.new(#{args.join(", ")}).#{key} should be #{value}" unless value == subject.send(key).current
+            raise "#{self}.new(#{args.join(", ")}).#{key} should be #{value ? 1 : 0}" unless value == subject.send(key).current
           end
         end
       end
@@ -181,3 +183,5 @@ module Logicuit
     end
   end
 end
+
+# steep:ignore:end

data/lib/logicuit/gates/and.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Gates
     # AND gate
@@ -10,9 +12,11 @@ module Logicuit
         (B)-|   |
       DIAGRAM
 
+      attr_reader :a, :b, :y #: Signals::Signal
+
       inputs :a, :b
 
-      outputs y: -> { a && b }
+      outputs y: -> { a & b }
 
       truth_table <<~TRUTH_TABLE
         | A | B | Y |

data/lib/logicuit/gates/nand.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Gates
     # NAND gate
@@ -10,9 +12,11 @@ module Logicuit
         (B)-|    |
       DIAGRAM
 
+      attr_reader :a, :b, :y #: Signals::Signal
+
       inputs :a, :b
 
-      outputs y: -> { !(a && b) }
+      outputs y: -> { !(a & b) }
 
       truth_table <<~TRUTH_TABLE
         | A | B | Y |

data/lib/logicuit/gates/not.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Gates
     # NOT gate
@@ -8,6 +10,8 @@ module Logicuit
         (A)-|NOT|-(Y)
       DIAGRAM
 
+      attr_reader :a, :y #: Signals::Signal
+
       inputs :a
 
       outputs y: -> { !a }

data/lib/logicuit/gates/or.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Gates
     # OR gate
@@ -10,9 +12,11 @@ module Logicuit
         (B)-|  |
       DIAGRAM
 
+      attr_reader :a, :b, :y #: Signals::Signal
+
       inputs :a, :b
 
-      outputs y: -> { a || b }
+      outputs y: -> { a | b }
 
       truth_table <<~TRUTH_TABLE
         | A | B | Y |

data/lib/logicuit/gates/xor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Logicuit
   module Gates
     # XOR gate
@@ -10,9 +12,11 @@ module Logicuit
         (B)-|   |
       DIAGRAM
 
+      attr_reader :a, :b, :y #: Signals::Signal
+
       inputs :a, :b
 
-      outputs y: -> { (a && !b) || (!a && b) }
+      outputs y: -> { (a & !b) | (!a & b) }
 
       truth_table <<~TRUTH_TABLE
         | A | B | Y |

data/lib/logicuit/runner.rb

@@ -23,7 +23,7 @@ module Logicuit
       render.call
     end
 
-    while (input = gets.chomp)
+    while (input = gets&.chomp)
       key = input.to_sym
       unless circuit.respond_to? key
         if circuit.clock && hz.zero?

data/lib/logicuit/signals/clock.rb

@@ -16,7 +16,7 @@ module Logicuit
         # Call the `evaluate` method for all components.
         # However, the input argument values should be bound to the values at the time `tick` is called.
         @downstreams.map do |component|
-          args = component.input_targets.map { |input| component.instance_variable_get("@#{input}").current }
+          args = component.input_targets.map { |input| Signal.new(component.send(input).current) }
           -> { component.evaluate(*args) }
         end.each(&:call)
       end