toys-core 0.11.5 → 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
@@ -1093,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