core/quotations/quotations-docs.factor

   1 USING: help.markup help.syntax kernel sequences ;
   2 IN: quotations
   3
   4 ARTICLE: "quotations" "Quotations"
   5 "A quotation is an anonymous function (a value denoting a snippet of code) which can be used as a value and called using the " { $link "call" } "."
   6 $nl
   7 "Quotation literals appearing in source code are delimited by square brackets, for example " { $snippet "[ 2 + ]" } "; see " { $link "syntax-quots" } " for details on their syntax."
   8 $nl
   9 "Quotations form a class of objects:"
  10 { $subsections
  11     quotation
  12     quotation?
  13 }
  14 "A more general class is provided for methods to dispatch on that includes quotations, " { $link curry } ", and " { $link compose } " objects:"
  15 { $subsections
  16     callable
  17 }
  18 "Quotations evaluate sequentially from beginning to end. Literals are pushed on the stack and words are executed. Details can be found in " { $link "evaluator" } ". Words can be placed in wrappers to suppress execution:"
  19 { $subsections "wrappers" }
  20 "Quotations implement the " { $link "sequence-protocol" } ", and existing sequences can be converted into quotations:"
  21 { $subsections
  22     >quotation
  23     1quotation
  24 }
  25 "Although quotations can be treated as sequences, the compiler will be unable to reason about quotations manipulated as sequences at runtime. " { $link "compositional-combinators" } " are provided for runtime partial application and composition of quotations." ;
  26
  27 ARTICLE: "wrappers" "Wrappers"
  28 "Wrappers evaluate to the object being wrapped when encountered in code. They are used to suppress the execution of " { $link "words" } " so that they can be used as values."
  29 { $subsections
  30     wrapper
  31     literalize
  32 }
  33 "Wrapper literal syntax is documented in " { $link "syntax-words" } "."
  34 { $example
  35   "IN: scratchpad"
  36   "DEFER: my-word"
  37   "\\ my-word name>> ."
  38   "\"my-word\""
  39 }
  40 { $see-also "combinators" } ;
  41
  42 ABOUT: "quotations"
  43
  44 HELP: callable
  45 { $class-description "The class whose instances can be passed to " { $link call } ". This includes quotations and composed quotations built up with " { $link curry } " or " { $link compose } "." } ;
  46
  47 HELP: quotation
  48 { $class-description "The class of quotations. See " { $link "syntax-quots" } " for syntax and " { $link "quotations" } " for general information." } ;
  49
  50 HELP: >quotation
  51 { $values { "seq" sequence } { "quot" quotation } }
  52 { $description "Outputs a freshly-allocated quotation with the same elements as a given sequence." } ;
  53
  54 HELP: 1quotation
  55 { $values { "obj" object } { "quot" quotation } }
  56 { $description "Constructs a quotation holding one element." }
  57 { $notes
  58     "The following two phrases are equivalent:"
  59     { $code "\\ reverse execute" }
  60     { $code "\\ reverse 1quotation call" }
  61 } ;
  62
  63 HELP: wrapper
  64 { $class-description "The class of wrappers. Wrappers are created by calling " { $link literalize } ". See " { $link "syntax-words" } " for syntax." } ;
  65
  66 HELP: <wrapper>
  67 { $values { "obj" object } { "wrapper" wrapper } }
  68 { $description "Creates an object which pushes " { $snippet "obj" } " on the stack when evaluated. User code should call " { $link literalize } " instead, since it avoids wrapping self-evaluating objects (which is redundant)." } ;
  69
  70 HELP: literalize
  71 { $values { "obj" object } { "wrapped" object } }
  72 { $description "Outputs an object which evaluates to " { $snippet "obj" } " when placed in a quotation. If " { $snippet "obj" } " is not self-evaluating (for example, it is a word), then it will be wrapped." }
  73 { $examples
  74     { $example "USING: prettyprint quotations ;" "5 literalize ." "5" }
  75     { $example "USING: math prettyprint quotations sequences ;" "[ + ] [ literalize ] map ." "[ \\ + ]" }
  76 } ;
  77
  78 { literalize curry <wrapper> POSTPONE: \ POSTPONE: W{ } related-words