From 7a5132140f1e7fe70a30e5eb5ba86498922dc083 Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Sun, 14 Nov 2010 17:11:17 +0900 Subject: [PATCH 01/12] concurrency.locks: fix typo in docs --- basis/concurrency/locks/locks-docs.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/concurrency/locks/locks-docs.factor b/basis/concurrency/locks/locks-docs.factor index f600b01056..4a331e8f19 100644 --- a/basis/concurrency/locks/locks-docs.factor +++ b/basis/concurrency/locks/locks-docs.factor @@ -60,7 +60,7 @@ ARTICLE: "concurrency.locks.rw" "Read-write locks" $nl "While this can be achieved with a simple " { $link "concurrency.locks.mutex" } ", performance will suffer, since in fact multiple threads can view the structure at the same time; serialization must only be enforced for writes." $nl -"Read/write locks allow any number of threads to hold the read lock simulateneously, however attempting to acquire a write lock blocks until all other threads release read locks and write locks." +"Read/write locks allow any number of threads to hold the read lock simultaneously, however attempting to acquire a write lock blocks until all other threads release read locks and write locks." $nl "Read/write locks are reentrant. A thread holding a write lock may acquire a read lock or a write lock without blocking. However a thread holding a read lock may not acquire a write lock recursively since that could break invariants assumed by the code executing with the read lock held." { $subsections From 12701675137a2c40137bd655189de9c5c04b5e64 Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Sun, 14 Nov 2010 17:14:40 +0900 Subject: [PATCH 02/12] vocabs: fix typo in docs --- core/vocabs/vocabs-docs.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/vocabs/vocabs-docs.factor b/core/vocabs/vocabs-docs.factor index 3f8a71e76c..b2cb422178 100644 --- a/core/vocabs/vocabs-docs.factor +++ b/core/vocabs/vocabs-docs.factor @@ -77,7 +77,7 @@ HELP: forget-vocab { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ; HELP: load-vocab-hook -{ $var-description { $quotation "( name -- vocab )" } " which loads a vocabulary. This quotation is called by " { $link load-vocab } ". The default value should not need to be changed; this functinality is implemented via a hook stored in a variable to break a circular dependency which would otherwise exist from " { $vocab-link "vocabs" } " to " { $vocab-link "vocabs.loader" } " to " { $vocab-link "parser" } " back to " { $vocab-link "vocabs" } "." } ; +{ $var-description { $quotation "( name -- vocab )" } " which loads a vocabulary. This quotation is called by " { $link load-vocab } ". The default value should not need to be changed; this functionality is implemented via a hook stored in a variable to break a circular dependency which would otherwise exist from " { $vocab-link "vocabs" } " to " { $vocab-link "vocabs.loader" } " to " { $vocab-link "parser" } " back to " { $vocab-link "vocabs" } "." } ; HELP: words-named { $values { "str" string } { "seq" "a sequence of words" } } From ae7b44e5eb6222e14eba6e9a35597279a2a3f178 Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Sun, 14 Nov 2010 17:18:56 +0900 Subject: [PATCH 03/12] io.directories: fix typo in example --- basis/io/directories/directories-docs.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/io/directories/directories-docs.factor b/basis/io/directories/directories-docs.factor index 3871f9be41..6370fdb90d 100644 --- a/basis/io/directories/directories-docs.factor +++ b/basis/io/directories/directories-docs.factor @@ -52,7 +52,7 @@ HELP: with-directory-files { $examples "Print all files in your home directory which are larger than a megabyte:" { $code - """USING: io.directoies io.files.info io.pathnames ; + """USING: io.directories io.files.info io.pathnames ; home [ [ dup link-info size>> 20 2^ > From 58bac61281e0d342bc64683d6af0718296de48d6 Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Tue, 16 Nov 2010 17:45:25 +0900 Subject: [PATCH 04/12] help.handbook: fix typo --- basis/help/handbook/handbook.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/help/handbook/handbook.factor b/basis/help/handbook/handbook.factor index da5f2911f8..9c8464cae1 100644 --- a/basis/help/handbook/handbook.factor +++ b/basis/help/handbook/handbook.factor @@ -45,7 +45,7 @@ $nl $nl "Some generic words have " { $strong "Description" } " headings, and others have " { $strong "Contract" } " headings. A distinction is made between words which are not intended to be extended with user-defined methods, and those that are." { $heading "Vocabulary naming conventions" } -"A vocabulary name ending in " { $snippet ".private" } " contains words which are either implementation details, unsafe, or both. For example, the " { $snippet "sequence.private" } " vocabulary contains words which access sequence elements without bounds checking (" { $link "sequences-unsafe" } "). You should avoid using private words from the Factor library unless absolutely necessary. Similarly, your own code can place words in private vocabularies using " { $link POSTPONE: Date: Thu, 18 Nov 2010 03:44:25 +0900 Subject: [PATCH 05/12] io.files.info.unix: fix a couple of set-file-permissions examples --- basis/io/files/info/unix/unix-docs.factor | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/basis/io/files/info/unix/unix-docs.factor b/basis/io/files/info/unix/unix-docs.factor index 7b98788226..d66520fa02 100644 --- a/basis/io/files/info/unix/unix-docs.factor +++ b/basis/io/files/info/unix/unix-docs.factor @@ -102,15 +102,15 @@ HELP: set-file-permissions { "path" "a pathname string" } { "n" "an integer, interepreted as a string of bits" } } { $description "Sets the file permissions for a given file with the supplied Unix permissions integer. Supplying an octal number with " { $link POSTPONE: OCT: } " is recommended." } { $examples "Using the tradidional octal value:" - { $unchecked-example "USING: io.files.unix kernel ;" + { $unchecked-example "USING: io.files.info.unix kernel ;" "\"resource:license.txt\" OCT: 755 set-file-permissions" "" } "Higher-level, setting named bits:" - { $unchecked-example "USING: io.files.unix kernel math.bitwise ;" + { $unchecked-example "USING: io.files.info.unix kernel literals ;" "\"resource:license.txt\"" - "{ USER-ALL GROUP-READ GROUP-EXECUTE OTHER-READ OTHER-EXECUTE }" - "flags set-file-permissions" + "flags{ USER-ALL GROUP-READ GROUP-EXECUTE OTHER-READ OTHER-EXECUTE }" + "set-file-permissions" "" } } ; From 04aeadbb15b54e664604c96d97a93a4c5d8e3185 Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Thu, 18 Nov 2010 04:29:36 +0900 Subject: [PATCH 06/12] io.files.info.unix: fix IN: in docs --- basis/io/files/info/unix/unix-docs.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/io/files/info/unix/unix-docs.factor b/basis/io/files/info/unix/unix-docs.factor index d66520fa02..c461c642b7 100644 --- a/basis/io/files/info/unix/unix-docs.factor +++ b/basis/io/files/info/unix/unix-docs.factor @@ -2,7 +2,7 @@ ! See http://factorcode.org/license.txt for BSD license. USING: classes help.markup help.syntax io.streams.string strings math calendar io.files.info io.files.info.unix ; -IN: io.files.unix +IN: io.files.info.unix HELP: add-file-permissions { $values From 7c963b9dbeed9acf211c0fb090d66ace9f4118ed Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Wed, 24 Nov 2010 05:58:15 +0900 Subject: [PATCH 07/12] eval: fix cad.objects path in example --- basis/eval/eval-docs.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/eval/eval-docs.factor b/basis/eval/eval-docs.factor index f3ee35d91c..e7e3c02303 100644 --- a/basis/eval/eval-docs.factor +++ b/basis/eval/eval-docs.factor @@ -50,7 +50,7 @@ $nl { $code """USING: eval listener vocabs.parser ; [ - "cad-objects" use-vocab + "cad.objects" use-vocab (( -- seq )) (eval) ] with-interactive-vocabs""" } From 18811fb04abcf98f1f60043f2aef30554724405c Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Sun, 28 Nov 2010 00:47:59 +0900 Subject: [PATCH 08/12] io.pathnames: fix typo in docs --- core/io/pathnames/pathnames-docs.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core/io/pathnames/pathnames-docs.factor b/core/io/pathnames/pathnames-docs.factor index cc637b59c3..a3b9338978 100644 --- a/core/io/pathnames/pathnames-docs.factor +++ b/core/io/pathnames/pathnames-docs.factor @@ -106,7 +106,7 @@ HELP: absolute-path { "path" "a pathname string" } { "path'" "a pathname string" } } -{ $description "Prepends the " { $link current-directory } " to the pathname and resolves a " { $snippet "resource:" } " or " { $snippet "voacb:" } " prefix, if present (see " { $link "io.pathnames.special" } ")." } +{ $description "Prepends the " { $link current-directory } " to the pathname and resolves a " { $snippet "resource:" } " or " { $snippet "vocab:" } " prefix, if present (see " { $link "io.pathnames.special" } ")." } { $notes "This word is exaclty the same as " { $link normalize-path } ", except on Windows NT platforms, where it does not prepend the Unicode path prefix. Most code should call " { $link normalize-path } " instead." } ; HELP: resolve-symlinks From 2dbee396fbb69d03d83c1bca5943ec9f3da0d5e5 Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Sun, 28 Nov 2010 03:34:27 +0900 Subject: [PATCH 09/12] db: fix some examples --- basis/db/db-docs.factor | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/basis/db/db-docs.factor b/basis/db/db-docs.factor index 66c9f32f7f..cf358fa4b2 100644 --- a/basis/db/db-docs.factor +++ b/basis/db/db-docs.factor @@ -271,24 +271,21 @@ ARTICLE: "db-lowlevel-tutorial" "Low-level database tutorial" { $subsections sql-query } "Here's an example usage where we'll make a book table, insert some objects, and query them." $nl "First, let's set up a custom combinator for using our database. See " { $link "db-custom-database-combinators" } " for more details." -{ $code """ -USING: db.sqlite db io.files io.files.temp ; +{ $code """USING: db.sqlite db io.files io.files.temp ; : with-book-db ( quot -- ) - "book.db" temp-file swap with-db ; inline" } + "book.db" temp-file swap with-db ; inline""" } "Now let's create the table manually:" -{ $code " "create table books +{ $code """"create table books (id integer primary key, title text, author text, date_published timestamp, edition integer, cover_price double, condition text)" [ sql-command ] with-book-db""" } "Time to insert some books:" -{ $code """ -"insert into books +{ $code """"insert into books (title, author, date_published, edition, cover_price, condition) values('Factor for Sheeple', 'Mister Stacky Pants', date('now'), 1, 13.37, 'mint')" [ sql-command ] with-book-db""" } "Now let's select the book:" -{ $code """ -"select id, title, cover_price from books;" [ sql-query ] with-book-db""" } +{ $code """"select id, title, cover_price from books;" [ sql-query ] with-book-db""" } "Notice that the result of this query is a Factor array containing the database rows as arrays of strings. We would have to convert the " { $snippet "cover_price" } " from a string to a number in order to use it in a calculation." $nl "In conclusion, this method of accessing a database is supported, but it is fairly low-level and generally specific to a single database. The " { $vocab-link "db.tuples" } " vocabulary is a good alternative to writing SQL by hand." ; @@ -298,10 +295,9 @@ ARTICLE: "db-custom-database-combinators" "Custom database combinators" "Make a " { $snippet "with-" } " combinator to open and close a database so that resources are not leaked." $nl "SQLite example combinator:" -{ $code """ -USING: db.sqlite db io.files io.files.temp ; +{ $code """USING: db.sqlite db io.files io.files.temp ; : with-sqlite-db ( quot -- ) - "my-database.db" temp-file swap with-db ; inline""" } + "my-database.db" temp-file swap with-db ; inline""" } "PostgreSQL example combinator:" { $code """USING: db.postgresql db ; From cca391861ecdb609ac6d46c9a3fce57ae171fcf6 Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Mon, 29 Nov 2010 03:44:45 +0900 Subject: [PATCH 10/12] help: add stack effect declaration and using to HELP: example in docs --- basis/help/help-docs.factor | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/basis/help/help-docs.factor b/basis/help/help-docs.factor index e3bd50a6f2..597830ab7e 100644 --- a/basis/help/help-docs.factor +++ b/basis/help/help-docs.factor @@ -476,7 +476,8 @@ HELP: HELP: { $description "Defines documentation for a word." } { $examples { $code - ": foo 2 + ;" + "USING: help help.markup help.syntax math syntax ;" + ": foo ( m -- n ) 2 + ;" "HELP: foo" "{ $values { \"m\" \"an integer\" } { \"n\" \"an integer\" } }" "{ $description \"Increments a value by 2.\" } ;" From e7796b4118962992f58e0d4eb43ea7e795e68070 Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Mon, 29 Nov 2010 18:41:57 +0900 Subject: [PATCH 11/12] tools.crossref: fix example --- basis/tools/crossref/crossref-docs.factor | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/basis/tools/crossref/crossref-docs.factor b/basis/tools/crossref/crossref-docs.factor index e8c45ee4a0..29b3d26d10 100644 --- a/basis/tools/crossref/crossref-docs.factor +++ b/basis/tools/crossref/crossref-docs.factor @@ -28,7 +28,7 @@ HELP: uses { $notes "The sequence might include the definition itself, if it is a recursive word." } { $examples "We can ask the " { $link sq } " word to produce a list of words it calls:" - { $unchecked-example "\ sq uses ." "{ dup * }" } + { $unchecked-example "\\ sq uses ." "{ dup * }" } } ; HELP: crossref From 3e7af333436d21df0561de2eb8b31481d833436e Mon Sep 17 00:00:00 2001 From: Keita Haga Date: Tue, 30 Nov 2010 04:53:11 +0900 Subject: [PATCH 12/12] hints: fix two examples and formatting in docs --- basis/hints/hints-docs.factor | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/basis/hints/hints-docs.factor b/basis/hints/hints-docs.factor index 46bdc698b7..4ff973a251 100644 --- a/basis/hints/hints-docs.factor +++ b/basis/hints/hints-docs.factor @@ -24,20 +24,26 @@ HELP: HINTS: { $description "Defines specialization hints for a word or a method." $nl "Each sequence in the list will cause a specialized version of the word to be compiled. Classes are tested for using their predicate, and literals are tested using " { $link eq? } "." } -{ $examples "The " { $link append } " word has a specializer for the very common case where two strings or two arrays are appended:" -{ $code "HINTS: append { string string } { array array } ;" } -"Specializers can also be defined on methods:" -{ $code - "GENERIC: count-occurrences ( elt obj -- n )" - "" - "M: sequence count-occurrences [ = ] with count ;" - "" - "M: assoc count-occurrences" - " swap [ = nip ] curry assoc-filter assoc-size ;" - "" - "HINTS: M\ sequence count-occurrences { object array } ;" - "HINTS: M\ assoc count-occurrences { object hashtable } ;" -} +{ $examples + "The " { $link append } " word has a specializer for the very common case where two strings or two arrays are appended:" + { $code + "USING: arrays hints sequences strings syntax ;" + "HINTS: append { string string } { array array } ;" + } + "Specializers can also be defined on methods:" + { $code + "USING: assocs hashtables hints kernel sequences" + "syntax ;" + "GENERIC: count-occurrences ( elt obj -- n )" + "" + "M: sequence count-occurrences [ = ] with count ;" + "" + "M: assoc count-occurrences" + " swap [ = nip ] curry assoc-filter assoc-size ;" + "" + "HINTS: M\\ sequence count-occurrences { object array } ;" + "HINTS: M\\ assoc count-occurrences { object hashtable } ;" + } } ; ABOUT: "hints"