toys-core 0.9.4 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13ebab12cc43b3347b2a350bda3b376cd22d86b61f29551146698acf7aff0725
-  data.tar.gz: 9185077682bbc7cf674efc5f83a1cb8ee76f8b87d8d72a35d884f82da5bde38d
+  metadata.gz: 3a9f077375706e67827afa561f71081c121d0eb00c30be6586501e6c76ab47c5
+  data.tar.gz: 305e31b023d22f687a2406efdd0cea377a1c9725626c8320cebbf013b10f145b
 SHA512:
-  metadata.gz: 412c26dfba427a00e499779fe7edfcbceea0c1579e83953eb9474bf72544842b3fc33f7ffb98ca7cb9a8a935f3b0886d6a55bf593ca964610ba8b4f988fd1f9c
-  data.tar.gz: d07b2d164ad561cd260145dd768c434ea175c139c0b187438ae4396231f7b46ed2e293fa2594ac7629490d8b6e840c3fde111c425364862652a46e1e0265a901
+  metadata.gz: 661b472175296ea3224e3dee08902ca8b2bf04e78f949109a91f4fa471c0b7904a454e0b18e845cf46d8cf04458872c84f55fd3f43bcbb2f3ecd40478783b8a5
+  data.tar.gz: f9761ab43fffd295af8629906ae3fdee621c42d5df49a92b3539cc68a9588546338a4fdd3a70459639c3127c261de443c5f2359778807d281b451b4c2655316a

data/.yardopts

@@ -3,7 +3,8 @@
 --markup=markdown
 --markup-provider redcarpet
 --main=README.md
-./lib/**/*.rb
+./lib/toys/**/*.rb
+./lib/toys-core.rb
 -
 README.md
 LICENSE.md

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Release History
 
+### 0.10.0 / 2020-02-24
+
+Functional changes:
+
+* ADDED: `:bundler` mixin that installs and sets up a bundle for the tool
+* ADDED: `bundle` method to `Toys::Utils::Gems` that performs bundler install and setup
+* ADDED: `subtool_apply` directive which applies a block to all subtools.
+* ADDED: Add `.lib` directories to the Ruby load path when executing a tool.
+* ADDED: `toys_version?` and `toys_version!` directives that check against version requirements.
+* ADDED: `exec_separate_tool` and `capture_separate_tool` methods in the `:exec` mixin, to support executing tools in a separate process without forking
+* IMPROVED: `long_desc` directive can now read the description from a text file.
+* IMPROVED: The `tool` directive can take delimited strings as tool names.
+* IMPROVED: Subtool blocks aren't actually executed unless the tool is needed.
+* CHANGED: Added `on_missing` and `on_conflict` arguments to `Toys::Utils::Gems` constructor (which also affects the `:gems` mixin), and deprecated `suppress_confirm` and `default_confirm`.
+
+Internal interface changes:
+
+* ADDED: `Toys::Tool#subtool_middleware_stack` allowing a tool to modify the middleware stack for its subtools.
+* ADDED: The `Toys::Middleware::Stack` class represents a stack of middleware specs, and distinguishes the default set from those added afterward.
+* ADDED: `Toys.executable_path` attribute allowing an executable to provide the executable for running tools separately.
+* ADDED: `Toys::CLI` now has a `logger_factory` property, to generate separate loggers per tool execution.
+* ADDED: `Toys::CLI` and `Toys::Loader` now let you set `:lib_dir_name`.
+* IMPROVED: Toys-core no longer has a general dependency on rubygems. (Parts that do depend on rubygems, such as the `:gems` mixin, do an explicit `require "rubygems"`.) This makes it possible to write an executable with `ruby --disable=gems` which improves startup time.
+* IMPROVED: Middleware objects no longer have to respond to all middleware methods. If a method is not implemented, it is simply considered a nop.
+* IMPROVED: `Toys::Utils::Terminal` is now thread-safe.
+* CHANGED: `Toys::Utils::Terminal#styled` is no longer mutable.
+* CHANGED: `Toys::Tool#middleware_stack` renamed to `Toys::Tool#built_middleware` to clarify that it is an array of middleware objects rather than specs.
+* CHANGED: `Toys::CLI.default_logger` removed and replaced with `Toys::CLI.default_logger_factory`. In general, global loggers for CLI are now discouraged because they are not thread-safe.
+* CHANGED: `Toys::Loader` uses an internal monitor rather than including `MonitorMixin`.
+
 ### 0.9.4 / 2020-01-26
 
 * FIXED: Crash in the loader when a non-ruby file appears in a toys directory

data/LICENSE.md

@@ -1,6 +1,6 @@
 # License
 
-Copyright 2019 Daniel Azuma
+Copyright 2019-2020 Daniel Azuma and the Toys contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -74,7 +74,7 @@ use to write Toys files. You could point your executable at a directory
 containing actual Toys files, but the simplest option is to provide the
 information to the Toys CLI object in a block.
 
-Let's add some functionality. 
+Let's add some functionality.
 
     #!/usr/bin/env ruby
 
@@ -150,7 +150,7 @@ available tools.
     $ ./mycmd
 
 Notice that the description set at the "root" of the config block (outside the
-tool blocks) shows up here.     
+tool blocks) shows up here.
 
 ### Configuring the CLI
 
@@ -338,7 +338,7 @@ templates, and middleware, in the
 
 ## License
 
-Copyright 2019 Daniel Azuma
+Copyright 2019-2020 Daniel Azuma and the Toys contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/toys-core.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 ##
 # 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
@@ -68,6 +47,17 @@ module Toys
   # `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
 
 require "toys/acceptor"

data/lib/toys/acceptor.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   ##
   # An Acceptor validates and converts arguments. It is designed to be

data/lib/toys/arg_parser.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   ##
   # An internal class that parses command line arguments for a tool.
@@ -444,7 +423,7 @@ module Toys
         Context::Key::ARGS => nil,
         Context::Key::CLI => cli,
         Context::Key::CONTEXT_DIRECTORY => tool.context_directory,
-        Context::Key::LOGGER => cli.logger,
+        Context::Key::LOGGER => cli.logger_factory.call(tool),
         Context::Key::TOOL => tool,
         Context::Key::TOOL_SOURCE => tool.source_info,
         Context::Key::TOOL_NAME => tool.full_name,

data/lib/toys/cli.rb

@@ -1,26 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
+require "rbconfig"
 require "logger"
 require "toys/completion"
 
@@ -71,7 +51,8 @@ module Toys
     # roughly into four categories:
     #
     #  *  Options affecting output behavior:
-    #      *  `logger`: The logger
+    #      *  `logger`: A global logger for all tools to use
+    #      *  `logger_factory`: A proc that returns a logger to use
     #      *  `base_level`: The default log level
     #      *  `error_handler`: Callback for handling exceptions
     #      *  `executable_name`: The name of the executable
@@ -91,10 +72,17 @@ module Toys
     #      *  `preload_dir_name`: Name of preload directories in tool directories
     #      *  `data_dir_name`: Name of data directories in tool directories
     #
-    # @param logger [Logger] The logger to use.
-    #     Optional. If not provided, will use a default logger that writes
-    #     formatted output to `STDERR`, as defined by
-    #     {Toys::CLI.default_logger}.
+    # @param logger [Logger] A global logger to use for all tools. This may be
+    #     set if the CLI will call at most one tool at a time. However, it will
+    #     behave incorrectly if CLI might run multiple tools at the same time
+    #     with different verbosity settings (since the logger cannot have
+    #     multiple level settings simultaneously). In that case, do not set a
+    #     global logger, but use the `logger_factory` parameter instead.
+    # @param logger_factory [Proc] A proc that takes a {Toys::Tool} as an
+    #     argument, and returns a `Logger` to use when running that tool.
+    #     Optional. If not provided (and no global logger is set), CLI will use
+    #     a default factory that writes generates loggers writing formatted
+    #     output to `STDERR`, as defined by {Toys::CLI.default_logger_factory}.
     # @param base_level [Integer] The logger level that should correspond
     #     to zero verbosity.
     #     Optional. If not provided, defaults to the current level of the
@@ -181,13 +169,31 @@ module Toys
     #     path for any tool file in that directory.
     #     Optional. If not provided, data directories are disabled.
     #     Note: the standard toys executable sets this to `".data"`.
-    #
-    def initialize(
-      executable_name: nil, middleware_stack: nil, extra_delimiters: "",
-      config_dir_name: nil, config_file_name: nil, index_file_name: nil,
-      preload_file_name: nil, preload_dir_name: nil, data_dir_name: nil,
-      mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil,
-      logger: nil, base_level: nil, error_handler: nil, completion: nil
+    # @param lib_dir_name [String] A directory with this name that appears in
+    #     any configuration directory is added to the Ruby load path when
+    #     executing any tool file in that directory.
+    #     Optional. If not provided, lib directories are disabled.
+    #     Note: the standard toys executable sets this to `".lib"`.
+    #
+    def initialize( # rubocop:disable Metrics/MethodLength
+      executable_name: nil,
+      middleware_stack: nil,
+      extra_delimiters: "",
+      config_dir_name: nil,
+      config_file_name: nil,
+      index_file_name: nil,
+      preload_file_name: nil,
+      preload_dir_name: nil,
+      data_dir_name: nil,
+      lib_dir_name: nil,
+      mixin_lookup: nil,
+      middleware_lookup: nil,
+      template_lookup: nil,
+      logger_factory: nil,
+      logger: nil,
+      base_level: nil,
+      error_handler: nil,
+      completion: nil
     )
       @executable_name = executable_name || ::File.basename($PROGRAM_NAME)
       @middleware_stack = middleware_stack || CLI.default_middleware_stack
@@ -196,8 +202,9 @@ module Toys
       @template_lookup = template_lookup || CLI.default_template_lookup
       @error_handler = error_handler || DefaultErrorHandler.new
       @completion = completion || DefaultCompletion.new
-      @logger = logger || CLI.default_logger
-      @base_level = base_level || @logger.level
+      @logger = logger
+      @logger_factory = logger ? proc { logger } : logger_factory || CLI.default_logger_factory
+      @base_level = base_level
       @extra_delimiters = extra_delimiters
       @config_dir_name = config_dir_name
       @config_file_name = config_file_name
@@ -205,12 +212,18 @@ module Toys
       @preload_file_name = preload_file_name
       @preload_dir_name = preload_dir_name
       @data_dir_name = data_dir_name
+      @lib_dir_name = lib_dir_name
       @loader = Loader.new(
-        index_file_name: @index_file_name, extra_delimiters: @extra_delimiters,
-        preload_dir_name: @preload_dir_name, preload_file_name: @preload_file_name,
+        index_file_name: @index_file_name,
+        preload_dir_name: @preload_dir_name,
+        preload_file_name: @preload_file_name,
         data_dir_name: @data_dir_name,
-        mixin_lookup: @mixin_lookup, template_lookup: @template_lookup,
-        middleware_lookup: @middleware_lookup, middleware_stack: @middleware_stack
+        lib_dir_name: @lib_dir_name,
+        middleware_stack: @middleware_stack,
+        extra_delimiters: @extra_delimiters,
+        mixin_lookup: @mixin_lookup,
+        template_lookup: @template_lookup,
+        middleware_lookup: @middleware_lookup
       )
     end
 
@@ -235,12 +248,14 @@ module Toys
         preload_dir_name: @preload_dir_name,
         preload_file_name: @preload_file_name,
         data_dir_name: @data_dir_name,
+        lib_dir_name: @lib_dir_name,
         middleware_stack: @middleware_stack,
         extra_delimiters: @extra_delimiters,
         mixin_lookup: @mixin_lookup,
         middleware_lookup: @middleware_lookup,
         template_lookup: @template_lookup,
         logger: @logger,
+        logger_factory: @logger_factory,
         base_level: @base_level,
         error_handler: @error_handler,
         completion: @completion,
@@ -269,14 +284,21 @@ module Toys
     attr_reader :extra_delimiters
 
     ##
-    # The logger used by this CLI.
-    # @return [Logger]
+    # The global logger, if any.
+    # @return [Logger,nil]
     #
     attr_reader :logger
 
+    ##
+    # The logger factory.
+    # @return [Proc]
+    #
+    attr_reader :logger_factory
+
     ##
     # The initial logger level in this CLI, used as the level for verbosity 0.
-    # @return [Integer]
+    # May be `nil`, indicating it will use the initial logger setting.
+    # @return [Integer,nil]
     #
     attr_reader :base_level
 
@@ -432,19 +454,22 @@ module Toys
                                  require_exact_flag_match: tool.exact_flag_match_required?)
       arg_parser.parse(args).finish
       context = tool.tool_class.new(arg_parser.data)
+      tool.source_info&.apply_lib_paths
       tool.run_initializers(context)
 
-      cur_logger = logger
-      original_level = cur_logger.level
-      cur_logger.level = base_level - context[Context::Key::VERBOSITY]
+      cur_logger = context[Context::Key::LOGGER]
+      if cur_logger
+        original_level = cur_logger.level
+        cur_logger.level = (base_level || original_level) - context[Context::Key::VERBOSITY].to_i
+      end
       begin
-        perform_execution(context, tool)
+        execute_tool_in_context(context, tool)
       ensure
-        cur_logger.level = original_level
+        cur_logger.level = original_level if cur_logger
       end
     end
 
-    def perform_execution(context, tool)
+    def execute_tool_in_context(context, tool)
       executor = proc do
         begin
           if !context[Context::Key::USAGE_ERRORS].empty?
@@ -459,7 +484,7 @@ module Toys
           handle_interrupt(context, tool.interrupt_handler, e)
         end
       end
-      tool.middleware_stack.reverse_each do |middleware|
+      tool.built_middleware.reverse_each do |middleware|
         executor = make_executor(middleware, context, executor)
       end
       catch(:result) do
@@ -493,7 +518,11 @@ module Toys
     end
 
     def make_executor(middleware, context, next_executor)
-      proc { middleware.run(context, &next_executor) }
+      if middleware.respond_to?(:run)
+        proc { middleware.run(context, &next_executor) }
+      else
+        next_executor
+      end
     end
 
     ##
@@ -646,30 +675,33 @@ module Toys
       end
 
       ##
-      # Returns a default logger that writes formatted logs to a given stream.
+      # Returns a logger factory that generates loggers that write to stderr.
+      # All loggers generated by this factory share a single
+      # {Toys::Utils::Terminal}, so log entries may interleave but will not
+      # interrupt one another.
       #
-      # @param output [IO] The stream to output to (defaults to `$stderr`)
-      # @return [Logger]
+      # @return [Proc]
       #
-      def default_logger(output: nil)
+      def default_logger_factory
         require "toys/utils/terminal"
-        output ||= $stderr
-        logger = ::Logger.new(output)
-        terminal = Utils::Terminal.new(output: output)
-        logger.formatter = proc do |severity, time, _progname, msg|
-          msg_str =
-            case msg
-            when ::String
-              msg
-            when ::Exception
-              "#{msg.message} (#{msg.class})\n" << (msg.backtrace || []).join("\n")
-            else
-              msg.inspect
-            end
-          format_log(terminal, time, severity, msg_str)
+        shared_terminal = Utils::Terminal.new(output: $stderr)
+        proc do
+          logger = ::Logger.new(shared_terminal)
+          logger.formatter = proc do |severity, time, _progname, msg|
+            msg_str =
+              case msg
+              when ::String
+                msg
+              when ::Exception
+                "#{msg.message} (#{msg.class})\n" << (msg.backtrace || []).join("\n")
+              else
+                msg.inspect
+              end
+            format_log(shared_terminal, time, severity, msg_str)
+          end
+          logger.level = ::Logger::WARN
+          logger
         end
-        logger.level = ::Logger::WARN
-        logger
       end
 
       private