rubycli 0.1.7 → 0.2.0

data/lib/rubycli/help_renderer.rb

@@ -1,4 +1,6 @@
-require_relative "type_utils"
+# frozen_string_literal: true
+
+require_relative 'type_utils'
 
 module Rubycli
   class HelpRenderer
@@ -8,43 +10,42 @@ module Rubycli
       @documentation_registry = documentation_registry
     end
 
-    def print_help(target, catalog)
-      puts "Usage: #{File.basename($PROGRAM_NAME)} COMMAND [arguments]"
-      puts
+    # +io+ is $stderr when the help is shown because a command failed, so that
+    # piping stdout to another program never mixes diagnostics into the payload.
+    def print_help(target, catalog, io: $stdout)
+      io.puts(help_text(target, catalog))
+    end
+
+    def help_text(_target, catalog)
+      lines = ["Usage: #{File.basename($PROGRAM_NAME)} COMMAND [arguments]", '']
 
       instance_entries = catalog.entries_for(:instance)
       class_entries = catalog.entries_for(:class)
       groups = []
-      groups << { label: "Instance methods", entries: instance_entries } unless instance_entries.empty?
-      groups << { label: "Class methods", entries: class_entries } unless class_entries.empty?
+      groups << { label: 'Instance methods', entries: instance_entries } unless instance_entries.empty?
+      groups << { label: 'Class methods', entries: class_entries } unless class_entries.empty?
 
-      if groups.empty?
-        puts "No commands available."
-        return
-      end
+      return (lines << 'No commands available.').join("\n") if groups.empty?
 
-      puts "Available commands:"
+      lines << 'Available commands:'
       groups.each do |group|
-        puts "  #{group[:label]}:"
+        lines << "  #{group[:label]}:"
         group[:entries].each do |entry|
           description = method_description(entry.method)
           line = "    #{entry.command.ljust(20)}"
           line += " #{description}" unless description.empty?
-          puts line.rstrip
+          lines << line.rstrip
 
-          unless entry.aliases.empty?
-            puts "      Aliases: #{entry.aliases.join(", ")}"
-          end
+          lines << "      Aliases: #{entry.aliases.join(', ')}" unless entry.aliases.empty?
         end
-        puts unless group.equal?(groups.last)
+        lines << '' unless group.equal?(groups.last)
       end
 
-      if catalog.duplicates.any?
-        puts "Methods with the same name can be invoked via instance::NAME / class::NAME."
-      end
+      lines << 'Methods with the same name can be invoked via instance::NAME / class::NAME.' if catalog.duplicates.any?
 
-      puts
-      puts "Detailed command help: #{File.basename($PROGRAM_NAME)} COMMAND help"
+      lines << ''
+      lines << "Detailed command help: #{File.basename($PROGRAM_NAME)} COMMAND help"
+      lines.join("\n")
     end
 
     def method_description(method_obj)
@@ -53,7 +54,7 @@ module Rubycli
       return summary if summary && !summary.empty?
 
       params_str = format_method_parameters(method_obj.parameters, metadata)
-      params_str.empty? ? "(no arguments)" : params_str
+      params_str.empty? ? '(no arguments)' : params_str
     end
 
     def usage_for_method(command, method)
@@ -69,17 +70,17 @@ module Rubycli
 
       returns = metadata[:returns] || []
       if returns.any?
-        usage_lines << "" unless usage_lines.last == ""
-        usage_lines << "Return values:"
+        usage_lines << '' unless usage_lines.last == ''
+        usage_lines << 'Return values:'
         returns.each do |ret|
-          type_label = (ret.types || []).join(" | ")
+          type_label = (ret.types || []).join(' | ')
           line = "  #{type_label}"
           line += "  #{ret.description}" if ret.description && !ret.description.empty?
           usage_lines << line
         end
       end
 
-      usage_lines.pop while usage_lines.last == ""
+      usage_lines.pop while usage_lines.last == ''
       usage_block = usage_lines.join("\n")
 
       sections = []
@@ -100,7 +101,7 @@ module Rubycli
       option_map = (metadata[:options] || []).each_with_object({}) { |opt, h| h[opt[:keyword]] = opt }
       positional_map = metadata[:positionals_map] || {}
 
-      parameters.map { |type, name|
+      parameters.map do |type, name|
         case type
         when :req
           positional_usage_token(type, name, positional_map[name])
@@ -122,19 +123,19 @@ module Rubycli
         when :key
           opt = option_map[name]
           label = if opt
-            if opt.doc_format == :auto_generated
-              auto_generated_option_usage_label(name, opt)
-            else
-              option_flag_with_placeholder(opt)
-            end
-          else
-            "--#{name.to_s.tr('_', '-')}=<value>"
-          end
+                    if opt.doc_format == :auto_generated
+                      auto_generated_option_usage_label(name, opt)
+                    else
+                      option_flag_with_placeholder(opt)
+                    end
+                  else
+                    "--#{name.to_s.tr('_', '-')}=<value>"
+                  end
           "[#{label}]"
-        when :keyrest then "[--<option>...]"
-        else ""
+        when :keyrest then '[--<option>...]'
+        else ''
         end
-      }.compact.reject(&:empty?).join(" ")
+      end.compact.reject(&:empty?).join(' ')
     end
 
     def auto_generated_option_usage_label(name, opt)
@@ -145,13 +146,13 @@ module Rubycli
       formatted = if value_name && !value_name.to_s.strip.empty?
                     ensure_angle_bracket_placeholder(value_name)
                   else
-                    "<value>"
+                    '<value>'
                   end
       "#{base_flag}=#{formatted}"
     end
 
     def render_positionals(positionals_in_order)
-        rows = positionals_in_order.map do |info|
+      rows = positionals_in_order.map do |info|
         definition = info[:definition]
         label = info[:label]
         type = type_display(definition)
@@ -162,7 +163,7 @@ module Rubycli
         description_parts << default_text if default_text
         [label, type, requirement, description_parts.join(' ')]
       end
-      table_block("Positional arguments:", rows)
+      table_block('Positional arguments:', rows)
     end
 
     def render_options(options, required_keywords)
@@ -176,7 +177,7 @@ module Rubycli
         description_parts << default_text if default_text
         [label, type, requirement, description_parts.join(' ').strip]
       end
-      table_block("Options:", rows)
+      table_block('Options:', rows)
     end
 
     def table_block(header, rows)
@@ -185,7 +186,7 @@ module Rubycli
       cols = rows.transpose
       widths = cols.map { |col| col.map { |value| value.to_s.length }.max || 0 }
 
-      lines = ["", header]
+      lines = ['', header]
       rows.each do |row|
         padded = row.each_with_index.map do |value, idx|
           text = value.to_s
@@ -247,32 +248,33 @@ module Rubycli
     end
 
     def positional_requirement(kind)
-      kind == :opt ? 'optional' : 'required'
+      %i[opt rest].include?(kind) ? 'optional' : 'required'
     end
 
     def positional_default(definition)
       return nil unless definition
+
       value = definition.default_value
       return nil if value.nil? || value.to_s.empty?
 
       "(default: #{value})"
     end
 
- def option_default(opt)
-   value = opt.default_value
-   return nil if value.nil? || value.to_s.empty?
+    def option_default(opt)
+      value = opt.default_value
+      return nil if value.nil? || value.to_s.empty?
 
-   "(default: #{value})"
- end
+      "(default: #{value})"
+    end
 
- def required_keyword_names(method)
-   method.parameters.select { |type, _| type == :keyreq }.map { |_, name| name }
- end
+    def required_keyword_names(method)
+      method.parameters.select { |type, _| type == :keyreq }.map { |_, name| name }
+    end
 
     def ordered_positionals(method, metadata)
       positional_map = metadata[:positionals_map] || {}
       method.parameters.each_with_object([]) do |(type, name), memo|
-        next unless %i[req opt].include?(type)
+        next unless %i[req opt rest].include?(type)
 
         definition = positional_map[name]
         label = display_label_for(definition, name)
@@ -296,8 +298,6 @@ module Rubycli
         optional_placeholder(placeholder, definition, name)
       when :rest
         rest_placeholder(placeholder, definition, name)
-      else
-        nil
       end
     end
 
@@ -319,7 +319,10 @@ module Rubycli
 
     def optional_placeholder(placeholder, definition, name)
       unless placeholder.nil? || placeholder.strip.empty? || auto_generated_placeholder?(placeholder, definition, name)
-        return placeholder.strip
+        documented = placeholder.strip
+        return documented if documented.start_with?('[') && documented.end_with?(']')
+
+        return "[#{documented}]"
       end
 
       "[#{default_positional_label(definition, name, uppercase: true)}]"
@@ -327,7 +330,10 @@ module Rubycli
 
     def rest_placeholder(placeholder, definition, name)
       unless placeholder.nil? || placeholder.strip.empty? || auto_generated_placeholder?(placeholder, definition, name)
-        return placeholder.strip
+        documented = placeholder.strip
+        documented = documented[1..-2].strip if documented.start_with?('[') && documented.end_with?(']')
+        documented = "#{documented}..." unless documented.end_with?('...')
+        return "[#{documented}]"
       end
 
       base = default_positional_label(definition, name, uppercase: true)
@@ -344,8 +350,8 @@ module Rubycli
 
     def option_flag_with_placeholder(opt)
       flags = [opt.short, opt.long].compact
-      flags = ["--#{opt.keyword.to_s.tr("_", "-")}"] if flags.empty?
-      flag_label = flags.join(", ")
+      flags = ["--#{opt.keyword.to_s.tr('_', '-')}"] if flags.empty?
+      flag_label = flags.join(', ')
       placeholder = option_value_placeholder(opt)
       if placeholder
         formatted = ensure_angle_bracket_placeholder(placeholder)
@@ -364,8 +370,7 @@ module Rubycli
       return nil if opt.boolean_flag
       return opt.value_name if opt.value_name && !opt.value_name.empty?
 
-      first_non_nil_type = opt.types&.find { |type| !nil_type?(type) && !boolean_type?(type) }
-      first_non_nil_type
+      opt.types&.find { |type| !nil_type?(type) && !boolean_type?(type) }
     end
 
     def auto_generated_placeholder?(placeholder, definition, name)

data/lib/rubycli/json_coercer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rubycli
   class JsonCoercer
     THREAD_KEY = :rubycli_json_mode

data/lib/rubycli/result_emitter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rubycli
   class ResultEmitter
     def initialize(environment:)
@@ -26,15 +28,23 @@ module Rubycli
       when Array, Hash
         JSON.pretty_generate(result)
       else
-        if result.respond_to?(:to_h)
-          JSON.pretty_generate(result.to_h)
-        elsif result.respond_to?(:to_ary)
-          JSON.pretty_generate(result.to_ary)
-        else
-          result.inspect
-        end
+        format_convertible_result(result)
+      end
+    rescue JSON::GeneratorError, JSON::NestingError
+      result.inspect
+    end
+
+    # to_h / to_ary are duck-typed: every Enumerable answers to_h, but Set,
+    # Range and Enumerator raise TypeError unless their elements are pairs.
+    def format_convertible_result(result)
+      if result.respond_to?(:to_h)
+        JSON.pretty_generate(result.to_h)
+      elsif result.respond_to?(:to_ary)
+        JSON.pretty_generate(result.to_ary)
+      else
+        result.inspect
       end
-    rescue JSON::GeneratorError
+    rescue TypeError
       result.inspect
     end
   end