toys 0.15.6 → 0.16.0

data/core-docs/toys/completion.rb

@@ -1,340 +0,0 @@
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # 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.
-  #
-  module Completion
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # The context in which to determine completion candidates.
-    #
-    class Context
-      ##
-      # Create a completion context
-      #
-      # @param cli [Toys::CLI] The CLI being run. Required.
-      # @param previous_words [Array<String>] Array of complete strings that
-      #     appeared prior to the fragment to complete.
-      # @param fragment_prefix [String] A prefix in the fragment that does not
-      #     participate in completion. (e.g. "key=")
-      # @param fragment [String] The string fragment to complete.
-      # @param params [Hash] Miscellaneous context data
-      #
-      def initialize(cli:, previous_words: [], fragment_prefix: "", fragment: "", **params)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Create a new completion context with the given modifications.
-      #
-      # @param delta_params [Hash] Replace context data.
-      # @return [Toys::Completion::Context]
-      #
-      def with(**delta_params)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # The CLI being run.
-      # @return [Toys::CLI]
-      #
-      attr_reader :cli
-
-      ##
-      # All previous words.
-      # @return [Array<String>]
-      #
-      attr_reader :previous_words
-
-      ##
-      # A non-completed prefix for the current fragment.
-      # @return [String]
-      #
-      attr_reader :fragment_prefix
-
-      ##
-      # The current string fragment to complete
-      # @return [String]
-      #
-      attr_reader :fragment
-
-      ##
-      # Get data for arbitrary key.
-      # @param [Symbol] key
-      # @return [Object]
-      #
-      def [](key)
-        # Source available in the toys-core gem
-      end
-      alias get []
-
-      ##
-      # The tool being invoked, which should control the completion.
-      # @return [Toys::ToolDefinition]
-      #
-      def tool
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # An array of complete arguments passed to the tool, prior to the
-      # fragment to complete.
-      # @return [Array<String>]
-      #
-      def args
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Current ArgParser indicating the status of argument parsing up to
-      # this point.
-      #
-      # @return [Toys::ArgParser]
-      #
-      def arg_parser
-        # Source available in the toys-core gem
-      end
-    end
-
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A candidate for completing a string fragment.
-    #
-    # A candidate includes a string representing the potential completed
-    # word, as well as a flag indicating whether it is a *partial* completion
-    # (i.e. a prefix that could still be added to) versus a *final* word.
-    # Generally, tab completion systems should add a trailing space after a
-    # final completion but not after a partial completion.
-    #
-    class Candidate
-      include ::Comparable
-
-      ##
-      # Create a new candidate
-      # @param string [String] The candidate string
-      # @param partial [Boolean] Whether the candidate is partial. Defaults
-      #     to `false`.
-      #
-      def initialize(string, partial: false)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Get the candidate string.
-      # @return [String]
-      #
-      attr_reader :string
-      alias to_s string
-
-      ##
-      # Determine whether the candidate is partial completion.
-      # @return [Boolean]
-      #
-      def partial?
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Determine whether the candidate is a final completion.
-      # @return [Boolean]
-      #
-      def final?
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Create an array of candidates given an array of strings.
-      #
-      # @param array [Array<String>]
-      # @return [Array<Toys::Completion::Candidate]
-      #
-      def self.new_multi(array, partial: false)
-        # Source available in the toys-core gem
-      end
-    end
-
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A base class that returns no completions.
-    #
-    # Completions *may* but do not need to subclass this base class. They
-    # merely need to duck-type `Proc` by implementing the `call` method.
-    #
-    class Base
-      ##
-      # Returns candidates for the current completion.
-      # This default implementation returns an empty list.
-      #
-      # @param context [Toys::Completion::Context] The current completion
-      #     context including the string fragment.
-      # @return [Array<Toys::Completion::Candidate>] An array of candidates
-      #
-      def call(context)
-        # Source available in the toys-core gem
-      end
-    end
-
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A Completion that returns candidates from the local file system.
-    #
-    class FileSystem < Base
-      ##
-      # Create a completion that gets candidates from names in the local file
-      # system.
-      #
-      # @param cwd [String] Working directory (defaults to the current dir).
-      # @param omit_files [Boolean] Omit files from candidates
-      # @param omit_directories [Boolean] Omit directories from candidates
-      # @param prefix_constraint [String,Regexp] Constraint on the fragment
-      #     prefix. Defaults to requiring the prefix be empty.
-      #
-      def initialize(cwd: nil, omit_files: false, omit_directories: false, prefix_constraint: "")
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Whether files are included in the completion candidates.
-      # @return [Boolean]
-      #
-      attr_reader :include_files
-
-      ##
-      # Whether directories are included in the completion candidates.
-      # @return [Boolean]
-      #
-      attr_reader :include_directories
-
-      ##
-      # Constraint on the fragment prefix.
-      # @return [String,Regexp]
-      #
-      attr_reader :prefix_constraint
-
-      ##
-      # Path to the starting directory.
-      # @return [String]
-      #
-      attr_reader :cwd
-
-      ##
-      # Returns candidates for the current completion.
-      #
-      # @param context [Toys::Completion::Context] the current completion
-      #     context including the string fragment.
-      # @return [Array<Toys::Completion::Candidate>] an array of candidates
-      #
-      def call(context)
-        # Source available in the toys-core gem
-      end
-    end
-
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A Completion whose candidates come from a static list of strings.
-    #
-    class Enum < Base
-      ##
-      # Create a completion from a list of values.
-      #
-      # @param values [Array<String>]
-      # @param prefix_constraint [String,Regexp] Constraint on the fragment
-      #     prefix. Defaults to requiring the prefix be empty.
-      #
-      def initialize(values, prefix_constraint: "")
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # The array of completion candidates.
-      # @return [Array<String>]
-      #
-      attr_reader :values
-
-      ##
-      # Constraint on the fragment prefix.
-      # @return [String,Regexp]
-      #
-      attr_reader :prefix_constraint
-
-      ##
-      # Returns candidates for the current completion.
-      #
-      # @param context [Toys::Completion::Context] the current completion
-      #     context including the string fragment.
-      # @return [Array<Toys::Completion::Candidate>] an array of candidates
-      #
-      def call(context)
-        # Source available in the toys-core gem
-      end
-    end
-
-    ##
-    # An instance of the empty completion that returns no candidates.
-    # @return [Toys:::Completion::Base]
-    #
-    EMPTY = Base.new
-
-    ##
-    # 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]
-    #
-    def self.create(spec = nil, **options, &block)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Take the various ways to express a completion spec, and convert them to a
-    # canonical form expressed as a single object. This is called from the DSL
-    # DSL to generate a spec object that can be stored.
-    #
-    # @private This interface is internal and subject to change without warning.
-    #
-    def self.scalarize_spec(spec, options, block)
-      # Source available in the toys-core gem
-    end
-  end
-end