toys 0.11.5 → 0.12.0

data/lib/toys/testing.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Toys
+  ##
+  # Helpers for writing tool tests.
+  #
+  # EXPERIMENTAL: Interfaces are subject to change.
+  #
+  module Testing
+    ##
+    # Returns the Toys CLI for this test class. By default, a single CLI and
+    # Loader are shared by all tests in a given class (or _describe_ block).
+    #
+    # @return [Toys::CLI]
+    #
+    def toys_cli
+      self.class.toys_cli
+    end
+
+    ##
+    # Runs the tool corresponding to the given command line, provided as an
+    # array of arguments, and returns a {Toys::Exec::Result}.
+    #
+    # 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}.
+    #
+    # @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.
+    #
+    def exec_tool(cmd, **opts, &block)
+      cli = opts.delete(: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)
+    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}.
+    #
+    # 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.
+    #
+    # 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`.
+    #
+    # @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.
+    #
+    def exec_separate_tool(cmd, **opts, &block)
+      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)
+    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}.
+    #
+    # @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.
+    #
+    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.
+    #
+    # Unlike {#capture_tool}, this method does not use "fork", and thus can be
+    # called in an environment such as JRuby or Ruby on Windows.
+    #
+    # @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.
+    #
+    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:
+    #
+    #     out: :controller,
+    #     err: :controller,
+    #     in: :controller,
+    #     background: block.nil?
+    #
+    # 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.
+    #
+    # @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.
+    #
+    def control_tool(cmd, **opts, &block)
+      opts = opts.merge(out: :controller, err: :controller, in: :controller, background: block.nil?)
+      exec_tool(cmd, **opts, &block)
+    end
+
+    @toys_mutex = ::Mutex.new
+
+    # @private
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    # @private
+    def self.toys_mutex
+      @toys_mutex
+    end
+
+    # @private
+    module ClassMethods
+      # @private
+      def toys_cli
+        Testing.toys_mutex.synchronize do
+          @toys_cli ||= StandardCLI.new
+        end
+      end
+
+      # @private
+      def toys_exec
+        Testing.toys_mutex.synchronize do
+          require "toys/utils/exec"
+          @toys_exec ||= Utils::Exec.new
+        end
+      end
+    end
+  end
+end

data/lib/toys/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.11.5
+  version: 0.12.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-03-28 00:00:00.000000000 Z
+date: 2021-08-05 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.11.5
+        version: 0.12.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.11.5
+        version: 0.12.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
@@ -44,7 +44,9 @@ files:
 - README.md
 - bin/toys
 - builtins/do.rb
-- builtins/system.rb
+- builtins/system/bash-completion.rb
+- builtins/system/test.rb
+- builtins/system/update.rb
 - docs/guide.md
 - lib/toys.rb
 - lib/toys/standard_cli.rb
@@ -56,6 +58,7 @@ files:
 - lib/toys/templates/rspec.rb
 - lib/toys/templates/rubocop.rb
 - lib/toys/templates/yardoc.rb
+- lib/toys/testing.rb
 - lib/toys/version.rb
 - share/bash-completion-remove.sh
 - share/bash-completion.sh
@@ -63,10 +66,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.11.5/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.12.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.11.5
+  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.12.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -75,14 +78,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: A configurable command line tool

data/builtins/system.rb

@@ -1,152 +0,0 @@
-# frozen_string_literal: true
-
-desc "A set of system commands for Toys"
-
-long_desc "Contains tools that inspect, configure, and update Toys itself."
-
-tool "version" do
-  desc "Print the current Toys version"
-
-  def run
-    puts ::Toys::VERSION
-  end
-end
-
-tool "update" do
-  desc "Update Toys if a newer version is available"
-
-  long_desc "Checks rubygems for a newer version of Toys. If one is available, downloads" \
-            " and installs it."
-
-  flag :yes, "-y", "--yes", desc: "Do not ask for interactive confirmation"
-
-  include :exec
-  include :terminal
-
-  def run
-    require "rubygems"
-    configure_exec(exit_on_nonzero_status: true)
-    version_info = spinner(leading_text: "Checking rubygems for the latest release... ",
-                           final_text: "Done.\n") do
-      capture(["gem", "list", "-q", "-r", "-e", "toys"])
-    end
-    if version_info =~ /toys\s\((.+)\)/
-      latest_version = ::Gem::Version.new(::Regexp.last_match(1))
-      cur_version = ::Gem::Version.new(::Toys::VERSION)
-      if latest_version > cur_version
-        prompt = "Update Toys from #{cur_version} to #{latest_version}? "
-        exit(1) unless yes || confirm(prompt, default: true)
-        result = spinner(leading_text: "Installing Toys version #{latest_version}... ",
-                         final_text: "Done.\n") do
-          exec(["gem", "install", "toys", "--version", latest_version.to_s],
-               out: :capture, err: :capture)
-        end
-        if result.error?
-          puts(result.captured_out + result.captured_err)
-          puts("Toys failed to install version #{latest_version}", :red, :bold)
-          exit(1)
-        end
-        puts("Toys successfully installed version #{latest_version}", :green, :bold)
-      elsif latest_version < cur_version
-        puts("Toys is already at experimental version #{cur_version}, which is later than" \
-             " the latest released version #{latest_version}",
-             :yellow, :bold)
-      else
-        puts("Toys is already at the latest version: #{latest_version}", :green, :bold)
-      end
-    else
-      puts("Could not get latest Toys version", :red, :bold)
-      exit(1)
-    end
-  end
-end
-
-tool "bash-completion" do
-  desc "Bash tab completion for Toys"
-
-  long_desc \
-    "Tools that manage tab completion for Toys in the bash shell.",
-    "",
-    "To install tab completion for Toys, execute the following line in a bash shell, or" \
-      " include it in an init file such as your .bashrc:",
-    ["  $(toys system bash-completion install)"],
-    "",
-    "To remove tab completion, execute:",
-    ["  $(toys system bash-completion remove)"],
-    "",
-    "It is also possible to install completions for different executable names if you have" \
-      " aliases for Toys. See the help for the \"install\" and \"remove\" tools for details.",
-    "",
-    "The \"eval\" tool is the actual completion command invoked by bash when it needs to" \
-      " complete a toys command line. You shouldn't need to invoke it directly."
-
-  tool "eval" do
-    desc "Tab completion command (executed by bash)"
-
-    long_desc \
-      "Completion command invoked by bash to compete a toys command line. Generally you do not" \
-        " need to invoke this directly. It reads the command line context from the COMP_LINE" \
-        " and COMP_POINT environment variables, and outputs completion candidates to stdout."
-
-    disable_argument_parsing
-
-    def run
-      require "toys/utils/completion_engine"
-      result = ::Toys::Utils::CompletionEngine::Bash.new(cli).run
-      if result > 1
-        logger.fatal("This tool must be invoked as a bash completion command.")
-      end
-      exit(result)
-    end
-  end
-
-  tool "install" do
-    desc "Install bash tab completion"
-
-    long_desc \
-      "Outputs a command to set up Toys tab completion in the current bash shell.",
-      "",
-      "To use, execute the following line in a bash shell, or include it in an init file" \
-        " such as your .bashrc:",
-      ["  $(toys system bash-completion install)"],
-      "",
-      "This will associate the toys tab completion logic with the `toys` executable by default." \
-        " If you have aliases for the toys executable, pass them as arguments. e.g.",
-      ["  $(toys system bash-completion install my-toys-alias another-alias)"]
-
-    remaining_args :executable_names,
-                   desc: "Names of executables for which to set up tab completion" \
-                         " (default: #{::Toys::StandardCLI::EXECUTABLE_NAME})"
-
-    def run
-      require "shellwords"
-      path = ::File.join(::File.dirname(__dir__), "share", "bash-completion.sh")
-      exes = executable_names.empty? ? [::Toys::StandardCLI::EXECUTABLE_NAME] : executable_names
-      puts Shellwords.join(["source", path] + exes)
-    end
-  end
-
-  tool "remove" do
-    desc "Remove bash tab completion"
-
-    long_desc \
-      "Outputs a command to remove Toys tab completion from the current bash shell.",
-      "",
-      "To use, execute the following line in a bash shell:",
-      ["  $(toys system bash-completion remove)"],
-      "",
-      "If you have other names or aliases for the toys executable, pass them as arguments. e.g.",
-      ["  $(toys system bash-completion remove my-toys-alias another-alias)"]
-
-    remaining_args :executable_names,
-                   desc: "Names of executables for which to set up tab completion" \
-                         " (default: #{::Toys::StandardCLI::EXECUTABLE_NAME})"
-
-    def run
-      require "shellwords"
-      path = ::File.join(::File.dirname(__dir__), "share", "bash-completion-remove.sh")
-      exes = executable_names.empty? ? [::Toys::StandardCLI::EXECUTABLE_NAME] : executable_names
-      puts Shellwords.join(["source", path] + exes)
-    end
-  end
-end