{"id":13878650,"url":"https://github.com/bkuhlmann/marameters","last_synced_at":"2025-08-01T07:38:19.388Z","repository":{"id":45138330,"uuid":"466602187","full_name":"bkuhlmann/marameters","owner":"bkuhlmann","description":"A dynamic method parameter inspector.","archived":false,"fork":false,"pushed_at":"2024-10-23T23:48:28.000Z","size":298,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-24T13:24:35.880Z","etag":null,"topics":["metaprogramming","methods","parameters","ruby"],"latest_commit_sha":null,"homepage":"https://alchemists.io/projects/marameters","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bkuhlmann.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.adoc","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["bkuhlmann"]}},"created_at":"2022-03-06T00:49:02.000Z","updated_at":"2024-10-18T23:01:22.000Z","dependencies_parsed_at":"2023-02-12T17:30:58.460Z","dependency_job_id":"7957ec15-51e6-48a5-8cde-02701b4349b3","html_url":"https://github.com/bkuhlmann/marameters","commit_stats":{"total_commits":176,"total_committers":1,"mean_commits":176.0,"dds":0.0,"last_synced_commit":"b27a97dff8bab34b6d76893c823760aea4b09026"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fmarameters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fmarameters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fmarameters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fmarameters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkuhlmann","download_url":"https://codeload.github.com/bkuhlmann/marameters/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242254163,"owners_count":20097529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["metaprogramming","methods","parameters","ruby"],"created_at":"2024-08-06T08:01:55.686Z","updated_at":"2025-03-06T17:31:43.538Z","avatar_url":"https://github.com/bkuhlmann.png","language":"Ruby","funding_links":["https://github.com/sponsors/bkuhlmann"],"categories":["Ruby"],"sub_categories":[],"readme":":toc: macro\n:toclevels: 5\n:figure-caption!:\n\n:amazing_print_link: link:https://github.com/amazing-print/amazing_print[Amazing Print]\n:article_link: link:https://alchemists.io/articles/ruby_method_parameters_and_arguments[method parameters and arguments]\n:infusible_link: link:/projects/infusible[Infusible]\n\n= Marameters\n\nMarameters 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:\n\n* *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`.\n* *Arguments*: Represents the _actual_ values passed to the method when messaged. Example: `demo 1, two: 2`.\n\nThis gem will help you debug methods or aid your workflow when\nmetaprogramming -- as used in the link:https://alchemists.io/projects/infusible[Infusible] gem -- when architecting more sophisticated applications.\n\ntoc::[]\n\n== Features\n\n* Provides specialized objects for keyword, positional, and block parameters.\n\n== Requirements\n\n. link:https://www.ruby-lang.org[Ruby].\n. A solid understanding of {article_link}.\n\n== Setup\n\nTo install _with_ security, run:\n\n[source,bash]\n----\n# 💡 Skip this line if you already have the public certificate installed.\ngem cert --add \u003c(curl --compressed --location https://alchemists.io/gems.pem)\ngem install marameters --trust-policy HighSecurity\n----\n\nTo install _without_ security, run:\n\n[source,bash]\n----\ngem install marameters\n----\n\nYou can also add the gem directly to your project:\n\n[source,bash]\n----\nbundle add marameters\n----\n\nOnce the gem is installed, you only need to require it:\n\n[source,ruby]\n----\nrequire \"marameters\"\n----\n\n== Usage\n\nAt a high level, you can use `Marameters` as a single Object API for accessing all capabilities provided by this gem. Here's an overview:\n\n*Setup*\n\n[source,ruby]\n----\ndef demo(one, two = 2, three: 3) = puts \"One: #{one}, Two: #{two}, Three: #{three}\"\n\nparameters = method(:demo).parameters\narguments = %w[one two]\n----\n\n*Categorize*\n\n[source,ruby]\n----\nMarameters.categorize parameters, arguments\n# #\u003cstruct Marameters::Models::Forward positionals=[\"one\", \"two\"], keywords={}, block=nil\u003e\n----\n\n*Probe*\n\n[source,ruby]\n----\nMarameters.of self, :demo            # []\n\nprobe = Marameters.for parameters\nprobe.positionals                    # [:one, :two]\nprobe.keywords                       # [:three]\nprobe.to_a                           # [[:req, :one], [:opt, :two], [:key, :three]]\n----\n\n*Signature*\n\n[source,ruby]\n----\nMarameters.signature([%i[req one], [:opt, :two, 2], [:key, :three, 3]]).to_s\n# \"one, two = 2, three: 3\"\n----\n\n=== Constants\n\nThe `KINDS` constant allows you to know the kinds of parameters allowed:\n\n[source,ruby]\n----\nMarameters::KINDS\n# [\n#   :req,\n#   :opt,\n#   :rest,\n#   :nokey,\n#   :keyreq,\n#   :key,\n#   :keyrest,\n#   :block\n# ]\n----\n\n=== Probe\n\nThe probe (`Marameters::Probe`) allows you to analyze a method's parameters. To understand how, consider the following:\n\n[source,ruby]\n----\nclass Demo\n  def initialize logger: Logger.new(STDOUT)\n    @logger = logger\n  end\n\n  def all one, two = nil, *three, four:, five: nil, **six, \u0026seven\n    logger.debug [one, two, three, four, five, six, seven]\n  end\n\n  def none = logger.debug \"Nothing to see here.\"\n\n  private\n\n  attr_reader :logger\nend\n----\n\nYou can then probe the `#all` method's parameters as follows:\n\n[source,ruby]\n----\nprobe = Marameters.for Demo.instance_method(:all).parameters\n\nprobe.deconstruct                      # (same as to_a, see below)\nprobe.empty?                           # false\nprobe.include? %i[req one]             # true\nprobe.keywords                         # [:four, :five]\nprobe.keywords?                        # true\nprobe.keywords_for :four, four: :demo  # {four: :demo}\nprobe.kind?(:keyrest)                  # true\n\nprobe.kinds\n# [:req, :opt, :rest, :keyreq, :key, :keyrest, :block]\n\nprobe.name?(:three)                    # true\n\nprobe.names\n# [:one, :two, :three, :four, :five, :six, :seven]\n\nprobe.only_bare_splats?                # false\nprobe.only_double_splats?              # false\nprobe.only_single_splats?              # false\nprobe.positionals                      # [:one, :two]\nprobe.positionals?                     # true\nprobe.positionals_and_maybe_keywords?  # true\n\nprobe.to_a\n# [\n#   [:req, :one],\n#   [:opt, :two],\n#   [:rest, :three],\n#   [:keyreq, :four],\n#   [:key, :five],\n#   [:keyrest, :six],\n#   [:block, :seven]\n# ]\n----\n\nIn contrast to the above, we can probe the `#none` method which has no parameters for a completely\ndifferent result:\n\n[source,ruby]\n----\nprobe = Marameters.for Demo.instance_method(:none).parameters\n\nprobe.deconstruct                      # (same as to_a, see below)\nprobe.empty?                           # true\nprobe.include? %i[req one]             # false\nprobe.keywords                         # []\nprobe.keywords?                        # false\nprobe.keywords_for :four, four: :demo  # {}\nprobe.kind?(:req)                      # true\nprobe.kinds                            # []\nprobe.name?(:three)                    # false\nprobe.names                            # []\nprobe.only_bare_splats?                # false\nprobe.only_double_splats?              # false\nprobe.only_single_splats?              # false\nprobe.positionals                      # []\nprobe.positionals?                     # false\nprobe.positionals_and_maybe_keywords?  # false\nprobe.to_a                             # []\n----\n\nThe `#keywords_for` method might need additional explaining because it's meant for selecting keywords which adhere to _either_ of the following criteria:\n\n* The given keys don't match any key in the given attributes.\n* The given keys match the parameter keywords.\n\n[source,ruby]\n----\nmodule Demo\n  def self.keywords(four:, five: 5, **six) = puts \"Four: #{four}, Five: #{five}, Six: #{six}\"\nend\n\nprobe = Marameters.for Demo.method(:keywords).parameters\n\nprobe.keywords_for :a, a: 1, four: 4         # {four: 4}\nprobe.keywords_for :four, a: 1               # {a: 1}\nprobe.keywords_for :a, four: 4, five: :five  # {four: 4, five: :five}\nprobe.keywords_for :a, six: {name: :test}    # {six: {name: :test}}\n----\n\nThis useful in gems, like {infusible_link}, when determining which keyword arguments to pass up to the superclass.\n\n=== Categorize\n\nCategorization (`Marameters::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:\n\n[source,ruby]\n----\nfunction = proc { \"test\" }\n\nmodule Demo\n  def self.test one, two = nil, *three, four:, five: nil, **six, \u0026seven\n    puts \"The .#{__method__} method received the following arguments:\\n\"\n\n    [one, two, three, four, five, six, seven].each.with_index 1 do |argument, index|\n      puts \"#{index}. #{argument.inspect}\"\n    end\n\n    puts\n  end\nend\n\nmodule Inspector\n  def self.call arguments\n    Marameters.categorize(Demo.method(:test).parameters, arguments)\n              .then do |record|\n                ap record\n                puts\n                Demo.test(*record.positionals, **record.keywords, \u0026record.block)\n              end\n  end\nend\n\nInspector.call [1, nil, nil, {four: 4}]\n\n# #\u003cStruct:Marameters::Models::Forward:0x00021930\n#   block = nil,\n#   keywords = {\n#     :four =\u003e 4\n#   },\n#   positionals = [\n#     1,\n#     nil\n#   ]\n# \u003e\n#\n# The .test method received the following arguments:\n# 1. 1\n# 2. nil\n# 3. []\n# 4. 4\n# 5. nil\n# 6. {}\n# 7. nil\n----\n\nWhen we step through the above implementation and output, we see the following unfold:\n\n. The `Demo` module allows us to define a maximum set of parameters and then print the arguments received for inspection purposes.\n. The `Inspector` module provides a wrapper around the categorization so we can conveniently pass in different arguments for experimentation purposes.\n. We pass in our arguments to `Inspector.call` where `nil` is used for optional arguments and hashes for keyword arguments.\n. Once inside `Inspector.call`, the `Categorizer` is initialized with the `Demo.test` method parameters.\n. Then the `splat` (i.e. Struct) is printed out so you can see the categorized positional, keyword, and block arguments.\n. Finally, `Demo.test` method is called with the splatted arguments.\n\nThe above example satisfies the minimum required arguments but if we pass in the maximum arguments -- loosely speaking -- we see more detail:\n\n[source,ruby]\n----\nInspector.call [1, 2, [98, 99], {four: 4}, {five: 5}, {twenty: 20, thirty: 30}, function]\n\n# Output\n\n# #\u003cStruct:Marameters::Models::Forward:0x00029cc0\n#   block = #\u003cProc:0x000000010a88cec0 (irb):1\u003e,\n#   keywords = {\n#       :four =\u003e 4,\n#       :five =\u003e 5,\n#     :twenty =\u003e 20,\n#     :thirty =\u003e 30\n#   },\n#   positionals = [\n#     1,\n#     2,\n#     98,\n#     99\n#   ]\n# \u003e\n#\n# The .test method received the following arguments:\n# 1. 1\n# 2. 2\n# 3. [98, 99]\n# 4. 4\n# 5. 5\n# 6. {:twenty=\u003e20, :thirty=\u003e30}\n# 7. #\u003cProc:0x000000010a88cec0 (irb):1\u003e\n----\n\nOnce 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:\n\n[source,ruby]\n----\nparameters = Demo.method(:test).parameters\narguments = [1, 2, [98, 99], {four: 4}, {five: 5}, {twenty: 20, thirty: 30}, function]\n----\n\nWith {amazing_print_link}, we can print out this information:\n\n[source,ruby]\n----\nap parameters\nap arguments\n----\n\n...which can be further illustrated by this comparison table:\n\n[options=\"header\"]\n|===\n| Parameter         | Argument\n| `%i[reg one]`     | `1`\n| `%i[opt two]`     | `2`\n| `%i[rest three]`  | `[98, 99]`\n| `%i[keyreq four]` | `{four: 4}`\n| `%i[key five]`    | `{five: 5}`\n| `%i[keyrest six]` | `{twenty: 20, thirty: 30}`\n| `%i[block seven]` | `#\u003cProc:0x0000000108edc778\u003e`\n|===\n\nThis also means:\n\n* 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://docs.ruby-lang.org/en/master/Method.html#method-i-parameters[Method#parameters] works. Use `nil` to fill an optional argument when you don't need it.\n* The `:rest` (single splat) argument must be an array or `nil` if not present because even though it is _optional_, it is still _positional_.\n* The `:keyrest` (double splat) argument -- much like the `:rest` argument -- must be a hash or `nil` if not present.\n\nLastly, 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.\n\nFor C-based primitives, like `Struct`, `Data`, etc., you'll want to provide a conversion method. Example:\n\n[source,ruby]\n----\nurl = Struct.new(:label, :url) do\n  def self.for(**) = new(**)\nend\n\nMarameters.categorize(url.method(:for).parameters, label: \"Example\", url: \"https://example.com\")\n          .then { |record| url.for(**record.keywords) }\n\n# Yields: #\u003cstruct label=\"Example\", url=\"https://example.com\"\u003e\n----\n\nFor further details, please refer back to my {article_link} article mentioned in the xref:_requirements[Requirements] section.\n\n=== Signature\n\nThe signature (`Marameters::Signature`) is the opposite of the probe class which allows you to turn a raw array of parameters into a method signature. This is most useful when metaprogramming and needing to dynamically build method signatures. Example:\n\n[source,ruby]\n----\nsignature = Marameters.signature [[:opt, :text, \"This is a test.\"]]\n\nExample = Module.new do\n  module_eval \u003c\u003c~METHOD, __FILE__, __LINE__ + 1\n    def self.say(#{signature}) = text\n  METHOD\nend\n\nputs Example.say           # \"This is a test.\"\nputs Example.say(\"Hello\")  # \"Hello\"\n----\n\n==== Keys\n\nThe following demonstrates how you can construct a method signature with all possible parameters using the same keys as used by `Method#parameters`:\n\n[source,ruby]\n----\nsignature = Marameters.signature [\n  %i[req one],\n  %i[opt two],\n  %i[rest three],\n  %i[keyreq four],\n  %i[key five],\n  %i[keyrest six],\n  %i[block seven]\n]\n\nputs signature\n# \"one, two = nil, *three, four:, five: nil, **six, \u0026seven\"\n----\n\n==== Values\n\nWith the above examples, each sub-array uses a simple key/value pair to map the kind of parameter with the corresponding name. You can also provide a _third_ value when needing to provide a default value for _optional_ parameters. Example:\n\n[source,ruby]\n----\nputs Marameters.signature([[:opt, :one, 1], [:key, :two, 2]])\n# one = 1, two: 2\n----\n\nThis can be demonstrated further by using optional keywords (same applies for optional positionals):\n\n[source,ruby]\n----\n# With implicit nil.\nputs Marameters.signature([%i[key demo]])\n# \"demo: nil\"\n\n# With explicit nil.\nputs Marameters.signature([[:key, :demo, nil]])\n# \"demo: nil\"\n\n# With any primitive.\nputs Marameters.signature([[:key, :demo, :test]])\n# \"demo: :test\"\n\n# With proc (no parameters).\nputs Marameters.signature([[:key, :demo, proc { Object.new }]])\n# \"demo: Object.new\"\n\n# With proc (with parameters).\nputs Marameters.signature([[:key, :demo, proc { |no| no }]])\n# Avoid using parameters for proc defaults. (ArgumentError)\n\n# With lambda.\nputs Marameters.signature([[:key, :demo, -\u003e { Object.new }]])\n# Use procs instead of lambdas for defaults. (TypeError)\n----\n\nYou can use any primitive, custom object, etc. as a default despite the limited examples shown above.\n\nProcs _must_ be used when supplying complex objects as default values. _Avoid_ using parameters when using procs because only the source (body) of your proc will be used as a _literal_ string when building the method signature in order to ensure lazy evaluation.\n\nLastly, you can use anonymous splats/blocks by only supplying their kind. Example:\n\n[source,ruby]\n----\nputs Marameters.signature([[:rest], [:keyrest], [:block]])\n# \"*, **, \u0026\"\n----\n\nYou can supply `nil` as a second element (i.e. the name) for each kind but that is the equivalent of the above.\n\n==== Argument Forwarding\n\nUse `:all` for building a method signature with argument forwarding. Example:\n\n[source, ruby]\n----\nputs Marameters.signature(:all)\n# \"...\"\n----\n\nUse of `:all` is special in that you must _only_ supply `:all` with no other keys/values or you'll get an `ArgumentError`.\n\n💡 This is only provided for convenience and completeness. In truth, you're better off writing `my_method(+...+)`, for example, than using this class.\n\n==== Bare\n\nUse an empty array when you need a bare method signature. Example:\n\n[source,ruby]\n----\nputs Marameters.signature []\n# \"\"\n----\n\n💡 This is only provided for convenience and completeness. In truth, if you need a bare method, then you don't need to use this class.\n\n==== Inheritance\n\nObject/method inheritance is more complicated than building a signature for a single method because you need to blend the super and sub parameters as a unified set of parameters. Additionally, you have to account for the arguments that need to be forwarded to the super method via the `super` keyword. To aid in this endeavor, the following objects are available to help you build these more complex method parameters and arguments:\n\n* `Marameters::Signatures::Inheritor`: Blends super and sub parameters to produce a unified set of parameters you can turn into a method signature.\n* `Marameters::Signatures::Super`: Blends super and sub parameters to produce arguments for forwarding via the `super` keyword. _This does not support disabled block forwarding (i.e. `\u0026nil`) since there is no way to determine this from the super and sub parameters alone._\n\nHere's an example which incorporates both of the above:\n\n[source,ruby]\n----\nmodule Demo\n  def self.parent(one, two = 2, *three, \u0026block) = nil\nend\n\nsuper_parameters = Marameters.for Demo.method(:parent).parameters\n\nsub_parameters = Marameters.for [\n  [:opt, :two, 22],\n  %i[keyreq four],\n  [:key, :five, 5],\n  %i[keyrest six]\n]\n\ninheritor = Marameters::Signatures::Inheritor.new\nforwarder = Marameters::Signatures::Super.new\n\nputs Marameters.signature inheritor.call(super_parameters, sub_parameters)\n# \"one, two = 22, *three, four:, five: 5, **six, \u0026block\"\n\nputs forwarder.call(super_parameters, sub_parameters)\n# \"one, two, *three, \u0026block\"\n----\n\nAs you can see, the above combines the parameters of your super method with the parameters of your sub method in order to produce a method signature -- with no duplicates -- while ensuring you can forward all necessary parameters that the `super` keyword requires. Defaults, if given, will override previously defined defaults as is identical with standard object inheritance.\n\n== Development\n\nTo contribute, run:\n\n[source,bash]\n----\ngit clone https://github.com/bkuhlmann/marameters\ncd marameters\nbin/setup\n----\n\nYou can also use the IRB console for direct access to all objects:\n\n[source,bash]\n----\nbin/console\n----\n\n== Tests\n\nTo test, run:\n\n[source,bash]\n----\nbin/rake\n----\n\n== link:https://alchemists.io/policies/license[License]\n\n== link:https://alchemists.io/policies/security[Security]\n\n== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]\n\n== link:https://alchemists.io/policies/contributions[Contributions]\n\n== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]\n\n== link:https://alchemists.io/projects/marameters/versions[Versions]\n\n== link:https://alchemists.io/community[Community]\n\n== Credits\n\n* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].\n* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkuhlmann%2Fmarameters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkuhlmann%2Fmarameters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkuhlmann%2Fmarameters/lists"}