coglius 0.0.1

data/lib/coglius/commands/help.rb

@@ -0,0 +1,73 @@
+require 'erb'
+require 'coglius/command'
+require 'coglius/terminal'
+require 'coglius/commands/help_modules/list_formatter'
+require 'coglius/commands/help_modules/text_wrapper'
+require 'coglius/commands/help_modules/one_line_wrapper'
+require 'coglius/commands/help_modules/verbatim_wrapper'
+require 'coglius/commands/help_modules/tty_only_wrapper'
+require 'coglius/commands/help_modules/options_formatter'
+require 'coglius/commands/help_modules/global_help_format'
+require 'coglius/commands/help_modules/command_help_format'
+require 'coglius/commands/help_modules/help_completion_format'
+require 'coglius/commands/help_modules/command_finder'
+require 'coglius/commands/help_modules/arg_name_formatter'
+
+module Coglius
+  module Commands
+    SORTERS = {
+      :manually => lambda { |list| list },
+      :alpha    => lambda { |list| list.sort },
+    }
+
+    WRAPPERS = {
+      :to_terminal => HelpModules::TextWrapper,
+      :never       => HelpModules::OneLineWrapper,
+      :one_line    => HelpModules::OneLineWrapper,
+      :tty_only    => HelpModules::TTYOnlyWrapper,
+      :none        => HelpModules::VerbatimWrapper,
+      :verbatim    => HelpModules::VerbatimWrapper,
+    }
+    # The help command used for the two-level interactive help system
+    class Help < Command
+      def initialize(app,output=$stdout,error=$stderr)
+        super(:names => :help,
+              :description => 'Shows a list of commands or help for one command',
+              :arguments_name => 'command',
+              :long_desc => 'Gets help for the application or its commands. Can also list the commands in a way helpful to creating a bash-style completion function',
+              :skips_pre => true,
+              :skips_post => true,
+              :skips_around => true)
+        @app = app
+        @sorter = SORTERS[@app.help_sort_type]
+        @text_wrapping_class = WRAPPERS[@app.help_text_wrap_type]
+
+        desc 'List commands one per line, to assist with shell completion'
+        switch :c
+
+        action do |global_options,options,arguments|
+          show_help(global_options,options,arguments,output,error)
+        end
+      end
+
+    private
+
+      def show_help(global_options,options,arguments,out,error)
+        command_finder = HelpModules::CommandFinder.new(@app,arguments,error)
+        if options[:c]
+          help_output = HelpModules::HelpCompletionFormat.new(@app,command_finder,arguments).format
+          out.puts help_output unless help_output.nil?
+        elsif arguments.empty? || options[:c]
+          out.puts HelpModules::GlobalHelpFormat.new(@app,@sorter,@text_wrapping_class).format
+        else
+          name = arguments.shift
+          command = command_finder.find_command(name)
+          unless command.nil?
+            out.puts HelpModules::CommandHelpFormat.new(command,@app,File.basename($0).to_s,@sorter,@text_wrapping_class).format
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/coglius/commands/help_modules/arg_name_formatter.rb

@@ -0,0 +1,20 @@
+module Coglius
+  module Commands
+    module HelpModules
+      # Handles wrapping text
+      class ArgNameFormatter
+        def format(arguments_description,arguments_options)
+          return '' if String(arguments_description).strip == ''
+          desc = arguments_description
+          if arguments_options.include? :optional
+            desc = "[#{desc}]"
+          end
+          if arguments_options.include? :multiple
+            desc = "#{desc}[, #{desc}]*"
+          end
+          " " + desc
+        end
+      end
+    end
+  end
+end

data/lib/coglius/commands/help_modules/command_finder.rb

@@ -0,0 +1,60 @@
+module Coglius
+  module Commands
+    module HelpModules
+      # Finds commands from the application/command data structures
+      class CommandFinder
+
+        attr_reader :last_unknown_command
+        attr_reader :last_found_command
+        attr_writer :squelch_stderr
+
+        def initialize(app,arguments,error)
+          @app = app
+          @arguments = arguments
+          @error = error
+          @squelch_stderr = false
+          @last_unknown_command = nil
+        end
+
+        def find_command(name)
+          command = find_command_from_base(name,@app)
+          return if unknown_command?(command,name,@error)
+          @last_found_command = command
+          while !@arguments.empty?
+            name = @arguments.shift
+            command = find_command_from_base(name,command)
+            return if unknown_command?(command,name,@error)
+            @last_found_command = command
+          end
+          command
+        end
+
+      private
+
+        # Given the name of a command to find, and a base, either the app or another command, returns
+        # the command object or nil.
+        def find_command_from_base(command_name,base)
+          base.commands.values.select { |command|
+            if [command.name,Array(command.aliases)].flatten.map(&:to_s).any? { |_| _ == command_name }
+              command
+            end
+          }.first
+        end
+
+        # Checks if the return from find_command was unknown and, if so, prints an error
+        # for the user on the error device, returning true or false if the command was unknown.
+        def unknown_command?(command,name,error)
+          if command.nil?
+            @last_unknown_command = name
+            unless @squelch_stderr
+              error.puts "error: Unknown command '#{name}'.  Use '#{File.basename($PROGRAM_NAME)} help' for a list of commands."
+            end
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coglius/commands/help_modules/command_help_format.rb

@@ -0,0 +1,138 @@
+require 'erb'
+
+module Coglius
+  module Commands
+    module HelpModules
+      class CommandHelpFormat
+        def initialize(command,app,basic_invocation,sorter,wrapper_class=TextWrapper)
+          @basic_invocation = basic_invocation
+          @app = app
+          @command = command
+          @sorter = sorter
+          @wrapper_class = wrapper_class
+        end
+
+        def format
+          command_wrapper = @wrapper_class.new(Terminal.instance.size[0],4 + @command.name.to_s.size + 3)
+          wrapper = @wrapper_class.new(Terminal.instance.size[0],4)
+          flags_and_switches = (@command.topmost_ancestor.flags_declaration_order + @command.topmost_ancestor.switches_declaration_order).select { |option| option.associated_command == @command }
+          options_description = OptionsFormatter.new(flags_and_switches,@sorter,@wrapper_class).format
+          commands_description = format_subcommands(@command)
+
+          synopses = []
+          one_line_usage = basic_usage
+          one_line_usage << @command.arguments_description
+          if @command.commands.empty?
+            synopses << one_line_usage
+          else
+            synopses = sorted_synopses
+            if @command.has_action?
+              synopses.unshift(one_line_usage)
+            end
+
+          end
+
+          COMMAND_HELP.result(binding)
+        end
+
+      private
+        COMMAND_HELP = ERB.new(%q(NAME
+    <%= @command.name %> - <%= command_wrapper.wrap(@command.description) %>
+
+SYNOPSIS
+<% synopses.each do |s| %>
+    <%= s %>
+<% end %>
+<% unless @command.long_description.nil? %>
+
+DESCRIPTION
+    <%= wrapper.wrap(@command.long_description) %> 
+<% end %>
+<% if options_description.strip.length != 0 %>
+
+COMMAND OPTIONS
+<%= options_description %>
+<% end %>
+<% unless @command.commands.empty? %>
+
+COMMANDS
+<%= commands_description %>
+<% end %>),nil,'<>')
+
+        def command_with_subcommand_usage(sub,is_default_command)
+          usage = basic_usage
+          sub_options = @command.flags.merge(@command.switches).select { |_,o| o.associated_command == sub }
+          usage << sub_options.map { |option_name,option| 
+            all_names = [option.name,Array(option.aliases)].flatten
+            all_names.map { |_| 
+              CommandLineOption.name_as_string(_,false) + (option.kind_of?(Flag) ? " #{option.argument_name }" : '')
+            }.join('|')
+          }.map { |_| "[#{_}]" }.sort.join(' ')
+          usage << ' '
+          if is_default_command
+            usage << "[#{sub.name}]"
+          else
+            usage << sub.name.to_s
+          end
+          usage << ArgNameFormatter.new.format(sub.arguments_description,sub.arguments_options)
+          usage
+        end
+
+ 
+        def basic_usage
+          usage = @basic_invocation.dup
+          usage << " [global options] #{path_to_command} "
+          usage << "[command options] " unless global_flags_and_switches.empty?
+          usage
+        end
+ 
+        def path_to_command
+          path = []
+          c = @command
+          while c.kind_of? Command
+            path.unshift(c.name)
+            c = c.parent
+          end
+          path.join(' ')
+        end
+ 
+        def global_flags_and_switches
+          @app.flags.merge(@app.switches)
+        end
+ 
+        def format_subcommands(command)
+          commands_array = @sorter.call(command.commands_declaration_order).map { |cmd| 
+            if command.get_default_command == cmd.name
+              [cmd.names,cmd.description + " (default)"] 
+            else
+              [cmd.names,cmd.description] 
+            end
+          }
+          if command.has_action?
+            commands_array.unshift(["<default>",command.default_description])
+          end
+          formatter = ListFormatter.new(commands_array,@wrapper_class)
+          StringIO.new.tap { |io| formatter.output(io) }.string
+        end
+
+        def sorted_synopses
+          synopses_command = {}
+          @command.commands.each do |name,sub|
+            default = @command.get_default_command == name
+            synopsis = command_with_subcommand_usage(sub,default)
+            synopses_command[synopsis] = sub
+          end
+          synopses = synopses_command.keys.sort { |one,two|
+            if synopses_command[one].name == @command.get_default_command
+              -1
+            elsif synopses_command[two].name == @command.get_default_command
+              1
+            else
+              synopses_command[one] <=> synopses_command[two]
+            end
+          }
+        end
+      end
+    end
+  end
+end

data/lib/coglius/commands/help_modules/global_help_format.rb

@@ -0,0 +1,70 @@
+require 'erb'
+
+module Coglius
+  module Commands
+    module HelpModules
+      class GlobalHelpFormat
+        def initialize(app,sorter,wrapper_class)
+          @app = app
+          @sorter = sorter
+          @wrapper_class = wrapper_class
+        end
+
+        def format
+          program_desc = @app.program_desc
+          program_long_desc = @app.program_long_desc
+          if program_long_desc
+            wrapper = @wrapper_class.new(Terminal.instance.size[0],4)
+            program_long_desc = "\n    #{wrapper.wrap(program_long_desc)}\n\n" if program_long_desc
+          else
+            program_long_desc = "\n"
+          end
+
+          command_formatter = ListFormatter.new(@sorter.call(@app.commands_declaration_order.reject(&:nodoc)).map { |command|
+            [[command.name,Array(command.aliases)].flatten.join(', '),command.description]
+          }, @wrapper_class)
+          stringio = StringIO.new
+          command_formatter.output(stringio)
+          commands = stringio.string
+
+          global_option_descriptions = OptionsFormatter.new(global_flags_and_switches,@sorter,@wrapper_class).format
+
+          GLOBAL_HELP.result(binding)
+        end
+
+      private
+
+        GLOBAL_HELP = ERB.new(%q(NAME
+    <%= File.basename($0) %> - <%= program_desc %>
+<%= program_long_desc %>
+SYNOPSIS
+    <%= usage_string %>
+
+<% unless @app.version_string.nil? %>
+VERSION
+    <%= @app.version_string %>
+
+<% end %>
+<% unless global_flags_and_switches.empty? %>
+GLOBAL OPTIONS
+<%= global_option_descriptions %>
+
+<% end %>
+COMMANDS
+<%= commands %>),nil,'<>')
+
+        def global_flags_and_switches
+          @app.flags_declaration_order + @app.switches_declaration_order
+        end
+
+        def usage_string
+          "#{File.basename($0)} ".tap do |string|
+            string << "[global options] " unless global_flags_and_switches.empty?
+            string << "command "
+            string << "[command options] [arguments...]"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coglius/commands/help_modules/help_completion_format.rb

@@ -0,0 +1,31 @@
+module Coglius
+  module Commands
+    module HelpModules
+      class HelpCompletionFormat
+        def initialize(app,command_finder,args)
+          @app = app
+          @command_finder = command_finder
+          @command_finder.squelch_stderr = true
+          @args = args
+        end
+
+        def format
+          name = @args.shift
+
+          base = @command_finder.find_command(name)
+          base = @command_finder.last_found_command if base.nil?
+          base = @app if base.nil?
+
+          prefix_to_match = @command_finder.last_unknown_command
+
+          base.commands.values.map { |command|
+            [command.name,command.aliases]
+          }.flatten.compact.map(&:to_s).sort.select { |command_name|
+            prefix_to_match.nil? || command_name =~ /^#{prefix_to_match}/
+          }.join("\n")
+        end
+
+      end
+    end
+  end
+end

data/lib/coglius/commands/help_modules/list_formatter.rb

@@ -0,0 +1,23 @@
+module Coglius
+  module Commands
+    module HelpModules
+      # Given a list of two-element lists, formats on the terminal 
+      class ListFormatter
+        def initialize(list,wrapper_class=TextWrapper)
+          @list = list
+          @wrapper_class = wrapper_class
+        end
+
+        # Output the list to the output_device
+        def output(output_device)
+          return if @list.empty?
+          max_width = @list.map { |_| _[0].length }.max
+          wrapper = @wrapper_class.new(Terminal.instance.size[0],4 + max_width + 3)
+          @list.each do |(name,description)|
+            output_device.printf("    %-#{max_width}s - %s\n",name,wrapper.wrap(String(description).strip))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coglius/commands/help_modules/one_line_wrapper.rb

@@ -0,0 +1,18 @@
+module Coglius
+  module Commands
+    module HelpModules
+      # Formats text in one line, stripping newlines and NOT wrapping
+      class OneLineWrapper
+        # Args are ignored entirely; this keeps it consistent with the TextWrapper interface
+        def initialize(width,indent)
+        end
+
+        # Return a wrapped version of text, assuming that the first line has already been
+        # indented by @indent characters.  Resulting text does NOT have a newline in it.
+        def wrap(text)
+          return String(text).gsub(/\n+/,' ').strip
+        end
+      end
+    end
+  end
+end

data/lib/coglius/commands/help_modules/options_formatter.rb

@@ -0,0 +1,49 @@
+module Coglius
+  module Commands
+    module HelpModules
+      class OptionsFormatter
+        def initialize(flags_and_switches,sorter,wrapper_class)
+          @flags_and_switches = sorter.call(flags_and_switches)
+          @wrapper_class = wrapper_class
+        end
+
+        def format
+          list_formatter = ListFormatter.new(@flags_and_switches.map { |option|
+            if option.respond_to? :argument_name
+              [option_names_for_help_string(option,option.argument_name),description_with_default(option)]
+            else
+              [option_names_for_help_string(option),description_with_default(option)]
+            end
+          },@wrapper_class)
+          stringio = StringIO.new
+          list_formatter.output(stringio)
+          stringio.string
+        end
+
+      private
+
+        def description_with_default(option)
+          if option.kind_of? Flag
+            String(option.description) + " (default: #{option.safe_default_value || 'none'})"
+          else
+            String(option.description) +  (option.default_value ?  " (default: enabled)" : "")
+          end
+        end
+
+        def option_names_for_help_string(option,arg_name=nil)
+          names = [option.name,Array(option.aliases)].flatten
+          names = names.map { |name| CommandLineOption.name_as_string(name,option.kind_of?(Switch) ? option.negatable? : false) }
+          if arg_name.nil?
+            names.join(', ')
+          else
+            if names[-1] =~ /^--/
+              names.join(', ') + "=#{arg_name}"
+            else
+              names.join(', ') + " #{arg_name}"
+            end
+          end
+        end
+      end
+    end
+  end
+end