class CTioga2::Commands::Documentation::CommandLineHelp
Displays help about command-line options and such.
Constants
- DefaultStyles
The default value for the
styles
attribute.
Attributes
Color output ?
How much space to leave for the options ?
Styles, ie a hash 'object' (option, argument…) => ANSI color code.
Whether we should send output to pager if output has terminal support.
Whether output has (moderate) terminal capabilities
How many columns do we have at all ?
Public Class Methods
Creates an object to display command-line help. Available values for the options are given by the hash CommandLineHelpOptions. Their meaning is:
-
'pager': disables or enables the use of a pager when sending output to a terminal
# File lib/ctioga2/commands/doc/help.rb, line 62 def initialize(options) @options_column_width = 20 @to_pager = if options.key? 'pager' options['pager'] else true end @styles = DefaultStyles.dup @color = true end
Public Instance Methods
Prints short help text suitable for a –help option about available commands, by groups (ungrouped last). It takes a list of all commands (cmds) and the list of groups to display.
todo maybe the part about sending to the pager should be factorized into a neat utility class ?
# File lib/ctioga2/commands/doc/help.rb, line 81 def print_commandline_options(cmds, groups) @to_tty = false if STDOUT.tty? @to_tty = true begin require 'curses' Curses.init_screen @total_width = Curses.cols Curses.close_screen rescue LoadError => e # We'll be missing the exact term size end end @total_width ||= 80 # 80 by default # Disable color output if not a to a terminal if ! @to_tty @color = false end should_close = false output = $stdout if @to_tty and @to_pager # We pass -R as default value... ENV['LESS'] = 'R' pager = 'pager' for w in [ENV['PAGER'], 'less', 'pager' ] if Utils::which(w) pager = w break end end begin output = IO::popen(pager, "w") should_close = true rescue end end for group in groups output.puts unless group == groups[0] name = (group && group.name) || "Ungrouped commands" if group && group.blacklisted name << " (blacklisted)" end output.puts style(name, 'title') for cmd in cmds[group].sort {|a,b| a.long_option <=> b.long_option } output.puts format_one_entry(cmd) end end output.close if should_close end
Protected Instance Methods
Colorizes some text with the given ANSI code.
Word wrapping should be used before, as it will not work after.
# File lib/ctioga2/commands/doc/help.rb, line 192 def colorize(str, code) # We split into lines, as I'm unsure color status is kept # across lines return str.split("\n").map {|s| "\e[#{code}m#{s}\e[0m" }.join("\n") end
Formats one entry of the commands
# File lib/ctioga2/commands/doc/help.rb, line 141 def format_one_entry(cmd) sh, long, desc = cmd.option_strings # Hmmm... # desc = MarkedUpText.new(@doc, desc).to_s str = "#{leading_spaces}%2s%1s %-#{@options_column_width}s" % [ sh, (sh ? "," : " "), long] size = @total_width - total_leading_spaces.size # Do the coloring: we need to parse option string first if str =~ /(.*--\S+)(.*)/ switch = $1 args = $2 str = "#{style(switch,'switch')}#{style(args,'arguments')}" end # Now, add the description. desc_lines = WordWrapper.wrap(desc, size) if long.size >= @options_column_width str += "\n#{total_leading_spaces}" end str += desc_lines.join("\n#{total_leading_spaces}") if cmd.has_options? op_start = ' options: ' options = cmd.optional_arguments. keys.sort.map { |x| "/#{cmd.normalize_option_name(x)}"}.join(' ') opts_lines = WordWrapper.wrap(options, size - op_start.size) str += "\n#{total_leading_spaces}#{style(op_start,'switch')}" + style(opts_lines.join("\n#{total_leading_spaces}#{' ' * op_start.size}"), 'options') end return str end
Spaces before any 'short' option appears
# File lib/ctioga2/commands/doc/help.rb, line 184 def leading_spaces return " " end
Changes the style of the object.
# File lib/ctioga2/commands/doc/help.rb, line 201 def style(str, what) if ! @color return str end if @styles[what] return colorize(str, @styles[what]) else return str end end
Leading spaces to align a string with the other option texts
# File lib/ctioga2/commands/doc/help.rb, line 178 def total_leading_spaces return "#{leading_spaces}#{" " *(@options_column_width + 4)}" # 4: '-o, ' end