toys-core 0.11.5 → 0.13.0

data/lib/toys/standard_mixins/exec.rb

@@ -16,8 +16,6 @@ module Toys
     # This is a frontend for {Toys::Utils::Exec}. More information is
     # available in that class's documentation.
     #
-    # ## Features
-    #
     # ### Controlling processes
     #
     # A process can be started in the *foreground* or the *background*. If you
@@ -149,7 +147,7 @@ module Toys
     #
     #     include :exec, exit_on_nonzero_status: true
     #
-    # ## 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. You can also set
@@ -231,20 +229,6 @@ module Toys
       #
       KEY = ::Object.new.freeze
 
-      on_initialize do |**opts|
-        require "toys/utils/exec"
-        context = self
-        opts = Exec._setup_exec_opts(opts, context)
-        context[KEY] = Utils::Exec.new(**opts) do |k|
-          case k
-          when :logger
-            context[Context::Key::LOGGER]
-          when :cli
-            context[Context::Key::CLI]
-          end
-        end
-      end
-
       ##
       # Set default configuration options.
       #
@@ -267,7 +251,7 @@ module Toys
       # If the process is not set to run in the background, and a block is
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
-      # ## Examples
+      # ### Examples
       #
       # Run a command without a shell, and print the exit code (0 for success):
       #
@@ -303,11 +287,11 @@ module Toys
       # If the process is not set to run in the background, and a block is
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
-      # ## Example
+      # ### Example
       #
       # Execute a small script with warnings
       #
-      #     exec_ruby("-w", "-e", "(1..10).each { |i| puts i }")
+      #     exec_ruby(["-w", "-e", "(1..10).each { |i| puts i }"])
       #
       # @param args [String,Array<String>] The arguments to ruby.
       # @param opts [keywords] The command options. See the section on
@@ -337,7 +321,7 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
-      # ## Example
+      # ### Example
       #
       # Run a proc in a forked process.
       #
@@ -377,7 +361,7 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
-      # ## Example
+      # ### Example
       #
       # Run the "system update" tool and pass it an argument.
       #
@@ -399,6 +383,7 @@ module Toys
       def exec_tool(cmd, **opts, &block)
         func = Exec._make_tool_caller(cmd)
         opts = Exec._setup_exec_opts(opts, self)
+        opts = {log_cmd: "exec tool: #{cmd.inspect}"}.merge(opts)
         self[KEY].exec_proc(func, **opts, &block)
       end
 
@@ -424,7 +409,7 @@ module Toys
       # run a tool that uses a different bundle. It may also be necessary on
       # environments without "fork" (such as JRuby or Ruby on Windows).
       #
-      # ## Example
+      # ### Example
       #
       # Run the "system update" tool and pass it an argument.
       #
@@ -459,7 +444,7 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # ## Example
+      # ### Example
       #
       # Capture the output of an echo command
       #
@@ -490,7 +475,7 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # ## Example
+      # ### Example
       #
       # Capture the output of a ruby script.
       #
@@ -524,7 +509,7 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
-      # ## Example
+      # ### Example
       #
       # Run a proc in a forked process and capture its output:
       #
@@ -564,7 +549,7 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
-      # ## Example
+      # ### Example
       #
       # Run the "system version" tool and capture its output.
       #
@@ -612,7 +597,7 @@ module Toys
       # run a tool that uses a different bundle. It may also be necessary on
       # environments without "fork" (such as JRuby or Ruby on Windows).
       #
-      # ## Example
+      # ### Example
       #
       # Run the "system version" tool and capture its output.
       #
@@ -642,7 +627,7 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # ## Example
+      # ### Example
       #
       # Run a shell script
       #
@@ -677,13 +662,17 @@ module Toys
         0
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def self._make_tool_caller(cmd)
         cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
         proc { |config| ::Kernel.exit(config[:cli].run(*cmd)) }
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def self._setup_exec_opts(opts, context)
         count = 0
         result_callback = nil
@@ -706,7 +695,9 @@ module Toys
         opts
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def self._interpret_e(value, context)
         return nil unless value
         proc do |result|
@@ -720,7 +711,9 @@ module Toys
         end
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def self._interpret_result_callback(value, context)
         if value.is_a?(::Symbol)
           context.method(value)
@@ -733,7 +726,9 @@ module Toys
         end
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def self._setup_clean_process(cmd)
         raise ::ArgumentError, "Toys process is unknown" unless ::Toys.executable_path
         cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
@@ -748,6 +743,20 @@ module Toys
           yield(cmd)
         end
       end
+
+      on_initialize do |**opts|
+        require "toys/utils/exec"
+        context = self
+        opts = Exec._setup_exec_opts(opts, context)
+        context[KEY] = Utils::Exec.new(**opts) do |k|
+          case k
+          when :logger
+            context[Context::Key::LOGGER]
+          when :cli
+            context[Context::Key::CLI]
+          end
+        end
+      end
     end
   end
 end

data/lib/toys/standard_mixins/fileutils.rb

@@ -16,7 +16,9 @@ module Toys
     module Fileutils
       include Mixin
 
-      ## @private
+      ##
+      # @private
+      #
       def self.included(mod)
         mod.include(::FileUtils)
       end

data/lib/toys/standard_mixins/gems.rb

@@ -25,23 +25,6 @@ module Toys
     module Gems
       include Mixin
 
-      on_include do |**opts|
-        @__gems_opts = opts
-
-        ## @private
-        def self.gems
-          require "toys/utils/gems"
-          # rubocop:disable Naming/MemoizedInstanceVariableName
-          @__gems ||= Utils::Gems.new(**@__gems_opts)
-          # rubocop:enable Naming/MemoizedInstanceVariableName
-        end
-
-        ## @private
-        def self.gem(name, *requirements)
-          gems.activate(name, *requirements)
-        end
-      end
-
       ##
       # A tool-wide instance of {Toys::Utils::Gems}.
       # @return [Toys::Utils::Gems]
@@ -60,6 +43,27 @@ module Toys
       def gem(name, *requirements)
         self.class.gems.activate(name, *requirements)
       end
+
+      on_include do |**opts|
+        @__gems_opts = opts
+
+        ##
+        # @private
+        #
+        def self.gems
+          require "toys/utils/gems"
+          # rubocop:disable Naming/MemoizedInstanceVariableName
+          @__gems ||= Utils::Gems.new(**@__gems_opts)
+          # rubocop:enable Naming/MemoizedInstanceVariableName
+        end
+
+        ##
+        # @private
+        #
+        def self.gem(name, *requirements)
+          gems.activate(name, *requirements)
+        end
+      end
     end
   end
 end

data/lib/toys/standard_mixins/git_cache.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+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
+
+      ##
+      # Access the builtin GitCache.
+      #
+      # @return [Toys::Utils::GitCache]
+      #
+      def git_cache
+        self[KEY]
+      end
+
+      on_initialize do
+        require "toys/utils/git_cache"
+        self[KEY] = Utils::GitCache.new
+      end
+    end
+  end
+end

data/lib/toys/standard_mixins/highline.rb

@@ -36,14 +36,6 @@ module Toys
       #
       KEY = ::Object.new.freeze
 
-      on_initialize do |*args|
-        require "toys/utils/gems"
-        Toys::Utils::Gems.activate("highline", "~> 2.0")
-        require "highline"
-        self[KEY] = ::HighLine.new(*args)
-        self[KEY].use_color = $stdout.tty?
-      end
-
       ##
       # A tool-wide [HighLine](https://www.rubydoc.info/gems/highline/HighLine)
       # instance
@@ -136,6 +128,14 @@ module Toys
       def new_scope
         highline.new_scope
       end
+
+      on_initialize do |*args|
+        require "toys/utils/gems"
+        Toys::Utils::Gems.activate("highline", "~> 2.0")
+        require "highline"
+        self[KEY] = ::HighLine.new(*args)
+        self[KEY].use_color = $stdout.tty?
+      end
     end
   end
 end

data/lib/toys/standard_mixins/terminal.rb

@@ -35,11 +35,6 @@ module Toys
       #
       KEY = ::Object.new.freeze
 
-      on_initialize do |**opts|
-        require "toys/utils/terminal"
-        self[KEY] = Utils::Terminal.new(**opts)
-      end
-
       ##
       # A tool-wide terminal instance
       # @return [Toys::Utils::Terminal]
@@ -139,6 +134,11 @@ module Toys
                          frame_length: frame_length, frames: frames, style: style,
                          &block)
       end
+
+      on_initialize do |**opts|
+        require "toys/utils/terminal"
+        self[KEY] = Utils::Terminal.new(**opts)
+      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
+
+      ##
+      # Access XDG utility methods.
+      #
+      # @return [Toys::Utils::XDG]
+      #
+      def xdg
+        self[KEY]
+      end
+
+      on_initialize do
+        require "toys/utils/xdg"
+        self[KEY] = Utils::XDG.new
+      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
@@ -84,13 +84,6 @@ module Toys
       template_class
     end
 
-    ## @private
-    def self.included(mod)
-      return if mod.respond_to?(:on_expand)
-      mod.extend(ClassMethods)
-      mod.include(Context::Key)
-    end
-
     ##
     # Class methods that will be added to a template class.
     #
@@ -118,5 +111,14 @@ module Toys
       #
       attr_accessor :expansion
     end
+
+    ##
+    # @private
+    #
+    def self.included(mod)
+      return if mod.respond_to?(:on_expand)
+      mod.extend(ClassMethods)
+      mod.include(Context::Key)
+    end
   end
 end