toys-core 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ebb136d89b19617cfdaf8de9c870cce070857748abd208ab8faa4896b7e7b36
-  data.tar.gz: eb079b488d1da544e5f31ab0fe0f9730d77d6878549c673bc6ba4711a5d6c295
+  metadata.gz: 26fce1d32fe0161a806a4b6d6d831b546be343290a0d0103c5e6a52e14f2f106
+  data.tar.gz: b57713c9fd6436f5f90007769663340a4df5599bf9c72f0c9eb160ebcdc7ed8a
 SHA512:
-  metadata.gz: 864c7bc16399227e29e013372611ed70df77339185593d3830a31a5092e7dea6540d62ed83704e23ce5d78410ce2b4e34ae5ce9f709d67d8bb82e5075ed09cc3
-  data.tar.gz: 5eb3e60cefb50d7a289ef2283a91574ede820bf1d2bb5769d8038d60d760e999f36e49882899c06f2de6dd37a23d828ee25bd1e2a0764e11cc0e31553764368c
+  metadata.gz: f2427161dc5f1635473fa09f5e67c6f3ad58f861669de6c909c03fe55a2b44778e2b905f44b0bbeb250019e583d721296eb1a3adccd62c2f76e4abed99bdd860
+  data.tar.gz: c9ab4052480bcbd91e3452eba2d2e425013eba043f4d825b4f5a88f92a248ca780368206a5c06b0bf2ea9a67dea93fda8163babef2c64e4147cb38c650486f6a

data/CHANGELOG.md

@@ -1,9 +1,31 @@
 # Release History
 
+### 0.3.4 / 2018-05-14
+
+* CHANGED: Renamed switch to flag
+* CHANGED: Renamed Utils::Usage to Utils::HelpText
+* CHANGED: Renamed show_usage middleware to show_help and default everything false.
+* CHANGED: Renamed docs: parameter again, to desc: and long_desc: to match tool desc.
+* CHANGED: Middleware config method takes a loader as the second arg
+* CHANGED: desc is now a single string rather than an array.
+* CHANGED: Removed Loader#execute, and returned remaining args from Loader#lookup.
+* CHANGED: Wrapped most errors with Toys::ContextualError
+* CHANGED: accept: parameter now controls whether a switch takes a value by default
+* CHANGED: Explicit and implicit show-help now handled by separate middleware instances
+* CHANGED: All description strings are now wrappable
+* IMPROVED: gem_build template can suppress interactive confirmation.
+* IMPROVED: Logger colors the header when possible.
+* IMPROVED: HelpText class can now generate nicer help pages
+* IMPROVED: Style support for spinner helper
+* IMPROVED: Set default descriptions for flags and args
+* ADDED: CLI now takes an error handler to report most errors.
+* ADDED: Alias DSL methods `required`, `optional`, and `remaining`.
+* FIXED: Finish definitions for subtools since the desc may depend on it
+
 ### 0.3.3 / 2018-05-09
 
 * CHANGED: Renamed file_utils helper to fileutils.
-* CHANGED: Renamed doc: parameter to docs:
+* CHANGED: Renamed `doc:` parameter to `docs:`.
 * CHANGED: SwitchDefinition has separate fields for acceptor and docs.
 * CHANGED: Description and long description are now arrays of strings.
 * FIXED: Documentation strings that begin with "--" no longer cause problems.

data/lib/toys-core.rb

@@ -27,6 +27,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
+gem "highline", "~> 1.7"
+
 ##
 # Toys is a Ruby library and command line tool that lets you build your own
 # command line suite of tools (with commands and subcommands) using a Ruby DSL.

data/lib/toys/cli.rb

@@ -28,6 +28,9 @@
 ;
 
 require "logger"
+require "highline"
+
+require "toys/utils/line_output"
 
 module Toys
   ##
@@ -69,6 +72,10 @@ module Toys
     # @param [Integer,nil] base_level The logger level that should correspond
     #     to zero verbosity. If not provided, will default to the current level
     #     of the logger.
+    # @param [Proc,nil] error_handler A proc that is called when an error is
+    #     caught. The proc should take a {Toys::ContextualError} argument and
+    #     report the error. It should return an exit code (normally nonzero).
+    #     Default is a {Toys::CLI::DefaultErrorHandler} writing to the logger.
     #
     def initialize(
       binary_name: nil,
@@ -78,7 +85,8 @@ module Toys
       preload_file_name: nil,
       middleware_stack: nil,
       logger: nil,
-      base_level: nil
+      base_level: nil,
+      error_handler: nil
     )
       @logger = logger || self.class.default_logger
       @base_level = base_level || @logger.level
@@ -93,6 +101,7 @@ module Toys
         preload_file_name: preload_file_name,
         middleware_stack: middleware_stack
       )
+      @error_handler = error_handler || DefaultErrorHandler.new
     end
 
     ##
@@ -200,7 +209,12 @@ module Toys
     # @return [Integer] The resulting status code
     #
     def run(*args, verbosity: 0)
-      @loader.execute(self, args.flatten, verbosity: verbosity)
+      tool, remaining = ContextualError.capture("Error finding tool definition") do
+        @loader.lookup(args.flatten)
+      end
+      tool.execute(self, remaining, verbosity: verbosity)
+    rescue ContextualError => e
+      @error_handler.call(e)
     end
 
     ##
@@ -216,37 +230,92 @@ module Toys
               preload_file_name: @preload_file_name,
               middleware_stack: @middleware_stack,
               logger: @logger,
-              base_level: @base_level)
+              base_level: @base_level,
+              error_handler: @error_handler)
+    end
+
+    ##
+    # A basic error handler that prints out captured errors to a stream or
+    # a logger.
+    #
+    class DefaultErrorHandler
+      ##
+      # Create an error handler.
+      #
+      # @param [IO,Logger,nil] sink Where to write errors. Default is `$stderr`.
+      #
+      def initialize(sink = $stderr)
+        @line_output = Utils::LineOutput.new(sink, log_level: ::Logger::FATAL)
+      end
+
+      ## @private
+      def call(error)
+        @line_output.puts(cause_string(error.cause))
+        @line_output.puts(context_string(error), :bold)
+        -1
+      end
+
+      private
+
+      def cause_string(cause)
+        lines = ["#{cause.class}: #{cause.message}"]
+        cause.backtrace.each_with_index.reverse_each do |bt, i|
+          lines << "    #{(i + 1).to_s.rjust(3)}: #{bt}"
+        end
+        lines.join("\n")
+      end
+
+      def context_string(error)
+        lines = [
+          error.banner || "Unexpected error!",
+          "    #{error.cause.class}: #{error.cause.message}"
+        ]
+        if error.config_path
+          lines << "    in config file: #{error.config_path}:#{error.config_line}"
+        end
+        if error.tool_name
+          lines << "    while executing tool: #{error.tool_name.join(' ').inspect}"
+          if error.tool_args
+            lines << "    with arguments: #{error.tool_args.inspect}"
+          end
+        end
+        lines.join("\n")
+      end
     end
 
     class << self
       ##
       # Returns a default set of middleware that may be used as a starting
-      # point for a typical CLI. This set includes:
+      # point for a typical CLI. This set includes the following in order:
       #
+      # *  {Toys::Middleware::SetDefaultDescriptions} providing defaults for
+      #    description fields
+      # *  {Toys::Middleware::ShowHelp} adding the `--help` flag
       # *  {Toys::Middleware::HandleUsageErrors}
-      # *  {Toys::Middleware::ShowUsage} adding the `--help` switch and
-      #    providing default behavior for groups
-      # *  {Toys::Middleware::AddVerbositySwitches} adding the `--verbose` and
-      #    `--quiet` switches for managing the logger level
+      # *  {Toys::Middleware::ShowHelp} providing default behavior for groups
+      # *  {Toys::Middleware::AddVerbosityFlags} adding the `--verbose` and
+      #    `--quiet` flags for managing the logger level
       #
       # @return [Array]
       #
       def default_middleware_stack
         [
-          :handle_usage_errors,
-          :show_usage,
-          :add_verbosity_switches
+          [:set_default_descriptions],
+          [:show_help, help_flags: true],
+          [:handle_usage_errors],
+          [:show_help, fallback_execution: true],
+          [:add_verbosity_flags]
         ]
       end
 
       ##
       # Returns a default logger that logs to `STDERR`.
       #
+      # @param [IO] stream Stream to write to. Defaults to `$stderr`.
       # @return [Logger]
       #
-      def default_logger
-        logger = ::Logger.new(::STDERR)
+      def default_logger(stream = $stderr)
+        logger = ::Logger.new(stream)
         logger.formatter = proc do |severity, time, _progname, msg|
           msg_str =
             case msg
@@ -257,12 +326,36 @@ module Toys
             else
               msg.inspect
             end
-          timestr = time.strftime("%Y-%m-%d %H:%M:%S")
-          format("[%s %5s]  %s\n", timestr, severity, msg_str)
+          format_log(stream.tty?, time, severity, msg_str)
         end
         logger.level = ::Logger::WARN
         logger
       end
+
+      private
+
+      def format_log(is_tty, time, severity, msg)
+        timestr = time.strftime("%Y-%m-%d %H:%M:%S")
+        header = format("[%s %5s]", timestr, severity)
+        if is_tty
+          header =
+            case severity
+            when "FATAL"
+              ::HighLine.color(header, :bright_magenta, :bold, :underline)
+            when "ERROR"
+              ::HighLine.color(header, :bright_red, :bold)
+            when "WARN"
+              ::HighLine.color(header, :bright_yellow)
+            when "INFO"
+              ::HighLine.color(header, :bright_cyan)
+            when "DEBUG"
+              ::HighLine.color(header, :white)
+            else
+              header
+            end
+        end
+        "#{header}  #{msg}\n"
+      end
     end
   end
 end

data/lib/toys/config_dsl.rb

@@ -32,7 +32,7 @@ module Toys
   # This class defines the DSL for a toys configuration file.
   #
   # A toys configuration defines one or more named tools. It provides syntax
-  # for setting the description, defining switches and arguments, specifying
+  # for setting the description, defining flags and arguments, specifying
   # how to execute the tool, and requesting helper modules and other services.
   # It also lets you define subtools, nested arbitrarily deep, using blocks.
   #
@@ -161,52 +161,63 @@ module Toys
     end
 
     ##
-    # Set the long description for the current tool. The long description is
-    # displayed in the usage documentation for the tool itself.
+    # Set the short description for the current tool. The short description is
+    # displayed with the tool in a subtool list. You may also use the
+    # equivalent method `short_desc`.
     #
-    # @param [String,Toys::Utils::WrappableString...] strs The long description
+    # The description may be provided as a {Toys::Utils::WrappableString}, a
+    # single string (which will be wrapped), or an array of strings, which will
+    # be interpreted as string fragments that will be concatenated and wrapped.
     #
-    def long_desc(*strs)
+    # @param [Toys::Utils::WrappableString,String,Array<String>] str
+    #
+    def desc(str)
       return self if _cur_tool.nil?
-      _cur_tool.definition_path = @path
-      _cur_tool.long_desc = strs
+      _cur_tool.lock_definition_path(@path)
+      _cur_tool.desc = str
       self
     end
+    alias short_desc desc
 
     ##
-    # Set the short description for the current tool. The short description is
-    # displayed with the tool in a command list. You may also use the
-    # equivalent method `short_desc`.
+    # Set the long description for the current tool. The long description is
+    # displayed in the usage documentation for the tool itself.
+    #
+    # Each string may be provided as a {Toys::Utils::WrappableString}, a single
+    # string (which will be wrapped), or an array of strings, which will be
+    # interpreted as string fragments that will be concatenated and wrapped.
     #
-    # @param [String,Toys::Utils::WrappableString...] strs The short description
+    # @param [Toys::Utils::WrappableString,String,Array<String>...] strs
     #
-    def desc(*strs)
+    def long_desc(*strs)
       return self if _cur_tool.nil?
-      _cur_tool.definition_path = @path
-      _cur_tool.desc = strs
+      _cur_tool.lock_definition_path(@path)
+      _cur_tool.long_desc = strs
       self
     end
-    alias short_desc desc
 
     ##
-    # Add a switch to the current tool. Each switch must specify a key which
-    # the executor may use to obtain the switch value from the context.
-    # You may then provide the switches themselves in `OptionParser` form.
+    # Add a flag to the current tool. Each flag must specify a key which
+    # the executor may use to obtain the flag value from the context.
+    # You may then provide the flags themselves in `OptionParser` form.
     #
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
-    # @param [String...] switches The switches in OptionParser format.
+    # @param [String...] flags The flags in OptionParser format.
     # @param [Object,nil] accept An OptionParser acceptor. Optional.
     # @param [Object] default The default value. This is the value that will
-    #     be set in the context if this switch is not provided on the command
+    #     be set in the context if this flag is not provided on the command
     #     line. Defaults to `nil`.
     # @param [String,Toys::Utils::WrappableString,
-    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
-    #     the switch. Defaults to empty array.
-    # @param [Boolean] only_unique If true, any switches that are already
-    #     defined in this tool are removed from this switch. For example, if
-    #     an earlier switch uses `-a`, and this switch wants to use both
-    #     `-a` and `-b`, then only `-b` will be assigned to this switch.
+    #     Array<String,Toys::Utils::WrappableString>] desc Short description
+    #     for the flag. Defaults to empty array.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] long_desc Long
+    #     description for the flag. Defaults to empty array.
+    # @param [Boolean] only_unique If true, any flags that are already
+    #     defined in this tool are removed from this flag. For example, if
+    #     an earlier flag uses `-a`, and this flag wants to use both
+    #     `-a` and `-b`, then only `-b` will be assigned to this flag.
     #     Defaults to false.
     # @param [Proc,nil] handler An optional handler for setting/updating the
     #     value. If given, it should take two arguments, the new given value
@@ -214,13 +225,17 @@ module Toys
     #     should be set. The default handler simply replaces the previous
     #     value. i.e. the default is effectively `-> (val, _prev) { val }`.
     #
-    def switch(key, *switches,
-               accept: nil, default: nil, docs: nil, only_unique: false, handler: nil)
+    def flag(key, *flags,
+             accept: nil, default: nil, desc: nil, long_desc: nil,
+             only_unique: false, handler: nil,
+             &block)
       return self if _cur_tool.nil?
-      _cur_tool.definition_path = @path
-      _cur_tool.add_switch(key, *switches,
-                           accept: accept, default: default, docs: docs,
-                           only_unique: only_unique, handler: handler)
+      _cur_tool.lock_definition_path(@path)
+      _cur_tool.add_flag(key, *flags,
+                         accept: accept, default: default,
+                         desc: desc, long_desc: long_desc,
+                         only_unique: only_unique, handler: handler,
+                         &block)
       self
     end
 
@@ -232,16 +247,25 @@ module Toys
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
     # @param [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [String] display_name A name to use for display (in help text and
+    #     error reports). Defaults to the key in upper case.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] desc Short description
+    #     for the arg. Defaults to empty array.
     # @param [String,Toys::Utils::WrappableString,
-    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for the
-    #     arg. Defaults to empty array.
+    #     Array<String,Toys::Utils::WrappableString>] long_desc Long
+    #     description for the arg. Defaults to empty array.
     #
-    def required_arg(key, accept: nil, docs: nil)
+    def required_arg(key, accept: nil, display_name: nil, desc: nil, long_desc: nil, &block)
       return self if _cur_tool.nil?
-      _cur_tool.definition_path = @path
-      _cur_tool.add_required_arg(key, accept: accept, docs: docs)
+      _cur_tool.lock_definition_path(@path)
+      _cur_tool.add_required_arg(key,
+                                 accept: accept, display_name: display_name,
+                                 desc: desc, long_desc: long_desc,
+                                 &block)
       self
     end
+    alias required required_arg
 
     ##
     # Add an optional positional argument to the current tool. You must specify
@@ -251,20 +275,30 @@ module Toys
     #
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
-    # @param [Object,nil] accept An OptionParser acceptor. Optional.
     # @param [Object] default The default value. This is the value that will
     #     be set in the context if this argument is not provided on the command
     #     line. Defaults to `nil`.
+    # @param [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [String] display_name A name to use for display (in help text and
+    #     error reports). Defaults to the key in upper case.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] desc Short description
+    #     for the arg. Defaults to empty array.
     # @param [String,Toys::Utils::WrappableString,
-    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for the
-    #     arg. Defaults to empty array.
+    #     Array<String,Toys::Utils::WrappableString>] long_desc Long
+    #     description for the arg. Defaults to empty array.
     #
-    def optional_arg(key, accept: nil, default: nil, docs: nil)
+    def optional_arg(key, default: nil, accept: nil, display_name: nil,
+                     desc: nil, long_desc: nil, &block)
       return self if _cur_tool.nil?
-      _cur_tool.definition_path = @path
-      _cur_tool.add_optional_arg(key, accept: accept, default: default, docs: docs)
+      _cur_tool.lock_definition_path(@path)
+      _cur_tool.add_optional_arg(key,
+                                 accept: accept, default: default, display_name: display_name,
+                                 desc: desc, long_desc: long_desc,
+                                 &block)
       self
     end
+    alias optional optional_arg
 
     ##
     # Specify what should be done with unmatched positional arguments. You must
@@ -273,20 +307,30 @@ module Toys
     #
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
-    # @param [Object,nil] accept An OptionParser acceptor. Optional.
     # @param [Object] default The default value. This is the value that will
     #     be set in the context if no unmatched arguments are provided on the
     #     command line. Defaults to the empty array `[]`.
+    # @param [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [String] display_name A name to use for display (in help text and
+    #     error reports). Defaults to the key in upper case.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] desc Short description
+    #     for the arg. Defaults to empty array.
     # @param [String,Toys::Utils::WrappableString,
-    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for the
-    #     args. Defaults to empty array.
+    #     Array<String,Toys::Utils::WrappableString>] long_desc Long
+    #     description for the arg. Defaults to empty array.
     #
-    def remaining_args(key, accept: nil, default: [], docs: nil)
+    def remaining_args(key, default: [], accept: nil, display_name: nil,
+                       desc: nil, long_desc: nil, &block)
       return self if _cur_tool.nil?
-      _cur_tool.definition_path = @path
-      _cur_tool.set_remaining_args(key, accept: accept, default: default, docs: docs)
+      _cur_tool.lock_definition_path(@path)
+      _cur_tool.set_remaining_args(key,
+                                   accept: accept, default: default, display_name: display_name,
+                                   desc: desc, long_desc: long_desc,
+                                   &block)
       self
     end
+    alias remaining remaining_args
 
     ##
     # Specify the executor for this tool. This is a block that will be called,
@@ -294,7 +338,7 @@ module Toys
     #
     def execute(&block)
       return self if _cur_tool.nil?
-      _cur_tool.definition_path = @path
+      _cur_tool.lock_definition_path(@path)
       _cur_tool.executor = block
       self
     end
@@ -309,7 +353,7 @@ module Toys
     #
     def helper(name, &block)
       return self if _cur_tool.nil?
-      _cur_tool.definition_path = @path
+      _cur_tool.lock_definition_path(@path)
       _cur_tool.add_helper(name, &block)
       self
     end
@@ -324,7 +368,7 @@ module Toys
     #
     def use(mod)
       return self if _cur_tool.nil?
-      _cur_tool.definition_path = @path
+      _cur_tool.lock_definition_path(@path)
       _cur_tool.use_module(mod)
       self
     end
@@ -347,9 +391,11 @@ module Toys
       dsl = new(words, remaining_words, priority, loader, path)
       case source
       when String
-        # rubocop:disable Security/Eval
-        eval(source, dsl._binding, path, 1)
-        # rubocop:enable Security/Eval
+        ContextualError.capture_path("Error while loading Toys config!", path) do
+          # rubocop:disable Security/Eval
+          eval(source, dsl._binding, path, 1)
+          # rubocop:enable Security/Eval
+        end
       when ::Proc
         dsl.instance_eval(&source)
       end