Module: Toys::Acceptor

Defined in:: lib/toys/acceptor.rb

Overview

An Acceptor validates and converts arguments. It is designed to be compatible with the OptionParser accept mechanism.

First, an acceptor validates the argument via its Base#match method. This method should determine whether the argument is valid, and return information that will help with conversion of the argument.

Second, an acceptor converts the argument to its final form via the Base#convert method.

Finally, an acceptor has a name that may appear in help text for flags and arguments that use it.

Defined Under Namespace

Classes: Base, Enum, Pattern, Range, Simple

Constant Summary collapse

REJECT = A sentinel that may be returned from a function-based acceptor to indicate invalid input. Returns: (Object)

::Object.new.freeze

DEFAULT_TYPE_DESC = The default type description. Returns: (String)

"string"

DEFAULT = The default acceptor. Corresponds to the well-known acceptor for Object. Returns: (Toys::Acceptor::Base)

Base.new(type_desc: "string", well_known_spec: ::Object)

INTEGER_CONVERTER = A converter proc that handles integers. Useful in Simple and Range acceptors. Returns: (Proc)

proc { |s| s.nil? ? nil : Integer(s) }

FLOAT_CONVERTER = A converter proc that handles floats. Useful in Simple and Range acceptors. Returns: (Proc)

proc { |s| s.nil? ? nil : Float(s) }

RATIONAL_CONVERTER = A converter proc that handles rationals. Useful in Simple and Range acceptors. Returns: (Proc)

proc { |s| s.nil? ? nil : Rational(s) }

NUMERIC_CONVERTER = A converter proc that handles any numeric value. Useful in Simple and Range acceptors. Returns: (Proc)

proc do |s|
  if s.nil?
    nil
  elsif s.include?("/")
    Rational(s)
  elsif s.include?(".") || (s.include?("e") && s !~ /\A-?0x/)
    Float(s)
  else
    Integer(s)
  end
end

Class Method Summary collapse

.create(spec = nil, **options, &block) ⇒ Toys::Acceptor::Base, Proc
Create an acceptor from a variety of specification formats.
.lookup_well_known(spec) ⇒ Toys::Acceptor::Base^?
Lookup a standard acceptor name recognized by OptionParser.

Class Method Details

.create(spec = nil, **options, &block) ⇒ `Toys::Acceptor::Base`, `Proc`

Create an acceptor from a variety of specification formats. The acceptor is constructed from the given specification object and/or the given block. Additionally, some acceptors can take an optional type description string used to describe the type of data in online help.

Recognized specs include:

Any well-known acceptor recognized by OptionParser, such as Integer, Array, or OptionParser::DecimalInteger. Any block and type description you provide are ignored.
Any regular expression. The returned acceptor validates only if the regex matches the entire string parameter.

You can also provide an optional conversion function as a block. If provided, the block must take a variable number of arguments, the first being the matched string and the remainder being the captures from the regular expression. It should return the converted object that will be stored in the context data. If you do not provide a block, no conversion takes place, and the original string is used.
An array of possible values. The acceptor validates if the string parameter matches the string form of one of the array elements (i.e. the results of calling to_s on the element.)

An array acceptor automatically converts the string parameter to the actual array element that it matched. For example, if the symbol :foo is in the array, it will match the string "foo", and then store the symbol :foo in the tool data. You may not further customize the conversion function; any block is ignored.
A range of possible values. The acceptor validates if the string parameter, after conversion to the range type, lies within the range. The final value stored in context data is the converted value. For numeric ranges, conversion is provided, but if the range has a different type, you must provide the conversion function as a block.
A function as a Proc (where the block is ignored) or a block (if the spec is nil). This function performs both validation and conversion. It should take the string parameter as its argument, and it must either return the object that should be stored in the tool data, or raise an exception (descended from StandardError) to indicate that the string parameter is invalid. You may also return the sentinel value REJECT to indicate that the string is invalid.
The value nil or :default with no block, to indicate the default pass-through acceptor DEFAULT. Any type description you provide is ignored.

Additional options:

:type_desc (String) The type description for interpolating into help text. Ignored if the spec indicates the default acceptor or a well-known acceptor.

Parameters:

spec (Object) (defaults to: nil) —
See the description for recognized values.
options (Hash) —
Additional options to pass to the acceptor.
block (Proc) —
See the description for recognized forms.

Returns:

(Toys::Acceptor::Base, Proc)

# File 'lib/toys/acceptor.rb', line 512

def create(spec = nil, **options, &block)
  well_known = lookup_well_known(spec)
  return well_known if well_known
  if spec.is_a?(::Hash)
    options = options.merge(spec)
    spec = nil
  end
  spec ||= options.delete(:"")
  internal_create(spec, options, block)
end

.lookup_well_known(spec) ⇒ `Toys::Acceptor::Base`^?

Lookup a standard acceptor name recognized by OptionParser.