Commit | Line | Data |
---|---|---|
07d83abe 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 | ||
7 | @page | |
8 | @node Debugging | |
9 | @section Debugging Infrastructure | |
10 | ||
11 | @menu | |
12 | * Interactive Debugging:: Functions intended for interactive use. | |
13 | * Breakpoints:: | |
14 | * Source Properties:: Remembering the source of an expression. | |
15 | * Using Traps:: | |
16 | * Capturing the Stack or Innermost Stack Frame:: | |
17 | * Examining the Stack:: | |
18 | * Examining Stack Frames:: | |
19 | * Decoding Memoized Source Expressions:: | |
20 | * Starting a New Stack:: | |
21 | @end menu | |
22 | ||
23 | @node Interactive Debugging | |
24 | @subsection Interactive Debugging | |
25 | ||
7cd44c6d MV |
26 | @deffn {Scheme Procedure} backtrace [highlights] |
27 | @deffnx {C Function} scm_backtrace_with_highlights (highlights) | |
07d83abe MV |
28 | @deffnx {C Function} scm_backtrace () |
29 | Display a backtrace of the stack saved by the last error | |
7cd44c6d MV |
30 | to the current output port. When @var{highlights} is given, |
31 | it should be a list and all members of it are highligthed in | |
32 | the backtrace. | |
07d83abe MV |
33 | @end deffn |
34 | ||
35 | @deffn {Scheme Procedure} debug | |
36 | Invoke the Guile debugger to explore the context of the last error. | |
37 | @end deffn | |
38 | ||
39 | @node Breakpoints | |
40 | @subsection Breakpoints | |
41 | ||
42 | @deffn {Generic Function} set-breakpoint! behaviour . location-args | |
43 | Set a breakpoint with behaviour @var{behaviour} at the location | |
44 | specified by @var{location-args}. | |
45 | ||
46 | The form of the @var{location-args} depends upon what methods for | |
47 | @code{set-breakpoint!} have been provided by the implementations of | |
48 | subclasses of the @code{<breakpoint>} base class. | |
49 | @end deffn | |
50 | ||
51 | @deffn {Generic Function} get-breakpoint . location-args | |
52 | Find and return the breakpoint instance at the location specified by | |
53 | @var{location-args}. | |
54 | ||
55 | The form of the @var{location-args} depends upon what methods for | |
56 | @code{get-breakpoint} have been provided by the implementations of | |
57 | subclasses of the @code{<breakpoint>} base class. | |
58 | @end deffn | |
59 | ||
60 | @deffn {Method} set-breakpoint! behaviour (proc <procedure>) | |
61 | Set a breakpoint with behaviour @var{behaviour} before applications of | |
62 | the procedure @var{proc}. | |
63 | @end deffn | |
64 | ||
65 | @deffn {Method} set-breakpoint! behaviour x-as-read (x-pairified <pair>) | |
66 | Set a breakpoint with behaviour @var{behaviour} on the source expression | |
67 | @var{x-pairified}, storing @var{x-as-read} for use in messages | |
68 | describing the breakpoint. | |
69 | @end deffn | |
70 | ||
71 | @deffn {Method} set-breakpoint! behaviour (number <integer>) | |
72 | Change the behaviour of existing breakpoint number @var{number} to | |
73 | @var{behaviour}. | |
74 | @end deffn | |
75 | ||
76 | @deffn {Accessor} bp-behaviour breakpoint | |
77 | Get or set the behaviour of the breakpoint instance @var{breakpoint}. | |
78 | @end deffn | |
79 | ||
80 | @deffn {Accessor} bp-enabled? breakpoint | |
81 | Get or set the enabled state of the specified @var{breakpoint}. | |
82 | @end deffn | |
83 | ||
84 | @deffn {Procedure} enable-breakpoint! . location-args | |
85 | @deffnx {Procedure} disable-breakpoint! . location-args | |
86 | Enable or disable the breakpoint at the location specified by | |
87 | @var{location-args}. | |
88 | @end deffn | |
89 | ||
90 | @deffn {Generic Function} bp-delete! breakpoint | |
91 | Delete breakpoint @var{breakpoint}. This means (1) doing whatever is | |
92 | needed to prevent the breakpoint from triggering again, and (2) removing | |
93 | it from the global list of current breakpoints. | |
94 | @end deffn | |
95 | ||
96 | @deffn {Procedure} delete-breakpoint! . location-args | |
97 | Delete the breakpoint at the location specified by @var{location-args}. | |
98 | @end deffn | |
99 | ||
100 | @deffn {Generic Function} bp-describe breakpoint port | |
101 | Print a description of @var{breakpoint} to the specified @var{port}. | |
102 | @var{port} can be @code{#t} for standard output, or else any output | |
103 | port. | |
104 | @end deffn | |
105 | ||
106 | @deffn {Procedure} describe-breakpoint . location-args | |
107 | Print (to standard output) a description of the breakpoint at location | |
108 | specified by @var{location-args}. | |
109 | @end deffn | |
110 | ||
111 | @deffn {Procedure} all-breakpoints | |
112 | Return a list of all current breakpoints, ordered by breakpoint number. | |
113 | @end deffn | |
114 | ||
115 | @deffn {Procedure} describe-all-breakpoints | |
116 | Print a description of all current breakpoints to standard output. | |
117 | @end deffn | |
118 | ||
119 | ||
120 | @node Source Properties | |
121 | @subsection Source Properties | |
122 | ||
123 | @cindex source properties | |
124 | As Guile reads in Scheme code from file or from standard input, it | |
125 | remembers the file name, line number and column number where each | |
126 | expression begins. These pieces of information are known as the | |
127 | @dfn{source properties} of the expression. If an expression undergoes | |
128 | transformation --- for example, if there is a syntax transformer in | |
129 | effect, or the expression is a macro call --- the source properties are | |
130 | copied from the untransformed to the transformed expression so that, if | |
131 | an error occurs when evaluating the transformed expression, Guile's | |
132 | debugger can point back to the file and location where the expression | |
133 | originated. | |
134 | ||
135 | The way that source properties are stored means that Guile can only | |
136 | associate source properties with parenthesized expressions, and not, for | |
137 | example, with individual symbols, numbers or strings. The difference | |
138 | can be seen by typing @code{(xxx)} and @code{xxx} at the Guile prompt | |
139 | (where the variable @code{xxx} has not been defined): | |
140 | ||
141 | @example | |
142 | guile> (xxx) | |
143 | standard input:2:1: In expression (xxx): | |
144 | standard input:2:1: Unbound variable: xxx | |
145 | ABORT: (unbound-variable) | |
146 | guile> xxx | |
147 | <unnamed port>: In expression xxx: | |
148 | <unnamed port>: Unbound variable: xxx | |
149 | ABORT: (unbound-variable) | |
150 | @end example | |
151 | ||
152 | @noindent | |
153 | In the latter case, no source properties were stored, so the best that | |
154 | Guile could say regarding the location of the problem was ``<unnamed | |
155 | port>''. | |
156 | ||
157 | The recording of source properties is controlled by the read option | |
158 | named ``positions'' (@pxref{Reader options}). This option is switched | |
159 | @emph{on} by default, together with the debug options ``debug'' and | |
160 | ``backtrace'' (@pxref{Debugger options}), when Guile is run | |
161 | interactively; all these options are @emph{off} by default when Guile | |
162 | runs a script non-interactively. | |
163 | ||
164 | ||
165 | @node Using Traps | |
166 | @subsection Using Traps | |
167 | ||
168 | @deffn {Scheme Procedure} with-traps thunk | |
169 | @deffnx {C Function} scm_with_traps (thunk) | |
170 | Call @var{thunk} with traps enabled. | |
171 | @end deffn | |
172 | ||
173 | @deffn {Scheme Procedure} debug-object? obj | |
174 | @deffnx {C Function} scm_debug_object_p (obj) | |
175 | Return @code{#t} if @var{obj} is a debug object. | |
176 | @end deffn | |
177 | ||
178 | ||
179 | @node Capturing the Stack or Innermost Stack Frame | |
180 | @subsection Capturing the Stack or Innermost Stack Frame | |
181 | ||
182 | When an error occurs in a running program, or the program hits a | |
183 | breakpoint, its state at that point can be represented by a @dfn{stack} | |
184 | of all the evaluations and procedure applications that are logically in | |
185 | progress at that time, each of which is known as a @dfn{frame}. The | |
186 | programmer can learn more about the program's state at the point of | |
187 | interruption or error by inspecting the stack and its frames. | |
188 | ||
189 | @deffn {Scheme Procedure} make-stack obj . args | |
190 | @deffnx {C Function} scm_make_stack (obj, args) | |
191 | Create a new stack. If @var{obj} is @code{#t}, the current | |
192 | evaluation stack is used for creating the stack frames, | |
193 | otherwise the frames are taken from @var{obj} (which must be | |
194 | either a debug object or a continuation). | |
195 | ||
196 | @var{args} should be a list containing any combination of | |
197 | integer, procedure and @code{#t} values. | |
198 | ||
199 | These values specify various ways of cutting away uninteresting | |
200 | stack frames from the top and bottom of the stack that | |
201 | @code{make-stack} returns. They come in pairs like this: | |
202 | @code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2} | |
203 | @var{outer_cut_2} @dots{})}. | |
204 | ||
205 | Each @var{inner_cut_N} can be @code{#t}, an integer, or a | |
206 | procedure. @code{#t} means to cut away all frames up to but | |
207 | excluding the first user module frame. An integer means to cut | |
208 | away exactly that number of frames. A procedure means to cut | |
209 | away all frames up to but excluding the application frame whose | |
210 | procedure matches the specified one. | |
211 | ||
212 | Each @var{outer_cut_N} can be an integer or a procedure. An | |
213 | integer means to cut away that number of frames. A procedure | |
214 | means to cut away frames down to but excluding the application | |
215 | frame whose procedure matches the specified one. | |
216 | ||
217 | If the @var{outer_cut_N} of the last pair is missing, it is | |
218 | taken as 0. | |
219 | @end deffn | |
220 | ||
221 | @deffn {Scheme Procedure} last-stack-frame obj | |
222 | @deffnx {C Function} scm_last_stack_frame (obj) | |
223 | Return a stack which consists of a single frame, which is the | |
224 | last stack frame for @var{obj}. @var{obj} must be either a | |
225 | debug object or a continuation. | |
226 | @end deffn | |
227 | ||
228 | ||
229 | @node Examining the Stack | |
230 | @subsection Examining the Stack | |
231 | ||
232 | @deffn {Scheme Procedure} stack? obj | |
233 | @deffnx {C Function} scm_stack_p (obj) | |
234 | Return @code{#t} if @var{obj} is a calling stack. | |
235 | @end deffn | |
236 | ||
237 | @deffn {Scheme Procedure} stack-id stack | |
238 | @deffnx {C Function} scm_stack_id (stack) | |
239 | Return the identifier given to @var{stack} by @code{start-stack}. | |
240 | @end deffn | |
241 | ||
242 | @deffn {Scheme Procedure} stack-length stack | |
243 | @deffnx {C Function} scm_stack_length (stack) | |
244 | Return the length of @var{stack}. | |
245 | @end deffn | |
246 | ||
247 | @deffn {Scheme Procedure} stack-ref stack index | |
248 | @deffnx {C Function} scm_stack_ref (stack, index) | |
249 | Return the @var{index}'th frame from @var{stack}. | |
250 | @end deffn | |
251 | ||
7cd44c6d MV |
252 | @deffn {Scheme Procedure} display-backtrace stack port [first [depth [highlights]]] |
253 | @deffnx {C Function} scm_display_backtrace_with_highlights (stack, port, first, depth, highlights) | |
07d83abe MV |
254 | @deffnx {C Function} scm_display_backtrace (stack, port, first, depth) |
255 | Display a backtrace to the output port @var{port}. @var{stack} | |
256 | is the stack to take the backtrace from, @var{first} specifies | |
257 | where in the stack to start and @var{depth} how much frames | |
258 | to display. Both @var{first} and @var{depth} can be @code{#f}, | |
259 | which means that default values will be used. | |
7cd44c6d MV |
260 | When @var{highlights} is given, |
261 | it should be a list and all members of it are highligthed in | |
262 | the backtrace. | |
07d83abe MV |
263 | @end deffn |
264 | ||
265 | ||
266 | @node Examining Stack Frames | |
267 | @subsection Examining Stack Frames | |
268 | ||
269 | @deffn {Scheme Procedure} frame? obj | |
270 | @deffnx {C Function} scm_frame_p (obj) | |
271 | Return @code{#t} if @var{obj} is a stack frame. | |
272 | @end deffn | |
273 | ||
274 | @deffn {Scheme Procedure} frame-number frame | |
275 | @deffnx {C Function} scm_frame_number (frame) | |
276 | Return the frame number of @var{frame}. | |
277 | @end deffn | |
278 | ||
279 | @deffn {Scheme Procedure} frame-previous frame | |
280 | @deffnx {C Function} scm_frame_previous (frame) | |
281 | Return the previous frame of @var{frame}, or @code{#f} if | |
282 | @var{frame} is the first frame in its stack. | |
283 | @end deffn | |
284 | ||
285 | @deffn {Scheme Procedure} frame-next frame | |
286 | @deffnx {C Function} scm_frame_next (frame) | |
287 | Return the next frame of @var{frame}, or @code{#f} if | |
288 | @var{frame} is the last frame in its stack. | |
289 | @end deffn | |
290 | ||
291 | @deffn {Scheme Procedure} frame-source frame | |
292 | @deffnx {C Function} scm_frame_source (frame) | |
293 | Return the source of @var{frame}. | |
294 | @end deffn | |
295 | ||
296 | @deffn {Scheme Procedure} frame-procedure? frame | |
297 | @deffnx {C Function} scm_frame_procedure_p (frame) | |
298 | Return @code{#t} if a procedure is associated with @var{frame}. | |
299 | @end deffn | |
300 | ||
301 | @deffn {Scheme Procedure} frame-procedure frame | |
302 | @deffnx {C Function} scm_frame_procedure (frame) | |
303 | Return the procedure for @var{frame}, or @code{#f} if no | |
304 | procedure is associated with @var{frame}. | |
305 | @end deffn | |
306 | ||
307 | @deffn {Scheme Procedure} frame-arguments frame | |
308 | @deffnx {C Function} scm_frame_arguments (frame) | |
309 | Return the arguments of @var{frame}. | |
310 | @end deffn | |
311 | ||
312 | @deffn {Scheme Procedure} frame-evaluating-args? frame | |
313 | @deffnx {C Function} scm_frame_evaluating_args_p (frame) | |
314 | Return @code{#t} if @var{frame} contains evaluated arguments. | |
315 | @end deffn | |
316 | ||
317 | @deffn {Scheme Procedure} frame-overflow? frame | |
318 | @deffnx {C Function} scm_frame_overflow_p (frame) | |
319 | Return @code{#t} if @var{frame} is an overflow frame. | |
320 | @end deffn | |
321 | ||
322 | @deffn {Scheme Procedure} frame-real? frame | |
323 | @deffnx {C Function} scm_frame_real_p (frame) | |
324 | Return @code{#t} if @var{frame} is a real frame. | |
325 | @end deffn | |
326 | ||
327 | @deffn {Scheme Procedure} display-application frame [port [indent]] | |
328 | @deffnx {C Function} scm_display_application (frame, port, indent) | |
329 | Display a procedure application @var{frame} to the output port | |
330 | @var{port}. @var{indent} specifies the indentation of the | |
331 | output. | |
332 | @end deffn | |
333 | ||
334 | ||
335 | @node Decoding Memoized Source Expressions | |
336 | @subsection Decoding Memoized Source Expressions | |
337 | ||
338 | @deffn {Scheme Procedure} memoized? obj | |
339 | @deffnx {C Function} scm_memoized_p (obj) | |
340 | Return @code{#t} if @var{obj} is memoized. | |
341 | @end deffn | |
342 | ||
343 | @deffn {Scheme Procedure} unmemoize m | |
344 | @deffnx {C Function} scm_unmemoize (m) | |
345 | Unmemoize the memoized expression @var{m}, | |
346 | @end deffn | |
347 | ||
348 | @deffn {Scheme Procedure} memoized-environment m | |
349 | @deffnx {C Function} scm_memoized_environment (m) | |
350 | Return the environment of the memoized expression @var{m}. | |
351 | @end deffn | |
352 | ||
353 | ||
354 | @node Starting a New Stack | |
355 | @subsection Starting a New Stack | |
356 | ||
357 | @deffn {Scheme Syntax} start-stack id exp | |
358 | Evaluate @var{exp} on a new calling stack with identity @var{id}. If | |
359 | @var{exp} is interrupted during evaluation, backtraces will not display | |
360 | frames farther back than @var{exp}'s top-level form. This macro is a | |
361 | way of artificially limiting backtraces and stack procedures, largely as | |
362 | a convenience to the user. | |
363 | @end deffn | |
364 | ||
365 | ||
366 | @c Local Variables: | |
367 | @c TeX-master: "guile.texi" | |
368 | @c End: |