Marameters

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.

This gem will help you debug methods or aid your workflow when metaprogramming — as used in the Infusible gem — when architecting more sophisticated applications.

Table of Contents

Features
Requirements
Setup
Usage
- Probe
- Categorizer
- Signature
Development
Tests
License
Security
Code of Conduct
Contributions
Versions
Community
Credits

Features

Provides specialized objects for keyword, positional, and block parameters.

Requirements

Ruby.
A solid understanding of method parameters and arguments.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install marameters --trust-policy HighSecurity

To install without security, run:

gem install marameters

You can also add the gem directly to your project:

bundle add marameters

Once the gem is installed, you only need to require it:

require "marameters"

Usage

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
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 wrapper

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

# 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

The probe allows you to analyze a method’s parameters. To understand how, consider the following:

class Demo
  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

You can then probe the #all method’s parameters as follows:

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]]

In contrast the above, we can also probe the #none method which has no parameters for a completely different result:

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                 # []

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 (i.e. ap) is used to format the output:

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:

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:

parameters = Demo.method(:test).parameters
arguments = [1, 2, [98, 99], {four: 4}, {five: 5}, {twenty: 20, thirty: 30}, function]

With Amazing Print, we can print out this information:

ap parameters
ap arguments

…which can be further illustrated by this comparison table:

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 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:

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 method parameters and arguments article mentioned in the 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 following demonstrates how you might construct a method signature with all possible parameters:

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):

# 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:

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

puts Example.say
# This is a test.

puts Example.say "Hello"
# Hello

Development

To contribute, run:

git clone https://github.com/bkuhlmann/marameters
cd marameters
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

Credits

Built with Gemsmith.
Engineered by Brooke Kuhlmann.

marameters

Runtime

Marameters

Features

Requirements

Setup

Usage

Probe

Categorizer

Signature

Development

Tests

License

Security

Code of Conduct

Contributions

Versions

Community

Credits