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

stack-checker.errors: improve documentation a bit

db4
Slava Pestov 2009-09-17 13:27:15 -07:00
parent 086d4a87b4
commit 7f1c33f363
1 changed files with 34 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
basis/stack-checker/errors/errors-docs.factor
View File

@ -1,14 +1,43 @@
USING: help.markup help.syntax kernel effects sequences
sequences.private words ;
sequences.private words combinators ;
IN: stack-checker.errors
HELP: do-not-compile
{ $error-description "Thrown when inference encounters a macro being applied to a value which is not known to be a literal. Such code needs changes before it can compile and run. See " { $link "inference-combinators" } " and " { $link "inference-escape" } " for details." }
{ $examples
"In this example, " { $link cleave } " is being applied to an array that is constructed on the fly. This is not allowed and fails to compile with a " { $link do-not-compile } " error:"
{ $code
": cannot-compile-call-example ( x -- y z )"
" [ 1 + ] [ 1 - ] 2array cleave ;"
}
} ;
HELP: literal-expected
{ $error-description "Thrown when inference encounters a combinator or macro being applied to a value which is not known to be a literal, or constructed in a manner which can be analyzed statically. Such code needs changes before it can compile and run. See " { $link "inference-combinators" } " and " { $link "inference-escape" } " for details." }
{ $examples
"In this example, words calling " { $snippet "literal-expected-example" } " will have a static stac keffect, even if " { $snippet "literal-expected-example" } " does not:"
"In this example, the words being defined cannot be called, because they fail to compile with a " { $link literal-expected } " error:"
{ $code
": literal-expected-example ( quot -- )"
": bad-example ( quot -- )"
" [ call ] [ call ] bi ;"
""
": usage ( -- )"
" 10 [ 2 * ] bad-example . ;"
}
"One fix is to declare the combinator as inline:"
{ $code
": good-example ( quot -- )"
" [ call ] [ call ] bi ; inline"
""
": usage ( -- )"
" 10 [ 2 * ] good-example . ;"
}
"Another fix is to use " { $link POSTPONE: call( } ":"
{ $code
": good-example ( quot -- )"
" [ call( x -- y ) ] [ call( x -- y ) ] bi ;"
""
": usage ( -- )"
" 10 [ 2 * ] good-example . ;"
}
} ;
@ -89,7 +118,8 @@ ARTICLE: "inference-errors" "Stack checker errors"
{ { $link "tools.inference" } " throws them as errors" }
{ "The " { $link "compiler" } " reports them via " { $link "tools.errors" } }
}
"Error thrown when insufficient information is available to calculate the stack effect of a combinator call (see " { $link "inference-combinators" } "):"
"Errors thrown when insufficient information is available to calculate the stack effect of a call to a combinator or macro (see " { $link "inference-combinators" } "):"
{ $subsection do-not-compile }
{ $subsection literal-expected }
"Error thrown when a word's stack effect declaration does not match the composition of the stack effects of its factors:"
{ $subsection effect-error }