toys-core 0.14.7 → 0.15.1

data/lib/toys/standard_mixins/exec.rb

@@ -3,10 +3,10 @@
 module Toys
   module StandardMixins
     ##
-    # A set of helper methods for invoking subcommands. Provides shortcuts for
-    # common cases such as invoking Ruby in a subprocess or capturing output
-    # in a string. Also provides an interface for controlling a spawned
-    # process's streams.
+    # The `:exec` mixin provides set of helper methods for executing processes
+    # and subcommands. It provides shortcuts for common cases such as invoking
+    # a Ruby script in a subprocess or capturing output in a string. It also
+    # provides an interface for controlling a spawned process's streams.
     #
     # You can make these methods available to your tool by including the
     # following directive in your tool configuration:
@@ -16,6 +16,25 @@ module Toys
     # This is a frontend for {Toys::Utils::Exec}. More information is
     # available in that class's documentation.
     #
+    # ### Mixin overview
+    #
+    # The mixin provides a number of methods for spawning processes. The most
+    # basic are {#exec} and {#exec_proc}. The {#exec} method spawns an
+    # operating system process specified by an executable and a set of
+    # arguments. The {#exec_proc} method takes a `Proc` and forks a Ruby
+    # process. Both of these can be heavily configured with stream handling,
+    # result handling, and numerous other options described below. The mixin
+    # also provides convenience methods for common cases such as spawning a
+    # Ruby process, spawning a shell script, or capturing output.
+    #
+    # The mixin also stores default configuration that it applies to processes
+    # it spawns. You can change these defaults by calling {#configure_exec}.
+    #
+    # Underlying the mixin is a service object of type {Toys::Utils::Exec}.
+    # Normally you would use the mixin methods to access this functionality,
+    # but you can also retrieve the service object itself by calling
+    # {Toys::Context#get} with the key {Toys::StandardMixins::Exec::KEY}.
+    #
     # ### Controlling processes
     #
     # A process can be started in the *foreground* or the *background*. If you
@@ -24,7 +43,7 @@ module Toys
     # If you start a background process, its streams will be redirected to null
     # by default, and control will be returned to you immediately.
     #
-    # When a process is running, you can control it using a
+    # While a process is running, you can control it using a
     # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
     # the process's input and output streams, send it signals, or wait for it
     # to complete.
@@ -44,7 +63,7 @@ module Toys
     # When running a process in the background, the controller is returned from
     # the method that starts the process:
     #
-    #     controller = exec_service.exec(["git", "init"], background: true)
+    #     controller = exec(["git", "init"], background: true)
     #
     # ### Stream handling
     #
@@ -464,7 +483,8 @@ module Toys
       #
       def exec_separate_tool(cmd, **opts, &block)
         Exec._setup_clean_process(cmd) do |clean_cmd|
-          exec(clean_cmd, **opts, &block)
+          opts = Exec._setup_exec_opts(opts, self)
+          self[KEY].exec(clean_cmd, **opts, &block)
         end
       end
 
@@ -650,7 +670,8 @@ module Toys
       #
       def capture_separate_tool(cmd, **opts, &block)
         Exec._setup_clean_process(cmd) do |clean_cmd|
-          capture(clean_cmd, **opts, &block)
+          opts = Exec._setup_exec_opts(opts, self)
+          self[KEY].capture(clean_cmd, **opts, &block)
         end
       end
 
@@ -809,6 +830,8 @@ module Toys
       end
 
       on_initialize do |**opts|
+        require "rbconfig"
+        require "shellwords"
         require "toys/utils/exec"
         context = self
         opts = Exec._setup_exec_opts(opts, context)

data/lib/toys/standard_mixins/fileutils.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "fileutils"
-
 module Toys
   module StandardMixins
     ##
@@ -20,6 +18,7 @@ module Toys
       # @private
       #
       def self.included(mod)
+        require "fileutils"
         mod.include(::FileUtils)
       end
     end

data/lib/toys/standard_mixins/gems.rb

@@ -10,11 +10,24 @@ module Toys
     # tool DSL itself, so you can also ensure a gem is present when defining a
     # tool.
     #
-    # You may make these methods available to your tool by including the
-    # following directive in your tool configuration:
+    # ### Usage
+    #
+    # Make these methods available to your tool by including this mixin in your
+    # tool:
     #
     #     include :gems
     #
+    # You can then call the mixin method {#gem} to ensure that a gem is
+    # installed and in the load path. For example:
+    #
+    #     tool "my_tool" do
+    #       include :gems
+    #       gem "nokogiri", "~> 1.15"
+    #       def run
+    #         # Do stuff with Nokogiri
+    #       end
+    #     end
+    #
     # If you pass additional options to the include directive, those are used
     # to initialize settings for the gem install process. For example:
     #
@@ -34,7 +47,8 @@ module Toys
       end
 
       ##
-      # Activate the given gem.
+      # Activate the given gem. If it is not present, attempt to install it (or
+      # inform the user to update the bundle).
       #
       # @param name [String] Name of the gem
       # @param requirements [String...] Version requirements
@@ -51,9 +65,11 @@ module Toys
         # @private
         #
         def self.gems
-          require "toys/utils/gems"
           # rubocop:disable Naming/MemoizedInstanceVariableName
-          @__gems ||= Utils::Gems.new(**@__gems_opts)
+          @__gems ||= begin
+            require "toys/utils/gems"
+            Utils::Gems.new(**@__gems_opts)
+          end
           # rubocop:enable Naming/MemoizedInstanceVariableName
         end
 

data/lib/toys/standard_mixins/highline.rb

@@ -49,89 +49,89 @@ module Toys
       # Calls [HighLine#agree](https://www.rubydoc.info/gems/highline/HighLine:agree)
       #
       def agree(*args, &block)
-        highline.agree(*args, &block)
+        self[KEY].agree(*args, &block)
       end
 
       ##
       # Calls [HighLine#ask](https://www.rubydoc.info/gems/highline/HighLine:ask)
       #
       def ask(*args, &block)
-        highline.ask(*args, &block)
+        self[KEY].ask(*args, &block)
       end
 
       ##
       # Calls [HighLine#choose](https://www.rubydoc.info/gems/highline/HighLine:choose)
       #
       def choose(*args, &block)
-        highline.choose(*args, &block)
+        self[KEY].choose(*args, &block)
       end
 
       ##
       # Calls [HighLine#list](https://www.rubydoc.info/gems/highline/HighLine:list)
       #
       def list(*args, &block)
-        highline.list(*args, &block)
+        self[KEY].list(*args, &block)
       end
 
       ##
       # Calls [HighLine#say](https://www.rubydoc.info/gems/highline/HighLine:say)
       #
       def say(*args, &block)
-        highline.say(*args, &block)
+        self[KEY].say(*args, &block)
       end
 
       ##
       # Calls [HighLine#indent](https://www.rubydoc.info/gems/highline/HighLine:indent)
       #
       def indent(*args, &block)
-        highline.indent(*args, &block)
+        self[KEY].indent(*args, &block)
       end
 
       ##
       # Calls [HighLine#newline](https://www.rubydoc.info/gems/highline/HighLine:newline)
       #
       def newline
-        highline.newline
+        self[KEY].newline
       end
 
       ##
       # Calls [HighLine#puts](https://www.rubydoc.info/gems/highline/HighLine:puts)
       #
       def puts(*args)
-        highline.puts(*args)
+        self[KEY].puts(*args)
       end
 
       ##
       # Calls [HighLine#color](https://www.rubydoc.info/gems/highline/HighLine:color)
       #
       def color(*args)
-        highline.color(*args)
+        self[KEY].color(*args)
       end
 
       ##
       # Calls [HighLine#color_code](https://www.rubydoc.info/gems/highline/HighLine:color_code)
       #
       def color_code(*args)
-        highline.color_code(*args)
+        self[KEY].color_code(*args)
       end
 
       ##
       # Calls [HighLine#uncolor](https://www.rubydoc.info/gems/highline/HighLine:uncolor)
       #
       def uncolor(*args)
-        highline.uncolor(*args)
+        self[KEY].uncolor(*args)
       end
 
       ##
       # Calls [HighLine#new_scope](https://www.rubydoc.info/gems/highline/HighLine:new_scope)
       #
       def new_scope
-        highline.new_scope
+        self[KEY].new_scope
       end
 
       on_initialize do |*args|
         require "toys/utils/gems"
-        Toys::Utils::Gems.activate("highline", "~> 2.0")
+        ::Toys::Utils::Gems.activate("highline", "~> 2.0")
         require "highline"
         self[KEY] = ::HighLine.new(*args)
         self[KEY].use_color = $stdout.tty?

data/lib/toys/standard_mixins/terminal.rb

@@ -54,7 +54,7 @@ module Toys
       # @return [self]
       #
       def puts(str = "", *styles)
-        terminal.puts(str, *styles)
+        self[KEY].puts(str, *styles)
         self
       end
       alias say puts
@@ -70,7 +70,7 @@ module Toys
       # @return [self]
       #
       def write(str = "", *styles)
-        terminal.write(str, *styles)
+        self[KEY].write(str, *styles)
         self
       end
 
@@ -89,7 +89,7 @@ module Toys
       # @return [String]
       #
       def ask(prompt, *styles, default: nil, trailing_text: :default)
-        terminal.ask(prompt, *styles, default: default, trailing_text: trailing_text)
+        self[KEY].ask(prompt, *styles, default: default, trailing_text: trailing_text)
       end
 
       ##
@@ -105,7 +105,7 @@ module Toys
       # @return [Boolean]
       #
       def confirm(prompt = "Proceed?", *styles, default: nil)
-        terminal.confirm(prompt, *styles, default: default)
+        self[KEY].confirm(prompt, *styles, default: default)
       end
 
       ##
@@ -130,9 +130,9 @@ module Toys
       #
       def spinner(leading_text: "", final_text: "",
                   frame_length: nil, frames: nil, style: nil, &block)
-        terminal.spinner(leading_text: leading_text, final_text: final_text,
-                         frame_length: frame_length, frames: frames, style: style,
-                         &block)
+        self[KEY].spinner(leading_text: leading_text, final_text: final_text,
+                          frame_length: frame_length, frames: frames, style: style,
+                          &block)
       end
 
       on_initialize do |**opts|

data/lib/toys/standard_mixins/xdg.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "fileutils"
-
 module Toys
   module StandardMixins
     ##