toys 0.3.0 → 0.3.1

data/lib/toys/utils/usage.rb

@@ -30,19 +30,45 @@
 module Toys
   module Utils
     ##
-    # Helper that generates usage text
+    # A helper class that generates usage documentation for a tool.
+    #
+    # This class generates full usage documentation, including description,
+    # switches, and arguments. It is used by middleware that implements help
+    # and related options.
     #
     class Usage
+      ##
+      # Create a usage helper given an execution context.
+      #
+      # @param [Toys::Context] context The current execution context.
+      # @return [Toys::Utils::Usage]
+      #
       def self.from_context(context)
         new(context[Context::TOOL], context[Context::BINARY_NAME], context[Context::LOADER])
       end
 
+      ##
+      # Create a usage helper.
+      #
+      # @param [Toys::Tool] tool The tool for which to generate documentation.
+      # @param [String] binary_name The name of the binary. e.g. `"toys"`.
+      # @param [Toys::Loader] loader A loader that can provide subcommands.
+      #
+      # @return [Toys::Utils::Usage]
+      #
       def initialize(tool, binary_name, loader)
         @tool = tool
         @binary_name = binary_name
         @loader = loader
       end
 
+      ##
+      # Generate a usage string.
+      #
+      # @param [Boolean] recursive If true, and the tool is a group tool,
+      #     display all subcommands recursively. Defaults to false.
+      # @return [String] A usage string.
+      #
       def string(recursive: false)
         optparse = ::OptionParser.new
         optparse.banner = @tool.includes_executor? ? tool_banner : group_banner
@@ -61,37 +87,51 @@ module Toys
 
       private
 
+      #
+      # Returns the banner string for a normal tool
+      #
       def tool_banner
         banner = ["Usage:", @binary_name] + @tool.full_name
-        banner << "[<options...>]" unless @tool.switches.empty?
-        @tool.required_args.each do |arg_info|
+        banner << "[<options...>]" unless @tool.switch_definitions.empty?
+        @tool.required_arg_definitions.each do |arg_info|
           banner << "<#{arg_info.canonical_name}>"
         end
-        @tool.optional_args.each do |arg_info|
+        @tool.optional_arg_definitions.each do |arg_info|
           banner << "[<#{arg_info.canonical_name}>]"
         end
-        if @tool.remaining_args
-          banner << "[<#{@tool.remaining_args.canonical_name}...>]"
+        if @tool.remaining_args_definition
+          banner << "[<#{@tool.remaining_args_definition.canonical_name}...>]"
         end
         banner.join(" ")
       end
 
+      #
+      # Returns the banner string for a group
+      #
       def group_banner
         (["Usage:", @binary_name] + @tool.full_name + ["<command>", "[<options...>]"]).join(" ")
       end
 
+      #
+      # Add switches from the tool to the given optionparser. Causes the
+      # optparser to generate documentation for those switches.
+      #
       def add_switches(optparse)
-        return if @tool.switches.empty?
+        return if @tool.switch_definitions.empty?
         optparse.separator("")
         optparse.separator("Options:")
-        @tool.switches.each do |switch|
+        @tool.switch_definitions.each do |switch|
           optparse.on(*switch.optparse_info)
         end
       end
 
+      #
+      # Add documentation for the tool's positional arguments, to the given
+      # option parser.
+      #
       def add_positional_arguments(optparse)
-        args_to_display = @tool.required_args + @tool.optional_args
-        args_to_display << @tool.remaining_args if @tool.remaining_args
+        args_to_display = @tool.required_arg_definitions + @tool.optional_arg_definitions
+        args_to_display << @tool.remaining_args_definition if @tool.remaining_args_definition
         return if args_to_display.empty?
         optparse.separator("")
         optparse.separator("Positional arguments:")
@@ -103,9 +143,13 @@ module Toys
         end
       end
 
+      #
+      # Add documentation for the tool's subcommands, to the given option
+      # parser.
+      #
       def add_command_list(optparse, recursive)
         name_len = @tool.full_name.length
-        subtools = @loader.list_subtools(@tool.full_name, recursive)
+        subtools = @loader.list_subtools(@tool.full_name, recursive: recursive)
         return if subtools.empty?
         optparse.separator("")
         optparse.separator("Commands:")

data/lib/toys/version.rb

@@ -32,5 +32,5 @@ module Toys
   # Current version of Toys
   # @return [String]
   #
-  VERSION = "0.3.0".freeze
+  VERSION = "0.3.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-01 00:00:00.000000000 Z
+date: 2018-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -88,15 +88,16 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.md
 - README.md
 - bin/toys
 - lib/toys.rb
-- lib/toys/builder.rb
 - lib/toys/builtins/do.rb
 - lib/toys/builtins/system.rb
 - lib/toys/cli.rb
+- lib/toys/config_dsl.rb
 - lib/toys/context.rb
 - lib/toys/errors.rb
 - lib/toys/helpers.rb
@@ -105,9 +106,9 @@ files:
 - lib/toys/loader.rb
 - lib/toys/middleware.rb
 - lib/toys/middleware/base.rb
-- lib/toys/middleware/group_default.rb
 - lib/toys/middleware/set_verbosity.rb
-- lib/toys/middleware/show_tool_help.rb
+- lib/toys/middleware/show_group_usage.rb
+- lib/toys/middleware/show_tool_usage.rb
 - lib/toys/middleware/show_usage_errors.rb
 - lib/toys/template.rb
 - lib/toys/templates.rb

data/lib/toys/builder.rb

@@ -1,227 +0,0 @@
-# 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
-  ##
-  # The object context in effect in a toys configuration file
-  #
-  class Builder
-    def initialize(path, tool, remaining_words, priority, loader, type)
-      @path = path
-      @tool = tool
-      @remaining_words = remaining_words
-      @priority = priority
-      @loader = loader
-      @type = type
-    end
-
-    def tool(word, alias_of: nil, &block)
-      word = word.to_s
-      subtool = @loader.get_tool(@tool.full_name + [word], @priority, assume_parent: true)
-      return self if subtool.nil?
-      if alias_of
-        if block
-          raise ToolDefinitionError, "Cannot take a block with alias_of"
-        end
-        subtool.make_alias_of_word(alias_of.to_s)
-        return self
-      end
-      next_remaining = Loader.next_remaining_words(@remaining_words, word)
-      Builder.build(@path, subtool, next_remaining, @priority, @loader, block, :tool)
-      self
-    end
-    alias name tool
-
-    def append(word, &block)
-      word = word.to_s
-      subtool = @loader.get_tool(@tool.full_name + [word], nil, assume_parent: true)
-      next_remaining = Loader.next_remaining_words(@remaining_words, word)
-      Builder.build(@path, subtool, next_remaining, @priority, @loader, block, :append)
-      self
-    end
-
-    def group(word, &block)
-      word = word.to_s
-      subtool = @loader.get_tool(@tool.full_name + [word], @priority, assume_parent: true)
-      return self if subtool.nil?
-      next_remaining = Loader.next_remaining_words(@remaining_words, word)
-      Builder.build(@path, subtool, next_remaining, @priority, @loader, block, :group)
-      self
-    end
-
-    def alias_as(word)
-      if @tool.root?
-        raise ToolDefinitionError, "Cannot make an alias of the root tool"
-      end
-      if @type == :group || @type == :append
-        raise ToolDefinitionError, "Cannot make an alias of a group"
-      end
-      alias_name = @tool.full_name.slice(0..-2) + [word.to_s]
-      alias_tool = @loader.get_tool(alias_name, @priority)
-      alias_tool.make_alias_of(@tool.simple_name) if alias_tool
-      self
-    end
-
-    def alias_of(word)
-      if @tool.root?
-        raise ToolDefinitionError, "Cannot make the root tool an alias"
-      end
-      if @type == :group || @type == :append
-        raise ToolDefinitionError, "Cannot make a group an alias"
-      end
-      @tool.make_alias_of(word.to_s)
-      self
-    end
-
-    def include(path)
-      @tool.yield_definition do
-        @loader.include_path(path, @tool.full_name, @remaining_words, @priority)
-      end
-      self
-    end
-
-    def expand(template_class, *args)
-      unless template_class.is_a?(::Class)
-        name = template_class.to_s
-        template_class = Templates.lookup(name)
-        if template_class.nil?
-          raise ToolDefinitionError, "Template not found: #{name.inspect}"
-        end
-      end
-      template = template_class.new(*args)
-      yield template if block_given?
-      instance_exec(template, &template_class.expander)
-      self
-    end
-
-    def long_desc(desc)
-      if @type == :append
-        raise ToolDefinitionError, "Cannot set the description when appending"
-      end
-      @tool.long_desc = desc
-      self
-    end
-
-    def desc(desc)
-      if @type == :append
-        raise ToolDefinitionError, "Cannot set the description when appending"
-      end
-      @tool.desc = desc
-      self
-    end
-    alias short_desc desc
-
-    def switch(key, *switches,
-               accept: nil, default: nil, doc: nil, only_unique: false, handler: nil)
-      if @type == :append
-        raise ToolDefinitionError, "Cannot add a switch when appending"
-      end
-      @tool.add_switch(key, *switches,
-                       accept: accept, default: default, doc: doc,
-                       only_unique: only_unique, handler: handler)
-      self
-    end
-
-    def required_arg(key, accept: nil, doc: nil)
-      if @type == :append
-        raise ToolDefinitionError, "Cannot add an argument when appending"
-      end
-      @tool.add_required_arg(key, accept: accept, doc: doc)
-      self
-    end
-
-    def optional_arg(key, accept: nil, default: nil, doc: nil)
-      if @type == :append
-        raise ToolDefinitionError, "Cannot add an argument when appending"
-      end
-      @tool.add_optional_arg(key, accept: accept, default: default, doc: doc)
-      self
-    end
-
-    def remaining_args(key, accept: nil, default: [], doc: nil)
-      if @type == :append
-        raise ToolDefinitionError, "Cannot add an argument when appending"
-      end
-      @tool.set_remaining_args(key, accept: accept, default: default, doc: doc)
-      self
-    end
-
-    def execute(&block)
-      if @type == :group || @type == :append
-        raise ToolDefinitionError, "Cannot set the executor of a group"
-      end
-      @tool.executor = block
-      self
-    end
-
-    def helper(name, &block)
-      if @type == :group || @type == :append
-        raise ToolDefinitionError, "Cannot define a helper method to a group"
-      end
-      @tool.add_helper(name, &block)
-      self
-    end
-
-    def use(mod)
-      if @type == :group || @type == :append
-        raise ToolDefinitionError, "Cannot use a helper module in a group"
-      end
-      @tool.use_module(mod)
-      self
-    end
-
-    def _binding
-      binding
-    end
-
-    def self.build(path, tool, remaining_words, priority, loader, source, type)
-      builder = new(path, tool, remaining_words, priority, loader, type)
-      if type == :append
-        eval_source(builder, path, source)
-      else
-        tool.defining_from(path) do
-          eval_source(builder, path, source)
-          tool.finish_definition
-        end
-      end
-      tool
-    end
-
-    def self.eval_source(builder, path, source)
-      case source
-      when String
-        # rubocop:disable Security/Eval
-        eval(source, builder._binding, path, 1)
-        # rubocop:enable Security/Eval
-      when ::Proc
-        builder.instance_eval(&source)
-      end
-    end
-  end
-end