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(spec = nil, **options, &block) click to toggle source

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
scalarize_spec(spec, options, block) click to toggle source

@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