Module magnus::scan_args

Types and functions for complex method arguments.

Ruby’s APIs to define methods, exposed in magnus through functions such as define_method and the method macro, allow defining methods with a fixed number of positional arguments, or an unbounded collection of arguments as a slice or Ruby array. The functions in this module allow for more complex agument handling.

Ruby arguments can be classified as follows:

def example(a, b, c=nil, d=nil, *rest, e, f, g:, h:, i: nil, j: nil, **kwargs, &block)
            \__/  \__________/  \___/  \__/  \____/  \____________/  \______/  \____/
              |        |          |      |     |            |           |        |
           required    |        splat    |  keywords     keywords    keywords  block
                    optional             | (required)   (optional)   (splat)
                                         |
                                      trailing
                                      required

The scan_args function can be used with a method defined as method!(name, -1) (i.e. receiving a slice of arguments) to implement this more complex functionality.

The get_kwargs function is used to extract keywords from a Ruby Hash of keywords and implement the behaviour around required and optional keyword arguments.

Structs

Args

Arguments returned from scan_args.

KwArgs

Arguments returned from get_kwargs.

Traits

ScanArgsBlock

Trait implemented for types that can be retrieved as a block argument by scan_args.

ScanArgsKw

Trait implemented for types that can be retrieved as keyword arguments by scan_args.

ScanArgsOpt

Trait implemented for types that can be retrieved as optional arguments by scan_args.

ScanArgsRequired

Trait implemented for types that can be retrieved as required arguments by scan_args.

ScanArgsSplat

Trait implemented for types that can be retrieved a ‘splat’ argument by scan_args.

Functions

check_arity

Returns Err containing a Ruby ArgumentError if len is not within bounds.

get_kwargs

Deconstruct keyword arguments.

scan_args

Retrieves arguments from a slice.