Class: CTioga2::Data::Backends::BackendDescription

Inherits:
Object
  • Object
show all
Defined in:
lib/ctioga2/data/backends/description.rb

Overview

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…

Constant Summary collapse

DefaultBackendGroupPriority =

The priority of the CmdGroup

20

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(cls, name, long_name, description = "", register = true) ⇒ BackendDescription

Initializes a Description



105
106
107
108
109
110
111
112
113
114
115
116
117
 
# 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

Instance Attribute Details

#description ⇒ Object

(text) description !



85
86
87
 
# File 'lib/ctioga2/data/backends/description.rb', line 85

def description
  @description
end

#long_name ⇒ Object

Long name, the one for public display



88
89
90
 
# File 'lib/ctioga2/data/backends/description.rb', line 88

def long_name
  @long_name
end

#name ⇒ Object

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



82
83
84
 
# File 'lib/ctioga2/data/backends/description.rb', line 82

def name
  @name
end

#object_class ⇒ Object

The Class to instantiate.



79
80
81
 
# File 'lib/ctioga2/data/backends/description.rb', line 79

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.



98
99
100
 
# File 'lib/ctioga2/data/backends/description.rb', line 98

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.



94
95
96
 
# File 'lib/ctioga2/data/backends/description.rb', line 94

def param_list
  @param_list
end

Instance Method Details

#add_param(param) ⇒ Object

Adds a new parameter to the description



120
121
122
123
124
125
126
127
128
129
130
 
# 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

#create_backend_commands ⇒ Object

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 the Backend.

In addition, this function creates a group to store Backend commands.

todo finish this !!!



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# 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

#instantiate(*a) ⇒ Object

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.



135
136
137
 
# File 'lib/ctioga2/data/backends/description.rb', line 135

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