toys 0.15.6 → 0.16.0

data/core-docs/toys/utils/xdg.rb

@@ -1,253 +0,0 @@
-module Toys
-  module Utils
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A class that provides tools for working with the XDG Base Directory
-    # Specification.
-    #
-    # This class provides utility methods that locate base directories and
-    # search paths for application state, configuration, caches, and other
-    # data, according to the [XDG Base Directory Spec version
-    # 0.8](https://specifications.freedesktop.org/basedir-spec/0.8/).
-    #
-    # Tools can use the `:xdg` mixin for convenient access to this class.
-    #
-    # ### Example
-    #
-    #     require "toys/utils/xdg"
-    #
-    #     xdg = Toys::Utils::XDG.new
-    #
-    #     # Get config file paths, in order from most to least inportant
-    #     config_files = xdg.lookup_config("my-config.toml")
-    #     config_files.each { |path| read_my_config(path) }
-    #
-    # ### Windows operation
-    #
-    # The Spec assumes a unix-like environment, and cannot be applied directly
-    # to Windows without modification. In general, this class will function on
-    # Windows, but with the following caveats:
-    #
-    #  *   All file paths must use Windows-style absolute paths, beginning with
-    #      the drive letter.
-    #  *   Environment variables that can contain multiple paths (`XDG_*_DIRS`)
-    #      use the Windows path delimiter (`;`) rather than the unix path
-    #      delimiter (`:`).
-    #  *   Defaults for home directories (`XDG_*_HOME`) will follow unix
-    #      conventions, using subdirectories under the user's profile directory
-    #      rather than the Windows known folder paths.
-    #  *   Defaults for search paths (`XDG_*_DIRS`) will be empty and will not
-    #      use the Windows known folder paths.
-    #
-    class XDG
-      ##
-      # Create an instance of XDG.
-      #
-      # @param env [Hash{String=>String}] the environment variables. Normally,
-      #     you can omit this argument, as it will default to `::ENV`.
-      #
-      def initialize(env: ::ENV)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to the current user's home directory.
-      #
-      # @return [String]
-      #
-      def home_dir
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to the single base directory relative to
-      # which user-specific data files should be written.
-      # Corresponds to the value of the `$XDG_DATA_HOME` environment variable
-      # and its defaults according to the XDG Base Directory Spec.
-      #
-      # @return [String]
-      #
-      def data_home
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to the single base directory relative to
-      # which user-specific configuration files should be written.
-      # Corresponds to the value of the `$XDG_CONFIG_HOME` environment variable
-      # and its defaults according to the XDG Base Directory Spec.
-      #
-      # @return [String]
-      #
-      def config_home
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to the single base directory relative to
-      # which user-specific state files should be written.
-      # Corresponds to the value of the `$XDG_STATE_HOME` environment variable
-      # and its defaults according to the XDG Base Directory Spec.
-      #
-      # @return [String]
-      #
-      def state_home
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to the single base directory relative to
-      # which user-specific non-essential (cached) data should be written.
-      # Corresponds to the value of the `$XDG_CACHE_HOME` environment variable
-      # and its defaults according to the XDG Base Directory Spec.
-      #
-      # @return [String]
-      #
-      def cache_home
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to the single base directory relative to
-      # which user-specific executable files may be written.
-      # Returns the value of `$HOME/.local/bin` as specified by the XDG Base
-      # Directory Spec.
-      #
-      # @return [String]
-      #
-      def executable_home
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the set of preference ordered base directories relative to
-      # which data files should be searched, as an array of absolute paths.
-      # The array is ordered from most to least important, and does _not_
-      # include the data home directory.
-      # Corresponds to the value of the `$XDG_DATA_DIRS` environment variable
-      # and its defaults according to the XDG Base Directory Spec.
-      #
-      # @return [Array<String>]
-      #
-      def data_dirs
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the set of preference ordered base directories relative to
-      # which configuration files should be searched, as an array of absolute
-      # paths. The array is ordered from most to least important, and does
-      # _not_ include the config home directory.
-      # Corresponds to the value of the `$XDG_CONFIG_DIRS` environment variable
-      # and its defaults according to the XDG Base Directory Spec.
-      #
-      # @return [Array<String>]
-      #
-      def config_dirs
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to the single base directory relative to
-      # which user-specific runtime files and other file objects should be
-      # placed. May return `nil` if no such directory could be determined.
-      #
-      # @return [String,nil]
-      #
-      def runtime_dir
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Searches the data directories for an object with the given relative
-      # path, and returns an array of absolute paths to all objects found in
-      # the data directories (i.e. in {#data_dirs} or {#data_home}), in order
-      # from most to least important.
-      #
-      # @param path [String] Relative path of the object to search for
-      # @param type [String,Symbol,Array<String,Symbol>] The type(s) of objects
-      #     to find. You can specify any of the types defined by
-      #     [File::Stat#ftype](https://ruby-doc.org/core/File/Stat.html#method-i-ftype),
-      #     such as `file` or `directory`, or the special type `any`. Types can
-      #     be specified as strings or the  corresponding symbols. If this
-      #     argument is not provided, the default of `file` is used.
-      # @return [Array<String>]
-      #
-      def lookup_data(path, type: :file)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Searches the config directories for an object with the given relative
-      # path, and returns an array of absolute paths to all objects found in
-      # the config directories (i.e. in {#config_dirs} or {#config_home}), in
-      # order from most to least important.
-      #
-      # @param path [String] Relative path of the object to search for
-      # @param type [String,Symbol,Array<String,Symbol>] The type(s) of objects
-      #     to find. You can specify any of the types defined by
-      #     [File::Stat#ftype](https://ruby-doc.org/core/File/Stat.html#method-i-ftype),
-      #     such as `file` or `directory`, or the special type `any`. Types can
-      #     be specified as strings or the  corresponding symbols. If this
-      #     argument is not provided, the default of `file` is used.
-      # @return [Array<String>]
-      #
-      def lookup_config(path, type: :file)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to a directory under {#data_home}, creating
-      # it if it doesn't already exist.
-      #
-      # @param path [String] The relative path to the subdir within the base
-      #     data directory.
-      # @return [String] The absolute path to the subdir.
-      # @raise [Errno::EEXIST] If a non-directory already exists there
-      #
-      def ensure_data_subdir(path)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to a directory under {#config_home}, creating
-      # it if it doesn't already exist.
-      #
-      # @param path [String] The relative path to the subdir within the base
-      #     config directory.
-      # @return [String] The absolute path to the subdir.
-      # @raise [Errno::EEXIST] If a non-directory already exists there
-      #
-      def ensure_config_subdir(path)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to a directory under {#state_home}, creating
-      # it if it doesn't already exist.
-      #
-      # @param path [String] The relative path to the subdir within the base
-      #     state directory.
-      # @return [String] The absolute path to the subdir.
-      # @raise [Errno::EEXIST] If a non-directory already exists there
-      #
-      def ensure_state_subdir(path)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns the absolute path to a directory under {#cache_home}, creating
-      # it if it doesn't already exist.
-      #
-      # @param path [String] The relative path to the subdir within the base
-      #     cache directory.
-      # @return [String] The absolute path to the subdir.
-      # @raise [Errno::EEXIST] If a non-directory already exists there
-      #
-      def ensure_cache_subdir(path)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

data/core-docs/toys/wrappable_string.rb

@@ -1,132 +0,0 @@
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # A string intended for word-wrapped display.
-  #
-  # A WrappableString is an array of string "fragments" representing the atomic
-  # units that should not be split when word-wrapping. It should be possible to
-  # reconstruct the original string by joining these fragments with whitespace.
-  #
-  class WrappableString
-    ##
-    # Create a wrapped string.
-    #
-    # You can pass either:
-    #
-    #  *  A single String, which will be split into fragments by whitespace.
-    #  *  An array of Strings representing the fragments explicitly.
-    #
-    # @param string [String,Array<String>] The string or array of string
-    #     fragments
-    #
-    def initialize(string = "")
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Returns the string fragments, i.e. the individual "words" for wrapping.
-    #
-    # @return [Array<String>]
-    #
-    attr_reader :fragments
-
-    ##
-    # Returns a new WrappaableString whose content is the concatenation of this
-    # WrappableString with another WrappableString.
-    #
-    # @param other [WrappableString]
-    # @return [WrappableString]
-    #
-    def +(other)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Returns true if the string is empty (i.e. has no fragments)
-    #
-    # @return [Boolean]
-    #
-    def empty?
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Returns the string without any wrapping
-    #
-    # @return [String]
-    #
-    def string
-      # Source available in the toys-core gem
-    end
-    alias to_s string
-
-    ##
-    # Tests two wrappable strings for equality
-    # @param other [Object]
-    # @return [Boolean]
-    #
-    def ==(other)
-      # Source available in the toys-core gem
-    end
-    alias eql? ==
-
-    ##
-    # Returns a hash code for this object
-    # @return [Integer]
-    #
-    def hash
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Wraps the string to the given width.
-    #
-    # @param width [Integer,nil] Width in characters, or `nil` for infinite.
-    # @param width2 [Integer,nil] Width in characters for the second and
-    #     subsequent lines, or `nil` to use the same as width.
-    #
-    # @return [Array<String>] Wrapped lines
-    #
-    def wrap(width, width2 = nil)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Wraps an array of lines to the given width.
-    #
-    # @param strs [Array<WrappableString>] Array of strings to wrap.
-    # @param width [Integer,nil] Width in characters, or `nil` for infinite.
-    # @param width2 [Integer,nil] Width in characters for the second and
-    #     subsequent lines, or `nil` to use the same as width.
-    #
-    # @return [Array<String>] Wrapped lines
-    #
-    def self.wrap_lines(strs, width, width2 = nil)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Make the given object a WrappableString.
-    # If the object is already a WrappableString, return it. Otherwise,
-    # treat it as a string or an array of strings and wrap it in a
-    # WrappableString.
-    #
-    # @param obj [Toys::WrappableString,String,Array<String>]
-    # @return [Toys::WrappableString]
-    #
-    def self.make(obj)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Make the given object an array of WrappableString.
-    #
-    # @param objs [Array<Toys::WrappableString,String,Array<String>>]
-    # @return [Array<Toys::WrappableString>]
-    #
-    def self.make_array(objs)
-      # Source available in the toys-core gem
-    end
-  end
-end

data/core-docs/toys-core.rb

@@ -1,111 +0,0 @@
-##
-# **_Defined in the toys-core gem_**
-#
-# Toys is a configurable command line tool. Write commands in config files
-# using a simple DSL, and Toys will provide the command line executable and
-# take care of all the details such as argument parsing, online help, and error
-# reporting. Toys is designed for software developers, IT professionals, and
-# other power users who want to write and organize scripts to automate their
-# workflows. It can also be used as a Rake replacement, providing a more
-# natural command line interface for your project's build tasks.
-#
-# This module contains the command line framework underlying Toys. It can be
-# used to create command line executables using the Toys DSL and classes.
-#
-# ## Common starting points
-#
-# Some of the most commonly needed class documentation is listed below:
-#
-# * For information on the DSL used to write tools, start with
-#   {Toys::DSL::Tool}.
-# * The base class for tool runtime (i.e. that defines the basic methods
-#   available to a tool's implementation) is {Toys::Context}.
-# * For information on writing mixins, see {Toys::Mixin}.
-# * For information on writing templates, see {Toys::Template}.
-# * For information on writing acceptors, see {Toys::Acceptor}.
-# * For information on writing custom shell completions, see {Toys::Completion}.
-# * Standard mixins are defined under the {Toys::StandardMixins} module.
-# * Various utilities are defined under {Toys::Utils}. Some of these serve as
-#   the implementations of corresponding mixins.
-# * The main entrypoint for the command line framework is {Toys::CLI}.
-#
-# Other important internal classes are listed below.
-#
-# * The definition of a tool is represented by {Toys::ToolDefinition} along
-#   the helpers {Toys::Flag}, {Toys::PositionalArg}, and {Toys::FlagGroup}.
-# * Argument parsing is implemented by {Toys::ArgParser}.
-# * The process of finding and loading a tool definition given a tool name, is
-#   implemented by {Toys::Loader}.
-# * Text wrapping is handled by {Toys::WrappableString}.
-# * The settings system is implemented by {Toys::Settings}.
-#
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # Namespace for DSL classes. These classes provide the directives that can be
-  # used in configuration files.
-  #
-  # DSL directives that can appear at the top level of Toys files and tool
-  # blocks are defined by the {Toys::DSL::Tool} module.
-  #
-  # Directives that can appear within a block passed to {Toys::DSL::Tool#flag}
-  # are defined by the {Toys::DSL::Flag} class.
-  #
-  # Directives that can appear within a {Toys::DSL::Tool#flag_group} block or
-  # any of its related directives, are defined by the {Toys::DSL::FlagGroup}
-  # class.
-  #
-  # Directives that can appear within a {Toys::DSL::Tool#required_arg},
-  # {Toys::DSL::Tool#optional_arg}, or {Toys::DSL::Tool#remaining_args} block,
-  # are defined by the {Toys::DSL::PositionalArg} class.
-  #
-  module DSL
-  end
-
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # Namespace for standard middleware classes.
-  #
-  # These middleware are provided by Toys-Core and can be referenced by name
-  # when creating a {Toys::CLI}.
-  #
-  module StandardMiddleware
-  end
-
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # Namespace for standard mixin classes.
-  #
-  # These mixins are provided by Toys-Core and can be included by name by
-  # passing a symbol to {Toys::DSL::Tool#include}.
-  #
-  module StandardMixins
-  end
-
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # Namespace for common utility classes.
-  #
-  # These classes are not loaded by default, and must be required explicitly.
-  # For example, before using {Toys::Utils::Exec}, you must:
-  #
-  #     require "toys/utils/exec"
-  #
-  module Utils
-  end
-
-  class << self
-    ##
-    # Path to the executable. This can, for example, be invoked to run a subtool
-    # in a clean environment.
-    #
-    # @return [String] if there is an executable
-    # @return [nil] if there is no such executable
-    #
-    attr_accessor :executable_path
-  end
-end