factor/basis/macros/macros-docs.factor

51 lines
3.3 KiB
Factor
Raw Normal View History

2009-02-06 11:22:09 -05:00
USING: help.markup help.syntax quotations kernel
2010-08-17 22:24:45 -04:00
stack-checker.transforms sequences combinators ;
2007-09-20 18:09:08 -04:00
IN: macros
HELP: MACRO:
{ $syntax "MACRO: word ( inputs... -- quot ) definition... ;" }
2010-08-17 22:24:45 -04:00
{ $description "Defines a macro word. The definition must have stack effect " { $snippet "( inputs... -- quot )" } "." }
2007-09-20 18:09:08 -04:00
{ $notes
2010-08-17 22:24:45 -04:00
"A call of a macro inside a word definition is replaced with the quotation expansion at compile-time. The following two conditions must hold:"
2009-02-06 11:22:09 -05:00
{ $list
2010-08-17 22:24:45 -04:00
{ "All inputs to the macro call must be literals" }
2009-02-06 11:22:09 -05:00
{ "The expansion quotation produced by the macro has a static stack effect" }
}
2010-08-17 22:24:45 -04:00
"Macros allow computation to be moved from run-time to compile-time, splicing the result of this computation into the generated quotation."
2009-02-06 11:22:09 -05:00
}
{ $examples
"A macro that calls a quotation but preserves any values it consumes off the stack:"
{ $code
"USING: fry generalizations kernel macros stack-checker ;"
"MACRO: preserving ( quot -- quot' )"
" [ inputs ] keep '[ _ ndup @ ] ;"
2009-02-06 11:22:09 -05:00
}
"Using this macro, we can define a variant of " { $link if } " which takes a predicate quotation instead of a boolean; any values consumed by the predicate quotation are restored immediately after:"
{ $code
": ifte ( pred true false -- ) [ preserving ] 2dip if ; inline"
}
"Note that " { $snippet "ifte" } " is an ordinary word, and it passes one of its inputs to the macro. If another word calls " { $snippet "ifte" } " with all three input quotations literal, then " { $snippet "ifte" } " will be inlined and " { $snippet "preserving" } " will expand at compile-time, and the generated machine code will be exactly the same as if the inputs consumed by the predicate were duplicated by hand."
$nl
"The " { $snippet "ifte" } " combinator presented here has similar semantics to the " { $snippet "ifte" } " combinator of the Joy programming language."
2007-09-20 18:09:08 -04:00
} ;
HELP: macro
{ $class-description "Class of words defined with " { $link POSTPONE: MACRO: } "." } ;
ARTICLE: "macros" "Macros"
2009-02-06 11:22:09 -05:00
"The " { $vocab-link "macros" } " vocabulary implements " { $emphasis "macros" } ", which are code transformations that may run at compile-time under the right circumstances."
$nl
2010-08-17 22:24:45 -04:00
"Macros can be used to implement combinators whose stack effects depend on an input parameter. Since macros are expanded at compile time, this permits the compiler to infer a static stack effect for the word calling the macro."
$nl
"Macros can also be used to calculate lookup tables and generate code at compile time, which can improve performance, raise the level of abstraction, and simplify code."
2009-02-06 11:22:09 -05:00
$nl
"Factor macros are similar to Lisp macros; they are not like C preprocessor macros."
2007-09-20 18:09:08 -04:00
$nl
"Defining new macros:"
{ $subsections POSTPONE: MACRO: }
2010-08-17 22:24:45 -04:00
"A slightly lower-level facility, " { $emphasis "compiler transforms" } ", allows an ordinary word definition to co-exist with a version that performs compile-time expansion. The ordinary definition is only used from code compiled with the non-optimizing compiler. Under normal circumstances, macros should be used instead of compiler transforms; compiler transforms are only used for words such as " { $link cond } " which are frequently invoked during the bootstrap process, and this having a performant non-optimized definition which does not generate code on the fly is important."
{ $subsections define-transform }
2009-05-01 03:03:22 -04:00
{ $see-also "generalizations" "fry" } ;
2007-09-20 18:09:08 -04:00
ABOUT: "macros"