Class: Loquacious::Configuration::Help

Inherits:
Object
  • Object
show all
Defined in:
lib/loquacious/configuration/help.rb

Overview

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.

Defined Under Namespace

Classes: Error

Constant Summary collapse

@@defaults =

:stopdoc:

{
  :io => $stdout,
  :name_leader => '  - '.freeze,
  :name_length => 0,
  :name_value_sep => ' => '.freeze,
  :desc_leader => ' '.freeze,
  :nesting_nodes => true,
  :colorize => false,
  :colors => {
    :name => :white,
    :value => :cyan,
    :description => :green,
    :leader => :yellow
  }.freeze
}.freeze

Instance Method Summary collapse

Constructor Details

#initialize(config, opts = {}) ⇒ Help

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.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/loquacious/configuration/help.rb', line 58

def initialize( config, opts = {} )
  opts = @@defaults.merge opts
  @config = config.kind_of?(::Loquacious::Configuration) ? config :
            ::Loquacious::Configuration.for(config)

  @io = opts[:io]
  @name_length = Integer(opts[:name_length])
  @desc_leader = opts[:desc_leader]
  @nesting_nodes = opts[:nesting_nodes]
  @colorize = opts[:colorize]
  @colors = opts[:colors]

  unless @name_length > 0
    Iterator.new(@config).each do |node|
      length = node.name.length
      @name_length = length if length > @name_length
    end
  end

  name_leader = opts[:name_leader]
  name_value_sep = opts[:name_value_sep]
  extra_length = name_leader.length + name_value_sep.length
  name_value_sep = name_value_sep.gsub('%', '%%')

  @value_length = 78 - @name_length - extra_length
  @value_leader = "\n" + ' '*(@name_length + extra_length)
  @format = "#{name_leader}%-#{@name_length}s#{name_value_sep}%s"
  @name_format = "#{name_leader}%s"

  if colorize?
    @desc_leader = self.__send__(@colors[:leader], @desc_leader)
    name_leader = self.__send__(@colors[:leader], name_leader)
    name_value_sep = self.__send__(@colors[:leader], name_value_sep)

    @format = name_leader.dup
    @format << self.__send__(@colors[:name], "%-#{@name_length}s")
    @format << name_value_sep.dup
    @format << self.__send__(@colors[:value], "%s")

    @name_format = name_leader.dup
    @name_format << self.__send__(@colors[:name], "%s")
  end

  @desc_leader.freeze
  @value_leader.freeze
  @format.freeze
  @name_format.freeze
end

Instance Method Details

#colorize? ⇒ Boolean

Returns true if the help instance is configured to colorize the output messages. Returns false otherwise.

Returns:

  • (Boolean) 


110
111
112
 
# File 'lib/loquacious/configuration/help.rb', line 110

def colorize?
  @colorize
end

#format_name(node, show_value) ⇒ Object

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.



199
200
201
202
203
204
205
206
207
208
 
# File 'lib/loquacious/configuration/help.rb', line 199

def format_name( node, show_value )
  name = node.name.reduce @name_length
  return @name_format % name if node.config? or !show_value

  sio = StringIO.new
  PP.pp(node.obj, sio, @value_length)
  sio.seek 0
  obj = sio.read.chomp.gsub("\n", @value_leader)
  @format % [name, obj]
end

#normalize_attr(name) ⇒ Object

Normalize the attribute name.



163
164
165
166
167
168
169
170
171
 
# File 'lib/loquacious/configuration/help.rb', line 163

def normalize_attr( name )
  case name
  when String, nil; name.to_s
  when Symbol; name.to_s
  when Array;  name.join('.')
  else
    raise Error, "cannot convert #{name.inspect} into an attribute identifier"
  end
end

#print_node(node, show_description, show_value) ⇒ Object

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.



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/loquacious/configuration/help.rb', line 179

def print_node( node, show_description, show_value )
  desc = node.desc.to_s.dup
  show_description = false if desc.empty?

  if show_description
    if colorize?
      desc = desc.gsub(%r/([^\n]+)/,
                       self.__send__(@colors[:description], '\1'))
    end
    @io.puts(desc.indent(@desc_leader))
  end

  @io.puts(format_name(node, show_value))
  @io.puts if show_description
end

#show_all(opts = {}) ⇒ Object Also known as: show_attributes

Show all attributes for the configuration. The same options allowed by the show method are also supported by this method.



156
157
158
 
# File 'lib/loquacious/configuration/help.rb', line 156

def show_all( opts = {} )
  show_attribute(nil, opts)
end

#show_attribute(name = nil, opts = {}) ⇒ Object Also known as: show

call-seq:

show_attribute( name = nil, opts = {} )

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



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/loquacious/configuration/help.rb', line 134

def show_attribute( name = nil, opts = {} )
  name, opts = nil, name if name.is_a?(Hash)
  opts = {
    :descriptions => true,
    :values => false
  }.merge!(opts)

  rgxp = Regexp.new(normalize_attr(name))
  show_description = opts[:descriptions]
  show_value = opts[:values]

  Iterator.new(@config).each do |node|
    next unless rgxp =~ node.name
    next if !show_nesting_nodes? and node.config?
    print_node(node, show_description, show_value)
  end
end

#show_nesting_nodes? ⇒ Boolean

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.

Returns:

  • (Boolean) 


119
120
121
 
# File 'lib/loquacious/configuration/help.rb', line 119

def show_nesting_nodes?
  @nesting_nodes
end