toys-core 0.3.7.1 → 0.3.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1aa9e869c65cf77b35297969e3ca1982242afecadf90d9cb916dac0e0d5f5167
-  data.tar.gz: e46555ffe1779fc8f4375f301e4ee34c892785cfb01b454f24854ffac905bab8
+  metadata.gz: bbe7cd88d7c1eba9d74c0006bfe81372963949d969671ad3d13597b941525a3f
+  data.tar.gz: 5c567a9a61f747fd292339681d24d7bc56fa89859d9f60f6f0f6796665b93148
 SHA512:
-  metadata.gz: f9e864b63f7ea61c2e1eed7e5ca0fbdeabc393d8fc2c1c284a7b899a63d3cfa33a58f6790417fa73bb4fd20ca73bfd04c1ccdf4fe093259ce090a01b81ce4d09
-  data.tar.gz: 5ac0fe98810ac7b71880fb843f3deb1148d81aa5912af67e0385e5e422e02bc059747b77c59306de743a65f724942a5f813f322ba4209a4f03f8ad12f8cb7ac6
+  metadata.gz: fe5308be03b7d7348390caf05d6c6ba76503746133b45931b1b7c75c7b5095f03ca4ee88cefde3e0a46583901a66fa56bd5fb628c242c64d3abb854d3fb548c8
+  data.tar.gz: 9766792fef7ba0e77aa8e0254f222ea6f64238eaa3bdc1ed758faf8429105662be235014de8c375803a2da38fe2b0c3da1ae110e77a96d127e318f452f29453b

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History
 
+### 0.3.8 / 2018-06-10
+
+* CHANGED: Renamed helpers to mixins.
+* CHANGED: ModuleLookup is now a customizable class and can have multiple sources.
+* CHANGED: Moved the existing templates to the toys gem since they are rake replacements.
+* CHANGED: Renamed :in_from, :out_to, and :err_to exec options to :in, :out, :err
+* ADDED: CLI can now customize the standard mixins, templates, and middleware.
+* IMPROVED: Exec raises an error if passed an unknown option.
+* IMPROVED: Exec now accepts nearly all the same stream specifications as Process#spawn.
+
 ### 0.3.7.1 / 2018-05-30
 
 * No changes.

data/README.md

@@ -19,8 +19,7 @@ highly experimental, and the code is evolving very rapidly. Please contact the
 author before embarking on a major pull request. More detailed contribution
 guidelines will be provided when the software stabilizes further.
 
-The source can be found on Github at
-[https://github.com/dazuma/toys](https://github.com/dazuma/toys)
+The source can be found on Github at https://github.com/dazuma/toys
 
 ## License
 

data/lib/toys-core.rb

@@ -34,20 +34,31 @@
 # individual directories.
 #
 module Toys
-  ##
-  # Namespace for common utility classes.
-  #
-  module Utils; end
-
   ##
   # Namespace for object definition classes.
   #
   module Definition; end
 
   ##
-  # Namespace for DSL classes.
+  # Namespace for DSL classes. These classes provide the directives that can be
+  # used in configuration files. Most are defined in {Toys::DSL::Tool}.
   #
   module DSL; end
+
+  ##
+  # Namespace for standard mixin classes.
+  #
+  module StandardMixins; end
+
+  ##
+  # Namespace for standard middleware classes.
+  #
+  module StandardMiddleware; end
+
+  ##
+  # Namespace for common utility classes.
+  #
+  module Utils; end
 end
 
 require "toys/cli"
@@ -61,11 +72,15 @@ require "toys/dsl/arg"
 require "toys/dsl/flag"
 require "toys/dsl/tool"
 require "toys/errors"
-require "toys/helpers"
 require "toys/input_file"
 require "toys/loader"
 require "toys/middleware"
 require "toys/runner"
 require "toys/template"
-require "toys/templates"
 require "toys/tool"
+require "toys/utils/exec"
+require "toys/utils/gems"
+require "toys/utils/help_text"
+require "toys/utils/module_lookup"
+require "toys/utils/terminal"
+require "toys/utils/wrappable_string"

data/lib/toys/cli.rb

@@ -29,8 +29,6 @@
 
 require "logger"
 
-require "toys/utils/terminal"
-
 module Toys
   ##
   # A Toys-based CLI.
@@ -39,7 +37,7 @@ module Toys
   #
   class CLI
     ##
-    # Create a CLI
+    # Create a CLI.
     #
     # @param [String,nil] binary_name The binary name displayed in help text.
     #     Optional. Defaults to the ruby program name.
@@ -65,7 +63,17 @@ module Toys
     #     may use such a file to define auxiliary Ruby modules and classes that
     #     used by the tools defined in that directory.
     # @param [Array] middleware_stack An array of middleware that will be used
-    #     by default for all tools loaded by this CLI.
+    #     by default for all tools loaded by this CLI. If not provided, uses
+    #     {Toys::CLI.default_middleware_stack}.
+    # @param [Toys::Utils::ModuleLookup] mixin_lookup A lookup for well-known
+    #     mixin modules. If not provided, uses
+    #     {Toys::CLI.default_mixin_lookup}.
+    # @param [Toys::Utils::ModuleLookup] middleware_lookup A lookup for
+    #     well-known middleware classes. If not provided, uses
+    #     {Toys::CLI.default_middleware_lookup}.
+    # @param [Toys::Utils::ModuleLookup] template_lookup A lookup for
+    #     well-known template classes. If not provided, uses
+    #     {Toys::CLI.default_template_lookup}.
     # @param [Logger,nil] logger The logger to use. If not provided, a default
     #     logger that writes to `STDERR` is used.
     # @param [Integer,nil] base_level The logger level that should correspond
@@ -77,15 +85,11 @@ module Toys
     #     Default is a {Toys::CLI::DefaultErrorHandler} writing to the logger.
     #
     def initialize(
-      binary_name: nil,
-      config_dir_name: nil,
-      config_file_name: nil,
-      index_file_name: nil,
-      preload_file_name: nil,
-      middleware_stack: nil,
-      logger: nil,
-      base_level: nil,
-      error_handler: nil
+      binary_name: nil, middleware_stack: nil,
+      config_dir_name: nil, config_file_name: nil,
+      index_file_name: nil, preload_file_name: nil,
+      mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil,
+      logger: nil, base_level: nil, error_handler: nil
     )
       @logger = logger || self.class.default_logger
       @base_level = base_level || @logger.level
@@ -95,10 +99,13 @@ module Toys
       @config_file_name = config_file_name
       @index_file_name = index_file_name
       @preload_file_name = preload_file_name
+      @mixin_lookup = mixin_lookup || self.class.default_mixin_lookup
+      @middleware_lookup = middleware_lookup || self.class.default_middleware_lookup
+      @template_lookup = template_lookup || self.class.default_template_lookup
       @loader = Loader.new(
-        index_file_name: index_file_name,
-        preload_file_name: preload_file_name,
-        middleware_stack: @middleware_stack
+        index_file_name: index_file_name, preload_file_name: preload_file_name,
+        mixin_lookup: @mixin_lookup, template_lookup: @template_lookup,
+        middleware_lookup: @middleware_lookup, middleware_stack: @middleware_stack
       )
       @error_handler = error_handler || DefaultErrorHandler.new
     end
@@ -236,6 +243,9 @@ module Toys
                     index_file_name: @index_file_name,
                     preload_file_name: @preload_file_name,
                     middleware_stack: @middleware_stack,
+                    mixin_lookup: @mixin_lookup,
+                    middleware_lookup: @middleware_lookup,
+                    template_lookup: @template_lookup,
                     logger: @logger,
                     base_level: @base_level,
                     error_handler: @error_handler)
@@ -301,14 +311,14 @@ module Toys
       # Returns a default set of middleware that may be used as a starting
       # point for a typical CLI. This set includes the following in order:
       #
-      # *  {Toys::Middleware::SetDefaultDescriptions} providing defaults for
-      #    description fields
-      # *  {Toys::Middleware::ShowHelp} adding the `--help` flag
-      # *  {Toys::Middleware::HandleUsageErrors}
-      # *  {Toys::Middleware::ShowHelp} providing default behavior for
+      # *  {Toys::StandardMiddleware::SetDefaultDescriptions} providing
+      #    defaults for description fields
+      # *  {Toys::StandardMiddleware::ShowHelp} adding the `--help` flag
+      # *  {Toys::StandardMiddleware::HandleUsageErrors}
+      # *  {Toys::StandardMiddleware::ShowHelp} providing default behavior for
       #    namespaces
-      # *  {Toys::Middleware::AddVerbosityFlags} adding the `--verbose` and
-      #    `--quiet` flags for managing the logger level
+      # *  {Toys::StandardMiddleware::AddVerbosityFlags} adding the `--verbose`
+      #    and `--quiet` flags for managing the logger level
       #
       # @return [Array]
       #
@@ -322,6 +332,35 @@ module Toys
         ]
       end
 
+      ##
+      # Returns a default ModuleLookup for mixins that points at the
+      # StandardMixins module.
+      #
+      # @return [Toys::Utils::ModuleLookup]
+      #
+      def default_mixin_lookup
+        Utils::ModuleLookup.new.add_path("toys/standard_mixins")
+      end
+
+      ##
+      # Returns a default ModuleLookup for middleware that points at the
+      # StandardMiddleware module.
+      #
+      # @return [Toys::Utils::ModuleLookup]
+      #
+      def default_middleware_lookup
+        Utils::ModuleLookup.new.add_path("toys/standard_middleware")
+      end
+
+      ##
+      # Returns a default empty ModuleLookup for templates.
+      #
+      # @return [Toys::Utils::ModuleLookup]
+      #
+      def default_template_lookup
+        Utils::ModuleLookup.new
+      end
+
       ##
       # Returns a default logger that logs to `$stderr`.
       #

data/lib/toys/core_version.rb

@@ -32,5 +32,5 @@ module Toys
   # Current version of Toys core
   # @return [String]
   #
-  CORE_VERSION = "0.3.7.1".freeze
+  CORE_VERSION = "0.3.8".freeze
 end

data/lib/toys/definition/arg.rb

@@ -29,8 +29,6 @@
 
 require "optparse"
 
-require "toys/utils/wrappable_string"
-
 module Toys
   module Definition
     ##

data/lib/toys/definition/flag.rb

@@ -27,10 +27,6 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "optparse"
-
-require "toys/utils/wrappable_string"
-
 module Toys
   module Definition
     ##
@@ -55,6 +51,8 @@ module Toys
           setup(str, [$1], $1, "--", nil, nil, nil, nil)
         when /^(--\w[\?\w-]*)([= ])\[(\w+)\]$/
           setup(str, [$1], $1, "--", :value, :optional, $2, $3)
+        when /^(--\w[\?\w-]*)\[([= ])(\w+)\]$/
+          setup(str, [$1], $1, "--", :value, :optional, $2, $3)
         when /^(--\w[\?\w-]*)([= ])(\w+)$/
           setup(str, [$1], $1, "--", :value, :required, $2, $3)
         else

data/lib/toys/definition/tool.rb

@@ -29,8 +29,6 @@
 
 require "optparse"
 
-require "toys/utils/wrappable_string"
-
 module Toys
   module Definition
     ##
@@ -71,12 +69,12 @@ module Toys
         @full_name = full_name.dup.freeze
         @tool_class = DSL::Tool.new_class(@full_name, priority, loader)
         @priority = priority
-        @middleware_stack = Middleware.resolve_stack(middleware_stack)
+        @middleware_stack = middleware_stack
 
         @source_path = nil
         @definition_finished = false
 
-        @desc = Toys::Utils::WrappableString.new("")
+        @desc = Utils::WrappableString.new("")
         @long_desc = []
 
         @default_data = {}
@@ -84,7 +82,7 @@ module Toys
         OPTPARSER_ACCEPTORS.each { |a| @acceptors[a] = a }
         @used_flags = []
 
-        @helpers = {}
+        @mixins = {}
 
         @flag_definitions = []
         @required_arg_definitions = []
@@ -253,7 +251,7 @@ module Toys
 
       ##
       # Returns a list of all custom acceptors used by this tool.
-      # @return [Array<Toys::Tool::Acceptor>]
+      # @return [Array<Toys::Definition::Acceptor>]
       #
       def custom_acceptors
         result = []
@@ -267,21 +265,21 @@ module Toys
       end
 
       ##
-      # Get the named helper from this tool or its ancestors.
+      # Get the named mixin from this tool or its ancestors.
       #
-      # @param [String] name The helper name
-      # @return [Module,nil] The helper module, or `nil` if not found.
+      # @param [String] name The mixin name
+      # @return [Module,nil] The mixin module, or `nil` if not found.
       #
-      def resolve_helper(name)
-        @helpers.fetch(name.to_s) { |k| @parent ? @parent.resolve_helper(k) : nil }
+      def resolve_mixin(name)
+        @mixins.fetch(name.to_s) { |k| @parent ? @parent.resolve_mixin(k) : nil }
       end
 
       ##
-      # Include the given helper in the tool class.
+      # Include the given mixin in the tool class.
       #
-      # @param [String,Symbol,Module] name The helper name or module
+      # @param [String,Symbol,Module] name The mixin name or module
       #
-      def include_helper(name)
+      def include_mixin(name)
         tool_class.include(name)
         self
       end
@@ -334,7 +332,7 @@ module Toys
       # Add an acceptor to the tool. This acceptor may be refereneced by name
       # when adding a flag or an arg.
       #
-      # @param [Toys::Tool::Acceptor] acceptor The acceptor to add.
+      # @param [Toys::Definition::Acceptor] acceptor The acceptor to add.
       #
       def add_acceptor(acceptor)
         @acceptors[acceptor.name] = acceptor
@@ -342,13 +340,13 @@ module Toys
       end
 
       ##
-      # Add a named helper module to this tool.
+      # Add a named mixin module to this tool.
       #
-      # @param [String] name The name of the helper.
-      # @param [Module] helper_module The helper module.
+      # @param [String] name The name of the mixin.
+      # @param [Module] mixin_module The mixin module.
       #
-      def add_helper(name, helper_module)
-        @helpers[name.to_s] = helper_module
+      def add_mixin(name, mixin_module)
+        @mixins[name.to_s] = mixin_module
         self
       end
 
@@ -376,11 +374,12 @@ module Toys
       #     requested that is already in use or marked as disabled. Default is
       #     true.
       # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-      #     description for the flag. See {Toys::Tool#desc=} for a description of
-      #     allowed formats. Defaults to the empty string.
+      #     description for the flag. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to the empty string.
       # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-      #     Long description for the flag. See {Toys::Tool#long_desc=} for a
-      #     description of allowed formats. Defaults to the empty array.
+      #     Long description for the flag. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
       #
       def add_flag(key, flags = [],
                    accept: nil, default: nil, handler: nil,
@@ -428,11 +427,12 @@ module Toys
       # @param [String] display_name A name to use for display (in help text and
       #     error reports). Defaults to the key in upper case.
       # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-      #     description for the flag. See {Toys::Tool#desc=} for a description of
-      #     allowed formats. Defaults to the empty string.
+      #     description for the arg. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to the empty string.
       # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-      #     Long description for the flag. See {Toys::Tool#long_desc=} for a
-      #     description of allowed formats. Defaults to the empty array.
+      #     Long description for the arg. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
       #
       def add_required_arg(key, accept: nil, display_name: nil, desc: nil, long_desc: nil)
         check_definition_state
@@ -460,11 +460,12 @@ module Toys
       # @param [String] display_name A name to use for display (in help text and
       #     error reports). Defaults to the key in upper case.
       # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-      #     description for the flag. See {Toys::Tool#desc=} for a description of
-      #     allowed formats. Defaults to the empty string.
+      #     description for the arg. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to the empty string.
       # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-      #     Long description for the flag. See {Toys::Tool#long_desc=} for a
-      #     description of allowed formats. Defaults to the empty array.
+      #     Long description for the arg. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
       #
       def add_optional_arg(key, default: nil, accept: nil, display_name: nil,
                            desc: nil, long_desc: nil)
@@ -494,11 +495,12 @@ module Toys
       # @param [String] display_name A name to use for display (in help text and
       #     error reports). Defaults to the key in upper case.
       # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-      #     description for the flag. See {Toys::Tool#desc=} for a description of
-      #     allowed formats. Defaults to the empty string.
+      #     description for the arg. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to the empty string.
       # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-      #     Long description for the flag. See {Toys::Tool#long_desc=} for a
-      #     description of allowed formats. Defaults to the empty array.
+      #     Long description for the arg. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
       #
       def set_remaining_args(key, default: [], accept: nil, display_name: nil,
                              desc: nil, long_desc: nil)

data/lib/toys/dsl/arg.rb

@@ -33,6 +33,10 @@ module Toys
     # DSL for an arg definition block. Lets you set arg attributes in a block
     # instead of a long series of keyword arguments.
     #
+    # These directives are available inside a block passed to
+    # {Toys::DSL::Tool#required_arg}, {Toys::DSL::Tool#optional_arg}, or
+    # {Toys::DSL::Tool#remaining_args}.
+    #
     class Arg
       ## @private
       def initialize(accept, default, display_name, desc, long_desc)