basis/macros/macros-docs.factor

   1 USING: help.markup help.syntax quotations kernel ;
   2 IN: macros
   3
   4 HELP: MACRO:
   5 { $syntax "MACRO: word ( inputs... -- ) definition... ;" }
   6 { $description "Defines a compile-time code transformation. If all inputs to the word are literal and the word calling the macro has a static stack effect, then the macro body is invoked at compile-time to produce a quotation; this quotation is then spliced into the compiled code. If the inputs are not literal, or if the word is invoked from a word which does not have a static stack effect, the macro body will execute every time and the result will be passed to " { $link call } "."
   7 $nl
   8 "The stack effect declaration must be present because it tells the compiler how many literal inputs to expect."
   9 }
  10 { $notes
  11     "Semantically, the following two definitions are equivalent:"
  12     { $code "MACRO: foo ... ;" }
  13     { $code ": foo ... call ;" }
  14     "However, the compiler folds in macro definitions at compile-time where possible; if the macro body performs an expensive calculation, it can lead to a performance boost."
  15 } ;
  16
  17 HELP: macro
  18 { $class-description "Class of words defined with " { $link POSTPONE: MACRO: } "." } ;
  19
  20 ARTICLE: "macros" "Macros"
  21 "The " { $vocab-link "macros" } " vocabulary implements macros in the Lisp sense; compile-time code transformers and generators. Macros can be used to calculate lookup tables and generate code at compile time, which can improve performance, the level of abstraction and simplify code."
  22 $nl
  23 "Defining new macros:"
  24 { $subsection POSTPONE: MACRO: }
  25 "Macros are really just a very thin layer of syntax sugar over " { $link "compiler-transforms" } "." ;
  26
  27 ABOUT: "macros"