source: project/chicken/trunk/manual/Unit eval @ 5945

Last change on this file since 5945 was 5945, checked in by felix winkelmann, 12 years ago

renamed some tools in misc/; apply hack fix on x86-64 (again); re-added manual

File size: 9.2 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit eval
5
6This unit has support for evaluation and macro-handling. This unit is used
7by default, unless the program is compiled with the {{-explicit-use}}
8option.
9
10=== Loading code
11
12==== load
13
14 [procedure] (load FILE [EVALPROC])
15
16Loads and evaluates expressions from the given source file, which may
17be either a string or an input port.  Each expression read is passed to
18{{EVALPROC}} (which defaults to {{eval}}).  On platforms that
19support it (currently native Windows, Linux ELF and Solaris), {{load}} can be used
20to load compiled programs:
21
22 % cat x.scm
23 (define (hello) (print "Hello!"))
24 % csc -s x.scm
25 % csi -q
26 #;1> (load "x.so")
27 ; loading x.so ...
28 #;2> (hello)
29 Hello!
30 #;3>
31
32The second argument to {{load}} is ignored when loading compiled
33code.
34If source code is loaded from a port, then that port is closed after
35all expressions have been read.
36
37Compiled code can be re-loaded, but care has to be taken, if code
38from the replaced dynamically loaded module is still executing (i.e.
39if an active continuation refers to compiled code in the old module).
40
41Support for reloading compiled code dynamically is still experimental.
42
43==== load-relative
44
45 [procedure] (load-relative FILE [EVALPROC])
46
47Similar to {{load}}, but loads {{FILE}} relative to the path
48of the currently loaded file.
49
50==== load-noisily
51
52 [procedure] (load-noisily FILE #!key EVALUATOR TIME PRINTER)
53
54As {{load}} but the result(s) of each evaluated toplevel-expression
55is written to standard output. If {{EVALUATOR}} is given and not {{#f}},
56then each expression is evaluated by calling this argument with the read
57expression as argument. If {{TIME}} is given and not false, then
58the execution time of each expression is shown (as with the {{time}} macro).
59If {{PRINTER}} is given and not false, then each expression is
60printed before evaluation by applying the expression to the value of this
61argument, which should be a one-argument procedure.
62
63See also the [[http://chicken.wiki.br/Parameters#load-verbose|load-verbose]] parameter.
64==== load-library
65
66 [procedure] (load-library UNIT [LIBRARYFILE])
67
68On platforms that support dynamic loading, {{load-library}} loads
69the compiled library unit {{UNIT}} (which should be a symbol). If the
70string {{LIBRARYFILE}} is given, then the given shared library will
71be loaded and the toplevel code of the contained unit will be executed.
72If no {{LIBRARYFILE}} argument is given, then the following libraries
73are checked for the required unit:
74
75* a file named ''{{<UNIT>.so}}''
76* the files given in the parameter {{dynamic-load-libraries}}
77
78If the unit is not found, an error is signaled.  When the library unit
79can be successfully loaded, a feature-identifier named {{UNIT}}
80is registered. If the feature is already registered before loading,
81the {{load-library}} does nothing.
82
83==== set-dynamic-load-mode!
84
85 [procedure] (set-dynamic-load-mode! MODELIST)
86
87On systems that support dynamic loading of compiled code via the {{dlopen(3)}}
88interface (for example Linux and Solaris), some options can be specified to
89fine-tune the behaviour of the dynamic linker. {{MODE}} should be a list of
90symbols (or a single symbol) taken from the following set:
91
92; {{local}} : If {{local}} is given, then any C/C++ symbols defined in the dynamically loaded file are not available for subsequently loaded files and libraries. Use this if you have linked foreign code into your dynamically loadable file and if you don't want to export them (for example because you want to load another file that defines the same symbols).
93; {{global}} : The default is {{global}}, which means all C/C++ symbols are available to code loaded at a later stage.
94; {{now}} : If {{now}} is specified, all symbols are resolved immediately.
95; {{lazy}} : Unresolved symbols are resolved as code from the file is executed. This is the default.
96
97Note that this procedure does not control the way Scheme variables are handled -
98this facility is mainly of interest when accessing foreign code.
99
100
101=== Read-eval-print loop
102
103==== repl
104
105 [procedure] (repl)
106
107Start a new read-eval-print loop. Sets the {{reset-handler}} so that
108any invocation of {{reset}} restarts the read-eval-print loop. Also
109changes the current exception-handler to display a message, write
110any arguments to the value of {{(current-error-port)}} and reset.
111
112
113=== Macros
114
115==== get-line-number
116
117 [procedure] (get-line-number EXPR)
118
119If {{EXPR}} is a pair with the car being a symbol, and line-number
120information is available for this expression, then this procedure returns
121the associated line number. If line-number information is not available,
122then {{#f}} is returned.  Note that line-number information for
123expressions is only available in the compiler.
124
125==== macro?
126
127 [procedure] (macro? SYMBOL)
128
129Returns {{#t}} if there exists a macro-definition for {{SYMBOL}}.
130
131==== macroexpand
132
133 [procedure] (macroexpand X)
134
135If {{X}} is a macro-form, expand the macro (and repeat expansion
136until expression is a non-macro form).  Returns the resulting expression.
137
138==== macroexpand-1
139
140 [procedure] (macroexpand-1 X)
141
142If {{X}} is a macro-form, expand the macro.  Returns the resulting
143expression.
144
145==== undefine-macro!
146
147 [procedure] (undefine-macro! SYMBOL)
148
149Remove the current macro-definition of the macro named {{SYMBOL}}.
150
151==== syntax-error
152
153 [procedure] (syntax-error [LOCATION] MESSAGE ARGUMENT ...)
154
155Signals an exception of the kind {{(exn syntax)}}. Otherwise identical to
156{{error}}.
157
158
159=== Loading extension libraries
160
161This functionality is only available on platforms that support dynamic
162loading of compiled code. Currently Linux, BSD, Solaris, Windows (with Cygwin) and HP/UX are supported.
163
164==== repository-path
165
166; [parameter] repository-path :
167Contains a string naming the path to the extension repository, which defaults to
168either the value of the environment variable {{CHICKEN_REPOSITORY}}, the value
169of the environment variable {{CHICKEN_HOME}} or the default library path
170(usually {{/usr/local/lib/chicken}} on UNIX systems).
171
172==== extension-information
173
174 [procedure] (extension-information ID)
175
176If an extension with the name {{ID}} is installed and if it has a setup-information
177list registered in the extension repository, then the info-list is returned. Otherwise
178{{extension-information}} returns {{#f}}.
179
180==== provide
181
182 [procedure] (provide ID ...)
183
184Registers the extension IDs {{ID ...}} as loaded. This is mainly
185intended to provide aliases for certain extension identifiers.
186
187==== provided?
188
189 [procedure] (provided? ID ...)
190
191Returns {{#t}} if the extension with the IDs {{ID ...}}
192are currently loaded, or {{#f}} otherwise.
193
194==== require
195
196 [procedure] (require ID ...)
197 [procedure] (require-for-syntax ID ...)
198
199If the extension library {{ID}} is not already loaded into the
200system, then {{require}} will lookup the location of the shared
201extension library and load it. If {{ID}} names a library-unit of
202the base system, then it is loaded via {{load-library}}.  If no
203extension library is available for the given ID, then an attempt is
204made to load the file {{ID.so}} or {{ID.scm}} (in that order)
205from one of the following locations:
206
207* the current include path, which defaults to the pathnames given in {{CHICKEN_INCLUDE_PATH}} and {{CHICKEN_HOME}}.
208* the current directory
209
210{{ID}} should be a string or a symbol. The difference between {{require}} and
211{{require-for-syntax}} is the the latter loads the extension library
212at compile-time (the argument is still evaluated), while the former
213loads it at run-time.
214
215==== set-extension-specifier!
216
217 [procedure] (set-extension-specifier! SYMBOL PROC)
218
219Registers the handler-procedure {{PROC}} as a extension-specifier with the
220name {{SYMBOL}}. This facility allows extending the set of valid extension
221specifiers to be used with {{require-extension}}. When {{register-extension}}
222is called with an extension specifier of the form {{(SPEC ...)}} and {{SPEC}}
223has been registered with {{set-extension-specifier!}}, then {{PROC}} will
224be called with two arguments: the specifier and the previously installed handler
225(or {{#f}} if no such handler was defined). The handler should return a new
226specifier that will be processed recursively. If the handler returns a vector,
227then each element of the vector will be processed recursively.
228Alternatively the handler may return a string which specifies a file to be loaded:
229
230<enscript highlight=scheme>
231(eval-when (compile eval)
232  (set-extension-specifier!
233    'my-package
234    (lambda (spec old)
235      (make-pathname my-package-directory (->string (cadr spec))) ) ) )
236
237(require-extension (my-package stuff))     ; --> expands into '(load "my-package-dir/stuff")
238</enscript>
239
240Note that the handler has to be registered at compile time, if it is to be
241visible in compiled code.
242
243
244=== System information
245
246==== chicken-home
247
248 [procedure] (chicken-home)
249
250Returns a string given the installation directory (usually {{/usr/local/share/chicken}} on UNIX-like systems).
251If the environment variable {{CHICKEN_HOME}} is set, then its value will be returned. As a last option,
252if the environment variable {{CHICKEN_PREFIX}} is set, then {{chicken-home}} will return
253{{$CHICKEN_PREFIX/share}}.
254
255
256=== Eval
257
258==== eval
259
260 [procedure] (eval EXP [ENVIRONMENT])
261
262Evaluates {{EXP}} and returns the result of the evaluation. The second argument is optional
263and defaults to the value of {{(interaction-environment)}}.
264
265
266Previous: [[Unit library]]
267
268Next: [[Unit extras]]
Note: See TracBrowser for help on using the repository browser.