toys-core 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9ea4eb80e6cbef15a8fafda59f0150f53aeb3a1a196b4749b5abe357d8fc47c
-  data.tar.gz: 374d30463b4eb8388674c5764a3fbcc050986ae927f3b2cb576d671bf47b3bc5
+  metadata.gz: 125540448a7c5431f6c788058f7b5b02d0d089b28def144fa673b579bd2b1bff
+  data.tar.gz: 878c996695f10022f756b2a17459e556f29a06b1e96b8b9e2d636624e8bfc65c
 SHA512:
-  metadata.gz: 061e82b410a5640bf233bfed13f6ca15b08b16699c2c8ebee1bece2cb48a0e8af0afb5c96ad28fcbd1ab09b484a679c018a0ea26f40cedb8263fca75cf4fdba6
-  data.tar.gz: 123e78e35b94cb1b3e56107f379f9e63f3fe4b4151e3d790a6828457c208cbcbd5c8ac9f4ac111d0176499b4e728c600760833dc6159ad00548601d7c3837305
+  metadata.gz: 5a3e9c3fe05a4ced439a842c53c6c2cb73026417f5c6707a3a1ac1e8394a003e546d8aa50a73d94749ac79bd2720148ee86a18c53b60fe52a080a8368f133098
+  data.tar.gz: 98f82815c36fcca6b534248e98ab642762a513410f22467de12a819d32bd589d6e8a8ca1fd187b55bada01987021c9a3f8922ab0e8dec329cade1239db1f464c

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Release History
 
+### 0.9.0 / 2019-12-02
+
+Functional changes:
+
+* ADDED: The `delegate_to` directive causes the tool to delegate execution to another tool. This means it takes the same arguments and has the same execution behavior.
+* ADDED: The `delegate_to` argument to the `tool` directive causes the tool to delegate to another tool. (Note: the `alias_tool` directive is now just shorthand for creating a tool with a delegate, and as such is mildly deprecated.)
+* ADDED: The `current_tool` function can be called from the DSL to get the current `Toys::Tool` object.
+* ADDED: The `:e` option is now an alias for `:exit_on_nonzero_status`.
+* IMPROVED: `alias_tool` is now just shorthand for delegating. This means, aliases can now point to namespaces and will resolve subtools of their targets, and they now support tab completion and online help.
+* IMPROVED: This release of Toys is now compatible with Ruby 2.7.0-preview3. It fixes some Ruby 2.7 specific bugs, and sanitizes keyword argument usage to eliminate Ruby 2.7 warnings.
+* IMPROVED: JRuby is now supported for most operations. However, JRuby is generally not recommended because of JVM boot latency, lack of Kernel#fork support, and other issues.
+* FIXED: The the `tool` directive no longer crashes if not passed a block.
+
+Internal interface changes:
+
+* REMOVED: The `Toys::Alias` class has been removed, along with relevant functionality in `Toys::Loader` including `Toys::Loader#make_alias`. Use tool delegation instead.
+* CHANGED: Positional arguments to middleware specs must now be wrapped in an array.
+* CHANGED: The `Toys::ArgParser` constructor takes a `default_data` argument instead of `verbosity`.
+* CHANGED: Version constant is now `Toys::Core::VERSION`.
+* CHNAGED: The `flag` argument to `Toys::Flag::DefaultCompletion#initialize` is now a required keyword argument.
+* ADDED: `Toys::Tool#delegate_to` causes the tool to delegate to another tool.
+* ADDED: The `Toys::Context::Key::DELEGATED_FROM` key provides the delegating context, if any.
+
 ### 0.8.1 / 2019-11-19
 
 * FIXED: Listing subtools would crash if a broken alias was present.
@@ -12,6 +35,7 @@ This is a major update with significant new features and a bunch of fixes. It al
 Major changes and features:
 
 * CHANGED: Relicensed under the MIT License.
+* CHANGED: Requires Ruby 2.3 or later.
 * ADDED: Tab completion for bash. Added APIs and DSL constructs for tools to customize completions.
 * ADDED: The usage error screen displays suggestions when an argument is misspelled. (Requires Ruby 2.4 or later.)
 * ADDED: Tools can provide an interrupt handler and a custom usage error handler. Added appropriate APIs and DSL methods.

data/README.md

@@ -9,10 +9,10 @@ to write command line executables using the Toys DSL and the power of the Toys
 classes.
 
 For more detailed information about Toys-Core, see the
-[Toys-Core User's Guide](https://www.rubydoc.info/gems/toys-core/file/docs/guide.md).
+[Toys-Core User's Guide](https://dazuma.github.io/toys/gems/toys-core/latest/file.guide.html).
 For background information about Toys itself, see the
-[Toys README](https://www.rubydoc.info/gems/toys) and the
-[Toys User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
+[Toys README](https://dazuma.github.io/toys/gems/toys/latest) and the
+[Toys User Guide](https://dazuma.github.io/toys/gems/toys/latest/file.guide.html).
 
 ## Introductory tutorial
 
@@ -21,14 +21,12 @@ executable using Toys-Core.
 
 It assumes basic familiarity with Toys, so, if you have not done so, I
 recommend first walking through the tutorial in the
-[Toys README](https://www.rubydoc.info/gems/toys). It also assumes you are
-running a unix-like system such as Linux or macOS. Some commands might need to
-be modified if you're running on Windows.
+[Toys README](https://dazuma.github.io/toys/gems/toys/latest). It also assumes
+you are running a unix-like system such as Linux or macOS. Some commands might
+need to be modified if you're running on Windows.
 
 ### Install Toys
 
-Toys requires Ruby 2.3 or later. (JRuby is not currently supported.)
-
 Install the **toys-core** gem using:
 
     $ gem install toys-core
@@ -36,6 +34,11 @@ Install the **toys-core** gem using:
 You may also install the **toys** gem, which brings in **toys-core** as a
 dependency.
 
+Toys-Core requires Ruby 2.3 or later.
+
+Most parts of Toys-Core work on JRuby. However, JRuby is not recommended
+because of JVM boot latency, lack of support for Kernel#fork, and other issues.
+
 ### Create a new executable
 
 We'll start by creating an executable Ruby script. Using your favorite text
@@ -327,11 +330,11 @@ deep framework with many more features. Learn about how to write tools using
 the Toys DSL, including validating and interpreting command line arguments,
 using templates and mixins, controlling subprocesses, and producing nice styled
 output, in the
-[Toys User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
+[Toys User Guide](https://dazuma.github.io/toys/gems/toys/latest/file.guide.html).
 Learn more about how to customize and package your own executable, including
 handling errors, controlling log output, and providing your own mixins,
 templates, and middleware, in the
-[Toys-Core User Guide](https://www.rubydoc.info/gems/toys-core/file/docs/guide.md).
+[Toys-Core User Guide](https://dazuma.github.io/toys/gems/toys-core/latest/file.guide.html).
 
 ## License
 

data/docs/guide.md

@@ -14,7 +14,7 @@ line executables in Ruby using the Toys-Core framework.
 This guide assumes you are already familiar with Toys itself, including how to
 define tools by writing Toys files, parsing arguments and flags, and how tools
 are executed. For background, please see the
-[Toys User's Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
+[Toys User's Guide](https://dazuma.github.io/toys/gems/toys/latest/file.guide.html).
 
 **(This user's guide is still under construction.)**
 

data/lib/toys-core.rb

@@ -71,13 +71,12 @@ module Toys
 end
 
 require "toys/acceptor"
-require "toys/alias"
 require "toys/arg_parser"
 require "toys/cli"
 require "toys/compat"
 require "toys/completion"
 require "toys/context"
-require "toys/core_version"
+require "toys/core"
 require "toys/dsl/flag"
 require "toys/dsl/flag_group"
 require "toys/dsl/positional_arg"

data/lib/toys/acceptor.rb

@@ -512,36 +512,61 @@ module Toys
       #     default pass-through acceptor {Toys::Acceptor::DEFAULT}. Any type
       #     description you provide is ignored.
       #
-      # @param spec [Object] See the description for recognized values.
-      # @param type_desc [String] The type description for interpolating into
+      # Additional options:
+      #
+      #  *  `:type_desc` (String) The type description for interpolating into
       #     help text. Ignored if the spec indicates the default acceptor or a
       #     well-known acceptor.
+      #
+      # @param spec [Object] See the description for recognized values.
+      # @param options [Hash] Additional options to pass to the completion.
       # @param block [Proc] See the description for recognized forms.
       # @return [Toys::Acceptor::Base,Proc]
       #
-      def create(spec = nil, type_desc: nil, &block)
+      def create(spec = nil, **options, &block)
         well_known = lookup_well_known(spec)
         return well_known if well_known
+        if spec.is_a?(::Hash)
+          options = options.merge(spec)
+          spec = nil
+        end
+        spec ||= options.delete(:"")
+        internal_create(spec, options, block)
+      end
+
+      ## @private
+      def scalarize_spec(spec, options, block)
+        spec ||= block
+        if options.empty?
+          spec
+        elsif spec
+          options.merge({"": spec})
+        else
+          options
+        end
+      end
+
+      private
+
+      def internal_create(spec, options, block)
         case spec
         when Base
           spec
         when ::Regexp
-          Pattern.new(spec, type_desc: type_desc, &block)
+          Pattern.new(spec, **options, &block)
         when ::Array
-          Enum.new(spec, type_desc: type_desc)
+          Enum.new(spec, **options)
         when ::Proc
-          Simple.new(spec, type_desc: type_desc)
+          Simple.new(spec, **options)
         when ::Range
-          Range.new(spec, type_desc: type_desc, &block)
+          Range.new(spec, **options, &block)
         when nil, :default
-          block ? Simple.new(type_desc: type_desc, &block) : DEFAULT
+          block ? Simple.new(**options, &block) : DEFAULT
         else
           raise ToolDefinitionError, "Illegal acceptor spec: #{spec.inspect}"
         end
       end
 
-      private
-
       def standard_well_knowns
         @standard_well_knowns ||= {
           ::Object => DEFAULT,

data/lib/toys/arg_parser.rb

@@ -266,7 +266,7 @@ module Toys
       #     to the user. Optional.
       #
       def initialize(message = nil, value: nil, values: nil, suggestions: nil)
-        super(message || "Tool not found: \"#{Array(values).join(' ')}\".",
+        super(message || "Tool not found: \"#{Array(values).join(' ')}\"",
               value: value, suggestions: suggestions)
         @name = name
       end
@@ -291,14 +291,14 @@ module Toys
     #
     # @param cli [Toys::CLI] The CLI in effect.
     # @param tool [Toys::Tool] The tool defining the argument format.
-    # @param verbosity [Integer] The initial verbosity level (default is 0).
+    # @param default_data [Hash] Additional initial data (such as verbosity).
     # @param require_exact_flag_match [Boolean] Whether to require flag matches
     #     be exact (not partial). Default is false.
     #
-    def initialize(cli, tool, verbosity: 0, require_exact_flag_match: false)
+    def initialize(cli, tool, default_data: {}, require_exact_flag_match: false)
       @require_exact_flag_match = require_exact_flag_match
       @loader = cli.loader
-      @data = initial_data(cli, tool, verbosity)
+      @data = initial_data(cli, tool, default_data)
       @tool = tool
       @seen_flag_keys = []
       @errors = []
@@ -439,7 +439,7 @@ module Toys
     REMAINING_HANDLER = ->(val, prev) { prev.is_a?(::Array) ? prev << val : [val] }
     ARG_HANDLER = ->(val, _prev) { val }
 
-    def initial_data(cli, tool, verbosity)
+    def initial_data(cli, tool, default_data)
       data = {
         Context::Key::ARGS => nil,
         Context::Key::CLI => cli,
@@ -451,7 +451,7 @@ module Toys
         Context::Key::USAGE_ERRORS => [],
       }
       Compat.merge_clones(data, tool.default_data)
-      data[Context::Key::VERBOSITY] ||= verbosity
+      default_data.each { |k, v| data[k] ||= v }
       data
     end
 

data/lib/toys/cli.rb

@@ -224,7 +224,7 @@ module Toys
     # @yieldparam cli [Toys::CLI] If you pass a block, the new CLI is yielded
     #     to it so you can add paths and make other modifications.
     #
-    def child(_opts = {})
+    def child(**_opts)
       cli = CLI.new(executable_name: @executable_name,
                     config_dir_name: @config_dir_name,
                     config_file_name: @config_file_name,
@@ -392,7 +392,7 @@ module Toys
     #
     # @return [Integer] The resulting process status code (i.e. 0 for success).
     #
-    def run(*args, verbosity: 0)
+    def run(*args, verbosity: 0, delegated_from: nil)
       tool, remaining = ContextualError.capture("Error finding tool definition") do
         @loader.lookup(args.flatten)
       end
@@ -400,7 +400,11 @@ module Toys
         "Error during tool execution!", tool.source_info&.source_path,
         tool_name: tool.full_name, tool_args: remaining
       ) do
-        run_tool(tool, remaining, verbosity: verbosity)
+        default_data = {
+          Context::Key::VERBOSITY => verbosity,
+          Context::Key::DELEGATED_FROM => delegated_from,
+        }
+        run_tool(tool, remaining, default_data)
       end
     rescue ContextualError, ::Interrupt => e
       @error_handler.call(e).to_i
@@ -414,12 +418,12 @@ module Toys
     #
     # @param tool [Toys::Tool] The tool to run.
     # @param args [Array<String>] Command line arguments passed to the tool.
-    # @param verbosity [Integer] Initial verbosity. Default is 0.
+    # @param default_data [Hash] Initial tool context data.
     # @return [Integer] The resulting status code
     #
-    def run_tool(tool, args, verbosity: 0)
+    def run_tool(tool, args, default_data)
       arg_parser = ArgParser.new(self, tool,
-                                 verbosity: verbosity,
+                                 default_data: default_data,
                                  require_exact_flag_match: tool.exact_flag_match_required?)
       arg_parser.parse(args).finish
       context = tool.tool_class.new(arg_parser.data)

data/lib/toys/compat.rb

@@ -30,6 +30,14 @@ module Toys
     ## @private
     CURRENT_VERSION = ::Gem::Version.new(::RUBY_VERSION)
 
+    ## @private
+    IS_JRUBY = ::RUBY_PLATFORM == "java"
+
+    ## @private
+    def self.allow_fork?
+      !IS_JRUBY && RbConfig::CONFIG["host_os"] !~ /mswin/
+    end
+
     ## @private
     def self.check_minimum_version(version)
       CURRENT_VERSION >= ::Gem::Version.new(version)

data/lib/toys/completion.rb

@@ -70,7 +70,7 @@ module Toys
       # @return [Toys::Completion::Context]
       #
       def with(**delta_params)
-        Context.new(@params.merge(delta_params))
+        Context.new(**@params.merge(delta_params))
       end
 
       ##
@@ -208,7 +208,7 @@ module Toys
 
       ## @private
       def hash
-        string.hash
+        string.hash ^ (partial? ? 1 : 0)
       end
 
       ##
@@ -306,7 +306,7 @@ module Toys
         dir = ::File.expand_path(prefix, @cwd)
         return [] unless ::File.directory?(dir)
         prefix = nil if [".", ""].include?(prefix)
-        omits = [".", ".."]
+        omits = [".", "..", ""]
         children = Compat.glob_in_dir(name, dir).find_all do |child|
           !omits.include?(child)
         end
@@ -420,16 +420,22 @@ module Toys
     # @return [Toys::Completion::Base,Proc]
     #
     def self.create(spec = nil, **options, &block)
-      spec ||= block
+      if spec.is_a?(::Hash)
+        options = options.merge(spec)
+        spec = nil
+      end
+      spec ||= options.delete(:"") || block
       case spec
       when nil, :empty, :default
         EMPTY
       when ::Proc, Base
         spec
       when ::Array
-        Enum.new(spec, options)
+        Enum.new(spec, **options)
       when :file_system
-        FileSystem.new(options)
+        FileSystem.new(**options)
+      when ::Class
+        spec.new(**options)
       else
         if spec.respond_to?(:call)
           spec
@@ -438,5 +444,17 @@ module Toys
         end
       end
     end
+
+    ## @private
+    def self.scalarize_spec(spec, options, block)
+      spec ||= block
+      if options.empty?
+        spec
+      elsif spec
+        options.merge({"": spec})
+      else
+        options
+      end
+    end
   end
 end

data/lib/toys/context.rb

@@ -86,6 +86,14 @@ module Toys
       #
       CONTEXT_DIRECTORY = ::Object.new.freeze
 
+      ##
+      # Context key for the context from which the current call was delegated.
+      # The value is either another context object, or `nil` if the current
+      # call is not delegated.
+      # @return [Object]
+      #
+      DELEGATED_FROM = ::Object.new.freeze
+
       ##
       # Context key for the active `Logger` object.
       # @return [Object]

data/lib/toys/{core_version.rb → core.rb}

@@ -23,8 +23,16 @@
 
 module Toys
   ##
-  # Current version of Toys core.
-  # @return [String]
+  # The core Toys classes.
   #
-  CORE_VERSION = "0.8.1"
+  module Core
+    ##
+    # Current version of Toys core.
+    # @return [String]
+    #
+    VERSION = "0.9.0"
+  end
+
+  ## @private deprecated
+  CORE_VERSION = Core::VERSION
 end

data/lib/toys/dsl/flag.rb

@@ -55,8 +55,8 @@ module Toys
         @long_desc = long_desc || []
         @display_name = display_name
         accept(acceptor)
-        complete_flags(flag_completion)
-        complete_values(value_completion)
+        complete_flags(flag_completion, **{})
+        complete_values(value_completion, **{})
       end
 
       ##
@@ -135,9 +135,7 @@ module Toys
       # @return [self]
       #
       def accept(spec = nil, **options, &block)
-        @acceptor_spec = spec
-        @acceptor_options = options
-        @acceptor_block = block
+        @acceptor = Acceptor.scalarize_spec(spec, options, block)
         self
       end
 
@@ -186,9 +184,7 @@ module Toys
       # @return [self]
       #
       def complete_flags(spec = nil, **options, &block)
-        @flag_completion_spec = spec
-        @flag_completion_options = options
-        @flag_completion_block = block
+        @flag_completion = Completion.scalarize_spec(spec, options, block)
         self
       end
 
@@ -204,9 +200,7 @@ module Toys
       # @return [self]
       #
       def complete_values(spec = nil, **options, &block)
-        @value_completion_spec = spec
-        @value_completion_options = options
-        @value_completion_block = block
+        @value_completion = Completion.scalarize_spec(spec, options, block)
         self
       end
 
@@ -313,16 +307,9 @@ module Toys
 
       ## @private
       def _add_to(tool, key)
-        acceptor = tool.scalar_acceptor(@acceptor_spec, @acceptor_options, &@acceptor_block)
-        flag_completion = tool.scalar_completion(
-          @flag_completion_spec, @flag_completion_options, &@flag_completion_block
-        )
-        value_completion = tool.scalar_completion(
-          @value_completion_spec, @value_completion_options, &@value_completion_block
-        )
         tool.add_flag(key, @flags,
-                      accept: acceptor, default: @default, handler: @handler,
-                      complete_flags: flag_completion, complete_values: value_completion,
+                      accept: @acceptor, default: @default, handler: @handler,
+                      complete_flags: @flag_completion, complete_values: @value_completion,
                       report_collisions: @report_collisions, group: @group,
                       desc: @desc, long_desc: @long_desc, display_name: @display_name)
       end