toys 0.10.5 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4d27fd4743feddadec86f143f5d0a9d5afff98cf3b10afd18732d29f495db38
-  data.tar.gz: bdc935b5876b1a1c7779a3fefc59ea9b6c506cf1f0eba67c54ff05a5e1e46013
+  metadata.gz: 93df1335be3b4e82bc30602ed8e78d8a04e99e1df6eecadb1a13430107c761c0
+  data.tar.gz: 448add98c695e182efcd00dd3995f4c62a8533f47dc8d80a915399a17ec584d5
 SHA512:
-  metadata.gz: 9e8bcf630b41f3fe9a3c906460e5f40008b1a9190becf38ce3700308193240a9f5ec60c6ecec2dfd03bcf6eb8dafd77171c5039fa9dd239770d7f7251a6cf90f
-  data.tar.gz: a5d4cc200823a52c4586d2109fb89e1ebd17737d191cea509b53e344a9868fddc1ccb05cb735b796c662fd297bb75a7d7078d2065df9ffb7799d78d122c6de3b
+  metadata.gz: '014558969bf84b3f37a8e1948eaeaa7a4acfc0a07b4cfda1a0ec50f1fc11691219fa659a81ed73a0470e1f04ba85311810a3a151d2f5422042c983e969560584'
+  data.tar.gz: 5fdb203c6b967e554bc16aeadd4d5e8dcccc931f11d04bca0e22d9b635727f7891b4a80363f4ac60b4e0d80ebdc39188595b3dce6e6a3dce72d9e27c83c14e86

data/CHANGELOG.md

@@ -1,10 +1,22 @@
 # Release History
 
+### 0.11.0 / 2020-08-21
+
+* ADDED: The toys search path can be truncated using the `truncate_load_path!` directive.
+* ADDED: The `:clean` template recognizes `:gitignore` as a path indicating all gitignored files.
+* IMPROVED: Generated help for delegates now includes the information for the target tool, plus subtools of the delegate.
+* IMPROVED: The `:bundler` mixin searches for `gems.rb` and `.gems.rb` in addition to `Gemfile`.
+* IMPROVED: The `:budnler` mixin can load a specific Gemfile path.
+* FIXED: The loader can now find `.data` and `.lib` directories at the root level of a `.toys` directory.
+* FIXED: Exec::Result correctly reports processes that terminated due to signals.
+* FIXED: Fixed a rare Exec capture failure that resulted from a race condition when closing streams.
+* DOCS: The Toys user guide now covers static bundle loading and `truncate_load_path!`.
+
 ### 0.10.5 / 2020-07-18
 
 * IMPROVED: The bundler mixin silences bundler output during bundle setup.
 * IMPROVED: The bundler mixin allows toys and toys-core to be in the Gemfile. It checks their version requirements against the running Toys version, and either adds the corret version to the bundle or raises IncompatibleToysError.
-* IMPROVED: The bundler mixin utomatically updates the bundle if install fails (typically because a transitive dependency has been explicitly updated.)
+* IMPROVED: The bundler mixin automatically updates the bundle if install fails (typically because a transitive dependency has been explicitly updated.)
 * FIXED: Some cases of transitive dependency handling by the bundler mixin.
 * FIXED: Fixed a crash when computing suggestions, when running with a bundle on Ruby 2.6 or earlier.
 

data/README.md

@@ -240,8 +240,9 @@ Note that if you normally run Rake with Bundler (e.g. `bundle exec rake test`),
 you may need to add Toys to your Gemfile and use Bundler to invoke Toys (i.e.
 `bundle exec toys test`). This is because Toys is just calling the Rake API to
 run your task, and the Rake task might require the bundle. However, when Toys
-is not wrapping Rake, typical practice is actually *not* to use Bundler. Toys
-provides its own mechanisms to activate and even install needed gems for you.
+is not wrapping Rake, typical practice is actually *not* to use `bundle exec`.
+Toys provides its own mechanisms to setup a bundle, or to activate and even
+install individual gems.
 
 So far, we've made Toys a front-end for your Rake tasks. This may be useful by
 itself. Toys lets you pass command line arguments "normally" to tools, whereas

data/docs/guide.md

@@ -1,4 +1,6 @@
+<!--
 # @title Toys User Guide
+-->
 
 # Toys User Guide
 
@@ -1300,7 +1302,29 @@ the same point (the current directory) in the search path.
 Note that in the search path above, steps (1) and (2) are *context-dependent*.
 That is, they may be different depending on what directory you are in. However,
 step (3) is *not* context-dependent, and is searched regardless of where you
-are located. Tools defined here are **global**, available everywhere.
+are located. Tools defined here are *global*, available everywhere.
+
+#### Stopping search
+
+Though it is uncommon practice, it is possible to stop the search process and
+prevent Toys from loading tools further down in the search path (e.g. prevent
+tools from being defined from parent directories or global directories). To do
+so, use the directive
+[Toys::DSL::Tool#truncate_load_path!](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/DSL/Tool#truncate_load_path!-instance_method). This directive removes all
+directories further down the search path. It can be used, for example, to
+disable global tools when you run Toys from the current directory. It can also
+be useful if you are using [Bundler integration](#Using_bundler_with_a_tool) to
+prevent bundle conflicts with parent directories, by disabling tools from
+parent directories.
+
+The `truncate_load_path!` directive works only if no tools from further down
+the search path have been loaded yet. It will raise
+[Toys::ToolDefinitionError](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/ToolDefinitionError)
+if it fails to truncate the load path. In most cases, Toys is very smart about
+loading tools only when needed, but there are exceptions. To minimize the
+chance of problems, if you need to use `truncate_load_path!`, locate it as
+early as possible in your Toys files, typically at the top of the
+[index file](#Index_files).
 
 ## The execution environment
 
@@ -1308,9 +1332,9 @@ This section describes the context and resources available to your tool when it
 is running; that is, what you can call from your tool's `run` method.
 
 Each tool is defined as a class that subclasses
-[Toys::Context](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Context). The base
-class defines a number of methods, and provides access to a variety of data and
-objects relevant to your tool. We have already seen earlier how to use the
+[Toys::Context](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Context).
+The base class defines helper methods, and provides access to a variety of data
+and objects relevant to your tool. We have already seen earlier how to use the
 [Toys::Context#get](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Context#get-instance_method)
 method to retrieve option values, and how to use the
 [Toys::Context#exit](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Context#exit-instance_method)
@@ -1380,8 +1404,8 @@ A common operation a tool might want to do is "call" another tool. This can be
 done via the CLI object, which you can retrieve using the `CLI` key or the
 [Toys::Context#cli method](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Context#cli-instance_method).
 These return the current instance of
-[Toys::CLI](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/CLI) which is the
-"main" interface to Toys. In particular, it provides the
+[Toys::CLI](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/CLI) which
+is the "main" interface to Toys. In particular, it provides the
 [Toys::CLI#run method](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/CLI#run-instance_method)
 which can be used to call another tool:
 
@@ -1799,8 +1823,8 @@ directive by setting properties on the template object.
 
 Finally, templates are classes, and you can create a template directly as a
 class by including the
-[Toys::Template](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Template) module
-in your class definition.
+[Toys::Template](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Template)
+module in your class definition.
 
     class GreetTemplate
       include Toys::Template
@@ -2060,6 +2084,8 @@ tool is *executed*. This assumes the bundle is already installed, and brings
 the appropriate gems into the Ruby load path. That is, it's basically the same
 as `bundle exec`, but it applies only to the running tool.
 
+#### Applying bundler to all subtools
+
 In many cases, you might find that bundler is needed for many or most of the
 tools you write for a particular project. In this case, you might find it
 convenient to use
@@ -2090,7 +2116,7 @@ for more information on `subtool_apply`.
 By default, the `:bundler` mixin will look for a `Gemfile` within the `.toys`
 directory (if your tool is defined in one), and if one is not found there,
 within the [context directory](#The_context_directory) (the directory
-containing your `.toys` directory or `.toys.rb`file), and if one still is not
+containing your `.toys` directory or `.toys.rb` file), and if one still is not
 found, in the current working directory. You can change this behavior by
 passing an option to the `:bundler` mixin. For example, you can search only the
 current working directory by passing `search_dirs: :current` as such:
@@ -2100,7 +2126,24 @@ current working directory by passing `search_dirs: :current` as such:
       # etc...
     end
 
-You can also pass a specific directory path to this option.
+The `:search_dirs` option takes a either directory path (as a string) or a
+symbol indicating a "semantic" directory. You can also pass an array of
+directories that will be searched in order. For each directory, Toys will look
+for a file called `.gems.rb`, `gems.rb`, or `Gemfile` (in that order) and use
+the first one that it finds.
+
+The supported "semantic directory" symbols are `:current` indicating the
+current working directory, `:context` indicating the context directory, and
+`:toys` indicating the Toys directory in which the tool is defined.
+Furthermore, the semantic directory `:toys` is treated specially in that it
+looks up the `.toys` directory hierarchy. So if your tool is defined in
+`.toys/foo/bar.rb`, it will look for a Gemfile first in `.toys/foo/` and then
+in `.toys/`. Additionally, when looking for a Gemfile in `:toys`, it searches
+only for `.gems.rb` and `Gemfile`. A file called `gems.rb` is not treated as a
+Gemfile under the `:toys` directory, because it could be a tool.
+
+The default gemfile search path, if you do not provide the `search_dirs:`
+option, is equivalent to `[:toys, :context, :current]`.
 
 If the bundle is not installed, or is out of date, Toys will ask you whether
 you want it to install the bundle first before running the tool. A tool can
@@ -2143,6 +2186,48 @@ a different bundle. If you need to do this, use the
 method from the `:exec` mixin, to call the tool. This method spawns a separate
 process with a clean Bundler setup for running the tool.
 
+#### When a bundle is needed to define a tool
+
+Usually, the `:bundler` mixin sets up your bundle when the tool is *executed*.
+However, occasionally, you need the gems in the bundle to *define* a tool. This
+might happen, for instance, if your bundle includes gesm that define mixins or
+templates used by your tool.
+
+If you need the bundle set up immediately because its gems are needed by the
+tool definition, pass the `static: true` option when including the `:bundler`
+mixin. For example, if you are using the
+[flame_server_toys](https://github.com/AlexWayfer/flame_server_toys) gem, which
+provides a template that generates tools for the
+[Flame](https://github.com/AlexWayfer/flame) web framework, you could include
+the `flame_server_toys` gem in your Gemfile, and make it available for defining
+tools:
+
+    # Set up the bundle immediately.
+    include :bundler, static: true
+
+    # Now you can use the gems in the bundle when defining tools.
+    require "flame_server_toys"
+    expand FlameServerToys::Template
+
+There is a big caveat to using `static: true`, which is that you are setting up
+a bundle immediately, and as a result any subsequent attempt to set up or use a
+different bundle will fail. (See the section on
+[bundle conflicts](#Solving_bundle_conflicts) for a discussion of other reasons
+this can happen.) As a result, it's best not to use `static: true` unless you
+*really* need it to define tools. If you do run into this problem, here are two
+things you could try:
+
+ 1. "Scope" the bundle to the tool or the namespace where you need it. Toys
+    makes an effort not to define a tool unless you actually need to execute it
+    or one of its subtools, so if you can locate `include :bundler` inside just
+    the tool or namespace that needs it, you might be able to avoid conflicts.
+
+ 2. Failing that, if you need a particular gem in order to define a tool, you
+    could consider activating the gem directly rather than as part of a bundle.
+    See the following section on
+    [Activating gems directly](#Activating_gems_directly) for details on this
+    technique.
+
 ### Activating gems directly
 
 Although we recommend the `:bundler` mixin for most cases, it is also possible
@@ -2197,22 +2282,35 @@ to ensure highline is installed while the tool is being defined.
       end
     end
 
-If you are not in the Toys DSL context—for example from a class-based
-mixin—you should use
-[Toys::Utils::Gems.activate](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Utils/Gems#activate-class_method)
-instead. (Note that you must `require "toys/utils/gems"` explicitly before
-invoking the
+Note these methods are a bit different from the
+[gem method](http://ruby-doc.org/stdlib/libdoc/rubygems/rdoc/Kernel.html)
+provided by Rubygems. The Toys version attempts to install a missing gem for
+you, whereas Rubygems will just throw an exception.
+
+### Activating gems outside the DSL
+
+The above techniques for installing a bundle or activating a gem directly, are
+all part of the tool definition DSL. However, the functionality is also
+available outside the DSL---for example, from a class-based mixin.
+
+To set up a bundle, call
+[Toys::Utils::Gems#bundle](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Utils/Gems#bundle-instance_method).
+(Note that you must `require "toys/utils/gems"` explicitly before invoking the
 [Toys::Utils::Gems](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Utils/Gems)
 class because, like all classes under `Toys::Utils`, Toys does not load it
 automatically.) For example:
 
     require "toys/utils/gems"
-    Toys::Utils::Gems.activate("highline", "~> 2.0")
+    gem_utils = Toys::Utils::Gems.new
+    gem_utils.bundle(search_dirs: Dir.getwd)
 
-Note these methods are a bit different from the
-[gem method](http://ruby-doc.org/stdlib/libdoc/rubygems/rdoc/Kernel.html)
-provided by Rubygems. The Toys version attempts to install a missing gem for
-you, whereas Rubygems will just throw an exception.
+To activate single gems explicitly, call
+[Toys::Utils::Gems#activate](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Utils/Gems#activate-instance_method).
+For example:
+
+    require "toys/utils/gems"
+    gem_utils = Toys::Utils::Gems.new
+    gem_utils.activate("highline", "~> 2.0")
 
 ### Useful gems
 
@@ -2319,7 +2417,7 @@ than declarative.
 The Toys approach to build tools simply embraces the fact that our build
 processes already tend to be imperative. So unlike Rake, Toys does not provide
 syntax for describing targets and dependencies, since we generally don't have
-them in Ruby programs. Instead, it is optimized for writing tools.
+them in Ruby programs. Instead, it is optimized for writing imperative tools.
 
 For example, Rake provides a primitive mechanism for passing arguments to a
 task, but it is clumsy and quite different from most unix programs. However, to

data/lib/toys/templates/clean.rb

@@ -20,7 +20,9 @@ module Toys
       # @param name [String] Name of the tool to create. Defaults to
       #     {DEFAULT_TOOL_NAME}.
       # @param paths [Array<String>] An array of glob patterns indicating what
-      #     to clean.
+      #     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.
       #
       def initialize(name: nil, paths: [])
         @name = name
@@ -57,22 +59,69 @@ module Toys
         tool(template.name) do
           desc "Clean built files and directories."
 
+          static :template_paths, template.paths
+
           include :fileutils
+          include :exec
 
-          to_run do
-            ::Dir.chdir(context_directory || ::Dir.getwd) do
-              files = []
-              template.paths.each do |pattern|
-                files.concat(::Dir.glob(pattern))
-              end
-              files.uniq.each do |file|
-                if ::File.exist?(file)
-                  rm_rf(file)
-                  puts "Cleaned: #{file}"
+          # @private
+          def run
+            cd(context_directory || ::Dir.getwd) do
+              template_paths.each do |elem|
+                case elem
+                when :gitignore
+                  clean_gitignore
+                when ::String
+                  clean_pattern(elem)
+                else
+                  raise "Unknown path in clean: #{elem.inspect}"
                 end
               end
             end
           end
+
+          # @private
+          def clean_gitignore
+            result = exec(["git", "rev-parse", "--is-inside-work-tree"], out: :null, err: :null)
+            unless result.success?
+              logger.error("Skipping :gitignore because we don't seem to be in a git directory")
+              return
+            end
+            clean_gitignore_dir(".")
+          end
+
+          # @private
+          def clean_gitignore_dir(dir)
+            children = dir_children(dir)
+            result = exec(["git", "check-ignore", "--stdin"],
+                          in: :controller, out: :capture) do |controller|
+              children.each { |child| controller.in.puts(child) }
+            end
+            result.captured_out.split("\n").each { |path| clean_path(path) }
+            children = dir_children(dir) if result.success?
+            children.each { |child| clean_gitignore_dir(child) if ::File.directory?(child) }
+          end
+
+          # @private
+          def dir_children(dir)
+            ::Dir.entries(dir)
+                 .reject { |entry| entry =~ /^\.\.?$/ }
+                 .sort
+                 .map { |entry| ::File.join(dir, entry) }
+          end
+
+          # @private
+          def clean_pattern(pattern)
+            ::Dir.glob(pattern) { |path| clean_path(path) }
+          end
+
+          # @private
+          def clean_path(path)
+            if ::File.exist?(path)
+              rm_rf(path)
+              puts "Cleaned: #{path}"
+            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.10.5"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.10.5
+  version: 0.11.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-19 00:00:00.000000000 Z
+date: 2020-08-21 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.10.5
+        version: 0.11.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.10.5
+        version: 0.11.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
@@ -63,10 +63,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.10.5/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.11.0/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.10.5
+  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.11.0
 post_install_message: 
 rdoc_options: []
 require_paths: