toys 0.3.7.1 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 712c3527fa2521408e41064789e32d6af61c71d6b1552059cbd076d3460ab93d
-  data.tar.gz: 3434cd2b2486b7c296e3cedc4bed96ac12b68110e4f5a94ceca4885251469754
+  metadata.gz: c9e8109a98db77604b1b398e113a6c8dff058645fe36f63dd08c013e92c06330
+  data.tar.gz: 9c706a637f851fa847fcc125b706499132d2fbdbbde12aaa6327f60bf95a1e3d
 SHA512:
-  metadata.gz: 88d801b601cd339ad650dd94814e5b49e26d0df8358b80fc93857571c09fb9e981c4a0f06e3751adf6fbfd5137812f07ed8f74f7dea33f3ce786be75b298727a
-  data.tar.gz: 562e0dd6893833a2cf9132986d8ea272308a554cccfca64bfbe1a9c06c69018157f6914e9958218e2486d6be8a794aef272246a9e03e932db3d4f8c5fa29697f
+  metadata.gz: 6695774bf47169ccb18aa06fe45164229e75c8d20fcca24e79187d4f3e747b79adc80a24974dd8d7c0c2c3f4077225ce4362ee0d408bcb7e7213313ded926dfc
+  data.tar.gz: e04182467471e21017b659b0b5366f9850a42b61b350edc8c46472d171dad4db244e03e4abac76fe1328beab9fcfbb72c97f7ba135939c6acc1524003ecce9c2

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release History
 
+### 0.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
 
 * FIXED: Fix crash in system update.

data/README.md

@@ -30,10 +30,11 @@ 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.
 
-You can also use the core functionality of Toys to create your own command line
-binaries, by using the *toys-core* API, which is available as a separate gem.
-For more info on using toys-core, see
-[https://ruby-doc.info/gems/toys-core](https://ruby-doc.info/gems/toys-core).
+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
+separate gem. For more info on using toys-core, see
+https://ruby-doc.info/gems/toys-core
 
 ## Quick Start
 
@@ -85,7 +86,7 @@ The tool also recognizes a flag on the command line. Try this:
 Toys provides a rich set of features for defining command line arguments and
 flags. It can also validate arguments. Try this:
 
-    toys greet --hello
+    toys greet --bye
 
 Notice that Toys automatically generated a usage summary for your tool. It can
 also automatically generate a full help screen, which you can view using the
@@ -95,22 +96,19 @@ also automatically generate a full help screen, which you can view using the
 
 ### Next steps
 
-You can add any number of additional tools to your `.toys.rb` file. Note also
-that the tools you create in that file are available only in this directory
-and its subdirectories. If you move outside the directory tree, Toys will not
-use that file. Thus, you can define tools scoped to particular directories and
-projects.
+You can add any number of additional tools to your `.toys.rb` config file. Note
+also that the tools you create in the config file are available only in this
+directory and its subdirectories. If you move into a different directory tree,
+Toys will instead look for a config file in that directory. Thus, you can
+define tools scoped to particular projects. You can also define "global" tools
+by creating a `.toys.rb` config in your home directory.
 
-Toys also lets you create hierarchies of tools. The "system version" tool you
-tried earlier is an example. The "system" tool is treated as a namespace, and
-various subtools, such as "version", are available under that namespace.
-
-Toys provides a rich set of useful libraries for writing tools. It gives you a
-logger and automatically provides flags to control verbosity of log output. It
-includes a simple library that you can use to produce styled output 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.
+Toys provides a rich set of useful libraries for writing tools and subtools. It
+gives you a logger and automatically provides flags to control verbosity of log
+output. It includes a simple library that you can use to produce styled output
+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
@@ -123,8 +121,7 @@ highly experimental, and the code is evolving very rapidly. Please contact the
 author before embarking on a major pull request. More detailed contribution
 guidelines will be provided when the software stabilizes further.
 
-The source can be found on Github at
-[https://github.com/dazuma/toys](https://github.com/dazuma/toys)
+The source can be found on Github at https://github.com/dazuma/toys
 
 ## License
 

data/builtins/system.rb

@@ -65,7 +65,7 @@ tool "update" do
         result = terminal.spinner(leading_text: "Installing Toys version #{latest_version}... ",
                                   final_text: "Done.\n") do
           exec(["gem", "install", "toys", "--version", latest_version.to_s],
-               out_to: :capture, err_to: :capture)
+               out: :capture, err: :capture)
         end
         if result.error?
           puts(result.captured_out + result.captured_err)

data/docs/guide.md

@@ -8,38 +8,45 @@ reporting, logging, help text, and many other details for you. Toys is designed
 for software developers, IT specialists, and other power users who want to
 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.)
+
 This user's guide covers everything you need to know to use Toys effectively.
 
 ## 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
-actual behavior of the toys binary by writing **configuration files**.
+actual behavior of the Toys binary by writing **Toys files**.
 
-Toys is a multi-command binary. You may define a collection of commands, called
+Toys is a multi-command binary. You may define any number of commands, called
 **tools**, which can be invoked by passing the tool name as an argument to the
 `toys` binary. Tools are arranged in a hierarchy; a tool may be a **namespace**
-that has *subtools*.
+that has **subtools**.
 
 Tools may recognize command line arguments in the form of **flags** and
 **positional arguments**. Flags can optionally take **values**, while
 positional arguments may be **required** or **optional**.
 
-The configuration of a tool may define **descriptions**, for the tool itself,
+The configuration of a tool may include **descriptions**, for the tool itself,
 and for each command line argument. These descriptions are displayed in the
 tool's **online help** screen. Descriptions come in **long** and **short**
 forms, which appear in different styles of help.
 
-Toys searches for configuration in specifically-named **configuration files**
-and **configuration directories**. It searches for these in the current
-directory, its ancestors, and in a **configuration search path**.
+Toys searches for tools in specifically-named **Toys files** and **Toys
+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 you can add to
-your configuration.
+tool can call, and **templates** which are prefabricated tools that you can
+configure for your needs.
 
-Finally, Toys provides certain **built-in behavior**, including automatically
+Finally, Toys provides useful **built-in behavior**, including automatically
 providing flags to display help screens and set verbosity. It also includes a
 built-in namespace of **system tools** that let you inspect and configure the
 Toys system itself.
@@ -55,10 +62,10 @@ The general form of the `toys` command line is:
 
 ### Tools
 
-The *tool name* consists of all the command line arguments until the first
-argument that begins with a hyphen (which is interpreted as a *flag*), until
+The **tool name** consists of all the command line arguments until the first
+argument that begins with a hyphen (which is interpreted as a **flag**), until
 no tool with that name exists (in which case the argument is treated as the
-first *positional argument*), or until there are no more arguments.
+first **positional argument**), or until there are no more arguments.
 
 For example, in the following command:
 
@@ -67,31 +74,31 @@ For example, in the following command:
 
 The tool name is `system version`. Notice that the tool name may have multiple
 words. Tools are arranged hierarchically. In this case, `system` is a
-*namespace* for tools related to the Toys system, and `version` is one of its
-*subtools*. It prints the current Toys version.
+**namespace** for tools related to the Toys system, and `version` is one of its
+**subtools**. It prints the current Toys version.
 
 In the following command:
 
          |TOOL| |ARG|
-    toys system blah
+    toys system frodo
 
-There is no subtool `blah` under the `system` namespace, so Toys works backward
-until it finds an existing tool. In this case, the `system` namespace itself
-does exist, so it is interpreted as the tool, and `blah` is interpreted as an
-argument passed to it.
+There is no subtool `frodo` under the `system` namespace, so Toys works
+backward until it finds an existing tool. In this case, the `system` namespace
+itself does exist, so Toys runs *it* as the tool, and passes it `frodo` as an
+argument.
 
 Namespaces such as `system` are themselves tools and can be executed like any
-other tool. In the above case, its function is to take the argument `blah`,
-note that it has no subtool of that name, and print an error message. Most
-commonly, though, you might execute a namespace without arguments:
+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,
+you might execute a namespace without arguments:
 
     toys system
 
-This displays the *online help screen* for the `system` namespace, which
+This displays the **online help screen** for the `system` namespace, which
 includes a list of all its subtools and what they do.
 
-It is also legitimate for the tool name to be empty. This invokes the "root"
-tool, the toplevel namespace:
+It is also legitimate for the tool name to be empty. This invokes the **root
+tool**, the toplevel namespace:
 
     toys
 
@@ -100,30 +107,30 @@ of its subtools.
 
 One last example:
 
-    toys blah
+    toys frodo
 
-If there is no tool called `blah` in the toplevel namespace, then once again,
-`blah` is interpreted as an argument to the root tool. The root tool responds
-by printing an error message that the `blah` tool does not exist.
+If there is no tool called `frodo` in the toplevel namespace, then once again,
+`frodo` is interpreted as an argument to the root tool. The root tool responds
+by printing an error message that the `frodo` tool does not exist.
 
 ### Flags
 
-Flags are generally arguments that begin with a hyphen, and are used to set
+**Flags** are generally arguments that begin with a hyphen, and are used to set
 options for a tool.
 
 Each tool recognizes a specific set of flags. If you pass an unknown flag to a
 tool, the tool will generally display an error message.
 
-Toys follows the typical unix conventions for flags: you can provide short
-(single-character) flags with a single hyphen, or long flags with a double
-hyphen. You can also provide optional values for flags. Following are a few
-examples.
+Toys follows the typical unix conventions for flags, specifically those covered
+by Ruby's OptionParser library. You can provide short (single-character) flags
+with a single hyphen, or long flags with a double hyphen. You can also provide
+optional **values** for flags. Following are a few examples.
 
 Pass a single short flag (for verbose output).
 
     toys -v
 
-Pass multiple long flags (verbose output, and recursive subtool search).
+Pass multiple long flags (for verbose output and recursive subtool search).
 
     toys --verbose --recursive
 
@@ -150,7 +157,7 @@ arguments, even if they begin with hyphens. For example:
 
 That will cause `--recursive` to be treated as a positional argument. (In this
 case, as we saw earlier, the root tool will respond by printing an error
-message that no subtool named `--recursive` exists.)
+message that no tool named `--recursive` exists.)
 
 Note that a single hyphen by itself `-` is not considered a flag, nor does it
 disable flag parsing. It is treated as a normal positional argument.
@@ -188,59 +195,61 @@ Finally, the root tool also supports:
 ### Positional Arguments
 
 Any arguments not recognized as flags or flag arguments, are interpreted as
-positional arguments. Positional arguments are recognized in order and may be
-required or optional.
+**positional arguments**. Positional arguments are recognized in order and may
+be required or optional.
 
 Each tool recognizes a specific set of positional arguments. If you do not pass
 a value for a required argument, or you pass too many arguments, the tool will
 generally display an error message.
 
-For example, the `do` tool runs multiple tools in sequence. It recognizes any
-number of positional arguments. Those arguments specify which tools to run and
-what arguments to pass to them. If, for example, you had a `build` tool and a
-`test` tool, you could run them in sequence with:
+For example, the built-in `do` tool runs multiple tools in sequence. It
+recognizes any number of positional arguments. Those arguments specify which
+tools to run and what arguments to pass to them. If, for example, you had a
+`build` tool and a `test` tool, you could run them in sequence with:
 
             |---ARGS---|
     toys do build , test
 
-The arguments `build`, `,`, and `test` are positional arguments to the `do`
-tool. (The `do` tool splits them using `,` as the delimiter.)
+The three arguments `build`, `,`, and `test` are positional arguments to the
+`do` tool. (The `do` tool uses `,` to delimit the tools that it should run.)
 
 Here is a more complex example illustrating the interaction between flags and
 positional arguments. Suppose we want to use `do` to display the help screens
 for the root tool and the system tool in sequence. That is, we want to run
 `toys --help` and `toys system --help` in sequence. We might start by trying:
 
+            |FLAG| |-ARGS-| |FLAG|
     toys do --help , system --help
 
 However, this simply displays the help for the `do` tool itself, because the
-first `--help` is interpreted as a flag for `do` instead of a positional
-argument specifying the first tool for `do` to run. We need to force `do` to
-treat all its arguments as positional, and we can do that by starting with `--`
-like so:
+first `--help` is interpreted as a flag for `do`. What we actually want is for
+`do` to treat it as a positional argument specifying the first tool to run. So
+Let's force `do` to treat all its arguments as positional, by starting with
+`--` like so:
 
                |--------ARGS--------|
     toys do -- --help , system --help
 
 ## Defining Tools
 
-Tools are defined by writing Toys *configuration files*. The simplest form of a
-configuration file is a file named `.toys.rb` (note the leading period) in the
-current working directory. Such a file may define tools that are available in
-the current directory, and for this section we will assume we are writing such
-a file. The following section on "Understanding Configurations" will cover the
-larger concerns of how configuration files are looked up and how multiple
-configurations interact.
+In this section, you will learn how to define tools by writing a **Toys file**.
+
+A file named `.toys.rb` (note the leading period) in the current working
+directory defines tools available in that directory and its subdirectories. We
+will cover how to write tools, including specifying the functionality of the
+tool, the flags and arguments it takes, and how its description appears in the
+help screen.
 
-### Basic Config Syntax
+### Basic Toys Syntax
 
-The format of a Toys configuration file is a Ruby DSL including method calls
-and nested blocks. The actual DSL is specified in the
+The format of a Toys file is a Ruby DSL that includes directives, methods, and
+nested blocks. The actual DSL is specified in the
 [Toys::DSL::Tool class](https://www.rubydoc.info/gems/toys-core/Toys/DSL/Tool).
 
 To create a tool, write a `tool` block, giving the tool a name. Within the
-block, set the properties of the tool, including a description, the flags and
-arguments recognized by the tool, and the actual functionality of the tool.
+block, use directives to set the properties of the tool, including descriptions
+and the flags and arguments recognized by the tool. The actual functionality of
+the tool is set by defining a `run` method.
 
 Consider the following example:
 
@@ -267,16 +276,16 @@ details below.
 
 ### Descriptions
 
-Each tool may have a short and a long description. The short description is a
-generally a single string that is displayed with the tool name at the top of
-its help page, or in a subtool list. The long description can include multiple
-strings, which are displayed in multiple lines in the "description" section of
-the tool's help page. Long descriptions may include blank lines to separate
-paragraphs visually.
+Each tool may have a **short description** and/or a **long description**. The
+short description is a generally a single string that is displayed with the
+tool name, at the top of its help page or in a subtool list. The long
+description typically includes multiple strings, which are displayed in
+multiple lines in the "description" section of the tool's help page. Long
+descriptions may include blank lines to separate paragraphs visually.
 
 Each description string/line is word-wrapped by default when displayed. In the
-long description above, the first line is a bit longer than 80 characters, and
-may be word-wrapped if displayed on an 80-character terminal.
+long description example above, the first line is a bit longer than 80
+characters, and may be word-wrapped if displayed on an 80-character terminal.
 
 If you need to control the wrapping behavior, pass an array of strings for that
 line. Each array element will be considered a unit for wrapping purposes, and
@@ -285,18 +294,21 @@ illustrates how to prevent a line from being word-wrapped. This is also a
 useful technique for preserving spaces and indentation.
 
 For more details, see the reference documentation for
-[DSL::Tool#desc](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:desc)
+[Toys::DSL::Tool#desc](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:desc)
 and
-[DSL::Tool#long_desc](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:long_desc).
+[Toys::DSL::Tool#long_desc](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:long_desc).
 
 ### Positional Arguments
 
-Tools may recognize required and optional positional arguments. Each argument
-must provide a name, which defines how the argument value is exposed to the
-tool at execution time. The above example uses the DSL method
-[DSL::Tool#optional_arg](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:optional_arg)
-to declare an optional argument named `:whom`. If the argument is provided on
-the command line e.g.
+Tools may recognize any number of **positional arguments**. Each argument must
+have a name, which is a key that the tool can use to obtain the argument's
+value at execution time. Arguments may also have various properties controlling
+how values are validated and expressed.
+
+The above example uses the directive
+[Toys::DSL::Tool#optional_arg](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:optional_arg)
+to declare an **optional argument** named `:whom`. If the argument is provided
+on the command line e.g.
 
     toys greet ruby
 
@@ -308,108 +320,821 @@ argument is omitted, e.g.
 
 Then the option `:whom` is set to the default value `"world"`.
 
-Arguments may also be **required** which means they must be provided on the
+An argument may also be **required**, which means it must be provided on the
 command line; otherwise the tool will report a usage error. You may declare a
-required argument using the DSL method
-[DSL::Tool#required_arg](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:required_arg).
+required argument using the directive
+[Toys::DSL::Tool#required_arg](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:required_arg).
+
+#### Parsing Required and Optional Arguments
 
 When command line arguments are parsed, the required arguments are matched
 first, in order, followed by the optional arguments. For example:
 
-    tool "arguments" do
+    tool "args-demo" do
       optional_arg :arg2
       required_arg :arg1
       # ...
 
 If a user runs
 
-    toys arguments foo
+    toys args-demo foo
 
 Then the required argument `:arg1` will be set to `"foo"`, and the optional
 argument `:arg2` will not be set (i.e. it will remain `nil`).
 
 If the user runs:
 
-    toys arguments foo bar
+    toys args-demo foo bar
 
 Then `:arg1` is set to `"foo"`, and `:arg2` is set to `"bar"`.
 
 Running the following:
 
-    toys arguments
+    toys args-demo
 
 Will produce a usage error, because no value is set for the required argument
 `:arg1`. Similarly, running:
 
-    toys arguments foo bar baz
+    toys args-demo foo bar baz
 
-Will also produce an error, since the tool does not provide an argument to
+Will also produce an error, since the tool does not define an argument to
 match `"baz"`.
 
-You can also provide an "argument" to match all remaining unmatched arguments
-at the end, using the DSL method
-[DSL::Tool#remaining_args](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:remaining_args). For example:
+Optional arguments may declare a default value to be used if the argument is
+not provided on the command line. For example:
 
-    tool "arguments" do
-      optional_arg :arg2
+    tool "args-demo" do
+      required_arg :arg1
+      optional_arg :arg2, default: "the-default"
+      # ...
+
+Now running the following:
+
+    toys args-demo foo
+
+Will set the required argument to `"foo"` as usual, and the optional argument,
+because it is not provided, will default to `"the-default"` instead of `nil`.
+
+#### Remaining Arguments
+
+Normally, unmatched arguments will result in an error message. However, you can
+provide an "argument" to match all **remaining** unmatched arguments at the
+end, using the directive
+[Toys::DSL::Tool#remaining_args](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:remaining_args).
+For example:
+
+    tool "args-demo" do
       required_arg :arg1
+      optional_arg :arg2
       remaining_args :arg3
       # ...
 
 Now, running:
 
-    toys arguments foo bar baz bey
+    toys args-demo foo bar baz bey
 
 Sets the following option data:
 
     {arg1: "foo", arg2: "bar", arg3: ["baz", "bey"]}
 
+If instead you run:
+
+    toys args-demo foo
+
+This sets the following option data:
+
+    {arg1: "foo", arg2: nil, arg3: []}
+
+Whereas your tool can include any number of `required_arg` and `optional_arg`
+directives, declaring any number of required and optional arguments, it can
+have only at most a single `remaining_args` directive.
+
+#### Descriptions and the Args DSL
+
 Positional arguments may also have short and long descriptions, which are
-displayed in online help.
+displayed in online help. Set descriptions via the `desc:` and `long_desc:`
+arguments to the argument directive. The `desc:` argument takes a single string
+description, while the `long_desc:` argument takes an array of strings. Here is
+an example:
+
+    required_arg :arg,
+                 desc: "This is a short description for the arg",
+                 long_desc: ["Long descriptions may have multiple lines.",
+                             "This is the second line."]
+
+See the above section on Descriptions for more information on how descriptions
+are rendered and word wrapped.
+
+Long descriptions may be unwieldly to write as a hash argument in this way. So
+Toys provides an alternate syntax for defining arguments using a block.
+
+    required_arg :arg do
+      desc "This is a short description for the arg"
+      long_desc "Long desc can be set as multiple lines together,",
+                "like this second line."
+      long_desc "Or you can call long_desc again to add more lines."
+    end
+
+For detailed info on configuring an argument using a block, see the
+[Toys::DSL::Arg class](https://www.rubydoc.info/gems/toys-core/Toys/DSL/Arg).
+
+#### Acceptors
+
+Finally, positional arguments may use **acceptors** to define how to validate
+arguments and convert them to Ruby objects for your tool to consume. By
+default, Toys will accept an argument string in any form, and expose it to your
+tool as a raw string. However, you may provide an acceptor to change this
+behavior.
+
+Acceptors are part of the OptionParser interface, and are described under the
+[type coercion](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#class-OptionParser-label-Type+Coercion)
+section. For example, you can provide the `Integer` class as an acceptor, which
+will validate that the argument is a well-formed integer, and convert it to an
+integer during parsing:
+
+    tool "args-demo" do
+      required_arg :age, accept: Integer
+      def run
+        age = option(:age)  # This is an integer
+        ...
+
+If you pass a non-integer for this argument, Toys will report a usage error.
+
+You may use any of the ready-to-use coercion types provided by OptionParser,
+including the special types such as
+[OptionParser::DecimalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#DecimalInteger)
+and
+[OptionParser::OctalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#OctalInteger).
+
+You may also create **custom acceptors**. See the section below on Custom
+Acceptors for more information.
 
 ### Flags
 
-Tools may also recognize flags on the command line. In our "greet" example, we
-declared a flag named `:shout`:
+Tools may also recognize **flags** on the command line. In our "greet" example,
+we declared a flag named `:shout`:
 
     flag :shout, "-s", "--shout", desc: "Greet loudly."
 
-(guid is still incomplete)
+Like a positional argument, a flag sets an option based on the command line
+arguments passed to the tool. In the case above, the `:shout` option is set to
+`true` if either `-s` or `--shout` is provided on the command line; otherwise
+it is set to `false`. Any number of short or long flags can be declared; they
+will be synonyms and have the same effect.
+
+#### Flag Types
+
+Toys recognizes the same syntax used by the standard OptionParser library. This
+means you can also declare a flag that can be both set and unset:
+
+    flag :shout, "--[no-]shout"
+
+If you do not provide any actual flags, Toys will infer a long flag from the
+name of the option. Hence, the following two definitions are equivalent:
+
+    flag :shout
+    flag :shout, "--shout"
+
+You can declare that a short or long flag takes a value:
+
+    flag :whom, "--whom=VALUE"
+    flag :whom, "--whom VALUE"
+    flag :whom, "-wVALUE"
+    flag :whom, "-w VALUE"
+
+You can also declare the value to be optional:
+
+    flag :whom, "--whom[=VALUE]"
+    flag :whom, "--whom [VALUE]"
+    flag :whom, "-wVALUE"
+    flag :whom, "-w VALUE"
+
+Note that if you define multiple flags together, they will all be coerced to
+the same "type". That is, if one takes a value, they all will implicitly take
+a value. (This is the same behavior as OptionParser.) In this example:
+
+    flag :whom, "-w", "--whom=VALUE"
+
+The `-w` flag will also implicitly take a value, because it is defined as an
+alias with another flag that takes a value.
+
+Note also that Toys will raise an error if those flags are incompatible. For
+example:
+
+    flag :whom, "-w[VALUE]", "--whom=VALUE"
+
+Raises an error because one flag's value is optional while the other is
+required. (Again, this is consistent with OptionParser's behavior.)
+
+#### Custom Acceptors
+
+Flags may use **acceptors** to define how to validate values and convert them
+to Ruby objects for your tool to consume. By default, Toys will accept a flag
+value string in any form, and expose it to your tool as a raw string. However,
+you may provide an acceptor to change this behavior.
 
-### The Execution Script
+Acceptors are part of the OptionParser interface, and are described under the
+[type coercion](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#class-OptionParser-label-Type+Coercion)
+section. For example, you can provide the `Integer` class as an acceptor, which
+will validate that the argument is a well-formed integer, and convert it to an
+integer during parsing:
 
-### Namespaces
+    tool "args-demo" do
+      flag :age, accept: Integer
+      def run
+        option(:age)  # This is an integer
+        ...
+
+If you pass a non-integer for this flag value, Toys will report a usage error.
+
+You may use any of the ready-to-use coercion types provided by OptionParser,
+including the special types such as
+[OptionParser::DecimalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#DecimalInteger)
+and
+[OptionParser::OctalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#OctalInteger).
+
+You may also create **custom acceptors**. See the section below on Custom
+Acceptors for more information.
+
+#### Defaults and Handlers
+
+Currently, flags are always optional and a flag can appear in a command line
+zero, one, or any number of times. If a flag is not passed in the command line
+arguments for a tool, by default its corresponding option value will be `nil`.
+
+You may change this by providing a default value for a flag:
+
+    flag :age, accept: Integer, default: 21
+
+If you pass a flag multiple times on the command line, by default the *last*
+appearance of the flag will take effect. That is, suppose you define this flag:
+
+    flag :shout, "--[no-]shout"
+
+Now if you pass `--shout --no-shout`, then the value of the `:shout` option
+will be `false`, i.e. the last value set on the command line. This is because a
+flag *sets* its option value, replacing any previous value. You may change this
+behavior by providing a **handler**.
+
+A handler is a proc that governs what a flag does to its option value. It takes
+two arguments, the new value given, and the previously set value (which might
+be the default value if this is the first appearance of the flag), and returns
+the new value that should be set. So effectively, the default behavior is
+equivalent to the following handler:
+
+    flag :shout, "--[no-]shout", handler: proc { | val, _prev| val }
+
+For example, most tools automatically get a "--verbose" flag. This flag may
+appear any number of times, and each appearance increases the verbosity. The
+value of this verbosity is an integer. This flag is actually implemented by
+Toys, as follows:
+
+    flag Toys::Tool::Keys::VERBOSITY, "-v", "--verbose",
+         default: 0,
+         handler: proc { |_val, prev| prev + 1 }
+
+Similarly, the "--quiet" flag, which decreases the verbosity, is implemented
+as follows:
+
+    flag Toys::Tool::Keys::VERBOSITY, "-q", "--quiet",
+         default: 0,
+         handler: proc { |_val, prev| prev - 1 }
+
+Note that both flags affect the same option value, `VERBOSITY`. The first
+increments it each time it appears, and the second decrements it. A tool can
+query this option and get an integer telling the requested verbosity level, as
+you will see below in the section on execution environment.
+
+#### Descriptions and the Flags DSL
+
+Flags may also have short and long descriptions, which are displayed in online
+help. Set descriptions via the `desc:` and `long_desc:` arguments to the flag
+directive. The `desc:` argument takes a single string description, while the
+`long_desc:` argument takes an array of strings. Here is an example:
+
+    flag :my_flag, "--my-flag",
+         desc: "This is a short description for the arg",
+         long_desc: ["Long descriptions may have multiple lines.",
+                     "This is the second line."]
+
+See the above section on Descriptions for more information on how descriptions
+are rendered and word wrapped.
+
+Long descriptions may be unwieldly to write as a hash argument in this way. So
+Toys provides an alternate syntax for defining flags using a block.
 
-## Understanding Configurations
+    flag :my_flag do
+      flags "--my-flag"
+      desc "This is a short description for the flag"
+      long_desc "Long desc can be set as multiple lines together,",
+                "like this second line."
+      long_desc "Or you can call long_desc again to add more lines."
+    end
+
+For detailed info on configuring an flag using a block, see the
+[Toys::DSL::Flag class](https://www.rubydoc.info/gems/toys-core/Toys/DSL/Flag).
+
+### Tool Execution Basics
+
+When you run a tool from the command line, Toys will build the tool based on
+its definition in a Toys file, and then it will attempt to execute it by
+calling the `run` method. Normally, you should define this method in each of
+your tools.
+
+Note: If you do not define the `run` method for a tool, Toys provides a default
+implementation that displays the tool's help screen. This is typically used for
+namespaces, as we shall see below. Most tools, however, should define `run`.
+
+Let's revisit the "greet" example we covered earlier.
+
+    tool "greet" do
+      optional_arg :whom, default: "world"
+      flag :shout, "-s", "--shout"
+
+      def run
+        greeting = "Hello, #{option(:whom)}!"
+        greeting.upcase! if option(:shout)
+        puts greeting
+      end
+    end
+
+Note how the `run` method uses the
+[Toys::Tool#option](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:option)
+method to access values that were assigned by flags or positional arguments.
+Note also that you can produce output or interact with the console using the
+normal Ruby `$stdout`, `$stderr`, and `$stdin` streams.
+
+If a tool's `run` method finishes normally, Toys will exit with a result code
+of 0, indicating success. You may exit immediately and/or provide a nonzero
+result using the
+[Toys::Tool#exit](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:exit)
+method:
+
+    def run
+      puts "Exiting with an error..."
+      exit(1)
+      puts "Will never get here."
+    end
+
+If your `run` method raises an exception, Toys will display the exception and
+exit with a nonzero code.
 
-## Helper Methods and Modules
+Finally, you may also define additional methods within the tool. These are
+available to be called by your `run` method, and can be used to decompose your
+tool implementation.
 
-### The Standard Helpers
+This should be enough to get you started implementing tools. A variety of
+additional features are available for your tool implementation and will be
+discussed further below. But first we will cover a few important topics.
+
+### Namespaces and Subtools
+
+Like many command line frameworks, Toys supports **subtools**. You may, for
+example create a tool called "test" that runs your tests for a particular
+project, but you might also want "test unit" and "test integration" tools to
+run specific subsets of the test suite. One way to do this, of course, is for
+the "test" tool to parse "unit" and "integration" as arguments. However, you
+could also define them as separate tools, subtools of "test".
+
+To define a subtool, create nested `tool` directives. Here's a simple example:
+
+    tool "test" do
+      tool "unit" do
+        def run
+          puts "run unit tests here..."
+        end
+      end
+
+      tool "integration" do
+        def run
+          puts "run integration tests here..."
+        end
+      end
+    end
+
+You can now invoke them like this:
+
+    toys test unit
+    toys test integration
+
+Notice in this case, the parent "test" tool itself has no `run` method. This is
+a common pattern: "test" is just a "container" for tools, a way of organizing
+your tools. In Toys terminology, it is called a **namespace**. But it is still
+a tool, and it can still be run:
+
+    toys test
+
+As discussed earlier, Toys provides a default implementation that displays the
+help screen, which includes a list of the subtools and their descriptions.
+
+As another example, the "root" tool is also normally a namespace. If you just
+run Toys with no arguments:
+
+    toys
+
+The root tool will display the overall help screen for Toys.
+
+Although it is a less common pattern, it is possible for a tool that has
+subtools to have its own `run` method:
+
+    tool "test" do
+      def run
+        puts "run all tests here..."
+      end
+
+      tool "unit" do
+        def run
+          puts "run only unit tests here..."
+        end
+      end
+
+      tool "integration" do
+        def run
+          puts "run only integration tests here..."
+        end
+      end
+    end
+
+Now running `toys test` will run its own implementation.
+
+(Yes, it is even possible to write a `run` method for the root tool. I don't
+recommend doing so, because then you lose the root tool's useful default
+implementation that lists all your tools.)
+
+Toys allows subtools to be nested arbitrarily deep. Although in practice, more
+than two or three levels of hierarchy can be confusing to use.
+
+## Understanding Toys Files
+
+Toys commands are defined in Toys files. We covered the basic syntax for these
+files in the above section on defining tools. In this section, we will take a
+deeper look at Toys files, including:
+
+* Defining subtools in their own files
+* Global and local Toys files
+* The `TOYS_PATH`
+* Overriding tools
+
+### Toys Directories
+
+So far we have been defining tools by writing a Toys file named `.toys.rb`
+located in the current working directory. This works great if you have a small
+number of fairly simple tools, but if you are defining many tools or tools with
+long or complex implementations, you may find it better to define some tools in
+separate files. You can have Toys load tools from multiple files by creating a
+**Toys directory**.
+
+A Toys directory is a directory called `.toys` located in the current working
+directory. Ruby files inside a Toys directory (or any of its subdirectories)
+are loaded when Toys looks for tool definitions. Furthermore, the name of the
+Ruby file (and indeed its path relative to the Toys directory) determines which
+tool it defines.
+
+For example, one way to create a "greet" tool, as we saw before, is to write a
+`.toys.rb` file in the current directory, and populate it like this:
+
+    tool "greet" do
+      optional_arg :whom, default: "world"
+      def run
+        puts "Hello, #{option(:whom)}"
+      end
+    end
+
+You could also create the same tool by creating a `.toys` directory, and then
+creating a file `greet.rb` inside that directory. The contents would be:
+
+    optional_arg :whom, default: "world"
+    def run
+      puts "Hello, #{option(:whom)}"
+    end
+
+Notice that we did not use a `tool "greet"` block here. That is because the
+name of the file `greet.rb` already provides a tool context: Toys already knows
+that we are defining a "greet" tool.
+
+If you do include a `tool` block inside the `greet.rb` file, it will create a
+*subtool* of `greet`. So, inside a Toys directory, the path to each Ruby file
+defines the "starting point" namespace for the tools defined in that file.
+
+If you create subdirectories inside a Toys directory, their names also
+contribute to the namespace of created tools. For example, if you create a
+directory `.toys/test` and a file `unit.rb` under that directory, it will
+create the tool `test unit`.
+
+    (current directory)
+    |
+    +- .toys/
+       |
+       +- greet.rb   <-- defines "greet" (and subtools)
+       |
+       +- test/
+          |
+          +- unit.rb   <-- defines "test unit" (and its subtools)
+
+Once again, `test unit` is the "starting point" for tools defined in the
+`.toys/test/unit.rb` file. Declarations and methods at the top level of that
+file will define the `test unit` tool. Any `tool` blocks you add to that file
+will define subtools of `test unit`.
+
+#### Index Files
+
+The file name `.toys.rb` can also be used inside Toys directories and
+subdirectories. Such files are called **index files**, and they create tools
+with the directory as the "starting point" namespace. For example, if you
+create an index file directly underneath a `.toys` directory, it will define
+top level tools (just like a `.toys.rb` file in the current directory.) An
+index file located inside `.toys/test` will define tools with `test` as the
+"starting point" namespace.
+
+    (current directory)
+    |
+    +- .toys/
+       |
+       +- .toys.rb   <-- index file, defines tools at the top level
+       |
+       +- greet.rb   <-- defines "greet" (and subtools)
+       |
+       +- test/
+          |
+          +- .toys.rb   <-- index file, defines "test" (and its subtools)
+          |
+          +- unit.rb   <-- defines "test unit" (and its subtools)
+
+Index files give you some flexibility for organizing your tools. For example,
+if you have a number of subtools of `test`, including a lot of small tools and
+one big complex subtool called `unit`, you might define all the simple tools in
+the index file `.toys/test/.toys.rb`, while defining the large `test unit` tool
+in the separate file `.toys/test/unit.rb`.
+
+Toys also loads index files first before other files in the directory. This
+means they are convenient places to define shared code that can be used by all
+the subtools, as we shall see later in the section on helpers.
+
+### The Toys Search Path
+
+So far we have seen how to define tools by writing a `.toys.rb` file in the
+current directory, or by writing files inside a `.toys` directory in the
+current directory. These tools are "scoped" to the current directory. If you
+move to a different directory, they may not be available.
+
+When Toys runs, it looks for tools in a **search path**. Specifically:
+
+(1) It looks for a `.toys.rb` file and/or a `.toys` directory in the *current
+    working directory*.
+(2) It does the same in the *parent directory* of the current directory, and
+    its parent, all the way up to the root of the file system.
+(3) It does the same in the current user's *home directory*.
+(4) It does the same in the system configuration directory (i.e. `/etc` on unix
+    systems)
+
+It uses the *first* implementation that it finds for the requested tool. For
+example, if the tool `greet` is defined in the `.toys.rb` file in the current
+working directory, and also in the `.toys/greet.rb` file of the parent
+directory, it will use the version in the current directory.
+
+This means you could write a default implementation for a tool in your home
+directory, and override it in the current directory. For example, you could
+define a tool `get-credentials` in your home directory that gets credentials
+you need for *most* of your projects. But maybe on particular project requires
+different credentials, so you could define a different `get-credentials` tool
+in that project's directory.
+
+While a tool can be overridden when it is defined at different points in the
+search path, it is *not* allowed to provide multiple definitions of a tool at
+the *same* point in the search path. For example, if you define the `greet`
+tool twice in the same `.toys.rb` file, Toys will report an error. Perhaps less
+obviously, if you define `greet` in the `.toys.rb` file in the current
+directory, and you also define it in the `.toys/greet.rb` file in the same
+current directory, Toys will also report an error, since both are defined at
+the same point (the current directory) in the search path.
+
+#### Global Toys
+
+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,
+steps (3) and (4) are *not* context-dependent, and are searched regardless of
+where you are located. Toys defined here are **global**, available everywhere.
+
+By default, global tools are defined in your home directory and the system
+configuration directory. However, you can change this by defining the
+environment variable `TOYS_PATH`. This environment variable should contain a
+colon-delimited list of paths that should be searched for global toys. If you
+do define it, it replaces (3) and (4) with the paths you specify.
 
 ## The Execution Environment
 
+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.
+
+Generally, your tool is executed in an object of type
+[Toys::Tool](https://www.rubydoc.info/gems/toys-core/Toys/Tool). This 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::Tool#option](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:option)
+method to retrieve option values, and how to use the
+[Toys::Tool#exit](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:exit)
+method to exit immediately and return an exit code. Now we will cover other
+resources available to your tool.
+
 ### Built-in Context
 
+The options set by your tool's flags and command line arguments are only a
+subset of the data you can access. A variety of other data and objects are
+also accessible using the
+[Toys::Tool#get method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:get)
+For example, you can get the full name of the tool being executed like this:
+
+    def run
+      puts "Current tool is #{get(TOOL_NAME)}"
+    end
+
+The `TOOL_NAME` constant above is a well-known key that corresponds to the full
+name (as an array of strings) of the running tool. A variety of well-known keys
+are defined in the
+[Toys::Tool::Keys module](https://www.rubydoc.info/gems/toys-core/Toys/Tool/Keys).
+They range from the tool name and the original command line arguments passed to
+it (before they were parsed), to references to some of the Toys objects that
+can be used to do things like write to the log or look up and call other tools.
+
+(The `get` method also returns the options that were set by flags or command
+line arguments if you pass the corresponding option keys. However, it is
+generally good practice to use
+[Toys::Tool#option](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:option)
+to get option values.)
+
+Most of the important context also can be accessed from convenience methods.
+For example, the `TOOL_NAME` is also available from the
+[Toys::Tool#tool_name method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:tool_name):
+
+    def run
+      puts "Current tool is #{tool_name}"
+    end
+
+Let's take a look at a few things your tool can do with the objects you can
+access from built-in context.
+
 ### Logging and Verbosity
 
+Toys provides a Logger (a simple instance of the Ruby standard library logger
+that writes to standard error) for your tool to use to report status
+information. You can access this logger via the `LOGGER` context key, or the
+[Toys::Tool#logger method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:logger).
+For example:
+
+    def run
+      logger.warn "Danger Will Robinson!"
+    end
+
+The current logger level is controlled by the verbosity. Verbosity is an
+integer context value that you can retrieve using the `VERBOSITY` context key
+or the
+[Toys::Tool#verbosity method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:verbosity).
+The verbosity is set to 0 by default. This corresponds to a logger level of
+`WARN`. That is, warnings, errors, and fatals are displayed, while infos and
+debugs are not. However, as we saw earlier, tools automatically respond to the
+`--verbose` and `--quiet` flags, (or `-v` and `-q`), which increment and
+decrement the verbosity value, respectively. If you run a tool with `-v`, the
+verbosity is incremented to 1, and the logger level is set to `INFO`. If you
+set `-q`, the verbosity is decremented to -1, and the logger level is set to
+`ERROR`. So by using the provided logger, a tool can easily provide command
+line based control of the output verbosity.
+
 ### Running Tools from Tools
 
+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::Tool#cli method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:cli).
+These return the current instance of
+[Toys::CLI](https://www.rubydoc.info/gems/toys-core/Toys/CLI) which is the
+"main" interface to Toys. In particular, it provides the
+[Toys::CLI#run method](https://www.rubydoc.info/gems/toys-core/Toys%2FCLI:run)
+which can be used to call another tool:
+
+    def run
+      status = cli.run("greet", "rubyists", "-v")
+      exit(status) unless status.zero?
+    end
+
+Pass the tool name and arguments as arguments to the run method. It will
+execute, and return a process status object (i.e. 0 for success, and nonzero
+for error). Make sure you handle the exit status. For example, in most cases,
+you should probably exit if the tool you are calling returns a nonzero code.
+
+### Helper Methods and Mixins
+
+The methods of [Toys::Tool](https://www.rubydoc.info/gems/toys-core/Toys/Tool)
+are not the only methods available for your tool to call. We saw earlier that
+a tool can define additional methods that you can use as helpers.
+
+You can also include **mixins**, which are modules that bring in a whole set of
+helper methods. Include a mixin using the `include` directive:
+
+    tool "greet" do
+      include :terminal
+      def run
+        puts "This is a bold line.", :bold
+      end
+    end
+
+Th mixins may be specified by providing a module itself, or by providing a
+**mixin name**. In the above example, we used `:terminal`, which is the name
+of a built-in mixin that Toys provides. Among other things, it defines a
+special `puts` method that lets you include style information such as `:bold`,
+which affects the display on ANSI-capable terminals.
+
+For details on the standard mixins provided by Toys, see the modules under
+[Toys::StandardMixins](https://www.rubydoc.info/gems/toys-core/Toys/StandardMixins).
+We will look at a few examples of the use of these mixins below. You can also
+define your own mixins, as we will see in the next section on sharing code.
+
 ### Executing Subprocesses
 
+Another common operation you might do in a tool is to execute other binaries.
+For example, you might write a tool that shells out to `scp` to copy files to
+a remote server.
+
+Ruby itself provides a few convenient methods for simple execution, such as the
+[Kernel#system](http://ruby-doc.org/core/Kernel.html#method-i-system) method.
+However, these typically provide limited ability to control or interact with
+subprocess streams, and you need to remember to handle the exit status
+yourself. If you do want to exert any control over subprocesses, you can use
+[Process.spawn](http://ruby-doc.org/core/Process.html#method-c-spawn), or a
+higher-level wrapper such as the
+[open3 library](http://ruby-doc.org/stdlib/libdoc/open3/rdoc/index.html).
+
+Another alternative is to use the `:exec` built-in mixin. This mixin provides
+convenient methods for the common cases of executing subprocesses and capturing
+their output, and a powerful block-based interface for controlling streams. The
+exec mixin also lets you set a useful default option that causes the tool to
+exit automatically if one of its subprocesses exits abnormally.
+
+For more information, see the
+[Toys::StandardMixins::Exec mixin module](https://www.rubydoc.info/gems/toys-core/Toys/StandardMixins/Exec)
+and the underyling library
+[Toys::Utils::Exec](https://www.rubydoc.info/gems/toys-core/Toys/Utils/Exec).
+
 ### Formatting Output
 
-## Prefabricated Tools with Templates
+Interacting with the user is a very common function of a command line tool, and
+many modern tools include intricately designed and styled output, and terminal
+effects such as progress bars and spinners. Toys provides several mixins that
+can help create nicer interfaces.
+
+First, there is `:terminal`, which provides some basic terminal features such
+as styled output and simple spinners. For information, see the
+[Toys::StandardMixins::Terminal mixin module](https://www.rubydoc.info/gems/toys-core/Toys/StandardMixins/Terminal)
+and the underyling library
+[Toys::Utils::Terminal](https://www.rubydoc.info/gems/toys-core/Toys/Utils/Terminal).
+
+If you prefer the venerable Highline library interface, Toys provides a mixin
+that makes Highline available. It also automatically installs the highline
+gem if it is not available. For more information, see the
+[Toys::StandardMixins::Highline mixin module](https://www.rubydoc.info/gems/toys-core/Toys/StandardMixins/Highline).
+
+Additional mixins are forthcoming...
+
+## Sharing Code
+
+
+
+### Defining Mixins
+
+
+
+### Using Constants
+
+
+
+### Expanding Templates
+
+
+
+#### Defining Templates
+
 
-### Defining Templates
 
 ## Advanced Tool Definition Techniques
 
+
+
 ### Aliases
 
-### Includes
+
+
+### Custom Acceptors
+
+
 
 ### Controlling Built-in Flags
 
-## The System Tools
+
+
+### Middleware
+
+
+
+## Toys Administration using the System Tools
+
+
 
 ## Embedding Toys