diff --git a/library/bootstrap/boot-stage1.factor b/library/bootstrap/boot-stage1.factor index 0f7e5cd1c9..e64df5acef 100644 --- a/library/bootstrap/boot-stage1.factor +++ b/library/bootstrap/boot-stage1.factor @@ -97,6 +97,13 @@ vectors words ; "/library/tools/annotations.factor" "/library/tools/inspector.factor" + "/library/help/database.factor" + "/library/help/stylesheet.factor" + "/library/help/help.factor" + "/library/help/markup.factor" + "/library/help/word-help.factor" + "/library/help/syntax.factor" + "/library/test/test.factor" "/library/threads.factor" @@ -143,13 +150,6 @@ vectors words ; "/library/bootstrap/init.factor" - "/library/help/database.factor" - "/library/help/stylesheet.factor" - "/library/help/help.factor" - "/library/help/markup.factor" - "/library/help/word-help.factor" - "/library/help/syntax.factor" - ! This must be the last file of parsing words loaded "/library/syntax/parse-syntax.factor" @@ -197,6 +197,7 @@ vectors words ; "/library/help/commands.factor" + "/library/continuations.facts" "/library/kernel.facts" "/library/vocabularies.facts" "/library/words.facts" diff --git a/library/continuations.factor b/library/continuations.factor index 3debb642e4..2cbea0fc49 100644 --- a/library/continuations.factor +++ b/library/continuations.factor @@ -13,9 +13,6 @@ USING: namespaces sequences ; TUPLE: continuation data call name catch ; : continuation ( -- interp ) - #! The continuation is reified from after the *caller* of - #! this word returns. It must be declared inline for this - #! invariant to be preserved in compiled code too. datastack callstack dup pop* dup pop* namestack catchstack ; inline @@ -26,32 +23,20 @@ TUPLE: continuation data call name catch ; continuation-catch ; inline : ifcc ( terminator balance -- | quot: continuation -- ) - #! Note that the branch at the end must not be optimized out - #! by the compiler. [ continuation dup continuation-data f over push f swap push dup ] call 2swap if ; inline -: callcc0 ( quot -- | quot: continuation -- ) - #! Call a quotation with the current continuation, which may - #! be restored using continue. - [ drop ] ifcc ; inline +: callcc0 [ drop ] ifcc ; inline : continue ( continuation -- ) - #! Restore a continuation. >continuation< set-catchstack set-namestack set-callstack set-datastack ; inline : (continue-with) 9 getenv ; -: callcc1 ( quot -- | quot: continuation -- ) - #! Call a quotation with the current continuation, which may - #! be restored using continue-with. - [ drop (continue-with) ] ifcc ; inline +: callcc1 [ drop (continue-with) ] ifcc ; inline -: continue-with ( object continuation -- object ) - #! Restore a continuation, and place the object in the - #! restored data stack. - swap 9 setenv continue ; inline +: continue-with swap 9 setenv continue ; inline diff --git a/library/continuations.facts b/library/continuations.facts new file mode 100644 index 0000000000..86c6cb9e92 --- /dev/null +++ b/library/continuations.facts @@ -0,0 +1,44 @@ +USING: errors help kernel ; + +HELP: catchstack* "( -- catchstack )" +{ $values { "catchstack" "a vector" } } +{ $description "Outputs the current catchstack." } ; + +HELP: catchstack "( -- catchstack )" +{ $values { "catchstack" "a vector" } } +{ $description "Outputs a copy of the current catchstack." } ; + +HELP: set-catchstack "( catchstack -- )" +{ $values { "catchstack" "a vector" } } +{ $description "Replaces the catchstack with a copy of the given vector." } ; + +HELP: continuation "( -- continuation )" +{ $values { "continuation" "a continuation" } } +{ $description "Reifies the current continuation from the point immediately after which the caller returns." } ; + +HELP: >continuation< "( continuation -- data call name catch )" +{ $values { "continuation" "a continuation" } { "data" "a vector" } { "call" "a vector" } { "name" "a vector" } { "catch" "a vector" } } +{ $description "Takes a continuation apart into its four constituents." } ; + +HELP: ifcc "( terminator balance -- )" +{ $values { "terminator" "a quotation with stack effect " { $snippet "( continuation -- )" } { "balance" "a quotation" } } +{ $description "Reifies a continuation and passes it to " { $snippet "terminator" } ". When the continuation is restored, execution resumes; " { $snippet "terminator" } " is still on the stack and "{ $snippet "balance" } " is called." } +{ $see-also callcc0 callcc1 } ; + +HELP: callcc0 "( quot -- )" +{ $values { "quot" "a quotation with stack effect " { $snippet "( continuation -- )" } } } +{ $description "Applies the quotation to the current continuation. The " { $link continue } " word resumes the continuation." } +{ $see-also ifcc callcc1 continue } ; + +HELP: callcc1 "( quot -- obj )" +{ $values { "quot" "a quotation with stack effect " { $snippet "( continuation -- )" } } { "obj" "an object provided when resuming the continuation" } } +{ $description "Applies the quotation to the current continuation. The " { $link continue-with } " word resumes the continuation, passing a value back to the original execution context." } +{ $see-also ifcc callcc0 continue-with } ; + +HELP: continue "( continuation -- )" +{ $values { "continuation" "a continuation" } } +{ $description "Resumes a continuation reified by " { $link callcc0 } "." } ; + +HELP: continue-with "( obj continuation -- )" +{ $values { "obj" "an object to pass to the continuation's execution context" } { "continuation" "a continuation" } } +{ $description "Resumes a continuation reified by " { $link callcc1 } ". The object remains on the stack when the continuation resumes executing." } ; diff --git a/library/errors.factor b/library/errors.factor index 30b46404ed..76f3dd6aec 100644 --- a/library/errors.factor +++ b/library/errors.factor @@ -3,8 +3,6 @@ IN: errors USING: kernel kernel-internals lists sequences ; -! This is a very lightweight exception handling system. - TUPLE: no-method object generic ; : no-method ( object generic -- ) throw ; diff --git a/library/errors.facts b/library/errors.facts new file mode 100644 index 0000000000..09e17459d4 --- /dev/null +++ b/library/errors.facts @@ -0,0 +1,7 @@ +USING: errors help ; + +HELP: throw "( error -- )" +{ $values { "error" "an object" } } +{ $description "Throws an error. Execution does not continue at the point after the " { $link throw } " call. Rather, the innermost catch block is invoked, and execution continues at that point." } ; + + diff --git a/library/help/markup.factor b/library/help/markup.factor index 4cf74016f0..c393b9bc89 100644 --- a/library/help/markup.factor +++ b/library/help/markup.factor @@ -179,10 +179,10 @@ DEFER: help terpri ] interleave ; -: $predicate ( content -- :r) - { { "object" object } } $values +: $predicate ( content -- ) + { { "object" "an object" } } $values "Tests if the top of the stack is " $description - dup word-name a/an print-element $link "." print-element ; + dup first word-name a/an format* $link "." format* ; : $list ( content -- ) terpri* [ "- " format* print-element terpri* ] each ; diff --git a/library/tools/describe.factor b/library/tools/describe.factor index a98c924d3e..942ca07fef 100644 --- a/library/tools/describe.factor +++ b/library/tools/describe.factor @@ -1,7 +1,7 @@ ! Copyright (C) 2005 Slava Pestov. ! See http://factor.sf.net/license.txt for BSD license. IN: inspector -USING: arrays generic hashtables io kernel kernel-internals +USING: arrays generic hashtables help io kernel kernel-internals lists math prettyprint sequences strings vectors words ; GENERIC: summary ( object -- string ) @@ -83,16 +83,13 @@ DEFER: describe : describe ( object -- ) dup summary print sheet sheet. ; -: word. ( word -- ) - dup word-name swap dup [ see ] curry simple-outliner ; - : sequence-outliner ( seq quot -- | quot: obj -- ) swap [ [ unparse-short ] keep rot dupd curry simple-outliner ] each-with ; : words. ( vocab -- ) - words word-sort [ see ] sequence-outliner ; + words word-sort [ (help) ] sequence-outliner ; : vocabs. ( -- ) #! Outlining word browser.