toys-core 0.3.9.1 → 0.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ddc8eac1d584a35898abadd2c8ef601c6fa4c98fc6854e0bd5578e47f46b6ae
-  data.tar.gz: e15d35d38f56128bb8d5cdef467db338b6e813f88df5be5cbe4a44b9698703fd
+  metadata.gz: 7bfede9155648ae5e0b3766dfad5b5165f80fa865eca0e91d390706616372c6e
+  data.tar.gz: 78ba80645b891e5382049153d47168ef69f18e7e762efe553a0f77ad14aa178a
 SHA512:
-  metadata.gz: 0ff220cbdc9fca5b657d7f4924ad5ac263984ece39be6ed267c2d1f1989004ebcba2cb00f69c3427c890c45341fe0829852987ff324e02d2915abe9a58b4d380
-  data.tar.gz: 20bc712ca5414341e309178d7367f7d4bdc506a8bd1d7f0fda3fa01f4f9f4d64e8c733f0879060d610626a760b6f5db3bb8279ffe096bc50b35f79d99f1a0f29
+  metadata.gz: f0f9533b044b056ea6ea46d121a18fd0a9966b1aadacc845c36651c258bf7bdf8ba8851ccd0f00770a27da67697dcf1fe003804e94b720f87efab4a348cb9cab
+  data.tar.gz: c010707f7452adf31bdbe1d4bd692f39a285091e899c46d6cd964c686ba1aa3df7e119df3888da0f2f660732409c96b1768604f0af48768efa90c188c8497d22

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 0.3.10 / 2018-06-30
+
+* CHANGED: Dropped Tool#option. Use Tool#get instead.
+* CHANGED: "run" directive renamed to "to_run"
+* CHANGED: Highline mixin now uses Highline 2.0
+* CHANGED: Middleware-added keys no longer show up in the options hash
+* ADDED: Mixins can provide initializers
+* ADDED: Loader can load an inline block
+
 ### 0.3.9.1 / 2018-06-24
 
 * FIXED: Built-in flags were interfering with disable_argument_parsing

data/lib/toys/cli.rb

@@ -151,6 +151,20 @@ module Toys
       self
     end
 
+    ##
+    # Add a configuration block to the loader.
+    #
+    # @param [Boolean] high_priority Add the config at the head of the priority
+    #     list rather than the tail.
+    # @param [String] path The "path" that will be shown in documentation for
+    #     tools defined in this block. If omitted, a default unique string will
+    #     be generated.
+    #
+    def add_config_block(high_priority: false, path: nil, &block)
+      @loader.add_block(high_priority: high_priority, path: path, &block)
+      self
+    end
+
     ##
     # Searches the given directory for a well-known config directory and/or
     # config file. If found, these are added to the loader.

data/lib/toys/core_version.rb

@@ -32,5 +32,5 @@ module Toys
   # Current version of Toys core
   # @return [String]
   #
-  CORE_VERSION = "0.3.9.1".freeze
+  CORE_VERSION = "0.3.10".freeze
 end

data/lib/toys/definition/arg.rb

@@ -39,7 +39,7 @@ module Toys
       # Create an Arg definition
       # @private
       #
-      def initialize(key, type, accept, default, desc, long_desc, display_name)
+      def initialize(key, type, accept, default, desc, long_desc, display_name = nil)
         @key = key
         @type = type
         @accept = accept
@@ -103,7 +103,7 @@ module Toys
         result = input
         optparse = ::OptionParser.new
         optparse.accept(accept) if accept.is_a?(Acceptor)
-        optparse.on("--abc=VALUE", accept) { |v| result = v }
+        optparse.on("--abc VALUE", accept) { |v| result = v }
         optparse.parse(["--abc", input])
         result
       end

data/lib/toys/definition/flag.rb

@@ -43,6 +43,8 @@ module Toys
           setup(str, [$1], $1, "-", nil, nil, nil, nil)
         when /^(-[\?\w])( ?)\[(\w+)\]$/
           setup(str, [$1], $1, "-", :value, :optional, $2, $3)
+        when /^(-[\?\w])\[( )(\w+)\]$/
+          setup(str, [$1], $1, "-", :value, :optional, $2, $3)
         when /^(-[\?\w])( ?)(\w+)$/
           setup(str, [$1], $1, "-", :value, :required, $2, $3)
         when /^--\[no-\](\w[\?\w-]*)$/
@@ -305,6 +307,7 @@ module Toys
           analyze_flag_syntax(flag)
         end
         @flag_type ||= :boolean
+        @value_type ||= :required if @flag_type == :value
         flag_syntax.each do |flag|
           flag.configure_canonical(@flag_type, @value_type, @value_label, @value_delim)
         end

data/lib/toys/definition/tool.rb

@@ -82,6 +82,7 @@ module Toys
 
         @default_data = {}
         @used_flags = []
+        @initializers = []
 
         @acceptors = {}
         @mixins = {}
@@ -381,6 +382,20 @@ module Toys
         @long_desc = Utils::WrappableString.make_array(long_desc)
       end
 
+      ##
+      # Append long description strings.
+      #
+      # Each string may be provided as a {Toys::Utils::WrappableString}, a single
+      # string (which will be wrapped), or an array of strings, which will be
+      # interpreted as string fragments that will be concatenated and wrapped.
+      #
+      # @param [Array<Toys::Utils::WrappableString,String,Array<String>>] long_desc
+      #
+      def append_long_desc(long_desc)
+        check_definition_state
+        @long_desc += Utils::WrappableString.make_array(long_desc)
+      end
+
       ##
       # Add an acceptor to the tool. This acceptor may be refereneced by name
       # when adding a flag or an arg.
@@ -615,7 +630,19 @@ module Toys
       # @param [Proc] proc The runnable block
       #
       def runnable=(proc)
-        @tool_class.run(&proc)
+        @tool_class.to_run(&proc)
+      end
+
+      ##
+      # Add an initializer.
+      #
+      # @param [Proc] proc The initializer block
+      # @param [Object...] args Arguments to pass to the initializer
+      #
+      def add_initializer(proc, *args)
+        check_definition_state
+        @initializers << [proc, args]
+        self
       end
 
       ##
@@ -647,6 +674,17 @@ module Toys
         self
       end
 
+      ##
+      # Run all initializers against a tool. Should be called from the Runner
+      # only.
+      # @private
+      #
+      def run_initializers(tool)
+        @initializers.each do |func, args|
+          tool.instance_exec(*args, &func)
+        end
+      end
+
       private
 
       def make_config_proc(middleware, loader, next_config)

data/lib/toys/dsl/arg.rb

@@ -44,7 +44,7 @@ module Toys
         @default = default
         @display_name = display_name
         @desc = desc
-        @long_desc = long_desc
+        @long_desc = long_desc || []
       end
 
       ##
@@ -70,7 +70,7 @@ module Toys
       # @param [String] display_name
       #
       def display_name(display_name)
-        @handler = display_name
+        @display_name = display_name
         self
       end
 

data/lib/toys/dsl/flag.rb

@@ -45,7 +45,7 @@ module Toys
         @handler = handler
         @report_collisions = report_collisions
         @desc = desc
-        @long_desc = long_desc
+        @long_desc = long_desc || []
       end
 
       ##

data/lib/toys/dsl/tool.rb

@@ -48,7 +48,7 @@ module Toys
     #       optional_arg :recipient, default: "world"
     #
     #       def run
-    #         puts "Hello, #{option(:recipient)}!"
+    #         puts "Hello, #{get(:recipient)}!"
     #       end
     #     end
     #
@@ -63,7 +63,7 @@ module Toys
     module Tool
       ## @private
       def method_added(meth)
-        cur_tool = DSL::Tool.activate_tool(self)
+        cur_tool = DSL::Tool.current_tool(self, true)
         cur_tool.mark_runnable if cur_tool && meth == :run
       end
 
@@ -108,7 +108,7 @@ module Toys
       # @param [Proc,nil] converter The validator.
       #
       def acceptor(name, validator = nil, converter = nil, &block)
-        cur_tool = DSL::Tool.activate_tool(self)
+        cur_tool = DSL::Tool.current_tool(self, false)
         return self if cur_tool.nil?
         accept =
           case validator
@@ -134,8 +134,14 @@ module Toys
       # @param [String] name Name of the mixin
       #
       def mixin(name, &block)
-        cur_tool = DSL::Tool.activate_tool(self)
-        cur_tool.add_mixin(name, ::Module.new(&block)) if cur_tool
+        cur_tool = DSL::Tool.current_tool(self, false)
+        if cur_tool
+          mixin_mod = ::Module.new do
+            include ::Toys::Mixin
+          end
+          mixin_mod.module_eval(&block)
+          cur_tool.add_mixin(name, mixin_mod)
+        end
         self
       end
 
@@ -152,7 +158,7 @@ module Toys
       # @param [String] name Name of the template
       #
       def template(name, &block)
-        cur_tool = DSL::Tool.activate_tool(self)
+        cur_tool = DSL::Tool.current_tool(self, false)
         if cur_tool
           template_class = ::Class.new do
             include ::Toys::Template
@@ -200,7 +206,7 @@ module Toys
       # @param [String] path The file or directory to include.
       #
       def load(path)
-        @__loader.include_path(path, @__words, @__remaining_words, @__priority)
+        @__loader.load_path(path, @__words, @__remaining_words, @__priority)
         self
       end
 
@@ -215,6 +221,8 @@ module Toys
       # @param [Object...] args Template arguments
       #
       def expand(template_class, *args)
+        cur_tool = DSL::Tool.current_tool(self, true)
+        return self if cur_tool.nil?
         name = template_class.to_s
         if template_class.is_a?(::String)
           template_class = cur_tool.resolve_template(template_class)
@@ -260,7 +268,7 @@ module Toys
       # @param [Toys::Utils::WrappableString,String,Array<String>] str
       #
       def desc(str)
-        cur_tool = DSL::Tool.activate_tool(self)
+        cur_tool = DSL::Tool.current_tool(self, true)
         cur_tool.desc = str if cur_tool
         self
       end
@@ -286,8 +294,8 @@ module Toys
       # @param [Toys::Utils::WrappableString,String,Array<String>...] strs
       #
       def long_desc(*strs)
-        cur_tool = DSL::Tool.activate_tool(self)
-        cur_tool.long_desc = strs if cur_tool
+        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool.append_long_desc(strs) if cur_tool
         self
       end
 
@@ -333,7 +341,7 @@ module Toys
                report_collisions: true,
                desc: nil, long_desc: nil,
                &block)
-        cur_tool = DSL::Tool.activate_tool(self)
+        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)
@@ -369,7 +377,7 @@ module Toys
       def required_arg(key,
                        accept: nil, display_name: nil, desc: nil, long_desc: nil,
                        &block)
-        cur_tool = DSL::Tool.activate_tool(self)
+        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
@@ -410,7 +418,7 @@ module Toys
                        default: nil, accept: nil, display_name: nil,
                        desc: nil, long_desc: nil,
                        &block)
-        cur_tool = DSL::Tool.activate_tool(self)
+        cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
         arg_dsl = DSL::Arg.new(accept, default, display_name, desc, long_desc)
         arg_dsl.instance_exec(arg_dsl, &block) if block
@@ -450,7 +458,7 @@ module Toys
                          default: [], accept: nil, display_name: nil,
                          desc: nil, long_desc: nil,
                          &block)
-        cur_tool = DSL::Tool.activate_tool(self)
+        cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
         arg_dsl = DSL::Arg.new(accept, default, display_name, desc, long_desc)
         arg_dsl.instance_exec(arg_dsl, &block) if block
@@ -466,10 +474,14 @@ module Toys
       #     execution context.
       # @param [Object] value The value to set.
       #
-      def set(key, value)
-        cur_tool = DSL::Tool.activate_tool(self)
+      def set(key, value = nil)
+        cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
-        cur_tool.default_data[key] = value
+        if key.is_a?(::Hash)
+          cur_tool.default_data.merge!(key)
+        else
+          cur_tool.default_data[key] = value
+        end
         self
       end
 
@@ -482,29 +494,29 @@ module Toys
       # declare arguments or flags.
       #
       def disable_argument_parsing
-        cur_tool = DSL::Tool.activate_tool(self)
+        cur_tool = DSL::Tool.current_tool(self, true)
         cur_tool.disable_argument_parsing unless cur_tool.nil?
         self
       end
 
       ##
       # Mark one or more flags as disabled, preventing their use by any
-      # subsequent flag definition. This may be used to prevent middleware from
+      # subsequent flag definition. This can be used to prevent middleware from
       # defining a particular flag.
       #
       # @param [String...] flags The flags to disable
       #
       def disable_flag(*flags)
-        cur_tool = DSL::Tool.activate_tool(self)
+        cur_tool = DSL::Tool.current_tool(self, true)
         cur_tool.disable_flag(*flags) unless cur_tool.nil?
         self
       end
 
       ##
-      # Specify how to run this tool. You may do this by providing a block to
+      # Specify how to run this tool. You can do this by providing a block to
       # this directive, or by defining the `run` method in the tool.
       #
-      def run(&block)
+      def to_run(&block)
         define_method(:run, &block)
         self
       end
@@ -518,9 +530,10 @@ module Toys
       # of a well-known mixin.
       #
       # @param [Module,Symbol,String] mod Module or module name.
+      # @param [Object...] args Arguments to pass to the initializer
       #
-      def include(mod)
-        cur_tool = DSL::Tool.activate_tool(self)
+      def include(mod, *args)
+        cur_tool = DSL::Tool.current_tool(self, true)
         return if cur_tool.nil?
         name = mod.to_s
         if mod.is_a?(::String)
@@ -531,6 +544,9 @@ module Toys
         if mod.nil?
           raise ToolDefinitionError, "Module not found: #{name.inspect}"
         end
+        if mod.respond_to?(:initializer)
+          cur_tool.add_initializer(mod.initializer, *args) if mod.initializer
+        end
         super(mod)
       end
 
@@ -558,24 +574,28 @@ module Toys
       end
 
       ## @private
-      def self.activate_tool(tool_class)
+      def self.current_tool(tool_class, activate)
+        memoize_var = activate ? :@__active_tool : :@__cur_tool
         path = tool_class.instance_variable_get(:@__path)
-        cur_tool =
-          if tool_class.instance_variable_defined?(:@__cur_tool)
-            tool_class.instance_variable_get(:@__cur_tool)
-          else
-            loader = tool_class.instance_variable_get(:@__loader)
-            words = tool_class.instance_variable_get(:@__words)
-            priority = tool_class.instance_variable_get(:@__priority)
-            cur_tool = loader.activate_tool_definition(words, priority)
-            if cur_tool.is_a?(Definition::Alias)
-              raise ToolDefinitionError,
-                    "Cannot configure #{words.join(' ').inspect} because it is an alias"
+        if tool_class.instance_variable_defined?(memoize_var)
+          cur_tool = tool_class.instance_variable_get(memoize_var)
+        else
+          loader = tool_class.instance_variable_get(:@__loader)
+          words = tool_class.instance_variable_get(:@__words)
+          priority = tool_class.instance_variable_get(:@__priority)
+          cur_tool =
+            if activate
+              loader.activate_tool_definition(words, priority)
+            else
+              loader.get_tool_definition(words, priority)
             end
-            tool_class.instance_variable_set(:@__cur_tool, cur_tool)
-            cur_tool
+          if cur_tool.is_a?(Definition::Alias)
+            raise ToolDefinitionError,
+                  "Cannot configure #{words.join(' ').inspect} because it is an alias"
           end
-        cur_tool.lock_source_path(path) if cur_tool
+          tool_class.instance_variable_set(memoize_var, cur_tool)
+        end
+        cur_tool.lock_source_path(path) if cur_tool && activate
         cur_tool
       end
 

data/lib/toys/loader.rb

@@ -44,6 +44,9 @@ module Toys
       end
     end
 
+    ## @private
+    LOW_PRIORITY = -999_999
+
     ##
     # Create a Loader
     #
@@ -80,7 +83,7 @@ module Toys
       @index_file_name = index_file_name
       @preload_file_name = preload_file_name
       @middleware_stack = middleware_stack
-      @load_worklist = []
+      @worklist = []
       @tool_data = {}
       @max_priority = @min_priority = 0
     end
@@ -97,11 +100,28 @@ module Toys
       paths = Array(path)
       priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
       paths.each do |p|
-        @load_worklist << [check_path(p), [], priority]
+        @worklist << [:file, check_path(p), [], priority]
       end
       self
     end
 
+    ##
+    # Add a configuration block to the loader.
+    #
+    # @param [Boolean] high_priority If true, add this block at the top of the
+    #     priority list. Defaults to false, indicating the block should be at
+    #     the bottom of the priority list.
+    # @param [String] path The "path" that will be shown in documentation for
+    #     tools defined in this block. If omitted, a default unique string will
+    #     be generated.
+    #
+    def add_block(high_priority: false, path: nil, &block)
+      path ||= "(Block #{block.object_id})"
+      priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
+      @worklist << [block, path, [], priority]
+      self
+    end
+
     ##
     # Given a list of command line arguments, find the appropriate tool to
     # handle the command, loading it from the configuration if necessary, and
@@ -131,7 +151,7 @@ module Toys
           break if p.empty? || p.length <= cur_prefix.length
           p = p.slice(0..-2)
         end
-        return nil if cur_prefix.empty?
+        return get_tool_definition([], LOW_PRIORITY) if cur_prefix.empty?
         cur_prefix = cur_prefix.slice(0..-2)
       end
     end
@@ -279,8 +299,26 @@ module Toys
     #
     # @private
     #
-    def include_path(path, words, remaining_words, priority)
-      handle_path(check_path(path), words, remaining_words, priority)
+    def load_path(path, words, remaining_words, priority)
+      load_validated_path(check_path(path), words, remaining_words, priority)
+    end
+
+    ##
+    # Load configuration from the given proc.
+    #
+    # @private
+    #
+    def load_proc(proc, words, remaining_words, priority, path)
+      if remaining_words
+        tool_class = get_tool_definition(words, priority).tool_class
+        ::Toys::DSL::Tool.prepare(tool_class, remaining_words, path) do
+          ::Toys::ContextualError.capture("Error while loading Toys config!") do
+            tool_class.class_eval(&proc)
+          end
+        end
+      else
+        @worklist << [proc, path, words, priority]
+      end
     end
 
     ##
@@ -365,22 +403,27 @@ module Toys
     end
 
     def load_for_prefix(prefix)
-      cur_worklist = @load_worklist
-      @load_worklist = []
-      cur_worklist.each do |path, words, priority|
-        handle_path(path, words, calc_remaining_words(prefix, words), priority)
+      cur_worklist = @worklist
+      @worklist = []
+      cur_worklist.each do |source, path, words, priority|
+        remaining_words = calc_remaining_words(prefix, words)
+        if source.respond_to?(:call)
+          load_proc(source, words, remaining_words, priority, path)
+        elsif source == :file
+          load_validated_path(path, words, remaining_words, priority)
+        end
       end
     end
 
-    def handle_path(path, words, remaining_words, priority)
+    def load_validated_path(path, words, remaining_words, priority)
       if remaining_words
-        load_path(path, words, remaining_words, priority)
+        load_relevant_path(path, words, remaining_words, priority)
       else
-        @load_worklist << [path, words, priority]
+        @worklist << [:file, path, words, priority]
       end
     end
 
-    def load_path(path, words, remaining_words, priority)
+    def load_relevant_path(path, words, remaining_words, priority)
       if ::File.extname(path) == ".rb"
         tool_class = get_tool_definition(words, priority).tool_class
         Toys::InputFile.evaluate(tool_class, remaining_words, path)
@@ -404,7 +447,7 @@ module Toys
       return unless @index_file_name
       index_path = ::File.join(path, @index_file_name)
       index_path = check_path(index_path, type: :file, lenient: true)
-      load_path(index_path, words, remaining_words, priority) if index_path
+      load_relevant_path(index_path, words, remaining_words, priority) if index_path
     end
 
     def load_child_in(path, child, words, remaining_words, priority)
@@ -414,7 +457,7 @@ module Toys
       child_word = ::File.basename(child, ".rb")
       next_words = words + [child_word]
       next_remaining = Loader.next_remaining_words(remaining_words, child_word)
-      handle_path(child_path, next_words, next_remaining, priority)
+      load_validated_path(child_path, next_words, next_remaining, priority)
     end
 
     def check_path(path, lenient: false, type: nil)

data/lib/toys/mixin.rb

@@ -0,0 +1,112 @@
+# Copyright 2018 Daniel Azuma
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+;
+
+module Toys
+  ##
+  # A mixin definition. Mixin modules should include this module.
+  #
+  # A mixin is a collection of methods that are available to be called from a
+  # tool implementation (i.e. its run method). The mixin is added to the tool
+  # class, so it has access to the same methods that can be called by the tool,
+  # such as {Toys::Tool#option}.
+  #
+  # ## Usage
+  #
+  # To create a mixin, define a module, and include this module. Then define
+  # the methods you want to be available.
+  #
+  # If you want to perform some initialization specific to the mixin, use a
+  # `to_initialize` block. This block is passed any extra arguments that were
+  # passed to the `include` directive. It is called in the context of the tool,
+  # so it also has access to tool methods such as {Toys::Tool#option}. It can
+  # perform any setup required, which often involves initializing some
+  # persistent state and storing it in the tool using {Toys::Tool#set}.
+  #
+  # ## Example
+  #
+  # This is an example that implements a simple counter. Whenever the counter
+  # is incremented, a log message is emitted. The tool can also retrieve the
+  # final counter value.
+  #
+  #     # Define a mixin by creating a module that includes Toys::Mixin
+  #     module MyCounterMixin
+  #       include Toys::Mixin
+  #
+  #       # Initialize the counter. Called with self set to the tool so it can
+  #       # affect the tool state.
+  #       to_initialize do |start = 0|
+  #         set(:counter_value, start)
+  #       end
+  #
+  #       # Mixin methods are called with self set to the tool and can affect
+  #       # the tool state.
+  #       def increment
+  #         self[:counter_value] += 1
+  #         logger.info("Incremented counter")
+  #       end
+  #     end
+  #
+  # Now we can use it from a tool:
+  #
+  #     tool "count-up" do
+  #       # Pass 1 as an extra argument to the mixin initializer
+  #       include MyCounterMixin, 1
+  #
+  #       def run
+  #         5.times { increment }
+  #         puts "Final value is #{get(:counter_value)}"
+  #       end
+  #     end
+  #
+  module Mixin
+    ## @private
+    def self.included(mod)
+      return if mod.respond_to?(:to_initialize)
+      mod.extend(ClassMethods)
+    end
+
+    ##
+    # Class methods that will be added to a mixin module.
+    #
+    module ClassMethods
+      ##
+      # Provide the block that initializes this mixin.
+      #
+      def to_initialize(&block)
+        self.initializer = block
+      end
+
+      ##
+      # You may alternately set the initializer block using this accessor.
+      # @return [Proc]
+      #
+      attr_accessor :initializer
+    end
+  end
+end

data/lib/toys/runner.rb

@@ -61,6 +61,7 @@ module Toys
       data = create_data(args, verbosity)
       parse_args(args, data) unless @tool_definition.argument_parsing_disabled?
       tool = @tool_definition.tool_class.new(@cli, data)
+      @tool_definition.run_initializers(tool)
 
       original_level = @cli.logger.level
       @cli.logger.level = @cli.base_level - data[Tool::Keys::VERBOSITY]

data/lib/toys/standard_middleware/show_help.rb

@@ -66,6 +66,36 @@ module Toys
       #
       DEFAULT_SEARCH_FLAGS = ["-s WORD", "--search=WORD"].freeze
 
+      ##
+      # Key set when the show help flag is present
+      # @return [Object]
+      #
+      SHOW_HELP_KEY = Object.new.freeze
+
+      ##
+      # Key set when the show usage flag is present
+      # @return [Object]
+      #
+      SHOW_USAGE_KEY = Object.new.freeze
+
+      ##
+      # Key for the recursive setting
+      # @return [Object]
+      #
+      RECURSIVE_SUBTOOLS_KEY = Object.new.freeze
+
+      ##
+      # Key for the search string
+      # @return [Object]
+      #
+      SEARCH_STRING_KEY = Object.new.freeze
+
+      ##
+      # Key for the tool name
+      # @return [Object]
+      #
+      TOOL_NAME_KEY = Object.new.freeze
+
       ##
       # Create a ShowHelp middleware.
       #
@@ -155,7 +185,7 @@ module Toys
           usage_flags = add_usage_flags(tool_definition)
           if @allow_root_args && (!help_flags.empty? || !usage_flags.empty?)
             if tool_definition.root? && tool_definition.arg_definitions.empty?
-              tool_definition.set_remaining_args(:_tool_name,
+              tool_definition.set_remaining_args(TOOL_NAME_KEY,
                                                  display_name: "TOOL_NAME",
                                                  desc: "The tool for which to display help")
             end
@@ -173,15 +203,15 @@ module Toys
       # Display help text if requested.
       #
       def run(tool)
-        if tool[:_show_usage]
+        if tool[SHOW_USAGE_KEY]
           help_text = get_help_text(tool)
           str = help_text.usage_string(wrap_width: terminal.width)
           terminal.puts(str)
         elsif @fallback_execution && !tool[Tool::Keys::TOOL_DEFINITION].runnable? ||
-              tool[:_show_help]
+              tool[SHOW_HELP_KEY]
           help_text = get_help_text(tool)
-          str = help_text.help_string(recursive: tool[:_recursive_subtools],
-                                      search: tool[:_search_subtools],
+          str = help_text.help_string(recursive: tool[RECURSIVE_SUBTOOLS_KEY],
+                                      search: tool[SEARCH_STRING_KEY],
                                       show_source_path: @show_source_path,
                                       wrap_width: terminal.width)
           output_help(str)
@@ -216,7 +246,7 @@ module Toys
       end
 
       def get_help_text(tool)
-        tool_name = tool[:_tool_name]
+        tool_name = tool[TOOL_NAME_KEY]
         return Utils::HelpText.from_tool(tool) if tool_name.nil? || tool_name.empty?
         loader = tool[Tool::Keys::LOADER]
         tool_definition, rest = loader.lookup(tool_name)
@@ -236,7 +266,7 @@ module Toys
         help_flags = resolve_flags_spec(@help_flags, tool_definition, DEFAULT_HELP_FLAGS)
         unless help_flags.empty?
           tool_definition.add_flag(
-            :_show_help, help_flags,
+            SHOW_HELP_KEY, help_flags,
             report_collisions: false,
             desc: "Display help for this tool"
           )
@@ -248,7 +278,7 @@ module Toys
         usage_flags = resolve_flags_spec(@usage_flags, tool_definition, DEFAULT_USAGE_FLAGS)
         unless usage_flags.empty?
           tool_definition.add_flag(
-            :_show_usage, usage_flags,
+            SHOW_USAGE_KEY, usage_flags,
             report_collisions: false,
             desc: "Display a brief usage string for this tool"
           )
@@ -261,7 +291,7 @@ module Toys
                                              DEFAULT_RECURSIVE_FLAGS)
         unless recursive_flags.empty?
           tool_definition.add_flag(
-            :_recursive_subtools, recursive_flags,
+            RECURSIVE_SUBTOOLS_KEY, recursive_flags,
             report_collisions: false, default: @default_recursive,
             desc: "Show all subtools recursively (default is #{@default_recursive})"
           )
@@ -272,7 +302,7 @@ module Toys
         search_flags = resolve_flags_spec(@search_flags, tool_definition, DEFAULT_SEARCH_FLAGS)
         unless search_flags.empty?
           tool_definition.add_flag(
-            :_search_subtools, search_flags,
+            SEARCH_STRING_KEY, search_flags,
             report_collisions: false,
             desc: "Search subtools for the given regular expression"
           )

data/lib/toys/standard_middleware/show_root_version.rb

@@ -48,6 +48,12 @@ module Toys
       #
       DEFAULT_VERSION_FLAG_DESC = "Display the version".freeze
 
+      ##
+      # Key set when the version flag is present
+      # @return [Object]
+      #
+      SHOW_VERSION_KEY = Object.new.freeze
+
       ##
       # Create a ShowVersion middleware
       #
@@ -72,7 +78,7 @@ module Toys
       #
       def config(tool_definition, _loader)
         if @version_string && tool_definition.root?
-          tool_definition.add_flag(:_show_version, @version_flags,
+          tool_definition.add_flag(SHOW_VERSION_KEY, @version_flags,
                                    report_collisions: false, desc: @version_flag_desc)
         end
         yield
@@ -82,7 +88,7 @@ module Toys
       # This middleware displays the version.
       #
       def run(tool)
-        if tool[:_show_version]
+        if tool[SHOW_VERSION_KEY]
           @terminal.puts(@version_string)
         else
           yield

data/lib/toys/standard_mixins/exec.rb

@@ -44,6 +44,26 @@ module Toys
     # available in that class's documentation.
     #
     module Exec
+      include Mixin
+
+      ##
+      # Context key for the executor object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      to_initialize do |opts = {}|
+        tool = self
+        tool[KEY] = Utils::Exec.new(opts) do |k|
+          case k
+          when :logger
+            tool[Tool::Keys::LOGGER]
+          when :cli
+            tool[Tool::Keys::CLI]
+          end
+        end
+      end
+
       ##
       # Set default configuration keys.
       #
@@ -51,7 +71,7 @@ module Toys
       #     configuration options in the {Toys::Utils::Exec} docs.
       #
       def configure_exec(opts = {})
-        Exec._exec(self).configure_defaults(Exec._setup_exec_opts(opts, self))
+        self[KEY].configure_defaults(Exec._setup_exec_opts(opts, self))
       end
 
       ##
@@ -71,7 +91,7 @@ module Toys
       #     the exit code and any captured output.
       #
       def exec(cmd, opts = {}, &block)
-        Exec._exec(self).exec(cmd, Exec._setup_exec_opts(opts, self), &block)
+        self[KEY].exec(cmd, Exec._setup_exec_opts(opts, self), &block)
       end
 
       ##
@@ -90,7 +110,7 @@ module Toys
       #     the exit code and any captured output.
       #
       def exec_ruby(args, opts = {}, &block)
-        Exec._exec(self).exec_ruby(args, Exec._setup_exec_opts(opts, self), &block)
+        self[KEY].exec_ruby(args, Exec._setup_exec_opts(opts, self), &block)
       end
       alias ruby exec_ruby
 
@@ -110,7 +130,7 @@ module Toys
       #     exit code and any captured output.
       #
       def exec_proc(func, opts = {}, &block)
-        Exec._exec(self).exec_proc(func, Exec._setup_exec_opts(opts, self), &block)
+        self[KEY].exec_proc(func, Exec._setup_exec_opts(opts, self), &block)
       end
 
       ##
@@ -131,7 +151,7 @@ module Toys
       #
       def exec_tool(cmd, opts = {}, &block)
         func = Exec._make_tool_caller(cmd)
-        Exec._exec(self).exec_proc(func, Exec._setup_exec_opts(opts, self), &block)
+        self[KEY].exec_proc(func, Exec._setup_exec_opts(opts, self), &block)
       end
 
       ##
@@ -147,7 +167,7 @@ module Toys
       # @return [String] What was written to standard out.
       #
       def capture(cmd, opts = {})
-        Exec._exec(self).capture(cmd, Exec._setup_exec_opts(opts, self))
+        self[KEY].capture(cmd, Exec._setup_exec_opts(opts, self))
       end
 
       ##
@@ -162,7 +182,7 @@ module Toys
       # @return [String] What was written to standard out.
       #
       def capture_ruby(args, opts = {})
-        Exec._exec(self).capture_ruby(args, Exec._setup_exec_opts(opts, self))
+        self[KEY].capture_ruby(args, Exec._setup_exec_opts(opts, self))
       end
 
       ##
@@ -177,7 +197,7 @@ module Toys
       # @return [String] What was written to standard out.
       #
       def capture_proc(func, opts = {})
-        Exec._exec(self).capture_proc(func, Exec._setup_exec_opts(opts, self))
+        self[KEY].capture_proc(func, Exec._setup_exec_opts(opts, self))
       end
 
       ##
@@ -194,7 +214,7 @@ module Toys
       #
       def capture_tool(cmd, opts = {})
         func = Exec._make_tool_caller(cmd)
-        Exec._exec(self).capture_proc(func, Exec._setup_exec_opts(opts, self))
+        self[KEY].capture_proc(func, Exec._setup_exec_opts(opts, self))
       end
 
       ##
@@ -207,7 +227,7 @@ module Toys
       # @return [Integer] The exit code
       #
       def sh(cmd, opts = {})
-        Exec._exec(self).sh(cmd, Exec._setup_exec_opts(opts, self))
+        self[KEY].sh(cmd, Exec._setup_exec_opts(opts, self))
       end
 
       ##
@@ -222,18 +242,6 @@ module Toys
         0
       end
 
-      ## @private
-      def self._exec(tool)
-        tool[Exec] ||= Utils::Exec.new do |k|
-          case k
-          when :logger
-            tool[Tool::Keys::LOGGER]
-          when :cli
-            tool[Tool::Keys::CLI]
-          end
-        end
-      end
-
       ## @private
       def self._make_tool_caller(cmd)
         cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)

data/lib/toys/standard_mixins/fileutils.rb

@@ -41,6 +41,8 @@ module Toys
     #     include :fileutils
     #
     module Fileutils
+      include Mixin
+
       ## @private
       def self.included(mod)
         mod.include(::FileUtils)

data/lib/toys/standard_mixins/highline.rb

@@ -27,7 +27,7 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-Toys::Utils::Gems.activate("highline", "~> 1.7")
+Toys::Utils::Gems.activate("highline", "~> 2.0")
 require "highline"
 
 module Toys
@@ -41,15 +41,25 @@ module Toys
     #     include :highline
     #
     module Highline
+      include Mixin
+
+      ##
+      # Context key for the executor object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      to_initialize do |*args|
+        self[KEY] = ::HighLine.new(*args)
+        self[KEY].use_color = $stdout.tty?
+      end
+
       ##
       # Returns a global highline instance
       # @return [::HighLine]
       #
       def highline
-        self[Highline] ||= begin
-          ::HighLine.use_color = $stdout.tty?
-          ::HighLine.new
-        end
+        self[KEY]
       end
 
       ##
@@ -88,38 +98,52 @@ module Toys
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine.color HighLine.color
+      # @see https://www.rubydoc.info/gems/highline/HighLine:indent HighLine#indent
       #
-      def color(*args, &block)
-        ::HighLine.color(*args, &block)
+      def indent(*args, &block)
+        highline.indent(*args, &block)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine.color_code HighLine.color_code
+      # @see https://www.rubydoc.info/gems/highline/HighLine:newline HighLine#newline
       #
-      def color_code(*args, &block)
-        ::HighLine.color_code(*args, &block)
+      def newline
+        highline.newline
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine.uncolor HighLine.uncolor
+      # @see https://www.rubydoc.info/gems/highline/HighLine:puts HighLine#puts
       #
-      def uncolor(*args, &block)
-        ::HighLine.uncolor(*args, &block)
+      def puts(*args)
+        highline.puts(*args)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:indent HighLine#indent
+      # @see https://www.rubydoc.info/gems/highline/HighLine:color HighLine#color
       #
-      def indent(*args, &block)
-        highline.indent(*args, &block)
+      def color(*args)
+        highline.color(*args)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:newline HighLine#newline
+      # @see https://www.rubydoc.info/gems/highline/HighLine:color_code HighLine#color_code
+      #
+      def color_code(*args)
+        highline.color_code(*args)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine:uncolor HighLine#uncolor
+      #
+      def uncolor(*args)
+        highline.uncolor(*args)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine:new_scope HighLine#new_scope
       #
-      def newline(*args, &block)
-        highline.newline(*args, &block)
+      def new_scope
+        highline.new_scope
       end
     end
   end

data/lib/toys/standard_mixins/terminal.rb

@@ -32,7 +32,9 @@ module Toys
     ##
     # A mixin that provides a simple terminal. It includes a set of methods
     # that produce styled output, get user input, and otherwise interact with
-    # the user's terminal.
+    # the user's terminal. This mixin is not as richly featured as other mixins
+    # such as Highline, but it has no gem dependencies so is ideal for basic
+    # cases.
     #
     # You may make these methods available to your tool by including the
     # following directive in your tool configuration:
@@ -40,12 +42,24 @@ module Toys
     #     include :terminal
     #
     module Terminal
+      include Mixin
+
+      ##
+      # Context key for the terminal object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      to_initialize do |opts = {}|
+        self[KEY] = Utils::Terminal.new(opts)
+      end
+
       ##
       # Returns a global terminal instance
       # @return [Toys::Utils::Terminal]
       #
       def terminal
-        self[Terminal] ||= Utils::Terminal.new
+        self[KEY]
       end
 
       ##

data/lib/toys/template.rb

@@ -77,7 +77,7 @@ module Toys
   #       to_expand do |template|
   #         desc "Prints a greeting to #{template.name}"
   #         tool "templated-greeting" do
-  #           run do
+  #           to_run do
   #             puts "Hello, #{template.name}!"
   #           end
   #         end
@@ -112,7 +112,7 @@ module Toys
       # Provide the block that implements the template.
       #
       def to_expand(&block)
-        @expander = block
+        self.expander = block
       end
 
       ##

data/lib/toys/tool.rb

@@ -257,18 +257,6 @@ module Toys
       end
     end
 
-    ##
-    # Returns the value of the given option. Returns only options with string
-    # or symbol keys; returns `nil` if passed other well-known context keys
-    # such as verbosity.
-    #
-    # @param [String,Symbol] key
-    # @return [Object]
-    #
-    def option(key)
-      key.is_a?(::Symbol) || key.is_a?(::String) ? @__data[key] : nil
-    end
-
     ##
     # Activate the given gem. If it is not present, attempt to install it (or
     # inform the user to update the bundle).

data/lib/toys-core.rb

@@ -75,6 +75,7 @@ require "toys/errors"
 require "toys/input_file"
 require "toys/loader"
 require "toys/middleware"
+require "toys/mixin"
 require "toys/runner"
 require "toys/template"
 require "toys/tool"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.3.9.1
+  version: 0.3.10
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-25 00:00:00.000000000 Z
+date: 2018-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -108,6 +108,7 @@ files:
 - lib/toys/input_file.rb
 - lib/toys/loader.rb
 - lib/toys/middleware.rb
+- lib/toys/mixin.rb
 - lib/toys/runner.rb
 - lib/toys/standard_middleware/add_verbosity_flags.rb
 - lib/toys/standard_middleware/handle_usage_errors.rb