1 \input texinfo @c -*-texinfo-*-
4 @settitle IDLWAVE User Manual
7 * IDLWAVE: (idlwave). Major mode and shell for IDL files.
15 @set NSYSROUTINES 1322
16 @set NSYSKEYWORDS 5952
18 @set AUTHOR J.D. Smith & Carsten Dominik
19 @set AUTHOR-EMAIL dominik@@astro.uva.nl
20 @set MAINTAINER J.D. Smith
21 @set MAINTAINER-EMAIL jdsmith@@as.arizona.edu
22 @set IDLWAVE-HOMEPAGE http://idlwave.org/
27 This file documents IDLWAVE, a major mode for editing IDL files with
28 Emacs, and interacting with an IDL shell run as a subprocess.
30 This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE
33 Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation,
36 Permission is granted to make and distribute verbatim
37 copies of this manual provided the copyright notice and
38 this permission notice are preserved on all copies.
41 Permission is granted to process this file through TeX and print the
42 results, provided the printed document carries a copying permission
43 notice identical to this one except for the removal of this paragraph
44 (this paragraph not being relevant to the printed manual).
47 Permission is granted to copy and distribute modified
48 versions of this manual under the conditions for
49 verbatim copying, provided that the entire resulting
50 derived work is distributed under the terms of a permission
51 notice identical to this one.
53 Permission is granted to copy and distribute
54 translations of this manual into another language,
55 under the above conditions for modified versions,
56 except that this permission notice may be stated in a
57 translation approved by the Free Software Foundation.
61 @title IDLWAVE User Manual
62 @subtitle Emacs major mode and shell for IDL
63 @subtitle Edition @value{EDITION}, @value{DATE}
65 @author by Carsten Dominik & J.D. Smith
67 Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
70 This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for
71 IDLWAVE version @value{VERSION}, @value{DATE}.
75 @cindex Copyright, of IDLWAVE
76 Permission is granted to make and distribute verbatim
77 copies of this manual provided the copyright notice and
78 this permission notice are preserved on all copies.
80 Permission is granted to copy and distribute modified
81 versions of this manual under the conditions for
82 verbatim copying, provided that the entire resulting
83 derive work is distributed under the terms of a permission
84 notice identical to this one.
86 Permission is granted to copy and distribute
87 translations of this manual into another language,
88 under the above conditions for modified versions,
89 except that this permission notice may be stated in a
90 translation approved by the Free Software Foundation.
99 @node Top, Introduction, (dir), (dir)
101 IDLWAVE is a package which supports editing source for the
102 Interactive Data Language (IDL), and running IDL as an inferior
108 * Introduction:: What IDLWAVE is and what it's not
109 * IDLWAVE in a Nutshell:: One page quick-start guide
110 * Getting Started:: Tutorial
111 * The IDLWAVE Major Mode:: The mode to edit IDL programs
112 * The IDLWAVE Shell:: The mode to run IDL as an inferior program
113 * Installation:: How to Install or Upgrade
114 * Acknowledgements:: Who did what
115 * Sources of Routine Info:: How does IDLWAVE know about routine XYZ
116 * Configuration Examples:: The user is king...
117 * Windows and MacOS:: What still works, and how
118 * Index:: Fast access
121 --- The Detailed Node Listing ---
123 Getting Started (Tutorial)
125 * Lesson I -- Development Cycle::
126 * Lesson II -- Customization::
127 * Lesson III -- Library Catalog::
129 The IDLWAVE Major Mode
131 * Code Formatting:: Making code look nice
132 * Routine Info:: Calling Sequence and Keyword List
133 * Online Help:: One key press from source to help
134 * Completion:: Completing routine names and Keywords
135 * Routine Source:: Finding routines, the easy way
136 * Resolving Routines:: Force the Shell to compile a routine
137 * Code Templates:: Frequent code constructs
138 * Abbreviations:: Abbreviations for common commands
139 * Actions:: Changing case, Padding, End checking
140 * Doc Header:: Inserting a standard header
141 * Motion Commands:: Moving through the structure of a program
142 * Misc Options:: Things that fit nowhere else
146 * Code Indentation:: Reflecting the logical structure
147 * Continued Statement Indentation::
148 * Comment Indentation:: Special indentation for comment lines
149 * Continuation Lines:: Splitting statements over lines
150 * Syntax Highlighting:: Font-lock support
151 * Octals and Highlighting:: Why "123 causes problems
155 * Case of Completed Words:: CaseOFcomPletedWords
156 * Object Method Completion and Class Ambiguity:: obj->Method, what?
157 * Class and Keyword Inheritance:: obj->Method, _EXTRA=e
158 * Structure Tag Completion:: Completing state.Tag
162 * Block Boundary Check:: Is the END correct
163 * Padding Operators:: Enforcing space around `=' etc
164 * Case Changes:: Enforcing upper case keywords
168 * Starting the Shell:: How to launch IDL as a subprocess
169 * Using the Shell:: Interactively working with the Shell
170 * Debugging IDL Programs:: Compilation/Debugging
171 * Examining Variables::
172 * Custom Expression Examination::
174 Debugging IDL Programs
176 * Compiling Programs:: Compiling buffers under the shell
177 * Breakpoints and Stepping:: Deciding where to stop and look
178 * Walking the Calling Stack:: From where was this routine called?
182 * Installing IDLWAVE:: How to install the distribution
183 * Installing Online Help:: Where to get the additional files needed
184 * Upgrading from idl.el:: Necessary configuration changes
186 Sources of Routine Info
188 * Routine Definitions:: Where IDL Routines are defined.
189 * Routine Information Sources:: So how does IDLWAVE know about...
190 * Library Catalog:: Scanning the Libraries for Routine Info
191 * Load-Path Shadows:: Routines defined in several places
192 * Documentation Scan:: Scanning the IDL Manuals
197 @node Introduction, IDLWAVE in a Nutshell, Top, Top
198 @chapter Introduction
200 @cindex CORBA (Common Object Request Broker Architecture)
201 @cindex Interface Definition Language
202 @cindex Interactive Data Language
204 @cindex @file{idl.el}
205 @cindex @file{idl-shell.el}
206 @cindex Feature overview
208 IDLWAVE is a package which supports editing source files for the
209 Interactive Data Language (IDL@footnote{IDL is a registered trademark of
210 Research Systems, Inc., a Kodak Company}), and for running IDL as an
211 inferior shell@footnote{Note that this package has nothing to do with
212 the Interface Definition Language, part of the Common Object Request
213 Broker Architecture (CORBA)}. It can also be used for editing source
214 files for the related WAVE/CL language, but with only limited
215 support. Note that this package has nothing to do with the Interface
216 Definition Language, part of the Common Object Request Broker
217 Architecture (CORBA).
219 IDLWAVE consists of two main parts: a major mode for editing IDL source
220 files files (@code{idlwave-mode}) and a mode for running the IDL program
221 as an inferior shell (@code{idlwave-shell-mode}). Although one mode can
222 be used without the other, both work together closely to form a complete
223 development environment. Here is a brief summary of what IDLWAVE does:
227 Code indentation and formatting.
229 Three level syntax highlighting support.
231 Context-sensitive display of calling sequences and keywords for more
232 than 1000 native IDL routines, extendible to any number of additional
233 routines in your local IDL libraries.
235 Name space conflict search, with likelihood ranking.
237 Fast, context-sensitive online help.
239 Context sensitive completion of routine names and keywords.
241 Easy insertion of code templates.
243 Automatic corrections to enforce a variety of customizable coding
246 Integrity checks and auto-termination of logical blocks.
248 Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs).
250 Documentation support.
252 Running IDL as an inferior Shell with history search, command line
253 editing and all the completion and routine info capabilities present in
256 Compilation, execution and interactive debugging of programs directly
257 from the source buffer.
259 Quick, source-guided navigation of the calling stack, with variable
262 Examining variables and expressions with a mouse click.
264 And much, much more...
269 Here are a number of screenshots showing IDLWAVE in action:
273 @uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer}
275 @uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed}
277 @uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.}
279 @uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed}
281 @uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code
282 stopped at a breakpoint}
286 IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el}
287 files written by Chris Chase. The modes and files had to be renamed
288 because of a name space conflict with CORBA's @code{idl-mode}, defined in
289 Emacs in the file @file{cc-mode.el}. If you have been using the old
290 files, check @ref{Upgrading from idl.el} for information on how to
293 In this manual, each section ends with a list of related user options.
294 Don't be confused by the sheer number of options available --- in most
295 cases the default settings are just fine. The variables are listed here
296 to make sure you know where to look if you want to change anything. For
297 a full description of what a particular variable does and how to
298 configure it, see the documentation string of that variable (available
299 with @kbd{C-h v}). Some configuration examples are also given in the
302 @node IDLWAVE in a Nutshell, Getting Started, Introduction, Top
303 @chapter IDLWAVE in a Nutshell
304 @cindex Summary of important commands
305 @cindex IDLWAVE in a Nutshell
306 @cindex Nutshell, IDLWAVE in a
308 @subheading Editing IDL Programs
310 @multitable @columnfractions .15 .85
312 @tab Indent the current line relative to context.
314 @tab Re-indent all lines in the current region.
315 @item @kbd{C-u @key{TAB}}
316 @tab Re-indent all lines in the current statement.
317 @item @kbd{M-@key{RET}}
318 @tab Start a continuation line, or split the current line at point.
320 @tab Fill the current comment paragraph.
322 @tab Display calling sequence and keywords for the procedure or function call
325 @tab Load context sensitive online help for nearby routine, keyword, etc.
326 @item @kbd{M-@key{TAB}}
327 @tab Complete a procedure name, function name or keyword in the buffer.
329 @tab Update IDLWAVE's knowledge about functions and procedures.
331 @tab Visit the source code of a procedure/function.
333 @tab Insert a standard documentation header.
334 @item @kbd{C-c @key{RET}}
335 @tab Insert a new timestamp and history item in the documentation header.
338 @subheading Running the IDLWAVE Shell, Debugging Programs
340 @multitable @columnfractions .15 .85
342 @tab Start IDL as a subprocess and/or switch to the interaction buffer.
344 @tab Cycle back through IDL command history.
347 @item @kbd{M-@key{TAB}}
348 @tab Complete a procedure name, function name or keyword in the shell buffer.
349 @item @kbd{C-c C-d C-c}
350 @tab Save and compile the source file in the current buffer.
351 @item @kbd{C-c C-d C-x}
352 @tab Goto next syntax error.
353 @item @kbd{C-c C-d C-b}
354 @tab Set a breakpoint at the nearest viable source line.
355 @item @kbd{C-c C-d C-d}
356 @tab Clear the nearest breakpoint.
357 @item @kbd{C-c C-d C-p}
358 @tab Print the value of the expression near point in IDL.
361 @subheading Commonly used Settings in @file{.emacs}
363 ;; Change the indentation preferences
364 (setq idlwave-main-block-indent 2 ; default 0
365 idlwave-block-indent 2 ; default 4
366 idlwave-end-offset -2) ; default -4
367 ;; Start autoloading routine info after 2 idle seconds
368 (setq idlwave-init-rinfo-when-idle-after 2)
369 ;; Pad some operators with spaces
370 (setq idlwave-do-actions t
371 idlwave-surround-by-blank t)
372 ;; Syntax Highlighting
373 (add-hook 'idlwave-mode-hook 'turn-on-font-lock)
374 ;; Automatically start the shell when needed
375 (setq idlwave-shell-automatic-start t)
376 ;; Bind debugging commands with CONTROL and SHIFT modifiers
377 (setq idlwave-shell-debug-modifiers '(control shift))
378 ;; Specify the online help files' location.
379 (setq idlwave-help-directory "~/.idlwave")
382 @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top
383 @chapter Getting Started (Tutorial)
386 @cindex Getting Started
389 * Lesson I -- Development Cycle::
390 * Lesson II -- Customization::
391 * Lesson III -- Library Catalog::
394 @node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started
395 @section Lesson I: Development Cycle
397 The purpose of this tutorial is to guide you through a very basic
398 development cycle using IDLWAVE. We will paste a simple program into a
399 buffer and use the shell to compile, debug and run it. On the way we
400 will use many of the important IDLWAVE commands. Note however that
401 there are many more capabilities in IDLWAVE than covered here, which can
402 be discovered by reading the entire manual.
404 It is assumed that you have access to Emacs or XEmacs with the full
405 IDLWAVE package including online help (@pxref{Installation}). We also
406 assume that you are familiar with Emacs and can read the nomenclature of
407 key presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL}
408 and @kbd{M} for @key{META} (often the @key{ALT} key carries this
411 Open a new source file by typing:
414 @kbd{C-x C-f tutorial.pro @key{RET}}
417 A buffer for this file will pop up, and it should be in IDLWAVE mode, as
418 shown in the mode line just below the editing window. Also, the menu
419 bar should contain entries @samp{IDLWAVE} and @samp{Debug}.
421 Now cut-and-paste the following code, also available as
422 @file{tutorial.pro} in the IDLWAVE distribution.
426 ;; compute a sequence number for a date
428 if y lt 100 then y = y+1900
429 if m le 2 then delta = 1 else delta = 0
430 m1 = m + delta*12 + 1
432 return, d + floor(m1*30.6)+floor(y1*365.25)+5
435 function weekday,day,month,year
436 ;; compute weekday number for date
437 nr = daynr(day,month,year)
441 pro plot_wday,day,month
442 ;; Plot the weekday of a date in the first 10 years of this century.
443 years = 2000,+indgen(10)
445 for i=0,n_elements(wdays)-1 do begin
446 wdays[i] = weekday(day,month,years[i])
448 plot,years,wdays,YS=2,YT="Wday (0=Sunday)"
452 The indentation probably looks funny, since it's different from the
453 settings you use, so use the @key{TAB} key in each line to automatically
454 line it up (or more quickly @emph{select} the entire buffer with
455 @kbd{C-x h}, and indent the whole region with @kbd{C-M-\}). Notice how
456 different syntactical elements are highlighted in different colors, if
457 you have set up support for font-lock.
459 Let's check out two particular editing features of IDLWAVE. Place the
460 cursor after the @code{end} statement of the @code{for} loop and press
461 @key{SPC}. IDLWAVE blinks back to the beginning of the block and
462 changes the generic @code{end} to the specific @code{endfor}
463 automatically. Now place the cursor in any line you would like to split
464 and press @kbd{M-@key{RET}}. The line is split at the cursor position,
465 with the continuation @samp{$} and indentation all taken care of. Use
466 @kbd{C-/} to undo the last change.
468 The procedure @code{plot_wday} is supposed to plot the weekday of a
469 given date for the first 10 years of the 21st century. As in most code,
470 there are a few bugs, which we are going to use IDLWAVE to help us fix.
472 First, let's launch the IDLWAVE shell. You do this with the command
473 @kbd{C-c C-s}. The Emacs window will split and display IDL running in a
474 shell interaction buffer. Type a few commands like @code{print,!PI} to
475 convince yourself that you can work there just as well as in a terminal,
476 or the IDLDE. Use the arrow keys to cycle through your command history.
477 Are we having fun now?
479 Now go back to the source window and type @kbd{C-c C-d C-c} to compile
480 the program. If you watch the shell buffer, you see that IDLWAVE types
481 @samp{.run tutorial.pro} for you. But the compilation fails because
482 there is a comma in the line @samp{years=...}. The line with the error
483 is highlighted and the cursor positioned at the error, so remove the
484 comma (you should only need to hit @kbd{Delete}!). Compile again, using
485 the same keystrokes as before. Notice that the file is automatically
486 saved for you. This time everything should work fine, and you should
487 see the three routines compile.
489 Now we want to use the command to plot the day of the week on January
490 1st. We could type the full command ourselves, but why do that? Go
491 back to the shell window, type @samp{plot_} and hit @key{TAB}. After a
492 bit of a delay (while IDLWAVE initializes its routine info database, if
493 necessary), the window will split to show all procedures it knows
494 starting with that string, and @w{@code{plot_wday}} should be one of
495 them. Saving the buffer alerted IDLWAVE about this new routine. Click
496 with the middle mouse button on @code{plot_wday} and it will be copied
497 to the shell buffer, or if you prefer, add @samp{w} to @samp{plot_} to
498 make it unambiguous, hit @key{TAB} again, and the full routine name will
499 be completed. Now provide the two arguments:
505 and press @key{RET}. This fails with an error message telling you the
506 @code{YT} keyword to plot is ambiguous. What are the allowed keywords
507 again? Go back to the source window and put the cursor into the `plot'
508 line, and press @kbd{C-c ?}. This shows the routine info window for the
509 plot routine, which contains a list of keywords, along with the argument
510 list. Oh, we wanted @code{YTITLE}. Fix that up. Recompile with
511 @kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press
512 the @key{UP} arrow to recall the previous command and execute again.
514 This time we get a plot, but it is pretty ugly --- the points are all
515 connected with a line. Hmm, isn't there a way for @code{plot} to use
516 symbols instead? What was that keyword? Position the cursor on the
517 plot line after a comma (where you'd normally type a keyword), and hit
518 @kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, there
519 it is, @code{PSYM}. Middle click to insert it. An @samp{=} sign is
520 included for you too. Now what were the values of @code{PSYM} supposed
521 to be? With the cursor on or after the keyword, press @kbd{M-?} for
522 online help (alternatively, you could have right clicked on the colored
523 keyword itself in the completion list). The online help window will pop
524 up showing the documentation for the @code{PYSM} keyword. OK, let's use
525 diamonds=4. Fix this, recompile (you know the command by now: @kbd{C-c
526 C-d C-c}, go back to the shell (if it's vanished, you know the command
527 to recall it by now: @kbd{C-c C-s}) and execute again. Now things look
530 Let's try a different day --- how about April fool's day?
536 Oops, this looks very wrong. All April fool's days cannot be Fridays!
537 We've got a bug in the program, perhaps in the @code{daynr} function.
538 Let's put a breakpoint on the last line there. Position the cursor on
539 the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a
540 breakpoint (as you see in the shell window), and the line is highlighted
541 in some way. Back to the shell buffer, re-execute the previous command.
542 IDL stops at the line with the breakpoint. Now hold down the SHIFT key
543 and click with the middle mouse button on a few variables there:
544 @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't the
545 correct type. CONTROL-SHIFT middle-click on it for help. Well, it's an
546 integer, so that's not the problem. Aha, @samp{y1} is zero, but it
547 should be the year, depending on delta. Shift click @samp{delta} to see
548 that it's 0. Below, we see the offending line: @samp{y1=y*delta...} the
549 multiplication should have been a minus sign! So fix the line to read:
555 Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the
556 command. Everything should now work fine. How about those leap years?
557 Change the code to plot 100 years and see that every 28 years, the
558 sequence of weekdays repeats.
560 @node Lesson II -- Customization, Lesson III -- Library Catalog, Lesson I -- Development Cycle, Getting Started
561 @section Lesson II: Customization
563 Emacs is probably the most customizable piece of software available, and
564 it would be a shame if you did not make use of this and adapt IDLWAVE to
565 your own preferences. Customizing Emacs or IDLWAVE is accomplished by
566 setting Lisp variables in the @file{.emacs} file in your home directory
567 --- but do not be dismayed; for the most part, you can just copy and work
568 from the examples given here.
570 Let's first use a boolean variable. These are variables which you turn
571 on or off, much like a checkbox. A value of @samp{t} means on, a value
572 of @samp{nil} means off. Copy the following line into your
573 @file{.emacs} file, exit and restart Emacs.
576 (setq idlwave-reserved-word-upcase t)
579 When this option is turned on, each reserved word you type into an IDL
580 source buffer will be converted to upper case when you press @key{SPC}
581 or @key{RET} right after the word. Try it out! @samp{if} changes to
582 @samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this
583 behavior, remove the option again from your @file{.emacs} file.
585 You likely have your own indentation preferences for IDL code. For
586 example, some like to indent the main block of an IDL program from the
587 margin, different from the conventions used by RSI, and use only 3
588 spaces as indentation between @code{BEGIN} and @code{END}. Try the
589 following lines in @file{.emacs}:
592 (setq idlwave-main-block-indent 2)
593 (setq idlwave-block-indent 3)
594 (setq idlwave-end-offset -3)
597 Restart Emacs, and re-indent the program we developed in the first part
598 of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep
599 these lines in @file{.emacs}, with values adjusted to your likings. If
600 you want to get more information about any of these variables, type,
601 e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which
602 variables can be customized, look for items marked @samp{User Option:}
603 throughout this manual.
605 If you cannot seem to master this Lisp customization in @file{.emacs},
606 there is another, more user-friendly way to customize all the IDLWAVE
607 variables. You can access it through the IDLWAVE menu in one of the
608 @file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE
609 Group}. Here you'll be presented with all the various variables grouped
610 into categories. You can navigate the hierarchy (e.g. Idlwave Code
611 Formatting->Idlwave Main Block Indent), read about the variables, change
612 them, and `Save for Future Sessions'. Few of these variables need
613 customization, but you can exercise considerable control over IDLWAVE's
614 functionality with them.
616 You may also find the key bindings used for the debugging commands too
617 long and complicated. Often we have heard such complaints, ``Do I
618 really have to type @kbd{C-c C-d C-c} to run a simple command?'' Due to
619 Emacs rules and conventions, shorter bindings cannot be set by default,
620 but you can enable them. First, there is a way to assign all debugging
621 commands in a single sweep to other combinations. The only problem is
622 that we have to use something which Emacs does not need for other
623 important commands. One good option is to execute debugging commands by
624 holding down @key{CONTROL} and @key{SHIFT} while pressing a single
625 character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for
626 compiling the current source file, @kbd{C-S-a} for deleting all
627 breakpoints. You can enable this with:
630 (setq idlwave-shell-debug-modifiers '(shift control))
633 @noindent If you have a special keyboard with, for example, a
634 @key{HYPER} key, you could even shorten that:
637 (setq idlwave-shell-debug-modifiers '(hyper))
640 @noindent to get compilation on @kbd{H-c}. Often, a modifier key like
641 @key{HYPER} or @key{SUPER} is bound or can be bound to an otherwise
642 unused key -- consult your system documentation.
644 You can also assign specific commands to keys. This you must do in the
645 @emph{mode-hook}, a special function which is run when a new buffer gets
646 set up. Keybindings can only be done when the buffer exists. The
647 possibilities for key customization are endless. Here we set function
648 keys f5-f8 to common debugging commands.
651 ;; First for the source buffer
652 (add-hook 'idlwave-mode-hook
654 (local-set-key [f5] 'idlwave-shell-break-here)
655 (local-set-key [f6] 'idlwave-shell-clear-current-bp)
656 (local-set-key [f7] 'idlwave-shell-cont)
657 (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
658 ;; Then for the shell buffer
659 (add-hook 'idlwave-shell-mode-hook
661 (local-set-key [f5] 'idlwave-shell-break-here)
662 (local-set-key [f6] 'idlwave-shell-clear-current-bp)
663 (local-set-key [f7] 'idlwave-shell-cont)
664 (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
667 @node Lesson III -- Library Catalog, , Lesson II -- Customization, Getting Started
668 @section Lesson III: Library Catalog
670 We have already used the routine info display in the first part of this
671 tutorial. This was the key @kbd{C-c ?} which displays information about
672 the IDL routine near the cursor position. Wouldn't it be nice
673 to have the same available for your own library routines and for the
674 huge amount of code in major extension libraries like JHUPL or the
675 IDL-Astro library? To do this, you must give IDLWAVE a chance to study
676 these routines first. We call this @emph{Building the library catalog}.
678 From the IDLWAVE entry in the menu bar, select @code{Routine Info/Select
679 Catalog Directories}. If necessary, start the shell first with @kbd{C-c
680 C-s} (@pxref{Starting the Shell}). IDLWAVE will find out about the IDL
681 @code{!PATH} variable and offer a list of directories on the path.
682 Simply select them all (or whichever you want) and click on the
683 @samp{Scan&Save} button. Then go for a cup of coffee while IDLWAVE
684 collects information for each and every IDL routine on your search path.
685 All this information is written to the file @file{.idlcat} in your home
686 directory and will from now one be automatically loaded whenever you use
687 IDLWAVE. You may find it necessary to rebuild the catalog on occasion
688 as your local libraries change. Try to use routine info (@kbd{C-c ?})
689 or completion (@kbd{M-@key{TAB}}) while on any routine or partial routine
690 name you know to be located in the library. E.g., if you have scanned
691 the IDL-Astro library:
698 expands to `readfits('. Then try
701 a=readfits(@key{C-c ?}
707 Usage: Result = READFITS(filename, header, heap)
711 I hope you made it until here. Now you are set to work with IDLWAVE.
712 On the way you will want to change other things, and to learn more about
713 the possibilities not discussed in this short tutorial. Read the
714 manual, look at the documentation strings of interesting variables (with
715 @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining
716 questions on the newsgroup @code{comp.lang.idl-pvwave}.
718 @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top
719 @chapter The IDLWAVE Major Mode
720 @cindex IDLWAVE major mode
721 @cindex Major mode, @code{idlwave-mode}
723 The IDLWAVE major mode supports editing IDL source files. In this
724 chapter we describe the main features of the mode and how to customize
728 * Code Formatting:: Making code look nice
729 * Routine Info:: Calling Sequence and Keyword List
730 * Online Help:: One key press from source to help
731 * Completion:: Completing routine names and Keywords
732 * Routine Source:: Finding routines, the easy way
733 * Resolving Routines:: Force the Shell to compile a routine
734 * Code Templates:: Frequent code constructs
735 * Abbreviations:: Abbreviations for common commands
736 * Actions:: Changing case, Padding, End checking
737 * Doc Header:: Inserting a standard header
738 * Motion Commands:: Moving through the structure of a program
739 * Misc Options:: Things that fit nowhere else
742 @node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode
743 @section Code Formatting
744 @cindex Code formatting
745 @cindex Formatting, of code
748 * Code Indentation:: Reflecting the logical structure
749 * Continued Statement Indentation::
750 * Comment Indentation:: Special indentation for comment lines
751 * Continuation Lines:: Splitting statements over lines
752 * Syntax Highlighting:: Font-lock support
753 * Octals and Highlighting:: Why "123 causes problems
756 The IDL language, with it's early roots in FORTRAN, modern
757 implementation in C, and liberal borrowing of features of many vector
758 languages along its 25+ year history, has inherited an unusual mix of
759 syntax elements. Left to his or her own devices, a novice IDL
760 programmer will often conjure code which is very difficult to read and
761 impossible to adapt. Much can be gleaned from studying available IDL
762 code libraries for coding style pointers, but, due to the variety of IDL
763 syntax elements, replicating this style can be challenging at best.
764 Luckily, IDLWAVE understands the structure IDL code very well, and takes
765 care of almost all formatting issues for you. After configuring it to
766 match your coding standards, you can rely on it to help keep your code
769 @cindex Foreign code, adapting
770 @cindex Indentation, of foreign code
772 To re-indent a larger portion of code (e.g. when working with foreign code
773 written with different conventions), use @kbd{C-M-\}
774 (@code{indent-region}) after marking the relevant code. Useful marking
775 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the
776 current subprogram). @xref{Actions}, for information how to impose
777 additional formatting conventions on foreign code.
779 @node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting
780 @subsection Code Indentation
781 @cindex Code indentation
784 Like all Emacs programming modes, IDLWAVE performs code indentation.
785 The @key{TAB} key indents the current line relative to context.
786 @key{LFD} insert a newline and indents the new line. The indentation is
787 governed by a number of variables. IDLWAVE indents blocks (between
788 @code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and
791 @defopt idlwave-main-block-indent (@code{0})
792 Extra indentation for the main block of code. That is the block between
793 the FUNCTION/PRO statement and the END statement for that program
797 @defopt idlwave-block-indent (@code{4})
798 Extra indentation applied to block lines. If you change this, you
799 probably also want to change @code{idlwave-end-offset}.
802 @defopt idlwave-end-offset (@code{-4})
803 Extra indentation applied to block END lines. A value equal to negative
804 @code{idlwave-block-indent} will make END lines line up with the block
808 @node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting
809 @subsection Continued Statement Indentation
810 @cindex Indentation, continued statement
811 @cindex Continued statement indentation
812 Continuation lines (following a line ending with @code{$}) can receive a
813 fixed indentation offset from the main level, but in several situations
814 IDLWAVE can use a special form of indentation which aligns continued
815 statements more naturally. Special indentation is calculated for
816 continued routine definition statements and calls, enclosing parentheses
817 (like function calls, structure/class definitions, explicit structures
818 or lists, etc.), and continued assignments. An attempt is made to line
819 up with the first non-whitespace character after the relevant opening
820 punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}). For
821 lines without any non-comment characters on the line with the opening
822 punctuation, the continued line(s) are aligned just past the
823 punctuation. An example:
826 function foo, a, b, $
834 The only drawback to this special continued statement indentation is
835 that it consumes more space, e.g., for long function names or left hand
836 sides of an assignment:
839 function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $
843 You can instruct IDLWAVE when to use this special continuation
844 indentation by setting the variable
845 @code{idlwave-max-extra-continuation-indent}, which specifies the
846 maximum additional indentation beyond the basic indent to be tolerated,
847 otherwise defaulting to fixed-offset from the enclosing indent (the size
848 of which offset is set in @code{idlwave-continuation-indent}). Also,
849 since the indentation level is somewhat dynamic in continued statements
850 with special continuation indentation, especially if
851 @code{idlwave-max-extra-continuation-indent} is small, the key @kbd{C-u
852 @key{TAB}} will re-indent all lines in the current statement. Note that
853 @code{idlwave-indent-to-open-paren}, if non-nil, overrides the
854 @code{idlwave-max-extra-continuation-indent} limit, for parentheses
855 only, forcing them always to line up.
858 @defopt idlwave-continuation-indent (@code{2})
859 Extra indentation applied to normal continuation lines.
862 @defopt idlwave-max-extra-continuation-indent (@code{20})
863 The maximum additional indentation (over the basic continuation-indent)
864 that will be permitted for special continues. To effectively disable
865 special continuation indentation, set to @code{0}. To enable it
866 constantly, set to a large number (like @code{100}). Note that the
867 indentation in a long continued statement never decreases from line to
868 line, outside of nested parentheses statements.
871 @defopt idlwave-indent-to-open-paren (@code{t})
872 Non-@code{nil} means indent continuation lines to innermost open
873 parenthesis, regardless of whether the
874 @code{idlwave-max-extra-continuation-indent} limit is satisfied.
877 @node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting
878 @subsection Comment Indentation
879 @cindex Comment indentation
880 @cindex Hanging paragraphs
881 @cindex Paragraphs, filling
882 @cindex Paragraphs, hanging
884 In IDL, lines starting with a @samp{;} are called @emph{comment lines}.
885 Comment lines are indented as follows:
887 @multitable @columnfractions .1 .90
889 @tab The indentation of lines starting with three semicolons remains
892 @tab Lines starting with two semicolons are indented like the surrounding code.
894 @tab Lines starting with a single semicolon are indent to a minimum column.
898 The indentation of comments starting in column 0 is never changed.
900 @defopt idlwave-no-change-comment
901 The indentation of a comment starting with this regexp will not be
905 @defopt idlwave-begin-line-comment
906 A comment anchored at the beginning of line.
909 @defopt idlwave-code-comment
910 A comment that starts with this regexp is indented as if it is a part of
914 @node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting
915 @subsection Continuation Lines and Filling
916 @cindex Continuation lines
917 @cindex Line splitting
918 @cindex String splitting
919 @cindex Splitting, of lines
922 In IDL, a newline character terminates a statement unless preceded by a
923 @samp{$}. If you would like to start a continuation line, use
924 @kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}.
925 It inserts the continuation character @samp{$}, terminates the line and
926 indents the new line. The command @kbd{M-@key{RET}} can also be invoked
927 inside a string to split it at that point, in which case the @samp{+}
928 concatenation operator is used.
931 @cindex @code{auto-fill-mode}
932 @cindex Hanging paragraphs
933 When filling comment paragraphs, IDLWAVE overloads the normal filling
934 functions and uses a function which creates the hanging paragraphs
935 customary in IDL routine headers. When @code{auto-fill-mode} is turned
936 on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the
937 first line of a paragraph contains a match for
938 @code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent
939 lines are positioned to line up after it, as in the following example.
943 ;=================================
944 ; x - an array containing
945 ; lots of interesting numbers.
947 ; y - another variable where
948 ; a hanging paragraph is used
950 ;=================================
955 You can also refill a comment at any time paragraph with @kbd{M-q}.
956 Comment delimiting lines as in the above example, consisting of one or
957 more @samp{;} followed by one or more of the characters @samp{+=-_*},
958 are kept in place, as is.
960 @defopt idlwave-fill-comment-line-only (@code{t})
961 Non-@code{nil} means auto fill will only operate on comment lines.
964 @defopt idlwave-auto-fill-split-string (@code{t})
965 Non-@code{nil} means auto fill will split strings with the IDL @samp{+}
969 @defopt idlwave-split-line-string (@code{t})
970 Non-@code{nil} means @code{idlwave-split-line} will split strings with
974 @defopt idlwave-hanging-indent (@code{t})
975 Non-@code{nil} means comment paragraphs are indented under the hanging
976 indent given by @code{idlwave-hang-indent-regexp} match in the first
977 line of the paragraph.
980 @defopt idlwave-hang-indent-regexp (@code{"- "})
981 Regular expression matching the position of the hanging indent
982 in the first line of a comment paragraph.
985 @defopt idlwave-use-last-hang-indent (@code{nil})
986 Non-@code{nil} means use last match on line for
987 @code{idlwave-indent-regexp}.
990 @node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting
991 @subsection Syntax Highlighting
992 @cindex Syntax highlighting
993 @cindex Highlighting of syntax
996 Highlighting of keywords, comments, strings etc. can be accomplished
997 with @code{font-lock}. If you are using @code{global-font-lock-mode}
998 (in Emacs), or have @code{font-lock} turned on in any other buffer in
999 XEmacs, it should also automatically work in IDLWAVE buffers. If you'd
1000 prefer invoking font-lock individually by mode, you can enforce it in
1001 @code{idlwave-mode} with the following line in your @file{.emacs}:
1004 (add-hook 'idlwave-mode-hook 'turn-on-font-lock)
1007 @noindent IDLWAVE supports 3 increasing levels of syntax highlighting.
1008 The variable @code{font-lock-maximum-decoration} determines which level
1009 is selected. Individual categories of special tokens can be selected
1010 for highlighting using the variable
1011 @code{idlwave-default-font-lock-items}.
1013 @defopt idlwave-default-font-lock-items
1014 Items which should be fontified on the default fontification level
1018 @node Octals and Highlighting, , Syntax Highlighting, Code Formatting
1019 @subsection Octals and Highlighting
1020 @cindex Syntax highlighting, Octals
1021 @cindex Highlighting of syntax, Octals
1023 A rare syntax highlighting problem results from the extremely
1024 unfortunate notation for octal numbers in IDL: @code{"123}. This
1025 unpaired quotation mark is very difficult to parse, given that it can be
1026 mixed on a single line with any number of strings. Emacs will
1027 incorrectly identify this as a string, and the highlighting of following
1028 lines of code can be distorted, since the string is never terminated.
1030 One solution to this involves terminating the mistakenly identified
1031 string yourself by providing a closing quotation mark in a comment:
1034 string("305B) + $ ;" <--- for font-lock
1038 @noindent A far better solution is to abandon this notation for octals
1039 altogether, and use the more sensible alternative IDL provides:
1042 string('305'OB) + ' is an Angstrom.'
1045 @noindent This simultaneously solves the font-lock problem and is more
1046 consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}.
1048 @node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode
1049 @section Routine Info
1050 @cindex Routine info
1051 @cindex Updating routine info
1052 @cindex Scanning buffers for routine info
1053 @cindex Buffers, scanning for routine info
1054 @cindex Shell, querying for routine info
1057 IDL comes bundled with more than one thousand procedures, functions and
1058 object methods, and large libraries typically contain hundreds or even
1059 thousands more. This large command set makes it difficult to remember
1060 the calling sequence and keywords for routines you use, but IDLWAVE can
1061 help. It builds up routine information using a wide variety of sources:
1062 IDLWAVE in fact knows far more about the routines on your system than
1063 IDL itself. It maintains a list of all built-in routines, with calling
1064 sequences and keywords@footnote{This list is created by scanning the IDL
1065 manuals and might contain (very few) errors. Please report any errors
1066 to the maintainer, so that they can be fixed.}. It also scans Emacs
1067 buffers and library files for routine definitions, and queries the
1068 IDLWAVE-Shell for information about routines currently compiled there.
1069 This information is updated automatically, and so should usually be
1070 current. To force a global update and refresh the routine information,
1071 use @kbd{C-c C-i} (@code{idlwave-update-routine-info}).
1074 To display the information about a routine, press @kbd{C-c ?}, which
1075 calls the command @code{idlwave-routine-info}. When the current cursor
1076 position is on the name or in the argument list of a procedure or
1077 function, information will be displayed about the routine. For example,
1078 consider the indicated cursor positions in the following line:
1081 plot,x,alog(x+5*sin(x) + 2),
1086 @cindex Default routine, for info and help
1087 On positions 1,2 and 8, information about the @samp{plot} procedure will
1088 be shown. On positions 3,4, and 7, the @samp{alog} function will be
1089 described, while positions 5 and 6 will investigate the @samp{sin}
1092 When you ask for routine information about an object method, and the
1093 method exists in several classes, IDLWAVE queries for the class of the
1094 object, unless the class is already known through a text property on the
1095 @samp{->} operator (@pxref{Object Method Completion and Class
1096 Ambiguity}), or by having been explicity included in the call
1097 (e.g. @code{a->myclass::Foo}).
1099 @cindex Calling sequences
1100 @cindex Keywords of a routine
1101 @cindex Routine source information
1102 The description displayed contains the calling sequence, the list of
1103 keywords and the source location of this routine. It looks like this:
1106 Usage: XMANAGER, NAME, ID
1107 Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER
1108 JUST_REG MODAL NO_BLOCK
1109 Source: SystemLib [CSB] /soft1/idl53/lib/xmanager.pro
1112 @cindex Categories, of routines
1113 @cindex Load-path shadows
1114 @cindex Shadows, load-path
1115 @cindex IDL variable @code{!PATH}
1116 @cindex @code{!PATH}, IDL variable
1117 @cindex IDL variable @code{!DIR}
1118 @cindex @code{!DIR}, IDL variable
1120 If a definition of this routine exists in several files accessible to
1121 IDLWAVE, several @samp{Source} lines will point to the different files.
1122 This may indicate that your routine is shadowing a library routine,
1123 which may or may not be what you want (@pxref{Load-Path Shadows}). The
1124 information about the calling sequence and keywords is derived from the
1125 first source listed. Library routines are supported only if you have
1126 scanned your local IDL libraries (@pxref{Library Catalog}). The source
1127 entry consists of a @emph{source category}, a set of @emph{flags} and
1128 the path to the @emph{source file}. The following categories exist:
1130 @multitable @columnfractions .15 .85
1132 @tab A system routine of unknown origin. When the system library has
1133 been scanned (@pxref{Library Catalog}), this category will automatically
1134 split into the next two.
1136 @tab A builtin system routine with no source code available.
1138 @tab A library system routine in the official lib directory @file{!DIR/lib}.
1140 @tab A library routine in the official lib directory @file{!DIR/lib/obsolete}.
1142 @tab A routine in a file on IDL's search path @code{!PATH}.
1144 @tab Any other routine with a file not known to be on the search path.
1145 @item @i{Unresolved}
1146 @tab An otherwise unkown routine the shell lists as unresolved
1147 (referenced, but not compiled).
1150 You can create additional categories based on the routine's filepath
1151 with the variable @code{idlwave-special-lib-alist}. This is useful for
1152 easy discrimination of various libraries, or even versions of the same
1155 @cindex Flags, in routine info
1156 @cindex Duplicate routines
1157 @cindex Multiply defined routines
1158 @cindex Routine definitions, multiple
1159 The flags @code{[CSB]} indicate the source of the information IDLWAVE
1160 has regarding the file: from a library catalog (@w{@code{[C--]}},
1161 @pxref{Library Catalog}), from the IDL Shell (@w{@code{[-S-]}}) or from
1162 an Emacs buffer (@w{@code{[--B]}}). Combinations are possible (a
1163 compiled library routine visited in a buffer might read
1164 @w{@code{[CSB]}}). If a file contains multiple definitions of the same
1165 routine, the file name will be prefixed with @samp{(Nx)} where @samp{N}
1166 is the number of definitions.
1168 @cindex Online Help from the routine info buffer
1169 @cindex Active text, in routine info
1170 @cindex Inserting keywords, from routine info
1171 @cindex Source file, access from routine info
1172 Some of the text in the @file{*Help*} routine info buffer will be active
1173 (it is highlighted when the mouse moves over it). Typically, clicking
1174 with the right mouse button invokes online help lookup, and clicking
1175 with the middle mouse button inserts keywords or visits files:
1177 @multitable @columnfractions 0.15 0.85
1179 @tab If online help is installed, a click with the @emph{right} mouse
1180 button on the @i{Usage:} line will access the help for the
1181 routine (@pxref{Online Help}).
1183 @tab Online help about keywords is also available with the
1184 @emph{right} mouse button. Clicking on a keyword with the @emph{middle}
1185 mouse button will insert this keyword in the buffer from where
1186 @code{idlwave-routine-info} was called. Holding down @key{SHIFT} while
1187 clicking also adds the initial @samp{/}.
1189 @tab Clicking with the @emph{middle} mouse button on a @samp{Source} line
1190 finds the source file of the routine and visits it in another window.
1191 Another click on the same line switches back to the buffer from which
1192 @kbd{C-c ?} was called. If you use the @emph{right} mouse button, the
1193 source will not be visited by a buffer, but displayed in the online help
1196 @tab The @i{Classes} line is only included in the routine info window if
1197 the current class inherits from other classes. You can click with the
1198 @emph{middle} mouse button to display routine info about the current
1199 method in other classes on the inheritance chain, if such a method
1203 @defopt idlwave-resize-routine-help-window (@code{t})
1204 Non-@code{nil} means resize the Routine-info @file{*Help*} window to
1208 @defopt idlwave-special-lib-alist
1209 Alist of regular expressions matching special library directories.
1212 @defopt idlwave-rinfo-max-source-lines (@code{5})
1213 Maximum number of source files displayed in the Routine Info window.
1217 @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode
1218 @section Online Help
1221 @cindex @file{idlw-help.txt}
1222 @cindex @file{idlw-help.el}
1223 @cindex IDL manual, ASCII version
1224 @cindex Installing online help
1225 @cindex Online Help, Installation
1226 @cindex Speed, of online help
1227 For IDL system routines, RSI provides extensive documentation. IDLWAVE
1228 can access an ASCII version of this documentation very quickly and
1229 accurately. This is @emph{much} faster than using the IDL online help
1230 application, because usually IDLWAVE gets you to the right place in the
1231 docs directly, without any additional browsing and scrolling. For this
1232 online help to work, an ASCII version of the IDL documentation, which is
1233 not part of the standalone IDLWAVE distribution, is required. The
1234 necessary help files can be downloaded from
1235 @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. The text
1236 extracted from the PDF files is fine for normal documentation
1237 paragraphs, but graphics and multiline equations will not be well
1238 formatted. See also @ref{Documentation Scan}.
1240 @cindex Updated online help
1241 @cindex Online help, updates
1242 @cindex @code{<NEW>..</NEW>}
1243 Occasionally RSI releases a synopsis of new features in an IDL release,
1244 without simultaneously updating the documentation files, instead
1245 preferring a @i{What's New} document which describes the changes. These
1246 updates are incorporated directly into the IDLWAVE online help, and are
1247 delimited in @code{<NEW>..</NEW>} blocks.
1249 @cindex Source code, as online help
1250 @cindex DocLib header, as online help
1251 For routines which are not documented in the IDL manual (for example
1252 your own routines), the source code is used as help text. If the
1253 requested information can be found in a (more or less) standard DocLib
1254 file header, IDLWAVE shows the header (scrolling down to appropriate
1255 keywords). Otherwise the routine definition statement
1256 (@code{pro}/@code{function}) is shown.
1259 In any IDL program (or, as with most IDLWAVE commands, in the IDL
1260 Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with
1261 @kbd{S-mouse-3} to access context sensitive online help. The following
1262 locations are recognized context for help:
1264 @cindex Context, for online help
1265 @multitable @columnfractions .25 .75
1266 @item @i{Routine name}
1267 @tab The name of a routine (function, procedure, method).
1268 @item @i{Keyword Parameter}
1269 @tab A keyword parameter of a routine.
1270 @item @i{System Variable}
1271 @tab System variables like @code{!DPI}.
1272 @item @i{IDL Statement}
1273 @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc.
1274 @item @i{Class name}
1275 @tab A class name in an @code{OBJ_NEW} call.
1276 @item @i{Class Init}
1277 @tab Beyond the class name in an @code{OBJ_NEW} call.
1278 @item @i{Executive Command}
1279 @tab An executive command like @code{.RUN}. Mostly useful in the shell.
1281 @tab The routine that would be selected for routine info display.
1284 @cindex @code{OBJ_NEW}, special online help
1285 Note that the @code{OBJ_NEW} function is special in that the help
1286 displayed depends on the cursor position: If the cursor is on the
1287 @samp{OBJ_NEW}, this function is described. If it is on the class name
1288 inside the quotes, the documentation for the class is pulled up. If the
1289 cursor is @emph{after} the class name, anywhere in the argument list,
1290 the documentation for the corresponding @code{Init} method and its
1291 keywords is targeted.
1293 @noindent Apart from source buffers, there are two more places from
1294 which online help can be accessed.
1298 Online help for routines and keywords can be accessed through the
1299 Routine Info display. Click with @kbd{mouse-3} on an item to see the
1300 corresponding help (@pxref{Routine Info}).
1302 When using completion and Emacs pops up a window with possible
1303 completions, clicking with @kbd{mouse-3} on a completion item invokes
1304 help on that item (@pxref{Completion}).
1307 In both cases, a blue face indicates that the item is documented in the
1308 IDL manual, but an attempt will be made to visit non-blue items directly
1309 in the originating source file.
1311 @cindex Help application, keybindings
1312 @cindex Keybindings, in help application
1313 The help window is normally displayed in a separate frame. The
1314 following commands can be used to navigate inside the help system:
1316 @multitable @columnfractions .15 .85
1317 @item @kbd{@key{SPACE}}
1318 @tab Scroll forward one page.
1319 @item @kbd{@key{RET}}
1320 @tab Scroll forward one line.
1321 @item @kbd{@key{DEL}}
1322 @tab Scroll back one page.
1324 @tab Browse to the next or previous topic (in physical sequence).
1326 @tab Move back and forward through the help topic history.
1328 @tab Clear the history.
1330 @tab Follow a link. Active links are displayed in a different font.
1331 Items under @i{See Also} are active, and classes have links to their
1334 @tab Open a topic. The topic can be selected with completion.
1336 @tab Load the whole help file into Emacs, for global text searches.
1338 @tab Kill the help window.
1342 @noindent When the help text is a source file, the following commands
1345 @multitable @columnfractions .15 .85
1347 @tab Jump to DocLib Header of the routine whose source is displayed
1350 @tab Jump to the first DocLib Header in the file.
1351 @item @kbd{.} @r{(Dot)}
1352 @tab Jump back and forth between the routine definition (the
1353 @code{pro}/@code{function} statement) and the description of the help
1354 item in the DocLib header.
1356 @tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}.
1359 @defopt idlwave-help-directory
1360 The directory where idlw-help.txt and idlw-help.el are stored.
1363 @defopt idlwave-help-use-dedicated-frame (@code{t})
1364 Non-@code{nil} means use a separate frame for Online Help if possible.
1367 @defopt idlwave-help-frame-parameters
1368 The frame parameters for the special Online Help frame.
1371 @defopt idlwave-max-popup-menu-items (@code{20})
1372 Maximum number of items per pane in popup menus.
1375 @defopt idlwave-extra-help-function
1376 Function to call for help if the normal help fails.
1379 @defopt idlwave-help-fontify-source-code (@code{nil})
1380 Non-@code{nil} means fontify source code displayed as help.
1383 @defopt idlwave-help-source-try-header (@code{t})
1384 Non-@code{nil} means try to find help in routine header when displaying source
1388 @defopt idlwave-help-link-face
1389 The face for links in IDLWAVE online help.
1392 @defopt idlwave-help-activate-links-aggressively (@code{t})
1393 Non-@code{nil} means make all possible links in help window active.
1396 @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode
1399 @cindex Keyword completion
1400 @cindex Method completion
1401 @cindex Object method completion
1402 @cindex Class name completion
1403 @cindex Function name completion
1404 @cindex Procedure name completion
1408 IDLWAVE offers completion for class names, routine names, keywords,
1409 system variables, class structure tags, regular structure tags and file
1410 names. As in many programming modes, completion is bound to
1411 @kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the IDLWAVE Shell ---
1412 @pxref{Using the Shell}). Completion uses exactly the same internal
1413 information as routine info, so when necessary (rarely) it can be
1414 updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}).
1416 The completion function is context sensitive and figures out what to
1417 complete based location of the point. Here are example lines and what
1418 @kbd{M-@key{TAB}} would try to complete when the cursor is on the
1419 position marked with a @samp{_}:
1424 plot,xra_ @r{Keyword of @code{plot} procedure}
1425 plot,x,y,/x_ @r{Keyword of @code{plot} procedure}
1426 plot,min(_ @r{Keyword of @code{min} function}
1427 obj -> a_ @r{Object method (procedure)}
1428 a(2,3) = obj -> a_ @r{Object method (function)}
1429 x = obj_new('IDL_ @r{Class name}
1430 x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}}
1431 pro A_ @r{Class name}
1432 pro _ @r{Fill in @code{Class::} of first method in this file}
1433 !v_ @r{System variable}
1434 !version.t_ @r{Structure tag of system variable}
1435 self.g_ @r{Class structure tag in methods}
1436 state.w_ @r{Structure tag, if tag completion enabled}
1437 name = 'a_ @r{File name (default inside quotes)}
1440 @cindex Completion, ambiguity
1441 @cindex Completion, forcing function name
1442 The only place where completion is ambiguous is procedure/function
1443 @emph{keywords} versus @emph{functions}. After @samp{plot,x_}, IDLWAVE
1444 will always assume a keyword to plot. You can force completion of a
1445 function name at such a location with a prefix arg: @kbd{C-u
1448 @cindex Scrolling the @file{*Completions*} window
1449 @cindex Completion, scrolling
1450 @cindex Completion, Online Help
1451 @cindex Online Help in @file{*Completions*} buffer
1452 If the list of completions is too long to fit in the
1453 @file{*Completions*} window, the window can be scrolled by pressing
1454 @kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each
1455 possible completion is available by clicking with @kbd{mouse-3} on the
1456 item. Items for which system online help (from the IDL manual) is
1457 available will be displayed in a different font (e.g. colored blue).
1458 For other items, the corresponding source code or DocLib header will be
1459 used as the help text.
1461 @defopt idlwave-keyword-completion-adds-equal (@code{t})
1462 Non-@code{nil} means completion automatically adds @samp{=} after
1466 @defopt idlwave-function-completion-adds-paren (@code{t})
1467 Non-@code{nil} means completion automatically adds @samp{(} after
1468 completed function. A value of `2' means also add the closing
1469 parenthesis and position the cursor between the two.
1472 @defopt idlwave-completion-restore-window-configuration (@code{t})
1473 Non-@code{nil} means restore window configuration after successful
1477 @defopt idlwave-highlight-help-links-in-completion (@code{t})
1478 Non-@code{nil} means highlight completions for which system help is
1483 * Case of Completed Words:: CaseOFcomPletedWords
1484 * Object Method Completion and Class Ambiguity:: obj->Method, what?
1485 * Class and Keyword Inheritance:: obj->Method, _EXTRA=e
1486 * Structure Tag Completion:: Completing state.Tag
1489 @node Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion
1490 @subsection Case of Completed Words
1491 @cindex Case of completed words
1492 @cindex Mixed case completion
1493 The case of the completed words is determined by what is already in the
1494 buffer. When the partial word being completed is all lower case, the
1495 completion will be lower case as well. If at least one character is
1496 upper case, the string will be completed in upper case or mixed case.
1497 The default is to use upper case for procedures, functions and keywords,
1498 and mixed case for object class names and methods, similar to the
1499 conventions in the IDL manuals. These defaults can be changed with the
1500 variable @code{idlwave-completion-case}. For instance, to enable
1501 mixed-case completion for routines in addition to classes and methods,
1502 you need an entry such as @code{routine . preserve} in that variable.
1503 To enable total control over the case of completed items, independent of
1504 buffer context, set @code{idlwave-completion-force-default-case} to
1507 @defopt idlwave-completion-case
1508 Association list setting the case (UPPER/lower/Capitalized/MixedCase...)
1512 @defopt idlwave-completion-force-default-case (@code{nil})
1513 Non-@code{nil} means completion will always honor the settings in
1514 @code{idlwave-completion-case}. When nil (the default), entirely lower
1515 case strings will always be completed to lower case, no matter what the
1516 settings in @code{idlwave-completion-case}.
1519 @defopt idlwave-complete-empty-string-as-lower-case (@code{nil})
1520 Non-@code{nil} means the empty string is considered lower case for
1524 @node Object Method Completion and Class Ambiguity, Class and Keyword Inheritance, Case of Completed Words, Completion
1525 @subsection Object Method Completion and Class Ambiguity
1526 @cindex Object methods
1527 @cindex Class ambiguity
1528 @cindex @code{self} object, default class
1529 An object method is not uniquely determined without the object's class.
1530 Since the class is almost always omitted in the calling source, IDLWAVE
1531 considers all available methods in all classes as possible method name
1532 completions. The combined list of keywords of the current method in
1533 @emph{all} known classes which contain that method will be considered
1534 for keyword completion. In the @file{*Completions*} buffer, the
1535 matching classes will be shown next to each item (see option
1536 @code{idlwave-completion-show-classes}). As a special case, the class
1537 of an object called @samp{self} is always taken to be the class of the
1538 current routine. All classes it inherits from are considered as well
1541 @cindex Forcing class query.
1542 @cindex Class query, forcing
1543 You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u
1544 M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to
1545 narrow down the number of possible completions. The variable
1546 @code{idlwave-query-class} can be configured to make such prompting the
1547 default for all methods (not recommended), or selectively for very
1548 common methods for which the number of completing keywords would be too
1549 large (e.g. @code{Init}). After you have specified the class for a
1550 particular statement (e.g. when completing the method), IDLWAVE can
1551 remember it for the rest of the editing session. Subsequent completions
1552 in the same statement (e.g. keywords) can then reuse this class
1553 information. This works by placing a text property on the method
1554 invocation operator @samp{->}, after which the operator will be shown in
1555 a different face. This is not enabled by default --- the variable
1556 @code{idlwave-store-inquired-class} can be used to turn it on.
1558 @defopt idlwave-completion-show-classes (@code{1})
1559 Non-@code{nil} means show classes in @file{*Completions*} buffer when
1560 completing object methods and keywords.
1563 @defopt idlwave-completion-fontify-classes (@code{t})
1564 Non-@code{nil} means fontify the classes in completions buffer.
1567 @defopt idlwave-query-class (@code{nil})
1568 Association list governing query for object classes during completion.
1571 @defopt idlwave-store-inquired-class (@code{nil})
1572 Non-@code{nil} means store class of a method call as text property on
1576 @defopt idlwave-class-arrow-face
1577 Face to highlight object operator arrows @samp{->} which carry a class
1581 @node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion and Class Ambiguity, Completion
1582 @subsection Class and Keyword Inheritance
1583 @cindex Inheritance, class
1584 @cindex Keyword inheritance
1585 @cindex Inheritance, keyword
1587 Class inheritance affects which methods are called in IDL. An object of
1588 a class which inherits methods from one or more superclasses can
1589 override that method by defining its own method of the same name, extend
1590 the method by calling the method(s) of its superclass(es) in its
1591 version, or inherit the method directly by making no modifications.
1592 IDLWAVE examines class definitions during completion and routine
1593 information display, and records all inheritance information it finds.
1594 This information is displayed if appropriate with the calling sequence
1595 for methods (@pxref{Routine Info}), as long as variable
1596 @code{idlwave-support-inheritance} is non-@code{nil}.
1598 In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and
1599 @code{_REF_EXTRA}) is used hand-in-hand with class inheritance and
1600 method overriding. E.g., in a @code{SetProperty} method, this technique
1601 allows a single call @code{obj->SetProperty} to set properties up the
1602 entire class inheritance chain. This is often referred to as
1603 @emph{chaining}, and is characterized by chained method calls like
1604 @w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}.
1606 IDLWAVE can accomodate this special synergy between class and keyword
1607 inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} are detected among a
1608 method's keyword parameters, all keywords of superclass versions of the
1609 method being considered are included in completion. The completion
1610 buffer will label keywords based on their originating class. The
1611 variable @code{idlwave-keyword-class-inheritance} can be used to
1612 configure which methods have keyword inheritance treated in this simple,
1613 class-driven way. By default, only @code{Init} and
1614 @code{(Get|Set)Property} are.
1616 @defopt idlwave-support-inheritance (@code{t})
1617 Non-@code{nil} means consider inheritance during completion, online help etc.
1620 @defopt idlwave-keyword-class-inheritance
1621 A list of regular expressions to match methods for which simple
1622 class-driven keyword inheritance will be used for Completion.
1625 @node Structure Tag Completion, , Class and Keyword Inheritance, Completion
1626 @subsection Structure Tag Completion
1627 @cindex Completion, structure tag
1628 @cindex Structure tag completion
1630 In many programs, especially those involving widgets, large structures
1631 (e.g. the @samp{state} structure) are used to communicate among
1632 routines. It is very convenient to be able to complete structure tags,
1633 in the same way as for instance variables of the @samp{self} object
1634 (@pxref{Object Method Completion and Class Ambiguity}). Add-in code for
1635 structure tag completion is available in the form of a loadable
1636 completion module: @file{idlw-complete-structtag.el}. Tag completion in
1637 structures is highly ambiguous (much more so than @samp{self}
1638 completion), so @code{idlw-complete-structtag} makes an unusual and
1639 specific assumption: the exact same variable name is used to refer to
1640 the structure in all parts of the program. So, if you consistently
1641 refer to the same structure with the same variable name
1642 (e.g. @samp{state}), structure tags which are read from its definition
1643 can be used for completion.
1645 Structure tag completion is not enabled by default. To enable it,
1646 simply add the following to your @file{.emacs}:
1649 (add-hook 'idlwave-load-hook
1650 (lambda () (require 'idlw-complete-structtag)))
1653 @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode
1654 @section Routine Source
1655 @cindex Routine source file
1656 @cindex Module source file
1657 @cindex Source file, of a routine
1659 In addition to clicking on a @i{Source:} line in the routine info
1660 window, there is another way to find the source file of a routine. The
1661 command @kbd{C-c C-v} (@code{idlwave-find-module}) asks for a module
1662 name, offering the same default as @code{idlwave-routine-info} would
1663 have used, taken from nearby buffer contents. In the minibuffer,
1664 specify a complete routine name (including any class part). IDLWAVE
1665 will display the source file in another window, positioned at the
1666 routine in question.
1668 @cindex Buffers, killing
1669 @cindex Killing autoloaded buffers
1670 Since getting the source of a routine into a buffer is so easy with
1671 IDLWAVE, too many buffers visiting different IDL source files are
1672 sometimes created. The special command @kbd{C-c C-k}
1673 (@code{idlwave-kill-autoloaded-buffers}) can be used to remove these
1676 @node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode
1677 @section Resolving Routines
1678 @cindex @code{RESOLVE_ROUTINE}
1679 @cindex Compiling library modules
1680 @cindex Routines, resolving
1682 The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve}
1683 and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL
1684 in order to resolve (compile) it. The default routine to be resolved is
1685 taken from context, but you get a chance to edit it.
1687 @code{idlwave-resolve} is one way to get a library module within reach
1688 of IDLWAVE's routine info collecting functions. A better way is to
1689 scan (parts of) the library (@pxref{Library Catalog}). Routine info on
1690 library modules will then be available without the need to compile the
1691 modules first, and even without a running shell.
1693 @xref{Sources of Routine Info}, for more information on the ways IDLWAVE
1694 collects data about routines, and how to update this information.
1696 @node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode
1697 @section Code Templates
1698 @cindex Code templates
1701 IDLWAVE can insert IDL code templates into the buffer. For a few
1702 templates, this is done with direct keybindings:
1704 @multitable @columnfractions .15 .85
1706 @tab @code{CASE} statement template
1708 @tab @code{FOR} loop template
1710 @tab @code{REPEAT} loop template
1712 @tab @code{WHILE} loop template
1715 All code templates are also available as abbreviations
1716 (@pxref{Abbreviations}).
1718 @node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode
1719 @section Abbreviations
1720 @cindex Abbreviations
1722 Special abbreviations exist to enable rapid entry of commonly used
1723 commands. Emacs abbreviations are expanded by typing text into the
1724 buffer and pressing @key{SPC} or @key{RET}. The special abbreviations
1725 used to insert code templates all start with a @samp{\} (the backslash),
1726 or, optionally, any other character set in
1727 @code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are
1728 only expanded where they should be (i.e., not in a string or comment),
1729 and permits the point to be moved after an abbreviation expansion ---
1730 very useful for positioning the mark inside of parentheses, etc.
1732 Special abbreviations are pre-defined for code templates and other
1733 useful items. To visit the full list of abbreviations, use @kbd{M-x
1734 idlwave-list-abbrevs}.
1736 Template abbreviations:
1738 @multitable @columnfractions .15 .85
1740 @tab @code{PROCEDURE} template
1742 @tab @code{FUNCTION} template
1744 @tab @code{CASE} statement template
1746 @tab @code{FOR} loop template
1748 @tab @code{REPEAT} loop template
1750 @tab @code{WHILE} loop template
1752 @tab @code{IF} statement template
1754 @tab @code{IF-ELSE} statement template
1757 String abbreviations:
1759 @multitable @columnfractions .15 .85
1761 @tab @code{arg_present()}
1767 @tab @code{complex()}
1769 @tab @code{double()}
1777 @tab @code{string()}
1789 @tab @code{endif else if}
1791 @tab @code{endif else}
1797 @tab @code{endswitch}
1799 @tab @code{endwhile}
1805 @tab @code{if keyword_set() then}
1807 @tab @code{if arg_present() then}
1809 @tab @code{if n_elements() eq 0 then}
1811 @tab @code{if n_elements() ne 0 then}
1813 @tab @code{keyword_set()}
1815 @tab @code{n_elements()}
1817 @tab @code{n_params()}
1819 @tab @code{on_ioerror,}
1841 @tab @code{strcompress()}
1843 @tab @code{strlowcase()}
1845 @tab @code{strmid()}
1847 @tab @code{strlen()}
1849 @tab @code{strpos()}
1851 @tab @code{strtrim()}
1853 @tab @code{strput()}
1855 @tab @code{strupcase()}
1861 @tab @code{widget_control,}
1863 @tab @code{widget_info()}
1868 @noindent You can easily add your own abbreviations or override existing
1869 abbrevs with @code{define-abbrev} in your mode hook using the
1870 convenience function @code{idlwave-define-abbrev}:
1873 (add-hook 'idlwave-mode-hook
1875 (idlwave-define-abbrev "wb" "widget_base()"
1876 (idlwave-keyword-abbrev 1))
1877 (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN"
1878 (idlwave-keyword-abbrev 11))))
1881 Notice how the abbreviation (here @emph{wb}) and its expansion
1882 (@emph{widget_base()}) are given as argument, and the single argument to
1883 @code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to
1884 move the point upon expansion (in this example, to put it between the
1887 The abbreviations are expanded in upper or lower case, depending upon
1888 the variables @code{idlwave-abbrev-change-case} and (for reserved word
1889 templates) @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}).
1891 @defopt idlwave-abbrev-start-char (@code{"\"})
1892 A single character string used to start abbreviations in abbrev
1896 @defopt idlwave-abbrev-move (@code{t})
1897 Non-@code{nil} means the abbrev hook can move point, e.g. to end up
1898 between the parenthesis of a function call.
1901 @node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode
1904 @cindex Coding standards, enforcing
1906 @emph{Actions} are special commands which are executed automatically
1907 while you write code in order to check the structure of the program or
1908 to enforce coding standards. Most actions which have been implemented
1909 in IDLWAVE are turned off by default, assuming that the average user
1910 wants her code the way she writes it. But if you are a lazy typist and
1911 want your code to adhere to certain standards, actions can be
1914 Actions can be applied in three ways:
1918 Some actions are applied directly while typing. For example, pressing
1919 @samp{=} can run a check to make sure that this operator is surrounded
1920 by spaces and insert these spaces if necessary. Pressing @key{SPC}
1921 after a reserved word can call a command to change the word to upper
1924 When a line is re-indented with @key{TAB}, actions can be applied to the
1925 entire line. To enable this, the variable @code{idlwave-do-actions}
1926 must be non-@code{nil}.
1928 @cindex Foreign code, adapting
1929 @cindex Actions, applied to foreign code
1930 Actions can also be applied to a larger piece of code, e.g. to convert
1931 foreign code to your own style. To do this, mark the relevant part of
1932 the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking
1933 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current
1934 subprogram). @xref{Code Indentation}, for information how to adjust the
1935 indentation of the code.
1938 @defopt idlwave-do-actions (@code{nil})
1939 Non-@code{nil} means performs actions when indenting.
1943 * Block Boundary Check:: Is the END correct
1944 * Padding Operators:: Enforcing space around `=' etc
1945 * Case Changes:: Enforcing upper case keywords
1948 @node Block Boundary Check, Padding Operators, Actions, Actions
1949 @subsection Block Boundary Check
1950 @cindex Block boundary check
1951 @cindex @code{END} type checking
1952 @cindex @code{END}, automatic insertion
1953 @cindex @code{END}, expanding
1954 @cindex Block, closing
1955 @cindex Closing a block
1957 Whenever you type an @code{END} statement, IDLWAVE finds the
1958 corresponding start of the block and the cursor blinks back to that
1959 location for a second. If you have typed a specific @code{END}, like
1960 @code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator
1961 does not match the type of block it terminates.
1963 Set the variable @code{idlwave-expand-generic-end} in order to have all
1964 generic @code{END} statements automatically expanded to the appropriate
1965 type. You can also type @kbd{C-c ]} to close the current block by
1966 inserting the appropriate @code{END} statement.
1968 @defopt idlwave-show-block (@code{t})
1969 Non-@code{nil} means point blinks to block beginning for
1970 @code{idlwave-show-begin}.
1973 @defopt idlwave-expand-generic-end (@code{t})
1974 Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc.
1977 @defopt idlwave-reindent-end (@code{t})
1978 Non-@code{nil} means re-indent line after END was typed.
1981 @node Padding Operators, Case Changes, Block Boundary Check, Actions
1982 @subsection Padding Operators
1983 @cindex Padding operators with spaces
1984 @cindex Operators, padding with spaces
1985 @cindex Space, around operators
1987 Some operators can be automatically surrounded by spaces. This can
1988 happen when the operator is typed, or later when the line is indented.
1989 IDLWAVE can pad the operators @samp{&}, @samp{<}, @samp{>}, @samp{,},
1990 @samp{=}, and @samp{->}, but this feature is turned off by default. If
1991 you want to turn it on, customize the variables
1992 @code{idlwave-surround-by-blank} and @code{idlwave-do-actions}. You can
1993 also define similar actions for other operators by using the function
1994 @code{idlwave-action-and-binding} in the mode hook. For example, to
1995 enforce space padding of the @samp{+} and @samp{*} operators, try this
1999 (add-hook 'idlwave-mode-hook
2001 (setq idlwave-surround-by-blank t) ; Turn this type of actions on
2002 (idlwave-action-and-binding "*" '(idlwave-surround 1 1))
2003 (idlwave-action-and-binding "+" '(idlwave-surround 1 1))))
2006 @defopt idlwave-surround-by-blank (@code{nil})
2007 Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil},
2008 @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are
2009 surrounded with spaces by @code{idlwave-surround}.
2012 @defopt idlwave-pad-keyword (@code{t})
2013 Non-@code{nil} means pad @samp{=} for keywords like assignments.
2016 @node Case Changes, , Padding Operators, Actions
2017 @subsection Case Changes
2018 @cindex Case changes
2019 @cindex Upcase, enforcing for reserved words
2020 @cindex Downcase, enforcing for reserved words
2022 Actions can be used to change the case of reserved words or expanded
2023 abbreviations by customizing the variables
2024 @code{idlwave-abbrev-change-case} and
2025 @code{idlwave-reserved-word-upcase}. If you want to change the case of
2026 additional words automatically, put something like the following into
2027 your @file{.emacs} file:
2030 (add-hook 'idlwave-mode-hook
2032 ;; Capitalize system vars
2033 (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t)
2034 ;; Capitalize procedure name
2035 (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"
2036 '(capitalize-word 1) t)
2037 ;; Capitalize common block name
2038 (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"
2039 '(capitalize-word 1) t)))
2042 For more information, see the documentation string for the function
2043 @code{idlwave-action-and-binding}. For information on controlling the
2044 case of routines, keywords, classes, and methods as they are completed, see
2047 @defopt idlwave-abbrev-change-case (@code{nil})
2048 Non-@code{nil} means all abbrevs will be forced to either upper or lower
2049 case. Legal values are @code{nil}, @code{t}, and @code{down}.
2052 @defopt idlwave-reserved-word-upcase (@code{nil})
2053 Non-@code{nil} means reserved words will be made upper case via abbrev
2058 @node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode
2059 @section Documentation Header
2060 @cindex Documentation header
2061 @cindex DocLib header
2062 @cindex Modification timestamp
2063 @cindex Header, for file documentation
2064 @cindex Timestamp, in doc header.
2065 @cindex Changelog, in doc header.
2069 The command @kbd{C-c C-h} inserts a standard routine header into the
2070 buffer, with the usual fields for documentation (a different header can
2071 be specified with @code{idlwave-file-header}). One of the keywords is
2072 @samp{MODIFICATION HISTORY} under which the changes to a routine can be
2073 recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION
2074 HISTORY} of the current routine or file and inserts the user name with a
2077 @defopt idlwave-file-header
2078 The doc-header template or a path to a file containing it.
2081 @defopt idlwave-header-to-beginning-of-file (@code{nil})
2082 Non-@code{nil} means the documentation header will always be at start
2086 @defopt idlwave-timestamp-hook
2087 The hook function used to update the timestamp of a function.
2090 @defopt idlwave-doc-modifications-keyword
2091 The modifications keyword to use with the log documentation commands.
2094 @defopt idlwave-doclib-start
2095 Regexp matching the start of a document library header.
2098 @defopt idlwave-doclib-end
2099 Regexp matching the start of a document library header.
2102 @node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode
2103 @section Motion Commands
2104 @cindex Motion commands
2105 @cindex Program structure, moving through
2106 @cindex Code structure, moving through
2107 @cindex @file{Func-menu}, XEmacs package
2108 @cindex @file{Imenu}, Emacs package
2109 @cindex Function definitions, jumping to
2110 @cindex Procedure definitions, jumping to
2112 IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages
2113 which make it easy to jump to the definitions of functions and
2114 procedures in the current file with a pop-up selection. To bind
2115 @file{Imenu} to a mouse-press, use in your @file{.emacs}:
2118 (define-key global-map [S-down-mouse-3] 'imenu)
2121 @cindex @file{Speedbar}, Emacs package
2123 In addition, @file{Speedbar} support allows convenient navigation of a
2124 source tree of IDL routine files, quickly stepping to routine
2125 definitions. See @code{Tools->Display Speedbar}.
2127 Several commands allow you to move quickly through the structure of an
2130 @multitable @columnfractions .15 .85
2132 @tab Beginning of subprogram
2134 @tab End of subprogram
2136 @tab Beginning of block (stay inside the block)
2138 @tab End of block (stay inside the block)
2140 @tab Forward block (on same level)
2142 @tab Backward block (on same level)
2144 @tab Down block (enters a block)
2146 @tab Backward up block (leaves a block)
2152 @node Misc Options, , Motion Commands, The IDLWAVE Major Mode
2153 @section Miscellaneous Options
2156 @defopt idlwave-help-application
2157 The external application providing reference help for programming.
2160 @defopt idlwave-startup-message (@code{t})
2161 Non-@code{nil} means display a startup message when @code{idlwave-mode}'
2165 @defopt idlwave-mode-hook
2166 Normal hook. Executed when a buffer is put into @code{idlwave-mode}.
2169 @defopt idlwave-load-hook
2170 Normal hook. Executed when @file{idlwave.el} is loaded.
2175 @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top
2176 @chapter The IDLWAVE Shell
2177 @cindex IDLWAVE shell
2178 @cindex Major mode, @code{idlwave-shell-mode}
2179 @cindex IDL, as Emacs subprocess
2180 @cindex Subprocess of Emacs, IDL
2181 @cindex Comint, Emacs package
2186 The IDLWAVE shell is an Emacs major mode which permits running the IDL
2187 program as an inferior process of Emacs, and works closely with the
2188 IDLWAVE major mode in buffers. It can be used to work with IDL
2189 interactively, to compile and run IDL programs in Emacs buffers and to
2190 debug these programs. The IDLWAVE shell is built upon @file{comint}, an
2191 Emacs packages which handles the communication with the IDL program.
2192 Unfortunately IDL for Windows and MacOS do not have command-prompt
2193 versions and thus do not allow the interaction with
2194 Emacs@footnote{Please inform the maintainer if you come up with a way to
2195 make the IDLWAVE shell work on these systems.} --- so the IDLWAVE shell
2196 currently only works under Unix.
2199 * Starting the Shell:: How to launch IDL as a subprocess
2200 * Using the Shell:: Interactively working with the Shell
2201 * Debugging IDL Programs:: Compilation/Debugging
2202 * Examining Variables::
2203 * Custom Expression Examination::
2206 @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell
2207 @section Starting the Shell
2208 @cindex Starting the shell
2209 @cindex Shell, starting
2210 @cindex Dedicated frame, for shell buffer
2211 @cindex Frame, for shell buffer
2212 @cindex Subprocess of Emacs, IDL
2215 The IDLWAVE shell can be started with the command @kbd{M-x
2216 idlwave-shell}. In @code{idlwave-mode} the function is bound to
2217 @kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to
2218 interact with the shell. If the shell is already running, @kbd{C-c C-s}
2219 will simple switch to the shell buffer. The command @kbd{C-c C-l}
2220 (@code{idlwave-shell-recenter-shell-window}) displays the shell window
2221 without selecting it. The shell can also be started automatically when
2222 another command tries to send a command to it. To enable auto start,
2223 set the variable @code{idlwave-shell-automatic-start} to @code{t}.
2225 In order to create a separate frame for the IDLWAVE shell buffer, call
2226 @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or
2227 @kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell
2228 window, configure the variable
2229 @code{idlwave-shell-use-dedicated-frame}.
2231 To launch a quick IDLWAVE shell directly from a shell prompt without an
2232 IDLWAVE buffer (e.g., as a replacement for running inside an xterm),
2233 define an alias with the following content:
2236 emacs -geometry 80x32 -eval "(idlwave-shell 'quick)"
2239 Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer
2240 the Emacs process to run directly inside the terminal window.
2242 @defopt idlwave-shell-explicit-file-name (@file{idl})
2243 This is the command to run IDL.
2246 @defopt idlwave-shell-command-line-options
2247 A list of command line options for calling the IDL program.
2250 @defopt idlwave-shell-prompt-pattern
2251 Regexp to match IDL prompt at beginning of a line.
2254 @defopt idlwave-shell-process-name
2255 Name to be associated with the IDL process.
2258 @defopt idlwave-shell-automatic-start (@code{nil})
2259 Non-@code{nil} means attempt to invoke idlwave-shell if not already
2263 @defopt idlwave-shell-initial-commands
2264 Initial commands, separated by newlines, to send to IDL.
2267 @defopt idlwave-shell-save-command-history (@code{t})
2268 Non-@code{nil} means preserve command history between sessions.
2271 @defopt idlwave-shell-command-history-file (@file{~/.idlwhist})
2272 The file in which the command history of the idlwave shell is saved.
2275 @defopt idlwave-shell-use-dedicated-frame (@code{nil})
2276 Non-@code{nil} means IDLWAVE should use a special frame to display
2280 @defopt idlwave-shell-frame-parameters
2281 The frame parameters for a dedicated idlwave-shell frame.
2284 @defopt idlwave-shell-raise-frame (@code{t})
2285 Non-@code{nil} means `idlwave-shell' raises the frame showing the shell
2289 @defopt idlwave-shell-temp-pro-prefix
2290 The prefix for temporary IDL files used when compiling regions.
2294 @defopt idlwave-shell-mode-hook
2295 Hook for customizing @code{idlwave-shell-mode}.
2298 @node Using the Shell, Debugging IDL Programs, Starting the Shell, The IDLWAVE Shell
2299 @section Using the Shell
2301 @cindex Shell, basic commands
2303 The IDLWAVE shell works in the same fashion as other shell modes in
2304 Emacs. It provides command history, command line editing and job
2305 control. The @key{UP} and @key{DOWN} arrows cycle through the input
2306 history just like in an X terminal@footnote{This is different from
2307 normal Emacs/Comint behavior, but more like an xterm. If you prefer the
2308 default comint functionality, check the variable
2309 @code{idlwave-shell-arrows-do-history}.}. The history is preserved
2310 between emacs and IDL sessions. Here is a list of commonly used
2313 @multitable @columnfractions .12 .88
2315 @tab Cycle backwards in input history
2317 @tab Cycle forwards in input history
2319 @tab Cycle backwards in input history @emph{matching input}
2321 @tab Cycle forwards in input history @emph{matching input}
2323 @tab Previous input matching a regexp
2325 @tab Next input that matches a regexp
2327 @tab Send input or copy line to current prompt
2329 @tab Beginning of line; skip prompt
2331 @tab Kill input to beginning of line
2333 @tab Kill word before cursor
2341 @tab Delete last batch of process output
2343 @tab Show last batch of process output
2345 @tab List input history
2348 In addition to these standard @file{comint} commands,
2349 @code{idlwave-shell-mode} provides many of the commands which simplify
2350 writing IDL code, including abbreviations, online help, and completion.
2351 See @ref{Routine Info} and @ref{Online Help} and @ref{Completion} for more
2352 information on these commands.
2354 @cindex Completion, in the shell
2355 @cindex Routine info, in the shell
2356 @cindex Online Help, in the shell
2357 @multitable @columnfractions .12 .88
2358 @item @kbd{@key{TAB}}
2359 @tab Completion of file names (between quotes and after executive
2360 commands @samp{.run} and @samp{.compile}), routine names, class names,
2361 keywords, system variables, system variable tags etc.
2362 (@code{idlwave-shell-complete}).
2363 @item @kbd{M-@key{TAB}}
2364 @tab Same as @key{TAB}
2366 @tab Routine Info display (@code{idlwave-routine-info})
2368 @tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp})
2370 @tab Update routine info from buffers and shell
2371 (@code{idlwave-update-routine-info})
2373 @tab Find the source file of a routine (@code{idlwave-find-module})
2375 @tab Compile a library routine (@code{idlwave-resolve})
2378 @defopt idlwave-shell-arrows-do-history (@code{t})
2379 Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command
2383 @defopt idlwave-shell-comint-settings
2384 Alist of special settings for the comint variables in the IDLWAVE Shell.
2387 @defopt idlwave-shell-file-name-chars
2388 The characters allowed in file names, as a string. Used for file name
2392 @defopt idlwave-shell-graphics-window-size
2393 Size of IDL graphics windows popped up by special IDLWAVE command.
2397 @cindex Character input mode (Shell)
2398 @cindex Line input mode (Shell)
2399 @cindex Magic spells, for input mode
2400 @cindex Spells, magic
2401 IDLWAVE works in line input mode: You compose a full command line, using
2402 all the power Emacs gives you to do this. When you press @key{RET}, the
2403 whole line is sent to IDL. Sometimes it is necessary to send single
2404 characters (without a newline), for example when an IDL program is
2405 waiting for single character input with the @code{GET_KBRD} function.
2406 You can send a single character to IDL with the command @kbd{C-c C-x}
2407 (@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y}
2408 (@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop
2409 which accepts characters and immediately sends them to IDL. The loop
2410 can be exited with @kbd{C-g}. It terminates also automatically when the
2411 current IDL command is finished. Check the documentation of the two
2412 variables described below for a way to make IDL programs trigger
2413 automatic switches of the input mode.
2415 @defopt idlwave-shell-use-input-mode-magic (@code{nil})
2416 Non-@code{nil} means IDLWAVE should check for input mode spells in
2420 @defopt idlwave-shell-input-mode-spells
2421 The three regular expressions which match the magic spells for input
2425 @node Debugging IDL Programs, Examining Variables, Using the Shell, The IDLWAVE Shell
2426 @section Debugging IDL Programs
2428 @cindex Keybindings for debugging
2432 Programs can be compiled, run, and debugged directly from the source
2433 buffer in Emacs. The IDLWAVE shell installs keybindings both in the
2434 shell buffer and in all IDL code buffers of the current Emacs session.
2435 On Emacs versions which support this, it also installs a debugging
2436 toolbar. The display of the toolbar can be toggled with @kbd{C-c C-d
2437 C-t} (@code{idlwave-shell-toggle-toolbar}).
2439 The debugging keybindings are by default on the prefix key @kbd{C-c
2440 C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d
2441 C-b}, compiling a source file with @kbd{C-c C-d C-c}. If you find this
2442 too much work, you can add bindings for one or more modifier keys which
2443 is not used by other commands. For example, if you write in
2447 (setq idlwave-shell-debug-modifiers '(control shift))
2450 @noindent a breakpoint can be set by pressing @kbd{b} while holding down
2451 @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a
2452 source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d},
2453 etc. In the remainder of this chapter we will assume that the @kbd{C-c
2454 C-d} bindings are active, but each of these bindings will have an
2455 equivalent single-keypress shortcut if modifiers are given in the
2456 @code{idlwave-shell-debug-modifiers} variable (see @pxref{Lesson II --
2459 @defopt idlwave-shell-prefix-key (@kbd{C-c C-d})
2460 The prefix key for the debugging map
2461 @code{idlwave-shell-mode-prefix-map}.
2464 @defopt idlwave-shell-activate-prefix-keybindings (@code{t})
2465 Non-@code{nil} means debug commands will be bound to the prefix
2466 key, like @kbd{C-c C-d C-b}.
2469 @defopt idlwave-shell-debug-modifiers (@code{nil})
2470 List of modifier keys to use for additional binding of debugging
2471 commands in the shell and source buffers.
2474 @defopt idlwave-shell-use-toolbar (@code{t})
2475 Non-@code{nil} means use the debugging toolbar in all IDL related
2481 * Compiling Programs:: Compiling buffers under the shell
2482 * Breakpoints and Stepping:: Deciding where to stop and look
2483 * Walking the Calling Stack:: From where was this routine called?
2486 @node Compiling Programs, Breakpoints and Stepping, Debugging IDL Programs, Debugging IDL Programs
2487 @subsection Compiling Programs
2488 @cindex Compiling programs
2489 @cindex Programs, compiling
2490 @cindex Default command line, executing
2491 @cindex Executing a default command line
2494 In order to compile the current buffer under the IDLWAVE shell, press
2495 @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the
2496 current buffer and then sends the command @samp{.run path/to/file} to the
2497 shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in
2498 which case the most recently compiled buffer will be saved and
2501 When developing or debugging a program, it is often necessary to execute
2502 the same command line many times. A convenient way to do this is
2503 @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}).
2504 This command first resets IDL from a state of interrupted execution by
2505 closing all files and returning to the main interpreter level. Then a
2506 default command line is send to the shell. To edit the default command
2507 line, call @code{idlwave-shell-execute-default-command-line} with a
2508 prefix argument: @kbd{C-u C-c C-d C-y}.
2510 @defopt idlwave-shell-mark-stop-line (@code{t})
2511 Non-@code{nil} means mark the source code line where IDL is currently
2512 stopped. The value specifies the preferred method. Legal values are
2513 @code{nil}, @code{t}, @code{arrow}, and @code{face}.
2516 @defopt idlwave-shell-overlay-arrow (@code{">"})
2517 The overlay arrow to display at source lines where execution halts, if
2518 configured in @code{idlwave-shell-mark-stop-line}.
2521 @defopt idlwave-shell-stop-line-face
2522 The face which highlights the source line where IDL is stopped, if
2523 configured in @code{idlwave-shell-mark-stop-line}.
2526 @node Breakpoints and Stepping, Walking the Calling Stack, Compiling Programs, Debugging IDL Programs
2527 @subsection Breakpoints and Stepping
2530 @cindex Execution, controlled
2534 You can set breakpoints and step through a program with IDLWAVE.
2535 Setting a breakpoint in the current line of the source buffer is done
2536 with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a prefix
2537 arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}, the breakpoint gets a @code{/ONCE}
2538 keyword, meaning that it will be deleted after first use. With a
2539 numeric prefix greater than one, the breakpoint will only be active the
2540 @code{nth} time it is hit. To clear the breakpoint in the current line,
2541 use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When executed
2542 from the shell window, the breakpoint where IDL is currently stopped
2543 will be deleted. To clear all breakpoints, use @kbd{C-c C-d C-a}
2544 (@code{idlwave-clear-all-bp}). Breakpoint lines are highlighted in the
2547 Once the program has stopped somewhere, you can step through it. The
2548 most important stepping commands are @kbd{C-c C-d C-s} to execute one
2549 line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line,
2550 treating procedure and function calls as a single step ("step over");
2551 @kbd{C-c C-d C-h} to continue execution to the line at the cursor and
2552 @kbd{C-c C-d C-r} to continue execution. Here is a summary of the
2553 breakpoint and stepping commands:
2555 @multitable @columnfractions .23 .77
2556 @item @kbd{C-c C-d C-b}
2557 @tab Set breakpoint (@code{idlwave-shell-break-here})
2558 @item @kbd{C-c C-d C-i}
2559 @tab Set breakpoint in function named here (@code{idlwave-shell-break-in})
2560 @item @kbd{C-c C-d C-d}
2561 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})
2562 @item @kbd{C-c C-d C-a}
2563 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})
2564 @item @kbd{C-c C-d C-s}
2565 @tab Step, into function calls (@code{idlwave-shell-step})
2566 @item @kbd{C-c C-d C-n}
2567 @tab Step, over function calls (@code{idlwave-shell-stepover})
2568 @item @kbd{C-c C-d C-k}
2569 @tab Skip one statement (@code{idlwave-shell-skip})
2570 @item @kbd{C-c C-d C-u}
2571 @tab Continue to end of block (@code{idlwave-shell-up})
2572 @item @kbd{C-c C-d C-m}
2573 @tab Continue to end of function (@code{idlwave-shell-return})
2574 @item @kbd{C-c C-d C-o}
2575 @tab Continue past end of function (@code{idlwave-shell-out})
2576 @item @kbd{C-c C-d C-h}
2577 @tab Continue to line at cursor position (@code{idlwave-shell-to-here})
2578 @item @kbd{C-c C-d C-r}
2579 @tab Continue execution to next breakpoint (@code{idlwave-shell-cont})
2580 @item @kbd{C-c C-d C-up}
2581 @tab Show higher level in calling stack (@code{idlwave-shell-stack-up})
2582 @item @kbd{C-c C-d C-down}
2583 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down})
2586 @defopt idlwave-shell-mark-breakpoints (@code{t})
2587 Non-@code{nil} means mark breakpoints in the source file buffers. The
2588 value indicates the preferred method. Legal values are @code{nil},
2589 @code{t}, @code{face}, and @code{glyph}.
2592 @defopt idlwave-shell-breakpoint-face
2593 The face for breakpoint lines in the source code if
2594 @code{idlwave-shell-mark-breakpoints} has the value @code{face}.
2597 @node Walking the Calling Stack, , Breakpoints and Stepping, Debugging IDL Programs
2598 @subsection Walking the Calling Stack
2599 @cindex Calling stack, walking
2601 While debugging a program, it can be very useful to check the context in
2602 which the current routine was called, for instance to help understand
2603 the value of the arguments passed. To do so conveniently you need to
2604 examine the calling stack. If execution is stopped somewhere deep in a
2605 program, you can use the commands @kbd{C-c C-d C-@key{UP}}
2606 (@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}}
2607 (@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons,
2608 to move up or down through the calling stack. The mode line of the
2609 shell window will indicate the position within the stack with a label
2610 like @samp{[-3:MYPRO]}. The line of IDL code at that stack position
2611 will be highlighted. If you continue execution, IDLWAVE will
2612 automatically return to the current level. @xref{Examining Variables},
2613 for information how to examine the value of variables and expressions on
2614 higher calling stack levels.
2616 @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell
2617 @section Examining Variables
2618 @cindex @code{PRINT} expressions
2619 @cindex @code{HELP}, on expressions
2620 @cindex Expressions, printing
2621 @cindex Expressions, help
2622 @cindex Printing expressions
2623 @cindex Mouse binding to print expressions
2626 Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)},
2627 and similar statements to remind yourself of the
2628 type/size/structure/value/etc. of variables and expressions in your code
2629 or at the command line? IDLWAVE has a suite of special commands to
2630 automate these types of variables or expression examinations. They work
2631 by sending statements to the shell formatted to include the indicated
2634 These examination commands can be used in the shell or buffer at any
2635 time (as long as the shell is running), and are very useful when
2636 execution is stopped in a buffer due to a triggered breakpoint or error,
2637 or while composing a long command in the IDLWAVE shell. In the latter
2638 case, the command is sent to the shell and its output is visible, but
2639 point remains unmoved in the command being composed --- you can inspect
2640 the contituents of a command you're building without interrupting the
2641 process of building it! You can even print arbitrary expressions from
2642 older input or output further up in the shell window --- any expression,
2643 variable, number, or function you see can be examined.
2645 If the variable @code{idlwave-shell-separate-examine-output} is
2646 non-@code{nil} (the default), all examine output will be sent to a
2647 special @file{*Examine*} buffer, rather than the shell. The output of
2648 prior examine commands is saved. In this buffer @key{c} clears the
2649 contents, and @key{q} hides the buffer.
2651 The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to
2652 print the expression at point, and @kbd{C-c C-d ?}, to invoke help on
2653 this expression. The expression at point is either an array expression
2654 or a function call, or the contents of a pair of parentheses. The
2655 selected expression is highlighted, and simultaneously the resulting
2656 output is highlighted in the shell. Calling the above commands with a
2657 prefix argument will prompt for an expression instead of using the one
2658 at point. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will use the
2659 current region as expression.
2661 For added speed and convenience, there are mouse bindings which allow
2662 you to click on expressions and examine their values. Use
2663 @kbd{S-mouse-2} to print an expression and @kbd{C-M-mouse-2} to invoke
2664 help (i.e. you need to hold down @key{META} and @key{CONTROL} while
2665 clicking with the middle mouse button). If you simply click, the
2666 nearest expression will be selected in the same manner as described
2667 above. You can also @emph{drag} the mouse in order to highlight exactly
2668 a specific expression or sub-expression to be examined. For custom
2669 expression examination, and the customizable pop-up examine selection,
2670 @xref{Custom Expression Examination}.
2672 @cindex Printing expressions, on calling stack
2673 @cindex Restrictions for expression printing
2674 The same variable inspection commands work both in the IDL Shell and
2675 IDLWAVE buffers, and even for variables at higher levels of the calling
2676 stack. For instance, if you're stopped at a breakpoint in a routine,
2677 you can examine the values of variables and expressions inside its
2678 calling routine, and so on, all the way up through the calling stack.
2679 Simply step up the stack, and print variables as you see them
2680 (@pxref{Walking the Calling Stack}, for information on stepping back
2681 through the calling stack). The following restrictions apply for all
2682 levels except the current:
2686 Array expressions must use the @samp{[ ]} index delimiters. Identifiers
2687 with a @samp{( )} will be interpreted as function calls.
2689 @cindex ROUTINE_NAMES, IDL procedure
2690 N.B.: printing values of expressions on higher levels of the calling
2691 stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES},
2692 which may or may not be available in future versions of IDL.
2695 @defopt idlwave-shell-expression-face
2696 The face for @code{idlwave-shell-expression-overlay}.
2697 Allows you to choose the font, color and other properties for
2698 the expression printed by IDL.
2701 @defopt idlwave-shell-output-face
2702 The face for @code{idlwave-shell-output-overlay}.
2703 Allows to choose the font, color and other properties for the most
2704 recent output of IDL when examining an expression."
2707 @defopt idlwave-shell-separate-examine-output (@code{t})
2708 If non-@code{nil}, re-direct the output of examine commands to a special
2709 @file{*Examine*} buffer, instead of in the shell itself.
2712 @node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell
2713 @section Custom Expression Examination
2714 @cindex Expressions, custom examination
2715 @cindex Custom expression examination
2717 The variety of possible variable and expression examination commands is
2718 endless (just look, for instance, at the keyword list to
2719 @code{widget_info()}). Rather than attempt to include them all, IDLWAVE
2720 provides two easy methods to customize your own commands, with a special
2721 mouse examine command, and two macros for generating your own examine
2724 The most powerful and flexible mouse examine command is available on
2725 @kbd{C-S-mouse-2}. Just as for all the other mouse examine commands, it
2726 permits click or drag expression selection, but instead of sending
2727 hard-coded commands to the shell, it pops-up a customizable selection
2728 list of examine functions to choose among, configured with the
2729 @code{idlwave-shell-examine-alist} variable. This variable is a list of
2730 key-value pairs (an @emph{alist} in Emacs parlance), where the keys name
2731 the command, and the values are the command strings, in which the text
2732 @code{___} (three underscores) will be replaced by the selected
2733 expression before being sent to the shell. An example might be key
2734 @code{Structure Help} with value @code{help,___,/STRUCTURE}.
2736 In addition to the popup mouse command, you can easily create your own
2737 customized bindings to inspect expressions using the two convenience
2738 macros @code{idlwave-shell-inspect} and
2739 @code{idlwave-shell-mouse-inspect}. These create keyboard or
2740 mouse-based custom inspections of variables, sharing all the same
2741 properties of the built-in examine commands. Both functions take a
2742 single string argument sharing the syntax of the
2743 @code{idlwave-shell-examine-alist} values, e.g.:
2746 (add-hook 'idlwave-shell-mode-hook
2748 (idlwave-shell-define-key-both [s-down-mouse-2]
2749 (idlwave-shell-mouse-examine
2750 "print, size(___,/DIMENSIONS)"))
2751 (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
2752 "print, size(___,/DIMENSIONS)"))
2753 (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
2754 "print,size(___,/TNAME)"))
2755 (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
2756 "help,___,/STRUCTURE"))))
2759 @noindent Now pressing @key{f9}, or middle-mouse dragging with the
2760 @key{SUPER} key depressed, will print the dimensions of the nearby or
2761 highlighted expression. Pressing @key{f10} will give the type string,
2762 and @key{f11} will show the contents of a nearby structure. As you can
2763 see, the possibilities are only marginally finite.
2765 @defopt idlwave-shell-examine-alist
2766 An alist of examine commands in which the keys name the command and are
2767 displayed in the selection popup, and the values are custom IDL examine
2768 command strings to send, after all instances of @code{___} are replaced
2769 by the indicated expression.
2773 @node Installation, Acknowledgements, The IDLWAVE Shell, Top
2774 @chapter Installation
2775 @cindex Installation
2778 * Installing IDLWAVE:: How to install the distribution
2779 * Installing Online Help:: Where to get the additional files needed
2780 * Upgrading from idl.el:: Necessary configuration changes
2783 @node Installing IDLWAVE, Installing Online Help, Installation, Installation
2784 @section Installing IDLWAVE
2787 @cindex URL, homepage for IDLWAVE
2788 @cindex Homepage for IDLWAVE
2789 @cindex IDLWAVE, homepage
2790 @cindex XEmacs package IDLWAVE
2791 @cindex Emacs, distributed with IDLWAVE
2792 @cindex Copyright, of IDL manual
2793 IDLWAVE is part of Emacs 21.1 and later. It is also an XEmacs package
2794 and can be installed from
2795 @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site}
2796 with the normal package management system on XEmacs 21. These
2797 pre-installed versions should work out-of-the-box. However, the files
2798 required for online help are not distributed with XEmacs/Emacs and have
2799 to be installed separately@footnote{Due to copyright reasons, the ASCII
2800 version of the IDL manual cannot be distributed under the GPL.}
2801 (@pxref{Installing Online Help}).
2803 You can also download IDLWAVE and install it yourself from
2804 @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. Follow the
2805 instructions in the INSTALL file.
2807 @node Installing Online Help, Upgrading from idl.el, Installing IDLWAVE, Installation
2808 @section Installing Online Help
2809 @cindex Installing online help
2810 @cindex Online Help, Installation
2812 If you want to use the online help display, two additional files (an
2813 ASCII version of the IDL documentation and a topics/code file) must be
2814 installed. These files can also be downloaded from
2815 @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. You need to
2816 place the files somewhere on your system and tell IDLWAVE where they are
2820 (setq idlwave-help-directory "/path/to/help/files/")
2823 @node Upgrading from idl.el, , Installing Online Help, Installation
2824 @section Upgrading from the old @b{@file{idl.el}} file
2825 @cindex Upgrading from old @b{@file{idl.el}}
2826 @cindex Renaming old variables
2827 @cindex Old variables, renaming
2830 If you have been using the old @file{idl.el} and @file{idl-shell.el}
2831 files and would like to use IDLWAVE, you need to update your
2832 customization in @file{.emacs}.
2836 Change all variable and function prefixes from @samp{idl-} to @samp{idlwave-}.
2838 Remove the now invalid @code{autoload} and @code{auto-mode-alist} forms
2839 pointing to the @file{idl.el} and @file{idl-shell.el} files. Install
2840 the new autoload forms.
2842 If you have been using the hook function recommended in earlier versions
2843 to get a separate frame for the IDL shell, remove that command from your
2844 @code{idlwave-shell-mode-hook}. Instead, set the variable
2845 @code{idlwave-shell-use-dedicated-frame} with
2847 (setq idlwave-shell-use-dedicated-frame t)
2850 The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character.
2851 Like in in many other Emacs modes, @kbd{M-@key{TAB}} now does
2852 completion. Inserting a TAB has therefore been moved to
2853 @kbd{C-@key{TAB}}. On a character based terminal you can also use
2854 @kbd{C-c @key{SPC}}.
2857 @node Acknowledgements, Sources of Routine Info, Installation, Top
2858 @chapter Acknowledgements
2859 @cindex Acknowledgements
2860 @cindex Maintainer, of IDLWAVE
2861 @cindex Authors, of IDLWAVE
2862 @cindex Contributors, to IDLWAVE
2863 @cindex Email address, of Maintainer
2867 The main contributors to the IDLWAVE package have been:
2871 @uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author.
2872 Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them
2876 @uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge
2877 of the package from version 3.0, during which time he overhauled almost
2878 everything, modernized IDLWAVE with many new features, and developed the
2882 @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current
2883 maintainer, as of version 4.10, helped shape object method completion
2884 and most new features introduced in versions 4.x.
2888 The following people have also contributed to the development of IDLWAVE
2889 with patches, ideas, bug reports and suggestions.
2893 Ulrik Dickow <dickow@@nbi.dk>
2895 Eric E. Dors <edors@@lanl.gov>
2897 Stein Vidar H. Haugan <s.v.h.haugan@@astro.uio.no>
2899 David Huenemoerder <dph@@space.mit.edu>
2901 Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de>
2903 Dick Jackson <dick@@d-jackson.com>
2905 Xuyong Liu <liu@@stsci.edu>
2907 Simon Marshall <Simon.Marshall@@esrin.esa.it>
2909 Craig Markwardt <craigm@@cow.physics.wisc.edu>
2911 Laurent Mugnier <mugnier@@onera.fr>
2913 Lubos Pochman <lubos@@rsinc.com>
2915 Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov>
2917 Marty Ryba <ryba@@ll.mit.edu>
2919 Phil Williams <williams@@irc.chmcc.org>
2921 Phil Sterne <sterne@@dublin.llnl.gov>
2927 @node Sources of Routine Info, Configuration Examples, Acknowledgements, Top
2928 @appendix Sources of Routine Info
2930 @cindex Sources of routine information
2931 In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE
2932 displays the calling sequence and keywords of routines, and completes
2933 routine names and keywords. For these features to work, IDLWAVE must
2934 know about the accessible routines.
2937 * Routine Definitions:: Where IDL Routines are defined.
2938 * Routine Information Sources:: So how does IDLWAVE know about...
2939 * Library Catalog:: Scanning the Libraries for Routine Info
2940 * Load-Path Shadows:: Routines defined in several places
2941 * Documentation Scan:: Scanning the IDL Manuals
2944 @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info
2945 @appendixsec Routine Definitions
2946 @cindex Routine definitions
2947 @cindex IDL variable @code{!PATH}
2948 @cindex @code{!PATH}, IDL variable
2949 @cindex @code{CALL_EXTERNAL}, IDL routine
2950 @cindex @code{LINKIMAGE}, IDL routine
2951 @cindex External routines
2953 @noindent Routines which can be used in an IDL program can be defined in
2958 @emph{Builtin routines} are defined inside IDL itself. The source
2959 code of such routines is not available.
2961 Routines which are @emph{part of the current program}, defined in a
2962 file which is explicitly compiled by the user. This file may or may not
2963 be located on the IDL search path.
2965 @emph{Library routines} are defined in files located on IDL's search
2966 path, and will need not be manually compiled. When a library routine is
2967 called for the first time, IDL will find the source file and compile it
2968 dynamically. A special sub-category of library routines are the
2969 @emph{system routines} distributed with IDL, and usually available in
2970 the @file{lib} subdirectory of the IDL distribution.
2972 External routines written in other languages (like Fortran or C) can be
2973 called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE},
2974 or included as dynamically loaded modules (DLMs). Currently IDLWAVE
2975 cannot provide routine info and completion for such external routines.
2978 @node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info
2979 @appendixsec Routine Information Sources
2980 @cindex Routine info sources
2981 @cindex Builtin list of routines
2982 @cindex Updating routine info
2983 @cindex Scanning buffers for routine info
2984 @cindex Buffers, scanning for routine info
2985 @cindex Shell, querying for routine info
2987 @noindent To maintain the most comprehensive information about all IDL
2988 routines on a system, IDLWAVE collects data from many sources:
2993 It has a @emph{builtin list} with the properties of the builtin IDL
2994 routines. IDLWAVE @value{VERSION} is distributed with a list of
2995 @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords,
2996 reflecting IDL version @value{IDLVERSION}. This list has been created
2997 by scanning the IDL manuals and is stored in the file
2998 @file{idlw-rinfo.el}. @xref{Documentation Scan}, for information on how
2999 to regenerate this file for new versions of IDL.
3002 It @emph{scans} all @emph{buffers} of the current Emacs session for
3003 routine definitions. This is done automatically when routine
3004 information or completion is first requested by the user. Each new
3005 buffer and each buffer which is saved after making changes is also
3006 scanned. The command @kbd{C-c C-i} (@code{idlwave-update-routine-info})
3007 can be used at any time to rescan all buffers.
3010 If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will
3011 @emph{query the shell} for compiled routines and their arguments. This
3012 happens automatically when routine information or completion is first
3013 requested by the user, and each time an Emacs buffer is compiled with
3014 @kbd{C-c C-d C-c}. Though rarely necessary, the command @kbd{C-c C-i}
3015 (@code{idlwave-update-routine-info}) can be used to update the shell
3019 IDLWAVE can scan all or selected library source files and store the
3020 result in a file which will be automatically loaded just like
3021 @file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to
3025 Loading routine and catalog information is a time consuming process.
3026 Depending on the system and network configuration it can take up to 30
3027 seconds. In order to minimize the waiting time upon your first
3028 completion or routine info command in a session, IDLWAVE uses Emacs idle
3029 time to do the initialization in 5 steps, yielding to user input in
3030 between. If this gets into your way, set the variable
3031 @code{idlwave-init-rinfo-when-idle-after} to 0 (zero).
3033 @defopt idlwave-init-rinfo-when-idle-after (@code{10})
3034 Seconds of idle time before routine info is automatically initialized.
3037 @defopt idlwave-scan-all-buffers-for-routine-info (@code{t})
3038 Non-@code{nil} means scan all buffers for IDL programs when updating
3042 @defopt idlwave-query-shell-for-routine-info (@code{t})
3043 Non-@code{nil} means query the shell for info about compiled routines.
3046 @defopt idlwave-auto-routine-info-updates
3047 Controls under what circumstances routine info is updated automatically.
3050 @node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
3051 @appendixsec Library Catalog
3052 @cindex Library scan
3053 @cindex Library catalog
3054 @cindex IDL library routine info
3058 @cindex IDL variable @code{!DIR}
3059 @cindex @code{!DIR}, IDL variable
3062 IDLWAVE can extract routine information from library modules and store
3063 that information in a file. To do this, the variable
3064 @code{idlwave-libinfo-file} needs to contain the path to a file in an
3065 existing directory (the default is @code{"~/.idlcat.el"}). Since the
3066 file will contain lisp code, its name should end in @file{.el}. Under
3067 Windows and MacOS, you also need to specify the search path for IDL
3068 library files in the variable @code{idlwave-library-path}, and the
3069 location of the IDL directory (the value of the @code{!DIR} system
3070 variable) in the variable @code{idlwave-system-directory}, like
3071 this@footnote{The initial @samp{+} leads to recursive expansion of the
3072 path, just like in IDL}:
3075 (setq idlwave-library-path
3076 '("+c:/RSI/IDL54/lib/" "+c:/user/me/idllibs" ))
3077 (setq idlwave-system-directory "c:/RSI/IDL54/")
3080 @noindent Under UNIX, these values will be automatically inferred from
3083 The command @kbd{M-x idlwave-create-libinfo-file} can then be used to
3084 scan library files. It brings up a widget in which you can select some
3085 or all directories on the search path. If you only want to have routine
3086 and completion info of some libraries, it is sufficient to scan those
3087 directories. However, if you want IDLWAVE to detect possible name
3088 conflicts with routines defined in other libraries, the whole pass
3091 After selecting directories, click on the @w{@samp{[Scan & Save]}}
3092 button in the widget to scan all files in the selected directories and
3093 write the resulting routine information into the file
3094 @code{idlwave-libinfo-file}. In order to update the library information
3095 from the same directories, call the command
3096 @code{idlwave-update-routine-info} with a double prefix argument:
3097 @w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously
3098 selected directories, write an updated version of the libinfo file and
3099 rebuild IDLWAVE's internal lists. If you give three prefix arguments
3100 @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a background
3101 job@footnote{Unix systems only, I think.}. You can continue to work,
3102 and the library catalog will be re-read when it is ready.
3104 A note of caution: Depending on your local installation, the IDL
3105 library can be very large. Parsing it for routine information will take
3106 time and loading this information into Emacs can require a
3107 significant amount of memory. However, having this information
3108 available will be a great help.
3110 @defopt idlwave-libinfo-file
3111 File for routine information of the IDL library.
3114 @defopt idlwave-library-path
3115 IDL library path for Windows and MacOS. Not needed under Unix.
3118 @defopt idlwave-system-directory
3119 The IDL system directory for Windows and MacOS. Not needed under UNIX.
3122 @defopt idlwave-special-lib-alist
3123 Alist of regular expressions matching special library directories.
3126 @node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info
3127 @appendixsec Load-Path Shadows
3128 @cindex Load-path shadows
3129 @cindex Shadows, load-path
3130 @cindex Duplicate routines
3131 @cindex Multiply defined routines
3132 @cindex Routine definitions, multiple
3133 @cindex Application, testing for shadowing
3134 @cindex Buffer, testing for shadowing
3136 IDLWAVE can compile a list of routines which are defined in several
3137 different files. Since one definition will hide (shadow) the others
3138 depending on which file is compiled first, such multiple definitions are
3139 called "load-path shadows". IDLWAVE has several routines to scan for
3140 load path shadows. The output is placed into the special buffer
3141 @file{*Shadows*}. The format of the output is identical to the source
3142 section of the routine info buffer (@pxref{Routine Info}). The
3143 different definitions of a routine are listed in the sequence of
3144 @emph{likelihood of use}. So the first entry will be most likely the
3145 one you'll get if an unsuspecting command uses that routine. Before
3146 listing shadows, you should make sure that routine info is up-to-date by
3147 pressing @kbd{C-c C-i}. Here are the different routines:
3150 @item @kbd{M-x idlwave-list-buffer-load-path-shadows}
3151 This commands checks the names of all routines defined in the current
3152 buffer for shadowing conflicts with other routines accessible to
3153 IDLWAVE. The command also has a key binding: @kbd{C-c C-b}
3154 @item @kbd{M-x idlwave-list-shell-load-path-shadows}.
3155 Checks all routines compiled under the shell for shadowing. This is
3156 very useful when you have written a complete application. Just compile
3157 the application, use @code{RESOLVE_ALL} to compile any routines used by
3158 your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and
3159 then check for shadowing.
3160 @item @kbd{M-x idlwave-list-all-load-path-shadows}
3161 This command checks all routines accessible to IDLWAVE for conflicts.
3164 For these commands to work properly you should have scanned the entire
3165 load path, not just selected directories. Also, IDLWAVE should be able
3166 to distinguish between the system library files (normally installed in
3167 @file{/usr/local/rsi/idl/lib}) and any site specific or user specific
3168 files. Therefore, such local files should not be installed inside the
3169 @file{lib} directory of the IDL directory. This is also advisable for
3174 @cindex IDL variable @code{!DIR}
3175 @cindex @code{!DIR}, IDL variable
3176 Users of Windows and MacOS also must set the variable
3177 @code{idlwave-system-directory} to the value of the @code{!DIR} system
3178 variable in IDL. IDLWAVE appends @file{lib} to the value of this
3179 variable and assumes that all files found on that path are system
3182 Another way to find out if a specific routine has multiple definitions
3183 on the load path is routine info display (@pxref{Routine Info}).
3185 @node Documentation Scan, , Load-Path Shadows, Sources of Routine Info
3186 @appendixsec Documentation Scan
3187 @cindex @file{get_rinfo}
3188 @cindex @file{idlw-rinfo.el}
3189 @cindex @file{idlw-help.txt}
3190 @cindex @file{idlw-help.el}
3191 @cindex Scanning the documentation
3192 @cindex Perl program, to create @file{idlw-rinfo.el}
3194 IDLWAVE derives it knowledge about system routines from the IDL
3195 manuals. The file @file{idlw-rinfo.el} contains the routine information
3196 for the IDL system routines. The Online Help feature of IDLWAVE
3197 requires ASCII versions of some IDL manuals to be available in a
3198 specific format (@file{idlw-help.txt}), along with an Emacs-Lisp file
3199 @file{idlw-help.el} with supporting code and pointers to the ASCII file.
3201 All 3 files can be derived from the IDL documentation. If you are
3202 lucky, the maintainer of IDLWAVE will always have access to the newest
3203 version of IDL and provide updates. The IDLWAVE distribution also
3204 contains the Perl program @file{get_rinfo} which constructs these files
3205 by scanning selected files from the IDL documentation. Instructions on
3206 how to use @file{get_rinfo} are in the program itself.
3208 One particularly frustrating situation occurs when a new IDL version is
3209 released without the associated documentation updates. Instead, a
3210 @emph{What's New} file containing new and updated documentation is
3211 shipped alongside the previous version's reference material. The
3212 @file{get_rinfo} script can merge this new information into the standard
3213 help text and routine information, as long as it is pre-formatted in a
3214 simple way. See @file{get_rinfo} for more information.
3216 @node Configuration Examples, Windows and MacOS, Sources of Routine Info, Top
3217 @appendix Configuration Examples
3218 @cindex Configuration examples
3219 @cindex Example configuration
3220 @cindex @file{.emacs}
3221 @cindex Default settings, of options
3222 @cindex Interview, with the maintainer
3225 @b{Question:} You have all these complicated configuration options in
3226 your package, but which ones do @emph{you} as the maintainer actually
3227 set in your own configuration?
3230 @b{Answer:} Not many, beyond custom key bindings. I set most defaults
3231 the way that seems best. However, the default settings do not turn on
3236 are not self-evident (i.e. too magic) when used by an unsuspecting user.
3240 will not work properly on all Emacs installations.
3242 break with widely used standards.
3244 use function or other non-standard keys.
3246 are purely personal customizations, like additional key bindings, and
3250 @noindent To see what I mean, here is the @emph{entire} configuration
3251 the old maintainer had in his @file{.emacs}:
3254 (setq idlwave-shell-debug-modifiers '(control shift)
3255 idlwave-store-inquired-class t
3256 idlwave-shell-automatic-start t
3257 idlwave-main-block-indent 2
3258 idlwave-init-rinfo-when-idle-after 2
3259 idlwave-help-dir "~/lib/emacs/idlwave"
3260 idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib")
3261 ("/jhuapl/" . "JHUAPL-Lib")
3262 ("/dominik/lib/idl/" . "MyLib")))
3265 However, if you are an Emacs power-user and want IDLWAVE to work
3266 completely differently, you can change almost every aspect of it. Here
3267 is an example of a much more extensive configuration of IDLWAVE. The
3271 ;;; Settings for IDLWAVE mode
3273 (setq idlwave-block-indent 3) ; Indentation settings
3274 (setq idlwave-main-block-indent 3)
3275 (setq idlwave-end-offset -3)
3276 (setq idlwave-continuation-indent 1)
3277 (setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;"
3278 ; anchored at start of line.
3279 (setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,>
3280 (setq idlwave-pad-keyword nil) ; Remove spaces for keyword '='
3281 (setq idlwave-expand-generic-end t) ; convert END to ENDIF etc...
3282 (setq idlwave-reserved-word-upcase t) ; Make reserved words upper case
3283 ; (with abbrevs only)
3284 (setq idlwave-abbrev-change-case nil) ; Don't force case of expansions
3285 (setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill
3286 (setq idlwave-show-block nil) ; Turn off blinking to begin
3287 (setq idlwave-abbrev-move t) ; Allow abbrevs to move point
3288 (setq idlwave-query-class '((method-default . nil) ; No query for method
3289 (keyword-default . nil); or keyword completion
3290 ("INIT" . t) ; except for these
3293 ("GETPROPERTY" .t)))
3295 ;; Some setting can only be done from a mode hook. Here is an example:
3296 (add-hook 'idlwave-mode-hook
3298 (setq case-fold-search nil) ; Make searches case sensitive
3299 ;; Run other functions here
3300 (font-lock-mode 1) ; Turn on font-lock mode
3301 (idlwave-auto-fill-mode 0) ; Turn off auto filling
3303 ;; Pad with with 1 space (if -n is used then make the
3304 ;; padding a minimum of n spaces.) The defaults use -1
3306 (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1))
3307 (idlwave-action-and-binding "<" '(idlwave-surround 1 1))
3308 (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-)))
3309 (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
3311 ;; Only pad after comma and with exactly 1 space
3312 (idlwave-action-and-binding "," '(idlwave-surround nil 1))
3313 (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
3315 ;; Pad only after `->', remove any space before the arrow
3316 (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2))
3318 ;; Set some personal bindings
3319 ;; (In this case, makes `,' have the normal self-insert behavior.)
3320 (local-set-key "," 'self-insert-command)
3321 (local-set-key [f5] 'idlwave-shell-break-here)
3322 (local-set-key [f6] 'idlwave-shell-clear-current-bp)
3324 ;; Create a newline, indenting the original and new line.
3325 ;; A similar function that does _not_ reindent the original
3326 ;; line is on "\C-j" (The default for emacs programming modes).
3327 (local-set-key "\n" 'idlwave-newline)
3328 ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.
3330 ;; Some personal abbreviations
3331 (define-abbrev idlwave-mode-abbrev-table
3332 (concat idlwave-abbrev-start-char "wb") "widget_base()"
3333 (idlwave-keyword-abbrev 1))
3334 (define-abbrev idlwave-mode-abbrev-table
3335 (concat idlwave-abbrev-start-char "on") "obj_new()"
3336 (idlwave-keyword-abbrev 1))
3339 ;;; Settings for IDLWAVE SHELL mode
3341 (setq idlwave-shell-overlay-arrow "=>") ; default is ">"
3342 (setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame
3343 (setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> "
3344 (setq idlwave-shell-explicit-file-name "wave")
3345 (setq idlwave-shell-process-name "wave")
3346 (setq idlwave-shell-use-toolbar nil) ; No toolbar
3348 ;; Most shell interaction settings can be done from the shell-mode-hook.
3349 (add-hook 'idlwave-shell-mode-hook
3351 ;; Set up some custom key and mouse examine commands
3352 (idlwave-shell-define-key-both [s-down-mouse-2]
3353 (idlwave-shell-mouse-examine
3354 "print, size(___,/DIMENSIONS)"))
3355 (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
3356 "print, size(___,/DIMENSIONS)"))
3357 (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
3358 "print,size(___,/TNAME)"))
3359 (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
3360 "help,___,/STRUCTURE"))))
3363 @node Windows and MacOS, Index, Configuration Examples, Top
3364 @appendix Windows and MacOS
3368 IDLWAVE was developed on a UNIX system. However, due to the portability
3369 of Emacs, much of IDLWAVE does also work under different operating
3370 systems like Windows (with NTEmacs or NTXEmacs) or MacOS.
3372 The only problem really is that RSI does not provide a command-line
3373 version of IDL for Windows or MacOS which IDLWAVE can interact
3374 with@footnote{Call your RSI representative and complain --- it should be
3375 trivial for them to provide one. And if enough people ask for it, maybe
3376 they will. The upcoming IDL for Mac OSX is slated to have a
3377 command-line version.}. Therefore the IDLWAVE Shell does not work and
3378 you have to rely on IDLDE to run and debug your programs. However,
3379 editing IDL source files with Emacs/IDLWAVE works with all bells and
3380 whistles, including routine info, completion and fast online help. Only
3381 a small amount of additional information must be specified in your
3382 .emacs file: You must specify path names which on a UNIX can be
3383 automatically gathered by talking to the IDL program.
3385 Here is an example of the additional configuration needed for a Windows
3386 system. I am assuming that IDLWAVE has been installed in
3387 @w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in
3388 @w{@samp{C:\RSI\IDL55}}.
3391 ;; location of the lisp files (needed if IDLWAVE is not part of
3392 ;; the X/Emacs installation)
3393 (setq load-path (cons "c:/program files/IDLWAVE" load-path))
3395 ;; The location of the IDL library files, both from RSI and your own.
3396 ;; note that the initial "+" expands the path recursively
3397 (setq idlwave-library-path
3398 '("+c:/RSI/IDL55/lib/" "+c:/user/me/idllibs" ))
3400 ;; location of the IDL system directory (try "print,!DIR")
3401 (setq idlwave-system-directory "c:/RSI/IDL55/")
3403 ;; location of the IDLWAVE help files idlw-help.el and idlw-help.txt.
3404 (setq idlwave-help-directory "c:/IDLWAVE")
3406 ;; file in which to store the user catalog info
3407 (setq idlwave-libinfo-file "c:/IDLWAVE/idlcat.el")
3410 @noindent Furthermore, Windows sometimes tries to outsmart you --- make
3411 sure you check the following things:
3414 @item When you download the IDLWAVE distribution, make sure you save the
3415 files under the names @file{idlwave.tar.gz} and
3416 @file{idlwave-help-tar.gz}.
3417 @item Be sure that your software for untarring/ungzipping is @emph{NOT}
3418 doing smart CR/LF conversion (WinZip users will find this in
3419 Options:Configuration:Miscellaneous, change the setting, then re-open
3420 the archive). This adds one byte per line, throwing off the
3421 byte-counts for the help file lookups and defeating fast online help lookup.
3422 @item M-TAB switches among running programs --- use Esc-TAB
3424 @item Other issues as yet unnamed...
3428 @node Index, , Windows and MacOS, Top