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

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

eric ide

mercurial