summaryrefslogtreecommitdiff
path: root/doc/ref/scheme-options.texi
blob: e4da66355ff27ac783a7aa0b68438cfd70456aaa (plain)
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
@page
@node Options and Config
@chapter Runtime Options and Configuration

Guile's behaviour can be modified by setting options.  For example, is
the language that Guile accepts case sensitive, or should the debugger
automatically show a backtrace on error?

Guile has two levels of interface for managing options: a low-level
control interface, and a user-level interface which allows the enabling
or disabling of options.

Moreover, the options are classified in groups according to whether they
configure @emph{reading}, @emph{printing}, @emph{debugging} or
@emph{evaluating}.

@menu
* General option interface::
* Reader options::
* Printing options::
* Debugger options::
* Evaluator options::
* Evaluator trap options::
* Examples of option use::
* Install Config::              Installation and configuration data.
@end menu

@node General option interface
@section General option interface

We will use the expression @code{<group>} to represent @code{read},
@code{print}, @code{debug} or @code{evaluator}.

@subheading Low level

@c NJFIXME
@deffn primitive <group>-options-interface
@deffnx primitive read-options-interface [SOME-INT]
@deffnx primitive print-options-interface [SOME-INT]
@deffnx primitive evaluator-traps-interface [SOME-INT]
@deffnx primitive read-options-interface [SOME-INT]
[FIXME: I have just taken the comments for C routine scm_options that
implements all of these.  It needs to be presented better.]

If scm_options is called without arguments, the current option setting
is returned.  If the argument is an option setting, options are altered
and the old setting is returned.  If the argument isn't a list, a list
of sublists is returned, where each sublist contains option name, value
and documentation string.
@end deffn


@subheading User level

@c @deftp {Data type} scm_option
@c @code{scm_option} is used to represent run time options.  It can be a
@c @emph{boolean} type, in which case the option will be set by the strings
@c @code{"yes"} and @code{"no"}.  It can be a
@c @end deftp

@c NJFIXME
@deffn procedure <group>-options [arg]
@deffnx procedure read-options [arg]
@deffnx procedure print-options [arg]
@deffnx procedure debug-options [arg]
@deffnx procedure traps [arg]
These functions list the options in their group.  The optional argument
@var{arg} is a symbol which modifies the form in which the options are
presented.

With no arguments, @code{<group>-options} returns the values of the
options in that particular group.  If @var{arg} is @code{'help}, a
description of each option is given.  If @var{arg} is @code{'full},
programmers' options are also shown.

@var{arg} can also be a list representing the state of all options.  In
this case, the list contains single symbols (for enabled boolean
options) and symbols followed by values.
@end deffn
[FIXME: I don't think 'full is ever any different from 'help.  What's
up?]

@c NJFIXME
@deffn procedure <group>-enable option-symbol
@deffnx procedure read-enable option-symbol
@deffnx procedure print-enable option-symbol
@deffnx procedure debug-enable option-symbol
@deffnx procedure trap-enable option-symbol
These functions set the specified @var{option-symbol} in their options
group.  They only work if the option is boolean, and throw an error
otherwise.
@end deffn

@c NJFIXME
@deffn procedure <group>-disable option-symbol
@deffnx procedure read-disable option-symbol
@deffnx procedure print-disable option-symbol
@deffnx procedure debug-disable option-symbol
@deffnx procedure trap-disable option-symbol
These functions turn off the specified @var{option-symbol} in their
options group.  They only work if the option is boolean, and throw an
error otherwise.
@end deffn

@c NJFIXME
@deffn syntax <group>-set! option-symbol value
@deffnx syntax read-set! option-symbol value
@deffnx syntax print-set! option-symbol value
@deffnx syntax debug-set! option-symbol value
@deffnx syntax trap-set! option-symbol value
These functions set a non-boolean @var{option-symbol} to the specified
@var{value}.
@end deffn


@node Reader options
@section Reader options
@cindex options - read
@cindex read options

Here is the list of reader options generated by typing
@code{(read-options 'full)} in Guile.  You can also see the default
values.

@smalllisp
keywords         #f      Style of keyword recognition: #f or 'prefix
case-insensitive no      Convert symbols to lower case.
positions        yes     Record positions of source code expressions.
copy             no      Copy source code expressions.
@end smalllisp

Notice that while Standard Scheme is case insensitive, to ease
translation of other Lisp dialects, notably Emacs Lisp, into Guile,
Guile is case-sensitive by default.

To make Guile case insensitive, you can type

@smalllisp
(read-enable 'case-insensitive)
@end smalllisp

@node Printing options
@section Printing options

Here is the list of print options generated by typing
@code{(print-options 'full)} in Guile.  You can also see the default
values.

@smallexample
source          no      Print closures with source.
closure-hook    #f      Hook for printing closures.
@end smallexample


@node Evaluator options
@section Evaluator options
These are the evaluator options with their default values, as they are
printed by typing @code{(eval-options 'full)} in Guile.

@smallexample
stack           22000   Size of thread stacks (in machine words).
@end smallexample

@node Evaluator trap options
@section Evaluator trap options
[FIXME: These flags, together with their corresponding handlers, are not
user level options.  Probably this entire section should be moved to the
documentation about the low-level programmer debugging interface.]

Here is the list of evaluator trap options generated by typing
@code{(traps 'full)} in Guile.  You can also see the default values.

@smallexample
exit-frame      no      Trap when exiting eval or apply.
apply-frame     no      Trap when entering apply.
enter-frame     no      Trap when eval enters new frame.
traps		yes	Enable evaluator traps.
@end smallexample

@deffn apply-frame-handler key cont tailp
Called when a procedure is being applied.

Called if:

@itemize @bullet
@item
evaluator traps are enabled [traps interface], and
@item
either
@itemize @minus
@item
@code{apply-frame} is enabled [traps interface], or
@item
trace mode is on [debug-options interface], and the procedure being
called has the trace property enabled.
@end itemize
@end itemize

If cheap traps are enabled [debug-options interface], @var{cont} is a
debug object, otherwise it is a restartable continuation.

@var{tailp} is true if this is a tail call
@end deffn

@deffn exit-frame-handler key cont retval
Called when a value is returned from a procedure.

Called if:

@itemize @bullet
@item
evaluator traps are enabled [traps interface], and
@item
either
@itemize @minus
@item
 @code{exit-frame} is enabled [traps interface], or
@item
trace mode is on [debug-options interface], and the procedure being
called has the trace property enabled.
@end itemize
@end itemize

If cheap traps are enabled [debug-options interface], @var{cont} is a
debug object, otherwise it is a restartable continuation.

@var{retval} is the return value.
@end deffn

@node Debugger options
@section Debugger options

Here is the list of print options generated by typing
@code{(debug-options 'full)} in Guile.  You can also see the default
values.

@smallexample
stack           20000   Stack size limit (0 = no check).
debug           yes     Use the debugging evaluator.
backtrace       no      Show backtrace on error.
depth           20      Maximal length of printed backtrace.
maxdepth        1000    Maximal number of stored backtrace frames.
frames          3       Maximum number of tail-recursive frames in backtrace.
indent          10      Maximal indentation in backtrace.
backwards       no      Display backtrace in anti-chronological order.
procnames       yes     Record procedure names at definition.
trace           no      *Trace mode.
breakpoints     no      *Check for breakpoints.
cheap           yes     *Flyweight representation of the stack at traps.
@end smallexample


@node Examples of option use
@section Examples of option use

Here is an example of a session in which some read and debug option
handling procedures are used.  In this example, the user

@enumerate
@item
Notices that the symbols @code{abc} and @code{aBc} are not the same
@item
Examines the @code{read-options}, and sees that @code{case-insensitive}
is set to ``no''.
@item
Enables @code{case-insensitive}
@item
Verifies that now @code{aBc} and @code{abc} are the same
@item
Disables @code{case-insensitive} and enables debugging @code{backtrace}
@item
Reproduces the error of displaying @code{aBc} with backtracing enabled
[FIXME: this last example is lame because there is no depth in the
backtrace.  Need to give a better example, possibly putting debugging
option examples in a separate session.]
@end enumerate


@smalllisp
guile> (define abc "hello")
guile> abc
"hello"
guile> aBc
ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)

Type "(backtrace)" to get more information.
guile> (read-options 'help)
keywords	#f	Style of keyword recognition: #f or 'prefix
case-insensitive	no	Convert symbols to lower case.
positions	yes	Record positions of source code expressions.
copy		no	Copy source code expressions.
guile> (debug-options 'help)
stack		20000	Stack size limit (0 = no check).
debug		yes	Use the debugging evaluator.
backtrace	no	Show backtrace on error.
depth		20	Maximal length of printed backtrace.
maxdepth	1000	Maximal number of stored backtrace frames.
frames		3	Maximum number of tail-recursive frames in backtrace.
indent		10	Maximal indentation in backtrace.
backwards	no	Display backtrace in anti-chronological order.
procnames	yes	Record procedure names at definition.
trace		no	*Trace mode.
breakpoints	no	*Check for breakpoints.
cheap		yes	*Flyweight representation of the stack at traps.
guile> (read-enable 'case-insensitive)
(keywords #f case-insensitive positions)
guile> aBc
"hello"
guile> (read-disable 'case-insensitive)
(keywords #f positions)
guile> (debug-enable 'backtrace)
(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
guile> aBc

Backtrace:
0* aBc

ERROR: In expression aBc:
ERROR: Unbound variable: aBc
ABORT: (misc-error)
guile>
@end smalllisp


@node Install Config
@section Installation and Configuration Data

It is often useful to have site-specific information about the current
Guile installation.  This chapter describes how to find out about
Guile's configuration at run time.

@deffn primitive version
@deffnx primitive major-version
@deffnx primitive minor-version
@deffnx primitive micro-version
Return a string describing Guile's version number, or its major, minor
or micro version number, respectively.

@lisp
(version) @result{} "1.6.0"
(major-version) @result{} "1"
(minor-version) @result{} "6"
(micro-version) @result{} "0"
@end lisp
@end deffn

@c NJFIXME not in libguile!
@deffn primitive libguile-config-stamp
Return a string describing the date on which @code{libguile} was
configured.  This is used to determine whether the Guile core
interpreter and the ice-9 runtime have grown out of date with one
another.
@end deffn

@deffn primitive %package-data-dir
Return the name of the directory where Scheme packages, modules and
libraries are kept.  On most Unix systems, this will be
@samp{/usr/local/share/guile}.
@end deffn

@deffn primitive %library-dir
Return the directory where the Guile Scheme library files are installed.
E.g., may return "/usr/share/guile/1.3.5".
@end deffn

@deffn primitive %site-dir
Return the directory where the Guile site files are installed.
E.g., may return "/usr/share/guile/site".
@end deffn

@deffn primitive parse-path path [tail]
Parse @var{path}, which is expected to be a colon-separated
string, into a list and return the resulting list with
@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
is returned.
@end deffn

@deffn primitive search-path path filename [extensions]
Search @var{path} for a directory containing a file named
@var{filename}. The file must be readable, and not a directory.
If we find one, return its full filename; otherwise, return
@code{#f}.  If @var{filename} is absolute, return it unchanged.
If given, @var{extensions} is a list of strings; for each
directory in @var{path}, we search for @var{filename}
concatenated with each @var{extension}.
@end deffn

@defvar %load-path
Return the list of directories which should be searched for Scheme
modules and libraries.
@end defvar


@c Local Variables:
@c TeX-master: "guile.texi"
@c End: