module Toys::Completion
A Completion
is a callable Proc that determines candidates for shell tab completion. You pass a {Toys::Completion::Context} object (which includes the current string fragment and other information) and it returns an array of candidates, represented by {Toys::Completion::Candidate} objects, for completing the fragment.
A useful method here is the class method {Toys::Completion.create} which takes a variety of inputs and returns a suitable completion Proc.
Constants
- EMPTY
An instance of the empty completion that returns no candidates. @return [Toys:::Completion::Base]
Public Class Methods
Create a completion Proc from a variety of specification formats. The completion is constructed from the given specification object and/or the given block. Additionally, some completions can take a hash of options.
Recognized specs include:
* `:empty`: Returns the empty completion. Any block or options are ignored. * `:file_system`: Returns a completion that searches the current directory for file and directory names. You may also pass any of the options recognized by {Toys::Completion::FileSystem#initialize}. The block is ignored. * An **Array** of strings. Returns a completion that uses those values as candidates. You may also pass any of the options recognized by {Toys::Completion::Enum#initialize}. The block is ignored. * A **function**, either passed as a Proc (where the block is ignored) or as a block (if the spec is nil). The function must behave as a completion object, taking {Toys::Completion::Context} as the sole argument, and returning an array of {Toys::Completion::Candidate}. * `:default` and `nil` indicate the **default completion**. For this method, the default is the empty completion (i.e. these are synonyms for `:empty`). However, other completion resolution methods might have a different default.
@param spec [Object] See the description for recognized values. @param options [Hash] Additional options to pass to the completion. @param block [Proc] See the description for recognized forms. @return [Toys::Completion::Base,Proc]
# File lib/toys/completion.rb, line 403 def self.create(spec = nil, **options, &block) if spec.is_a?(::Hash) options = options.merge(spec) spec = nil end spec ||= options.delete(:"") || block case spec when nil, :empty, :default EMPTY when ::Proc, Base spec when ::Array Enum.new(spec, **options) when :file_system FileSystem.new(**options) when ::Class spec.new(**options) else if spec.respond_to?(:call) spec else raise ToolDefinitionError, "Illegal completion spec: #{spec.inspect}" end end end
@private
# File lib/toys/completion.rb, line 430 def self.scalarize_spec(spec, options, block) spec ||= block if options.empty? spec elsif spec options.merge({"": spec}) else options end end