core/macros/macros-docs.factor

   1 USING: help.markup help.syntax kernel
   2 stack-checker.transforms combinators ;
   3 IN: macros
   4
   5 HELP: MACRO:
   6 { $syntax "MACRO: word ( inputs... -- quot ) definition... ;" }
   7 { $description "Defines a macro word. The definition must have stack effect " { $snippet "( inputs... -- quot )" } "." }
   8 { $notes
   9   "A call of a macro inside a word definition is replaced with the quotation expansion at compile-time. The following two conditions must hold:"
  10   { $list
  11     { "All inputs to the macro call must be literals" }
  12     { "The expansion quotation produced by the macro has a static stack effect" }
  13   }
  14   "Macros allow computation to be moved from run-time to compile-time, splicing the result of this computation into the generated quotation."
  15 }
  16 { $examples
  17   "A macro that calls a quotation but preserves any values it consumes off the stack:"
  18   { $code
  19     "USING: fry generalizations kernel macros stack-checker ;"
  20     "MACRO: preserving ( quot -- quot' )"
  21     "    [ inputs ] keep '[ _ ndup @ ] ;"
  22   }
  23   "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:"
  24   { $code
  25     ": ifte ( pred true false -- ) [ preserving ] 2dip if ; inline"
  26   }
  27   "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."
  28   $nl
  29   "The " { $snippet "ifte" } " combinator presented here has similar semantics to the " { $snippet "ifte" } " combinator of the Joy programming language."
  30 } ;
  31
  32 HELP: macro
  33 { $class-description "Class of words defined with " { $link POSTPONE: MACRO: } "." } ;
  34
  35 ARTICLE: "macros" "Macros"
  36 "The " { $vocab-link "macros" } " vocabulary implements " { $emphasis "macros" } ", which are code transformations that may run at compile-time under the right circumstances."
  37 $nl
  38 "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."
  39 $nl
  40 "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."
  41 $nl
  42 "Factor macros are similar to Lisp macros; they are not like C preprocessor macros."
  43 $nl
  44 "Defining new macros:"
  45 { $subsections POSTPONE: MACRO: }
  46 "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."
  47 { $subsections define-transform }
  48 { $see-also "generalizations" "fry" } ;
  49
  50 ABOUT: "macros"