yard 0.9.18 → 0.9.23

data/lib/yard/registry_resolver.rb

@@ -1,189 +1,231 @@
-# frozen_string_literal: true
-module YARD
-  # Handles all logic for complex lexical and inherited object resolution.
-  # Used by {Registry.resolve}, so there is no need to use this class
-  # directly.
-  #
-  # @see Registry.resolve
-  # @since 0.9.1
-  class RegistryResolver
-    include CodeObjects::NamespaceMapper
-
-    # Creates a new resolver object for a registry.
-    #
-    # @param registry [Registry] only set this if customizing the registry
-    #   object
-    def initialize(registry = Registry)
-      @registry = registry
-      @default_sep = nil
-    end
-
-    # Performs a lookup on a given path in the registry. Resolution will occur
-    # in a similar way to standard Ruby identifier resolution, doing lexical
-    # lookup, as well as (optionally) through the inheritance chain. A proxy
-    # object can be returned if the lookup fails for future resolution. The
-    # proxy will be type hinted with the +type+ used in the original lookup.
-    #
-    # @option opts namespace [CodeObjects::Base, :root, nil] (nil) the namespace
-    #   object to start searching from. If root or nil is provided, {Registry.root}
-    #   is assumed.
-    # @option opts inheritance [Boolean] (false) whether to perform lookups through
-    #   the inheritance chain (includes mixins)
-    # @option opts proxy_fallback [Boolean] (false) when true, a proxy is returned
-    #   if no match is found
-    # @option opts type [Symbol] (nil) an optional type hint for the resolver
-    #   to consider when performing a lookup. If a type is provided and the
-    #   resolved object's type does not match the hint, the object is discarded.
-    # @return [CodeObjects::Base, CodeObjects::Proxy, nil] the first object
-    #   that matches the path lookup. If proxy_fallback is provided, a proxy
-    #   object will be returned in the event of no match, otherwise nil will
-    #   be returned.
-    # @example A lookup from root
-    #   resolver.lookup_by_path("A::B::C")
-    # @example A lookup from the A::B namespace
-    #   resolver.lookup_by_path("C", namespace: P("A::B"))
-    # @example A lookup on a method through the inheritance tree
-    #   resolver.lookup_by_math("A::B#foo", inheritance: true)
-    def lookup_by_path(path, opts = {})
-      path = path.to_s
-      namespace = opts[:namespace]
-      inheritance = opts[:inheritance] || false
-      proxy_fallback = opts[:proxy_fallback] || false
-      type = opts[:type]
-
-      if namespace.is_a?(CodeObjects::Proxy)
-        return proxy_fallback ? CodeObjects::Proxy.new(namespace, path, type) : nil
-      end
-
-      if namespace == :root || !namespace
-        namespace = @registry.root
-      else
-        namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
-      end
-      orignamespace = namespace
-
-      if path =~ /\A#{default_separator}/
-        path = $'
-        namespace = @registry.root
-        orignamespace = @registry.root
-      end
-
-      resolved = nil
-      lexical_lookup = 0
-      while namespace && !resolved
-        resolved = lookup_path_direct(namespace, path, type)
-        resolved ||= lookup_path_inherited(namespace, path, type) if inheritance
-        break if resolved
-        namespace = namespace.parent
-        lexical_lookup += 1
-      end
-
-      # method objects cannot be resolved through lexical lookup by more than 1 ns
-      if lexical_lookup > 1 && resolved.is_a?(CodeObjects::MethodObject)
-        resolved = nil
-      end
-
-      if proxy_fallback
-        resolved ||= CodeObjects::Proxy.new(orignamespace, path, type)
-      end
-
-      resolved
-    end
-
-    private
-
-    # return [Boolean] if the obj's type matches the provided type.
-    def validate(obj, type)
-      !type || (obj && obj.type == type) ? obj : nil
-    end
-
-    # Performs a lexical lookup from a namespace for a path and a type hint.
-    def lookup_path_direct(namespace, path, type)
-      result = namespace.root? && validate(@registry.at(path), type)
-      return result if result
-
-      if path =~ /\A(#{separators_match})/
-        return validate(@registry.at(namespace.path + path), type)
-      end
-
-      separators.each do |sep|
-        result = validate(@registry.at(namespace.path + sep + path), type)
-        return result if result
-      end
-
-      nil
-    end
-
-    # Performs a lookup through the inheritance chain on a path with a type hint.
-    def lookup_path_inherited(namespace, path, type)
-      resolved = nil
-      last_obj = namespace
-      scopes = []
-      last_sep = nil
-      pos = 0
-
-      if path =~ /\A(#{separators_match})/
-        last_sep = $1
-        path = $'
-      end
-
-      path.scan(/(.+?)(#{separators_match}|$)/).each do |part, sep|
-        cur_obj = nil
-        pos += "#{part}#{sep}".length
-        parsed_end = pos == path.length
-
-        if !last_obj || (!parsed_end && !last_obj.is_a?(CodeObjects::NamespaceObject))
-          break # can't continue
-        end
-
-        collect_namespaces(last_obj).each do |ns|
-          next if ns.is_a?(CodeObjects::Proxy)
-
-          found = nil
-          search_seps = []
-          scopes.each do |scope|
-            search_seps += separators_for_type(scope)
-          end
-
-          if search_seps.empty?
-            search_seps =
-              if ns.type == :root
-                [""]
-              elsif last_sep.nil?
-                separators
-              else
-                [@default_sep]
-              end
-          end
-
-          ([last_sep] | search_seps).compact.each do |search_sep|
-            found = @registry.at(ns.path + search_sep.to_s + part)
-            break if found
-          end
-
-          break cur_obj = found if found
-        end
-
-        last_sep = sep
-        scopes = types_for_separator(sep) || []
-        last_obj = cur_obj
-        resolved = cur_obj if parsed_end && cur_obj && (type.nil? || type == cur_obj.type)
-      end
-
-      resolved
-    end
-
-    # Collects and returns all inherited namespaces for a given object
-    def collect_namespaces(object)
-      return [] unless object.respond_to?(:inheritance_tree)
-
-      nss = object.inheritance_tree(true)
-      if object.respond_to?(:superclass)
-        nss |= [P('Object')] if object.superclass != P('BasicObject')
-        nss |= [P('BasicObject')]
-      end
-
-      nss
-    end
-  end
-end
+# frozen_string_literal: true
+module YARD
+  # Handles all logic for complex lexical and inherited object resolution.
+  # Used by {Registry.resolve}, so there is no need to use this class
+  # directly.
+  #
+  # @see Registry.resolve
+  # @since 0.9.1
+  class RegistryResolver
+    include CodeObjects::NamespaceMapper
+
+    # Creates a new resolver object for a registry.
+    #
+    # @param registry [Registry] only set this if customizing the registry
+    #   object
+    def initialize(registry = Registry)
+      @registry = registry
+      @default_sep = nil
+    end
+
+    # Performs a lookup on a given path in the registry. Resolution will occur
+    # in a similar way to standard Ruby identifier resolution, doing lexical
+    # lookup, as well as (optionally) through the inheritance chain. A proxy
+    # object can be returned if the lookup fails for future resolution. The
+    # proxy will be type hinted with the +type+ used in the original lookup.
+    #
+    # @option opts namespace [CodeObjects::Base, :root, nil] (nil) the namespace
+    #   object to start searching from. If root or nil is provided, {Registry.root}
+    #   is assumed.
+    # @option opts inheritance [Boolean] (false) whether to perform lookups through
+    #   the inheritance chain (includes mixins)
+    # @option opts proxy_fallback [Boolean] (false) when true, a proxy is returned
+    #   if no match is found
+    # @option opts type [Symbol] (nil) an optional type hint for the resolver
+    #   to consider when performing a lookup. If a type is provided and the
+    #   resolved object's type does not match the hint, the object is discarded.
+    # @return [CodeObjects::Base, CodeObjects::Proxy, nil] the first object
+    #   that matches the path lookup. If proxy_fallback is provided, a proxy
+    #   object will be returned in the event of no match, otherwise nil will
+    #   be returned.
+    # @example A lookup from root
+    #   resolver.lookup_by_path("A::B::C")
+    # @example A lookup from the A::B namespace
+    #   resolver.lookup_by_path("C", namespace: P("A::B"))
+    # @example A lookup on a method through the inheritance tree
+    #   resolver.lookup_by_math("A::B#foo", inheritance: true)
+    def lookup_by_path(path, opts = {})
+      path = path.to_s
+      namespace = opts[:namespace]
+      inheritance = opts[:inheritance] || false
+      proxy_fallback = opts[:proxy_fallback] || false
+      type = opts[:type]
+
+      if namespace.is_a?(CodeObjects::Proxy)
+        return proxy_fallback ? CodeObjects::Proxy.new(namespace, path, type) : nil
+      end
+
+      if namespace == :root || !namespace
+        namespace = @registry.root
+      else
+        namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
+      end
+      orignamespace = namespace
+
+      if path =~ starts_with_default_separator_match
+        path = $'
+        namespace = @registry.root
+        orignamespace = @registry.root
+      end
+
+      resolved = nil
+      lexical_lookup = 0
+      while namespace && !resolved
+        resolved = lookup_path_direct(namespace, path, type)
+        resolved ||= lookup_path_inherited(namespace, path, type) if inheritance
+        break if resolved
+        namespace = namespace.parent
+        lexical_lookup += 1
+      end
+
+      # method objects cannot be resolved through lexical lookup by more than 1 ns
+      if lexical_lookup > 1 && resolved.is_a?(CodeObjects::MethodObject)
+        resolved = nil
+      end
+
+      if proxy_fallback
+        resolved ||= CodeObjects::Proxy.new(orignamespace, path, type)
+      end
+
+      resolved
+    end
+
+    private
+
+    # return [Boolean] if the obj's type matches the provided type.
+    def validate(obj, type)
+      !type || (obj && obj.type == type) ? obj : nil
+    end
+
+    # Performs a lexical lookup from a namespace for a path and a type hint.
+    def lookup_path_direct(namespace, path, type)
+      result = namespace.root? && validate(@registry.at(path), type)
+      return result if result
+
+      if path =~ starts_with_separator_match
+        return validate(@registry.at(namespace.path + path), type)
+      end
+
+      separators.each do |sep|
+        result = validate(@registry.at("#{namespace.path}#{sep}#{path}"), type)
+        return result if result
+      end
+
+      nil
+    end
+
+    # Performs a lookup through the inheritance chain on a path with a type hint.
+    def lookup_path_inherited(namespace, path, type)
+      resolved = nil
+      last_obj = namespace
+      scopes = []
+      last_sep = nil
+      pos = 0
+
+      if path =~ starts_with_separator_match
+        last_sep = $1
+        path = $'
+      end
+
+      path.scan(split_on_separators_match).each do |part, sep|
+        cur_obj = nil
+        pos += "#{part}#{sep}".length
+        parsed_end = pos == path.length
+
+        if !last_obj || (!parsed_end && !last_obj.is_a?(CodeObjects::NamespaceObject))
+          break # can't continue
+        end
+
+        collect_namespaces(last_obj).each do |ns|
+          next if ns.is_a?(CodeObjects::Proxy)
+
+          found = nil
+          search_seps = []
+          scopes.each do |scope|
+            search_seps += separators_for_type(scope)
+          end
+
+          if search_seps.empty?
+            search_seps =
+              if ns.type == :root
+                [""]
+              elsif last_sep.nil?
+                separators
+              else
+                [@default_sep]
+              end
+          end
+
+          ([last_sep] | search_seps).compact.each do |search_sep|
+            found = @registry.at(ns.path + search_sep.to_s + part)
+            break if found
+          end
+
+          break cur_obj = found if found
+        end
+
+        last_sep = sep
+        scopes = types_for_separator(sep) || []
+        last_obj = cur_obj
+        resolved = cur_obj if parsed_end && cur_obj && (type.nil? || type == cur_obj.type)
+      end
+
+      resolved
+    end
+
+    # Collects and returns all inherited namespaces for a given object
+    def collect_namespaces(object)
+      return [] unless object.respond_to?(:inheritance_tree)
+
+      nss = object.inheritance_tree(true)
+      if object.respond_to?(:superclass)
+        nss |= [P('Object')] if object.superclass != P('BasicObject')
+        nss |= [P('BasicObject')]
+      end
+
+      nss
+    end
+
+    # @see NamespaceMapper#register_separator
+    def register_separator(*)
+      super
+      invalidate_memoized_matchers
+    end
+
+    # @see NamespaceMapper#clear_separators
+    def clear_separators
+      super
+      invalidate_memoized_matchers
+    end
+
+    # @see NamespaceMapper#default_separator
+    def default_separator(value = nil)
+      @starts_with_default_separator_match = nil if value
+      super
+    end
+
+    # @return [Regexp] the regexp match of the default separator
+    def starts_with_default_separator_match
+      @starts_with_default_separator_match ||= /\A#{default_separator}/
+    end
+
+    # @return [Regexp] the regexp that matches strings starting with
+    #   a separator
+    def starts_with_separator_match
+      @starts_with_separator_match ||= /\A(#{separators_match})/
+    end
+
+    # @return [Regexp] the regexp that can be used to split a string on all
+    #   occurrences of separator tokens
+    def split_on_separators_match
+      @split_on_separators_match ||= /(.+?)(#{separators_match}|$)/
+    end
+
+    # Additional invalidations to done when NamespaceMapper API methods are
+    # called on this class
+    def invalidate_memoized_matchers
+      @starts_with_separator_match = nil
+      @split_on_separators_match = nil
+    end
+  end
+end

data/lib/yard/registry_store.rb

@@ -1,337 +1,342 @@
-# frozen_string_literal: true
-require 'fileutils'
-
-module YARD
-  # The data store for the {Registry}.
-  #
-  # @see Registry
-  # @see Serializers::YardocSerializer
-  class RegistryStore
-    # @deprecated The registry no longer tracks proxy types
-    attr_reader :proxy_types
-    attr_reader :file, :checksums
-
-    def initialize
-      @file = nil
-      @checksums = {}
-      @store = {}
-      @proxy_types = {}
-      @object_types = {:root => [:root]}
-      @notfound = {}
-      @loaded_objects = 0
-      @available_objects = 0
-      @locales = {}
-      @store[:root] = CodeObjects::RootObject.allocate
-      @store[:root].send(:initialize, nil, :root)
-    end
-
-    # Gets a {CodeObjects::Base} from the store
-    #
-    # @param [String, Symbol] key the path name of the object to look for.
-    #   If it is empty or :root, returns the {#root} object.
-    # @return [CodeObjects::Base, nil] a code object or nil if none is found
-    def get(key)
-      key = :root if key == ''
-      key = key.to_sym
-      return @store[key] if @store[key]
-      return if @loaded_objects >= @available_objects
-
-      # check disk
-      return if @notfound[key]
-      obj = @serializer.deserialize(key)
-      if obj
-        @loaded_objects += 1
-        put(key, obj)
-      else
-        @notfound[key] = true
-        nil
-      end
-    end
-
-    # Associates an object with a path
-    # @param [String, Symbol] key the path name (:root or '' for root object)
-    # @param [CodeObjects::Base] value the object to store
-    # @return [CodeObjects::Base] returns +value+
-    def put(key, value)
-      if key == ''
-        @object_types[:root] = [:root]
-        @store[:root] = value
-      else
-        @notfound.delete(key.to_sym)
-        (@object_types[value.type] ||= []) << key.to_s
-        if @store[key.to_sym]
-          @object_types[@store[key.to_sym].type].delete(key.to_s)
-        end
-        @store[key.to_sym] = value
-      end
-    end
-
-    alias [] get
-    alias []= put
-
-    # Deletes an object at a given path
-    # @param [#to_sym] key the key to delete
-    # @return [void]
-    def delete(key) @store.delete(key.to_sym) end
-
-    # Gets all path names from the store. Loads the entire database
-    # if +reload+ is +true+
-    #
-    # @param [Boolean] reload if false, does not load the entire database
-    #   before a lookup.
-    # @return [Array<Symbol>] the path names of all the code objects
-    def keys(reload = false) load_all if reload; @store.keys end
-
-    # Gets all code objects from the store. Loads the entire database
-    # if +reload+ is +true+
-    #
-    # @param [Boolean] reload if false, does not load the entire database
-    #   before a lookup.
-    # @return [Array<CodeObjects::Base>] all the code objects
-    def values(reload = false) load_all if reload; @store.values end
-
-    # @param [Symbol] type the type to look for
-    # @return [Array<String>] a list of object paths with a given
-    #   {CodeObjects::Base#type}
-    # @since 0.8.0
-    def paths_for_type(type, reload = false)
-      load_all if reload
-      @object_types[type] || []
-    end
-
-    # @param [Symbol] type the type to look for
-    # @return [Array<CodeObjects::Base>] a list of objects with a given
-    #   {CodeObjects::Base#type}
-    # @since 0.8.0
-    def values_for_type(type, reload = false)
-      load_all if reload
-      paths_for_type(type).map {|t| @store[t.to_sym] }
-    end
-
-    # @return [CodeObjects::RootObject] the root object
-    def root; @store[:root] end
-
-    # @param [String] name the locale name.
-    # @return [I18n::Locale] the locale object for +name+.
-    # @since 0.8.3
-    def locale(name)
-      @locales[name] ||= load_locale(name)
-    end
-
-    # @param [String, nil] file the name of the yardoc db to load
-    # @return [Boolean] whether the database was loaded
-    def load(file = nil)
-      initialize
-      @file = file
-      @serializer = Serializers::YardocSerializer.new(@file)
-      load_yardoc
-    end
-
-    # Loads the .yardoc file and loads all cached objects into memory
-    # automatically.
-    #
-    # @param [String, nil] file the name of the yardoc db to load
-    # @return [Boolean] whether the database was loaded
-    # @see #load_all
-    # @since 0.5.1
-    def load!(file = nil)
-      if load(file)
-        load_all
-        true
-      else
-        false
-      end
-    end
-
-    # Loads all cached objects into memory
-    # @return [void]
-    def load_all
-      return unless @file
-      return if @loaded_objects >= @available_objects
-      log.debug "Loading entire database: #{@file} ..."
-      objects = []
-
-      all_disk_objects.sort_by(&:size).each do |path|
-        obj = @serializer.deserialize(path, true)
-        objects << obj if obj
-      end
-
-      objects.each do |obj|
-        put(obj.path, obj)
-      end
-
-      @loaded_objects += objects.size
-      log.debug "Loaded database (file='#{@file}' count=#{objects.size} total=#{@available_objects})"
-    end
-
-    # Saves the database to disk
-    # @param [Boolean] merge if true, merges the data in memory with the
-    #   data on disk, otherwise the data on disk is deleted.
-    # @param [String, nil] file if supplied, the name of the file to save to
-    # @return [Boolean] whether the database was saved
-    def save(merge = true, file = nil)
-      if file && file != @file
-        @file = file
-        @serializer = Serializers::YardocSerializer.new(@file)
-      end
-      destroy unless merge
-
-      sdb = Registry.single_object_db
-      if sdb == true || sdb.nil?
-        @serializer.serialize(@store)
-      else
-        values(false).each do |object|
-          @serializer.serialize(object)
-        end
-      end
-      write_proxy_types
-      write_object_types
-      write_checksums
-      write_complete_lock
-      true
-    end
-
-    # (see Serializers::YardocSerializer#lock_for_writing)
-    # @param file [String] if supplied, the path to the database
-    def lock_for_writing(file = nil, &block)
-      Serializers::YardocSerializer.new(file || @file).lock_for_writing(&block)
-    end
-
-    # (see Serializers::YardocSerializer#locked_for_writing?)
-    # @param file [String] if supplied, the path to the database
-    def locked_for_writing?(file = nil)
-      Serializers::YardocSerializer.new(file || @file).locked_for_writing?
-    end
-
-    # Deletes the .yardoc database on disk
-    #
-    # @param [Boolean] force if force is not set to true, the file/directory
-    #   will only be removed if it ends with .yardoc. This helps with
-    #   cases where the directory might have been named incorrectly.
-    # @return [Boolean] true if the .yardoc database was deleted, false
-    #   otherwise.
-    def destroy(force = false)
-      if (!force && file =~ /\.yardoc$/) || force
-        if File.file?(@file)
-          # Handle silent upgrade of old .yardoc format
-          File.unlink(@file)
-        elsif File.directory?(@file)
-          FileUtils.rm_rf(@file)
-        end
-        true
-      else
-        false
-      end
-    end
-
-    protected
-
-    def objects_path
-      @serializer.objects_path
-    end
-
-    # @deprecated The registry no longer tracks proxy types
-    def proxy_types_path
-      @serializer.proxy_types_path
-    end
-
-    def checksums_path
-      @serializer.checksums_path
-    end
-
-    def object_types_path
-      @serializer.object_types_path
-    end
-
-    def load_yardoc
-      return false unless @file
-      if File.directory?(@file) # new format
-        @loaded_objects = 0
-        @available_objects = all_disk_objects.size
-        load_proxy_types
-        load_checksums
-        load_root
-        load_object_types
-        true
-      elsif File.file?(@file) # old format
-        load_yardoc_old
-        true
-      else
-        false
-      end
-    end
-
-    private
-
-    def load_yardoc_old
-      @store, @proxy_types = *Marshal.load(File.read_binary(@file))
-    end
-
-    # @deprecated The registry no longer tracks proxy types
-    def load_proxy_types
-      return unless File.file?(proxy_types_path)
-      @proxy_types = Marshal.load(File.read_binary(proxy_types_path))
-    end
-
-    def load_object_types
-      if File.file?(object_types_path)
-        @object_types = Marshal.load(File.read_binary(object_types_path))
-      else # migrate db without object_types
-        values.each do |object|
-          (@object_types[object.type] ||= []) << object.path
-        end
-      end
-    end
-
-    def load_checksums
-      return unless File.file?(checksums_path)
-      lines = File.readlines(checksums_path).map do |line|
-        line.strip.split(/\s+/)
-      end
-      @checksums = Hash[lines]
-    end
-
-    def load_root
-      root = @serializer.deserialize('root')
-      return if root.nil?
-
-      @loaded_objects += 1
-      if root.is_a?(Hash) # single object db
-        log.debug "Loading single object DB from .yardoc"
-        @loaded_objects += (root.keys.size - 1)
-        @store = root
-      else # just the root object
-        @store[:root] = root
-      end
-    end
-
-    def load_locale(name)
-      locale = I18n::Locale.new(name)
-      locale.load(Registry.po_dir)
-      locale
-    end
-
-    def all_disk_objects
-      Dir.glob(File.join(objects_path, '**/*')).select {|f| File.file?(f) }
-    end
-
-    # @deprecated The registry no longer tracks proxy types
-    def write_proxy_types
-      File.open!(proxy_types_path, 'wb') {|f| f.write(Marshal.dump(@proxy_types)) }
-    end
-
-    def write_object_types
-      File.open!(object_types_path, 'wb') {|f| f.write(Marshal.dump(@object_types)) }
-    end
-
-    def write_checksums
-      File.open!(checksums_path, 'w') do |f|
-        @checksums.each {|k, v| f.puts("#{k} #{v}") }
-      end
-    end
-
-    def write_complete_lock
-      File.open!(@serializer.complete_lock_path, 'w') {}
-    end
-  end
-end
+# frozen_string_literal: true
+require 'fileutils'
+
+module YARD
+  # The data store for the {Registry}.
+  #
+  # @see Registry
+  # @see Serializers::YardocSerializer
+  class RegistryStore
+    # @deprecated The registry no longer tracks proxy types
+    attr_reader :proxy_types
+    attr_reader :file, :checksums
+
+    def initialize
+      @file = nil
+      @checksums = {}
+      @store = {}
+      @proxy_types = {}
+      @object_types = {:root => [:root]}
+      @notfound = {}
+      @loaded_objects = 0
+      @available_objects = 0
+      @locales = {}
+      @store[:root] = CodeObjects::RootObject.allocate
+      @store[:root].send(:initialize, nil, :root)
+    end
+
+    # Gets a {CodeObjects::Base} from the store
+    #
+    # @param [String, Symbol] key the path name of the object to look for.
+    #   If it is empty or :root, returns the {#root} object.
+    # @return [CodeObjects::Base, nil] a code object or nil if none is found
+    def get(key)
+      key = :root if key == ''
+      key = key.to_sym
+      return @store[key] if @store[key]
+      return if @loaded_objects >= @available_objects
+
+      # check disk
+      return if @notfound[key]
+      obj = @serializer.deserialize(key)
+      if obj
+        @loaded_objects += 1
+        put(key, obj)
+      else
+        @notfound[key] = true
+        nil
+      end
+    end
+
+    # Associates an object with a path
+    # @param [String, Symbol] key the path name (:root or '' for root object)
+    # @param [CodeObjects::Base] value the object to store
+    # @return [CodeObjects::Base] returns +value+
+    def put(key, value)
+      if key == ''
+        @object_types[:root] = [:root]
+        @store[:root] = value
+      else
+        @notfound.delete(key.to_sym)
+        (@object_types[value.type] ||= []) << key.to_s
+        if @store[key.to_sym]
+          @object_types[@store[key.to_sym].type].delete(key.to_s)
+        end
+        @store[key.to_sym] = value
+      end
+    end
+
+    alias [] get
+    alias []= put
+
+    # Deletes an object at a given path
+    # @param [#to_sym] key the key to delete
+    # @return [void]
+    def delete(key)
+      if @store[key.to_sym]
+        @object_types[@store[key.to_sym].type].delete(key.to_s)
+        @store.delete(key.to_sym)
+      end
+    end
+
+    # Gets all path names from the store. Loads the entire database
+    # if +reload+ is +true+
+    #
+    # @param [Boolean] reload if false, does not load the entire database
+    #   before a lookup.
+    # @return [Array<Symbol>] the path names of all the code objects
+    def keys(reload = false) load_all if reload; @store.keys end
+
+    # Gets all code objects from the store. Loads the entire database
+    # if +reload+ is +true+
+    #
+    # @param [Boolean] reload if false, does not load the entire database
+    #   before a lookup.
+    # @return [Array<CodeObjects::Base>] all the code objects
+    def values(reload = false) load_all if reload; @store.values end
+
+    # @param [Symbol] type the type to look for
+    # @return [Array<String>] a list of object paths with a given
+    #   {CodeObjects::Base#type}
+    # @since 0.8.0
+    def paths_for_type(type, reload = false)
+      load_all if reload
+      @object_types[type] || []
+    end
+
+    # @param [Symbol] type the type to look for
+    # @return [Array<CodeObjects::Base>] a list of objects with a given
+    #   {CodeObjects::Base#type}
+    # @since 0.8.0
+    def values_for_type(type, reload = false)
+      load_all if reload
+      paths_for_type(type).map {|t| @store[t.to_sym] }
+    end
+
+    # @return [CodeObjects::RootObject] the root object
+    def root; @store[:root] end
+
+    # @param [String] name the locale name.
+    # @return [I18n::Locale] the locale object for +name+.
+    # @since 0.8.3
+    def locale(name)
+      @locales[name] ||= load_locale(name)
+    end
+
+    # @param [String, nil] file the name of the yardoc db to load
+    # @return [Boolean] whether the database was loaded
+    def load(file = nil)
+      initialize
+      @file = file
+      @serializer = Serializers::YardocSerializer.new(@file)
+      load_yardoc
+    end
+
+    # Loads the .yardoc file and loads all cached objects into memory
+    # automatically.
+    #
+    # @param [String, nil] file the name of the yardoc db to load
+    # @return [Boolean] whether the database was loaded
+    # @see #load_all
+    # @since 0.5.1
+    def load!(file = nil)
+      if load(file)
+        load_all
+        true
+      else
+        false
+      end
+    end
+
+    # Loads all cached objects into memory
+    # @return [void]
+    def load_all
+      return unless @file
+      return if @loaded_objects >= @available_objects
+      log.debug "Loading entire database: #{@file} ..."
+      objects = []
+
+      all_disk_objects.sort_by(&:size).each do |path|
+        obj = @serializer.deserialize(path, true)
+        objects << obj if obj
+      end
+
+      objects.each do |obj|
+        put(obj.path, obj)
+      end
+
+      @loaded_objects += objects.size
+      log.debug "Loaded database (file='#{@file}' count=#{objects.size} total=#{@available_objects})"
+    end
+
+    # Saves the database to disk
+    # @param [Boolean] merge if true, merges the data in memory with the
+    #   data on disk, otherwise the data on disk is deleted.
+    # @param [String, nil] file if supplied, the name of the file to save to
+    # @return [Boolean] whether the database was saved
+    def save(merge = true, file = nil)
+      if file && file != @file
+        @file = file
+        @serializer = Serializers::YardocSerializer.new(@file)
+      end
+      destroy unless merge
+
+      sdb = Registry.single_object_db
+      if sdb == true || sdb.nil?
+        @serializer.serialize(@store)
+      else
+        values(false).each do |object|
+          @serializer.serialize(object)
+        end
+      end
+      write_proxy_types
+      write_object_types
+      write_checksums
+      write_complete_lock
+      true
+    end
+
+    # (see Serializers::YardocSerializer#lock_for_writing)
+    # @param file [String] if supplied, the path to the database
+    def lock_for_writing(file = nil, &block)
+      Serializers::YardocSerializer.new(file || @file).lock_for_writing(&block)
+    end
+
+    # (see Serializers::YardocSerializer#locked_for_writing?)
+    # @param file [String] if supplied, the path to the database
+    def locked_for_writing?(file = nil)
+      Serializers::YardocSerializer.new(file || @file).locked_for_writing?
+    end
+
+    # Deletes the .yardoc database on disk
+    #
+    # @param [Boolean] force if force is not set to true, the file/directory
+    #   will only be removed if it ends with .yardoc. This helps with
+    #   cases where the directory might have been named incorrectly.
+    # @return [Boolean] true if the .yardoc database was deleted, false
+    #   otherwise.
+    def destroy(force = false)
+      if (!force && file =~ /\.yardoc$/) || force
+        if File.file?(@file)
+          # Handle silent upgrade of old .yardoc format
+          File.unlink(@file)
+        elsif File.directory?(@file)
+          FileUtils.rm_rf(@file)
+        end
+        true
+      else
+        false
+      end
+    end
+
+    protected
+
+    def objects_path
+      @serializer.objects_path
+    end
+
+    # @deprecated The registry no longer tracks proxy types
+    def proxy_types_path
+      @serializer.proxy_types_path
+    end
+
+    def checksums_path
+      @serializer.checksums_path
+    end
+
+    def object_types_path
+      @serializer.object_types_path
+    end
+
+    def load_yardoc
+      return false unless @file
+      if File.directory?(@file) # new format
+        @loaded_objects = 0
+        @available_objects = all_disk_objects.size
+        load_proxy_types
+        load_checksums
+        load_root
+        load_object_types
+        true
+      elsif File.file?(@file) # old format
+        load_yardoc_old
+        true
+      else
+        false
+      end
+    end
+
+    private
+
+    def load_yardoc_old
+      @store, @proxy_types = *Marshal.load(File.read_binary(@file))
+    end
+
+    # @deprecated The registry no longer tracks proxy types
+    def load_proxy_types
+      return unless File.file?(proxy_types_path)
+      @proxy_types = Marshal.load(File.read_binary(proxy_types_path))
+    end
+
+    def load_object_types
+      if File.file?(object_types_path)
+        @object_types = Marshal.load(File.read_binary(object_types_path))
+      else # migrate db without object_types
+        values.each do |object|
+          (@object_types[object.type] ||= []) << object.path
+        end
+      end
+    end
+
+    def load_checksums
+      return unless File.file?(checksums_path)
+      lines = File.readlines(checksums_path).map do |line|
+        line.strip.split(/\s+/)
+      end
+      @checksums = Hash[lines]
+    end
+
+    def load_root
+      root = @serializer.deserialize('root')
+      return if root.nil?
+
+      @loaded_objects += 1
+      if root.is_a?(Hash) # single object db
+        log.debug "Loading single object DB from .yardoc"
+        @loaded_objects += (root.keys.size - 1)
+        @store = root
+      else # just the root object
+        @store[:root] = root
+      end
+    end
+
+    def load_locale(name)
+      locale = I18n::Locale.new(name)
+      locale.load(Registry.po_dir)
+      locale
+    end
+
+    def all_disk_objects
+      Dir.glob(File.join(objects_path, '**/*')).select {|f| File.file?(f) }
+    end
+
+    # @deprecated The registry no longer tracks proxy types
+    def write_proxy_types
+      File.open!(proxy_types_path, 'wb') {|f| f.write(Marshal.dump(@proxy_types)) }
+    end
+
+    def write_object_types
+      File.open!(object_types_path, 'wb') {|f| f.write(Marshal.dump(@object_types)) }
+    end
+
+    def write_checksums
+      File.open!(checksums_path, 'w') do |f|
+        @checksums.each {|k, v| f.puts("#{k} #{v}") }
+      end
+    end
+
+    def write_complete_lock
+      File.open!(@serializer.complete_lock_path, 'w') {}
+    end
+  end
+end