source: project/chicken/trunk/manual/Non-standard macros and special forms @ 5945

Last change on this file since 5945 was 5945, checked in by felix winkelmann, 12 years ago

renamed some tools in misc/; apply hack fix on x86-64 (again); re-added manual

File size: 20.5 KB
Line 
1[[tags: manual]]
2
3[[toc:]]
4
5== Non-standard macros and special forms
6
7=== Making extra libraries and extensions availablee
8
9==== require-extension
10
11 [syntax] (require-extension ID ...)
12 [syntax] (use ID ...)
13
14This form does all necessary steps to make the libraries or extensions given
15in {{ID ...}} available. It loads syntactic extension, if needed and generates
16code for loading/linking with core library modules or separately installed
17extensions. {{use}} is just a shorter alias for {{require-extension}}.
18This implementation of {{require-extension}} is compliant to [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]]
19(see the [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]] document for more information).
20
21During interpretation/evaluation {{require-extension}} performs one of the
22following:
23
24* If {{ID}} names a built-in feature {{chicken srfi-0 srfi-2 srfi-6 srfi-8 srfi-9 srfi-10 srfi-17 srfi-23 srfi-30 srfi-39 srfi-55}}, then nothing is done.
25* If {{ID}} names one of the syntactic extensions {{chicken-more-macros chicken-ffi-macros}}, then this extension will be loaded.
26* {{ID}} names one of the core library units shipped with CHICKEN, then a {{(load-library 'ID)}} will be performed.
27* {{ID}} names an installed extension with the {{syntax}} or {{require-at-runtime}} attribute, then the equivalent of {{(require-for-syntax 'ID)}} is performed, probably followed by {{(require ...)}} for any run-time requirements.
28* Otherwise {{(require-extension ID)}} is equivalent to {{(require 'ID)}}.
29
30During compilation one of the following happens instead:
31
32* If {{ID}} names a built-in feature {{chicken srfi-0 srfi-2 srfi-6 srfi-8 srfi-9 srfi-10 srfi-17 srfi-23 srfi-30 srfi-39 srfi-55}}, then nothing is done.
33* If {{ID}} names one of the syntactic extensions {{chicken-more-macros chicken-ffi-macros}}, then this extension will be loaded at compile-time, making the syntactic extensions available in compiled code.
34* If {{ID}} names one of the core library units shipped with CHICKEN, or if the option {{-uses ID}} has been passed to the compiler then a {{(declare (uses ID))}} is generated.
35* If {{ID}} names an installed extension with the {{syntax}} or {{require-at-runtime}} attribute, then the equivalent of {{(require-for-syntax 'ID)}} is performed, and code is emitted to {{(require ...)}} any needed run-time requirements.
36* Otherwise {{(require-extension ID)}} is equivalent to {{(require 'ID)}}.
37
38To make long matters short - just use {{require-extension}} and it will normally figure everything out for dynamically
39loadable extensions and core library units.
40
41{{ID}} should be a pure extension name and should not contain any path prefixes (for example {{dir/lib...}}) is illegal).
42
43{{ID}} may also be a list that designates an extension-specifier. Currently the following extension specifiers are
44defined:
45
46* {{(srfi NUMBER ...)}} is required for SRFI-55 compatibility and is fully implemented
47* {{(version ID NUMBER)}} is equivalent to {{ID}}, but checks at compile-time whether the extension named {{ID}} is installed and whether its version is equal or higher than {{NUMBER}}. {{NUMBER}} may be a string or a number, the comparison is done lexicographically (using {{string>=?}}).
48
49See also: {{set-extension-specifier!}}
50
51When syntax extensions are loaded that redefine the global toplevel macro-expander (for example the
52[[http://www.call-with-current-continuation.org/eggs/syntax-case.html|syntax-case]] extension), then
53all remaining expression ''in the same toplevel form'' are still expanded with the old toplevel
54macro-expander.
55
56==== define-extension
57
58 [syntax] (define-extension NAME CLAUSE ...)
59
60This macro simplifies the task of writing extensions that can be linked both statically and dynamically.
61If encountered in interpreted code or code that is compiled into a shared object (specifically if compiled
62with the feature {{chicken-compile-shared}}, done automatically by {{csc}} when compiling with
63the {{-shared}} or {{-dynamic}} option) then the code given by clauses of the form
64
65<enscript highlight=scheme>
66(dynamic EXPRESSION ...)
67</enscript>
68
69are inserted into the output as a {{begin}} form.
70
71If compiled statically (specifically if the feature {{chicken-compile-shared}} has not been given), then
72this form expands into the following:
73
74<enscript highlight=scheme>
75(declare (unit NAME))
76(provide 'NAME)
77</enscript>
78
79and all clauses of the form
80
81<enscript highlight=scheme>
82(static EXPRESSION ...)
83</enscript>
84
85all additionally inserted into the expansion.
86
87As a convenience, the clause
88
89<enscript highlight=scheme>
90(export IDENTIFIER ...)
91</enscript>
92
93is also allowed and is identical to {{(declare (export IDENTIFIER ...))}} (unless the {{define-extension}} form
94occurs in interpreted code, in with it is simply ignored).
95
96Note that the compiler option {{-extension NAME}} is equivalent to prefixing the
97compiled file with
98
99<enscript highlight=scheme>
100(define-extension NAME)
101</enscript>
102
103
104=== Binding forms for optional arguments
105
106==== optional
107
108 [syntax] (optional ARGS DEFAULT)
109
110Use this form for procedures that take a single optional argument. If
111{{ARGS}} is the empty list {{DEFAULT}} is evaluated and
112returned, otherwise the first element of the list {{ARGS}}. It is
113an error if {{ARGS}} contains more than one value.
114
115<enscript highlight=scheme>
116(define (incr x . i) (+ x (optional i 1)))
117(incr 10)                                   ==> 11
118(incr 12 5)                                 ==> 17
119</enscript>
120==== case-lambda
121
122 [syntax] (case-lambda (LAMBDA-LIST1 EXP1 ...) ...)
123
124Expands into a lambda that invokes the body following the first
125matching lambda-list.
126
127<enscript highlight=scheme>
128(define plus
129  (case-lambda
130    (() 0)
131    ((x) x)
132    ((x y) (+ x y))
133    ((x y z) (+ (+ x y) z))
134    (args (apply + args))))
135
136(plus)                      ==> 9
137(plus 1)                    ==> 1
138(plus 1 2 3)                ==> 6
139</enscript>
140
141For more information see the documentation for
142[[http://srfi.schemers.org/srfi-16/srfi-16.html|SRFI-16]]
143
144==== let-optionals
145
146 [syntax]  (let-optionals ARGS ((VAR1 DEFAULT1) ...) BODY ...)
147
148Binding constructs for optional procedure arguments. {{ARGS}} should
149be a rest-parameter taken from a lambda-list. {{let-optionals}}
150binds {{VAR1 ...}} to available arguments in parallel, or
151to {{DEFAULT1 ...}} if not enough arguments were provided.
152{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every
153variable sees the previous ones. it is an error if any excess
154arguments are provided.
155
156<enscript highlight=scheme>
157(let-optionals '(one two) ((a 1) (b 2) (c 3))
158  (list a b c) )                               ==> (one two 3)
159</enscript>
160
161==== let-optionals*
162
163 [syntax]  (let-optionals* ARGS ((VAR1 DEFAULT1) ... [RESTVAR]) BODY ...)
164
165Binding constructs for optional procedure arguments. {{ARGS}} should
166be a rest-parameter taken from a lambda-list. {{let-optionals}}
167binds {{VAR1 ...}} to available arguments in parallel, or
168to {{DEFAULT1 ...}} if not enough arguments were provided.
169{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every
170variable sees the previous ones. If a single variable {{RESTVAR}}
171is given, then it is bound to any remaining arguments, otherwise it is
172an error if any excess arguments are provided.
173
174<enscript highlight=scheme>
175(let-optionals* '(one two) ((a 1) (b 2) (c a))
176  (list a b c) )                               ==> (one two one)
177</enscript>
178
179
180=== Other binding forms
181
182==== and-let*
183
184 [syntax] (and-let* (BINDING ...) EXP1 EXP2 ...)
185
186SRFI-2. Bind sequentially and execute body. {{BINDING}} can
187be a list of a variable and an expression, a list with a single
188expression, or a single variable. If the value of an expression
189bound to a variable is {{#f}}, the {{and-let*}} form
190evaluates to {{#f}} (and the subsequent bindings and the body
191are not executed).  Otherwise the next binding is performed. If
192all bindings/expressions evaluate to a true result, the body is
193executed normally and the result of the last expression is the
194result of the {{and-let*}} form. See also the documentation for
195[[http://srfi.schemers.org/srfi-2/srfi-2.html|SRFI-2]].
196
197==== rec
198
199 [syntax] (rec NAME EXPRESSION)
200 [syntax] (rec (NAME VARIABLE ...) BODY ...)
201
202Allows simple definition of recursive definitions. {{(rec NAME EXPRESSION)}} is
203equivalent to {{(letrec ((NAME EXPRESSION)) NAME)}} and {{(rec (NAME VARIABLE ...) BODY ...)}}
204is the same as {{(letrec ((NAME (lambda (VARIABLE ...) BODY ...))) NAME)}}.
205
206==== cut
207
208 [syntax] (cut SLOT ...)
209 [syntax] (cute SLOT ...)
210
211[[http://srfi.schemers.org/srfi-26/srfi-26.html|Syntactic sugar for specializing parameters]].
212
213==== define-values
214
215 [syntax] (define-values (NAME ...) EXP)
216
217Defines several variables at once, with the result values of expression
218{{EXP}}.
219
220==== fluid-let
221
222 [syntax] (fluid-let ((VAR1 X1) ...) BODY ...)
223
224Binds the variables {{VAR1 ...}} dynamically to the values {{X1 ...}}
225during execution of {{BODY ...}}.
226
227==== let-values
228
229 [syntax] (let-values (((NAME ...) EXP) ...) BODY ...)
230
231Binds multiple variables to the result values of {{EXP ...}}.
232All variables are bound simultaneously.
233
234==== let*-values
235
236 [syntax] (let*-values (((NAME ...) EXP) ...) BODY ...)
237
238Binds multiple variables to the result values of {{EXP ...}}.
239The variables are bound sequentially.
240
241<enscript highlight=scheme>
242(let*-values (((a b) (values 2 3))
243              ((p) (+ a b)) )
244  p)                               ==> 5
245</enscript>
246
247==== letrec-values
248
249 [syntax] (letrec-values (((NAME ...) EXP) ...) BODY ...)
250
251Binds the result values of {{EXP ...}} to multiple variables at once.
252All variables are mutually recursive.
253
254<enscript highlight=scheme>
255(letrec-values (((odd even)
256                   (values
257                     (lambda (n) (if (zero? n) #f (even (sub1 n))))
258                     (lambda (n) (if (zero? n) #t (odd (sub1 n)))) ) ) )
259  (odd 17) )                           ==> #t
260</enscript>
261
262==== parameterize
263
264 [syntax] (parameterize ((PARAMETER1 X1) ...) BODY ...)
265
266Binds the parameters {{PARAMETER1 ...}} dynamically to the values
267{{X1 ...}} during execution of {{BODY ...}}.  (see also:
268{{make-parameter}} in [[Parameters]]). Note that {{PARAMETER}} may be any
269expression that evaluates to a parameter procedure.
270
271==== receive
272
273 [syntax] (receive (NAME1 ... [. NAMEn]) VALUEEXP BODY ...)
274 [syntax] (receive VALUEEXP)
275
276SRFI-8. Syntactic sugar for {{call-with-values}}. Binds variables
277to the result values of {{VALUEEXP}} and evaluates {{BODY ...}}.
278
279The syntax
280
281<enscript highlight=scheme>
282(receive VALUEEXP)
283</enscript>
284
285is equivalent to
286
287<enscript highlight=scheme>
288(receive _ VALUEEXP _)
289</enscript>
290
291==== set!-values
292
293 [syntax] (set!-values (NAME ...) EXP)
294
295Assigns the result values of expression {{EXP}} to multiple
296variables.
297
298
299=== Substitution forms and macros
300
301==== define-constant
302
303 [syntax] (define-constant NAME CONST)
304
305Define a variable with a constant value, evaluated at compile-time.
306Any reference to such a
307constant should appear textually '''after''' its definition. This
308construct is equivalent to {{define}} when evaluated or interpreted.
309Constant definitions should only appear at toplevel. Note that constants
310are local to the current compilation unit and are not available outside
311of the source file in which they are defined. Names of constants still
312exist in the Scheme namespace and can be lexically shadowed.  If the
313value is mutable, then the compiler is careful to preserve its identity.
314{{CONST}} may be any constant expression, and may also refer to
315constants defined via {{define-constant}} previously.
316This for should only be used at top-level.
317
318==== define-inline
319
320 [syntax] (define-inline (NAME VAR ... [. VAR]) BODY ...)
321 [syntax] (define-inline NAME EXP)
322
323Defines an inline procedure. Any occurrence of {{NAME}} will be
324replaced by {{EXP}} or {{(lambda (VAR ... [. VAR]) BODY ...)}}.
325This is similar to a macro, but variable-names and -scope will
326be correctly handled.  Inline substitutions take place '''after'''
327macro-expansion.  {{EXP}} should be a lambda-expression. Any
328reference to {{NAME}} should appear textually '''after'''
329its definition. Note that inline procedures are local to the current
330compilation unit and are not available outside of the source file in
331which they are defined. Names of inline procedures still exist in the
332Scheme namespace and can be lexically shadowed.  This construct is
333equivalent to {{define}} when evaluated or interpreted. Inline
334definitions should only appear at toplevel.
335
336==== define-macro
337
338 [syntax] (define-macro (NAME VAR ... [. VAR]) EXP1 ...)
339 [syntax] (define-macro NAME (lambda (VAR ... [. VAR]) EXP1 ...))
340 [syntax] (define-macro NAME1 NAME2)
341
342Define a globally visible macro special form. The macro is available
343as soon as it is defined, i.e. it is registered at compile-time. If
344the file containing this definition invokes {{eval}} and the
345declaration {{run-time-macros}} (or the command line option
346{{-run-time-macros}}) has been used, then the
347macro is visible in evaluated expressions during runtime. The second
348possible syntax for {{define-macro}} is allowed for portability
349purposes only. In this case the second argument '''must''' be a
350lambda-expression or a macro name.  Only global macros can be defined using this form.
351{{(define-macro NAME1 NAME2)}} simply copies the macro definition
352from {{NAME2}} to {{NAME1}}, creating an alias.
353
354Extended lambda list syntax ({{#!optional}}, etc.) can be used but note
355that arguments are source expressions and thus default values for optional
356or keyword arguments should take this into consideration.
357
358==== define-for-syntax
359
360 [syntax] (define-for-syntax (NAME VAR ... [. VAR]) EXP1 ...)
361 [syntax] (define-for-syntax NAME [VALUE])
362
363Defines the toplevel variable {{NAME}} at macro-expansion time. This can
364be helpful when you want to define support procedures for use in macro-transformers,
365for example.
366
367
368=== Conditional forms
369
370==== select
371
372 [syntax] (select EXP ((KEY ...) EXP1 ...) ... [(else EXPn ...)])
373
374This is similar to {{case}}, but the keys are evaluated.
375
376==== unless
377
378 [syntax] (unless TEST EXP1 EXP2 ...)
379
380Equivalent to:
381
382<enscript highlight=scheme>
383(if (not TEST) (begin EXP1 EXP2 ...))
384</enscript>
385
386==== when
387
388 [syntax] (when TEST EXP1 EXP2 ...)
389
390Equivalent to:
391
392<enscript highlight=scheme>
393(if TEST (begin EXP1 EXP2 ...))
394</enscript>
395
396
397=== Record structures
398
399==== define-record
400
401 [syntax] (define-record NAME SLOTNAME ...)
402
403Defines a record type. Call {{make-NAME}} to create an instance
404of the structure (with one initialization-argument for each slot).
405{{(NAME? STRUCT)}} tests any object for being an instance of this
406structure.  Slots are accessed via {{(NAME-SLOTNAME STRUCT)}}
407and updated using {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.
408
409<enscript highlight=scheme>
410(define-record point x y)
411(define p1 (make-point 123 456))
412(point? p1)                      ==> #t
413(point-x p1)                     ==> 123
414(point-y-set! p1 99)
415(point-y p1)                     ==> 99
416</enscript>
417
418==== define-record-printer
419
420 [syntax] (define-record-printer (NAME RECORDVAR PORTVAR) BODY ...)
421 [syntax] (define-record-printer NAME PROCEDURE)
422
423Defines a printing method for record of the type {{NAME}} by
424associating a procedure with the record type. When a record of this
425type is written using {{display, write}} or {{print}}, then
426the procedure is called with two arguments: the record to be printed
427and an output-port.
428
429<enscript highlight=scheme>
430(define-record foo x y z)
431(define f (make-foo 1 2 3))
432(define-record-printer (foo x out)
433  (fprintf out "#,(foo ~S ~S ~S)"
434           (foo-x x) (foo-y x) (foo-z x)) )
435(define-reader-ctor 'foo make-foo)
436(define s (with-output-to-string
437              (lambda () (write f))))
438s                                   ==> "#,(foo 1 2 3)"
439(equal? f (with-input-from-string
440              s read)))             ==> #t
441</enscript>
442
443{{define-record-printer}} works also with SRFI-9 record types.
444
445==== define-record-type
446
447 [syntax] (define-record-type NAME
448                              (CONSTRUCTOR TAG ...)
449                              PREDICATE
450                              (FIELD ACCESSOR [MODIFIER]) ...)
451
452SRFI-9 record types. For more information see the documentation for
453[[http://srfi.schemers.org/srfi-9/srfi-9.html|SRFI-9]].
454
455
456=== Other forms
457
458==== assert
459
460 [syntax] (assert EXP [STRING ARG ...])
461
462Signals an error if {{EXP}} evaluates to false. An optional message
463{{STRING}} and arguments {{ARG ...}} may be supplied to give a
464more informative error-message.  If compiled in ''unsafe'' mode (either
465by specifying the {{-unsafe}} compiler option or by declaring
466{{(unsafe)}}), then this expression expands to an unspecified value.
467The result is the value of {{EXP}}.
468
469==== cond-expand
470
471 [syntax] (cond-expand FEATURE-CLAUSE ...)
472
473Expands by selecting feature clauses. This form is allowed to appear in non-toplevel expressions.
474
475Predefined feature-identifiers are "situation" specific:
476
477; compile : {{eval}}, {{library}}, {{match}}, {{compiling}}, {{srfi-11}}, {{srfi-15}}, {{srfi-31}}, {{srfi-26}}, {{srfi-16}}, {{utils}}, {{regex}}, {{srfi-4}}, {{match}}, {{srfi-1}}, {{srfi-69}}, {{srfi-28}}, {{extras}}, {{srfi-8}}, {{srfi-6}}, {{srfi-2}}, {{srfi-0}}, {{srfi-10}}, {{srfi-9}}, {{srfi-55}}, {{srfi-61}} {{chicken}}, {{srfi-23}}, {{srfi-30}}, {{srfi-39}}, {{srfi-62}}, {{srfi-17}}, {{srfi-12}}.
478
479; load : {{srfi-69}}, {{srfi-28}}, {{extras}}, {{srfi-8}}, {{srfi-6}}, {{srfi-2}}, {{srfi-0}}, {{srfi-10}}, {{srfi-9}}, {{srfi-55}}, {{srfi-61}}, {{chicken}}, {{srfi-23}}, {{srfi-30}}, {{srfi-39}}, {{srfi-62}}, {{srfi-17}}, {{srfi-12}}. {{library}} is implicit.
480
481; eval : {{match}}, {{csi}}, {{srfi-11}}, {{srfi-15}}, {{srfi-31}}, {{srfi-26}}, {{srfi-16}}, {{srfi-69}}, {{srfi-28}}, {{extras}}, {{srfi-8}}, {{srfi-6}}, {{srfi-2}}, {{srfi-0}}, {{srfi-10}}, {{srfi-9}}, {{srfi-55}}, {{srfi-61}}, {{chicken}}, {{srfi-23}}, {{srfi-30}}, {{srfi-39}}, {{srfi-62}}, {{srfi-17}}, {{srfi-12}}. {{library}} is implicit.
482
483The following feature-identifiers are available in all situations: {{(machine-byte-order)}}, {{(machine-type)}}, {{(software-type)}}, {{(software-version)}}, where the actual feature-identifier is platform dependent.
484
485In addition the following feature-identifiers may exist: {{applyhook}}, {{extraslot}}, {{ptables}}, {{dload}}, {{libffi}}.
486
487For further information, see the documentation for [[http://srfi.schemers.org/srfi-0/srfi-0.html|SRFI-0]].
488
489==== ensure
490
491 [syntax] (ensure PREDICATE EXP [ARGUMENTS ...])
492
493Evaluates the expression {{EXP}} and applies the one-argument
494procedure {{PREDICATE}} to the result. If the predicate returns
495{{#f}} an error is signaled, otherwise the result of {{EXP}}
496is returned.  If compiled in ''unsafe'' mode (either by specifying
497the {{-unsafe}} compiler option or by declaring {{(unsafe)}}),
498then this expression expands to an unspecified value.  If specified,
499the optional {{ARGUMENTS}} are used as arguments to the invocation
500of the error-signalling code, as in {{(error ARGUMENTS ...)}}. If
501no {{ARGUMENTS}} are given, a generic error message is displayed
502with the offending value and {{PREDICATE}} expression.
503
504==== eval-when
505
506 [syntax] (eval-when (SITUATION ...) EXP ...)
507
508Controls evaluation/compilation of subforms. {{SITUATION}} should
509be one of the symbols {{eval}}, {{compile}} or {{load}}.
510When encountered in the evaluator, and the situation specifier
511{{eval}} is not given, then this form is not evaluated and an
512unspecified value is returned.  When encountered while compiling code,
513and the situation specifier {{compile}} is given, then this form is
514evaluated at compile-time.  When encountered while compiling code, and the
515situation specifier {{load}} is not given, then this form is ignored
516and an expression resulting into an unspecified value is compiled instead.
517
518The following table should make this clearer:
519
520<table>
521<tr><th></th><th>In compiled code</th><th>In interpreted code</th></tr>
522<tr><td>{{eval}}</td><td>ignore</td><td>evaluate</td></tr>
523<tr><td>{{compile}}</td><td>evaluate at compile time</td><td>ignore</td></tr>
524<tr><td>{{load}}</td><td>compile as normal</td><td>ignore</td></tr>
525</table>
526
527The situation specifiers {{compile-time}} and {{run-time}} are also
528defined and have the same meaning as {{compile}} and {{load}}, respectively.
529
530==== include
531
532 [syntax] (include STRING)
533
534Include toplevel-expressions from the given source file in the currently
535compiled/interpreted program.  If the included file has the extension
536{{.scm}}, then it may be omitted.  The file is searched in the
537current directory and, if not found, in all directories specified in the
538{{-include-path}} option.
539
540==== nth-value
541
542 [syntax] (nth-value N EXP)
543
544Returns the {{N}}th value (counting from zero) of the values returned
545by expression {{EXP}}.
546
547==== time
548
549 [syntax] (time EXP1 ...)
550
551Evaluates {{EXP1 ...}} and prints elapsed time and some
552values about GC use, like time spent in major GCs, number of minor
553and major GCs.
554
555Previous: [[Non-standard read syntax]]
556
557Next: [[Pattern matching]]
Note: See TracBrowser for help on using the repository browser.