toys 0.12.2 → 0.13.0

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

@@ -0,0 +1,310 @@
+begin
+  require "io/console"
+rescue ::LoadError
+  # TODO: alternate methods of getting terminal size
+end
+
+module Toys
+  module Utils
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A simple terminal class.
+    #
+    # ### Styles
+    #
+    # This class supports ANSI styled output where supported.
+    #
+    # Styles may be specified in any of the following forms:
+    #  *  A symbol indicating the name of a well-known style, or the name of
+    #     a defined style.
+    #  *  An rgb string in hex "rgb" or "rrggbb" form.
+    #  *  An ANSI code string in `\e[XXm` form.
+    #  *  An array of ANSI codes as integers.
+    #
+    class Terminal
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Fatal terminal error.
+      #
+      class TerminalError < ::StandardError
+      end
+
+      ##
+      # ANSI style code to clear styles
+      # @return [String]
+      #
+      CLEAR_CODE = "\e[0m"
+
+      ##
+      # Standard ANSI style codes by name.
+      # @return [Hash{Symbol => Array<Integer>}]
+      #
+      BUILTIN_STYLE_NAMES = {
+        clear: [0],
+        reset: [0],
+        bold: [1],
+        faint: [2],
+        italic: [3],
+        underline: [4],
+        blink: [5],
+        reverse: [7],
+        black: [30],
+        red: [31],
+        green: [32],
+        yellow: [33],
+        blue: [34],
+        magenta: [35],
+        cyan: [36],
+        white: [37],
+        on_black: [30],
+        on_red: [31],
+        on_green: [32],
+        on_yellow: [33],
+        on_blue: [34],
+        on_magenta: [35],
+        on_cyan: [36],
+        on_white: [37],
+        bright_black: [90],
+        bright_red: [91],
+        bright_green: [92],
+        bright_yellow: [93],
+        bright_blue: [94],
+        bright_magenta: [95],
+        bright_cyan: [96],
+        bright_white: [97],
+        on_bright_black: [100],
+        on_bright_red: [101],
+        on_bright_green: [102],
+        on_bright_yellow: [103],
+        on_bright_blue: [104],
+        on_bright_magenta: [105],
+        on_bright_cyan: [106],
+        on_bright_white: [107],
+      }.freeze
+
+      ##
+      # Default length of a single spinner frame, in seconds.
+      # @return [Float]
+      #
+      DEFAULT_SPINNER_FRAME_LENGTH = 0.1
+
+      ##
+      # Default set of spinner frames.
+      # @return [Array<String>]
+      #
+      DEFAULT_SPINNER_FRAMES = ["-", "\\", "|", "/"].freeze
+
+      ##
+      # Returns a copy of the given string with all ANSI style codes removed.
+      #
+      # @param str [String] Input string
+      # @return [String] String with styles removed
+      #
+      def self.remove_style_escapes(str)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Create a terminal.
+      #
+      # @param input [IO,nil] Input stream.
+      # @param output [IO,Logger,nil] Output stream or logger.
+      # @param styled [Boolean,nil] Whether to output ansi styles. If `nil`, the
+      #     setting is inferred from whether the output has a tty.
+      #
+      def initialize(input: $stdin, output: $stdout, styled: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Output stream or logger
+      # @return [IO,Logger,nil]
+      #
+      attr_reader :output
+
+      ##
+      # Input stream
+      # @return [IO,nil]
+      #
+      attr_reader :input
+
+      ##
+      # Whether output is styled
+      # @return [Boolean]
+      #
+      attr_reader :styled
+
+      ##
+      # Write a partial line without appending a newline.
+      #
+      # @param str [String] The line to write
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
+      #     partial line.
+      # @return [self]
+      #
+      def write(str = "", *styles)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Read a line, blocking until one is available.
+      #
+      # @return [String] the entire string including the temrinating newline
+      # @return [nil] if the input is closed or at eof, or there is no input
+      #
+      def readline
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # This method is defined so that `::Logger` will recognize a terminal as
+      # a log device target, but it does not actually close anything.
+      #
+      def close
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Write a line, appending a newline if one is not already present.
+      #
+      # @param str [String] The line to write
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
+      #     entire line.
+      # @return [self]
+      #
+      def puts(str = "", *styles)
+        # Source available in the toys-core gem
+      end
+      alias say puts
+
+      ##
+      # Write a line, appending a newline if one is not already present.
+      #
+      # @param str [String] The line to write
+      # @return [self]
+      #
+      def <<(str)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Write a newline and flush the current line.
+      # @return [self]
+      #
+      def newline
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Ask a question and get a response.
+      #
+      # @param prompt [String] Required prompt string.
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
+      #     prompt.
+      # @param default [String,nil] Default value, or `nil` for no default.
+      #     Uses `nil` if not specified.
+      # @param trailing_text [:default,String,nil] Trailing text appended to
+      #     the prompt, `nil` for none, or `:default` to show the default.
+      # @return [String]
+      #
+      def ask(prompt, *styles, default: nil, trailing_text: :default)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Confirm with the user.
+      #
+      # @param prompt [String] Prompt string. Defaults to `"Proceed?"`.
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
+      #     prompt.
+      # @param default [Boolean,nil] Default value, or `nil` for no default.
+      #     Uses `nil` if not specified.
+      # @return [Boolean]
+      #
+      def confirm(prompt = "Proceed? ", *styles, default: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Display a spinner during a task. You should provide a block that
+      # performs the long-running task. While the block is executing, a
+      # spinner will be displayed.
+      #
+      # @param leading_text [String] Optional leading string to display to the
+      #     left of the spinner. Default is the empty string.
+      # @param frame_length [Float] Length of a single frame, in seconds.
+      #     Defaults to {DEFAULT_SPINNER_FRAME_LENGTH}.
+      # @param frames [Array<String>] An array of frames. Defaults to
+      #     {DEFAULT_SPINNER_FRAMES}.
+      # @param style [Symbol,Array<Symbol>] A terminal style or array of styles
+      #     to apply to all frames in the spinner. Defaults to empty,
+      # @param final_text [String] Optional final string to display when the
+      #     spinner is complete. Default is the empty string. A common practice
+      #     is to set this to newline.
+      # @return [Object] The return value of the block.
+      #
+      def spinner(leading_text: "", final_text: "",
+                  frame_length: nil, frames: nil, style: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Return the terminal size as an array of width, height.
+      #
+      # @return [Array(Integer,Integer)]
+      #
+      def size
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Return the terminal width
+      #
+      # @return [Integer]
+      #
+      def width
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Return the terminal height
+      #
+      # @return [Integer]
+      #
+      def height
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Define a named style.
+      #
+      # Style names must be symbols.
+      # The definition of a style may include any valid style specification,
+      # including the symbol names of existing defined styles.
+      #
+      # @param name [Symbol] The name for the style
+      # @param styles [Symbol,String,Array<Integer>...]
+      # @return [self]
+      #
+      def define_style(name, *styles)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Apply the given styles to the given string, returning the styled
+      # string. Honors the styled setting; if styling is disabled, does not
+      # add any ANSI style codes and in fact removes any existing codes. If
+      # styles were added, ensures that the string ends with a clear code.
+      #
+      # @param str [String] String to style
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply
+      # @return [String] The styled string
+      #
+      def apply_styles(str, *styles)
+        # Source available in the toys-core gem
+      end
+    end
+  end
+end

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

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

@@ -0,0 +1,120 @@
+module Toys
+  ##
+  # **_Defined in the toys-core gem_**
+  #
+  # A string intended for word-wrapped display.
+  #
+  class WrappableString
+    ##
+    # Create a wrapped string.
+    # @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