:toc: macro
:toclevels: 5
:figure-caption!:

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

* *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 and architecting more sophisticated applications.

toc::[]

== Features

* Provides a core object as a primary interface.
* Provides specialized objects for keyword, positional, and splatted parameters.

== Requirements

. link:https://www.ruby-lang.org[Ruby].

== Setup

To install, run:

[source,bash]
----
gem install marameters
----

Add the following to your Gemfile file:

[source,ruby]
----
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:

[source,ruby]
----
class Demo
  def initialize logger: Logger.new(STDOUT)
    @logger = logger
  end

  def example one, two = nil, *three, four:, five: nil, **six, &seven
    logger.debug [one, two, three, four, five, six, seven]
  end

  private

  attr_reader :logger
end
----

We can then analyze the above `#example` method's parameters as follows:

[source,ruby]
----
analyzer = Marameters::Analyzer.new Demo.instance_method(:example).parameters

analyzer.block                # :seven
analyzer.block?               # true
analyzer.empty?               # false
analyzer.keywords             # [:four, :five]
analyzer.keywords?            # true
analyzer.kind?(:keyrest)      # true
analyzer.kinds                # [:req, :opt, :rest, :keyreq, :key, :keyrest, :block]
analyzer.name?(:three)        # true
analyzer.names                # [:one, :two, :three, :four, :five, :six, :seven]
analyzer.only_bare_splats?    # false
analyzer.only_double_splats?  # false
analyzer.only_single_splats?  # false
analyzer.positionals          # [:one, :two]
analyzer.positionals?         # true
analyzer.splats               # [:three, :six]
analyzer.splats?              # true
analyzer.to_a                 # [[:req, :one], [:opt, :two], [:rest, :three], [:keyreq, :four], [:key, :five], [:keyrest, :six], [:block, :seven]]
analyzer.to_h                 # {:req=>:one, :opt=>:two, :rest=>:three, :keyreq=>:four, :key=>:five, :keyrest=>:six, :block=>:seven}
----

== Development

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

[source,bash]
----
bin/console
----

== Tests

To test, run:

[source,bash]
----
bundle exec rake
----

== link:https://www.alchemists.io/policies/license[License]

== link:https://www.alchemists.io/policies/security[Security]

== link:https://www.alchemists.io/policies/code_of_conduct[Code of Conduct]

== link:https://www.alchemists.io/policies/contributions[Contributions]

== link:https://www.alchemists.io/projects/marameters/versions[Versions]

== link:https://www.alchemists.io/community[Community]

== Credits

* Built with link:https://www.alchemists.io/projects/gemsmith[Gemsmith].
* Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].