ynl 0.3.0 → 0.4.2

data/lib/ynl/models.rb

@@ -1,11 +1,12 @@
 module Ynl
   module Models
-    Family = ::Struct.new(:name, :protocol, :protonum, :doc,
+    Family = ::Struct.new(:name, :protocol, :version, :protonum, :doc,
       :consts, :enums, :flags, :structs,
       :attribute_sets, :sub_messages, :operations, :mcast_groups)
     class Family
       def resolve
         structs.transform_values! {|s| s.resolve(self) }
+        sub_messages.transform_values! {|s| s.resolve(self) }
         attribute_sets.transform_values! {|s| s.resolve(self) }
         operations.transform_values! {|operation| operation.resolve(self) }
         self
@@ -29,9 +30,16 @@ module Ynl
     end
 
     Const = ::Struct.new(:name, :value, :doc)
+    Check = ::Struct.new(:operation, :value)
 
     class SubMessage
-      Format = ::Struct.new(:value, :attribute_set)
+      Format = ::Struct.new(:value, :fixed_header, :attribute_set) do
+        def resolve(f)
+          self.fixed_header = fixed_header.resolve(f) if fixed_header.is_a?(Thunk)
+          self.attribute_set = attribute_set.resolve(f) if attribute_set.is_a?(Thunk)
+          self
+        end
+      end
 
       attr_reader :name, :formats
 
@@ -41,6 +49,7 @@ module Ynl
       end
 
       def resolve(f)
+        formats.map! { it.resolve(f) }
         self
       end
     end
@@ -100,11 +109,16 @@ module Ynl
     end
 
     class AttributeSet
-      Attribute = ::Struct.new(:name, :type, :value, :checks, :doc) do
+      Attribute = ::Struct.new(:name, :type, :value, :checks, :doc, :multi_attr, :enum, :enum_as_flags) do
         def resolve(f)
           self.type = type.resolve(f)
+          self.enum = enum.resolve(f) if enum
           self
         end
+
+        def multi?
+          multi_attr
+        end
       end
 
       attr_reader :name, :name_prefix, :attributes, :doc
@@ -135,17 +149,14 @@ module Ynl
       end
 
       def attributes
-        # WORKAROUND: Some upstream specs (e.g. devlink) contain duplicate attribute
-        # entries in subset-of attribute sets. Deduplicate by name here until the
-        # upstream specs are fixed.
-        @attributes.uniq {|attr| attr.fetch('name') }.map do |attr|
-          name = attr.fetch('name')
-          superset.attributes.find { it.name == name } or raise ParseError "No attribute with name #{name}"
-        end
+        @attributes
       end
 
       def resolve(f)
+        attributes.map! { it.resolve(f) }
         self
+      rescue
+        raise ParseError, "Failed to resolve attribute subset: #{name}"
       end
     end
 

data/lib/ynl/parser.rb

@@ -4,6 +4,8 @@ require_relative 'models'
 
 module Ynl
   class Parser
+    # @param [String, #read] source
+    # @rbs (String | _Readable source) -> void
     def initialize(source)
       @yaml = YAML.load(source, aliases: true)
 
@@ -13,17 +15,24 @@ module Ynl
       @structs = {}
 
       @attribute_sets = {}
+      @attribute_definitions = {}
       @sub_messages = {}
       @operations = {}
       @mcast_groups = {}
     end
 
+    # @param [String, #to_path] path
+    # @return [Models::Family]
+    # @rbs (String | _PathLike path) -> Models::Family
     def self.parse_file(path)
       File.open(path) {|f| new(f) }.parse
     end
 
+    # @return [Models::Family]
+    # @rbs () -> Models::Family
     def parse
       protocol = @yaml['protocol'] || 'genetlink'
+      version = @yaml.fetch('version', 1)
       protonum = @yaml['protonum']
       name = @yaml['name']
       doc = translate_doc(@yaml['doc'])
@@ -86,6 +95,7 @@ module Ynl
       Models::Family.new(
         name:,
         protocol:,
+        version:,
         protonum:,
         doc:,
         consts: @consts,
@@ -106,9 +116,11 @@ module Ynl
         @consts[v.name] = v
       when 'enum'
         v = parse_enum_flags(d, type: :enum)
+        reject_enum_flags_name_collision(v.name, @flags)
         @enums[v.name] = v
       when 'flags'
         v = parse_enum_flags(d, type: :flags)
+        reject_enum_flags_name_collision(v.name, @enums)
         @flags[v.name] = v
       when 'struct'
         v = parse_struct(d)
@@ -118,19 +130,33 @@ module Ynl
       end
     end
 
+    private def reject_enum_flags_name_collision(name, other_definitions)
+      return unless other_definitions.key?(name)
+
+      raise ParseError, "Definition #{name.inspect} cannot be both an enum and flags"
+    end
+
     private def parse_const(d)
       name = "#{d['name-prefix']}#{d.fetch('name')}"
-      Models::Const.new(name, d.fetch('value'), translate_doc(d['doc']))
+      value = d.fetch('value')
+      unless value.is_a?(Integer) || value.is_a?(String)
+        raise ParseError, "Constant value must be a string or an integer: #{name}"
+      end
+
+      Models::Const.new(name, value, translate_doc(d['doc']))
     end
 
     private def parse_enum_flags(d, type:)
       cls = type == :enum ? Models::Enum : Models::Flags
       result = cls.new(name: d.fetch('name'), doc: translate_doc(d['doc']))
 
-      start_value = d['start-value'] || 0
-      value = type == :enum ? start_value : 1 << start_value
+      start_value = d['value-start'] || 0
+      raw_value = start_value
 
       d.fetch('entries').each do |v|
+        explicit_value = v.is_a?(Hash) ? v['value'] : nil
+        raw_value = explicit_value unless explicit_value.nil?
+        value = type == :enum ? raw_value : 1 << raw_value
         case v
         when String
           entry = cls::Entry.new(name: v, value:)
@@ -142,7 +168,7 @@ module Ynl
 
         result.entries << entry
 
-        value = type == :enum ? value + 1 : value << 1
+        raw_value += 1
 
       rescue
         raise ParseError, "Failed to parse enum/flags entry: #{v.fetch('name')}"
@@ -164,6 +190,7 @@ module Ynl
       when 'binary'
         Types::Binary.new(
           struct: d['struct'] ? Models::Thunk.new {|f| f.structs.fetch(d['struct']) } : nil,
+          length: d['len'],
           display_hint: d['display-hint'],
         )
       when 'pad'
@@ -184,10 +211,15 @@ module Ynl
           byte_order: parse_byte_order(d['byte-order']),
         )
       when 'binary'
-        Types::Binary.new(
-          struct: d['struct'] ? Models::Thunk.new {|f| f.structs.fetch(d.fetch('struct')) } : nil,
-          display_hint: d['display-hint'],
-        )
+        if d.key?('sub-type')
+          Types::PackedArray.new(sub_type: parse_packed_array_sub_type(d))
+        else
+          Types::Binary.new(
+            struct: d['struct'] ? Models::Thunk.new {|f| f.structs.fetch(d.fetch('struct')) } : nil,
+            length: nil,
+            display_hint: d['display-hint'],
+          )
+        end
       when 'string'
         Types::String.new
       when 'nest'
@@ -205,7 +237,7 @@ module Ynl
             type_values: d.fetch('type-value'),
           )
         else
-          Types::Binary.new(struct: nil, display_hint: nil)
+          Types::Binary.new(struct: nil, length: nil, display_hint: nil)
         end
       when 'sub-message'
         Types::SubMessage.new(
@@ -238,6 +270,7 @@ module Ynl
       when 'binary'
         Types::Binary.new(
           struct: nil,
+          length: nil,
           display_hint: d['display-hint'],
         )
       when 'nest'
@@ -249,13 +282,26 @@ module Ynl
       end
     end
 
+    private def parse_packed_array_sub_type(d)
+      sub_type = d.fetch('sub-type')
+      case sub_type
+      when 'u8', 'u16', 'u32', 'u64', 's8', 's16', 's32', 's64', 'int'
+        Types::Scalar.new(
+          type: sub_type,
+          byte_order: parse_byte_order(d['byte-order']),
+        )
+      else
+        raise ParseError, "Unknown packed-array sub-type: #{sub_type}"
+      end
+    end
+
     private def parse_byte_order(v)
       case v
       when nil
         :host
       when 'big-endian'
         :big
-      when 'litten-endian'
+      when 'little-endian'
         :little
       else
         raise ParseError, "Unknown endian: #{v}"
@@ -288,21 +334,8 @@ module Ynl
 
     private def parse_check(op, value_literal)
       case op
-      when 'max'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is greater than maximum #{value}" unless it <= #{value}}
-      when 'min'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is less than minimum #{value}" unless it >= #{value}}
-      when 'min-len'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is shorter than minimum length #{value}" unless it.bytesize >= #{value}}
-      when 'max-len'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is longer than maximum length #{value}" unless it.bytesize <= #{value}}
-      when 'exact-len'
-        value = parse_value(value_literal)
-        return %{raise ArgumentError, "Value \#{it.inspect} is not equal to length #{value}" unless it.bytesize == #{value}}
+      when 'max', 'min', 'min-len', 'max-len', 'exact-len'
+        Models::Check.new(operation: op, value: parse_value(value_literal))
       when 'unterminated-ok'
         return nil
       else
@@ -322,7 +355,7 @@ module Ynl
         (2 ** 31) - 1
       when String
         const = @consts[v] or raise ParseError, "Unknown value: #{v}"
-        const.value
+        const
       else
         raise ParseError, "Unknown value: #{v}"
       end
@@ -332,38 +365,72 @@ module Ynl
       name = d.fetch('name')
       if subset_of = d['subset-of']
         superset = @attribute_sets.fetch(subset_of)
-        result = Models::AttributeSubset.new(name:, superset:, attributes: d.fetch('attributes'), doc: translate_doc(d['doc']))
+        inherited = @attribute_definitions.fetch(subset_of).to_h { [it.fetch('name'), it] }
+        definitions = d.fetch('attributes').uniq { it.fetch('name') }.map do |override|
+          parent = inherited.fetch(override.fetch('name'))
+          parent.merge(override).merge('value' => parent.fetch('value'))
+        end
+        attributes = definitions.filter_map { parse_attribute(it) }
+        result = Models::AttributeSubset.new(name:, superset:, attributes:, doc: translate_doc(d['doc']))
       else
         name_prefix = d['name_prefix']
         result = Models::AttributeSet.new(name:, name_prefix:, doc: translate_doc(d['doc']))
         value = 0
-
-        d.fetch('attributes').each do |v|
+        definitions = d.fetch('attributes').map do |v|
           value = v.fetch('value', value + 1)
-          if type = parse_attribute_type(v)
-            attribute = Models::AttributeSet::Attribute.new(name: v.fetch('name'), type: type, value:)
-            result.attributes << attribute
-            if checks = v['checks']
-              attribute.checks = parse_checks(checks)
-            end
-          end
-        rescue
-          raise ParseError, "Failed to parse attribute: #{v.fetch('name')}"
+          v.merge('value' => value)
         end
+        result.attributes.concat(definitions.filter_map { parse_attribute(it) })
       end
 
       @attribute_sets[name] = result
+      @attribute_definitions[name] = definitions
 
-    rescue
-      raise ParseError, "Failed to parse attribute set: #{d.fetch('name')}"
+    rescue => error
+      raise ParseError, "Failed to parse attribute set #{d.fetch('name')}: #{error.message}"
+    end
+
+    private def parse_attribute(d)
+      multi_attr = d.fetch('multi-attr', false)
+      unless multi_attr == true || multi_attr == false
+        raise ParseError, "multi-attr must be a boolean"
+      end
+
+      enum_as_flags = d.fetch('enum-as-flags', false)
+      unless enum_as_flags == true || enum_as_flags == false
+        raise ParseError, "enum-as-flags must be a boolean"
+      end
+      if enum_as_flags && !d['enum']
+        raise ParseError, "enum-as-flags requires enum"
+      end
+
+      return unless type = parse_attribute_type(d)
+
+      Models::AttributeSet::Attribute.new(
+        name: d.fetch('name'),
+        type:,
+        value: d.fetch('value'),
+        checks: (parse_checks(d['checks']) if d['checks']),
+        doc: translate_doc(d['doc']),
+        multi_attr:,
+        enum: d['enum']&.then { |ref| Models::Thunk.new {|f| f.find_type(ref) } },
+        enum_as_flags:,
+      )
+    rescue => error
+      raise ParseError, "Failed to parse attribute #{d.fetch('name')}: #{error.message}"
     end
 
     private def parse_sub_message(d)
       name = d.fetch('name')
       result = Models::SubMessage.new(name:)
       d.fetch('formats', []).each do |fmt|
-        attr_set = fmt['attribute-set']&.then { @attribute_sets[it] }
-        result.formats << Models::SubMessage::Format.new(fmt['value'], attr_set)
+        fixed_header = fmt['fixed-header']&.then do |ref|
+          Models::Thunk.new {|f| f.structs.fetch(ref) }
+        end
+        attr_set = fmt['attribute-set']&.then do |ref|
+          Models::Thunk.new {|f| f.attribute_sets.fetch(ref) }
+        end
+        result.formats << Models::SubMessage::Format.new(fmt.fetch('value'), fixed_header, attr_set)
       end
       @sub_messages[name] = result
     end

data/lib/ynl/version.rb

@@ -1,3 +1,3 @@
 module Ynl
-  VERSION = '0.3.0'
+  VERSION = '0.4.2'
 end

data/lib/ynl.rb

@@ -1,12 +1,28 @@
-# Parse for YNL netlink specification
+# Parser for YNL netlink specification
 #
 # See: https://www.kernel.org/doc/html/latest/userspace-api/netlink/specs.html
+#-
 
 require_relative 'ynl/family'
 
+# Ynl parser and code generator. See {Family} for library entrypoint.
 module Ynl
+  # @rbs!
+  #   interface _Readable
+  #     def read: () -> String
+  #   end
+  #
+  #   interface _Writable
+  #     def write: (*String strings) -> untyped
+  #   end
+  #
+  #   interface _PathLike
+  #      def to_path: () -> String
+  #   end
+
   class ParseError < StandardError; end
 
+  # @private
   module Types
     Scalar = Data.define(:type, :byte_order) do
       def resolve(f)
@@ -27,13 +43,25 @@ module Ynl
       end
     end
     Binary = Struct.new(:struct, :length, :display_hint) do
+      using Generator::Refinements
+
       def resolve(f)
         self.struct = struct.resolve(f) if self.struct
         self
       end
 
       def rbs_type
-        '::String'
+        struct ? 'Structs::' + struct.name.as_class_name : '::String'
+      end
+    end
+    PackedArray = Struct.new(:sub_type) do
+      def resolve(f)
+        self.sub_type = sub_type.resolve(f)
+        self
+      end
+
+      def rbs_type
+        "::Array[#{sub_type.rbs_type}]"
       end
     end
     NestedAttributes = Struct.new(:attribute_set) do
@@ -69,7 +97,7 @@ module Ynl
       end
 
       def rbs_type
-        '::String'
+        '::Nl::SubMessage'
       end
     end
 
@@ -99,7 +127,7 @@ module Ynl
       end
 
       def rbs_type
-        '::Integer'
+        '::Nl::Bitfield32'
       end
     end
 

data/sig/generated/ynl/family.rbs

@@ -0,0 +1,24 @@
+# Generated from lib/ynl/family.rb with RBS::Inline
+
+module Ynl
+  # Entry points for generating family classes from YNL specifications.
+  class Family
+    # Builds a family class from a YNL specification file.
+    #
+    # @param [String, #to_path] path a path to a YNL specification file
+    # @return [Class<Nl::Family>] the generated family class
+    # @rbs (String | _PathLike path) -> Class
+    def self.build: (String | _PathLike path) -> Class
+
+    # Generates Ruby source code to define a family class from a YNL specification.
+    #
+    # @param [String, #read] source a YAML string or readable IO containing the YNL specification
+    # @param [#write] out the destination for the generated source code
+    # @option kwargs [String, nil] superclass the name of the generated class's superclass
+    # @option kwargs [String, nil] namespace the namespace in which to define the family class
+    # @option kwargs [String, nil] default_resolver the expression used as the default family resolver
+    # @return [String] the generated family class name
+    # @rbs (String | _Readable source, _Writable out, ?superclass: String?, ?namespace: String?, ?default_resolver: String?) -> String
+    def self.generate: (String | _Readable source, _Writable out, ?superclass: String?, ?namespace: String?, ?default_resolver: String?) -> String
+  end
+end

data/sig/generated/ynl/generator.rbs

@@ -0,0 +1,163 @@
+# Generated from lib/ynl/generator.rb with RBS::Inline
+
+module Ynl
+  # Generates Ruby code from a parsed YNL specification.
+  class Generator
+    # @private
+    module Refinements
+      WORD_DELIM: ::Regexp
+
+      def as_const_name: () -> untyped
+
+      def as_class_name: () -> untyped
+
+      def as_variable_name: () -> untyped
+
+      alias as_method_name as_variable_name
+
+      def as_string_literal: () -> untyped
+
+      def as_symbol_literal: () -> untyped
+    end
+
+    PRELUDE: untyped
+
+    OPERATION_FLAG_DOCS: untyped
+
+    KERNEL_DOC_REFERENCE: ::Regexp
+
+    # @rbs (Models::Family ynl, _Writable out) -> void
+    def initialize: (Models::Family ynl, _Writable out) -> void
+
+    # @rbs (?superclass: String?, ?namespace: String?, ?default_resolver: String?) -> void
+    def generate: (?superclass: String?, ?namespace: String?, ?default_resolver: String?) -> void
+
+    INDENT: untyped
+
+    NEWLINE: untyped
+
+    private def write: (*untyped str) -> untyped
+
+    private def indent: () -> untyped
+
+    private def emit_module: (untyped name) -> untyped
+
+    private def emit_class: (untyped name, ?untyped superclass) -> untyped
+
+    private def emit_singleton_class: () -> untyped
+
+    private def emit_const: (untyped name, untyped value, ?rbs: untyped, ?internal: untyped) -> untyped
+
+    private def emit_value_definitions: (untyped namespace, untyped definitions) -> untyped
+
+    private def enums_used_as_flags: () -> untyped
+
+    private def emit_getter: (untyped name, untyped expr) -> untyped
+
+    private def emit_internal: () -> untyped
+
+    private def emit_open: (raw: untyped, default_resolver: untyped, classname: untyped) -> untyped
+
+    private def emit_yard_open_params: (resolver: untyped, ?indentation: untyped) -> untyped
+
+    private def emit_comment: (untyped comment) -> untyped
+
+    private def operation_doc: (untyped operation) -> untyped
+
+    private def notification_operations: () -> untyped
+
+    private def notification_doc: (untyped operation) -> untyped
+
+    private def notification_layout: (untyped operation) -> untyped
+
+    private def emit_message_class: (untyped name, untyped message, fixed_header: untyped, attribute_set: untyped, doc: untyped) -> untyped
+
+    private def emit_sub_messages: () -> untyped
+
+    private def emit_sub_message_class: (untyped name, untyped format) -> untyped
+
+    private def parameter_rbs_type: (untyped param) -> untyped
+
+    private def parameter_yard_type: (untyped param) -> untyped
+
+    private def struct_member_rbs_type: (untyped type) -> untyped
+
+    private def struct_member_yard_type: (untyped type) -> untyped
+
+    private def input_rbs_type: (untyped type) -> untyped
+
+    private def input_yard_type: (untyped type) -> untyped
+
+    private def attribute_rbs_type: (untyped attribute) -> untyped
+
+    private def attribute_yard_type: (untyped attribute) -> untyped
+
+    private def attribute_doc: (untyped attribute) -> untyped
+
+    private def attribute_value_definition: (untyped attribute) -> untyped
+
+    private def sub_message_rbs_type: (untyped type) -> untyped
+
+    private def sub_message_yard_type: (untyped type) -> untyped
+
+    private def yard_type: (untyped type) -> untyped
+
+    private def emit_mcast_groups: () -> untyped
+
+    private def emit_subscription_methods: () -> untyped
+
+    private def emit_rbs_comment: (*untyped args) -> untyped
+
+    private def emit_yard_overload: (untyped signature) -> untyped
+
+    private def emit_yard_options: (untyped params, ?indentation: untyped) -> untyped
+
+    private def emit_yard_option: (untyped parameter, untyped name, untyped type, untyped description, ?indentation: untyped) -> untyped
+
+    private def emit_yard_attribute: (untyped name, untyped type, untyped description) -> untyped
+
+    private def emit_yard_param: (untyped name, untyped type, ?indentation: untyped) -> untyped
+
+    private def emit_yard_return: (untyped type, ?untyped description, ?indentation: untyped) -> untyped
+
+    private def emit_yard_see: (untyped object) -> untyped
+
+    private def emit_yard_yieldparam: (untyped name, untyped type, ?indentation: untyped) -> untyped
+
+    private def build_selector_plan: () -> untyped
+
+    private def require_selector: (untyped set, untyped selector) -> untyped
+
+    private def build_attribute_orders: () -> untyped
+
+    private def build_selector_sources: (untyped roots) -> untyped
+
+    private def validate_selector_values: () -> untyped
+
+    private def child_attribute_sets: (untyped type) -> untyped
+
+    private def attribute_by_name: (untyped set, untyped name) -> untyped
+
+    private def selector_source_literal: (untyped set, untyped selector) -> untyped
+
+    private def selector_bindings_literal: (untyped parent, untyped child) -> untyped
+
+    private def selector_value_literal: (untyped set, untyped selector, untyped format_value) -> untyped
+
+    private def to_datatype: (untyped type, untyped checks, ?owner: untyped) -> untyped
+
+    private def to_struct_member_datatype: (untyped type) -> untyped
+
+    private def to_checks: (untyped checks) -> untyped
+
+    private def to_check: (untyped check) -> untyped
+
+    private def check_message_value: (untyped check, untyped value) -> untyped
+
+    private def const_value_literal: (untyped value) -> untyped
+
+    private def integer_literal: (untyped value) -> untyped
+
+    private def mcast_group_value_literal: (untyped value) -> untyped
+  end
+end