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

Clarify documentation for compilation units and 'undefined' error

db4
Slava Pestov 2010-02-02 00:57:01 +13:00
parent cde6a2c5f7
commit 3e8d21b493
3 changed files with 31 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
basis/debugger/debugger.factor
View File

@ -237,8 +237,8 @@ M: redefine-error error.
M: undefined summary
word>> undefined?
"Cannot call a deferred word before it has been defined"
"Cannot call a word before it has been compiled"
"Cannot execute a deferred word before it has been defined"
"Cannot execute a word before it has been compiled"
? ;
M: no-compilation-unit error.

27
core/compiler/units/units-docs.factor
View File

@ -1,14 +1,10 @@
USING: help.markup help.syntax words math source-files
parser quotations definitions ;
parser quotations definitions stack-checker.errors ;
IN: compiler.units
ARTICLE: "compilation-units" "Compilation units"
"A " { $emphasis "compilation unit" } " scopes a group of related definitions. They are compiled and entered into the system in one atomic operation."
ARTICLE: "compilation-units-internals" "Compilation units internals"
"These words do not need to be called directly, and only serve to support the implementation."
$nl
"Words defined in a compilation unit may not be called until the compilation unit is finished. The parser detects this case for parsing words and throws a " { $link staging-violation } "; calling any other word from within its own compilation unit throws an " { $link undefined } " error."
$nl
"The parser groups all definitions in a source file into one compilation unit, and parsing words do not need to concern themselves with compilation units. However, if definitions are being created at run time, a compilation unit must be created explicitly:"
{ $subsections with-compilation-unit }
"Compiling a set of words:"
{ $subsections compile }
"Words called to associate a definition with a compilation unit and a source file location:"
@ -23,6 +19,23 @@ $nl
"Low-level compiler interface exported by the Factor VM:"
{ $subsections modify-code-heap } ;
ARTICLE: "compilation-units" "Compilation units"
"A " { $emphasis "compilation unit" } " scopes a group of related definitions. They are compiled and entered into the system in one atomic operation."
$nl
"When a source file is being parsed, all definitions are part of a single compilation unit, unless the " { $link POSTPONE: << } " parsing word is used to create nested compilation units."
$nl
"Words defined in a compilation unit may not be called until the compilation unit is finished. The parser detects this case for parsing words and throws a " { $link staging-violation } ". Similarly, an attempt to use a macro from a word defined in the same compilation unit will throw a " { $link transform-expansion-error } ". Calling any other word from within its own compilation unit throws an " { $link undefined } " error."
$nl
"This means that parsing words and macros generally cannot be used in the same source file as they are defined. There are two means of getting around this:"
{ $list
{ "The simplest way is to split off the parsing words and macros into sub-vocabularies; perhaps suffixed by " { $snippet ".syntax" } " and " { $snippet ".macros" } "." }
{ "Alternatively, nested compilation units can be created using " { $link "syntax-immediate" } "." }
}
"Parsing words which create new definitions at parse time will implicitly add them to the compilation unit of the current source file. Code which creates new definitions at run time will need to explicitly create a compilation unit with a combinator:"
{ $subsections with-compilation-unit }
"Additional topics:"
{ $subsections "compilation-units-internals" } ;
ABOUT: "compilation-units"
HELP: redefine-error

10
core/words/words-docs.factor
View File

@ -65,7 +65,7 @@ $nl
"Deferred words are just compound definitions in disguise. The following two lines are equivalent:"
{ $code
"DEFER: foo"
": foo undefined ;"
": foo ( -- * ) undefined ;"
} ;
ARTICLE: "declarations" "Compiler declarations"
@ -192,6 +192,14 @@ HELP: deferred
{ deferred POSTPONE: DEFER: } related-words
HELP: undefined
{ $error-description "This error is thrown in two cases, and the debugger's summary message reflects the cause:"
{ $list
{ "A word was executed before being compiled. For example, this can happen if a macro is defined in the same compilation unit where it was used. See " { $link "compilation-units" } " for a discussion." }
{ "A word defined with " { $link POSTPONE: DEFER: } " was executed. Since this syntax is usually used for mutually-recursive word definitions, executing a deferred word usually indicates a programmer mistake." }
}
} ;
HELP: primitive
{ $description "The class of primitive words." } ;