toys-core 0.9.4 → 0.10.0

data/lib/toys/compat.rb

@@ -1,25 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
+require "rbconfig"
 
 module Toys
   ##
@@ -27,44 +8,51 @@ module Toys
   # @private
   #
   module Compat
-    ## @private
-    CURRENT_VERSION = ::Gem::Version.new(::RUBY_VERSION)
+    parts = ::RUBY_VERSION.split(".")
+    ruby_version = parts[0].to_i * 10000 + parts[1].to_i * 100 + parts[2].to_i
 
-    ## @private
+    # @private
     def self.jruby?
       ::RUBY_PLATFORM == "java"
     end
 
-    ## @private
+    # @private
     def self.allow_fork?
-      !jruby? && RbConfig::CONFIG["host_os"] !~ /mswin/
+      !jruby? && ::RbConfig::CONFIG["host_os"] !~ /mswin/
     end
 
-    ## @private
-    def self.check_minimum_version(version)
-      CURRENT_VERSION >= ::Gem::Version.new(version)
+    # @private
+    def self.supports_suggestions?
+      unless defined?(@supports_suggestions)
+        require "rubygems"
+        begin
+          require "did_you_mean"
+          @supports_suggestions = defined?(::DidYouMean::SpellChecker)
+        rescue ::LoadError
+          @supports_suggestions = false
+        end
+      end
+      @supports_suggestions
     end
 
-    if check_minimum_version("2.4.0")
-      ## @private
-      def self.suggestions(word, list)
+    # @private
+    def self.suggestions(word, list)
+      if supports_suggestions?
         ::DidYouMean::SpellChecker.new(dictionary: list).correct(word)
-      end
-    else
-      ## @private
-      def self.suggestions(_word, _list)
+      else
         []
       end
     end
 
-    if check_minimum_version("2.4.0")
-      ## @private
+    # In Ruby < 2.4, some objects such as nil cannot be cloned.
+    if ruby_version >= 20400
+      # @private
       def self.merge_clones(hash, orig)
         orig.each { |k, v| hash[k] = v.clone }
         hash
       end
     else
-      ## @private
+      # @private
       def self.merge_clones(hash, orig)
         orig.each do |k, v|
           hash[k] =
@@ -78,16 +66,36 @@ module Toys
       end
     end
 
-    if check_minimum_version("2.5.0")
-      ## @private
+    # The :base argument to Dir.glob requires Ruby 2.5 or later.
+    if ruby_version >= 20500
+      # @private
       def self.glob_in_dir(glob, dir)
         ::Dir.glob(glob, base: dir)
       end
     else
-      ## @private
+      # @private
       def self.glob_in_dir(glob, dir)
         ::Dir.chdir(dir) { ::Dir.glob(glob) }
       end
     end
+
+    # Due to a bug in Ruby < 2.7, passing an empty **kwargs splat to
+    # initialize will fail if there are no formal keyword args.
+    if ruby_version >= 20700
+      # @private
+      def self.instantiate(klass, args, kwargs, block)
+        klass.new(*args, **kwargs, &block)
+      end
+    else
+      # @private
+      def self.instantiate(klass, args, kwargs, block)
+        formals = klass.instance_method(:initialize).parameters
+        if kwargs.empty? && formals.all? { |arg| arg.first != :key && arg.first != :keyrest }
+          klass.new(*args, &block)
+        else
+          klass.new(*args, **kwargs, &block)
+        end
+      end
+    end
   end
 end

data/lib/toys/completion.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   ##
   # A Completion is a callable Proc that determines candidates for shell tab

data/lib/toys/context.rb

@@ -1,28 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
-require "logger"
-
 module Toys
   ##
   # This is the base class for tool execution. It represents `self` when your

data/lib/toys/core.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   ##
   # The core Toys classes.
@@ -30,7 +9,7 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.9.4"
+    VERSION = "0.10.0"
   end
 
   ## @private deprecated

data/lib/toys/dsl/flag.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   module DSL
     ##

data/lib/toys/dsl/flag_group.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   module DSL
     ##

data/lib/toys/dsl/positional_arg.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   module DSL
     ##

data/lib/toys/dsl/tool.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   module DSL
     ##
@@ -226,7 +205,8 @@ module Toys
       #
       def template(name, template_class = nil, &block)
         cur_tool = DSL::Tool.current_tool(self, false)
-        cur_tool&.add_template(name, template_class, &block)
+        return self if cur_tool.nil?
+        cur_tool.add_template(name, template_class, &block)
         self
       end
 
@@ -273,7 +253,8 @@ module Toys
       #
       def completion(name, spec = nil, **options, &block)
         cur_tool = DSL::Tool.current_tool(self, false)
-        cur_tool&.add_completion(name, spec, **options, &block)
+        return self if cur_tool.nil?
+        cur_tool.add_completion(name, spec, **options, &block)
         self
       end
 
@@ -322,11 +303,11 @@ module Toys
       # @return [self]
       #
       def tool(words, if_defined: :combine, delegate_to: nil, &block)
-        subtool_words = @__words
+        subtool_words = @__words.dup
         next_remaining = @__remaining_words
-        Array(words).each do |word|
+        @__loader.split_path(words).each do |word|
           word = word.to_s
-          subtool_words += [word]
+          subtool_words << word
           next_remaining = Loader.next_remaining_words(next_remaining, word)
         end
         subtool = @__loader.get_tool(subtool_words, @__priority)
@@ -338,10 +319,12 @@ module Toys
             subtool.reset_definition(@__loader)
           end
         end
-        subtool_class = subtool.tool_class
-        DSL::Tool.prepare(subtool_class, next_remaining, source_info) do
-          subtool_class.delegate_to(delegate_to) if delegate_to
-          subtool_class.class_eval(&block) if block
+        if delegate_to
+          delegator = proc { self.delegate_to(delegate_to) }
+          @__loader.load_block(source_info, delegator, subtool_words, next_remaining, @__priority)
+        end
+        if block
+          @__loader.load_block(source_info, block, subtool_words, next_remaining, @__priority)
         end
         self
       end
@@ -455,6 +438,7 @@ module Toys
       #
       def expand(template_class, *args, **kwargs)
         cur_tool = DSL::Tool.current_tool(self, false)
+        return self if cur_tool.nil?
         name = template_class.to_s
         if template_class.is_a?(::String)
           template_class = cur_tool.lookup_template(template_class)
@@ -464,15 +448,7 @@ module Toys
         if template_class.nil?
           raise ToolDefinitionError, "Template not found: #{name.inspect}"
         end
-        # Due to a bug in Ruby < 2.7, passing an empty **kwargs splat to
-        # initialize will fail if there are no formal keyword args.
-        formals = template_class.instance_method(:initialize).parameters
-        template =
-          if kwargs.empty? && formals.all? { |(type, _name)| type != :key && type != :keyrest }
-            template_class.new(*args)
-          else
-            template_class.new(*args, **kwargs)
-          end
+        template = Compat.instantiate(template_class, args, kwargs, nil)
         yield template if block_given?
         class_exec(template, &template_class.expansion)
         self
@@ -513,7 +489,8 @@ module Toys
       #
       def desc(str)
         cur_tool = DSL::Tool.current_tool(self, true)
-        cur_tool.desc = str if cur_tool
+        return self if cur_tool.nil?
+        cur_tool.desc = str
         self
       end
       alias short_desc desc
@@ -539,10 +516,27 @@ module Toys
       #     long_desc "This line is appended to the description."
       #
       # @param strs [Toys::WrappableString,String,Array<String>...]
+      # @param file [String] Optional. Read the description from the given file
+      #     provided relative to the current toys file. The file must be a
+      #     plain text file whose suffix is `.txt`.
+      # @param data [String] Optional. Read the description from the given data
+      #     file. The file must be a plain text file whose suffix is `.txt`.
       # @return [self]
       #
-      def long_desc(*strs)
-        DSL::Tool.current_tool(self, true)&.append_long_desc(strs)
+      def long_desc(*strs, file: nil, data: nil)
+        cur_tool = DSL::Tool.current_tool(self, true)
+        return self if cur_tool.nil?
+        if file
+          unless source_info.source_path
+            raise ::Toys::ToolDefinitionError,
+                  "Cannot set long_desc from a file because the tool is not defined in a file"
+          end
+          file = ::File.join(::File.dirname(source_info.source_path), file)
+        elsif data
+          file = source_info.find_data(data, type: :file)
+        end
+        strs += DSL::Tool.load_long_desc_file(file) if file
+        cur_tool.append_long_desc(strs)
         self
       end
 
@@ -1405,7 +1399,8 @@ module Toys
       #
       def on_interrupt(handler = nil, &block)
         cur_tool = DSL::Tool.current_tool(self, true)
-        cur_tool.interrupt_handler = handler || block unless cur_tool.nil?
+        return self if cur_tool.nil?
+        cur_tool.interrupt_handler = handler || block
         self
       end
 
@@ -1436,7 +1431,8 @@ module Toys
       #
       def on_usage_error(handler = nil, &block)
         cur_tool = DSL::Tool.current_tool(self, true)
-        cur_tool.usage_error_handler = handler || block unless cur_tool.nil?
+        return self if cur_tool.nil?
+        cur_tool.usage_error_handler = handler || block
         self
       end
 
@@ -1578,11 +1574,84 @@ module Toys
       #
       def set_context_directory(dir) # rubocop:disable Naming/AccessorMethodName
         cur_tool = DSL::Tool.current_tool(self, false)
-        return if cur_tool.nil?
+        return self if cur_tool.nil?
         cur_tool.custom_context_directory = dir
         self
       end
 
+      ##
+      # Applies the given block to all subtools, recursively. Effectively, the
+      # given block is run at the *end* of every tool block. This can be used,
+      # for example, to provide some shared configuration for all tools.
+      #
+      # The block is applied only to subtools defined *after* the block
+      # appears. Subtools defined before the block appears are not affected.
+      #
+      # ## Example
+      #
+      # It is common for tools to use the `:exec` mixin to invoke external
+      # programs. This example automatically includes the exec mixin in all
+      # subtools, recursively, so you do not have to repeat the `include`
+      # directive in every tool.
+      #
+      #     # .toys.rb
+      #
+      #     subtool_apply do
+      #       # Include the mixin only if the tool hasn't already done so
+      #       unless include?(:exec)
+      #         include :exec, exit_on_nonzero_status: true
+      #       end
+      #     end
+      #
+      #     tool "foo" do
+      #       def run
+      #         # This tool has access to methods defined by the :exec mixin
+      #         # because the above block is applied to the tool.
+      #         sh "echo hello"
+      #       end
+      #     end
+      #
+      def subtool_apply(&block)
+        cur_tool = DSL::Tool.current_tool(self, false)
+        return self if cur_tool.nil?
+        cur_tool.subtool_middleware_stack.add(:apply_config,
+                                              parent_source: source_info, &block)
+        self
+      end
+
+      ##
+      # Determines whether the current Toys version satisfies the given
+      # requirements.
+      #
+      # @return [Boolean] whether or not the requirements are satisfied
+      #
+      def toys_version?(*requirements)
+        require "rubygems"
+        version = ::Gem::Version.new(Core::VERSION)
+        requirement = ::Gem::Requirement.new(*requirements)
+        requirement.satisfied_by?(version)
+      end
+
+      ##
+      # Asserts that the current Toys version against the given requirements,
+      # raising an exception if not.
+      #
+      # @return [self]
+      #
+      # @raise [Toys::ToolDefinitionError] if the current Toys version does not
+      #     satisfy the requirements.
+      #
+      def toys_version!(*requirements)
+        require "rubygems"
+        version = ::Gem::Version.new(Core::VERSION)
+        requirement = ::Gem::Requirement.new(*requirements)
+        unless requirement.satisfied_by?(version)
+          raise Toys::ToolDefinitionError,
+                "Toys version requirements #{requirement} not satisfied by {version}"
+        end
+        self
+      end
+
       ## @private
       def self.new_class(words, priority, loader)
         tool_class = ::Class.new(::Toys::Context)
@@ -1599,7 +1668,7 @@ module Toys
       def self.current_tool(tool_class, activate)
         memoize_var = activate ? :@__active_tool : :@__cur_tool
         if tool_class.instance_variable_defined?(memoize_var)
-          cur_tool = tool_class.instance_variable_get(memoize_var)
+          tool_class.instance_variable_get(memoize_var)
         else
           loader = tool_class.instance_variable_get(:@__loader)
           words = tool_class.instance_variable_get(:@__words)
@@ -1610,13 +1679,12 @@ module Toys
             else
               loader.get_tool(words, priority)
             end
+          if cur_tool && activate
+            source = tool_class.instance_variable_get(:@__source).last
+            cur_tool.lock_source(source)
+          end
           tool_class.instance_variable_set(memoize_var, cur_tool)
         end
-        if cur_tool && activate
-          source = tool_class.instance_variable_get(:@__source).last
-          cur_tool.lock_source(source)
-        end
-        cur_tool
       end
 
       ## @private
@@ -1654,6 +1722,22 @@ module Toys
         end
         mod
       end
+
+      ## @private
+      def self.load_long_desc_file(path)
+        if ::File.extname(path) == ".txt"
+          begin
+            ::File.readlines(path).map do |line|
+              line = line.chomp
+              line =~ /^\s/ ? [line] : line
+            end
+          rescue ::SystemCallError => e
+            raise Toys::ToolDefinitionError, e.to_s
+          end
+        else
+          raise Toys::ToolDefinitionError, "Cannot load long desc from file type: #{path}"
+        end
+      end
     end
   end
 end