Class: Toys::Definition::Acceptor

Inherits:
Object
  • Object
show all
Defined in:
lib/toys/definition/acceptor.rb

Overview

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

First, an acceptor validates an argument via the #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 from the input string to its final form via the #convert method.

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

Direct Known Subclasses

EnumAcceptor, PatternAcceptor

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, converter = nil, &block) ⇒ Acceptor

Create a base acceptor.

The base acceptor does not do any validation (i.e. it accepts all arguments). You may subclass this object and override the #match method to change this behavior.

The base acceptor lets you provide a converter as a proc. The proc should take one or more arguments, the first of which is the entire argument string, and the others of which are any additional values returned from validation. The converter should return the final converted value of the argument.

The converter may be provided either as a proc in the converter parameter, or as a block. If neither is provided, the base acceptor performs no conversion and uses the argument string.

Parameters:

  • name (String) —

    A visible name for the acceptor, shown in help.

  • converter (Proc) (defaults to: nil) —

    A converter function. May also be given as a block.



70
71
72
73
 
# File 'lib/toys/definition/acceptor.rb', line 70

def initialize(name, converter = nil, &block)
  @name = name.to_s
  @converter = converter || block
end

Instance Attribute Details

#name ⇒ String (readonly) Also known as: to_s

Name of the acceptor

Returns:

  • (String) 


79
80
81
 
# File 'lib/toys/definition/acceptor.rb', line 79

def name
  @name
end

Instance Method Details

#convert(str, *extra) ⇒ Object

Convert the given input. Uses the converter provided to this object's constructor. Subclasses may also override this method.

Parameters:

  • str (String) —

    Original argument string

  • extra (Object...) —

    Zero or more additional arguments comprising additional elements returned from the match function.

Returns:

  • (Object) —

    The converted argument as it should be stored in the context data.



115
116
117
 
# File 'lib/toys/definition/acceptor.rb', line 115

def convert(str, *extra)
  @converter ? @converter.call(str, *extra) : str
end

#match(str) ⇒ String, Array

Validate the given input.

You may override this method to specify a validation function. For a valid input, the function must return either the original argument string, or an array of which the first element is the original argument string, and the remaining elements may comprise additional information. All returned information is then passed to the conversion function. Note that a MatchInfo object is a legitimate return value since it duck-types the appropriate array.

For an invalid input, you should return a falsy value.

The default implementation simply returns the original argument string, indicating all inputs are valid.

Parameters:

  • str (String) —

    Input argument string

Returns:

  • (String, Array) 


101
102
103
 
# File 'lib/toys/definition/acceptor.rb', line 101

def match(str)
  str
end