source: project/wiki/eggref/5/combinators @ 39495

Last change on this file since 39495 was 39495, checked in by Alaric Snell-Pym, 8 weeks ago

combinators: copy docs from chicken 4 to chicken 5
File size: 11.5 KB
Line 
1[[tags: egg]]
2
3== combinators
4
5Combinators grab-bag.
6
7[[toc:]]
8
9
10== Documentation
11
12=== Section Combinators
13
14==== Usage
15
16<enscript language=scheme>
17(require-extension section-combinators)
18</enscript>
19
20{{FUNC}} a procedure.
21
22==== left-section
23
24<procedure>(left-section FUNC ARG0 ...) => procedure</procedure>
25
26Returns a procedure that partially applies some of its arguments from the left.
27
28{{ARG0 ...}} a prefix of the arguments for {{FUNC}}.
29
30Returns a partially curried procedure.
31
32==== right-section
33
34<procedure>(right-section FUNC ARG0 ...) => procedure</procedure>
35
36Returns a procedure that partially applies some of its arguments from the right.
37
38{{ARG0 ...}} a suffix of the arguments for {{FUNC}}.
39
40Returns a partially curried procedure.
41
42==== crop-left
43
44<procedure>(crop-left FUNC N) => procedure</procedure>
45
46Returns a procedure that drops the {{N}} left arguments before applying {{FUNC}}.
47
48==== crop-right
49
50<procedure>(crop-right FUNC N) => procedure</procedure>
51
52Returns a procedure that drops the {{N}} right arguments before applying {{FUNC}}.
53
54==== reversed
55
56<procedure>(reversed FUNC) => procedure</procedure>
57
58Returns a procedure that reverses the arguments before applying {{FUNC}}.
59
60==== arguments-chain
61
62<procedure>(arguments-chain [FUNC0...]) => procedure</procedure>
63
64Returns a procedure that applies each {{FUNCi}} to result of the {{FUNCi+1}}.
65{{FUNCn}} is applied to the arguments.
66
67Examples:
68
69 ((arguments-chain f g h) arg...) -> (apply f (apply g (apply h arg...)))
70
71 ((arguments-chain f) arg...) -> (apply f arg...)
72
73 ((arguments-chain) arg...) -> (list arg...)
74
75==== arguments-each
76
77<procedure>(arguments-each [FUNC0...]) => procedure</procedure>
78
79Returns a procedure that calls each {{FUNCi}} to the {{ARGi}}. The result is
80returned as a {{list}}. The {{FUNC0...}} are re-used until the argument list is
81exhausted.
82
83Examples:
84
85 ((arguments-each f g h) a b c d e) -> (list (f a) (g b) (h c) (f d) (g e))
86
87 ((arguments-each f g h) a b c) -> (list (f a) (g b) (h c))
88
89 ((arguments-each) arg...) -> (list arg...)
90
91==== arguments-all
92
93<procedure>(arguments-all [FUNC0...]) => procedure</procedure>
94
95Returns a procedure that calls each {{FUNCi}} with all the arguments. The
96result is returned as a {{list}}.
97
98Examples:
99
100 ((arguments-all f g h) a b c) -> (list (f a b c) (g a b c) (h a b c))
101
102 ((arguments-all) arg...) -> (list arg...)
103
104
105=== Sort Combinators
106
107Except for {{make-less-than/key}} and {{make-equal/key}} these are not combinators.
108
109==== Usage
110
111<enscript language=scheme>
112(require-extension sort-combinators)
113</enscript>
114
115==== Examples
116
117<enscript highlight=scheme>
118(group/key identity '(1 2 3 3 4 4 4)) ;=> ((1) (2) (3 3) (4 4 4))
119
120(group/key car '((a 1) (a 2) (b 1)))  ;=> '(((a 1) (a 2)) ((b 1)))
121
122(sort '(("a" . 1) ("z" . 3) ("b" . 2)) (make-less-than/key first string-ci<?)) ;=> (("a" . 1) ("b" . 2) ("z" . 3))
123</enscript>
124
125==== group-by
126
127<procedure>(group-by FUNC [EQUALITY equal?]) => procedure</procedure>
128
129Returns a procedure that takes a list and groups the elements by some key
130attribute. Uses the single-argument {{FUNC}} to retrieve key values & the
131{{EQUALITY}} function to compare them.
132
133==== group/key
134
135<procedure>(group/key FUNC LYST [EQUALITY equal?])</procedure>
136
137Groups a {{LYST}} of elements by some key attribute. Uses the single-argument
138{{FUNC}} to retrieve key values & the {{EQUALITY}} function to compare
139them.
140
141The {{LYST}} must be in sorted order with respect to the key!
142
143Returns a list of grouped elements.
144
145==== make-less-than/key
146
147<procedure>(make-less-than/key FUNC [LESS-THAN <]) => {{procedure/2}}</procedure>
148
149Returns a two-argument procedure that uses the single-argument {{FUNC}} to
150retrieve key values & the two-argument {{LESS-THAN}} procedure to compare them.
151
152==== make-equal/key
153
154<procedure>(make-equal/key FUNC [EQUAL =]) => {{procedure/2}}</procedure>
155
156Returns a two-argument procedure that uses the single-argument {{FUNC}} to
157retrieve key values & the two-argument {{EQUAL}} procedure to compare them.
158
159
160=== Logical Combinators
161
162==== Usage
163
164<enscript language=scheme>
165(require-extension logical-combinators)
166</enscript>
167
168==== andf
169
170<procedure>(andf OBJECT...)</procedure>
171
172Eager version of {{and}}.
173
174Returns last {{(not #f)}} {{OBJECT}} when all {{OBJECT...}} are {{(not #f)}},
175{{#f}} otherwise.
176
177==== orf
178
179<procedure>(orf OBJECT...)</procedure>
180
181Eager version of {{or}}.
182
183Returns first {{(not #f)}} {{OBJECT}}, {{#f}} otherwise.
184
185
186=== Uni Combinators
187
188{{C}} is a {{function}}.
189
190{{F}}, {{G}} and {{H}} are {{function}}.
191
192==== Usage
193
194<enscript language=scheme>
195(require-extension uni-combinators)
196</enscript>
197
198==== uni
199
200<procedure>(uni C F) => procedure</procedure>
201
202Returns {{(lambda (X) (C (F X)))}}.
203
204==== uni2
205
206<procedure>(uni2 C F) => procedure</procedure>
207
208Returns {{(lambda (X Y) (C (F X Y)))}}.
209
210==== uni3
211
212<procedure>(uni3 C F) => procedure</procedure>
213
214Returns {{(lambda (X Y Z) (C (F X Y Z)))}}.
215
216==== uni-each
217
218<procedure>(uni-each C F) => procedure</procedure>
219
220Same as {{uni}}.
221
222==== uni-all
223
224<procedure>(uni-all C F) => procedure</procedure>
225
226Returns {{(lambda XS (C (apply F XS)))}}.
227
228
229=== Bi Combinators
230
231==== Usage
232
233<enscript language=scheme>
234(require-extension bi-combinators)
235</enscript>
236
237==== bi
238
239<procedure>(bi C F G) => procedure</procedure>
240
241Returns {{(lambda (X) (C (F X) (G X)))}}.
242
243==== bi2
244
245<procedure>(bi2 C F G) => procedure</procedure>
246
247Returns {{(lambda (X Y) (C (F X Y) (G X Y)))}}.
248
249==== bi3
250
251<procedure>(bi3 C F G) => procedure</procedure>
252
253Returns {{(lambda (X Y Z) (C (F X Y Z) (G X Y Z)))}}.
254
255==== bi-each
256
257<procedure>(bi-each C F) => procedure</procedure>
258
259Returns {{(lambda (X Y) (C (F X) (F Y)))}}.
260
261==== bi-all
262
263<procedure>(bi-all C F G) => procedure</procedure>
264
265Returns {{(lambda XS (C (apply F XS) (apply G XS)))}}.
266
267
268=== Tri Combinators
269
270==== Usage
271
272<enscript language=scheme>
273(require-extension tri-combinators)
274</enscript>
275
276==== tri
277
278<procedure>(tri C F G H) => procedure</procedure>
279
280Returns {{(lambda (X) (C (F X) (G X) (H X)))}}.
281
282==== tri2
283
284<procedure>(tri2 C F G H) => procedure</procedure>
285
286Returns {{(lambda (X Y) (C (F X Y) (G X Y) (H X Y)))}}.
287
288==== tri3
289
290<procedure>(tri3 C F G H) => procedure</procedure>
291
292Returns {{(lambda (X Y Z) (C (F X Y Z) (G X Y Z) (H X Y Z)))}}.
293
294==== tri-each
295
296<procedure>(tri-each C F) => procedure</procedure>
297
298Returns {{(lambda (X Y Z) (C (F X) (F Y) (F Z)))}}.
299
300==== tri-all
301
302<procedure>(tri-all C F G H) => procedure</procedure>
303
304Returns {{(lambda XS (C (apply F XS) (apply G XS) (apply H XS)))}}.
305
306
307=== Stack Combinators
308
309These treat the argument list as a FORTH-like stack.
310
311The utility is probably low.
312
313==== Usage
314
315<enscript language=scheme>
316(require-extension stack-combinators)
317</enscript>
318
319{{C}} is a {{function}}.
320
321{{F}}, {{G}} and {{H}} are {{function}}.
322
323{{X}}, {{Y}} and {{Z}} are {{object}}.
324
325==== uni
326
327<procedure>(uni X F C) => procedure</procedure>
328
329Returns the result of {{(C (F X))}}.
330
331<procedure>(uni F C) => {{procedure/1}}</procedure>
332<procedure>(uni C) => {{procedure/1}}</procedure>
333<procedure>(uni) => {{procedure/1}}</procedure>
334
335Returns a curried procedure.
336
337==== uni2
338
339<procedure>(uni2 X Y F C) => procedure</procedure>
340
341Returns the result of {{(C (F X Y))}}.
342
343<procedure>(uni2 F C) => {{procedure/2}}</procedure>
344<procedure>(uni2 C) => {{procedure/1}}</procedure>
345<procedure>(uni2) => {{procedure/1}}</procedure>
346
347Returns a curried procedure.
348
349==== uni3
350
351<procedure>(uni3 X Y Z F C) => procedure</procedure>
352
353Returns the result of {{(C (F X Y Z))}}.
354
355<procedure>(uni3 F C) => {{procedure/3}}</procedure>
356<procedure>(uni3 C) => {{procedure/1}}</procedure>
357<procedure>(uni3) => {{procedure/1}}</procedure>
358
359Returns a curried procedure.
360
361==== uni@
362
363<procedure>(uni@ X F C) => procedure</procedure>
364
365Returns the result of {{(C (F X))}}.
366
367<procedure>(uni@ F C) => {{procedure/1}}</procedure>
368
369Returns a curried procedure.
370
371==== bi
372
373<procedure>(bi X F G C) => procedure</procedure>
374
375Returns the result of {{(C (F X) (G X))}}.
376
377<procedure>(bi F G C) => {{procedure/1}}</procedure>
378<procedure>(bi F G) => {{procedure/1}}</procedure>
379<procedure>(bi C) => {{procedure/2}}</procedure>
380<procedure>(bi) => {{procedure/1}}</procedure>
381
382Returns a curried procedure.
383
384==== bi2
385
386<procedure>(bi2 X Y F G C) => procedure</procedure>
387
388Returns the result of {{(C (F X Y) (G X Y))}}.
389
390<procedure>(bi2 F G C) => {{procedure/2}}</procedure>
391<procedure>(bi2 F G) => {{procedure/1}}</procedure>
392<procedure>(bi2 C) => {{procedure/2}}</procedure>
393<procedure>(bi2) => {{procedure/1}}</procedure>
394
395Returns a curried procedure.
396
397==== bi3
398
399<procedure>(bi3 X Y Z F G C) => procedure</procedure>
400
401Returns the result of {{(C (F X Y Z) (G X Y Z))}}.
402
403<procedure>(bi3 F G C) => {{procedure/3}}</procedure>
404<procedure>(bi3 F G) => {{procedure/1}}</procedure>
405<procedure>(bi3 C) => {{procedure/2}}</procedure>
406<procedure>(bi3) => {{procedure/1}}</procedure>
407
408Returns a curried procedure.
409
410==== bi@
411
412<procedure>(bi@ X Y F C) => procedure</procedure>
413
414Returns the result of {{(C (F X) (F Y))}}.
415
416<procedure>(bi@ F C) => {{procedure/2}}</procedure>
417
418Returns a curried procedure.
419
420==== tri
421
422<procedure>(tri X F G H C) => procedure</procedure>
423
424Returns the result of {{(C (F X) (G X) (H X))}}.
425
426<procedure>(tri F G H C) => {{procedure/1}}</procedure>
427<procedure>(tri F G H) => {{procedure/1}}</procedure>
428<procedure>(tri C) => {{procedure/3}}</procedure>
429<procedure>(tri) => {{procedure/1}}</procedure>
430
431Returns a curried procedure.
432
433==== tri2
434
435<procedure>(tri2 X Y F G H C) => procedure</procedure>
436
437Returns the result of {{(C (F X Y) (G X Y) (H X Y))}}.
438
439<procedure>(tri2 F G H C) => {{procedure/2}}</procedure>
440<procedure>(tri2 F G H) => {{procedure/1}}</procedure>
441<procedure>(tri2 C) => {{procedure/3}}</procedure>
442<procedure>(tri2) => {{procedure/1}}</procedure>
443
444Returns a curried procedure.
445
446==== tri3
447
448<procedure>(tri3 X Y Z F G H C) => procedure</procedure>
449
450Returns the result of {{(C (F X Y Z) (G X Y Z) (H X Y Z))}}.
451
452<procedure>(tri3 F G H C) => {{procedure/3}}</procedure>
453<procedure>(tri3 F G H) => {{procedure/1}}</procedure>
454<procedure>(tri3 C) => {{procedure/3}}</procedure>
455<procedure>(tri3) => {{procedure/1}}</procedure>
456
457Returns a curried procedure.
458
459==== tri@
460
461<procedure>(tri@ X Y Z F C) => procedure</procedure>
462
463Returns the result of {{(C (F X) (F Y) (F Z))}}.
464
465<procedure>(tri@ F C) => {{procedure/3}}</procedure>
466
467Returns a curried procedure.
468
469==== dip
470
471<procedure>(dip X Y F C) => procedure</procedure>
472
473Returns the result of {{(C (F X) Y)}}.
474
475<procedure>(dip F C) => {{procedure/2}}</procedure>
476
477Returns a curried procedure.
478
479==== dup
480
481<procedure>(dup X C) => procedure</procedure>
482
483Returns the result of {{(C X X)}}.
484
485<procedure>(dup C) => {{procedure/1}}</procedure>
486
487Returns a curried procedure.
488
489==== dupd
490
491<procedure>(dupd X Y C) => procedure</procedure>
492
493Returns the result of {{(C X X Y)}}.
494
495<procedure>(dupd C) => {{procedure/2}}</procedure>
496
497Returns a curried procedure.
498
499==== swap
500
501<procedure>(swap X Y C) => procedure</procedure>
502
503Returns the result of {{(C Y X)}}.
504
505<procedure>(swap C) => {{procedure/2}}</procedure>
506
507Returns a curried procedure.
508
509==== drop
510
511<procedure>(drop X C) => procedure</procedure>
512
513Returns the result of {{(C)}}.
514
515<procedure>(drop C) => {{procedure/1}}</procedure>
516
517Returns a curried procedure.
518
519==== drop/2
520
521<procedure>(drop/2 X Y C) => procedure</procedure>
522
523Returns the result of {{(C X)}}.
524
525<procedure>(drop/2 C) => {{procedure/2}}</procedure>
526
527Returns a curried procedure.
528
529
530== Notes
531
532* Inspired by e-mail conversations with Graham Fawcett in Feb '08.
533
534* The procedures {{left-section}} and {{right-section}} from Philip L. Bewig.
535
536
537== Author
538
539[[/users/kon-lovett|Kon Lovett]]
540
541
542== Version history
543
544; 1.2.0 : Added {{uni/bi/tri-combinators}} & more {{section-combinators}}.
545; 1.1.0 : Added {{section-combinators}}.
546; 1.0.0 : Chicken 4 release.
547
548
549== License
550
551Public Domain.
Note: See TracBrowser for help on using the repository browser.