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

Last change on this file since 14236 was 14236, checked in by felix winkelmann, 11 years ago

added er-macro-transformer

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