class YAML::DBM - RDoc Documentation

# class YAML::DBM

`YAML` + `DBM` = YDBM

`YAML::DBM` provides the same interface as `::DBM`.

However, while `DBM` only allows strings for both keys and values, this library allows one to use most Ruby objects for values by first converting them to `YAML`. Keys must be strings.

Conversion to and from `YAML` is performed automatically.

See the documentation for `::DBM` and `::YAML` for more information.

### Public Instance Methods

ydbm[key] → value click to toggle source

Return value associated with `key` from database.

Returns `nil` if there is no such `key`.

See `fetch` for more information.

    # File lib/yaml/dbm.rb, line 29
    def []( key )
        fetch( key )
    end

ydbm[key] = value click to toggle source

`Set` `key` to `value` in database.

`value` will be converted to `YAML` before storage.

See `store` for more information.

    # File lib/yaml/dbm.rb, line 41
    def []=( key, val )
        store( key, val )
    end

delete(key) click to toggle source

Deletes value from database associated with `key`.

Returns value or `nil`.

Calls superclass method `DBM#delete`

    # File lib/yaml/dbm.rb, line 102
    def delete( key )
        v = super( key )
        if String === v
            v = YAML.load( v )
        end
        v
    end

delete_if { |key, value| ... } click to toggle source

Calls the given block once for each `key`, `value` pair in the database. Deletes all entries for which the block returns true.

Returns `self`.

    # File lib/yaml/dbm.rb, line 117
    def delete_if # :yields: [key, value]
        del_keys = keys.dup
        del_keys.delete_if { |k| yield( k, fetch( k ) ) == false }
        del_keys.each { |k| delete( k ) }
        self
    end

Alias for: each_pair

Calls the given block once for each `key`, `value` pair in the database.

Returns `self`.

    # File lib/yaml/dbm.rb, line 140
    def each_pair # :yields: [key, value]
        keys.each { |k| yield k, fetch( k ) }
        self
    end

Also aliased as: each
each_value { |value| ... } click to toggle source

Calls the given block for each value in database.

Returns `self`.

Calls superclass method `DBM#each_value`

    # File lib/yaml/dbm.rb, line 151
    def each_value # :yields: value
        super { |v| yield YAML.load( v ) }
        self
    end

fetch( key, ifnone = nil ) click to toggle source
fetch( key ) { |key| ... }

Return value associated with `key`.

If there is no value for `key` and no block is given, returns `ifnone`.

Otherwise, calls block passing in the given `key`.

See `::DBM#fetch` for more information.

Calls superclass method `DBM#fetch`

    # File lib/yaml/dbm.rb, line 56
    def fetch( keystr, ifnone = nil )
        begin
            val = super( keystr )
            return YAML.load( val ) if String === val
        rescue IndexError
        end
        if block_given?
            yield keystr
        else
            ifnone
        end
    end

has_value?(value) click to toggle source

Returns true if specified `value` is found in the database.

    # File lib/yaml/dbm.rb, line 168
    def has_value?( val )
        each_value { |v| return true if v == val }
        return false
    end

index( keystr ) click to toggle source

Deprecated, used `YAML::DBM#key` instead.

Note: `YAML::DBM#index` makes warning from internal of ::DBM#index. It says 'DBM#index is deprecated; use `DBM#key`', but `DBM#key` behaves not same as `DBM#index`.

Calls superclass method

    # File lib/yaml/dbm.rb, line 76
    def index( keystr )
        super( keystr.to_yaml )
    end

invert → hash click to toggle source

Returns a `Hash` (not a `DBM` database) created by using each value in the database as a key, with the corresponding key as its value.

Note that all values in the hash will be Strings, but the keys will be actual objects.

    # File lib/yaml/dbm.rb, line 181
    def invert
        h = {}
        keys.each { |k| h[ self.fetch( k ) ] = k }
        h
    end

key(value) → string click to toggle source

Returns the key for the specified value.

    # File lib/yaml/dbm.rb, line 84
    def key( keystr )
        invert[keystr]
    end

reject { |key, value| ... } click to toggle source

Converts the contents of the database to an in-memory `Hash`, then calls `Hash#reject` with the specified code block, returning a new `Hash`.

    # File lib/yaml/dbm.rb, line 129
    def reject
        hsh = self.to_hash
        hsh.reject { |k,v| yield k, v }
    end

replace(hash) → ydbm click to toggle source

Replaces the contents of the database with the contents of the specified object. Takes any object which implements the `each_pair` method, including `Hash` and `DBM` objects.

    # File lib/yaml/dbm.rb, line 193
    def replace( hsh )
        clear
        update( hsh )
    end

select { |key, value| ... } click to toggle source
select(*keys)

If a block is provided, returns a new array containing [key, value] pairs for which the block returns true.

Otherwise, same as `values_at`

    # File lib/yaml/dbm.rb, line 219
    def select( *keys )
        if block_given?
            self.keys.collect { |k| v = self[k]; [k, v] if yield k, v }.compact
        else
            values_at( *keys )
        end
    end

shift → [key, value] click to toggle source

Removes a [key, value] pair from the database, and returns it. If the database is empty, returns `nil`.

The order in which values are removed/returned is not guaranteed.

Calls superclass method `DBM#shift`

    # File lib/yaml/dbm.rb, line 205
    def shift
        a = super
        a[1] = YAML.load( a[1] ) if a
        a
    end

store(key, value) → value click to toggle source

Stores `value` in database with `key` as the index. `value` is converted to `YAML` before being stored.

Returns `value`

Calls superclass method `DBM#store`

    # File lib/yaml/dbm.rb, line 234
    def store( key, val )
        super( key, val.to_yaml )
        val
    end

to_a → array click to toggle source

Converts the contents of the database to an array of [key, value] arrays, and returns it.

    # File lib/yaml/dbm.rb, line 259
    def to_a
        a = []
        keys.each { |k| a.push [ k, self.fetch( k ) ] }
        a
    end

to_hash → hash click to toggle source

Converts the contents of the database to an in-memory `Hash` object, and returns it.

    # File lib/yaml/dbm.rb, line 271
    def to_hash
        h = {}
        keys.each { |k| h[ k ] = self.fetch( k ) }
        h
    end

update(hash) → ydbm click to toggle source

Updates the database with multiple values from the specified object. Takes any object which implements the `each_pair` method, including `Hash` and `DBM` objects.

Returns `self`.

    # File lib/yaml/dbm.rb, line 247
    def update( hsh )
        hsh.each_pair do |k,v|
            self.store( k, v )
        end
        self
    end

values click to toggle source

Returns an array of values from the database.

Calls superclass method `DBM#values`

    # File lib/yaml/dbm.rb, line 160
    def values
        super.collect { |v| YAML.load( v ) }
    end

values_at(*keys) click to toggle source

Returns an array containing the values associated with the given keys.

    # File lib/yaml/dbm.rb, line 92
    def values_at( *keys )
        keys.collect { |k| fetch( k ) }
    end