toys 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20520c07615ed64145bf678f175e4e37835e69fe2b92c88f083b554c1902e969
-  data.tar.gz: b3e1efd5fc4e05a620d7834361e353840579c5b4c6c555f95da1f350d81737b0
+  metadata.gz: 4090b70821f47975fbfd82cd40651b3ee93e43ecf77cb7a820f20322524a3447
+  data.tar.gz: 70440b824c11d8c7b14e0cda8bfd57f8a74df0aa084c5f47b63efbd3047a7706
 SHA512:
-  metadata.gz: cdd293b0870059e7ff90dfac63844046d435b4150cd32d15fa2e8b8bef39c975db6ba6df87af89bf84f17fa075a57ffd9b6499b7fbcd4206cc7a281701411aed
-  data.tar.gz: 3e75b09dc3e6df45113bbad6d2dfb9c40601eb35b743d3557455be8821ace82d5bc762c34c07c89d5faf043c9d10de08dd49227346578ab20c675bad8e57a6a3
+  metadata.gz: e2a58b4eea98ed65f797dcccdef7bc5abbb3df45aa9771263e9c69bc809b3d15507521cfc012753285dc9464c441db0d08e7a31c15c098e610fffe959888e621
+  data.tar.gz: 41a9dbfee92b60d34cb74b07ac8599a8bf01da0203d386dcfd73a3dac8711030d97c6548ff40caa3dd63dc9fb123c14eb590dbb6a5809679978ebc081328141d

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 0.3.6 / 2018-05-21
+
+* CHANGED: Removed Context#new_cli and exposed Context#cli instead.
+* CHANGED: Raises ToolDefinitionError if you declare a duplicate flag.
+* IMPROVED: Provide more details in default descriptions.
+* IMPROVED: Optional parameters are now supported for flags.
+* IMPROVED: Support custom acceptors.
+* IMPROVED: Highline helper automatically sets use_color based on the type of stdout.
+
 ### 0.3.5 / 2018-05-15
 
 * CHANGED: Flag and arg blocks in the DSL have an interface more similar to the rest of the DSL.

data/README.md

@@ -7,15 +7,28 @@ for software developers, IT specialists, and other power users who want to
 write and organize scripts to automate their workflows.
 
 I wrote Toys because I was accumulating dozens of ad hoc Ruby scripts that I
-had written to automate everything from refreshing credentials, to displaying
-git history in my favorite format, to running builds and tests of complex
-multi-component projects. It was becoming difficult to remember which scripts
-did what, and what arguments to pass, and I was repeating the same
-OptionParser and common tool boilerplate each time I wrote a new one.
-
-Toys is a powerful tool that makes it easy to write and organize your scripts.
-You write your functionality, and Toys takes care of all the details expected
-from a good command line tool.
+had written to automate various tasks in my workflow, everything from
+refreshing credentials, to displaying git history in my favorite format, to
+running builds and tests of complex multi-component projects. It was becoming
+difficult to remember which scripts did what, and what arguments each required,
+and I was constantly digging back into their source just to remember how to use
+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
+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
+organize shared code. It automatically generates help text, so you can see
+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
+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.
@@ -24,7 +37,7 @@ For more info on using toys-core, see
 
 ## Quick Start
 
-Here's a five-minute tutorial to get the feel of what Toys can do.
+Here's a five-minute tutorial to get a feel of what Toys can do.
 
 ### Install toys
 
@@ -40,8 +53,8 @@ You can run the binary immediately:
 This displays overall help for the Toys binary. If you have `less` installed,
 Toys will use it to display the help screen. Press `q` to exit.
 
-You may notice that the help text lists some tools that are preinstalled. Let's
-run one of them:
+You may notice that the help screen lists some tools that are preinstalled.
+Let's run one of them:
 
     toys system version
 
@@ -74,8 +87,8 @@ flags. It can also validate arguments. Try this:
 
     toys greet --hello
 
-Notice that Toys automatically generated a usage summary for your tool. It also
-automatically generates a full help screen, which you can view using the
+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
 `--help` flag:
 
     toys greet --help
@@ -83,10 +96,10 @@ automatically generates 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 created in that file are available only in this directory
-and its subdirectories; if you move outside the directory tree, they are no
-longer present. You can use this to create tools scoped to particular
-directories and projects.
+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.
 
 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
@@ -99,7 +112,8 @@ console-based interfaces, and special effects. It also includes a library that
 makes it easy to control subprocesses.
 
 For a more detailed look at Toys, see the
-{file:docs/tutorial.md Extended Tutorial} and {file:docs/guide.md User Guide}.
+{file:docs/tutorial.md Extended Tutorial} and the
+{file:docs/guide.md User Guide}.
 
 ## Contributing
 

data/builtins/do.rb

@@ -35,12 +35,17 @@ long_desc \
     " the string \",\" by default). Toys will run them in order, stopping if any tool" \
     " returns a nonzero exit code.",
   "",
-  "Example: Suppose you have a \"rails build\" tool and a \"deploy\" tool, each with some" \
-    " flags. You could run them in order, with their flags, like this:",
-  ["    toys do rails build --staging , deploy --migrate"],
+  "Example: Suppose you have a \"rails build\" tool and a \"deploy\" tool. You could run them" \
+    " in order like this:",
+  ["    toys do rails build , deploy"],
+  "",
+  "However, if you want to pass flags to the tools to run, you need to preface the arguments" \
+    " with \"--\" in order to prevent \"do\" from trying to use them as its own flags. That" \
+    " might look something like this:",
+  ["    toys do -- rails build --staging , deploy --migrate"],
   "",
   "You may change the delimiter using the --delim flag. For example:",
-  ["    toys do --delim=/ rails build --staging / deploy --migrate"]
+  ["    toys do --delim=/ -- rails build --staging / deploy --migrate"]
 
 flag :delim, "-d", "--delim=VALUE",
      default: ",",

data/docs/guide.md

@@ -21,9 +21,9 @@ Toys is a multi-command binary. You may define a collection of commands, called
 `toys` binary. Tools are arranged in a hierarchy; a tool may be a *namespace*
 that has *subtools*.
 
-Each tool defines the command line arguments, in the form of *flags* and
-*positional arguments*, that it recognizes. Flags can optionally take *values*,
-and positional arguments may be *required* or *optional*.
+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, and
 for each command line argument. These descriptions are displayed in the tool's
@@ -42,18 +42,198 @@ configuration.
 Finally, Toys provides certain *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.
+Toys system itself.
 
 ## The Toys Command Line
 
-## Config Syntax
+In this section, you will learn how Toys parses its command line, identifies a
+tool to run, and interprets flags and other command line arguments.
 
-## Config Search Path
+The general form of the `toys` command line is:
 
-## Defining Helpers
+    toys [TOOL...] [FLAGS...] [ARGS...]
+
+### 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
+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.
+
+For example, in the following command:
+
+         |----TOOL----|
+    toys system version
+
+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.
+
+In the following command:
+
+         |TOOL| |ARG|
+    toys system blah
+
+There is no subtool `blah` under the `system` namespace, so Toys works backward
+until it finds a legitimate 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.
+
+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:
+
+    toys system
+
+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:
+
+    toys
+
+Like any namespace, the root tool displays its help screen, including the list
+of its subtools.
+
+One last example:
+
+    toys blah
+
+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.
+
+### Flags
+
+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.
+
+Pass a single short flag (for verbose output).
+
+    toys -v
+
+Pass multiple long flags (verbose output, and recursive subtool search).
+
+    toys --verbose --recursive
+
+You can combine short flags. This does the same as the previous example.
+
+    toys -rv
+
+Pass a value using a long flag. This searches subtools for the keyword `build`.
+
+    toys --search=build
+    toys --search build
+
+Pass a value using a short flag.
+
+    toys -s build
+    toys -sbuild
+
+If a double hyphen `--` appears by itself in the arguments, it disables flag
+parsing from that point. Any further arguments are treated as positional
+arguments, even if they begin with hyphens. For example:
+
+         |--FLAG--|   |---ARG---|
+    toys --verbose -- --recursive
+
+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.)
+
+Note that a single hyphen by itself `-` is not considered a flag and is treated
+as a positional argument.
+
+#### Standard Flags
+
+For the most part, each tool specifies which flags and arguments it recognizes.
+However, Toys adds a few standard flags globally to every tool. (It is possible
+for individual tools to override these flags, but most tools should support
+them.) These standard flags include:
+
+*   `--help` (also `-?`) which displays the full help screen for the tool.
+*   `--usage` which displays a shorter usage screen for the tool.
+*   `--verbose` (also `-v`) which increases the verbosity. This affects the
+    tool's logging display, increasing the number of log levels shown. This
+    flag may be issued multiple times.
+*   `--quiet` (also `-q`) which decreases the verbosity. This affects the
+    tool's logging display, decreasing the number of log levels shown. This
+    flag may also be issued multiple times.
+
+Namespace tools (tools that have subtools but no explicit functionality of
+their own) always behave as though `--help` is invoked. (They do recognize the
+flag, but it has no additional effect.) Namespaces also support the following
+additional flags:
+
+*   `--[no-]recursive` (also `-r`) which displays all subtools recursively,
+    instead of only the immediate subtools.
+*   `--search=TERM` which displays only subtools whose name or description
+    contain the specified search term.
+
+Finally, the root tool also supports:
+
+*   `--version` which displays the current Toys version.
+
+### 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.
+
+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:
+
+            |---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.)
+
+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:
+
+    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:
+
+               |--------ARGS--------|
+    toys do -- --help , system --help
+
+## Defining Tools
+
+## Understanding Configurations
+
+## Helper Methods and Modules
+
+## The Standard Helpers
+
+## Prefabricated Tools with Templates
 
 ## Defining Templates
 
-## Built-in Flags and Behavior
+## Advanced Tool Definition Techniques
 
 ## Embedding Toys

data/lib/toys/standard_cli.rb

@@ -29,9 +29,6 @@
 
 require "logger"
 
-require "toys/middleware/show_version"
-require "toys/utils/wrappable_string"
-
 module Toys
   ##
   # Helpers that configure the toys-core CLI with the behavior for the
@@ -86,10 +83,16 @@ module Toys
     #
     DEFAULT_ROOT_LONG_DESC =
       "Toys is your personal command line tool. You can add to the list of commands below by" \
-      " writing scripts in Ruby using a simple DSL, and toys will organize and document them" \
+      " writing scripts in Ruby using a simple DSL, and Toys will organize and document them" \
       " and make them available globally or scoped to specific directories that you choose." \
       " For detailed information, see https://www.rubydoc.info/gems/toys".freeze
 
+    ##
+    # Short description for the verion flag
+    # @return [String]
+    #
+    DEFAULT_VERSION_FLAG_DESC = "Show the version of Toys.".freeze
+
     ##
     # Create a standard CLI, configured with the appropriate paths and
     # middleware.
@@ -160,11 +163,13 @@ module Toys
           search_flags: true,
           default_recursive: true,
           allow_root_args: true,
+          show_source_path: true,
           use_less: true
         ],
         [
-          :show_version,
-          version_displayer: Middleware::ShowVersion.root_version_displayer(::Toys::VERSION)
+          :show_root_version,
+          version_string: ::Toys::VERSION,
+          version_flag_desc: DEFAULT_VERSION_FLAG_DESC
         ],
         [
           :handle_usage_errors
@@ -175,6 +180,7 @@ module Toys
           recursive_flags: true,
           search_flags: true,
           default_recursive: true,
+          show_source_path: true,
           use_less: true
         ],
         [

data/lib/toys/version.rb

@@ -32,5 +32,5 @@ module Toys
   # Current version of the Toys command line binary
   # @return [String]
   #
-  VERSION = "0.3.5".freeze
+  VERSION = "0.3.6".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-15 00:00:00.000000000 Z
+date: 2018-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: toys-core
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 0.3.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.5
+        version: 0.3.6
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement