toys-core 0.11.5 → 0.13.0

data/lib/toys/compat.rb

@@ -5,28 +5,44 @@ require "rbconfig"
 module Toys
   ##
   # Compatibility wrappers for older Ruby versions.
+  #
   # @private
   #
   module Compat
     parts = ::RUBY_VERSION.split(".")
     ruby_version = parts[0].to_i * 10000 + parts[1].to_i * 100 + parts[2].to_i
 
+    ##
     # @private
+    #
     def self.jruby?
-      ::RUBY_PLATFORM == "java"
+      ::RUBY_ENGINE == "jruby"
+    end
+
+    ##
+    # @private
+    #
+    def self.truffleruby?
+      ::RUBY_ENGINE == "truffleruby"
     end
 
+    ##
     # @private
+    #
     def self.windows?
       ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
     end
 
+    ##
     # @private
+    #
     def self.allow_fork?
-      !jruby? && !windows?
+      !jruby? && !truffleruby? && !windows?
     end
 
+    ##
     # @private
+    #
     def self.supports_suggestions?
       unless defined?(@supports_suggestions)
         begin
@@ -44,7 +60,9 @@ module Toys
       @supports_suggestions
     end
 
+    ##
     # @private
+    #
     def self.suggestions(word, list)
       if supports_suggestions?
         ::DidYouMean::SpellChecker.new(dictionary: list).correct(word)
@@ -53,50 +71,55 @@ module Toys
       end
     end
 
-    # In Ruby < 2.4, some objects such as nil cannot be cloned.
-    if ruby_version >= 20400
+    # The :base argument to Dir.glob requires Ruby 2.5 or later.
+    if ruby_version >= 20500
+      ##
       # @private
-      def self.merge_clones(hash, orig)
-        orig.each { |k, v| hash[k] = v.clone }
-        hash
+      #
+      def self.glob_in_dir(glob, dir)
+        ::Dir.glob(glob, base: dir)
       end
     else
+      ##
       # @private
-      def self.merge_clones(hash, orig)
-        orig.each do |k, v|
-          hash[k] =
-            begin
-              v.clone
-            rescue ::TypeError
-              v
-            end
-        end
-        hash
+      #
+      def self.glob_in_dir(glob, dir)
+        ::Dir.chdir(dir) { ::Dir.glob(glob) }
       end
     end
 
-    # The :base argument to Dir.glob requires Ruby 2.5 or later.
+    # Dir.children requires Ruby 2.5 or later.
     if ruby_version >= 20500
+      ##
       # @private
-      def self.glob_in_dir(glob, dir)
-        ::Dir.glob(glob, base: dir)
+      #
+      def self.dir_children(dir)
+        ::Dir.children(dir)
       end
     else
+      ##
       # @private
-      def self.glob_in_dir(glob, dir)
-        ::Dir.chdir(dir) { ::Dir.glob(glob) }
+      #
+      def self.dir_children(dir)
+        ::Dir.entries(dir) - [".", ".."]
       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
+    # This also hits TruffleRuby
+    # (see https://github.com/oracle/truffleruby/issues/2567)
+    if ruby_version >= 20700 && !truffleruby?
+      ##
       # @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 }
@@ -106,5 +129,30 @@ module Toys
         end
       end
     end
+
+    # File.absolute_path? requires Ruby 2.7 or later. For earlier Rubies, use
+    # an ad-hoc mechanism.
+    if ruby_version >= 20700
+      ##
+      # @private
+      #
+      def self.absolute_path?(path)
+        ::File.absolute_path?(path)
+      end
+    elsif ::Dir.getwd =~ /^[a-zA-Z]:/
+      ##
+      # @private
+      #
+      def self.absolute_path?(path)
+        /^[a-zA-Z]:/.match?(path)
+      end
+    else
+      ##
+      # @private
+      #
+      def self.absolute_path?(path)
+        path.start_with?("/")
+      end
+    end
   end
 end

data/lib/toys/completion.rb

@@ -88,7 +88,7 @@ module Toys
 
       ##
       # The tool being invoked, which should control the completion.
-      # @return [Toys::Tool]
+      # @return [Toys::ToolDefinition]
       #
       def tool
         lookup_tool
@@ -116,7 +116,9 @@ module Toys
         @arg_parser ||= ArgParser.new(@cli, @tool).parse(@args)
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def inspect
         "<Toys::Completion::Context previous=#{previous_words.inspect}" \
           " prefix=#{fragment_prefix.inspect} fragment=#{fragment.inspect}>"
@@ -175,17 +177,23 @@ module Toys
         !@partial
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def eql?(other)
         other.is_a?(Candidate) && other.string.eql?(string) && other.partial? == @partial
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def <=>(other)
         string <=> other.string
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def hash
         string.hash ^ (partial? ? 1 : 0)
       end
@@ -236,6 +244,7 @@ module Toys
       #     prefix. Defaults to requiring the prefix be empty.
       #
       def initialize(cwd: nil, omit_files: false, omit_directories: false, prefix_constraint: "")
+        super()
         @cwd = cwd || ::Dir.pwd
         @include_files = !omit_files
         @include_directories = !omit_directories
@@ -328,6 +337,7 @@ module Toys
       #     prefix. Defaults to requiring the prefix be empty.
       #
       def initialize(values, prefix_constraint: "")
+        super()
         @values = values.flatten.map { |v| Candidate.new(v) }.sort
         @prefix_constraint = prefix_constraint
       end
@@ -424,7 +434,9 @@ module Toys
       end
     end
 
-    ## @private
+    ##
+    # @private
+    #
     def self.scalarize_spec(spec, options, block)
       spec ||= block
       if options.empty?

data/lib/toys/context.rb

@@ -33,7 +33,7 @@ module Toys
     # This module is mixed into the runtime context. This means you can
     # reference any of these constants directly from your run method.
     #
-    # ## Example
+    # ### Example
     #
     #     tool "my-name" do
     #       def run
@@ -78,7 +78,7 @@ module Toys
       LOGGER = ::Object.new.freeze
 
       ##
-      # Context key for the {Toys::Tool} object being executed.
+      # Context key for the {Toys::ToolDefinition} object being executed.
       # @return [Object]
       #
       TOOL = ::Object.new.freeze
@@ -133,19 +133,6 @@ module Toys
       VERBOSITY = ::Object.new.freeze
     end
 
-    ##
-    # Create a Context object. Applications generally will not need to create
-    # these objects directly; they are created by the tool when it is preparing
-    # for execution.
-    #
-    # @private
-    #
-    # @param data [Hash]
-    #
-    def initialize(data)
-      @__data = data
-    end
-
     ##
     # The raw arguments passed to the tool, as an array of strings.
     # This does not include the tool name itself.
@@ -335,5 +322,27 @@ module Toys
     def self.exit(code = 0)
       throw :result, code
     end
+
+    ##
+    # Create a Context object. Applications generally will not need to create
+    # these objects directly; they are created by the tool when it is preparing
+    # for execution.
+    #
+    # @param data [Hash]
+    #
+    # @private
+    #
+    def initialize(data)
+      @__data = data
+    end
+
+    ##
+    # @private
+    #
+    def inspect
+      name = Array(@__data[Key::TOOL_NAME]).join(" ")
+      id = object_id.to_s(16)
+      "#<Toys::Context id=0x#{id} #{name}>"
+    end
   end
 end

data/lib/toys/core.rb

@@ -9,9 +9,13 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.11.5"
+    VERSION = "0.13.0"
   end
 
-  ## @private deprecated
+  ##
+  # Deprecated
+  #
+  # @private
+  #
   CORE_VERSION = Core::VERSION
 end

data/lib/toys/dsl/base.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+##
+# Create a base class for defining a tool with a given name.
+#
+# This method returns a base class for defining a tool with a given name.
+# This is useful if the naming behavior of {Toys::Tool} is not adequate for
+# your tool.
+#
+# ### Example
+#
+#     class FooBar < Toys.Tool("Foo_Bar")
+#       desc "This is a tool called Foo_Bar"
+#
+#       def run
+#         puts "Foo_Bar called"
+#       end
+#     end
+#
+# @param name [String] Name of the tool. Defaults to a name inferred from the
+#     class name. (See {Toys::Tool}.)
+# @param base [Class] Use this tool class as the base class, and inherit helper
+#     methods from it.
+# @param args [String,Class] Any string-valued positional argument is
+#     interpreted as the name. Any class-valued positional argument is
+#     interpreted as the base class.
+#
+def Toys.Tool(*args, name: nil, base: nil) # rubocop:disable Naming/MethodName
+  args.each do |arg|
+    case arg
+    when ::Class
+      raise ::ArgumentError, "Both base keyword argument and class-valud argument received" if base
+      base = arg
+    when ::String, ::Symbol
+      raise ::ArgumentError, "Both name keyword argument and string-valud argument received" if name
+      name = arg
+    else
+      raise ::ArgumentError, "Unrecognized argument: #{arg}"
+    end
+  end
+  if base && !base.ancestors.include?(::Toys::Context)
+    raise ::ArgumentError, "Base class must itself be a tool"
+  end
+  return base || ::Toys::Tool if name.nil?
+  ::Class.new(base || ::Toys::Context) do
+    base_class = self
+    define_singleton_method(:inherited) do |tool_class|
+      ::Toys::DSL::Internal.configure_class(tool_class, base_class == self ? name.to_s : nil)
+      super(tool_class)
+      ::Toys::DSL::Internal.setup_class_dsl(tool_class)
+    end
+  end
+end
+
+module Toys
+  ##
+  # Base class for defining tools
+  #
+  # This base class provides an alternative to the {Toys::DSL::Tool#tool}
+  # directive for defining tools in the Toys DSL. Creating a subclass of
+  # `Toys::Tool` will create a tool whose name is the "kebab-case" of the class
+  # name. Subclasses can be created only in the context of a tool configuration
+  # DSL. Furthermore, a class-defined tool can be created only at the top level
+  # of a configuration file, or within another class-defined tool. It cannot
+  # be a subtool of a tool block.
+  #
+  # ### Example
+  #
+  #     class FooBar < Toys::Tool
+  #       desc "This is a tool called foo-bar"
+  #
+  #       def run
+  #         puts "foo-bar called"
+  #       end
+  #     end
+  #
+  class Tool < Context
+    ##
+    # @private
+    #
+    def self.inherited(tool_class)
+      DSL::Internal.configure_class(tool_class)
+      super
+      DSL::Internal.setup_class_dsl(tool_class)
+    end
+  end
+end

data/lib/toys/dsl/flag.rb

@@ -9,7 +9,7 @@ module Toys
     # These directives are available inside a block passed to
     # {Toys::DSL::Tool#flag}.
     #
-    # ## Example
+    # ### Example
     #
     #     tool "mytool" do
     #       flag :value do
@@ -22,22 +22,6 @@ module Toys
     #     end
     #
     class Flag
-      ## @private
-      def initialize(flags, acceptor, default, handler, flag_completion, value_completion,
-                     report_collisions, group, desc, long_desc, display_name)
-        @flags = flags
-        @default = default
-        @handler = handler
-        @report_collisions = report_collisions
-        @group = group
-        @desc = desc
-        @long_desc = long_desc || []
-        @display_name = display_name
-        accept(acceptor)
-        complete_flags(flag_completion, **{})
-        complete_values(value_completion, **{})
-      end
-
       ##
       # Add flags in OptionParser format. This may be called multiple times,
       # and the results are cumulative.
@@ -212,7 +196,7 @@ module Toys
       #     across the strings in the array. In this case, whitespace is not
       #     compacted.
       #
-      # ## Examples
+      # ### Examples
       #
       # If you pass in a sentence as a simple string, it may be word wrapped
       # when displayed:
@@ -243,7 +227,7 @@ module Toys
       # word-wrapped when displayed. To insert a blank line, include an empty
       # string as one of the descriptions.
       #
-      # ## Example
+      # ### Example
       #
       #     long_desc "This initial paragraph might get word wrapped.",
       #               "This next paragraph is followed by a blank line.",
@@ -284,7 +268,29 @@ module Toys
         self
       end
 
-      ## @private
+      ##
+      # Called only from DSL::Tool
+      #
+      # @private
+      #
+      def initialize(flags, acceptor, default, handler, flag_completion, value_completion,
+                     report_collisions, group, desc, long_desc, display_name)
+        @flags = flags
+        @default = default
+        @handler = handler
+        @report_collisions = report_collisions
+        @group = group
+        @desc = desc
+        @long_desc = long_desc || []
+        @display_name = display_name
+        accept(acceptor)
+        complete_flags(flag_completion, **{})
+        complete_values(value_completion, **{})
+      end
+
+      ##
+      # @private
+      #
       def _add_to(tool, key)
         tool.add_flag(key, @flags,
                       accept: @acceptor, default: @default, handler: @handler,

data/lib/toys/dsl/flag_group.rb

@@ -10,7 +10,7 @@ module Toys
     # {Toys::DSL::Tool#at_most_one}, {Toys::DSL::Tool#at_least_one}, or
     # {Toys::DSL::Tool#exactly_one}.
     #
-    # ## Example
+    # ### Example
     #
     #     tool "login" do
     #       all_required do
@@ -22,13 +22,6 @@ module Toys
     #     end
     #
     class FlagGroup
-      ## @private
-      def initialize(tool_dsl, tool, flag_group)
-        @tool_dsl = tool_dsl
-        @tool = tool
-        @flag_group = flag_group
-      end
-
       ##
       # Add a flag to the current group. Each flag must specify a key which
       # the script may use to obtain the flag value from the context.
@@ -43,7 +36,7 @@ module Toys
       # set in a block passed to this method. If you provide a block, you can
       # use directives in {Toys::DSL::Flag} within the block.
       #
-      # ## Flag syntax
+      # ### Flag syntax
       #
       # The flags themselves should be provided in OptionParser form. Following
       # are examples of valid syntax.
@@ -98,7 +91,7 @@ module Toys
       #     or off. This effectively creates two flags, `--abc` which sets the
       #     value to `true`, and `--no-abc` which sets the falue to `false`.
       #
-      # ## Default flag syntax
+      # ### Default flag syntax
       #
       # If no flag syntax strings are provided, a default syntax will be
       # inferred based on the key and other options.
@@ -123,7 +116,7 @@ module Toys
       #     flag :number, accept: Integer
       #     flag :number, "--number=VAL", accept: Integer
       #
-      # ## More examples
+      # ### More examples
       #
       # A flag that sets its value to the number of times it appears on the
       # command line:
@@ -200,7 +193,7 @@ module Toys
                                  report_collisions, @flag_group, desc, long_desc, display_name)
         flag_dsl.instance_exec(flag_dsl, &block) if block
         flag_dsl._add_to(@tool, key)
-        DSL::Tool.maybe_add_getter(@tool_dsl, key)
+        DSL::Internal.maybe_add_getter(@tool_dsl, key)
         self
       end
 
@@ -221,7 +214,7 @@ module Toys
       #     across the strings in the array. In this case, whitespace is not
       #     compacted.
       #
-      # ## Examples
+      # ### Examples
       #
       # If you pass in a sentence as a simple string, it may be word wrapped
       # when displayed:
@@ -252,7 +245,7 @@ module Toys
       # word-wrapped when displayed. To insert a blank line, include an empty
       # string as one of the descriptions.
       #
-      # ## Example
+      # ### Example
       #
       #     long_desc "This initial paragraph might get word wrapped.",
       #               "This next paragraph is followed by a blank line.",
@@ -268,6 +261,17 @@ module Toys
         @flag_group.append_long_desc(long_desc)
         self
       end
+
+      ##
+      # Called only from DSL::Tool.
+      #
+      # @private
+      #
+      def initialize(tool_dsl, tool, flag_group)
+        @tool_dsl = tool_dsl
+        @tool = tool
+        @flag_group = flag_group
+      end
     end
   end
 end