# 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