marameters 0.0.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a92d21f1146d77f296e63cf36db2f70a2b71318c6d117bb962fc4d4ac34616c
-  data.tar.gz: 102690432048fb246e14f6bce38ed34d1ac6415ed82a7356ac3f43313bf78eeb
+  metadata.gz: 832b6f5bce93dd251a0e1972c9e4ef234237dc1d1e94f6b8ca15814dec7ddc00
+  data.tar.gz: 23c459d6e85fa64da272f5c9b319084f188c31d0360856be9826a92f59b619d9
 SHA512:
-  metadata.gz: 91efba790017f9d67f5de1513027455a34915822346b6e0e4502dfb6d4e1d0bb4e638342b364108caac35a8598cd18344f6df7d68743107db355cf36eb9470cd
-  data.tar.gz: 7931c8990397233aac682ca43701b5b90c4d045263abde99c3d52ac800050acbaabea5b96d02e5f0fae687d635894d3d1681d9f0eb856a1cd5f27219c0e8b6cb
+  metadata.gz: '0338c575983adaff7b72af01ddc941ba2084b095f073992e853c740ac2aac70f8c4f3eaff9cea4001802240393e52b0a6cceb00ac3d20b47eda320591546e7b7'
+  data.tar.gz: 9bddaf3365b3b3d60f766479a036d754f6323082d606a1120a99343145858ba92436177236bf6f1cb6901b810bba55184ff0512262061fe25d58cf3db36a3663

data/README.adoc

@@ -4,23 +4,23 @@
 
 = Marameters
 
-Marameters is short for method parameters (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 to 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)`.
+* *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`.
+  Example: `demo 1, two: 2`.
 
 This gem will help you debug methods or -- more importantly -- aid your workflow when
-metaprogramming and architecting more sophisticated applications.
+metaprogramming, as used in the link:https://www.alchemists.io/projects/auto_injector[Auto Injector]
+gem, when architecting more sophisticated applications.
 
 toc::[]
 
 == Features
 
-* Provides a core object as a primary interface.
 * Provides specialized objects for keyword, positional, and splatted parameters.
 
 == Requirements
@@ -45,50 +45,172 @@ gem "marameters"
 
 == Usage
 
-The primary object you'll most likely want to interact with is the `Marameters::Core` class. The
-following code snippet will help demonstrate the Object API:
+There are two main objects you'll want to interact with:
+
+* *Marameters::Probe*: Allows you to analyze a method's parameters.
+* *Marameters::Signature*: Allows you to dynamically build a method signature from raw parameters.
+
+Both of these objects are meant to serve as building blocks to more complex architectures.
+
+=== Probe
+
+To understand how to analyze a method's parameters, consider the following demonstration class:
 
 [source,ruby]
 ----
 class Demo
-  def example one, two = nil, *three, four:, five: nil, **six, &seven
-    [one, two, three, four, five, six, seven]
+  def initialize logger: Logger.new(STDOUT)
+    @logger = logger
+  end
+
+  def all one, two = nil, *three, four:, five: nil, **six, &seven
+    logger.debug [one, two, three, four, five, six, seven]
   end
+
+  def none = logger.debug "Nothing to see here."
+
+  private
+
+  attr_reader :logger
 end
+----
 
-marameters = Marameters::Core.new Demo.instance_method(:example).parameters
+You can then probe the `#all` method's parameters as follows:
 
-marameters.empty?                    # false
-marameters.keyword? :one             # false
-marameters.keyword? :four            # true
-marameters.keywords                  # [:four, :five]
-marameters.kinds                     # [:req, :opt, :keyreq, :key, :rest, :keyrest]
-marameters.named_single_splat_only?  # false
-marameters.names                     # [:one, :two, :four, :five, :three, :six]
-marameters.positional?               # true
-marameters.positionals               # [:one, :two]
-marameters.to_a                      # [[:req, :one], [:opt, :two], [:rest, :three], [:keyreq, :four], [:key, :five], [:keyrest, :six], [:block, :seven]]
-marameters.unnamed_splats_only?      # false
+[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}
 ----
 
-The `Marameters::Core` delegates to the following classes which you can use individually as well:
+In contrast the above, we can also probe the `#none` method which has no parameters for a completely
+different result:
 
 [source,ruby]
 ----
-class Demo
-  def example one, two = nil, *three, four:, five: nil, **six, &seven
-    [one, two, three, four, five, six, seven]
-  end
-end
+probe = Marameters::Probe.new 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                 # {}
+----
+
+=== 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.
 
-# Specializes in positional method parameters only.
-positional = Marameters::Positional.new Demo.instance_method(:example).parameters
+The following demonstrates how you might construct a method signature with all possible parameters:
+
+[source,ruby]
+----
+signature = Marameters::Signature.new(
+  {
+    req: :one,
+    opt: [:two, 2],
+    rest: :three,
+    keyreq: :four,
+    key: [:five, 5],
+    keyrest: :six,
+    block: :seven
+  }
+)
+
+puts signature
+# one, two = 2, *three, four:, five: 5, **six, &seven
+----
+
+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 explicit nil as default
+puts Marameters::Signature.new({key: [:demo, nil]})
+# demo: nil
+
+# With string as default
+puts Marameters::Signature.new({key: [:demo, "test"]})
+# demo: "test"
+
+# With symbol as default
+puts Marameters::Signature.new({key: [:demo, :test]})
+# demo: :test
+
+# With object(dependency) as default
+puts Marameters::Signature.new({key: [:demo, "*Object.new"]})
+# demo: Object.new
+----
+
+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:
+
+* 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.
+
+When you put all of this together, you can dynamically build a method as follows:
+
+[source,ruby]
+----
+signature = Marameters::Signature.new({opt: [:text, "This is a test."]})
+
+Example = Module.new do
+  module_eval <<~DEFINITION, __FILE__, __LINE__ + 1
+    def self.say(#{signature}) = text
+  DEFINITION
+end
 
-# Specializes in keyword method parameters only.
-keyword = Marameters::Keyword.new Demo.instance_method(:example).parameters
+puts Example.say
+# This is a test.
 
-# Specializes in splatted method parameters only.
-splat = Marameters::Splat.new Demo.instance_method(:example).parameters
+puts Example.say "Hello"
+# Hello
 ----
 
 == Development

data/lib/marameters/builder.rb

@@ -0,0 +1,28 @@
+# 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
+
+    # :reek:DuplicateMethodCall
+    def call kind, name, default: nil
+      case kind
+        when :req then name
+        when :opt then "#{name} = #{defaulter.call default}"
+        when :rest then "*#{name}"
+        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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Marameters
+  # Calculates the default for a given value when used within a method's parameter.
+  class Defaulter
+    PASSTHROUGH = "*"
+
+    def self.call(...) = new(...).call
+
+    def initialize value, passthrough: PASSTHROUGH
+      @value = value
+      @passthrough = passthrough
+    end
+
+    def call
+      case value
+        when nil then "nil"
+        when /\A#{Regexp.escape passthrough}/ then value.delete_prefix passthrough
+        when String then value.dump
+        when Symbol then value.inspect
+        else value
+      end
+    end
+
+    private
+
+    attr_reader :value, :passthrough
+  end
+end

data/lib/marameters/probe.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "refinements/arrays"
+
+module Marameters
+  # Provides insight into a method's parameters.
+  class Probe
+    using Refinements::Arrays
+
+    # :reek:TooManyStatements
+    def self.of klass, name, collection: []
+      method = klass.instance_method name
+
+      return collection unless method
+
+      collection << new(method.parameters)
+      super_method = method.super_method
+      of super_method.owner, super_method.name, collection:
+    rescue NameError
+      collection
+    end
+
+    def initialize parameters
+      @parameters = parameters
+      @items = parameters.reduce({}) { |all, (kind, name)| all.merge kind => name }
+    end
+
+    def block = items[:block]
+
+    def block? = items.key? :block
+
+    def empty? = items.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 kinds = items.keys
+
+    def name?(name) = items.value? name
+
+    def names = items.values
+
+    def only_bare_splats? = (parameters in [[:rest]] | [[:keyrest]] | [[:rest], [:keyrest]])
+
+    def only_double_splats? = (parameters in [[:keyrest, *]])
+
+    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
+  end
+end

data/lib/marameters/signature.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Marameters
+  # Produces a method signature for given parameters.
+  class Signature
+    def initialize parameters, builder: Builder.new
+      @parameters = parameters
+      @builder = builder
+    end
+
+    def to_s = build.join ", "
+
+    alias to_str to_s
+
+    private
+
+    attr_reader :parameters, :builder
+
+    def build
+      parameters.reduce [] do |signature, (kind, (name, default))|
+        signature << builder.call(kind, name, default:)
+      end
+    end
+  end
+end

data/lib/marameters.rb

@@ -6,8 +6,4 @@ Zeitwerk::Loader.for_gem.setup
 
 # Main namespace.
 module Marameters
-  TRANSFORMER = lambda do |parameters, pattern|
-    parameters.select { |kind, _name| pattern.include? kind }
-              .reduce({}) { |collection, (kind, name)| collection.merge kind => name }
-  end
 end

data/marameters.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |spec|
   spec.name = "marameters"
-  spec.version = "0.0.0"
+  spec.version = "0.3.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://www.alchemists.io/projects/marameters"
-  spec.summary = "Provides method parameter introspection."
+  spec.summary = "Provides dynamic method parameter construction and deconstruction."
   spec.license = "Hippocratic-2.1"
 
   spec.metadata = {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: marameters
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -10,9 +10,9 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIIC/jCCAeagAwIBAgIBBDANBgkqhkiG9w0BAQsFADAlMSMwIQYDVQQDDBpicm9v
-  a2UvREM9YWxjaGVtaXN0cy9EQz1pbzAeFw0yMTAzMTkxMjQ4MDZaFw0yMjAzMTkx
-  MjQ4MDZaMCUxIzAhBgNVBAMMGmJyb29rZS9EQz1hbGNoZW1pc3RzL0RDPWlvMIIB
+  MIIC/jCCAeagAwIBAgIBBTANBgkqhkiG9w0BAQsFADAlMSMwIQYDVQQDDBpicm9v
+  a2UvREM9YWxjaGVtaXN0cy9EQz1pbzAeFw0yMjAzMTkxNzI0MzJaFw0yMzAzMTkx
+  NzI0MzJaMCUxIzAhBgNVBAMMGmJyb29rZS9EQz1hbGNoZW1pc3RzL0RDPWlvMIIB
   IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6l1qpXTiomH1RfMRloyw7MiE
   xyVx/x8Yc3EupdH7uhNaTXQGyORN6aOY//1QXXMHIZ9tW74nZLhesWMSUMYy0XhB
   brs+KkurHnc9FnEJAbG7ebGvl/ncqZt72nQvaxpDxvuCBHgJAz+8i5wl6FhLw+oT
@@ -20,15 +20,15 @@ cert_chain:
   D5vkU0YlAm1r98BymuJlcQ1qdkVEI1d48ph4kcS0S0nv1RiuyVb6TCAR3Nu3VaVq
   3fPzZKJLZBx67UvXdbdicWPiUR75elI4PXpLIic3xytaF52ZJYyKZCNZJhNwfQID
   AQABozkwNzAJBgNVHRMEAjAAMAsGA1UdDwQEAwIEsDAdBgNVHQ4EFgQU0nzow9vc
-  2CdikiiE3fJhP/gY4ggwDQYJKoZIhvcNAQELBQADggEBAEjpaOXHHp8s/7GL2qCb
-  YAs7urOLv9VHSPfQWAwaTMVnSsIf3Sw4xzISOP/mmfEPBPXtz61K5esrE/uTFtgb
-  FyjxQk2H0sEWgrRXGGNHBWQRhhEs7LP/TByoC15A0br++xLxRz4r7HBLGAWQQDpg
-  66BJ2TBVjxS6K64tKbq7+ACyrOZGgTfNHACh4M076y0x0oRf/rwBrU39/KRfuhbb
-  cm+nNCEtO35gTmZ2bVDHLGvWazi3gJt6+huQjfXTCUUG2YYBxwhu+GPdAGQPxpf9
-  lkHilIrX69jq8wMPpBhlaw2mRmeSL50Wv5u6xVBvOHhXFSP1crXM95vfLhLyRYod
-  W2A=
+  2CdikiiE3fJhP/gY4ggwDQYJKoZIhvcNAQELBQADggEBAJbbNyWzFjqUNVPPCUCo
+  IMrhDa9xf1xkORXNYYbmXgoxRy/KyNbUr+jgEEoWJAm9GXlcqxxWAUI6pK/i4/Qi
+  X6rPFEFmeObDOHNvuqy8Hd6AYsu+kP94U/KJhe9wnWGMmGoNKJNU3EkW3jM/osSl
+  +JRxiH5t4WtnDiVyoYl5nYC02rYdjJkG6VMxDymXTqn7u6HhYgZkGujq1UPar8x2
+  hNIWJblDKKSu7hA2d6+kUthuYo13o1sg1Da/AEDg0hoZSUvhqDEF5Hy232qb3pDt
+  CxDe2+VuChj4I1nvIHdu+E6XoEVlanUPKmSg6nddhkKn2gC45Kyzh6FZqnzH/CRp
+  RFE=
   -----END CERTIFICATE-----
-date: 2022-03-06 00:00:00.000000000 Z
+date: 2022-04-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: refinements
@@ -70,10 +70,10 @@ files:
 - LICENSE.adoc
 - README.adoc
 - lib/marameters.rb
-- lib/marameters/core.rb
-- lib/marameters/keyword.rb
-- lib/marameters/positional.rb
-- lib/marameters/splat.rb
+- lib/marameters/builder.rb
+- lib/marameters/defaulter.rb
+- lib/marameters/probe.rb
+- lib/marameters/signature.rb
 - marameters.gemspec
 homepage: https://www.alchemists.io/projects/marameters
 licenses:
@@ -100,8 +100,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.8
+rubygems_version: 3.3.10
 signing_key:
 specification_version: 4
-summary: Provides method parameter introspection.
+summary: Provides dynamic method parameter construction and deconstruction.
 test_files: []

data/lib/marameters/core.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-module Marameters
-  # Provides access to method arguments for meta-programming and/or debugging purposes.
-  class Core
-    # Order matters.
-    DELEGATES = {positional: Positional, keyword: Keyword, splat: Splat}.freeze
-
-    # :reek:TooManyStatements
-    def self.of klass, name, collection: []
-      method = klass.instance_method name
-
-      return collection unless method
-
-      collection << new(method.parameters)
-      super_method = method.super_method
-      of super_method.owner, super_method.name, collection:
-    rescue NameError
-      collection
-    end
-
-    def initialize parameters, delegates: DELEGATES
-      @parameters = parameters
-
-      @delegates = delegates.reduce({}) do |accumulator, (key, klass)|
-        accumulator.merge key => klass.new(parameters)
-      end
-    end
-
-    def empty? = parameters.empty?
-
-    def keyword?(name) = keyword.name? name
-
-    def keywords = keyword.names
-
-    def kinds = delegates.values.reduce([]) { |collection, delegate| collection + delegate.kinds }
-
-    def named_single_splat_only? = splat.named_single_only?
-
-    def names = delegates.values.reduce([]) { |collection, delegate| collection + delegate.names }
-
-    def positional? = !positional.empty?
-
-    def positionals = positional.names
-
-    def slice collection, keys:
-      collection.select { |key| !keys.include?(key) || keyword.names.include?(key) }
-    end
-
-    def to_a = parameters
-
-    def unnamed_splats_only? = splat.unnamed_only?
-
-    private
-
-    attr_reader :parameters, :delegates
-
-    def keyword = delegates.fetch(__method__)
-
-    def splat = delegates.fetch(__method__)
-
-    def positional = delegates.fetch(__method__)
-  end
-end

data/lib/marameters/keyword.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Marameters
-  # Specializes in providing keyword method parameter information only.
-  class Keyword
-    PATTERN = %i[key keyreq].freeze
-
-    def initialize parameters, pattern: PATTERN, transformer: TRANSFORMER
-      @parameters = parameters
-      @collection = transformer.call parameters, pattern
-    end
-
-    def empty? = collection.empty?
-
-    def kinds = collection.keys
-
-    def name?(name) = collection.value? name
-
-    def names = collection.values
-
-    private
-
-    attr_reader :parameters, :collection
-  end
-end

data/lib/marameters/positional.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Marameters
-  # Specializes in providing positional method paratemer information only.
-  class Positional
-    PATTERN = %i[req opt].freeze
-
-    def initialize parameters, pattern: PATTERN, transformer: TRANSFORMER
-      @parameters = parameters
-      @collection = transformer.call parameters, pattern
-    end
-
-    def empty? = collection.empty?
-
-    def kinds = collection.keys
-
-    def names = collection.values
-
-    private
-
-    attr_reader :parameters, :collection
-  end
-end

data/lib/marameters/splat.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module Marameters
-  # Specializes in providing passthrough method parameter information only.
-  class Splat
-    PATTERN = %i[rest keyrest].freeze
-
-    def initialize parameters, pattern: PATTERN, transformer: TRANSFORMER
-      @parameters = parameters
-      @collection = transformer.call parameters, pattern
-    end
-
-    def empty? = collection.empty?
-
-    def kinds = collection.keys
-
-    def names = collection.values
-
-    def named_double_only? = (parameters in [[:keyrest, *]])
-
-    def named_single_only? = (parameters in [[:rest, *]])
-
-    def unnamed_only? = (parameters in [[:rest]] | [[:keyrest]] | [[:rest], [:keyrest]])
-
-    private
-
-    attr_reader :parameters, :collection
-  end
-end