toys 0.12.2 → 0.13.0

data/lib/toys/templates/yardoc.rb

@@ -326,67 +326,122 @@ module Toys
         self
       end
 
+      ##
       # @private
+      #
       attr_reader :generate_output
+
+      ##
       # @private
+      #
       attr_reader :generate_output_flag
+
+      ##
       # @private
+      #
       attr_reader :fail_on_warning
+
+      ##
       # @private
+      #
       attr_reader :fail_on_undocumented_objects
+
+      ##
       # @private
+      #
       attr_reader :show_public
+
+      ##
       # @private
+      #
       attr_reader :show_protected
+
+      ##
       # @private
+      #
       attr_reader :show_private
+
+      ##
       # @private
+      #
       attr_reader :hide_private_tag
+
+      ##
       # @private
+      #
       attr_reader :readme
+
+      ##
       # @private
+      #
       attr_reader :markup
+
+      ##
       # @private
+      #
       attr_reader :template
+
+      ##
       # @private
+      #
       attr_reader :template_path
+
+      ##
       # @private
+      #
       attr_reader :format
+
+      ##
       # @private
+      #
       attr_reader :context_directory
 
+      ##
       # @private
+      #
       def name
         @name || DEFAULT_TOOL_NAME
       end
 
+      ##
       # @private
+      #
       def gem_version
         return Array(@gem_version) if @gem_version
         @bundler ? [] : DEFAULT_GEM_VERSION_REQUIREMENTS
       end
 
+      ##
       # @private
+      #
       def files
         @files ? Array(@files) : DEFAULT_FILES
       end
 
+      ##
       # @private
+      #
       def output_dir
         @output_dir || DEFAULT_OUTPUT_DIR
       end
 
+      ##
       # @private
+      #
       def options
         Array(@options)
       end
 
+      ##
       # @private
+      #
       def stats_options
         Array(@stats_options)
       end
 
+      ##
       # @private
+      #
       def bundler_settings
         if @bundler && !@bundler.is_a?(::Hash)
           {}

data/lib/toys/testing.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "shellwords"
+
 module Toys
   ##
   # Helpers for writing tool tests.
@@ -18,174 +20,249 @@ module Toys
     end
 
     ##
-    # Runs the tool corresponding to the given command line, provided as an
-    # array of arguments, and returns a {Toys::Exec::Result}.
+    # Prepares the tool corresponding to the given command line, but instead of
+    # running it, yields the execution context to the given block. This can be
+    # used to test individual methods in a tool.
     #
     # By default, a single CLI is shared among the tests in each test class or
     # _describe_ block. Thus, tools are loaded only once, and the loader is
     # shared across the tests. If you need to isolate loading for a test,
     # create a separate CLI and pass it in using the `:cli` keyword argument.
     #
-    # All other keyword arguments are the same as those defined by the
-    # `Toys::Utils::Exec` class. If a block is given, a
-    # `Toys::Utils::Exec::Controller` is yielded to it. For more info, see the
-    # documentation for `Toys::Utils::Exec#exec`.
-    #
-    # This method uses "fork" to isolate the run of the tool. On an environment
-    # without "fork" support, such as JRuby or Ruby on Windows, consider
-    # {#exec_separate_tool}.
+    # Note: this method runs the given block in-process. This means you can
+    # test assertions within the block, but any input or output performed by
+    # the tool's methods that you call, will manifest during your test. If this
+    # is a problem, you might consider redirecting the standard streams when
+    # calling this method, for example by using
+    # [capture_subprocess_io](https://docs.seattlerb.org/minitest/Minitest/Assertions.html#method-i-capture_subprocess_io).
     #
     # @param cmd [String,Array<String>] The command to execute.
-    # @param opts [keywords] The command options.
-    # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-    #     for the subprocess streams.
+    # @yieldparam tool [Toys::Context] The tool context.
+    # @return [Object] The value returned from the block.
+    #
+    # @example
+    #   # Given the following tool:
+    #
+    #   tool "hello" do
+    #     flag :shout
+    #     def run
+    #       puts message
+    #     end
+    #     def message
+    #       shout ? "HELLO" : "hello"
+    #     end
+    #   end
+    #
+    #   # You can test the `message` method as follows:
     #
-    # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
-    #     the process is running in the background.
-    # @return [Toys::Utils::Exec::Result] The result, if the process ran in
-    #     the foreground.
+    #   class MyTest < Minitest::Test
+    #     include Toys::Testing
+    #     def test_message_without_shout
+    #       toys_load_tool(["hello"]) do |tool|
+    #         assert_equal("hello", tool.message)
+    #       end
+    #     end
+    #     def test_message_with_shout
+    #       toys_load_tool(["hello", "--shout"]) do |tool|
+    #         assert_equal("HELLO", tool.message)
+    #       end
+    #     end
+    #   end
     #
-    def exec_tool(cmd, **opts, &block)
-      cli = opts.delete(:cli) || toys_cli
+    def toys_load_tool(cmd, cli: nil, &block)
+      cli ||= toys_cli
       cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
-      cli.loader.lookup(cmd)
-      tool_caller = proc { ::Kernel.exit(cli.run(*cmd)) }
-      self.class.toys_exec.exec_proc(tool_caller, **opts, &block)
+      cli.load_tool(*cmd, &block)
     end
 
     ##
-    # Runs the tool corresponding to the given command line, provided as an
-    # array of arguments, in a separately spawned process, and returns a
-    # {Toys::Exec::Result}.
+    # Runs the tool corresponding to the given command line, in-process, and
+    # returns the result code.
     #
-    # Unlike {#exec_tool}, this method does not use the shared CLI, but instead
-    # spawns a completely new Toys process for each run. It is thus slower than
-    # {#exec_tool}, but compatible with environments without "fork" support,
-    # such as JRuby or Ruby on Windows.
+    # By default, a single CLI is shared among the tests in each test class or
+    # _describe_ block. Thus, tools are loaded only once, and the loader is
+    # shared across the tests. If you need to isolate loading for a test,
+    # create a separate CLI and pass it in using the `:cli` keyword argument.
     #
-    # Supported keyword arguments are the same as those defined by the
-    # `Toys::Utils::Exec` class. If a block is given, a
-    # `Toys::Utils::Exec::Controller` is yielded to it. For more info, see the
-    # documentation for `Toys::Utils::Exec#exec`.
+    # Note: This method runs the tool in-process. This is often faster than
+    # running it in a separate process with {#toys_exec_tool}, but it also
+    # means any input or output performed by the tool, will manifest during
+    # your test. If this is a problem, you might consider redirecting the
+    # standard streams when calling this method, for example by using
+    # [capture_subprocess_io](https://docs.seattlerb.org/minitest/Minitest/Assertions.html#method-i-capture_subprocess_io).
     #
     # @param cmd [String,Array<String>] The command to execute.
-    # @param opts [keywords] The command options.
-    # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-    #     for the subprocess streams.
-    #
-    # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
-    #     the process is running in the background.
-    # @return [Toys::Utils::Exec::Result] The result, if the process ran in
-    #     the foreground.
+    # @return [Integer] The integer result code (i.e. 0 for success).
     #
-    def exec_separate_tool(cmd, **opts, &block)
+    def toys_run_tool(cmd, cli: nil)
+      cli ||= toys_cli
       cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
-      cmd = [::RbConfig.ruby, "--disable=gems", ::Toys.executable_path] + cmd
-      self.class.toys_exec.exec(cmd, **opts, &block)
+      cli.run(*cmd)
     end
 
     ##
-    # Runs the tool corresponding to the given command line, and returns the
-    # data written to `STDOUT`. This is equivalent to calling {#exec_tool}
-    # with the keyword arguments `out: :capture, background: false`, and
-    # calling `#captured_out` on the result.
-    #
-    # Note: this method uses "fork" to execute the tool. If you are using an
-    # environment without "fork" support, such as JRuby oor Ruby on Windows,
-    # consider {#capture_separate_tool}.
+    # Runs the tool corresponding to the given command line, in a separate
+    # forked process, and returns a {Toys::Exec::Result}. You can either
+    # provide a block to control the process, or simply let it run and capture
+    # its output.
     #
-    # @param cmd [String,Array<String>] The command to execute.
-    # @param opts [keywords] The command options.
-    # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-    #     for the subprocess streams.
-    #
-    # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
-    #     the process is running in the background.
-    # @return [Toys::Utils::Exec::Result] The result, if the process ran in
-    #     the foreground.
+    # By default, a single CLI is shared among the tests in each test class or
+    # _describe_ block. Thus, tools are loaded only once, and the loader is
+    # shared across the tests. If you need to isolate loading for a test,
+    # create a separate CLI and pass it in using the `:cli` keyword argument.
     #
-    def capture_tool(cmd, **opts, &block)
-      opts = opts.merge(out: :capture, background: false)
-      exec_tool(cmd, **opts, &block).captured_out
-    end
-
-    ##
-    # Runs the tool corresponding to the given command line, and returns the
-    # data written to `STDOUT`. This is equivalent to calling
-    # {#exec_separate_tool} with the keyword arguments
-    # `out: :capture, background: false`, and calling `#captured_out` on the
-    # result.
+    # All other keyword arguments are the same as those defined by the
+    # {Toys::Utils::Exec} class. If a block is given, all streams are directed
+    # to a {Toys::Utils::Exec::Controller} which is yielded to the block. If no
+    # block is given, the output and error streams are captured and the input
+    # stream is closed.
     #
-    # Unlike {#capture_tool}, this method does not use "fork", and thus can be
-    # called in an environment such as JRuby or Ruby on Windows.
+    # This method uses "fork" to isolate the run of the tool. It will not work
+    # on environments such as JRuby or Ruby on Windows that do not support
+    # process forking.
     #
     # @param cmd [String,Array<String>] The command to execute.
     # @param opts [keywords] The command options.
     # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
     #     for the subprocess streams.
+    # @return [Toys::Utils::Exec::Result] The process result.
     #
-    # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
-    #     the process is running in the background.
-    # @return [Toys::Utils::Exec::Result] The result, if the process ran in
-    #     the foreground.
-    #
-    def capture_separate_tool(cmd, **opts, &block)
-      opts = opts.merge(out: :capture, background: false)
-      exec_separate_tool(cmd, **opts, &block).captured_out
-    end
-
-    ##
-    # Runs the tool corresponding to the given command line, managing streams
-    # using a controller. This is equivalent to calling {#exec_tool} with the
-    # keyword arguments:
+    # @example
+    #   # Given the following tool:
     #
-    #     out: :controller,
-    #     err: :controller,
-    #     in: :controller,
-    #     background: block.nil?
+    #   tool "hello" do
+    #     flag :shout
+    #     def run
+    #       puts message
+    #     end
+    #     def message
+    #       shout ? "HELLO" : "hello"
+    #     end
+    #   end
     #
-    # If a block is given, the command is run in the foreground, the
-    # controller is passed to the block during the run, and a result object is
-    # returned. If no block is given, the command is run in the background, and
-    # the controller object is returned.
+    #   # You can test the tool's output as follows:
     #
-    # @param cmd [String,Array<String>] The command to execute.
-    # @param opts [keywords] The command options.
-    # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-    #     for the subprocess streams.
+    #   class MyTest < Minitest::Test
+    #     include Toys::Testing
+    #     def test_output_without_shout
+    #       result = toys_exec_tool(["hello"])
+    #       assert_equal("hello hello\n", result.captured_out)
+    #     end
+    #     def test_with_shout
+    #       result = toys_exec_tool(["hello", "--shout"])
+    #       assert_equal("HELLO HELLO\n", result.captured_out)
+    #     end
+    #   end
     #
-    # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
-    #     the process is running in the background.
-    # @return [Toys::Utils::Exec::Result] The result, if the process ran in
-    #     the foreground.
-    #
-    def control_tool(cmd, **opts, &block)
-      opts = opts.merge(out: :controller, err: :controller, in: :controller, background: block.nil?)
-      exec_tool(cmd, **opts, &block)
+    def toys_exec_tool(cmd, cli: nil, **opts, &block)
+      cli ||= toys_cli
+      cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
+      opts =
+        if block
+          {
+            out: :controller,
+            err: :controller,
+            in: :controller,
+          }.merge(opts)
+        else
+          {
+            out: :capture,
+            err: :capture,
+            in: :close,
+          }.merge(opts)
+        end
+      cli.loader.lookup(cmd)
+      tool_caller = proc { ::Kernel.exit(cli.run(*cmd)) }
+      self.class.toys_exec.exec_proc(tool_caller, **opts, &block)
     end
+    alias exec_tool toys_exec_tool
 
     @toys_mutex = ::Mutex.new
 
+    ##
     # @private
+    #
     def self.included(klass)
       klass.extend(ClassMethods)
     end
 
+    ##
     # @private
+    #
     def self.toys_mutex
       @toys_mutex
     end
 
+    ##
     # @private
+    #
+    def self.toys_custom_paths(paths = :read)
+      @toys_custom_paths = paths unless paths == :read
+      @toys_custom_paths
+    end
+
+    ##
+    # @private
+    #
+    def self.toys_include_builtins(value = :read)
+      @toys_include_builtins = value unless value == :read
+      @toys_include_builtins
+    end
+
+    @toys_custom_paths = nil
+    @toys_include_builtins = true
+
+    ##
+    # Class methods added to a test class or describe block when
+    # {Toys::Testing} is included. Generally, these are methods that configure
+    # the load path for the CLI in scope for the block.
+    #
     module ClassMethods
+      ##
+      # Configure the Toys CLI to load tools from the given paths, and ignore
+      # the current directory and global paths.
+      #
+      # @param paths [String,Array<String>] The paths to load from.
+      #
+      def toys_custom_paths(paths = :read)
+        @toys_custom_paths = paths unless paths == :read
+        return @toys_custom_paths if defined?(@toys_custom_paths)
+        begin
+          super
+        rescue ::NoMethodError
+          Testing.toys_custom_paths
+        end
+      end
+
+      ##
+      # Configure the Toys CLI to include or exclude builtins. Normally
+      # builtins are included unless false is passed to this method.
+      #
+      # @param value [boolean] Whether to include builtins.
+      #
+      def toys_include_builtins(value = :read)
+        @toys_include_builtins = value unless value == :read
+        return @toys_include_builtins if defined?(@toys_include_builtins)
+        begin
+          super
+        rescue ::NoMethodError
+          Testing.toys_include_builtins
+        end
+      end
+
+      ##
       # @private
+      #
       def toys_cli
         Testing.toys_mutex.synchronize do
-          @toys_cli ||= StandardCLI.new
+          @toys_cli ||= StandardCLI.new(custom_paths: toys_custom_paths,
+                                        include_builtins: toys_include_builtins)
         end
       end
 
+      ##
       # @private
+      #
       def toys_exec
         Testing.toys_mutex.synchronize do
           require "toys/utils/exec"

data/lib/toys/version.rb

@@ -5,5 +5,5 @@ module Toys
   # Current version of the Toys command line executable.
   # @return [String]
   #
-  VERSION = "0.12.2"
+  VERSION = "0.13.0"
 end

data/lib/toys.rb

@@ -6,7 +6,7 @@ require "toys/version"
 # environment variable explicitly, but in production, we get it from rubygems.
 # We prepend to $LOAD_PATH directly rather than calling Kernel.gem, so that we
 # don't get clobbered in case someone sets up bundler later.
-::ENV["TOYS_CORE_LIB_PATH"] ||= begin
+unless ::ENV.key?("TOYS_CORE_LIB_PATH")
   path = ::File.expand_path("../../toys-core-#{::Toys::VERSION}/lib", __dir__)
   unless path && ::File.directory?(path)
     require "rubygems"
@@ -14,7 +14,7 @@ require "toys/version"
     path = dep.to_spec.full_require_paths.first
   end
   abort "Unable to find toys-core gem!" unless path && ::File.directory?(path)
-  path
+  ::ENV.store("TOYS_CORE_LIB_PATH", path)
 end
 
 $LOAD_PATH.delete(::ENV["TOYS_CORE_LIB_PATH"])
@@ -39,7 +39,9 @@ module Toys
   #
   EXECUTABLE_PATH = ::ENV["TOYS_BIN_PATH"]
 
+  ##
   # @private
+  #
   LIB_PATH = __dir__
 
   ##

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.13.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-30 00:00:00.000000000 Z
+date: 2022-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: toys-core
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.12.2
+        version: 0.13.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.12.2
+        version: 0.13.0
 description: Toys is a configurable command line tool. Write commands in Ruby using
   a simple DSL, and Toys will provide the command line executable and take care of
   all the details such as argument parsing, online help, and error reporting. Toys
@@ -45,8 +45,58 @@ files:
 - bin/toys
 - builtins/do.rb
 - builtins/system/bash-completion.rb
+- builtins/system/git-cache.rb
 - builtins/system/test.rb
 - builtins/system/update.rb
+- core-docs/toys-core.rb
+- core-docs/toys/acceptor.rb
+- core-docs/toys/arg_parser.rb
+- core-docs/toys/cli.rb
+- core-docs/toys/compat.rb
+- core-docs/toys/completion.rb
+- core-docs/toys/context.rb
+- core-docs/toys/core.rb
+- core-docs/toys/dsl/base.rb
+- core-docs/toys/dsl/flag.rb
+- core-docs/toys/dsl/flag_group.rb
+- core-docs/toys/dsl/internal.rb
+- core-docs/toys/dsl/positional_arg.rb
+- core-docs/toys/dsl/tool.rb
+- core-docs/toys/errors.rb
+- core-docs/toys/flag.rb
+- core-docs/toys/flag_group.rb
+- core-docs/toys/input_file.rb
+- core-docs/toys/loader.rb
+- core-docs/toys/middleware.rb
+- core-docs/toys/mixin.rb
+- core-docs/toys/module_lookup.rb
+- core-docs/toys/positional_arg.rb
+- core-docs/toys/settings.rb
+- core-docs/toys/source_info.rb
+- core-docs/toys/standard_middleware/add_verbosity_flags.rb
+- core-docs/toys/standard_middleware/apply_config.rb
+- core-docs/toys/standard_middleware/handle_usage_errors.rb
+- core-docs/toys/standard_middleware/set_default_descriptions.rb
+- core-docs/toys/standard_middleware/show_help.rb
+- core-docs/toys/standard_middleware/show_root_version.rb
+- core-docs/toys/standard_mixins/bundler.rb
+- core-docs/toys/standard_mixins/exec.rb
+- core-docs/toys/standard_mixins/fileutils.rb
+- core-docs/toys/standard_mixins/gems.rb
+- core-docs/toys/standard_mixins/git_cache.rb
+- core-docs/toys/standard_mixins/highline.rb
+- core-docs/toys/standard_mixins/terminal.rb
+- core-docs/toys/standard_mixins/xdg.rb
+- core-docs/toys/template.rb
+- core-docs/toys/tool_definition.rb
+- core-docs/toys/utils/completion_engine.rb
+- core-docs/toys/utils/exec.rb
+- core-docs/toys/utils/gems.rb
+- core-docs/toys/utils/git_cache.rb
+- core-docs/toys/utils/help_text.rb
+- core-docs/toys/utils/terminal.rb
+- core-docs/toys/utils/xdg.rb
+- core-docs/toys/wrappable_string.rb
 - docs/guide.md
 - lib/toys.rb
 - lib/toys/standard_cli.rb
@@ -66,10 +116,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.12.2/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.13.0/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys/tree/main/toys
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.12.2
+  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.13.0
 post_install_message: 
 rdoc_options: []
 require_paths: