| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The IDLWAVE shell is an Emacs major mode which permits running the IDL program as an inferior process of Emacs, and works closely with the IDLWAVE major mode in buffers. It can be used to work with IDL interactively, to compile and run IDL programs in Emacs buffers and to debug these programs. The IDLWAVE shell is built upon `comint', an Emacs packages which handles the communication with the IDL program. Unfortunately IDL for Windows and MacOS do not have command-prompt versions and thus do not allow the interaction with Emacs(4) -- so the IDLWAVE shell currently only works under Unix.
5.1 Starting the Shell How to launch IDL as a subprocess 5.2 Using the Shell Interactively working with the Shell 5.3 Commands Sent to the Shell 5.4 Debugging IDL Programs 5.5 Examining Variables 5.6 Custom Expression Examination
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The IDLWAVE shell can be started with the command M-x
idlwave-shell. In idlwave-mode the function is bound to
C-c C-s. It creates a buffer `*idl*' which is used to
interact with the shell. If the shell is already running, C-c C-s
will simple switch to the shell buffer. The command C-c C-l
(idlwave-shell-recenter-shell-window) displays the shell window
without selecting it. The shell can also be started automatically when
another command tries to send a command to it. To enable auto start,
set the variable idlwave-shell-automatic-start to t.
In order to create a separate frame for the IDLWAVE shell buffer, call
idlwave-shell with a prefix argument: C-u C-c C-s or
C-u C-c C-l. If you always want a dedicated frame for the shell
window, configure the variable
idlwave-shell-use-dedicated-frame.
To launch a quick IDLWAVE shell directly from a shell prompt without an IDLWAVE buffer (e.g., as a replacement for running inside an xterm), define an alias with the following content:
emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" |
Replace the `-geometry 80x32' option with `-nw' if you prefer the Emacs process to run directly inside the terminal window.
nil)
nil means attempt to invoke idlwave-shell if not already
running.
t)
nil means preserve command history between sessions.
nil)
nil means IDLWAVE should use a special frame to display
shell buffer.
t)
nil means `idlwave-shell' raises the frame showing the shell
window.
idlwave-shell-mode.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The IDLWAVE shell works in the same fashion as other shell modes in Emacs. It provides command history, command line editing and job control. The UP and DOWN arrows cycle through the input history just like in an X terminal(5). The history is preserved between emacs and IDL sessions. Here is a list of commonly used commands:
| UP, M-p | Cycle backwards in input history |
| DOWN, M-n | Cycle forwards in input history |
| M-r | Previous input matching a regexp |
| M-s | Next input matching a regexp |
| return | Send input or copy line to current prompt |
| C-c C-a | Beginning of line; skip prompt |
| C-c C-u | Kill input to beginning of line |
| C-c C-w | Kill word before cursor |
| C-c C-c | Send ^C |
| C-c C-z | Send ^Z |
| C-c C-\ | Send ^\ |
| C-c C-o | Delete last batch of process output |
| C-c C-r | Show last batch of process output |
| C-c C-l | List input history |
In addition to these standard `comint' commands,
idlwave-shell-mode provides many of the same commands which
simplify writing IDL code available in IDLWAVE buffers. This includes
abbreviations, online help, and completion. See 4.2 Routine Info and
4.3 Online Help and 4.4 Completion for more information on these
commands.
| TAB | Completion of file names (between quotes and after executive
commands `.run' and `.compile'), routine names, class names,
keywords, system variables, system variable tags etc.
(idlwave-shell-complete).
|
| M-TAB | Same as TAB |
| C-c ? | Routine Info display (idlwave-routine-info)
|
| M-? | IDL online help on routine (idlwave-routine-info-from-idlhelp)
|
| C-c C-i | Update routine info from buffers and shell
(idlwave-update-routine-info)
|
| C-c C-v | Find the source file of a routine (idlwave-find-module)
|
| C-c = | Compile a library routine (idlwave-resolve)
|
t)
nil means UP and DOWN arrows move through command
history like xterm.
IDLWAVE works in line input mode: You compose a full command line, using
all the power Emacs gives you to do this. When you press RET, the
whole line is sent to IDL. Sometimes it is necessary to send single
characters (without a newline), for example when an IDL program is
waiting for single character input with the GET_KBRD function.
You can send a single character to IDL with the command C-c C-x
(idlwave-shell-send-char). When you press C-c C-y
(idlwave-shell-char-mode-loop), IDLWAVE runs a blocking loop
which accepts characters and immediately sends them to IDL. The loop
can be exited with C-g. It terminates also automatically when the
current IDL command is finished. Check the documentation of the two
variables described below for a way to make IDL programs trigger
automatic switches of the input mode.
nil)
nil means IDLWAVE should check for input mode spells in
output.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The IDLWAVE buffers and shell interact very closely. In addition to the
normal commands you enter at the IDL> prompt, many other special
commands are sent to the shell, sometimes as a direct result of invoking
a key command, menu item, or toolbar button, but also automatically, as
part of the normal flow of information updates between the buffer and
shell.
The commands sent include breakpoint, .step and other
debug commands (see section 5.4 Debugging IDL Programs), .run and other
compilation statements (see section 5.4.2 Compiling Programs), examination
commands like print and help (see section 5.5 Examining Variables), and other special purpose commands designed to keep
information on the running shell current.
By default, much of this background shell input and output is hidden
from the user, but this is configurable. The custom variable
idlwave-abbrev-show-commands allows you to configure which
commands sent to the shell are shown there. For a related customization
for separating the output of examine commands See section 5.5 Examining Variables.
'(run misc breakpoint))
run for .run, .compile and other run commands,
misc for lesser used commands like window, retall,
etc., breakpoint for breakpoint setting and clearing commands,
and debug for other debug, stepping, and continue commands. In
addition, if the variable is set to the single symbol 'everything,
all the copious shell input is displayed (which is probably only useful
for debugging purposes).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Programs can be compiled, run, and debugged directly from the source
buffer in Emacs. IDLWAVE makes compiling and debugging IDL programs
far less cumbersome by providing a full-featured,
key/menu/toolbar-driven interface to commands like breakpoint,
.step, .run, etc.
The IDLWAVE shell installs key bindings both in the shell buffer and in
all IDL code buffers of the current Emacs session, so debug commands
work in both places (in the shell, commands operate on the last file
compiled). On Emacs versions which support this, a debugging toolbar is
also installed. The display of the toolbar can be toggled with C-c
C-d C-t (idlwave-shell-toggle-toolbar).
t)
nil means use the debugging toolbar in all IDL related
buffers.
5.4.1 Debug Key Bindings 5.4.2 Compiling Programs 5.4.3 Breakpoints and Stepping 5.4.4 Walking the Calling Stack
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The debugging key bindings are by default on the prefix key C-c
C-d, so for example setting a breakpoint is done with C-c C-d
C-b, and compiling a source file with C-c C-d C-c. If you find
this too much work, you can easily configure IDLWAVE to use one or more
modifier keys not in use by other commands, in lieu of the prefix
C-c C-d (though these bindings will typically also be available
--- see idlwave-shell-activate-prefix-keybindings). For example,
if you write in `.emacs':
(setq idlwave-shell-debug-modifiers '(control shift)) |
a breakpoint can be set by pressing b while holding down
shift and control keys, i.e. C-S-b. Compiling a
source file will be on C-S-c, deleting a breakpoint C-S-d,
etc. In the remainder of this chapter we will assume that the C-c
C-d bindings are active, but each of these bindings will have an
equivalent single-keypress shortcut if modifiers are given in the
idlwave-shell-debug-modifiers variable (see see section 3.2 Lesson II: Customization).
idlwave-shell-mode-prefix-map.
t)
nil means debug commands will be bound to the prefix
key, like C-c C-d C-b.
nil)
control, meta, super, hyper, alt, and
shift.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In order to compile the current buffer under the IDLWAVE shell, press
C-c C-d C-c (idlwave-save-and-run). This first saves the
current buffer and then sends the command `.run path/to/file' to the
shell. You can also execute C-c C-d C-c from the shell buffer, in
which case the most recently compiled buffer will be saved and
re-compiled.
When developing or debugging a program, it is often necessary to execute
the same command line many times. A convenient way to do this is
C-c C-d C-y (idlwave-shell-execute-default-command-line).
This command first resets IDL from a state of interrupted execution by
closing all files and returning to the main interpreter level. Then a
default command line is send to the shell. To edit the default command
line, call idlwave-shell-execute-default-command-line with a
prefix argument: C-u C-c C-d C-y.
t)
nil means mark the source code line where IDL is currently
stopped. The value specifies the preferred method. Legal values are
nil, t, arrow, and face.
">")
idlwave-shell-mark-stop-line.
idlwave-shell-mark-stop-line.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can set breakpoints and step through a program with IDLWAVE.
Setting a breakpoint in the current line of the source buffer is done
with C-c C-d C-b (idlwave-shell-break-here). With a prefix
arg of 1 (i.e. C-1 C-c C-d C-b), the breakpoint gets a
/ONCE keyword, meaning that it will be deleted after first use.
With a numeric prefix greater than one (e.g. C-4 C-c C-d C-b), the
breakpoint will only be active the nth time it is hit. With a
single non-numeric prefix (i.e. C-u C-c C-d C-b), prompt for a
condition -- an IDL expression to be evaulated and trigger the
breakpoint only if true. To clear the breakpoint in the current line,
use C-c C-d C-d (idlwave-clear-current-bp). When executed
from the shell window, the breakpoint where IDL is currently stopped
will be deleted. To clear all breakpoints, use C-c C-d C-a
(idlwave-clear-all-bp). Breakpoint lines are highlighted in the
source code. Note that IDL places breakpoints as close as possible on
or after the line you specify. IDLWAVE queries the shell for the actual
breakpoint location which was set, so the exact line you specify may not
be marked.
Once the program has stopped somewhere, you can step through it. The most important stepping commands are C-c C-d C-s to execute one line of IDL code ("step into"); C-c C-d C-n to step a single line, treating procedure and function calls as a single step ("step over"); C-c C-d C-h to continue execution to the line at the cursor and C-c C-d C-r to continue execution. See section 5.3 Commands Sent to the Shell, for information on displaying or hiding the breakpoint and stepping commands the shell receives. Here is a summary of the breakpoint and stepping commands:
| C-c C-d C-b | Set breakpoint (idlwave-shell-break-here)
|
| C-c C-d C-i | Set breakpoint in function named here (idlwave-shell-break-in)
|
| C-c C-d C-d | Clear current breakpoint (idlwave-shell-clear-current-bp)
|
| C-c C-d C-a | Clear all breakpoints (idlwave-shell-clear-all-bp)
|
| C-c C-d C-s | Step, into function calls (idlwave-shell-step)
|
| C-c C-d C-n | Step, over function calls (idlwave-shell-stepover)
|
| C-c C-d C-k | Skip one statement (idlwave-shell-skip)
|
| C-c C-d C-u | Continue to end of block (idlwave-shell-up)
|
| C-c C-d C-m | Continue to end of function (idlwave-shell-return)
|
| C-c C-d C-o | Continue past end of function (idlwave-shell-out)
|
| C-c C-d C-h | Continue to line at cursor position (idlwave-shell-to-here)
|
| C-c C-d C-r | Continue execution to next breakpoint (idlwave-shell-cont)
|
| C-c C-d C-up | Show higher level in calling stack (idlwave-shell-stack-up)
|
| C-c C-d C-down | Show lower level in calling stack (idlwave-shell-stack-down)
|
t)
nil means mark breakpoints in the source file buffers. The
value indicates the preferred method. Legal values are nil,
t, face, and glyph.
idlwave-shell-mark-breakpoints has the value face.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
While debugging a program, it can be very useful to check the context in
which the current routine was called, for instance to help understand
the value of the arguments passed. To do so conveniently you need to
examine the calling stack. If execution is stopped somewhere deep in a
program, you can use the commands C-c C-d C-UP
(idlwave-shell-stack-up) and C-c C-d C-DOWN
(idlwave-shell-stack-down), or the corresponding toolbar buttons,
to move up or down through the calling stack. The mode line of the
shell window will indicate the position within the stack with a label
like `[-3:MYPRO]'. The line of IDL code at that stack position
will be highlighted. If you continue execution, IDLWAVE will
automatically return to the current level. See section 5.5 Examining Variables,
for information how to examine the value of variables and expressions on
higher calling stack levels.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Do you find yourself repeatedly typing, e.g. print,n_elements(x),
and similar statements to remind yourself of the
type/size/structure/value/etc. of variables and expressions in your code
or at the command line? IDLWAVE has a suite of special commands to
automate these types of variables or expression examinations. They work
by sending statements to the shell formatted to include the indicated
expression.
These examination commands can be used in the shell or buffer at any time (as long as the shell is running), and are very useful when execution is stopped in a buffer due to a triggered breakpoint or error, or while composing a long command in the IDLWAVE shell. In the latter case, the command is sent to the shell and its output is visible, but point remains unmoved in the command being composed -- you can inspect the contituents of a command you're building without interrupting the process of building it! You can even print arbitrary expressions from older input or output further up in the shell window -- any expression, variable, number, or function you see can be examined.
If the variable idlwave-shell-separate-examine-output is
non-nil (the default), all examine output will be sent to a
special `*Examine*' buffer, rather than the shell. The output of
prior examine commands is saved. In this buffer c clears the
contents, and q hides the buffer.
The two most basic examine commands are bound to C-c C-d C-p, to print the expression at point, and C-c C-d ?, to invoke help on this expression. The expression at point is either an array expression or a function call, or the contents of a pair of parentheses. The selected expression is highlighted, and simultaneously the resulting output is highlighted in the shell. Calling the above commands with a prefix argument will prompt for an expression instead of using the one at point. Two prefix arguments (C-u C-u C-c C-d C-p) will use the current region as expression.
For added speed and convenience, there are mouse bindings which allow you to click on expressions and examine their values. Use S-Mouse-2 to print an expression and C-M-Mouse-2 to invoke help (i.e. you need to hold down META and CONTROL while clicking with the middle mouse button). If you simply click, the nearest expression will be selected in the same manner as described above. You can also drag the mouse in order to highlight exactly a specific expression or sub-expression to be examined. For custom expression examination, and the customizable pop-up examine selection, See section 5.6 Custom Expression Examination.
The same variable inspection commands work both in the IDL Shell and IDLWAVE buffers, and even for variables at higher levels of the calling stack. For instance, if you're stopped at a breakpoint in a routine, you can examine the values of variables and expressions inside its calling routine, and so on, all the way up through the calling stack. Simply step up the stack, and print variables as you see them (see section 5.4.4 Walking the Calling Stack, for information on stepping back through the calling stack). The following restrictions apply for all levels except the current:
ROUTINE_NAMES,
which may or may not be available in future versions of IDL.
idlwave-shell-expression-overlay.
Allows you to choose the font, color and other properties for
the expression printed by IDL.
idlwave-shell-output-overlay.
Allows to choose the font, color and other properties for the most
recent output of IDL when examining an expression."
t)
nil, re-direct the output of examine commands to a special
`*Examine*' buffer, instead of in the shell itself.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The variety of possible variable and expression examination commands is
endless (just look, for instance, at the keyword list to
widget_info()). Rather than attempt to include them all, IDLWAVE
provides two easy methods to customize your own commands, with a special
mouse examine command, and two macros for generating your own examine
bindings.
The most powerful and flexible mouse examine command is available on
C-S-Mouse-2. Just as for all the other mouse examine commands, it
permits click or drag expression selection, but instead of sending
hard-coded commands to the shell, it pops-up a customizable selection
list of examine functions to choose among, configured with the
idlwave-shell-examine-alist variable. This variable is a list of
key-value pairs (an alist in Emacs parlance), where the keys name
the command, and the values are the command strings, in which the text
___ (three underscores) will be replaced by the selected
expression before being sent to the shell. An example might be key
Structure Help with value help,___,/STRUCTURE.
idlwave-shell-examine-alist comes by default with a large list of
examine commands, but can be easily customized to add more.
In addition to the pop-up mouse command, you can easily create your own
customized bindings to inspect expressions using the two convenience
macros idlwave-shell-inspect and
idlwave-shell-mouse-inspect. These create keyboard or
mouse-based custom inspections of variables, sharing all the same
properties of the built-in examine commands. Both functions take a
single string argument sharing the syntax of the
idlwave-shell-examine-alist values, e.g.:
(add-hook 'idlwave-shell-mode-hook
(lambda ()
(idlwave-shell-define-key-both [s-down-mouse-2]
(idlwave-shell-mouse-examine
"print, size(___,/DIMENSIONS)"))
(idlwave-shell-define-key-both [f9] (idlwave-shell-examine
"print, size(___,/DIMENSIONS)"))
(idlwave-shell-define-key-both [f10] (idlwave-shell-examine
"print,size(___,/TNAME)"))
(idlwave-shell-define-key-both [f11] (idlwave-shell-examine
"help,___,/STRUCTURE"))))
|
___ are replaced
by the indicated expression.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |