source: project/chicken/branches/scrutiny/manual/Modules and macros @ 14827

Last change on this file since 14827 was 14827, checked in by felix winkelmann, 10 years ago

merged trunk changes until 14826 into scrutiny branch

File size: 17.3 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
296Note that the module system is only a device for controlling the
297mapping of identifiers to value or syntax bindings. Modules do not
298instantiate separate environments that contain their own bindings, as
299do many other module systems. Redefinition of value or syntax bindings
300will modify the original, imported definition.
301
302
303==== export
304
305 [syntax] (export EXPORT ...)
306
307Allows augmenting module-exports from inside the module-body.
308{{EXPORT}} is if the same form as an export-specifier in a
309{{module}} export list. An export must precede its first occurrence
310(either use or definition).
311
312==== import
313
314 [syntax] (import IMPORT ...)
315
316Imports module bindings into the current syntactical environment.
317The visibility of any imported bindings is limited to the current
318module, if used inside a module-definition, or to the current
319compilation unit, if compiled and used outside of a module.
320
321Importing a module does not load or link it - this is a separate
322operation from importing its bindings.
323
324{{IMPORT}} may be a module name, or an ''import specifier''.
325An {{IMPORT}} defines a set of bindings that are to be made visible
326in the current scope.
327
328Note that the imported bindings are only visible in the next toplevel
329expression (regardless of whether the import appears inside or outside
330a module):
331
332  (begin
333    (import m1)
334    ...              ; imports not visible here
335 
336  ...                ; imports visible here
337
338===== only
339
340 [import specifier] (only IMPORT IDENTIFIER ...)
341
342Only import the listed value- or syntax bindings from the set given
343by {{IMPORT}}.
344
345===== except
346
347 [import specifier] (except IMPORT IDENTIFIER ...)
348
349Remove the listed identifiers from the import-set defined by {{IMPORT}}.
350
351===== rename
352
353 [import specifier] (rename IMPORT (OLD1 NEW1) ...)
354
355Renames identifiers imported from {{IMPORT}}.
356
357===== prefix
358
359 [import specifier] (prefix IMPORT SYMBOL)
360
361Prefixes all imported identifiers with {{SYMBOL}}.
362
363
364==== import-for-syntax
365
366 [syntax] (import-for-syntax IMPORT ...)
367
368Similar to {{import}}, but imports exported bindings of a module into
369the environment in which macro transformers are evaluated.
370
371Note: currently this isn't fully correct - value bindings are still
372imported into the normal environment because a separate import
373environment for syntax has not been implemented (syntactic bindings
374are kept separate correctly).
375
376
377=== import libraries
378
379''import libraries'' allow the syntactical (compile-time)
380and run-time parts of a compiled module to be separated into a normal
381compiled file and a shared library that only contains macro definitions
382and module information. This reduces the size of executables and
383simplifies compiling code that uses modules for a different architecture
384than the machine the compiler is executing on (i.e. "cross" compilation).
385
386By using the {{emit-import-library}} compiler-option or declaration,
387a separate file is generated that only contains syntactical information
388(including macros) for a module. {{import}} will automatically find and
389load an import library for a currently unknown module, if the import-
390library is either in the extension repository or the current include
391path. Import libraries may also be explicitly loaded into the
392compiler by using the {{-extend}} compiler option. Interpreted code
393can simply load the import library to make the module-definition
394available. Macro-support definitions defined with {{define-for-syntax}}
395and expansion-time expressions of the form {{(begin-for-syntax ...)}}
396will be added to import libraries to make them available for exported
397macros. Note that these definitions will ruthlessly pollute the
398toplevel namespace and so they should be used sparingly.
399
400
401=== Predefined modules
402
403Import libraries for the following modules are initially
404available:
405
406 [module] scheme
407
408Exports the standard R5RS bindings.
409
410 [module] chicken
411
412Everything from the {{library}}, {{eval}} and {{expand}} library units.
413
414 [module] extras
415 [module] data-structures
416 [module] ports
417 [module] lolevel
418 [module] posix
419 [module] regex
420 [module] srfi-1
421 [module] srfi-4
422 [module] srfi-13
423 [module] srfi-14
424 [module] srfi-18
425 [module] srfi-69
426 [module] tcp
427 [module] utils
428
429Modules exporting the bindings from the respective library units.
430
431 [module] foreign
432
433Exports all macros and procedures that are used to access foreign
434C/C++ code.
435
436
437=== Examples of using modules
438
439Here is a silly little test module to demonstrate how modules
440are defined and used:
441
442;; hello.scm
443
444(module test (hello greet)
445  (import scheme)
446
447  (define-syntax greet
448    (syntax-rules ()
449      ((_ whom)
450       (begin
451         (display "Hello, ")
452         (display whom)
453         (display " !\n") ) ) ) )
454
455  (define (hello)
456    (greet "world") )  )
457
458The module {{test}} exports one value ({{hello}}) and one syntax
459binding ({{greet}}). To use it in {{csi}}, the interpreter,
460simply load and import it:
461
462  #;1> ,l hello.scm
463  ; loading hello.scm ...
464  ; loading /usr/local/lib/chicken/4/scheme.import.so ...
465  #;1> (import test)
466  #;2> (hello)
467  Hello, world !
468  #;3> (greet "you")
469  Hello, you !
470
471The module can easily be compiled
472
473  % csc -s hello.scm
474
475and used in an identical manner:
476
477  #;1> ,l hello.so
478  ; loading hello.so ...
479  #;1> (import test)
480  #;2> (hello)
481  Hello, world !
482  #;3> (greet "you")
483  Hello, you !
484
485If you want to keep macro-definitions in a separate file, use import
486libraries:
487
488  % csc -s hello.scm -j test
489  % csc -s test.import.scm
490
491  #;1> ,l hello.so
492  ; loading hello.so ...
493  #;1> (import test)
494  ; loading ./test.import.so ...
495  #;2> (hello)
496  Hello, world !
497  #;3> (greet "you")
498  Hello, you !
499
500If an import library (compiled or in source-form) is located
501somewhere in the extensions-repository or include path, it
502is automatically loaded on import. Otherwise you have to
503load it manually:
504
505  #;1> ,l hello.so
506  ; loading hello.so ...
507  #;1> ,l test.import.so
508  ; loading test.import.so ...
509  #;1> (import test)
510  #;2>
511
512
513=== Caveats
514
515The macro- and module system has been implemented relatively
516recently and is likely to contain bugs. Please contact the
517maintainers if you encounter behavior that you think is
518not correct or that triggers an error where there shouldn't
519be one.
520
521* 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)
522* Currently value bindings imported by {{import}} and {{import-for-syntax}} share the same import-environment.
523
524
525---
526Previous: [[Non-standard macros and special forms]]
527
528Next: [[Declarations]]
Note: See TracBrowser for help on using the repository browser.