0001-Documentation-for-YAML-DBM.patch

Justin Collins, 05/14/2011 06:18 AM

Download (6.12 KB)

View differences:

lib/yaml/dbm.rb
1 1
require 'yaml'
2 2
require 'dbm'
3
#
4
# YAML + DBM = YDBM
5
# - Same interface as DBM class
6
#
3

  
7 4
module YAML
8 5

  
6
# YAML + DBM = YDBM
7
# 
8
# YAML::DBM provides the same interface as ::DBM.
9
#
10
# However, while DBM only allows strings for both keys and values,
11
# this library allows one to use most Ruby objects for values
12
# by first converting them to YAML. Keys must be strings.
13
#
14
# Conversion to and from YAML is performed automatically.
15
#
16
# See the documentation for ::DBM and ::YAML for more information.
9 17
class DBM < ::DBM
10 18
    VERSION = "0.1"
19

  
20
    # Return value associated with +key+ from database.
21
    #
22
    # Returns +nil+ if there is no such +key+.
11 23
    def []( key )
12 24
        fetch( key )
13 25
    end
26

  
27
    # :call-seq:
28
    #   []=( key, value )
29
    #
30
    # Set +key+ to +value+ in database.
31
    #
32
    # +value+ will be converted to YAML before storage.
14 33
    def []=( key, val )
15 34
        store( key, val )
16 35
    end
36

  
37
    # :call-seq:
38
    #   fetch( key, ifnone = nil )
39
    #   fetch( key, &block )
40
    #
41
    # Return value associated with +key+.
42
    #
43
    # If there is no value for +key+ and no block is given, returns +ifnone+.
44
    #
45
    # Otherwise, calls block passing in the given +key+.
17 46
    def fetch( keystr, ifnone = nil )
18 47
        begin
19 48
            val = super( keystr )
......
26 55
            ifnone
27 56
        end
28 57
    end
58

  
59
    # Deprecated, used YAML::DBM#key instead.
29 60
    def index( keystr )
30 61
        super( keystr.to_yaml )
31 62
    end
63

  
64
    # Returns an array containing the values associated with the given keys.
32 65
    def values_at( *keys )
33 66
        keys.collect { |k| fetch( k ) }
34 67
    end
68

  
69
    # Deletes value from database assocated with +key+.
70
    #
71
    # Returns value or +nil+.
35 72
    def delete( key )
36 73
        v = super( key )
37 74
        if String === v
......
39 76
        end
40 77
        v
41 78
    end
42
    def delete_if
79

  
80
    # Calls the given block once for each +key+, +value+ pair in the database.
81
    # Deletes all entries for which the block returns true.
82
    #
83
    # Returns +self+.
84
    def delete_if # :yields: [key, value]
43 85
        del_keys = keys.dup
44 86
        del_keys.delete_if { |k| yield( k, fetch( k ) ) == false }
45 87
        del_keys.each { |k| delete( k ) }
46 88
        self
47 89
    end
90

  
91
    # Converts the contents of the database to an in-memory Hash, then calls
92
    # Hash#reject with the specified code block, returning a new Hash.
48 93
    def reject
49 94
        hsh = self.to_hash
50 95
        hsh.reject { |k,v| yield k, v }
51 96
    end
52
    def each_pair
97

  
98
    # Calls the given block once for each +key+, +value+ pair in the database.
99
    #
100
    # Returns +self+.
101
    def each_pair # :yields: [key, value]
53 102
        keys.each { |k| yield k, fetch( k ) }
54 103
        self
55 104
    end
56
    def each_value
105

  
106
    # Calls the given block for each value in database.
107
    #
108
    # Returns +self+.
109
    def each_value # :yields: value
57 110
        super { |v| yield YAML.load( v ) }
58 111
        self
59 112
    end
113

  
114
    # Returns an array of values from the database.
60 115
    def values
61 116
        super.collect { |v| YAML.load( v ) }
62 117
    end
118

  
119
    # Returns true if specified value is found in the database.
63 120
    def has_value?( val )
64 121
        each_value { |v| return true if v == val }
65 122
        return false
66 123
    end
124

  
125
    # Returns a Hash (not a DBM database) created by using each value in the
126
    # database as a key, with the corresponding key as its value.
127
    #
128
    # Note that all values in the hash will be Strings, but the keys will be
129
    # actual objects.
67 130
    def invert
68 131
        h = {}
69 132
        keys.each { |k| h[ self.fetch( k ) ] = k }
70 133
        h
71 134
    end
135

  
136
    # Replaces the contents of the database with the contents of the specified
137
    # object. Takes any object which implements the each_pair method, including
138
    # Hash and DBM objects.
72 139
    def replace( hsh )
73 140
        clear
74 141
        update( hsh )
75 142
    end
143

  
144
    # Removes a [key, value] pair from the database, and returns it.
145
    # If the database is empty, returns +nil+.
146
    #
147
    # The order in which values are removed/returned is not guaranteed.
76 148
    def shift
77 149
        a = super
78 150
        a[1] = YAML.load( a[1] ) if a
79 151
        a
80 152
    end
153

  
154
    # :call-seq:
155
    #   select( &block )
156
    #   select( *keys )
157
    #
158
    # If a block is provided, returns a new array containing [key, value] pairs
159
    # for which the block returns true.
160
    #
161
    # Otherwise, same as #values_at
81 162
    def select( *keys )
82 163
        if block_given?
83 164
            self.keys.collect { |k| v = self[k]; [k, v] if yield k, v }.compact
......
85 166
            values_at( *keys )
86 167
        end
87 168
    end
169

  
170
    # :call-seq:
171
    #   store( key, value )
172
    #
173
    #Stores +value+ in database with +key+ as the index. +value+ is converted
174
    #to YAML before being stored.
175
    #
176
    #Returns +value+
88 177
    def store( key, val )
89 178
        super( key, val.to_yaml )
90 179
        val
91 180
    end
181

  
182
    # Updates the database with multiple values from the specified object.
183
    # Takes any object which implements the each_pair method, including
184
    # Hash and DBM objects.
185
    #
186
    # Returns +self+.
92 187
    def update( hsh )
93 188
        hsh.keys.each do |k|
94 189
            self.store( k, hsh.fetch( k ) )
95 190
        end
96 191
        self
97 192
    end
193

  
194
    # Converts the contents of the database to an array of [key, value] arrays,
195
    # and returns it.
98 196
    def to_a
99 197
        a = []
100 198
        keys.each { |k| a.push [ k, self.fetch( k ) ] }
101 199
        a
102 200
    end
201

  
202
   
203
    # Converts the contents of the database to an in-memory Hash object, and
204
    # returns it.
103 205
    def to_hash
104 206
        h = {}
105 207
        keys.each { |k| h[ k ] = self.fetch( k ) }
106 208
        h
107 209
    end
210

  
108 211
    alias :each :each_pair
109 212
end
110 213

  
111
-