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       Marshal.restore(val)
 124     end
 125
 126     # lookup a key in the registry
 127     def [](key)
 128       if @registry.has_key?(@prefix + key)
 129         return restore(@registry[@prefix + key])
 130       elsif @default != nil
 131         return restore(@default)
 132       else
 133         return nil
 134       end
 135     end
 136
 137     # set a key in the registry
 138     def []=(key,value)
 139       @registry[@prefix + key] = store(value)
 140     end
 141
 142     # set the default value for registry lookups, if the key sought is not
 143     # found, the default will be returned. The default default (har) is nil.
 144     def set_default (default)
 145       @default = store(default)
 146     end
 147
 148     # just like Hash#each
 149     def each(&block)
 150       @registry.each {|key,value|
 151         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 152           block.call(key, restore(value))
 153         end
 154       }
 155     end
 156
 157     # just like Hash#each_key
 158     def each_key(&block)
 159       @registry.each {|key, value|
 160         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 161           block.call(key)
 162         end
 163       }
 164     end
 165
 166     # just like Hash#each_value
 167     def each_value(&block)
 168       @registry.each {|key, value|
 169         if key =~ /^#{Regexp.escape(@prefix)}/
 170           block.call(restore(value))
 171         end
 172       }
 173     end
 174
 175     # just like Hash#has_key?
 176     def has_key?(key)
 177       return @registry.has_key?(@prefix + key)
 178     end
 179     alias include? has_key?
 180     alias member? has_key?
 181
 182     # just like Hash#has_both?
 183     def has_both?(key, value)
 184       return @registry.has_both?(@prefix + key, store(value))
 185     end
 186
 187     # just like Hash#has_value?
 188     def has_value?(value)
 189       return @registry.has_value?(store(value))
 190     end
 191
 192     # just like Hash#index?
 193     def index(value)
 194       ind = @registry.index(store(value))
 195       if ind && ind.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 196         return ind
 197       else
 198         return nil
 199       end
 200     end
 201
 202     # delete a key from the registry
 203     def delete(key)
 204       return @registry.delete(@prefix + key)
 205     end
 206
 207     # returns a list of your keys
 208     def keys
 209       return @registry.keys.collect {|key|
 210         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 211           key
 212         else
 213           nil
 214         end
 215       }.compact
 216     end
 217
 218     # Return an array of all associations [key, value] in your namespace
 219     def to_a
 220       ret = Array.new
 221       @registry.each {|key, value|
 222         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 223           ret << [key, restore(value)]
 224         end
 225       }
 226       return ret
 227     end
 228
 229     # Return an hash of all associations {key => value} in your namespace
 230     def to_hash
 231       ret = Hash.new
 232       @registry.each {|key, value|
 233         if key.gsub!(/^#{Regexp.escape(@prefix)}/, "")
 234           ret[key] = restore(value)
 235         end
 236       }
 237       return ret
 238     end
 239
 240     # empties the registry (restricted to your namespace)
 241     def clear
 242       @registry.each_key {|key|
 243         if key =~ /^#{Regexp.escape(@prefix)}/
 244           @registry.delete(key)
 245         end
 246       }
 247     end
 248     alias truncate clear
 249
 250     # returns an array of the values in your namespace of the registry
 251     def values
 252       ret = Array.new
 253       self.each {|k,v|
 254         ret << restore(v)
 255       }
 256       return ret
 257     end
 258
 259     # returns the number of keys in your registry namespace
 260     def length
 261       self.keys.length
 262     end
 263     alias size length
 264
 265     def flush
 266       @registry.flush
 267     end
 268
 269   end
 270
 271 end