Merge branch 'doc-fixes' of git://github.com/keitahaga/factor
commit
6f0375b3ba
|
@ -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
|
||||
|
|
|
@ -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 ;
|
||||
|
|
|
@ -50,7 +50,7 @@ $nl
|
|||
{ $code
|
||||
"""USING: eval listener vocabs.parser ;
|
||||
[
|
||||
"cad-objects" use-vocab
|
||||
"cad.objects" use-vocab
|
||||
(( -- seq )) (eval)
|
||||
] with-interactive-vocabs"""
|
||||
}
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.\" } ;"
|
||||
|
|
|
@ -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"
|
||||
|
|
|
@ -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^ >
|
||||
|
|
|
@ -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"
|
||||
"" }
|
||||
} ;
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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" } }
|
||||
|
|
Loading…
Reference in New Issue