toys 0.3.6 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4090b70821f47975fbfd82cd40651b3ee93e43ecf77cb7a820f20322524a3447
-  data.tar.gz: 70440b824c11d8c7b14e0cda8bfd57f8a74df0aa084c5f47b63efbd3047a7706
+  metadata.gz: 7744684eb5fd0d03f650315fad4bb84bc433d0ce4e0529c82f6bf2ebcb60f9f5
+  data.tar.gz: 26c4d2e48917887441bd6bc03986110f7269bdd2b1f0098d1b9cd3a19a5b0248
 SHA512:
-  metadata.gz: e2a58b4eea98ed65f797dcccdef7bc5abbb3df45aa9771263e9c69bc809b3d15507521cfc012753285dc9464c441db0d08e7a31c15c098e610fffe959888e621
-  data.tar.gz: 41a9dbfee92b60d34cb74b07ac8599a8bf01da0203d386dcfd73a3dac8711030d97c6548ff40caa3dd63dc9fb123c14eb590dbb6a5809679978ebc081328141d
+  metadata.gz: 61445d45a25a6d64f9f2fc547e38589b7f49d8cdf08a07e7bff33b3687307bbeed4b7aa1f8528c2c91a6abf52c3bea86a79392d3d0bbf98652fe5fd2d526f693
+  data.tar.gz: a08b400babfecc9c6fd119447d37f62df645986b3d23e5ef381cbf7e05d766b3d1eebd97d0947bb7a8c7cd5b5f53c59aaca329f4bfbb4a8c0463520b11ca1dca

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 0.3.7 / 2018-05-30
+
+* CHANGED: Execution runs in the same scope as the DSL, which lets us use normal methods instead of helper-blocks.
+* CHANGED: Renamed "script" to "run", and allow setting of runnable by defining a "run" method
+* CHANGED: Set up a constant scope for each config file, to make constant lookup make sense.
+* CHANGED: Removed run_toys and dropped EXIT_ON_NONZERO_STATUS key in favor of using cli directly.
+* CHANGED: Removed spinner helper and added terminal helper.
+* ADDED: Helper modules scoped to the tool hierarchy
+
 ### 0.3.6 / 2018-05-21
 
 * CHANGED: Removed Context#new_cli and exposed Context#cli instead.

data/README.md

@@ -69,8 +69,8 @@ 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]}!"
+      def run
+        puts "Hello, #{option(:whom)}!"
       end
     end
 
@@ -107,9 +107,10 @@ 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.
+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

data/bin/toys

@@ -29,6 +29,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
+::ENV["TOYS_BIN_PATH"] ||= ::File.absolute_path(__FILE__)
+
 $LOAD_PATH.unshift(::File.absolute_path(::File.join(::File.dirname(__dir__), "lib")))
 require "toys"
 

data/builtins/do.rb

@@ -54,12 +54,11 @@ flag :delim, "-d", "--delim=VALUE",
 
 remaining_args :args, desc: "A series of tools to run, separated by the delimiter"
 
-script do
-  delim = self[:delim]
-  self[:args]
-    .chunk { |arg| arg == delim ? :_separator : true }
+def run
+  option(:args)
+    .chunk { |arg| arg == option(:delim) ? :_separator : true }
     .each do |_, action|
-      code = run(action)
+      code = cli.run(action)
       exit(code) unless code.zero?
     end
 end

data/builtins/system.rb

@@ -32,42 +32,56 @@ desc "A set of system commands for Toys"
 long_desc "Contains tools that inspect, configure, and update Toys itself."
 
 tool "version" do
-  desc "Print current Toys version."
+  desc "Print the current Toys version"
 
-  script do
+  def run
     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" \
             " and installs it."
 
   flag :yes, "-y", "--yes", desc: "Do not ask for interactive confirmation"
 
-  use :exec
-  use :highline
+  include :exec
+  include :terminal
 
-  script do
-    logger.info "Checking rubygems for the latest Toys release..."
-    version_info = capture("gem query -q -r -e toys")
+  def run
+    configure_exec(exit_on_nonzero_status: true)
+    version_info = terminal.spinner(leading_text: "Checking rubygems for the latest release... ",
+                                    final_text: "Done.\n") do
+      capture(["gem", "query", "-q", "-r", "-e", "toys"])
+    end
     if version_info =~ /toys\s\((.+)\)/
       latest_version = ::Gem::Version.new($1)
       cur_version = ::Gem::Version.new(::Toys::VERSION)
       if latest_version > cur_version
-        exit(1) unless options[:yes] ||
-                       agree("Update toys from #{cur_version} to #{latest_version}? (y/n) ")
-        sh("gem install toys")
+        prompt = "Update toys from #{cur_version} to #{latest_version}?"
+        exit(1) unless option(:yes) || confirm(prompt)
+        result = terminal.spinner(leading_text: "Installing Toys version #{latest_version}... ",
+                                  final_text: "Done.\n") do
+          exec(["gem", "install", "toys", "--version", latest_version],
+               out_to: :capture, err_to: :capture)
+        end
+        if result.error?
+          puts(result.captured_out + result.captured_err)
+          puts("Toys failed to install version #{latest_version}", :red, :bold)
+          exit(1)
+        end
+        puts("Toys successfully installed version #{latest_version}", :green, :bold)
       elsif latest_version < cur_version
-        logger.warn("Toys is already at experimental version #{cur_version}, which is later than" \
-                    " the latest released version #{latest_version}")
+        puts("Toys is already at experimental version #{cur_version}, which is later than" \
+             " the latest released version #{latest_version}",
+             :yellow, :bold)
       else
-        logger.warn("Toys is already at the latest version: #{latest_version}")
+        puts("Toys is already at the latest version: #{latest_version}", :green, :bold)
       end
     else
-      logger.error("Could not get latest Toys version")
+      puts("Could not get latest Toys version", :red, :bold)
       exit(1)
     end
   end

data/docs/guide.md

@@ -14,34 +14,34 @@ This user's guide covers everything you need to know to use Toys effectively.
 
 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 **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*
+**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*.
 
-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*.
+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
-*online help* screen. Descriptions come in *long* and *short* forms, which
-appear in different styles of help.
+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 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 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.
+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
+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
+built-in namespace of **system tools** that let you inspect and configure the
 Toys system itself.
 
 ## The Toys Command Line
@@ -76,7 +76,7 @@ In the following command:
     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
+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.
 
@@ -152,8 +152,8 @@ 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.
+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.
 
 #### Standard Flags
 
@@ -224,16 +224,192 @@ like so:
 
 ## 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.
+
+### Basic Config 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
+[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.
+
+Consider the following example:
+
+    tool "greet" do
+      desc "Print a friendly greeting."
+      long_desc "Prints a friendly greeting. You may customize whom to" \
+                  " greet, and how friendly it should be.",
+                "",
+                "Example:",
+                ["    toys greet --shout ruby"]
+
+      optional_arg :whom, default: "world", desc: "Whom to greet."
+      flag :shout, "-s", "--shout", desc: "Greet loudly."
+
+      def run
+        greeting = "Hello, #{option(:whom)}!"
+        greeting.upcase! if option(:shout)
+        puts greeting
+      end
+    end
+
+Its results should be mostly self-evident. We'll take a look at some of the
+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 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.
+
+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
+will not be split. The example command in the long description above
+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)
+and
+[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.
+
+    toys greet ruby
+
+Then the option `:whom` is set to the string `"ruby"`. The value is made
+available via the `options` hash in the tools's script. Otherwise, if the
+argument is omitted, e.g.
+
+    toys greet
+
+Then the option `:whom` is set to the default value `"world"`.
+
+Arguments may also be **required** which means they 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).
+
+When command line arguments are parsed, the required arguments are matched
+first, in order, followed by the optional arguments. For example:
+
+    tool "arguments" do
+      optional_arg :arg2
+      required_arg :arg1
+      # ...
+
+If a user runs
+
+    toys arguments 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
+
+Then `:arg1` is set to `"foo"`, and `:arg2` is set to `"bar"`.
+
+Running the following:
+
+    toys arguments
+
+Will produce a usage error, because no value is set for the required argument
+`:arg1`. Similarly, running:
+
+    toys arguments foo bar baz
+
+Will also produce an error, since the tool does not provide 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:
+
+    tool "arguments" do
+      optional_arg :arg2
+      required_arg :arg1
+      remaining_args :arg3
+      # ...
+
+Now, running:
+
+    toys arguments foo bar baz bey
+
+Sets the following option data:
+
+    {arg1: "foo", arg2: "bar", arg3: ["baz", "bey"]}
+
+Positional arguments may also have short and long descriptions, which are
+displayed in online help.
+
+### Flags
+
+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)
+
+### The Execution Script
+
+### Namespaces
+
 ## Understanding Configurations
 
 ## Helper Methods and Modules
 
-## The Standard Helpers
+### The Standard Helpers
+
+## The Execution Environment
+
+### Built-in Context
+
+### Logging and Verbosity
+
+### Running Tools from Tools
+
+### Executing Subprocesses
+
+### Formatting Output
 
 ## Prefabricated Tools with Templates
 
-## Defining Templates
+### Defining Templates
 
 ## Advanced Tool Definition Techniques
 
+### Aliases
+
+### Includes
+
+### Controlling Built-in Flags
+
+## The System Tools
+
 ## Embedding Toys

data/lib/toys.rb

@@ -34,6 +34,11 @@
 # individual directories.
 #
 module Toys
+  ##
+  # Path to the Toys binary
+  # @return [String]
+  #
+  BINARY_PATH = ::ENV["TOYS_BIN_PATH"] || "toys"
 end
 
 require "toys/version"

data/lib/toys/standard_cli.rb

@@ -75,7 +75,7 @@ module Toys
     # Short description for the standard root tool
     # @return [String]
     #
-    DEFAULT_ROOT_DESC = "Your personal command line tool.".freeze
+    DEFAULT_ROOT_DESC = "Your personal command line tool".freeze
 
     ##
     # Help text for the standard root tool
@@ -125,9 +125,9 @@ module Toys
     #    `$HOME:/etc` by default.
     # *  The builtins for the standard toys binary.
     #
+    # @param [Toys::CLI] cli Add paths to this CLI
     # @param [String,nil] directory Starting search directory for configs.
     #     Defaults to the current working directory.
-    # @param [Toys::CLI] cli Add paths to this CLI
     #
     def self.add_standard_paths(cli, directory: nil)
       cli.add_search_path_hierarchy(start: directory)

data/lib/toys/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.3.7
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-21 00:00:00.000000000 Z
+date: 2018-05-30 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.6
+        version: 0.3.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.6
+        version: 0.3.7
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement