# Class: YARD::RegistryStore

Inherits:
  Object
  - Object
  - YARD::RegistryStore
  show all

Defined in:
  lib/yard/registry_store.rb

## Overview

The data store for the Registry.

See Also:

- Registry
- Serializers::YardocSerializer

## Instance Attribute Summary collapse

- #checksums ⇒ Object readonly

  Returns the value of attribute checksums.

- #file ⇒ Object readonly

  Returns the value of attribute file.

- #proxy_types ⇒ Object readonly deprecated Deprecated.

  The registry no longer tracks proxy types

## Instance Method Summary collapse

- #checksums_path ⇒ Object protected
- #delete(key) ⇒ void

  Deletes an object at a given path.

- #destroy(force = false) ⇒ Boolean

  Deletes the .yardoc database on disk.

- #get(key) ⇒ CodeObjects::Base? (also: #[])

  Gets a CodeObjects::Base from the store.

- #initialize ⇒ RegistryStore constructor

  A new instance of RegistryStore.

- #keys(reload = false) ⇒ Array<Symbol>

  Gets all path names from the store.

- #load(file = nil) ⇒ Boolean

  Whether the database was loaded.

- #load!(file = nil) ⇒ Boolean

  Loads the .yardoc file and loads all cached objects into memory automatically.

- #load_all ⇒ void

  Loads all cached objects into memory.

- #load_yardoc ⇒ Object protected
- #locale(name) ⇒ I18n::Locale

  The locale object for `name`.

- #lock_for_writing(file = nil, &block) ⇒ Object

  Creates a pessmistic transactional lock on the database for writing.

- #locked_for_writing?(file = nil) ⇒ Boolean

  Whether the database is currently locked for writing.

- #object_types_path ⇒ Object protected
- #objects_path ⇒ Object protected
- #paths_for_type(type, reload = false) ⇒ Array<String>

  A list of object paths with a given CodeObjects::Base#type.

- #proxy_types_path ⇒ Object protected deprecated Deprecated.

  The registry no longer tracks proxy types

- #put(key, value) ⇒ CodeObjects::Base (also: #[]=)

  Associates an object with a path.

- #root ⇒ CodeObjects::RootObject

  The root object.

- #save(merge = true, file = nil) ⇒ Boolean

  Saves the database to disk.

- #values(reload = false) ⇒ Array<CodeObjects::Base>

  Gets all code objects from the store.

- #values_for_type(type, reload = false) ⇒ Array<CodeObjects::Base>

  A list of objects with a given CodeObjects::Base#type.

## Constructor Details

### #initialize ⇒ `RegistryStore`

Returns a new instance of RegistryStore.

    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26

    # File 'lib/yard/registry_store.rb', line 14

    def initialize
      @file = nil
      @checksums = {}
      @store = {}
      @proxy_types = {}
      @object_types = {:root => [:root]}
      @notfound = {}
      @loaded_objects = 0
      @available_objects = 0
      @locales = {}
      @store[:root] = CodeObjects::RootObject.allocate
      @store[:root].send(:initialize, nil, :root)
    end

## Instance Attribute Details

### #checksums ⇒ `Object` (readonly)

Returns the value of attribute checksums.

    12
    13
    14

    # File 'lib/yard/registry_store.rb', line 12

    def checksums
      @checksums
    end

### #file ⇒ `Object` (readonly)

Returns the value of attribute file.

    12
    13
    14

    # File 'lib/yard/registry_store.rb', line 12

    def file
      @file
    end

### #proxy_types ⇒ `Object` (readonly)

Deprecated.

The registry no longer tracks proxy types

    11
    12
    13

    # File 'lib/yard/registry_store.rb', line 11

    def proxy_types
      @proxy_types
    end

## Instance Method Details

### #checksums_path ⇒ `Object` (protected)

    243
    244
    245

    # File 'lib/yard/registry_store.rb', line 243

    def checksums_path
      @serializer.checksums_path
    end

### #delete(key) ⇒ `void`

This method returns an undefined value.

Deletes an object at a given path

Parameters:

- key (`#to_sym`) —

  the key to delete

    75
    76
    77
    78
    79
    80

    # File 'lib/yard/registry_store.rb', line 75

    def delete(key)
      if @store[key.to_sym]
        @object_types[@store[key.to_sym].type].delete(key.to_s)
        @store.delete(key.to_sym)
      end
    end

### #destroy(force = false) ⇒ `Boolean`

Deletes the .yardoc database on disk

Parameters:

- force (`Boolean`) (defaults to: `false`) —

  if force is not set to true, the file/directory will only be removed if it ends with .yardoc. This helps with cases where the directory might have been named incorrectly.

Returns:

- (`Boolean`) —

  true if the .yardoc database was deleted, false otherwise.

    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230

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

    def destroy(force = false)
      if (!force && file =~ /\.yardoc$/) || force
        if File.file?(@file)
          # Handle silent upgrade of old .yardoc format
          File.unlink(@file)
        elsif File.directory?(@file)
          FileUtils.rm_rf(@file)
        end
        true
      else
        false
      end
    end

### #get(key) ⇒ `CodeObjects::Base`? Also known as: []

Gets a CodeObjects::Base from the store

Parameters:

- key (`String`, `Symbol`) —

  the path name of the object to look for. If it is empty or :root, returns the #root object.

Returns:

- (`CodeObjects::Base`, `nil`) —

  a code object or nil if none is found

    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49

    # File 'lib/yard/registry_store.rb', line 33

    def get(key)
      key = :root if key == ''
      key = key.to_sym
      return @store[key] if @store[key]
      return if @loaded_objects >= @available_objects

      # check disk
      return if @notfound[key]
      obj = @serializer.deserialize(key)
      if obj
        @loaded_objects += 1
        put(key, obj)
      else
        @notfound[key] = true
        nil
      end
    end

### #keys(reload = false) ⇒ `Array<Symbol>`

Gets all path names from the store. Loads the entire database if `reload` is `true`

Parameters:

- reload (`Boolean`) (defaults to: `false`) —

  if false, does not load the entire database before a lookup.

Returns:

- (`Array<Symbol>`) —

  the path names of all the code objects

    88

    # File 'lib/yard/registry_store.rb', line 88

    def keys(reload = false) load_all if reload; @store.keys end

### #load(file = nil) ⇒ `Boolean`

Returns whether the database was loaded.

Parameters:

- file (`String`, `nil`) (defaults to: `nil`) —

  the name of the yardoc db to load

Returns:

- (`Boolean`) —

  whether the database was loaded

    128
    129
    130
    131
    132
    133

    # File 'lib/yard/registry_store.rb', line 128

    def load(file = nil)
      initialize
      @file = file
      @serializer = Serializers::YardocSerializer.new(@file)
      load_yardoc
    end

### #load!(file = nil) ⇒ `Boolean`

Loads the .yardoc file and loads all cached objects into memory automatically.

Parameters:

- file (`String`, `nil`) (defaults to: `nil`) —

  the name of the yardoc db to load

Returns:

- (`Boolean`) —

  whether the database was loaded

See Also:

- #load_all

Since:

- 0.5.1

    142
    143
    144
    145
    146
    147
    148
    149

    # File 'lib/yard/registry_store.rb', line 142

    def load!(file = nil)
      if load(file)
        load_all
        true
      else
        false
      end
    end

### #load_all ⇒ `void`

This method returns an undefined value.

Loads all cached objects into memory

    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170

    # File 'lib/yard/registry_store.rb', line 153

    def load_all
      return unless @file
      return if @loaded_objects >= @available_objects
      log.debug "Loading entire database: #{@file} ..."
      objects = []

      all_disk_objects.sort_by(&:size).each do |path|
        obj = @serializer.deserialize(path, true)
        objects << obj if obj
      end

      objects.each do |obj|
        put(obj.path, obj)
      end

      @loaded_objects += objects.size
      log.debug "Loaded database (file='#{@file}' count=#{objects.size} total=#{@available_objects})"
    end

### #load_yardoc ⇒ `Object` (protected)

    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267

    # File 'lib/yard/registry_store.rb', line 251

    def load_yardoc
      return false unless @file
      if File.directory?(@file) # new format
        @loaded_objects = 0
        @available_objects = all_disk_objects.size
        load_proxy_types
        load_checksums
        load_root
        load_object_types
        true
      elsif File.file?(@file) # old format
        load_yardoc_old
        true
      else
        false
      end
    end

### #locale(name) ⇒ `I18n::Locale`

Returns the locale object for `name`.

Parameters:

- name (`String`) —

  the locale name.

Returns:

- (`I18n::Locale`) —

  the locale object for `name`.

Since:

- 0.8.3

    122
    123
    124

    # File 'lib/yard/registry_store.rb', line 122

    def locale(name)
      @locales[name] ||= load_locale(name)
    end

### #lock_for_writing(file = nil, &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.

Parameters:

- file (`String`) (defaults to: `nil`) —

  if supplied, the path to the database

See Also:

- #locked_for_writing?

    201
    202
    203

    # File 'lib/yard/registry_store.rb', line 201

    def lock_for_writing(file = nil, &block)
      Serializers::YardocSerializer.new(file || @file).lock_for_writing(&block)
    end

### #locked_for_writing?(file = nil) ⇒ `Boolean`

Returns whether the database is currently locked for writing.

Parameters:

- file (`String`) (defaults to: `nil`) —

  if supplied, the path to the database

Returns:

- (`Boolean`) —

  whether the database is currently locked for writing

    207
    208
    209

    # File 'lib/yard/registry_store.rb', line 207

    def locked_for_writing?(file = nil)
      Serializers::YardocSerializer.new(file || @file).locked_for_writing?
    end

### #object_types_path ⇒ `Object` (protected)

    247
    248
    249

    # File 'lib/yard/registry_store.rb', line 247

    def object_types_path
      @serializer.object_types_path
    end

### #objects_path ⇒ `Object` (protected)

    234
    235
    236

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

    def objects_path
      @serializer.objects_path
    end

### #paths_for_type(type, reload = false) ⇒ `Array<String>`

Returns a list of object paths with a given CodeObjects::Base#type.

Parameters:

- type (`Symbol`) —

  the type to look for

Returns:

- (`Array<String>`) —

  a list of object paths with a given CodeObjects::Base#type

Since:

- 0.8.0

    102
    103
    104
    105

    # File 'lib/yard/registry_store.rb', line 102

    def paths_for_type(type, reload = false)
      load_all if reload
      @object_types[type] || []
    end

### #proxy_types_path ⇒ `Object` (protected)

Deprecated.

The registry no longer tracks proxy types

    239
    240
    241

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

    def proxy_types_path
      @serializer.proxy_types_path
    end

### #put(key, value) ⇒ `CodeObjects::Base` Also known as: []=

Associates an object with a path

Parameters:

- key (`String`, `Symbol`) —

  the path name (:root or ” for root object)

- value (`CodeObjects::Base`) —

  the object to store

Returns:

- (`CodeObjects::Base`) —

  returns `value`

    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67

    # File 'lib/yard/registry_store.rb', line 55

    def put(key, value)
      if key == ''
        @object_types[:root] = [:root]
        @store[:root] = value
      else
        @notfound.delete(key.to_sym)
        (@object_types[value.type] ||= []) << key.to_s
        if @store[key.to_sym]
          @object_types[@store[key.to_sym].type].delete(key.to_s)
        end
        @store[key.to_sym] = value
      end
    end

### #root ⇒ `CodeObjects::RootObject`

Returns the root object.

Returns:

- (`CodeObjects::RootObject`) —

  the root object

    117

    # File 'lib/yard/registry_store.rb', line 117

    def root; @store[:root] end

### #save(merge = true, file = nil) ⇒ `Boolean`

Saves the database to disk

Parameters:

- merge (`Boolean`) (defaults to: `true`) —

  if true, merges the data in memory with the data on disk, otherwise the data on disk is deleted.

- file (`String`, `nil`) (defaults to: `nil`) —

  if supplied, the name of the file to save to

Returns:

- (`Boolean`) —

  whether the database was saved

    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197

    # File 'lib/yard/registry_store.rb', line 177

    def save(merge = true, file = nil)
      if file && file != @file
        @file = file
        @serializer = Serializers::YardocSerializer.new(@file)
      end
      destroy unless merge

      sdb = Registry.single_object_db
      if sdb == true || sdb.nil?
        @serializer.serialize(@store)
      else
        values(false).each do |object|
          @serializer.serialize(object)
        end
      end
      write_proxy_types
      write_object_types
      write_checksums
      write_complete_lock
      true
    end

### #values(reload = false) ⇒ `Array<CodeObjects::Base>`

Gets all code objects from the store. Loads the entire database if `reload` is `true`

Parameters:

- reload (`Boolean`) (defaults to: `false`) —

  if false, does not load the entire database before a lookup.

Returns:

- (`Array<CodeObjects::Base>`) —

  all the code objects

    96

    # File 'lib/yard/registry_store.rb', line 96

    def values(reload = false) load_all if reload; @store.values end

### #values_for_type(type, reload = false) ⇒ `Array<CodeObjects::Base>`

Returns a list of objects with a given CodeObjects::Base#type.

Parameters:

- type (`Symbol`) —

  the type to look for

Returns:

- (`Array<CodeObjects::Base>`) —

  a list of objects with a given CodeObjects::Base#type

Since:

- 0.8.0

    111
    112
    113
    114

    # File 'lib/yard/registry_store.rb', line 111

    def values_for_type(type, reload = false)
      load_all if reload
      paths_for_type(type).map {|t| @store[t.to_sym] }
    end