PageRenderTime 35ms CodeModel.GetById 25ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 0ms

/core/quotations/quotations-docs.factor

http://github.com/abeaumont/factor
Unknown | 79 lines | 68 code | 11 blank | 0 comment | 0 complexity | 14def7d9dcce2eae17367b4296e05cb2 MD5 | raw file
 1USING: arrays help.markup help.syntax strings sbufs
 2vectors kernel combinators ;
 3IN: quotations
 4
 5ARTICLE: "quotations" "Quotations"
 6"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" } "."
 7$nl
 8"Quotation literals appearing in source code are delimited by square brackets, for example " { $snippet "[ 2 + ]" } "; see " { $link "syntax-quots" } " for details on their syntax."
 9$nl
10"Quotations form a class of objects:"
11{ $subsections
12    quotation
13    quotation?
14}
15"A more general class is provided for methods to dispatch on that includes quotations, " { $link curry } ", and " { $link compose } " objects:"
16{ $subsections
17    callable
18}
19"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:"
20{ $subsections "wrappers" }
21"Quotations implement the " { $link "sequence-protocol" } ", and existing sequences can be converted into quotations:"
22{ $subsections
23    >quotation
24    1quotation
25}
26"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." ;
27
28ARTICLE: "wrappers" "Wrappers"
29"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."
30{ $subsections
31    wrapper
32    literalize
33}
34"Wrapper literal syntax is documented in " { $link "syntax-words" } "."
35{ $example
36  "IN: scratchpad"
37  "DEFER: my-word"
38  "\\ my-word name>> ."
39  "\"my-word\""
40}
41{ $see-also "combinators" } ;
42
43ABOUT: "quotations"
44
45HELP: callable
46{ $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 } "." } ;
47
48HELP: quotation
49{ $description "The class of quotations. See " { $link "syntax-quots" } " for syntax and " { $link "quotations" } " for general information." } ;
50
51HELP: >quotation
52{ $values { "seq" "a sequence" } { "quot" quotation } }
53{ $description "Outputs a freshly-allocated quotation with the same elements as a given sequence." } ;
54
55HELP: 1quotation
56{ $values { "obj" object } { "quot" quotation } }
57{ $description "Constructs a quotation holding one element." }
58{ $notes
59    "The following two phrases are equivalent:"
60    { $code "\\ reverse execute" }
61    { $code "\\ reverse 1quotation call" }
62} ;
63
64HELP: wrapper
65{ $description "The class of wrappers. Wrappers are created by calling " { $link literalize } ". See " { $link "syntax-words" } " for syntax." } ;
66
67HELP: <wrapper>
68{ $values { "obj" object } { "wrapper" wrapper } }
69{ $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)." } ;
70
71HELP: literalize
72{ $values { "obj" object } { "wrapped" object } }
73{ $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." }
74{ $examples
75    { $example "USING: prettyprint quotations ;" "5 literalize ." "5" }
76    { $example "USING: math prettyprint quotations sequences ;" "[ + ] [ literalize ] map ." "[ \\ + ]" }
77} ;
78
79{ literalize curry <wrapper> POSTPONE: \ POSTPONE: W{ } related-words