toys-core 0.3.5 → 0.3.6

data/lib/toys/core_version.rb

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

data/lib/toys/helpers/exec.rb

@@ -62,7 +62,7 @@ module Toys
       #     configuration options in the {Toys::Utils::Exec} docs.
       #
       def configure_exec(opts = {})
-        self[Exec].config_defaults(opts)
+        self[Exec].configure_defaults(opts)
       end
 
       ##

data/lib/toys/helpers/highline.rb

@@ -35,20 +35,15 @@ module Toys
     # A module that provides access to highline.
     #
     module Highline
-      ##
-      # Returns a global highline instance
-      # @return [::HighLine]
-      #
-      def self.highline
-        @highline ||= ::HighLine.new
-      end
-
       ##
       # Returns a global highline instance
       # @return [::HighLine]
       #
       def highline
-        Highline.highline
+        self[Highline] ||= begin
+          ::HighLine.use_color = $stdout.tty?
+          ::HighLine.new
+        end
       end
 
       ##

data/lib/toys/middleware/add_verbosity_flags.rb

@@ -89,10 +89,10 @@ module Toys
         unless verbose_flags.empty?
           long_desc = "Increase verbosity, causing additional logging levels to display."
           tool.add_flag(Context::VERBOSITY, verbose_flags,
-                        desc: "Increase verbosity",
-                        long_desc: long_desc,
+                        report_collisions: false,
                         handler: ->(_val, cur) { cur + 1 },
-                        only_unique: true)
+                        desc: "Increase verbosity",
+                        long_desc: long_desc)
         end
       end
 
@@ -102,10 +102,10 @@ module Toys
         unless quiet_flags.empty?
           long_desc = "Decrease verbosity, causing fewer logging levels to display."
           tool.add_flag(Context::VERBOSITY, quiet_flags,
-                        desc: "Decrease verbosity",
-                        long_desc: long_desc,
+                        report_collisions: false,
                         handler: ->(_val, cur) { cur - 1 },
-                        only_unique: true)
+                        desc: "Decrease verbosity",
+                        long_desc: long_desc)
         end
       end
     end

data/lib/toys/middleware/set_default_descriptions.rb

@@ -32,9 +32,12 @@ require "toys/middleware/base"
 module Toys
   module Middleware
     ##
-    # This middleware sets default description fields for tools that do not
-    # have them set otherwise. You can set separate descriptions for tools,
-    # namespaces, and the root.
+    # This middleware sets default description fields for tools and command
+    # line arguments and flags that do not have them set otherwise.
+    #
+    # You can modify the static descriptions for tools, namespaces, and the
+    # root tool by passing parameters to this middleware. For finer control,
+    # you can override methods to modify the description generation logic.
     #
     class SetDefaultDescriptions < Base
       ##
@@ -59,34 +62,25 @@ module Toys
       # The default long description for the root tool.
       # @return [String]
       #
-      DEFAULT_ROOT_LONG_DESC =
+      DEFAULT_ROOT_LONG_DESC = [
         "This command line tool was built using the toys-core gem. See" \
-        " https://www.rubydoc.info/gems/toys-core for more info. To replace this message," \
-        " configure the SetDefaultDescriptions middleware.".freeze
-
-      ##
-      # The default description for flags.
-      # @return [String]
-      #
-      DEFAULT_FLAG_DESC = "(No flag description available)".freeze
-
-      ##
-      # The default description for required args.
-      # @return [String]
-      #
-      DEFAULT_REQUIRED_ARG_DESC = "(Required argument - no description available)".freeze
-
-      ##
-      # The default description for optional args.
-      # @return [String]
-      #
-      DEFAULT_OPTIONAL_ARG_DESC = "(Optional argument - no description available)".freeze
+          " https://www.rubydoc.info/gems/toys-core for more info.",
+        "To replace this message, configure the SetDefaultDescriptions middleware."
+      ].freeze
 
       ##
-      # The default description for remaining args.
-      # @return [String]
+      # A mapping of names for acceptable types
+      # @return [Hash]
       #
-      DEFAULT_REMAINING_ARG_DESC = "(Remaining arguments - no description available)".freeze
+      ACCEPTABLE_NAMES = {
+        nil => "string",
+        ::String => "nonempty string",
+        ::TrueClass => "boolean",
+        ::FalseClass => "boolean",
+        ::OptionParser::DecimalInteger => "decimal integer",
+        ::OptionParser::OctalInteger => "octal integer",
+        ::OptionParser::DecimalNumeric => "decimal numeric"
+      }.freeze
 
       ##
       # Create a SetDefaultDescriptions middleware given default descriptions.
@@ -109,100 +103,176 @@ module Toys
       # @param [String,nil] default_root_long_desc The default long description
       #     for the root tool, or `nil` not to set one. Defaults to
       #     {DEFAULT_ROOT_LONG_DESC}.
-      # @param [String,nil] default_flag_desc The default short description for
-      #     flags, or `nil` not to set one. Defaults to {DEFAULT_FLAG_DESC}.
-      # @param [String,nil] default_flag_long_desc The default long description
-      #     for flags, or `nil` not to set one. Defaults to `nil`.
-      # @param [String,nil] default_required_arg_desc The default short
-      #     description for required args, or `nil` not to set one. Defaults to
-      #     {DEFAULT_REQUIRED_ARG_DESC}.
-      # @param [String,nil] default_required_arg_long_desc The default long
-      #     description for required args, or `nil` not to set one. Defaults to
-      #     `nil`.
-      # @param [String,nil] default_optional_arg_desc The default short
-      #     description for optional args, or `nil` not to set one. Defaults to
-      #     {DEFAULT_OPTIONAL_ARG_DESC}.
-      # @param [String,nil] default_optional_arg_long_desc The default long
-      #     description for optional args, or `nil` not to set one. Defaults to
-      #     `nil`.
-      # @param [String,nil] default_remaining_arg_desc The default short
-      #     description for remaining args, or `nil` not to set one. Defaults
-      #     to {DEFAULT_REMAINING_ARG_DESC}.
-      # @param [String,nil] default_remaining_arg_long_desc The default long
-      #     description for remaining args, or `nil` not to set one. Defaults
-      #     to `nil`.
       #
       def initialize(default_tool_desc: DEFAULT_TOOL_DESC,
                      default_tool_long_desc: nil,
                      default_namespace_desc: DEFAULT_NAMESPACE_DESC,
                      default_namespace_long_desc: nil,
                      default_root_desc: DEFAULT_ROOT_DESC,
-                     default_root_long_desc: DEFAULT_ROOT_LONG_DESC,
-                     default_flag_desc: DEFAULT_FLAG_DESC,
-                     default_flag_long_desc: nil,
-                     default_required_arg_desc: DEFAULT_REQUIRED_ARG_DESC,
-                     default_required_arg_long_desc: nil,
-                     default_optional_arg_desc: DEFAULT_OPTIONAL_ARG_DESC,
-                     default_optional_arg_long_desc: nil,
-                     default_remaining_arg_desc: DEFAULT_REMAINING_ARG_DESC,
-                     default_remaining_arg_long_desc: nil)
+                     default_root_long_desc: DEFAULT_ROOT_LONG_DESC)
         @default_tool_desc = default_tool_desc
         @default_tool_long_desc = default_tool_long_desc
         @default_namespace_desc = default_namespace_desc
         @default_namespace_long_desc = default_namespace_long_desc
         @default_root_desc = default_root_desc
         @default_root_long_desc = default_root_long_desc
-        @default_flag_desc = default_flag_desc
-        @default_flag_long_desc = default_flag_long_desc
-        @default_required_arg_desc = default_required_arg_desc
-        @default_required_arg_long_desc = default_required_arg_long_desc
-        @default_optional_arg_desc = default_optional_arg_desc
-        @default_optional_arg_long_desc = default_optional_arg_long_desc
-        @default_remaining_arg_desc = default_remaining_arg_desc
-        @default_remaining_arg_long_desc = default_remaining_arg_long_desc
       end
 
       ##
       # Add default description text to tools.
       #
-      def config(tool, _loader)
-        if tool.root?
-          config_descs(tool, @default_root_desc, @default_root_long_desc)
-        elsif tool.includes_script?
-          config_descs(tool, @default_tool_desc, @default_tool_long_desc)
-        else
-          config_descs(tool, @default_namespace_desc, @default_namespace_long_desc)
-        end
+      def config(tool, loader)
+        data = {tool: tool, loader: loader}
         tool.flag_definitions.each do |flag|
-          config_descs(flag, @default_flag_desc, @default_flag_long_desc)
+          config_desc(flag, generate_flag_desc(flag, data), generate_flag_long_desc(flag, data))
+        end
+        tool.arg_definitions.each do |arg|
+          config_desc(arg, generate_arg_desc(arg, data), generate_arg_long_desc(arg, data))
         end
-        config_args(tool)
+        config_desc(tool, generate_tool_desc(tool, data), generate_tool_long_desc(tool, data))
         yield
       end
 
-      private
+      protected
 
-      def config_args(tool)
-        tool.required_arg_definitions.each do |arg|
-          config_descs(arg, @default_required_arg_desc, @default_required_arg_long_desc)
-        end
-        tool.optional_arg_definitions.each do |arg|
-          config_descs(arg, @default_optional_arg_desc, @default_optional_arg_long_desc)
-        end
-        if tool.remaining_args_definition
-          config_descs(tool.remaining_args_definition,
-                       @default_remaining_arg_desc, @default_remaining_arg_long_desc)
+      ##
+      # This method implements the logic for generating a tool description.
+      # By default, it uses the parameters given to the middleware object.
+      # Override this method to provide different logic.
+      #
+      # @param [Toys::Tool] tool The tool to document.
+      # @param [Hash] data Additional data that might be useful. Currently,
+      #     the {Toys::Loader} is passed with key `:loader`. Future versions
+      #     of Toys may provide additional information.
+      # @return [String,Array<String>,Toys::Utils::WrappableString,nil] The
+      #     default description, or `nil` not to set a default. See
+      #     {Toys::Tool#desc=} for info on the format.
+      #
+      def generate_tool_desc(tool, data)
+        if tool.root?
+          @default_root_desc
+        elsif !tool.includes_script? && data[:loader].has_subtools?(tool.full_name)
+          @default_namespace_desc
+        else
+          @default_tool_desc
         end
       end
 
-      def config_descs(object, default_desc, default_long_desc)
-        if default_desc && object.desc.empty?
-          object.desc = default_desc
+      ##
+      # This method implements logic for generating a tool long description.
+      # By default, it uses the parameters given to the middleware object.
+      # Override this method to provide different logic.
+      #
+      # @param [Toys::Tool] tool The tool to document
+      # @param [Hash] data Additional data that might be useful. Currently,
+      #     the {Toys::Loader} is passed with key `:loader`. Future versions
+      #     of Toys may provide additional information.
+      # @return [Array<Toys::Utils::WrappableString,String,Array<String>>,nil]
+      #     The default long description, or `nil` not to set a default. See
+      #     {Toys::Tool#long_desc=} for info on the format.
+      #
+      def generate_tool_long_desc(tool, data)
+        if tool.root?
+          @default_root_long_desc
+        elsif !tool.includes_script? && data[:loader].has_subtools?(tool.full_name)
+          @default_namespace_long_desc
+        else
+          @default_tool_long_desc
         end
-        if default_long_desc && object.long_desc.empty?
-          object.long_desc = default_long_desc
+      end
+
+      ##
+      # This method implements the logic for generating a flag description.
+      # Override this method to provide different logic.
+      #
+      # @param [Toys::Tool::FlagDefinition] flag The flag to document
+      # @param [Hash] data Additional data that might be useful. Currently,
+      #     the {Toys::Tool} is passed with key `:tool`. Future versions of
+      #     Toys may provide additional information.
+      # @return [String,Array<String>,Toys::Utils::WrappableString,nil] The
+      #     default description, or `nil` not to set a default. See
+      #     {Toys::Tool#desc=} for info on the format.
+      #
+      def generate_flag_desc(flag, data) # rubocop:disable Lint/UnusedMethodArgument
+        name = flag.key.to_s.tr("_", "-").gsub(/[^\w-]/, "").downcase.inspect
+        acceptable = flag.flag_type == :value ? acceptable_name(flag.accept) : "boolean flag"
+        default_clause = flag.default ? " (default is #{flag.default.inspect})" : ""
+        "Sets the #{name} option as type #{acceptable}#{default_clause}."
+      end
+
+      ##
+      # This method implements logic for generating a flag long description.
+      # Override this method to provide different logic.
+      #
+      # @param [Toys::Tool::FlagDefinition] flag The flag to document
+      # @param [Hash] data Additional data that might be useful. Currently,
+      #     the {Toys::Tool} is passed with key `:tool`. Future versions of
+      #     Toys may provide additional information.
+      # @return [Array<Toys::Utils::WrappableString,String,Array<String>>,nil]
+      #     The default long description, or `nil` not to set a default. See
+      #     {Toys::Tool#long_desc=} for info on the format.
+      #
+      def generate_flag_long_desc(flag, data) # rubocop:disable Lint/UnusedMethodArgument
+        nil
+      end
+
+      ##
+      # This method implements the logic for generating an arg description.
+      # Override this method to provide different logic.
+      #
+      # @param [Toys::Tool::ArgDefinition] arg The arg to document
+      # @param [Hash] data Additional data that might be useful. Currently,
+      #     the {Toys::Tool} is passed with key `:tool`. Future versions of
+      #     Toys may provide additional information.
+      # @return [String,Array<String>,Toys::Utils::WrappableString,nil] The
+      #     default description, or `nil` not to set a default. See
+      #     {Toys::Tool#desc=} for info on the format.
+      #
+      def generate_arg_desc(arg, data) # rubocop:disable Lint/UnusedMethodArgument
+        acceptable = acceptable_name(arg.accept)
+        default_clause = arg.default ? " (default is #{arg.default.inspect})" : ""
+        case arg.type
+        when :required
+          "Required #{acceptable} argument."
+        when :optional
+          "Optional #{acceptable} argument#{default_clause}."
+        else
+          "Remaining arguments are type #{acceptable}#{default_clause}."
         end
       end
+
+      ##
+      # This method implements logic for generating an arg long description.
+      # Override this method to provide different logic.
+      #
+      # @param [Toys::Tool::ArgDefinition] arg The arg to document
+      # @param [Hash] data Additional data that might be useful. Currently,
+      #     the {Toys::Tool} is passed with key `:tool`. Future versions of
+      #     Toys may provide additional information.
+      # @return [Array<Toys::Utils::WrappableString,String,Array<String>>,nil]
+      #     The default long description, or `nil` not to set a default. See
+      #     {Toys::Tool#long_desc=} for info on the format.
+      #
+      def generate_arg_long_desc(arg, data) # rubocop:disable Lint/UnusedMethodArgument
+        nil
+      end
+
+      ##
+      # Return a reasonable name for an acceptor
+      #
+      # @param [Object] accept An acceptor to name
+      # @return [String]
+      #
+      def acceptable_name(accept)
+        ACCEPTABLE_NAMES[accept] || accept.to_s.downcase
+      end
+
+      private
+
+      def config_desc(object, desc, long_desc)
+        object.desc = desc if desc && object.desc.empty?
+        object.long_desc = long_desc if long_desc && object.long_desc.empty?
+      end
     end
   end
 end

data/lib/toys/middleware/show_help.rb

@@ -110,6 +110,8 @@ module Toys
       #     help or usage, and doesn't otherwise use positional arguments,
       #     then a tool name can be passed as arguments to display help for
       #     that tool.
+      # @param [Boolean] show_source_path Show the source path section. Default
+      #     is `false`.
       # @param [Boolean] use_less If the `less` tool is available, and the
       #     output stream is a tty, then use `less` to display help text.
       # @param [IO] stream Output stream to write to. Default is stdout.
@@ -124,6 +126,7 @@ module Toys
                      default_recursive: false,
                      fallback_execution: false,
                      allow_root_args: false,
+                     show_source_path: false,
                      use_less: false,
                      stream: $stdout,
                      styled_output: nil)
@@ -134,6 +137,7 @@ module Toys
         @default_recursive = default_recursive ? true : false
         @fallback_execution = fallback_execution
         @allow_root_args = allow_root_args
+        @show_source_path = show_source_path
         @stream = stream
         @styled_output = styled_output
         @use_less = use_less
@@ -171,6 +175,7 @@ module Toys
           help_text = get_help_text(context)
           str = help_text.help_string(recursive: context[:_recursive_subtools],
                                       search: context[:_search_subtools],
+                                      show_source_path: @show_source_path,
                                       wrap_width: output_cols)
           output_help(str)
         else
@@ -229,7 +234,7 @@ module Toys
                                                    DEFAULT_HELP_FLAGS)
         unless help_flags.empty?
           tool.add_flag(:_show_help, help_flags,
-                        desc: "Display help for this tool", only_unique: true)
+                        report_collisions: false, desc: "Display help for this tool")
         end
         help_flags
       end
@@ -239,7 +244,8 @@ module Toys
                                                     DEFAULT_USAGE_FLAGS)
         unless usage_flags.empty?
           tool.add_flag(:_show_usage, usage_flags,
-                        desc: "Display a brief usage string for this tool", only_unique: true)
+                        report_collisions: false,
+                        desc: "Display a brief usage string for this tool")
         end
         usage_flags
       end
@@ -249,9 +255,9 @@ module Toys
                                                         DEFAULT_RECURSIVE_FLAGS)
         unless recursive_flags.empty?
           tool.add_flag(:_recursive_subtools, recursive_flags,
+                        report_collisions: false,
                         default: @default_recursive,
-                        desc: "Show all subtools recursively (default is #{@default_recursive})",
-                        only_unique: true)
+                        desc: "Show all subtools recursively (default is #{@default_recursive})")
         end
       end
 
@@ -260,8 +266,8 @@ module Toys
                                                      DEFAULT_SEARCH_FLAGS)
         unless search_flags.empty?
           tool.add_flag(:_search_subtools, search_flags,
-                        desc: "Search subtools for the given regular expression",
-                        only_unique: true)
+                        report_collisions: false,
+                        desc: "Search subtools for the given regular expression")
         end
       end
     end