extra/gdbm/gdbm-docs.factor

   1 ! Copyright (C) 2010 Dmitry Shubin.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: gdbm.ffi gdbm.private help.markup help.syntax kernel math
   4 quotations strings ;
   5 IN: gdbm
   6
   7 HELP: gdbm
   8 { $class-description "Instance of this class is used as database configuration object. It has following slots:"
   9
  10   { $table
  11     { { $slot "name" } "The file name of the database." }
  12     { { $slot "block-size" } "The size of a single transfer from disk to memory. If the value is less than 512, the file system blocksize is used (this is default)." }
  13     { { $slot "role" } "Determines what kind of access the user wants to obtain (see below)." }
  14     { { $slot "sync" } { "Being set to " { $link t } " causes all database operations to be synchronized to the disk." } }
  15     { { $slot "nolock" } { "Being set to " { $link t } " prevents gdbm from performing any locking on the database file." } }
  16     { { $slot "mode" } "An integer representing standard UNIX access permissions." }
  17   }
  18   "The " { $slot "role" } " can be set to one of the folowing values:"
  19   { $table
  20     { { $snippet "reader" } "The user can only read from existing database." }
  21     { { $snippet "writer" } "The user can access existing database as reader and writer." }
  22     { { $snippet "wrcreat" } "Open the database for reading and writing if it exists and create new one otherwise." }
  23     { { $snippet "newdb" } "Create empty database even if there is already one with the same name." }
  24   }
  25 } ;
  26
  27 HELP: <gdbm>
  28 { $values { "gdbm" gdbm } }
  29 { $description "Creates database configuration object with all slots set to their default values. See " { $link gdbm } " for complete slots description." } ;
  30
  31 HELP: gdbm-info
  32 { $values { "str" string } }
  33 { $description "Returns version number and build date." } ;
  34
  35 HELP: delete
  36 { $values { "key" object } }
  37 { $description "Removes the keyed item from the database." } ;
  38
  39 HELP: gdbm-error-message
  40 { $values { "error" gdbm-error } { "msg" string } }
  41 { $description "Returns error message in human readable format." } ;
  42
  43 HELP: exists?
  44 { $values { "key" object } { "?" boolean } }
  45 { $description "Searches for a particular key without retreiving it." } ;
  46
  47 HELP: each-key
  48 { $values { "quot" quotation } }
  49 { $description "Applies the quotation to the each key in the database." } ;
  50
  51 HELP: each-value
  52 { $values { "quot" quotation } }
  53 { $description "Applies the quotation to the each value in the database." } ;
  54
  55 HELP: each-record
  56 { $values { "quot" quotation } }
  57 { $description "Applies the quotation to the each key-value pair in the database." } ;
  58
  59 HELP: gdbm-file-descriptor
  60 { $values { "desc" integer } }
  61 { $description "Returns the file descriptor of the database. This is used for manual database locking if it was opened with " { $snippet "nolock" } " flag set to " { $link t } "." } ;
  62
  63 HELP: fetch
  64 { $values
  65   { "key" object }
  66   { "content/f" { "the value associated with " { $snippet "key" } " or " { $link f } " if there is no such key" } }
  67 }
  68 { $description "Looks up a given key and returns value associated with it. This word makes no distinction between a missing value and a value set to " { $link f } "." } ;
  69
  70 HELP: fetch*
  71 { $values { "key" object } { "content" object } { "?" boolean } }
  72 { $description "Looks up a given key and returns value associated with it. The boolean flag can decide between the case of a missing value, and a value of " { $link f } "." } ;
  73
  74 HELP: first-key
  75 { $values { "key/f" object } }
  76 { $description "Returns first key in the database. This word makes no distinction between an empty database case and a case of a first value set to " { $link f } "." } ;
  77
  78 HELP: first-key*
  79 { $values { "key" object } { "?" boolean } }
  80 { $description "Returns first key in the database. The boolean flag can decide between the case of an empty database and a case of a first value set to " { $link f } "." } ;
  81
  82 HELP: insert
  83 { $values { "key" object } { "content" object } }
  84 { $description "Inserts record into the database. Throws an error if the key already exists." } ;
  85
  86 HELP: next-key
  87 { $values { "key" object } { "key/f" object } }
  88 { $description "Given a key returns next key in the database. This word makes no distinction between reaching the end of the database case and a case of a next value set to " { $link f } "." } ;
  89
  90 HELP: next-key*
  91 { $values { "key" object } { "next-key" object } { "?" boolean } }
  92 { $description "Given a key returns next key in the database. The boolean flag can decide between the case of reaching the end of the database and a case of a next value set to " { $link f } "." } ;
  93
  94 HELP: reorganize
  95 { $description "Reorganisation is a process of shinking the space used by gdbm. This requires creating a new file and moving all elements from old gdbm file to new one." } ;
  96
  97 HELP: replace
  98 { $values { "key" object } { "content" object } }
  99 { $description "Inserts record into the database replacing old value with the new one if the key already exists." } ;
 100
 101 HELP: set-block-merging
 102 { $values { "?" boolean } }
 103 { $description "If set, this option causes adjacent free blocks to be merged. The default is " { $link f } "." } ;
 104
 105 HELP: set-block-pool
 106 { $values { "?" boolean } }
 107 { $description "If set, this option causes all subsequent free blocks to be placed in the global pool. The default is " { $link f } "." } ;
 108
 109 HELP: set-cache-size
 110 { $values { "size" integer } }
 111 { $description "Sets the size of the internal bucket cache. The default value is 100. This option may only be set once." } ;
 112
 113 HELP: set-sync-mode
 114 { $values { "?" boolean } }
 115 { $description "Turns on or off file system synchronization. The default is " { $link f } "." } ;
 116
 117 HELP: synchronize
 118 { $description "Performs database synchronization: make sure the disk version of the database has been completely updated." } ;
 119
 120 HELP: with-gdbm
 121 { $values
 122   { "gdbm" "a database configuration object" } { "quot" quotation }
 123 }
 124 { $description "Calls the quotation with a database bound to " { $link current-dbf } " symbol." } ;
 125
 126
 127 ARTICLE: "gdbm" "GNU Database Manager"
 128 "The " { $vocab-link "gdbm" } " vocabulary provides an interface to GNU DataBase Manager. This is a GNU implementation of the standard Unix dbm library, originally developed at Berkeley."
 129
 130 $nl
 131 "This is a very brief manual. For a more detailed description consult the official gdbm documentation."
 132
 133 { $heading "Basics" }
 134 "All interaction with gdbm database should be realized using special combinator which automates all work for database initialisation and cleanup. All initialisation options are passed to combinator with a database configuration object."
 135 { $subsections gdbm <gdbm> with-gdbm }
 136 "For actual record manipulation the following words are used:"
 137 { $subsections insert exists? fetch delete }
 138
 139 { $heading "Sequential access" }
 140 "It is possible to iterate through all records in the database with"
 141 { $subsections first-key next-key }
 142 "The following combinators, however, provide more convenient way to do that:"
 143 { $subsections each-key each-value each-record }
 144 "The order in which records are accessed has nothing to do with the order in which records have been stored. Note that these words can only be used in read-only algorithms since delete operation re-arranges the hash table."
 145 ;
 146
 147 ABOUT: "gdbm"