core/quotations/quotations-docs.factor

   1 USING: arrays help.markup help.syntax strings sbufs
   2 vectors kernel combinators ;
   3 IN: quotations
   4
   5 ARTICLE: "quotations" "Quotations"
   6 "Conceptually, a quotation is an anonymous function (a value denoting a snippet of code) which can be passed around and called."
   7 $nl
   8 "Concretely, a quotation is an immutable sequence of objects, some of which may be words, together with a block of machine code which may be executed to achieve the effect of evaluating the quotation. The machine code is generated by a fast non-optimizing quotation compiler which is always running and is transparent to the developer."
   9 $nl
  10 "Quotations form a class of objects, however in most cases, methods should dispatch on " { $link callable } " instead, so that " { $link curry } " and " { $link compose } " values can participate."
  11 { $subsection quotation }
  12 { $subsection quotation? }
  13 "Quotations evaluate sequentially from beginning to end. Literals are pushed on the stack and words are executed. Details can be found in " { $link "evaluator" } "."
  14 $nl
  15 "Quotation literal syntax is documented in " { $link "syntax-quots" } "."
  16 $nl
  17 "Quotations implement the " { $link "sequence-protocol" } ", and existing sequences can be converted into quotations:"
  18 { $subsection >quotation }
  19 { $subsection 1quotation }
  20 "Wrappers:"
  21 { $subsection "wrappers" } ;
  22
  23 ARTICLE: "wrappers" "Wrappers"
  24 "Wrappers are used to push words on the data stack; they evaluate to the object being wrapped:"
  25 { $subsection wrapper }
  26 { $subsection literalize }
  27 { $see-also "combinators" } ;
  28
  29 ABOUT: "quotations"
  30
  31 HELP: callable
  32 { $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 } "." } ;
  33
  34 HELP: quotation
  35 { $description "The class of quotations. See " { $link "syntax-quots" } " for syntax and " { $link "quotations" } " for general information." } ;
  36
  37 HELP: >quotation
  38 { $values { "seq" "a sequence" } { "quot" quotation } }
  39 { $description "Outputs a freshly-allocated quotation with the same elements as a given sequence." } ;
  40
  41 HELP: 1quotation
  42 { $values { "obj" object } { "quot" quotation } }
  43 { $description "Constructs a quotation holding one element." }
  44 { $notes
  45     "The following two phrases are equivalent:"
  46     { $code "\\ reverse execute" }
  47     { $code "\\ reverse 1quotation call" }
  48 } ;
  49
  50 HELP: wrapper
  51 { $description "The class of wrappers. Wrappers are created by calling " { $link literalize } ". See " { $link "syntax-words" } " for syntax." } ;
  52
  53 HELP: <wrapper> ( obj -- wrapper )
  54 { $values { "obj" object } { "wrapper" wrapper } }
  55 { $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)." } ;
  56
  57 HELP: literalize
  58 { $values { "obj" object } { "wrapped" object } }
  59 { $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." }
  60 { $examples
  61     { $example "USING: prettyprint quotations ;" "5 literalize ." "5" }
  62     { $example "USING: math prettyprint quotations sequences ;" "[ + ] [ literalize ] map ." "[ \\ + ]" }
  63 } ;
  64
  65 { literalize curry <wrapper> POSTPONE: \ POSTPONE: W{ } related-words