lib/rbot/registry.rb

   1 require 'rbot/dbhash'
   2
   3 module Irc
   4
   5   # this is the backend of the RegistryAccessor class, which ties it to a
   6   # DBHash object called plugin_registry(.db). All methods are delegated to
   7   # the DBHash.
   8   class BotRegistry
   9     def initialize(bot)
  10       @bot = bot
  11       upgrade_data
  12       @db = DBTree.new @bot, "plugin_registry"
  13     end
  14
  15     # delegation hack
  16     def method_missing(method, *args, &block)
  17       @db.send(method, *args, &block)
  18     end
  19
  20     # check for older versions of rbot with data formats that require updating
  21     # NB this function is called _early_ in init(), pretty much all you have to
  22     # work with is @bot.botclass.
  23     def upgrade_data
  24       if File.exist?("#{@bot.botclass}/registry.db")
  25         puts "upgrading old-style (rbot 0.9.5 or earlier) plugin registry to new format"
  26         old = BDB::Hash.open "#{@bot.botclass}/registry.db", nil,
  27                              "r+", 0600, "set_pagesize" => 1024,
  28                              "set_cachesize" => [0, 32 * 1024, 0]
  29         new = BDB::CIBtree.open "#{@bot.botclass}/plugin_registry.db", nil,
  30                                 BDB::CREATE | BDB::EXCL | BDB::TRUNCATE,
  31                                 0600, "set_pagesize" => 1024,
  32                                 "set_cachesize" => [0, 32 * 1024, 0]
  33         old.each {|k,v|
  34           new[k] = v
  35         }
  36         old.close
  37         new.close
  38         File.delete("#{@bot.botclass}/registry.db")
  39       end
  40     end
  41   end
  42
  43   # This class provides persistent storage for plugins via a hash interface.
  44   # The default mode is an object store, so you can store ruby objects and
  45   # reference them with hash keys. This is because the default store/restore
  46   # methods of the plugins' RegistryAccessor are calls to Marshal.dump and
  47   # Marshal.restore,
  48   # for example:
  49   #   blah = Hash.new
  50   #   blah[:foo] = "fum"
  51   #   @registry[:blah] = blah
  52   # then, even after the bot is shut down and disconnected, on the next run you
  53   # can access the blah object as it was, with:
  54   #   blah = @registry[:blah]
  55   # The registry can of course be used to store simple strings, fixnums, etc as
  56   # well, and should be useful to store or cache plugin data or dynamic plugin
  57   # configuration.
  58   #
  59   # WARNING:
  60   # in object store mode, don't make the mistake of treating it like a live
  61   # object, e.g. (using the example above)
  62   #   @registry[:blah][:foo] = "flump"
  63   # will NOT modify the object in the registry - remember that BotRegistry#[]
  64   # returns a Marshal.restore'd object, the object you just modified in place
  65   # will disappear. You would need to:
  66   #   blah = @registry[:blah]
  67   #   blah[:foo] = "flump"
  68   #   @registry[:blah] = blah
  69
  70   # If you don't need to store objects, and strictly want a persistant hash of
  71   # strings, you can override the store/restore methods to suit your needs, for
  72   # example (in your plugin):
  73   #   def initialize
  74   #     class << @registry
  75   #       def store(val)
  76   #         val
  77   #       end
  78   #       def restore(val)
  79   #         val
  80   #       end
  81   #     end
  82   #   end
  83   # Your plugins section of the registry is private, it has its own namespace
  84   # (derived from the plugin's class name, so change it and lose your data).
  85   # Calls to registry.each etc, will only iterate over your namespace.
  86   class BotRegistryAccessor
  87     # plugins don't call this - a BotRegistryAccessor is created for them and
  88     # is accessible via @registry.
  89     def initialize(bot, prefix)
  90       @bot = bot
  91       @registry = @bot.registry
  92       @orig_prefix = prefix
  93       @prefix = prefix + "/"
  94       @default = nil
  95       # debug "initializing registry accessor with prefix #{@prefix}"
  96     end
  97
  98     # use this to chop up your namespace into bits, so you can keep and
  99     # reference separate object stores under the same registry
 100     def sub_registry(prefix)
 101       return BotRegistryAccessor.new(@bot, @orig_prefix + "+" + prefix)
 102     end
 103
 104     # convert value to string form for storing in the registry
 105     # defaults to Marshal.dump(val) but you can override this in your module's
 106     # registry object to use any method you like.
 107     # For example, if you always just handle strings use:
 108     #   def store(val)
 109     #     val
 110     #   end
 111     def store(val)
 112       Marshal.dump(val)
 113     end
 114
 115     # restores object from string form, restore(store(val)) must return val.
 116     # If you override store, you should override restore to reverse the
 117     # action.
 118     # For example, if you always just handle strings use:
 119     #   def restore(val)
 120     #     val
 121     #   end
 122     def restore(val)
 123       begin
 124         Marshal.restore(val)
 125       rescue
 126         $stderr.puts "failed to restore marshal data, falling back to default"
 127         if @default != nil
 128           begin
 129             return Marshal.restore(@default)
 130           rescue
 131             return nil
 132           end
 133         else
 134           return nil
 135         end
 136       end
 137     end
 138
 139     # lookup a key in the registry
 140     def [](key)
 141       if @registry.has_key?(@prefix + key)
 142         return restore(@registry[@prefix + key])
 143       elsif @default != nil
 144         return restore(@default)
 145       else
 146         return nil
 147       end
 148     end
 149
 150     # set a key in the registry
 151     def []=(key,value)
 152       @registry[@prefix + key] = store(value)
 153     end
 154
 155     # set the default value for registry lookups, if the key sought is not
 156     # found, the default will be returned. The default default (har) is nil.
 157     def set_default (default)
 158       @default = store(default)
 159     end
 160
 161     # just like Hash#each
 162     def each(&block)
 163       @registry.each {|key,value|
 164         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 165           block.call(key, restore(value))
 166         end
 167       }
 168     end
 169
 170     # just like Hash#each_key
 171     def each_key(&block)
 172       @registry.each {|key, value|
 173         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 174           block.call(key)
 175         end
 176       }
 177     end
 178
 179     # just like Hash#each_value
 180     def each_value(&block)
 181       @registry.each {|key, value|
 182         if key =~ /^#{Regexp.escape(@prefix)}/
 183           block.call(restore(value))
 184         end
 185       }
 186     end
 187
 188     # just like Hash#has_key?
 189     def has_key?(key)
 190       return @registry.has_key?(@prefix + key)
 191     end
 192     alias include? has_key?
 193     alias member? has_key?
 194
 195     # just like Hash#has_both?
 196     def has_both?(key, value)
 197       return @registry.has_both?(@prefix + key, store(value))
 198     end
 199
 200     # just like Hash#has_value?
 201     def has_value?(value)
 202       return @registry.has_value?(store(value))
 203     end
 204
 205     # just like Hash#index?
 206     def index(value)
 207       ind = @registry.index(store(value))
 208       if ind && ind.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 209         return ind
 210       else
 211         return nil
 212       end
 213     end
 214
 215     # delete a key from the registry
 216     def delete(key)
 217       return @registry.delete(@prefix + key)
 218     end
 219
 220     # returns a list of your keys
 221     def keys
 222       return @registry.keys.collect {|key|
 223         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 224           key
 225         else
 226           nil
 227         end
 228       }.compact
 229     end
 230
 231     # Return an array of all associations [key, value] in your namespace
 232     def to_a
 233       ret = Array.new
 234       @registry.each {|key, value|
 235         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 236           ret << [key, restore(value)]
 237         end
 238       }
 239       return ret
 240     end
 241
 242     # Return an hash of all associations {key => value} in your namespace
 243     def to_hash
 244       ret = Hash.new
 245       @registry.each {|key, value|
 246         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 247           ret[key] = restore(value)
 248         end
 249       }
 250       return ret
 251     end
 252
 253     # empties the registry (restricted to your namespace)
 254     def clear
 255       @registry.each_key {|key|
 256         if key =~ /^#{Regexp.escape(@prefix)}/
 257           @registry.delete(key)
 258         end
 259       }
 260     end
 261     alias truncate clear
 262
 263     # returns an array of the values in your namespace of the registry
 264     def values
 265       ret = Array.new
 266       self.each {|k,v|
 267         ret << restore(v)
 268       }
 269       return ret
 270     end
 271
 272     # returns the number of keys in your registry namespace
 273     def length
 274       self.keys.length
 275     end
 276     alias size length
 277
 278     def flush
 279       @registry.flush
 280     end
 281
 282   end
 283
 284 end