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 collapse
- DEFAULT_YARDOC_FILE =
".yardoc"
- LOCAL_YARDOC_INDEX =
File.(File.join(Config::CONFIG_DIR, 'gem_index'))
- DEFAULT_PO_DIR =
"po"
Getting .yardoc File Locations collapse
-
.yardoc_file ⇒ String
Gets/sets the yardoc filename.
Managing Internal State (Advanced / Testing Only) collapse
-
.single_object_db ⇒ Boolean?
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
-
.po_dir ⇒ String
Gets/sets the directory that has LANG.po files.
Getting .yardoc File Locations collapse
-
.yardoc_file_for_gem(gem, ver_require = ">= 0", for_writing = false) ⇒ String?
Returns the .yardoc file associated with a gem.
Loading Data from Disk collapse
-
.load(files = [], reparse = false) ⇒ Registry
Loads the registry and/or parses a list of files.
-
.load!(file = yardoc_file) ⇒ Registry
Loads a yardoc file and forces all objects cached on disk into memory.
-
.load_all ⇒ Registry
Forces all objects cached on disk into memory.
-
.load_yardoc(file = yardoc_file) ⇒ Registry
Loads a yardoc file directly.
Saving and Deleting Data from Disk collapse
-
.delete_from_disk ⇒ void
Deletes the yardoc file from disk.
-
.save(merge = false, file = yardoc_file) ⇒ Boolean
Saves the registry to
file
.
Adding and Deleting Objects from the Registry collapse
-
.clear ⇒ void
Clears the registry.
-
.delete(object) ⇒ void
Deletes an object from the registry.
-
.lock_for_writing(file = yardoc_file, &block) ⇒ Object
Creates a pessmistic transactional lock on the database for writing.
-
.locked_for_writing?(file = yardoc_file) ⇒ Boolean
Whether the database is currently locked for writing.
-
.register(object) ⇒ CodeObjects::Base
Registers a new object with the registry.
Accessing Objects in the Registry collapse
-
.all(*types) ⇒ Array<CodeObjects::Base>
Returns all objects in the registry that match one of the types provided in the
types
list (iftypes
is provided). -
.at(path) ⇒ CodeObjects::Base?
(also: [])
Returns the object at a specific path.
-
.each(&block) ⇒ Object
Iterates over Registry.all with no arguments.
-
.locale(name) ⇒ I18n::Locale
The locale object for
name
. -
.paths(reload = false) ⇒ Array<String>
Returns the paths of all of the objects in the registry.
-
.resolve(namespace, name, inheritance = false, proxy_fallback = false, type = nil) ⇒ CodeObjects::Base, ...
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. -
.root ⇒ CodeObjects::RootObject
The root namespace object.
Managing Source File Checksums collapse
-
.checksum_for(data) ⇒ String
The SHA1 checksum for data.
-
.checksums ⇒ Hash{String => String}
A set of checksums for files.
Legacy Methods collapse
-
.instance ⇒ Registry
deprecated
Deprecated.
use Registry.methodname directly.
Class Attribute Details
.po_dir ⇒ String
Gets/sets the directory that has LANG.po files
347 348 349 |
# File 'lib/yard/registry.rb', line 347 def po_dir @po_dir end |
.single_object_db ⇒ Boolean?
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).
330 331 332 |
# File 'lib/yard/registry.rb', line 330 def single_object_db @single_object_db end |
.yardoc_file ⇒ String
Gets/sets the yardoc filename
83 84 85 |
# File 'lib/yard/registry.rb', line 83 def yardoc_file @yardoc_file end |
Class Method Details
.all(*types) ⇒ Array<CodeObjects::Base>
Returns all objects in the registry that match one of the types provided in the types
list (if types
is provided).
235 236 237 238 239 240 241 242 243 244 245 |
# File 'lib/yard/registry.rb', line 235 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 |
.at(path) ⇒ CodeObjects::Base? Also known as: []
Returns the object at a specific path.
259 |
# File 'lib/yard/registry.rb', line 259 def at(path) path ? thread_local_store[path] : nil end |
.checksum_for(data) ⇒ String
Returns the SHA1 checksum for data.
316 317 318 |
# File 'lib/yard/registry.rb', line 316 def checksum_for(data) Digest::SHA1.hexdigest(data) end |
.checksums ⇒ Hash{String => String}
Returns a set of checksums for files.
310 311 312 |
# File 'lib/yard/registry.rb', line 310 def checksums thread_local_store.checksums end |
.clear ⇒ void
This method returns an undefined value.
Clears the registry
198 199 200 |
# File 'lib/yard/registry.rb', line 198 def clear self.thread_local_store = RegistryStore.new end |
.delete(object) ⇒ void
This method returns an undefined value.
Deletes an object from the registry
192 193 194 |
# File 'lib/yard/registry.rb', line 192 def delete(object) thread_local_store.delete(object.path) end |
.delete_from_disk ⇒ void
This method returns an undefined value.
Deletes the yardoc file from disk
174 175 176 |
# File 'lib/yard/registry.rb', line 174 def delete_from_disk thread_local_store.destroy end |
.each(&block) ⇒ Object
Iterates over all with no arguments
219 220 221 |
# File 'lib/yard/registry.rb', line 219 def each(&block) all.each(&block) end |
.instance ⇒ Registry
use Registry.methodname directly.
The registry singleton instance.
360 |
# File 'lib/yard/registry.rb', line 360 def instance; self end |
.load(files = [], reparse = false) ⇒ Registry
Loads the registry and/or parses a list of files
107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 |
# File 'lib/yard/registry.rb', line 107 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 |
.load!(file = yardoc_file) ⇒ Registry
Loads a yardoc file and forces all objects cached on disk into memory. Equivalent to calling load_yardoc followed by load_all
142 143 144 145 146 |
# File 'lib/yard/registry.rb', line 142 def load!(file = yardoc_file) clear thread_local_store.load!(file) self end |
.load_all ⇒ Registry
Forces all objects cached on disk into memory
157 158 159 160 |
# File 'lib/yard/registry.rb', line 157 def load_all thread_local_store.load_all self end |
.load_yardoc(file = yardoc_file) ⇒ Registry
Loads a yardoc file directly
128 129 130 131 132 |
# File 'lib/yard/registry.rb', line 128 def load_yardoc(file = yardoc_file) clear thread_local_store.load(file) self end |
.locale(name) ⇒ I18n::Locale
Returns the locale object for name
.
269 270 271 |
# File 'lib/yard/registry.rb', line 269 def locale(name) thread_local_store.locale(name) end |
.lock_for_writing(file = yardoc_file, &block) ⇒ Object
Creates a pessmistic transactional lock on the database for writing. Use with YARD.parse to ensure the database is not written multiple times.
207 208 209 |
# File 'lib/yard/registry.rb', line 207 def lock_for_writing(file = yardoc_file, &block) thread_local_store.lock_for_writing(file, &block) end |
.locked_for_writing?(file = yardoc_file) ⇒ Boolean
Returns whether the database is currently locked for writing.
212 213 214 |
# File 'lib/yard/registry.rb', line 212 def locked_for_writing?(file = yardoc_file) thread_local_store.locked_for_writing?(file) end |
.paths(reload = false) ⇒ Array<String>
Returns the paths of all of the objects in the registry.
250 251 252 |
# File 'lib/yard/registry.rb', line 250 def paths(reload = false) thread_local_store.keys(reload).map {|k| k.to_s } end |
.register(object) ⇒ CodeObjects::Base
Registers a new object with the registry
184 185 186 187 |
# File 'lib/yard/registry.rb', line 184 def register(object) return if object.is_a?(CodeObjects::Proxy) thread_local_store[object.path] = object end |
.resolve(namespace, name, inheritance = false, proxy_fallback = false, type = nil) ⇒ CodeObjects::Base, ...
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.
301 302 303 304 305 |
# File 'lib/yard/registry.rb', line 301 def resolve(namespace, name, inheritance = false, proxy_fallback = false, type = nil) thread_local_resolver.lookup_by_path name, :namespace => namespace, :inheritance => inheritance, :proxy_fallback => proxy_fallback, :type => type end |
.root ⇒ CodeObjects::RootObject
The root namespace object.
264 |
# File 'lib/yard/registry.rb', line 264 def root; thread_local_store[:root] end |
.save(merge = false, file = yardoc_file) ⇒ Boolean
Saves the registry to file
168 169 170 |
# File 'lib/yard/registry.rb', line 168 def save(merge = false, file = yardoc_file) thread_local_store.save(merge, file) end |
.yardoc_file_for_gem(gem, ver_require = ">= 0", for_writing = false) ⇒ String?
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 70 71 72 73 74 75 76 77 78 |
# File 'lib/yard/registry.rb', line 52 def yardoc_file_for_gem(gem, ver_require = ">= 0", for_writing = false) specs = Gem.source_index.find_name(gem, ver_require) return if specs.empty? result = nil specs.reverse.each do |spec| if gem =~ /^yard-doc-/ path = File.join(spec.full_gem_path, DEFAULT_YARDOC_FILE) result = File.exist?(path) && !for_writing ? path : nil result ? break : next end if for_writing result = global_yardoc_file(spec, for_writing) || old_global_yardoc_file(spec, for_writing) || local_yardoc_file(spec, for_writing) else result = local_yardoc_file(spec, for_writing) || global_yardoc_file(spec, for_writing) || old_global_yardoc_file(spec, for_writing) end break if result end result end |