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.

Examples:

Loading a Registry

Registry.load!('/path/to/yardocfile') # loads all objects into memory
Registry.at('YARD::CodeObjects::Base').docstring
# => "+Base+ is the superclass of all code objects ..."

Performing a Search on a Registry

Registry.resolve(P('YARD::CodeObjects::Base'), '#docstring')
# => <

Constant Summary collapse

DEFAULT_YARDOC_FILE = 
".yardoc"
LOCAL_YARDOC_INDEX = 
File.expand_path('~/.yard/gem_index')

Getting .yardoc File Locations collapse

Managing Internal State (Advanced / Testing Only) collapse

Getting .yardoc File Locations collapse

Loading Data from Disk collapse

Saving and Deleting Data from Disk collapse

Adding and Deleting Objects from the Registry collapse

Accessing Objects in the Registry collapse

Managing Source File Checksums collapse

Legacy Methods collapse

Class Attribute Details

.single_object_db ⇒ Boolean?

Note:

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).

Returns:

  • (Boolean, nil) —

    if this value is set to nil, the storage adapter will decide how to store the data.



323
324
325
 
# File 'lib/yard/registry.rb', line 323

def single_object_db
  @single_object_db
end

.yardoc_file ⇒ String

Gets/sets the yardoc filename

Returns:

  • (String) —

    the yardoc filename

See Also:



72
73
74
 
# File 'lib/yard/registry.rb', line 72

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).

Examples:

Returns all objects

Registry.all

Returns all classes and modules

Registry.all(:class, :module)

Parameters:

  • types (Array<Symbol>) —

    an optional list of types to narrow the objects down by. Equivalent to performing a select: 

    +Registry.all.select {|o| types.include(o.type) }+

Returns:

See Also:



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

.at(path) ⇒ CodeObjects::Base? Also known as: []

Returns the object at a specific path.

Parameters:

  • path (String, :root) —

    the pathname to look for. If path is root, returns the root object.

Returns:



234
 
# File 'lib/yard/registry.rb', line 234

def at(path) path ? thread_local_store[path] : nil end

.checksum_for(data) ⇒ String

Returns the SHA1 checksum for data.

Parameters:

  • data (String) —

    data to checksum

Returns:

  • (String) —

    the SHA1 checksum for data



309
310
311
 
# File 'lib/yard/registry.rb', line 309

def checksum_for(data)
  Digest::SHA1.hexdigest(data)
end

.checksums ⇒ Hash{String => String}

Returns a set of checksums for files.

Returns:



303
304
305
 
# File 'lib/yard/registry.rb', line 303

def checksums
  thread_local_store.checksums
end

.clear ⇒ void

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

.delete(object) ⇒ void

This method returns an undefined value.

Deletes an object from the registry

Parameters:



180
181
182
 
# File 'lib/yard/registry.rb', line 180

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



162
163
164
 
# File 'lib/yard/registry.rb', line 162

def delete_from_disk
  thread_local_store.destroy
end

.each(&block) ⇒ Object

Iterates over all with no arguments



193
194
195
 
# File 'lib/yard/registry.rb', line 193

def each(&block)
  all.each(&block)
end

.instance ⇒ Registry

Deprecated.

use Registry.methodname directly.

The registry singleton instance.

Returns:

  • (Registry) —

    returns the registry instance



340
 
# File 'lib/yard/registry.rb', line 340

def instance; self end

.load(files = [], reparse = false) ⇒ Registry

Loads the registry and/or parses a list of files

Examples:

Loads the yardoc file or parses files ‘a’, ‘b’ and ‘c’ (but not both)

Registry.load(['a', 'b', 'c'])

Reparses files ‘a’ and ‘b’ regardless of whether yardoc file exists

Registry.load(['a', 'b'], true)

Parameters:

  • files (String, Array) (defaults to: []) —

    if files is an Array, it should represent a list of files that YARD should parse into the registry. If reload is set to false and the yardoc file already exists, these files are skipped. If files is a String, it should represent the yardoc file to load into the registry.

  • reparse (Boolean) (defaults to: false) —

    if reparse is false and a yardoc file already exists, any files passed in will be ignored.

Returns:

  • (Registry) —

    the registry object (for chaining)

Raises:

  • (ArgumentError) —

    if files is not a String or Array



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

.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

Parameters:

  • file (String) (defaults to: yardoc_file) —

    the yardoc file to load

Returns:

  • (Registry) —

    the registry object (for chaining)

See Also:

  • #load_yardoc
  • #load_all

Since:

  • 0.5.1



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

.load_all ⇒ Registry

Forces all objects cached on disk into memory

Examples:

Loads all objects from disk

Registry.load
Registry.all.count #=> 0
Registry.load_all
Registry.all.count #=> 17

Returns:

  • (Registry) —

    the registry object (for chaining)

Since:

  • 0.5.1



145
146
147
148
 
# File 'lib/yard/registry.rb', line 145

def load_all
  thread_local_store.load_all
  self
end

.load_yardoc(file = yardoc_file) ⇒ Registry

Loads a yardoc file directly

Parameters:

  • file (String) (defaults to: yardoc_file) —

    the yardoc file to load.

Returns:

  • (Registry) —

    the registry object (for chaining)



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

.paths(reload = false) ⇒ Array<String>

Returns the paths of all of the objects in the registry.

Parameters:

  • reload (Boolean) (defaults to: false) —

    whether to load entire database

Returns:

  • (Array<String>) —

    all of the paths 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

.register(object) ⇒ CodeObjects::Base

Registers a new object with the registry

Parameters:

Returns:



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

.resolve(namespace, name, inheritance = false, proxy_fallback = false) ⇒ 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.

Examples:

Looks for instance method #reverse starting from A::B::C

Registry.resolve(P("A::B::C"), "#reverse")

Looks for a constant in the root namespace

Registry.resolve(nil, 'CONSTANT')

Looks for a class method respecting the inheritance tree

Registry.resolve(myclass, 'mymethod', true)

Looks for a constant but returns a proxy if not found

Registry.resolve(P('A::B::C'), 'D', false, true) # => #<yardoc proxy A::B::C::D>

Looks for a complex path from a namespace

Registry.resolve(P('A::B'), 'B::D') # => #<yardoc class A::B::D>

Parameters:

  • namespace (CodeObjects::NamespaceObject, nil) —

    the starting namespace (module or class). If nil or :root, starts from the root object.

  • name (String, Symbol) —

    the name (or complex path) to look for from namespace.

  • inheritance (Boolean) (defaults to: false) —

    Follows inheritance chain (mixins, superclass) when performing name resolution if set to true.

  • proxy_fallback (Boolean) (defaults to: false) —

    If true, returns a proxy representing the unresolved path (namespace + name) if no object is found.

Returns:

  • (CodeObjects::Base) —

    the object if it is found

  • (CodeObjects::Proxy) —

    a Proxy representing the object if proxy_fallback is true.

  • (nil) —

    if proxy_fallback is false and no object was found.

See Also:

  • P


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

.root ⇒ CodeObjects::RootObject

The root namespace object.

Returns:



239
 
# File 'lib/yard/registry.rb', line 239

def root; thread_local_store[:root] end

.save(merge = false, file = yardoc_file) ⇒ Boolean

Saves the registry to file

Parameters:

  • file (String) (defaults to: yardoc_file) —

    the yardoc file to save to

Returns:

  • (Boolean) —

    true if the file was saved



156
157
158
 
# File 'lib/yard/registry.rb', line 156

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.

Parameters:

  • gem (String) —

    the name of the gem to search for

  • ver_require (String) (defaults to: ">= 0") —

    an optional Gem version requirement

  • for_writing (Boolean) (defaults to: false) —

    whether or not the method should search for writable locations

Returns:

  • (String) —

    if for_writing is set to true, returns the best location suitable to write the .yardoc file. Otherwise, the first existing location associated with the gem’s .yardoc file.

  • (nil) —

    if for_writing is set to false and no yardoc file is found, returns nil.



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