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