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.

The registry is saved to a "yardoc" file, which can be loaded back to perform any lookups.

This class is a singleton class. Any method called on the class will be delegated to the instance.

Constant Summary collapse

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

Getting .yardoc File Locations 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

.yardoc_file ⇒ String

Gets/sets the yardoc filename

See Also:



60
61
62
 
# File 'lib/yard/registry.rb', line 60

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)

See Also:



193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/yard/registry.rb', line 193

def all(*types)
  @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.



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

def at(path) path ? @store[path] : nil end

.checksum_for(data) ⇒ String 



293
294
295
 
# File 'lib/yard/registry.rb', line 293

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

.checksums ⇒ Hash{String => String} 



287
288
289
 
# File 'lib/yard/registry.rb', line 287

def checksums
  @store.checksums
end

.clear ⇒ void

This method returns an undefined value.

Clears the registry



170
171
172
 
# File 'lib/yard/registry.rb', line 170

def clear
  @store = RegistryStore.new
end

.delete(object) ⇒ void

This method returns an undefined value.

Deletes an object from the registry



164
165
166
 
# File 'lib/yard/registry.rb', line 164

def delete(object) 
  @store.delete(object.path)
end

.delete_from_disk ⇒ void

This method returns an undefined value.

Deletes the yardoc file from disk



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

def delete_from_disk
  @store.destroy
end

.each(&block) ⇒ Object

Iterates over all with no arguments



177
178
179
 
# File 'lib/yard/registry.rb', line 177

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

.instance ⇒ Registry

Deprecated.

use Registry.methodname directly.

The registry singleton instance.



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

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)

Raises:

  • (ArgumentError) —

    if files is not a String or Array



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/yard/registry.rb', line 79

def load(files = [], reparse = false)
  if files.is_a?(Array)
    if File.exists?(yardoc_file) && !reparse
      load_yardoc
    else
      size = @store.keys.size
      YARD.parse(files)
      save if @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

See Also:

  • #load_yardoc
  • #load_all

Since:

  • 0.5.1



114
115
116
117
118
 
# File 'lib/yard/registry.rb', line 114

def load!(file = yardoc_file)
  clear
  @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

Since:

  • 0.5.1



129
130
131
132
 
# File 'lib/yard/registry.rb', line 129

def load_all
  @store.load_all
  self
end

.load_yardoc(file = yardoc_file) ⇒ Registry

Loads a yardoc file directly



100
101
102
103
104
 
# File 'lib/yard/registry.rb', line 100

def load_yardoc(file = yardoc_file)
  clear
  @store.load(file)
  self
end

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

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



209
210
211
 
# File 'lib/yard/registry.rb', line 209

def paths(reload = false)
  @store.keys(reload).map {|k| k.to_s }
end

.register(object) ⇒ CodeObjects::Base

Registers a new object with the registry



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

def register(object)
  return if object.is_a?(CodeObjects::Proxy)
  @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>

See Also:

  • P


251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/yard/registry.rb', line 251

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.



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

def root; @store[:root] end

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

Saves the registry to file



140
141
142
 
# File 'lib/yard/registry.rb', line 140

def save(merge = false, file = yardoc_file)
  @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.



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/yard/registry.rb', line 38

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