toys-core 0.3.2

data/lib/toys/utils/module_lookup.rb

@@ -0,0 +1,101 @@
+# 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
+  module Utils
+    ##
+    # A helper module that provides methods to do module lookups. This is
+    # used to obtain named helpers, middleware, and templates from the
+    # respective modules.
+    #
+    # You generally do not need to use these module methods directly. Instead
+    # use the convenience methods {Toys::Helpers.lookup},
+    # {Toys::Middleware.lookup}, or {Toys::Templates.lookup}.
+    #
+    module ModuleLookup
+      class << self
+        ##
+        # Convert the given string to a path element. Specifically, converts
+        # to `lower_snake_case`.
+        #
+        # @param [String,Symbol] str String to convert.
+        # @return [String] Converted string
+        #
+        def to_path_name(str)
+          str.to_s.gsub(/([a-zA-Z])([A-Z])/) { |_m| "#{$1}_#{$2.downcase}" }.downcase
+        end
+
+        ##
+        # Convert the given string to a module name. Specifically, converts
+        # to `UpperCamelCase`.
+        #
+        # @param [String,Symbol] str String to convert.
+        # @return [String] Converted string
+        #
+        def to_module_name(str)
+          str.to_s.gsub(/(^|_)([a-zA-Z0-9])/) { |_m| $2.upcase }
+        end
+
+        ##
+        # Obtain a named module from the given collection. Raises an exception
+        # on failure.
+        #
+        # @param [String,Symbol] collection The collection to search. Typical
+        #     values are `:helpers`, `:middleware`, and `:templates`.
+        # @param [String,Symbol] name The name of the module to return.
+        #
+        # @return [Module] The specified module
+        # @raise [LoadError] No Ruby file containing the given module could
+        #     be found.
+        # @raise [NameError] The given module was not defined.
+        #
+        def lookup!(collection, name)
+          require "toys/#{to_path_name(collection)}/#{to_path_name(name)}"
+          ::Toys.const_get(to_module_name(collection)).const_get(to_module_name(name))
+        end
+
+        ##
+        # Obtain a named module from the given collection. Returns `nil` on
+        # failure.
+        #
+        # @param [String,Symbol] collection The collection to search. Typical
+        #     values are `:helpers`, `:middleware`, and `:templates`.
+        # @param [String,Symbol] name The name of the module to return.
+        #
+        # @return [Module,nil] The specified module, or `nil` if not found.
+        #
+        def lookup(collection, name)
+          lookup!(collection, name)
+        rescue ::NameError, ::LoadError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/toys/utils/usage.rb

@@ -0,0 +1,196 @@
+# 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
+  module Utils
+    ##
+    # 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.
+      # @param [String,nil] search An optional string to search for when
+      #     listing subcommands. Defaults to `nil` which finds all subcommands.
+      # @param [Boolean] show_path If true, shows the path to the config file
+      #     containing the tool definition (if set). Defaults to false.
+      #
+      # @return [String] A usage string.
+      #
+      def string(recursive: false, search: nil, show_path: false)
+        optparse = ::OptionParser.new
+        optparse.banner = @tool.includes_executor? ? tool_banner : group_banner
+        unless @tool.effective_long_desc.empty?
+          optparse.separator("")
+          optparse.separator(@tool.effective_long_desc)
+        end
+        if show_path && @tool.definition_path
+          optparse.separator("")
+          optparse.separator("Defined in #{@tool.definition_path}")
+        end
+        add_switches(optparse)
+        if @tool.includes_executor?
+          add_positional_arguments(optparse)
+        else
+          add_command_list(optparse, recursive, search)
+        end
+        optparse.to_s
+      end
+
+      private
+
+      #
+      # Returns the banner string for a normal tool
+      #
+      def tool_banner
+        banner = ["Usage:", @binary_name] + @tool.full_name
+        banner << "[<options...>]" unless @tool.switch_definitions.empty?
+        @tool.required_arg_definitions.each do |arg_info|
+          banner << "<#{arg_info.canonical_name}>"
+        end
+        @tool.optional_arg_definitions.each do |arg_info|
+          banner << "[<#{arg_info.canonical_name}>]"
+        end
+        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
+        list = ["Usage:", @binary_name] +
+               @tool.full_name +
+               ["<command>", "<command-arguments...>"]
+        list.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.switch_definitions.empty?
+        optparse.separator("")
+        optparse.separator("Options:")
+        @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_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:")
+        args_to_display.each do |arg_info|
+          optparse.separator("    #{arg_info.canonical_name.ljust(31)}  #{arg_info.doc.first}")
+          (arg_info.doc[1..-1] || []).each do |d|
+            optparse.separator("                                     #{d}")
+          end
+        end
+      end
+
+      #
+      # Add documentation for the tool's subcommands, to the given option
+      # parser.
+      #
+      def add_command_list(optparse, recursive, search)
+        name_len = @tool.full_name.length
+        subtools = find_commands(recursive, search)
+        return if subtools.empty?
+        optparse.separator("")
+        if search
+          optparse.separator("Commands with search term #{search.inspect}:")
+        else
+          optparse.separator("Commands:")
+        end
+        subtools.each do |subtool|
+          tool_name = subtool.full_name.slice(name_len..-1).join(" ").ljust(31)
+          if subtool.is_a?(Alias)
+            optparse.separator("    #{tool_name}  (Alias of #{subtool.display_target})")
+          else
+            optparse.separator("    #{tool_name}  #{subtool.effective_desc}")
+          end
+        end
+      end
+
+      #
+      # Find subcommands of the current tool
+      #
+      def find_commands(recursive, search)
+        subtools = @loader.list_subtools(@tool.full_name, recursive: recursive)
+        return subtools if search.nil? || search.empty?
+        regex = Regexp.new("(^|\\s)#{Regexp.escape(search)}(\\s|$)", Regexp::IGNORECASE)
+        subtools.find_all do |tool|
+          regex =~ tool.display_name || regex =~ tool.effective_desc ||
+            regex =~ tool.effective_long_desc
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: toys-core
+version: !ruby/object:Gem::Version
+  version: 0.3.2
+platform: ruby
+authors:
+- Daniel Azuma
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-05-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.11'
+- !ruby/object:Gem::Dependency
+  name: minitest-focus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: minitest-rg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.55.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.55.0
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A simple command line tool framework
+email:
+- dazuma@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/toys-core.rb
+- lib/toys/alias.rb
+- lib/toys/cli.rb
+- lib/toys/config_dsl.rb
+- lib/toys/context.rb
+- lib/toys/core_version.rb
+- lib/toys/errors.rb
+- lib/toys/helpers.rb
+- lib/toys/helpers/exec.rb
+- lib/toys/helpers/file_utils.rb
+- lib/toys/loader.rb
+- lib/toys/middleware.rb
+- lib/toys/middleware/add_verbosity_switches.rb
+- lib/toys/middleware/base.rb
+- lib/toys/middleware/handle_usage_errors.rb
+- lib/toys/middleware/set_default_descriptions.rb
+- lib/toys/middleware/show_usage.rb
+- lib/toys/middleware/show_version.rb
+- lib/toys/template.rb
+- lib/toys/templates.rb
+- lib/toys/templates/clean.rb
+- lib/toys/templates/gem_build.rb
+- lib/toys/templates/minitest.rb
+- lib/toys/templates/rubocop.rb
+- lib/toys/templates/yardoc.rb
+- lib/toys/tool.rb
+- lib/toys/utils/module_lookup.rb
+- lib/toys/utils/usage.rb
+homepage: https://github.com/dazuma/toys
+licenses:
+- BSD-3-Clause
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Command line tool framework
+test_files: []