Commit | Line | Data |
---|---|---|
2da09c3f MV |
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 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
a0e07ba4 NJ |
7 | @page |
8 | @node Debugging | |
f2ba76ae | 9 | @chapter Debugging Infrastructure |
a0e07ba4 | 10 | |
c936bede NJ |
11 | @menu |
12 | * Source Properties:: Remembering the source of an expression. | |
13 | * Using Traps:: | |
14 | * Capturing the Stack or Innermost Stack Frame:: | |
15 | * Examining the Stack:: | |
16 | * Examining Stack Frames:: | |
17 | * Decoding Memoized Source Expressions:: | |
18 | * Starting a New Stack:: | |
19 | @end menu | |
20 | ||
21 | ||
22 | @node Source Properties | |
23 | @section Source Properties | |
24 | ||
25 | @cindex source properties | |
26 | As Guile reads in Scheme code from file or from standard input, it | |
27 | remembers the file name, line number and column number where each | |
28 | expression begins. These pieces of information are known as the | |
29 | @dfn{source properties} of the expression. If an expression undergoes | |
30 | transformation --- for example, if there is a syntax transformer in | |
31 | effect, or the expression is a macro call --- the source properties are | |
32 | copied from the untransformed to the transformed expression so that, if | |
33 | an error occurs when evaluating the transformed expression, Guile's | |
34 | debugger can point back to the file and location where the expression | |
35 | originated. | |
36 | ||
37 | The way that source properties are stored means that Guile can only | |
38 | associate source properties with parenthesized expressions, and not, for | |
39 | example, with individual symbols, numbers or strings. The difference | |
40 | can be seen by typing @code{(xxx)} and @code{xxx} at the Guile prompt | |
41 | (where the variable @code{xxx} has not been defined): | |
42 | ||
43 | @example | |
44 | guile> (xxx) | |
45 | standard input:2:1: In expression (xxx): | |
46 | standard input:2:1: Unbound variable: xxx | |
47 | ABORT: (unbound-variable) | |
48 | guile> xxx | |
49 | <unnamed port>: In expression xxx: | |
50 | <unnamed port>: Unbound variable: xxx | |
51 | ABORT: (unbound-variable) | |
52 | @end example | |
53 | ||
54 | @noindent | |
55 | In the latter case, no source properties were stored, so the best that | |
56 | Guile could say regarding the location of the problem was ``<unnamed | |
57 | port>''. | |
58 | ||
59 | The recording of source properties is controlled by the read option | |
60 | named ``positions'' (@pxref{Reader options}). This option is switched | |
61 | @emph{on} by default, together with the debug options ``debug'' and | |
62 | ``backtrace'' (@pxref{Debugger options}), when Guile is run | |
63 | interactively; all these options are @emph{off} by default when Guile | |
64 | runs a script non-interactively. | |
65 | ||
66 | ||
67 | @node Using Traps | |
f2ba76ae NJ |
68 | @section Using Traps |
69 | ||
8f85c0c6 NJ |
70 | @deffn {Scheme Procedure} with-traps thunk |
71 | @deffnx {C Function} scm_with_traps (thunk) | |
a0e07ba4 NJ |
72 | Call @var{thunk} with traps enabled. |
73 | @end deffn | |
74 | ||
8f85c0c6 NJ |
75 | @deffn {Scheme Procedure} debug-object? obj |
76 | @deffnx {C Function} scm_debug_object_p (obj) | |
a0e07ba4 NJ |
77 | Return @code{#t} if @var{obj} is a debug object. |
78 | @end deffn | |
79 | ||
a0e07ba4 | 80 | |
c936bede | 81 | @node Capturing the Stack or Innermost Stack Frame |
f2ba76ae | 82 | @section Capturing the Stack or Innermost Stack Frame |
a0e07ba4 | 83 | |
ce9d0562 NJ |
84 | When an error occurs in a running program, or the program hits a |
85 | breakpoint, its state at that point can be represented by a @dfn{stack} | |
86 | of all the evaluations and procedure applications that are logically in | |
87 | progress at that time, each of which is known as a @dfn{frame}. The | |
88 | programmer can learn more about the program's state at the point of | |
89 | interruption or error by inspecting the stack and its frames. | |
90 | ||
8f85c0c6 NJ |
91 | @deffn {Scheme Procedure} make-stack obj . args |
92 | @deffnx {C Function} scm_make_stack (obj, args) | |
a0e07ba4 NJ |
93 | Create a new stack. If @var{obj} is @code{#t}, the current |
94 | evaluation stack is used for creating the stack frames, | |
95 | otherwise the frames are taken from @var{obj} (which must be | |
96 | either a debug object or a continuation). | |
97 | ||
98 | @var{args} should be a list containing any combination of | |
99 | integer, procedure and @code{#t} values. | |
100 | ||
101 | These values specify various ways of cutting away uninteresting | |
102 | stack frames from the top and bottom of the stack that | |
103 | @code{make-stack} returns. They come in pairs like this: | |
104 | @code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2} | |
105 | @var{outer_cut_2} @dots{})}. | |
106 | ||
107 | Each @var{inner_cut_N} can be @code{#t}, an integer, or a | |
108 | procedure. @code{#t} means to cut away all frames up to but | |
109 | excluding the first user module frame. An integer means to cut | |
110 | away exactly that number of frames. A procedure means to cut | |
111 | away all frames up to but excluding the application frame whose | |
112 | procedure matches the specified one. | |
113 | ||
114 | Each @var{outer_cut_N} can be an integer or a procedure. An | |
115 | integer means to cut away that number of frames. A procedure | |
116 | means to cut away frames down to but excluding the application | |
117 | frame whose procedure matches the specified one. | |
118 | ||
119 | If the @var{outer_cut_N} of the last pair is missing, it is | |
120 | taken as 0. | |
121 | @end deffn | |
122 | ||
f2ba76ae NJ |
123 | @deffn {Scheme Procedure} last-stack-frame obj |
124 | @deffnx {C Function} scm_last_stack_frame (obj) | |
125 | Return a stack which consists of a single frame, which is the | |
126 | last stack frame for @var{obj}. @var{obj} must be either a | |
127 | debug object or a continuation. | |
128 | @end deffn | |
129 | ||
130 | ||
c936bede | 131 | @node Examining the Stack |
f2ba76ae NJ |
132 | @section Examining the Stack |
133 | ||
134 | @deffn {Scheme Procedure} stack? obj | |
135 | @deffnx {C Function} scm_stack_p (obj) | |
136 | Return @code{#t} if @var{obj} is a calling stack. | |
137 | @end deffn | |
138 | ||
8f85c0c6 NJ |
139 | @deffn {Scheme Procedure} stack-id stack |
140 | @deffnx {C Function} scm_stack_id (stack) | |
a0e07ba4 NJ |
141 | Return the identifier given to @var{stack} by @code{start-stack}. |
142 | @end deffn | |
143 | ||
8f85c0c6 NJ |
144 | @deffn {Scheme Procedure} stack-length stack |
145 | @deffnx {C Function} scm_stack_length (stack) | |
a0e07ba4 NJ |
146 | Return the length of @var{stack}. |
147 | @end deffn | |
148 | ||
8f85c0c6 NJ |
149 | @deffn {Scheme Procedure} stack-ref stack index |
150 | @deffnx {C Function} scm_stack_ref (stack, index) | |
9401323e | 151 | Return the @var{index}'th frame from @var{stack}. |
a0e07ba4 NJ |
152 | @end deffn |
153 | ||
f2ba76ae NJ |
154 | @deffn {Scheme Procedure} display-backtrace stack port [first [depth]] |
155 | @deffnx {C Function} scm_display_backtrace (stack, port, first, depth) | |
156 | Display a backtrace to the output port @var{port}. @var{stack} | |
157 | is the stack to take the backtrace from, @var{first} specifies | |
158 | where in the stack to start and @var{depth} how much frames | |
159 | to display. Both @var{first} and @var{depth} can be @code{#f}, | |
160 | which means that default values will be used. | |
161 | @end deffn | |
162 | ||
163 | ||
c936bede | 164 | @node Examining Stack Frames |
f2ba76ae NJ |
165 | @section Examining Stack Frames |
166 | ||
167 | @deffn {Scheme Procedure} frame? obj | |
168 | @deffnx {C Function} scm_frame_p (obj) | |
169 | Return @code{#t} if @var{obj} is a stack frame. | |
170 | @end deffn | |
171 | ||
172 | @deffn {Scheme Procedure} frame-number frame | |
173 | @deffnx {C Function} scm_frame_number (frame) | |
174 | Return the frame number of @var{frame}. | |
175 | @end deffn | |
176 | ||
177 | @deffn {Scheme Procedure} frame-previous frame | |
178 | @deffnx {C Function} scm_frame_previous (frame) | |
179 | Return the previous frame of @var{frame}, or @code{#f} if | |
180 | @var{frame} is the first frame in its stack. | |
181 | @end deffn | |
182 | ||
183 | @deffn {Scheme Procedure} frame-next frame | |
184 | @deffnx {C Function} scm_frame_next (frame) | |
185 | Return the next frame of @var{frame}, or @code{#f} if | |
186 | @var{frame} is the last frame in its stack. | |
187 | @end deffn | |
188 | ||
189 | @deffn {Scheme Procedure} frame-source frame | |
190 | @deffnx {C Function} scm_frame_source (frame) | |
191 | Return the source of @var{frame}. | |
192 | @end deffn | |
193 | ||
194 | @deffn {Scheme Procedure} frame-procedure? frame | |
195 | @deffnx {C Function} scm_frame_procedure_p (frame) | |
196 | Return @code{#t} if a procedure is associated with @var{frame}. | |
197 | @end deffn | |
198 | ||
199 | @deffn {Scheme Procedure} frame-procedure frame | |
200 | @deffnx {C Function} scm_frame_procedure (frame) | |
201 | Return the procedure for @var{frame}, or @code{#f} if no | |
202 | procedure is associated with @var{frame}. | |
203 | @end deffn | |
204 | ||
205 | @deffn {Scheme Procedure} frame-arguments frame | |
206 | @deffnx {C Function} scm_frame_arguments (frame) | |
207 | Return the arguments of @var{frame}. | |
208 | @end deffn | |
209 | ||
210 | @deffn {Scheme Procedure} frame-evaluating-args? frame | |
211 | @deffnx {C Function} scm_frame_evaluating_args_p (frame) | |
212 | Return @code{#t} if @var{frame} contains evaluated arguments. | |
213 | @end deffn | |
214 | ||
215 | @deffn {Scheme Procedure} frame-overflow? frame | |
216 | @deffnx {C Function} scm_frame_overflow_p (frame) | |
217 | Return @code{#t} if @var{frame} is an overflow frame. | |
218 | @end deffn | |
219 | ||
220 | @deffn {Scheme Procedure} frame-real? frame | |
221 | @deffnx {C Function} scm_frame_real_p (frame) | |
222 | Return @code{#t} if @var{frame} is a real frame. | |
223 | @end deffn | |
224 | ||
225 | @deffn {Scheme Procedure} display-application frame [port [indent]] | |
226 | @deffnx {C Function} scm_display_application (frame, port, indent) | |
227 | Display a procedure application @var{frame} to the output port | |
228 | @var{port}. @var{indent} specifies the indentation of the | |
229 | output. | |
230 | @end deffn | |
231 | ||
232 | ||
c936bede | 233 | @node Decoding Memoized Source Expressions |
f2ba76ae NJ |
234 | @section Decoding Memoized Source Expressions |
235 | ||
236 | @deffn {Scheme Procedure} memoized? obj | |
237 | @deffnx {C Function} scm_memoized_p (obj) | |
238 | Return @code{#t} if @var{obj} is memoized. | |
239 | @end deffn | |
240 | ||
241 | @deffn {Scheme Procedure} unmemoize m | |
242 | @deffnx {C Function} scm_unmemoize (m) | |
243 | Unmemoize the memoized expression @var{m}, | |
244 | @end deffn | |
245 | ||
246 | @deffn {Scheme Procedure} memoized-environment m | |
247 | @deffnx {C Function} scm_memoized_environment (m) | |
248 | Return the environment of the memoized expression @var{m}. | |
a0e07ba4 NJ |
249 | @end deffn |
250 | ||
251 | ||
c936bede | 252 | @node Starting a New Stack |
ce9d0562 NJ |
253 | @section Starting a New Stack |
254 | ||
255 | @deffn {Scheme Syntax} start-stack id exp | |
256 | Evaluate @var{exp} on a new calling stack with identity @var{id}. If | |
257 | @var{exp} is interrupted during evaluation, backtraces will not display | |
258 | frames farther back than @var{exp}'s top-level form. This macro is a | |
259 | way of artificially limiting backtraces and stack procedures, largely as | |
260 | a convenience to the user. | |
261 | @end deffn | |
262 | ||
263 | ||
a0e07ba4 NJ |
264 | @c Local Variables: |
265 | @c TeX-master: "guile.texi" | |
266 | @c End: |