source: project/wiki/eggref/5/clojurian @ 37636

Last change on this file since 37636 was 37545, checked in by Moritz Heidkamp, 9 months ago

clojurian: Update C5 documentation with the correct module names

File size: 6.6 KB
Line 
1[[tags: egg]]
2
3== clojurian
4
5A collection of modules providing syntax and utility functions
6inspired by [[http://clojure.com|Clojure]].
7
8[[toc:]]
9
10=== Overview
11
12Currently this egg provides two modules: {{(clojurian syntax)}} and
13{{(clojurian atom)}}.
14
15=== Modules
16
17==== {{(clojurian syntax)}}
18
19<syntax>(doto val (proc args ...) ...)</syntax>
20
21Inserts {{val}} as the first argument of each {{(proc args ...)}}
22clause (i.e. right after {{proc}}). Returns {{val}}. This is useful
23e.g. for mutating a record on initialization.
24
25Example:
26
27<enscript highlight="scheme">
28(define boolean-vector
29  (doto (make-vector 100)
30        (vector-fill! #t 0 50)
31        (vector-fill! #f 50)))
32=>
33
34(define boolean-vector
35  (let ((vec (make-vector 100)))
36    (vector-fill! vec #t 0 50)
37    (vector-fill! vec #f 50)
38    vec))
39</enscript>
40
41
42
43<syntax>(-> val (proc args ...) ...)</syntax>
44<syntax>(->* val (proc args ...) ...)</syntax>
45
46Inserts {{val}} as the first argument of the first {{(proc args ...)}}
47clause. The resulting form is then inserted as the first argument of
48the following {{proc}} form and so on. This is known as the ''thrush
49combinator''. The starred version ({{->*}}) is multi value aware,
50i.e. each form's return values are spliced into the argument list of
51the successing form. As a shorthand it is also possible to pass
52{{proc}} instead of {{(proc)}}.
53
54Single value example:
55
56<enscript highlight="scheme">
57
58(-> 10 (- 2) (/ 5) (* 3))
59
60=>
61
62(* (/ (- 10 2) 5) 3)
63</enscript>
64
65Multi value example:
66
67<enscript highlight="scheme">
68
69(->* (values 1 2) (list))
70
71=>
72
73(receive args (values 1 2) (apply list args))
74</enscript>
75
76
77<syntax>(->> val (proc args ...) ...)</syntax>
78<syntax>(->>* val (proc args ...) ...)</syntax>
79
80Works just like {{->}} and {{->*}} only that the forms are inserted at
81the end of each successive clause's argument list.
82
83Example:
84
85<enscript highlight="scheme">
86(->> (iota 10)
87     (map add1)
88     (fold + 0)
89     (print))
90
91=>
92
93(print
94 (fold + 0
95  (map add1
96   (iota 10))))
97</enscript>
98
99
100<syntax>(as-> val name forms ...)</syntax>
101
102Evaluates {{forms}} in order in a scope where {{name}} is bound to
103{{val}} for the first form, the result of that for the second form,
104the result of that for the third form, and so forth. Returns the
105result of the last form.
106
107Examples:
108
109<enscript highlight="scheme">
110(as-> 3 x (+ x 7) (/ x 2)) => 5
111</enscript>
112
113It's mainly useful in combination with {{->}}:
114
115<enscript highlight="scheme">
116(-> 10 (+ 3) (+ 7) (as-> x (/ 200 x))) => 10
117</enscript>
118
119
120<syntax>(and-> val forms ...)</syntax>
121
122Works just like {{->}} but will return {{#f}} in case {{val}} or any
123of the {{forms}} evaluates to {{#f}}.
124
125Examples:
126
127<enscript highlight="scheme">
128(define some-alist '((a . 1) (b . 2)))
129
130(and-> 'b (assq some-alist) cdr add1) => 3
131
132(and-> 'c (assq some-alist) cdr add1) => #f
133</enscript>
134
135This syntax is essentially a shortcut for certain uses of
136{{and-let*}}, e.g. the above example would often be expressed like
137this:
138
139<enscript highlight="scheme">
140(and-let* ((x 'b)
141           (x (assq x some-alist))
142           (x (cdr x)))
143  (add1 x))
144</enscript>
145
146
147
148<syntax>(if-let (var val) then else)</syntax>
149
150Equivalent to {{(let ((var val)) (if var then else))}}.
151
152
153<syntax>(if-let* ((x1 y1) (x2 y2) ...) then else)</syntax>
154
155Similar to {{(or (and-let* ((x1 y1) (x2 y2) ...) then) else)}} except
156that returning {{#f}} from the {{then}} clause will not lead to the
157{{else}} clause being evaluated.
158
159
160==== {{(clojurian atom)}} (experimental)
161
162This module provides an implementation of
163[[http://clojure.org/atoms|Clojure's atom reference type]]. It is in
164an experimental state right now and only provides the very basic
165functionality, e.g. validators and watches are still missing. Note
166that atoms only work with immutable data structures so they can't be
167used to coordinate updates of record slots, for example.
168
169
170<procedure>(atom value)</procedure>
171
172Returns and atom with the given initial {{value}}.
173
174
175<procedure>(atom? x)</procedure>
176
177Checks whether {{x}} is an atom.
178
179
180<procedure>(atom-value atom)</procedure>
181
182Returns the current value of {{atom}}.
183
184
185<procedure>(atom-compare-and-set! atom old new)</procedure>
186
187Atomically sets the value of {{atom}} to {{new}} if its current value
188is {{eq?}} to the given {{old}} value. Returns {{#t}} if the update
189was successful and {{#f}} if not.
190
191
192<procedure>(atom-swap! atom proc . args)</procedure>
193
194Atomically swaps the value of {{atom}} to be {{(apply proc (atom-value
195atom) args)}}. Because {{proc}} may be called multiple times it must
196be free of side-effects. Returns the new value of {{atom}}.
197
198
199<procedure>(atom-reset! atom value)</procedure>
200
201Sets the value of {{atom}} to {{value}}. Returns {{value}}.
202
203
204=== About this egg
205
206==== Source
207
208The [[https://bitbucket.org/DerGuteMoritz/clojurian|source code is
209hosted at Bitbucket]]. Feel free to fork it and send pull requests
210there.
211
212==== Authors
213
214[[/users/moritz-heidkamp|Moritz Heidkamp]]
215
216Original {{doto}} implementation by Martin DeMello
217
218==== Version history
219
220; 3 : First version to be compatible with CHICKEN 5.
221
222For previous versions, see [[http://wiki.call-cc.org/eggref/4/clojurian#version-history|documentation of the CHICKEN 4 version of this egg]].
223
224==== License
225
226
227  Copyright (c) 2014-2018, Moritz Heidkamp
228  All rights reserved.
229 
230  Redistribution and use in source and binary forms, with or without
231  modification, are permitted provided that the following conditions are
232  met:
233 
234  Redistributions of source code must retain the above copyright
235  notice, this list of conditions and the following disclaimer.
236 
237  Redistributions in binary form must reproduce the above copyright
238  notice, this list of conditions and the following disclaimer in the
239  documentation and/or other materials provided with the distribution.
240 
241  Neither the name of the author nor the names of its contributors may
242  be used to endorse or promote products derived from this software
243  without specific prior written permission.
244 
245  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
246  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
247  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
248  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
249  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
250  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
251  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
252  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
253  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
254  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
255  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
256  OF THE POSSIBILITY OF SUCH DAMAGE.
257
Note: See TracBrowser for help on using the repository browser.