toys-core 0.11.2 → 0.12.0

data/lib/toys/standard_mixins/git_cache.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Toys
+  module StandardMixins
+    ##
+    # A mixin that provides a git cache.
+    #
+    # This mixin provides an instance of {Toys::Utils::GitCache}, providing
+    # cached access to files from a remote git repo.
+    #
+    # Example usage:
+    #
+    #     include :git_cache
+    #
+    #     def run
+    #       # Pull and cache the HEAD commit from the Toys repo.
+    #       dir = git_cache.find("https://github.com/dazuma/toys.git")
+    #       # Display the contents of the readme file.
+    #       puts File.read(File.join(dir, "README.md"))
+    #     end
+    #
+    module GitCache
+      include Mixin
+
+      ##
+      # Context key for the GitCache object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      on_initialize do
+        require "toys/utils/git_cache"
+        self[KEY] = Utils::GitCache.new
+      end
+
+      ##
+      # Access the builtin GitCache.
+      #
+      # @return [Toys::Utils::GitCache]
+      #
+      def git_cache
+        self[KEY]
+      end
+    end
+  end
+end

data/lib/toys/standard_mixins/xdg.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Toys
+  module StandardMixins
+    ##
+    # A mixin that provides tools for working with the XDG Base Directory
+    # Specification.
+    #
+    # This mixin provides an instance of {Toys::Utils::XDG}, which includes
+    # utility methods that locate base directories and search paths for
+    # application state, configuration, caches, and other data, according to
+    # the [XDG Base Directory Spec version
+    # 0.8](https://specifications.freedesktop.org/basedir-spec/0.8/).
+    #
+    # Example usage:
+    #
+    #     include :xdg
+    #
+    #     def run
+    #       # Get config file paths, in order from most to least inportant
+    #       config_files = xdg.lookup_config("my-config.toml")
+    #       config_files.each { |path| read_my_config(path) }
+    #     end
+    #
+    module XDG
+      include Mixin
+
+      ##
+      # Context key for the XDG object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      on_initialize do
+        require "toys/utils/xdg"
+        self[KEY] = Utils::XDG.new
+      end
+
+      ##
+      # Access XDG utility methods.
+      #
+      # @return [Toys::Utils::XDG]
+      #
+      def xdg
+        self[KEY]
+      end
+    end
+
+    ##
+    # An alternate name for the {XDG} module
+    #
+    Xdg = XDG
+  end
+end

data/lib/toys/template.rb

@@ -10,7 +10,7 @@ module Toys
   # Templates will often support configuration; for example the minitest
   # template lets you configure the paths to the test files.
   #
-  # ## Usage
+  # ### Usage
   #
   # To create a template, define a class and include this module.
   # The class defines the "configuration" of the template. If your template
@@ -25,7 +25,7 @@ module Toys
   # this block are "inserted" into the user's configuration. The template
   # object is passed to the block so you have access to the template options.
   #
-  # ## Example
+  # ### Example
   #
   # This is a simple template that generates a "hello" tool. The tool simply
   # prints a `"Hello, #{name}!"` greeting. The name is set as a template

data/lib/toys/{tool.rb → tool_definition.rb}

@@ -4,22 +4,25 @@ require "set"
 
 module Toys
   ##
-  # A Tool describes a single command that can be invoked using Toys.
+  # A ToolDefinition describes a single command that can be invoked using Toys.
   # It has a name, a series of one or more words that you use to identify
   # the tool on the command line. It also has a set of formal flags and
   # command line arguments supported, and a block that gets run when the
   # tool is executed.
   #
-  class Tool
+  class ToolDefinition
     ##
     # Create a new tool.
     # Should be created only from the DSL via the Loader.
     # @private
     #
-    def initialize(loader, parent, full_name, priority, middleware_stack, middleware_lookup)
+    def initialize(parent, full_name, priority, source_root, middleware_stack, middleware_lookup,
+                   tool_class = nil)
       @parent = parent
+      @settings = Settings.new(parent: parent&.settings)
       @full_name = full_name.dup.freeze
       @priority = priority
+      @source_root = source_root
       @built_middleware = middleware_stack.build(middleware_lookup)
       @subtool_middleware_stack = middleware_stack.dup
 
@@ -28,7 +31,9 @@ module Toys
       @templates = {}
       @completions = {}
 
-      reset_definition(loader)
+      @precreated_class = tool_class
+
+      reset_definition
     end
 
     ##
@@ -37,8 +42,8 @@ module Toys
     # Should be called only from the DSL.
     # @private
     #
-    def reset_definition(loader)
-      @tool_class = DSL::Tool.new_class(@full_name, @priority, loader)
+    def reset_definition
+      @tool_class = @precreated_class || create_class
 
       @source_info = nil
       @definition_finished = false
@@ -72,6 +77,13 @@ module Toys
       @completion = DefaultCompletion.new
     end
 
+    ##
+    # Settings for this tool
+    #
+    # @return [Toys::Tool::Settings]
+    #
+    attr_reader :settings
+
     ##
     # The name of the tool as an array of strings.
     # This array may not be modified.
@@ -87,6 +99,13 @@ module Toys
     #
     attr_reader :priority
 
+    ##
+    # The root source info defining this tool, or nil if there is no source.
+    #
+    # @return [Toys::SourceInfo,nil]
+    #
+    attr_reader :source_root
+
     ##
     # The tool class.
     #
@@ -217,14 +236,14 @@ module Toys
     #
     # When reading, this may return an instance of one of the subclasses of
     # {Toys::Completion::Base}, or a Proc that duck-types it. Generally, this
-    # defaults to a {Toys::Tool::DefaultCompletion}, providing a standard
-    # algorithm that finds appropriate completions from flags, positional
-    # arguments, and subtools.
+    # defaults to a {Toys::ToolDefinition::DefaultCompletion}, providing a
+    # standard algorithm that finds appropriate completions from flags,
+    # positional arguments, and subtools.
     #
     # When setting, you may pass any of the following:
     #  *  `nil` or `:default` which sets the value to a default instance.
-    #  *  A Hash of options to pass to the {Toys::Tool::DefaultCompletion}
-    #     constructor.
+    #  *  A Hash of options to pass to the
+    #     {Toys::ToolDefinition::DefaultCompletion} constructor.
     #  *  Any other form recognized by {Toys::Completion.create}.
     #
     # @return [Toys::Completion::Base,Proc]
@@ -408,7 +427,7 @@ module Toys
     # Get the named acceptor from this tool or its ancestors.
     #
     # @param name [String] The acceptor name.
-    # @return [Tool::Acceptor::Base] The acceptor.
+    # @return [Toys::Acceptor::Base] The acceptor.
     # @return [nil] if no acceptor of the given name is found.
     #
     def lookup_acceptor(name)
@@ -441,7 +460,7 @@ module Toys
     # Get the named completion from this tool or its ancestors.
     #
     # @param name [String] The completion name
-    # @return [Tool::Completion::Base,Proc] The completion proc.
+    # @return [Toys::Completion::Base,Proc] The completion proc.
     # @return [nil] if no completion of the given name is found.
     #
     def lookup_completion(name)
@@ -451,11 +470,31 @@ module Toys
     ##
     # Include the given mixin in the tool class.
     #
-    # @param name [String,Symbol,Module] The mixin name or module
+    # The mixin must be given as a module. You can use {#lookup_mixin} or
+    # {Loader#resolve_standard_mixin} to resolve named mixins.
+    #
+    # @param mod [Module] The mixin module
     # @return [self]
     #
-    def include_mixin(name)
-      tool_class.include(name)
+    def include_mixin(mod, *args, **kwargs)
+      check_definition_state
+      if tool_class.included_modules.include?(mod)
+        raise ToolDefinitionError, "Mixin already included: #{mod.name}"
+      end
+      @includes_modules = true
+      if tool_class.respond_to?(:super_include)
+        tool_class.super_include(mod)
+      else
+        tool_class.include(mod)
+      end
+      if mod.respond_to?(:initializer)
+        callback = mod.initializer
+        add_initializer(callback, *args, **kwargs) if callback
+      end
+      if mod.respond_to?(:inclusion)
+        callback = mod.inclusion
+        tool_class.class_exec(*args, **kwargs, &callback) if callback
+      end
       self
     end
 
@@ -565,7 +604,7 @@ module Toys
     # completion.
     #
     # @param name [String] The name of the completion.
-    # @param completion [Proc,Tool::Completion::Base,Object] The completion to
+    # @param completion [Proc,Toys::Completion::Base,Object] The completion to
     #     add. You can provide either a completion object, or a spec understood
     #     by {Toys::Completion.create}.
     # @param options [Hash] Additional options to pass to the completion.
@@ -669,11 +708,12 @@ module Toys
     #
     # @param type [Symbol] The type of group. Default is `:optional`.
     # @param desc [String,Array<String>,Toys::WrappableString] Short
-    #     description for the group. See {Toys::Tool#desc=} for a description
-    #     of allowed formats. Defaults to `"Flags"`.
+    #     description for the group. See {Toys::ToolDefinition#desc} for a
+    #     description of allowed formats. Defaults to `"Flags"`.
     # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
-    #     Long description for the flag group. See {Toys::Tool#long_desc=} for
-    #     a description of allowed formats. Defaults to the empty array.
+    #     Long description for the flag group. See
+    #     {Toys::ToolDefinition#long_desc} for a description of allowed
+    #     formats. Defaults to the empty array.
     # @param name [String,Symbol,nil] The name of the group, or nil for no
     #     name.
     # @param report_collisions [Boolean] If `true`, raise an exception if a
@@ -741,11 +781,11 @@ module Toys
     #     this flag. You may provide a group name, a FlagGroup object, or
     #     `nil` which denotes the default group.
     # @param desc [String,Array<String>,Toys::WrappableString] 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::ToolDefinition#desc} for a
+    #     description of allowed formats. Defaults to the empty string.
     # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
-    #     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::ToolDefinition#long_desc}
+    #     for a description of allowed formats. Defaults to the empty array.
     # @param display_name [String] A display name for this flag, used in help
     #     text and error messages.
     # @return [self]
@@ -808,11 +848,11 @@ module Toys
     # @param display_name [String] A name to use for display (in help text and
     #     error reports). Defaults to the key in upper case.
     # @param desc [String,Array<String>,Toys::WrappableString] Short
-    #     description for the arg. See {Toys::Tool#desc=} for a description of
-    #     allowed formats. Defaults to the empty string.
+    #     description for the arg. See {Toys::ToolDefinition#desc} for a
+    #     description of allowed formats. Defaults to the empty string.
     # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
-    #     Long description for the arg. See {Toys::Tool#long_desc=} for a
-    #     description of allowed formats. Defaults to the empty array.
+    #     Long description for the arg. See {Toys::ToolDefinition#long_desc}
+    #     for a description of allowed formats. Defaults to the empty array.
     # @return [self]
     #
     def add_required_arg(key, accept: nil, complete: nil, display_name: nil,
@@ -846,11 +886,11 @@ module Toys
     # @param display_name [String] A name to use for display (in help text and
     #     error reports). Defaults to the key in upper case.
     # @param desc [String,Array<String>,Toys::WrappableString] Short
-    #     description for the arg. See {Toys::Tool#desc=} for a description of
-    #     allowed formats. Defaults to the empty string.
+    #     description for the arg. See {Toys::ToolDefinition#desc} for a
+    #     description of allowed formats. Defaults to the empty string.
     # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
-    #     Long description for the arg. See {Toys::Tool#long_desc=} for a
-    #     description of allowed formats. Defaults to the empty array.
+    #     Long description for the arg. See {Toys::ToolDefinition#long_desc}
+    #     for a description of allowed formats. Defaults to the empty array.
     # @return [self]
     #
     def add_optional_arg(key, default: nil, accept: nil, complete: nil,
@@ -884,11 +924,11 @@ module Toys
     # @param display_name [String] A name to use for display (in help text and
     #     error reports). Defaults to the key in upper case.
     # @param desc [String,Array<String>,Toys::WrappableString] Short
-    #     description for the arg. See {Toys::Tool#desc=} for a description of
-    #     allowed formats. Defaults to the empty string.
+    #     description for the arg. See {Toys::ToolDefinition#desc} for a
+    #     description of allowed formats. Defaults to the empty string.
     # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
-    #     Long description for the arg. See {Toys::Tool#long_desc=} for a
-    #     description of allowed formats. Defaults to the empty array.
+    #     Long description for the arg. See {Toys::ToolDefinition#long_desc}
+    #     for a description of allowed formats. Defaults to the empty array.
     # @return [self]
     #
     def set_remaining_args(key, default: [], accept: nil, complete: nil,
@@ -910,7 +950,9 @@ module Toys
     #
     def run_handler=(proc)
       check_definition_state(is_method: true)
-      @tool_class.to_run(&proc)
+      tool_class.class_eval do
+        define_method(:run, &proc)
+      end
     end
 
     ##
@@ -966,7 +1008,7 @@ module Toys
     end
 
     ##
-    # Set the completion strategy for this Tool.
+    # Set the completion strategy for this ToolDefinition.
     #
     # See {#completion} for details.
     #
@@ -1056,7 +1098,7 @@ module Toys
     def finish_definition(loader)
       unless @definition_finished
         ContextualError.capture("Error installing tool middleware!", tool_name: full_name) do
-          config_proc = proc {}
+          config_proc = proc { nil }
           @built_middleware.reverse_each do |middleware|
             config_proc = make_config_proc(middleware, loader, config_proc)
           end
@@ -1120,6 +1162,7 @@ module Toys
       def initialize(complete_subtools: true, include_hidden_subtools: false,
                      complete_args: true, complete_flags: true, complete_flag_values: true,
                      delegation_target: nil)
+        super()
         @complete_subtools = complete_subtools
         @include_hidden_subtools = include_hidden_subtools
         @complete_flags = complete_flags
@@ -1206,7 +1249,7 @@ module Toys
         return unless arg_parser.flags_allowed?
         active_flag_def = arg_parser.active_flag_def
         return if active_flag_def && active_flag_def.value_type == :required
-        match = /\A(--\w[\?\w-]*)=(.*)\z/.match(context.fragment_prefix)
+        match = /\A(--\w[?\w-]*)=(.*)\z/.match(context.fragment_prefix)
         return unless match
         flag_value_context = context.with(fragment_prefix: match[2])
         flag_def = flag_value_context.tool.resolve_flag(match[1]).unique_flag
@@ -1287,8 +1330,24 @@ module Toys
       end
     end
 
+    ##
+    # Tool-based settings class.
+    #
+    # The following settings are supported:
+    #
+    #  *  `propagate_helper_methods` (_Boolean_) - Whether subtools should
+    #     inherit methods defined by parent tools. Defaults to `false`.
+    #
+    class Settings < ::Toys::Settings
+      settings_attr :propagate_helper_methods, default: false
+    end
+
     private
 
+    def create_class
+      ::Class.new(@parent&.settings&.propagate_helper_methods ? @parent.tool_class : ::Toys::Context)
+    end
+
     def make_config_proc(middleware, loader, next_config)
       if middleware.respond_to?(:config)
         proc { middleware.config(self, loader, &next_config) }

data/lib/toys/utils/exec.rb

@@ -16,8 +16,6 @@ module Toys
     # This class is not loaded by default. Before using it directly, you should
     # `require "toys/utils/exec"`
     #
-    # ## Features
-    #
     # ### Controlling processes
     #
     # A process can be started in the *foreground* or the *background*. If you
@@ -138,7 +136,7 @@ module Toys
     #     end
     #     exec_service.exec(["git", "init"], result_callback: my_callback)
     #
-    # ## Configuration options
+    # ### Configuration options
     #
     # A variety of options can be used to control subprocesses. These can be
     # provided to any method that starts a subprocess. Youc an also set
@@ -250,13 +248,14 @@ module Toys
         exec_opts = Opts.new(@default_opts).add(opts)
         spawn_cmd =
           if cmd.is_a?(::Array)
-            if cmd.size == 1 && cmd.first.is_a?(::String)
-              [[cmd.first, exec_opts.config_opts[:argv0] || cmd.first]]
+            if cmd.size > 1
+              binary = canonical_binary_spec(cmd.first, exec_opts)
+              [binary] + cmd[1..-1].map(&:to_s)
             else
-              cmd
+              [canonical_binary_spec(Array(cmd.first), exec_opts)]
             end
           else
-            [cmd]
+            [cmd.to_s]
           end
         executor = Executor.new(exec_opts, spawn_cmd, block)
         executor.execute
@@ -796,7 +795,7 @@ module Toys
       #     {Result#success?} or {Result#error?} will return true, and
       #     {Result.exit_code} will return the numeric exit code.
       #  *  The process executed but was terminated by an uncaught signal.
-      #     {Result#signaled?} will return true, and {Result#term_signal} will
+      #     {Result#signaled?} will return true, and {Result#signal_code} will
       #     return the numeric signal code.
       #
       class Result
@@ -848,6 +847,8 @@ module Toys
         # The exception raised if a process couldn't be started.
         #
         # Exactly one of {#exception} and {#status} will be non-nil.
+        # Exactly one of {#exception}, {#exit_code}, or {#signal_code} will be
+        # non-nil.
         #
         # @return [Exception] The exception raised from process start.
         # @return [nil] if the process started successfully.
@@ -857,7 +858,7 @@ module Toys
         ##
         # The numeric status code for a process that exited normally,
         #
-        # Exactly one of {#exception}, {#exit_code}, and {#term_signal} will be
+        # Exactly one of {#exception}, {#exit_code}, or {#signal_code} will be
         # non-nil.
         #
         # @return [Integer] the numeric status code, if the process started
@@ -872,16 +873,17 @@ module Toys
         ##
         # The numeric signal code that caused process termination.
         #
-        # Exactly one of {#exception}, {#exit_code}, and {#term_signal} will be
+        # Exactly one of {#exception}, {#exit_code}, or {#signal_code} will be
         # non-nil.
         #
         # @return [Integer] The signal that caused the process to terminate.
         # @return [nil] if the process did not start successfully, or executed
         #     and exited with a normal exit code.
         #
-        def term_signal
+        def signal_code
           status&.termsig
         end
+        alias term_signal signal_code
 
         ##
         # Returns true if the subprocess failed to start, or false if the
@@ -900,7 +902,7 @@ module Toys
         # @return [Boolean]
         #
         def signaled?
-          !term_signal.nil?
+          !signal_code.nil?
         end
 
         ##
@@ -968,12 +970,19 @@ module Toys
         def log_command
           logger = @config_opts[:logger]
           if logger && @config_opts[:log_level] != false
-            cmd_str = @config_opts[:log_cmd]
-            cmd_str ||= @spawn_cmd.size == 1 ? @spawn_cmd.first : @spawn_cmd.inspect if @spawn_cmd
+            cmd_str = @config_opts[:log_cmd] || default_log_str(@spawn_cmd)
             logger.add(@config_opts[:log_level] || ::Logger::INFO, cmd_str) if cmd_str
           end
         end
 
+        def default_log_str(spawn_cmd)
+          return nil unless spawn_cmd
+          return spawn_cmd.first if spawn_cmd.size == 1 && spawn_cmd.first.is_a?(::String)
+          cmd_binary = spawn_cmd.first
+          cmd_binary = cmd_binary.first if cmd_binary.is_a?(::Array)
+          ([cmd_binary] + spawn_cmd[1..-1]).inspect
+        end
+
         def start_with_controller
           pid =
             begin
@@ -1082,9 +1091,10 @@ module Toys
 
         def interpret_out_array_within_fork(stream)
           if stream.first == :child
-            if stream[1] == :err
+            case stream[1]
+            when :err
               $stderr
-            elsif stream[1] == :out
+            when :out
               $stdout
             end
           else
@@ -1300,6 +1310,17 @@ module Toys
           end
         end
       end
+
+      private
+
+      def canonical_binary_spec(cmd, exec_opts)
+        config_argv0 = exec_opts.config_opts[:argv0]
+        return cmd.to_s if !config_argv0 && !cmd.is_a?(::Array)
+        cmd = Array(cmd)
+        actual_cmd = cmd.first
+        argv0 = cmd[1] || config_argv0 || actual_cmd
+        [actual_cmd.to_s, argv0.to_s]
+      end
     end
   end
 end