next up previous contents index
Next: The Rehash Button: Rebuild Up: The User Menu: User Previous: Encrypted Scripts   Contents   Index

The Debug Button: Enter Script Debugger

The Debugger button in the User Menu, which unlike most of the other commands in this menu is an internal command, brings up a panel which facilitates script development. The panel contains debugging options such as breakpoints, single-stepping, and text editing.

The text window displays the text of the currently loaded script. In editing mode, the verbatim text is shown. When not in editing mode, the text is shifted to the right by two columns, so that the first column can be used to indicate breakpoints and the current line.

The current mode (editing or executing) is switched by the button to the left of the title bar. The label of this button switches between ``Run'' and ``Edit'' to indicate the mode to switch to. In edit mode, the Execute menu is not available. In execute mode, the Edit menu is not available, and some functions in the File menu, such as New and Load, will switch back to edit mode.

While in editing mode, the text in the window can be edited, using the same keyboard commands as the text editor pop-up. The text is shown as it appears in the buffer, without the first two columns reserved for breakpoint indication as used outside of edit mode.

The following command buttons appear in the File menu.

This button will clear the present contents of the text window, allowing a new script to be keyed in. If the present script is modified and not saved, a message will inform the user, and the text will not be cleared. Pressing the New button a second time will clear the text, and the previous changes will be lost.

The Load button will prompt for the name of a script file, which will be loaded into the debugger. A full path must be given to the file, if the file is not in the script search path. If, while the load pop-up is active, a script is selected in the User Menu, that script name will be loaded into the load dialog text area.

The Print button brings up a control panel for sending the contents of the text window to a printer, or to a file.

Save As
This button allows the contents of the text window to be saved in a file. The user is prompted for the name of the file, the default being the original file name, if any. A pre-existing file of the same name will be retained with a ``.bak'' extension.

Write CRLF
This menu item appears only in the Windows version. It controls the line termination format used in files written using Save As. The default is to use the archaic Windows two-byte (DOS) termination. If this button is unset, the more modern and efficient Unix-style termination is used. Older Windows programs such as Notepad require two-byte termination. Most newer objects and programs can use either format, as can the XicTools programs.

The Quit button will retire the debug panel, which is the same effect as pressing the Debugger button in the User Menu a second time. If there is unsaved text, a message will alert the user, and the panel will not be withdrawn. Pressing the Quit button a second time will retire the panel without saving changes. The debugger can also be dismissed with the window manager ``delete window'' function, which has the same effect as the Quit button.

The debugger text window serves as a drop receiver. Files can be loaded by dragging from the File Selection panel or another drag source, and dropping into the text window of the debugger, or the small ``load'' dialog window that receives the file name. The file name will be transferred to the load dialog, which will appear if not already present.

If, while in editing mode, the Ctrl key is held during the drop, the text will instead be inserted into the document at the insertion point.

The Edit menu contains commands specific to editing mode, and is disabled while in execute mode.

Undo This will undo the last modification, progressively. The number of operations that can be undone is limited to 25 in Windows, but is unlimited in Unix/Linux.

Redo This will redo previously undone operations, progressively.

The remaining entries allow copying of selected text to and from other windows. These work with the clipboard provided by the operating system, which is a means of transferring a data item between windows on the desktop (see 3.13.3).

Cut to Clipboard
Delete selected text to the clipboard. The accelerator Ctrl-x also performs this operation. This function is not available if the text is read-only.

Copy to Clipboard
Copy selected text to the clipboard. The accelerator Ctrl-c also performs this operation. This function is available whether or not the text is read-only.

Paste from Clipboard
Paste the contents of the clipboard into the document at the cursor location. The accelerator Ctrl-v also performs this operation. This function is not available if the text is read-only.

Paste Primary (Unix/Linux only)
Paste the contents of the primary selection register into the document at the cursor location. The accelerator Alt-p also performs this operation. This function is not available if the text is read-only.

The Execute menu contains commands for executing the script in a controlled fashion. Displaying this menu switches to execute mode. The text is shifted to the right by two columns. The first column is used to indicate the next line to execute, and breakpoints.

The current line, which would be executed next, is shown with a colored `>' in the first column. Clicking on this line will cause the line to be executed, and the `>' will advance to the next executable line (the same as the Step menu item). Clicking on any other executable line of text in the text window will set a breakpoint, or clear the breakpoint if a breakpoint is already set on that line. A line containing a breakpoint is shown with a `B' in the first column. Execution, initiated with the Run button, will pause before the next line containing a breakpoint, after the current line.

The Run button will cause lines of the script to be executed until a line containing a breakpoint or the end of the script is reached. Pressing Ctrl-c when a drawing window has the focus will cause the script to pause at the next line.

The Step button causes the current line to be executed, and the current line pointer will be advanced to the next line.

The Reset button will reset the current line to the start of the script.

In addition to the accelerators listed in the Execute menu, there are hard-coded accelerators for the menu functions.

t, Space single step
r run
e, Backspace reset

A problem with the menu accelerators is that they require the Ctrl key to be pressed, which may fool scripts that are sensitive to the Ctrl key.

The Monitor button allows variables to be monitored and set.

After the Monitor button is pressed, the user is prompted for the names of variables from the Xic prompt line. A list of variable names (space separated) is entered. A pop-up window will appear which lists these variables and their present values. If the variable is undefined or not in scope, the value will be ``???''. The values are updated after each line is executed. If, in response to the prompt for a list of variables, one enters ``all'' or ``*'' or ``.'', all of the variables currently in scope will be monitored.

Variables being displayed in the monitor window can be set to an arbitrary value by clicking on the variable name in the monitor window. The value will be prompted for on the Xic prompt line. Only variables that are in scope will accept a value. This feature can be used to alter program operation as the program is being run. Variables will continue to be monitored until the monitor window is dismissed.

The monitor window in the script debugger can handle multi-dimensional arrays. When specifying an array variable, the variable name can be followed by a range specification, enclosed in square brackets, as follows:

[rmin- rmax,dim2,dim3]

This is entirely optional, as are the individual entries. The three comma separated fields correspond to the three dimensions (maximum) of the array. The lowest dimension can be a range, where rmin and rmax set the range of indices to print or set. The remaining two fields are indices into the higher dimensions. These indices are taken as 0 if not given. One of the range values can be omitted, with the following interpretations:

[rmin, ... Use the single index rmin.
[rmin- , ... Use the range rmin to the length of the lowest dimension.
[- rmax, ... Use the range 0 - rmax.

White space can appear, and the commas are optional, except in the second form above where a comma must follow the `-'.

If the rmax value is less than rmin, the printing order of the elements is reversed, as is the order of elements accepted when the variable is being set.

A similar range specification can be applied to string variables. In this case, only the first field is relevant, and the range applies to character positions.

The following commands are found in the Options menu of the editor. These commands are always available.

Pop up a dialog which solicits a regular expression to search for in the document. The up and down arrow buttons will perform the search, in the direction of the arrows. If the No Case button is active, case will be ignored in the search. The next matching text in the document will be highlighted. If there is no match, ``not found'' will be displayed in the message area of the pop-up.

The search starts at the current text insertion point (the location of the I-beam cursor). This may not be visible in execute mode, but can be set by clicking with button 1 (which may set a breakpoint, so you will have to click again to remove it). The search does not wrap.

This brings up a tool for selecting the font to use in the text window. Selecting a font will change the present font, and will set the default fixed-pitch font used in pop-up text windows.

next up previous contents index
Next: The Rehash Button: Rebuild Up: The User Menu: User Previous: Encrypted Scripts   Contents   Index
Stephen R. Whiteley 2022-05-28