toys-core 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9266b9c87907b8844cd20529fd8102391737845d2e85cecc6674d6657a9d0d27
-  data.tar.gz: da4bf58af8136859679ee2d8123e649310af0b82dbe896730af081d4e18c2c5d
+  metadata.gz: c599749b4dfa556b393f532a666455ced20062d746a8e9156aa472bdcbe5c6a2
+  data.tar.gz: 303c5615df653c4ca0fcb7646a413630fd74db0c28518ff2d8baae9f6ba80ccb
 SHA512:
-  metadata.gz: 511416609364d830a23c27279ddcd545182cbca9fc0fc2727f832c75d4cfedaab0e4faa2d23456c880d202c4fb18e95239948bfbbdbe46035ccc008d0d84996b
-  data.tar.gz: '075912df93384641e0c7b43807571d8ac4873af0906f022265db1483b66258fea88e7026d0a35c4716a5f96ac237ef9965b53398cdcf31d7254c2b5e2fb85895'
+  metadata.gz: 0b92268de87c8555a113e2e9804d4a4b3489cbe3c216dc1056e45595214297e4aaf4b19a95da9db5c024bfa41336d8d25f6df591b1861fb85c3f552a69cf3b3a
+  data.tar.gz: 860c322590729d3a111b3e205197eb42110cc8dd455dc8c6c5ff7ba042f69dd25583f3d720e9ccc3104fe9bd021999a655639c15fcec185b9b4fdd0126052aca

data/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Release History
 
+### 0.8.0 / 2019-06-20
+
+This is a major update with significant new features and a bunch of fixes. It also includes a significant amount of internal reorganization and cleanup, some of which resulted in backward incompatible changes. Basic use should not be affected. All signifiant features planned for beta are now implemented.
+
+Major changes and features:
+
+* CHANGED: Relicensed under the MIT License.
+* ADDED: Tab completion for bash. Added APIs and DSL constructs for tools to customize completions.
+* ADDED: The usage error screen displays suggestions when an argument is misspelled. (Requires Ruby 2.4 or later.)
+* ADDED: Tools can provide an interrupt handler and a custom usage error handler. Added appropriate APIs and DSL methods.
+* ADDED: Tools can enforce that flags must be given before positional args, and can control whether partial flags are accepted.
+
+Other notable changes:
+
+* ADDED: Flag handlers can accept the symbolic names `:set` and `:push` for common cases.
+* ADDED: Function and range based acceptors.
+* ADDED: The `acceptor` directive takes an optional `type_desc` argument.
+* ADDED: The `accept` directives under flag and positional arg blocks in the DSL can now take blocks and `type_desc` values.
+* ADDED: Context keys `UNMATCHED_ARGS`, `UNMATCHED_POSITIONAL`, and `UNMATCHED_FLAGS` that provide arguments that were not handled during arg parsing.
+* ADDED: The Exec util and mixin support specifying a callback for process results.
+* ADDED: The Exec util and mixin provide a way to identify processes by name.
+* CHANGED: Implemented custom argument parsing and custom implementations of the standard OptionParser acceptors, rather than relying on OptionParser itself. For the most part, OptionParser behavior is preserved, except in cases where there is clearly a bug.
+* CHANGED: Flags create a short form flag by default if the name has one character.
+* CHANGED: Flags with explicit value-less syntax are no longer given a value if they specify a default or an acceptor.
+* CHANGED: Renamed the `TOOL_DEFINITION` context key to `TOOL`, and removed the `tool_definition` convenience method.
+* CHANGED: Removed the `BINARY_NAME` and `LOADER` context keys, and removed the corresponding convenience methods. Get these values from the CLI if needed.
+* CHANGED: Renamed the `USAGE_ERROR` context key to `USAGE_ERRORS`, and the corresponding convenience method to `usage_errors`. The value is now a (possibly empty) array of `Toys::ArgParser::UsageError` objects rather than a string that isn't machine-parseable.
+* CHANGED: The help middleware no longer defines remaining_args on the root tool.
+* CHANGED: Renamed `to_expand` to `on_expand` in template definitions.
+* CHANGED: Renamed `to_initialize` to `on_initialize`, and `to_include` to `on_include` in mixin definitions.
+* CHANGED: The CLI options `preload_directory_name` and `data_directory_name` renamed to `preload_dir_name` and `data_dir_name`.
+* CHANGED: Default descriptions for flag groups is now handled by the `set_default_descriptions` middleware rather than hard-coded in FlagGroup.
+* CHANGED: Exec reports failure to start processes in the result object rather than, e.g. raising ENOENT.
+* IMPROVED: Default error handler no longer displays a stack trace if a tool is interrupted.
+* IMPROVED: Error messages for flag groups are more complete.
+* IMPROVED: All context data, including well-known data, is available to be modified by flags and args.
+* FIXED: Flags with optional values are properly set to `true` (rather than left at `nil`) if no value is provided.
+* FIXED: Acceptors no longer raise errors when run on missing optional values.
+* FIXED: When reporting errors in toys files, the line number was off by 2.
+* FIXED: The `--usage` help flag now honors `--all` and `--no-recursive`.
+* FIXED: The terminal now handles nil streams, as advertised.
+
+Changes to internal interfaces:
+
+* General changes:
+    * CHANGED: Renamed `Toys::Tool` to `Toys::Context`, and the `Keys` submodule to `Key`.
+    * CHANGED: Moved the `ModuleLookup` and `WrappableString` out of the `Utils` module to be located directly under `Toys`. Other modules remain under `Utils`.  The remaining files under "toys/utils" must now be required explicitly. This directory is now specifically for modules that are not part of the "core" interface.
+    * CHANGED: All the classes under `Toys::Definition` are now located directly under `Toys`. For example, `Toys::Definition::Tool` is now `Toys::Tool`.
+    * CHANGED: Generally removed the term "definition" from interfaces. For example, an accessor method called `tool_definition` is now just called `tool`.
+    * CHANGED: Renamed `Toys::DSL::Arg` to `Toys::DSL::PositionalArg`
+    * CHANGED: Removed `Toys::Runner` and folded its functionality into `Toys::CLI`.
+    * CHANGED: The fallback execution feature of the show_help middleware is implemented by catching an exception afterward rather than detecting non-runnable up front. This lets us remove the second copy of show_help from the middleware stack.
+    * ADDED: Functionality dependent on Ruby version is kept in `Toys::Compat`.
+* Changes related to the tool classes:
+    * CHANGED: Moved `Toys::Definition::Tool` to `Toys::Tool`.
+    * CHANGED: Removed the term "definition" from accessors. Specifically `flag_definitions` renamed to `flags`, `required_arg_definitions` renamed to `required_args`, `optional_arg_definitions` renamed to `optional_args`, `remaining_args_definition` renamed to `remaining_arg`, and `arg_definitions` renamed to `positional_args`.
+    * CHANGED: Renamed `Tool#runnable=` to `Tool#run_handler=`.
+    * CHANGED: `Tool#add_acceptor` takes the name as a separate argument, for consistency with `add_mixin` and `add_template`.
+    * CHANGED: Removed `Tool#custom_acceptors` method.
+    * CHANGED: Removed `Tool#resolve_acceptor` and replaced with `lookup_acceptor` which only looks up names.
+    * CHANGED: Renamed `Tool#resolve_mixin` to `lookup_mixin` and `Tool#resolve_template` to `lookup_template`.
+    * ADDED: Added `resolve_flag` method to look up flags by syntax.
+    * ADDED: Accessor for interrupt handler.
+    * ADDED: `enforce_flags_before_args` setting and `flags_before_args_enforced?` query.
+    * ADDED: Completion accessor, and options to the various flag and positional arg methods to set their completion strategies.
+    * ADDED: Added `Tool::DefaultCompletion` class.
+    * IMPROVED: `add_mixin`, `add_template`, and `add_acceptor` support all the specs understood by their create methods.
+* Changes related to the flag classes:
+    * CHANGED: Moved `Toys::Definition::Flag` to `Toys::Flag`
+    * CHANGED: `FlagSyntax` is now `Flag::Syntax`.
+    * CHANGED: `Flag::Syntax#flag_style` now has values `:short` and `:long` instead of `"-"` and `"--"`.
+    * CHANGED: `Flag#single_flag_syntax` renamed to `Flag#short_flag_syntax`, and `Flag#double_flag_syntax` renamed to `Flag#long_flag_syntax`.
+    * CHANGED: Renamed `Flag#accept` to `Flag#acceptor` which now always returns an acceptor object (even for well-known acceptors such as `Integer`).
+    * CHANGED: Removed `Flag#optparser_info` and replaced with `Flag#canonical_syntax_strings`.
+    * ADDED: `Flag#create` class method providing a sane construction interface.
+    * ADDED: `Flag#resolve` method to look up flag syntax.
+    * ADDED: `Flag#completion` field.
+    * ADDED: Added `Flag::Resolution` and `Flag::DefaultCompletion` classes.
+* Changes related to the positional arg classes:
+    * CHANGED: Moved `Toys::Definition::Arg` to `Toys::PositionalArg`.
+    * CHANGED: Renamed `Arg#accept` to `PositionalArg#acceptor` which now always returns an acceptor object (even for well-known acceptors such as `Integer`).
+    * ADDED: `PositionalArg#create` class method providing a sane construction interface.
+    * ADDED: `PositionalArg#completion` field
+* Changes related to the flag group classes:
+    * CHANGED: Moved `Toys::Definition::FlagGroup` to `Toys::FlagGroup`
+    * CHANGED: The base class is now `FlagGroup::Base` instead of `FlagGroup` itself.
+    * ADDED: `FlagGroup#create` class method providing a sane construction interface.
+* Changes related to acceptors:
+    * CHANGED: Moved `Toys::Definition::Acceptor` to `Toys::Acceptor`
+    * CHANGED: The base ciass is now `Acceptor::Base` instead of `Acceptor` itself.
+    * CHANGED: Subclasses are now submodules under `Acceptor`. For example, moved `Toys::Definition::PatternAcceptor` to `Toys::Acceptor::Pattern`.
+    * CHANGED: Replaced `name` field with separate `type_desc` and `well_known_spec` fields.
+    * CHANGED: The base class no longer takes a conversion proc. It is always a no-op. `Acceptor::Pattern`, however, does take a converter so it can continue to handle custom OptionParser acceptors.
+    * ADDED: Acceptors may define `suggestions` which returns results from did-you-mean.
+    * ADDED: Simple acceptor (`Acceptor::Simple`) which uses a single function to validate and convert input.
+    * ADDED: Range acceptor (`Acceptor::Range`) which validates against a range.
+    * ADDED: Class methods `Acceptor.create` and `Acceptor.lookup_well_known`.
+
 ### 0.7.0 / 2019-01-23
 
 * ADDED: Flag groups, which enforce policies around which flags are required.

data/LICENSE.md

@@ -1,29 +1,21 @@
 # License
 
-Copyright 2018 Daniel Azuma
+Copyright 2019 Daniel Azuma
 
-All rights reserved.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-*   Redistributions of source code must retain the above copyright notice,
-    this list of conditions and the following disclaimer.
-*   Redistributions in binary form must reproduce the above copyright notice,
-    this list of conditions and the following disclaimer in the documentation
-    and/or other materials provided with the distribution.
-*   Neither the name of the copyright holder, nor the names of any other
-    contributors to this software, may be used to endorse or promote products
-    derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

data/README.md

@@ -1,108 +1,356 @@
-# Toys
+# Toys-Core
 
 Toys is a configurable command line tool. Write commands in config files using
-a simple DSL, and Toys will provide the command line binary and take care of
-all the details such as argument parsing, online help, and error reporting.
+a simple DSL, and Toys will provide the command line executable and take care
+of all the details such as argument parsing, online help, and error reporting.
+
 Toys-Core is the command line tool framework underlying Toys. It can be used
-to create your own command line binaries using the internal Toys APIs.
+to write command line executables using the Toys DSL and the power of the Toys
+classes.
 
 For more detailed information about Toys-Core, see the
 [Toys-Core User's Guide](https://www.rubydoc.info/gems/toys-core/file/docs/guide.md).
 For background information about Toys itself, see the
+[Toys README](https://www.rubydoc.info/gems/toys) and the
 [Toys User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
 
-## Quick Start
+## Introductory tutorial
+
+Here's a tutorial to help you get a feel for how to write a basic command line
+executable using Toys-Core.
 
-Here's a ten-minute tutorial to get a feel for how to write a basic command
-line binary using Toys-Core.
+It assumes basic familiarity with Toys, so, if you have not done so, I
+recommend first walking through the tutorial in the
+[Toys README](https://www.rubydoc.info/gems/toys). It also assumes you are
+running a unix-like system such as Linux or macOS. Some commands might need to
+be modified if you're running on Windows.
 
 ### Install Toys
 
+Toys requires Ruby 2.3 or later. (JRuby is not currently supported.)
+
 Install the **toys-core** gem using:
 
-    gem install toys-core
+    $ gem install toys-core
 
 You may also install the **toys** gem, which brings in **toys-core** as a
 dependency.
 
-### Create a Toys File
+### Create a new executable
+
+We'll start by creating an executable Ruby script. Using your favorite text
+editor, create new a file called `mycmd` with the following contents:
+
+    #!/usr/bin/env ruby
+
+    require "toys-core"
+
+    cli = Toys::CLI.new
+
+    exit(cli.run(*ARGV))
 
-A *Toys File* is a configuration file used by Toys to define commands, called
-"tools" in Toys lingo. If you've used the **toys** binary itself, you've
-probably written one already. You use the same file format when you create your
-own command line binary using Toys-Core.
+Make sure the file's executable bit is set:
+
+    $ chmod a+x mycmd
+
+That's it! This is a fully-functional Toys-based executable! Let's see what
+happens when you run it:
+
+    $ ./mycmd
+
+Just as with Toys itself, you get a help screen by default (since we haven't
+yet actually implemented any behavior.) As you can see, some of the same
+features from Toys are present already: online help, and `--verbose` and
+`--quiet` flags. These features can of course all be customized, but they're
+useful to have to start off.
+
+### Add some functionality
+
+You implement the functionality of your executable using the same DSL that you
+use to write Toys files. You could point your executable at a directory
+containing actual Toys files, but the simplest option is to provide the
+information to the Toys CLI object in a block.
+
+Let's add some functionality. 
+
+    #!/usr/bin/env ruby
+
+    require "toys-core"
 
-Create a new empty directory. In the directory, using your favorite text
-editor, create a file called `tools.rb`. Copy the following into the file, and
-save it:
+    cli = Toys::CLI.new
 
-    tool "greet" do
-      desc "My first tool!"
+    #### Insert the following block ...
+    cli.add_config_block do
+      desc "My first executable!"
       flag :whom, default: "world"
       def run
         puts "Hello, #{whom}!"
       end
     end
 
-If you're already familiar with writing Toys Files, feel free to modify and
-experiment with it.
+    exit(cli.run(*ARGV))
+
+If you went through the tutorial in the README for the Toys gem, this should
+look familiar. Let's run it now, and experiment with passing flags to it.
+
+    $ ./mycmd
+    $ ./mycmd --whom=ruby
+    $ ./mycmd --bye
+    $ ./mycmd --help
 
-### Create Your Binary
+Notice that we did not create a `tool` block, but instead set up description,
+flags, and functionality directly in the configuration block. This configures
+the "root tool", i.e. what happens when you run the executable without passing
+a tool name to it. (Note, it's legal to do this in Toys as well, by setting
+functionality at the "top level" of a `.toys.rb` file without including any
+`tool` block.)
 
-Now we will write a command line binary that uses that Toys File. In the same
-new directory, create a new file called `mycmd`. Copy the following into it:
+### Tool-based executables
+
+But perhaps you want your executable to have multiple "tools", similar to other
+familiar executables like git or kubectl. You can define tools, including
+nested tools, by writing `tool` blocks in your config. Here's an example:
 
     #!/usr/bin/env ruby
+
     require "toys-core"
+
     cli = Toys::CLI.new
-    cli.add_config_path(File.join(__dir__, "tools.rb"))
-    exit(cli.run(ARGV))
 
-Save the file and make it executable:
+    #### Change the config block as follows ...
+    cli.add_config_block do
+      # Things outside any tool block still apply to the root
+      desc "My first executable with several tools"
+
+      # We'll put the greet function here
+      tool "greet" do
+        desc "My first tool!"
+        flag :whom, default: "world"
+        def run
+          puts "Hello, #{whom}!"
+        end
+      end
+
+      # Try writing a second tool here. You could use the "new-repo"
+      # example from the Toys tutorial.
+    end
+
+    exit(cli.run(*ARGV))
+
+Now you can run `greet` as a tool:
+
+    $ ./mycmd greet
+
+The "root" functionality once again shows global help, including a list of the
+available tools.
+
+    $ ./mycmd
+
+Notice that the description set at the "root" of the config block (outside the
+tool blocks) shows up here.     
+
+### Configuring the CLI
+
+So far, our executable behaves very similarly to Toys itself. Help screens are
+shown by default, flags for help and verbosity are provided automatically, and
+any exceptions are displayed to the terminal.
+
+These and many more aspects of the behavior of our executable can be customized
+by passing options to the `Toys::CLI` constructor. Here's an example that
+modifies error handling and delimiter parsing.
+
+    #!/usr/bin/env ruby
+
+    require "toys-core"
+
+    #### Pass some additional options to the CLI constructor ...
+    cli = Toys::CLI.new(
+      extra_delimiters: ":",
+      error_handler: ->(e) {
+        puts "Dude, an error happened..."
+        return 1
+      }
+    )
+
+    #### Change the config block as follows ...
+    cli.add_config_block do
+      tool "example" do
+        tool "greet" do
+          def run
+            puts "Hello, world!"
+          end
+        end
+        tool "error" do
+          def run
+            raise "Whoops!"
+          end
+        end
+      end
+    end
+
+    exit(cli.run(*ARGV))
+
+Try these runs. Do they behave as you expected?
+
+    $ ./mycmd example greet
+    $ ./mycmd example:greet
+    $ ./mycmd example.greet
+    $ ./mycmd example error
+
+### Configuring middleware
+
+Toys _middleware_ are objects that provide common functionality for all the
+tools in your executable. For example, a middleware adds the `--help` flag to
+your tools by default.
+
+The next example modifies the middleware stack to alter this common tool
+functionality.
+
+    #!/usr/bin/env ruby
+
+    require "toys-core"
+
+    #### Change the CLI construction again ...
+    middlewares = [
+      [:set_default_descriptions, default_tool_desc: "Hey look, a tool!"],
+      [:show_help, help_flags: true]
+    ]
+    cli = Toys::CLI.new middleware_stack: middlewares
+
+    #### Use this config block ...
+    cli.add_config_block do
+      tool "greet" do
+        def run
+          puts "Hello, world!"
+        end
+      end
+    end
+
+    exit(cli.run(*ARGV))
+
+We've now modified the default description applied to tools that don't provide
+their own description. See the effect with:
+
+    $ ./mycmd greet --help
 
-    chmod +x mycmd
+We've also omitted some of the default middleware, including the one that adds
+the `--verbose` and `--quiet` flags to all your tools. Notice those flags are
+no longer present.
 
-Now you can run your command. Try these, to get a feel for how it behaves by
-default:
+We've also omitted the middleware that provides default execution behavior
+(i.e. displaying the help screen) when there is no `run` method. Now, since we
+haven't defined a toplevel `run` method in this last example, invoking the root
+tool will cause an error:
 
-    ./mycmd greet
-    ./mycmd greet --whom=Ruby
-    ./mycmd greet --help
-    ./mycmd
-    ./mycmd foo
+    $ ./mycmd
 
-### Next Steps
+It is even possible to write your own middleware. In general, while the
+`Toys::CLI` constructor provides defaults that should work for many use cases,
+you can also customize it heavily to suit the needs of your executable.
 
-A basic command line binary based on Toys-Core consists of just the binary
-itself, and a Toys File (or directory) defining the commands to run. All the
-features of Toys, described in the
-[Toys User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md),
-are at your disposal for writing tools for your binary. Or, if you want your
-binary to have a single function rather than support a set of tools, you can
-just write a toplevel tool in your Toys File.
+### Packaging as a gem
 
-You'll notice that Toys-Core provides a number of features "out of the box",
-such as online help, verbose and quiet flags, and default descriptions. These
-features are controlled by Toys *Middleware*, which are classes that customize
-the base behavior of Toys-Core. Toys-Core defaults to a certain set of
-middleware, but you can customize and change them for your own binary.
+So far we've created simple one-file executables that you could distribute by
+itself. However, the `toys-core` gem is a dependency, and your users will need
+to have it installed. You could alleviate this by wrapping your executable in a
+gem that can declare `toys-core` as a dependency explicitly.
 
-Finally, you may want to distribute your binary in a gem. Just make sure you
-include the Toys File or Directory in the gem, and that your binary configures
-`Toys::CLI` with the correct config path. The Toys File does not need to be in
-the require path (i.e. in the `lib` directory), and indeed it is probably best
-for it not to be, to prevent users of your gem from requiring it accidentally.
+The [examples directory](https://github.com/dazuma/toys/tree/master/toys-core/examples)
+includes a few simple examples that you can use as a starting point.
 
-See the
-[Toys-Core User's Guide](https://www.rubydoc.info/gems/toys-core/file/docs/guide.md)
-for thorough documentation on writing a command line binary using Toys-Core.
+To experiment with the examples, clone the Toys repo from GitHub:
+
+    $ git clone https://github.com/dazuma/toys.git
+    $ cd toys
+
+Navigate to the simple-gem example:
+
+    $ cd toys-core/examples/simple-gem
+
+This example wraps the simple "greet" executable that we
+[covered earlier](#Add_some_functionality) in a gem. You can see the
+[executable file](https://github.com/dazuma/toys/tree/master/toys-core/examples/simple-gem/bin/toys-core-simple-example)
+in the bin directory.
+
+Try it out by building and installing the gem. From the `examples/simple-gem`
+directory, run:
+
+    $ toys install
+
+Once the gem has successfully installed, you can run the executable, which
+Rubygems should have added to your path. (Note: if you are using a ruby
+installation manager, you may need to "rehash" or "reshim" to gain access to
+the executable.)
+
+    $ toys-core-simple-example --whom=Toys
+
+Clean up by uninstalling the gem:
+
+    $ gem uninstall toys-core-simple-example
+
+If the implementation of your executable is more complex, you might want to
+break it up into multiple files. The multi-file gem example demonstrates this.
+
+    $ cd ../multi-file-gem
+
+This executable's implementation resides in its
+[lib directory](https://github.com/dazuma/toys/tree/master/toys-core/examples/multi-file-gem/lib),
+a technique that may be familiar to writers of command line executables. More
+interestingly, the tools themselves are no longer defined in a block passed to
+the CLI object, but have been moved into a separate
+["tools" directory](https://github.com/dazuma/toys/tree/master/toys-core/examples/multi-file-gem/tools).
+This directory has the same structure and supports the same features that are
+available when writing complex sets of tools in a `.toys` directory. You then
+configure the CLI object to look in this directory for its tools definitions,
+as you can see in
+[the code](https://github.com/dazuma/toys/tree/master/toys-core/examples/multi-file-gem/lib/toys-core-multi-gem-example.rb).
+
+Try it out now. From the `examples/multi-file-gem` directory, run:
+
+    $ toys install
+
+Once the gem has successfully installed, you can run the executable, which
+Rubygems should have added to your path. (Note: if you are using a ruby
+installation manager, you may need to "rehash" or "reshim" to gain access to
+the executable.)
+
+    $ toys-core-multi-file-example greet
+
+Clean up by uninstalling the gem:
+
+    $ gem uninstall toys-core-multi-file-example
+
+### Learning more
+
+This introduction should be enough to get you started. However, Toys-Core is a
+deep framework with many more features. Learn about how to write tools using
+the Toys DSL, including validating and interpreting command line arguments,
+using templates and mixins, controlling subprocesses, and producing nice styled
+output, in the
+[Toys User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
+Learn more about how to customize and package your own executable, including
+handling errors, controlling log output, and providing your own mixins,
+templates, and middleware, in the
+[Toys-Core User Guide](https://www.rubydoc.info/gems/toys-core/file/docs/guide.md).
 
 ## License
 
-Copyright 2018 Daniel Azuma
+Copyright 2019 Daniel Azuma
 
-This software is licensed under the 3-clause BSD license.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-See the LICENSE.md file for more information.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-The source can be found on Github at https://github.com/dazuma/toys
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.