steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

db4
Slava Pestov 2010-12-05 20:58:11 -08:00
parent 9f7c22be60 7bd8c3deba
commit 70a2cfad37
7 changed files with 110 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
basis/concurrency/messaging/messaging-docs.factor
View File

@ -1,35 +1,35 @@
! Copyright (C) 2006 Chris Double.
! See http://factorcode.org/license.txt for BSD license.
USING: help.syntax help.markup
USING: help.syntax help.markup
threads kernel arrays quotations strings ;
IN: concurrency.messaging
HELP: send
{ $values { "message" object }
{ "thread" thread }
{ $values { "message" object }
{ "thread" thread }
}
{ $description "Send the message to the thread by placing it in the threads mailbox. This is an asynchronous operation and will return immediately. The receving thread will act on the message the next time it retrieves that item from its mailbox (usually using the " { $link receive } " word. The message can be any Factor object. For destinations that are instances of remote-thread the message must be a serializable Factor type." }
{ $description "Send the message to the thread by placing it in the threads mailbox. This is an asynchronous operation and will return immediately. The receiving thread will act on the message the next time it retrieves that item from its mailbox (usually using the " { $link receive } " word. The message can be any Factor object. For destinations that are instances of remote-thread the message must be a serializable Factor type." }
{ $see-also receive receive-if } ;
HELP: receive
{ $values { "message" object }
{ $values { "message" object }
}
{ $description "Return a message from the current threads mailbox. If the box is empty, suspend the thread until another thread places an item in the mailbox (usually via the " { $link send } " word." }
{ $description "Return a message from the current threads mailbox. If the box is empty, suspend the thread until another thread places an item in the mailbox (usually via the " { $link send } " word." }
{ $see-also send receive-if } ;
HELP: receive-if
{ $values { "pred" "a predicate with stack effect " { $snippet "( obj -- ? )" } }
{ "message" object }
{ $values { "pred" "a predicate with stack effect " { $snippet "( obj -- ? )" } }
{ "message" object }
}
{ $description "Return the first message from the current threads mailbox that satisfies the predicate. To satisfy the predicate, " { $snippet "pred" } " is called with the item on the stack and the predicate should leave a boolean indicating whether it was satisfied or not. If nothing in the mailbox satisfies the predicate then the thread will block until something does." }
{ $description "Return the first message from the current threads mailbox that satisfies the predicate. To satisfy the predicate, " { $snippet "pred" } " is called with the item on the stack and the predicate should leave a boolean indicating whether it was satisfied or not. If nothing in the mailbox satisfies the predicate then the thread will block until something does." }
{ $see-also send receive } ;
HELP: spawn-linked
{ $values { "quot" quotation }
{ "name" string }
{ "thread" thread }
{ "thread" thread }
}
{ $description "Start a thread which runs the given quotation. If that quotation throws an error which is not caught then the error will get propagated to the thread that spawned it. This can be used to set up 'supervisor' threads that restart child threads that crash due to uncaught errors.\n" }
{ $description "Start a thread which runs the given quotation. If that quotation throws an error which is not caught then the error will get propagated to the thread that spawned it. This can be used to set up 'supervisor' threads that restart child threads that crash due to uncaught errors.\n" }
{ $see-also spawn } ;
ARTICLE: { "concurrency" "messaging" } "Sending and receiving messages"
@ -65,15 +65,15 @@ ARTICLE: { "concurrency" "synchronous-sends" } "Synchronous sends"
} ;
ARTICLE: { "concurrency" "exceptions" } "Linked exceptions"
"A thread can handle exceptions using the standard Factor exception handling mechanism. If an exception is uncaught the thread will terminate. For example:"
{ $code "[ 1 0 / \"This will not print\" print ] \"division-by-zero\" spawn" }
"A thread can handle exceptions using the standard Factor exception handling mechanism. If an exception is uncaught the thread will terminate. For example:"
{ $code "[ 1 0 / \"This will not print\" print ] \"division-by-zero\" spawn" }
"Processes can be linked so that a parent thread can receive the exception that caused the child thread to terminate. In this way 'supervisor' threads can be created that are notified when child threads terminate and possibly restart them."
{ $subsections spawn-linked }
"This will create a unidirectional link, such that if an uncaught exception causes the child to terminate, the parent thread can catch it:"
{ $code "["
" [ 1 0 / \"This will not print\" print ] \"linked-division\" spawn-linked drop"
" receive"
"] [ \"Exception caught.\" print ] recover" }
"] [ \"Exception caught.\" print ] recover" }
"Exceptions are only raised in the parent when the parent does a " { $link receive } " or " { $link receive-if } ". This is because the exception is sent from the child to the parent as a message." ;
ARTICLE: "concurrency.messaging" "Message-passing concurrency"

6
basis/db/tuples/tuples-docs.factor
View File

@ -233,8 +233,7 @@ T{ book
{ date-published T{ timestamp { year 2009 } { month 3 } { day 3 } } }
{ edition 1 }
{ cover-price 13.37 }
} book set
""" }
} book set""" }
"Now we've created a book. Let's save it to the database."
{ $code """USING: db db.sqlite fry io.files.temp ;
: with-book-tutorial ( quot -- )
@ -243,8 +242,7 @@ T{ book
[
book recreate-table
book get insert-tuple
] with-book-tutorial
""" }
] with-book-tutorial""" }
"Is it really there?"
{ $code """[
T{ book { title "Factor for Sheeple" } } select-tuples .

60
basis/io/styles/styles-docs.factor
View File

@ -61,6 +61,7 @@ $nl
"The " { $snippet "style" } " hashtable holds table style information. See " { $link "table-styles" } "." }
{ $examples
{ $code
"USING: io.styles prettyprint sequences ;"
"{ { 1 2 } { 3 4 } }"
"H{ { table-gap { 10 10 } } } ["
" [ [ [ [ . ] with-cell ] each ] with-row ] each"
@ -201,12 +202,13 @@ HELP: bold-italic
{ $description "A value for the " { $link font-style } " character style denoting boldface italicized text." } ;
HELP: foreground
{ $description "Character style. An instance of " { $link color } ". See " { $link "colors" } "." }
{ $description "Character style. An instance of " { $link color } ". See " { $link "colors" } "." }
{ $examples
{ $code
"USING: colors.gray io.styles hashtables sequences kernel math ;"
"10 iota ["
" \"Hello world\\n\""
" swap 10 / 1 <gray> foreground associate format"
" \"Hello world\\n\""
" swap 10 / 1 <gray> foreground associate format"
"] each"
}
} ;
@ -215,10 +217,11 @@ HELP: background
{ $description "Character style. An instance of " { $link color } ". See " { $link "colors" } "." }
{ $examples
{ $code
"USING: colors hashtables io io.styles kernel math sequences ;"
"10 iota ["
" \"Hello world\\n\""
" swap 10 / 1 over - over 1 <rgba>"
" background associate format nl"
" \"Hello world\\n\""
" swap 10 / 1 over - over 1 <rgba>"
" background associate format nl"
"] each"
}
} ;
@ -227,14 +230,20 @@ HELP: font-name
{ $description "Character style. Font family named by a string." }
{ $examples
"This example outputs some different font sizes:"
{ $code "{ \"monospace\" \"serif\" \"sans-serif\" }\n[ dup font-name associate format nl ] each" }
{ $code
"USING: hashtables io io.styles kernel sequences ;"
"{ \"monospace\" \"serif\" \"sans-serif\" }"
"[ dup font-name associate format nl ] each"
}
} ;
HELP: font-size
{ $description "Character style. Font size, an integer." }
{ $examples
"This example outputs some different font sizes:"
{ $code "{ 12 18 24 72 }"
{ $code
"USING: hashtables io io.styles kernel sequences ;"
"{ 12 18 24 72 }"
"[ \"Bigger\" swap font-size associate format nl ] each"
}
} ;
@ -243,28 +252,44 @@ HELP: font-style
{ $description "Character style. Font style, one of " { $link plain } ", " { $link bold } ", " { $link italic } ", or " { $link bold-italic } "." }
{ $examples
"This example outputs text in all three styles:"
{ $code "{ plain bold italic bold-italic }\n[ [ name>> ] keep font-style associate format nl ] each" }
{ $code
"USING: accessors hashtables io io.styles kernel sequences ;"
"{ plain bold italic bold-italic }"
"[ [ name>> ] keep font-style associate format nl ] each"
}
} ;
HELP: presented
{ $description "Character and paragraph style. An object associated with the text. In the Factor UI, this is shown as a clickable presentation of the object; left-clicking invokes a default command, and right-clicking shows a menu of commands." } ;
HELP: page-color
{ $description "Paragraph style. An instance of " { $link color } ". See " { $link "colors" } "." }
{ $description "Paragraph style. An instance of " { $link color } ". See " { $link "colors" } "." }
{ $examples
{ $code "H{ { page-color T{ rgba f 1 0.8 0.5 1 } } }\n[ \"A background\" write ] with-nesting nl" }
{ $code
"USING: colors io io.styles ;"
"H{ { page-color T{ rgba f 1 0.8 0.5 1 } } }"
"[ \"A background\" write ] with-nesting nl"
}
} ;
HELP: border-color
{ $description "Paragraph style. An instance of " { $link color } ". See " { $link "colors" } "." }
{ $examples
{ $code "H{ { border-color T{ rgba f 1 0 0 1 } } }\n[ \"A border\" write ] with-nesting nl" }
{ $code
"USING: colors io io.styles ;"
"H{ { border-color T{ rgba f 1 0 0 1 } } }"
"[ \"A border\" write ] with-nesting nl"
}
} ;
HELP: inset
{ $description "Paragraph style. A pair of integers representing the number of pixels that the content should be inset from the border. The first number is the horizontal inset, and the second is the vertical inset." }
{ $description "Paragraph style. A pair of integers representing the number of pixels that the content should be inset from the border. The first number is the horizontal inset, and the second is the vertical inset." }
{ $examples
{ $code "H{ { inset { 10 10 } } }\n[ \"Some inset text\" write ] with-nesting nl" }
{ $code
"USING: io io.styles ;"
"H{ { inset { 10 10 } } }"
"[ \"Some inset text\" write ] with-nesting nl"
}
} ;
HELP: wrap-margin
@ -284,7 +309,10 @@ HELP: input
{ $class-description "Class of input text presentations. Instances can be used passed to " { $link write-object } " to output a clickable piece of input. Input text presentations are created by calling " { $link <input> } "." }
{ $examples
"This presentation class is used for the code examples you see in the online help:"
{ $code "\"2 3 + .\" dup <input> write-object nl" }
{ $code
"USING: io io.styles kernel ;"
"\"2 3 + .\" dup <input> write-object nl"
}
} ;
HELP: <input>
@ -302,4 +330,4 @@ ARTICLE: "io.streams.plain" "Plain writer streams"
{ $link make-span-stream } ", "
{ $link make-block-stream } " and "
{ $link make-cell-stream } "."
{ $subsections plain-writer } ;
{ $subsections plain-writer } ;

85
basis/literals/literals-docs.factor
View File

@ -8,23 +8,22 @@ HELP: $
{ $description "Executes " { $snippet "word" } " at parse time and adds the result(s) to the parser accumulator." }
{ $notes { $snippet "word" } "'s definition is looked up and " { $link call } "ed at parse time, so words that reference words in the current compilation unit cannot be used with " { $snippet "$" } "." }
{ $examples
{ $example """
USING: kernel literals prettyprint ;
IN: scratchpad
CONSTANT: five 5
{ $ five } .
""" "{ 5 }" }
{ $example """
USING: kernel literals prettyprint ;
IN: scratchpad
: seven-eleven ( -- a b ) 7 11 ;
{ $ seven-eleven } .
""" "{ 7 11 }" }
{ $example
"USING: kernel literals prettyprint ;"
"IN: scratchpad"
""
"CONSTANT: five 5"
"{ $ five } ."
"{ 5 }"
}
{ $example
"USING: kernel literals prettyprint ;"
"IN: scratchpad"
""
": seven-eleven ( -- a b ) 7 11 ;"
"{ $ seven-eleven } ."
"{ 7 11 }"
}
} ;
HELP: $[
@ -32,15 +31,14 @@ HELP: $[
{ $description "Calls " { $snippet "code" } " at parse time and adds the result(s) to the parser accumulator." }
{ $notes "Since " { $snippet "code" } " is " { $link call } "ed at parse time, it cannot reference any words defined in the same compilation unit." }
{ $examples
{ $example """
USING: kernel literals math prettyprint ;
IN: scratchpad
<< CONSTANT: five 5 >>
{ $[ five dup 1 + dup 2 + ] } .
""" "{ 5 6 8 }" }
{ $example
"USING: kernel literals math prettyprint ;"
"IN: scratchpad"
""
"<< CONSTANT: five 5 >>"
"{ $[ five dup 1 + dup 2 + ] } ."
"{ 5 6 8 }"
}
} ;
HELP: ${
@ -48,15 +46,14 @@ HELP: ${
{ $description "Outputs an array containing the results of executing " { $snippet "code" } " at parse time." }
{ $notes { $snippet "code" } "'s definition is looked up and " { $link call } "ed at parse time, so words that reference words in the current compilation unit cannot be used with " { $snippet "$" } "." }
{ $examples
{ $example """
USING: kernel literals math prettyprint ;
IN: scratchpad
CONSTANT: five 5
CONSTANT: six 6
${ five six 7 } .
""" "{ 5 6 7 }"
{ $example
"USING: kernel literals math prettyprint ;"
"IN: scratchpad"
""
"CONSTANT: five 5"
"CONSTANT: six 6"
"${ five six 7 } ."
"{ 5 6 7 }"
}
} ;
@ -66,7 +63,8 @@ HELP: flags{
{ $values { "values" sequence } }
{ $description "Constructs a constant flag value from a sequence of integers or words that output integers. The resulting constant is computed at parse-time, which makes this word as efficient as using a literal integer." }
{ $examples
{ $example "USING: literals kernel prettyprint ;"
{ $example
"USING: literals kernel prettyprint ;"
"IN: scratchpad"
"CONSTANT: x HEX: 1"
"flags{ HEX: 20 x BIN: 100 } .h"
@ -77,13 +75,14 @@ HELP: flags{
ARTICLE: "literals" "Interpolating code results into literal values"
"The " { $vocab-link "literals" } " vocabulary contains words to run code at parse time and insert the results into more complex literal values."
{ $example """
USE: literals
IN: scratchpad
CONSTANT: five 5
{ $ five $[ five dup 1 + dup 2 + ] } .
""" "{ 5 5 6 8 }" }
{ $example
"USING: kernel literals math prettyprint ;"
"IN: scratchpad"
""
"<< CONSTANT: five 5 >>"
"{ $ five $[ five dup 1 + dup 2 + ] } ."
"{ 5 5 6 8 }"
}
{ $subsections
POSTPONE: $
POSTPONE: $[

2
basis/urls/encoding/encoding-docs.factor
View File

@ -1,4 +1,4 @@
USING: strings help.markup help.syntax assocs ;
USING: strings help.markup help.syntax assocs urls ;
IN: urls.encoding
HELP: url-decode

10
core/classes/tuple/tuple-docs.factor
View File

@ -190,7 +190,7 @@ $nl
{ $subsections
"tuple-inheritance-example"
"tuple-inheritance-anti-example"
}
}
"Declaring a tuple class final prohibits other classes from subclassing it:"
{ $subsections POSTPONE: final }
{ $see-also "call-next-method" "parametrized-constructors" "unions" "mixins" } ;
@ -215,12 +215,14 @@ ARTICLE: "tuple-examples" "Tuple examples"
{ $table
{ "Reader" "Writer" "Setter" "Changer" }
{ { $snippet "name>>" } { $snippet "name<<" } { $snippet ">>name" } { $snippet "change-name" } }
{ { $snippet "position>>" } { $snippet "position<<" } { $snippet ">>position" } { $snippet "change-position" } }
{ { $snippet "salary>>" } { $snippet "salary<<" } { $snippet ">>salary" } { $snippet "change-salary" } }
{ { $snippet "position>>" } { $snippet "position<<" } { $snippet ">>position" } { $snippet "change-position" } }
}
"We can define a constructor which makes an empty employee:"
{ $code ": <employee> ( -- employee )"
" employee new ;" }
{ $code
": <employee> ( -- employee )"
" employee new ;"
}
"Or we may wish the default constructor to always give employees a starting salary:"
{ $code
": <employee> ( -- employee )"

2
core/generic/generic-docs.factor
View File

@ -129,7 +129,7 @@ HELP: define-generic
HELP: M\
{ $syntax "M\\ class generic" }
{ $class-description "Pushes a method on the stack." }
{ $examples { $code "M\\ fixnum + see" } { $code "USING: ui.gadgets ui.gadgets.editors ;" "M\\ editor draw-gadget* edit" } } ;
{ $examples { $code "M\\ fixnum + see" } { $code "USING: ui.gadgets.editors ui.render ;" "M\\ editor draw-gadget* edit" } } ;
HELP: method
{ $values { "class" class } { "generic" generic } { "method/f" { $maybe method } } }