toys 0.17.1 → 0.17.2

data/core-docs/toys/completion.rb

@@ -0,0 +1,340 @@
+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

data/core-docs/toys/context.rb

@@ -0,0 +1,386 @@
+module Toys
+  ##
+  # **_Defined in the toys-core gem_**
+  #
+  # This is the base class for tool execution. It represents `self` when your
+  # tool's methods (such as `run`) are called, and it defines the methods that
+  # can be called by your tool (such as {#logger} and {#exit}.)
+  #
+  # This class also manages the "data" available to your tool when it runs.
+  # This data is a hash of key-value pairs. It consists of values set by flags
+  # and arguments defined by the tool, plus some "well-known" values such as
+  # the logger and verbosity level.
+  #
+  # You can obtain a value from the data using the {Toys::Context#get} method.
+  # Additionally, convenience methods are provided for many of the well-known
+  # keys. For instance, you can call {Toys::Context#verbosity} to obtain the
+  # value for the key {Toys::Context::Key::VERBOSITY}. Finally, flags and
+  # positional arguments that store their data here will also typically
+  # generate convenience methods. For example, an argument with key `:abc` will
+  # add a method called `abc` that you can call to get the value.
+  #
+  # By convention, flags and arguments defined by your tool should use strings
+  # or symbols as keys. Keys that are not strings or symbols should either be
+  # well-known keys such as {Toys::Context::Key::VERBOSITY}, or should be used
+  # for internal private information needed by middleware and mixins. The
+  # module {Toys::Context::Key} defines a number of well-known keys as
+  # constants.
+  #
+  class Context
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # Well-known context keys.
+    #
+    # This module is mixed into the runtime context. This means you can
+    # reference any of these constants directly from your run method.
+    #
+    # ### Example
+    #
+    #     tool "my-name" do
+    #       def run
+    #         # TOOL_NAME is available here.
+    #         puts "My name is #{get(TOOL_NAME)}"
+    #       end
+    #     end
+    #
+    module Key
+      ##
+      # Context key for the argument list passed to the current tool. Value is
+      # an array of strings.
+      # @return [Object]
+      #
+      ARGS = ::Object.new.freeze
+
+      ##
+      # Context key for the currently running {Toys::CLI}. You can use the
+      # value to run other tools from your tool by calling {Toys::CLI#run}.
+      # @return [Object]
+      #
+      CLI = ::Object.new.freeze
+
+      ##
+      # Context key for the context directory path. The value is a string
+      # @return [Object]
+      #
+      CONTEXT_DIRECTORY = ::Object.new.freeze
+
+      ##
+      # Context key for the context from which the current call was delegated.
+      # The value is either another context object, or `nil` if the current
+      # call is not delegated.
+      # @return [Object]
+      #
+      DELEGATED_FROM = ::Object.new.freeze
+
+      ##
+      # Context key for the active `Logger` object.
+      # @return [Object]
+      #
+      LOGGER = ::Object.new.freeze
+
+      ##
+      # Context key for the {Toys::ToolDefinition} object being executed.
+      # @return [Object]
+      #
+      TOOL = ::Object.new.freeze
+
+      ##
+      # Context key for the full name of the tool being executed. Value is an
+      # array of strings.
+      # @return [Object]
+      #
+      TOOL_NAME = ::Object.new.freeze
+
+      ##
+      # Context key for the {Toys::SourceInfo} describing the source of this
+      # tool.
+      # @return [Object]
+      #
+      TOOL_SOURCE = ::Object.new.freeze
+
+      ##
+      # Context key for all unmatched args in order. The value is an array of
+      # strings.
+      # @return [Object]
+      #
+      UNMATCHED_ARGS = ::Object.new.freeze
+
+      ##
+      # Context key for unmatched flags. The value is an array of strings.
+      # @return [Object]
+      #
+      UNMATCHED_FLAGS = ::Object.new.freeze
+
+      ##
+      # Context key for unmatched positional args. The value is an array of
+      # strings.
+      # @return [Object]
+      #
+      UNMATCHED_POSITIONAL = ::Object.new.freeze
+
+      ##
+      # Context key for the list of usage errors raised. The value is an array
+      # of {Toys::ArgParser::UsageError}.
+      # @return [Object]
+      #
+      USAGE_ERRORS = ::Object.new.freeze
+
+      ##
+      # Context key for the verbosity value. The value is an integer defaulting
+      # to 0, with higher values meaning more verbose and lower meaning more
+      # quiet.
+      # @return [Object]
+      #
+      VERBOSITY = ::Object.new.freeze
+    end
+
+    ##
+    # The raw arguments passed to the tool, as an array of strings.
+    # This does not include the tool name itself.
+    #
+    # This is a convenience getter for {Toys::Context::Key::ARGS}.
+    #
+    # If the `args` method is overridden by the tool, you can still access it
+    # using the name `__args`.
+    #
+    # @return [Array<String>]
+    #
+    def args
+      # Source available in the toys-core gem
+    end
+    alias __args args
+
+    ##
+    # The currently running CLI.
+    #
+    # This is a convenience getter for {Toys::Context::Key::CLI}.
+    #
+    # If the `cli` method is overridden by the tool, you can still access it
+    # using the name `__cli`.
+    #
+    # @return [Toys::CLI]
+    #
+    def cli
+      # Source available in the toys-core gem
+    end
+    alias __cli cli
+
+    ##
+    # Return the context directory for this tool. Generally, this defaults
+    # to the directory containing the toys config directory structure being
+    # read, but it may be changed by setting a different context directory
+    # for the tool.
+    #
+    # This is a convenience getter for {Toys::Context::Key::CONTEXT_DIRECTORY}.
+    #
+    # If the `context_directory` method is overridden by the tool, you can
+    # still access it using the name `__context_directory`.
+    #
+    # @return [String] Context directory path
+    # @return [nil] if there is no context.
+    #
+    def context_directory
+      # Source available in the toys-core gem
+    end
+    alias __context_directory context_directory
+
+    ##
+    # The logger for this execution.
+    #
+    # This is a convenience getter for {Toys::Context::Key::LOGGER}.
+    #
+    # If the `logger` method is overridden by the tool, you can still access it
+    # using the name `__logger`.
+    #
+    # @return [Logger]
+    #
+    def logger
+      # Source available in the toys-core gem
+    end
+    alias __logger logger
+
+    ##
+    # The full name of the tool being executed, as an array of strings.
+    #
+    # This is a convenience getter for {Toys::Context::Key::TOOL_NAME}.
+    #
+    # If the `tool_name` method is overridden by the tool, you can still access
+    # it using the name `__tool_name`.
+    #
+    # @return [Array<String>]
+    #
+    def tool_name
+      # Source available in the toys-core gem
+    end
+    alias __tool_name tool_name
+
+    ##
+    # The source of the tool being executed.
+    #
+    # This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
+    #
+    # If the `tool_source` method is overridden by the tool, you can still
+    # access it using the name `__tool_source`.
+    #
+    # @return [Toys::SourceInfo]
+    #
+    def tool_source
+      # Source available in the toys-core gem
+    end
+    alias __tool_source tool_source
+
+    ##
+    # The (possibly empty) array of errors detected during argument parsing.
+    #
+    # This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
+    #
+    # If the `usage_errors` method is overridden by the tool, you can still
+    # access it using the name `__usage_errors`.
+    #
+    # @return [Array<Toys::ArgParser::UsageError>]
+    #
+    def usage_errors
+      # Source available in the toys-core gem
+    end
+    alias __usage_errors usage_errors
+
+    ##
+    # The current verbosity setting as an integer.
+    #
+    # This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
+    #
+    # If the `verbosity` method is overridden by the tool, you can still access
+    # it using the name `__verbosity`.
+    #
+    # @return [Integer]
+    #
+    def verbosity
+      # Source available in the toys-core gem
+    end
+    alias __verbosity verbosity
+
+    ##
+    # Fetch an option or other piece of data by key.
+    #
+    # If the `get` method is overridden by the tool, you can still access it
+    # using the name `__get` or the `[]` operator.
+    #
+    # @param key [Symbol]
+    # @return [Object]
+    #
+    def [](key)
+      # Source available in the toys-core gem
+    end
+    alias get []
+    alias __get []
+
+    ##
+    # Set an option or other piece of context data by key.
+    #
+    # @param key [Symbol]
+    # @param value [Object]
+    #
+    def []=(key, value)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Set one or more options or other context data by key.
+    #
+    # If the `set` method is overridden by the tool, you can still access it
+    # using the name `__set`.
+    #
+    # @return [self]
+    #
+    # @overload set(key, value)
+    #   Set an option or other piece of context data by key.
+    #   @param key [Symbol]
+    #   @param value [Object]
+    #   @return [self]
+    #
+    # @overload set(hash)
+    #   Set multiple content data keys and values
+    #   @param hash [Hash] The keys and values to set
+    #   @return [self]
+    #
+    def set(key, value = nil)
+      # Source available in the toys-core gem
+    end
+    alias __set set
+
+    ##
+    # The subset of the context that uses string or symbol keys. By convention,
+    # this includes keys that are set by tool flags and arguments, but does not
+    # include well-known context values such as verbosity or private context
+    # values used by middleware or mixins.
+    #
+    # If the `options` method is overridden by the tool, you can still access
+    # it using the name `__options`.
+    #
+    # @return [Hash]
+    #
+    def options
+      # Source available in the toys-core gem
+    end
+    alias __options options
+
+    ##
+    # Find the given data file or directory in this tool's search path.
+    #
+    # If the `find_data` method is overridden by the tool, you can still access
+    # it using the name `__find_data`.
+    #
+    # @param path [String] The path to find
+    # @param type [nil,:file,:directory] Type of file system object to find,
+    #     or nil to return any type.
+    #
+    # @return [String] Absolute path of the result
+    # @return [nil] if the data was not found.
+    #
+    def find_data(path, type: nil)
+      # Source available in the toys-core gem
+    end
+    alias __find_data find_data
+
+    ##
+    # Exit immediately with the given status code.
+    #
+    # If the `exit` method is overridden by the tool, you can still access it
+    # using the name `__exit` or by calling {Context.exit}.
+    #
+    # @param code [Integer] The status code, which should be 0 for no error,
+    #     or nonzero for an error condition. Default is 0.
+    # @return [void]
+    #
+    def exit(code = 0)
+      # Source available in the toys-core gem
+    end
+    alias __exit exit
+
+    ##
+    # Exit immediately with the given status code. This class method can be
+    # called if the instance method is or could be replaced by the tool.
+    #
+    # @param code [Integer] The status code, which should be 0 for no error,
+    #     or nonzero for an error condition. Default is 0.
+    # @return [void]
+    #
+    def self.exit(code = 0)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Create a Context object. Applications generally will not need to create
+    # these objects directly; they are created by the tool when it is preparing
+    # for execution.
+    #
+    # @param data [Hash]
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def initialize(data)
+      # Source available in the toys-core gem
+    end
+  end
+end