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: +db-assigned-id+
   8 { $description "The database assigns a primary key to the object. The primary key is most likely a big integer, but is database-dependent." } ;
   9
  10 HELP: +default+
  11 { $description "Allows a default value for a column to be provided." } ;
  12
  13 HELP: +not-null+
  14 { $description "Ensures that a column is not null." } ;
  15
  16 HELP: +null+
  17 { $description "Allows a column to be null." } ;
  18
  19 HELP: +primary-key+
  20 { $description "Makes a column a primary key. Only one column may be a primary key." } ;
  21
  22 HELP: +random-id+
  23 { $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." } ;
  24
  25 HELP: +user-assigned-id+
  26 { $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+ } "." } ;
  27
  28 HELP: <generator-bind>
  29 { $values { "slot-name" object } { "key" object } { "generator-singleton" object } { "type" object } { "generator-bind" generator-bind } }
  30 { $description "An internal constructor for creating objects containing parameters used for binding generated values to a tuple query." } ;
  31
  32 HELP: <literal-bind>
  33 { $values { "key" object } { "type" object } { "value" object } { "literal-bind" literal-bind } }
  34 { $description "An internal constructor for creating objects containing parameters used for binding literal values to a tuple query." } ;
  35
  36 HELP: BIG-INTEGER
  37 { $description "A 64-bit integer. Whether this number is signed or unsigned depends on the database backend." } ;
  38
  39 HELP: BLOB
  40 { $description "A byte array." } ;
  41
  42 HELP: BOOLEAN
  43 { $description "Either true or false." } ;
  44
  45 HELP: DATE
  46 { $description "A date without a time component." } ;
  47
  48 HELP: DATETIME
  49 { $description "A date and a time." } ;
  50
  51 HELP: DOUBLE
  52 { $description "Corresponds to Factor's 64-bit floating-point numbers." } ;
  53
  54 HELP: FACTOR-BLOB
  55 { $description "A serialized Factor object." } ;
  56
  57 HELP: INTEGER
  58 { $description "A small integer, at least 32 bits in length. Whether this number is signed or unsigned depends on the database backend." } ;
  59
  60 HELP: NULL
  61 { $description "The SQL null type." } ;
  62
  63 HELP: REAL
  64 { $description "A real number of unlimited precision. May not be supported on all databases." } ;
  65
  66 HELP: SIGNED-BIG-INTEGER
  67 { $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 } "." } ;
  68
  69 HELP: TEXT
  70 { $description "Stores a string that is longer than a " { $link VARCHAR } ". SQLite uses this type for strings; it does not handle " { $link VARCHAR } " strings." } ;
  71
  72 HELP: TIME
  73 { $description "A timestamp without a date component." } ;
  74
  75 HELP: TIMESTAMP
  76 { $description "A Factor timestamp." } ;
  77
  78 HELP: UNSIGNED-BIG-INTEGER
  79 { $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 } "." } ;
  80
  81 { INTEGER SIGNED-BIG-INTEGER UNSIGNED-BIG-INTEGER } related-words
  82
  83 HELP: URL
  84 { $description "A Factor " { $link "urls" } " object." } ;
  85
  86 HELP: VARCHAR
  87 { $description "The SQL varchar type. This type can take an integer as an argument." }
  88 { $examples { $unchecked-example "{ VARCHAR 256 }" "" } } ;
  89
  90 HELP: user-assigned-id-spec?
  91 { $values
  92      { "specs" "a sequence of SQL specs" }
  93      { "?" "a boolean" } }
  94 { $description "Tests if any of the SQL specs has the type " { $link +user-assigned-id+ } "." } ;
  95
  96 HELP: bind#
  97 { $values
  98      { "spec" "a SQL spec" } { "obj" object } }
  99 { $description "A generic word that lets a database construct a literal binding." } ;
 100
 101 HELP: bind%
 102 { $values
 103      { "spec" "a SQL spec" } }
 104 { $description "A generic word that lets a database output a binding." } ;
 105
 106 HELP: db-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 +db-assigned-id+ } "." } ;
 111
 112 HELP: find-primary-key
 113 { $values
 114      { "specs" "a sequence of SQL specs" }
 115      { "seq" "a sequence of SQL specs" } }
 116 { $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." }
 117 { $notes "This is a low-level word." } ;
 118
 119 HELP: no-sql-type
 120 { $values
 121      { "type" "a SQL type" } }
 122 { $description "Throws an error containing a SQL type that is unsupported or the result of a typo." } ;
 123
 124 HELP: normalize-spec
 125 { $values
 126      { "spec" "a SQL spec" } }
 127 { $description "Normalizes a SQL spec." } ;
 128
 129 HELP: primary-key?
 130 { $values
 131      { "spec" "a SQL spec" }
 132      { "?" "a boolean" } }
 133 { $description "Returns true if a SQL spec is a primary key." } ;
 134
 135 HELP: relation?
 136 { $values
 137      { "spec" "a SQL spec" }
 138      { "?" "a boolean" } }
 139 { $description "Returns true if a SQL spec is a relation." } ;
 140
 141 HELP: unknown-modifier
 142 { $values { "modifier" string } }
 143 { $description "Throws an error containing an unknown SQL modifier." } ;
 144
 145 ARTICLE: "db.types" "Database types"
 146 "The " { $vocab-link "db.types" } " vocabulary maps Factor types to database types." $nl
 147 "Primary keys:"
 148 { $subsections
 149     +db-assigned-id+
 150     +user-assigned-id+
 151     +random-id+
 152 }
 153 "Null and boolean types:"
 154 { $subsections
 155     NULL
 156     BOOLEAN
 157 }
 158 "Text types:"
 159 { $subsections
 160     VARCHAR
 161     TEXT
 162 }
 163 "Number types:"
 164 { $subsections
 165     INTEGER
 166     BIG-INTEGER
 167     SIGNED-BIG-INTEGER
 168     UNSIGNED-BIG-INTEGER
 169     DOUBLE
 170     REAL
 171 }
 172 "Calendar types:"
 173 { $subsections
 174     DATE
 175     DATETIME
 176     TIME
 177     TIMESTAMP
 178 }
 179 "Factor byte-arrays:"
 180 { $subsections BLOB }
 181 "Arbitrary Factor objects:"
 182 { $subsections FACTOR-BLOB }
 183 "Factor URLs:"
 184 { $subsections URL } ;
 185
 186 ABOUT: "db.types"