basis/db/types/types-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: classes hashtables help.markup help.syntax io.streams.string
   4 kernel sequences strings math ;
   5 IN: db.types
   6
   7 HELP: +autoincrement+
   8 { $description "" } ;
   9
  10 HELP: +db-assigned-id+
  11 { $description "The database assigns a primary key to the object. The primary key is most likely a big integer, but is database-dependent." } ;
  12
  13 HELP: +default+
  14 { $description "" } ;
  15
  16 HELP: +foreign-id+
  17 { $description "" } ;
  18
  19 HELP: +has-many+
  20 { $description "" } ;
  21
  22 HELP: +not-null+
  23 { $description "" } ;
  24
  25 HELP: +null+
  26 { $description "" } ;
  27
  28 HELP: +primary-key+
  29 { $description "" } ;
  30
  31 HELP: +random-id+
  32 { $description "Factor chooses a random number and tries to insert the tuple into the database with this number as its primary key. The default number of retries to find a unique random number is 10, though in practice it will almost certainly succeed on the first try." } ;
  33
  34 HELP: +serial+
  35 { $description "" } ;
  36
  37 HELP: +unique+
  38 { $description "" } ;
  39
  40 HELP: +user-assigned-id+
  41 { $description "The user is responsible for choosing a primary key for tuples inserted with this database type. Keys must be unique or else the database will throw an error. Usually it is better to use a " { $link +db-assigned-id+ } "." } ;
  42
  43 HELP: <generator-bind>
  44 { $values { "slot-name" object } { "key" object } { "generator-singleton" object } { "type" object } { "generator-bind" generator-bind } }
  45 { $description "" } ;
  46
  47 HELP: <literal-bind>
  48 { $values { "key" object } { "type" object } { "value" object } { "literal-bind" literal-bind } }
  49 { $description "" } ;
  50
  51 HELP: <low-level-binding>
  52 { $values { "value" object } { "low-level-binding" low-level-binding } }
  53 { $description "" } ;
  54
  55 HELP: BIG-INTEGER
  56 { $description "A 64-bit integer. Whether this number is signed or unsigned depends on the database backend." } ;
  57
  58 HELP: BLOB
  59 { $description "A byte array." } ;
  60
  61 HELP: BOOLEAN
  62 { $description "Either true or false." } ;
  63
  64 HELP: DATE
  65 { $description "A date without a time component." } ;
  66
  67 HELP: DATETIME
  68 { $description "A date and a time." } ;
  69
  70 HELP: DOUBLE
  71 { $description "Corresponds to Factor's 64-bit floating-point numbers." } ;
  72
  73 HELP: FACTOR-BLOB
  74 { $description "A serialized Factor object." } ;
  75
  76 HELP: INTEGER
  77 { $description "A small integer, at least 32 bits in length. Whether this number is signed or unsigned depends on the database backend." } ;
  78
  79 HELP: NULL
  80 { $description "The SQL null type." } ;
  81
  82 HELP: REAL
  83 { $description "A real number of unlimited precision. May not be supported on all databases." } ;
  84
  85 HELP: SIGNED-BIG-INTEGER
  86 { $description "For portability, if a number is known to be 64bit and signed, then this datatype may be used. Some databases, like SQLite, cannot store arbitrary bignums as BIGINT types. If storing arbitrary bignums, use " { $link FACTOR-BLOB } "." } ;
  87
  88 HELP: TEXT
  89 { $description "Stores a string that is longer than a " { $link VARCHAR } ". SQLite uses this type for strings; it does not handle " { $link VARCHAR } " strings." } ;
  90
  91 HELP: TIME
  92 { $description "A timestamp without a date component." } ;
  93
  94 HELP: TIMESTAMP
  95 { $description "A Factor timestamp." } ;
  96
  97 HELP: UNSIGNED-BIG-INTEGER
  98 { $description "For portability, if a number is known to be 64bit, then this datatype may be used. Some databases, like SQLite, cannot store arbitrary bignums as BIGINT types. If storing arbitrary bignums, use " { $link FACTOR-BLOB } "." } ;
  99
 100 { INTEGER SIGNED-BIG-INTEGER UNSIGNED-BIG-INTEGER } related-words
 101
 102 HELP: URL
 103 { $description "A Factor " { $link "urls" } " object." } ;
 104
 105 HELP: VARCHAR
 106 { $description "The SQL varchar type. This type can take an integer as an argument." }
 107 { $examples { $unchecked-example "{ VARCHAR 256 }" "" } } ;
 108
 109 HELP: user-assigned-id-spec?
 110 { $values
 111      { "specs" "a sequence of sql specs" }
 112      { "?" "a boolean" } }
 113 { $description "Tests if any of the sql specs has the type " { $link +user-assigned-id+ } "." } ;
 114
 115 HELP: bind#
 116 { $values
 117      { "spec" null } { "obj" object } }
 118 { $description "" } ;
 119
 120 HELP: bind%
 121 { $values
 122      { "spec" null } }
 123 { $description "" } ;
 124
 125 HELP: compound
 126 { $values
 127      { "string" string } { "obj" object }
 128      { "hash" hashtable } }
 129 { $description "" } ;
 130
 131 HELP: db-assigned-id-spec?
 132 { $values
 133      { "specs" "a sequence of sql specs" }
 134      { "?" "a boolean" } }
 135 { $description "Tests if any of the sql specs has the type " { $link +db-assigned-id+ } "." } ;
 136
 137 HELP: find-primary-key
 138 { $values
 139      { "specs" "a sequence of sql-specs" }
 140      { "seq" "a sequence of sql-specs" } }
 141 { $description "Returns the rows from the sql-specs array that are part of the primary key. Composite primary keys are supported, so this word must return a sequence." }
 142 { $notes "This is a low-level word." } ;
 143
 144 HELP: generator-bind
 145 { $description "" } ;
 146
 147 HELP: get-slot-named
 148 { $values
 149      { "name" "a slot name" } { "tuple" tuple }
 150      { "value" "the value stored in the slot" } }
 151 { $description "Returns the value stored in a tuple slot, where the tuple slot is a string." } ;
 152
 153 HELP: literal-bind
 154 { $description "" } ;
 155
 156 HELP: lookup-create-type
 157 { $values
 158      { "obj" object }
 159      { "string" string } }
 160 { $description "" } ;
 161
 162 HELP: lookup-modifier
 163 { $values
 164      { "obj" object }
 165      { "string" string } }
 166 { $description "" } ;
 167
 168 HELP: lookup-type
 169 { $values
 170      { "obj" object }
 171      { "string" string } }
 172 { $description "" } ;
 173
 174 HELP: low-level-binding
 175 { $description "" } ;
 176
 177 HELP: modifiers
 178 { $values
 179      { "spec" null }
 180      { "string" string } }
 181 { $description "" } ;
 182
 183 HELP: no-sql-type
 184 { $values
 185      { "type" "a sql type" } }
 186 { $description "Throws an error containing a sql type that is unsupported or the result of a typo." } ;
 187
 188 HELP: normalize-spec
 189 { $values
 190      { "spec" null } }
 191 { $description "" } ;
 192
 193 HELP: offset-of-slot
 194 { $values
 195      { "string" string } { "tuple" tuple }
 196      { "n" integer } }
 197 { $description "Returns the offset of a tuple slot accessed by name." } ;
 198
 199 HELP: persistent-table
 200 { $values
 201
 202      { "hash" hashtable } }
 203 { $description "" } ;
 204
 205 HELP: primary-key?
 206 { $values
 207      { "spec" null }
 208      { "?" "a boolean" } }
 209 { $description "" } ;
 210
 211 HELP: random-id-generator
 212 { $description "" } ;
 213
 214 HELP: relation?
 215 { $values
 216      { "spec" null }
 217      { "?" "a boolean" } }
 218 { $description "" } ;
 219
 220 HELP: remove-db-assigned-id
 221 { $values
 222      { "specs" null }
 223      { "obj" object } }
 224 { $description "" } ;
 225
 226 HELP: remove-id
 227 { $values
 228      { "specs" null }
 229      { "obj" object } }
 230 { $description "" } ;
 231
 232 HELP: remove-relations
 233 { $values
 234      { "specs" null }
 235      { "newcolumns" null } }
 236 { $description "" } ;
 237
 238 HELP: set-slot-named
 239 { $values
 240      { "value" null } { "name" null } { "obj" object } }
 241 { $description "" } ;
 242
 243 HELP: spec>tuple
 244 { $values
 245      { "class" class } { "spec" null }
 246      { "tuple" null } }
 247 { $description "" } ;
 248
 249 HELP: sql-spec
 250 { $description "" } ;
 251
 252 HELP: unknown-modifier
 253 { $values { "modifier" string } }
 254 { $description "Throws an error containing an unknown sql modifier." } ;
 255
 256 ARTICLE: "db.types" "Database types"
 257 "The " { $vocab-link "db.types" } " vocabulary maps Factor types to database types." $nl
 258 "Primary keys:"
 259 { $subsection +db-assigned-id+ }
 260 { $subsection +user-assigned-id+ }
 261 { $subsection +random-id+ }
 262 "Null and boolean types:"
 263 { $subsection NULL }
 264 { $subsection BOOLEAN }
 265 "Text types:"
 266 { $subsection VARCHAR }
 267 { $subsection TEXT }
 268 "Number types:"
 269 { $subsection INTEGER }
 270 { $subsection BIG-INTEGER }
 271 { $subsection SIGNED-BIG-INTEGER }
 272 { $subsection UNSIGNED-BIG-INTEGER }
 273 { $subsection DOUBLE }
 274 { $subsection REAL }
 275 "Calendar types:"
 276 { $subsection DATE }
 277 { $subsection DATETIME }
 278 { $subsection TIME }
 279 { $subsection TIMESTAMP }
 280 "Factor byte-arrays:"
 281 { $subsection BLOB }
 282 "Arbitrary Factor objects:"
 283 { $subsection FACTOR-BLOB }
 284 "Factor URLs:"
 285 { $subsection URL } ;
 286
 287 ABOUT: "db.types"