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) —

    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.



118
119
120
 
# File 'lib/toys/acceptor.rb', line 118

def convert(str, *extra) # rubocop:disable Lint/UnusedMethodArgument
  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 can 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) —

    The input argument string.

Returns:

  • (String, Array, nil) 


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

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



135
136
137
 
# File 'lib/toys/acceptor.rb', line 135

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