toys 0.3.8 → 0.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9e8109a98db77604b1b398e113a6c8dff058645fe36f63dd08c013e92c06330
-  data.tar.gz: 9c706a637f851fa847fcc125b706499132d2fbdbbde12aaa6327f60bf95a1e3d
+  metadata.gz: c487937ebe79d0f42a022cc6bab700a49e684e5ec2c4dbfb6af52acb60b4876e
+  data.tar.gz: 65c95d766c8b2172099ed6be196a46740b4e05753bb3df455daf54c88ab4e6fc
 SHA512:
-  metadata.gz: 6695774bf47169ccb18aa06fe45164229e75c8d20fcca24e79187d4f3e747b79adc80a24974dd8d7c0c2c3f4077225ce4362ee0d408bcb7e7213313ded926dfc
-  data.tar.gz: e04182467471e21017b659b0b5366f9850a42b61b350edc8c46472d171dad4db244e03e4abac76fe1328beab9fcfbb72c97f7ba135939c6acc1524003ecce9c2
+  metadata.gz: 13c9507f71773f10696ba52f017975b87204329b1e8ec54fc2c6fdf4ec788469badde38b71573766e425bddd0cdd409ce80e76aa77ad0169e7d15a6e1fb38c4e
+  data.tar.gz: b7aaacef8a2017439390647ce2d519081ccda7ee27f34a3d06881040d2ebb6d906ea4e06d64dbc24179ed6642cb0cf2c1651facfb616a97fb8951db0e045a6fc

data/.yardopts

@@ -8,4 +8,3 @@ README.md
 LICENSE.md
 CHANGELOG.md
 docs/guide.md
-docs/tutorial.md

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History
 
+### 0.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
+* ADDED: Ability to disable argument parsing
+* ADDED: Rdoc template
+* ADDED: Exec#exec_proc and Exec#exec_tool that supports all the stream redirects
+* 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
 
 * CHANGED: Renamed helpers to mixins.

data/README.md

@@ -16,7 +16,7 @@ them. Furthermore, when writing new scripts, I was repeating the same
 OptionParser boilerplate and common functionality.
 
 Toys was designed to address those problems by providing a framework for
-writing and organizing command line scripts. You provide the actual script
+writing and organizing your own command line scripts. You provide the actual
 functionality, and Toys takes care of all the other details expected from a
 good command line tool. It provides a streamlined interface for defining and
 handling command line flags and positional arguments, and sensible ways to
@@ -25,14 +25,14 @@ usage information at a glance, and it also provides a search feature to help
 you find the script you need.
 
 Toys can also be used to share scripts. For example, it can be used instead of
-Rake to provide build and test scripts for a project--- tools that, unlike Rake
+Rake to provide build and test scripts for a project—tools that, unlike Rake
 tasks, can be invoked and passed arguments using familiar unix command line
 arguments and flags. The Toys github repo itself comes with Toys configs
 instead of Rakefiles.
 
 Unlike most command line frameworks, Toys is *not primarily* designed to help
 you build and ship a custom command line binary written in Ruby. However, you
-*can* use it in that way by building witn the "toys-core" API, available as a
+*can* use it in that way by building with the "toys-core" API, available as a
 separate gem. For more info on using toys-core, see
 https://ruby-doc.info/gems/toys-core
 
@@ -63,9 +63,9 @@ The "system version" tool displays the current version of the toys gem.
 
 ### Write your first tool
 
-You can define tools by creating toys *config files*. Using your favorite
-editor, create a new file called `.toys.rb` (note the leading period) in your
-current directory. Copy the following into the file, and save it:
+You can define tools by creating a *Toys file*. Go into any directory, and,
+using your favorite editor, create a new file called `.toys.rb` (note the
+leading period). Copy the following into the file, and save it:
 
     tool "greet" do
       desc "My first tool!"
@@ -110,9 +110,7 @@ and basic console-based interfaces, and another library that makes it easy to
 spawn and control subprocesses. You can also take advantage of a variety of
 third-party libraries such as Highline and TTY.
 
-For a more detailed look at Toys, see the
-{file:docs/tutorial.md Extended Tutorial} and the
-{file:docs/guide.md User Guide}.
+For a more detailed look at Toys, see the {file:docs/guide.md User Guide}.
 
 ## Contributing
 

data/docs/guide.md

@@ -10,14 +10,13 @@ write and organize scripts to automate their workflows.
 
 Unlike most command line frameworks, Toys is *not primarily* designed to help
 you build and ship a custom command line binary written in Ruby. Rather, it
-provides a single multi-command binary called `toys`. You configure this binary
-by writing configuration files that define the commands that Toys recongizes.
-(You can, however, build your own custom command line binary using the separate
-**toys-core** library.)
+provides a single binary called `toys`. You define the commands recognized by
+the Toys binary by writing configuration files. (You can, however, build your
+own custom command line binary using the related **toys-core** library.)
 
 This user's guide covers everything you need to know to use Toys effectively.
 
-## Conceptual overview
+## Conceptual Overview
 
 Toys is a command line *framework*. It provides a binary called `toys` along
 with basic functions such as argument parsing and online help. You provide the
@@ -42,9 +41,9 @@ directories**. It searches for these in the current directory, its ancestors,
 and in the Toys **search path**.
 
 Toys provides various features to help you write tools. This includes providing
-a **logger** for each tool, **helper modules** that provide common functions a
-tool can call, and **templates** which are prefabricated tools that you can
-configure for your needs.
+a **logger** for each tool, **mixins** that provide common functions a tool can
+call (such as controlling subprocesses and styling output), and **templates**
+which are prefabricated tools that you can configure for your needs.
 
 Finally, Toys provides useful **built-in behavior**, including automatically
 providing flags to display help screens and set verbosity. It also includes a
@@ -89,7 +88,7 @@ argument.
 
 Namespaces such as `system` are themselves tools and can be executed like any
 other tool. In the above case, it takes the argument `frodo`, determines it has
-no subtool of that name, and prints an error message. Most commonly, though,
+no subtool of that name, and prints an error message. More commonly, though,
 you might execute a namespace without arguments:
 
     toys system
@@ -128,17 +127,18 @@ optional **values** for flags. Following are a few examples.
 
 Pass a single short flag (for verbose output).
 
-    toys -v
+    toys system version -v
 
 Pass multiple long flags (for verbose output and recursive subtool search).
 
-    toys --verbose --recursive
+    toys system version --verbose --recursive
 
 You can combine short flags. This does the same as the previous example.
 
-    toys -rv
+    toys system version -rv
 
-Pass a value using a long flag. This searches subtools for the keyword `build`.
+Pass a value using a long flag. The root tool supports the `--search` flag to
+search for tools that have the given keyword.
 
     toys --search=build
     toys --search build
@@ -1095,46 +1095,756 @@ Additional mixins are forthcoming...
 
 ## Sharing Code
 
-
+As you accumulate additional and more complex tools, you may find that some of
+your tools need to share some common configuration, data, or logic. You might,
+for example, have a set of admin scripts that need to do some common
+authentication. This section describes several techniques for sharing code
+between tools, and describes the scope of Ruby structures, such as methods,
+classes, and constants, that you might define in your tools.
 
 ### Defining Mixins
 
+We saw earlier that you can mix a module (with all its methods) into your tool
+using the `include` directive. You can specify a module itself, or the name of
+a built-in mixin such as `:exec` or `:terminal`. But you can also define your
+own mixin using the `mixin` directive. A mixin defined in a tool can be
+`include`d in that tool or any of its subtools or their subtools, recursively,
+so it's a useful way to share code. Here's how that works.
+
+Define a mixin using the `mixin` directive, and give it a name and a block. In
+the block, you can define methods that will be made available to any tool that
+includes the mixin, in the same way that you can include a Ruby module.
+
+(Unlike full modules, however, mixins allow only methods to be shared. Mixins
+do not support constants. See the next section on using constants to learn how
+constants are treated by Toys.)
 
+Here's an example. Suppose you had common setup code that you wanted to share
+among your testing tools.
+
+    tool "test" do
+      # Define a mixin, which is just a collection of methods.
+      mixin "common_test_code" do
+        def setup
+          # Do setup here
+        end
+      end
+
+      tool "unit" do
+        # Include the mixin by name
+        include "common_test_code"
+        def run
+          setup  # Mixin methods are made available
+          puts "run only unit tests here..."
+        end
+      end
+
+      tool "integration" do
+        include "common_test_code"
+        def run
+          setup
+          puts "run only integration tests here..."
+        end
+      end
+    end
+
+A mixin is available to the tool in which it is defined, and any subtools and
+descendants defined at the same point in the Toys search path, but not from
+tools defined in a different point in the search path. For example, if you
+define a mixin in a file located in a `.toys` directory, it will be visible to
+descendant tools defined in that same directory, but not in a different `.toys`
+directory.
+
+A common technique, for example, would be to define a mixin in the index file
+in a Toys directory. You can then include it from any subtools defined in other
+files in that same directory.
 
 ### Using Constants
 
+You can define and use Ruby cconstants, i.e. names beginning with a capital
+letter, in a Toys file. However, they are subject to Ruby's rules regarding
+constant scope and lookup, which can be confusing, especially in a DSL. Toys
+tries to simplify those rules and make constant behavior somewhat tractable,
+but if you do use constants (which includes modules and classes defined in a
+Toys file), it is important to understand how they work.
+
+Constants in Toys are visible only within the Toys file in which they are
+defined. They always behave as though they are defined at the "top level" of
+the file. Even if you define a constant lexically "inside" a tool or a mixin,
+the constant does _not_ end up connected to that tool or mixin; it is always
+defined at the file level.
 
+    tool "test" do
+      tool "unit" do
+        # This constant is now usable for the rest of the file
+        API_KEY_FOR_TESTING = "12345"
+        def run
+          # It is visible here
+          puts API_KEY_FOR_TESTING
+        end
+      end
 
-### Expanding Templates
+      tool "integration" do
+        def run
+          # And it is still visible here
+          puts API_KEY_FOR_TESTING
+        end
+      end
+    end
 
+Because of this, it is highly recommended that you define constants only at the
+top level of a Toys file, so it doesn't "look" like it is scoped to something
+smaller. In particular, do not attempt to define constants in a mixin. The
+constants will not actually be connected to the mixin, and will not be
+available to tools that include the mixin.
 
+Modules and classes defined using the `module` or `class` keyword, are also
+constants, and thus follow the same rules. So you could, for example, define a
+"mixin" module like this:
+
+    module CommonTestCode
+      def setup
+        # Do setup here
+      end
+    end
+
+    tool "test" do
+      tool "unit" do
+        # Include the modules as a mixin
+        include CommonTestCode
+        def run
+          setup  # Module methods are made available
+          puts "run only unit tests here..."
+        end
+      end
+
+      tool "integration" do
+        include CommonTestCode
+        def run
+          setup
+          puts "run only integration tests here..."
+        end
+      end
+    end
+
+The difference between this technique and using the `mixin` directive we saw
+earlier, is the scope. The module here is accessed via a constant, and so, like
+any constant, it is visible only in the same file it is defined in. The `mixin`
+directive creates mixins that are visible from _all_ files at the same point in
+the search path.
+
+### Templates
+
+One final way to share code is to expand a **template**.
+
+A template is a class that inserts a bunch of lines into a Toys file. It is
+often used to "instantiate" prefabricated tools. For instance, Toys comes with
+a template called "minitest" that can generate a test tool for you. You
+instantiate it using the `expand` directive in your Toys file, like this:
+
+    expand :minitest
+
+And it will generate a tool called "test" that runs your test suite.
+
+Most templates generate one or more complete tools. However, it is possible for
+a template to generate just part of a tool, such as one or more description
+directives. In general, expanding a template simply adds directives to your
+Toys file.
+
+Many templates can be configured with options such as the name of the tool to
+generate, or details of the tool's behavior. This is done by passing additional
+arguments to the `expand` directive, such as:
+
+    expand :minitest, name: "unit-test", warnings: true
+
+Alternatively, you may provide a block to `expand`. It will yield the template
+to your block, letting you modify its properties:
+
+    expand :minitest do |tmpl|
+      tmpl.name "unit-test"
+      tmpl.warnings = true
+    end
+
+Toys provides several built-in templates that are useful for project and gem
+development, including templates that generate build, test, and documentation
+tools. You can read more about these templates in the next section on using
+Toys as a Rake replacement.
+
+You may also write your own templates. Here's how...
 
 #### Defining Templates
 
+One way to define a template is to use the `template` directive. Like the
+`mixin` directive, this creates a named template that you can access inside the
+current tool and any of its subtools.
 
+Following is a simple template example:
 
-## Advanced Tool Definition Techniques
+    template "greet" do
+      def initialize(name: "greet", whom: "world")
+        @name = name
+        @whom = whom
+      end
+      attr_accessor :name
+      attr_accessor :whom
+
+      to_expand do |template|
+        tool template.name do
+          desc "A greeting tool generated from a template"
+          run do
+            puts "Hello, #{template.whom}!"
+          end
+        end
+      end
+    end
+
+    expand "greet"
+
+    expand "greet", name: "greet-ruby", whom: "ruby"
+
+Above we created a template called "greet". A template is simply a class. It
+will typically have a constructor, and methods to access configuration
+properties. When the template is expanded, the class gets instantiated, and you
+can set those properties.
+
+Next, a template has a `to_expand` block. This block contains the Toys file
+directives that should be generated by the template. The template object is
+passed to the block, so it can access the template configuration when
+generating directives. The "greet" template in the above example generates a
+tool whose name is set by the template's `name` property.
+
+Notice that in the above example, we used `run do`, providing a _block_ for the
+tool's execution, rather than `def run`, providing a method. Both forms are
+valid and will work in a template (as well in a normal Toys file), but the
+block form is often useful in a template because you can access the `template`
+variable inside the block, whereas it would not be accessible if you defined a
+method. Similarly, if your template generates helper methods, and the body of
+those methods need access to the `template` variable, you can use
+[Module#define_method](http://ruby-doc.org/core/Module.html#method-i-define_method)
+instead of `def`.
+
+By convention, it is a good idea for configuration options for your template to
+be settable either as arguments to the constructor, or as `attr_accessor`
+properties. In this way, when you expand the template, options can be provided
+either as arguments to the `expand` directive, or in a block passed to the
+directive by setting properties on the template object.
+
+#### Template Classes
+
+Finally, templates are classes, and you can create a template directly as a
+class by including the
+[Toys::Template](https://www.rubydoc.info/gems/toys-core/Toys/Template) module
+in your class definition.
+
+    class GreetTemplate
+      include Toys::Template
+
+      def initialize(name: "greet", whom: "world")
+        @name = name
+        @whom = whom
+      end
+      attr_accessor :name
+      attr_accessor :whom
+
+      to_expand do |template|
+        tool template.name do
+          desc "A greeting tool generated from a template"
+          run do
+            puts "Hello, #{template.whom}!"
+          end
+        end
+      end
+    end
+
+    expand GreetTemplate, name: "greet-ruby", whom: "ruby"
+
+Remember that classes created this way are constants, and so the name
+`GreetTemplate` is available only inside the Toys file where it was defined.
+
+You must `include Toys::Template` if you define a template directly as a class,
+but you can omit it if you use the `template` directive to define the template.
+
+Defining templates as classes is also a useful way for third-party gems to
+provide Toys integration. For example, suppose you are writing a code analysis
+gem, and you want to make it easy for your users to create a Toys tool that
+invokes your analysis. Just write a template class in your gem, maybe named
+`MyAnalysis::ToysTemplate`. Now, just instruct your users to include the
+following in their Toys file:
+
+    require "my_analysis"
+    expand MyAnalysis::ToysTemplate
+
+## Toys as a Rake Replacement
+
+Toys was designed to organize scripts that may be "scoped" to a project or
+directory. Rake is also commonly used for this purpose: you can write a
+"Rakefile" that defines rake tasks scoped to a directory. In many cases, Toys
+can be used as a replacement for Rake. Indeed, the Toys repository itself,
+rather than a Rakefile, contains a `.toys.rb` file that defines tools for
+running tests, builds, and so forth.
+
+This section will explore the differences between Toys and Rake, and describe
+how to use Toys for some of the things traditionally done with Rake.
+
+### Comparing Toys and Rake
+
+Although Toys and Rake serve many of the same use cases, they have very
+different design goals, and it is useful to understand them.
+
+Rake's design is based on the classic "make" tool often provided in unix
+development environments. This design focuses on _targets_ and _dependencies_,
+and is meant for a world where you invoke an external compiler tool whenever
+changes are made to an individual source file or any of its dependencies. This
+"declarative" approach expresses very well the build process for programs
+written in C and similar compiled languages.
+
+Ruby, however, does not have an external compiler, and certainly not one that
+requires separate invocation for each source file as does the C compiler. So
+although Rake does support file dependencies, they are much less commonly used
+than in their Makefile cousins. Instead, in practice, most Rake tasks are not
+connected to a dependency at all; they are simply standalone tasks, what would
+be called "phony" targets in Makefile parlance. Such tasks are more imperative
+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.
+
+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
+do otherwise would clash with Rake's design goal of treating tasks as targets
+and dependencies. Toys does not have those design goals, so it is able to
+embrace the familiar ways to pass command line arguments.
+
+Toys actually borrows some of its design from the "mix" build tool used for
+Elixir and Erlang programs. Unlike C, the Erlang and Elixir compilers do their
+own dependency management, so mix does not require those capabilities. Instead,
+it focuses on making it easy to define imperative tasks.
+
+All told, this boils down to the principle of using the best tool for the job.
+There will be times when you need to express file-based dependencies in some of
+your build tasks. Rake will continue to be your friend in those cases. However,
+for high level tasks such as "run my tests", "build my YARD documentation", or
+"release my gem", you may find Toys easier to use.
+
+### From Rakefiles to Toys Files
+
+If you want to migrate some of your project's build tasks from Rake to Toys,
+there are some common patterns.
+
+When you use Rake for these tasks, you will typically require a particular file
+from your Rakefile, and/or write some code. Different tools will have different
+mechanisms for generating tasks. For example, a test task might be defined like
+this:
+
+    require "rake/testtask"
+    Rake::TestTask.new do |t|
+      t.test_files = FileList["test/test*.rb"]
+    end
+
+In Toys, templates are the standard mechanism for generating tools.
+
+    expand :minitest do |t|
+      t.files = ["test/test*.rb"]
+    end
+
+The following sections will describe some of the built-in templates provided by
+Toys to generate common build tools.
+
+Note that Rakefiles and Toys files can coexist in the same directory, so you
+can use either or both tools, depending on your needs.
+
+### Running Tests
+
+Toys provides a built-in template for minitest, called `:minitest`. It is
+implemented by the template class {Toys::Templates::Minitest}, and it uses the
+minitest gem, which is provided with most recent versions of Ruby.
+
+    expand :minitest, files: ["test/test*.rb"], libs: ["lib", "ext"]
+
+See the {Toys::Templates::Minitest} documentation for details on the various
+options.
+
+If you want to enforce code style using the "rubocop" gem, you can use the
+built-in `:rubocop` template:
+
+    expand :rubocop
+
+See the {Toys::Templates::Rubocop} documentation for details on the available
+options.
+
+### Building and Releasing Gems
+
+The `:gem_build` built-in template can generate a variety of build and release
+tools for gems, and is a useful alternative to the Rake tasks provided by
+bundler. It is implemented by {Toys::Templates::GemBuild}.
+
+Expanding `:gem_build` by default looks for a gemspec file in the current
+directory, and builds that gem into a `pkg` directory. You can also build a
+specific gem if you have multiple gemspec files.
 
+You may also configure the template so it also releases the gem to Rubygems
+(using your stored Rubygems credentials), by setting the `push_gem` option.
+For example, here is how to generate a "release" tool that builds and releases
+your gem:
 
+    expand :gem_build, name: "release", push_gem: true
+
+See the {Toys::Templates::GemBuild} documentation for details on the various
+options for build tools.
+
+To generate a "clean" tool, you can use the `:clean` built-in template. For
+example:
+
+    expand :clean, paths: ["pkg", "doc", "tmp"]
+
+See the {Toys::Templates::Clean} documentation for details on the various
+options for clean tools.
+
+### Building Documentation
+
+Toys provides an `:rdoc` template for creating tools that generate RDoc
+documentation, and a `:yardoc` template for creating tools that generate YARD.
+Both templates provide a variety of options for controlling documentation
+generation. See {Toys::Templates::Rdoc} and {Toys::Templates::Yardoc} for
+detailed information.
+
+Here's an example for YARD:
+
+    expand :yardoc, protected: true, markup: "markdown"
+
+### Gem Example
+
+Let's look at a complete example that combines the techniques above to provide
+all the basic tools for a Ruby gem. It includes:
+
+* A testing tool that can be run with `toys test`
+* Code style checking using Rubocop, run with `toys rubocop`
+* Documentation building using Yardoc, run with `toys yardoc`
+* Gem building, run with `toys build`
+* Gem build and release to Rubygems.org, run with `toys release`
+* A full CI tool, run with `toys ci`, that can be run from your favorite CI
+  system. It runs the tests and style checks, and checks (but does not
+  actually build) the documentation for warnings and completeness.
+
+Below is the full annotated `.toys.rb` file. For many gems, you could drop this
+into the gem source repo with minimal or no modifications. Indeed, this is
+essentially identical to the Toys files provided for the **toys** and
+**toys-core** gems themselves.
+
+    # A "clean" tool that cleans out gem builds (from the pkg directory), and
+    # documentation builds (from doc and .yardoc)
+    expand :clean, paths: ["pkg", "doc", ".yardoc"]
+
+    # This is the "test" tool.
+    expand :minitest, libs: ["lib", "test"]
+
+    # This is the "rubocop" tool.
+    expand :rubocop
+
+    # This is the "yardoc" tool. We cause it to fail on warnings and if there
+    # are any undocumented objects, which is useful for CI. We also configure
+    # the tool so it recognizes the "--no-output" flag. The CI tool will use
+    # this flag to invoke yardoc but suppress output, because it just wants to
+    # check for warnings.
+    expand :yardoc do |t|
+      t.generate_output_flag = true
+      t.fail_on_warning = true
+      t.fail_on_undocumented_objects = true
+    end
+
+    # The normal "build" tool that just builds a gem into the pkg directory.
+    expand :gem_build
+
+    # A full gem "release" tool that builds the gem, and pushes it to rubygems.
+    # This assumes your local rubygems configuration is set up with the proper
+    # credentials.
+    expand :gem_build, name: "release", push_gem: true
+
+    # Now we have a full CI tool. It runs the test, rubocop, and yardoc tools
+    # and checks for errors. This tool could be invoked from Travis-CI or
+    # similar CI system.
+    tool "ci" do
+      # The :exec mixin provides the exec_tool() method that we will use to run
+      # other tools and check their exit status.
+      include :exec
+      # The :terminal mixin provides an enhanced "puts" method that lets you
+      # write styled text to the terminal.
+      include :terminal
+
+      # A helper method, that runs a tool and outputs the result. It also
+      # terminates if the tool reported an error.
+      def run_stage(name, tool)
+        if exec_tool(tool).success?
+          puts("** #{name} passed", :green, :bold)
+          puts
+        else
+          puts("** CI terminated: #{name} failed!", :red, :bold)
+          exit(1)
+        end
+      end
+
+      # The main run method. It just calls the above helper method for the
+      # three tools we want to run for CI
+      def run
+        run_stage("Tests", ["test"])
+        run_stage("Style checker", ["rubocop"])
+        run_stage("Docs generation", ["yardoc", "--no-output"])
+      end
+    end
+
+## Advanced Tool Definition Techniques
+
+This section covers some additional features that are often useful for writing
+tools. I've labeled them "advanced", but all that really means is that this
+user's guide didn't happen to have covered them until this section. Each of
+these features is very useful for certain types of tools, and it is good at
+least to know that you *can* do these things, even if you don't use them
+regularly.
 
 ### Aliases
 
+An **alias** is simply an alternate name for a tool. For example, suppose you
+have a tool called `test` that you run with `toys test`. You could define an
+alias `t` that points to `test`; then you can run the same tool with `toys t`.
+
+To define an alias, use the `alias_tool` directive:
+
+    tool "test" do
+      # Define test tool here...
+    end
+
+    alias_tool "t", "test"
+
+You may create an alias of a subtool, but the alias must have the same parent
+(namespace) tool as the target tool. For example:
+
+    tool "gem" do
+      tool "test" do
+        # Define test tool here...
+      end
 
+      # Allows you to invoke `toys gem t`
+      alias_tool "t", "test"
+    end
 
 ### Custom Acceptors
 
+We saw earlier that flags and positional arguments can have acceptors, which
+control the allowed format, and may also convert the string argument to a Ruby
+object. By default, Toys supports the same acceptors recognized by Ruby's
+OptionParser library. And like OptionParser, Toys also lets you define your own
+acceptors.
+
+Define an acceptor using the `acceptor` directive. You provide a name for the
+acceptor, and specify how to validate input strings and how to convert input
+strings to Ruby objects. You may then reference the acceptor in that tool or
+any of its subtools or their subtools, recursively.
+
+There are several ways to define an acceptor.
+
+You may validate input strings against a regular expression, by passing the
+regex to the `acceptor` directive. You may also optionally provide a block to
+convert input strings to objects (or omit the block to use the original string
+as the option value.) For example, a simple hexadecimal input acceptor might
+look like this:
+
+    acceptor("hex", /^[0-9a-fA-F]+$/) { |input| input.to_i(16) }
+
+You may also accept enum values by passing an array of valid values to the
+`acceptor` directive. Inputs will be matched against the `to_s` form of the
+given values, and will be converted to the value itself. For example, one way
+to accept integers from 1 to 5 is:
+
+    acceptor("1to5", [1, 2, 3, 4, 5])
 
+There are various other options. See the reference documentation for
+[Toys::DSL::Tool#acceptor](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:acceptor).
+
+An acceptor is available to the tool in which it is defined, and any subtools
+and descendants defined at the same point in the Toys search path, but not from
+tools defined in a different point in the search path. For example, if you
+define an acceptor in a file located in a `.toys` directory, it will be visible
+to descendant tools defined in that same directory, but not in a different
+`.toys` directory.
+
+A common technique, for example, would be to define an acceptor in the index
+file in a Toys directory. You can then include it from any subtools defined in
+other files in that same directory.
 
 ### Controlling Built-in Flags
 
+Earlier we saw that certain flags are added automatically to every tool:
+`--verbose`, `--quiet`, `--help`, and so forth. You may occasionally want to
+disable some of these "built-in" flags. There are two ways to do so:
+
+If you want to use one of the built-in flags for another purpose, simply define
+the flag as you choose. Flags explicitly defined by your tool take precedence
+over the built-ins.
+
+For example, normally two built-in flags are provided to decrease the verbosity
+level: `-q` and `--quiet`. If you define `-q` yourself—for example to activate
+a "quick" mode—then `-q` will be repurposed for your flag, but `--quiet` will
+still be present to decrease verbosity.
+
+    # Repurposes -q to set the "quick" option instead of "quiet"
+    flag :quick, "-q"
+
+You may also completely disable a flag, and _not_ repurpose it, using the
+`disable_flag` directive. It lets you mark one or more flags as "never use".
 
+For example, if you disable the `-q` flag, then `-q` will no longer be a
+built-in flag that decreases the verbosity, but `--quiet` will remain. To
+completely disable decreasing the verbosity, disable both `-q` and `--quiet`.
 
-### Middleware
+    # Disables -q but leaves --quiet
+    disable_flag "-q"
 
+    # Completely disables decreasing verbosity
+    disable_flag "-q", "--quiet"
 
+### Disabling Argument Parsing
 
-## Toys Administration using the System Tools
+Normally Toys handles parsing command line arguments for you. This makes
+writing tools easier, but also allows Toys to generate documentation
+automatically for flags and arguments. However, occasionally you'll not want
+Toys to perform any parsing, but just to give you the command line arguments
+raw. One common case is if your tool turns around and passes its arguments to
+another subprocess.
+
+To disable argument parsing, use the `disable_argument_parsing` directive. This
+directive disables parsing and validation of flags and positional arguments.
+(Thus, it is incompatible with specifying any flags or arguments for the tool.)
+Instead, you can retrieve the raw arguments using the
+[Toys::Tool#args method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:args).
+
+Here is an example that wraps calls to git:
+
+    tool "my-git" do
+      desc "Prints a message, and then calls git normally"
+      disable_argument_parsing
+      def run
+        puts "Calling my-git!"
+        Kernel.exec(["git"] + args)
+      end
+    end
 
+### Activating Gems
+
+Sometimes implementing a tool will require a third-party gem. Some mixins also
+utilize a gem. Toys provides a way to help the user install such gems if
+needed.
+
+If the gem is needed to *define* the tool, use the `gem` directive to ensure
+the gem is installed and activated. This takes the name of the gem, and an
+optional set of version requirements. If a gem matching the given version
+requirements is installed, it is activated. If not, the gem is installed (which
+the user can confirm or abort). Or, if Toys is being run in a bundle, a message
+is printed informing the user that they need to add the gem to their Gemfile.
+
+For example, here's a way to configure a tool with flags for each of the
+HighLine styles:
+
+    tool "highline-styles-demo" do
+      gem "highline", "~> 2.0"
+      require "highline"
+      HighLine::BuiltinStyles::STYLES.each do |style|
+        style = style.downcase
+        flag style.to_sym, "--#{style}", "Apply #{style} to the text"
+      end
+      def run
+        # ...
+
+If the gem is *not* needed to define the tool, but is needed to *run* the tool,
+then you can call
+[Toys::Tool#gem](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:gem) from
+your `run` method. Here's an example:
+
+    tool "rake" do
+      disable_argument_passing
+      def run
+        gem "rake", "~> 12.0"
+        Kernel.exec(["rake"] + args)
+      end
+    end
 
+If a gem satisfying the given version constraints is already activated, it
+remains active. If a gem with a conflicting version is already activated, an
+exception is raised.
 
-## Embedding Toys
+If you are not in the Toys DSL context—e.g. you are writing a class-based
+mixin—you should use
+[Toys::Utils::Gems.activate](https://www.rubydoc.info/gems/toys-core/Toys%2FUtils%2FGems:activate)
+instead. For example:
+
+    Toys::Utils::Gems.activate("highline", "~> 2.0")
+
+Note these methods are a bit different from the
+[gem method](http://ruby-doc.org/stdlib-2.5.1/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.
+
+## Toys Administration Using the System Tools
+
+Toys comes with a few built-in tools, including some that let you administer
+Toys itself. These tools live in the `system` namespace.
+
+### Getting the Toys Version
+
+You can get the current version of Toys by running:
+
+    toys system version
+
+Note that the same output can be obtained by passing the `--version` flag to
+the root tool:
+
+    toys --version
+
+### Upgrading Toys
+
+To update Toys to the latest released version, run:
+
+    toys system update
+
+This will determine the latest version from Rubygems, and update your Toys
+installation if it is not already current.
+
+Normall it asks you for confirmation before downloading. To disable interactive
+confirmation, pass the `--yes` flag.
+
+A similar effect can of course be obtained simply by `gem install toys`.
+
+## Writing Your Own CLI Using Toys
+
+Toys is not primarily designed to help you write a custom command-line binary,
+but you can use it in that fashion. Toys is factored into two gems:
+**toys-core**, which includes all the underlying machinery for creating
+command-line binaries, and **toys**, which is really just a wrapper that
+provides the `toys` binary itself and its built-in commands and behavior. To
+write your own command line binary based on the Toys system, just require the
+**toys-core** gem and configure your binary the way you want.
+
+Toys-Core is modular and lets you customize much of the behavior of a command
+line binary. For example:
+
+*   Toys itself automatically adds a number of flags, such as `--verbose` and
+    `--help`, to each tool. Toys-Core lets you customize what flags are
+    automatically added for your own command line binary.
+*   Toys itself provides a default way to run tools that have no `run` method:
+    it assumes such tools are namespaces, and displays the online help screen.
+    Toys-Core lets you provide an alternate default run method for your own
+    command line binary.
+*   Toys itself provides several built-in tools, such as `do`, and `system`.
+    Toys-Core lets your own command line binary define its own built-in tools.
+*   Toys itself implements a particular search path for user-provided Toys
+    files, and looks for specific file and directory names such as `.toys.rb`.
+    Toys-Core lets you change the search path, the file/directory names, or
+    disable user-provided Toys files altogether for your own command line
+    binary. Indeed, most command line binaries do not need user-customizable
+    tools, and can ship with only built-in tools.
+*   Toys itself has a particular way of displaying online help and displaying
+    errors. Toys-Core lets your own command line binary customize these.
+
+For more information, see the
+[Toys-Core documentation](https://www.rubydoc.info/gems/toys-core/).