1 ! Copyright (C) 2009 Doug Coleman.
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: classes.tuple help.markup help.syntax kernel math
4 quotations sequences stack-checker arrays ;
12 { $description "Infers the number of inputs, " { $snippet "n" } ", to " { $snippet "quot" } " and calls the " { $snippet "quot" } " with the first " { $snippet "n" } " values from a sequence." }
15 "USING: combinators.smart math prettyprint ;"
16 "{ 1 2 3 } [ + + ] input<sequence ."
26 { $description "Infers the number of outputs from the quotation and constructs an array from those outputs." }
29 "USING: combinators combinators.smart math prettyprint ;
31 { [ 1 - ] [ 1 + ] [ sq ] } cleave
39 { "quot" quotation } { "exemplar" "an exemplar" }
42 { $description "Infers the number of outputs from the quotation and constructs a new sequence from those objects of the same type as the exemplar." }
45 "USING: combinators.smart kernel math prettyprint ;"
46 "4 [ [ 1 + ] [ 2 + ] [ 3 + ] tri ] V{ } output>sequence ."
53 { "quot" quotation } { "operation" quotation }
55 { $description "Infers the number of outputs from " { $snippet "quot" } " and reduces them using " { $snippet "operation" } ". The identity for the " { $link reduce } " operation is the first output." }
58 "USING: combinators.smart kernel math prettyprint ;"
59 "3 [ [ 4 * ] [ 4 / ] [ 4 - ] tri ] [ * ] reduce-outputs ."
69 { $description "Infers the number of outputs from " { $snippet "quot" } " and returns their sum." }
72 "USING: combinators.smart kernel math prettyprint ;"
73 "10 [ [ 1 - ] [ 1 + ] bi ] sum-outputs ."
83 { $description "Infers the number of outputs from " { $snippet "quot" } " and returns a sequence of the outputs appended." }
86 "USING: combinators.smart prettyprint ;"
87 "[ { 1 2 } { \"A\" \"b\" } ] append-outputs ."
92 HELP: append-outputs-as
94 { "quot" quotation } { "exemplar" sequence }
97 { $description "Infers the number of outputs from " { $snippet "quot" } " and returns a sequence of type " { $snippet "exemplar" } " of the outputs appended." }
100 "USING: combinators.smart prettyprint ;"
101 "[ { 1 2 } { \"A\" \"b\" } ] V{ } append-outputs-as ."
102 "V{ 1 2 \"A\" \"b\" }"
106 { append-outputs append-outputs-as } related-words
109 { $values { "quot" quotation } }
110 { $description "Calls a quotation and drops any values it leaves on the stack." } ;
113 { $values { "quot" quotation } }
114 { $description "Calls a quotation and preserves any values it takes off the stack." } ;
116 { drop-outputs keep-inputs } related-words
121 { "quot'" quotation }
123 { $description "Outputs a quotation that, when called, will have the effect of dropping the number of inputs to the original quotation." }
126 """USING: combinators.smart math prettyprint ;
127 [ + + ] dropping ."""
132 HELP: input<sequence-unsafe
137 { $description "An unsafe version of " { $link input<sequence-unsafe } "." } ;
139 HELP: map-reduce-outputs
141 { "quot" quotation } { "mapper" quotation } { "reducer" quotation }
143 { $description "Infers the number of outputs from " { $snippet "quot" } " and, treating those outputs as a sequence, calls " { $link map-reduce } " on them." }
146 """USING: math combinators.smart prettyprint ;
147 [ 1 2 3 ] [ sq ] [ + ] map-reduce-outputs ."""
156 { $description "Infers the number of inputs to a quotation and drops them from the stack." }
159 """USING: combinators.smart kernel math ;
168 { $description "Calls a quotation and leaves any consumed inputs on the stack beneath the quotation's outputs." }
171 """USING: combinators.smart kernel math prettyprint ;
172 1 2 [ + ] preserving [ . ] tri@"""
181 { "quot" quotation } { "n" integer }
183 { $description "Applies a quotation to the datastack " { $snippet "n" } " times, starting lower on the stack and working up in increments of the number of inferred inputs to the quotation." }
186 """USING: combinators.smart prettyprint math kernel ;
187 1 2 3 4 [ + ] 2 smart-apply [ . ] bi@"""
195 { "pred" quotation } { "true" quotation } { "false" quotation }
197 { $description "A version of " { $link if } " that takes three quotations, where the first quotation is a predicate that preserves any inputs it consumes." } ;
201 { "pred" quotation } { "true" quotation } { "false" quotation }
203 { $description "A version of " { $link if } " that takes three quotations, where the first quotation is a predicate that preserves any inputs it consumes, the second is the " { $snippet "true" } " branch, and the third is the " { $snippet "false" } " branch. If the " { $snippet "true" } " branch is taken, the values are left on the stack and the quotation is called. If the " { $snippet "false" } " branch is taken, the number of inputs inferred from predicate quotation is dropped and the quotation is called." } ;
207 { "pred" quotation } { "false" quotation }
209 { $description "A version of " { $link unless } " that takes two quotations, where the first quotation is a predicate that preserves any inputs it consumes and the second is the " { $snippet "false" } " branch." } ;
213 { "pred" quotation } { "false" quotation }
215 { $description "A version of " { $link unless } " that takes two quotations, where the first quotation is a predicate that preserves any inputs it consumes and the second is the " { $snippet "false" } " branch. If the " { $snippet "true" } " branch is taken, the values are left on the stack. If the " { $snippet "false" } " branch is taken, the number of inputs inferred from predicate quotation is dropped and the quotation is called." } ;
219 { "pred" quotation } { "true" quotation }
221 { $description "A version of " { $link when } " that takes two quotations, where the first quotation is a predicate that preserves any inputs it consumes and the second is the " { $snippet "true" } " branch." } ;
225 { "pred" quotation } { "true" quotation }
227 { $description "A version of " { $link when } " that takes two quotations, where the first quotation is a predicate that preserves any inputs it consumes and the second is the " { $snippet "true" } " branch. If the " { $snippet "true" } " branch is taken, the values are left on the stack and the quotation is called. If the " { $snippet "false" } " branch is taken, the number of inputs inferred from predicate quotation is dropped." } ;
231 { "param" object } { "obj" object } { "quot" { $quotation "( param ..a -- ..b )" } } { "curry" curry } }
232 { $description "A version of " { $link with } " that puts the parameter before any inputs the quotation uses." } ;
235 { $values { "reduce-quots" sequence } }
236 { $description "A version of " { $link reduce } " that takes a sequence of " { $snippet "{ identity reduce-quot }" } " pairs, returning the " { $link reduce } " result for each pair." } ;
238 HELP: smart-map-reduce
239 { $values { "map-reduce-quots" sequence } }
240 { $description "A version of " { $link map-reduce } " that takes a sequence of " { $snippet "{ map-quot reduce-quot }" } " pairs, returning the " { $link map-reduce } " result for each pair." } ;
243 { $values { "2reduce-quots" sequence } }
244 { $description "A version of " { $link 2reduce } " that takes a sequence of " { $snippet "{ identity 2reduce-quot }" } " pairs, returning the " { $link 2reduce } " result for each pair." } ;
246 HELP: smart-2map-reduce
247 { $values { "2map-reduce-quots" sequence } }
248 { $description "A version of " { $link 2map-reduce } " that takes a sequence of " { $snippet "{ 2map-quot 2reduce-quot }" } " pairs, returning the " { $link 2map-reduce } " result for each pair." } ;
250 ARTICLE: "combinators.smart" "Smart combinators"
251 "A " { $emphasis "smart combinator" } " is a macro which reflects on the stack effect of an input quotation. The " { $vocab-link "combinators.smart" } " vocabulary implements a few simple smart combinators which look at the static stack effects of input quotations and generate code which produces or consumes the relevant number of stack values." $nl
252 "Take all input values from a sequence:"
255 input<sequence-unsafe
257 "Store all output values to a sequence:"
262 "Reducing the set of output values:"
267 "Applying a quotation to groups of elements on the stack:"
268 { $subsections smart-apply }
269 "Summing output values:"
270 { $subsections sum-outputs }
271 "Concatenating output values:"
276 "Drop the outputs after calling a quotation:"
277 { $subsections drop-outputs }
278 "Cause a quotation to act as a no-op and drop the inputs:"
279 { $subsection nullary }
280 "Preserve the inputs below or above the outputs of the quotation:"
281 { $subsections preserving keep-inputs }
282 "Versions of if that infer how many inputs to keep from the predicate quotation:"
283 { $subsections smart-if smart-when smart-unless }
284 "Versions of if* that infer how many inputs to keep from the predicate quotation:"
285 { $subsections smart-if* smart-when* smart-unless* }
286 "New smart combinators can be created by defining " { $link "macros" } " which call " { $link infer } "." ;
288 ABOUT: "combinators.smart"