toys-core 0.3.10 → 0.3.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bfede9155648ae5e0b3766dfad5b5165f80fa865eca0e91d390706616372c6e
-  data.tar.gz: 78ba80645b891e5382049153d47168ef69f18e7e762efe553a0f77ad14aa178a
+  metadata.gz: 170a7493ef1b6d852d4a551b7e6f38d0cf861f6660c8b2b1d710c1eee7b5dd2b
+  data.tar.gz: eb2b614017aff294664306a4a2aa6ce96eda22bf37a375c9bb03641c39eb439d
 SHA512:
-  metadata.gz: f0f9533b044b056ea6ea46d121a18fd0a9966b1aadacc845c36651c258bf7bdf8ba8851ccd0f00770a27da67697dcf1fe003804e94b720f87efab4a348cb9cab
-  data.tar.gz: c010707f7452adf31bdbe1d4bd692f39a285091e899c46d6cd964c686ba1aa3df7e119df3888da0f2f660732409c96b1768604f0af48768efa90c188c8497d22
+  metadata.gz: 2e0dc6614370daa927916614b19631dd6b9541d3ed664593b4aeaa6cab2407cb8abf7284afbf13c100fc7b6a783ac261c10e280f7112e6f359bcce90125ab414
+  data.tar.gz: aa7dbaf6c473f233207886fb2b4ce11a7dd551f802dd4e16ad9e8647ee394c8c96f5b6f483e3a775aab08224d4213cce05cf78dbf5fb1000258c4630942e2dc9

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 0.3.11 / 2018-07-02
+
+* CHANGED: Require Ruby 2.3 or later
+* CHANGED: Renamed "set" directive to "static" to reduce confusion with Tool#set.
+* ADDED: Convenience methods for getting option values
+
 ### 0.3.10 / 2018-06-30
 
 * CHANGED: Dropped Tool#option. Use Tool#get instead.

data/README.md

@@ -10,7 +10,7 @@ Toys-Core is the command line tool framework underlying Toys. It can be used
 to create command line binaries using the internal Toys APIs.
 
 To get started using toys-core for your own command line binary, see the
-{file:docs/getting-started.md Getting Started Guide}.
+[Getting Started Guide](https://www.rubydoc.info/gems/toys-core/file/docs/getting-started.md)
 
 ## Contributing
 

data/lib/toys-core.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/cli.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/core_version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -32,5 +34,5 @@ module Toys
   # Current version of Toys core
   # @return [String]
   #
-  CORE_VERSION = "0.3.10".freeze
+  CORE_VERSION = "0.3.11"
 end

data/lib/toys/definition/acceptor.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/definition/alias.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/definition/arg.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/definition/flag.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/definition/tool.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -465,8 +467,8 @@ module Toys
       # the script may use to obtain the flag value from the context.
       # You may then provide the flags themselves in `OptionParser` form.
       #
-      # @param [Symbol] key The key to use to retrieve the value from the
-      #     execution context.
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
       # @param [Array<String>] flags The flags in OptionParser format.
       # @param [Object] accept An acceptor that validates and/or converts the
       #     value. You may provide either the name of an acceptor you have
@@ -529,8 +531,8 @@ module Toys
       # a key which the script may use to obtain the argument value from the
       # context.
       #
-      # @param [Symbol] key The key to use to retrieve the value from the
-      #     execution context.
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
       # @param [Object] accept An acceptor that validates and/or converts the
       #     value. You may provide either the name of an acceptor you have
       #     defined, or one of the default acceptors provided by OptionParser.
@@ -559,8 +561,8 @@ module Toys
       # context. If an optional argument is not given on the command line, the
       # value is set to the given default.
       #
-      # @param [Symbol] key The key to use to retrieve the value from the
-      #     execution context.
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
       # @param [Object] default The default value. This is the value that will
       #     be set in the context if this argument is not provided on the command
       #     line. Defaults to `nil`.
@@ -594,8 +596,8 @@ module Toys
       # specify a key which the script may use to obtain the remaining args
       # from the context.
       #
-      # @param [Symbol] key The key to use to retrieve the value from the
-      #     execution context.
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
       # @param [Object] default The default value. This is the value that will
       #     be set in the context if no unmatched arguments are provided on the
       #     command line. Defaults to the empty array `[]`.

data/lib/toys/dsl/arg.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/dsl/flag.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/dsl/tool.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -48,7 +50,7 @@ module Toys
     #       optional_arg :recipient, default: "world"
     #
     #       def run
-    #         puts "Hello, #{get(:recipient)}!"
+    #         puts "Hello, #{recipient}!"
     #       end
     #     end
     #
@@ -294,8 +296,7 @@ module Toys
       # @param [Toys::Utils::WrappableString,String,Array<String>...] strs
       #
       def long_desc(*strs)
-        cur_tool = DSL::Tool.current_tool(self, true)
-        cur_tool.append_long_desc(strs) if cur_tool
+        DSL::Tool.current_tool(self, true)&.append_long_desc(strs)
         self
       end
 
@@ -304,11 +305,17 @@ module Toys
       # the script may use to obtain the flag value from the context.
       # You may then provide the flags themselves in OptionParser form.
       #
+      # If the given key is a symbol representing a valid method name, then a
+      # helper method is automatically added to retrieve the value. Otherwise,
+      # if the key is a string or does not represent a valid method name, the
+      # tool can retrieve the value by calling {Toys::Tool#get}.
+      #
       # Attributes of the flag may be passed in as arguments to this method, or
-      # set in a block passed to this method.
+      # set in a block passed to this method. If you provide a block, you can
+      # use directives in {Toys::DSL::Flag} within the block.
       #
-      # @param [Symbol] key The key to use to retrieve the value from the
-      #     execution context.
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
       # @param [String...] flags The flags in OptionParser format.
       # @param [Object] accept An acceptor that validates and/or converts the
       #     value. You may provide either the name of an acceptor you have
@@ -343,10 +350,11 @@ module Toys
                &block)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
-        flag_dsl = DSL::Flag.new(flags, accept, default, handler, report_collisions,
-                                 desc, long_desc)
+        flag_dsl = DSL::Flag.new(flags, accept, default, handler,
+                                 report_collisions, desc, long_desc)
         flag_dsl.instance_exec(flag_dsl, &block) if block
         flag_dsl._add_to(cur_tool, key)
+        DSL::Tool.maybe_add_getter(self, key)
         self
       end
 
@@ -355,8 +363,17 @@ module Toys
       # a key which the script may use to obtain the argument value from the
       # context.
       #
-      # @param [Symbol] key The key to use to retrieve the value from the
-      #     execution context.
+      # If the given key is a symbol representing a valid method name, then a
+      # helper method is automatically added to retrieve the value. Otherwise,
+      # if the key is a string or does not represent a valid method name, the
+      # tool can retrieve the value by calling {Toys::Tool#get}.
+      #
+      # Attributes of the arg may be passed in as arguments to this method, or
+      # set in a block passed to this method. If you provide a block, you can
+      # use directives in {Toys::DSL::Arg} within the block.
+      #
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
       # @param [Object] accept An acceptor that validates and/or converts the
       #     value. You may provide either the name of an acceptor you have
       #     defined, or one of the default acceptors provided by OptionParser.
@@ -375,13 +392,15 @@ module Toys
       #     this argument in a block.
       #
       def required_arg(key,
-                       accept: nil, display_name: nil, desc: nil, long_desc: nil,
+                       accept: nil, display_name: nil,
+                       desc: nil, long_desc: nil,
                        &block)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
         arg_dsl = DSL::Arg.new(accept, nil, display_name, desc, long_desc)
         arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._add_required_to(cur_tool, key)
+        DSL::Tool.maybe_add_getter(self, key)
         self
       end
       alias required required_arg
@@ -392,8 +411,17 @@ module Toys
       # context. If an optional argument is not given on the command line, the
       # value is set to the given default.
       #
-      # @param [Symbol] key The key to use to retrieve the value from the
-      #     execution context.
+      # If the given key is a symbol representing a valid method name, then a
+      # helper method is automatically added to retrieve the value. Otherwise,
+      # if the key is a string or does not represent a valid method name, the
+      # tool can retrieve the value by calling {Toys::Tool#get}.
+      #
+      # Attributes of the arg may be passed in as arguments to this method, or
+      # set in a block passed to this method. If you provide a block, you can
+      # use directives in {Toys::DSL::Arg} within the block.
+      #
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
       # @param [Object] default The default value. This is the value that will
       #     be set in the context if this argument is not provided on the command
       #     line. Defaults to `nil`.
@@ -423,6 +451,7 @@ module Toys
         arg_dsl = DSL::Arg.new(accept, default, display_name, desc, long_desc)
         arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._add_optional_to(cur_tool, key)
+        DSL::Tool.maybe_add_getter(self, key)
         self
       end
       alias optional optional_arg
@@ -432,8 +461,17 @@ module Toys
       # specify a key which the script may use to obtain the remaining args from
       # the context.
       #
-      # @param [Symbol] key The key to use to retrieve the value from the
-      #     execution context.
+      # If the given key is a symbol representing a valid method name, then a
+      # helper method is automatically added to retrieve the value. Otherwise,
+      # if the key is a string or does not represent a valid method name, the
+      # tool can retrieve the value by calling {Toys::Tool#get}.
+      #
+      # Attributes of the arg may be passed in as arguments to this method, or
+      # set in a block passed to this method. If you provide a block, you can
+      # use directives in {Toys::DSL::Arg} within the block.
+      #
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
       # @param [Object] default The default value. This is the value that will
       #     be set in the context if no unmatched arguments are provided on the
       #     command line. Defaults to the empty array `[]`.
@@ -463,6 +501,7 @@ module Toys
         arg_dsl = DSL::Arg.new(accept, default, display_name, desc, long_desc)
         arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._set_remaining_on(cur_tool, key)
+        DSL::Tool.maybe_add_getter(self, key)
         self
       end
       alias remaining remaining_args
@@ -470,17 +509,26 @@ module Toys
       ##
       # Set an option value statically.
       #
-      # @param [Symbol] key The key to use to retrieve the value from the
-      #     execution context.
+      # If the given key is a symbol representing a valid method name, then a
+      # helper method is automatically added to retrieve the value. Otherwise,
+      # if the key is a string or does not represent a valid method name, the
+      # tool can retrieve the value by calling {Toys::Tool#get}.
+      #
+      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     the execution context.
       # @param [Object] value The value to set.
       #
-      def set(key, value = nil)
+      def static(key, value = nil)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
         if key.is_a?(::Hash)
           cur_tool.default_data.merge!(key)
+          key.each_key do |k|
+            DSL::Tool.maybe_add_getter(self, k)
+          end
         else
           cur_tool.default_data[key] = value
+          DSL::Tool.maybe_add_getter(self, key)
         end
         self
       end
@@ -494,8 +542,7 @@ module Toys
       # declare arguments or flags.
       #
       def disable_argument_parsing
-        cur_tool = DSL::Tool.current_tool(self, true)
-        cur_tool.disable_argument_parsing unless cur_tool.nil?
+        DSL::Tool.current_tool(self, true)&.disable_argument_parsing
         self
       end
 
@@ -507,8 +554,7 @@ module Toys
       # @param [String...] flags The flags to disable
       #
       def disable_flag(*flags)
-        cur_tool = DSL::Tool.current_tool(self, true)
-        cur_tool.disable_flag(*flags) unless cur_tool.nil?
+        DSL::Tool.current_tool(self, true)&.disable_flag(*flags)
         self
       end
 
@@ -608,6 +654,17 @@ module Toys
         tool_class.instance_variable_set(:@__remaining_words, nil)
         tool_class.instance_variable_set(:@__path, nil)
       end
+
+      ## @private
+      def self.maybe_add_getter(tool_class, key)
+        if key.is_a?(::Symbol) && key.to_s =~ /^[_a-zA-Z]\w*[!\?]?$/
+          tool_class.class_eval do
+            define_method(key) do
+              self[key]
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/toys/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/input_file.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/loader.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -44,9 +46,6 @@ module Toys
       end
     end
 
-    ## @private
-    LOW_PRIORITY = -999_999
-
     ##
     # Create a Loader
     #
@@ -86,6 +85,7 @@ module Toys
       @worklist = []
       @tool_data = {}
       @max_priority = @min_priority = 0
+      get_tool_definition([], -999_999)
     end
 
     ##
@@ -151,7 +151,7 @@ module Toys
           break if p.empty? || p.length <= cur_prefix.length
           p = p.slice(0..-2)
         end
-        return get_tool_definition([], LOW_PRIORITY) if cur_prefix.empty?
+        raise "Unexpected error" if cur_prefix.empty?
         cur_prefix = cur_prefix.slice(0..-2)
       end
     end

data/lib/toys/middleware.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/mixin.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -66,8 +68,12 @@ module Toys
   #
   #       # Mixin methods are called with self set to the tool and can affect
   #       # the tool state.
+  #       def counter_value
+  #         get(:counter_value)
+  #       end
+  #
   #       def increment
-  #         self[:counter_value] += 1
+  #         set(:counter_value, counter_value + 1)
   #         logger.info("Incremented counter")
   #       end
   #     end
@@ -79,8 +85,9 @@ module Toys
   #       include MyCounterMixin, 1
   #
   #       def run
+  #         # Mixin methods can be called.
   #         5.times { increment }
-  #         puts "Final value is #{get(:counter_value)}"
+  #         puts "Final value is #{counter_value}"
   #       end
   #     end
   #

data/lib/toys/runner.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/standard_middleware/add_verbosity_flags.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/standard_middleware/handle_usage_errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -62,7 +64,7 @@ module Toys
           @terminal.puts(tool[Tool::Keys::USAGE_ERROR], :bright_red, :bold)
           @terminal.puts("")
           @terminal.puts(help_text.usage_string(wrap_width: @terminal.width))
-          tool.exit(@exit_code)
+          Tool.exit(@exit_code)
         else
           yield
         end

data/lib/toys/standard_middleware/set_default_descriptions.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -44,19 +46,19 @@ module Toys
       # The default description for tools.
       # @return [String]
       #
-      DEFAULT_TOOL_DESC = "(No tool description available)".freeze
+      DEFAULT_TOOL_DESC = "(No tool description available)"
 
       ##
       # The default description for namespaces.
       # @return [String]
       #
-      DEFAULT_NAMESPACE_DESC = "(A namespace of tools)".freeze
+      DEFAULT_NAMESPACE_DESC = "(A namespace of tools)"
 
       ##
       # The default description for the root tool.
       # @return [String]
       #
-      DEFAULT_ROOT_DESC = "Command line tool built using the toys-core gem.".freeze
+      DEFAULT_ROOT_DESC = "Command line tool built using the toys-core gem."
 
       ##
       # The default long description for the root tool.

data/lib/toys/standard_middleware/show_help.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -251,15 +253,15 @@ module Toys
         loader = tool[Tool::Keys::LOADER]
         tool_definition, rest = loader.lookup(tool_name)
         help_text = Utils::HelpText.new(tool_definition, loader, tool[Tool::Keys::BINARY_NAME])
-        report_usage_error(tool, tool_name, help_text) unless rest.empty?
+        report_usage_error(tool_name, help_text) unless rest.empty?
         help_text
       end
 
-      def report_usage_error(tool, tool_name, help_text)
+      def report_usage_error(tool_name, help_text)
         terminal.puts("Tool not found: #{tool_name.join(' ')}", :bright_red, :bold)
         terminal.puts
         terminal.puts help_text.usage_string(wrap_width: terminal.width)
-        tool.exit(1)
+        Tool.exit(1)
       end
 
       def add_help_flags(tool_definition)
@@ -289,13 +291,16 @@ module Toys
       def add_recursive_flags(tool_definition)
         recursive_flags = resolve_flags_spec(@recursive_flags, tool_definition,
                                              DEFAULT_RECURSIVE_FLAGS)
-        unless recursive_flags.empty?
+        if recursive_flags.empty?
+          tool_definition.default_data[RECURSIVE_SUBTOOLS_KEY] = @default_recursive
+        else
           tool_definition.add_flag(
             RECURSIVE_SUBTOOLS_KEY, recursive_flags,
             report_collisions: false, default: @default_recursive,
             desc: "Show all subtools recursively (default is #{@default_recursive})"
           )
         end
+        recursive_flags
       end
 
       def add_search_flags(tool_definition)
@@ -307,10 +312,11 @@ module Toys
             desc: "Search subtools for the given regular expression"
           )
         end
+        search_flags
       end
 
-      def resolve_flags_spec(flags, tool, defaults)
-        flags = flags.call(tool) if flags.respond_to?(:call)
+      def resolve_flags_spec(flags, tool_definition, defaults)
+        flags = flags.call(tool_definition) if flags.respond_to?(:call)
         case flags
         when true, :default
           Array(defaults)

data/lib/toys/standard_middleware/show_root_version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -46,7 +48,7 @@ module Toys
       # Default description for the version flags
       # @return [String]
       #
-      DEFAULT_VERSION_FLAG_DESC = "Display the version".freeze
+      DEFAULT_VERSION_FLAG_DESC = "Display the version"
 
       ##
       # Key set when the version flag is present

data/lib/toys/standard_mixins/exec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -43,6 +45,23 @@ module Toys
     # This is a frontend for {Toys::Utils::Exec}. More information is
     # available in that class's documentation.
     #
+    # ## Configuration Options
+    #
+    # Subprocesses may be configured using the options in the
+    # {Toys::Utils::Exec} class. These include a variety of options supported
+    # by `Process#spawn`, and some options supported by {Toys::Utils::Exec}
+    # itself.
+    #
+    # In addition, this mixin supports one more option,
+    # `exit_on_nonzero_status`. When set to true, if any subprocess returns a
+    # nonzero result code, the tool will immediately exit with that same code,
+    # similar to `set -e` in a bash script.
+    #
+    # You can set initial configuration by passing options to the `include`
+    # directive. For example:
+    #
+    #     include :exec, exit_on_nonzero_status: true
+    #
     module Exec
       include Mixin
 
@@ -54,6 +73,7 @@ module Toys
 
       to_initialize do |opts = {}|
         tool = self
+        opts = Exec._setup_exec_opts(opts, tool)
         tool[KEY] = Utils::Exec.new(opts) do |k|
           case k
           when :logger
@@ -67,8 +87,10 @@ module Toys
       ##
       # Set default configuration keys.
       #
-      # @param [Hash] opts The default options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} docs.
+      # All options listed in the {Toys::Utils::Exec} documentation are
+      # supported, plus the `exit_on_nonzero_status` option.
+      #
+      # @param [Hash] opts The default options.
       #
       def configure_exec(opts = {})
         self[KEY].configure_defaults(Exec._setup_exec_opts(opts, self))
@@ -82,8 +104,9 @@ module Toys
       # yielded to it, allowing you to interact with the subprocess streams.
       #
       # @param [String,Array<String>] cmd The command to execute.
-      # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @param [Hash] opts The command options. All options listed in the
+      #     {Toys::Utils::Exec} documentation are supported, plus the
+      #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
       #     the subprocess streams.
       #
@@ -101,8 +124,9 @@ module Toys
       # yielded to it, allowing you to interact with the subprocess streams.
       #
       # @param [String,Array<String>] args The arguments to ruby.
-      # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @param [Hash] opts The command options. All options listed in the
+      #     {Toys::Utils::Exec} documentation are supported, plus the
+      #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
       #     for the subprocess streams.
       #
@@ -121,8 +145,9 @@ module Toys
       # yielded to it, allowing you to interact with the subprocess streams.
       #
       # @param [Proc] func The proc to call.
-      # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @param [Hash] opts The command options. Most options listed in the
+      #     {Toys::Utils::Exec} documentation are supported, plus the
+      #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
       #
@@ -141,8 +166,9 @@ module Toys
       # yielded to it, allowing you to interact with the subprocess streams.
       #
       # @param [String,Array<String>] cmd The tool to execute.
-      # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @param [Hash] opts The command options. Most options listed in the
+      #     {Toys::Utils::Exec} documentation are supported, plus the
+      #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
       #
@@ -161,8 +187,9 @@ module Toys
       # Captures standard out and returns it as a string.
       #
       # @param [String,Array<String>] cmd The command to execute.
-      # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @param [Hash] opts The command options. All options listed in the
+      #     {Toys::Utils::Exec} documentation are supported, plus the
+      #     `exit_on_nonzero_status` option.
       #
       # @return [String] What was written to standard out.
       #
@@ -176,8 +203,9 @@ module Toys
       # Captures standard out and returns it as a string.
       #
       # @param [String,Array<String>] args The arguments to ruby.
-      # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @param [Hash] opts The command options. All options listed in the
+      #     {Toys::Utils::Exec} documentation are supported, plus the
+      #     `exit_on_nonzero_status` option.
       #
       # @return [String] What was written to standard out.
       #
@@ -191,8 +219,9 @@ module Toys
       # Captures standard out and returns it as a string.
       #
       # @param [Proc] func The proc to call.
-      # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @param [Hash] opts The command options. Most options listed in the
+      #     {Toys::Utils::Exec} documentation are supported, plus the
+      #     `exit_on_nonzero_status` option.
       #
       # @return [String] What was written to standard out.
       #
@@ -207,8 +236,9 @@ module Toys
       # Captures standard out and returns it as a string.
       #
       # @param [String,Array<String>] cmd The tool to execute.
-      # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @param [Hash] opts The command options. Most options listed in the
+      #     {Toys::Utils::Exec} documentation are supported, plus the
+      #     `exit_on_nonzero_status` option.
       #
       # @return [String] What was written to standard out.
       #
@@ -221,8 +251,9 @@ module Toys
       # Execute the given string in a shell. Returns the exit code.
       #
       # @param [String] cmd The shell command to execute.
-      # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @param [Hash] opts The command options. All options listed in the
+      #     {Toys::Utils::Exec} documentation are supported, plus the
+      #     `exit_on_nonzero_status` option.
       #
       # @return [Integer] The exit code
       #
@@ -238,7 +269,7 @@ module Toys
       def exit_on_nonzero_status(status)
         status = status.exit_code if status.respond_to?(:exit_code)
         status = status.exitstatus if status.respond_to?(:exitstatus)
-        exit(status) unless status.zero?
+        Tool.exit(status) unless status.zero?
         0
       end
 

data/lib/toys/standard_mixins/fileutils.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/standard_mixins/highline.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -35,16 +37,33 @@ module Toys
     ##
     # A mixin that provides access to the capabilities of the highline gem.
     #
+    # This mixin requires the highline gem, version 2.0 or later. It will
+    # attempt to install the gem if it is not available.
+    #
     # You may make these methods available to your tool by including the
     # following directive in your tool configuration:
     #
     #     include :highline
     #
+    # A HighLine object will then be available by calling the {#highline}
+    # method. For information on using this object, see the
+    # [Highline documentation](https://www.rubydoc.info/gems/highline). Some of
+    # the most common HighLine methods, such as `say`, are also mixed into the
+    # tool and can be called directly.
+    #
+    # You can configure the HighLine object by passing options to the `include`
+    # directive. For example:
+    #
+    #     include :highline, my_stdin, my_stdout
+    #
+    # The arguments will be passed on to the
+    # [HighLine constructor](https://www.rubydoc.info/gems/highline/HighLine:initialize).
+    #
     module Highline
       include Mixin
 
       ##
-      # Context key for the executor object.
+      # Context key for the highline object.
       # @return [Object]
       #
       KEY = ::Object.new.freeze

data/lib/toys/standard_mixins/terminal.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -41,6 +43,18 @@ module Toys
     #
     #     include :terminal
     #
+    # A Terminal object will then be available by calling the {#terminal}
+    # method. For information on using this object, see the documentation for
+    # {Toys::Utils::Terminal}. Some of the most useful methods are also mixed
+    # into the tool and can be called directly.
+    #
+    # You can configure the Terminal object by passing options to the `include`
+    # directive. For example:
+    #
+    #     include :terminal, styled: true
+    #
+    # The arguments will be passed on to {Toys::Utils::Terminal#initialize}.
+    #
     module Terminal
       include Mixin
 
@@ -79,8 +93,8 @@ module Toys
       ##
       # @see Toys::Utils::Terminal#confirm
       #
-      def confirm(prompt = "Proceed?")
-        terminal.confirm(prompt)
+      def confirm(prompt = "Proceed?", default: false)
+        terminal.confirm(prompt, default: default)
       end
 
       ##

data/lib/toys/template.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/tool.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -272,9 +274,19 @@ module Toys
     # Exit immediately with the given status code
     #
     # @param [Integer] code The status code, which should be 0 for no error,
-    #     or nonzero for an error condition.
+    #     or nonzero for an error condition. Default is 0.
+    #
+    def exit(code = 0)
+      throw :result, code
+    end
+
+    ##
+    # Exit immediately with the given status code
+    #
+    # @param [Integer] code The status code, which should be 0 for no error,
+    #     or nonzero for an error condition. Default is 0.
     #
-    def exit(code)
+    def self.exit(code = 0)
       throw :result, code
     end
   end

data/lib/toys/utils/exec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/utils/gems.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -60,16 +62,17 @@ module Toys
       #
       # @param [String] name Name of the gem
       # @param [String...] requirements Version requirements
+      # @param [Boolean] default_confirm Default response for the confirmation prompt
       #
-      def self.activate(name, *requirements)
-        new.activate(name, *requirements)
+      def self.activate(name, *requirements, default_confirm: false)
+        new.activate(name, *requirements, default_confirm: default_confirm)
       end
 
       ##
       # Create a new gem activator.
       #
-      def initialize
-        @terminal = Terminal.new(output: $stderr)
+      def initialize(input: $stdin, output: $stderr)
+        @terminal = Terminal.new(input: input, output: output)
         @exec = Exec.new
       end
 
@@ -79,11 +82,12 @@ module Toys
       #
       # @param [String] name Name of the gem
       # @param [String...] requirements Version requirements
+      # @param [Boolean] default_confirm Default response for the confirmation prompt
       #
-      def activate(name, *requirements)
+      def activate(name, *requirements, default_confirm: false)
         gem(name, *requirements)
       rescue ::Gem::MissingSpecError
-        install_gem(name, requirements)
+        install_gem(name, requirements, default_confirm: default_confirm)
       rescue ::Gem::LoadError => e
         if ::ENV["BUNDLE_GEMFILE"]
           raise GemfileUpdateNeededError.new(gem_requirements_text(name, requirements),
@@ -98,9 +102,10 @@ module Toys
         "#{name.inspect}, #{requirements.map(&:inspect).join(', ')}"
       end
 
-      def install_gem(name, requirements)
+      def install_gem(name, requirements, default_confirm: false)
         requirements_text = gem_requirements_text(name, requirements)
-        response = @terminal.confirm("Gem needed: #{requirements_text}. Install?")
+        response = @terminal.confirm("Gem needed: #{requirements_text}. Install?",
+                                     default: default_confirm)
         unless response
           raise InstallFailedError, "Canceled installation of needed gem: #{requirements_text}"
         end

data/lib/toys/utils/help_text.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/utils/module_lookup.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.

data/lib/toys/utils/terminal.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -54,7 +56,7 @@ module Toys
     #
     class Terminal
       ## ANSI style code to clear styles
-      CLEAR_CODE = "\e[0m".freeze
+      CLEAR_CODE = "\e[0m"
 
       ## Standard ANSI style codes
       BUILTIN_STYLE_NAMES = {
@@ -205,15 +207,21 @@ module Toys
       # Confirm with the user.
       #
       # @param [String] prompt Prompt string. Defaults to `"Proceed?"`.
+      # @param [Boolean] default Default value (defaults to false).
       # @return [Boolean]
       #
-      def confirm(prompt = "Proceed?")
-        write("#{prompt} (y/n) ")
-        resp = input.gets
-        if resp =~ /^y/i
+      def confirm(prompt = "Proceed?", default: false)
+        y = default ? "Y" : "y"
+        n = default ? "n" : "N"
+        write("#{prompt} (#{y}/#{n}) ")
+        resp = input.gets.to_s.strip
+        case resp
+        when /^y/i
           true
-        elsif resp =~ /^n/i
+        when /^n/i
           false
+        when ""
+          default
         else
           confirm("Please answer \"y\" or \"n\"")
         end
@@ -386,7 +394,7 @@ module Toys
             @stopping = true
             @cond.broadcast
           end
-          @thread.join if @thread
+          @thread&.join
           self
         end
 

data/lib/toys/utils/wrappable_string.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2018 Daniel Azuma
 #
 # All rights reserved.
@@ -113,7 +115,7 @@ module Toys
             line = "#{line} #{frag}"
           end
         end
-        lines << line if line_len > 0
+        lines << line if line_len.positive?
         lines
       end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.3.10
+  version: 0.3.11
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-30 00:00:00.000000000 Z
+date: 2018-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -80,6 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: highline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: Toys-Core is the command line tool framework underlying Toys. It can
   be used to create command line binaries using the internal Toys APIs.
 email:
@@ -139,7 +153,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.2.0
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="