idlwave: Routine Info
4.2 Routine Info
================
IDL comes bundled with more than one thousand procedures, functions and
object methods, and large libraries typically contain hundreds or even
thousands more (each with a few to tens of keywords and arguments).
This large command set can make it difficult to remember the calling
sequence and keywords for the routines you use, but IDLWAVE can help.
It builds up routine information from a wide variety of sources; IDLWAVE
in fact knows far more about the ‘.pro’ routines on your system than IDL
itself! It maintains a list of all built-in routines, with calling
sequences and keywords(1). It also scans Emacs buffers for routine
definitions, queries the IDLWAVE-Shell for information about routines
currently compiled there, and automatically locates library and
user-created catalogs. This information is updated automatically, and
so should usually be current. To force a global update and refresh the
routine information, use ‘C-c C-i’ (‘idlwave-update-routine-info’).
To display the information about a routine, press ‘C-c ?’, which
calls the command ‘idlwave-routine-info’. When the current cursor
position is on the name or in the argument list of a procedure or
function, information will be displayed about the routine. For example,
consider the indicated cursor positions in the following line:
plot,x,alog(x+5*sin(x) + 2),
| | | | | | | |
1 2 3 4 5 6 7 8
On positions 1,2 and 8, information about the ‘plot’ procedure will
be shown. On positions 3,4, and 7, the ‘alog’ function will be
described, while positions 5 and 6 will investigate the ‘sin’ function.
When you ask for routine information about an object method, and the
method exists in several classes, IDLWAVE queries for the class of the
object, unless the class is already known through a text property on the
‘->’ operator (
Object Method Completion and Class Ambiguity), or
by having been explicitly included in the call (e.g.,
‘a->myclass::Foo’).
The description displayed contains the calling sequence, the list of
keywords and the source location of this routine. It looks like this:
Usage: XMANAGER, NAME, ID
Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER
JUST_REG MODAL NO_BLOCK
Source: SystemLib [LCSB] /soft1/idl53/lib/xmanager.pro
If a definition of this routine exists in several files accessible to
IDLWAVE, several ‘Source’ lines will point to the different files. This
may indicate that your routine is shadowing a system library routine,
which may or may not be what you want (Load-Path Shadows). The
information about the calling sequence and keywords is derived from the
first source listed. Library routines are available only if you have
scanned your local IDL directories or are using pre-scanned libraries
(Catalogs). The source entry consists of a _source category_, a
set of _flags_ and the path to the _source file_. The following default
categories exist:
System A system routine of unknown origin. When the system
library has been scanned as part of a catalog
(Catalogs), this category will automatically split
into the next two.
Builtin A builtin system routine with no source code available.
SystemLib A library system routine in the official lib directory
‘!DIR/lib’.
Obsolete A library routine in the official lib directory
‘!DIR/lib/obsolete’.
Library A routine in a file on IDL’s search path ‘!PATH’.
Other Any other routine with a file not known to be on the search
path.
Unresolved An otherwise unknown routine the shell lists as unresolved
(referenced, but not compiled).
Any routines discovered in library catalogs (Library
Catalogs), will display the category assigned during creation, e.g.,
‘NasaLib’. For routines not discovered in this way, you can create
additional categories based on the routine’s filename using the variable
‘idlwave-special-lib-alist’.
The flags ‘[LCSB]’ indicate the source of the information IDLWAVE has
regarding the file: from a library catalog (‘[L---]’), from a user
catalog (‘[-C--]’, from the IDL Shell (‘[--S-]’) or from an Emacs buffer
(‘[---B]’). Combinations are possible (a compiled library routine
visited in a buffer might read ‘[L-SB]’). If a file contains multiple
definitions of the same routine, the file name will be prefixed with
‘(Nx)’ where ‘N’ is the number of definitions.
Some of the text in the ‘*Help*’ routine info buffer will be active
(it is highlighted when the mouse moves over it). Typically, clicking
with the right mouse button invokes online help lookup, and clicking
with the middle mouse button inserts keywords or visits files:
Usage If online help is installed, a click with the _right_ mouse
button on the Usage: line will access the help for the
routine (Online Help).
Keyword Online help about keywords is also available with the
_right_ mouse button. Clicking on a keyword with the
_middle_ mouse button will insert this keyword in the
buffer from where ‘idlwave-routine-info’ was called.
Holding down <SHIFT> while clicking also adds the initial
‘/’.
Source Clicking with the _middle_ mouse button on a ‘Source’ line
finds the source file of the routine and visits it in
another window. Another click on the same line switches
back to the buffer from which ‘C-c ?’ was called. If you
use the _right_ mouse button, the source will not be
visited by a buffer, but displayed in the online help
window.
Classes The Classes line is only included in the routine info
window if the current class inherits from other classes.
You can click with the _middle_ mouse button to display
routine info about the current method in other classes on
the inheritance chain, if such a method exists there.
-- User Option: idlwave-resize-routine-help-window (‘t’)
Non-‘nil’ means resize the Routine-info ‘*Help*’ window to fit the
content.
-- User Option: idlwave-special-lib-alist
Alist of regular expressions matching special library directories.
-- User Option: idlwave-rinfo-max-source-lines (‘5’)
Maximum number of source files displayed in the Routine Info
window.
---------- Footnotes ----------
(1) This list is created by scanning the IDL manuals and might
contain (very few) errors. Please report any errors to the maintainer,
so that they can be fixed.
Info Catalog
idlwave: Code Formatting
idlwave: The IDLWAVE Major Mode
idlwave: Online Help