kicad 0.8.1 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 679cc2e86c98081d38458ec0503b64fc176dec709a412bcc8fcee6ff1ccc9fbc
-  data.tar.gz: 5c4c4d2e0fa767c8c9c841f3235f7124c6f81b4aef66841e24c0e652b17dad52
+  metadata.gz: '097aa1cbc02ed277cface17ac18f0ee277328b17be825a7ca45d4e63bd0d7e50'
+  data.tar.gz: 9bd0c4a1ee66de76c8f4036d88e2e1e77f472f13ec3d0fc00ad81e52d625d8cd
 SHA512:
-  metadata.gz: ae34e7b3091ed815b836ca0f5f3f9f73ba5c622411279122f436949bb1a9e372c5d440795ba1f494cec5f5033a51f65578405c574ff70591a3db42640d5d7011
-  data.tar.gz: 8cf7ebfc425f27b4bd89389db45c6f3528236dd2c534b930a3102f5d06931ab383883db724d898f7eb67d518fdb5127aa384d91df74ef6fe03f59269f050d7d1
+  metadata.gz: 175c29e9a0d6fdd616b325c88cd5aa7e02e45735e13379356153814a8c02384486d0d998f79d4c580cf7621e07044552579547897ce32eb60bec310c5ed4622a
+  data.tar.gz: e42383f3dd059c3749e34ad48dd8201661930543d86ae15d50d8f4e1957be6293e7c0515b5b758d8e8233eb3132b4b1591a8548be251b8fc984de47d01854fed

data/README.md

@@ -6,21 +6,40 @@ Parse, load, modify and rewrite Kicad (s-epression) files into a convenient tree
 
     gem install kicad
 
-## Usage
+## Usage Example
+
+For all parts with no PartNumber property, copy it from the Value field and make sure it's hidden:
 
     $ irb -r kicad
-    irb(main):001> k = KiCad.load("my_file.kicad_sym").value
-    irb(main):001> k.children.filter{|c| KiCad::AST::Symbol === c }.map{|c| c.values[1]}
-    ["BC107", "CD4046"]
-    irb(main):001> puts k.emit
+    irb(main):001> k = KiCad.load('mylib.kicad_sym').value
+    => 
+    #<KiCad::AST::KicadSymbolLib:0x00000001473f5488
+    ...
+    irb(main):002> k.all_symbol.each{|s| s['PartNumber'] = s.property('Value') unless s.property('PartNumber') }; nil
+    => nil
+    irb(main):003> k.all_symbol.each{|s| s.property_node('PartNumber')&.hide = true }
+    => nil
+    irb(main):001> File.open("rewrite.kicad_sym", "w") { |f| f.puts k.emit }
     ...
 
 ## Development
 
-After checking out the repo, run `bundle` to install dependencies. Then, run `rake spec` to run the tests.
+After checking out the repo, run `bundle` to install dependencies.
 
 To install this gem onto your local machine from local source code, run `rake install`.
 
+## Resources
+
+KiCad uses a version of the Cadence SPECCTRA Design Language, defined in https://cdn.hackaday.io/files/1666717130852064/specctra.pdf
+
+KiCad's documentation of this is at https://dev-docs.kicad.org/en/file-formats/sexpr-intro/
+The documentation is incomplete. This library contains some items as found in KiCad 9 symbol libraries,
+and doesn't contain everything documented above, especially of those have not been found.
+Best efforts - if you find a problem, you discovered why this is open source.
+lib/kicad/asts.rb is your starting point for adding metedata.
+
+A related Rust library that was not consulted while building this is https://github.com/adom-inc/kicad_lib/tree/main/kicad_sexpr
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/cjheath/kicad-rb

data/lib/kicad/ast.rb

@@ -11,136 +11,386 @@ module KiCad
       def emit depth = 0
         "\t"*depth +
         '(' +
-        @values.map{|v| value(v) }*' ' +
+        @values.map{|v| String === v ? v.inspect : v.to_s }*' ' +
         (@children.size == 0 ? '' : "\n" + @children.map{|c| c.emit(depth+1) }*''+"\t"*depth) +
         ")\n"
       end
 
-      def value(v)
-        case v
-        when ::Symbol
-          v.to_s
-        when String
-          v.inspect
-        when Float, Integer
-          v.to_s
-        else
-          "Internal error"
+      # Define setter and getter methods for each value type this class allows
+      def self.value_types vts
+        i = 1   # @values[0] is always the class symbol
+        vts.each do |k, v|
+          # puts "#{self.name} attribute #{k.to_s} => #{v.inspect}"
+          # puts "attr_accessor #{self.name}.#{k} (values #{v.inspect}) is stored in @values[#{i}]"
+          begin
+            o = i # Avoid capturing i after the loop ends
+            define_method(:"#{k}") do
+              # puts "accessing #{self.class.name}.#{k} as @values[#{o}]"
+              @values[o]
+            end
+            define_method(:"#{k}=") do |v|
+              # puts "setting #{self.class.name}.#{k} as @values[#{o}]"
+              # REVISIT: Check valid data type matching v
+              @values[o] = v
+            end
+          end
+          i = i+1
         end
       end
+
+      def children_of_type *cts  # cts is an array of AST class symbols or strings
+        class_names = cts.flatten.map{|k| 'KiCad::AST::'+self.class.to_class_name(k)}
+        @children.filter{|h| class_names.include?(h.class.name) }
+      end
+
+      # Define methods for each child type this class allows
+      def self.child_types *cts
+        # puts "#{self.name} allows child types #{cts.inspect}"
+        cts.each do |c|
+          if Array === c
+            define_method(:"all_#{c[0].to_s}") do
+              # puts "Looking for all [#{class_names*', '}] in #{@children.map{|q| q.class.name}.inspect}"
+              children_of_type(c)
+            end
+            # REVISIT: Allow deleting and adding instances to the array
+            # new_child = KiCad.parse('(some new node)').value
+            # @children.append(new_child)
+          else
+            class_name = 'KiCad::AST::'+to_class_name(c)
+            define_method(:"#{c}") do
+              # puts "Looking for first #{class_name} in #{@children.map{|q| q.class.name}.inspect}"
+              a = children_of_type(c)
+              puts "Choosing first #{self.class.name}.#{c} of #{a.size}" if a.size > 1
+              a.first
+            end
+            # Allow deleting this instance
+            define_method(:"unset_#{c.to_s}") do
+              child = send(:"#{c}")
+              @children = @children - [child] if child
+              child ? true : nil
+            end
+          end
+        end
+      end
+
+      def self.to_class_name sym
+        sym.to_s.gsub(/\A[a-z]|_[a-z]/) {|from| from[-1].upcase }
+      end
+
+      def self.to_symbol class_name
+        class_name.to_s.gsub(/[A-Z]/) {|from| '_'+from[-1].downcase }.sub(/\A_/,'')
+      end
     end
 
     class KicadSymbolLib < Node
-      def initialize values, children
-        super
-      end
+      child_types :version, :generator, :generator_version, [:symbol]
     end
 
-    # Uncomment or add whatever class you need to customise:
+    class Generator < Node
+    end
 
-    class Symbol < Node
+    class GeneratorVersion < Node
     end
 
-=begin
+    class Version < Node
+    end
+
+    # Uncomment or add whatever class you need to customise:
+
+    # Position Identifier
     class At < Node
+      value_types :x => Float, :y => Float, :angle => Float
     end
 
-    class Center < Node
+    # Coordinate Point List
+    class Pts < Node
+      value_types({})
+      child_types [:xy]
     end
 
-    class Circle < Node
+    class Xy < Node
+      value_types :x => Float, :y => Float
     end
 
-    class Effects < Node
+    # Stroke Definition
+    class Stroke < Node
+      child_types :width, :type, :color
     end
 
-    class EmbeddedFonts < Node
+    class Width < Node
+      value_types :width => Float
     end
 
-    class End < Node
+    class Type < Node
+      value_types :type => [:dash, :dash_dot, :dash_dot_dot, :dot, :default, :solid]
     end
 
-    class ExcludeFromSim < Node
+    class Color < Node
+      value_types :r => Integer, :g => Integer, :b => Integer, :a => Integer
     end
 
-    class Fill < Node
+    # Text Effects
+    class Effects < Node
+      child_types :font, :justify, :hide
     end
 
     class Font < Node
+      child_types :face, :size, :thickness, :bold, :italic, :line_spacing
     end
 
-    class Generator < Node
+    class Face < Node
+      value_types :face_name => String
     end
 
-    class GeneratorVersion < Node
+    class Size < Node
+      value_types :height => Float, :width => Float
     end
 
-    class Hide < Node
+    class Thickness < Node
+      value_types :thickness => Float
     end
 
-    class InBom < Node
+    class Bold < Node
+      value_types :bold => [:no, :yes]
     end
 
-    class Length < Node
+    class Italic < Node
+      value_types :bold => [:no, :yes]
     end
 
-    class Name < Node
+    class LineSpacing < Node
+      value_types :line_spacing => Float
     end
 
-    class Number < Node
+    class Justify < Node
+      value_types :justify => [[:right, :left, :top, :bottom, :mirror]]   # Can have multiple
     end
 
-    class Offset < Node
+    class Hide < Node
+      value_types :hide => [:no, :yes]
     end
 
-    class OnBoard < Node
+    # Page Settings
+    class Paper < Node
+      # REVISIT: Either paper_size or width/height
+      value_types :paper_size => [:A0, :A1, :A2, :A3, :A4, :A5, :A, :B, :C, :D, :E],
+          :width => Float, :height => Float,
+          :portrait => [:portrait]
     end
 
-    class Pin < Node
+    # Title Block
+    class TitleBlock < Node
+      child_types :title, :date, :rev, :company,        # All take one string as value
+          [:comment]                                    # N (1..9) and String # REVISIT: Implement Comment
     end
 
-    class PinNames < Node
+    # Properties
+    class Property < Node
+      value_types :key => String, :value => String
+      child_types :at, :effects
+
+      # Set or clear (hide) on the property_node
+      def hide=(h = true)
+        v = (h ? :yes : :no)
+        if !effects                     # No effects yet
+          prop = KiCad.parse(%Q{(effects(hide #{v}))})&.value
+          @children.append(prop) if prop
+        elsif (existing = effects.hide) # Effects and hide already
+          existing.hide = v
+        else                            # Create new (hide) node
+          prop = KiCad.parse(%Q{(hide #{v})})&.value
+          @children.append(prop) if prop
+        end
+      end
     end
 
-    class PinNumbers < Node
+    # Universally Unique Identifier
+    class Uuid < Node
+      value_types :uuid => String
     end
 
-    class Polyline < Node
+    # Images
+    class Image < Node
+      child_types :at, :scale, :layer, :uuid, :data
     end
 
-    class Property < Node
+    class Data < Node
+      value_types :data => String    # REVISIT: Base64 data - not encoded as a string I think?
     end
 
-    class Pts < Node
+    class Circle < Node
+      child_types :center, :radius, :stroke, :fill
+    end
+
+    class Center < Xy
+      # value_types :x => Float, :y => Float
     end
 
     class Radius < Node
+      value_types :radius => Float
+    end
+
+    class Fill < Node
+      value_types :fill => [:no, :yes]
+    end
+
+    class Arc < Node
+      child_types :start, :mid, :end, :stroke, :fill
+    end
+
+    class Start < Xy
+      # value_types :x => Float, :y => Float
+    end
+
+    class Mid < Xy
+      # value_types :x => Float, :y => Float
+    end
+
+    class End < Xy
+      # value_types :x => Float, :y => Float
     end
 
     class Rectangle < Node
+      child_types :start, :end, :stroke, :fill
     end
 
-    class Size < Node
+    class Polyline < Node
+      child_types :pts, :stroke, :fill
     end
 
-    class Start < Node
+    class Text < Node
+      value_types :text => String
+      child_types :at, :effects
     end
 
-    class Stroke < Node
+    class Offset < Xy
+      # value_types :x => Float, :y => Float
     end
 
-    class Type < Node
+    # Symbol Pins
+    class Pin < Node
+      value_types :electrical_type => [
+            :input,                             # Pin is an input.
+            :output,                            # Pin is an output.
+            :bidirectional,                     # Pin can be both input and output.
+            :tri_state,                         # Pin is a tri-state output.
+            :passive,                           # Pin is electrically passive.
+            :free,                              # Not internally connected.
+            :unspecified,                       # Pin does not have a specified electrical type.
+            :power_in,                          # Pin is a power input.
+            :power_out,                         # Pin is a power output.
+            :open_collector,                    # Pin is an open collector output.
+            :open_emitter,                      # Pin is an open emitter output.
+            :no_connect,                        # Pin has no electrical connection.
+          ], :graphic_style => [
+            :line,
+            :inverted,
+            :clock,
+            :inverted_clock,
+            :input_low,
+            :clock_low,
+            :output_low,
+            :edge_clock_high,
+            :non_logic
+          ]
+      child_types :length, :name, :number
     end
 
-    class Version < Node
+    class Length < Node
+      value_types :length => Float
     end
 
-    class Width < Node
+    class Name < Node
+      value_types :name => String
+      child_types :effects
     end
 
-    class Xy < Node
+    class Number < Node
+      value_types :number => String
+      child_types :effects
+    end
+
+    class Polygon < Node
+      child_types :pts, :stroke, :fill
+    end
+
+    # Symbols
+    class Symbol < Node
+      value_types :id => String
+      child_types :extends, :exclude_from_sym, :pin_numbers, :pin_names, :in_bom, :on_board,
+        [:property],
+        [:shape, :circle, :rectangle, :text, :polyline, :arc],  # REVISIT: Lots more types of graphic items here...
+        [:pin],
+        [:symbol],      # Child symbols (units) embedded in a parent
+        :unit_name,
+        :embedded_fonts
+
+      # Get or set Property values by key, or as a Hash
+      def property_node k
+        self.all_property.detect{|p| p.key == k}
+      end
+
+      def property k = nil
+        if k
+          property_node(k)&.value
+        else  # Return all properties as a Hash
+          Hash[*self.all_property.map{|p| [p.key, p.value] }.flatten]
+        end
+      end
+
+      def [](k)
+        property[k]
+      end
+
+      def []=(k, v)
+        # puts "Setting property #{k} to #{v.inspect}"
+        if (prop = property_node(k))
+          prop.value = v
+        else  # Create new Property using the parser:
+          prop = KiCad.parse(%Q{
+            (property "#{k}" #{String === v ? v.inspect : v.to_s}
+              (at 0 0 0)
+              (effects(font(size 1.27 1.27)) (hide yes))
+            )
+          })&.value
+          @children.append(prop) if prop
+        end
+        prop
+      end
+    end
+
+    class Extends < Node
+      value_types :library_id => String
+    end
+
+    class PinNumbers < Node
+      value_types :hide => [:no, :yes]
+    end
+
+    class PinNames < Node
+      child_types :offset
+      value_types :hide => [:no, :yes]
+    end
+
+    class InBom < Node
+      value_types :in_bom => [:no, :yes]
+    end
+
+    class OnBoard < Node
+      value_types :on_board => [:no, :yes]
+    end
+
+    class UnitName < Node
+      value_types :name => String
+    end
+
+    class EmbeddedFonts < Node
+      value_types :embedded_fonts => [:no, :yes]
+    end
+
+    class ExcludeFromSim < Node
+      value_types :exclude_from_sim => [:no, :yes]
     end
-=end
 
   end
 end

data/lib/kicad/grammar.rb

@@ -33,19 +33,23 @@ module KiCad
 
     module Node2
       def s1
-        elements[1]
+        elements[0]
       end
 
-      def values
+      def s2
         elements[2]
       end
 
-      def nodes
+      def values
         elements[3]
       end
 
-      def s2
-        elements[5]
+      def nodes
+        elements[4]
+      end
+
+      def s3
+        elements[6]
       end
     end
 
@@ -74,84 +78,88 @@ module KiCad
       end
 
       i0, s0 = index, []
-      if (match_len = has_terminal?('(', false, index))
-        r1 = true
-        @index += match_len
-      else
-        terminal_parse_failure('\'(\'')
-        r1 = nil
-      end
+      r1 = _nt_s
       s0 << r1
       if r1
-        r2 = _nt_s
+        if (match_len = has_terminal?('(', false, index))
+          r2 = true
+          @index += match_len
+        else
+          terminal_parse_failure('\'(\'')
+          r2 = nil
+        end
         s0 << r2
         if r2
-          s3, i3 = [], index
-          loop do
-            i4, s4 = index, []
-            r5 = _nt_value
-            s4 << r5
-            if r5
-              r6 = _nt_s
-              s4 << r6
-            end
-            if s4.last
-              r4 = instantiate_node(SyntaxNode,input, i4...index, s4)
-              r4.extend(Node0)
-            else
-              @index = i4
-              r4 = nil
-            end
-            if r4
-              s3 << r4
-            else
-              break
-            end
-          end
-          if s3.empty?
-            @index = i3
-            r3 = nil
-          else
-            r3 = instantiate_node(SyntaxNode,input, i3...index, s3)
-          end
+          r3 = _nt_s
           s0 << r3
           if r3
-            s7, i7 = [], index
+            s4, i4 = [], index
             loop do
-              i8, s8 = index, []
-              r9 = _nt_node
-              s8 << r9
-              if r9
-                r10 = _nt_s
-                s8 << r10
+              i5, s5 = index, []
+              r6 = _nt_value
+              s5 << r6
+              if r6
+                r7 = _nt_s
+                s5 << r7
               end
-              if s8.last
-                r8 = instantiate_node(SyntaxNode,input, i8...index, s8)
-                r8.extend(Node1)
+              if s5.last
+                r5 = instantiate_node(SyntaxNode,input, i5...index, s5)
+                r5.extend(Node0)
               else
-                @index = i8
-                r8 = nil
+                @index = i5
+                r5 = nil
               end
-              if r8
-                s7 << r8
+              if r5
+                s4 << r5
               else
                 break
               end
             end
-            r7 = instantiate_node(SyntaxNode,input, i7...index, s7)
-            s0 << r7
-            if r7
-              if (match_len = has_terminal?(')', false, index))
-                r11 = true
-                @index += match_len
-              else
-                terminal_parse_failure('\')\'')
-                r11 = nil
+            if s4.empty?
+              @index = i4
+              r4 = nil
+            else
+              r4 = instantiate_node(SyntaxNode,input, i4...index, s4)
+            end
+            s0 << r4
+            if r4
+              s8, i8 = [], index
+              loop do
+                i9, s9 = index, []
+                r10 = _nt_node
+                s9 << r10
+                if r10
+                  r11 = _nt_s
+                  s9 << r11
+                end
+                if s9.last
+                  r9 = instantiate_node(SyntaxNode,input, i9...index, s9)
+                  r9.extend(Node1)
+                else
+                  @index = i9
+                  r9 = nil
+                end
+                if r9
+                  s8 << r9
+                else
+                  break
+                end
               end
-              s0 << r11
-              if r11
-                r12 = _nt_s
+              r8 = instantiate_node(SyntaxNode,input, i8...index, s8)
+              s0 << r8
+              if r8
+                if (match_len = has_terminal?(')', false, index))
+                  r12 = true
+                  @index += match_len
+                else
+                  terminal_parse_failure('\')\'')
+                  r12 = nil
+                end
                 s0 << r12
+                if r12
+                  r13 = _nt_s
+                  s0 << r13
+                end
               end
             end
           end

data/lib/kicad/grammar.tt

@@ -3,7 +3,7 @@ require 'kicad/ast'
 module KiCad
   grammar SExpr
     rule node
-      '(' s values:( value s)+ nodes:(node s)* ')' s
+      s '(' s values:( value s)+ nodes:(node s)* ')' s
       { def value
           klass_name = values.elements[0].value.value
           klass = KiCad::AST::Node

data/lib/kicad/version.rb

@@ -1,3 +1,3 @@
 module KiCad
-  VERSION = "0.8.1"
+  VERSION = "0.9.4"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: kicad
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.4
 platform: ruby
 authors:
 - Clifford Heath
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.8
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Load and rewrite Kicad s-expression files into a tree structure for scripting
 test_files: []