toys 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e219dd1cfc299c80e8f10f0cf46f3904b9288ee35a672102361cdbe4202cfc8
-  data.tar.gz: 2a26eb0d2ad89bed011e4400773b7cf22fbc3e2af54785a1685fd116fec8168b
+  metadata.gz: f9aca0f88db86e761a9c149409ac63f3abe8965f8bc3ed32c0367f248cfcb953
+  data.tar.gz: 8e23447ec1fb3ccc91d0367bd120bcc388147cd7b114cc9e3d1e91833323076a
 SHA512:
-  metadata.gz: cd0ff9780f576c094b3e5f82815b520cca154a18900f1bdaa72baebf00d7c9ab6d13f0c65ead072e8a06242d93e0a5b903982503f2e49a387a0c6ef4aa2ec332
-  data.tar.gz: 9666ad2f9206e27327bfe0b7b73b382dc54a6c72191534ba30261207f73de6843ade16a24b624838e8d6817cad12dba6d1f7046ecd063a9d2e0a49655c57baba
+  metadata.gz: 99865d61911d609c1dcf55ba6190f16f4bc00e044b696fed1b6bf202f29e3a0533ce87a971fbe1ae1b9cd83ec57a0a62f1eff49efd7f2801818bd43eafefd07e
+  data.tar.gz: a5ae272ae4585690cf5ab0abf7beabd9ba356203a26ebac976e90f94ca5a2120f62dd7a57b80ddc5907d7c04158e304df0a048dec543121b993de0fd8a7868fd

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release History
 
+### 0.7.0 / 2019-01-23
+
+* ADDED: A template for creating tools that invoke RSpec.
+* ADDED: Flag groups, which enforce policies around which flags are required.
+* CHANGED: Flags within a group are sorted in the help screens.
+* IMPROVED: The minitest template now honors all standard minitest flags.
+
 ### 0.6.1 / 2019-01-07
 
 * FIXED: The presence of aliases caused subtool listing to crash.

data/docs/guide.md

@@ -32,7 +32,9 @@ that have **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**.
+positional arguments may be **required** or **optional**. Flags may be
+organized into **flag groups** which support different kinds of constraints on
+which flags are required.
 
 The configuration of a tool may include **descriptions**, for the tool itself,
 and for each command line argument. These descriptions are displayed in the
@@ -193,10 +195,13 @@ 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:
 
+*   `--all` which displays all subtools, including
+    [hidden subtools](#Hidden_Tools) and namespaces.
 *   `--[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.
+*   `--tools` which displays just the list of subtools.
 
 Finally, the root tool also supports:
 
@@ -657,6 +662,72 @@ way, Toys provides an alternate syntax for defining flags using a block.
 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).
 
+#### Flag Groups
+
+Flags may be organized into groups. This serves two functions:
+
+*   Grouping related flags in the help and usage screens
+*   Implementing required flags and other constraints
+
+To create a simple flag group, use the `flag_group` directive, and provide a
+block that defines the group's flags. You may also provide a group description
+that appears in the help screen.
+
+    flag_group desc: "Debug flags" do
+      flag :debug, "-D", desc: "Enable debugger"
+      flag :warnings, "-W[VAL]", desc: "Enable warnings"
+    end
+
+Flag groups may have a "type" that specifies constraints on the flags contained
+in the group. Flags in a simple group like the above are ordinary optional
+flags. However, you may specify that flags in the group are required using the
+`all_required` directive:
+
+    all_required desc: "Login flags (all required)" do
+      flag :username, "--username=VAL", desc: "Set the username (required)"
+      flag :password, "--password=VAL", desc: "Set the password (required)"
+    end
+
+If the tool is invoked without providing each of these required flags, it will
+display an option parsing error.
+
+The `all_required` directive is actually just shorthand for passing
+`type: :required` to the `flag_group` directive. So the above is the same as:
+
+    flag_group type: :required, desc: "Login flags (all required)" do
+      flag :username, "--username=VAL", desc: "Set the username (required)"
+      flag :password, "--password=VAL", desc: "Set the password (required)"
+    end
+
+There are several other types of flag groups:
+
+*   The `:exactly_one` type, which you can create using the directive
+    `exactly_one_required`. Exactly one, and no more than one, flag from the
+    group must be provided on the command line to avoid an error.
+*   The `:at_most_one` type, which you can create using the directive
+    `at_most_one_required`. At most one flag from the group must be provided
+    on the command line to avoid an error.
+*   The `:at_least_one` type, which you can create using the directive
+    `at_least_one_required`. At least one flag from the group must be provided
+    on the command line to avoid an error.
+
+Flag group types are useful for a variety of tools. For example, suppose you
+are writing a tool that deploys an app to one of several different kinds of
+targets---say, a server, a VM, or a container. You could provide this
+configuration for your tool with a flag group:
+
+    tool "deploy" do
+      exactly_one_required desc: "Deployment targets" do
+        flag :server, "--server=IP_ADDR"
+        flag :vm, "--vm=VM_ID"
+        flag :container, "--container=CONTAINER_ID"
+      end
+
+      def run
+        # Now exactly one of server, vm, or container will be set.
+      end
+    end
+
 ### Tool Execution Basics
 
 When you run a tool from the command line, Toys will build the tool based on
@@ -951,9 +1022,10 @@ When Toys runs, it looks for tools in a **search path**. Specifically:
     working directory*.
 (2) It does the same in the *parent directory* of the current directory, and
     then 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*.
+(3) It does the same in the current user's *home directory* (but does not
+    proceed to parents of the home directory).
 (4) It does the same in the system configuration directory (i.e. `/etc` on unix
-    systems)
+    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
@@ -1790,7 +1862,7 @@ with:
 
     toys test
 
-Similarly, a task named `test:integration` can be invoekd with either of the
+Similarly, a task named `test:integration` can be invoked with either of the
 following:
 
     toys test integration
@@ -1863,14 +1935,22 @@ can use either or both tools, depending on your needs.
 
 ### Running Tests
 
-Toys provides a built-in template for minitest, called `:minitest`. It is
-implemented by the template class {Toys::Templates::Minitest}, and it uses the
-[minitest gem](https://rubygems.org/gems/minitest). The following directive
-uses the minitest template to create a tool called `test`:
+Toys provides a built-in template called `:minitest` for running unit tests
+with [minitest](https://github.com/seattlerb/minitest). The following example
+directive uses the minitest template to create a tool called `test`:
 
     expand :minitest, files: ["test/test*.rb"], libs: ["lib", "ext"]
 
-See the {Toys::Templates::Minitest} documentation for details on the various
+See the {Toys::Templates::Minitest} documentation for details on the available
+options.
+
+Toys also provides a built-in template called `:rspec` for running BDD examples
+using [RSpec](http://rspec.info). The following example directive uses this
+template to create a tool called `spec`:
+
+    expand :rspec, pattern: "spec/**/*_spec.rb", libs: ["lib, "ext"]
+
+See the {Toys::Templates::Rspec} documentation for details on the available
 options.
 
 If you want to enforce code style using the
@@ -2370,6 +2450,17 @@ context directory to `my-repo/gem1`. Here's what that could look like:
       # etc.
     end
 
+### Hidden Tools
+
+Tools whose name begins with an underscore (e.g. `_foo`) are called "hidden"
+tools. They can be executed the same as any other tool, but are normally
+omitted from the subtool list displayed in help and usage screens. You may use
+hidden tools as "internal" tools that are meant to be called only as part of
+the implementation of other tools.
+
+If you pass the `--all` flag when displaying help, the help screen will include
+hidden tools in the subtools list.
+
 ## Toys Administration Using the System Tools
 
 Toys comes with a few built-in tools, including some that let you administer

data/lib/toys/standard_cli.rb

@@ -114,6 +114,12 @@ module Toys
     #
     DEFAULT_VERSION_FLAG_DESC = "Show the version of Toys."
 
+    ##
+    # Name of the toys path environment variable
+    # @return [String]
+    #
+    TOYS_PATH_ENV = "TOYS_PATH"
+
     ##
     # Create a standard CLI, configured with the appropriate paths and
     # middleware.
@@ -223,12 +229,13 @@ module Toys
     # @return [Array<String>]
     #
     def self.default_global_dirs
-      paths = ::ENV["TOYS_PATH"].to_s.split(::File::PATH_SEPARATOR)
-      if paths.empty?
-        paths << ::ENV["HOME"] if ::ENV["HOME"]
-        paths << "/etc" if ::File.directory?("/etc") && ::File.readable?("/etc")
-      end
-      paths.map { |path| ::File.realpath(::File.expand_path(path)) }
+      paths = ::ENV[TOYS_PATH_ENV].to_s.split(::File::PATH_SEPARATOR)
+      paths = [::Dir.home, "/etc"] if paths.empty?
+      paths
+        .compact
+        .uniq
+        .select { |path| ::File.directory?(path) && ::File.readable?(path) }
+        .map { |path| ::File.realpath(::File.expand_path(path)) }
     end
 
     ##

data/lib/toys/templates/minitest.rb

@@ -79,11 +79,15 @@ module Toys
                      gem_version: nil,
                      libs: nil,
                      files: nil,
+                     seed: nil,
+                     verbose: false,
                      warnings: true)
         @name = name || DEFAULT_TOOL_NAME
         @gem_version = gem_version || DEFAULT_GEM_VERSION_REQUIREMENTS
         @libs = libs || DEFAULT_LIBS
         @files = files || DEFAULT_FILES
+        @seed = seed
+        @verbose = verbose
         @warnings = warnings
       end
 
@@ -91,6 +95,8 @@ module Toys
       attr_accessor :gem_version
       attr_accessor :libs
       attr_accessor :files
+      attr_accessor :seed
+      attr_accessor :verbose
       attr_accessor :warnings
 
       to_expand do |template|
@@ -100,9 +106,15 @@ module Toys
           include :exec
           include :gems
 
+          flag :seed, "-s", "--seed SEED",
+               default: template.seed, desc: "Sets random seed."
           flag :warnings, "-w", "--[no-]warnings",
                default: template.warnings,
                desc: "Turn on Ruby warnings (defaults to #{template.warnings})"
+          flag :name, "-n", "--name PATTERN",
+               desc: "Filter run on /regexp/ or string."
+          flag :exclude, "-e", "--exclude PATTERN",
+               desc: "Exclude /regexp/ or string from run."
 
           remaining_args :tests, desc: "Paths to the tests to run (defaults to all tests)"
 
@@ -111,11 +123,16 @@ module Toys
 
             ::Dir.chdir(context_directory || ::Dir.getwd) do
               ruby_args = []
-              unless template.libs.empty?
-                lib_path = template.libs.join(::File::PATH_SEPARATOR)
-                ruby_args << "-I#{lib_path}"
-              end
+              libs = Array(template.libs)
+              ruby_args << "-I#{libs.join(::File::PATH_SEPARATOR)}" unless libs.empty?
               ruby_args << "-w" if warnings
+              ruby_args << "-"
+              ruby_args << "--seed" << seed if seed
+              vv = verbosity
+              vv += 1 if template.verbose
+              ruby_args << "--verbose" if vv.positive?
+              ruby_args << "--name" << name if name
+              ruby_args << "--exclude" << exclude if exclude
 
               if tests.empty?
                 Array(template.files).each do |pattern|
@@ -124,7 +141,8 @@ module Toys
                 tests.uniq!
               end
 
-              result = ruby(ruby_args, in: :controller) do |controller|
+              result = exec_ruby(ruby_args, in: :controller) do |controller|
+                controller.in.puts("require 'minitest/autorun'")
                 tests.each do |file|
                   controller.in.puts("load '#{file}'")
                 end

data/lib/toys/templates/rspec.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+# Copyright 2018 Daniel Azuma
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * 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.
+;
+
+module Toys
+  module Templates
+    ##
+    # A template for tools that run rspec
+    #
+    class Rspec
+      include Template
+
+      ##
+      # Default version requirements for the rspec gem.
+      # @return [Array<String>]
+      #
+      DEFAULT_GEM_VERSION_REQUIREMENTS = "~> 3.1"
+
+      ##
+      # Default tool name
+      # @return [String]
+      #
+      DEFAULT_TOOL_NAME = "spec"
+
+      ##
+      # Default set of library paths
+      # @return [Array<String>]
+      #
+      DEFAULT_LIBS = ["lib"].freeze
+
+      ##
+      # Default order type
+      # @return [String]
+      #
+      DEFAULT_ORDER = "defined"
+
+      ##
+      # Default spec file glob
+      # @return [String]
+      #
+      DEFAULT_PATTERN = "spec/**/*_spec.rb"
+
+      ##
+      # Create the template settings for the RSpec template.
+      #
+      # @param [String] name Name of the tool to create. Defaults to
+      #     {DEFAULT_TOOL_NAME}.
+      # @param [String,Array<String>] gem_version Version requirements for
+      #     the rspec gem. Defaults to {DEFAULT_GEM_VERSION_REQUIREMENTS}.
+      # @param [Array<String>] libs An array of library paths to add to the
+      #     ruby require path. Defaults to {DEFAULT_LIBS}.
+      # @param [String] options The path to a custom options file.
+      # @param [String] order The order in which to run examples. Default is
+      #     {DEFAULT_ORDER}.
+      # @param [String] format Choose a formatter code. Default is `p`.
+      # @param [String] out Write output to a file instead of stdout.
+      # @param [Boolean] backtrace Enable full backtrace (default is false).
+      # @param [String] pattern A glob indicating the spec files to load.
+      #     Defaults to {DEFAULT_PATTERN}.
+      # @param [Boolean] warnings If true, runs specs with Ruby warnings.
+      #     Defaults to true.
+      #
+      def initialize(name: nil,
+                     gem_version: nil,
+                     libs: nil,
+                     options: nil,
+                     order: nil,
+                     format: nil,
+                     out: nil,
+                     backtrace: false,
+                     pattern: nil,
+                     warnings: true)
+        @name = name || DEFAULT_TOOL_NAME
+        @gem_version = gem_version || DEFAULT_GEM_VERSION_REQUIREMENTS
+        @libs = libs || DEFAULT_LIBS
+        @options = options
+        @order = order || DEFAULT_ORDER
+        @format = format || "p"
+        @out = out
+        @backtrace = backtrace
+        @pattern = pattern || DEFAULT_PATTERN
+        @warnings = warnings
+      end
+
+      attr_accessor :name
+      attr_accessor :gem_version
+      attr_accessor :libs
+      attr_accessor :options
+      attr_accessor :order
+      attr_accessor :format
+      attr_accessor :out
+      attr_accessor :backtrace
+      attr_accessor :pattern
+      attr_accessor :warnings
+
+      to_expand do |template|
+        tool(template.name) do
+          desc "Run rspec on the current project."
+
+          include :exec
+          include :gems
+
+          flag :order, "--order TYPE",
+               default: template.order,
+               desc: "Run examples by the specified order type (default: #{template.order})"
+          flag :format, "-f", "--format FORMATTER",
+               default: template.format,
+               desc: "Choose a formatter (default: #{template.format})"
+          flag :out, "-o", "--out FILE",
+               default: template.out,
+               desc: "Write output to a file (default: #{template.out.inspect})"
+          flag :backtrace, "-b", "--[no-]backtrace",
+               default: template.backtrace,
+               desc: "Enable full backtrace (default: #{template.backtrace})"
+          flag :warnings, "-w", "--[no-]warnings",
+               default: template.warnings,
+               desc: "Turn on Ruby warnings (default: #{template.warnings})"
+          flag :pattern, "-P", "--pattern PATTERN",
+               default: template.pattern,
+               desc: "Load files matching pattern (default: #{template.pattern.inspect})"
+          flag :exclude_pattern, "--exclude-pattern PATTERN",
+               desc: "Load files except those matching pattern."
+          flag :example, "-e", "--example STRING",
+               desc: "Run examples whose full nested names include STRING" \
+                     " (may be used more than once)."
+          flag :tag, "-t", "--tag TAG",
+               desc: "Run examples with the specified tag, or exclude" \
+                     " examples by adding ~ before the tag."
+
+          remaining_args :files, desc: "Paths to the specs to run (defaults to all specs)"
+
+          to_run do
+            gem "rspec", *Array(template.gem_version)
+
+            ::Dir.chdir(context_directory || ::Dir.getwd) do
+              ruby_args = []
+              libs = Array(template.libs)
+              ruby_args << "-I#{libs.join(::File::PATH_SEPARATOR)}" unless libs.empty?
+              ruby_args << "-w" if warnings
+              ruby_args << "-"
+              ruby_args << "--options" << template.options if template.options
+              ruby_args << "--order" << order if order
+              ruby_args << "--format" << format if format
+              ruby_args << "--out" << out if out
+              ruby_args << "--backtrace" if backtrace
+              ruby_args << "--pattern" << pattern
+              ruby_args << "--exclude-pattern" << exclude_pattern if exclude_pattern
+              ruby_args << "--example" << example if example
+              ruby_args << "--tag" << tag if tag
+              ruby_args.concat(files)
+
+              result = exec_ruby(ruby_args, in: :controller) do |controller|
+                controller.in.puts("require 'rspec/core'")
+                controller.in.puts("::RSpec::Core::Runner.invoke")
+              end
+              if result.error?
+                logger.error("RSpec failed!")
+                exit(result.exit_code)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toys/templates/rubocop.rb

@@ -87,9 +87,9 @@ module Toys
             require "rubocop"
 
             ::Dir.chdir(context_directory || ::Dir.getwd) do
-              cli = ::RuboCop::CLI.new
+              rubocop = ::RuboCop::CLI.new
               logger.info "Running RuboCop..."
-              result = cli.run(template.options)
+              result = rubocop.run(template.options)
               if result.nonzero?
                 logger.error "RuboCop failed!"
                 exit(1) if template.fail_on_error

data/lib/toys/version.rb

@@ -34,5 +34,5 @@ module Toys
   # Current version of the Toys command line binary
   # @return [String]
   #
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-08 00:00:00.000000000 Z
+date: 2019-01-24 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.6.1
+        version: 0.7.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.7.0
 - !ruby/object:Gem::Dependency
   name: highline
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +108,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -165,6 +179,7 @@ files:
 - lib/toys/templates/minitest.rb
 - lib/toys/templates/rake.rb
 - lib/toys/templates/rdoc.rb
+- lib/toys/templates/rspec.rb
 - lib/toys/templates/rubocop.rb
 - lib/toys/templates/yardoc.rb
 - lib/toys/version.rb