shellopts 2.0.0.pre.14 → 2.0.2

data/lib/shellopts/formatter.rb

@@ -1,124 +1,324 @@
+require 'terminfo'
 
-require 'ext/algorithm'
-
-require 'stringio'
+# TODO: Move to ext/indented_io.rb
+module IndentedIO
+  class IndentedIO
+    def margin() combined_indent.size end
+  end
+end
 
 module ShellOpts
-  class Formatter
-    # Return string describing usage of command
-    def self.usage_string(command, levels: 1, margin: "")
-      elements(command, levels: levels, help: false).map { |line|
-        "#{margin}#{line}"
-      }.join("\n")
-    end
-
-    # Return string with help for the given command
-    def self.help_string(command, levels: 10, margin: "", tab: "  ")
-      io = StringIO.new
-      elements(command, levels: levels, help: true).each { |head, texts, options|
-        io.puts "#{margin}#{head}"
-        texts.each { |text| io.puts "#{margin}#{tab}#{text}" }
-        options.each { |opt_head, opt_texts|
-          io.puts
-          io.puts "#{margin}#{tab}#{opt_head}"
-          opt_texts.each { |text| io.puts "#{margin}#{tab*2}#{text}" }
-        }
-        io.puts
-      }
-      io.string[0..-2]
+  module Grammar
+    class Node
+      def puts_help() end
+      def puts_usage() end
     end
 
-  private
-    def self.elements(command, levels: 1, help: false)
-      result = []
-      recursive_elements(result, command, levels: levels, help: help)
-      result  
-    end
-
-    def self.recursive_elements(acc, command, levels: 1, help: false)
-      cmds = (command.virtual? ? command.cmds : [command])
-      cmds.each { |cmd|
-        if levels == 1 || cmd.cmds.empty?
-          usage = (
-              path_elements(cmd) + 
-              option_elements(cmd) +
-              subcommand_element(cmd) +
-              argument_elements(cmd)
-          ).compact.join(" ")
-          if help
-            opts = []
-            cmd.opts.each { |opt|
-              next if opt.text.empty?
-              opts << [option_help(opt), opt.text]
+    class Option
+    end
+
+    class OptionGroup
+      def puts_descr
+        puts Ansi.bold(render(:multi))
+        indent {
+          if description.any?
+            description.each { |descr|
+              descr.puts_descr
+              puts if descr != description.last
             }
-            acc << [usage, cmd.text, opts]
-          else
-            acc << usage
+          elsif brief
+            brief.puts_descr
           end
-        else
-          cmd.cmds.each { |subcmd|
-            recursive_elements(acc, subcmd, levels: levels - 1, help: help)
+        }
+      end
+    end
+
+    # brief one-line commands should optionally use compact options
+    class Command
+      using Ext::Array::Wrap
+
+      def puts_usage(bol: false)
+        if descrs.size == 0
+          print (lead = Formatter.command_prefix || "")
+          indent(lead.size, ' ', bol: bol && lead == "") { 
+            puts render(:multi, Formatter::USAGE_MAX_WIDTH) 
           }
+        else
+          lead = Formatter.command_prefix || ""
+          descrs.each { |descr|
+            print lead
+            puts render(:single, Formatter::USAGE_MAX_WIDTH, args: [descr.text]) 
+          } 
         end
-      }
+      end
+
+      def puts_brief
+        width = Formatter.rest
+        option_briefs = option_groups.map { |group| [group.render(:enum), group.brief&.words] }
+        command_briefs = commands.map { |command| [command.render(:single, width), command.brief&.words] }
+        widths = Formatter::compute_columns(width, option_briefs + command_briefs)
+
+        if brief
+          puts brief
+          puts
+        end
+
+        puts "Usage"
+        indent { puts_usage(bol: true) }
+
+        if options.any?
+          puts
+          puts "Options"
+          indent { Formatter::puts_columns(widths, option_briefs) }
+        end
+
+        if commands.any?
+          puts
+          puts "Commands"
+          indent { Formatter::puts_columns(widths, command_briefs) }
+        end
+      end
+
+      def puts_descr(prefix, brief: !self.brief.nil?, name: :path)
+        puts Ansi.bold([prefix, render(:single, Formatter.rest)].flatten.compact.join(" "))
+        indent {
+          if brief
+            puts self.brief.words.wrap(Formatter.rest)
+          else
+            newline = false
+            children.each { |child|
+              puts if newline
+              newline = true
+
+              if child.is_a?(Command)
+                child.puts_descr(prefix, name: :path)
+               else
+                child.puts_descr
+              end
+            }
+          end
+        }
+      end
+
+      def puts_help
+        puts Ansi.bold "NAME"
+        full_name = [Formatter::command_prefix, name].join
+        indent { puts brief ? "#{full_name} - #{brief}" : full_name }
+        puts
+
+        puts Ansi.bold "USAGE"
+        indent { puts_usage(bol: true) }
+
+        section = {
+          Paragraph => "DESCRIPTION",
+          OptionGroup => "OPTIONS",
+          Command => "COMMANDS"
+        }
+
+        newline = false # True if a newline should be printed before child 
+        indent {
+          children.each { |child|
+            if child.is_a?(Section) # Explicit section
+#             p :A
+              puts
+              indent(-1).puts Ansi.bold child.name
+              section.delete_if { |_,v| v == child.name }
+              section.delete(Paragraph)
+              newline = false
+              next
+            elsif s = section[child.class] # Implicit section
+#             p :B
+              puts  
+              indent(-1).puts Ansi.bold s
+              section.delete(child.class)
+              section.delete(Paragraph)
+              newline = false
+            else # Any other node add a newline
+#             p :C
+              puts if newline
+              newline = true
+            end
+
+            if child.is_a?(Command)
+#             prefix = child.parent != self ? nil : child.supercommand&.name
+              prefix = child.supercommand == self ? nil : child.supercommand&.name
+              child.puts_descr(prefix, brief: false, name: :path)
+              newline = true
+             else
+              child.puts_descr
+              newline = true
+            end
+          }
+
+          # Also emit commands not declared in nested scope
+          (commands - children.select { |child| child.is_a?(Command) }).each { |cmd|
+            puts if newline
+            newline = true
+            prefix = cmd.supercommand == self ? nil : cmd.supercommand&.name
+            cmd.puts_descr(prefix, brief: false, name: path)
+          }
+        }
+      end
     end
 
-    # Return command line usage string
-    def self.command(cmd)
-      (path_elements(cmd) + option_elements(cmd) + argument_elements(cmd)).compact.join(" ")
+    class Program
+      using Ext::Array::Wrap
     end
 
-    def self.path_elements(cmd)
-      Algorithm.follow(cmd, :parent).map { |parent| parent.name }.reverse
+    class DocNode
+      def puts_descr() puts lines end
     end
 
-    def self.option_elements(cmd)
-      elements = []
-      collapsable_opts, other_opts = cmd.opts.partition { |opt| opt.shortname && !opt.argument? }
+    module WrappedNode
+      def puts_descr(width = Formatter.rest) puts lines(width) end
+    end
 
-      if !collapsable_opts.empty?
-        elements << "-" + collapsable_opts.map(&:shortname).join
-      end
+    class Code
+      def puts_descr() indent { super } end
+    end
+  end
 
-      elements + other_opts.map { |opt|
-        if opt.shortname
-          "-#{opt.shortname} #{opt.argument_name}" # We know opt has an argument
-        elsif opt.argument?
-          "--#{opt.longname}=#{opt.argument_name}"
-        else
-          "--#{opt.longname}"
-        end
+  class Formatter
+    using Ext::Array::Wrap
+
+    # Right margin
+    MARGIN_RIGHT = 3
+
+    # String for 'Usage' in error messages
+    USAGE_STRING = "Usage"
+
+    # Indent to use in usage output
+    USAGE_INDENT = USAGE_STRING.size
+
+    # Width of usage (after usage string)
+    USAGE_MAX_WIDTH = 70
+
+    # Indent to use in brief output
+    BRIEF_INDENT = 2
+
+    # Number of characters between columns in brief output
+    BRIEF_COL_SEP = 2
+
+    # Maximum width of first column in brief option and command lists
+    BRIEF_COL1_MIN_WIDTH = 6
+
+    # Maximum width of first column in brief option and command lists
+    BRIEF_COL1_MAX_WIDTH = 40
+
+    # Minimum width of second column in brief option and command lists
+    BRIEF_COL2_MAX_WIDTH = 50
+
+    # Indent to use in help output
+    HELP_INDENT = 4
+
+    # Command prefix when subject is a sub-command
+    def self.command_prefix() @command_prefix end
+
+    # Usage string in error messages
+    def self.usage(subject)
+      subject = Grammar::Command.command(subject)
+      @command_prefix = subject.ancestors.map { |node| node.name + " " }.join
+      setup_indent(1) {
+        print lead = "#{USAGE_STRING}: "
+        indent(lead.size, ' ', bol: false) { subject.puts_usage }
       }
     end
 
-    def self.option_help(opt)
-      result = opt.names.map { |name|
-        if name.size == 1
-          "-#{name}"
-        else
-          "--#{name}"
-        end
-      }.join(", ")
-      if opt.argument?
-        if opt.longname
-          result += "=#{opt.argument_name}"
+#   # TODO
+#   def self.usage=(usage_lambda)
+#   end
+
+    # When the user gives a -h option
+    def self.brief(command)
+      command = Grammar::Command.command(command)
+      @command_prefix = command.ancestors.map { |node| node.name + " " }.join
+      setup_indent(BRIEF_INDENT) { command.puts_brief }
+    end
+
+#   # TODO
+#   def self.brief=(brief_lambda)
+#   end
+
+    # When the user gives a --help option
+    def self.help(subject)
+      subject = Grammar::Command.command(subject)
+      @command_prefix = subject.ancestors.map { |node| node.name + " " }.join
+      setup_indent(HELP_INDENT) { subject.puts_help }
+    end
+
+    # Short-hand to get the Grammar::Command object
+    def self.command_of(obj)
+      constrain obj, Grammar::Command, ::ShellOpts::Program
+      obj.is_a?(Grammar::Command) ? obj : obj.__grammar__
+    end
+
+#   # TODO
+#   def self.help_w_lambda(program)
+#     if @help_lambda
+#       #
+#     else
+#       program = Grammar::Command.command(program)
+#       setup_indent(HELP_INDENT) { program.puts_descr }
+#     end
+#   end
+#
+#   def self.help=(help_lambda) @help_lambda end
+
+    def self.puts_columns(widths, fields)
+      l = []
+      first_width, second_width = *widths
+      second_col = first_width + 2
+
+      for (first, second) in fields
+        if first.size > first_width
+          puts first
+          indent(first_width + BRIEF_COL_SEP, ' ') { puts second.wrap(second_width) } if second
+        elsif second
+          printf "%-#{first_width + BRIEF_COL_SEP}s", first
+          indent(first_width, bol: false) { puts second.wrap(second_width) }
         else
-          result += " #{opt.argument_name}"
+          puts first
         end
       end
-      result
     end
 
-    def self.subcommand_element(cmd)
-      !cmd.cmds.empty? ? [cmd.cmds.map(&:name).join("|")] : []
+    def self.compute_columns(width, fields)
+      first_max = [
+        (fields.map { |first, _| first.size } + [BRIEF_COL1_MIN_WIDTH]).max, 
+        BRIEF_COL1_MAX_WIDTH
+      ].min
+      second_max = fields.map { |_, second| second ? second&.map(&:size).sum + second.size - 1: 0 }.max
+
+      if first_max + BRIEF_COL_SEP + second_max <= width
+        first_width = first_max
+        second_width = second_max
+      elsif first_max + BRIEF_COL_SEP + BRIEF_COL2_MAX_WIDTH <= width
+        first_width = first_max
+        second_width = width - first_width - BRIEF_COL_SEP
+      else
+        first_width = [width - BRIEF_COL_SEP - BRIEF_COL2_MAX_WIDTH, BRIEF_COL1_MAX_WIDTH].min
+        second_width = BRIEF_COL2_MAX_WIDTH
+      end
+
+      [first_width, second_width]
     end
 
-    def self.argument_elements(cmd)
-      cmd.args
+    def self.width()
+      @width ||= TermInfo.screen_width - MARGIN_RIGHT
     end
 
-    def self.help_element(cmd)
-      text.map { |l| l.sub(/^\s*# /, "").rstrip }.join(" ")
+    def self.rest() width - $stdout.margin end
+
+  private
+    # TODO Get rid of?
+    def self.setup_indent(indent, &block)
+      default_indent = IndentedIO.default_indent
+      begin
+        IndentedIO.default_indent = " " * indent
+        indent(0) { yield } # Ensure IndentedIO is on the top of the stack so we can use $stdout.levels
+      ensure
+        IndentedIO.default_indent = default_indent
+      end
     end
   end
 end