toys 0.11.5 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 063c28a7b9b7d3bc5f7ada761beb8623ff144b92847f2a9424889ca953d27cee
-  data.tar.gz: a1bcdb384d7592a0a43760aab7cd6da0e4afa4b6a1fd1ad59bb74ed6a6eeef73
+  metadata.gz: '091a51c34d19b918c203d88f0bbae74432343aae63a0ee7d62799fa30a1c8097'
+  data.tar.gz: 00e1a389cf5de2d5a85133a7ca148480e6885f2c80822fcfc4e9838d36d724a3
 SHA512:
-  metadata.gz: 50596ee8741422c0e186c7c2b63b52410a0afa1de04dfbea43e06acbf52c8b56f46c54c86471a80bae451c004d238ea94b58d666e7c39742de80bf9c95f95106
-  data.tar.gz: 1230cf4acb2414f378be58279a3017cd897a101a7c715e4db88394a8490fdb46dee7d0d9a617196698c034dddf3c6ac88b3855ba19262785dd4989dcf253d409
+  metadata.gz: 93b41a0886856f9665f3650596dba6fa4cb9a13c0a1c3fa040aed3b669382b86373e38d57bf3ac8bc0f90ed33a5094e2bcd4c89ea974ff98fc7dd5aebff5cb88
+  data.tar.gz: c83a1aa39ba8e3be2246aaa4bd8f6003b6c10d52e91beeb04ecc9082403b19e64fd5af7c0a04a8bd10c21d0f731bd63a0d8f3c0649163027fdc78429760553ef

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Release History
 
+### v0.12.0 / 2021-08-05
+
+Toys 0.12.0 is a major release with significant new features and bug fixes, and a few minor breaking changes. Additionally, this release now requires Ruby 2.4 or later.
+
+Breaking changes:
+
+* Defining a tool with whitespace, control characters, or certain punctuation in the name, now raises ToolDefinitionError.
+* The Toys::Tool class (for the object returned by the Toys::Context::Key::TOOL attribute) has been renamed to Toys::ToolDefinition so that the old name can be used for class-based tool definition.
+
+New functionality:
+
+* The DSL now supports a class-based tool definition syntax (in addition to the existing block-based syntax). Some users may prefer this new class-based style as more Ruby-like.
+* The subtool list on help screens is now split into sections by source directory
+* You can now load tools from a remote git repository using the load_git directive.
+* Whitespace is now automatically considered a name delimiter when defining tools.
+* There is experimental support for providing tests for tools.
+* There is now an extensible settings mechanism to activate less-common tool behavior. Currently there is one setting, which causes subtools to inherit their parent's methods by default.
+* The load directive can load into a new tool.
+* You can now set the context directory individually for the standard build tools.
+* Added a new standard mixin that provides XDG Base Directory information.
+* Added a new standard mixin that provides cached access to remote git repos.
+
+Fixes:
+
+* Fixed some bundler integration issues that occurred when the bundle is being installed in a separate path such as a vendor directory.
+* Exceptions raised from internal classes now include the full backtrace.
+
 ### v0.11.5 / 2021-03-28
 
 * BREAKING CHANGE: The exit_on_nonzero_status option to exec now exits on signals and failures to spawn, in addition to error codes.

data/README.md

@@ -50,7 +50,7 @@ Toys does not yet specially implement tab completion for zsh or other shells.
 However, if you are using zsh, installing bash completion using `bashcompinit`
 *mostly* works.
 
-Toys requires Ruby 2.3 or later.
+Toys requires Ruby 2.4 or later.
 
 Most parts of Toys work on JRuby. However, JRuby is not recommended because of
 JVM boot latency, lack of support for Kernel#fork, and other issues.

data/builtins/system/bash-completion.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+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(::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(::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

data/builtins/system/test.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+desc "Run tool tests"
+
+flag :directory, "-d", "--directory PATH",
+     desc: "Run tests from the given directory"
+flag :seed, "-s", "--seed SEED",
+     desc: "Sets random seed."
+flag :warnings, "-w", "--[no-]warnings",
+     default: true,
+     desc: "Turn on Ruby warnings (defaults to true)"
+flag :name, "-n", "--name PATTERN",
+     desc: "Filter run on /regexp/ or string."
+flag :exclude, "-e", "--exclude PATTERN",
+     desc: "Exclude /regexp/ or string from run."
+flag :recursive, "--[no-]recursive", default: true,
+     desc: "Recursively test subtools (default is true)"
+flag :tool, "-t TOOL", "--tool TOOL", default: "",
+     desc: "Run tests only for tools under the given path"
+
+include :exec
+include :gems
+include :terminal
+
+def run
+  gem "minitest", "~> 5.0"
+  ::Dir.chdir(tool_dir)
+  test_files = find_test_files
+  result = exec_ruby(ruby_args, in: :controller, log_cmd: "Starting minitest...") do |controller|
+    controller.in.puts("gem 'minitest', '~> 5.0'")
+    controller.in.puts("require 'minitest/autorun'")
+    controller.in.puts("require 'toys'")
+    controller.in.puts("require 'toys/testing'")
+    test_files.each do |file|
+      controller.in.puts("load '#{file}'")
+    end
+  end
+  if result.error?
+    logger.error("Minitest failed!")
+    exit(result.exit_code)
+  end
+end
+
+def find_test_files
+  glob = ".test/**/test_*.rb"
+  glob = "**/#{glob}" if recursive
+  test_files = ::Dir.glob(glob)
+  if test_files.empty?
+    logger.warn("No test files found")
+    exit
+  end
+  test_files.each do |file|
+    logger.info("Loading: #{file}")
+  end
+  test_files
+end
+
+def tool_dir
+  words = cli.loader.split_path(tool)
+  dir = base_dir
+  unless words.empty?
+    dir = ::File.join(dir, *words)
+    unless ::File.directory?(dir)
+      logger.warn("No such directory: #{dir}")
+      exit
+    end
+  end
+  dir
+end
+
+def base_dir
+  return ::File.absolute_path(directory) if directory
+  dir = ::Dir.getwd
+  loop do
+    candidate = ::File.join(dir, ::Toys::StandardCLI::CONFIG_DIR_NAME)
+    return candidate if ::File.directory?(candidate)
+    parent = ::File.dirname(dir)
+    if parent == dir
+      logger.error("Unable to find a Toys directory")
+      exit(1)
+    end
+    dir = parent
+  end
+end
+
+def ruby_args
+  args = []
+  args << "-w" if warnings
+  args << "-I#{::Toys::CORE_LIB_PATH}#{::File::PATH_SEPARATOR}#{::Toys::LIB_PATH}"
+  args << "-"
+  args << "--seed" << seed if seed
+  args << "--verbose" if verbosity.positive?
+  args << "--name" << name if name
+  args << "--exclude" << exclude if exclude
+  args
+end

data/builtins/system/update.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+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

data/docs/guide.md

@@ -1118,8 +1118,8 @@ run Toys with no arguments:
 
 The root tool will display the overall help screen for Toys.
 
-Although it is a less common pattern, it is possible for a tool that has
-subtools to have its own `run` method:
+Although it is a less common pattern, it is possible for a tool to have its own
+`run` method even if it has subtools:
 
     tool "test" do
       def run
@@ -1142,12 +1142,100 @@ subtools to have its own `run` method:
 Now running `toys test` will run its own implementation.
 
 (Yes, it is even possible to write a `run` method for the root tool. I don't
-recommend doing so, because then you lose the root tool's useful default
+recommend doing so, because you would lose the root tool's useful default
 implementation that lists all your tools.)
 
 Toys allows subtools to be nested arbitrarily deep. In practice, however, more
 than two or three levels of hierarchy can be confusing to use.
 
+### Defining subtools using classes
+
+It is also possible to define subtools by subclassing `Toys::Tool`. The class
+will support the same DSL as a `tool` block would. For example, this is what
+our greet tool would look like as a class:
+
+    class Greet < Toys::Tool
+      optional_arg :whom, default: "world"
+      flag :shout, "-s", "--shout"
+
+      def run
+        greeting = "Hello, #{whom}!"
+        greeting = greeting.upcase if shout
+        puts greeting
+      end
+    end
+
+Defining tools as clases is useful if you want your Toys files to look a bit
+more like normal Ruby or you want to avoid long blocks. Additionally, they can
+be useful to scope constants, which otherwise would be visible throughout the
+entire file, as noted in the [section on using constants](#Using_constants).
+
+When you define a tool as a class, Toys infers the tool name by converting the
+class name to "kebab-case". For example, the `Greet` class above would define a
+tool called `greet`. If the class were called `GreetMany`, the tool would be
+called `greet-many`. If you need to override this behavior or set a tool name
+that is not possible from legal class names, pass the desired tool name to the
+`Toys.Tool` method like this:
+
+    class Greet < Toys.Tool("_my_greet")
+      optional_arg :whom, default: "world"
+      flag :shout, "-s", "--shout"
+
+      def run
+        greeting = "Hello, #{whom}!"
+        greeting = greeting.upcase if shout
+        puts greeting
+      end
+    end
+
+You can create subtools by nesting classes:
+
+    class Test < Toys::Tool
+      class Unit < Toys::Tool
+        def run
+          puts "run only unit tests here..."
+        end
+      end
+
+      class Integration < Toys::Tool
+        def run
+          puts "run only integration tests here..."
+        end
+      end
+    end
+
+The above defines `test unit` and `test integration` tools as expected.
+
+Finally, you may not nest a class-based tool inside a block-based tool. (This
+is because Ruby's constant definition rules would put such a class in an
+unexpected namespace, leading to potential clashes that would be difficult to
+diagnose.) It is, however, permissible to nest a block-based tool inside a
+class-based tool.
+
+Hence, this is not allowed, and will result in an exception:
+
+    tool "test" do
+      # This will raise Toys::ToolDefinitionError...
+      class Unit < Toys::Tool
+        def run
+          puts "run unit tests..."
+        end
+      end
+    end
+
+But this is legal:
+
+    class Test < Toys::Tool
+      tool "unit" do
+        def run
+          puts "run unit tests..."
+        end
+      end
+    end
+
+In general, though, as a best practice, I recommend against mixing the two
+styles. Define tools either as classes or as blocks, not both.
+
 ## Understanding Toys files
 
 Toys commands are defined in Toys files. We covered the basic syntax for these

data/lib/toys/standard_cli.rb

@@ -139,7 +139,7 @@ module Toys
       add_search_path_hierarchy(start: cur_dir, terminate: global_dirs)
       global_dirs.each { |path| add_search_path(path) }
       builtins_path = ::File.join(::File.dirname(::File.dirname(__dir__)), "builtins")
-      add_config_path(builtins_path)
+      add_config_path(builtins_path, source_name: "(builtin tools)", context_directory: nil)
       self
     end
 
@@ -157,8 +157,6 @@ module Toys
       end
     end
 
-    # rubocop:disable Metrics/MethodLength
-
     ##
     # Returns the middleware for the standard Toys CLI.
     #
@@ -179,6 +177,7 @@ module Toys
                         default_recursive: true,
                         allow_root_args: true,
                         show_source_path: true,
+                        separate_sources: true,
                         use_less: true,
                         fallback_execution: true),
         Middleware.spec(:show_root_version,
@@ -189,8 +188,6 @@ module Toys
       ]
     end
 
-    # rubocop:enable Metrics/MethodLength
-
     ##
     # Returns the default set of global config directories.
     #

data/lib/toys/templates/clean.rb

@@ -23,10 +23,13 @@ module Toys
       #     to clean. You can also include the symbol `:gitignore` which will
       #     clean all items covered by `.gitignore` files, if contained in a
       #     git working tree.
+      # @param context_directory [String] A custom context directory to use
+      #     when executing this tool.
       #
-      def initialize(name: nil, paths: [])
+      def initialize(name: nil, paths: [], context_directory: nil)
         @name = name
         @paths = paths
+        @context_directory = context_directory
       end
 
       ##
@@ -45,6 +48,17 @@ module Toys
       #
       attr_writer :paths
 
+      ##
+      # Custom context directory for this tool.
+      #
+      # @param value [String]
+      # @return [String]
+      #
+      attr_writer :context_directory
+
+      # @private
+      attr_reader :context_directory
+
       # @private
       def paths
         Array(@paths)
@@ -59,6 +73,8 @@ module Toys
         tool(template.name) do
           desc "Clean built files and directories."
 
+          set_context_directory template.context_directory if template.context_directory
+
           static :template_paths, template.paths
 
           include :fileutils