Class: MetaBuilder::Description

Inherits:
Object
  • Object
show all
Defined in:
lib/MetaBuilder/descriptions.rb

Direct Known Subclasses

SciYAG::Backends::BackendDescription

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(cls, name, long_name, description = "") ⇒ Description

Initializes a Description



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/MetaBuilder/descriptions.rb', line 112

def initialize(cls, name, long_name, description = "")
  @object_class = cls
  @name = name
  @long_name = long_name
  @description = description
  @param_list = []
  @param_hash = {}
  @init_param_list = []

  @group_list = []
  @group_hash = {}

  # There is not default group.
  @current_group = nil
end

Instance Attribute Details

#description ⇒ Object

(text) description !



89
90
91
 
# File 'lib/MetaBuilder/descriptions.rb', line 89

def description
  @description
end

#group_hash ⇒ Object

A hash indexing the groups by their name



109
110
111
 
# File 'lib/MetaBuilder/descriptions.rb', line 109

def group_hash
  @group_hash
end

#group_list ⇒ Object

The list of groups



106
107
108
 
# File 'lib/MetaBuilder/descriptions.rb', line 106

def group_list
  @group_list
end

#long_name ⇒ Object

Long name, the one for public display



92
93
94
 
# File 'lib/MetaBuilder/descriptions.rb', line 92

def long_name
  @long_name
end

#name ⇒ Object

The name of the class (short, code-like)



86
87
88
 
# File 'lib/MetaBuilder/descriptions.rb', line 86

def name
  @name
end

#object_class ⇒ Object

The Class to instantiate.



83
84
85
 
# File 'lib/MetaBuilder/descriptions.rb', line 83

def object_class
  @object_class
end

#param_hash ⇒ Object (readonly)

A hash index on the (short) name and the symbols of the parameters, for quick access. None of those should overlap.



102
103
104
 
# File 'lib/MetaBuilder/descriptions.rb', line 102

def param_hash
  @param_hash
end

#param_list ⇒ Object (readonly)

The parameter list. The parameters are added when they are found in the class description, and will be used in the order found in this list to recreate the state; beware if one parameter is depending on another one.



98
99
100
 
# File 'lib/MetaBuilder/descriptions.rb', line 98

def param_list
  @param_list
end

Instance Method Details

#add_group(group) ⇒ Object

Adds a group to the list, and switches to it



130
131
132
133
134
 
# File 'lib/MetaBuilder/descriptions.rb', line 130

def add_group(group)
  @group_list << group
  @group_hash[group.name] = group
  @current_group = group
end

#add_param(param) ⇒ Object

Adds a new parameter to the description



142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/MetaBuilder/descriptions.rb', line 142

def add_param(param)
  @param_list << param

  # Update the parameter hash, for easy access.
  @param_hash[param.reader_symbol] = param
  @param_hash[param.writer_symbol] = param
  @param_hash[param.name] = param

  # Update the current group, if necessary
  @current_group.add_parameter(param) unless @current_group.nil?
end

Subclass Description and reimplement this method to have your own banner.



205
206
207
 
# File 'lib/MetaBuilder/descriptions.rb', line 205

def banner(instance)
  return false
end

#default_state ⇒ Object

Returns the default state of an freshly created instance. This way, you can create a well-defined state of one instance via parameters set thus:

state = desc.default_state.update({'param' -> "My Value"})



259
260
261
 
# File 'lib/MetaBuilder/descriptions.rb', line 259

def default_state
  return save_state(instantiate)
end

#instantiate(*a) ⇒ Object

Creates a new (default) instance of the #object_class associated with this Description. Although this method takes additional parameters that are fed to the new method of the class, its use is strongly discouraged.



267
268
269
 
# File 'lib/MetaBuilder/descriptions.rb', line 267

def instantiate(*a)
  return @object_class.new(*a)
end

#option_parser_banner(parser, instance) ⇒ Object

Ouputs an OptionParser banner based on the return value of the #banner method.



211
212
213
214
215
 
# File 'lib/MetaBuilder/descriptions.rb', line 211

def option_parser_banner(parser, instance) 
  if b = banner(instance)
    parser.separator b
  end
end

#option_parser_fill(parser, instance, uniquify = true, groups = false) ⇒ Object

Fills an OptionParser with all the parameters the of the class. instance is the instance of the class we want to parametrize, parser is an OptionParser, and if uniquify is set, the description name is prefixed to the parameter name.



160
161
162
163
 
# File 'lib/MetaBuilder/descriptions.rb', line 160

def option_parser_fill(parser, instance, uniquify = true, groups = false)
  option_parser_banner(parser, instance)
  option_parser_options(parser, instance, uniquify, groups)
end

#option_parser_option(parser, param, instance, uniquify = true) ⇒ Object

Adds an option for the parameter param to the OptionParser parser. The corresponding parameter will be set in instance. If uniquify is set, the description name if prefixed to the option. param can be either a Parameter or a string|symbol registered in #param_hash.



190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/MetaBuilder/descriptions.rb', line 190

def option_parser_option(parser, param, instance, uniquify = true)
  raise "The instance is not of the right class" unless
    instance.is_a? @object_class
  if not param.is_a?(Parameter)
    param = param_hash.fetch(param)
  end
  if uniquify
    param_name = "#{@name}-#{param.name}"
  else
    param_name = "#{param.name}"
  end
  param.option_parser_option(parser, param_name, instance)
end

#option_parser_options(parser, instance, uniquify = true, grouping = false) ⇒ Object

Fills a parser with options for all parameters. parser, instance and uniquify have the same meaning as in #option_parser_option. If grouping is set to true, the options are organized according to group listing.



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/MetaBuilder/descriptions.rb', line 169

def option_parser_options(parser, instance, uniquify = true, 
                          grouping = false)
  if grouping
    for group in @group_list
      parser.separator group.long_name
      for param in group.parameter_list
        option_parser_option(parser, param, instance, uniquify)
      end
    end
  else
    for param in @param_list
      option_parser_option(parser, param, instance, uniquify)
    end
  end
end

#recreate_state(state) ⇒ Object

Creates a new instance of the #object_class associated with this description and fills its state



273
274
275
276
277
 
# File 'lib/MetaBuilder/descriptions.rb', line 273

def recreate_state(state)
  obj = instantiate
  restore_state(state, obj)
  return obj
end

#restore_state(state, target) ⇒ Object

Puts the target into the state returned by #save_state. The parameters are set in the order in which they are found in the class declaration.



245
246
247
248
249
250
251
252
 
# File 'lib/MetaBuilder/descriptions.rb', line 245

def restore_state(state, target)
  for param in @param_list
    if state.has_key?(param.name)
      param.set_raw(target, state[param.name])
    end
  end
  return target
end

#save_state(instance) ⇒ Object

Creates a hash representing the state of an instance of the described class at a given time. It can be fed to #restore_state and #recreate_state to restore the state to an already existing instance or to create a new one from scratch.

This function saves the raw parameters, as there is not much interest in converting to String and back from it.

It saves a duplicate of the values, not the values themselves, to make sure it really represents the state of the objects at a given time.



228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/MetaBuilder/descriptions.rb', line 228

def save_state(instance)
  ret = {}
  for param in @param_list
    val = param.get_raw(instance)
    ret[param.name] = begin # Necessary as some classes can't be duped.
                        val.dup
                      rescue
                        val # Typical case: nil, which still is a
                        # valid value
                      end
  end
  return ret
end

#switch_to_group(name) ⇒ Object

Switches to the named group



137
138
139
 
# File 'lib/MetaBuilder/descriptions.rb', line 137

def switch_to_group(name)
  @current_group = @group_hash.fetch(name)
end