eric4.DebugClients.Ruby.DebugClientBaseModule

File implementing a debug client base module.

Global Attributes

None

Classes

None

Modules

DebugClientBase Module implementing the client side of the debugger.

Functions

None


DebugClientBase

Module implementing the client side of the debugger.

It provides access to the Ruby interpeter from a debugger running in another process.

The protocol between the debugger and the client assumes that there will be a single source of debugger commands and a single source of Ruby statements. Commands and statement are always exactly one line and may be interspersed.

The protocol is as follows. First the client opens a connection to the debugger and then sends a series of one line commands. A command is either >Load<, >Step<, >StepInto<, ... or a Ruby statement. See DebugProtocol.rb for a listing of valid protocol tokens.

A Ruby statement consists of the statement to execute, followed (in a separate line) by >OK?<. If the statement was incomplete then the response is >Continue<. If there was an exception then the response is >Exception<. Otherwise the response is >OK<. The reason for the >OK?< part is to provide a sentinal (ie. the responding >OK<) after any possible output as a result of executing the command.

The client may send any other lines at any other time which should be interpreted as program output.

If the debugger closes the session there is no response from the client. The client may close the session at any time as a result of the script being debugged closing or crashing.

Note: This module is meant to be mixed in by individual DebugClient classes. Do not use it directly.

Module Attributes

@@clientCapabilities

Classes

None

Functions

canEval? Private method to check if the buffer's contents can be evaluated.
completionList Method used to handle the command completion request
connectDebugger Public method to establish a session with the debugger.
dumpVariable Private method to return the variables of a frame to the debug server.
dumpVariables Private method to return the variables of a frame to the debug server.
eventLoop Private method implementing our event loop.
eventPoll Private method to poll for events like 'set break point'.
extractAddress Private method to extract the address part of an object description.
extractTypeAndAddress Private method to extract the address and type parts of an object description.
formatVariablesList Private method to produce a formated variables list.
generateFilterObjects Private method to convert a filter string to a list of filter objects.
handleException Private method called in the case of an exception
handleLine Private method to handle the receipt of a complete line.
inFilter? Private method to check, if a variable is to be filtered based on its type.
initializeDebugClient Method to initialize the module
interact Private method to Interact with the debugger.
main Public method implementing the main method.
progTerminated Private method to tell the debugger that the program has terminated.
sessionClose Privat method to close the session with the debugger and terminate.
startProgInDebugger Method used to start the remote debugger.
trace_func Method executed by the tracing facility.
unhandled_exception Private method to report an unhandled exception.
write Private method to write data to the output stream.

DebugClientBase.canEval?

canEval?()

Private method to check if the buffer's contents can be evaluated.

Returns:
flag indicating if an eval might succeed (boolean)

DebugClientBase.completionList

completionList()

Method used to handle the command completion request

text
the text to be completed (string)

DebugClientBase.connectDebugger

connectDebugger(remoteAddress=nil, redirect=true)

Public method to establish a session with the debugger.

It opens a network connection to the debugger, connects it to stdin, stdout and stderr and saves these file objects in case the application being debugged redirects them itself.

port
the port number to connect to (int)
remoteAddress
the network address of the debug server host (string)
redirect
flag indicating redirection of stdin, stdout and stderr (boolean)

DebugClientBase.dumpVariable

dumpVariable(frmnr, scope, filter)

Private method to return the variables of a frame to the debug server.

var
list encoded name of the requested variable (list of strings)
frmnr
distance of frame reported on. 0 is the current frame (int)
scope
1 to report global variables, 0 for local variables (int)
filter
the indices of variable types to be filtered (list of int)

DebugClientBase.dumpVariables

dumpVariables(scope, filter)

Private method to return the variables of a frame to the debug server.

frmnr
distance of frame reported on. 0 is the current frame (int)
scope
1 to report global variables, 0 for local variables (int)
filter
the indices of variable types to be filtered (list of int)

DebugClientBase.eventLoop

eventLoop()

Private method implementing our event loop.

DebugClientBase.eventPoll

eventPoll()

Private method to poll for events like 'set break point'.

DebugClientBase.extractAddress

extractAddress()

Private method to extract the address part of an object description.

var
object description (String)
Returns:
the address contained in the object description (String)

DebugClientBase.extractTypeAndAddress

extractTypeAndAddress()

Private method to extract the address and type parts of an object description.

var
object description (String)
Returns:
list containing the type and address contained in the object description (Array of two String)

DebugClientBase.formatVariablesList

formatVariablesList(binding_, scope, filter = [], excludeSelf = false, access = nil)

Private method to produce a formated variables list.

The binding passed in to it is scanned. Variables are only added to the list, if their type is not contained in the filter list and their name doesn't match any of the filter expressions. The formated variables list (a list of lists of 3 values) is returned.

keylist
keys of the dictionary
binding_
the binding to be scanned
scope
1 to filter using the globals filter, 0 using the locals filter (int). Variables are only added to the list, if their name do not match any of the filter expressions.
filter
the indices of variable types to be filtered. Variables are only added to the list, if their type is not contained in the filter list.
excludeSelf
flag indicating if the self object should be excluded from the listing (boolean)
access
String specifying the access path to (String)
Returns:
A list consisting of a list of formatted variables. Each variable entry is a list of three elements, the variable name, its type and value.

DebugClientBase.generateFilterObjects

generateFilterObjects(filterString)

Private method to convert a filter string to a list of filter objects.

scope
1 to generate filter for global variables, 0 for local variables (int)
filterString
string of filter patterns separated by ';'

DebugClientBase.handleException

handleException()

Private method called in the case of an exception

It ensures that the debug server is informed of the raised exception.

DebugClientBase.handleLine

handleLine()

Private method to handle the receipt of a complete line.

It first looks for a valid protocol token at the start of the line. Thereafter it trys to execute the lines accumulated so far.

line
the received line

DebugClientBase.inFilter?

inFilter?(otype, oval)

Private method to check, if a variable is to be filtered based on its type.

filter
the indices of variable types to be filtered (Array of int.
otype
type of the variable to be checked (String)
oval
variable value to be checked (String)
Returns:
flag indicating, whether the variable should be filtered (boolean)

DebugClientBase.initializeDebugClient

initializeDebugClient()

Method to initialize the module

DebugClientBase.interact

interact()

Private method to Interact with the debugger.

DebugClientBase.main

main()

Public method implementing the main method.

DebugClientBase.progTerminated

progTerminated()

Private method to tell the debugger that the program has terminated.

status
the return status

DebugClientBase.sessionClose

sessionClose()

Privat method to close the session with the debugger and terminate.

DebugClientBase.startProgInDebugger

startProgInDebugger(wd = '', host = nil, port = nil, exceptions = true, traceRuby = false, redirect=true)

Method used to start the remote debugger.

progargs
commandline for the program to be debugged (list of strings)
wd
working directory for the program execution (string)
host
hostname of the debug server (string)
port
portnumber of the debug server (int)
exceptions
flag to enable exception reporting of the IDE (boolean)
traceRuby
flag to enable tracing into the Ruby library
redirect
flag indicating redirection of stdin, stdout and stderr (boolean)

DebugClientBase.trace_func

trace_func(file, line, id, binding_, klass)

Method executed by the tracing facility.

It is used to save the execution context of an exception.

event
the tracing event (String)
file
the name of the file being traced (String)
line
the line number being traced (int)
id
object id
binding_
a binding object
klass
name of a class

DebugClientBase.unhandled_exception

unhandled_exception()

Private method to report an unhandled exception.

exc
the exception object

DebugClientBase.write

write()

Private method to write data to the output stream.

s
data to be written (string)
Up