Module: YARD::Registry
- Extended by:
- Enumerable
- Defined in:
- lib/yard/registry.rb
Overview
The Registry is the centralized data store for all CodeObjects created during parsing. The storage is a key value store with the object's path (see CodeObjects::Base#path) as the key and the object itself as the value. Object paths must be unique to be stored in the Registry. All lookups for objects are done on the singleton Registry instance using the at or resolve methods.
Saving / Loading a Registry
The registry is saved to a "yardoc file" (actually a directory), which can be loaded back to perform any lookups. See load! and save for information on saving and loading of a yardoc file.
Threading Notes
The registry class is a singleton class that is accessed directly in many places across YARD. To mitigate threading issues, YARD (0.6.5+) makes the Registry thread local. This means all access to a registry for a specific object set must occur in the originating thread.
Constant Summary
- DEFAULT_YARDOC_FILE =
".yardoc"
- LOCAL_YARDOC_INDEX =
File.('~/.yard/gem_index')
Getting .yardoc File Locations (collapse)
-
+ (String) yardoc_file
Gets/sets the yardoc filename.
Managing Internal State (Advanced / Testing Only) (collapse)
-
+ (Boolean?) single_object_db
Whether or not the Registry storage should load everything into a single object database (for disk efficiency), or spread them out (for load time efficiency).
Getting .yardoc File Locations (collapse)
-
+ (String?) yardoc_file_for_gem(gem, ver_require = ">= 0", for_writing = false)
Returns the .yardoc file associated with a gem.
Loading Data from Disk (collapse)
-
+ (Registry) load(files = [], reparse = false)
Loads the registry and/or parses a list of files.
-
+ (Registry) load!(file = yardoc_file)
Loads a yardoc file and forces all objects cached on disk into memory.
-
+ (Registry) load_all
Forces all objects cached on disk into memory.
-
+ (Registry) load_yardoc(file = yardoc_file)
Loads a yardoc file directly.
Saving and Deleting Data from Disk (collapse)
-
+ (void) delete_from_disk
Deletes the yardoc file from disk.
-
+ (Boolean) save(merge = false, file = yardoc_file)
Saves the registry to file.
Adding and Deleting Objects from the Registry (collapse)
-
+ (void) clear
Clears the registry.
-
+ (void) delete(object)
Deletes an object from the registry.
-
+ (CodeObjects::Base) register(object)
Registers a new object with the registry.
Accessing Objects in the Registry (collapse)
-
+ (Array<CodeObjects::Base>) all(*types)
Returns all objects in the registry that match one of the types provided in the types list (if types is provided).
-
+ (CodeObjects::Base?) at(path)
(also: [])
Returns the object at a specific path.
-
+ (Object) each(&block)
Iterates over all with no arguments.
-
+ (Array<String>) paths(reload = false)
Returns the paths of all of the objects in the registry.
-
+ (CodeObjects::Base, ...) resolve(namespace, name, inheritance = false, proxy_fallback = false)
Attempts to find an object by name starting at namespace, performing a lookup similar to Ruby's method of resolving a constant in a namespace.
-
+ (CodeObjects::RootObject) root
The root namespace object.
Managing Source File Checksums (collapse)
-
+ (String) checksum_for(data)
The SHA1 checksum for data.
-
+ (Hash{String => String}) checksums
A set of checksums for files.
Legacy Methods (collapse)
-
+ (Registry) instance
Deprecated
Deprecated.
use Registry.methodname directly.
Class Attribute Details
+ (Boolean?) single_object_db
Setting this attribute to nil will offload the decision to the storage adapter.
Whether or not the Registry storage should load everything into a single object database (for disk efficiency), or spread them out (for load time efficiency).
323 |
# File 'lib/yard/registry.rb', line 323 def single_object_db; Thread.current[:__yard_single_db__] end |
+ (String) yardoc_file
Gets/sets the yardoc filename
72 73 74 |
# File 'lib/yard/registry.rb', line 72 def yardoc_file Thread.current[:__yard_yardoc_file__] ||= DEFAULT_YARDOC_FILE end |
Class Method Details
+ (Array<CodeObjects::Base>) all(*types)
Returns all objects in the registry that match one of the types provided in the types list (if types is provided).
209 210 211 212 213 214 215 216 217 218 219 220 |
# File 'lib/yard/registry.rb', line 209 def all(*types) thread_local_store.values.select do |obj| if types.empty? obj != root else obj != root && types.any? do |type| type.is_a?(Symbol) ? obj.type == type : obj.is_a?(type) end end end + (types.include?(:root) ? [root] : []) end |
+ (CodeObjects::Base?) at(path) Also known as: []
Returns the object at a specific path.
234 |
# File 'lib/yard/registry.rb', line 234 def at(path) path ? thread_local_store[path] : nil end |
+ (String) checksum_for(data)
The SHA1 checksum for data
309 310 311 |
# File 'lib/yard/registry.rb', line 309 def checksum_for(data) Digest::SHA1.hexdigest(data) end |
+ (Hash{String => String}) checksums
A set of checksums for files
303 304 305 |
# File 'lib/yard/registry.rb', line 303 def checksums thread_local_store.checksums end |
+ (void) clear
This method returns an undefined value.
Clears the registry
186 187 188 |
# File 'lib/yard/registry.rb', line 186 def clear self.thread_local_store = RegistryStore.new end |
+ (void) delete(object)
This method returns an undefined value.
Deletes an object from the registry
180 181 182 |
# File 'lib/yard/registry.rb', line 180 def delete(object) thread_local_store.delete(object.path) end |
+ (void) delete_from_disk
This method returns an undefined value.
Deletes the yardoc file from disk
162 163 164 |
# File 'lib/yard/registry.rb', line 162 def delete_from_disk thread_local_store.destroy end |
+ (Object) each(&block)
Iterates over all with no arguments
193 194 195 |
# File 'lib/yard/registry.rb', line 193 def each(&block) all.each(&block) end |
+ (Registry) instance
use Registry.methodname directly.
The registry singleton instance.
340 |
# File 'lib/yard/registry.rb', line 340 def instance; self end |
+ (Registry) load(files = [], reparse = false)
Loads the registry and/or parses a list of files
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 |
# File 'lib/yard/registry.rb', line 95 def load(files = [], reparse = false) if files.is_a?(Array) if File.exists?(yardoc_file) && !reparse load_yardoc else size = thread_local_store.keys.size YARD.parse(files) save if thread_local_store.keys.size > size end elsif files.is_a?(String) load_yardoc(files) else raise ArgumentError, "Must take a list of files to parse or the .yardoc file to load." end self end |
+ (Registry) load!(file = yardoc_file)
Loads a yardoc file and forces all objects cached on disk into memory. Equivalent to calling load_yardoc followed by load_all
130 131 132 133 134 |
# File 'lib/yard/registry.rb', line 130 def load!(file = yardoc_file) clear thread_local_store.load!(file) self end |
+ (Registry) load_all
Forces all objects cached on disk into memory
145 146 147 148 |
# File 'lib/yard/registry.rb', line 145 def load_all thread_local_store.load_all self end |
+ (Registry) load_yardoc(file = yardoc_file)
Loads a yardoc file directly
116 117 118 119 120 |
# File 'lib/yard/registry.rb', line 116 def load_yardoc(file = yardoc_file) clear thread_local_store.load(file) self end |
+ (Array<String>) paths(reload = false)
Returns the paths of all of the objects in the registry.
225 226 227 |
# File 'lib/yard/registry.rb', line 225 def paths(reload = false) thread_local_store.keys(reload).map {|k| k.to_s } end |
+ (CodeObjects::Base) register(object)
Registers a new object with the registry
172 173 174 175 |
# File 'lib/yard/registry.rb', line 172 def register(object) return if object.is_a?(CodeObjects::Proxy) thread_local_store[object.path] = object end |
+ (CodeObjects::Base, ...) resolve(namespace, name, inheritance = false, proxy_fallback = false)
Attempts to find an object by name starting at namespace, performing a lookup similar to Ruby's method of resolving a constant in a namespace.
267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 |
# File 'lib/yard/registry.rb', line 267 def resolve(namespace, name, inheritance = false, proxy_fallback = false) if namespace.is_a?(CodeObjects::Proxy) return proxy_fallback ? CodeObjects::Proxy.new(namespace, name) : nil end if namespace == :root || !namespace namespace = root else namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject) end orignamespace = namespace name = name.to_s if name =~ /^#{CodeObjects::NSEPQ}/ [name, name[2..-1]].each do |n| return at(n) if at(n) end else while namespace if namespace.is_a?(CodeObjects::NamespaceObject) nss = inheritance ? namespace.inheritance_tree(true) : [namespace] nss.each do |ns| next if ns.is_a?(CodeObjects::Proxy) found = partial_resolve(ns, name) return found if found end end namespace = namespace.parent end end proxy_fallback ? CodeObjects::Proxy.new(orignamespace, name) : nil end |
+ (CodeObjects::RootObject) root
The root namespace object.
239 |
# File 'lib/yard/registry.rb', line 239 def root; thread_local_store[:root] end |
+ (Boolean) save(merge = false, file = yardoc_file)
Saves the registry to file
156 157 158 |
# File 'lib/yard/registry.rb', line 156 def save(merge = false, file = yardoc_file) thread_local_store.save(merge, file) end |
+ (String?) yardoc_file_for_gem(gem, ver_require = ">= 0", for_writing = false)
Returns the .yardoc file associated with a gem.
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 |
# File 'lib/yard/registry.rb', line 50 def yardoc_file_for_gem(gem, ver_require = ">= 0", for_writing = false) spec = Gem.source_index.find_name(gem, ver_require) return if spec.empty? spec = spec.first if gem =~ /^yard-doc-/ path = File.join(spec.full_gem_path, DEFAULT_YARDOC_FILE) return File.exist?(path) && !for_writing ? path : nil end if for_writing global_yardoc_file(spec, for_writing) || local_yardoc_file(spec, for_writing) else local_yardoc_file(spec, for_writing) || global_yardoc_file(spec, for_writing) end end |