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

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

merged trunk rev. 13953

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