From 2e5273df527426a56282133027035054b6470460 Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Wed, 24 Sep 2008 22:22:36 -0500 Subject: [PATCH 1/5] xmodes now can't contain whitespace. [ factor { 1 2 3 }] prints literally instead of getting syntax-highlighted --- basis/farkup/farkup-tests.factor | 3 +++ basis/farkup/farkup.factor | 3 ++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/basis/farkup/farkup-tests.factor b/basis/farkup/farkup-tests.factor index 9120ec97f9..f136ec91d4 100644 --- a/basis/farkup/farkup-tests.factor +++ b/basis/farkup/farkup-tests.factor @@ -141,3 +141,6 @@ link-no-follow? off [ "

Factor-rific!

" ] [ "[[Factor]]-rific!" convert-farkup ] unit-test + +[ "

[ factor { 1 2 3 }]

" ] +[ "[ factor { 1 2 3 }]" convert-farkup ] unit-test diff --git a/basis/farkup/farkup.factor b/basis/farkup/farkup.factor index ec49655d5a..37233447bc 100644 --- a/basis/farkup/farkup.factor +++ b/basis/farkup/farkup.factor @@ -38,6 +38,7 @@ TUPLE: line ; EBNF: parse-farkup nl = ("\r\n" | "\r" | "\n") => [[ drop "\n" ]] +whitespace = " " | "\t" | nl heading1 = "=" (!("=" | nl).)+ "=" => [[ second >string heading1 boa ]] @@ -133,7 +134,7 @@ line = '___' => [[ drop line new ]] -named-code = '[' (!('{' | nl | '[').)+ '{' (!("}]").)+ "}]" +named-code = '[' (!('{' | whitespace | '[').)+ '{' (!("}]").)+ "}]" => [[ [ second >string ] [ fourth >string ] bi code boa ]] simple-code From 5be907e85724a18aeebf046cdcface0dce5130d3 Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Wed, 24 Sep 2008 22:24:34 -0500 Subject: [PATCH 2/5] fix potential infinite loop, minor docs updates --- basis/db/db-docs.factor | 2 +- basis/db/db.factor | 7 +++- basis/db/tuples/tuples-tests.factor | 1 + basis/db/types/types-docs.factor | 58 +++++++++++------------------ basis/db/types/types.factor | 4 +- 5 files changed, 30 insertions(+), 42 deletions(-) diff --git a/basis/db/db-docs.factor b/basis/db/db-docs.factor index 244555b93e..d726f48efe 100644 --- a/basis/db/db-docs.factor +++ b/basis/db/db-docs.factor @@ -116,7 +116,7 @@ HELP: execute-statement* HELP: execute-statement { $values { "statement" statement } } -{ $description } ; +{ $description "" } ; ARTICLE: "db" "Database library" { $subsection "db-custom-database-combinators" } diff --git a/basis/db/db.factor b/basis/db/db.factor index eac22a2999..87bf21d261 100755 --- a/basis/db/db.factor +++ b/basis/db/db.factor @@ -80,11 +80,14 @@ GENERIC: execute-statement* ( statement type -- ) M: object execute-statement* ( statement type -- ) drop query-results dispose ; +: execute-one-statement ( statement -- ) + dup type>> execute-statement* ; + : execute-statement ( statement -- ) dup sequence? [ - [ execute-statement ] each + [ execute-one-statement ] each ] [ - dup type>> execute-statement* + execute-one-statement ] if ; : bind-statement ( obj statement -- ) diff --git a/basis/db/tuples/tuples-tests.factor b/basis/db/tuples/tuples-tests.factor index e8e7fdacf3..4b1e49c76e 100755 --- a/basis/db/tuples/tuples-tests.factor +++ b/basis/db/tuples/tuples-tests.factor @@ -518,6 +518,7 @@ string-encoding-test "STRING_ENCODING_TEST" { ! [ ] [ T{ exam f f "Kenny" 60 } insert-tuple ] unit-test ! [ ] [ T{ exam f f "Cartman" 41 } insert-tuple ] unit-test [ ] [ 10 [ random-exam insert-tuple ] times ] unit-test + [ 5 ] [ T{ exam { score T{ interval { from { 0 t } } { to { 100 t } } } } } >>tuple 5 >>limit select-tuples length ] unit-test ! [ ] [ T{ exam { name "Kenny" } } >query ] unit-test ! [ ] [ query ] unit-test ; diff --git a/basis/db/types/types-docs.factor b/basis/db/types/types-docs.factor index 9300a68f2e..a7e230079c 100644 --- a/basis/db/types/types-docs.factor +++ b/basis/db/types/types-docs.factor @@ -1,14 +1,8 @@ ! Copyright (C) 2008 Doug Coleman. ! See http://factorcode.org/license.txt for BSD license. -USING: classes hashtables help.markup help.syntax io.streams.string kernel sequences strings ; +USING: classes hashtables help.markup help.syntax io.streams.string kernel sequences strings db.tuples math ; IN: db.types -HELP: (lookup-type) -{ $values - { "obj" object } - { "string" string } } -{ $description "" } ; - HELP: +autoincrement+ { $description "" } ; @@ -55,7 +49,7 @@ HELP: { $description "" } ; HELP: BIG-INTEGER -{ $description "A 64-bit integer." } ; +{ $description "A 64-bit integer. Whether this number is signed or unsigned depends on the database backend." } ; HELP: BLOB { $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." } ; @@ -73,13 +67,13 @@ HELP: DOUBLE { $description "Corresponds to Factor's 64bit floating-point numbers." } ; HELP: FACTOR-BLOB -{ $description "" } ; +{ $description "A serialized Factor object." } ; HELP: INTEGER -{ $description "" } ; +{ $description "A small integer, at least 32 bits in length. Whether this number is signed or unsigned depends on the database backend." } ; HELP: NULL -{ $description "" } ; +{ $description "The SQL null type." } ; HELP: REAL { $description "" } ; @@ -94,16 +88,18 @@ HELP: TIME { $description "" } ; HELP: TIMESTAMP -{ $description "" } ; +{ $description "A Factor timestamp." } ; HELP: UNSIGNED-BIG-INTEGER -{ $description "" } ; +{ $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 } "." } ; + +{ INTEGER SIGNED-BIG-INTEGER UNSIGNED-BIG-INTEGER } related-words HELP: URL -{ $description "" } ; +{ $description "A Factor " { $link "urls" } " object." } ; HELP: VARCHAR -{ $description "" } ; +{ $description "The SQL varchar type. This type can take an integer as an argument." } ; HELP: assigned-id-spec? { $values @@ -135,18 +131,19 @@ HELP: db-assigned-id-spec? HELP: find-primary-key { $values - { "specs" null } + { "specs" "an array of sql-specs" } { "obj" object } } -{ $description "" } ; +{ $description "Returns the row from the sql-specs array that was defined by " { $link define-persistent } "." } +{ $notes "This is a low-level word." } ; HELP: generator-bind { $description "" } ; HELP: get-slot-named { $values - { "name" null } { "obj" object } - { "value" null } } -{ $description "" } ; + { "name" "a slot name" } { "tuple" tuple } + { "value" "the value stored in the slot" } } +{ $description "Returns the value stored in a tuple slot, where the tuple slot is a string." } ; HELP: join-space { $values @@ -192,23 +189,11 @@ HELP: normalize-spec { "spec" null } } { $description "" } ; -HELP: number>string* -{ $values - { "n/string" null } - { "string" string } } -{ $description "" } ; - HELP: offset-of-slot { $values - { "string" string } { "obj" object } - { "n" null } } -{ $description "" } ; - -HELP: paren -{ $values - { "string" string } - { "new-string" null } } -{ $description "" } ; + { "string" string } { "tuple" tuple } + { "n" integer } } +{ $description "Returns the offset of a tuple slot accessed by name." } ; HELP: persistent-table { $values @@ -294,7 +279,6 @@ ARTICLE: "db.types" "Database types" { $subsection BLOB } { $subsection FACTOR-BLOB } "Factor URLs:" -{ $subsection URL } -; +{ $subsection URL } ; ABOUT: "db.types" diff --git a/basis/db/types/types.factor b/basis/db/types/types.factor index 476d82a1e2..24876336c7 100755 --- a/basis/db/types/types.factor +++ b/basis/db/types/types.factor @@ -126,11 +126,11 @@ ERROR: no-sql-type ; HOOK: bind% db ( spec -- ) HOOK: bind# db ( spec obj -- ) -: offset-of-slot ( string obj -- n ) +: offset-of-slot ( string tuple -- n ) class superclasses [ "slots" word-prop ] map concat slot-named offset>> ; -: get-slot-named ( name obj -- value ) +: get-slot-named ( name tuple -- value ) tuck offset-of-slot slot ; : set-slot-named ( value name obj -- ) From 37130f911cb26f4513ee876b47bc6162d247458f Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Wed, 24 Sep 2008 22:39:38 -0500 Subject: [PATCH 3/5] allow horizontal lines in paragraphs if they start at the beginning of a line --- basis/farkup/farkup-tests.factor | 6 ++++++ basis/farkup/farkup.factor | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/basis/farkup/farkup-tests.factor b/basis/farkup/farkup-tests.factor index f136ec91d4..693c559ac5 100644 --- a/basis/farkup/farkup-tests.factor +++ b/basis/farkup/farkup-tests.factor @@ -144,3 +144,9 @@ link-no-follow? off [ "

[ factor { 1 2 3 }]

" ] [ "[ factor { 1 2 3 }]" convert-farkup ] unit-test + +[ "

paragraph\n

" ] +[ "paragraph\n___" convert-farkup ] unit-test + +[ "

paragraph\n a ___ b

" ] +[ "paragraph\n a ___ b" convert-farkup ] unit-test diff --git a/basis/farkup/farkup.factor b/basis/farkup/farkup.factor index 37233447bc..7844cf8f41 100644 --- a/basis/farkup/farkup.factor +++ b/basis/farkup/farkup.factor @@ -108,7 +108,7 @@ table = ((table-row nl => [[ first ]] )+ table-row? | table-row) text = (!(nl | code | heading | inline-delimiter | table ).)+ => [[ >string ]] -paragraph-item = (table | nl list | code | text | inline-tag | inline-delimiter)+ +paragraph-item = (table | nl list | nl line | code | text | inline-tag | inline-delimiter)+ paragraph = ((paragraph-item nl => [[ first ]])+ nl+ => [[ first ]] | (paragraph-item nl)+ paragraph-item? | paragraph-item) From e56d49334e031689e09d4a9361e7f5cf03403ad8 Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Wed, 24 Sep 2008 22:40:05 -0500 Subject: [PATCH 4/5] add a horizontal line demo --- extra/webapps/wiki/initial-content/Farkup.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/extra/webapps/wiki/initial-content/Farkup.txt b/extra/webapps/wiki/initial-content/Farkup.txt index 65f9defc5b..33b3a6c51a 100644 --- a/extra/webapps/wiki/initial-content/Farkup.txt +++ b/extra/webapps/wiki/initial-content/Farkup.txt @@ -28,6 +28,10 @@ Ordered lists: # with three # numbered items +Horizontal lines: + +___ + Tables: |a table|with|four|columns| From 2057e643e733d810cfe99b57b43e6f06c2d3a671 Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Thu, 25 Sep 2008 00:05:41 -0500 Subject: [PATCH 5/5] more docs, fix circular vocabs --- basis/db/db-docs.factor | 151 +++++++++++++++++++++++++++-- basis/db/tuples/tuples-docs.factor | 2 +- basis/db/tuples/tuples.factor | 2 +- basis/db/types/types-docs.factor | 5 +- 4 files changed, 148 insertions(+), 12 deletions(-) diff --git a/basis/db/db-docs.factor b/basis/db/db-docs.factor index d726f48efe..74b72b8789 100644 --- a/basis/db/db-docs.factor +++ b/basis/db/db-docs.factor @@ -1,7 +1,7 @@ ! Copyright (C) 2008 Doug Coleman. ! See http://factorcode.org/license.txt for BSD license. USING: classes kernel help.markup help.syntax sequences -alien assocs strings math multiline ; +alien assocs strings math multiline quotations ; IN: db HELP: db @@ -45,7 +45,22 @@ HELP: prepared-statement { $description } ; HELP: result-set -{ $description } ; +{ $description "An object encapsulating a raw SQL result object. There are two ways in which a result set can be accessed, but they are specific to the database backend in use." + { $subsection "db-random-access-result-set" } + { $subsection "db-sequential-result-set" } +} ; + +HELP: init-result-set +{ $values + { "result-set" result-set } } +{ $description "" } ; + +HELP: new-result-set +{ $values + { "query" "a query" } { "handle" alien } { "class" class } + { "result-set" result-set } } +{ $description "Creates a new " { $link result-set } " object of type " { $snippet "class" } "." } ; + HELP: new-statement { $values { "sql" string } { "in" sequence } { "out" sequence } { "class" class } { "statement" statement } } @@ -81,7 +96,7 @@ HELP: query-results { $values { "query" object } { "result-set" result-set } } -{ $description "" } ; +{ $description "Returns a " { $link result-set } " object representing the reults of a SQL query." } ; HELP: #rows { $values { "result-set" result-set } { "n" integer } } @@ -95,32 +110,119 @@ HELP: row-column { $values { "result-set" result-set } { "column" integer } { "obj" object } } -{ $description "" } ; +{ $description "Returns the value indexed by " { $snippet "column" } " in the current row of a " { $link result-set } "." } ; HELP: row-column-typed { $values { "result-set" result-set } { "column" integer } { "sql" "sql" } } -{ $description "" } ; +{ $description "Returns the value indexed by " { $snippet "column" } " in the current row of a " { $link result-set } " and converts the result based on a type stored in the " { $link result-set } "'s " { $slot "out-params" } "." } ; HELP: advance-row { $values { "result-set" result-set } } -; +{ $description "Advanced the pointer to an underlying SQL result set stored in a " { $link result-set } " object." } ; HELP: more-rows? { $values { "result-set" result-set } { "?" "a boolean" } } -; +{ $description "Returns true if the " { $link result-set } " has more rows to traverse." } ; HELP: execute-statement* { $values { "statement" statement } { "type" object } } { $description } ; +HELP: execute-one-statement +{ $values + { "statement" null } } +{ $description "" } ; + HELP: execute-statement { $values { "statement" statement } } { $description "" } ; + + + + + +HELP: begin-transaction +{ $description "Begins a new transaction. User code should make use of the " { $link with-transaction } " combinator." } ; + +HELP: bind-statement +{ $values + { "obj" object } { "statement" null } } +{ $description "" } ; + +HELP: commit-transaction +{ $description "Commits a transaction. User code should make use of the " { $link with-transaction } " combinator." } ; + +HELP: default-query +{ $values + { "query" null } + { "result-set" null } } +{ $description "" } ; + +HELP: in-transaction +{ $description "A variable that is set true when a transaction is in progress." } ; + +HELP: in-transaction? +{ $values + { "?" "a boolean" } } +{ $description "Returns true if there is currently a transaction in progress in this scope." } ; + +HELP: query-each +{ $values + { "statement" null } { "quot" quotation } } +{ $description "" } ; + +HELP: query-map +{ $values + { "statement" null } { "quot" quotation } + { "seq" sequence } } +{ $description "" } ; + +HELP: rollback-transaction +{ $description "Rolls back a transaction; no data is committed to the database. User code should make use of the " { $link with-transaction } " combinator." } ; + +HELP: sql-command +{ $values + { "sql" string } } +{ $description "Executes a SQL string using the databse in the " { $link db } " symbol." } ; + +HELP: sql-query +{ $values + { "sql" string } + { "rows" "an array of arrays of strings" } } +{ $description "Runs a SQL query of raw text in the database in the " { $link db } " symbol. Each row is returned as an array of strings; no type-conversions are done on the resulting data." } ; + +{ sql-command sql-query } related-words + +HELP: sql-row +{ $values + { "result-set" result-set } + { "seq" sequence } } +{ $description "Returns the current row in a " { $link result-set } " as an array of strings." } ; + +HELP: sql-row-typed +{ $values + { "result-set" result-set } + { "seq" sequence } } +{ $description "Returns the current row in a " { $link result-set } " as an array of typed Factor objects." } ; + +{ sql-row sql-row-typed } related-words + +HELP: with-db +{ $values + { "seq" sequence } { "class" class } { "quot" quotation } } +{ $description "Calls the quotation with a database bound to the " { $link db } " symbol. The database called is based on the " { $snippet "class" } " with the " } ; + +HELP: with-transaction +{ $values + { "quot" quotation } } +{ $description "" } ; + ARTICLE: "db" "Database library" { $subsection "db-custom-database-combinators" } { $subsection "db-protocol" } +{ $subsection "db-result-sets" } { $subsection "db-lowlevel-tutorial" } "Higher-level database:" { $vocab-subsection "Database types" "db.types" } @@ -135,6 +237,40 @@ ARTICLE: "db" "Database library" { $subsection "db-porting-the-library" } ; +ARTICLE: "db-random-access-result-set" "Random access result sets" +"Random-access result sets do not have to be traversed in order. For instance, PostgreSQL's result set object can be accessed as a matrix with i,j coordinates." +$nl +"Databases which work in this way must provide methods for the following traversal words:" +{ $subsection #rows } +{ $subsection #columns } +{ $subsection row-column } +{ $subsection row-column-typed } ; + +ARTICLE: "db-sequential-result-set" "Sequential result sets" +"Sequential result sets can be iterated one element after the next. SQLite's result sets offer this method of traversal." +$nl +"Databases which work in this way must provide methods for the following traversal words:" +{ $subsection more-rows? } +{ $subsection advance-row } +{ $subsection row-column } +{ $subsection row-column-typed } ; + +ARTICLE: "db-result-sets" "Result sets" +"Result sets are the encapsulated, database-specific results from a SQL query." +$nl +"Two possible protocols for iterating over result sets exist:" +{ $subsection "db-random-access-result-set" } +{ $subsection "db-sequential-result-set" } +"Query the number of rows or columns:" +{ $subsection #rows } +{ $subsection #columns } +"Traversing a result set:" +{ $subsection advance-row } +{ $subsection more-rows? } +"Pulling out a single row of results:" +{ $subsection row-column } +{ $subsection row-column-typed } ; + ARTICLE: "db-protocol" "Low-level database protocol" "The high-level protocol (see " { $vocab-link "db.tuples" } ") uses this low-level protocol for executing statements and queries." ; @@ -157,7 +293,6 @@ USING: db.sqlite db io.files ; { "my-database.db" temp-file } sqlite-db rot with-db ; "> } - ; ABOUT: "db" diff --git a/basis/db/tuples/tuples-docs.factor b/basis/db/tuples/tuples-docs.factor index ec43ffe616..d7ee3a5ad2 100644 --- a/basis/db/tuples/tuples-docs.factor +++ b/basis/db/tuples/tuples-docs.factor @@ -1,7 +1,7 @@ ! Copyright (C) 2008 Doug Coleman. ! See http://factorcode.org/license.txt for BSD license. USING: classes help.markup help.syntax io.streams.string kernel -quotations sequences strings multiline math ; +quotations sequences strings multiline math db.types ; IN: db.tuples HELP: define-persistent diff --git a/basis/db/tuples/tuples.factor b/basis/db/tuples/tuples.factor index 862e28d58e..4ecff74c10 100755 --- a/basis/db/tuples/tuples.factor +++ b/basis/db/tuples/tuples.factor @@ -3,7 +3,7 @@ USING: arrays assocs classes db kernel namespaces classes.tuple words sequences slots math accessors math.parser io prettyprint db.types continuations -destructors mirrors sets ; +destructors mirrors sets db.types ; IN: db.tuples