Object
Generate nicely formatted help messages for a configuration. The Help class iterates over all the attributes in a configuration and outputs the name, value, and description to an IO stream. The format of the messages can be configured, and the description and/or value of the attribute can be shown or hidden independently.
Create a new Help instance for the given configuration where config can be either a Configuration instance or a configuration name or symbol. Several options can be provided to determine how the configuration information will be printed to the IO stream.
:name_leader String appearing before the attribute name :name_length Maximum length for an attribute name :name_value_sep String separating the attribute name from the value :desc_leader String appearing before the description :io The IO object where help will be written :nesting_nodes Flag to enable or disable output of nesting nodes (this does not affect display of attributes contained by the nesting nodes) :colorize Flag to colorize the output or not :colors Hash of colors for the name, value, description :name Name color :value Value color :description Description color :leader Leader and spacer color
The description is printed before each attribute name and value on its own line.
# File lib/loquacious/configuration/help.rb, line 58 58: def initialize( config, opts = {} ) 59: opts = @@defaults.merge opts 60: @config = config.kind_of?(::Loquacious::Configuration) ? config : 61: ::Loquacious::Configuration.for(config) 62: 63: @io = opts[:io] 64: @name_length = Integer(opts[:name_length]) 65: @desc_leader = opts[:desc_leader] 66: @nesting_nodes = opts[:nesting_nodes] 67: @colorize = opts[:colorize] 68: @colors = opts[:colors] 69: 70: unless @name_length > 0 71: Iterator.new(@config).each do |node| 72: length = node.name.length 73: @name_length = length if length > @name_length 74: end 75: end 76: 77: name_leader = opts[:name_leader] 78: name_value_sep = opts[:name_value_sep] 79: extra_length = name_leader.length + name_value_sep.length 80: name_value_sep = name_value_sep.gsub('%', '%%') 81: 82: @value_length = 78 - @name_length - extra_length 83: @value_leader = "\n" + ' '*(@name_length + extra_length) 84: @format = "#{name_leader}%-#{@name_length}s#{name_value_sep}%s" 85: @name_format = "#{name_leader}%s" 86: 87: if colorize? 88: @desc_leader = self.__send__(@colors[:leader], @desc_leader) 89: name_leader = self.__send__(@colors[:leader], name_leader) 90: name_value_sep = self.__send__(@colors[:leader], name_value_sep) 91: 92: @format = name_leader.dup 93: @format << self.__send__(@colors[:name], "%-#{@name_length}s") 94: @format << name_value_sep.dup 95: @format << self.__send__(@colors[:value], "%s") 96: 97: @name_format = name_leader.dup 98: @name_format << self.__send__(@colors[:name], "%s") 99: end 100: 101: @desc_leader.freeze 102: @value_leader.freeze 103: @format.freeze 104: @name_format.freeze 105: end
Returns true if the help instance is configured to colorize the output messages. Returns false otherwise.
# File lib/loquacious/configuration/help.rb, line 110 110: def colorize? 111: @colorize 112: end
Format the name of the attribute pointed at by the given node. If the show_value flag is set to true, then the attribute value will also be included in the returned string.
# File lib/loquacious/configuration/help.rb, line 199 199: def format_name( node, show_value ) 200: name = node.name.reduce @name_length 201: return @name_format % name if node.config? or !show_value 202: 203: sio = StringIO.new 204: PP.pp(node.obj, sio, @value_length) 205: sio.seek 0 206: obj = sio.read.chomp.gsub("\n", @value_leader) 207: @format % [name, obj] 208: end
Normalize the attribute name.
# File lib/loquacious/configuration/help.rb, line 163 163: def normalize_attr( name ) 164: case name 165: when String, nil; name.to_s 166: when Symbol; name.to_s 167: when Array; name.join('.') 168: else 169: raise Error, "cannot convert #{name.inspect} into an attribute identifier" 170: end 171: end
Format the attribute name, value, and description and print the results. The value can be printed or not by setting the show_value flag to either true or false. The description can be printed or not by setting the show_description flag to either true or false.
# File lib/loquacious/configuration/help.rb, line 179 179: def print_node( node, show_description, show_value ) 180: desc = node.desc.to_s.dup 181: show_description = false if desc.empty? 182: 183: if show_description 184: if colorize? 185: desc = desc.gsub(/([^\n]+)/, 186: self.__send__(@colors[:description], '\1')) 187: end 188: @io.puts(desc.indent(@desc_leader)) 189: end 190: 191: @io.puts(format_name(node, show_value)) 192: @io.puts if show_description 193: end
Show all attributes for the configuration. The same options allowed by the show method are also supported by this method.
# File lib/loquacious/configuration/help.rb, line 156 156: def show_all( opts = {} ) 157: show_attribute(nil, opts) 158: end
Use this method to show the description for a single attribute or for all the attributes if no name is given. The options allow you to show the values along with the attributes and to hide the descriptions (if all you want to see are the values).
:descriptions => true to show descriptions and false to hide them :values => true to show values and false to hide them
# File lib/loquacious/configuration/help.rb, line 134 134: def show_attribute( name = nil, opts = {} ) 135: name, opts = nil, name if name.is_a?(Hash) 136: opts = { 137: :descriptions => true, 138: :values => false 139: }.merge!(opts) 140: 141: rgxp = Regexp.new(normalize_attr(name)) 142: show_description = opts[:descriptions] 143: show_value = opts[:values] 144: 145: Iterator.new(@config).each do |node| 146: next unless rgxp =~ node.name 147: next if !show_nesting_nodes? and node.config? 148: print_node(node, show_description, show_value) 149: end 150: end
Returns true if the help instance is configured to show nesting configuration nodes when iterating over the attributes. This only prevents the nesting node name from being displayed. The attributes nested under the node are still displayed regardless of this setting.
# File lib/loquacious/configuration/help.rb, line 119 119: def show_nesting_nodes? 120: @nesting_nodes 121: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.