Loquacious::Configuration::Help

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.

Public Class Methods

new( config, opts = {} ) click to toggle source

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

Public Instance Methods

colorize?() click to toggle source

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_name( node, show_value ) click to toggle source

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_attr( name ) click to toggle source

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

print_node( node, show_description, show_value ) click to toggle source

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( name = nil, opts = {} ) click to toggle source

Alias for: show_attribute

show_all( opts = {} ) click to toggle source

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

Also aliased as: show_attributes

show_attribute( name = nil, opts = {} ) click to toggle source

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

Also aliased as: show

show_attributes( opts = {} ) click to toggle source

Alias for: show_all

show_nesting_nodes?() click to toggle source

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

Home Classes Methods

In Files

Parent

Methods

Files

Class Index

Loquacious::Configuration::Help

Public Class Methods

Public Instance Methods