Remove page breaks except before new chapters and indices
[bpt/guile.git] / doc / ref / api-options.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
6
7 @node Options and Config
8 @section Configuration, Features and Runtime Options
9
10 Why is my Guile different from your Guile? There are three kinds of
11 possible variation:
12
13 @itemize @bullet
14 @item
15 build differences --- different versions of the Guile source code,
16 installation directories, configuration flags that control pieces of
17 functionality being included or left out, etc.
18
19 @item
20 differences in dynamically loaded code --- behaviour and features
21 provided by modules that can be dynamically loaded into a running Guile
22
23 @item
24 different runtime options --- some of the options that are provided for
25 controlling Guile's behaviour may be set differently.
26 @end itemize
27
28 Guile provides ``introspective'' variables and procedures to query all
29 of these possible variations at runtime. For runtime options, it also
30 provides procedures to change the settings of options and to obtain
31 documentation on what the options mean.
32
33 @menu
34 * Build Config:: Build and installation configuration.
35 * Feature Tracking:: Available features in the Guile process.
36 * Runtime Options:: Controlling Guile's runtime behaviour.
37 @end menu
38
39
40 @node Build Config
41 @subsection Configuration, Build and Installation
42
43 The following procedures and variables provide information about how
44 Guile was configured, built and installed on your system.
45
46 @deffn {Scheme Procedure} version
47 @deffnx {Scheme Procedure} effective-version
48 @deffnx {Scheme Procedure} major-version
49 @deffnx {Scheme Procedure} minor-version
50 @deffnx {Scheme Procedure} micro-version
51 @deffnx {C Function} scm_version ()
52 @deffnx {C Function} scm_effective_version ()
53 @deffnx {C Function} scm_major_version ()
54 @deffnx {C Function} scm_minor_version ()
55 @deffnx {C Function} scm_micro_version ()
56 Return a string describing Guile's full version number, effective
57 version number, major, minor or micro version number, respectively.
58 The @code{effective-version} function returns the version name that
59 should remain unchanged during a stable series. Currently that means
60 that it omits the micro version. The effective version should be used
61 for items like the versioned share directory name
62 i.e. @file{/usr/share/guile/1.6/}
63
64 @lisp
65 (version) @result{} "1.6.0"
66 (effective-version) @result{} "1.6"
67 (major-version) @result{} "1"
68 (minor-version) @result{} "6"
69 (micro-version) @result{} "0"
70 @end lisp
71 @end deffn
72
73 @deffn {Scheme Procedure} %package-data-dir
74 @deffnx {C Function} scm_sys_package_data_dir ()
75 Return the name of the directory under which Guile Scheme files in
76 general are stored. On Unix-like systems, this is usually
77 @file{/usr/local/share/guile} or @file{/usr/share/guile}.
78 @end deffn
79
80 @deffn {Scheme Procedure} %library-dir
81 @deffnx {C Function} scm_sys_library_dir ()
82 Return the name of the directory where the Guile Scheme files that
83 belong to the core Guile installation (as opposed to files from a 3rd
84 party package) are installed. On Unix-like systems this is usually
85 @file{/usr/local/share/guile/<GUILE_EFFECTIVE_VERSION>} or
86 @file{/usr/share/guile/<GUILE_EFFECTIVE_VERSION>};
87
88 @noindent for example @file{/usr/local/share/guile/1.6}.
89 @end deffn
90
91 @deffn {Scheme Procedure} %site-dir
92 @deffnx {C Function} scm_sys_site_dir ()
93 Return the name of the directory where Guile Scheme files specific to
94 your site should be installed. On Unix-like systems, this is usually
95 @file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}.
96 @end deffn
97
98 @cindex GUILE_LOAD_PATH
99 @defvar %load-path
100 List of directories which should be searched for Scheme modules and
101 libraries. @code{%load-path} is initialized when Guile starts up to
102 @code{(list (%site-dir) (%library-dir) (%package-data-dir))},
103 prepended with the contents of the GUILE_LOAD_PATH environment variable,
104 if it is set.
105 @end defvar
106
107 @deffn {Scheme Procedure} parse-path path [tail]
108 @deffnx {C Function} scm_parse_path (path, tail)
109 Parse @var{path}, which is expected to be a colon-separated
110 string, into a list and return the resulting list with
111 @var{tail} appended. If @var{path} is @code{#f}, @var{tail}
112 is returned.
113 @end deffn
114
115 @deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
116 @deffnx {C Function} scm_search_path (path, filename, rest)
117 Search @var{path} for a directory containing a file named
118 @var{filename}. The file must be readable, and not a directory.
119 If we find one, return its full filename; otherwise, return
120 @code{#f}. If @var{filename} is absolute, return it unchanged.
121 If given, @var{extensions} is a list of strings; for each
122 directory in @var{path}, we search for @var{filename}
123 concatenated with each @var{extension}. If @var{require-exts?}
124 is true, require that the returned file name have one of the
125 given extensions; if @var{require-exts?} is not given, it
126 defaults to @code{#f}.
127
128 For compatibility with Guile 1.8 and earlier, the C function takes only
129 three arguments
130 @end deffn
131
132 @defvar %guile-build-info
133 Alist of information collected during the building of a particular
134 Guile. Entries can be grouped into one of several categories:
135 directories, env vars, and versioning info.
136
137 Briefly, here are the keys in @code{%guile-build-info}, by group:
138
139 @cindex @code{srcdir}
140 @cindex @code{top_srcdir}
141 @cindex @code{prefix}
142 @cindex @code{exec_prefix}
143 @cindex @code{bindir}
144 @cindex @code{sbindir}
145 @cindex @code{libexecdir}
146 @cindex @code{datadir}
147 @cindex @code{sysconfdir}
148 @cindex @code{sharedstatedir}
149 @cindex @code{localstatedir}
150 @cindex @code{libdir}
151 @cindex @code{infodir}
152 @cindex @code{mandir}
153 @cindex @code{includedir}
154 @cindex @code{pkgdatadir}
155 @cindex @code{pkglibdir}
156 @cindex @code{pkgincludedir}
157 @table @asis
158 @item directories
159 srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
160 datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
161 mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
162 @cindex @code{LIBS}
163 @item env vars
164 LIBS
165 @cindex @code{guileversion}
166 @cindex @code{libguileinterface}
167 @cindex @code{buildstamp}
168 @item versioning info
169 guileversion, libguileinterface, buildstamp
170 @end table
171
172 Values are all strings. The value for @code{LIBS} is typically found
173 also as a part of "guile-config link" output. The value for
174 @code{guileversion} has form X.Y.Z, and should be the same as returned
175 by @code{(version)}. The value for @code{libguileinterface} is
176 libtool compatible and has form CURRENT:REVISION:AGE
177 (@pxref{Versioning,, Library interface versions, libtool, GNU
178 Libtool}). The value for @code{buildstamp} is the output of the
179 date(1) command.
180
181 In the source, @code{%guile-build-info} is initialized from
182 libguile/libpath.h, which is completely generated, so deleting this file
183 before a build guarantees up-to-date values for that build.
184 @end defvar
185
186 @cindex GNU triplet
187 @cindex canonical host type
188
189 @defvar %host-type
190 The canonical host type (GNU triplet) of the host Guile was configured
191 for, e.g., @code{"x86_64-unknown-linux-gnu"} (@pxref{Canonicalizing,,,
192 autoconf, The GNU Autoconf Manual}).
193 @end defvar
194
195 @node Feature Tracking
196 @subsection Feature Tracking
197
198 Guile has a Scheme level variable @code{*features*} that keeps track to
199 some extent of the features that are available in a running Guile.
200 @code{*features*} is a list of symbols, for example @code{threads}, each
201 of which describes a feature of the running Guile process.
202
203 @defvar *features*
204 A list of symbols describing available features of the Guile process.
205 @end defvar
206
207 You shouldn't modify the @code{*features*} variable directly using
208 @code{set!}. Instead, see the procedures that are provided for this
209 purpose in the following subsection.
210
211 @menu
212 * Feature Manipulation:: Checking for and advertising features.
213 * Common Feature Symbols:: Commonly available features.
214 @end menu
215
216
217 @node Feature Manipulation
218 @subsubsection Feature Manipulation
219
220 To check whether a particular feature is available, use the
221 @code{provided?} procedure:
222
223 @deffn {Scheme Procedure} provided? feature
224 @deffnx {Deprecated Scheme Procedure} feature? feature
225 Return @code{#t} if the specified @var{feature} is available, otherwise
226 @code{#f}.
227 @end deffn
228
229 To advertise a feature from your own Scheme code, you can use the
230 @code{provide} procedure:
231
232 @deffn {Scheme Procedure} provide feature
233 Add @var{feature} to the list of available features in this Guile
234 process.
235 @end deffn
236
237 For C code, the equivalent function takes its feature name as a
238 @code{char *} argument for convenience:
239
240 @deftypefn {C Function} void scm_add_feature (const char *str)
241 Add a symbol with name @var{str} to the list of available features in
242 this Guile process.
243 @end deftypefn
244
245
246 @node Common Feature Symbols
247 @subsubsection Common Feature Symbols
248
249 In general, a particular feature may be available for one of two
250 reasons. Either because the Guile library was configured and compiled
251 with that feature enabled --- i.e. the feature is built into the library
252 on your system. Or because some C or Scheme code that was dynamically
253 loaded by Guile has added that feature to the list.
254
255 In the first category, here are the features that the current version of
256 Guile may define (depending on how it is built), and what they mean.
257
258 @table @code
259 @item array
260 Indicates support for arrays (@pxref{Arrays}).
261
262 @item array-for-each
263 Indicates availability of @code{array-for-each} and other array mapping
264 procedures (@pxref{Arrays}).
265
266 @item char-ready?
267 Indicates that the @code{char-ready?} function is available
268 (@pxref{Reading}).
269
270 @item complex
271 Indicates support for complex numbers.
272
273 @item current-time
274 Indicates availability of time-related functions: @code{times},
275 @code{get-internal-run-time} and so on (@pxref{Time}).
276
277 @item debug-extensions
278 Indicates that the debugging evaluator is available, together with the
279 options for controlling it.
280
281 @item delay
282 Indicates support for promises (@pxref{Delayed Evaluation}).
283
284 @item EIDs
285 Indicates that the @code{geteuid} and @code{getegid} really return
286 effective user and group IDs (@pxref{Processes}).
287
288 @item inexact
289 Indicates support for inexact numbers.
290
291 @item i/o-extensions
292 Indicates availability of the following extended I/O procedures:
293 @code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
294 @code{fileno}, @code{isatty?}, @code{fdopen},
295 @code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
296 File Descriptors}).
297
298 @item net-db
299 Indicates availability of network database functions:
300 @code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
301 @code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
302 @code{scm_setserv}, and their `byXXX' variants (@pxref{Network
303 Databases}).
304
305 @item posix
306 Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
307 @code{kill}, @code{execl} and so on (@pxref{POSIX}).
308
309 @item random
310 Indicates availability of random number generation functions:
311 @code{random}, @code{copy-random-state}, @code{random-uniform} and so on
312 (@pxref{Random}).
313
314 @item reckless
315 Indicates that Guile was built with important checks omitted --- you
316 should never see this!
317
318 @item regex
319 Indicates support for POSIX regular expressions using
320 @code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
321 Functions}).
322
323 @item socket
324 Indicates availability of socket-related functions: @code{socket},
325 @code{bind}, @code{connect} and so on (@pxref{Network Sockets and
326 Communication}).
327
328 @item sort
329 Indicates availability of sorting and merging functions
330 (@pxref{Sorting}).
331
332 @item system
333 Indicates that the @code{system} function is available
334 (@pxref{Processes}).
335
336 @item threads
337 Indicates support for multithreading (@pxref{Threads}).
338
339 @item values
340 Indicates support for multiple return values using @code{values} and
341 @code{call-with-values} (@pxref{Multiple Values}).
342 @end table
343
344 Available features in the second category depend, by definition, on what
345 additional code your Guile process has loaded in. The following table
346 lists features that you might encounter for this reason.
347
348 @table @code
349 @item defmacro
350 Indicates that the @code{defmacro} macro is available (@pxref{Macros}).
351
352 @item describe
353 Indicates that the @code{(oop goops describe)} module has been loaded,
354 which provides a procedure for describing the contents of GOOPS
355 instances.
356
357 @item readline
358 Indicates that Guile has loaded in Readline support, for command line
359 editing (@pxref{Readline Support}).
360
361 @item record
362 Indicates support for record definition using @code{make-record-type}
363 and friends (@pxref{Records}).
364 @end table
365
366 Although these tables may seem exhaustive, it is probably unwise in
367 practice to rely on them, as the correspondences between feature symbols
368 and available procedures/behaviour are not strictly defined. If you are
369 writing code that needs to check for the existence of some procedure, it
370 is probably safer to do so directly using the @code{defined?} procedure
371 than to test for the corresponding feature using @code{provided?}.
372
373
374 @node Runtime Options
375 @subsection Runtime Options
376
377 Guile's runtime behaviour can be modified by setting options. For
378 example, is the language that Guile accepts case sensitive, or should
379 the debugger automatically show a backtrace on error?
380
381 Guile has two levels of interface for managing options: a low-level
382 control interface, and a user-level interface which allows the enabling
383 or disabling of options.
384
385 Moreover, the options are classified in groups according to whether they
386 configure @emph{reading}, @emph{printing}, @emph{debugging} or
387 @emph{evaluating}.
388
389 @menu
390 * Low level options interfaces::
391 * User level options interfaces::
392 * Reader options::
393 * Printing options::
394 * Debugger options::
395 * Evaluator options::
396 * Evaluator trap options::
397 * Examples of option use::
398 @end menu
399
400
401 @node Low level options interfaces
402 @subsubsection Low Level Options Interfaces
403
404 @deffn {Scheme Procedure} read-options-interface [setting]
405 @deffnx {Scheme Procedure} eval-options-interface [setting]
406 @deffnx {Scheme Procedure} print-options-interface [setting]
407 @deffnx {Scheme Procedure} debug-options-interface [setting]
408 @deffnx {Scheme Procedure} evaluator-traps-interface [setting]
409 @deffnx {C Function} scm_read_options (setting)
410 @deffnx {C Function} scm_eval_options_interface (setting)
411 @deffnx {C Function} scm_print_options (setting)
412 @deffnx {C Function} scm_debug_options (setting)
413 @deffnx {C Function} scm_evaluator_traps (setting)
414 If one of these procedures is called with no arguments (or with
415 @code{setting == SCM_UNDEFINED} in C code), it returns a list describing
416 the current setting of the read, eval, print, debug or evaluator traps
417 options respectively. The setting of a boolean option is indicated
418 simply by the presence or absence of the option symbol in the list. The
419 setting of a non-boolean option is indicated by the presence of the
420 option symbol immediately followed by the option's current value.
421
422 If called with a list argument, these procedures interpret the list as
423 an option setting and modify the relevant options accordingly. [FIXME
424 --- this glosses over a lot of details!]
425
426 If called with any other argument, such as @code{'help}, these
427 procedures return a list of entries like @code{(@var{OPTION-SYMBOL}
428 @var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the
429 default value and documentation for each option symbol in the relevant
430 set of options.
431 @end deffn
432
433
434 @node User level options interfaces
435 @subsubsection User Level Options Interfaces
436
437 @c @deftp {Data type} scm_option
438 @c @code{scm_option} is used to represent run time options. It can be a
439 @c @emph{boolean} type, in which case the option will be set by the strings
440 @c @code{"yes"} and @code{"no"}. It can be a
441 @c @end deftp
442
443 @c NJFIXME
444 @deffn {Scheme Procedure} <group>-options [arg]
445 @deffnx {Scheme Procedure} read-options [arg]
446 @deffnx {Scheme Procedure} print-options [arg]
447 @deffnx {Scheme Procedure} debug-options [arg]
448 @deffnx {Scheme Procedure} traps [arg]
449 These functions list the options in their group. The optional argument
450 @var{arg} is a symbol which modifies the form in which the options are
451 presented.
452
453 With no arguments, @code{<group>-options} returns the values of the
454 options in that particular group. If @var{arg} is @code{'help}, a
455 description of each option is given. If @var{arg} is @code{'full},
456 programmers' options are also shown.
457
458 @var{arg} can also be a list representing the state of all options. In
459 this case, the list contains single symbols (for enabled boolean
460 options) and symbols followed by values.
461 @end deffn
462 [FIXME: I don't think 'full is ever any different from 'help. What's
463 up?]
464
465 @c NJFIXME
466 @deffn {Scheme Procedure} <group>-enable option-symbol
467 @deffnx {Scheme Procedure} read-enable option-symbol
468 @deffnx {Scheme Procedure} print-enable option-symbol
469 @deffnx {Scheme Procedure} debug-enable option-symbol
470 @deffnx {Scheme Procedure} trap-enable option-symbol
471 These functions set the specified @var{option-symbol} in their options
472 group. They only work if the option is boolean, and throw an error
473 otherwise.
474 @end deffn
475
476 @c NJFIXME
477 @deffn {Scheme Procedure} <group>-disable option-symbol
478 @deffnx {Scheme Procedure} read-disable option-symbol
479 @deffnx {Scheme Procedure} print-disable option-symbol
480 @deffnx {Scheme Procedure} debug-disable option-symbol
481 @deffnx {Scheme Procedure} trap-disable option-symbol
482 These functions turn off the specified @var{option-symbol} in their
483 options group. They only work if the option is boolean, and throw an
484 error otherwise.
485 @end deffn
486
487 @c NJFIXME
488 @deffn syntax <group>-set! option-symbol value
489 @deffnx syntax read-set! option-symbol value
490 @deffnx syntax print-set! option-symbol value
491 @deffnx syntax debug-set! option-symbol value
492 @deffnx syntax trap-set! option-symbol value
493 These functions set a non-boolean @var{option-symbol} to the specified
494 @var{value}.
495 @end deffn
496
497
498 @node Reader options
499 @subsubsection Reader options
500 @cindex options - read
501 @cindex read options
502
503 Here is the list of reader options generated by typing
504 @code{(read-options 'full)} in Guile. You can also see the default
505 values.
506
507 @smalllisp
508 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
509 case-insensitive no Convert symbols to lower case.
510 positions yes Record positions of source code expressions.
511 copy no Copy source code expressions.
512 @end smalllisp
513
514 Notice that while Standard Scheme is case insensitive, to ease
515 translation of other Lisp dialects, notably Emacs Lisp, into Guile,
516 Guile is case-sensitive by default.
517
518 To make Guile case insensitive, you can type
519
520 @lisp
521 (read-enable 'case-insensitive)
522 @end lisp
523
524 @node Printing options
525 @subsubsection Printing options
526
527 Here is the list of print options generated by typing
528 @code{(print-options 'full)} in Guile. You can also see the default
529 values.
530
531 @smallexample
532 quote-keywordish-symbols reader How to print symbols that have a colon
533 as their first or last character. The
534 value '#f' does not quote the colons;
535 '#t' quotes them; 'reader' quotes
536 them when the reader option
537 'keywords' is not '#f'.
538
539 highlight-prefix @{ The string to print before highlighted values.
540 highlight-suffix @} The string to print after highlighted values.
541
542 source no Print closures with source.
543 closure-hook #f Hook for printing closures.
544 @end smallexample
545
546
547 @node Evaluator options
548 @subsubsection Evaluator options
549
550 These are the evaluator options with their default values, as they are
551 printed by typing @code{(eval-options 'full)} in Guile.
552
553 @smallexample
554 stack 22000 Size of thread stacks (in machine words).
555 @end smallexample
556
557
558 @node Evaluator trap options
559 @subsubsection Evaluator trap options
560 [FIXME: These flags, together with their corresponding handlers, are not
561 user level options. Probably this entire section should be moved to the
562 documentation about the low-level programmer debugging interface.]
563
564 Here is the list of evaluator trap options generated by typing
565 @code{(traps 'full)} in Guile. You can also see the default values.
566
567 @smallexample
568 exit-frame no Trap when exiting eval or apply.
569 apply-frame no Trap when entering apply.
570 enter-frame no Trap when eval enters new frame.
571 memoize-symbol no Trap when eval memoizes a symbol's value
572 traps yes Enable evaluator traps.
573 @end smallexample
574
575 @deffn apply-frame-handler key cont tailp
576 Called when a procedure is being applied.
577
578 Called if:
579
580 @itemize @bullet
581 @item
582 evaluator traps are enabled [traps interface], and
583 @item
584 either
585 @itemize @minus
586 @item
587 @code{apply-frame} is enabled [traps interface], or
588 @item
589 trace mode is on [debug-options interface], and the procedure being
590 called has the trace property enabled.
591 @end itemize
592 @end itemize
593
594 @var{cont} is a ``debug object'', which means that it can be passed to
595 @code{make-stack} to discover the stack at the point of the trap. The
596 apply frame handler's code can capture a restartable continuation if it
597 wants to by using @code{call-with-current-continuation} in the usual way.
598
599 @var{tailp} is true if this is a tail call
600 @end deffn
601
602 @deffn exit-frame-handler key cont retval
603 Called when a value is returned from a procedure.
604
605 Called if:
606
607 @itemize @bullet
608 @item
609 evaluator traps are enabled [traps interface], and
610 @item
611 either
612 @itemize @minus
613 @item
614 @code{exit-frame} is enabled [traps interface], or
615 @item
616 trace mode is on [debug-options interface], and the procedure being
617 called has the trace property enabled.
618 @end itemize
619 @end itemize
620
621 @var{cont} is a ``debug object'', which means that it can be passed to
622 @code{make-stack} to discover the stack at the point of the trap. The
623 exit frame handler's code can capture a restartable continuation if it
624 wants to by using @code{call-with-current-continuation} in the usual
625 way.
626
627 @var{retval} is the return value.
628 @end deffn
629
630 @deffn memoize-symbol-handler key cont expression env
631 Called when the evaluator memoizes the value of a procedure symbol
632
633 @var{cont} is a ``debug object'', which means that it can be passed to
634 @code{make-stack} to discover the stack at the point of the trap. The
635 exit frame handler's code can capture a restartable continuation if it
636 wants to by using @code{call-with-current-continuation} in the usual
637 way.
638
639 @var{retval} is the return value.
640 @end deffn
641
642 @deffn {Scheme Procedure} with-traps thunk
643 @deffnx {C Function} scm_with_traps (thunk)
644 Call @var{thunk} with traps enabled.
645 @end deffn
646
647 @deffn {Scheme Procedure} debug-object? obj
648 @deffnx {C Function} scm_debug_object_p (obj)
649 Return @code{#t} if @var{obj} is a debug object.
650 @end deffn
651
652
653 @node Debugger options
654 @subsubsection Debugger options
655
656 Here is the list of print options generated by typing
657 @code{(debug-options 'full)} in Guile. You can also see the default
658 values.
659
660 @smallexample
661 stack 20000 Stack size limit (0 = no check).
662 debug yes Use the debugging evaluator.
663 backtrace no Show backtrace on error.
664 depth 20 Maximal length of printed backtrace.
665 maxdepth 1000 Maximal number of stored backtrace frames.
666 frames 3 Maximum number of tail-recursive frames in backtrace.
667 indent 10 Maximal indentation in backtrace.
668 backwards no Display backtrace in anti-chronological order.
669 procnames yes Record procedure names at definition.
670 trace no *Trace mode.
671 breakpoints no *Check for breakpoints.
672 cheap yes *This option is now obsolete. Setting it has no effect.
673 @end smallexample
674
675 @subsubheading Stack overflow
676
677 @cindex overflow, stack
678 @cindex stack overflow
679 Stack overflow errors are caused by a computation trying to use more
680 stack space than has been enabled by the @code{stack} option. They are
681 reported like this:
682
683 @lisp
684 (non-tail-recursive-factorial 500)
685 @print{}
686 ERROR: Stack overflow
687 ABORT: (stack-overflow)
688 @end lisp
689
690 If you get an error like this, you can either try rewriting your code to
691 use less stack space, or increase the maximum stack size. To increase
692 the maximum stack size, use @code{debug-set!}, for example:
693
694 @lisp
695 (debug-set! stack 200000)
696 @result{}
697 (show-file-name #t stack 200000 debug backtrace depth 20
698 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)
699
700 (non-tail-recursive-factorial 500)
701 @result{}
702 122013682599111006870123878542304692625357434@dots{}
703 @end lisp
704
705 If you prefer to try rewriting your code, you may be able to save stack
706 space by making some of your procedures @dfn{tail recursive}
707 (@pxref{Tail Calls}).
708
709
710 @node Examples of option use
711 @subsubsection Examples of option use
712
713 Here is an example of a session in which some read and debug option
714 handling procedures are used. In this example, the user
715
716 @enumerate
717 @item
718 Notices that the symbols @code{abc} and @code{aBc} are not the same
719 @item
720 Examines the @code{read-options}, and sees that @code{case-insensitive}
721 is set to ``no''.
722 @item
723 Enables @code{case-insensitive}
724 @item
725 Verifies that now @code{aBc} and @code{abc} are the same
726 @item
727 Disables @code{case-insensitive} and enables debugging @code{backtrace}
728 @item
729 Reproduces the error of displaying @code{aBc} with backtracing enabled
730 [FIXME: this last example is lame because there is no depth in the
731 backtrace. Need to give a better example, possibly putting debugging
732 option examples in a separate session.]
733 @end enumerate
734
735 @smalllisp
736 guile> (define abc "hello")
737 guile> abc
738 "hello"
739 guile> aBc
740 ERROR: In expression aBc:
741 ERROR: Unbound variable: aBc
742 ABORT: (misc-error)
743
744 Type "(backtrace)" to get more information.
745 guile> (read-options 'help)
746 keywords #f Style of keyword recognition: #f, 'prefix or 'postfix
747 case-insensitive no Convert symbols to lower case.
748 positions yes Record positions of source code expressions.
749 copy no Copy source code expressions.
750 guile> (debug-options 'help)
751 stack 20000 Stack size limit (0 = no check).
752 debug yes Use the debugging evaluator.
753 backtrace no Show backtrace on error.
754 depth 20 Maximal length of printed backtrace.
755 maxdepth 1000 Maximal number of stored backtrace frames.
756 frames 3 Maximum number of tail-recursive frames in backtrace.
757 indent 10 Maximal indentation in backtrace.
758 backwards no Display backtrace in anti-chronological order.
759 procnames yes Record procedure names at definition.
760 trace no *Trace mode.
761 breakpoints no *Check for breakpoints.
762 cheap yes *This option is now obsolete. Setting it has no effect.
763 guile> (read-enable 'case-insensitive)
764 (keywords #f case-insensitive positions)
765 guile> aBc
766 "hello"
767 guile> (read-disable 'case-insensitive)
768 (keywords #f positions)
769 guile> (debug-enable 'backtrace)
770 (stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
771 guile> aBc
772
773 Backtrace:
774 0* aBc
775
776 ERROR: In expression aBc:
777 ERROR: Unbound variable: aBc
778 ABORT: (misc-error)
779 guile>
780 @end smalllisp
781
782
783 @c Local Variables:
784 @c TeX-master: "guile.texi"
785 @c End: