Class: Toys::Acceptor::Base

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

Overview

A base class for acceptors.

The base acceptor does not do any validation (i.e. it accepts all arguments) or conversion (i.e. it returns the original string). You can subclass this base class and override the #match and #convert methods to implement an acceptor.

Direct Known Subclasses

Enum, Pattern, Simple

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(type_desc: nil, well_known_spec: nil) ⇒ Base

Create a base acceptor.

Parameters:

  • type_desc (String) (defaults to: nil) —

    Type description string, shown in help. Defaults to DEFAULT_TYPE_DESC.

  • well_known_spec (Object) (defaults to: nil) —

    The well-known acceptor spec associated with this acceptor, or nil for none.



50
51
52
53
 
# File 'lib/toys/acceptor.rb', line 50

def initialize(type_desc: nil, well_known_spec: nil)
  @type_desc = type_desc || DEFAULT_TYPE_DESC
  @well_known_spec = well_known_spec
end

Instance Attribute Details

#type_desc ⇒ String (readonly)

Type description string, shown in help.

Returns:

  • (String) 


59
60
61
 
# File 'lib/toys/acceptor.rb', line 59

def type_desc
  @type_desc
end

#well_known_spec ⇒ Object? (readonly)

The well-known acceptor spec associated with this acceptor, if any. This generally identifies an OptionParser-compatible acceptor spec. For example, the acceptor object that corresponds to Integer will return Integer from this attribute.

Returns:

  • (Object) —

    the well-known acceptor

  • (nil) —

    if there is no corresponding well-known acceptor



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

def well_known_spec
  @well_known_spec
end

Instance Method Details

#convert(str, *extra) ⇒ Object

Convert the given input.

This method is passed the results of a successful match, including the original input string and any other values returned from #match. It must return the final converted value to use.

Parameters:

  • str (String, nil) —

    Original argument string. May be nil if the value is optional and not provided.

  • 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.



120
121
122
 
# File 'lib/toys/acceptor.rb', line 120

def convert(str, *extra) # rubocop:disable Lint/UnusedMethodArgument
  str.nil? ? true : str
end

#match(str) ⇒ String, ...

Validate the given input.

When given a valid input, return an array in which the first element is the original input string, and the remaining elements (which may be empty) comprise any additional information that may be useful during conversion. If there is no additional information, you may return the original input string by itself without wrapping in an array.

When given an invalid input, return a falsy value such as nil.

Note that a MatchData object is a legitimate return value because it duck-types the appropriate array.

This default implementation simply returns the original input string, as the only array element, indicating all inputs are valid. You can override this method to provide a different validation function.

Parameters:

  • str (String, nil) —

    The input argument string. May be nil if the value is optional and not provided.

Returns:

  • (String, Array, nil) 


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

def match(str)
  [str]
end

#suggestions(str) ⇒ Array<String>

Return suggestions for a given non-matching string.

This method may be called when a match fails. It should return a (possibly empty) array of suggestions that could be displayed to the user as "did you mean..."

The default implementation returns the empty list.

Parameters:

  • str (String) —

    A string that failed matching.

Returns:

  • (Array<String>) —

    A possibly empty array of alternative suggestions that could be displayed with "did you mean..."



137
138
139
 
# File 'lib/toys/acceptor.rb', line 137

def suggestions(str) # rubocop:disable Lint/UnusedMethodArgument
  []
end

#to_s ⇒ String

Type description string, shown in help.

Returns:

  • (String) 


76
77
78
 
# File 'lib/toys/acceptor.rb', line 76

def to_s
  type_desc.to_s
end