A. Sources of Routine Info

In 4.2 Routine Info and 4.4 Completion we showed how IDLWAVE displays the calling sequence and keywords of routines, and completes routine names and keywords. For these features to work, IDLWAVE must know about the accessible routines.

A.1 Routine Definitions

Routines which can be used in an IDL program can be defined in several places:

1. Builtin routines are defined inside IDL itself. The source code of such routines is not available.
2. Routines which are part of the current program, are defined in a file explicitly compiled by the user. This file may or may not be located on the IDL search path.
3. Library routines are defined in files located on IDL's search path, and will not need to be manually compiled. When a library routine is called for the first time, IDL will find the source file and compile it dynamically. A special sub-category of library routines are the system routines distributed with IDL, and usually available in the `lib' subdirectory of the IDL distribution.
4. External routines written in other languages (like Fortran or C) can be called with CALL_EXTERNAL, linked into IDL via LINKIMAGE, or included as dynamically loaded modules (DLMs). Currently IDLWAVE cannot provide routine info and completion for such external routines.

A.2 Routine Information Sources

To maintain the most comprehensive information about all IDL routines on a system, IDLWAVE collects data from many sources:

1. It has a builtin list with information about the routines IDL ships with. IDLWAVE 5.1 is distributed with a list of 1460 routines and 6586 keywords, reflecting IDL version 5.6. This list has been created by scanning the IDL manuals and is stored in the file `idlw-rinfo.el'. See section A.5 Documentation Scan, for information on how to regenerate this file for new versions of IDL.

2. It scans all buffers of the current Emacs session for routine definitions. This is done automatically when routine information or completion is first requested by the user. Each new buffer and each buffer saved after making changes is also scanned. The command C-c C-i (idlwave-update-routine-info) can be used at any time to rescan all buffers.

3. If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will query the shell for compiled routines and their arguments. This happens automatically when routine information or completion is first requested by the user, and each time an Emacs buffer is compiled with C-c C-d C-c. Though rarely necessary, the command C-c C-i (idlwave-update-routine-info) can be used to update the shell routine data.

4. Many popular libraries are distributed with routine information already scanned into library catalogs (see section A.3.1 Library Catalogs). These per-directory catalog files can also be built by the user with the supplied `idlwave_catalog' tool.

5. IDLWAVE can scan selected directories of source files and store the result in a single user catalog file which will be automatically loaded just like `idlw-rinfo.el'. See section A.3.2 User Catalog, for information on how to scan files in this way.

Loading routine and catalog information can be a time consuming process, especially over slow networks. Depending on the system and network configuration it could take up to 30 seconds. In order to minimize the wait time upon your first completion or routine info command in a session, IDLWAVE uses Emacs idle time to do the initialization in six steps, yielding to user input in between. If this gets into your way, set the variable idlwave-init-rinfo-when-idle-after to 0 (zero). The more routines documented in library and user catalogs, the slower the loading will be, so reducing this number can help alleviate any long load times.

User Option: idlwave-init-rinfo-when-idle-after (10)

Seconds of idle time before routine info is automatically initialized.

User Option: idlwave-scan-all-buffers-for-routine-info (t)

Non-nil means scan all buffers for IDL programs when updating info.

User Option: idlwave-query-shell-for-routine-info (t)

Non-nil means query the shell for info about compiled routines.

User Option: idlwave-auto-routine-info-updates

Controls under what circumstances routine info is updated automatically.

<A NAME="CATALOGS"></A>

A.3 Catalogs

Catalogs are files containing scanned information on individual routines, including arguments and keywords, calling sequence, file path, class and procedure vs. function type, etc. They represent a way of extending the internal built-in information available for IDL system routines (see section 4.2 Routine Info) to other source collections.

Starting with version 5.0, there are two types of catalogs available with IDLWAVE. The traditional user catalog and the newer library catalogs. Although they can be used interchangeably, the library catalogs are more flexible, and preferred. There are few occasions when a user catalog might be preferred -- read below. Both types of catalogs can coexist without causing problems.

To facilitate the catalog systems, IDLWAVE stores information it gathers from the shell about the IDL search paths, and can write this information out automatically, or on-demand (menu Debug->Save Path Info). On systems with no shell from which to discover the path information (e.g. Windows), a library path must be specified in idlwave-library-path to allow library catalogs to be located, and to setup directories for user catalog scan (see section A.3.2 User Catalog for more on this variable).

User Option: idlwave-auto-write-path (t)

Write out information on the !PATH and !DIR paths from IDL automatically when they change and when the Shell is closed. These paths are needed to locate library catalogs.

User Option: idlwave-library-path

IDL library path for Windows and MacOS. Not needed under Unix/MacOSX.

User Option: idlwave-system-directory

The IDL system directory for Windows and MacOS. Not needed under Unix/MacOSX (obtained from the Shell).

User Option: idlwave-config-directory (`~/.idlwave')

Default path where IDLWAVE saves configuration information and any user catalog.

<A NAME="LIBRARY_CATALOGS"></A>

A.3.1 Library Catalogs

Library catalogs are files named `.idlwave_catalog' stored in directories containing .pro routine files. They are discovered on the IDL search path and loaded automatically when routine information is read. Each catalog file documents the routines found in that directory -- one catalog per directory. Every catalog has a library name associated with it (e.g. AstroLib). This name will be shown briefly when the catalog is found, and in the routine info of routines it documents.

Many popular libraries of routines include such catalog files by default, and so will be automatically discovered. Library catalogs are scanned externally to Emacs using a tool provided with IDLWAVE. Each can be re-scanned independently, depending on how often it changes. Catalogs can easily be made available system-wide with a common source repository, providing uniform routine information, and lifting the burden of scanning from the user (who may not even know they're using a scanned catalog). Since each catalog is independent of the others, they can be re-scanned automatically to gather updates, e.g. in a `cron' job. Scanning is much faster than with the built-in user catalog method. One minor disadvantage: the entire IDL search path is scanned for catalog files every time IDLWAVE starts up, which might be slow over a network.

A Perl tool to create library catalogs is distributed with IDLWAVE: idlwave_catalog. It can be called quite simply:

idlwave_catalog MyLib

This would scan all directories recursively beneath the current and populate them with `.idlwave_catalog' files, tagging the routines found with the name "MyLib". The full usage information:

Usage: idlwave_catalog  [-l] [-v] [-d] [-s] [-f] [-h] libname
       libname - Unique name of the catalog (4 or more alphanumeric
                 characters).
            -l - Scan local directory only, otherwise recursively
                 catalog all directories at or beneath this one.
            -v - Print verbose information.
            -d - Instead of scanning, delete all .idlwave_catalog files
                 here or below.
            -s - Be silent.
            -f - Force overwriting any catalogs found with a different
                 library name.
            -h - Print this usage.

To re-load the library catalogs on the IDL path, force a system routine info update using a single prefix to idlwave-update-routine-info: C-u C-c C-i.

User Option: idlwave-use-library-catalogs (t)

Whether to search for and load library catalogs. Only disable if performance is a problem and the catalogs are not needed.

A.3.2 User Catalog

The user catalog is the old routine catalog system. It is produced within Emacs, and stored in a single file in the user's home directory (`.idlwave/idlusercat.el' by default). Although library catalogs are more flexible, there may be reasons to prefer a user catalog instead, including:

• The scan is internal to Emacs, so you don't need a working Perl installation, as you do for library catalogs.
• Can be used to scan directories for which the user has no write privileges.
• Easy widget-based path selection.

However, no routine info is available in the user catalog by default; the user must actively complete a scan. In addition, this type of catalog is all or nothing: if a single routine changes, the entire catalog must be rescanned to update it. Creating the user catalog is also much slower than scanning library catalogs.

You can scan any of the directories on the currently known path. Under Windows and MacOS (not OSX), you need to specify the IDL search path in the variable idlwave-library-path, and the location of the IDL directory (the value of the !DIR system variable) in the variable idlwave-system-directory, like this(11):

(setq idlwave-library-path
        '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs"))
(setq idlwave-system-directory "c:/RSI/IDL56/")

Under GNU and UNIX, these values will be automatically gathered from the IDLWAVE shell.

The command M-x idlwave-create-user-catalog-file (or the menu item `IDLWAVE->Routine Info->Select Catalog Directories' can then be used to create a user catalog. It brings up a widget in which you can select some or all directories on the search path. Directories which already contain a library catalog are marked with `[LIB]', and need not be scanned (although there is no harm if you do so, other than the additional memory used for the duplication).

After selecting directories, click on the `[Scan & Save]' button in the widget to scan all files in the selected directories and write out the resulting routine information. In order to update the library information using the directory selection, call the command idlwave-update-routine-info with a double prefix argument: C-u C-u C-c C-i. This will rescan files in the previously selected directories, write an updated version of the user catalog file and rebuild IDLWAVE's internal lists. If you give three prefix arguments C-u C-u C-u C-c C-i, updating will be done with a background job(12). You can continue to work, and the library catalog will be re-read when it is ready. If you find you need to update the user catalog often, you should consider building a library catalog for these routines instead (see section A.3.1 Library Catalogs).

User Option: idlwave-special-lib-alist

Alist of regular expressions matching special library directories for labeling in routine-info display.

A.4 Load-Path Shadows

IDLWAVE can compile a list of routines which are defined in several different files. Since one definition will hide (shadow) the others depending on which file is compiled first, such multiple definitions are called "load-path shadows". IDLWAVE has several routines to scan for load path shadows. The output is placed into the special buffer `*Shadows*'. The format of the output is identical to the source section of the routine info buffer (see section 4.2 Routine Info). The different definitions of a routine are listed in the sequence of likelihood of use. So the first entry will be most likely the one you'll get if an unsuspecting command uses that routine. Before listing shadows, you should make sure that routine info is up-to-date by pressing C-c C-i. Here are the different routines:

M-x idlwave-list-buffer-load-path-shadows

This commands checks the names of all routines defined in the current buffer for shadowing conflicts with other routines accessible to IDLWAVE. The command also has a key binding: C-c C-b

M-x idlwave-list-shell-load-path-shadows.

Checks all routines compiled under the shell for shadowing. This is very useful when you have written a complete application. Just compile the application, use RESOLVE_ALL to compile any routines used by your code, update the routine info inside IDLWAVE with C-c C-i and then check for shadowing.

M-x idlwave-list-all-load-path-shadows

This command checks all routines accessible to IDLWAVE for conflicts.

For these commands to work fully you need to scan the entire load path in either a user or library catalog. Also, IDLWAVE should be able to distinguish between the system library files (normally installed in `/usr/local/rsi/idl/lib') and any site specific or user specific files. Therefore, such local files should not be installed inside the `lib' directory of the IDL directory. This is also advisable for many other reasons.

Users of Windows and MacOS also must set the variable idlwave-system-directory to the value of the !DIR system variable in IDL. IDLWAVE appends `lib' to the value of this variable and assumes that all files found on that path are system routines.

Another way to find out if a specific routine has multiple definitions on the load path is routine info display (see section 4.2 Routine Info).

A.5 Documentation Scan

IDLWAVE derives its knowledge about system routines from the IDL manuals. The file `idlw-rinfo.el' contains the routine information for the IDL system routines, and links to relevant sections of the HTML documentation. The Online Help feature of IDLWAVE requires HTML versions of the IDL manuals to be available.

The HTML files and related images can be produced from the `idl.chm' HTMLHelp file distributed with IDL using the free Microsoft HTML Help Workshop. If you are lucky, the maintainer of IDLWAVE will always have access to the newest version of IDL and provide updates. The IDLWAVE distribution also contains the Perl program `get_html_rinfo' which constructs the `idlw-rinfo.el' file by scanning the HTML documents produced from the IDL documentation. Instructions on how to use `get_html_rinfo' are in the program itself.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.