ctioga2 0.0

data/lib/ctioga2/data/backends/description.rb

@@ -0,0 +1,405 @@
+# description.rb : a system for
+# Copyright (C) 2006, 2009 Vincent Fourmond
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+
+require 'ctioga2/utils'
+require 'ctioga2/data/backends/parameter'
+require 'ctioga2/commands/commands'
+require 'ctioga2/commands/groups'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 59 $', '$Date: 2009-05-28 23:15:50 +0200 (Thu, 28 May 2009) $')
+  
+
+  module Data
+
+    module Backends
+
+      # 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...
+      class BackendDescription
+        # The Class to instantiate. 
+        attr_accessor :object_class
+        
+        # The name of the class (short, code-like)
+        attr_accessor :name
+        
+        # (text) description !
+        attr_accessor :description
+        
+        # Long name, the one for public display
+        attr_accessor :long_name
+
+        # 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.
+        attr_reader   :param_list
+
+        # A hash index on the (short) name and the symbols of the parameters,
+        # for quick access. None of those should overlap.
+        attr_reader   :param_hash
+
+        # The priority of the CmdGroup
+        DefaultBackendGroupPriority = 20
+        
+        
+        # Initializes a Description
+        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
+
+        # Adds a new parameter to the description
+        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 an instance of the Backend described by this
+        # BackendDescription. It takes parameters that are fed
+        # to the new function, but don't use them.
+        def instantiate(*a)
+          return @object_class.new(*a)
+        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 the Backend.
+        #
+        # In addition, this function creates a group to store Backend
+        # commands.
+        #
+        # TODO: finish this !!!
+        def create_backend_commands
+          group = CmdGroup.
+            new("backend-#{@name}", 
+                "The '#{@name}' backend: #{@long_name}",
+                "The commands in this group drive the "+
+                "behaviour of the #{@long_name} backend.\n" + 
+                @description,
+                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
+
+          # TODO: add option parsing
+          Cmd.new("#{@name}", nil, "--#{@name}", [], 
+                  backend_options, "Selects the '#{@name}' backend", 
+                  nil, group) do |plotmaker, options|
+            plotmaker.data_stack.backend_factory.set_current_backend(@name)
+            for k,v in options
+              plotmaker.data_stack.backend_factory.
+                set_backend_parameter_value(@name, k, v)
+            end
+          end
+        end
+
+      end
+
+      # 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.
+      module BackendDescriptionExtend
+
+        # The functions for factory handling.
+
+        # 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.
+        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
+
+        # Checks if the class has a factory
+        def has_factory?
+          return self.respond_to?(:factory)
+        end
+
+        # Returns the base description if there is one, or nil if
+        # there isn't
+        def base_description
+          if has_factory?
+            return factory.description
+          else
+            return nil
+          end
+        end
+
+        # Returns the description list of the factory. Raises an
+        # exception if there is no factory
+        def factory_description_list
+          raise "Must have a factory" unless has_factory?
+          return factory.private_description_list
+        end
+
+        # Returns the description hash of the factory. Raises an
+        # exception if there is no factory
+        def factory_description_hash
+          raise "Must have a factory" unless has_factory?
+          return factory.private_description_hash
+        end
+
+        # Returns the factory description with the given name
+        def factory_description(name)
+          raise "Must have a factory" unless has_factory?
+          return factory_description_hash.fetch(name)
+        end
+
+        # Returns the Class object associated with the given name in
+        # the factory
+        def factory_class(name)
+          return factory_description(name).object_class
+        end
+
+        # Registers the given description to the factory. If no
+        # description is given, the current class is registered.
+        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
+        
+        # Returns the Description of the class.
+        def description
+          return @description
+        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.
+        def set_description(desc)
+          @description = desc
+          if has_factory? and factory.private_auto_register
+            register_class
+          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 !!"
+        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, but creates a attr_reader in addition
+        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_.
+        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
+
+        # 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"
+        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
+        
+        # Creates a description attached to the current class. It
+        # needs to be used before anything else.
+        def describe(name, longname = name, desc = "")
+          d = Description.new(self, name, longname, desc)
+          set_description(d)
+        end
+        
+        
+        # Imports the given parameters directly from the parent class.
+        # This function is quite naive and will not look further than
+        # the direct #superclass.
+        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
+        
+      end
+      
+    end
+  end
+end

data/lib/ctioga2/data/backends/factory.rb

@@ -0,0 +1,73 @@
+# factory.rb : a class holdling a set of Backends
+# Copyright (C) 2009 Vincent Fourmond
+ 
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
+
+require 'ctioga2/utils'
+require 'ctioga2/data/backends/backend'
+
+module CTioga2
+
+  Version::register_svn_info('$Revision: 2 $', '$Date: 2009-04-25 14:03:30 +0200 (Sat, 25 Apr 2009) $')
+
+  module Data
+
+    module Backends
+
+      # This class holds an instance of all the different Backend
+      # available, and features a 'current backend'.
+      class BackendFactory
+
+        # A hash name (as in Description#name) -> Backend
+        attr_accessor :backends
+
+        # The current Backend
+        attr_accessor :current
+
+        # Creates a new BackendFactory
+        def initialize(default)
+          @backends = {}
+          @backend_descriptions = Backend.list_backends
+          for backend in @backend_descriptions.keys
+            reset_backend(backend)
+            # Add commands
+            @backend_descriptions[backend].create_backend_commands
+          end
+          @current = @backends[default]
+        end
+
+        # Resets the given backend to its default values.
+        def reset_backend(backend)
+          @backends[backend] = @backend_descriptions[backend].instantiate
+        end
+
+        # Selects the current backend
+        def set_current_backend(backend)
+          @current = @backends[backend]
+        end
+
+        
+        # Sets the (raw) value of the parameter of the given backend
+        def set_backend_parameter_value(backend, param, value)
+          b = @backends[backend]
+          # This is way too complicated !
+          b.description.param_hash[param].set_value(b, value)
+        end
+        
+      end
+
+    end
+  end
+end