source: project/chicken/trunk/manual/Modules and macros @ 15896

Last change on this file since 15896 was 15896, checked in by Ivan Raikov, 10 years ago

merged manual from wiki

File size: 17.2 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4
5== Modules and macros
6
7
8CHICKEN supports standard R5RS {{syntax-rules}} macros and a low-level
9macro system based on ''explicit renaming''.
10
11
12=== Macro definitions
13
14==== define-syntax
15
16 [syntax] (define-syntax IDENTIFIER TRANSFORMER)
17
18Defines a macro named {{IDENTIFIER}} that will transform an expression
19with {{IDENTIFIER}} in operator position according to {{TRANSFORMER}}.
20The transformer expression must be a procedure with three arguments or
21a {{syntax-rules}} form. If {{syntax-rules}} is used, the usual R5RS
22semantics apply. If {{TRANSFORMER}} is a procedure, then it will
23be called on expansion with the complete s-expression of the macro
24invocation, a rename procedure that hygienically renames identifiers
25and a comparison procedure that compares (possibly renamed) identifiers.
26
27{{define-syntax}} may be used to define local macros that are visible
28throughout the rest of the body in which the definition occurred, i.e.
29
30  (let ()
31    ...
32    (define-syntax foo ...)
33    (define-syntax bar ...)
34    ...)
35
36is expanded into
37
38  (let ()
39    ...
40    (letrec-syntax ((foo ...) (bar ...))
41      ...) )
42
43{{syntax-rules}} partially supports [[http://srfi.schemers.org/srfi-46/|SRFI-46]]
44in allowing the ellipsis identifier to be user-defined by passing it as the first
45argument to the {{syntax-rules}} form.
46
47The effect of destructively modifying the s-expression passed to a
48transformer procedure is undefined.
49
50
51==== define-compiled-syntax
52
53 [syntax] (define-compiled-syntax IDENTIFIER TRANSFORMER)
54
55Equivalent to {{define-syntax}}, but when compiled, will also define the macro
56at runtime.
57
58
59==== syntax
60
61 [syntax] (syntax EXPRESSION)
62
63Similar to {{quote}} but retains syntactical context information for
64embedded identifiers.
65
66
67==== strip-syntax
68
69 [procedure] (strip-syntax EXPRESSION)
70
71Strips all syntactical information from {{EXPRESSION}}, returning a new expression
72where symbols have all context-information removed.
73
74
75=== Explicit renaming macros
76
77The low-level macro facility that CHICKEN provides is called "explicit
78renaming" and allows writing hygienic or non-hygienic macros procedurally.
79When given a lambda-expression instead of a {{syntax-rules}} form,
80{{define-syntax}} evaluates the procedure in a distinct expansion
81environment (initially having access to the exported identifiers
82of the {{scheme}} module). The procedure takes an expression and two
83other arguments and returns a transformed expression.
84
85For example, the transformation
86procedure for a {{call}} macro such that
87{{(call proc arg ...)}} expands
88into {{(proc arg ...)}} can be written as
89
90  (lambda (exp rename compare)
91    (cdr exp))
92
93Expressions are represented as lists in the traditional manner,
94except that identifiers are represented as special uninterned symbols.
95
96The second argument to a transformation procedure is a renaming procedure that
97takes the representation of an identifier as its argument and returns the
98representation of a fresh identifier that occurs nowhere else in the
99program.  For example, the transformation procedure for a simplified
100version of the {{let}} macro might be written as
101
102  (lambda (exp rename compare)
103    (let ((vars (map car (cadr exp)))
104          (inits (map cadr (cadr exp)))
105          (body (cddr exp)))
106      `((lambda ,vars ,@body)
107        ,@inits)))
108
109This would not be hygienic, however.  A
110hygienic {{let}} macro must rename the identifier {{lambda}} to protect it
111from being captured by a local binding.  The renaming effectively
112creates a fresh alias for {{lambda}}, one that cannot be captured by
113any subsequent binding:
114
115  (lambda (exp rename compare)
116    (let ((vars (map car (cadr exp)))
117          (inits (map cadr (cadr exp)))
118          (body (cddr exp)))
119      `((,(rename 'lambda) ,vars ,@body)
120        ,@inits)))
121
122The expression returned by the transformation procedure will be
123expanded in the syntactic environment obtained from the syntactic
124environment of the macro application by binding any fresh identifiers
125generated by the renaming procedure to the denotations of the original
126identifiers in the syntactic environment in which the macro was
127defined.  This means that a renamed identifier will denote the same
128thing as the original identifier unless the transformation procedure
129that renamed the identifier placed an occurrence of it in a binding
130position.
131
132Identifiers obtained from any two calls to the renaming procedure with
133the same argument will necessarily be the same, but will denote the
134same syntactical binding. It is an error if the renaming procedure is
135called after the transformation procedure has returned.
136
137The third argument to a transformation procedure is a comparison
138predicate that takes the representations of two identifiers as its
139arguments and returns true if and only if they denote the same thing
140in the syntactic environment that will be used to expand the
141transformed macro application.  For example, the transformation
142procedure for a simplified version of the {{cond}} macro can be written
143as
144
145  (lambda (exp rename compare)
146    (let ((clauses (cdr exp)))
147      (if (null? clauses)
148          `(,(rename 'quote) unspecified)
149          (let* ((first (car clauses))
150                 (rest (cdr clauses))
151                 (test (car first)))
152            (cond ((and (symbol? test)
153                        (compare test (rename 'else)))
154                   `(,(rename 'begin) ,@(cdr first)))
155                  (else `(,(rename 'if)
156                          ,test
157                           (,(rename 'begin) ,@(cdr first))
158                           (cond ,@rest))))))))
159
160In this example the identifier {{else}} is renamed before being passed
161to the comparison predicate, so the comparison will be true if and
162only if the test expression is an identifier that denotes the same
163thing in the syntactic environment of the expression being transformed
164as {{else}} denotes in the syntactic environment in which the {{cond}}
165macro was defined.  If {{else}} were not renamed before being passed to
166the comparison predicate, then it would match a local variable that
167happened to be named {{else}}, and the macro would not be hygienic.
168
169Some macros are non-hygienic by design.  For example, the
170following defines a {{loop}} macro that implicitly binds {{exit}} to an
171escape procedure.  The binding of {{exit}} is intended to capture free
172references to {{exit}} in the body of the loop, so {{exit}} is not
173renamed.
174
175  (define-syntax loop
176     (lambda (x r c)
177       (let ((body (cdr x)))
178         `(,(r 'call-with-current-continuation)
179           (,(r 'lambda) (exit)
180            (,(r 'let) ,(r 'f) () ,@body (,(r 'f))))))))
181
182Suppose a {{while}} macro is implemented using {{loop}}, with the intent
183that {{exit}} may be used to escape from the {{while}} loop.  The {{while}}
184macro cannot be written as
185
186  (define-syntax while
187    (syntax-rules ()
188      ((while test body ...)
189       (loop (if (not test) (exit #f))
190             body ...))))
191
192because the reference to {{exit}} that is inserted by the {{while}} macro
193is intended to be captured by the binding of {{exit}} that will be
194inserted by the {{loop}} macro.  In other words, this {{while}} macro is
195not hygienic.  Like {{loop}}, it must be written using procedurally:
196
197  (define-syntax while
198     (lambda (x r c)
199       (let ((test (cadr x))
200             (body (cddr x)))
201         `(,(r 'loop)
202           (,(r 'if) (,(r 'not) ,test) (exit #f))
203           ,@body))))
204
205
206=== Modules
207
208To allow some control over visible bindings and to organize code at
209the global level, a simple module system is available. A ''module''
210defines a set of toplevel expressions that are initially evaluated in
211an empty syntactical environment. By ''importing'' other modules,
212exported value- and macro-bindings are made visible inside the
213environment of the module that imports them.
214
215Note that modules are purely syntactical - they do not change the
216control flow or delay the execution of the contained toplevel
217forms. The body of a module is executed at load-time, when code is
218loaded or accessed via the {{uses}} declaration, just like normal
219toplevel expressions. Exported macro-definitions are compiled as
220well, and can be accessed in interpreted or compiled code by loading
221and importing the compiled file that contains the module.
222
223Imported toplevel bindings can be assigned (with {{set!}}), any modifications
224to these will change the global value and will be visible to other
225modules that export or import the same toplevel binding.
226
227A module is initially empty (has no visible bindings). You must at least
228import the {{scheme}} module to do anything useful. To access any
229of the non-standard macros and procedures, import the {{chicken}}
230module.
231
232CHICKEN's module system has the following features and shortcomings:
233
234* Indirect exports for syntax definitions must be listed
235* Separation of compile/expansion-time and run-time code is provided, which allows cross compilation
236* Module-generating code is only created, when needed
237* Supports batch-compilation of separate compilation units
238* No separate "identifier" type is used, all identifiers appearing in code and processed in expansions are symbols
239* The module system is fully optional
240
241
242==== module
243
244 [syntax] (module NAME (EXPORT ...) BODY ...)
245 [syntax] (module NAME * BODY ...)
246
247Defines a module with the name {{NAME}}, a set of exported bindings
248and a contained sequence of toplevel expressions that are evaluated in
249an empty syntactical environment. {{EXPORT}} may be a symbol or a list
250of the form {{(IDENTIFIER1 IDENTIFIER2 ...)}}. In the former case the
251identifier given is exported from the module and can be imported at
252the toplevel or in other modules. The latter case exports
253{{IDENTIFIER1}} (which should name a macro) and also arranges for the
254remaining identifiers in the list to be visible in the expansion of
255the macro (this is a hint to the module expander to export bindings
256referenced by syntax-definitions which make use of them, but which
257would normally be internal to the module - that allows some
258optimization and also records).
259
260Nested modules, modules not at toplevel (i.e. local modules) or
261mutually recursive modules are not supported.
262
263When compiled, the module information, including exported macros
264is stored in the generated binary and available when loading
265it into interpreted or compiled code. Note that this is different
266to normal macros (outside of module declarations), which are normally
267not exported from compiled code.
268
269As a special case, specifying {{*}} instead of an export-list
270will export all definitions.
271
272Note that the module system is only a device for controlling the
273mapping of identifiers to value or syntax bindings. Modules do not
274instantiate separate environments that contain their own bindings, as
275do many other module systems. Redefinition of value or syntax bindings
276will modify the original, imported definition.
277
278
279==== export
280
281 [syntax] (export EXPORT ...)
282
283Allows augmenting module-exports from inside the module-body.
284{{EXPORT}} is if the same form as an export-specifier in a
285{{module}} export list. An export must precede its first occurrence
286(either use or definition).
287
288==== import
289
290 [syntax] (import IMPORT ...)
291
292Imports module bindings into the current syntactical environment.
293The visibility of any imported bindings is limited to the current
294module, if used inside a module-definition, or to the current
295compilation unit, if compiled and used outside of a module.
296
297Importing a module does not load or link it - this is a separate
298operation from importing its bindings.
299
300{{IMPORT}} may be a module name, or an ''import specifier''.
301An {{IMPORT}} defines a set of bindings that are to be made visible
302in the current scope.
303
304Note that the imported bindings are only visible in the next toplevel
305expression (regardless of whether the import appears inside or outside
306a module):
307
308  (begin
309    (import m1)
310    ...              ; imports not visible here
311 
312  ...                ; imports visible here
313
314===== only
315
316 [import specifier] (only IMPORT IDENTIFIER ...)
317
318Only import the listed value- or syntax bindings from the set given
319by {{IMPORT}}.
320
321===== except
322
323 [import specifier] (except IMPORT IDENTIFIER ...)
324
325Remove the listed identifiers from the import-set defined by {{IMPORT}}.
326
327===== rename
328
329 [import specifier] (rename IMPORT (OLD1 NEW1) ...)
330
331Renames identifiers imported from {{IMPORT}}.
332
333===== prefix
334
335 [import specifier] (prefix IMPORT SYMBOL)
336
337Prefixes all imported identifiers with {{SYMBOL}}.
338
339
340==== import-for-syntax
341
342 [syntax] (import-for-syntax IMPORT ...)
343
344Similar to {{import}}, but imports exported bindings of a module into
345the environment in which macro transformers are evaluated.
346
347Note: currently this isn't fully correct - value bindings are still
348imported into the normal environment because a separate import
349environment for syntax has not been implemented (syntactic bindings
350are kept separate correctly).
351
352
353==== reexport
354
355  [syntax] (reexport IMPORT ...)
356
357Imports {{IMPORT ...}} and automatically exports all imported identifiers.
358This can be used to build ''compound modules'': modules that just extend
359other modules:
360
361<scheme>
362(module r4rs ()
363  (import scheme chicken)
364  (reexport
365    (except scheme
366      dynamic-wind values call-with-values eval scheme-report-environment
367      null-environment interaction-environment)))
368</scheme>
369
370
371=== import libraries
372
373''import libraries'' allow the syntactical (compile-time)
374and run-time parts of a compiled module to be separated into a normal
375compiled file and a shared library that only contains macro definitions
376and module information. This reduces the size of executables and
377simplifies compiling code that uses modules for a different architecture
378than the machine the compiler is executing on (i.e. "cross" compilation).
379
380By using the {{emit-import-library}} compiler-option or declaration,
381a separate file is generated that only contains syntactical information
382(including macros) for a module. {{import}} will automatically find and
383load an import library for a currently unknown module, if the import-
384library is either in the extension repository or the current include
385path. Import libraries may also be explicitly loaded into the
386compiler by using the {{-extend}} compiler option. Interpreted code
387can simply load the import library to make the module-definition
388available. Macro-support definitions defined with {{define-for-syntax}}
389and expansion-time expressions of the form {{(begin-for-syntax ...)}}
390will be added to import libraries to make them available for exported
391macros. Note that these definitions will ruthlessly pollute the
392toplevel namespace and so they should be used sparingly.
393
394
395=== Predefined modules
396
397Import libraries for the following modules are initially
398available:
399
400 [module] scheme
401
402Exports the standard R5RS bindings.
403
404 [module] chicken
405
406Everything from the {{library}}, {{eval}} and {{expand}} library units.
407
408 [module] extras
409 [module] data-structures
410 [module] ports
411 [module] lolevel
412 [module] posix
413 [module] regex
414 [module] srfi-1
415 [module] srfi-4
416 [module] srfi-13
417 [module] srfi-14
418 [module] srfi-18
419 [module] srfi-69
420 [module] tcp
421 [module] utils
422
423Modules exporting the bindings from the respective library units.
424
425 [module] foreign
426
427Exports all macros and procedures that are used to access foreign
428C/C++ code.
429
430
431=== Examples of using modules
432
433Here is a silly little test module to demonstrate how modules
434are defined and used:
435
436 ;; hello.scm
437 
438 (module test (hello greet)
439   (import scheme)
440 
441   (define-syntax greet
442     (syntax-rules ()
443       ((_ whom)
444        (begin
445          (display "Hello, ")
446          (display whom)
447          (display " !\n") ) ) ) )
448 
449   (define (hello)
450     (greet "world") )  )
451
452The module {{test}} exports one value ({{hello}}) and one syntax
453binding ({{greet}}). To use it in {{csi}}, the interpreter,
454simply load and import it:
455
456  #;1> ,l hello.scm
457  ; loading hello.scm ...
458  ; loading /usr/local/lib/chicken/4/scheme.import.so ...
459  #;1> (import test)
460  #;2> (hello)
461  Hello, world !
462  #;3> (greet "you")
463  Hello, you !
464
465The module can easily be compiled
466
467  % csc -s hello.scm
468
469and used in an identical manner:
470
471  #;1> ,l hello.so
472  ; loading hello.so ...
473  #;1> (import test)
474  #;2> (hello)
475  Hello, world !
476  #;3> (greet "you")
477  Hello, you !
478
479If you want to keep macro-definitions in a separate file, use import
480libraries:
481
482  % csc -s hello.scm -j test
483  % csc -s test.import.scm
484
485  #;1> ,l hello.so
486  ; loading hello.so ...
487  #;1> (import test)
488  ; loading ./test.import.so ...
489  #;2> (hello)
490  Hello, world !
491  #;3> (greet "you")
492  Hello, you !
493
494If an import library (compiled or in source-form) is located
495somewhere in the extensions-repository or include path, it
496is automatically loaded on import. Otherwise you have to
497load it manually:
498
499  #;1> ,l hello.so
500  ; loading hello.so ...
501  #;1> ,l test.import.so
502  ; loading test.import.so ...
503  #;1> (import test)
504  #;2>
505
506
507=== Caveats
508
509The macro- and module system has been implemented relatively
510recently and is likely to contain bugs. Please contact the
511maintainers if you encounter behavior that you think is
512not correct or that triggers an error where there shouldn't
513be one.
514
515* In evaluated code, loading a file containing module information and importing from a module contained in that file will not work when the loading and import is performed in the same toplevel expression (this does not apply, when import libraries are used)
516* Currently value bindings imported by {{import}} and {{import-for-syntax}} share the same import-environment.
517
518
519---
520Previous: [[Non-standard macros and special forms]]
521
522Next: [[Declarations]]
Note: See TracBrowser for help on using the repository browser.