ynl 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e9f2afaf5ceef180b6fdfbe4e823d73f9f3a456b150f5b6bc1da9656ab3fdc4
-  data.tar.gz: e85e2ac604e46a15a8bae4097255882aec8edbfb7413100403f1ff4b7a6f8d91
+  metadata.gz: e19f2ff09effa0411bc676e0eb2356129f8aa496ec4bbf1df66935268d4e6763
+  data.tar.gz: 72bfd23c64c44dd2db4b449e6863c7855e34c1ed2c774b5f2ff3e16f7fd7910f
 SHA512:
-  metadata.gz: f22bce88df788cc8a332d8186cf93e25050ce459635dafbf13190739078c8325dae954123a41a5e1e84c4f60431678660373eee71890e3d6788a0f8ec4cdf708
-  data.tar.gz: 1e700baaba42287f513733403c4d49e96130aeed616ac88f76ac0acd1dd7c123a552144534fb803fc57b5a57b394bd4dcb3e1bc2d464e17211df880738181019
+  metadata.gz: c3c294f02102bb2031e6681a17a5bd92dfd4bbde39db1c94302dd8775756d34b47d1bea3ff0a7c94f4f5a857569fc2c4a658ae80ff275c7b109094c0d9b208c7
+  data.tar.gz: 941d649b3233024963fabd1bd51d083b3ba22639dfb15e9b2e74df5264b948fb82ac152d86751f6352be28d2a4a283c10aba2dbddcd154744db810594bbee821

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## v0.3.0 (2026-09-01)
+
+- Generate notification and event message classes, multicast group metadata,
+  and typed subscription methods.
+- Generate nested type-value attributes with their declared type-key depth.
+- Generate methods for operations with implicit empty requests.
+
 ## v0.2.4 (2026-08-22)
 
 - Assign correct values to attributes following `unused` entries.

data/lib/ynl/generator.rb

@@ -37,6 +37,12 @@ module Ynl
       require 'nl'
     RUBY
 
+    OPERATION_FLAG_DOCS = {
+      'admin-perm' => 'Requires CAP_NET_ADMIN in the initial user namespace.',
+      'uns-admin-perm' => 'Requires CAP_NET_ADMIN in the user namespace owning the network namespace.',
+    }.freeze
+    private_constant :OPERATION_FLAG_DOCS
+
     def initialize(ynl, out)
       @ynl = ynl
       @out = out
@@ -58,6 +64,8 @@ module Ynl
           emit_const('PROTOCOL', "Ractor.make_shareable(::Nl::Protocols::Genl.new(#{@ynl.name.as_string_literal}))")
         end
 
+        emit_mcast_groups
+
         emit_module('Structs') do
           @ynl.structs.each do |name, struct|
             emit_comment(struct.doc)
@@ -115,6 +123,7 @@ module Ynl
                   emit_const('TYPE', attr.value)
                   emit_const('NAME', attr.name.as_variable_name.as_symbol_literal)
                   if attr.type.is_a?(Types::NestedAttributes) ||
+                    attr.type.is_a?(Types::NestTypeValue) ||
                     (attr.type.is_a?(Types::IndexedArray) && attr.type.sub_type.is_a?(Types::NestedAttributes))
                     deferred_consts << ["#{name.as_class_name}::#{attr.name.as_class_name}::DATATYPE", to_datatype(attr.type, attr.checks)]
                   else
@@ -162,58 +171,43 @@ module Ynl
             %w[do dump].each do |method|
               if request_reply = oper.public_send(method + 'it')
                 %w[request reply].to_h { [it, request_reply.public_send(it)] }.compact.each do |type, msg|
-                  emit_comment(oper.doc)
-                  emit_class(method.as_class_name + oper.name.as_class_name + type.as_class_name, "#{@protocol}::Message") do
-                    emit_const('TYPE', msg.value)
-                    emit_const('FIXED_HEADER', oper.fixed_header&.then { 'Structs::' + it.name.as_class_name } || 'nil')
-                    emit_const('ATTRIBUTE_SET', "AttributeSets::#{oper.attribute_set.name.as_class_name}")
-                    params = msg.attributes
-                    attribute_params = oper.attribute_set.attributes.map(&:name) & params
-                    emit_const('ATTRIBUTES', "Ractor.make_shareable(%i[#{attribute_params.map { it.as_variable_name }.join(' ')}])")
-                    oper.fixed_header.members.each do |member|
-                      param = member.name
-                      datatype = member.type
-                      next if datatype.is_a? Types::Pad
-                      next if attribute_params.include?(param)
-                      emit_comment("Gets the value of `#{param}` field in the message's fixed header.")
-                      emit_rbs_comment(
-                        'return: ' + datatype.rbs_type,
-                      )
-                      emit_getter(param.as_method_name, "fixed_header.#{param.as_method_name}")
-                    end if oper.fixed_header
-                    attribute_params.each do |param|
-                      datatype = oper.attribute_set.attributes.find { it.name == param }.type
-                      next if datatype.is_a? Types::Pad
-                      extending = oper.fixed_header&.members&.any? { it.name == param }
-
-                      if extending
-                        emit_comment("Gets the value of `#{param}` attribute or fixed header in the message.")
-                      else
-                        emit_comment("Gets the value of `#{param}` attribute in the message.")
-                      end
-                      emit_rbs_comment(
-                        'return: ' + datatype.rbs_type,
-                      )
-                      if extending
-                        # If the fixed header and the attribute set have the same-name parameter, the value from the attribute should have
-                        # the precedence over that from the header.
-                        emit_getter(param.as_method_name, "attributes[#{param.as_variable_name.as_symbol_literal}]&.value || fixed_header.#{param.as_method_name}")
-                      else
-                        emit_getter(param.as_method_name, "attributes[#{param.as_variable_name.as_symbol_literal}]&.value")
-                      end
-                    end
-                  end
+                  emit_message_class(
+                    method.as_class_name + oper.name.as_class_name + type.as_class_name,
+                    msg,
+                    fixed_header: oper.fixed_header,
+                    attribute_set: oper.attribute_set,
+                    doc: operation_doc(oper),
+                  )
                 end
               end
             end
           end
         end
 
+        emit_module('Notifications') do
+          notification_operations.each do |oper|
+            message, fixed_header, attribute_set = notification_layout(oper)
+            emit_message_class(
+              oper.name.as_class_name,
+              message,
+              fixed_header:,
+              attribute_set:,
+              doc: notification_doc(oper),
+            )
+          end
+        end
+
+        emit_const(
+          'NOTIFICATIONS',
+          "Ractor.make_shareable({#{notification_operations.map { |oper| "#{oper.notification.message.value} => Notifications::#{oper.name.as_class_name}" }.join(', ') }})",
+          rbs: 'Hash[::Integer, ::Class]',
+        )
+
         # emit request methods
         @ynl.operations.each do |name, oper|
           %w[do dump].each do |method|
             if request_reply = oper.public_send(method + 'it')
-              next unless request = request_reply.request  # FIXME: what should we do in this case?
+              request = request_reply.request
 
               request_class = "Messages::#{method.as_class_name}#{oper.name.as_class_name}Request"
               reply_class = request_reply.reply ? "Messages::#{method.as_class_name}#{oper.name.as_class_name}Reply" : 'nil'
@@ -227,7 +221,7 @@ module Ynl
               rbs_params = params.map { |it| "?#{it.name.as_variable_name}: #{it.type.rbs_type}" }.join(', ')
               rbs_result = request_reply.reply ? reply_class : 'void'
 
-              emit_comment(oper.doc)
+              emit_comment(operation_doc(oper))
               if method == 'dump'
                 emit_rbs_comment(
                   "(#{rbs_params}) -> Enumerable[#{rbs_result}]\n  | (#{rbs_params}) { (#{rbs_result}) -> void } -> void",
@@ -249,6 +243,50 @@ module Ynl
             end
           end
         end
+
+        emit_class('AsyncOperations') do
+          emit_nodoc
+          write('def initialize(&exchange)')
+          indent do
+            write('@exchange = exchange')
+          end
+          write('end')
+
+          @ynl.operations.each do |name, oper|
+            %w[do dump].each do |method|
+              next unless request_reply = oper.public_send(method + 'it')
+
+              request_class = "Messages::#{method.as_class_name}#{oper.name.as_class_name}Request"
+              reply_class = request_reply.reply ? "Messages::#{method.as_class_name}#{oper.name.as_class_name}Reply" : 'nil'
+              header_params = oper.fixed_header&.members || []
+              attribute_params = oper.attribute_set.attributes.filter { request_reply.request.attributes.include?(it.name) }
+              attribute_params.reject! {|a| header_params.any? {|h| h.name == a.name } }
+              params = (header_params + attribute_params).reject { it.type.is_a? Types::Pad }
+              rbs_params = params.map { |it| "?#{it.name.as_variable_name}: #{it.type.rbs_type}" }.join(', ')
+              result = request_reply.reply ? reply_class : 'void'
+              operation = method == 'dump' ? "::Nl::Async::Stream[#{result}]" : "::Nl::Async::Future[#{result}]"
+
+              emit_comment(operation_doc(oper))
+              emit_rbs_comment("(#{rbs_params}) -> #{operation}")
+              write("def #{method.as_method_name}_#{oper.name.as_method_name}(**args)")
+              indent do
+                write("@exchange.call(#{method.as_symbol_literal}, #{request_class}, #{reply_class}, args)")
+              end
+              write('end')
+            end
+          end
+        end
+
+        emit_comment('Returns the asynchronous operation facade for this family.')
+        emit_rbs_comment('(?stream_capacity: ::Integer?) -> AsyncOperations')
+        write('def async(stream_capacity: nil)')
+        indent do
+          write('return @async_operations ||= build_async_facade(AsyncOperations) if stream_capacity.nil?')
+          write('build_async_facade(AsyncOperations, stream_capacity:)')
+        end
+        write('end')
+
+        emit_subscription_methods unless @ynl.mcast_groups.empty?
       end
 
       classname
@@ -310,6 +348,109 @@ module Ynl
       end
     end
 
+    private def operation_doc(operation)
+      flag_docs = operation.flags.filter_map { OPERATION_FLAG_DOCS[it] }
+      [operation.doc, *flag_docs].compact.join("\n\n")
+    end
+
+    private def notification_operations
+      @notification_operations ||= @ynl.operations.values.select(&:notification)
+    end
+
+    private def notification_doc(operation)
+      group = operation.notification.group
+      [operation.doc, ("Multicast group: `#{group.name}`." if group)].compact.join("\n\n")
+    end
+
+    private def notification_layout(operation)
+      notification = operation.notification
+      if notification.kind == :event
+        [notification.message, operation.fixed_header, operation.attribute_set]
+      else
+        source = notification.source
+        mode = source.doit || source.dumpit
+        reply = mode&.reply
+        unless reply
+          selected = source.doit ? 'do' : 'dump'
+          raise ParseError,
+            "Notification #{operation.name.inspect} references #{source.name.inspect}, which has no #{selected} reply"
+        end
+        message = Models::Message.new(
+          value: notification.message.value,
+          attributes: reply.attributes,
+        )
+        [message, source.fixed_header, source.attribute_set]
+      end
+    end
+
+    private def emit_message_class(name, message, fixed_header:, attribute_set:, doc:)
+      emit_comment(doc)
+      emit_class(name, "#{@protocol}::Message") do
+        emit_const('TYPE', message.value)
+        emit_const('FIXED_HEADER', fixed_header&.then { 'Structs::' + it.name.as_class_name } || 'nil')
+        emit_const('ATTRIBUTE_SET', "AttributeSets::#{attribute_set.name.as_class_name}")
+        attribute_params = attribute_set.attributes.map(&:name) & message.attributes
+        emit_const('ATTRIBUTES', "Ractor.make_shareable(%i[#{attribute_params.map { it.as_variable_name }.join(' ')}])")
+        fixed_header&.members&.each do |member|
+          param = member.name
+          datatype = member.type
+          next if datatype.is_a? Types::Pad
+          next if attribute_params.include?(param)
+          emit_comment("Gets the value of `#{param}` field in the message's fixed header.")
+          emit_rbs_comment('return: ' + datatype.rbs_type)
+          emit_getter(param.as_method_name, "fixed_header.#{param.as_method_name}")
+        end
+        attribute_params.each do |param|
+          datatype = attribute_set.attributes.find { it.name == param }.type
+          next if datatype.is_a? Types::Pad
+          extending = fixed_header&.members&.any? { it.name == param }
+
+          if extending
+            emit_comment("Gets the value of `#{param}` attribute or fixed header in the message.")
+          else
+            emit_comment("Gets the value of `#{param}` attribute in the message.")
+          end
+          emit_rbs_comment('return: ' + datatype.rbs_type)
+          if extending
+            emit_getter(param.as_method_name, "attributes[#{param.as_variable_name.as_symbol_literal}]&.value || fixed_header.#{param.as_method_name}")
+          else
+            emit_getter(param.as_method_name, "attributes[#{param.as_variable_name.as_symbol_literal}]&.value")
+          end
+        end
+      end
+    end
+
+    private def emit_mcast_groups
+      groups = @ynl.mcast_groups.values
+      grouped = groups.group_by { it.name.as_variable_name }
+      if collision = grouped.find { |_name, matches| matches.length > 1 }
+        ruby_name, matches = collision
+        raise ParseError,
+          "Multicast groups #{matches.map(&:name).map(&:inspect).join(' and ')} normalize to #{ruby_name.to_sym.inspect}"
+      end
+
+      entries = groups.map do |group|
+        key = group.name.as_variable_name.as_symbol_literal
+        value = "::Nl::McastGroup.new(#{group.name.as_string_literal}, #{group.value.inspect})"
+        "#{key} => #{value}"
+      end
+      emit_const(
+        'MCAST_GROUPS',
+        "Ractor.make_shareable({#{entries.join(', ')}})",
+        rbs: 'Hash[::Symbol, ::Nl::McastGroup]',
+      )
+    end
+
+    private def emit_subscription_methods
+      group_type = @ynl.mcast_groups.values
+        .map { ":#{it.name.as_variable_name}" }
+        .join(' | ')
+      emit_rbs_comment("(*(#{group_type}) groups) -> self")
+      write('def subscribe(*groups) = super')
+      emit_rbs_comment("(*(#{group_type}) groups) -> self")
+      write('def unsubscribe(*groups) = super')
+    end
+
     private def emit_rbs_comment(*args)
       write('#--')
       args.each do |arg|
@@ -337,6 +478,8 @@ module Ynl
         # end
       when Types::NestedAttributes
         "#{@protocol}::DataTypes::NestedAttributes.new(#{type.attribute_set.name.as_class_name})"
+      when Types::NestTypeValue
+        "#{@protocol}::DataTypes::NestTypeValue.new(#{type.attribute_set.name.as_class_name}, #{type.type_values.length})"
       when Types::IndexedArray
         "#{@protocol}::DataTypes::IndexedArray.new(#{to_datatype(type.sub_type, nil)})"
       when Types::SubMessage

data/lib/ynl/models.rb

@@ -7,6 +7,7 @@ module Ynl
       def resolve
         structs.transform_values! {|s| s.resolve(self) }
         attribute_sets.transform_values! {|s| s.resolve(self) }
+        operations.transform_values! {|operation| operation.resolve(self) }
         self
       end
 
@@ -148,22 +149,47 @@ module Ynl
       end
     end
 
+    McastGroup = ::Struct.new(:name, :value, :doc)
+
     class Operation
-      attr_reader :name, :doc, :fixed_header, :attribute_set, :doit, :dumpit
+      attr_reader :name, :doc, :flags, :fixed_header, :attribute_set, :doit, :dumpit, :notification
 
-      def initialize(name:, doc:, fixed_header:, attribute_set:, doit:, dumpit:)
+      def initialize(name:, doc:, flags:, fixed_header:, attribute_set:, doit:, dumpit:, notification:)
         @name = name
         @doc = doc
+        @flags = flags
         @fixed_header = fixed_header
         @attribute_set = attribute_set
         @doit = doit
         @dumpit = dumpit
+        @notification = notification
       end
 
       def resolve(f)
         @doit = @doit&.resolve(f)
         @dumpit = @dumpit&.resolve(f)
+        @notification = @notification&.resolve(f)
+        self
+      end
+    end
+
+    class Notification
+      attr_reader :kind, :message, :source, :group
+
+      def initialize(kind:, message:, source:, group:)
+        @kind = kind
+        @message = message
+        @source = source
+        @group = group
+      end
+
+      def resolve(f)
+        @message = @message.resolve(f)
+        @source = f.operations.fetch(@source) if @source
+        @group = f.mcast_groups.fetch(@group) if @group
         self
+      rescue KeyError => error
+        raise ParseError, "Failed to resolve #{kind} notification: #{error.message}"
       end
     end
 

data/lib/ynl/parser.rb

@@ -79,7 +79,7 @@ module Ynl
           end
         end
       end
-      @yaml['mcast-groups']&.each do |d|
+      @yaml.dig('mcast-groups', 'list')&.each do |d|
         parse_mcast_group(d)
       end
 
@@ -200,8 +200,9 @@ module Ynl
         )
       when 'nest-type-value'
         if d['nested-attributes']
-          Types::NestedAttributes.new(
+          Types::NestTypeValue.new(
             attribute_set: Models::Thunk.new {|f| f.attribute_sets.fetch(d.fetch('nested-attributes')) },
+            type_values: d.fetch('type-value'),
           )
         else
           Types::Binary.new(struct: nil, display_hint: nil)
@@ -384,18 +385,35 @@ module Ynl
 
       doit = d['do']&.then { parse_request_reply(it, default_request_id: request_id, default_reply_id: reply_id) }
       dumpit = d['dump']&.then { parse_request_reply(it, default_request_id: request_id, default_reply_id: reply_id) }
-
-      # TODO: notify
+      notification = parse_notification(d, default_id: reply_id)
 
       @operations[name] = Models::Operation.new(
-        name:, doc: translate_doc(d['doc']), fixed_header:, attribute_set:,
-        doit:, dumpit:,
+        name:, doc: translate_doc(d['doc']), flags: d.fetch('flags', []), fixed_header:, attribute_set:,
+        doit:, dumpit:, notification:,
       )
     end
 
+    private def parse_notification(d, default_id:)
+      if source = d['notify']
+        Models::Notification.new(
+          kind: :notify,
+          message: parse_message({}, default_id:),
+          source:,
+          group: d['mcgrp'],
+        )
+      elsif event = d['event']
+        Models::Notification.new(
+          kind: :event,
+          message: parse_message(event, default_id:),
+          source: nil,
+          group: d['mcgrp'],
+        )
+      end
+    end
+
     private def parse_request_reply(d, default_request_id:, default_reply_id:)
       Models::RequestReply.new(
-        request: d['request']&.then { parse_message(it, default_id: default_request_id) },
+        request: parse_message(d.fetch('request', {}), default_id: default_request_id),
         reply: d['reply']&.then { parse_message(it, default_id: default_reply_id) },
       )
     end
@@ -405,6 +423,12 @@ module Ynl
     end
 
     private def parse_mcast_group(d)
+      name = d.fetch('name')
+      @mcast_groups[name] = Models::McastGroup.new(
+        name,
+        d['value'],
+        translate_doc(d['doc']),
+      )
     end
 
     private def translate_doc(doc)

data/lib/ynl/version.rb

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

data/lib/ynl.rb

@@ -33,7 +33,7 @@ module Ynl
       end
 
       def rbs_type
-        'untyped'
+        '::String'
       end
     end
     NestedAttributes = Struct.new(:attribute_set) do
@@ -48,6 +48,20 @@ module Ynl
         'AttributeSets::' + attribute_set.name.as_class_name
       end
     end
+    NestTypeValue = Struct.new(:attribute_set, :type_values) do
+      using Generator::Refinements
+
+      def resolve(f)
+        self.attribute_set = attribute_set.resolve(f)
+        self
+      end
+
+      def rbs_type
+        type = 'AttributeSets::' + attribute_set.name.as_class_name
+        type_values.length.times { type = "::Hash[::Integer, #{type}]" }
+        type
+      end
+    end
     SubMessage = Struct.new(:sub_message, :selector) do
       def resolve(f)
         self.sub_message = sub_message.resolve(f)
@@ -55,7 +69,7 @@ module Ynl
       end
 
       def rbs_type
-        'untyped'
+        '::String'
       end
     end
 
@@ -96,7 +110,7 @@ module Ynl
       end
 
       def rbs_type
-        'untyped'
+        "::Array[#{sub_type.rbs_type}]"
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ynl
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Kasumi Hanazuki
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.4
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: yaml
   requirement: !ruby/object:Gem::Requirement
@@ -37,7 +37,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Linux Netlink
+description: ynl parses YAML Netlink specifications (YNL) and generates Netlink clients
+  for the interfaces they describe.
 email:
 - kasumi@rollingapple.net
 executables: []
@@ -70,7 +71,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -79,5 +80,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Linux Netlink - core
+summary: YAML Netlink specification tools for Ruby
 test_files: []