marameters 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e9a67405793129c6913e84a4ead90cbc6eda2abbec139f00764a677aa6d30b1
-  data.tar.gz: fe3d699a7717e37ae79d07773870cf1137ad0b4b14a761c3eaaa56ed9a4f9fdd
+  metadata.gz: a3daee40e52b7df55680618be8c5a37a6a62c3ca7f62b88128fbc724f4222c50
+  data.tar.gz: 3b4d527a40fc8ed6500faea3e6676b45be484a2fb9288b5e79ee38684ac0bec0
 SHA512:
-  metadata.gz: ded0a8de22a2f67bdb2f308bbfc02db520fb98028b1595825d9e4ab82396b6bdb062a5a602c1df52ced38862963c5b0eb3285cdee586a6934f5f888a6777d313
-  data.tar.gz: bc840a326f4116973cda051c23b411f92e74b53e2f704e69adb9536159ef178a16b094c29f52b038dfb17af65be2f26fbe10e7d062da2b5e222bb704895a7793
+  metadata.gz: 459d04fcc654dcf3ef58d23dfaaff01f5df52e0ffbb8d670cb0d1a9f59f10f91d0e9ff424e5871c9e892a1ba7f2b4cbdb236a287e3b3ffbdf32a1e56de9b5f97
+  data.tar.gz: 92df818d39aeacd231721b69299e0e23705b0f889db54360fefd0f269355fcbf40499b62c59bfc30a22b99dac39874b8a168c381e825ae4b2891a18b6fd9f53f

data/README.adoc

@@ -14,7 +14,8 @@ difference between a method's parameters and arguments is:
   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::[]
 
@@ -45,8 +46,16 @@ gem "marameters"
 
 == Usage
 
-The primary object you'll want to interact with is the `Marameters::Analyzer` class. To understand
-how to _analyze_ a method's parameters, consider the following demonstration class:
+There are two main objects you'll want to interact with:
+
+* *Analyzer*: Allows you to analyze a method's parameters.
+* *Signature*: Allows you to dynamically build a method signature.
+
+Both of these objects are meant to serve as building blocks to more complex architectures.
+
+=== Analyzer
+
+To understand how to _analyze_ a method's parameters, consider the following demonstration class:
 
 [source,ruby]
 ----
@@ -55,21 +64,23 @@ class Demo
     @logger = logger
   end
 
-  def example one, two = nil, *three, four:, five: nil, **six, &seven
+  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
 ----
 
-We can then analyze the above `#example` method's parameters as follows:
+You can then analyze the `#all` method's parameters as follows:
 
 [source,ruby]
 ----
-analyzer = Marameters::Analyzer.new Demo.instance_method(:example).parameters
+analyzer = Marameters::Analyzer.new Demo.instance_method(:all).parameters
 
 analyzer.block                # :seven
 analyzer.block?               # true
@@ -91,6 +102,119 @@ analyzer.to_a                 # [[:req, :one], [:opt, :two], [:rest, :three], [:
 analyzer.to_h                 # {:req=>:one, :opt=>:two, :rest=>:three, :keyreq=>:four, :key=>:five, :keyrest=>:six, :block=>:seven}
 ----
 
+In contrast the above, we can also analyze the `#none` method which has no parameters for a
+completely different result:
+
+[source,ruby]
+----
+analyzer = Marameters::Analyzer.new Demo.instance_method(:none).parameters
+
+analyzer.block                # nil
+analyzer.block?               # false
+analyzer.empty?               # true
+analyzer.keywords             # []
+analyzer.keywords?            # false
+analyzer.kind?(:req)          # true
+analyzer.kinds                # []
+analyzer.name?(:three)        # false
+analyzer.names                # []
+analyzer.only_bare_splats?    # false
+analyzer.only_double_splats?  # false
+analyzer.only_single_splats?  # false
+analyzer.positionals          # []
+analyzer.positionals?         # false
+analyzer.splats               # []
+analyzer.splats?              # false
+analyzer.to_a                 # []
+analyzer.to_h                 # {}
+----
+
+=== Signature
+
+The signature class is the opposite of the analyzer 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 for multiple methods when metaprogramming.
+
+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 is 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 analyzer 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 these as a normal string. There are two reasons why
+this is important:
+
+* The star (`*`) signifies that you want the object to be passed through without any further
+  processing while also not being confused normal strings.
+* Objects wrapped as strings allows your dependency to be lazy loaded. Otherwise, if `Object.new`
+  was pass 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
+    end
+  DEFINITION
+end
+
+puts Example.say
+# This is a test.
+
+puts Example.say "Hello"
+# Hello
+----
+
 == Development
 
 You can also use the IRB console for direct access to all objects:

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/signature.rb

@@ -0,0 +1,23 @@
+# 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 ", "
+
+    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/marameters.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |spec|
   spec.name = "marameters"
-  spec.version = "0.1.0"
+  spec.version = "0.2.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://www.alchemists.io/projects/marameters"
-  spec.summary = "Provides method parameter introspection which is useful when metaprogramming."
+  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.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -28,7 +28,7 @@ cert_chain:
   lkHilIrX69jq8wMPpBhlaw2mRmeSL50Wv5u6xVBvOHhXFSP1crXM95vfLhLyRYod
   W2A=
   -----END CERTIFICATE-----
-date: 2022-03-11 00:00:00.000000000 Z
+date: 2022-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: refinements
@@ -71,6 +71,9 @@ files:
 - README.adoc
 - lib/marameters.rb
 - lib/marameters/analyzer.rb
+- lib/marameters/builder.rb
+- lib/marameters/defaulter.rb
+- lib/marameters/signature.rb
 - marameters.gemspec
 homepage: https://www.alchemists.io/projects/marameters
 licenses:
@@ -97,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.9
 signing_key:
 specification_version: 4
-summary: Provides method parameter introspection which is useful when metaprogramming.
+summary: Provides dynamic method parameter construction and deconstruction.
 test_files: []