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 the 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 ..."

Getting an object by a specific path

Registry.at('YARD::CodeObjects::Base#docstring')

Performing a lookup on a method anywhere in the inheritance tree

Registry.resolve(P('YARD::CodeObjects::Base'), '#docstring', true)

Constant Summary

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

Getting .yardoc File Locations (collapse)

Managing Internal State (Advanced / Testing Only) (collapse)

I18n features (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

+ (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

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



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

Examples:

Returns all objects

Registry.all

Returns all classes and modules

Registry.all(:class, :module)

See Also:



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)



331
332
333
# File 'lib/yard/registry.rb', line 331

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

+ (Hash{String => String}) checksums



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

Deprecated.

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

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)

Raises:

  • (ArgumentError)

    if files is not a String or Array



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

See Also:

  • #load_yardoc
  • #load_all

Since:

  • 0.5.1



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

Examples:

Loads all objects from disk

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

Since:

  • 0.5.1



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.

Since:

  • 0.8.3



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.

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>

See Also:



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