toys 0.10.4 → 0.11.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2df55870f3530617a4961bb0cfa09d0752bb13e99f7642a4156ab4b7ffea3a8c
-  data.tar.gz: 74131a75411c11703347193f167c916e351fa3582401d0505036cd74dbb9911c
+  metadata.gz: b7352461981cbfeeba4271c71e58d864f210aab1e42ff572f94d15b56be16cbc
+  data.tar.gz: 22c10a76a8b53a8482b6b9b46650d005fb2c94a8c8f3d8be59d7e2f9720a243e
 SHA512:
-  metadata.gz: ff5a5e3e2c2fea1bebdcfbeef064bd51d5a587a48077b7ee6c6b4befe926433d0318ce5c4b8c63a067e8b4e6dbd21f191c86b11844e8e1ff9d8c6096cffad996
-  data.tar.gz: 464d5d87896965c77182d6f7f3793b23bbf9797439619c01b9142516bb71077f44a5c53e81492017890e8fd9db1cb7d5c9e83bed1ea68741f716d94833e7e3b6
+  metadata.gz: 4f2831bcebdf9606dba1d59dec4a8e1d3b997c03abaf54149c5e7f792e5aabca6e84d2f18af5aab2c88e6192645ffd3f2c954ab5913a6237368cd85c386e6b4b
+  data.tar.gz: b4f06825d9838ba0ddbafb607378b5a60996398f4a6efdce023169e07f7fb6f639e6d43f69edd3874b5e8af5364761e96c87048a0332226bb023dab04c2b35e6

data/CHANGELOG.md

@@ -1,23 +1,56 @@
 # Release History
 
-### 0.10.4 / 2020-07-11
+### v0.11.3 / 2020-09-13
+
+* FIXED: The Exec mixin recognizes the argv0 option, and logs it appropriately 
+
+### v0.11.2 / 2020-09-06
+
+* FIXED: Don't get confused when running toys from within a toys directory 
+* FIXED: Fix a JRuby-specific race condition when capturing exec streams
+
+### v0.11.1 / 2020-08-24
+
+* FIXED: The `.lib` directory actually works as advertised.
+
+### v0.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!`.
+
+### v0.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 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.
+
+### v0.10.4 / 2020-07-11
 
 * IMPROVED: Bundler integration can now handle Toys itself being in the bundle, as long as the version requirements cover the running Toys version.
 * IMPROVED: Passing `static: true` to the `:bundler` mixin installs the bundle at definition rather than execution time.
 
-### 0.10.3 / 2020-07-04
+### v0.10.3 / 2020-07-04
 
 * FIXED: The `exec_separate_tool` method in the `:exec` mixin no longer throws ENOEXEC on Windows.
 
-### 0.10.2 / 2020-07-03
+### v0.10.2 / 2020-07-03
 
 * FIXED: The load path no longer loses the toys and toys-core directories after a bundle install.
 
-### 0.10.1 / 2020-03-07
+### v0.10.1 / 2020-03-07
 
 * FIXED: Setting `:exit_on_nonzero_status` explicitly to false now works as expected.
 
-### 0.10.0 / 2020-02-24
+### v0.10.0 / 2020-02-24
 
 * ADDED: `:bundler` mixin that installs and sets up a bundle for the tool
 * ADDED: `bundler` options in the standard templates, to run those tools in a bundle
@@ -33,26 +66,26 @@
 * FIXED: `rdoc` template crashed if any nonstandard options were given.
 * FIXED: `rubocop` template would abort prematurely if standard streams were redirected.
 
-### 0.9.4 / 2020-01-26
+### v0.9.4 / 2020-01-26
 
 * FIXED: Crash in the loader when a non-ruby file appears in a toys directory
 
-### 0.9.3 / 2020-01-05
+### v0.9.3 / 2020-01-05
 
 * FIXED: `delegate_to` directive could crash if an overriding tool has already been defined.
 * FIXED: A Ruby 2.7 warning when reporting a Toys file syntax error.
 
-### 0.9.2 / 2020-01-03
+### v0.9.2 / 2020-01-03
 
 * IMPROVED: Mixins can now take real keyword arguments, and will pass them on properly to `on_initialize` and `on_include` blocks.
 * CHANGED: `Toys::Utils::Exec` and the `:exec` mixin methods now take real keyword arguments rather than an `opts` hash. This means you should use keywords (or the double-splat operator) to avoid a deprecation warning on Ruby 2.7.
 
-### 0.9.1 / 2019-12-22
+### v0.9.1 / 2019-12-22
 
 * IMPROVED: `delegate_to` and `alias_tool` can take symbols as well as strings.
 * DOCS: Fixed user guide internal links on rubydoc.info.
 
-### 0.9.0 / 2019-12-02
+### v0.9.0 / 2019-12-02
 
 * ADDED: The `delegate_to` directive causes the tool to delegate execution to another tool. This means it takes the same arguments and has the same execution behavior.
 * ADDED: The `delegate_to` argument to the `tool` directive causes the tool to delegate to another tool. (Note: the `alias_tool` directive is now just shorthand for creating a tool with a delegate, and as such is mildly deprecated.)
@@ -63,12 +96,12 @@
 * IMPROVED: JRuby is now supported for most operations. However, JRuby is generally not recommended because of JVM boot latency, lack of Kernel#fork support, and other issues.
 * FIXED: The the `tool` directive no longer crashes if not passed a block.
 
-### 0.8.1 / 2019-11-19
+### v0.8.1 / 2019-11-19
 
 * FIXED: Listing subtools would crash if a broken alias was present.
 * DOCUMENTATION: Switched from redcarpet to kramdown, and tried to make some structural fixes.
 
-### 0.8.0 / 2019-06-20
+### v0.8.0 / 2019-06-20
 
 This is a major update with significant new features and a bunch of fixes.
 It does include a few minor backward-incompatible changes. All signifiant
@@ -122,18 +155,18 @@ Details:
 
 Additionally, a significant amount of internal reorganization and cleanup happened in the toys-core gem. See the changelog for toys-core for more details.
 
-### 0.7.0 / 2019-01-23
+### v0.7.0 / 2019-01-23
 
 * ADDED: A template for creating tools that invoke RSpec.
 * ADDED: Flag groups, which enforce policies around which flags are required.
 * CHANGED: Flags within a group are sorted in the help screens.
 * IMPROVED: The minitest template now honors all standard minitest flags.
 
-### 0.6.1 / 2019-01-07
+### v0.6.1 / 2019-01-07
 
 * FIXED: The presence of aliases caused subtool listing to crash.
 
-### 0.6.0 / 2018-10-22
+### v0.6.0 / 2018-10-22
 
 * FIXED: Build tools cd into the context directory when running.
 * FIXED: Rakefiles are evaluated and tasks are run in the Rakefile's directory.
@@ -145,7 +178,7 @@ Additionally, a significant amount of internal reorganization and cleanup happen
 * IMPROVED: Non-runnable namespaces are no longer displayed in recursive subtool
   lists if their children are already displayed.
 
-### 0.5.0 / 2018-10-07
+### v0.5.0 / 2018-10-07
 
 * ADDED: Period and colon are recognized as tool path delimiters.
 * ADDED: New rake template that supports loading rake tasks as tools.
@@ -156,31 +189,31 @@ Additionally, a significant amount of internal reorganization and cleanup happen
 * IMPROVED: The tool directive can now take an `if_defined` argument.
 * FIXED: Template instantiation was failing if the hosting tool was priority-masked.
 
-### 0.4.5 / 2018-08-05
+### v0.4.5 / 2018-08-05
 
 * CHANGED: Dropped preload file feature
 
-### 0.4.4 / 2018-07-21
+### v0.4.4 / 2018-07-21
 
 * FIXED: Utils::Exec wasn't closing streams after copying.
 * IMPROVED: Utils::Exec::Controller can capture or redirect the remainder of a controlled stream.
 * ADDED: Terminal#ask
 
-### 0.4.3 / 2018-07-13
+### v0.4.3 / 2018-07-13
 
 * IMPROVED: Exec mixin methods can now spawn subprocesses in the background
 * IMPROVED: Exec mixin capture methods can now yield a controller
 
-### 0.4.2 / 2018-07-08
+### v0.4.2 / 2018-07-08
 
 * FIXED: Raise an error rather than cause unexpected behavior if a mixin is included twice.
 * IMPROVED: The `include?` method extended to support mixin names in a tool dsl.
 
-### 0.4.1 / 2018-07-03
+### v0.4.1 / 2018-07-03
 
 * FIXED: Terminal#confirm uppercased "N" for the wrong default.
 
-### 0.4.0 / 2018-07-03
+### v0.4.0 / 2018-07-03
 
 Now declaring this alpha quality. Backward-incompatible changes are still
 possible from this point, but I'll try to avoid them.
@@ -190,24 +223,24 @@ possible from this point, but I'll try to avoid them.
 * IMPROVED: Toys::Utils::Gems can suppress the confirmation prompt
 * IMPROVED: Magic comments are now honored in toys files.
 
-### 0.3.11 / 2018-07-02
+### v0.3.11 / 2018-07-02
 
 * CHANGED: Require Ruby 2.3 or later
 * CHANGED: Renamed "set" directive to "static" to reduce confusion with Tool#set.
 * ADDED: Convenience methods for getting option values
 
-### 0.3.10 / 2018-06-30
+### v0.3.10 / 2018-06-30
 
 * CHANGED: Dropped Tool#option. Use Tool#get instead.
 * CHANGED: "run" directive renamed to "to_run"
 * CHANGED: Highline mixin now uses Highline 2.0
 * ADDED: Mixins can provide initializers
 
-### 0.3.9.1 / 2018-06-24
+### v0.3.9.1 / 2018-06-24
 
 * FIXED: Built-in flags were interfering with disable_argument_parsing
 
-### 0.3.9 / 2018-06-24
+### v0.3.9 / 2018-06-24
 
 * CHANGED: Removed alias_as directive since it's incompatible with selective loading.
 * ADDED: Ability to define named templates in Toys files
@@ -217,18 +250,18 @@ possible from this point, but I'll try to avoid them.
 * IMPROVED: Acceptors can be looked up recursively in the same way as mixins and templates
 * FIXED: Templates were not activating needed gems
 
-### 0.3.8 / 2018-06-10
+### v0.3.8 / 2018-06-10
 
 * CHANGED: Renamed helpers to mixins.
 * CHANGED: Renamed :in_from, :out_to, and :err_to exec options to :in, :out, :err
 * IMPROVED: Exec raises an error if passed an unknown option.
 * IMPROVED: Exec now accepts nearly all the same stream specifications as Process#spawn.
 
-### 0.3.7.1 / 2018-05-30
+### v0.3.7.1 / 2018-05-30
 
 * FIXED: Fix crash in system update.
 
-### 0.3.7 / 2018-05-30
+### v0.3.7 / 2018-05-30
 
 * CHANGED: Execution runs in the same scope as the DSL, which lets us use normal methods instead of helper-blocks.
 * CHANGED: Renamed "script" to "run", and allow setting of runnable by defining a "run" method
@@ -237,7 +270,7 @@ possible from this point, but I'll try to avoid them.
 * CHANGED: Removed spinner helper and added terminal helper.
 * ADDED: Helper modules scoped to the tool hierarchy
 
-### 0.3.6 / 2018-05-21
+### v0.3.6 / 2018-05-21
 
 * CHANGED: Removed Context#new_cli and exposed Context#cli instead.
 * CHANGED: Raises ToolDefinitionError if you declare a duplicate flag.
@@ -246,13 +279,13 @@ possible from this point, but I'll try to avoid them.
 * IMPROVED: Support custom acceptors.
 * IMPROVED: Highline helper automatically sets use_color based on the type of stdout.
 
-### 0.3.5 / 2018-05-15
+### v0.3.5 / 2018-05-15
 
 * CHANGED: Flag and arg blocks in the DSL have an interface more similar to the rest of the DSL.
 * CHANGED: Renamed `execute do` to `script do`.
 * IMPROVED: Help display uses `less` if available.
 
-### 0.3.4 / 2018-05-14
+### v0.3.4 / 2018-05-14
 
 * CHANGED: Renamed switch to flag
 * CHANGED: Renamed docs: parameter again, to desc: and long_desc: to match tool desc.
@@ -269,7 +302,7 @@ possible from this point, but I'll try to avoid them.
 * FIXED: Subtools with no desc now properly pick up the default
 * FIXED: Usage errors and show-help now interact in the right way
 
-### 0.3.3 / 2018-05-09
+### v0.3.3 / 2018-05-09
 
 * CHANGED: Renamed file_utils helper to fileutils.
 * CHANGED: Renamed doc: parameter to docs:
@@ -279,7 +312,7 @@ possible from this point, but I'll try to avoid them.
 * ADDED: WrappableString for descriptions and docs
 * IMPROVED: Descriptions can have multiple lines
 
-### 0.3.2 / 2018-05-07
+### v0.3.2 / 2018-05-07
 
 * CHANGED: Split core engine out into separate "toys-core" gem. See the
   toys-core changelog for additional changes in core.
@@ -290,7 +323,7 @@ possible from this point, but I'll try to avoid them.
 * IMPROVED: Help shows the config file path on "--verbose".
 * IMPROVED: You can now run a sub-instance of toys from an executor.
 
-### 0.3.1 / 2018-05-02
+### v0.3.1 / 2018-05-02
 
 * CHANGED: Subcommand display is now recursive by default.
 * IMPROVED: Improved error messaging for bad switch syntax.
@@ -299,6 +332,6 @@ possible from this point, but I'll try to avoid them.
 * DOCS: Completed a first pass on class and method documentation.
 * INTERNAL: Adjusted naming of switch-related methods.
 
-### 0.3.0 / 2018-04-30
+### v0.3.0 / 2018-04-30
 
 * Initial generally usable release

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
@@ -252,7 +253,7 @@ than Rake does.
 But you also might find Toys a more natural way to *write* tasks, and indeed
 you can often rewrite an entire Rakefile as a Toys file and get quite a bit of
 benefit in readability and maintainability. For an example, see the
-[Toys file for the Toys repo itself](https://github.com/dazuma/toys/blob/master/toys/.toys.rb).
+[Toys file for the Toys repo itself](https://github.com/dazuma/toys/blob/main/toys/.toys.rb).
 It contains the Toys scripts that I use to develop, test, and release Toys
 itself. Yes, Toys is self-hosted. You'll notice most of this Toys file consists
 of template expansions. Toys provides templates for a lot of common build,

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/standard_cli.rb

@@ -42,6 +42,12 @@ module Toys
     #
     DATA_DIR_NAME = ".data"
 
+    ##
+    # Standard lib directory name in a toys configuration.
+    # @return [String]
+    #
+    LIB_DIR_NAME = ".lib"
+
     ##
     # Name of the standard toys executable.
     # @return [String]
@@ -99,11 +105,12 @@ 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,
         extra_delimiters: EXTRA_DELIMITERS,
         middleware_stack: default_middleware_stack,
         template_lookup: default_template_lookup
       )
-      add_standard_paths(cur_dir: cur_dir)
+      add_standard_paths(cur_dir: cur_dir, toys_dir_name: CONFIG_DIR_NAME)
     end
 
     private
@@ -125,8 +132,9 @@ module Toys
     #     directories, or `nil` to use the defaults.
     # @return [self]
     #
-    def add_standard_paths(cur_dir: nil, global_dirs: nil)
+    def add_standard_paths(cur_dir: nil, global_dirs: nil, toys_dir_name: nil)
       cur_dir ||= ::Dir.pwd
+      cur_dir = skip_toys_dir(cur_dir, toys_dir_name) if toys_dir_name
       global_dirs ||= default_global_dirs
       add_search_path_hierarchy(start: cur_dir, terminate: global_dirs)
       global_dirs.each { |path| add_search_path(path) }
@@ -135,6 +143,20 @@ module Toys
       self
     end
 
+    # Step out of any toys dir
+    def skip_toys_dir(dir, toys_dir_name)
+      cur_dir = dir
+      loop do
+        parent = ::File.dirname(dir)
+        return cur_dir if parent == dir
+        if ::File.basename(dir) == toys_dir_name
+          cur_dir = dir = parent
+        else
+          dir = parent
+        end
+      end
+    end
+
     # rubocop:disable Metrics/MethodLength
 
     ##

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.4"
+  VERSION = "0.11.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.10.4
+  version: 0.11.3
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-11 00:00:00.000000000 Z
+date: 2020-09-13 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.4
+        version: 0.11.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.10.4
+        version: 0.11.3
 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://github.com/dazuma/toys/blob/master/toys/CHANGELOG.md
+  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.11.3/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.4
+  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.11.3
 post_install_message: 
 rdoc_options: []
 require_paths: