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 Registry.at or Registry.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 Registry.load! and Registry.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')
- DEFAULT_PO_DIR =
"po"
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).
I18n features (collapse)
-
+ (String) po_dir
Gets/sets the directory that has LANG.po files.
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 Registry.all with no arguments.
-
+ (I18n::Locale) locale(name)
The locale object for name.
-
+ (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, type = nil)
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
+ (String) po_dir
Gets/sets the directory that has LANG.po files
362 363 364 |
# File 'lib/yard/registry.rb', line 362 def po_dir @po_dir end |
+ (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).
345 346 347 |
# File 'lib/yard/registry.rb', line 345 def single_object_db @single_object_db end |
+ (String) yardoc_file
Gets/sets the yardoc filename
74 75 76 |
# File 'lib/yard/registry.rb', line 74 def yardoc_file @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).
212 213 214 215 216 217 218 219 220 221 222 |
# File 'lib/yard/registry.rb', line 212 def all(*types) if types.empty? thread_local_store.values.select {|obj| obj != root } else list = [] types.each do |type| list += thread_local_store.values_for_type(type) end list end end |
+ (CodeObjects::Base?) at(path) Also known as: []
Returns the object at a specific path.
236 |
# File 'lib/yard/registry.rb', line 236 def at(path) path ? thread_local_store[path] : nil end |
+ (String) checksum_for(data)
Returns the SHA1 checksum for data
331 332 333 |
# File 'lib/yard/registry.rb', line 331 def checksum_for(data) Digest::SHA1.hexdigest(data) end |
+ (Hash{String => String}) checksums
Returns a set of checksums for files
325 326 327 |
# File 'lib/yard/registry.rb', line 325 def checksums thread_local_store.checksums end |
+ (void) clear
This method returns an undefined value.
Clears the registry
189 190 191 |
# File 'lib/yard/registry.rb', line 189 def clear self.thread_local_store = RegistryStore.new end |
+ (void) delete(object)
This method returns an undefined value.
Deletes an object from the registry
183 184 185 |
# File 'lib/yard/registry.rb', line 183 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
165 166 167 |
# File 'lib/yard/registry.rb', line 165 def delete_from_disk thread_local_store.destroy end |
+ (Object) each(&block)
Iterates over all with no arguments
196 197 198 |
# File 'lib/yard/registry.rb', line 196 def each(&block) all.each(&block) end |
+ (Registry) instance
use Registry.methodname directly.
The registry singleton instance.
375 |
# File 'lib/yard/registry.rb', line 375 def instance; self end |
+ (Registry) load(files = [], reparse = false)
Loads the registry and/or parses a list of files
98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 |
# File 'lib/yard/registry.rb', line 98 def load(files = [], reparse = false) if files.is_a?(Array) if File.exist?(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
133 134 135 136 137 |
# File 'lib/yard/registry.rb', line 133 def load!(file = yardoc_file) clear thread_local_store.load!(file) self end |
+ (Registry) load_all
Forces all objects cached on disk into memory
148 149 150 151 |
# File 'lib/yard/registry.rb', line 148 def load_all thread_local_store.load_all self end |
+ (Registry) load_yardoc(file = yardoc_file)
Loads a yardoc file directly
119 120 121 122 123 |
# File 'lib/yard/registry.rb', line 119 def load_yardoc(file = yardoc_file) clear thread_local_store.load(file) self end |
+ (I18n::Locale) locale(name)
Returns the locale object for name.
246 247 248 |
# File 'lib/yard/registry.rb', line 246 def locale(name) thread_local_store.locale(name) end |
+ (Array<String>) paths(reload = false)
Returns the paths of all of the objects in the registry.
227 228 229 |
# File 'lib/yard/registry.rb', line 227 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
175 176 177 178 |
# File 'lib/yard/registry.rb', line 175 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, type = nil)
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.
278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 |
# File 'lib/yard/registry.rb', line 278 def resolve(namespace, name, inheritance = false, proxy_fallback = false, type = nil) if namespace.is_a?(CodeObjects::Proxy) return proxy_fallback ? CodeObjects::Proxy.new(namespace, name, type) : 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| found = at(n) return found if found && (type.nil? || found.type == type) end else while namespace if namespace.is_a?(CodeObjects::NamespaceObject) if inheritance nss = namespace.inheritance_tree(true) if namespace.respond_to?(:superclass) if namespace.superclass != P('BasicObject') nss |= [P('Object')] end nss |= [P('BasicObject')] end else nss = [namespace] end nss.each do |ns| next if ns.is_a?(CodeObjects::Proxy) found = partial_resolve(ns, name, type) return found if found end end namespace = namespace.parent end end proxy_fallback ? CodeObjects::Proxy.new(orignamespace, name, type) : nil end |
+ (CodeObjects::RootObject) root
The root namespace object.
241 |
# File 'lib/yard/registry.rb', line 241 def root; thread_local_store[:root] end |
+ (Boolean) save(merge = false, file = yardoc_file)
Saves the registry to file
159 160 161 |
# File 'lib/yard/registry.rb', line 159 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.
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 |
# File 'lib/yard/registry.rb', line 52 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 |