toys 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b6bf7f26f6ec380fcff62d91f671dd0ac535c740c5dab496ea681f9a94ec93c
-  data.tar.gz: 84b17a1f483b441c3944fa5dc46a9a672b2a339b71c2b5521ce01a7fe117be28
+  metadata.gz: 20520c07615ed64145bf678f175e4e37835e69fe2b92c88f083b554c1902e969
+  data.tar.gz: b3e1efd5fc4e05a620d7834361e353840579c5b4c6c555f95da1f350d81737b0
 SHA512:
-  metadata.gz: dbdc0f5c476a6bd8e46623b7d62b1263ef5e259bc1936991e31294d94083cd551ec078c30f4c05b1bbd966d34c3c49c76ab2f05b37cba68f79b8cf8565995d48
-  data.tar.gz: 4b46179105d491e4860418d2737c3dd190fd199a93f0cdcd7496943c2c05510d4fd0b787df0265b50a65bd962a36129258899ef4fd29faa9b609a4efc0ed37ee
+  metadata.gz: cdd293b0870059e7ff90dfac63844046d435b4150cd32d15fa2e8b8bef39c975db6ba6df87af89bf84f17fa075a57ffd9b6499b7fbcd4206cc7a281701411aed
+  data.tar.gz: 3e75b09dc3e6df45113bbad6d2dfb9c40601eb35b743d3557455be8821ace82d5bc762c34c07c89d5faf043c9d10de08dd49227346578ab20c675bad8e57a6a3

data/.yardopts

@@ -7,3 +7,5 @@
 README.md
 LICENSE.md
 CHANGELOG.md
+docs/guide.md
+docs/tutorial.md

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 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.
+* CHANGED: Renamed `execute do` to `script do`.
+* IMPROVED: Help display uses `less` if available.
+
 ### 0.3.4 / 2018-05-14
 
 * CHANGED: Renamed switch to flag

data/README.md

@@ -1,12 +1,105 @@
 # Toys
 
-Toys is a command line binary that lets you build your own suite of command
-line tools (with commands and subcommands) using a Ruby DSL. Commands can be
-defined globally or scoped to directories.
+Toys is a command line binary that lets you build your own personal suite of
+command line tools using a Ruby DSL. Toys handles argument parsing, error
+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.
+
+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.
+
+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).
 
 ## Quick Start
 
-(TODO)
+Here's a five-minute tutorial to get the feel of what Toys can do.
+
+### Install toys
+
+Install the **toys** gem using:
+
+    gem install toys
+
+This installs the `toys` binary, along with some builtin tools and libraries.
+You can run the binary immediately:
+
+    toys
+
+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:
+
+    toys system version
+
+The "system version" tool displays the current version of the toys gem.
+
+### Write your first tool
+
+You can define tools by creating toys *config files*. Using your favorite
+editor, create a new file called `.toys.rb` (note the leading period) in your
+current directory. Copy the following into the file, and save it:
+
+    tool "greet" do
+      desc "My first tool!"
+      flag :whom, default: "world"
+      script do
+        puts "Hello, #{options[:whom]}!"
+      end
+    end
+
+This defines a tool named "greet". Try running it:
+
+    toys greet
+
+The tool also recognizes a flag on the command line. Try this:
+
+    toys greet --whom=ruby
+
+Toys provides a rich set of features for defining command line arguments and
+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
+`--help` flag:
+
+    toys greet --help
+
+### 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.
+
+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 the Highline library, which you can use to produce styled output,
+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}.
 
 ## Contributing
 

data/builtins/do.rb

@@ -49,7 +49,7 @@ flag :delim, "-d", "--delim=VALUE",
 
 remaining_args :args, desc: "A series of tools to run, separated by the delimiter"
 
-execute do
+script do
   delim = self[:delim]
   self[:args]
     .chunk { |arg| arg == delim ? :_separator : true }

data/builtins/system.rb

@@ -27,22 +27,22 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-desc "A group of system commands for toys"
+desc "A set of system commands for Toys"
 
-long_desc "Contains tools that inspect, configure, and update toys itself."
+long_desc "Contains tools that inspect, configure, and update Toys itself."
 
 tool "version" do
-  desc "Print current toys version."
+  desc "Print current Toys version."
 
-  execute do
+  script do
     puts ::Toys::VERSION
   end
 end
 
 tool "update" do
-  desc "Update toys if a newer version is available."
+  desc "Update Toys if a newer version is available."
 
-  long_desc "Checks rubygems for a newer version of toys. If one is available, downloads" \
+  long_desc "Checks rubygems for a newer version of Toys. If one is available, downloads" \
             " and installs it."
 
   flag :yes, "-y", "--yes", desc: "Do not ask for interactive confirmation"
@@ -50,8 +50,8 @@ tool "update" do
   use :exec
   use :highline
 
-  execute do
-    logger.info "Checking rubygems for the latest toys release..."
+  script do
+    logger.info "Checking rubygems for the latest Toys release..."
     version_info = capture("gem query -q -r -e toys")
     if version_info =~ /toys\s\((.+)\)/
       latest_version = ::Gem::Version.new($1)
@@ -67,7 +67,7 @@ tool "update" do
         logger.warn("Toys is already at the latest version: #{latest_version}")
       end
     else
-      logger.error("Could not get latest toys version")
+      logger.error("Could not get latest Toys version")
       exit(1)
     end
   end

data/docs/guide.md

@@ -0,0 +1,59 @@
+# @title Toys User Guide
+
+# Toys User Guide
+
+Toys is a command line binary that lets you build your own personal suite of
+command line tools using a Ruby DSL. Toys handles argument parsing, error
+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.
+
+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*.
+
+Toys is a multi-command binary. You may define a collection 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*.
+
+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*.
+
+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
+*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,
+and in a *configuration 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.
+
+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.
+
+## The Toys Command Line
+
+## Config Syntax
+
+## Config Search Path
+
+## Defining Helpers
+
+## Defining Templates
+
+## Built-in Flags and Behavior
+
+## Embedding Toys

data/docs/tutorial.md

@@ -0,0 +1,11 @@
+# @title Toys Tutorial
+
+# Toys Tutorial
+
+Toys is a command line binary that lets you build your own personal suite of
+command line tools using a Ruby DSL. Toys handles argument parsing, error
+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.
+
+(To be written)

data/lib/toys/standard_cli.rb

@@ -158,7 +158,9 @@ module Toys
           usage_flags: true,
           recursive_flags: true,
           search_flags: true,
-          allow_root_args: true
+          default_recursive: true,
+          allow_root_args: true,
+          use_less: true
         ],
         [
           :show_version,
@@ -171,7 +173,9 @@ module Toys
           :show_help,
           fallback_execution: true,
           recursive_flags: true,
-          search_flags: true
+          search_flags: true,
+          default_recursive: true,
+          use_less: true
         ],
         [
           :add_verbosity_flags

data/lib/toys/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-14 00:00:00.000000000 Z
+date: 2018-05-15 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.4
+        version: 0.3.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.4
+        version: 0.3.5
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -94,7 +94,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-description: A simple command line tool framework
+description: Toys is a command line binary that lets you build your own personal suite
+  of command line tools using a Ruby DSL. Toys handles argument parsing, error reporting,
+  logging, help text, and many other details for you. It is designed for software
+  developers, IT specialists, and other power users who want to write and organize
+  scripts to automate their workflows.
 email:
 - dazuma@gmail.com
 executables:
@@ -109,6 +113,8 @@ files:
 - bin/toys
 - builtins/do.rb
 - builtins/system.rb
+- docs/guide.md
+- docs/tutorial.md
 - lib/toys.rb
 - lib/toys/standard_cli.rb
 - lib/toys/version.rb
@@ -135,5 +141,5 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Command line tool framework
+summary: Framework for creating personal command line tools
 test_files: []