From a7f116783cf3b016d0ed2d99b5316f6f7502c23e Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Mon, 8 Sep 2008 18:15:37 -0500 Subject: [PATCH 1/2] fix typos --- basis/db/db-docs.factor | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/basis/db/db-docs.factor b/basis/db/db-docs.factor index 9c3a643ef0..baf28617e8 100644 --- a/basis/db/db-docs.factor +++ b/basis/db/db-docs.factor @@ -52,11 +52,13 @@ HELP: construct-statement { $description "Makes a new statement object from the given parameters." } ; HELP: -{ $values { "string" string } { "in" sequence } { "out" sequence } } +{ $values { "string" string } { "in" sequence } { "out" sequence } + { "statement" statement } } { $description "Makes a new simple statement object from the given parameters." } ; HELP: -{ $values { "string" string } { "in" sequence } { "out" sequence } } +{ $values { "string" string } { "in" sequence } { "out" sequence } + { "statement" statement } } { $description "Makes a new prepared statement object from the given parameters." } ; HELP: prepare-statement @@ -76,7 +78,9 @@ HELP: bind-tuple { $description "" } ; HELP: query-results -{ $values { "query" object } { "statement" statement } } +{ $values { "query" object } + { "result-set" result-set } +} { $description "" } ; HELP: #rows @@ -88,11 +92,14 @@ HELP: #columns { $description "Returns the number of columns in a result set." } ; HELP: row-column -{ $values { "result-set" result-set } { "column" integer } } +{ $values { "result-set" result-set } { "column" integer } + { "obj" object } +} { $description "" } ; HELP: row-column-typed -{ $values { "result-set" result-set } { "column" integer } } +{ $values { "result-set" result-set } { "column" integer } + { "sql" "sql" } } { $description "" } ; HELP: advance-row @@ -100,7 +107,7 @@ HELP: advance-row ; HELP: more-rows? -{ $values { "result-set" result-set } { "column" integer } } +{ $values { "result-set" result-set } { "?" "a boolean" } } ; HELP: execute-statement* From 13259398835ebae29d86ea291a183608883a8fb7 Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Mon, 8 Sep 2008 19:24:44 -0500 Subject: [PATCH 2/2] more docs --- basis/db/db-docs.factor | 3 +- basis/db/tuples/tuples-docs.factor | 6 ++-- basis/db/tuples/tuples.factor | 8 ++--- basis/db/types/types-docs.factor | 49 +++++++++++++++++++++++------- 4 files changed, 47 insertions(+), 19 deletions(-) diff --git a/basis/db/db-docs.factor b/basis/db/db-docs.factor index baf28617e8..3e29bcb4d6 100644 --- a/basis/db/db-docs.factor +++ b/basis/db/db-docs.factor @@ -150,8 +150,9 @@ ARTICLE: "db-custom-database-combinators" "Custom database combinators" "Make a " { $snippet "with-" } " word to open, close, and use your database." { $code <" +USING: db.sqlite db io.files ; : with-my-database ( quot -- ) - { "my-database.db" temp-file } + { "my-database.db" temp-file } sqlite-db rot with-db ; "> } diff --git a/basis/db/tuples/tuples-docs.factor b/basis/db/tuples/tuples-docs.factor index 42e9cdb928..ed605da25f 100644 --- a/basis/db/tuples/tuples-docs.factor +++ b/basis/db/tuples/tuples-docs.factor @@ -82,9 +82,9 @@ HELP: count-tuples HELP: query { $values - { "tuple" null } { "query" null } - { "tuples" null } } -{ $description "" } ; + { "tuple" tuple } { "query" query } + { "tuples" "a sequence of tuples" } } +{ $description "Allows for queries with group by, order by, limit, and offset clauses. " } ; { select-tuple select-tuples count-tuples query } related-words diff --git a/basis/db/tuples/tuples.factor b/basis/db/tuples/tuples.factor index 9c8f595e68..94fa1a66e8 100755 --- a/basis/db/tuples/tuples.factor +++ b/basis/db/tuples/tuples.factor @@ -50,10 +50,10 @@ HOOK: insert-tuple* db ( tuple statement -- ) GENERIC: eval-generator ( singleton -- obj ) -: resulting-tuple ( class row out-params -- tuple ) +: resulting-tuple ( exemplar-tuple row out-params -- tuple ) rot class new [ [ - >r slot-name>> r> set-slot-named + [ slot-name>> ] dip set-slot-named ] curry 2each ] keep ; @@ -65,7 +65,7 @@ GENERIC: eval-generator ( singleton -- obj ) : query-modify-tuple ( tuple statement -- ) [ query-results [ sql-row-typed ] with-disposal ] keep out-params>> rot [ - >r slot-name>> r> set-slot-named + [ slot-name>> ] dip set-slot-named ] curry 2each ; : with-disposals ( seq quot -- ) @@ -121,7 +121,7 @@ GENERIC: eval-generator ( singleton -- obj ) [ [ bind-tuple ] [ query-tuples ] 2bi ] with-disposal ; : query ( tuple query -- tuples ) - >r dup dup class r> do-select ; + [ dup dup class ] dip do-select ; : select-tuples ( tuple -- tuples ) dup dup class do-select ; diff --git a/basis/db/types/types-docs.factor b/basis/db/types/types-docs.factor index 687ce7b991..d60878555a 100644 --- a/basis/db/types/types-docs.factor +++ b/basis/db/types/types-docs.factor @@ -13,7 +13,7 @@ HELP: +autoincrement+ { $description "" } ; HELP: +db-assigned-id+ -{ $description "" } ; +{ $description "The database assigns a primary key to the object. The primary key is most likely a big integer, but is database-dependent." } ; HELP: +default+ { $description "" } ; @@ -34,7 +34,7 @@ HELP: +primary-key+ { $description "" } ; HELP: +random-id+ -{ $description "" } ; +{ $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." } ; HELP: +serial+ { $description "" } ; @@ -43,7 +43,7 @@ HELP: +unique+ { $description "" } ; HELP: +user-assigned-id+ -{ $description "" } ; +{ $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+ } "." } ; HELP: { $description "" } ; @@ -55,22 +55,22 @@ HELP: { $description "" } ; HELP: BIG-INTEGER -{ $description "" } ; +{ $description "A 64-bit integer." } ; HELP: BLOB -{ $description "" } ; +{ $description "A serialized Factor object. The database library automatically serializes the object for a SQL insert or update and deserializes it on a tuple query." } ; HELP: BOOLEAN -{ $description "" } ; +{ $description "Either true or false." } ; HELP: DATE -{ $description "" } ; +{ $description "A date without a time component." } ; HELP: DATETIME -{ $description "" } ; +{ $description "A date and a time." } ; HELP: DOUBLE -{ $description "" } ; +{ $description "Corresponds to Factor's 64bit floating-point numbers." } ; HELP: FACTOR-BLOB { $description "" } ; @@ -85,7 +85,7 @@ HELP: REAL { $description "" } ; HELP: SIGNED-BIG-INTEGER -{ $description "" } ; +{ $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 } "." } ; HELP: TEXT { $description "" } ; @@ -297,7 +297,34 @@ HELP: unknown-modifier { $description "" } ; ARTICLE: "db.types" "Database types" -"The " { $vocab-link "db.types" } " vocabulary maps Factor types to database types." +"The " { $vocab-link "db.types" } " vocabulary maps Factor types to database types." $nl +"Primary keys:" +{ $subsection +db-assigned-id+ } +{ $subsection +user-assigned-id+ } +{ $subsection +random-id+ } +"Null and boolean types:" +{ $subsection NULL } +{ $subsection BOOLEAN } +"Text types:" +{ $subsection VARCHAR } +{ $subsection TEXT } +"Number types:" +{ $subsection INTEGER } +{ $subsection BIG-INTEGER } +{ $subsection SIGNED-BIG-INTEGER } +{ $subsection UNSIGNED-BIG-INTEGER } +{ $subsection DOUBLE } +{ $subsection REAL } +"Calendar types:" +{ $subsection DATE } +{ $subsection DATETIME } +{ $subsection TIME } +{ $subsection TIMESTAMP } +"Arbitrary Factor objects:" +{ $subsection BLOB } +{ $subsection FACTOR-BLOB } +"Factor URLs:" +{ $subsection URL } ; ABOUT: "db.types"