Project

General

Profile

Bug #6410 ยป 0001-Add-documentation-for-SDBM.patch

jsc (Justin Collins), 05/08/2012 01:41 PM

View differences:

ext/sdbm/init.c
15 15
#include <fcntl.h>
16 16
#include <errno.h>
17 17

  
18
/*
19
 * Document-class: SDBM
20
 *
21
 * = Introduction
22
 *
23
 * SDBM provides a simple file-based key-value store, which can only store String
24
 * keys and values.
25
 *
26
 * Note that Ruby comes with the source code for SDBM, while the DBM and GDBM
27
 * standard libraries rely on external libraries and headers.
28
 *
29
 * = Examples
30
 *
31
 * Insert values:
32
 *
33
 *     require 'sdbm'
34
 *
35
 *     SDBM.open 'my_database' do |db|
36
 *       db['apple'] = 'fruit'
37
 *       db['pear'] = 'fruit'
38
 *       db['carrot'] = 'vegetable'
39
 *       db['tomato'] = 'vegetable'
40
 *     end
41
 *
42
 * Bulk update:
43
 *
44
 *     require 'sdbm'
45
 *
46
 *     SDBM.open 'my_database' do |db|
47
 *       db.update('peach' => 'fruit', 'tomato' => 'fruit')
48
 *     end
49
 *
50
 * Retrieve values:
51
 *
52
 *     require 'sdbm'
53
 *
54
 *     SDBM.open 'my_database' do |db|
55
 *       db.each do |key, value|
56
 *         puts "Key: #{key}, Value: #{value}"
57
 *       end
58
 *     end
59
 *
60
 *     #Output:
61
 *     #  Key: apple, Value: fruit
62
 *     #  Key: pear, Value: fruit
63
 *     #  Key: carrot, Value: vegetable
64
 *     #  Key: peach, Value: fruit
65
 *     #  Key: tomato, Value: fruit
66
 */
67

  
18 68
static VALUE rb_cDBM, rb_eDBMError;
19 69

  
20 70
struct dbmdata {
......
47 97
    ruby_xfree(dbmp);
48 98
}
49 99

  
100
/*
101
 * call-seq:
102
 *     sdbm.close -> nil
103
 *
104
 * Closes the database file.
105
 *
106
 * Raises SDBMError if the database is already closed.
107
 */ 
50 108
static VALUE
51 109
fsdbm_close(VALUE obj)
52 110
{
......
59 117
    return Qnil;
60 118
}
61 119

  
120
/*
121
* call-seq:
122
*     sdbm.closed? -> true or false
123
*
124
* Returns true if the database is closed.
125
*/ 
62 126
static VALUE
63 127
fsdbm_closed(VALUE obj)
64 128
{
......
78 142
{
79 143
    return Data_Wrap_Struct(klass, 0, free_sdbm, 0);
80 144
}
81

  
145
/*
146
* call-seq:
147
*      SDBM.new(filename, mode = 0666)
148
*
149
* Creates a new database handle by opening the given _filename_. sdbm actually
150
* uses two physical files, with extensions '.dir' and '.pag'. These extensions 
151
* will automatically be appended to the _filename_.
152
*
153
* If the file does not exist, a new file will be created using the given _mode_, unless _mode_ is explicitly set to nil. In the latter case, no database will be created.
154
*
155
* If the file exists, it will be opened in read/write mode. If this fails, it will be opened in read-only mode.
156
*/
82 157
static VALUE
83 158
fsdbm_initialize(int argc, VALUE *argv, VALUE obj)
84 159
{
......
120 195
    return obj;
121 196
}
122 197

  
198
/*
199
 * call-seq:
200
 *      SDBM.open(filename, mode = 0666)
201
 *      SDBM.open(filename, mode = 0666) { |sdbm| ... }
202
 *
203
 * If called without a block, this is the same as SDBM.new.
204
 *
205
 * If a block is given, the new database will be passed to the block and
206
 * will be safely closed after the block has executed.
207
 *
208
 * Example:
209
 *
210
 *     require 'sdbm'
211
 *
212
 *     SDBM.open('my_database') do |db|
213
 *       db['hello'] = 'world'
214
 *     end
215
 */
123 216
static VALUE
124 217
fsdbm_s_open(int argc, VALUE *argv, VALUE klass)
125 218
{
......
157 250
    return rb_external_str_new(value.dptr, value.dsize);
158 251
}
159 252

  
253
/*
254
 * call-seq:
255
 *      sdbm[key] -> value or nil
256
 *
257
 * Returns the value in the database associated with the given _key_ string.
258
 *
259
 * If no value is found, returns nil.
260
 */
160 261
static VALUE
161 262
fsdbm_aref(VALUE obj, VALUE keystr)
162 263
{
163 264
    return fsdbm_fetch(obj, keystr, Qnil);
164 265
}
165 266

  
267
/*
268
 * call-seq:
269
 *      sdbm.fetch(key) -> value or nil
270
 *      sdbm.fetch(key) { |key| ... }
271
 *
272
 * Returns the value in the database associated with the given _key_ string.
273
 *
274
 * If a block is provided, the block will be called when there is no value
275
 * associated with the given _key_. The _key_ will be passed in as an argument to
276
 * the block.
277
 *
278
 * If no block is provided and no value is associated with the given  _key_,
279
 * then an IndexError will be raised.
280
 */
166 281
static VALUE
167 282
fsdbm_fetch_m(int argc, VALUE *argv, VALUE obj)
168 283
{
......
176 291
    return valstr;
177 292
}
178 293

  
294
/*
295
 * call-seq:
296
 *      sdbm.key(value) -> key
297
 *
298
 * Returns the key associated with the given _value_. If more than one
299
 * key corresponds to the given value, then the first key to be found
300
 * will be returned. If no keys are found, nil will be returned.
301
 */
179 302
static VALUE
180 303
fsdbm_key(VALUE obj, VALUE valstr)
181 304
{
......
197 320
    return Qnil;
198 321
}
199 322

  
323
/*
324
 * call-seq:
325
 *      sdbm.index(value) -> key
326
 *
327
 * This method is the same as SDBM#key and has been deprecated.
328
 */
200 329
static VALUE
201 330
fsdbm_index(VALUE hash, VALUE value)
202 331
{
......
204 333
    return fsdbm_key(hash, value);
205 334
}
206 335

  
336
/* call-seq:
337
 *      sdbm.select { |key, value| block } -> array
338
 *
339
 * Returns a new array of key-value pairs for which the _block_ returns
340
 * true.
341
 *
342
 * Example:
343
 *
344
 *    require 'sdbm'
345
 *
346
 *    SDBM.open 'my_database' do |db|
347
 *      db['apple'] = 'fruit'
348
 *      db['pear'] = 'fruit'
349
 *      db['spinach'] = 'vegetable'
350
 *
351
 *      veggies = db.select do |key, value|
352
 *        value == 'vegetable'
353
 *      end                    #=> [["apple", "fruit"], ["pear", "fruit"]]
354
 *    end
355
 */
207 356
static VALUE
208 357
fsdbm_select(VALUE obj)
209 358
{
......
228 377
    return new;
229 378
}
230 379

  
380
/* call-seq:
381
 *      sdbm.values_at(key, ...) -> array
382
 *
383
 * Returns an array of values corresponding to the given keys.
384
 */
231 385
static VALUE
232 386
fsdbm_values_at(int argc, VALUE *argv, VALUE obj)
233 387
{
......
248 402
    if (OBJ_FROZEN(obj)) rb_error_frozen("SDBM");
249 403
}
250 404

  
405
/* 
406
 * call-seq:
407
 *      sdbm.delete(key) -> value or nil
408
 *      sdbm.delete(key) { |key, value| ... }
409
 *
410
 * Deletes the kay-value pair corresponding to the given _key_. If the
411
 * key exists, the deleted value will be returned, otherwise nil.
412
 *
413
 * If a block is provided, the deleted key and value will be passed to the
414
 * block as arguments. If the key does not exist in the database, the
415
 * value will be nil.
416
 */
251 417
static VALUE
252 418
fsdbm_delete(VALUE obj, VALUE keystr)
253 419
{
......
283 449
    return valstr;
284 450
}
285 451

  
452
/* 
453
 * call-seq:
454
 *      sdbm.shift -> array or nil
455
 *
456
 * Removes a key-value pair from the database and returns them as an
457
 * array. If the database is empty, returns nil.
458
 */
286 459
static VALUE
287 460
fsdbm_shift(VALUE obj)
288 461
{
......
306 479
    return rb_assoc_new(keystr, valstr);
307 480
}
308 481

  
482
/* 
483
 * call-seq:
484
 *      sdbm.delete_if { |key, value| block } -> self
485
 *      sdbm.reject! { |key, value| block } -> self
486
 *
487
 * Iterates over the key-value pairs in the database, deleting those for
488
 * which the _block_ returns true.
489
 */
309 490
static VALUE
310 491
fsdbm_delete_if(VALUE obj)
311 492
{
......
345 526
    return obj;
346 527
}
347 528

  
529
/*
530
 * call-seq:
531
 *      sdbm.clear -> self
532
 *
533
 * Deletes all data from the database.
534
 */
348 535
static VALUE
349 536
fsdbm_clear(VALUE obj)
350 537
{
......
365 552
    return obj;
366 553
}
367 554

  
555
/*
556
 * call-seq:
557
 *      sdbm.invert -> Hash
558
 *
559
 * Returns a Hash in which the key-value pairs have been inverted.
560
 *
561
 * Example:
562
 *
563
 *     require 'sdbm'
564
 *
565
 *     SDBM.open 'my_database' do |db|
566
 *       db.update('apple' => 'fruit', 'spinach' => 'vegetable')
567
 *
568
 *       db.invert  #=> {"fruit" => "apple", "vegetable" => "spinach"}
569
 *     end
570
 */
368 571
static VALUE
369 572
fsdbm_invert(VALUE obj)
370 573
{
......
384 587
    return hash;
385 588
}
386 589

  
590
/*
591
 * call-seq:
592
 *      sdbm.store(key, value) -> value
593
 *
594
 * Stores a new value in the database with the given _key_ as an index.
595
 *
596
 * If the key already exists, this will update the value associated with
597
 * the key.
598
 *
599
 * Returns the given _value_.
600
 */
387 601
static VALUE
388 602
fsdbm_store(VALUE obj, VALUE keystr, VALUE valstr)
389 603
{
......
430 644
    return Qnil;
431 645
}
432 646

  
647
/* 
648
 * call-seq:
649
 *      sdbm.update(pairs) -> self
650
 *
651
 * Insert or update key-value pairs.
652
 *
653
 * This method will work with any object which implements an each_pair
654
 * method, such as a Hash.
655
 */
433 656
static VALUE
434 657
fsdbm_update(VALUE obj, VALUE other)
435 658
{
......
437 660
    return obj;
438 661
}
439 662

  
663
/* 
664
 * call-seq:
665
 *      sdbm.replace(pairs) -> self
666
 *
667
 * Empties the database, then inserts the given key-value pairs.
668
 *
669
 * This method will work with any object which implements an each_pair
670
 * method, such as a Hash.
671
 */
440 672
static VALUE
441 673
fsdbm_replace(VALUE obj, VALUE other)
442 674
{
......
445 677
    return obj;
446 678
}
447 679

  
680
/*
681
 * call-seq:
682
 *      sdbm.length -> integer
683
 *      sdbm.size -> integer
684
 *
685
 * Returns the number of keys in the database.
686
 */ 
448 687
static VALUE
449 688
fsdbm_length(VALUE obj)
450 689
{
......
464 703
    return INT2FIX(i);
465 704
}
466 705

  
706
/*
707
 * call-seq:
708
 *      sdbm.empty? -> true or false
709
 *
710
 * Returns true if the database is empty.
711
 */
467 712
static VALUE
468 713
fsdbm_empty_p(VALUE obj)
469 714
{
......
487 732
    return Qfalse;
488 733
}
489 734

  
735
/*
736
 * call-seq:
737
 *      sdbm.each_value
738
 *      sdbm.each_value { |value| ... }
739
 *
740
 * Iterates over each value in the database.
741
 *
742
 * If no block is given, returns an Enumerator.
743
 */
490 744
static VALUE
491 745
fsdbm_each_value(VALUE obj)
492 746
{
......
505 759
    return obj;
506 760
}
507 761

  
762
/*
763
 * call-seq:
764
 *      sdbm.each_key
765
 *      sdbm.each_key { |key| ... }
766
 *
767
 * Iterates over each key in the database.
768
 *
769
 * If no block is given, returns an Enumerator.
770
 */
508 771
static VALUE
509 772
fsdbm_each_key(VALUE obj)
510 773
{
......
522 785
    return obj;
523 786
}
524 787

  
788
/*
789
 * call-seq:
790
 *      sdbm.each_pair
791
 *      sdbm.each_pair { |key, value| ... }
792
 *
793
 * Iterates over each key-value pair in the database.
794
 *
795
 * If no block is given, returns an Enumerator.
796
 */
525 797
static VALUE
526 798
fsdbm_each_pair(VALUE obj)
527 799
{
......
544 816
    return obj;
545 817
}
546 818

  
819
/*
820
 * call-seq:
821
 *      sdbm.keys -> array
822
 *
823
 * Returns a new array containing the keys in the database.
824
 */
547 825
static VALUE
548 826
fsdbm_keys(VALUE obj)
549 827
{
......
561 839
    return ary;
562 840
}
563 841

  
842
/*
843
 * call-seq:
844
 *      sdbm.values -> array
845
 *
846
 * Returns a new array containing the values in the database.
847
 */
564 848
static VALUE
565 849
fsdbm_values(VALUE obj)
566 850
{
......
579 863
    return ary;
580 864
}
581 865

  
866
/*
867
 * call-seq:
868
 *      sdbm.has_key?(key) -> true or false
869
 *
870
 * Returns true if the database contains the given _key_.
871
 */
582 872
static VALUE
583 873
fsdbm_has_key(VALUE obj, VALUE keystr)
584 874
{
......
596 886
    return Qfalse;
597 887
}
598 888

  
889
/*
890
 * call-seq:
891
 *      sdbm.has_value?(key) -> true or false
892
 *
893
 * Returns true if the database contains the given _value_.
894
 */
599 895
static VALUE
600 896
fsdbm_has_value(VALUE obj, VALUE valstr)
601 897
{
......
617 913
    return Qfalse;
618 914
}
619 915

  
916
/*
917
 * call-seq:
918
 *      sdbm.to_a -> array
919
 *
920
 * Returns a new array containing each key-value pair in the database.
921
 *
922
 * Example:
923
 *
924
 *     require 'sdbm'
925
 *
926
 *     SDBM.open 'my_database' do |db|
927
 *       db.update('apple' => 'fruit', 'spinach' => 'vegetable')
928
 *
929
 *       db.to_a  #=> [["apple", "fruit"], ["spinach", "vegetable"]]
930
 *     end
931
 */
620 932
static VALUE
621 933
fsdbm_to_a(VALUE obj)
622 934
{
......
636 948
    return ary;
637 949
}
638 950

  
951
/*
952
 * call-seq:
953
 *      sdbm.to_hash -> Hash
954
 *
955
 * Returns a new Hash containing each key-value pair in the database.
956
 */
639 957
static VALUE
640 958
fsdbm_to_hash(VALUE obj)
641 959
{
......
655 973
    return hash;
656 974
}
657 975

  
976
/*
977
 * call-seq:
978
 *      sdbm.reject { |key, value| block } -> Hash
979
 *
980
 * Creates a new Hash using the key-value pairs from the database, then
981
 * calls Hash#reject with the given _block_, which returns a Hash with
982
 * only the key-value pairs for which the block returns false.
983
 */
658 984
static VALUE
659 985
fsdbm_reject(VALUE obj)
660 986
{
......
666 992
{
667 993
    rb_cDBM = rb_define_class("SDBM", rb_cObject);
668 994
    rb_eDBMError = rb_define_class("SDBMError", rb_eStandardError);
995
    /* Document-class: SDBMError
996
     * Exception class used to return errors from the sdbm library.
997
     */
669 998
    rb_include_module(rb_cDBM, rb_mEnumerable);
670 999

  
671 1000
    rb_define_alloc_func(rb_cDBM, fsdbm_alloc);
672
-