class CTioga2::Data::Backends::BackendDescription
The Description class is a meta-information class that records several informations about the class:
-
a basic name, code-like, which is used mainly for internal purposes;
-
a long name, more explanatory, in proper English (or any other language. By the way, it should definitely be translated in a production environment);
-
a description itself, some small text describing the nature of the class;
-
a list of all the Parameters that are important for the class, and enough to recreate the state of an object.
This class is fairly general, and can be subclassed to fit specific needs. An example is in the SciYAG/Backend system, where the description of a backend is derived from Description.
To make use of the Description system for a class, use the following:
class SomeClass extend MetaBuilder::DescriptionExtend include MetaBuilder::DescriptionInclude describe 'someclass', 'Some nice class', <<EOD The description of a nice class EOD end
Descriptions can be used in two completely different manners:
-
you can use a single Description to facilitate the interface with the user to query|save parameters;
-
you can use the Description system to describe a whole set of classes providing similar functions and sharing a base ancestor, such as series of input|output plugins, database formats, themes… In this case, the Description system can act as a real plugin factory, recording every new subclass of the base one and providing facilities to prompt the user.
Please note that if you want to use the facilities to dynamically create objects at run-time, the classes used by describe *should not need any parameter for initialize*.
todo add functions to prepare commands to set the various parameters
todo write the parameters stuff again…
Constants
- DefaultBackendGroupPriority
The priority of the CmdGroup
Attributes
(text) description !
Long name, the one for public display
The name of the class (short, code-like)
The Class to instantiate.
A hash index on the (short) name and the symbols of the parameters, for quick access. None of those should overlap.
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.
Public Class Methods
Initializes a Description
# File lib/ctioga2/data/backends/description.rb, line 105 def initialize(cls, name, long_name, description = "", register = true) @object_class = cls @name = name @long_name = long_name @description = description @param_list = [] @param_hash = {} @init_param_list = [] if register Backend.register_class(self) end end
Public Instance Methods
Adds a new parameter to the description
# File lib/ctioga2/data/backends/description.rb, line 120 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
Creates a set of Cmd to interact with a given Backend
. Commands
created are:
-
one for each parameter to allow modification of its type
-
one for the selection of the
Backend
, allowing the use of optional arguments to change (permanently) the behaviour of theBackend
.
In addition, this function creates a group to store Backend
commands.
todo finish this !!!
# File lib/ctioga2/data/backends/description.rb, line 150 def create_backend_commands group = CmdGroup. new("backend-#{@name}", "The '#{@name}' backend: #{@long_name}", "The commands in this group drive the "+ "behaviour of the {backend: #{@name}} backend;\n" + "see its documentation for more information", DefaultBackendGroupPriority) backend_options = {} # Again, each is needed for scoping problems. @param_list.each do |param| arg = CmdArg.new(param.type, param.name) a = Cmd.new("#{@name}-#{param.name}", nil, "--#{@name}-#{param.name}", [arg], {}, "Set the #{param.long_name} parameter of backend '#{@name}'", param.description, group) do |plotmaker, value| plotmaker.data_stack.backend_factory. set_backend_parameter_value(@name, param.name, value) end backend_options[param.name] = arg.dup end Cmd.new("#{@name}", nil, "--#{@name}", [], backend_options, "Selects the '{backend: #{@name}}' backend", nil, group) do |plotmaker, options| plotmaker.data_stack.backend_factory.set_current_backend(@name) if options for k,v in options plotmaker.data_stack.backend_factory. set_backend_parameter_value(@name, k, v) end end # Commands#run_command set options to # nil if the options hash is an empty hash, so we have to # tackle this if it happens end end
Creates an instance of the Backend
described by this BackendDescription
. It takes parameters that are fed to the new function, but don't use them.
# File lib/ctioga2/data/backends/description.rb, line 135 def instantiate(*a) return @object_class.new(*a) end