-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathlibraries.html
1311 lines (961 loc) · 51.4 KB
/
libraries.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd"><!-- DO NOT EDIT THIS FILE-->
<!-- Edit the .tex version instead-->
<html>
<head>
<title>Libraries and Top-level Programs</title>
<link href="csug.css" rel="stylesheet" type="text/css">
</head>
<body>
<a name="g88"></a>
<a name="./libraries:h0"></a>
<h1>Chapter 10. Libraries and Top-level Programs<a name="CHPTLIBRARIES"></a></h1>
<p>
<a name="./libraries:s0"></a><a name="./libraries:s1"></a>The Revised<sup>6</sup> Report describes two units of portable code:
libraries and top-level programs.
A library is a named collection of bindings with a declared set of
explicitly exported bindings, a declared set of imported libraries, and a
body that initializes its bindings.
A top-level program is a stand-alone program with a declared set of
imported libraries and a body that is run when the top-level program is
run.
The bindings in a library are created and its initialization code run only
if the library is used, directly or indirectly, by a top-level program.
<p>
<a name="./libraries:s2"></a>The <tt>import</tt> declarations appearing within libraries and top-level
programs serve two purposes: first, they cause the imported libraries to
be loaded, and second, they cause the bindings of the imported libraries
to become visible in the importing library or top-level program.
Libraries are typically stored in the file system, with one library per
file, and the library name typically identifies the file-system path to
the library, possibly relative to a default or programmer-specified set of
library locations.
The exact mechanism by which top-level programs are run and libraries are
loaded is implementation-dependent.
<p>
This chapter describes the mechanisms by which libraries and programs are
loaded in <i>Chez Scheme</i> along with various features for controlling and
tracking this process.
It also describes the set of built-in libraries and syntactic forms for
defining new libraries and top-level programs outside of a library or
top-level program file.
<p>
<h3><a name="g89"></a><a name="./libraries:h1"></a>Section 10.1. Built-in Libraries<a name="SECTBUILTINLIBRARIES"></a></h3>
<p>
In addition to the RNRS libraries mandated by the Revised<sup>6</sup> Report:
<p>
<p><tt> (rnrs base (6))<br>
(rnrs arithmetic bitwise (6))<br>
(rnrs arithmetic fixnums (6))<br>
(rnrs arithmetic flonums (6))<br>
(rnrs bytevectors (6))<br>
(rnrs conditions (6))<br>
(rnrs control (6))<br>
(rnrs enums (6))<br>
(rnrs eval (6))<br>
(rnrs exceptions (6))<br>
(rnrs files (6))<br>
(rnrs hashtables (6))<br>
(rnrs io ports (6))<br>
(rnrs io simple (6))<br>
(rnrs lists (6))<br>
(rnrs mutable-pairs (6))<br>
(rnrs mutable-strings (6))<br>
(rnrs programs (6))<br>
(rnrs r5rs (6))<br>
(rnrs records procedural (6))<br>
(rnrs records syntactic (6))<br>
(rnrs records inspection (6))<br>
(rnrs sorting (6))<br>
(rnrs syntax-case (6))<br>
(rnrs unicode (6))</tt>
<p><a name="./libraries:s3"></a><a name="./libraries:s4"></a><a name="./libraries:s5"></a><a name="./libraries:s6"></a><i>Chez Scheme</i> also provides two additional libraries: <tt>(chezscheme)</tt>
and <tt>(chezscheme csv7)</tt>.
The former can also be referenced as <tt>(scheme)</tt> and the latter can
also be referenced as <tt>(scheme csv7)</tt>.
<p>
The <tt>(chezscheme)</tt> library exports bindings for every identifier whose
binding is described in this document, including those for keywords like
<tt>lambda</tt>, auxiliary keywords like <tt>else</tt>, module names
like <tt>scheme</tt>, and procedure names like <tt>cons</tt>.
In most cases where an identifier exported from the
<tt>(chezscheme)</tt> library corresponds to an identifier exported from
one of the RNRS libraries, the bindings are identical.
In some cases, however, the <tt>(chezscheme)</tt> bindings extend the
<tt>rnrs</tt> bindings in some way.
For example, the <tt>(chezscheme)</tt> <tt>syntax-rules</tt> form allows
its clauses to have fenders (Section <a href="./syntax.html#g97">11.2</a>), while the
<tt>(rnrs)</tt> <tt>syntax-rules</tt> form does not.
Similarly, the <tt>(chezscheme)</tt> <tt>current-input-port</tt> procedure
accepts an optional <tt><i>port</i></tt> argument that, when specified, sets the
current input port to <tt><i>port</i></tt> (Section <a href="./io.html#g78">9.8</a>), while the
<tt>(rnrs)</tt> <tt>current-input-port</tt> procedure does not.
When the <tt>(chezscheme)</tt> library extends an RNRS binding in some
way, the <tt>(chezscheme)</tt> library also exports the RNRS version,
with the name prefixed by <tt>r6rs:</tt>, e.g., <tt>r6rs:syntax-rules</tt>
or <tt>r6rs:current-input-port</tt>.
<p>
The <tt>(chezscheme csv7)</tt> Version 7 backward compatibility library
contains bindings for a set of syntactic forms and procedures whose syntax
or semantics directly conflicts with the RNRS bindings for the same
identifiers.
The following identifiers are exported from <tt>(chezscheme csv7)</tt>.
<p>
<p><tt>record-field-accessible?<br>
record-field-accessor<br>
record-field-mutable?<br>
record-field-mutator<br>
record-type-descriptor<br>
record-type-field-decls<br>
record-type-field-names<br>
record-type-name<br>
record-type-symbol</tt>
<p>The bindings of this library should be used only for old code; new
code should use the RNRS variants.
Each of these is also available in the <tt>(chezscheme)</tt> library with
the prefix <tt>csv7:</tt>, e.g., <tt>csv7:record-type-name</tt>.
<p>
The interaction environment in which code outside of a library or
RNRS top-level program is scoped contains all of the bindings of the
<tt>(chezscheme)</tt> library, as described in
Section <a href="./use.html#g8">2.3</a>.
<p>
<h3><a name="g90"></a><a name="./libraries:h2"></a>Section 10.2. Running Top-level Programs<a name="SECTRUNNINGTOPLEVELPROGRAMS"></a></h3>
<p>
<a name="./libraries:s7"></a><a name="./libraries:s8"></a><a name="./libraries:s9"></a>A top-level program must reside in its own file, which may have any
name and may reside anywhere in the file system.
A top-level program residing in a file is run by one of three mechanisms:
the <tt>scheme-script</tt> command, the <tt>--program</tt> command-line
argument, or the <tt>load-program</tt> procedure.
<p>
The <tt>scheme-script</tt> command is used as follows:
<p>
<p><tt>scheme-script <i>program-filename</i> <i>arg</i> ...</tt>
<p>It may also be run implicitly on Unix-based systems by placing the line
<p>
<p><tt>#! /usr/bin/env scheme-script</tt>
<p>at the front of the file containing the top-level program, making the
top-level program file executable, and executing the file.
This line may be replaced with
<p>
<p><tt>#! /usr/bin/scheme-script</tt>
<p>with <tt>/usr/bin</tt> replaced by the absolute path to the directory
containing <tt>scheme-script</tt> if it is not in <tt>/usr/bin</tt>.
The first form is recommended in the nonnormative appendices to the
Revised<sup>6</sup> Report [<a class=citation href="./bibliography.html#g174">28</a>], and works wherever
<tt>scheme-script</tt> appears in the path.
<p>
The <tt>--program</tt> command is used similarly with the <tt>scheme</tt>
or <tt>petite</tt> executables, either by running:
<p>
<p><tt>scheme --program <i>program-filename</i> <i>arg</i> ...<br>
petite --program <i>program-filename</i> <i>arg</i> ...</tt>
<p>or by including
<p>
<p><tt>#! /usr/bin/scheme --script</tt>
<p>or
<p>
<p><tt>#! /usr/bin/petite --script</tt>
<p>at the front of the top-level program file, making the file executable,
and executing the file.
Again, <tt>/usr/bin</tt> should be replaced with the absolute path to
the actual directory in which <tt>scheme</tt> and/or <tt>petite</tt>
resides, if not <tt>/usr/bin</tt>.
<p>
The <tt>load-program</tt> procedure, described in
Section <a href="./system.html#g111">12.4</a>, is used like <tt>load</tt>:
<p>
<p><tt>(load-program <i>string</i>)</tt>
<p>where <tt><i>string</i></tt> names the file in which the top-level program resides.
<p>
Regardless of the mechanism used, if the opening line is in one of the
forms described above, or more generally, consists of
<tt>#!</tt> followed by a space or a forward slash, the opening line
is not considered part of the program and is ignored once the Scheme
system starts up and begins to run the program.
Thus, the line may be present even in a file loaded by <tt>load-program</tt>.
In fact, <tt>load-program</tt> is ultimately used by the other two
mechanisms described above, via the value of the <tt>scheme-program</tt>
parameter described in Section <a href="./system.html#g115">12.8</a>, and it is
<tt>load-program</tt> that scans past the <tt>#!</tt> line, if present,
before evaluating the program.
<p>
A top-level program may be compiled with the
<a name="./libraries:s10"></a><tt>compile-program</tt>
procedure described in Section <a href="./system.html#g111">12.4</a>.
<tt>compile-program</tt> copies the <tt>#!</tt> line from the source
file to the object file, followed by a compiled version of the source
code.
Any libraries upon which the top-level program depends, other than
built-in libraries, must be compiled first via <tt>compile-file</tt>
or <tt>compile-library</tt>.
This can be done manually or by setting the parameter
<tt>compile-imported-libraries</tt> to <tt>#t</tt> before compiling
the program.
The program must be recompiled if any of the libraries upon which
it depends are recompiled.
A compiled top-level program can be run just like a source top-level
program via each of the mechanisms described above.
<p>
<a name="./libraries:s11"></a>In <i>Chez Scheme</i>, a library may also be defined in the REPL or placed in a
file to be loaded via <tt>load</tt> or <tt>load-library</tt>.
The syntax for a library is the same whether the library is placed in
its own file and implicitly loaded via <tt>import</tt>, entered into
the REPL, or placed in a file along with other top-level expressions to
be evaluated by <tt>load</tt>.
A top-level program may also be defined in the REPL or placed in a file
to be loaded via <tt>load</tt>, but in this case, the syntax is slightly
different.
In the language of the Revised<sup>6</sup> Report, a top-level program is merely
an unwrapped sequence of subforms consisting of an <tt>import</tt> form
and a body, delimited only by the boundaries of the file in which it
resides.
In order for a top-level program to be entered in the REPL or placed in
a file to be evaluated by <tt>load</tt>, <i>Chez Scheme</i> allows top-level
programs to be enclosed in a
<a name="./libraries:s12"></a><tt>top-level-program</tt> form.
<p>
<h3><a name="g91"></a><a name="./libraries:h3"></a>Section 10.3. Library and Top-level Program Forms<a name="SECTLIBRARYFORMS"></a></h3>
<p>
<a name="./libraries:s13"></a><span class=formdef><b>syntax</b>: <tt>(library <i>name</i> <i>exports</i> <i>imports</i> <i>library-body</i>)</tt></span>
<br>
<b>returns: </b>unspecified
<br>
<b>libraries: </b><tt>(chezscheme)</tt>
<p>The <tt>library</tt> form defines a new library with the specified
name, exports, imports, and body.
Details on the syntax and semantics of the library form are given in
Section <a href="http://scheme.com/tspl4/./libraries.html#g145">10.3</a> of <i>The Scheme Programming Language, 4th Edition</i> and in the Revised<sup>6</sup>
Report.
<p>
Only one version of a library can be loaded at any given time, and an
exception is raised if a library is implicitly loaded via <tt>import</tt>
when another version of the library has already been loaded.
<i>Chez Scheme</i> permits a different version of the library, or a new
instance of the same version, to be entered explicitly into the REPL
or loaded explicitly from a file, to facilitate interactive testing
and debugging.
The programmer should take care to make sure that any code that uses
the library is also reentered or reloaded, to make sure that code
accesses the bindings of the new instance of the library.
<p>
<p><tt>(library (test (1)) (export x) (import (rnrs)) (define x 3))<br>
(import (test))<br>
(define f (lambda () x))<br>
(f) <img src="math/csug/0.gif" alt="<graphic>"> 3
<br>
<br>
(library (test (1)) (export x) (import (rnrs)) (define x 4))<br>
(import (test))<br>
(f) <img src="math/csug/0.gif" alt="<graphic>"> 3 ; oops---forgot to redefine f<br>
(define f (lambda () x))<br>
(f) <img src="math/csug/0.gif" alt="<graphic>"> 4
<br>
<br>
(library (test (2)) (export x) (import (rnrs)) (define x 5))<br>
(import (test))<br>
(define f (lambda () x))<br>
(f) <img src="math/csug/0.gif" alt="<graphic>"> 5</tt>
<p>As with module imports (Section <a href="./syntax.html#g100">11.5</a>), a library
<tt>import</tt> may appear anywhere a definition may appear, including at
top level in the REPL, in a file to be loaded by <tt>load</tt>, or within
a <tt>lambda</tt>, <tt>let</tt>, <tt>letrec</tt>, <tt>letrec*</tt>,
etc., body.
The same <tt>import</tt> form may be used to import from both libraries
and modules.
<p>
<p><tt>(library (foo) (export a) (import (rnrs)) (define a 'a-from-foo))<br>
(module bar (b) (define b 'b-from-bar))<br>
(let () (import (foo) bar) (list a b)) <img src="math/csug/0.gif" alt="<graphic>"> (a-from-foo b-from-bar)</tt>
<p>The <tt>import</tt> keyword is not visible within a library body
unless the library imports it from the <tt>(chezscheme)</tt> library.
<p>
<a name="./libraries:s14"></a><span class=formdef><b>syntax</b>: <tt>(top-level-program <i>imports</i> <i>body</i>)</tt></span>
<br>
<b>returns: </b>unspecified
<br>
<b>libraries: </b><tt>(chezscheme)</tt>
<p><a name="./libraries:s15"></a>A <tt>top-level-program</tt> form may be entered into the REPL or placed
in a file to be loaded via <tt>load</tt>, where it behaves as if its
subforms were placed in a file and loaded via <tt>load-program</tt>.
Details on the syntax and semantics of a top-level program are given in
Section <a href="http://scheme.com/tspl4/./libraries.html#g145">10.3</a> of <i>The Scheme Programming Language, 4th Edition</i> and in the Revised<sup>6</sup>
Report.
<p>
The following transcript illustrates a <tt>top-level-program</tt> being
tested in the REPL.
<p>
<p><tt>> (top-level-program (import (rnrs))<br>
(display "hello!\n"))<br>
hello!</tt>
<p>
<h3><a name="g92"></a><a name="./libraries:h4"></a>Section 10.4. Standalone import and export forms<a name="SECTLIBRARYIMPORTEXPORTFORMS"></a></h3>
<p>
Although not required by the Revised<sup>6</sup> Report,
<i>Chez Scheme</i> supports the use of standalone import and
export forms.
The import forms can appear anywhere other definitions
can appear, including within a <tt>library</tt> body,
<tt>module</tt> (Section <a href="./syntax.html#g100">11.5</a>) body,
<tt>lambda</tt> or other local body, and at top level.
The export forms can appear within the definitions of a
<tt>library</tt> or <tt>module</tt> body to specify additional
exports for the library or module.
<p>
Within a library or top-level program, the keywords for
these forms must be imported from the <tt>(chezscheme)</tt>
library to be available for use, since they are not
defined in any of the Revised<sup>6</sup> Report libraries.
<p>
<a name="./libraries:s16"></a><span class=formdef><b>syntax</b>: <tt>(import <i>import-spec</i> ...)</tt></span>
<br><span class=formdef><b>syntax</b>: <tt>(import-only <i>import-spec</i> ...)</tt></span>
<br>
<b>returns: </b>unspecified
<br>
<b>libraries: </b><tt>(chezscheme)</tt>
<p>An <tt>import</tt> or <tt>import-only</tt> form is a definition and can
appear anywhere other definitions can appear, including
at the top level of a program, nested within the bodies of
<tt>lambda</tt> expressions, and nested within modules
and libraries.
<p>
Each <tt><i>import-spec</i></tt> must take one of the following forms.
<p>
<p><tt><i>import-set</i><br>
(for <i>import-set</i> <i>import-level</i> ...)</tt>
<p>The <tt>for</tt> wrapper and <tt><i>import-level</i></tt> are described in
Chapter <a href="http://scheme.com/tspl4/./libraries.html#g142">10</a> of <i>The Scheme Programming Language, 4th Edition</i>.
They are ignored by <i>Chez Scheme</i>, which determines
automatically the levels at which identifiers must
be imported, as permitted by the Revised<sup>6</sup> Report.
This frees the programmer from the obligation
to do so and results in more generality as well as more
precision in the set of libraries actually imported
at compile and run time [<a class=citation href="./bibliography.html#g167">21</a>,<a class=citation href="./bibliography.html#g165">19</a>].
<p>
An <tt><i>import-set</i></tt> must take one of the following forms:
<p>
<p><tt><i>library-spec</i><br>
<i>module-name</i><br>
(only <i>import-set</i> <i>identifier</i> ...)<br>
(except <i>import-set</i> <i>identifier</i> ...)<br>
(prefix <i>import-set</i> <i>prefix</i>)<br>
(add-prefix <i>import-set</i> <i>prefix</i>)<br>
(drop-prefix <i>import-set</i> <i>prefix</i>)<br>
(rename <i>import-set</i> (<i>import-name</i> <i>internal-name</i>) ...)<br>
(alias <i>import-set</i> (<i>import-name</i> <i>internal-name</i>) ...)</tt>
<p>Several of these are specified by the Revised<sup>6</sup> Report; the remainder
are <i>Chez Scheme</i> extensions, including <tt><i>module-name</i></tt> and the
<tt>add-prefix</tt>, <tt>drop-prefix</tt>, and <tt>alias</tt> forms.
<p>
An <tt>import</tt> or <tt>import-only</tt> form makes the specified bindings
visible in the scope in which they appear.
Except at top level, they differ in that <tt>import</tt> leaves all bindings
except for those shadowed by the imported names visible, whereas <tt>import-only</tt>
hides all existing bindings, i.e., makes only the imported names visible.
At top level, <tt>import-only</tt> behaves like <tt>import</tt>.
<p>
Each <tt><i>import-set</i></tt> identifies a set of names to make visible
as follows.
<p>
<dl compact>
<dt><tt><i>library-spec</i></tt>:<dd>
all exports of the library identified by the Revised<sup>6</sup> Report <tt><i>library-spec</i></tt>
(Chapter <a href="http://scheme.com/tspl4/./libraries.html#g142">10</a>.
<p>
<dt><tt><i>module-name</i></tt>:<dd>
all exports of module named by the identifier <tt><i>module-name</i></tt>
<p>
<dt><tt>(only <i>import-set</i> <i>identifier</i> ...)</tt>:<dd>
of those specified by <tt><i>import-set</i></tt>, just <tt><i>identifier</i> ...</tt>
<p>
<dt><tt>(except <i>import-set</i> <i>identifier</i> ...)</tt>:<dd>
all specified by <tt><i>import-set</i></tt> except <tt><i>identifier</i> ...</tt>
<p>
<dt><tt>(prefix <i>import-set</i> <i>prefix</i>)</tt>:<dd>
all specified by <tt><i>import-set</i></tt>, each prefixed by <tt><i>prefix</i></tt>
<p>
<dt><tt>(add-prefix <i>import-set</i> <i>prefix</i>)</tt>:<dd>
all specified by <tt><i>import-set</i></tt>, each prefixed by <tt><i>prefix</i></tt>
(just like <tt>prefix</tt>)
<p>
<dt><tt>(drop-prefix <i>import-set</i> <i>prefix</i>)</tt>:<dd>
all specified by <tt><i>import-set</i></tt>, with prefix <tt><i>prefix</i></tt> removed
<p>
<dt><tt>(rename <i>import-set</i> (<i>import-name</i> <i>internal-name</i>) ...)</tt>:<dd>
all specified by <tt><i>import-set</i></tt>, with each identifier <tt><i>import-name</i></tt>
renamed to the corresponding identifier <tt><i>internal-name</i></tt>
<p>
<dt><tt>(alias <i>import-set</i> (<i>import-name</i> <i>internal-name</i>) ...)</tt>:<dd>
all specified by <tt><i>import-set</i></tt>, with each <tt><i>internal-name</i></tt> as an alias
for <tt><i>import-name</i></tt>
</dl>
<p>
The <tt>alias</tt> form differs from the <tt>rename</tt> form in that both
<tt><i>import-name</i></tt> and <tt><i>internal-name</i></tt> are in the resulting set,
rather than just <tt><i>internal-name</i></tt>.
<p>
It is a syntax violation if the
given selection or transformation cannot be made because of a missing
export or prefix.
<p>
An identifier made visible via an import of a module or library is scoped as if its
definition appears where the import occurs.
The following example illustrates these scoping rules, using a local
module <tt>m</tt>.
<p>
<p><tt>(library (A) (export x) (import (rnrs)) (define x 0))<br>
(let ([x 1])<br>
(module m (x setter)<br>
(define-syntax x (identifier-syntax z))<br>
(define setter (lambda (x) (set! z x)))<br>
(define z 2))<br>
(let ([y x] [z 3])<br>
(import m (prefix (A) a:))<br>
(setter 4)<br>
(list x a:x y z))) <img src="math/csug/0.gif" alt="<graphic>"> (4 0 1 3)</tt>
<p>The inner <tt>let</tt> expression binds <tt>y</tt> to the value of
the <tt>x</tt> bound by the outer <tt>let</tt>.
The import of <tt>m</tt> makes the definitions of <tt>x</tt>
and <tt>setter</tt> visible within the inner <tt>let</tt>.
The import of <tt>(A)</tt> makes the variable <tt>x</tt> exported
from <tt>(A)</tt> visible as <tt>a:x</tt> within the body of the
inner <tt>let</tt>.
Thus, in the expression <tt>(list x a:x y z)</tt>, <tt>x</tt> refers to the
identifier macro exported from <tt>m</tt> while <tt>a:x</tt> refers to the
variable <tt>x</tt> exported from <tt>(A)</tt> and <tt>y</tt> and <tt>z</tt>
refer to the bindings established by the inner <tt>let</tt>.
The identifier macro <tt>x</tt> expands into a reference to
the variable <tt>z</tt> defined within the module.
<p>
With local import forms, it is rarely necessary to use the extended
import specifiers.
For example, an abstraction that encapsulates the import and reference
can easily be defined and used as follows.
<p>
<p><tt>(define-syntax from<br>
(syntax-rules ()<br>
[(_ m id) (let () (import-only m) id)]))
<br>
<br>
(library (A) (export x) (import (rnrs)) (define x 1))<br>
(let ([x 10])<br>
(module M (x) (define x 2))<br>
(cons (from (A) x) (from M x))) <img src="math/csug/0.gif" alt="<graphic>"> (1 . 2)</tt>
<p>The definition of <tt>from</tt> could use <tt>import</tt> rather than
<tt>import-only</tt>, but by using <tt>import-only</tt> we get feedback
if an attempt is made to import an identifier from a library or
module that does not export the identifier.
With <tt>import</tt> instead of <tt>import-only</tt>, the current binding,
if any, would be visible if the library or module does not export the
specified name.
<p>
<p><tt>(define-syntax lax-from<br>
(syntax-rules ()<br>
[(_ m id) (let () (import m) id)]))
<br>
<br>
(library (A) (export x) (import (rnrs)) (define x 1))
<br>
<br>
(let ([x 10])<br>
(module M (x) (define x 2))<br>
(+ (from (A) x) (from M y))) <img src="math/csug/0.gif" alt="<graphic>"> <i>exception: unbound identifier y</i><br>
<br>
(let ([x 10] [y 20])<br>
(module M (x) (define x 2))<br>
(+ (lax-from (A) x) (lax-from M y))) <img src="math/csug/0.gif" alt="<graphic>"> 21</tt>
<p>Import visibility interacts with hygienic macro expansion in such a
way that, as one might expect,
an identifier <tt><i>x</i></tt> imported from a module <tt><i>M</i></tt> is treated in
the importing context as if the corresponding export identifier had
been present in the import form along with <tt><i>M</i></tt>.
<p>
The <tt>from</tt> abstraction above works because both <tt><i>M</i></tt> and <tt><i>id</i></tt>
appear in the input to the abstraction, so the imported <tt><i>id</i></tt> captures
the reference to <tt><i>id</i></tt>.
<p>
The following variant of <tt><i>from</i></tt> also works, because both names are
introduced into the output by the transformer.
<p>
<p><tt>(module M (x) (define x 'x-of-M))<br>
(define-syntax x-from-M<br>
(syntax-rules ()<br>
[(_) (let () (import M) x)]))
<br>
<br>
(let ([x 'local-x]) (x-from-M)) <img src="math/csug/0.gif" alt="<graphic>"> x-of-M</tt>
<p>On the other hand, imports of introduced module names do not capture
free references.
<p>
<p><tt>(let ([x 'local-x])<br>
(define-syntax alpha<br>
(syntax-rules ()<br>
[(_ var) (let () (import M) (list x var))]))<br>
<br>
(alpha x)) <img src="math/csug/0.gif" alt="<graphic>"> (x-of-M local-x)</tt>
<p>Similarly, imports from free module names do not capture references
to introduced variables.
<p>
<p><tt>(let ([x 'local-x])<br>
(define-syntax beta<br>
(syntax-rules ()<br>
[(_ m var) (let () (import m) (list x var))]))
<br>
<br>
(beta M x)) <img src="math/csug/0.gif" alt="<graphic>"> (local-x x-of-M)</tt>
<p>This semantics extends to prefixed, renamed, and aliased bindings
created by the extended <tt>import</tt> specifiers <tt>prefix</tt>,
<tt>rename</tt>, and <tt>alias</tt>.
<p>
The <tt>from</tt> abstraction
works for variables but not for exported keywords, record names,
or module names, since the output is an expression and may thus appear only where
expressions may appear.
A generalization of this technique is used in the following definition
of <tt>import*</tt>, which supports renaming of imported bindings and
selective import of specific bindings---without the use of the built-in
<tt>import</tt> subforms for selecting and renaming identifiers
<p>
<p><tt>(define-syntax import*<br>
(syntax-rules ()<br>
[(_ m) (begin)]<br>
[(_ m (new old))<br>
(module (new)<br>
(module (tmp)<br>
(import m)<br>
(alias tmp old))<br>
(alias new tmp))]<br>
[(_ m id) (module (id) (import m))]<br>
[(_ m spec0 spec1 ...)<br>
(begin (import* m spec0) (import* m spec1 ...))]))</tt>
<p>To selectively import an identifier from module or library <tt>m</tt>, the
<tt>import*</tt> form expands into an anonymous module that first
imports all exports of <tt>m</tt> then re-exports only the selected
identifier.
To rename on import the macro expands into an anonymous module that
instead exports an alias (Section <a href="./syntax.html#g105">11.10</a>) bound to the new name.
<p>
If the output placed the definition of <tt>new</tt> in the same
scope as the import of <tt>m</tt>, a naming conflict would arise
whenever <tt>new</tt> is also present in the interface
of <tt>m</tt>.
To prevent this, the output instead places the import within a nested
anonymous module and links <tt>old</tt> and <tt>new</tt>
by means of an alias for the introduced identifier <tt>tmp</tt>.
<p>
The macro expands recursively to handle multiple import specifications.
Each of the following examples imports <tt>cons</tt> as <tt>+</tt> and <tt>+</tt> as
<tt>cons</tt>, which is probably not a very good idea.
<p>
<p><tt>(let ()<br>
(import* scheme (+ cons) (cons +))<br>
(+ (cons 1 2) (cons 3 4))) <img src="math/csug/0.gif" alt="<graphic>"> (3 . 7)
<br>
<br>
(let ()<br>
(import* (rnrs) (+ cons) (cons +))<br>
(+ (cons 1 2) (cons 3 4))) <img src="math/csug/0.gif" alt="<graphic>"> (3 . 7)</tt>
<p><a name="./libraries:s17"></a><span class=formdef><b>syntax</b>: <tt>(export <i>export-spec</i> ...)</tt></span>
<br>
<b>returns: </b>unspecified
<br>
<b>libraries: </b><tt>(chezscheme)</tt>
<p>An <tt>export</tt> form is a definition and can appear with other
definitions at the front of a <tt>library</tt> or <tt>module</tt>.
It is a syntax error for an <tt>export</tt> form to appear in other
contexts, including at top level or among the definitions of a
top-level program or <tt>lambda</tt> body.
<p>
Each <tt><i>export-spec</i></tt> must take one of the following forms.
<p>
<p><tt><i>identifier</i><br>
(rename (<i>internal-name</i> <i>export-name</i>) ...)<br>
(import <i>import-spec</i> ...)</tt>
<p>where each <tt><i>internal-name</i></tt> and <tt><i>export-name</i></tt> is an identifier.
The first two are syntactically identical to <tt>library</tt>
<tt><i>export-spec</i></tt>s, while the third is syntactically
identical to a <i>Chez Scheme</i> <tt>import</tt> form, which is an extension of the
R6RS library <tt>import</tt> subform.
The first form names a single export, <tt><i>identifier</i></tt>, whose export
name is the same as its internal name.
The second names a set of exports, each of whose export name is
given explicitly and may differ from its internal name.
<p>
For the third, the identifiers identified by the <tt>import</tt> form
become exports, with aliasing, renaming, prefixing, etc., as specified by the
<tt><i>import-spec</i></tt>s.
The module or library whose bindings are exported by an <tt>import</tt>
form appearing within an <tt>export</tt> form can
be defined within or outside the exporting module or library and need
not be imported elsewhere within the exporting module or library.
<p>
The following library exports a two-armed-only variant of <tt>if</tt>
along with all remaining bindings of the <tt>(rnrs)</tt> library.
<p>
<p><tt>(library (rnrs-no-one-armed-if) (export) (import (except (chezscheme) if))<br>
(export if (import (except (rnrs) if)))<br>
(define-syntax if<br>
(let ()<br>
(import (only (rnrs) if))<br>
(syntax-rules ()<br>
[(_ tst thn els) (if tst thn els)]))))
<br>
<br>
(import (rnrs-no-one-armed-if))<br>
(if #t 3 4) <img src="math/csug/0.gif" alt="<graphic>"> 3<br>
(if #t 3) <img src="math/csug/0.gif" alt="<graphic>"> <i>exception: invalid syntax</i></tt>
<p>Another way to define the same library would be to define the
two-armed-only <tt>if</tt> with a different internal name and use
<tt>rename</tt> to export it under the name <tt>if</tt>:
<p>
<p><tt>(library (rnrs-no-one-armed-if) (export) (import (chezscheme))<br>
(export (rename (two-armed-if if)) (import (except (rnrs) if)))<br>
(define-syntax two-armed-if<br>
(syntax-rules ()<br>
[(_ tst thn els) (if tst thn els)])))
<br>
<br>
(import (rnrs-no-one-armed-if))<br>
(if #t 3 4) <img src="math/csug/0.gif" alt="<graphic>"> 3<br>
(if #t 3) <img src="math/csug/0.gif" alt="<graphic>"> <i>exception: invalid syntax</i></tt>
<p>The placement of the <tt>export</tt> form in the library body is
irrelevant, e.g., the <tt>export</tt> form can appear after the
definition in the examples above.
<p>
<a name="./libraries:s18"></a><span class=formdef><b>syntax</b>: <tt>(indirect-export <i>id</i> <i>indirect-id</i> ...)</tt></span>
<br>
<b>returns: </b>unspecified
<br>
<b>libraries: </b><tt>(chezscheme)</tt>
<p>This form is a definition and can appear wherever any other definition
can appear.
<p>
An <tt>indirect-export</tt> form declares that the named
<tt><i>indirect-id</i></tt>s are indirectly exported to top level if <tt><i>id</i></tt>
is exported to top level.
<p>
In general, if an identifier is not directly exported by a library or
module, it can be referenced outside of the library or module only in
the expansion of a macro defined within and exported from the library
or module.
Even this cannot occur for libraries or modules defined at top level
(or nested within other libraries or modules), unless either (1)
the library or module has been set up to implicitly export all
identifiers as indirect exports, or (2) each indirectly exported
identifier is explicitly declared as an indirect export of some
other identifier that is exported, either directly or indirectly, from
the library or module, via an <tt>indirect-export</tt> or the built-in
indirect export feature of a <tt>module</tt> export subform.
By default, (1) is true for a library and false for a module, but the
default can be overridden via the <tt>implicit-exports</tt>
form, which is described below.
<p>
This form is meaningful only within a top-level library, top-level module,
or module enclosed within a library or top-level module, although it
has no effect if the library or module already implicitly exports all
bindings.
It is allowed anywhere else definitions can appear, however, so macros
that expand into indirect export forms can be used in any definition
context.
<p>
Indirect exports are listed so the compiler can determine the
exact set of bindings (direct and indirect) that must be inserted
into the top-level environment, and conversely, the set of bindings
that may be treated more efficiently as local bindings (and
perhaps discarded, if they are not used).
<p>
In the example below, <tt>indirect-export</tt> is used to indirectly
export <tt>count</tt> to top level when <tt>current-count</tt> is
exported to top level.
<p>
<p><tt>(module M (bump-count current-count)<br>
(define-syntax current-count (identifier-syntax count))<br>
(indirect-export current-count count)<br>
(define count 0)<br>
(define bump-count<br>
(lambda ()<br>
(set! count (+ count 1)))))
<br>
<br>
(import M)<br>
(bump-count)<br>
current-count <img src="math/csug/0.gif" alt="<graphic>"> 1<br>
count <img src="math/csug/0.gif" alt="<graphic>"> <i>exception: unbound identifier count</i></tt>
<p>An <tt>indirect-export</tt> form is not required to make <tt>count</tt>
visible for <tt>bump-count</tt>, since it is a procedure whose code
is contained within the module rather than a macro that might expand
into a reference to <tt>count</tt> somewhere outside the module.
<p>
It is often useful to use <tt>indirect-export</tt> in the output
of a macro that expands into another macro named <tt><i>a</i></tt> if
<tt><i>a</i></tt> expands into references to identifiers that might not
be directly exported, as illustrated by the alternative definition
of module <tt>M</tt> above.
<p>
<p><tt>(define-syntax define-counter<br>
(syntax-rules ()<br>
[(_ getter bumper init incr)<br>
(begin<br>
(define count init)<br>
(define-syntax getter (identifier-syntax count))<br>
(indirect-export getter count)<br>
(define bumper<br>
(lambda ()<br>
(set! count (incr count)))))]))
<br>
<br>
(module M (bump-count current-count)<br>
(define-counter current-count bump-count 0 add1))</tt>
<p><a name="./libraries:s19"></a><span class=formdef><b>syntax</b>: <tt>(implicit-exports #t)</tt></span>
<br><span class=formdef><b>syntax</b>: <tt>(implicit-exports #f)</tt></span>
<br>
<b>returns: </b>unspecified
<br>
<b>libraries: </b><tt>(chezscheme)</tt>
<p>An <tt>implicit-exports</tt> form is a definition and can appear with other
definitions at the front of a <tt>library</tt> or <tt>module</tt>.
It is a syntax error for an <tt>implicit-exports</tt> form to appear in other
contexts, including at top level or among the definitions of a
top-level program or <tt>lambda</tt> body.
<p>
The <tt>implicit-exports</tt> form determines whether identifiers
not directly exported from a module or library are automatically