0001-Add-documentation-for-YAML-DBM.patch

Mani Tadayon, 05/17/2011 12:59 PM

Download (4.98 KB)

View differences:

lib/yaml/dbm.rb
6 6
#
7 7
module YAML
8 8

  
9
# Inherit from ::DBM class (see /ext/dbm/dbm.c)
9 10
class DBM < ::DBM
11
    # YAML::DBM Version
10 12
    VERSION = "0.1"
13

  
14
    # Return a value from the database by locating the key string
15
    # provided.  If the key is not found, returns nil.
11 16
    def []( key )
12 17
        fetch( key )
13 18
    end
19

  
20
    # Stores the specified string value in the database, indexed via the
21
    # string key provided.
14 22
    def []=( key, val )
15 23
        store( key, val )
16 24
    end
25

  
26
    # Return a value from the database by locating the key string
27
    # provided.  If the key is not found, returns +ifnone+. If +ifnone+
28
    # is not given, raises IndexError.
17 29
    def fetch( keystr, ifnone = nil )
18 30
        begin
19 31
            val = super( keystr )
......
26 38
            ifnone
27 39
        end
28 40
    end
29
    def index( keystr )
41

  
42
    def index( keystr ) # :nodoc:
30 43
        super( keystr.to_yaml )
31 44
    end
45

  
46
    # Returns an array containing the values associated with the given keys.
32 47
    def values_at( *keys )
33 48
        keys.collect { |k| fetch( k ) }
34 49
    end
50

  
51
    # Deletes an entry from the database.
35 52
    def delete( key )
36 53
        v = super( key )
37 54
        if String === v
......
39 56
        end
40 57
        v
41 58
    end
59

  
60
    # Deletes all entries for which the code block returns true.
61
    # Returns self.
42 62
    def delete_if
43 63
        del_keys = keys.dup
44 64
        del_keys.delete_if { |k| yield( k, fetch( k ) ) == false }
45 65
        del_keys.each { |k| delete( k ) }
46 66
        self
47 67
    end
68

  
69
    # Converts the contents of the database to an in-memory Hash, then calls
70
    # Hash#reject with the specified code block, returning a new Hash.
48 71
    def reject
49 72
        hsh = self.to_hash
50 73
        hsh.reject { |k,v| yield k, v }
51 74
    end
75

  
76
    # Calls the block once for each [key, value] pair in the database.
77
    # Returns self.
52 78
    def each_pair
53 79
        keys.each { |k| yield k, fetch( k ) }
54 80
        self
55 81
    end
82

  
83
    # Calls the block once for each value string in the database. Returns self.
56 84
    def each_value
57 85
        super { |v| yield YAML.load( v ) }
58 86
        self
59 87
    end
88

  
89
    # Returns an array containing the values associated with the given keys.
60 90
    def values
61 91
        super.collect { |v| YAML.load( v ) }
62 92
    end
93

  
94
    # Returns true if the database contains the specified string value, false
95
    # otherwise.
63 96
    def has_value?( val )
64 97
        each_value { |v| return true if v == val }
65 98
        return false
66 99
    end
100

  
101
    # Returns a Hash (not a DBM database) created by using each value in the
102
    # database as a key, with the corresponding key as its value.
67 103
    def invert
68 104
        h = {}
69 105
        keys.each { |k| h[ self.fetch( k ) ] = k }
70 106
        h
71 107
    end
108

  
109
    # Replaces the contents of the database with the contents of the specified
110
    # object. Takes any object which implements the each_pair method, including
111
    # Hash and DBM objects.
72 112
    def replace( hsh )
73 113
        clear
74 114
        update( hsh )
75 115
    end
116

  
117
    # Removes a [key, value] pair from the database, and returns it.
118
    # If the database is empty, returns nil.
119
    # The order in which values are removed/returned is not guaranteed.
76 120
    def shift
77 121
        a = super
78 122
        a[1] = YAML.load( a[1] ) if a
79 123
        a
80 124
    end
125

  
126
    # Returns a new array consisting of the [key, value] pairs for which the code
127
    # block returns true.
81 128
    def select( *keys )
82 129
        if block_given?
83 130
            self.keys.collect { |k| v = self[k]; [k, v] if yield k, v }.compact
......
85 132
            values_at( *keys )
86 133
        end
87 134
    end
135

  
136
    # Stores the specified string value in the database, indexed via the
137
    # string key provided.
88 138
    def store( key, val )
89 139
        super( key, val.to_yaml )
90 140
        val
91 141
    end
142

  
143
    # Updates the database with multiple values from the specified object.
144
    # Takes any object which implements the each_pair method, including
145
    # Hash and DBM objects.
92 146
    def update( hsh )
93 147
        hsh.keys.each do |k|
94 148
            self.store( k, hsh.fetch( k ) )
95 149
        end
96 150
        self
97 151
    end
152

  
153
    # Converts the contents of the database to an array of [key, value] arrays,
154
    # and returns it.
98 155
    def to_a
99 156
        a = []
100 157
        keys.each { |k| a.push [ k, self.fetch( k ) ] }
101 158
        a
102 159
    end
160

  
161
    # Converts the contents of the database to an in-memory Hash object, and
162
    # returns it.
103 163
    def to_hash
104 164
        h = {}
105 165
        keys.each { |k| h[ k ] = self.fetch( k ) }
106 166
        h
107 167
    end
168

  
108 169
    alias :each :each_pair
109 170
end
110 171

  
111
-