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