structure 3.7.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 272646d259a42b8a13d4c0fbc29072022da5260f5a7948d2f8dbaddb9f625adf
-  data.tar.gz: a3045255ecb35adc801f827c48a5c620dc90943aee453f474bae6ab85bc8b58d
+  metadata.gz: 74f52e94d4ffd40ad55e291a4ab72c108af572be936ee2d1571fef47699af2cb
+  data.tar.gz: d2ef8dee35e2ea236237d1c34c68bc6877039145553f7e1b16729ea84e3778c4
 SHA512:
-  metadata.gz: 4d5914cb2446f277c61369d156d8286cfc50b866423b7bc86523964216d76a677901848a3135a5f1061f0383569fb3ad03624c3806de9d7841281bd751e5aa16
-  data.tar.gz: 3684e0a22399da848c493eb6b837d0c8427f0dd6f24857a7f65812914366b448108da8af2b377fc937a08715ea13de633b3f538f6b843a288c65936123dd32b7
+  metadata.gz: f0c4192ddde552c7cd4a583aca9bdad31aeb64dc039680e965944696ee7648cc9a423017ab8cea5546c708ae72b7920c21fb2c96e74442932f24a3a85faa6b81
+  data.tar.gz: 03d4ea5fda959cd3bcd60b79a323b8dbfaeb5792c22b809179b7f84f76aab36845e7dbcd2f30567cf7922eea9995997cfb730cd69e8dd726cebded2bd076f540

data/lib/structure/builder.rb

@@ -13,6 +13,7 @@ module Structure
       @mappings = {}
       @defaults = {}
       @types = {}
+      @optional = Set.new
     end
 
     # DSL method for defining attributes with optional type coercion
@@ -45,6 +46,25 @@ module Structure
       end
     end
 
+    # DSL method for defining optional attributes (key can be missing from input hash)
+    #
+    # @param name [Symbol] The attribute name
+    # @param type [Class, Symbol, Array, nil] Type for coercion (e.g., String, :boolean, [String])
+    # @param from [String, nil] Source key in the data hash (defaults to name.to_s)
+    # @param default [Object, nil] Default value if attribute is missing
+    # @yield [value] Block for custom transformation
+    # @raise [ArgumentError] If both type and block are provided
+    #
+    # @example Optional attribute
+    #   attribute? :age, Integer
+    #
+    # @example Optional with default
+    #   attribute? :status, String, default: "pending"
+    def attribute?(name, type = nil, from: nil, default: nil, &block)
+      attribute(name, type, from: from, default: default, &block)
+      @optional.add(name)
+    end
+
     # Defines a callback to run after parsing
     #
     # @yield [instance] Block that receives the parsed instance
@@ -59,9 +79,13 @@ module Structure
     end
 
     # @api private
-    def attributes
-      @mappings.keys
-    end
+    def attributes = @mappings.keys
+
+    # @api private
+    def optional = @optional.to_a
+
+    # @api private
+    def required = attributes - optional
 
     # @api private
     def coercions(context = nil)

data/lib/structure/rbs.rb

@@ -4,6 +4,10 @@ require "fileutils"
 require "pathname"
 
 module Structure
+  # Generates RBS type signatures for Structure classes
+  #
+  # Note: Custom methods defined in Structure blocks are not included and must be manually added to RBS files. This is
+  # consistent with how Ruby's RBS tooling handles Data classes.
   module RBS
     class << self
       def emit(klass)
@@ -17,11 +21,13 @@ module Structure
 
         attributes = meta[:mappings] ? meta[:mappings].keys : klass.members
         types = meta.fetch(:types, {}) # steep:ignore
+        required = meta.fetch(:required, attributes) # steep:ignore
 
         emit_rbs_content(
           class_name:,
           attributes:,
           types:,
+          required:,
           has_structure_modules: meta.any?,
         )
       end
@@ -47,7 +53,7 @@ module Structure
 
       private
 
-      def emit_rbs_content(class_name:, attributes:, types:, has_structure_modules:)
+      def emit_rbs_content(class_name:, attributes:, types:, required:, has_structure_modules:)
         # @type var lines: Array[String]
         lines = []
         lines << "class #{class_name} < Data"
@@ -61,46 +67,66 @@ module Structure
             [attr, rbs_type != "untyped" ? "#{rbs_type}?" : rbs_type]
           end.to_h
 
-          keyword_params = attributes.map { |attr| "#{attr}: #{rbs_types[attr]}" }.join(", ")
+          # Sort keyword params: required first, then optional (with ? prefix)
+          # Within each group, maintain declaration order
+          required_params = required.map { |attr| "#{attr}: #{rbs_types[attr]}" }
+          optional_params = (attributes - required).map { |attr| "?#{attr}: #{rbs_types[attr]}" }
+          keyword_params = (required_params + optional_params).join(", ")
           positional_params = attributes.map { |attr| rbs_types[attr] }.join(", ")
 
-          lines << "  def self.new: (#{keyword_params}) -> #{class_name}"
-          lines << "              | (#{positional_params}) -> #{class_name}"
-          lines << ""
-
           needs_parse_data = types.any? do |_attr, type|
             type == :self || type == [:self]
           end
 
+          # Generate type alias first if needed (RBS::Sorter puts types at top)
           if needs_parse_data
-            lines << "  type parse_data = {"
-            attributes.each do |attr|
+            lines << "  type parse_data = { " + attributes.map { |attr|
               type = types.fetch(attr, nil)
               parse_type = parse_data_type(type, class_name)
-              lines << "    ?#{attr}: #{parse_type},"
-            end
-            lines[-1] = lines[-1].chomp(",")
-            lines << "  }"
-            lines << ""
+              "?#{attr}: #{parse_type}"
+            }.join(", ") + " }"
+          end
+
+          lines << "  def self.new: (#{keyword_params}) -> #{class_name}"
+          lines << "              | (#{positional_params}) -> #{class_name}"
+          lines << ""
+          lines << "  def self.[]: (#{keyword_params}) -> #{class_name}"
+          lines << "             | (#{positional_params}) -> #{class_name}"
+          lines << ""
+
+          # Generate members tuple type
+          members_tuple = attributes.map { |attr| ":#{attr}" }.join(", ")
+          lines << "  def self.members: () -> [ #{members_tuple} ]"
+          lines << ""
+
+          # Generate parse method signatures
+          if needs_parse_data
             lines << "  def self.parse: (?parse_data data) -> #{class_name}"
             lines << "                | (?Hash[String, untyped] data) -> #{class_name}"
           else
-            # For structures without special types, just use Hash
-            lines << "  def self.parse: (?(Hash[String | Symbol, untyped]), **untyped) -> #{class_name}"
+            # Remove optional parentheses to match RBS::Sorter style
+            lines << "  def self.parse: (?Hash[String | Symbol, untyped], **untyped) -> #{class_name}"
           end
           lines << ""
 
-          attributes.each do |attr|
+          # Sort attr_reader lines alphabetically (RBS::Sorter does this)
+          attributes.sort.each do |attr|
             lines << "  attr_reader #{attr}: #{rbs_types[attr]}"
           end
-          lines << ""
 
-          types.each do |attr, type|
-            if type == :boolean && !attr.to_s.end_with?("?")
+          # Add boolean predicates
+          boolean_predicates = types.sort.select { |attr, type| type == :boolean && !attr.to_s.end_with?("?") }
+          unless boolean_predicates.empty?
+            lines << ""
+            boolean_predicates.each do |attr, _type|
               lines << "  def #{attr}?: () -> bool"
             end
           end
 
+          # Instance members method comes after attr_readers and predicates
+          lines << "  def members: () -> [ #{members_tuple} ]"
+          lines << ""
+
           hash_type = attributes.map { |attr| "#{attr}: #{rbs_types[attr]}" }.join(", ")
           lines << "  def to_h: () -> { #{hash_type} }"
         end

data/lib/structure/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Structure
-  VERSION = "3.7.0"
+  VERSION = "4.1.0"
 end

data/lib/structure.rb

@@ -26,6 +26,37 @@ module Structure
       # @type var klass: untyped
       klass = Data.define(*builder.attributes)
 
+      # Enable custom method definitions by evaluating block on the class
+      if block
+        # Provide temporary dummy DSL methods to prevent NoMethodError during class_eval
+        klass.define_singleton_method(:attribute) { |*args, **kwargs, &blk| }
+        klass.define_singleton_method(:attribute?) { |*args, **kwargs, &blk| }
+        klass.define_singleton_method(:after_parse) { |&blk| }
+
+        # Evaluate block in class context for method definitions
+        klass.class_eval(&block)
+
+        # Remove temporary DSL methods
+        klass.singleton_class.send(:remove_method, :attribute)
+        klass.singleton_class.send(:remove_method, :attribute?)
+        klass.singleton_class.send(:remove_method, :after_parse)
+      end
+
+      # Override initialize to make optional attributes truly optional
+      optional_attrs = builder.optional
+      unless optional_attrs.empty?
+        klass.class_eval do
+          alias_method(:__data_initialize__, :initialize)
+
+          define_method(:initialize) do |**kwargs| # steep:ignore
+            optional_attrs.each do |attr|
+              kwargs[attr] = nil unless kwargs.key?(attr)
+            end
+            __data_initialize__(**kwargs) # steep:ignore
+          end
+        end
+      end
+
       builder.predicate_methods.each do |pred, attr|
         klass.define_method(pred) { !!public_send(attr) }
       end
@@ -37,6 +68,7 @@ module Structure
         mappings: builder.mappings,
         coercions: builder.coercions(klass),
         after_parse: builder.after_parse_callback,
+        required: builder.required,
       }.freeze
       klass.instance_variable_set(:@__structure_meta__, meta)
       klass.singleton_class.attr_reader(:__structure_meta__)
@@ -72,6 +104,15 @@ module Structure
         mappings    = __structure_meta__[:mappings]
         defaults    = __structure_meta__[:defaults]
         after_parse = __structure_meta__[:after_parse]
+        required    = __structure_meta__[:required]
+
+        # Check for missing required attributes
+        required.each do |attr|
+          from = mappings[attr]
+          next if data.key?(from) || data.key?(from.to_sym) || defaults.key?(attr)
+
+          raise ArgumentError, "missing keyword: :#{attr}"
+        end
 
         mappings.each do |attr, from|
           value = data.fetch(from) do

data/sig/structure/builder.rbs

@@ -4,10 +4,14 @@ module Structure
     @types: Hash[Symbol, untyped]
     @defaults: Hash[Symbol, untyped]
     @after_parse_callback: Proc?
+    @optional: Set[Symbol]
 
     def attribute: (Symbol name, untyped type, ?from: String?, ?default: untyped) ?{ (untyped) -> untyped } -> void
                  | (Symbol name, ?from: String, ?default: untyped) ?{ (untyped) -> untyped } -> void
 
+    def attribute?: (Symbol name, untyped type, ?from: String?, ?default: untyped) ?{ (untyped) -> untyped } -> void
+                  | (Symbol name, ?from: String, ?default: untyped) ?{ (untyped) -> untyped } -> void
+
     def after_parse: () { (Data) -> void } -> void
 
     def attributes: () -> Array[Symbol]
@@ -16,6 +20,8 @@ module Structure
     def defaults: () -> Hash[Symbol, untyped]
     def coercions: (?untyped? context) -> Hash[Symbol, Proc]
     def predicate_methods: () -> Hash[Symbol, Symbol]
+    def optional: () -> Array[Symbol]
+    def required: () -> Array[Symbol]
     def after_parse_callback: () -> (Proc | nil)
   end
 end

data/sig/structure/rbs.rbs

@@ -3,7 +3,7 @@ module Structure
     def self.emit: (untyped klass) -> String?
     def self.write: (untyped klass, ?dir: String) -> String?
 
-    private def self.emit_rbs_content: (class_name: String, attributes: Array[Symbol], types: Hash[Symbol, untyped], has_structure_modules: bool) -> String
+    private def self.emit_rbs_content: (class_name: String, attributes: Array[Symbol], types: Hash[Symbol, untyped], required: Array[Symbol], has_structure_modules: bool) -> String
     private def self.parse_data_type: (untyped type, String class_name) -> String
     private def self.map_type_to_rbs: (untyped type, String class_name) -> String
   end

data/sig/structure.rbs

@@ -5,7 +5,8 @@ module Structure
       defaults: Hash[Symbol, untyped],
       mappings: Hash[Symbol, String],
       coercions: Hash[Symbol, untyped],
-      after_parse: untyped
+      after_parse: untyped,
+      required: Array[Symbol]
     }
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: structure
 version: !ruby/object:Gem::Version
-  version: 3.7.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Hakan Ensari