tty-option 0.2.0 → 0.3.0

data/lib/tty/option/formatter.rb

@@ -5,30 +5,55 @@ require_relative "usage_wrapper"
 
 module TTY
   module Option
+    # Responsible for formatting help display
+    #
+    # @api private
     class Formatter
       include UsageWrapper
 
-      SHORT_OPT_LENGTH = 4
+      BOOLEANS = [true, false].freeze
       DEFAULT_WIDTH = 80
-      NEWLINE = "\n"
+      DOUBLE_SPACE = "  "
       ELLIPSIS = "..."
+      EMPTY = ""
+      LIST_SEPARATOR = ", "
+      MAP_SEPARATOR = ":"
+      NEWLINE = "\n"
       SPACE = " "
 
-      DEFAULT_PARAM_DISPLAY = ->(str) { str.to_s.upcase }
+      DEFAULT_NAME_SELECTOR = ->(param) { param.name }
       DEFAULT_ORDER = ->(params) { params.sort }
+      DEFAULT_PARAM_DISPLAY = ->(str) { str.to_s.upcase }
       NOOP_PROC = ->(param) { param }
-      DEFAULT_NAME_SELECTOR = ->(param) { param.name }
 
+      # Generate help for parameters and usage
+      #
+      # @param [TTY::Option::Parameters] parameters
+      #   the parameters to format
+      # @param [TTY::Option::Usage] usage
+      #   the usage to format
+      #
+      # @return [String]
+      #
       # @api public
       def self.help(parameters, usage, **config, &block)
         new(parameters, usage, **config).help(&block)
       end
 
-      attr_reader :width
-
-      # Create a help formatter
+      # Create a Formatter instance
       #
-      # @param [Parameters]
+      # @param [TTY::Option::Parameters] parameters
+      #   the parameters to format
+      # @param [TTY::Option::Usage] usage
+      #   the usage to format
+      # @param [Proc] param_display
+      #   the parameter display formatter, by default, uppercases all chars
+      # @param [Integer] width
+      #   the width at which to wrap the help display, by default 80 columns
+      # @param [Proc] order
+      #   the order for displaying parameters, by default alphabetical
+      # @param [Integer] indent
+      #   the indent for help display
       #
       # @api public
       def initialize(parameters, usage, param_display: DEFAULT_PARAM_DISPLAY,
@@ -51,7 +76,10 @@ module TTY
         }
       end
 
-      # A formatted help usage information
+      # Generate help display
+      #
+      # @example
+      #   formatter.help
       #
       # @yieldparam [TTY::Option::Sections] sections
       #
@@ -90,18 +118,50 @@ module TTY
         formatted.end_with?(NEWLINE) ? formatted : formatted + NEWLINE
       end
 
+      # Generate help header
+      #
+      # @example
+      #   formatter.help_header
+      #
+      # @return [String]
+      #
+      # @api public
       def help_header
         "#{format_multiline(@usage.header, @indent)}#{NEWLINE}"
       end
 
+      # Generate help banner
+      #
+      # @example
+      #   formatter.help_banner
+      #
+      # @return [String]
+      #
+      # @api public
       def help_banner
         (@usage.banner? ? @usage.banner : format_usage)
       end
 
+      # Generate help description
+      #
+      # @example
+      #   formatter.help_description
+      #
+      # @return [String]
+      #
+      # @api public
       def help_description
         "#{NEWLINE}#{format_description}"
       end
 
+      # Generate help arguments
+      #
+      # @example
+      #   formatter.help_arguments
+      #
+      # @return [String]
+      #
+      # @api public
       def help_arguments
         "#{NEWLINE}#{@space_indent}#{@section_names[:arguments]}#{NEWLINE}" +
           format_section(@parameters.arguments, ->(param) do
@@ -109,6 +169,14 @@ module TTY
           end)
       end
 
+      # Generate help keywords
+      #
+      # @example
+      #   formatter.help_keywords
+      #
+      # @return [String]
+      #
+      # @api public
       def help_keywords
         "#{NEWLINE}#{@space_indent}#{@section_names[:keywords]}#{NEWLINE}" +
           format_section(@parameters.keywords, ->(param) do
@@ -116,28 +184,62 @@ module TTY
           end)
       end
 
+      # Generate help options
+      #
+      # @example
+      #   formatter.help_options
+      #
+      # @return [String]
+      #
+      # @api public
       def help_options
         "#{NEWLINE}#{@space_indent}#{@section_names[:options]}#{NEWLINE}" +
           format_options
       end
 
+      # Generate help environment variables
+      #
+      # @example
+      #   formatter.help_environments
+      #
+      # @return [String]
+      #
+      # @api public
       def help_environments
         "#{NEWLINE}#{@space_indent}#{@section_names[:env]}#{NEWLINE}" +
           format_section(@order.(@parameters.environments))
       end
 
+      # Generate help examples
+      #
+      # @example
+      #   formatter.help_examples
+      #
+      # @return [String]
+      #
+      # @api public
       def help_examples
         "#{NEWLINE}#{@space_indent}#{@section_names[:examples]}#{NEWLINE}" +
           format_examples
       end
 
+      # Generate help footer
+      #
+      # @example
+      #   formatter.help_footer
+      #
+      # @return [String]
+      #
+      # @api public
       def help_footer
         "#{NEWLINE}#{format_multiline(@usage.footer, @indent)}"
       end
 
       private
 
-      # Provide a default usage banner
+      # Format default usage banner
+      #
+      # @return [String]
       #
       # @api private
       def format_usage
@@ -149,10 +251,12 @@ module TTY
         output << " [#{@param_display.("environment")}]" if @parameters.environments?
         output << " #{format_arguments_usage}" if @parameters.arguments?
         output << " #{format_keywords_usage}" if @parameters.keywords?
-        usage + wrap(output.join, indent: usage.length, width: width)
+        usage + wrap(output.join, indent: usage.length, width: @width)
       end
 
-      # Format arguments
+      # Format arguments usage
+      #
+      # @return [String]
       #
       # @api private
       def format_arguments_usage
@@ -165,7 +269,12 @@ module TTY
         end.join(SPACE)
       end
 
-      # Provide an argument summary
+      # Format argument usage
+      #
+      # @param [TTY::Option::Parameter::Argument] arg
+      #   the argument to format
+      #
+      # @return [String]
       #
       # @api private
       def format_argument_usage(arg)
@@ -175,6 +284,13 @@ module TTY
 
       # Format parameter usage
       #
+      # @param [TTY::Option::Parameter] param
+      #   the parameter to format
+      # @param [String] param_name
+      #   the parameter name
+      #
+      # @return [String]
+      #
       # @api private
       def format_parameter_usage(param, param_name)
         args = []
@@ -193,6 +309,8 @@ module TTY
 
       # Format keywords usage
       #
+      # @return [String]
+      #
       # @api private
       def format_keywords_usage
         return "" unless @parameters.keywords?
@@ -204,7 +322,12 @@ module TTY
         end.join(SPACE)
       end
 
-      # Provide a keyword summary
+      # Format keyword usage
+      #
+      # @param [TTY::Option::Parameter::Keyword] kwarg
+      #   the keyword to format
+      #
+      # @return [String]
       #
       # @api private
       def format_keyword_usage(kwarg)
@@ -212,7 +335,14 @@ module TTY
         format_parameter_usage(kwarg, param_name)
       end
 
-      # Provide a keyword argument display format
+      # Format keyword name
+      #
+      # @param [TTY::Option::Parameter::Keyword] kwarg
+      #   the keyword to format
+      # @param [Proc] param_display
+      #   the parameter display formatter, by default, uppercases all chars
+      #
+      # @return [String]
       #
       # @api private
       def kwarg_param_display(kwarg, param_display = NOOP_PROC)
@@ -227,19 +357,18 @@ module TTY
         "#{kwarg_name}=#{conv_name}"
       end
 
-      # Format a parameter section in the help display
-      #
-      # @param [String] parameters_name
-      #   the name of parameter type
+      # Format section parameters
       #
+      # @param [Array<TTY::Option::Parameter>] params
+      #   the parameters to format
       # @param [Proc] name_selector
-      #   selects a name from the parameter, by defeault the name
+      #   the parameter name selector, by default, calls the name
       #
       # @return [String]
       #
       # @api private
       def format_section(params, name_selector = DEFAULT_NAME_SELECTOR)
-        longest_param = params.map(&name_selector).compact.max_by(&:length).length
+        longest_param = find_longest_parameter(params, &name_selector)
 
         params.reduce([]) do |acc, param|
           next acc if param.hidden?
@@ -248,44 +377,45 @@ module TTY
         end.join(NEWLINE)
       end
 
-      # Format a section parameter line
+      # Format section parameter
+      #
+      # @param [TTY::Option::Parameter] param
+      #   the parameter to format
+      # @param [Integer] longest_param
+      #   the longest parameter length
+      # @param [Proc] name_selector
+      #   the parameter name selector, by default, calls the name
       #
       # @return [String]
       #
       # @api private
       def format_section_parameter(param, longest_param, name_selector)
         line = []
-        desc = []
-        indent = @param_indent + longest_param + 2
         param_name = name_selector.(param)
+        description = parameter_description?(param)
+        template = description ? "%s%-#{longest_param}s" : "%s%s"
 
-        if param.desc?
-          line << format("%s%-#{longest_param}s", SPACE * @param_indent, param_name)
-          desc << "  #{param.desc}"
-        else
-          line << format("%s%s", SPACE * @param_indent, param_name)
-        end
+        line << format(template, SPACE * @param_indent, param_name)
 
-        if param.permit?
-          desc << format(" (permitted: %s)", param.permit.join(", "))
+        if description
+          desc = format_parameter_description(param)
+          indent = @param_indent + longest_param + 2
+          line << wrap(desc, indent: indent, width: @width)
         end
 
-        if (default = format_default(param))
-          desc << default
-        end
-
-        line << wrap(desc.join, indent: indent, width: width)
         line.join
       end
 
       # Format multiline description
       #
+      # @return [String]
+      #
       # @api private
       def format_description
         format_multiline(@usage.desc, @indent)
       end
 
-      # Returns all the options formatted to fit 80 columns
+      # Format options
       #
       # @return [String]
       #
@@ -293,69 +423,225 @@ module TTY
       def format_options
         return "" if @parameters.options.empty?
 
-        longest_option = @parameters.options.map(&:long)
-                                    .compact.max_by(&:length).length
-        any_short = @parameters.options.map(&:short).compact.any?
         ordered_options = @order.(@parameters.options)
+        longest_short = find_longest_short_option
+        longest_long = find_longest_long_option
 
         ordered_options.reduce([]) do |acc, option|
           next acc if option.hidden?
-          acc << format_option(option, longest_option, any_short)
+
+          acc << format_option(option, longest_short, longest_long)
         end.join(NEWLINE)
       end
 
+      # Find the longest short option
+      #
+      # @return [Integer, nil]
+      #
+      # @api private
+      def find_longest_short_option
+        short_options = @parameters.options.select(&:short?)
+        find_longest_parameter(short_options) do |option|
+          option.long? ? option.short_name : option.short
+        end
+      end
+
+      # Find the longest long option
+      #
+      # @return [Integer, nil]
+      #
+      # @api private
+      def find_longest_long_option
+        long_options = @parameters.options.select(&:long?)
+        find_longest_parameter(long_options, &:long)
+      end
+
+      # Find the longest parameter
+      #
+      # @param [Array<TTY::Option::Parameter>] params
+      #   the parameters to search
+      #
+      # @yield [TTY::Option::Parameter]
+      #
+      # @return [Integer, nil]
+      #
+      # @api private
+      def find_longest_parameter(params, &name_selector)
+        params = params.reject(&:hidden?).map(&name_selector)
+
+        params.max_by(&:length).length if params.any?
+      end
+
       # Format an option
       #
+      # @param [TTY::Option::Parameter::Option] option
+      #   the option to format
+      # @param [Integer, nil] longest_short
+      #   the longest short option length or nil
+      # @param [Integer, nil] longest_long
+      #   the longest long option length or nil
+      #
+      # @return [String]
+      #
       # @api private
-      def format_option(option, longest_length, any_short)
+      def format_option(option, longest_short, longest_long)
         line = [@space_indent]
-        desc = []
         indent = @indent
 
-        if any_short
-          short_option = option.short? ? option.short_name : SPACE
-          line << format("%#{SHORT_OPT_LENGTH}s", short_option)
-          indent += SHORT_OPT_LENGTH
+        if longest_short
+          line << "  #{format_short_option(option, longest_short)}"
+          indent += line.last.length
         end
 
-        # short & long option separator
-        line << ((option.short? && option.long?) ? ", " : "  ")
-        indent += 2
+        if longest_long
+          separator = short_and_long_option_separator(option)
+          line << "#{separator}#{format_long_option(option, longest_long)}"
+          indent += line.last.length
+        end
 
+        if parameter_description?(option)
+          indent += 2
+          desc = format_parameter_description(option)
+          line << wrap(desc, indent: indent, width: @width)
+        end
+
+        line.join
+      end
+
+      # Format a short option
+      #
+      # @param [TTY::Option::Parameter::Option] option
+      #   the option to format
+      # @param [Integer] longest
+      #   the longest short option length
+      #
+      # @return [String]
+      #
+      # @api private
+      def format_short_option(option, longest)
+        if option.long?
+          format("%-#{longest}s", option.short_name)
+        elsif parameter_description?(option)
+          format("%-#{longest}s", option.short)
+        else
+          option.short
+        end
+      end
+
+      # Format a long option
+      #
+      # @param [TTY::Option::Parameter::Option] option
+      #   the option to format
+      # @param [Integer] longest
+      #   the longest long option length
+      #
+      # @return [String]
+      #
+      # @api private
+      def format_long_option(option, longest)
         if option.long?
-          if option.desc?
-            line << format("%-#{longest_length}s", option.long)
+          if parameter_description?(option)
+            format("%-#{longest}s", option.long)
           else
-            line << option.long
+            option.long
           end
-        else
-          line << format("%-#{longest_length}s", SPACE)
+        elsif parameter_description?(option)
+          format("%-#{longest}s", SPACE)
         end
-        indent += longest_length
+      end
 
-        if option.desc?
-          desc << "  #{option.desc}"
+      # Short and long option separator
+      #
+      # @param [TTY::Option::Parameter::Option] option
+      #   the option to separate short and long names
+      #
+      # @return [String]
+      #
+      # @api private
+      def short_and_long_option_separator(option)
+        if option.short? && option.long?
+          LIST_SEPARATOR
+        elsif option.long? || parameter_description?(option)
+          DOUBLE_SPACE
+        else
+          EMPTY
         end
-        indent += 2
+      end
+
+      # Format a parameter description
+      #
+      # @param [TTY::Option::Parameter] param
+      #   the parameter to format
+      #
+      # @return [String]
+      #
+      # @api private
+      def format_parameter_description(param)
+        desc = []
 
-        if option.permit?
-          desc << format(" (permitted: %s)", option.permit.join(","))
+        desc << "  #{param.desc}" if param.desc?
+
+        if param.permit?
+          desc << SPACE unless param.desc?
+          desc << format_permitted(param.permit)
         end
 
-        if (default = format_default(option))
+        if (default = format_default(param))
+          desc << SPACE unless param.desc?
           desc << default
         end
 
-        line << wrap(desc.join, indent: indent, width: width)
+        desc.join
+      end
 
-        line.join
+      # Check whether or not parameter has description
+      #
+      # @param [TTY::Option::Parameter] param
+      #   the parameter to check for description
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def parameter_description?(param)
+        param.desc? || param.permit? || parameter_default?(param)
+      end
+
+      # Check whether or not parameter has default
+      #
+      # @param [TTY::Option::Parameter] param
+      #   the parameter to check for default
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def parameter_default?(param)
+        param.default? && !BOOLEANS.include?(param.default)
+      end
+
+      # Format permitted values
+      #
+      # @param [Parameter] values
+      #   the permitted values to format
+      #
+      # @return [String]
+      #
+      # @api private
+      def format_permitted(values)
+        format(" (permitted: %s)", values.map do |val|
+          val.respond_to?(:to_ary) ? val.join(MAP_SEPARATOR) : val
+        end.join(LIST_SEPARATOR))
       end
 
-      # Format default value
+      # Format a default value
+      #
+      # @param [TTY::Option::Parameter] param
+      #   the parameter to format
+      #
+      # @return [String]
       #
       # @api private
       def format_default(param)
-        return if !param.default? || [true, false].include?(param.default)
+        return unless parameter_default?(param)
 
         if param.default.is_a?(String)
           format(" (default %p)", param.default)
@@ -366,6 +652,8 @@ module TTY
 
       # Format examples section
       #
+      # @return [String]
+      #
       # @api private
       def format_examples
         format_multiline(@usage.example, @param_indent)
@@ -373,15 +661,22 @@ module TTY
 
       # Format multiline content
       #
+      # @param [Array<Array<String>>] lines
+      #   the lines to format
+      # @param [Integer] indent
+      #   the indent for the lines
+      #
+      # @return [String]
+      #
       # @api private
       def format_multiline(lines, indent)
         last_index = lines.size - 1
         lines.map.with_index do |line, i|
           line.map do |part|
             part.split(NEWLINE).map do |p|
-              wrap(p, indent: indent, width: width, indent_first: true)
+              wrap(p, indent: indent, width: @width, indent_first: true)
             end.join(NEWLINE)
-          end.join(NEWLINE) + (last_index != i ? NEWLINE : "")
+          end.join(NEWLINE) + (last_index == i ? EMPTY : NEWLINE)
         end.join(NEWLINE)
       end
     end # Formatter

data/lib/tty/option/param_permitted.rb

@@ -13,12 +13,16 @@ module TTY
       #
       # @api public
       def call(param, value)
-        return Result.success(value) unless param.permit?
+        return Result.success(value) if !param.permit? || value.nil?
 
-        if param.permit.include?(value)
+        unpermitted = Array(value) - Array(param.permit)
+
+        if unpermitted.empty?
           Result.success(value)
         else
-          Result.failure(UnpermittedArgument.new(param, value))
+          Result.failure(unpermitted.map do |val|
+            UnpermittedArgument.new(param, val)
+          end)
         end
       end
       module_function :call