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 { $description "" } ;
  45
  46 HELP: <literal-bind>
  47 { $description "" } ;
  48
  49 HELP: <low-level-binding>
  50 { $description "" } ;
  51
  52 HELP: BIG-INTEGER
  53 { $description "A 64-bit integer. Whether this number is signed or unsigned depends on the database backend." } ;
  54
  55 HELP: BLOB
  56 { $description "A byte array." } ;
  57
  58 HELP: BOOLEAN
  59 { $description "Either true or false." } ;
  60
  61 HELP: DATE
  62 { $description "A date without a time component." } ;
  63
  64 HELP: DATETIME
  65 { $description "A date and a time." } ;
  66
  67 HELP: DOUBLE
  68 { $description "Corresponds to Factor's 64-bit floating-point numbers." } ;
  69
  70 HELP: FACTOR-BLOB
  71 { $description "A serialized Factor object." } ;
  72
  73 HELP: INTEGER
  74 { $description "A small integer, at least 32 bits in length. Whether this number is signed or unsigned depends on the database backend." } ;
  75
  76 HELP: NULL
  77 { $description "The SQL null type." } ;
  78
  79 HELP: REAL
  80 { $description "A real number of unlimited precision. May not be supported on all databases." } ;
  81
  82 HELP: SIGNED-BIG-INTEGER
  83 { $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 } "." } ;
  84
  85 HELP: TEXT
  86 { $description "Stores a string that is longer than a " { $link VARCHAR } ". SQLite uses this type for strings; it does not handle " { $link VARCHAR } " strings." } ;
  87
  88 HELP: TIME
  89 { $description "A timestamp without a date component." } ;
  90
  91 HELP: TIMESTAMP
  92 { $description "A Factor timestamp." } ;
  93
  94 HELP: UNSIGNED-BIG-INTEGER
  95 { $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 } "." } ;
  96
  97 { INTEGER SIGNED-BIG-INTEGER UNSIGNED-BIG-INTEGER } related-words
  98
  99 HELP: URL
 100 { $description "A Factor " { $link "urls" } " object." } ;
 101
 102 HELP: VARCHAR
 103 { $description "The SQL varchar type. This type can take an integer as an argument." }
 104 { $examples { $unchecked-example "{ VARCHAR 256 }" "" } } ;
 105
 106 HELP: user-assigned-id-spec?
 107 { $values
 108      { "specs" "a sequence of sql specs" }
 109      { "?" "a boolean" } }
 110 { $description "Tests if any of the sql specs has the type " { $link +user-assigned-id+ } "." } ;
 111
 112 HELP: bind#
 113 { $values
 114      { "spec" null } { "obj" object } }
 115 { $description "" } ;
 116
 117 HELP: bind%
 118 { $values
 119      { "spec" null } }
 120 { $description "" } ;
 121
 122 HELP: compound
 123 { $values
 124      { "string" string } { "obj" object }
 125      { "hash" hashtable } }
 126 { $description "" } ;
 127
 128 HELP: db-assigned-id-spec?
 129 { $values
 130      { "specs" "a sequence of sql specs" }
 131      { "?" "a boolean" } }
 132 { $description "Tests if any of the sql specs has the type " { $link +db-assigned-id+ } "." } ;
 133
 134 HELP: find-primary-key
 135 { $values
 136      { "specs" "a sequence of sql-specs" }
 137      { "seq" "a sequence of sql-specs" } }
 138 { $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." }
 139 { $notes "This is a low-level word." } ;
 140
 141 HELP: generator-bind
 142 { $description "" } ;
 143
 144 HELP: get-slot-named
 145 { $values
 146      { "name" "a slot name" } { "tuple" tuple }
 147      { "value" "the value stored in the slot" } }
 148 { $description "Returns the value stored in a tuple slot, where the tuple slot is a string." } ;
 149
 150 HELP: literal-bind
 151 { $description "" } ;
 152
 153 HELP: lookup-create-type
 154 { $values
 155      { "obj" object }
 156      { "string" string } }
 157 { $description "" } ;
 158
 159 HELP: lookup-modifier
 160 { $values
 161      { "obj" object }
 162      { "string" string } }
 163 { $description "" } ;
 164
 165 HELP: lookup-type
 166 { $values
 167      { "obj" object }
 168      { "string" string } }
 169 { $description "" } ;
 170
 171 HELP: low-level-binding
 172 { $description "" } ;
 173
 174 HELP: modifiers
 175 { $values
 176      { "spec" null }
 177      { "string" string } }
 178 { $description "" } ;
 179
 180 HELP: no-sql-type
 181 { $values
 182      { "type" "a sql type" } }
 183 { $description "Throws an error containing a sql type that is unsupported or the result of a typo." } ;
 184
 185 HELP: normalize-spec
 186 { $values
 187      { "spec" null } }
 188 { $description "" } ;
 189
 190 HELP: offset-of-slot
 191 { $values
 192      { "string" string } { "tuple" tuple }
 193      { "n" integer } }
 194 { $description "Returns the offset of a tuple slot accessed by name." } ;
 195
 196 HELP: persistent-table
 197 { $values
 198
 199      { "hash" hashtable } }
 200 { $description "" } ;
 201
 202 HELP: primary-key?
 203 { $values
 204      { "spec" null }
 205      { "?" "a boolean" } }
 206 { $description "" } ;
 207
 208 HELP: random-id-generator
 209 { $description "" } ;
 210
 211 HELP: relation?
 212 { $values
 213      { "spec" null }
 214      { "?" "a boolean" } }
 215 { $description "" } ;
 216
 217 HELP: remove-db-assigned-id
 218 { $values
 219      { "specs" null }
 220      { "obj" object } }
 221 { $description "" } ;
 222
 223 HELP: remove-id
 224 { $values
 225      { "specs" null }
 226      { "obj" object } }
 227 { $description "" } ;
 228
 229 HELP: remove-relations
 230 { $values
 231      { "specs" null }
 232      { "newcolumns" null } }
 233 { $description "" } ;
 234
 235 HELP: set-slot-named
 236 { $values
 237      { "value" null } { "name" null } { "obj" object } }
 238 { $description "" } ;
 239
 240 HELP: spec>tuple
 241 { $values
 242      { "class" class } { "spec" null }
 243      { "tuple" null } }
 244 { $description "" } ;
 245
 246 HELP: sql-spec
 247 { $description "" } ;
 248
 249 HELP: unknown-modifier
 250 { $values { "modifier" string } }
 251 { $description "Throws an error containing an unknown sql modifier." } ;
 252
 253 ARTICLE: "db.types" "Database types"
 254 "The " { $vocab-link "db.types" } " vocabulary maps Factor types to database types." $nl
 255 "Primary keys:"
 256 { $subsection +db-assigned-id+ }
 257 { $subsection +user-assigned-id+ }
 258 { $subsection +random-id+ }
 259 "Null and boolean types:"
 260 { $subsection NULL }
 261 { $subsection BOOLEAN }
 262 "Text types:"
 263 { $subsection VARCHAR }
 264 { $subsection TEXT }
 265 "Number types:"
 266 { $subsection INTEGER }
 267 { $subsection BIG-INTEGER }
 268 { $subsection SIGNED-BIG-INTEGER }
 269 { $subsection UNSIGNED-BIG-INTEGER }
 270 { $subsection DOUBLE }
 271 { $subsection REAL }
 272 "Calendar types:"
 273 { $subsection DATE }
 274 { $subsection DATETIME }
 275 { $subsection TIME }
 276 { $subsection TIMESTAMP }
 277 "Factor byte-arrays:"
 278 { $subsection BLOB }
 279 "Arbitrary Factor objects:"
 280 { $subsection FACTOR-BLOB }
 281 "Factor URLs:"
 282 { $subsection URL } ;
 283
 284 ABOUT: "db.types"