Class: Toys::Acceptor::Base

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

Overview

Defined in the toys-core gem

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.



54
55
56
57
 
# File 'toys-core/lib/toys/acceptor.rb', line 54

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) 


63
64
65
 
# File 'toys-core/lib/toys/acceptor.rb', line 63

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



74
75
76
 
# File 'toys-core/lib/toys/acceptor.rb', line 74

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.



124
125
126
 
# File 'toys-core/lib/toys/acceptor.rb', line 124

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) 


106
107
108
 
# File 'toys-core/lib/toys/acceptor.rb', line 106

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



141
142
143
 
# File 'toys-core/lib/toys/acceptor.rb', line 141

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

#to_s ⇒ String

Type description string, shown in help.

Returns:

  • (String) 


80
81
82
 
# File 'toys-core/lib/toys/acceptor.rb', line 80

def to_s
  type_desc.to_s
end