Merge branch 'doc-fixes' of git://github.com/keitahaga/factor

db4
Slava Pestov 2010-12-01 03:02:38 -08:00
commit 6f0375b3ba
11 changed files with 41 additions and 38 deletions

View File

@ -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

View File

@ -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 <sqlite-db> swap with-db ; inline" }
"book.db" temp-file <sqlite-db> 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 <sqlite-db> swap with-db ; inline""" }
"my-database.db" temp-file <sqlite-db> swap with-db ; inline""" }
"PostgreSQL example combinator:"
{ $code """USING: db.postgresql db ;

View File

@ -50,7 +50,7 @@ $nl
{ $code
"""USING: eval listener vocabs.parser ;
[
"cad-objects" use-vocab
"cad.objects" use-vocab
(( -- seq )) (eval)
] with-interactive-vocabs"""
}

View File

@ -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: <PRIVATE } " if you do not want other people using them without good reason."
"A vocabulary name ending in " { $snippet ".private" } " contains words which are either implementation details, unsafe, or both. For example, the " { $snippet "sequences.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: <PRIVATE } " if you do not want other people using them without good reason."
{ $heading "Word naming conventions" }
"These conventions are not hard and fast, but are usually a good first step in understanding a word's behavior:"
{ $table

View File

@ -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.\" } ;"

View File

@ -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"

View File

@ -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^ >

View File

@ -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
@ -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"
"" }
} ;

View File

@ -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

View File

@ -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

View File

@ -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" } }