Documentation/Source/eric4.DebugClients.Ruby.DebugClientBaseModule.html

changeset 3
0d9daebf5b8c
equal deleted inserted replaced
2:bc6196164237 3:0d9daebf5b8c
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN'
3 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>
4 <html><head>
5 <title>eric4.DebugClients.Ruby.DebugClientBaseModule</title>
6 <style>
7 body {
8 background:white;
9 margin: 0em 1em 10em 1em;
10 color: black;
11 }
12
13 h1 { color: white; background: #4FA4FF; }
14 h2 { color: white; background: #4FA4FF; }
15 h3 { color: white; background: #00557F; }
16 h4 { color: white; background: #00557F; }
17
18 a { color: #AA5500; }
19
20 </style>
21 </head>
22 <body><a NAME="top" ID="top"></a>
23 <h1>eric4.DebugClients.Ruby.DebugClientBaseModule</h1>
24 <p>
25 File implementing a debug client base module.
26 </p>
27 <h3>Global Attributes</h3>
28 <table>
29 <tr><td>None</td></tr>
30 </table>
31 <h3>Classes</h3>
32 <table>
33 <tr><td>None</td></tr>
34 </table>
35 <h3>Modules</h3>
36 <table>
37 <tr>
38 <td><a href="#DebugClientBase">DebugClientBase</a></td>
39 <td>Module implementing the client side of the debugger.</td>
40 </tr>
41 </table>
42 <h3>Functions</h3>
43 <table>
44 <tr><td>None</td></tr>
45 </table>
46 <hr /><hr />
47 <a NAME="DebugClientBase" ID="DebugClientBase"></a>
48 <h2>DebugClientBase</h2>
49 <p>
50 Module implementing the client side of the debugger.
51 </p><p>
52 It provides access to the Ruby interpeter from a debugger running in another
53 process.
54 </p><p>
55 The protocol between the debugger and the client assumes that there will be
56 a single source of debugger commands and a single source of Ruby
57 statements. Commands and statement are always exactly one line and may be
58 interspersed.
59 </p><p>
60 The protocol is as follows. First the client opens a connection to the
61 debugger and then sends a series of one line commands. A command is either
62 &gt;Load&lt;, &gt;Step&lt;, &gt;StepInto&lt;, ... or a Ruby statement.
63 See DebugProtocol.rb for a listing of valid protocol tokens.
64 </p><p>
65 A Ruby statement consists of the statement to execute, followed (in a
66 separate line) by &gt;OK?&lt;. If the statement was incomplete then the response
67 is &gt;Continue&lt;. If there was an exception then the response is &gt;Exception&lt;.
68 Otherwise the response is &gt;OK&lt;. The reason for the &gt;OK?&lt; part is to
69 provide a sentinal (ie. the responding &gt;OK&lt;) after any possible output as a
70 result of executing the command.
71 </p><p>
72 The client may send any other lines at any other time which should be
73 interpreted as program output.
74 </p><p>
75 If the debugger closes the session there is no response from the client.
76 The client may close the session at any time as a result of the script
77 being debugged closing or crashing.
78 </p><p>
79 <b>Note</b>: This module is meant to be mixed in by individual DebugClient classes.
80 Do not use it directly.
81 </p>
82 <h3>Module Attributes</h3>
83 <table>
84 <tr><td>@@clientCapabilities</td></tr>
85 </table>
86 <h3>Classes</h3>
87 <table>
88 <tr><td>None</td></tr>
89 </table>
90 <h3>Functions</h3>
91 <table>
92 <tr>
93 <td><a href="#DebugClientBase.canEval?">canEval?</a></td>
94 <td>Private method to check if the buffer's contents can be evaluated.</td>
95 </tr><tr>
96 <td><a href="#DebugClientBase.completionList">completionList</a></td>
97 <td>Method used to handle the command completion request</td>
98 </tr><tr>
99 <td><a href="#DebugClientBase.connectDebugger">connectDebugger</a></td>
100 <td>Public method to establish a session with the debugger.</td>
101 </tr><tr>
102 <td><a href="#DebugClientBase.dumpVariable">dumpVariable</a></td>
103 <td>Private method to return the variables of a frame to the debug server.</td>
104 </tr><tr>
105 <td><a href="#DebugClientBase.dumpVariables">dumpVariables</a></td>
106 <td>Private method to return the variables of a frame to the debug server.</td>
107 </tr><tr>
108 <td><a href="#DebugClientBase.eventLoop">eventLoop</a></td>
109 <td>Private method implementing our event loop.</td>
110 </tr><tr>
111 <td><a href="#DebugClientBase.eventPoll">eventPoll</a></td>
112 <td>Private method to poll for events like 'set break point'.</td>
113 </tr><tr>
114 <td><a href="#DebugClientBase.extractAddress">extractAddress</a></td>
115 <td>Private method to extract the address part of an object description.</td>
116 </tr><tr>
117 <td><a href="#DebugClientBase.extractTypeAndAddress">extractTypeAndAddress</a></td>
118 <td>Private method to extract the address and type parts of an object description.</td>
119 </tr><tr>
120 <td><a href="#DebugClientBase.formatVariablesList">formatVariablesList</a></td>
121 <td>Private method to produce a formated variables list.</td>
122 </tr><tr>
123 <td><a href="#DebugClientBase.generateFilterObjects">generateFilterObjects</a></td>
124 <td>Private method to convert a filter string to a list of filter objects.</td>
125 </tr><tr>
126 <td><a href="#DebugClientBase.handleException">handleException</a></td>
127 <td>Private method called in the case of an exception</td>
128 </tr><tr>
129 <td><a href="#DebugClientBase.handleLine">handleLine</a></td>
130 <td>Private method to handle the receipt of a complete line.</td>
131 </tr><tr>
132 <td><a href="#DebugClientBase.inFilter?">inFilter?</a></td>
133 <td>Private method to check, if a variable is to be filtered based on its type.</td>
134 </tr><tr>
135 <td><a href="#DebugClientBase.initializeDebugClient">initializeDebugClient</a></td>
136 <td>Method to initialize the module</td>
137 </tr><tr>
138 <td><a href="#DebugClientBase.interact">interact</a></td>
139 <td>Private method to Interact with the debugger.</td>
140 </tr><tr>
141 <td><a href="#DebugClientBase.main">main</a></td>
142 <td>Public method implementing the main method.</td>
143 </tr><tr>
144 <td><a href="#DebugClientBase.progTerminated">progTerminated</a></td>
145 <td>Private method to tell the debugger that the program has terminated.</td>
146 </tr><tr>
147 <td><a href="#DebugClientBase.sessionClose">sessionClose</a></td>
148 <td>Privat method to close the session with the debugger and terminate.</td>
149 </tr><tr>
150 <td><a href="#DebugClientBase.startProgInDebugger">startProgInDebugger</a></td>
151 <td>Method used to start the remote debugger.</td>
152 </tr><tr>
153 <td><a href="#DebugClientBase.trace_func">trace_func</a></td>
154 <td>Method executed by the tracing facility.</td>
155 </tr><tr>
156 <td><a href="#DebugClientBase.unhandled_exception">unhandled_exception</a></td>
157 <td>Private method to report an unhandled exception.</td>
158 </tr><tr>
159 <td><a href="#DebugClientBase.write">write</a></td>
160 <td>Private method to write data to the output stream.</td>
161 </tr>
162 </table>
163 <hr />
164
165 <a NAME="DebugClientBase.canEval?" ID="DebugClientBase.canEval?"></a>
166 <h4>DebugClientBase.canEval?</h4>
167 <b>canEval?</b>(<i></i>)
168 <p>
169 Private method to check if the buffer's contents can be evaluated.
170 </p><dl>
171 <dt>Returns:</dt>
172 <dd>
173 flag indicating if an eval might succeed (boolean)
174 </dd>
175 </dl><a NAME="DebugClientBase.completionList" ID="DebugClientBase.completionList"></a>
176 <h4>DebugClientBase.completionList</h4>
177 <b>completionList</b>(<i></i>)
178 <p>
179 Method used to handle the command completion request
180 </p><dl>
181 <dt><i>text</i></dt>
182 <dd>
183 the text to be completed (string)
184 </dd>
185 </dl><a NAME="DebugClientBase.connectDebugger" ID="DebugClientBase.connectDebugger"></a>
186 <h4>DebugClientBase.connectDebugger</h4>
187 <b>connectDebugger</b>(<i>remoteAddress=nil, redirect=true</i>)
188 <p>
189 Public method to establish a session with the debugger.
190 </p><p>
191 It opens a network connection to the debugger, connects it to stdin,
192 stdout and stderr and saves these file objects in case the application
193 being debugged redirects them itself.
194 </p><dl>
195 <dt><i>port</i></dt>
196 <dd>
197 the port number to connect to (int)
198 </dd><dt><i>remoteAddress</i></dt>
199 <dd>
200 the network address of the debug server host (string)
201 </dd><dt><i>redirect</i></dt>
202 <dd>
203 flag indicating redirection of stdin, stdout and stderr (boolean)
204 </dd>
205 </dl><a NAME="DebugClientBase.dumpVariable" ID="DebugClientBase.dumpVariable"></a>
206 <h4>DebugClientBase.dumpVariable</h4>
207 <b>dumpVariable</b>(<i>frmnr, scope, filter</i>)
208 <p>
209 Private method to return the variables of a frame to the debug server.
210 </p><dl>
211 <dt><i>var</i></dt>
212 <dd>
213 list encoded name of the requested variable (list of strings)
214 </dd><dt><i>frmnr</i></dt>
215 <dd>
216 distance of frame reported on. 0 is the current frame (int)
217 </dd><dt><i>scope</i></dt>
218 <dd>
219 1 to report global variables, 0 for local variables (int)
220 </dd><dt><i>filter</i></dt>
221 <dd>
222 the indices of variable types to be filtered (list of int)
223 </dd>
224 </dl><a NAME="DebugClientBase.dumpVariables" ID="DebugClientBase.dumpVariables"></a>
225 <h4>DebugClientBase.dumpVariables</h4>
226 <b>dumpVariables</b>(<i>scope, filter</i>)
227 <p>
228 Private method to return the variables of a frame to the debug server.
229 </p><dl>
230 <dt><i>frmnr</i></dt>
231 <dd>
232 distance of frame reported on. 0 is the current frame (int)
233 </dd><dt><i>scope</i></dt>
234 <dd>
235 1 to report global variables, 0 for local variables (int)
236 </dd><dt><i>filter</i></dt>
237 <dd>
238 the indices of variable types to be filtered (list of int)
239 </dd>
240 </dl><a NAME="DebugClientBase.eventLoop" ID="DebugClientBase.eventLoop"></a>
241 <h4>DebugClientBase.eventLoop</h4>
242 <b>eventLoop</b>(<i></i>)
243 <p>
244 Private method implementing our event loop.
245 </p><a NAME="DebugClientBase.eventPoll" ID="DebugClientBase.eventPoll"></a>
246 <h4>DebugClientBase.eventPoll</h4>
247 <b>eventPoll</b>(<i></i>)
248 <p>
249 Private method to poll for events like 'set break point'.
250 </p><a NAME="DebugClientBase.extractAddress" ID="DebugClientBase.extractAddress"></a>
251 <h4>DebugClientBase.extractAddress</h4>
252 <b>extractAddress</b>(<i></i>)
253 <p>
254 Private method to extract the address part of an object description.
255 </p><dl>
256 <dt><i>var</i></dt>
257 <dd>
258 object description (String)
259 </dd>
260 </dl><dl>
261 <dt>Returns:</dt>
262 <dd>
263 the address contained in the object description (String)
264 </dd>
265 </dl><a NAME="DebugClientBase.extractTypeAndAddress" ID="DebugClientBase.extractTypeAndAddress"></a>
266 <h4>DebugClientBase.extractTypeAndAddress</h4>
267 <b>extractTypeAndAddress</b>(<i></i>)
268 <p>
269 Private method to extract the address and type parts of an object description.
270 </p><dl>
271 <dt><i>var</i></dt>
272 <dd>
273 object description (String)
274 </dd>
275 </dl><dl>
276 <dt>Returns:</dt>
277 <dd>
278 list containing the type and address contained in the object
279 description (Array of two String)
280 </dd>
281 </dl><a NAME="DebugClientBase.formatVariablesList" ID="DebugClientBase.formatVariablesList"></a>
282 <h4>DebugClientBase.formatVariablesList</h4>
283 <b>formatVariablesList</b>(<i>binding_, scope, filter = [], excludeSelf = false, access = nil</i>)
284 <p>
285 Private method to produce a formated variables list.
286 </p><p>
287 The binding passed in to it is scanned. Variables are
288 only added to the list, if their type is not contained
289 in the filter list and their name doesn't match any of the filter expressions.
290 The formated variables list (a list of lists of 3 values) is returned.
291 </p><dl>
292 <dt><i>keylist</i></dt>
293 <dd>
294 keys of the dictionary
295 </dd><dt><i>binding_</i></dt>
296 <dd>
297 the binding to be scanned
298 </dd><dt><i>scope</i></dt>
299 <dd>
300 1 to filter using the globals filter, 0 using the locals filter (int).
301 Variables are only added to the list, if their name do not match any of the
302 filter expressions.
303 </dd><dt><i>filter</i></dt>
304 <dd>
305 the indices of variable types to be filtered. Variables are
306 only added to the list, if their type is not contained in the filter
307 list.
308 </dd><dt><i>excludeSelf</i></dt>
309 <dd>
310 flag indicating if the self object should be excluded from
311 the listing (boolean)
312 </dd><dt><i>access</i></dt>
313 <dd>
314 String specifying the access path to (String)
315 </dd>
316 </dl><dl>
317 <dt>Returns:</dt>
318 <dd>
319 A list consisting of a list of formatted variables. Each variable
320 entry is a list of three elements, the variable name, its type and
321 value.
322 </dd>
323 </dl><a NAME="DebugClientBase.generateFilterObjects" ID="DebugClientBase.generateFilterObjects"></a>
324 <h4>DebugClientBase.generateFilterObjects</h4>
325 <b>generateFilterObjects</b>(<i>filterString</i>)
326 <p>
327 Private method to convert a filter string to a list of filter objects.
328 </p><dl>
329 <dt><i>scope</i></dt>
330 <dd>
331 1 to generate filter for global variables, 0 for local variables (int)
332 </dd><dt><i>filterString</i></dt>
333 <dd>
334 string of filter patterns separated by ';'
335 </dd>
336 </dl><a NAME="DebugClientBase.handleException" ID="DebugClientBase.handleException"></a>
337 <h4>DebugClientBase.handleException</h4>
338 <b>handleException</b>(<i></i>)
339 <p>
340 Private method called in the case of an exception
341 </p><p>
342 It ensures that the debug server is informed of the raised exception.
343 </p><a NAME="DebugClientBase.handleLine" ID="DebugClientBase.handleLine"></a>
344 <h4>DebugClientBase.handleLine</h4>
345 <b>handleLine</b>(<i></i>)
346 <p>
347 Private method to handle the receipt of a complete line.
348 </p><p>
349 It first looks for a valid protocol token at the start of the line. Thereafter
350 it trys to execute the lines accumulated so far.
351 </p><dl>
352 <dt><i>line</i></dt>
353 <dd>
354 the received line
355 </dd>
356 </dl><a NAME="DebugClientBase.inFilter?" ID="DebugClientBase.inFilter?"></a>
357 <h4>DebugClientBase.inFilter?</h4>
358 <b>inFilter?</b>(<i>otype, oval</i>)
359 <p>
360 Private method to check, if a variable is to be filtered based on its type.
361 </p><dl>
362 <dt><i>filter</i></dt>
363 <dd>
364 the indices of variable types to be filtered (Array of int.
365 </dd><dt><i>otype</i></dt>
366 <dd>
367 type of the variable to be checked (String)
368 </dd><dt><i>oval</i></dt>
369 <dd>
370 variable value to be checked (String)
371 </dd>
372 </dl><dl>
373 <dt>Returns:</dt>
374 <dd>
375 flag indicating, whether the variable should be filtered (boolean)
376 </dd>
377 </dl><a NAME="DebugClientBase.initializeDebugClient" ID="DebugClientBase.initializeDebugClient"></a>
378 <h4>DebugClientBase.initializeDebugClient</h4>
379 <b>initializeDebugClient</b>(<i></i>)
380 <p>
381 Method to initialize the module
382 </p><a NAME="DebugClientBase.interact" ID="DebugClientBase.interact"></a>
383 <h4>DebugClientBase.interact</h4>
384 <b>interact</b>(<i></i>)
385 <p>
386 Private method to Interact with the debugger.
387 </p><a NAME="DebugClientBase.main" ID="DebugClientBase.main"></a>
388 <h4>DebugClientBase.main</h4>
389 <b>main</b>(<i></i>)
390 <p>
391 Public method implementing the main method.
392 </p><a NAME="DebugClientBase.progTerminated" ID="DebugClientBase.progTerminated"></a>
393 <h4>DebugClientBase.progTerminated</h4>
394 <b>progTerminated</b>(<i></i>)
395 <p>
396 Private method to tell the debugger that the program has terminated.
397 </p><dl>
398 <dt><i>status</i></dt>
399 <dd>
400 the return status
401 </dd>
402 </dl><a NAME="DebugClientBase.sessionClose" ID="DebugClientBase.sessionClose"></a>
403 <h4>DebugClientBase.sessionClose</h4>
404 <b>sessionClose</b>(<i></i>)
405 <p>
406 Privat method to close the session with the debugger and terminate.
407 </p><a NAME="DebugClientBase.startProgInDebugger" ID="DebugClientBase.startProgInDebugger"></a>
408 <h4>DebugClientBase.startProgInDebugger</h4>
409 <b>startProgInDebugger</b>(<i>wd = '', host = nil, port = nil, exceptions = true, traceRuby = false, redirect=true</i>)
410 <p>
411 Method used to start the remote debugger.
412 </p><dl>
413 <dt><i>progargs</i></dt>
414 <dd>
415 commandline for the program to be debugged
416 (list of strings)
417 </dd><dt><i>wd</i></dt>
418 <dd>
419 working directory for the program execution (string)
420 </dd><dt><i>host</i></dt>
421 <dd>
422 hostname of the debug server (string)
423 </dd><dt><i>port</i></dt>
424 <dd>
425 portnumber of the debug server (int)
426 </dd><dt><i>exceptions</i></dt>
427 <dd>
428 flag to enable exception reporting of the IDE (boolean)
429 </dd><dt><i>traceRuby</i></dt>
430 <dd>
431 flag to enable tracing into the Ruby library
432 </dd><dt><i>redirect</i></dt>
433 <dd>
434 flag indicating redirection of stdin, stdout and stderr (boolean)
435 </dd>
436 </dl><a NAME="DebugClientBase.trace_func" ID="DebugClientBase.trace_func"></a>
437 <h4>DebugClientBase.trace_func</h4>
438 <b>trace_func</b>(<i>file, line, id, binding_, klass</i>)
439 <p>
440 Method executed by the tracing facility.
441 </p><p>
442 It is used to save the execution context of an exception.
443 </p><dl>
444 <dt><i>event</i></dt>
445 <dd>
446 the tracing event (String)
447 </dd><dt><i>file</i></dt>
448 <dd>
449 the name of the file being traced (String)
450 </dd><dt><i>line</i></dt>
451 <dd>
452 the line number being traced (int)
453 </dd><dt><i>id</i></dt>
454 <dd>
455 object id
456 </dd><dt><i>binding_</i></dt>
457 <dd>
458 a binding object
459 </dd><dt><i>klass</i></dt>
460 <dd>
461 name of a class
462 </dd>
463 </dl><a NAME="DebugClientBase.unhandled_exception" ID="DebugClientBase.unhandled_exception"></a>
464 <h4>DebugClientBase.unhandled_exception</h4>
465 <b>unhandled_exception</b>(<i></i>)
466 <p>
467 Private method to report an unhandled exception.
468 </p><dl>
469 <dt><i>exc</i></dt>
470 <dd>
471 the exception object
472 </dd>
473 </dl><a NAME="DebugClientBase.write" ID="DebugClientBase.write"></a>
474 <h4>DebugClientBase.write</h4>
475 <b>write</b>(<i></i>)
476 <p>
477 Private method to write data to the output stream.
478 </p><dl>
479 <dt><i>s</i></dt>
480 <dd>
481 data to be written (string)
482 </dd>
483 </dl>
484 <div align="right"><a href="#top">Up</a></div>
485 <hr />
486 </body></html>

eric ide

mercurial