projects.mako.cc - selectricity-live/blob - vendor/plugins/engines/lib/engines/ruby_extensions.rb

   1 #--
   2 # Add these methods to the top-level module so that they are available in all
   3 # modules, etc
   4 #++
   5 class ::Module
   6   # Defines a constant within a module/class ONLY if that constant does
   7   # not already exist.
   8   #
   9   # This can be used to implement defaults in plugins/engines/libraries, e.g.
  10   # if a plugin module exists:
  11   #   module MyPlugin
  12   #     default_constant :MyDefault, "the_default_value"
  13   #   end
  14   #
  15   # then developers can override this default by defining that constant at
  16   # some point *before* the module/plugin gets loaded (such as environment.rb)
  17   def default_constant(name, value)
  18     if !(name.is_a?(String) or name.is_a?(Symbol))
  19       raise "Cannot use a #{name.class.name} ['#{name}'] object as a constant name"
  20     end
  21     if !self.const_defined?(name)
  22       self.class_eval("#{name} = #{value.inspect}")
  23     end
  24   end
  25
  26   # A mechanism for defining configuration of Modules. With this
  27   # mechanism, default values for configuration can be provided within shareable
  28   # code, and the end user can customise the configuration without having to
  29   # provide all values.
  30   #
  31   # Example:
  32   #
  33   #  module MyModule
  34   #    config :param_one, "some value"
  35   #    config :param_two, 12345
  36   #  end
  37   #
  38   # Those values can now be accessed by the following method
  39   #
  40   #   MyModule.config :param_one
  41   #     => "some value"
  42   #   MyModule.config :param_two
  43   #     => 12345
  44   #
  45   # ... or, if you have overrriden the method 'config'
  46   #
  47   #   MyModule::CONFIG[:param_one]
  48   #     => "some value"
  49   #   MyModule::CONFIG[:param_two]
  50   #     => 12345
  51   #
  52   # Once a value is stored in the configuration, it will not be altered
  53   # by subsequent assignments, unless a special flag is given:
  54   #
  55   #   (later on in your code, most likely in another file)
  56   #   module MyModule
  57   #     config :param_one, "another value"
  58   #     config :param_two, 98765, :force
  59   #   end
  60   #
  61   # The configuration is now:
  62   #
  63   #   MyModule.config :param_one
  64   #     => "some value" # not changed
  65   #   MyModule.config :param_two
  66   #     => 98765
  67   #
  68   # Configuration values can also be given as a Hash:
  69   #
  70   #   MyModule.config :param1 => 'value1', :param2 => 'value2'
  71   #
  72   # Setting of these values can also be forced:
  73   #
  74   #   MyModule.config :param1 => 'value3', :param2 => 'value4', :force => true
  75   #
  76   # A value of anything other than false or nil given for the :force key will
  77   # result in the new values *always* being set.
  78   def config(*args)
  79
  80     raise "config expects at least one argument" if args.empty?
  81
  82     # extract the arguments
  83     if args[0].is_a?(Hash)
  84       override = args[0][:force]
  85       args[0].delete(:force)
  86       args[0].each { |key, value| _handle_config(key, value, override)}
  87     else
  88       _handle_config(*args)
  89     end
  90   end
  91
  92   private
  93     # Actually set the config values
  94     def _handle_config(name, value=nil, override=false)
  95       if !self.const_defined?("CONFIG")
  96         self.class_eval("CONFIG = {}")
  97       end
  98
  99       if value != nil
 100         if override or self::CONFIG[name] == nil
 101           self::CONFIG[name] = value
 102         end
 103       else
 104         # if we pass an array of config keys to config(),
 105         # get the array of values back
 106         if name.is_a? Array
 107           name.map { |c| self::CONFIG[c] }
 108         else
 109           self::CONFIG[name]
 110         end
 111       end
 112     end
 113 end