marameters 3.12.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc3c9fb9d29b4864125a1cdd08516fe3092bc36de4f0122298bbbd9b8f7e7490
-  data.tar.gz: 4efabec65f0782ddb448f72c35c2f4b900fa8d8828c28abc3891a9e7b43ee636
+  metadata.gz: b120830ab23db1facffaa30df5ddbc96557d37d9910a24c9b531dd7ad755c1e0
+  data.tar.gz: ed8fa0e3aaed0a2ce8c7ad0a5954a8574eaa4242206c5aeff81fcfb5a2b5321b
 SHA512:
-  metadata.gz: 6fa293cff9a15f7cd3fc10be82ddad97aff22e1e1fb33748dca1db035466ed764082397c50174d6851b5538f571310539baec240a288a8ca9f9bc6735ab8cb21
-  data.tar.gz: 3ca85f9fdec13a3b7c04b13a73103d8ea0944890df467fbcd3d5dcfbb35a7c85197cd0aafea41facfebdcd5aca40f7239f92119b52d35ea1086d5c988281ec4a
+  metadata.gz: 959d5a7edfafad4f1da16a02ea1a54fbfd23e3cb165230eb6239bd811b0d895e18f65a1d9b08fed8971e1cea6b306b87d095e3451e7c4ca4755a520e81722b93
+  data.tar.gz: 5932395cedf488a17862bfe5f820972d4d92cce26f19ff384134d44393ac3ea35219160d9dfca6150e9096ae7e9e5b0de9ab2a6d1881441333bd6c959e66aeda

data/README.adoc

@@ -4,6 +4,7 @@
 
 :amazing_print_link: link:https://github.com/amazing-print/amazing_print[Amazing Print]
 :article_link: link:https://alchemists.io/articles/ruby_method_parameters_and_arguments[method parameters and arguments]
+:infusible_link: link:/projects/infusible[Infusible]
 
 = Marameters
 
@@ -62,40 +63,66 @@ require "marameters"
 
 At a high level, you can use `Marameters` as a single Object API for accessing all capabilities provided by this gem. Here's an overview:
 
+*Setup*
+
 [source,ruby]
 ----
-# Setup
 def demo(one, two = 2, three: 3) = puts "One: #{one}, Two: #{two}, Three: #{three}"
 
 parameters = method(:demo).parameters
 arguments = %w[one two]
+----
 
-# Marameters::Categorizer wrapper
+*Categorize*
 
+[source,ruby]
+----
 Marameters.categorize parameters, arguments
-# #<struct Marameters::Splat positionals=["one", "two"], keywords={}, block=nil>
+# #<struct Marameters::Models::Forward positionals=["one", "two"], keywords={}, block=nil>
+----
 
-# Marameters::Probe wrapper
+*Probe*
 
+[source,ruby]
+----
 Marameters.of self, :demo            # []
 
 probe = Marameters.for parameters
-probe.to_a                           # [[:req, :one], [:opt, :two], [:key, :three]]
 probe.positionals                    # [:one, :two]
 probe.keywords                       # [:three]
-probe.block                          # nil
+probe.to_a                           # [[:req, :one], [:opt, :two], [:key, :three]]
+----
 
-# Marameters::Signature wrapper
+*Signature*
 
-Marameters.signature({req: :one, opt: [:two, 2], key: [:three, 3]}).to_s
-# one, two = 2, three: 3
+[source,ruby]
 ----
+Marameters.signature([%i[req one], [:opt, :two, 2], [:key, :three, 3]]).to_s
+# "one, two = 2, three: 3"
+----
+
+=== Constants
+
+The `KINDS` constant allows you to know the kinds of parameters allowed:
 
-Read on to learn more about the details on how each of these methods work and the objects they wrap.
+[source,ruby]
+----
+Marameters::KINDS
+# [
+#   :req,
+#   :opt,
+#   :rest,
+#   :nokey,
+#   :keyreq,
+#   :key,
+#   :keyrest,
+#   :block
+# ]
+----
 
 === Probe
 
-The probe allows you to analyze a method's parameters. To understand how, consider the following:
+The probe (`Marameters::Probe`) allows you to analyze a method's parameters. To understand how, consider the following:
 
 [source,ruby]
 ----
@@ -120,58 +147,93 @@ You can then probe the `#all` method's parameters as follows:
 
 [source,ruby]
 ----
-probe = Marameters::Probe.new Demo.instance_method(:all).parameters
-
-probe.block                # :seven
-probe.block?               # true
-probe.empty?               # false
-probe.keywords             # [:four, :five]
-probe.keywords?            # true
-probe.kind?(:keyrest)      # true
-probe.kinds                # [:req, :opt, :rest, :keyreq, :key, :keyrest, :block]
-probe.name?(:three)        # true
-probe.names                # [:one, :two, :three, :four, :five, :six, :seven]
-probe.only_bare_splats?    # false
-probe.only_double_splats?  # false
-probe.only_single_splats?  # false
-probe.positionals          # [:one, :two]
-probe.positionals?         # true
-probe.splats               # [:three, :six]
-probe.splats?              # true
-probe.to_a                 # [[:req, :one], [:opt, :two], [:rest, :three], [:keyreq, :four], [:key, :five], [:keyrest, :six], [:block, :seven]]
-probe.to_h                 # {req: :one, opt: :two, rest: :three, keyreq: :four, key: :five, keyrest: :six, block: :seven}
-----
-
-In contrast the above, we can also probe the `#none` method which has no parameters for a completely
+probe = Marameters.for Demo.instance_method(:all).parameters
+
+probe.deconstruct                      # (same as to_a, see below)
+probe.empty?                           # false
+probe.include? %i[req one]             # true
+probe.keywords                         # [:four, :five]
+probe.keywords?                        # true
+probe.keywords_for :four, four: :demo  # {four: :demo}
+probe.kind?(:keyrest)                  # true
+
+probe.kinds
+# [:req, :opt, :rest, :keyreq, :key, :keyrest, :block]
+
+probe.name?(:three)                    # true
+
+probe.names
+# [:one, :two, :three, :four, :five, :six, :seven]
+
+probe.only_bare_splats?                # false
+probe.only_double_splats?              # false
+probe.only_single_splats?              # false
+probe.positionals                      # [:one, :two]
+probe.positionals?                     # true
+probe.positionals_and_maybe_keywords?  # true
+
+probe.to_a
+# [
+#   [:req, :one],
+#   [:opt, :two],
+#   [:rest, :three],
+#   [:keyreq, :four],
+#   [:key, :five],
+#   [:keyrest, :six],
+#   [:block, :seven]
+# ]
+----
+
+In contrast to the above, we can probe the `#none` method which has no parameters for a completely
 different result:
 
 [source,ruby]
 ----
-probe = Marameters::Probe.new Demo.instance_method(:none).parameters
+probe = Marameters.for Demo.instance_method(:none).parameters
 
-probe.block                # nil
-probe.block?               # false
-probe.empty?               # true
-probe.keywords             # []
-probe.keywords?            # false
-probe.kind?(:req)          # true
-probe.kinds                # []
-probe.name?(:three)        # false
-probe.names                # []
-probe.only_bare_splats?    # false
-probe.only_double_splats?  # false
-probe.only_single_splats?  # false
-probe.positionals          # []
-probe.positionals?         # false
-probe.splats               # []
-probe.splats?              # false
-probe.to_a                 # []
-probe.to_h                 # {}
+probe.deconstruct                      # (same as to_a, see below)
+probe.empty?                           # true
+probe.include? %i[req one]             # false
+probe.keywords                         # []
+probe.keywords?                        # false
+probe.keywords_for :four, four: :demo  # {}
+probe.kind?(:req)                      # true
+probe.kinds                            # []
+probe.name?(:three)                    # false
+probe.names                            # []
+probe.only_bare_splats?                # false
+probe.only_double_splats?              # false
+probe.only_single_splats?              # false
+probe.positionals                      # []
+probe.positionals?                     # false
+probe.positionals_and_maybe_keywords?  # false
+probe.to_a                             # []
 ----
 
-=== Categorizer
+The `#keywords_for` method might need additional explaining because it's meant for selecting keywords which adhere to _either_ of the following criteria:
 
-The categorizer allows you to dynamically build positional, keyword, and block arguments for message passing. This is most valuable when you know the object and method while needing to align the arguments in the right order. Here's a demonstration where {amazing_print_link} (i.e. `ap`) is used to format the output:
+* The given keys don't match any key in the given attributes.
+* The given keys match the parameter keywords.
+
+[source,ruby]
+----
+module Demo
+  def self.keywords(four:, five: 5, **six) = puts "Four: #{four}, Five: #{five}, Six: #{six}"
+end
+
+probe = Marameters.for Demo.method(:keywords).parameters
+
+probe.keywords_for :a, a: 1, four: 4         # {four: 4}
+probe.keywords_for :four, a: 1               # {a: 1}
+probe.keywords_for :a, four: 4, five: :five  # {four: 4, five: :five}
+probe.keywords_for :a, six: {name: :test}    # {six: {name: :test}}
+----
+
+This useful in gems, like {infusible_link}, when determining which keyword arguments to pass up to the superclass.
+
+=== Categorize
+
+Categorization (`Marameters::Categorizer`) allows you to dynamically build positional, keyword, and block arguments for message passing. This is most valuable when you know the object and method while needing to align the arguments in the right order. Here's a demonstration where {amazing_print_link} (i.e. `ap`) is used to format the output:
 
 [source,ruby]
 ----
@@ -191,18 +253,18 @@ end
 
 module Inspector
   def self.call arguments
-    Marameters::Categorizer.new(Demo.method(:test).parameters)
-                           .call(arguments).then do |splat|
-                             ap splat
-                             puts
-                             Demo.test(*splat.positionals, **splat.keywords, &splat.block)
-                           end
+    Marameters.categorize(Demo.method(:test).parameters, arguments)
+              .then do |record|
+                ap record
+                puts
+                Demo.test(*record.positionals, **record.keywords, &record.block)
+              end
   end
 end
 
 Inspector.call [1, nil, nil, {four: 4}]
 
-# #<Struct:Marameters::Splat:0x00021930
+# #<Struct:Marameters::Models::Forward:0x00021930
 #   block = nil,
 #   keywords = {
 #     :four => 4
@@ -226,7 +288,7 @@ Inspector.call [1, nil, nil, {four: 4}]
 When we step through the above implementation and output, we see the following unfold:
 
 . The `Demo` module allows us to define a maximum set of parameters and then print the arguments received for inspection purposes.
-. The `Inspector` module provides a wrapper around the `Categorizer` so we can conveniently pass in different arguments for experimentation purposes.
+. The `Inspector` module provides a wrapper around the categorization so we can conveniently pass in different arguments for experimentation purposes.
 . We pass in our arguments to `Inspector.call` where `nil` is used for optional arguments and hashes for keyword arguments.
 . Once inside `Inspector.call`, the `Categorizer` is initialized with the `Demo.test` method parameters.
 . Then the `splat` (i.e. Struct) is printed out so you can see the categorized positional, keyword, and block arguments.
@@ -240,7 +302,7 @@ Inspector.call [1, 2, [98, 99], {four: 4}, {five: 5}, {twenty: 20, thirty: 30},
 
 # Output
 
-# #<Struct:Marameters::Splat:0x00029cc0
+# #<Struct:Marameters::Models::Forward:0x00029cc0
 #   block = #<Proc:0x000000010a88cec0 (irb):1>,
 #   keywords = {
 #       :four => 4,
@@ -296,109 +358,184 @@ ap arguments
 | `%i[block seven]` | `#<Proc:0x0000000108edc778>`
 |===
 
-This also means that:
+This also means:
 
-* All positions must be filled if you want to supply arguments beyond the first couple of positions because everything is positional due to the nature of how link:https://rubyapi.org/o/method#method-i-parameters[Method#parameters] works. Use `nil` to fill an optional argument when you don't need it.
+* All positions must be filled if you want to supply arguments beyond the first couple of positions because everything is positional due to the nature of how link:https://docs.ruby-lang.org/en/master/Method.html#method-i-parameters[Method#parameters] works. Use `nil` to fill an optional argument when you don't need it.
 * The `:rest` (single splat) argument must be an array or `nil` if not present because even though it is _optional_, it is still _positional_.
 * The `:keyrest` (double splat) argument -- much like the `:rest` argument -- must be a hash or `nil` if not present.
 
-Lastly, in all of the above examples, only an array of arguments has been used but you can pass in a single argument too (i.e. non-array). This is handy for method signatures which have only a single parameter or only use splats. Having to remember to wrap your argument in an array each time can get tedious so when _only_ a single argument is supplied, the categorizer will automatically cast the argument as an array. A good example of this use case is when using structs. Example:
+Lastly, in all of the above examples, only an array of arguments has been used but you can pass in a single argument too (i.e. non-array). This is handy for method signatures which have only a single parameter or only use splats.
+
+For C-based primitives, like `Struct`, `Data`, etc., you'll want to provide a conversion method. Example:
 
 [source,ruby]
 ----
-url = Struct.new :label, :url, keyword_init: true
+url = Struct.new(:label, :url) do
+  def self.for(**) = new(**)
+end
 
-Marameters.categorize(url.method(:new).parameters, {label: "Eaxmple", url: "https://example.com"})
-          .then { |splat| url.new(*splat.positionals, **splat.keywords) }
+Marameters.categorize(url.method(:for).parameters, label: "Example", url: "https://example.com")
+          .then { |record| url.for(**record.keywords) }
 
-# Yields: #<struct label="Eaxmple", url="https://example.com">
+# Yields: #<struct label="Example", url="https://example.com">
 ----
 
-For further details, please refer back to my {article_link} article mentioned in the _Requirements_ section.
+For further details, please refer back to my {article_link} article mentioned in the xref:_requirements[Requirements] section.
 
 === Signature
 
-The signature class is the inverse of the probe class in that you want to feed it parameters for turning into a method signature. This is useful when dynamically building method signatures or using the same signature when metaprogramming multiple methods.
+The signature (`Marameters::Signature`) is the opposite of the probe class which allows you to turn a raw array of parameters into a method signature. This is most useful when metaprogramming and needing to dynamically build method signatures. Example:
+
+[source,ruby]
+----
+signature = Marameters.signature [[:opt, :text, "This is a test."]]
+
+Example = Module.new do
+  module_eval <<~METHOD, __FILE__, __LINE__ + 1
+    def self.say(#{signature}) = text
+  METHOD
+end
+
+puts Example.say           # "This is a test."
+puts Example.say("Hello")  # "Hello"
+----
+
+==== Keys
 
-The following demonstrates how you might construct a method signature with all possible parameters:
+The following demonstrates how you can construct a method signature with all possible parameters using the same keys as used by `Method#parameters`:
 
 [source,ruby]
 ----
-signature = Marameters::Signature.new(
-  {
-    req: :one,
-    opt: [:two, 2],
-    rest: :three,
-    keyreq: :four,
-    key: [:five, 5],
-    keyrest: :six,
-    block: :seven
-  }
-)
+signature = Marameters.signature [
+  %i[req one],
+  %i[opt two],
+  %i[rest three],
+  %i[keyreq four],
+  %i[key five],
+  %i[keyrest six],
+  %i[block seven]
+]
 
 puts signature
-# one, two = 2, *three, four:, five: 5, **six, &seven
+# "one, two = nil, *three, four:, five: nil, **six, &seven"
+----
+
+==== Values
+
+With the above examples, each sub-array uses a simple key/value pair to map the kind of parameter with the corresponding name. You can also provide a _third_ value when needing to provide a default value for _optional_ parameters. Example:
+
+[source,ruby]
+----
+puts Marameters.signature([[:opt, :one, 1], [:key, :two, 2]])
+# one = 1, two: 2
 ----
 
-You'll notice that the parameters are a hash _and_ some values can be tuples. The reason is that
-it's easier to write a hash than a double nested array as normally produced by the probe or directly
-from `Method#parameters`. The optional positional and keyword parameters use tuples because you
-might want to supply a default value and this provides a way for you to do that with minimal syntax.
 This can be demonstrated further by using optional keywords (same applies for optional positionals):
 
 [source,ruby]
 ----
-# With no default
-puts Marameters::Signature.new({key: :demo})
-# demo: nil
+# With implicit nil.
+puts Marameters.signature([%i[key demo]])
+# "demo: nil"
+
+# With explicit nil.
+puts Marameters.signature([[:key, :demo, nil]])
+# "demo: nil"
 
-# With explicit nil as default
-puts Marameters::Signature.new({key: [:demo, nil]})
-# demo: nil
+# With any primitive.
+puts Marameters.signature([[:key, :demo, :test]])
+# "demo: :test"
 
-# With string as default
-puts Marameters::Signature.new({key: [:demo, "test"]})
-# demo: "test"
+# With proc (no parameters).
+puts Marameters.signature([[:key, :demo, proc { Object.new }]])
+# "demo: Object.new"
+# ⚠️ The above will answer "demo: nil" if used in IRB since the source can't be found.
 
-# With symbol as default
-puts Marameters::Signature.new({key: [:demo, :test]})
-# demo: :test
+# With proc (with parameters).
+puts Marameters.signature([[:key, :demo, proc { |no| no }]])
+# Avoid using parameters for proc defaults. (ArgumentError)
 
-# With object(dependency) as default
-puts Marameters::Signature.new({key: [:demo, "*Object.new"]})
-# demo: Object.new
+# With lambda.
+puts Marameters.signature([[:key, :demo, -> { Object.new }]])
+# Use procs instead of lambdas for defaults. (TypeError)
 ----
 
-In the case of object dependencies, you need to wrap these in a string _and_ prefix them with a star
-(`*`) so the signature builder won't confuse them as normal strings. There are two reasons why this
-is important:
+You can use any primitive, custom object, etc. as a default despite the limited examples shown above.
 
-* The star (`*`) signifies you want an object to be passed through without further processing while
-  also not being confused as a normal string.
-* Objects wrapped as strings allows your dependency to be lazy loaded. Otherwise, if `Object.new`
-  was pass in directly, you'd be passing the evaluated instance (i.e.
-  `#<Object:0x0000000107df4028>`) which is not what you want until much later when your method is
-  defined.
+Procs _must_ be used when supplying complex objects as default values. _Avoid_ using parameters when using procs because only the source (body) of your proc will be used as a _literal_ string when building the method signature in order to ensure lazy evaluation.
 
-When you put all of this together, you can dynamically build a method as follows:
+Lastly, you can use anonymous splats/blocks by only supplying their kind. Example:
 
 [source,ruby]
 ----
-signature = Marameters::Signature.new({opt: [:text, "This is a test."]})
+puts Marameters.signature([[:rest], [:keyrest], [:block]])
+# "*, **, &"
+----
 
-Example = Module.new do
-  module_eval <<~DEFINITION, __FILE__, __LINE__ + 1
-    def self.say(#{signature}) = text
-  DEFINITION
+You can supply `nil` as a second element (i.e. the name) for each kind but that is the equivalent of the above.
+
+==== Argument Forwarding
+
+Use `:all` for building a method signature with argument forwarding. Example:
+
+[source, ruby]
+----
+puts Marameters.signature(:all)
+# "..."
+----
+
+Use of `:all` is special in that you must _only_ supply `:all` with no other keys/values or you'll get an `ArgumentError`.
+
+💡 This is only provided for convenience and completeness. In truth, you're better off writing `my_method(+...+)`, for example, than using this class.
+
+==== Bare
+
+Use an empty array when you need a bare method signature. Example:
+
+[source,ruby]
+----
+puts Marameters.signature []
+# ""
+----
+
+💡 This is only provided for convenience and completeness. In truth, if you need a bare method, then you don't need to use this class.
+
+==== Inheritance
+
+Object/method inheritance is more complicated than building a signature for a single method because you need to blend the super and sub parameters as a unified set of parameters. Additionally, you have to account for the arguments that need to be forwarded to the super method via the `super` keyword. To aid in this endeavor, the following objects are available to help you build these more complex method parameters and arguments:
+
+* `Marameters::Signatures::Inheritor`: Blends super and sub parameters to produce a unified set of parameters you can turn into a method signature.
+* `Marameters::Signatures::Super`: Blends super and sub parameters to produce arguments for forwarding via the `super` keyword. _This does not support disabled block forwarding (i.e. `&nil`) since there is no way to determine this from the super and sub parameters alone._
+
+Here's an example which incorporates both of the above:
+
+[source,ruby]
+----
+module Demo
+  def self.parent(one, two = 2, *three, &block) = nil
 end
 
-puts Example.say
-# This is a test.
+super_parameters = Marameters.for Demo.method(:parent).parameters
+
+sub_parameters = Marameters.for [
+  [:opt, :two, 22],
+  %i[keyreq four],
+  [:key, :five, 5],
+  %i[keyrest six]
+]
+
+inheritor = Marameters::Signatures::Inheritor.new
+forwarder = Marameters::Signatures::Super.new
 
-puts Example.say "Hello"
-# Hello
+puts Marameters.signature inheritor.call(super_parameters, sub_parameters)
+# "one, two = 22, *three, four:, five: 5, **six, &block"
+
+puts forwarder.call(super_parameters, sub_parameters)
+# "one, two, *three, &block"
 ----
 
+As you can see, the above combines the parameters of your super method with the parameters of your sub method in order to produce a method signature -- with no duplicates -- while ensuring you can forward all necessary parameters that the `super` keyword requires. Defaults, if given, will override previously defined defaults as is identical with standard object inheritance.
+
 == Development
 
 To contribute, run:

data/lib/marameters/categorizer.rb

@@ -1,40 +1,33 @@
 # frozen_string_literal: true
 
-require "refinements/struct"
-
 module Marameters
   # Builds the primary argument categories based on method parameters and arguments.
   class Categorizer
-    using Refinements::Struct
-
-    def initialize parameters, model: Splat
-      @parameters = parameters
+    def initialize model: Models::Forward
       @model = model
     end
 
-    def call arguments
+    def call parameters, arguments
       @record = model.new
-      map arguments.is_a?(Array) ? arguments : [arguments]
-      record
+
+      return record if arguments.empty?
+
+      map parameters, arguments
     end
 
     private
 
-    attr_reader :parameters, :model, :record
-
-    def map arguments
-      return record if arguments.empty?
+    attr_reader :model, :record
 
+    def map parameters, arguments
       size = arguments.size
-
-      parameters.each.with_index do |pair, index|
-        filter pair, arguments[index] if index < size
-      end
+      parameters.each.with_index { |pair, index| filter pair, arguments[index] if index < size }
+      record
     end
 
     def filter pair, value
       case pair
-        in [:rest] | [:rest, :*] then splat_positional value
+        in [:rest] | [:rest, :*] then to_array value
         in [:keyrest] | [:keyrest, :**] then record.keywords = Hash value
         in [:req, *] | [:opt, *] then record.positionals.append value
         in [:rest, *] then record.positionals.append(*value)
@@ -48,7 +41,7 @@ module Marameters
       raise TypeError, "#{value.inspect} is an invalid #{pair.first.inspect} value."
     end
 
-    def splat_positional value
+    def to_array value
       return unless value
 
       record.positionals = value.is_a?(Array) ? value : [value]

data/lib/marameters/models/forward.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Marameters
+  module Models
+    # Models arguments, by category, for forwarding.
+    Forward = Struct.new :positionals, :keywords, :block do
+      def initialize(positionals: [], keywords: {}, block: nil) = super
+    end
+  end
+end

data/lib/marameters/probe.rb

@@ -7,11 +7,7 @@ module Marameters
   class Probe
     extend Forwardable
 
-    CATEGORIES = {
-      positionals: %i[req opt],
-      keywords: %i[keyreq key],
-      splats: %i[rest keyrest]
-    }.freeze
+    CATEGORIES = {positionals: %i[req opt], keywords: %i[keyreq key]}.freeze
 
     def self.of klass, name, collection: []
       method = klass.instance_method name
@@ -22,32 +18,28 @@ module Marameters
       collection
     end
 
-    delegate %i[deconstruct empty? include? to_a] => :parameters
+    delegate %i[any? deconstruct empty? hash include? inspect to_a] => :parameters
 
-    attr_reader :keywords, :positionals, :splats
+    attr_reader :keywords, :positionals
 
     def initialize parameters, categories: CATEGORIES
       @parameters = parameters
       categories.each { |category, kinds| define_variable category, kinds }
+      freeze
     end
 
-    def block = parameters.find { |kind, name| break name if kind == :block }
+    def ==(other) = hash == other.hash
 
-    def block? = (parameters in [*, [:block, *]])
+    alias eql? ==
 
-    def keyword_slice collection, keys:
-      warn "`#{self.class}##{__method__}` is deprecated, use `#keywords_for` instead.",
-           category: :deprecated
+    def <=>(other) = to_a <=> other.to_a
 
-      keywords_for(*keys, **collection)
-    end
+    def keywords? = keywords.any?
 
     def keywords_for(*keys, **attributes)
       attributes.select { |key| !keys.include?(key) || keywords.include?(key) }
     end
 
-    def keywords? = keywords.any?
-
     def kind?(value) = parameters.any? { |kind, _name| kind == value }
 
     def kinds = parameters.map { |kind, _name| kind }
@@ -58,10 +50,10 @@ module Marameters
 
     def only_bare_splats?
       parameters in [[:rest]] \
-                    | [[:keyrest]] \
-                    | [[:rest], [:keyrest]] \
                     | [[:rest, :*]] \
+                    | [[:keyrest]] \
                     | [[:keyrest, :**]] \
+                    | [[:rest], [:keyrest]] \
                     | [[:rest, :*], [:keyrest, :**]]
     end
 
@@ -71,9 +63,9 @@ module Marameters
 
     def positionals? = positionals.any?
 
-    def splats? = splats.any?
-
-    def to_h = parameters.each.with_object({}) { |(key, name), attributes| attributes[key] = name }
+    def positionals_and_maybe_keywords?
+      (positionals? && !keywords?) || (positionals? && keywords?)
+    end
 
     private
 

data/lib/marameters/signature.rb

@@ -3,12 +3,13 @@
 module Marameters
   # Builds a method's parameter signature.
   class Signature
-    def initialize parameters, builder: Builder.new
+    def initialize parameters, builder: Signatures::Builder.new
       @parameters = parameters
       @builder = builder
+      freeze
     end
 
-    def to_s = build.join ", "
+    def to_s = parameters == :all ? "..." : build.join(", ")
 
     alias to_str to_s
 
@@ -17,7 +18,7 @@ module Marameters
     attr_reader :parameters, :builder
 
     def build
-      parameters.reduce [] do |signature, (kind, (name, default))|
+      parameters.reduce [] do |signature, (kind, name, default)|
         signature << builder.call(kind, name, default:)
       end
     end

data/lib/marameters/signatures/builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Marameters
+  module Signatures
+    # Builds a single parameter for a method's signature.
+    class Builder
+      def initialize defaulter: Defaulter
+        @defaulter = defaulter
+        freeze
+      end
+
+      def call kind, name = nil, default: nil
+        case kind
+          when :req then name
+          when :opt then "#{name} = #{defaulter.call default}"
+          when :rest then "*#{name}"
+          when :nokey then "**nil"
+          when :keyreq then "#{name}:"
+          when :key then "#{name}: #{defaulter.call default}"
+          when :keyrest then "**#{name}"
+          when :block then "&#{name}"
+          else fail ArgumentError, "Wrong kind (#{kind}), name (#{name}), or default (#{default})."
+        end
+      end
+
+      private
+
+      attr_reader :defaulter
+    end
+  end
+end

data/lib/marameters/signatures/defaulter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Marameters
+  module Signatures
+    # Computes a method parameter's default value.
+    Defaulter = lambda do |value, extractor: Sources::Extractor.new|
+      case value
+        when Proc
+          fail TypeError, "Use procs instead of lambdas for defaults." if value.lambda?
+          fail ArgumentError, "Avoid using parameters for proc defaults." if value.arity.nonzero?
+
+          extractor.call value
+        when String then value.dump
+        when Symbol then value.inspect
+        when nil then "nil"
+        else value
+      end
+    end
+  end
+end

data/lib/marameters/signatures/forwarder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Marameters
+  module Signatures
+    # Builds single argument for super method's signature when argument forwarding.
+    Forwarder = lambda do |kind, name = nil|
+      case kind
+        when :req, :opt then name
+        when :rest then "*#{name}"
+        when :nokey then ""
+        when :keyreq, :key then "#{name}:"
+        when :keyrest then "**#{name}"
+        when :block then "&#{name}"
+        else fail ArgumentError, "Unable to forward unknown kind: #{kind.inspect}."
+      end
+    end
+  end
+end

data/lib/marameters/signatures/inheritor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Marameters
+  module Signatures
+    # Blends ancestor and descendant method parameters together while allowing default overrides.
+    class Inheritor
+      def initialize key_length: 1, kinds: KINDS
+        @key_length = key_length
+        @kinds = kinds
+        freeze
+      end
+
+      def call ancestor, descendant
+        merge(ancestor, descendant).values.sort_by! { |(kind, *)| kinds.index kind }
+      end
+
+      private
+
+      attr_reader :key_length, :kinds
+
+      def merge ancestor, descendant
+        ancestor.to_a.union(descendant.to_a).each.with_object({}) do |parameter, all|
+          key = parameter[..key_length]
+          kind = key.first
+
+          case kind
+            when :req, :opt then all[key] = parameter if descendant.positionals_and_maybe_keywords?
+            when :nokey then all
+            when :keyreq, :key
+              different = ancestor.keywords? && ancestor.keywords.sort != descendant.keywords.sort
+              all[:keyrest] = [:keyrest] if different
+              all[key] = parameter if descendant.include? parameter
+            else all[kind] = parameter
+          end
+        end
+      end
+    end
+  end
+end

data/lib/marameters/signatures/super.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Marameters
+  module Signatures
+    # Blends ancestor and descendant method arguments for forwarding to the super keyword.
+    class Super
+      def initialize key_length: 1, kinds: KINDS, forwarder: Signatures::Forwarder
+        @key_length = key_length
+        @kinds = kinds
+        @forwarder = forwarder
+        freeze
+      end
+
+      def call ancestor, descendant
+        return "" if ancestor.empty?
+
+        merge(ancestor, descendant).values
+                                   .sort_by! { |(kind, *)| kinds.index kind }
+                                   .then { |parameters| build parameters }
+      end
+
+      private
+
+      attr_reader :key_length, :kinds, :forwarder
+
+      def merge ancestor, descendant
+        ancestor.to_a.union(descendant.to_a).each.with_object({}) do |parameter, all|
+          key = parameter[..key_length]
+          kind, name = key
+
+          case kind
+            when :req, :opt
+              if ancestor.positionals? && !descendant.positionals? then all[:rest] = [:rest]
+              elsif ancestor.name? name then all[key] = parameter
+              else all
+              end
+            when :nokey then all.delete_if { |key, _| %i[keyreq key keyrest].include? key }
+            when :keyreq, :key
+              included = ancestor.name?(name) && descendant.name?(name)
+              different = ancestor.keywords? && ancestor.keywords.sort != descendant.keywords.sort
+
+              all[key] = parameter if included
+              all[:keyrest] = [:keyrest] if different
+            else all[kind] = parameter if ancestor.kind? kind
+          end
+        end
+      end
+
+      def build parameters
+        parameters.filter_map { |kind, name| forwarder.call kind, name }
+                  .join ", "
+      end
+    end
+  end
+end

data/lib/marameters/sources/extractor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Marameters
+  module Sources
+    # Extracts the literal source of a Proc's body.
+    class Extractor
+      PATTERN = /
+        proc          # Proc statement.
+        \s*           # Optional space.
+        \{            # Block open.
+        (?<body>.*?)  # Source code body.
+        \}            # Block close.
+      /x
+
+      def initialize pattern: PATTERN, reader: Reader.new
+        @pattern = pattern
+        @reader = reader
+        @fallback = "nil"
+        freeze
+      end
+
+      def call function
+        reader.call(function).then do |line|
+          line.match?(pattern) ? line.match(pattern)[:body].strip : fallback
+        end
+      end
+
+      private
+
+      attr_reader :pattern, :reader, :fallback
+    end
+  end
+end

data/lib/marameters/sources/reader.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Marameters
+  module Sources
+    # Reads object source code from memory or file (assumes implementation is a one-liner).
+    class Reader
+      def initialize offset: 1, parser: RubyVM::InstructionSequence, io: File
+        @offset = offset
+        @parser = parser
+        @io = io
+        freeze
+      end
+
+      def call object
+        instructions = parser.of object
+
+        fail StandardError, "Unable to load source for: #{object.inspect}." unless instructions
+
+        process object, instructions
+      end
+
+      private
+
+      attr_reader :offset, :parser, :io
+
+      def process object, instructions
+        lines = instructions.script_lines
+
+        return lines.first if lines
+        return extract(*object.source_location) if io.readable? instructions.absolute_path
+
+        fail StandardError, "Unable to load source for: #{object.inspect}."
+      end
+
+      def extract(path, line_number) = io.open(path) { |body| pluck body, line_number }
+
+      def pluck body, line_number
+        body.each_line
+            .with_index
+            .find { |_line, index| index + offset == line_number }
+            .first
+      end
+    end
+  end
+end

data/lib/marameters.rb

@@ -16,7 +16,7 @@ module Marameters
     @loader ||= registry.loaders.find { |loader| loader.tag == File.basename(__FILE__, ".rb") }
   end
 
-  def self.categorize(parameters, arguments) = Categorizer.new(parameters).call(arguments)
+  def self.categorize(parameters, arguments) = Categorizer.new.call parameters, arguments
 
   def self.of(...) = Probe.of(...)
 

data/marameters.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |spec|
   spec.name = "marameters"
-  spec.version = "3.12.0"
+  spec.version = "4.0.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/marameters"
-  spec.summary = "A dynamic method parameter inspector."
+  spec.summary = "A dynamic method parameter enhancer."
   spec.license = "Hippocratic-2.1"
 
   spec.metadata = {
@@ -22,8 +22,8 @@ Gem::Specification.new do |spec|
   spec.signing_key = Gem.default_key_path
   spec.cert_chain = [Gem.default_cert_path]
 
-  spec.required_ruby_version = ">= 3.3", "<= 3.4"
-  spec.add_dependency "refinements", "~> 12.10"
+  spec.required_ruby_version = "~> 3.4"
+  spec.add_dependency "refinements", "~> 13.0"
   spec.add_dependency "zeitwerk", "~> 2.7"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: marameters
 version: !ruby/object:Gem::Version
-  version: 3.12.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -35,7 +34,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-11-09 00:00:00.000000000 Z
+date: 2024-12-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: refinements
@@ -43,14 +42,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.10'
+        version: '13.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.10'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -65,7 +64,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.7'
-description:
 email:
 - brooke@alchemists.io
 executables: []
@@ -77,12 +75,17 @@ files:
 - LICENSE.adoc
 - README.adoc
 - lib/marameters.rb
-- lib/marameters/builder.rb
 - lib/marameters/categorizer.rb
-- lib/marameters/defaulter.rb
+- lib/marameters/models/forward.rb
 - lib/marameters/probe.rb
 - lib/marameters/signature.rb
-- lib/marameters/splat.rb
+- lib/marameters/signatures/builder.rb
+- lib/marameters/signatures/defaulter.rb
+- lib/marameters/signatures/forwarder.rb
+- lib/marameters/signatures/inheritor.rb
+- lib/marameters/signatures/super.rb
+- lib/marameters/sources/extractor.rb
+- lib/marameters/sources/reader.rb
 - marameters.gemspec
 homepage: https://alchemists.io/projects/marameters
 licenses:
@@ -95,16 +98,12 @@ metadata:
   label: Marameters
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/bkuhlmann/marameters
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
-    - !ruby/object:Gem::Version
-      version: '3.3'
-  - - "<="
+  - - "~>"
     - !ruby/object:Gem::Version
       version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
@@ -113,8 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
-summary: A dynamic method parameter inspector.
+summary: A dynamic method parameter enhancer.
 test_files: []

data/lib/marameters/builder.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Marameters
-  # Builds a single parameter of a method's parameter signature.
-  class Builder
-    def initialize defaulter: Defaulter
-      @defaulter = defaulter
-    end
-
-    def call kind, name = nil, default: nil
-      case kind
-        when :req then name
-        when :opt then "#{name} = #{defaulter.call default}"
-        when :rest then "*#{name}"
-        when :nokey then "**nil"
-        when :keyreq then "#{name}:"
-        when :key then "#{name}: #{defaulter.call default}"
-        when :keyrest then "**#{name}"
-        when :block then "&#{name}"
-        else fail ArgumentError, "Wrong kind (#{kind}), name (#{name}), or default (#{default})."
-      end
-    end
-
-    private
-
-    attr_reader :defaulter
-  end
-end

data/lib/marameters/defaulter.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-module Marameters
-  # Computes a method parameter's default value.
-  Defaulter = lambda do |value, passthrough: "*"|
-    case value
-      when /\A#{Regexp.escape passthrough}/ then value.delete_prefix passthrough
-      when String then value.dump
-      when Symbol then value.inspect
-      when nil then "nil"
-      else value
-    end
-  end
-end

data/lib/marameters/splat.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Marameters
-  # Captures arguments, by category, for message splatting.
-  Splat = Struct.new :positionals, :keywords, :block do
-    def initialize(positionals: [], keywords: {}, block: nil) = super
-  end
-end