toys 0.15.6 → 0.16.0

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

@@ -1,118 +0,0 @@
-module Toys
-  module Utils
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A class that invokes an external pager.
-    #
-    # @example Using a pager for regular output
-    #
-    #   Toys::Utils::Pager.start do |io|
-    #     io.puts "A long string\n"
-    #   end
-    #
-    # @example Piping output from a command
-    #
-    #   exec_service = Toys::Utils::Exec.new
-    #   Toys::Utils::Pager.start(exec_service: exec_service) do |io|
-    #     exec_service.exec(["/bin/ls", "-alF"], out: io)
-    #   end
-    #
-    class Pager
-      ##
-      # Creates a new pager.
-      #
-      # @param command [String,Array<String>,boolean] The command to use to
-      #     invoke the pager. May be specified as a string to be passed to the
-      #     shell, an array of strings representing a posix command, the value
-      #     `true` to use the default (normally `less -FIRX`), or the value
-      #     `false` to disable the pager and write directly to the output
-      #     stream. Default is `true`.
-      # @param exec_service [Toys::Utils::Exec] The service to use for
-      #     executing commands, or `nil` (the default) to use a default.
-      # @param fallback_io [IO] An IO-like object to write to if the pager is
-      #     disabled. Defaults to `$stdout`.
-      # @param rescue_broken_pipes [boolean] If `true` (the default), broken
-      #     pipes are silently rescued. This prevents the exception from
-      #     propagating out if the pager is interrupted. Set this parameter to
-      #     `false` to disable this behavior.
-      #
-      def initialize(command: true, exec_service: nil, fallback_io: nil,
-                     rescue_broken_pipes: true)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Runs the pager. Takes a block and yields an IO-like object that passes
-      # text to the pager. Can be called multiple times on the same pager.
-      #
-      # @yieldparam io [IO] An object that can be written to, to pass data to
-      #     the pager.
-      # @return [Integer] The exit code of the pager process.
-      #
-      # @example
-      #
-      #   pager = Toys::Utils::Pager.new
-      #   pager.start do |io|
-      #     io.puts "A long string\n"
-      #   end
-      #
-      def start
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # The command for running the pager process. May be specified as a string
-      # to be passed to the shell, an array of strings representing a posix
-      # command, or `nil` to disable the pager and write directly to an output
-      # stream.
-      #
-      # @return [String,Array<String>,nil]
-      #
-      attr_accessor :command
-
-      ##
-      # The IO stream used if the pager is disabled or could not be executed.
-      #
-      # @return [IO]
-      #
-      attr_accessor :fallback_io
-
-      class << self
-        ##
-        # A convenience method that creates a pager and runs it once by calling
-        # {Pager#start}.
-        #
-        # @param command [String,Array<String>,boolean] The command to use to
-        #     invoke the pager. May be specified as a string to be passed to the
-        #     shell, an array of strings representing a posix command, the value
-        #     `true` to use the default (normally `less -FIRX`), or the value
-        #     `false` to disable the pager and write directly to the output
-        #     stream. Default is `true`.
-        # @param exec_service [Toys::Utils::Exec] The service to use for
-        #     executing commands, or `nil` (the default) to use a default.
-        # @param fallback_io [IO] An IO-like object to write to if the pager is
-        #     disabled. Defaults to `$stdout`.
-        # @param rescue_broken_pipes [boolean] If `true` (the default), broken
-        #     pipes are silently rescued. This prevents the exception from
-        #     propagating out if the pager is interrupted. Set this parameter to
-        #     `false` to disable this behavior.
-        # @return [Integer] The exit code of the pager process.
-        #
-        # @example
-        #
-        #   Toys::Utils::Pager.start do |io|
-        #     io.puts "A long string\n"
-        #   end
-        #
-        def start(command: true,
-                  exec_service: nil,
-                  fallback_io: nil,
-                  rescue_broken_pipes: true,
-                  &block)
-          # Source available in the toys-core gem
-        end
-      end
-    end
-  end
-end

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

@@ -1,184 +0,0 @@
-module Toys
-  module Utils
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # An object that implements standard UI elements, such as error reports and
-    # logging, as provided by the `toys` command line. Specifically, it
-    # implements pretty formatting of log entries and stack traces, and renders
-    # using ANSI coloring where available via {Toys::Utils::Terminal}.
-    #
-    # This object can be used to implement `toys`-style behavior when creating
-    # a CLI object. For example:
-    #
-    #     require "toys/utils/standard_ui"
-    #     ui = Toys::Utils::StandardUI.new
-    #     cli = Toys::CLI.new(**ui.cli_args)
-    #
-    class StandardUI
-      ##
-      # Create a Standard UI.
-      #
-      # By default, all output is written to `$stderr`, and will share a single
-      # {Toys::Utils::Terminal} object, allowing multiple tools and/or threads
-      # to interleave messages without interrupting one another.
-      #
-      # @param output [IO,Toys::Utils::Terminal] Where to write output. You can
-      #     pass a terminal object, or an IO stream that will be wrapped in a
-      #     terminal output. Default is `$stderr`.
-      #
-      def initialize(output: nil)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # The terminal underlying this UI
-      #
-      # @return [Toys::Utils::Terminal]
-      #
-      attr_reader :terminal
-
-      ##
-      # A hash that maps severities to styles recognized by
-      # {Toys::Utils::Terminal}. Used to style the header for each log entry.
-      # This hash can be modified in place to adjust the behavior of loggers
-      # created by this UI.
-      #
-      # @return [Hash{String => Array<Symbol>}]
-      #
-      attr_reader :log_header_severity_styles
-
-      ##
-      # Convenience method that returns a hash of arguments that can be passed
-      # to the {Toys::CLI} constructor. Includes the `:error_handler` and
-      # `:logger_factory` arguments.
-      #
-      # @return [Hash]
-      #
-      def cli_args
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns an error handler conforming to the `:error_handler` argument to
-      # the {Toys::CLI} constructor. Specifically, it returns the
-      # {#error_handler_impl} method as a proc.
-      #
-      # @return [Proc]
-      #
-      def error_handler
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns a logger factory conforming to the `:logger_factory` argument
-      # to the {Toys::CLI} constructor. Specifically, it returns the
-      # {#logger_factory_impl} method as a proc.
-      #
-      # @return [Proc]
-      #
-      def logger_factory
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Implementation of the error handler. As dictated by the error handler
-      # specification in {Toys::CLI}, this must take a {Toys::ContextualError}
-      # as an argument, and return an exit code.
-      #
-      # The base implementation uses {#display_error_notice} and
-      # {#display_signal_notice} to print an appropriate message to the UI's
-      # terminal, and uses {#exit_code_for} to determine the correct exit code.
-      # Any of those methods can be overridden by a subclass to alter their
-      # behavior, or this main implementation method can be overridden to
-      # change the overall behavior.
-      #
-      # @param error [Toys::ContextualError] The error received
-      # @return [Integer] The exit code
-      #
-      def error_handler_impl(error)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Implementation of the logger factory. As dictated by the logger factory
-      # specification in {Toys::CLI}, this must take a {Toys::ToolDefinition}
-      # as an argument, and return a `Logger`.
-      #
-      # The base implementation returns a logger that writes to the UI's
-      # terminal, using {#logger_formatter_impl} as the formatter. It sets the
-      # level to `Logger::WARN` by default. Either this method or the helper
-      # methods can be overridden to change this behavior.
-      #
-      # @param _tool {Toys::ToolDefinition} The tool definition of the tool to
-      #     be executed
-      # @return [Logger]
-      #
-      def logger_factory_impl(_tool)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Returns an exit code appropriate for the given exception. Currently,
-      # the logic interprets signals (returning the convention of 128 + signo),
-      # usage errors (returning the conventional value of 2), and tool not
-      # runnable errors (returning the conventional value of 126), and defaults
-      # to 1 for all other error types.
-      #
-      # This method is used by {#error_handler_impl} and can be overridden to
-      # change its behavior.
-      #
-      # @param error [Exception] The exception raised. This method expects the
-      #     original exception, rather than a ContextualError.
-      # @return [Integer] The appropriate exit code
-      #
-      def exit_code_for(error)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Displays a default output for a signal received.
-      #
-      # This method is used by {#error_handler_impl} and can be overridden to
-      # change its behavior.
-      #
-      # @param error [SignalException]
-      #
-      def display_signal_notice(error)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Displays a default output for an error. Displays the error, the
-      # backtrace, and contextual information regarding what tool was run and
-      # where in its code the error occurred.
-      #
-      # This method is used by {#error_handler_impl} and can be overridden to
-      # change its behavior.
-      #
-      # @param error [Toys::ContextualError]
-      #
-      def display_error_notice(error)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Implementation of the formatter used by loggers created by this UI's
-      # logger factory. This interface is defined by the standard `Logger`
-      # class.
-      #
-      # This method can be overridden to change the behavior of loggers created
-      # by this UI.
-      #
-      # @param severity [String]
-      # @param time [Time]
-      # @param _progname [String]
-      # @param msg [Object]
-      # @return [String]
-      #
-      def logger_formatter_impl(severity, time, _progname, msg)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

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

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