module CTioga2::Data::Backends::BackendDescriptionExtend
This module should be used with extend
to provide the class with descriptions functionnalities. Please not that all the instance methods defined here will become class methods in the class you extend.
This module defines several methods to add a description (describe
) to a class, to add parameters (param
, param_noaccess) and to import parameters from parents (inherit_parameters
).
Factories can be created using the craete_factory statement. This makes the current class the factory repository for all the subclasses. It creates a factory class method returning the base factory. You can use register_class
to register the current class into the base factory class.
Public Instance Methods
Returns the base description if there is one, or nil if there isn't
# File lib/ctioga2/data/backends/description.rb, line 255 def base_description if has_factory? return factory.description else return nil end end
Makes this class the factory class for all subclasses. It creates four class methods: base_factory, that always points to the closest factory in the hierarchy and three methods used internally.
If auto is true, the subclasses are all automatically registered to the factory. If register_self is true the class itself is registered. It is probably not a good idea, so it is off by default.
# File lib/ctioga2/data/backends/description.rb, line 220 def create_factory(auto = true, register_self = false) cls = self # we create a temporary module so that we can use # define_method with a block and extend this class with it mod = Module.new mod.send(:define_method, :factory) do return cls end mod.send(:define_method, :private_description_list) do return @registered_descriptions end mod.send(:define_method, :private_description_hash) do return @registered_descriptions_hash end # Creates an accessor for the factory class mod.send(:define_method, :private_auto_register) do @auto_register_subclasses end self.extend(mod) # Creates the necessary arrays|hashes to handle the # registered classes: @registered_descriptions = [] @registered_descriptions_hash = {} @auto_register_subclasses = auto end
Creates a description attached to the current class. It needs to be used before anything else.
# File lib/ctioga2/data/backends/description.rb, line 377 def describe(name, longname = name, desc = "") d = Description.new(self, name, longname, desc) set_description(d) end
Returns the Description of the class.
# File lib/ctioga2/data/backends/description.rb, line 300 def description return @description end
Returns the Class object associated with the given name in the factory
# File lib/ctioga2/data/backends/description.rb, line 285 def factory_class(name) return factory_description(name).object_class end
Returns the factory description with the given name
# File lib/ctioga2/data/backends/description.rb, line 278 def factory_description(name) raise "Must have a factory" unless has_factory? return factory_description_hash.fetch(name) end
Returns the description hash of the factory. Raises an exception if there is no factory
# File lib/ctioga2/data/backends/description.rb, line 272 def factory_description_hash raise "Must have a factory" unless has_factory? return factory.private_description_hash end
Returns the description list of the factory. Raises an exception if there is no factory
# File lib/ctioga2/data/backends/description.rb, line 265 def factory_description_list raise "Must have a factory" unless has_factory? return factory.private_description_list end
Checks if the class has a factory
# File lib/ctioga2/data/backends/description.rb, line 249 def has_factory? return self.respond_to?(:factory) end
Imports the given parameters directly from the parent class. This function is quite naive and will not look further than the direct superclass.
# File lib/ctioga2/data/backends/description.rb, line 386 def inherit_parameters(*names) if self.superclass.respond_to?(:description) parents_params = self.superclass.description.param_hash for n in names if parents_params.key?(n) description.add_param(parents_params[n]) else warn { "Param #{n} not found" } end end else warn { "The parent class has no description" } end end
Registers an new parameter, with the following properties:
-
writer is the name of the method used to write that parameter;
-
reader the name of the method that returns its current value;
-
name is a short code-like name of the parameter (typically lowercase);
-
long_name is a more descriptive name, properly capitalized and localized if possible;
-
type is it's type. Please see the MetaBuilder::ParameterType for a better description of what is a type;
-
desc is a proper (short) description of the parameter, something that would fit on a What's this box, for instance.
-
attrs are optional parameters that may come useful, see Parameter#attributes documentation.
You might want to use the param_reader
, param_writer
, and param_accessor
facilities that create the respective accessors in addition. A typical example would be:
param :set_size, :size, 'size', "Size", {:type => :integer}, "The size !!"
# File lib/ctioga2/data/backends/description.rb, line 335 def param(writer, reader, name, long_name, type, desc = "") raise "Use describe first" if description.nil? param = nil param = Parameter.new(name, writer, reader, long_name, type, desc) description.add_param(param) return param end
The same as param_writer
, except that an attr_writer is created for the symbol instead of only a attr_writer. The most useful of the four methods. Typical use:
param_accessor :name, 'name', "Object name", {:type => :string}, "The name of the object"
# File lib/ctioga2/data/backends/description.rb, line 368 def param_accessor(symbol, name, long_name, type, desc = "") writer = (symbol.to_s + '=').to_sym attr_accessor symbol return param(writer, symbol, name, long_name, type, desc) end
The same as param
, but creates a attr_reader in addition
# File lib/ctioga2/data/backends/description.rb, line 346 def param_reader(writer, reader, name, long_name, type, desc = "") attr_reader reader return param(writer, reader, name, long_name, type, desc) end
The same as param
, except that writer is made from symbol by appending a = at the end. An attr_writer is created for the symbol.
# File lib/ctioga2/data/backends/description.rb, line 355 def param_writer(symbol, name, long_name, type, desc = "") writer = (symbol.to_s + '=').to_sym attr_writer symbol return param(writer, symbol, name, long_name, type, desc) end
Registers the given description to the factory. If no description is given, the current class is registered.
# File lib/ctioga2/data/backends/description.rb, line 291 def register_class(desc = nil) raise "One of the superclasses should have a 'factory' statement" unless has_factory? desc = description if desc.nil? factory_description_list << desc factory_description_hash[desc.name] = desc end
Sets the description of the class. It is probably way better to use describe
, or write your own class method in the base class in the case of a family of classes.
# File lib/ctioga2/data/backends/description.rb, line 307 def set_description(desc) @description = desc if has_factory? and factory.private_auto_register register_class end end