class Stannum::Contracts::ParametersContract::Builder

Builder class for defining item constraints for a ParametersContract.

This class should not be invoked directly. Instead, pass a block to the constructor for ParametersContract.

@api private

Public Instance Methods

argument(name, type = nil, index: nil, **options, &block) click to toggle source

Adds an argument constraint to the contract.

If the index is specified, then the constraint will be added for the argument at the specified index. If the index is not given, then the constraint will be applied to the next unconstrained argument. For example, the first argument constraint will be added for the argument at index 0, the second constraint for the argument at index 1, and so on.

@overload argument(name, type, index: nil, **options)

Generates an argument constraint based on the given type. If the type
is a constraint, then the given constraint will be copied with the
given options and added for the argument at the index. If the type is
a Class or a Module, then a Stannum::Constraints::Type constraint will
be created with the given type and options and added for the argument.

@param name [String, Symbol] The name of the argument.
@param type [Class, Module, Stannum::Constraints:Base] The expected
  type of the argument.
@param index [Integer, nil] The index of the argument. If not given,
  then the next argument will be constrained with the type.
@param options [Hash<Symbol, Object>] Configuration options for the
  constraint. Defaults to an empty Hash.

@return [Stannum::Contracts::ParametersContract::Builder] the builder.

@overload argument(name, index: nil, **options, &block

Generates a new Stannum::Constraint using the block.

@param name [String, Symbol] The name of the argument.
@param index [Integer, nil] The index of the argument. If not given,
  then the next argument will be constrained with the type.
@param options [Hash<Symbol, Object>] Configuration options for the
  constraint. Defaults to an empty Hash.

@yield The definition for the constraint. Each time #matches? is
  called for this constraint, the given object will be passed to this
  block and the result of the block will be returned.
@yieldparam actual [Object] The object to check against the
  constraint.
@yieldreturn [true, false] true if the given object matches the
  constraint, otherwise false.

@return [Stannum::Contracts::ParametersContract::Builder] the builder.
# File lib/stannum/contracts/parameters_contract.rb, line 233
def argument(name, type = nil, index: nil, **options, &block)
  type = resolve_constraint_or_type(type, **options, &block)

  contract.add_argument_constraint(
    index,
    type,
    property_name: name,
    **options
  )

  self
end
arguments(name, type) click to toggle source

Sets the variadic arguments constraint for the contract.

If the parameters includes variadic (or “splatted”) arguments, then each item in the variadic arguments array must match the given type or constraint. If the type is a constraint, then the given constraint will be copied with the given options. If the type is a Class or a Module, then a Stannum::Constraints::Type constraint will be created with the given type.

@param name [String, Symbol] a human-readable name for the variadic

arguments; used in generating error messages.

@param type [Class, Module, Stannum::Constraints:Base] The expected type

of the variadic arguments items.

@return [Stannum::Contracts::ParametersContract::Builder] the builder.

@raise [RuntimeError] if there is already a variadic arguments

constraint defined for the contract.
# File lib/stannum/contracts/parameters_contract.rb, line 264
def arguments(name, type)
  contract.set_arguments_item_constraint(name, type)

  self
end
block(present) click to toggle source

Sets the block parameter constraint for the contract.

If the expected presence is true, a block must be given as part of the parameters. If the expected presence is false, a block must not be given. If the presence is a constraint, then the block must match the constraint.

@param present [true, false, Stannum::Constraint] The expected presence

of the block.

@return [Stannum::Contracts::ParametersContract] the contract.

@raise [RuntimeError] if there is already a block constraint defined for

the contract.
# File lib/stannum/contracts/parameters_contract.rb, line 284
def block(present)
  contract.set_block_constraint(present)

  self
end
keyword(name, type = nil, **options, &block) click to toggle source

Adds a keyword constraint to the contract.

@overload keyword(name, type, **options)

Generates a keyword constraint based on the given type. If the type is
a constraint, then the given constraint will be copied with the given
options and added for the given keyword. If the type is a Class or a
Module, then a Stannum::Constraints::Type constraint will be created
with the given type and options and added for the keyword.

@param keyword [Symbol] The keyword to constrain.
@param type [Class, Module, Stannum::Constraints:Base] The expected
  type of the keyword.
@param options [Hash<Symbol, Object>] Configuration options for the
  constraint. Defaults to an empty Hash.

@return [Stannum::Contracts::ParametersContract::Builder] the builder.

@overload keyword(name, **options, &block)

Generates a new Stannum::Constraint using the block.

@param keyword [Symbol] The keyword to constrain.
@param options [Hash<Symbol, Object>] Configuration options for the
  constraint. Defaults to an empty Hash.

@yield The definition for the constraint. Each time #matches? is
  called for this constraint, the given object will be passed to this
  block and the result of the block will be returned.
@yieldparam actual [Object] The object to check against the
  constraint.
@yieldreturn [true, false] true if the given object matches the
  constraint, otherwise false.

@return [Stannum::Contracts::ParametersContract::Builder] the builder.
# File lib/stannum/contracts/parameters_contract.rb, line 323
def keyword(name, type = nil, **options, &block)
  type = resolve_constraint_or_type(type, **options, &block)

  contract.add_keyword_constraint(
    name,
    type,
    **options
  )

  self
end
keywords(name, type) click to toggle source

Sets the variadic keywords constraint for the contract.

If the parameters includes variadic (or “splatted”) keywords, then each value in the variadic keywords hash must match the given type or constraint. If the type is a constraint, then the given constraint will be copied with the given options. If the type is a Class or a Module, then a Stannum::Constraints::Type constraint will be created with the given type.

@param name [String, Symbol] a human-readable name for the variadic

keywords; used in generating error messages.

@param type [Class, Module, Stannum::Constraints:Base] The expected type

of the variadic keywords values.

@return [Stannum::Contracts::ParametersContract::Builder] the builder.

@raise [RuntimeError] if there is already a variadic keywords constraint

defined for the contract.
# File lib/stannum/contracts/parameters_contract.rb, line 353
def keywords(name, type)
  contract.set_keywords_value_constraint(name, type)

  self
end

Private Instance Methods

resolve_constraint_or_type(type = nil, **options, &block) click to toggle source
# File lib/stannum/contracts/parameters_contract.rb, line 361
def resolve_constraint_or_type(type = nil, **options, &block)
  if block_given? && type
    raise ArgumentError, ambiguous_values_error(type), caller(1..-1)
  end

  return type if type.is_a?(Module) || valid_constraint?(type)

  return Stannum::Constraint.new(**options, &block) if block

  raise ArgumentError,
    "invalid constraint #{type.inspect}",
    caller(1..-1)
end