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, 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 interpreted code, 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 HELP: macro-expand
  21 { $values { "..." "inputs to a macro" } { "word" macro } { "quot" quotation } }
  22 { $description "Expands a macro. Useful for debugging." }
  23 { $examples
  24     { $code "USING: math macros combinators.lib ;" "{ [ integer? ] [ 0 > ] [ 13 mod zero? ] } \ 1&& macro-expand ." }
  25 } ;
  26
  27 ARTICLE: "macros" "Macros"
  28 "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."
  29 $nl
  30 "Defining new macros:"
  31 { $subsection POSTPONE: MACRO: }
  32 "Expanding macros for debugging purposes:"
  33 { $subsection macro-expand }
  34 "Macros are really just a very thin layer of syntax sugar over " { $link "compiler-transforms" } "." ;
  35
  36 ABOUT: "macros"