toys-core 0.3.3 → 0.3.4

data/lib/toys/context.rb

@@ -37,7 +37,7 @@ module Toys
   # Keys that begin with two underscores are reserved common elements of the
   # context such as the tool being executed, or the verbosity level.
   # Other keys are available for use by your tool. Generally, they are set
-  # by switches and arguments in your tool. Context values may also be set
+  # by flags and arguments in your tool. Context values may also be set
   # by middleware. By convention, middleware-set keys begin with a single
   # underscore.
   #
@@ -236,8 +236,8 @@ module Toys
     ##
     # Execute another tool, given by the provided arguments.
     #
-    # @param [String...] args Command line arguments defining another tool
-    #     to run, along with parameters and switches.
+    # @param [String...] args The name of the tool to run along with its
+    #     command line arguments and flags.
     # @param [Toys::CLI,nil] cli The CLI to use to execute the tool. If `nil`
     #     (the default), uses the current CLI.
     # @param [Boolean] exit_on_nonzero_status If true, exit immediately if the

data/lib/toys/core_version.rb

@@ -32,5 +32,5 @@ module Toys
   # Current version of Toys core
   # @return [String]
   #
-  CORE_VERSION = "0.3.3".freeze
+  CORE_VERSION = "0.3.4".freeze
 end

data/lib/toys/errors.rb

@@ -39,4 +39,80 @@ module Toys
   #
   class LoaderError < ::StandardError
   end
+
+  ##
+  # A wrapper exception used to provide user-oriented context for an exception
+  #
+  class ContextualError < ::StandardError
+    ## @private
+    def initialize(cause, banner,
+                   config_path: nil, config_line: nil,
+                   tool_name: nil, tool_args: nil)
+      super("#{banner} : #{cause.message} (#{cause.class})")
+      @cause = cause
+      @banner = banner
+      @config_path = config_path
+      @config_line = config_line
+      @tool_name = tool_name
+      @tool_args = tool_args
+    end
+
+    attr_reader :cause
+    attr_reader :banner
+
+    attr_accessor :config_path
+    attr_accessor :config_line
+    attr_accessor :tool_name
+    attr_accessor :tool_args
+
+    class << self
+      ## @private
+      def capture_path(banner, path, opts = {})
+        yield
+      rescue ContextualError => e
+        add_fields_if_missing(e, opts)
+        add_config_path_if_missing(e, path)
+        raise e
+      rescue ::SyntaxError => e
+        if e.message =~ /#{::Regexp.escape(path)}:(\d+)/
+          opts = opts.merge(config_path: path, config_line: $1.to_i)
+          e = ContextualError.new(e, banner, opts)
+        end
+        raise e
+      rescue ::StandardError => e
+        e = ContextualError.new(e, banner)
+        add_fields_if_missing(e, opts)
+        add_config_path_if_missing(e, path)
+        raise e
+      end
+
+      ## @private
+      def capture(banner, opts = {})
+        yield
+      rescue ContextualError => e
+        add_fields_if_missing(e, opts)
+        raise e
+      rescue ::StandardError => e
+        raise ContextualError.new(e, banner, opts)
+      end
+
+      private
+
+      def add_fields_if_missing(error, opts)
+        opts.each do |k, v|
+          error.send(:"#{k}=", v) if error.send(k).nil?
+        end
+      end
+
+      def add_config_path_if_missing(error, path)
+        if error.config_path.nil? && error.config_line.nil?
+          l = error.cause.backtrace_locations.find { |b| b.absolute_path == path }
+          if l
+            error.config_path = path
+            error.config_line = l.lineno
+          end
+        end
+      end
+    end
+  end
 end

data/lib/toys/helpers/highline.rb

@@ -27,8 +27,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-gem "highline", "~> 1.7"
-
 require "highline"
 
 module Toys

data/lib/toys/helpers/spinner.rb

@@ -28,6 +28,7 @@
 ;
 
 require "monitor"
+require "highline"
 
 module Toys
   module Helpers
@@ -53,23 +54,23 @@ module Toys
       # spinner will be displayed.
       #
       # @param [String] leading_text Optional leading string to display to the
-      #     left of the spinner.
+      #     left of the spinner. Default is the empty string.
       # @param [Float] frame_length Length of a single frame, in seconds.
       #     Defaults to {DEFAULT_FRAME_LENGTH}.
-      # @param [Array<String,Array<String>>] frames An array of frames. Each
-      #     frame should be either a string, or a two-element array of string
-      #     and integer, where the integer is the visible length of the frame
-      #     on screen. The latter form should be used if the frame string
-      #     contains non-printing characters such as ANSI escape codes.
-      #     Defaults to {DEFAULT_FRAMES}.
+      # @param [Array<String>] frames An array of frames. Defaults to
+      #     {DEFAULT_FRAMES}.
+      # @param [Symbol,Array<Symbol>] style A HighLine style or array of styles
+      #     to apply to all frames in the spinner. Defaults to empty,
       # @param [IO] stream Stream to output the spinner to. Defaults to STDOUT.
       #     Note the spinner will be disabled if this stream is not a tty.
       # @param [String] final_text Optional final string to display when the
-      #     spinner is complete.
+      #     spinner is complete. Default is the empty string. A common practice
+      #     is to set this to newline.
       #
       def spinner(leading_text: "",
                   frame_length: DEFAULT_FRAME_LENGTH,
                   frames: DEFAULT_FRAMES,
+                  style: nil,
                   stream: $stdout,
                   final_text: "")
         return nil unless block_given?
@@ -77,7 +78,7 @@ module Toys
           stream.write(leading_text)
           stream.flush
         end
-        spin = SpinDriver.new(stream, frames, frame_length)
+        spin = SpinDriver.new(stream, frames, Array(style), frame_length)
         begin
           yield
         ensure
@@ -93,9 +94,14 @@ module Toys
       class SpinDriver
         include ::MonitorMixin
 
-        def initialize(stream, frames, frame_length)
+        def initialize(stream, frames, style, frame_length)
           @stream = stream
-          @frames = frames.map { |f| f.is_a?(::Array) ? f : [f, f.size] }
+          @frames = frames.map do |f|
+            [
+              style.empty? ? f : ::HighLine.color(f, *style),
+              ::HighLine.uncolor(f).size
+            ]
+          end
           @frame_length = frame_length
           @cur_frame = 0
           @stopping = false

data/lib/toys/loader.rb

@@ -51,10 +51,10 @@ module Toys
     #
     def initialize(index_file_name: nil, preload_file_name: nil, middleware_stack: [])
       if index_file_name && ::File.extname(index_file_name) != ".rb"
-        raise LoaderError, "Illegal index file name #{index_file_name.inspect}"
+        raise ::ArgumentError, "Illegal index file name #{index_file_name.inspect}"
       end
       if preload_file_name && ::File.extname(preload_file_name) != ".rb"
-        raise LoaderError, "Illegal preload file name #{preload_file_name.inspect}"
+        raise ::ArgumentError, "Illegal preload file name #{preload_file_name.inspect}"
       end
       @index_file_name = index_file_name
       @preload_file_name = preload_file_name
@@ -83,13 +83,17 @@ module Toys
 
     ##
     # Given a list of command line arguments, find the appropriate tool to
-    # handle the command, loading it from the configuration if necessary.
+    # handle the command, loading it from the configuration if necessary, and
+    # following aliases.
     # This always returns a tool. If the specific tool path is not defined and
-    # cannot be found in any configuration, it returns the nearest group that
+    # cannot be found in any configuration, it finds the nearest group that
     # _would_ contain that tool, up to the root tool.
     #
+    # Returns a tuple of the found tool, and the array of remaining arguments
+    # that are not part of the tool name and should be passed as tool args.
+    #
     # @param [String] args Command line arguments
-    # @return [Toys::Tool]
+    # @return [Array(Toys::Tool,Array<String>)]
     #
     def lookup(args)
       orig_prefix = args.take_while { |arg| !arg.start_with?("-") }
@@ -99,12 +103,17 @@ module Toys
         p = orig_prefix.dup
         while p.length >= cur_prefix.length
           tool = get_tool(p, [])
-          return tool if tool
+          if tool
+            finish_definitions_in_tree(tool.full_name)
+            return [tool, args.slice(p.length..-1)]
+          end
           p.pop
         end
         break unless cur_prefix.pop
       end
-      get_or_create_tool([])
+      tool = get_or_create_tool([])
+      finish_definitions_in_tree([])
+      [tool, args]
     end
 
     ##
@@ -133,19 +142,35 @@ module Toys
     end
 
     ##
-    # Execute the tool given by the given arguments, in the given context.
+    # Returns true if the given path has at least one subtool. Loads from the
+    # configuration if necessary.
     #
-    # @param [Toys::Context::Base] context_base The context in which to
-    #     execute.
-    # @param [String] args Command line arguments
-    # @param [Integer] verbosity Starting verbosity. Defaults to 0.
-    # @return [Integer] The exit code
+    # @param [Array<String>] words The name of the parent tool
+    # @return [Boolean]
     #
-    # @private
+    def has_subtools?(words)
+      load_for_prefix(words)
+      len = words.length
+      @tools.each do |n, _tp|
+        return true if !n.empty? && n.length > len && n.slice(0, len) == words
+      end
+      false
+    end
+
+    ##
+    # Finishes all tool definitions under the given path. This generally means
+    # installing middleware.
+    #
+    # @param [Array<String>] words The path to the tool under which all
+    #     definitions should be finished.
     #
-    def execute(context_base, args, verbosity: 0)
-      tool = lookup(args)
-      tool.execute(context_base, args.slice(tool.full_name.length..-1), verbosity: verbosity)
+    def finish_definitions_in_tree(words)
+      load_for_prefix(words)
+      len = words.length
+      @tools.each do |n, tp|
+        next if n.length < len || n.slice(0, len) != words
+        tp.first.finish_definition(self) unless tp.first.is_a?(Alias)
+      end
     end
 
     ##
@@ -351,7 +376,7 @@ module Toys
           raise LoaderError, "Cannot read directory #{path}"
         end
       else
-        raise ArgumentError, "Illegal type #{type}"
+        raise ::ArgumentError, "Illegal type #{type}"
       end
       path
     end

data/lib/toys/middleware.rb

@@ -40,11 +40,11 @@ module Toys
       #
       # Currently recognized middleware names are:
       #
-      # *  `:add_verbosity_switches` : Adds switches for affecting verbosity.
+      # *  `:add_verbosity_flags` : Adds flags for affecting verbosity.
       # *  `:handle_usage_errors` : Displays the usage error if one occurs.
       # *  `:set_default_descriptions` : Sets default descriptions for tools
       #    that do not have them set explicitly.
-      # *  `:show_usage` : Teaches tools to print their usage documentation.
+      # *  `:show_help` : Teaches tools to print their usage documentation.
       # *  `:show_version` : Teaches tools to print their version.
       #
       # @param [String,Symbol] name Name of the middleware class to return
@@ -90,31 +90,31 @@ module Toys
       end
 
       ##
-      # Resolves a typical switches specification. Used often in middleware.
+      # Resolves a typical flags specification. Used often in middleware.
       #
-      # You may provide any of the following for the `switches` parameter:
-      # *  A string, which becomes the single switch
+      # You may provide any of the following for the `flags` parameter:
+      # *  A string, which becomes the single flag
       # *  An array of strings
-      # *  The value `false` or `nil` which resolves to no switches
+      # *  The value `false` or `nil` which resolves to no flags
       # *  The value `true` or `:default` which resolves to the given defaults
       # *  A proc that takes a tool as argument and returns any of the above.
       #
-      # Always returns an array of switch strings, even if empty.
+      # Always returns an array of flag strings, even if empty.
       #
-      # @param [Boolean,String,Array<String>,Proc] switches Switch spec
+      # @param [Boolean,String,Array<String>,Proc] flags Flag spec
       # @param [Toys::Tool] tool The tool
       # @param [Array<String>] defaults The defaults to use for `true`.
-      # @return [Array<String>] An array of switches
+      # @return [Array<String>] An array of flags
       #
-      def resolve_switches_spec(switches, tool, defaults)
-        switches = switches.call(tool) if switches.respond_to?(:call)
-        case switches
+      def resolve_flags_spec(flags, tool, defaults)
+        flags = flags.call(tool) if flags.respond_to?(:call)
+        case flags
         when true, :default
           Array(defaults)
         when ::String
-          [switches]
+          [flags]
         when ::Array
-          switches
+          flags
         else
           []
         end

data/lib/toys/middleware/add_verbosity_flags.rb

@@ -0,0 +1,113 @@
+# Copyright 2018 Daniel Azuma
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+;
+
+require "toys/middleware/base"
+
+module Toys
+  module Middleware
+    ##
+    # A middleware that provides flags for editing the verbosity.
+    #
+    # This middleware adds `-v`, `--verbose`, `-q`, and `--quiet` flags, if
+    # not already defined by the tool. These flags affect the setting of
+    # {Toys::Context::VERBOSITY}, and, thus, the logger level.
+    #
+    class AddVerbosityFlags < Base
+      ##
+      # Default verbose flags
+      # @return [Array<String>]
+      #
+      DEFAULT_VERBOSE_FLAGS = ["-v", "--verbose"].freeze
+
+      ##
+      # Default quiet flags
+      # @return [Array<String>]
+      #
+      DEFAULT_QUIET_FLAGS = ["-q", "--quiet"].freeze
+
+      ##
+      # Create a AddVerbosityFlags middleware.
+      #
+      # @param [Boolean,Array<String>,Proc] verbose_flags Specify flags
+      #     to increase verbosity. The value may be any of the following:
+      #     *  An array of flags that increase verbosity.
+      #     *  The `true` value to use {DEFAULT_VERBOSE_FLAGS}. (Default)
+      #     *  The `false` value to disable verbose flags.
+      #     *  A proc that takes a tool and returns any of the above.
+      # @param [Boolean,Array<String>,Proc] quiet_flags Specify flags
+      #     to decrease verbosity. The value may be any of the following:
+      #     *  An array of flags that decrease verbosity.
+      #     *  The `true` value to use {DEFAULT_QUIET_FLAGS}. (Default)
+      #     *  The `false` value to disable quiet flags.
+      #     *  A proc that takes a tool and returns any of the above.
+      #
+      def initialize(verbose_flags: true, quiet_flags: true)
+        @verbose_flags = verbose_flags
+        @quiet_flags = quiet_flags
+      end
+
+      ##
+      # Configure the tool flags.
+      #
+      def config(tool, _loader)
+        add_verbose_flags(tool)
+        add_quiet_flags(tool)
+        yield
+      end
+
+      private
+
+      def add_verbose_flags(tool)
+        verbose_flags = Middleware.resolve_flags_spec(@verbose_flags, tool,
+                                                      DEFAULT_VERBOSE_FLAGS)
+        unless verbose_flags.empty?
+          long_desc = "Increase verbosity, causing additional logging levels to display."
+          tool.add_flag(Context::VERBOSITY, *verbose_flags,
+                        desc: "Increase verbosity",
+                        long_desc: long_desc,
+                        handler: ->(_val, cur) { cur + 1 },
+                        only_unique: true)
+        end
+      end
+
+      def add_quiet_flags(tool)
+        quiet_flags = Middleware.resolve_flags_spec(@quiet_flags, tool,
+                                                    DEFAULT_QUIET_FLAGS)
+        unless quiet_flags.empty?
+          long_desc = "Decrease verbosity, causing fewer logging levels to display."
+          tool.add_flag(Context::VERBOSITY, *quiet_flags,
+                        desc: "Decrease verbosity",
+                        long_desc: long_desc,
+                        handler: ->(_val, cur) { cur - 1 },
+                        only_unique: true)
+        end
+      end
+    end
+  end
+end