basis/db/tuples/tuples-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: classes help.markup help.syntax io.streams.string kernel
   4 quotations sequences strings multiline math ;
   5 IN: db.tuples
   6
   7 HELP: define-persistent
   8 { $values
   9      { "class" class } { "table" string } { "columns" "an array of slot specifiers" } }
  10 { $description "Defines a relation from a Factor " { $snippet "tuple class" } " to a SQL database table name. The format for the slot specifiers is as follows:"
  11 { $list
  12     { "a slot name from the " { $snippet "tuple class" } }
  13     { "the name of a database column that maps to the slot" }        { "a database type (see " { $link "db.types" } ")" }
  14 } } ;
  15
  16 HELP: create-table
  17 { $values
  18      { "class" class } }
  19 { $description "Creates a SQL table from a mapping defined by " { $link define-persistent } ". If the table already exists, the database will likely throw an error." } ;
  20
  21 HELP: ensure-table
  22 { $values
  23      { "class" class } }
  24 { $description "Creates a SQL table from a mapping defined by " { $link define-persistent } ". If the table already exists, the error is silently ignored." } ;
  25
  26 HELP: ensure-tables
  27 { $values
  28      { "classes" null } }
  29 { $description "Creates a SQL table from a mapping defined by " { $link define-persistent } ". If a table already exists, the error is silently ignored." } ;
  30
  31 HELP: recreate-table
  32 { $values
  33      { "class" class } }
  34 { $description "Drops an existing table and re-creates it from a mapping defined by " { $link define-persistent } ". If the table does not exist the error is silently ignored." }
  35 { $warning { $emphasis "THIS WORD WILL DELETE YOUR DATA." } $nl
  36 " Use " { $link ensure-table } " unless you want to delete the data in this table." } ;
  37
  38 { create-table ensure-table ensure-tables recreate-table } related-words
  39
  40 HELP: drop-table
  41 { $values
  42      { "class" class } }
  43 { $description "Drops an existing table which deletes all of the data. The database will probably throw an error if the table does not exist." }
  44 { $warning { $emphasis "THIS WORD WILL DELETE YOUR DATA." } } ;
  45
  46 HELP: insert-tuple
  47 { $values
  48      { "tuple" tuple } }
  49 { $description "Inserts a tuple into a database if a relation has been defined with " { $link define-persistent } ". If a mapping states that the database assigns a primary key to the tuple, this value will be set after this word runs." }
  50 { $notes "Objects should only be inserted into a database once per object. To store the object after the initial insert, call " { $link update-tuple } "." } ;
  51
  52 HELP: update-tuple
  53 { $values
  54      { "tuple" tuple } }
  55 { $description "Updates a tuple that has already been inserted into a database. The tuple must have a primary key that has been set by " { $link insert-tuple } " or that is user-defined." } ;
  56
  57 HELP: delete-tuples
  58 { $values
  59      { "tuple" tuple } }
  60 { $description "Uses the " { $snippet "tuple" } " as an exemplar object and deletes any objects that have the same slots set. If a slot is not " { $link f } ", then it is used to generate a SQL statement that deletes tuples." }
  61 { $warning "This word will delete your data." } ;
  62
  63 { insert-tuple update-tuple delete-tuples } related-words
  64
  65 HELP: select-tuple
  66 { $values
  67      { "tuple" tuple }
  68      { "tuple/f" "a tuple or f" } }
  69 { $description "A SQL query is constructed from the slots of the exemplar tuple that are not " { $link f } ". Returns a single tuple from the database if it matches the query constructed from the exemplar tuple." } ;
  70
  71 HELP: select-tuples
  72 { $values
  73      { "tuple" tuple }
  74      { "tuples" "an array of tuples" } }
  75 { $description "A SQL query is constructed from the slots of the exemplar tuple that are not " { $link f } ". Returns a multiple tuples from the database that match the query constructed from the exemplar tuple." } ;
  76
  77 HELP: count-tuples
  78 { $values
  79      { "tuple" tuple } { "groups" "an array of slots to group by" }
  80      { "n" integer } }
  81 { $description "" } ;
  82
  83 HELP: query
  84 { $values
  85      { "tuple" tuple } { "query" query }
  86      { "tuples" "a sequence of tuples" } }
  87 { $description "Allows for queries with group by, order by, limit, and offset clauses.  " } ;
  88
  89 { select-tuple select-tuples count-tuples query } related-words
  90
  91 ARTICLE: "db-tuples" "High-level tuple/database integration"
  92 "Start with a tutorial:"
  93 { $subsection "db-tuples-tutorial" }
  94 "Useful words:"
  95 { $subsection "db-tuples-words" }
  96
  97 ;
  98
  99 ARTICLE: "db-tuples-words" "High-level tuple/database words"
 100 "Making tuples work with a database:"
 101 { $subsection define-persistent }
 102 "Creating tables:"
 103 { $subsection create-table }
 104 { $subsection ensure-table }
 105 { $subsection ensure-tables }
 106 { $subsection recreate-table }
 107 "Dropping tables:"
 108 { $subsection drop-table }
 109 "Inserting a tuple:"
 110 { $subsection insert-tuple }
 111 "Updating a tuple:"
 112 { $subsection update-tuple }
 113 "Deleting tuples:"
 114 { $subsection delete-tuples }
 115 "Querying tuples:"
 116 { $subsection select-tuple }
 117 { $subsection select-tuples }
 118 { $subsection count-tuples }
 119 "Advanced querying of tuples:"
 120 { $subsection query } ;
 121
 122
 123 ARTICLE: "db-tuples-protocol" "High-level tuple/database protocol"
 124 ;
 125
 126 ARTICLE: "db-tuples-tutorial" "Tuple database tutorial"
 127 "Let's make a tuple and store it in a database. To follow along, click on each code example and run it in the listener.  If you forget to run an example, just start at the top and run them all again in order." $nl
 128 "We're going to store books in this tutorial."
 129 { $code "TUPLE: book id title author date-published edition cover-price condition ;" }
 130 "The title, author, and publisher should be strings; the date-published a timestamp; the edition an integer; the cover-price a float. These are the Factor types for which we will need to look up the corresponding " { $link "db.types" } ". " $nl
 131 "To actually bind the tuple slots to the database types, we'll use " { $link define-persistent } "."
 132 { $code
 133 <" USING: db.tuples db.types ;
 134 book "BOOK"
 135 {
 136     { "id" "ID" +db-assigned-id+ }
 137     { "title" "TITLE" VARCHAR }
 138     { "author" "AUTHOR" VARCHAR }
 139     { "date-published" "DATE_PUBLISHED" TIMESTAMP }
 140     { "edition" "EDITION" INTEGER }
 141     { "cover-price" "COVER_PRICE" DOUBLE }
 142     { "condition" "CONDITION" VARCHAR }
 143 } define-persistent "> }
 144 "That's all we'll have to do with the database for this tutorial. Now let's make a book."
 145 { $code <" USING: calendar namespaces ;
 146 T{ book
 147     { title "Factor for Sheeple" }
 148     { author "Mister Stacky Pants" }
 149     { date-published T{ timestamp { year 2009 } { month 3 } { day 3 } } }
 150     { edition 1 }
 151     { cover-price 13.37 }
 152 } book set
 153 "> }
 154 "Now we've created a book. Let's save it to the database."
 155 { $code <" USING: db db.sqlite fry io.files ;
 156 : with-book-tutorial ( quot -- )
 157      '[ "book-tutorial.db" temp-file sqlite-db _ with-db ] call ;
 158
 159 [
 160     book recreate-table
 161     book get insert-tuple
 162 ] with-book-tutorial
 163 "> }
 164 "Is it really there?"
 165 { $code <" [
 166     T{ book { title "Factor for Sheeple" } } select-tuples .
 167 ] with-book-tutorial "> }
 168 "Oops, we spilled some orange juice on the book cover."
 169 { $code <" book get "Small orange juice stain on cover" >>condition "> }
 170 "Now let's save the modified book."
 171 { $code <" [
 172     book get update-tuple
 173 ] with-book-tutorial "> }
 174 "And select it again.  You can query the database by any field -- just set it in the exemplar tuple you pass to " { $link select-tuples } "."
 175 { $code <" [
 176     T{ book { title "Factor for Sheeple" } } select-tuples
 177 ] with-book-tutorial "> }
 178 "Let's drop the table because we're done."
 179 { $code <" [
 180     book drop-table
 181 ] with-book-tutorial "> }
 182 "To summarize, the steps for using Factor's tuple database are:"
 183 { $list
 184     "Make a new tuple to represent your data"
 185     { "Map the Factor types to the database types with " { $link define-persistent } }
 186     { "Make a " { $link "db-custom-database-combinators" } " to open your database and run a " { $snippet "quotation" } }
 187     { "Create a table with " { $link create-table } ", " { $link ensure-table } ", or " { $link recreate-table } }
 188     { "Start making and storing objects with " { $link insert-tuple } ", " { $link update-tuple } ", " { $link delete-tuples } ", and " { $link select-tuples } }
 189 } ;
 190
 191 ABOUT: "db-tuples"