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   { $slots
  10     { "name" "The file name of the database." }
  11     { "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)." }
  12     { "role" "Determines what kind of access the user wants to obtain (see below)." }
  13     { "sync" { "Being set to " { $link t } " causes all database operations to be synchronized to the disk." } }
  14     { "nolock" { "Being set to " { $link t } " prevents gdbm from performing any locking on the database file." } }
  15     { "mode" "An integer representing standard UNIX access permissions." }
  16   }
  17   "The " { $slot "role" } " can be set to one of the folowing values:"
  18   { $table
  19     { { $snippet "reader" } "The user can only read from existing database." }
  20     { { $snippet "writer" } "The user can access existing database as reader and writer." }
  21     { { $snippet "wrcreat" } "Open the database for reading and writing if it exists and create new one otherwise." }
  22     { { $snippet "newdb" } "Create empty database even if there is already one with the same name." }
  23   }
  24 } ;
  25
  26 HELP: <gdbm>
  27 { $values { "gdbm" gdbm } }
  28 { $description "Creates database configuration object with all slots set to their default values. See " { $link gdbm } " for complete slots description." } ;
  29
  30 HELP: gdbm-info
  31 { $values { "str" string } }
  32 { $description "Returns version number and build date." } ;
  33
  34 HELP: delete
  35 { $values { "key" object } }
  36 { $description "Removes the keyed item from the database." } ;
  37
  38 HELP: gdbm-error-message
  39 { $values { "error" gdbm-error } { "msg" string } }
  40 { $description "Returns error message in human readable format." } ;
  41
  42 HELP: file-exists?
  43 { $values { "key" object } { "?" boolean } }
  44 { $description "Searches for a particular key without retreiving it." } ;
  45
  46 HELP: each-key
  47 { $values { "quot" quotation } }
  48 { $description "Applies the quotation to the each key in the database." } ;
  49
  50 HELP: each-value
  51 { $values { "quot" quotation } }
  52 { $description "Applies the quotation to the each value in the database." } ;
  53
  54 HELP: each-record
  55 { $values { "quot" quotation } }
  56 { $description "Applies the quotation to the each key-value pair in the database." } ;
  57
  58 HELP: gdbm-file-descriptor
  59 { $values { "desc" integer } }
  60 { $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 } "." } ;
  61
  62 HELP: fetch
  63 { $values
  64   { "key" object }
  65   { "content/f" { "the value associated with " { $snippet "key" } " or " { $link f } " if there is no such key" } }
  66 }
  67 { $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 } "." } ;
  68
  69 HELP: fetch*
  70 { $values { "key" object } { "content" object } { "?" boolean } }
  71 { $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 } "." } ;
  72
  73 HELP: first-key
  74 { $values { "key/f" object } }
  75 { $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 } "." } ;
  76
  77 HELP: first-key*
  78 { $values { "key" object } { "?" boolean } }
  79 { $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 } "." } ;
  80
  81 HELP: insert
  82 { $values { "key" object } { "content" object } }
  83 { $description "Inserts record into the database. Throws an error if the key already exists." } ;
  84
  85 HELP: next-key
  86 { $values { "key" object } { "key/f" object } }
  87 { $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 } "." } ;
  88
  89 HELP: next-key*
  90 { $values { "key" object } { "next-key" object } { "?" boolean } }
  91 { $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 } "." } ;
  92
  93 HELP: reorganize
  94 { $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." } ;
  95
  96 HELP: replace
  97 { $values { "key" object } { "content" object } }
  98 { $description "Inserts record into the database replacing old value with the new one if the key already exists." } ;
  99
 100 HELP: set-block-merging
 101 { $values { "?" boolean } }
 102 { $description "If set, this option causes adjacent free blocks to be merged. The default is " { $link f } "." } ;
 103
 104 HELP: set-block-pool
 105 { $values { "?" boolean } }
 106 { $description "If set, this option causes all subsequent free blocks to be placed in the global pool. The default is " { $link f } "." } ;
 107
 108 HELP: set-cache-size
 109 { $values { "size" integer } }
 110 { $description "Sets the size of the internal bucket cache. The default value is 100. This option may only be set once." } ;
 111
 112 HELP: set-sync-mode
 113 { $values { "?" boolean } }
 114 { $description "Turns on or off file system synchronization. The default is " { $link f } "." } ;
 115
 116 HELP: synchronize
 117 { $description "Performs database synchronization: make sure the disk version of the database has been completely updated." } ;
 118
 119 HELP: with-gdbm
 120 { $values
 121   { "gdbm" "a database configuration object" } { "quot" quotation }
 122 }
 123 { $description "Calls the quotation with a database bound to " { $link current-dbf } " symbol." } ;
 124
 125
 126 ARTICLE: "gdbm" "GNU Database Manager"
 127 "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."
 128
 129 $nl
 130 "This is a very brief manual. For a more detailed description consult the official gdbm documentation."
 131
 132 { $heading "Basics" }
 133 "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."
 134 { $subsections gdbm <gdbm> with-gdbm }
 135 "For actual record manipulation the following words are used:"
 136 { $subsections insert file-exists? fetch delete }
 137
 138 { $heading "Sequential access" }
 139 "It is possible to iterate through all records in the database with"
 140 { $subsections first-key next-key }
 141 "The following combinators, however, provide more convenient way to do that:"
 142 { $subsections each-key each-value each-record }
 143 "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."
 144 ;
 145
 146 ABOUT: "gdbm"