marameters 0.6.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: caaadc60d0c381ae6e86e9d7c9f5ceb6c11e5f0438b8d301f0e4fd43bb4b25f3
-  data.tar.gz: 5e174ba972eeafe5040207e481db675a3bd54d13ef5effbc8c08de3e100c0579
+  metadata.gz: b53c9a80f1845fabb688e43162c18519192414425ef6a5b2a4c16e2575d29f99
+  data.tar.gz: e49e58811bb7e32ec2c8bee2691b6d230be4dc0f18503b86f5cebdfa812033c6
 SHA512:
-  metadata.gz: d00d1a2e34d71d913ec250521e2f269fe12810fe032e70ce8d4c4297a3534d33b9c9a5bee5ad9efe167dee2042a8fcfa6d8b5d35defcaa5e63a19c2293aa7f35
-  data.tar.gz: 342d1b8ac5013166ca937c79bd1b530abfe298ba7b527d316625d18738d7f30af543380d242d0d2253d1e19dbf5c82e6383ac8999e84dc92f11f24e107bd850e
+  metadata.gz: c4763d0f9492fce3673c1803884ae5cc6d49e64957f35649c7b10045a9146fbabf513a64d21346fd3642df9e481ba4f12cb59fcc361bae5fae0eb0cb3b7cc7c4
+  data.tar.gz: 4c6ffd0555c7d563759d4c25eb880f44ae8d4158d0399520bcb1301d64709c67a88b7aeedea69b6485c9598430b94d2a7d58529001435e6721fe704de742a023

data/README.adoc

@@ -2,30 +2,29 @@
 :toclevels: 5
 :figure-caption!:
 
+:amazing_print_link: link:https://github.com/amazing-print/amazing_print[Amazing Print]
+:article_link: link:https://www.alchemists.io/articles/ruby_method_parameters_and_arguments[method parameters and arguments]
+
 = Marameters
 
-Marameters is a portmanteau (i.e. `[m]ethod + p[arameters] = marameters`) which is designed to
-provide additional insight and diagnostics to method parameters. For context, the difference between
-a method's parameters and arguments is:
+Marameters is a portmanteau (i.e. `[m]ethod + p[arameters] = marameters`) which is designed to provide additional insight and diagnostics for method parameters. For context, the difference between a method's parameters and arguments is:
 
-* *Parameters*: Represents the _expected_ values to be passed to a method when
-  messaged as defined when the method is implemented. Example: `def demo(one, two: nil)`.
-* *Arguments*: Represents the _actual_ values passed to the method when messaged.
-  Example: `demo 1, two: 2`.
+* *Parameters*: Represents the _expected_ values to be passed to a method when messaged as defined when the method is implemented. Example: `def demo one, two: nil`.
+* *Arguments*: Represents the _actual_ values passed to the method when messaged. Example: `demo 1, two: 2`.
 
-This gem will help you debug methods or -- more importantly -- aid your workflow when
-metaprogramming, as used in the link:https://www.alchemists.io/projects/auto_injector[Auto Injector]
-gem, when architecting more sophisticated applications.
+This gem will help you debug methods or aid your workflow when
+metaprogramming -- as used in the link:https://www.alchemists.io/projects/infusible[Infusible] gem -- when architecting more sophisticated applications.
 
 toc::[]
 
 == Features
 
-* Provides specialized objects for keyword, positional, and splatted parameters.
+* Provides specialized objects for keyword, positional, and block parameters.
 
 == Requirements
 
 . link:https://www.ruby-lang.org[Ruby].
+. A solid understanding of {article_link}.
 
 == Setup
 
@@ -45,16 +44,42 @@ gem "marameters"
 
 == Usage
 
-There are two main objects you'll want to interact with:
+At a high level, you can use `Marameters` as a single object interface for accessing all capabilities provided by this gem. Here's an overview:
+
+[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
+
+Marameters.categorize parameters, arguments
+# #<struct Marameters::Splat positionals=["one", "two"], keywords={}, block=nil>
 
-* *Marameters::Probe*: Allows you to analyze a method's parameters.
-* *Marameters::Signature*: Allows you to dynamically build a method signature from raw parameters.
+# Marameters::Probe wrapper
 
-Both of these objects are meant to serve as building blocks to more complex architectures.
+Marameters.of self, :demo            # []
+
+probe = Marameters.probe parameters
+probe.to_a                           # [[:req, :one], [:opt, :two], [:key, :three]]
+probe.positionals                    # [:one, :two]
+probe.keywords                       # [:three]
+probe.block                          # nil
+
+# Marameters::Signature wrapper
+
+Marameters.signature({req: :one, opt: [:two, 2], key: [:three, 3]}).to_s
+# one, two = 2, three: 3
+----
+
+Read on to learn more about the details on how each of these methods work and the objects they wrap.
 
 === Probe
 
-To understand how to analyze a method's parameters, consider the following demonstration class:
+The probe allows you to analyze a method's parameters. To understand how, consider the following demonstration class:
 
 [source,ruby]
 ----
@@ -98,7 +123,6 @@ 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
@@ -125,14 +149,158 @@ probe.positionals?         # false
 probe.splats               # []
 probe.splats?              # false
 probe.to_a                 # []
-probe.to_h                 # {}
 ----
 
+=== Categorizer
+
+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:
+
+[source,ruby]
+----
+function = proc { "test" }
+
+module Demo
+  def self.test one, two = nil, *three, four:, five: nil, **six, &seven
+    puts "The .#{__method__} method received the following arguments:\n"
+
+    [one, two, three, four, five, six, seven].each.with_index 1 do |argument, index|
+      puts "#{index}. #{argument.inspect}"
+    end
+
+    puts
+  end
+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
+  end
+end
+
+Inspector.call [1, nil, nil, {four: 4}]
+
+# #<Struct:Marameters::Splat:0x00021930
+#   block = nil,
+#   keywords = {
+#     :four => 4
+#   },
+#   positionals = [
+#     1,
+#     nil
+#   ]
+# >
+#
+# The .test method received the following arguments:
+# 1. 1
+# 2. nil
+# 3. []
+# 4. 4
+# 5. nil
+# 6. {}
+# 7. nil
+----
+
+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.
+. 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.
+. Finally, `Demo.test` method is called with the splatted arguments.
+
+The above example satisfies the minimum required arguments but if we pass in the maximum arguments -- loosely speaking -- we see more detail:
+
+[source,ruby]
+----
+Inspector.call [1, 2, [98, 99], {four: 4}, {five: 5}, {twenty: 20, thirty: 30}, function]
+
+# Output
+
+# #<Struct:Marameters::Splat:0x00029cc0
+#   block = #<Proc:0x000000010a88cec0 (irb):1>,
+#   keywords = {
+#       :four => 4,
+#       :five => 5,
+#     :twenty => 20,
+#     :thirty => 30
+#   },
+#   positionals = [
+#     1,
+#     2,
+#     98,
+#     99
+#   ]
+# >
+#
+# The .test method received the following arguments:
+# 1. 1
+# 2. 2
+# 3. [98, 99]
+# 4. 4
+# 5. 5
+# 6. {:twenty=>20, :thirty=>30}
+# 7. #<Proc:0x000000010a88cec0 (irb):1>
+----
+
+Once again, it is important to keep in mind that the argument positions _must_ align with the parameter positions since the parameters are an array of elements too. For illustration purposes -- using the above example -- we can compare the parameters to the arguments as follows:
+
+[source,ruby]
+----
+parameters = Demo.method(:test).parameters
+arguments = [1, 2, [98, 99], {four: 4}, {five: 5}, {twenty: 20, thirty: 30}, function]
+----
+
+With {amazing_print_link}, we can print out this information:
+
+[source,ruby]
+----
+ap parameters
+ap arguments
+----
+
+...which can be further illustrated by this comparison table:
+
+[options="header"]
+|===
+| Parameter         | Argument
+| `%i[reg one]`     | `1`
+| `%i[opt two]`     | `2`
+| `%i[rest three]`  | `[98, 99]`
+| `%i[keyreq four]` | `{four: 4}`
+| `%i[key five]`    | `{five: 5}`
+| `%i[keyrest six]` | `{twenty: 20, thirty: 30}`
+| `%i[block seven]` | `#<Proc:0x0000000108edc778>`
+|===
+
+This also means that:
+
+* 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.
+* 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:
+
+[source,ruby]
+----
+url = Struct.new :label, :url, keyword_init: true
+
+Marameters.categorize(url.method(:new).parameters, {label: "Eaxmple", url: "https://example.com"})
+          .then { |splat| url.new(*splat.positionals, **splat.keywords) }
+
+# Yields: #<struct label="Eaxmple", url="https://example.com">
+----
+
+For further details, please refer back to my {article_link} article mentioned in the _Requirements_ section.
+
 === Signature
 
-The signature class is the opposite of the probe 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 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 following demonstrates how you might construct a method signature with all possible parameters:
 

data/lib/marameters/builder.rb

@@ -7,7 +7,6 @@ module Marameters
       @defaulter = defaulter
     end
 
-    # :reek:DuplicateMethodCall
     def call kind, name, default: nil
       case kind
         when :req then name

data/lib/marameters/categorizer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "refinements/structs"
+
+module Marameters
+  # Builds the primary argument categories based on method parameters and arguments.
+  class Categorizer
+    using Refinements::Structs
+
+    def initialize parameters, model: Splat
+      @parameters = parameters
+      @model = model
+    end
+
+    def call arguments
+      @record = model.new
+      map arguments.is_a?(Array) ? arguments : [arguments]
+      record
+    end
+
+    private
+
+    attr_reader :parameters, :model, :record
+
+    def map arguments
+      return record if arguments.empty?
+
+      size = arguments.size
+
+      parameters.each.with_index do |pair, index|
+        filter pair, arguments[index] if index < size
+      end
+    end
+
+    def filter pair, value
+      case pair
+        in [:rest] | [:rest, :*] then splat_positional value
+        in [:keyrest] | [:keyrest, :**] then record.keywords = Hash value
+        in [:req, *] | [:opt, *] then record.positionals.append value
+        in [:rest, *] then record.positionals.append(*value)
+        in [:nokey] then nil
+        in [:keyreq, *] | [:key, *] then record.keywords.merge! value if value
+        in [:keyrest, *] then record.keywords.merge!(**value) if value
+        in [:block, *] then record.block = value
+        else fail ArgumentError, "Invalid parameter kind: #{pair.first.inspect}."
+      end
+    rescue TypeError
+      raise TypeError, "#{value.inspect} is an invalid #{pair.first.inspect} value."
+    end
+
+    def splat_positional value
+      return unless value
+
+      record.positionals = value.is_a?(Array) ? value : [value]
+    end
+  end
+end

data/lib/marameters/defaulter.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Marameters
-  # Calculates the default for a given value when used within a method's parameter.
+  # Computes a method parameter's default value.
   class Defaulter
     PASSTHROUGH = "*"
 

data/lib/marameters/probe.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
-require "refinements/arrays"
-
 module Marameters
-  # Provides insight into a method's parameters.
+  # Provides information on a method's parameters.
   class Probe
-    using Refinements::Arrays
+    CATEGORIES = {
+      positionals: %i[req opt],
+      keywords: %i[keyreq key],
+      splats: %i[rest keyrest]
+    }.freeze
 
     def self.of klass, name, collection: []
       method = klass.instance_method name
@@ -16,32 +18,32 @@ module Marameters
       collection
     end
 
-    def initialize parameters
+    attr_reader :keywords, :positionals, :splats
+
+    def initialize parameters, categories: CATEGORIES
       @parameters = parameters
-      @items = parameters.reduce({}) { |all, (kind, name)| all.merge kind => name }
+      categories.each { |category, kinds| define_variable category, kinds }
     end
 
-    def block = items[:block]
+    def block = parameters.find { |kind, name| break name if kind == :block }
 
-    def block? = items.key? :block
+    def block? = (parameters in [*, [:block, *]])
 
-    def empty? = items.empty?
+    def empty? = parameters.empty?
 
     def keyword_slice collection, keys:
       collection.select { |key| !keys.include?(key) || keywords.include?(key) }
     end
 
-    def keywords = items.values_at(:keyreq, :key).compress!
-
     def keywords? = keywords.any?
 
-    def kind?(kind) = items.key? kind
+    def kind?(value) = parameters.any? { |kind, _name| kind == value }
 
-    def kinds = items.keys
+    def kinds = parameters.map { |kind, _name| kind }
 
-    def name?(name) = items.value? name
+    def name?(value) = parameters.any? { |_kind, name| name == value }
 
-    def names = items.values
+    def names = parameters.map { |_kind, name| name }
 
     def only_bare_splats? = (parameters in [[:rest]] | [[:keyrest]] | [[:rest], [:keyrest]])
 
@@ -49,20 +51,19 @@ module Marameters
 
     def only_single_splats? = (parameters in [[:rest, *]])
 
-    def positionals = items.values_at(:req, :opt).compress!
-
     def positionals? = positionals.any?
 
-    def splats = items.values_at(:rest, :keyrest).compress!
-
     def splats? = splats.any?
 
     def to_a = parameters
 
-    def to_h = items
-
     private
 
-    attr_reader :parameters, :items
+    attr_reader :parameters
+
+    def define_variable category, kinds
+      parameters.filter_map { |kind, name| next name if kinds.include? kind }
+                .then { |collection| instance_variable_set "@#{category}", collection }
+    end
   end
 end

data/lib/marameters/signature.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Marameters
-  # Produces a method signature for given parameters.
+  # Builds a method's parameter signature.
   class Signature
     def initialize parameters, builder: Builder.new
       @parameters = parameters

data/lib/marameters/splat.rb

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

data/lib/marameters.rb

@@ -6,4 +6,11 @@ Zeitwerk::Loader.for_gem.setup
 
 # Main namespace.
 module Marameters
+  def self.categorize(parameters, arguments) = Categorizer.new(parameters).call(arguments)
+
+  def self.of(...) = Probe.of(...)
+
+  def self.probe(...) = Probe.new(...)
+
+  def self.signature(...) = Signature.new(...)
 end

data/marameters.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "marameters"
-  spec.version = "0.6.0"
+  spec.version = "0.9.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://www.alchemists.io/projects/marameters"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: marameters
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,7 +28,7 @@ cert_chain:
   CxDe2+VuChj4I1nvIHdu+E6XoEVlanUPKmSg6nddhkKn2gC45Kyzh6FZqnzH/CRp
   RFE=
   -----END CERTIFICATE-----
-date: 2022-08-13 00:00:00.000000000 Z
+date: 2022-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: refinements
@@ -71,9 +71,11 @@ files:
 - README.adoc
 - lib/marameters.rb
 - lib/marameters/builder.rb
+- lib/marameters/categorizer.rb
 - lib/marameters/defaulter.rb
 - lib/marameters/probe.rb
 - lib/marameters/signature.rb
+- lib/marameters/splat.rb
 - marameters.gemspec
 homepage: https://www.alchemists.io/projects/marameters
 licenses:
@@ -101,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.19
+rubygems_version: 3.3.21
 signing_key:
 specification_version: 4
 summary: Provides dynamic method parameter construction and deconstruction.