dbXtra and dbxtra

dbxtra keyboard interface

In order to use dbxtra screen functions (see ``dbxtra screen functions''), you must bind them to a key sequence using the dbxtra bindkey command.

The syntax of the command is:

bindkey [ key-sequence screen-function | > filename ]

The key-sequence can be any valid key designation defined in the terminfo(M) database. It can also be a combination of characters enclosed in double quotes ("), including control characters as entered from the keyboard. Control characters can also be specified using the ^X notation or as an octal number using the \nnn notation. For example, the following two key definitions are equivalent:

   (dbxtra) bindkey "^[[A" "cursor_up"
   (dbxtra) bindkey "\033[A" "cursor_up"

screen-function must be enclosed in double quotes ("). Key sequences are interpreted as soon as they are typed in. If one sequence is a prefix of another, then it is interpreted first, effectively hiding the longer one.

If key-sequence is not specified, definitions of all key-sequence are printed. This output can be redirected to a file (using "> filename") so that the bindings can be used in subsequent invocations of dbxtra.

To obtain a list of currently bound key sequences, execute:

   (dbxtra) bindkey

The directory /usr/lib/dbxtra/keys contains key binding files for various terminal types. For example, to load the key bindings file for the ansi terminal, execute:

   (dbxtra) source /usr/lib/dbxtra/keys/keys.ansi

To unbind a key bound with bindkey, use:

   (dbxtra) unbindkey key-sequence

The syntax for key-sequence is the same as that for bindkey.

If an attempt is made to bind a key that is already bound, the first argument cannot be given verbatim unless key interpretation is disabled (using the keys off command).

To use a different set of bindings, make use of the contents of the TERM environment variables as the name of the key bindings file for each terminal (for example, key.at386 or key.wy60). Thus the correct file is automatically loaded if the following line is included in your .dbxtrarc file:

   source /usr/lib/dbxtra/keys/keys.$TERM

If more than one screen-function is specified, each command must be separated by the ";" character. If no screen-function is specified, the current definition of the key-sequence is printed.

dbxtra screen functions

NOTE: In order to use dbxtra screen functions you must bind them to a key sequence using the dbxtra bindkey command. See ``dbxtra keyboard interface''.

The following is a listing and description of the various commands that can be specified in the screen-function parameter of the bindkey command:

bof: Move cursor to the beginning of file. The screen is scrolled or redrawn as necessary. If the current window is not a source window (for instance, if it was the interaction window), then the cursor is moved to the head of the buffer. The buffer contains up to 128 lines, so if more than 128 lines were written in this window the old lines are lost.
bol: Move cursor to beginning of line (not including line numbers if in source window).
close: Close the current window. If the current window is a source window, then another source window (the top neighbor by priority) is expanded, inherits the capabilities of the current window, and becomes the current window. If there is no other source window, the current window cannot be closed.
If the current window is the Output window, then the dbxtra session window (that is, the Interaction window) is expanded and inherits the Output capability. The Interaction window cannot be closed.
cursor_down: Move the cursor one line down. If the cursor is at the bottom of the window but not at the end of file, then the text is scrolled one line.
cursor_left: Move the cursor one character to the left.
cursor_right: Move the cursor one character to the right.
cursor_up: Move the cursor one line up. If the cursor is at the top of the window but not at the beginning of file, then the text is scrolled one line.
del_bol: If the cursor is on a line being entered as a dbxtra command, then delete from the cursor location to the beginning of the command.
del_char: If the cursor is on the line being entered as a dbxtra command, then delete the character at the cursor location.
del_word: If the cursor is on the line being entered as a dbxtra command, then delete the word (string delimited by spaces) to the left of the cursor.
eof: Move cursor to end of file (or buffer). It is a complementary function to bof.
eol: Move cursor to end of line. If the current line is the line being entered as a dbxtra command, then the cursor is moved one column beyond the last character on the line.
expand: Expand the current window by two lines. If the current window has two neighbors (above and below, not necessarily immediate neighbors) that are larger than one line, then each of them is shrunk by one line. Otherwise, the boundary between the current window and its neighbor is moved by two lines.
expand_lower: Expand current window by moving its lower edge by one line (provided that there exists a window that can be shrunk).
expand_upper: Expand current window by moving its upper edge by one line (provided that there exists a window that can be shrunk).
goto_line: Move cursor to line number. The user is prompted to enter the line number. This function only works for source windows.
goto_mark: Move cursor to the window location marked by set_mark (see below).
half_page_back: Scroll half page backward.
half_page_forw: Scroll half page forward.
load_file: Load file into current window. dbxtra prompts for the filename and this is entered from the keyboard. This command can only be used in a window with the browse, C, and C++ capabilities.
line_back: Scroll one line backward.
line_forw: Scroll one line forward.
move_capability: Move a capability to the current window. The capability must follow the command. The supported capabilities are browse and C. When the debugging is in C++ mode, the C++ capability is also recognized.
next_command: Display the next line entered by the user to the dbxtra interaction window.
next_window: Change current window to the next window below the current one. If the current window is the bottom window, then the next window is the top window. An asterisk (*) is displayed on the left side of the separator line of the window the cursor is in.
page_back: Scroll one page backward.
page_forw: Scroll one page forward.
prev_command: Display the previous line entered by the user to the dbxtra interaction window.
prev_window: Change current window to the previous window (above). If the current window is the top window, then the previous window is the bottom window. An asterisk (*) is displays on the left side of the separator line of the window the cursor is in.
quote_char: Accept next character as is, that is, do not perform key interpretation on it.
redraw: Redraw the screen.
screen_function: Prompt for the name of a screen function and invoke it.
This function can invoke screen functions that are not bound to keys.
send_edit: Display the argument as a command to dbxtra but do not execute the command so that it can be edited before being invoked. For example, suppose the string ``send_edit stop in'' is bound to the key ``^X''. Then typing <Ctrl>X causes dbxtra to echo ``stop in'' and then wait for the user to complete the command.
send_echo: Display the argument specified as a command to dbxtra and also execute the command. For example, binding ``^X'' to ``send_echo stop in main'' causes dbxtra to echo and execute the command ``stop in main'' when <Ctrl>X is typed.
send_noecho: Execute the command specified but do not display the command in the interaction window.
set_mark: Set a mark in a window. This mark is used by goto_mark (see above).
show_xref: Before using show_xref, the xref command must be used first on some identifier. When this has been done, move the cursor (using cursor_up, for example) to an identifier in the output of xref then use show_xref. This displays in the source window the lines around the identifier the cursor is at.
shrink: Shrink the current window by two lines. If the current window has two neighbors (above and below), then each of the neighboring windows is expanded by one line. Otherwise, the boundary between the current window and its neighbor is moved by two lines. A window cannot be shrunk to size zero.
split: Splitting a source window creates a new source window with no capabilities and the new window becomes the current window. Splitting the dbxtra session window creates a program window.
toggle_follow_cursor: Toggle between the static portion of the full screen window and the portion of the window containing the cursor. This is only useful when the program window is being used.
toggle_full_screen: Toggle between the full screen window and the standard dbx/source window layout. Since this is a screen function, it can only be used when the program is not executing.
toggle_line_numbers: Toggle with/without line numbers in source windows.
toggle_more: Toggle paging for interaction window.
toggle_wrap_around: Toggle wraparound of long lines in source windows.
word_left: Move cursor one word (single non-alphanumeric character or a string of alphanumeric and underline characters) left.
word_right: Move cursor one word (single non-alphanumeric character or a string of alphanumeric and underline characters) right.

Some of the commands require arguments. In these cases, the string following the command name, until a ``;'' or the end of the line is encountered, is used as the parameter. If the ``;'' character is preceded by a ``\'' (backslash) character, it is interpreted as part of the parameter rather than a parameter terminator. Any number of editing variables can be specified in the parameter string. The following are the editing variables supported and their functions:

$command

evaluates to the full dbxtra command at the cursor line. For example, the sequence ``cursor_up; send_edit $command'' causes dbxtra to display the command at the previous line and wait for the user to edit it.

$events

evaluates to the event-ids of breakpoints at the cursor line (applies to source windows only).

$expr

evaluates to the expression at the cursor location. The expression is derived according to the following rules:

If the character at the cursor location is alphanumeric (or "_"), then all adjacent alphanumeric characters to the left are included.
Otherwise, if the character at the cursor location is the dereference operator ("*"), it is included along with any spaces on its right.
If the next character on the right is alphanumeric (or "_"), it is included.
If the next character on the right is "(" or "[", then it is included along with all the characters up to (and including) the matching ")" or "]".
If the next character on the right is the field operator ("." or "->"), it is included.
If the next two characters on the right are "::" (the C++ class member operator) they are included.

Steps 3 through 6 are repeated until no more suitable characters are found.

$file

evaluates to source filename in the current window

$keyboard

causes dbxtra to prompt the user with a ``:'' to enter a line and evaluates that line. For example, ``move_capability $keyboard'' prompts the user for the name of the capability to be moved.

$line

evaluates to the source line number at the cursor location. For example, ``send_echo stop at $line'' sets a breakpoint at the current cursor location.

$var

evaluates to the longest string of alphanumeric and ``_'' characters at the cursor position.

Sample key bindings

The following is a set of sample key bindings, a subset of those in the file called /usr/lib/dbxtra/keys/keys.at386, distributed with the development system. They are known to work with the at386 terminfo entry included with your distribution of dbXtra and dbxtra. Use the source command to load them into your dbxtra session.

Key name/sequence Editing command

key_up "cursor_up"

key_left "cursor_left"

key_right "cursor_right"

key_down "cursor_down"

"^[[G" "page_forw"

"^[[I" "page_back"

"^[[E^[[H" "bof"

"^[[E^[[F" "eof"

"^[[H" "bol"

"^[[F" "eol"

"^[[C" "close"

"key_f9" "split; move_capability C"

"key_f10" "split; move_capability C++"

"^[[E^[[E" "next_window"

"^[[E^[[G" "expand"

"^[[E^[[I" "shrink"

"^[[L" "send_echo stop at $line"

"^[[E^?" "send_echo delete $events"

"^P" "prev_command"

"^N" "next_command"

Key name/sequence	Editing command
key_up	"cursor_up"
key_left	"cursor_left"
key_right	"cursor_right"
key_down	"cursor_down"
"^[[G"	"page_forw"
"^[[I"	"page_back"
"^[[E^[[H"	"bof"
"^[[E^[[F"	"eof"
"^[[H"	"bol"
"^[[F"	"eol"
"^[[C"	"close"
"key_f9"	"split; move_capability C"
"key_f10"	"split; move_capability C++"
"^[[E^[[E"	"next_window"
"^[[E^[[G"	"expand"
"^[[E^[[I"	"shrink"
"^[[L"	"send_echo stop at $line"
"^[[E^?"	"send_echo delete $events"

"^P"	"prev_command"
"^N"	"next_command"