source: project/wiki/eggref/5/r7rs @ 36801

Last change on this file since 36801 was 36801, checked in by evhan, 8 months ago

wiki/eggref: update docs/formatting/urls and eggref/5/{r7rs,fancypants,chicken-belt}

File size: 7.5 KB
Line 
1[[tags: egg]]
2
3== r7rs
4
5[[toc:]]
6
7== Description
8
9This egg provides support for most of the R7RS Scheme language.
10
11=== Requirements
12
13CHICKEN version 5.0 or newer, and the following extensions:
14
15* [[matchable]]
16* [[srfi-1]]
17* [[srfi-13]]
18
19== Usage
20
21To add R7RS support to a program, load the {{r7rs}} extension:
22
23<enscript highlight="scheme">
24(import (r7rs))
25</enscript>
26
27This makes most features of the R7RS available, and immediately imports
28all identifiers from the {{(scheme base)}} library.
29
30=== Compiling
31
32To compile R7RS code, it's usually sufficient to load the {{r7rs}}
33extension by providing the {{-require-extension}} (or {{-R}}) flag to
34{{csc(1)}}:
35
36<enscript highlight="sh">
37$ csc -R r7rs foo.scm
38</enscript>
39
40This is equivalent to beginning your program with {{(import (r7rs))}},
41but avoids the need to modify your source with CHICKEN-specific forms.
42Alternatively, you can {{cond-expand}} on the extension to load it only
43when your program is running on CHICKEN:
44
45<enscript highlight="scheme">
46(cond-expand
47  (r7rs)
48  (chicken (import (r7rs))))
49</enscript>
50
51Some syntactic features of the R7RS, such as long-form booleans and
52extended number literals, require that {{r7rs}} support be activated
53during compilation. To do this, load the {{r7rs}} egg as a compiler
54extension by providing the {{-extend}} (or {{-X}}) flag to {{csc(1)}},
55as well:
56
57<enscript highlight="sh">
58$ csc -X r7rs -R r7rs foo.scm
59</enscript>
60
61=== Libraries
62
63R7RS library forms are converted into standard CHICKEN modules at
64compile time. During this conversion, R7RS library names (which are
65proper lists rather than simple identifiers) are mapped to module names
66by joining their components with periods. Thus, the following programs
67are roughly equivalent:
68
69<enscript highlight="scheme">
70;; A standard CHICKEN module.
71(module (foo bar) (baz)
72  (import scheme)
73  (define baz 1))
74</enscript>
75
76<enscript highlight="scheme">
77;; An R7RS library definition.
78(import (r7rs))
79(define-library (foo bar)
80  (import (scheme base))
81  (export baz)
82  (begin (define baz 1)))
83</enscript>
84
85==== Inclusion
86
87Include forms within library definitions ({{include}}, {{include-ci}},
88and {{include-library-declarations}}) search for files relatively to the
89including file, as well as on the standard include path.
90
91The {{include}} form provided by the {{(scheme base)}} also includes
92files relatively, but only when used at the top level.
93
94==== Conditional expansion
95
96The {{(library ...)}} feature test of the {{(scheme base)}} library's
97{{cond-expand}} form searches for the specified library amongst all
98currently-loaded modules, any import files in the current directory, and
99any libraries registered in CHICKEN's extensions repository. Refer to
100the CHICKEN manual for more information about import files and
101extensions.
102
103<enscript highlight="scheme">
104(import (r7rs))
105(define spiffy-installed?
106  (cond-expand
107    ((library (spiffy)) #t)
108    (else #f)))
109</enscript>
110
111=== Macros
112
113The {{r7rs}} extension's {{syntax-rules}} behaves slightly differently
114than that of CHICKEN proper in a few edge cases. Specifically, it treats
115undercores as wildcards and allows ellipses within syntax templates to
116be escaped with {{(... <template>)}}.
117
118To use the {{r7rs}} extension's version of {{syntax-rules}}, it must be
119imported at macro expansion time with {{import-for-syntax}}:
120
121<enscript highlight="scheme">
122(import-for-syntax (r7rs)) ; Load r7rs's syntax-rules at expansion time.
123
124(define-syntax be-like-begin
125  (syntax-rules ()
126    ((be-like-begin name)
127     (define-syntax name
128       (syntax-rules ()
129         ((name expr (... ...))
130          (begin expr (... ...))))))))
131
132(be-like-begin sequence)
133(sequence 1 2 3 4) ; => 4
134</enscript>
135
136== Limitations
137
138=== Unsupported features
139
140The following features are currently unsupported:
141
142; {{\x...;}} escaped characters : Semicolon-terminated hex values in symbols and strings are not recognized, and will be treated incorrectly if used.
143; {{export}} renaming : Export forms with renaming, as in {{(export (rename foo bar))}}, currently signal an error.
144; {{equal?}} : The R7RS requires that {{equal?}} terminate when given cyclic data, however the current implementation may enter an infinite loop.
145
146=== Case folding
147
148The {{#!fold-case}} and {{#!no-fold-case}} directives are only supported
149when the {{(scheme read)}} library has been loaded. Use of these
150directives without first importing {{(scheme read)}} will signal an
151error.
152
153=== Procedure names
154
155Because the {{r7rs}} egg reexports some procedures directly from CHICKEN
156core under different identifiers, {{r7rs}} procedure names (as accessed
157by {{procedure-information}}) may not always be correct.
158
159=== Library loading
160
161Some implementations treat library name components as filesystem paths
162and attempt to load the library {{(foo bar baz)}} from the file
163"foo/bar/baz.scm", for example. This egg does not.
164
165Some implementations use the ".sld" file extension for files containing
166R7RS library definitions. This egg currently provides no special support
167for such files.
168
169=== Libraries
170
171==== scheme char
172
173The procedures exported by the {{(scheme char)}} library are not
174Unicode-aware.
175
176==== scheme r5rs
177
178The {{(scheme r5rs)}} library exports the R5RS versions of many
179identifiers. As such, some of its procedures are incompatible with their
180R7RS versions, and an unqualified import of the {{(scheme r5rs)}}
181library will overwrite those R7RS versions and lead to subtle problems.
182
183== Examples
184
185=== Compilation
186
187<enscript highlight="sh">
188$ cat foo.bar.scm
189(define-library (foo bar)
190  (import (scheme base))
191  (export baz)
192  (begin (define baz 1)))
193$ csc -X r7rs -R r7rs -sJ -o foo.bar.so foo.bar.scm
194$ cat program.scm
195(import (foo bar)
196        (scheme write))
197(display baz)
198(display #\newline)
199$ csc -X r7rs -R r7rs program.scm
200$ ./program
2011
202</enscript>
203
204== About
205
206=== Maintainers
207
208The CHICKEN Team
209
210=== History
211
212; 1.0.1 : Enable static linking
213; 1.0.0 : Port to CHICKEN 5
214; 0.0.6 : Export {{exp}} and {{truncate}}; drop export of nonexistent {{infinite?}} from scheme.inexact with no-numbers
215; 0.0.5 : Limit implicit imports in libraries to "meta language" (thanks to John J. Foerch)
216; 0.0.4 : Fix invalid import warnings
217; 0.0.3 : Add read and write hooks
218; 0.0.2 : More complete libraries
219; 0.0.1 : Prerelease
220
221=== License
222
223 Copyright (c) 2013-2018 The CHICKEN Team
224 
225 Redistribution and use in source and binary forms, with or without
226 modification, are permitted provided that the following conditions
227 are met:
228 
229 1. Redistributions of source code must retain the above copyright
230    notice, this list of conditions and the following disclaimer.
231 2. Redistributions in binary form must reproduce the above copyright
232    notice, this list of conditions and the following disclaimer in the
233    documentation and/or other materials provided with the distribution.
234 3. The name of the authors may not be used to endorse or promote products
235    derived from this software without specific prior written permission.
236 
237 THIS SOFTWARE IS PROVIDED BY THE AUTHORS "AS IS" AND ANY EXPRESS OR
238 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
239 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
240 IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
241 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
242 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
243 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
244 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
245 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
246 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.