1 \input texinfo @c -*-texinfo-*-
3 @setfilename ../info/idlwave
4 @settitle IDLWAVE User Manual
7 * IDLWAVE: (idlwave). Major mode and shell for IDL and WAVE/CL files.
15 @set NSYSROUTINES 1287
16 @set NSYSKEYWORDS 5724
17 @set DATE December 2000
18 @set AUTHOR Carsten Dominik
19 @set AUTHOR-EMAIL dominik@@astro.uva.nl
20 @set MAINTAINER Carsten Dominik
21 @set MAINTAINER-EMAIL dominik@@astro.uva.nl
22 @set IDLWAVE-HOMEPAGE http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave
27 This file documents IDLWAVE, a major mode for editing IDL and
28 WAVE/CL files with Emacs. It also implements a shell for running IDL as
31 This is edition @value{EDITION} of the IDLWAVE User Manual for
32 IDLWAVE @value{VERSION}
34 Copyright (c) 1999, 2000 Free Software Foundation, Inc.
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
42 and print the results, provided the printed document
43 carries a copying permission notice identical to this
44 one except for the removal of this paragraph (this
45 paragraph not being relevant to the printed manual).
48 Permission is granted to copy and distribute modified
49 versions of this manual under the conditions for
50 verbatim copying, provided that the entire resulting
51 derived work is distributed under the terms of a permission
52 notice identical to this one.
54 Permission is granted to copy and distribute
55 translations of this manual into another language,
56 under the above conditions for modified versions,
57 except that this permission notice may be stated in a
58 translation approved by the Free Software Foundation.
62 @title IDLWAVE User Manual
63 @subtitle Major Emacs mode and shell for IDL and WAVE/CL files
64 @subtitle Edition @value{EDITION}, @value{DATE}
66 @author by Carsten Dominik
68 Copyright @copyright{} 1999, 2000 Free Software Foundation, Inc.
71 This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for
72 IDLWAVE version @value{VERSION}, @value{DATE}.
76 @cindex Copyright, of IDLWAVE
77 Permission is granted to make and distribute verbatim
78 copies of this manual provided the copyright notice and
79 this permission notice are preserved on all copies.
81 Permission is granted to copy and distribute modified
82 versions of this manual under the conditions for
83 verbatim copying, provided that the entire resulting
84 derive work is distributed under the terms of a permission
85 notice identical to this one.
87 Permission is granted to copy and distribute
88 translations of this manual into another language,
89 under the above conditions for modified versions,
90 except that this permission notice may be stated in a
91 translation approved by the Free Software Foundation.
100 @node Top, Introduction, (dir), (dir)
102 IDLWAVE is a package to support editing command files for the
103 Interactive Data Language (IDL), and for running IDL as an inferior
109 * Introduction:: What IDLWAVE is and what not
110 * IDLWAVE in a Nutshell:: One page quick-start guide
111 * Getting Started:: Tutorial
112 * The IDLWAVE Major Mode:: The mode to edit IDL programs
113 * The IDLWAVE Shell:: The mode to run IDL as inferior program
114 * Installation:: How to Install or Upgrade
115 * Acknowledgement:: Who helped
116 * Sources of Routine Info:: How does IDLWAVE know about routine XYZ
117 * Configuration Examples:: The user is king...
118 * Index:: Fast access
120 @detailmenu --- The Detailed Node Listing ---
122 The IDLWAVE Major Mode
124 * Code Formatting:: Making code look nice
125 * Routine Info:: Calling Sequence and Keyword List
126 * Online Help:: One key press from source to help
127 * Completion:: Completing routine names and Keywords
128 * Routine Source:: How to visit the source file of routine XYZ
129 * Resolving Routines:: Force the Shell to compile a routine
130 * Code Templates:: Abbreviations for frequent constructs
131 * Actions:: Changing case, Padding, End checking
132 * Doc Header:: Inserting a standard header
133 * Motion Commands:: Moving through the structure of a program
134 * Misc Options:: Things that fit nowhere else
138 * Code Indentation:: Reflecting the logical structure
139 * Comment Indentation:: Special indentation for comment lines
140 * Continuation Lines:: Splitting statements over lines
141 * Syntax Highlighting:: Font-lock support
145 * Block Boundary Check:: Is the END correct
146 * Padding Operators:: Enforcing space around `=' etc
147 * Case Changes:: Enforcing upper case keywords
151 * Starting the Shell:: How to launch IDL as a subprocess
152 * Using the Shell:: Interactively working with the Shell
153 * Debugging IDL Programs:: Compilation/Debugging
155 Debugging IDL Programs
157 * Compiling Programs:: Compiling buffers under the shell
158 * Breakpoints and Stepping:: Deciding where to stop and look
159 * Walking the Calling Stack:: From where was this routine called?
160 * Examining Variables:: What is the value now?
164 * Installing IDLWAVE:: How to install the distribution
165 * Installing Online Help:: Where to get the additional files needed
166 * Upgrading from idl.el:: Necessary configuration changes
168 Sources of Routine Info
170 * Routine Definitions:: Where IDL Routines are defined.
171 * Routine Information Sources:: So how does IDLWAVE know about...
172 * Library Catalog:: Scanning the Libraries for Routine Info
173 * Load-Path Shadows:: Routines defined in several places
174 * Documentation Scan:: Scanning the IDL Manuals
179 @node Introduction, IDLWAVE in a Nutshell, Top, Top
180 @chapter Introduction
182 @cindex CORBA (Common Object Request Broker Architecture)
183 @cindex Interface Definition Language
184 @cindex Interactive Data Language
186 @cindex @file{idl.el}
187 @cindex @file{idl-shell.el}
188 @cindex Feature overview
190 IDLWAVE is a package to support editing command files for the
191 Interactive Data Language (IDL), and for running IDL as an inferior
192 shell. It also can be used for WAVE/CL command files, but the support
193 for these is limited. Note that this package has nothing to do with the
194 Interface Definition Language as part of the Common Object Request
195 Broker Architecture (CORBA).
197 IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el}
198 files written by Chris Chase. The modes and files had to be renamed
199 because of a name space conflict with CORBAs @code{idl-mode}, defined in
200 Emacs in the file @file{cc-mode.el}. If you have been using the old
201 files, check @ref{Upgrading from idl.el} for information on how to
204 IDLWAVE consists of two parts: A major mode for editing command files
205 (@code{idlwave-mode}) and a mode to allow running the IDL program as an
206 inferior shell (@code{idlwave-shell-mode}). Both modes work closely
207 together and form a complete development environment.
209 Here is a brief summary of what IDLWAVE does.
213 Code indentation and formatting.
215 Font-lock support on three levels.
217 Display of calling sequence and keywords of more than 1000 IDL
218 routines routines and any routines in your local IDL library.
220 Name space conflict search.
222 Fast context-sensitive online help.
224 Context sensitive completion of routine names and keywords.
226 Insertion of code templates.
228 Actions to enforce coding standards during typing.
230 Block structure check.
232 Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs).
234 Documentation support.
236 Running IDL as inferior process.
238 Shell with history search, command line editing and completion.
240 Compilation, execution and debugging of programs directly from the source
243 Examining expressions with a mouse click.
248 Here are a number of screenshots showing IDLWAVE in action.
252 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/font-lock.gif,
253 XEmacs 21.1 with formatted and fontified code}
255 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/rinfo.gif,
256 XEmacs 21.1 displaying routine info}
258 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/complete.gif,
259 XEmacs 21.1 completing a keyword}
261 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/shell.gif,
262 XEmacs 21.1 with debugging toolbar; execution stopped at a breakpoint}
266 In this manual, each section contains a list of user options related to
267 the subject. Don't be confused by the shear number of options available
268 -- in most cases the default settings are just fine. The variables are
269 listed here to make sure you know where to look if you want to change
270 things. For a full description of what a particular variable does and
271 how to configure it, see the documentation string of that variable.
272 Some configuration examples are also given in the appendix.
274 @node IDLWAVE in a Nutshell, Getting Started, Introduction, Top
275 @chapter IDLWAVE in a Nutshell
276 @cindex Summary of important commands
277 @cindex IDLWAVE in a Nutshell
278 @cindex Nutshell, IDLWAVE in a
280 @subheading Editing IDL Programs
282 @multitable @columnfractions .15 .85
284 @tab Indent the current line relative to context.
286 @tab Re-indent all lines in the current region.
287 @item @kbd{M-@key{RET}}
288 @tab Start a continuation line. Or split the current line at point.
290 @tab Fill the current comment paragraph.
292 @tab Display calling sequence, keywords of the procedure/function call
295 @tab Context sensitive online help.
296 @item @kbd{M-@key{TAB}}
297 @tab Complete a procedure name, function name or keyword in the buffer.
299 @tab Update IDLWAVE's knowledge about functions and procedures.
301 @tab Find the source code of a procedure/function.
303 @tab Insert a standard documentation header.
305 @tab Insert a new timestamp and history item in the documentation header.
308 @subheading Running the IDLWAVE Shell, Debugging Programs
310 @multitable @columnfractions .15 .85
312 @tab Start IDL as a subprocess and/or switch to the interaction buffer.
314 @tab Cycle back through IDL command history matching command line input.
317 @item @kbd{M-@key{TAB}}
318 @tab Complete a procedure name, function name or keyword in the shell buffer.
319 @item @kbd{C-c C-d C-c}
320 @tab Save and compile the source file in the current buffer.
321 @item @kbd{C-c C-d C-x}
322 @tab Goto next syntax error.
323 @item @kbd{C-c C-d C-b}
324 @tab Set a breakpoint at the current source line.
325 @item @kbd{C-c C-d C-d}
326 @tab Clear the current breakpoint.
327 @item @kbd{C-c C-d C-p}
328 @tab Ask IDL to print the value of the expression near point.
331 @subheading Commonly used Settings in @file{.emacs}
333 ;; Change the indentation preferences
334 (setq idlwave-main-block-indent 2 ; default 0
335 idlwave-block-indent 2 ; default 4
336 idlwave-end-offset -2) ; default -4
337 ;; Pad some operators with spaces
338 (setq idlwave-do-actions t
339 idlwave-surround-by-blank t)
340 ;; Syntax Highlighting
341 (add-hook 'idlwave-mode-hook 'turn-on-font-lock)
342 ;; Automatically start the shell when needed
343 (setq idlwave-shell-automatic-start t)
344 ;; Bind debugging commands with CONTROL and SHIFT modifiers
345 (setq idlwave-shell-debug-modifiers '(control shift))
346 ;; Where are the online help files?
347 (setq idlwave-help-directory "~/.idlwave")
350 @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top
351 @chapter Getting Started (Tutorial)
354 @cindex Getting Started
356 @section Lession I: Development Cycle
358 The purpose of this tutorial is to guide you through a very basic
359 development cycle with IDLWAVE. We will type a simple program into a
360 buffer and use the shell to compile, debug and run this program. On the
361 way we will use the most important commands in IDLWAVE. Note
362 however that there is much more funtionality available in IDLWAVE than
363 we cover here, and it will pay off greatly if eventually you go further
364 and read the whole manual.
366 I assume that you have access to Emacs or XEmacs with the full IDLWAVE
367 package including online help (@pxref{Installation}). I also assume
368 that you are familiar with Emacs and can read the nomenclature of key
369 presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL} and
370 @kbd{M} for @key{META} (often the @key{ALT} key carries this
373 Open a new source file by typing
376 @kbd{C-x C-f tutorial.pro @key{RET}}
379 A buffer for this file will pop up, and it should be in IDLWAVE mode.
380 You can see this by looking at the mode line, just below the editing
381 window. Also, the menu bar should contain entries @samp{IDLWAVE} and
384 Now cut-and-paste the following program, also available as
385 @file{tutorial.pro} in the IDLWAVE distribution.
389 ;; compute a sequence number for a date
391 if y lt 100 then y = y+1900
392 if m le 2 then delta = 1 else delta = 0
393 m1 = m + delta*12 + 1
395 return, d + floor(m1*30.6)+floor(y1*365.25)+5
398 function weekday,day,month,year
399 ;; compute weekday number for date
400 nr = daynr(day,month,year)
404 pro plot_wday,day,month
405 ;; Plot the weekday of a date in the first 10 years of this century.
406 years = 2000,+indgen(10)
408 for i=0,n_elements(wdays)-1 do begin
409 wdays[i] = weekday(day,month,years[i])
411 plot,years,wdays,YS=2,YT="Wday (0=sunday)"
415 The indentation probably looks funny, since it's different from the
416 settings you use, so use the @key{TAB} key in each line to automatically
417 line it up (or more quickly @emph{select} the entire buffer with
418 @kbd{C-x h} followed by @kbd{M-C-\}). Notice how different syntactical
419 elements are highlighted in different colors, if you have set up support
422 Let's check out two particular editing features of IDLWAVE. Place the
423 cursor after the @code{end} statement of the @code{for} loop and press
424 @key{SPC}. IDLWAVE blinks back to the beginning of the block and
425 changes the generic @code{end} to the specific @code{endfor}
426 automatically. Now place the cursor in any line you would like to split
427 into two and press @kbd{M-@key{RET}}. The line is split at the cursor
428 position, with the continuation @samp{$} and indentation all taken care
429 of. Use @kbd{C-/} to undo the last change.
431 The procedure @code{plot_wday} is supposed to plot the weekday of a given
432 date for the first 10 years of the 21st century. I have put in a few
433 bugs which we are going to fix now.
435 First, let's launch the IDLWAVE shell. You do this with the command
436 @kbd{C-c C-s}. The Emacs window will split and display IDL running in a
437 shell interaction buffer. Type a few commands like @code{print,!PI} to
438 convince yourself that you can work there like in an xterminal, or the
439 IDLDE. Use the arrow keys to cycle through your command history. Are
442 Now go back to the source window and type @kbd{C-c C-d C-c} to compile
443 the program. If you watch the shell buffer, you see that IDLWAVE types
444 @samp{.run tutorial.pro} for you. But the compilation fails because
445 there is a comma in the line @samp{years=...}. The line with the error
446 is highlighted and the cursor positioned at the error, so remove the
447 comma (you should only need to hit Delete!). Compile again, using the
448 same keystrokes as before. Notice that the file is saved for you. This
449 time everything should work fine, and you should see the three routines
452 Now we want to use the command to plot the weekdays for January 1st. We
453 could type the full command ourselves, but why do that? Go back to the
454 shell window, type @samp{plot_} and hit @key{TAB}. After a bit of a
455 delay (while IDLWAVE initializes its routine info database), the window
456 will split to show all procedures it knows starting with that string,
457 and @w{@code{plot_wday}} should be one of them. Saving the buffer was
458 enough to tell IDLWAVE about this new routine. Click with the middle
459 mouse button on @code{plot_wday} and it will be copied to the shell
460 buffer, or if you prefer, add @samp{w} to @samp{plot_} to make it
461 unambiguous, hit @key{TAB}, and the full routine name will be completed.
462 Now provide the two arguments:
469 and press @key{RET}. This fails with an error message telling you the
470 @code{YT} keyword to plot is ambiguous. What are the allowed keywords
471 again? Go back to the source window and put the cursor into the `plot'
472 line, and press @kbd{C-c ?}. This pops up the routine info window for
473 the plot routine, which contains a list of keywords, and the argument
474 list. Oh, we wanted @code{YTITLE}. Fix that up. Recompile with
475 @kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press
476 the @key{UP} arrow to recall the previous command and execute again.
478 This time we get a plot, but it is pretty ugly -- the points are all
479 connected with a line. Hmm, isn't there a way for @code{plot} to use
480 symbols instead? What was that keyword? Position the cursor on the
481 plot line after a comma (where you'd normally type a keyword), and hit
482 @kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, there
483 it is, @code{PSYM}. Middle click to insert it. An @samp{=} sign is
484 included for you too. Now what were the values of @code{PSYM} supposed
485 to be? With the cursor on or after the keyword, press @kbd{M-?} for
486 online help (alternatively, you could have right clicked on the colored
487 keyword itself in the completion list). The online help window will pop
488 up showing the documentation for the @code{PYSM} keyword. Ok, let's use
489 diamonds=4. Fix this, recompile (you know the command by now: @kbd{C-c
490 C-d C-c}, go back to the shell (if it's vanished, you know the command
491 to recall it by now: @kbd{C-c C-s}) and execute again. Now things look
494 Lets try a different day - how about April fool's day?
500 Oops, this looks very wrong. All April fool's days cannot be
501 Fridays! We've got a bug in the program, perhaps in the @code{daynr}
502 function. Lets put a breakpoint on the last line there. Position the
503 cursor on the @samp{return, d+...} line and press @kbd{C-c C-d C-b}.
504 IDL sets a breakpoint (as you see in the shell window), and the line is
505 highlighted in some way. Back to the shell buffer, re-execute the
506 previous command. IDL stops at the line with the breakpoint. Now hold
507 down the SHIFT key and click with the middle mouse button on a few
508 variables there: @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe
509 @code{d} isn't the correct type. CONTROL-SHIFT middle-click on it for
510 help. Well, it's an integer, so that's not the problem. Aha, @samp{y1}
511 is zero, but it should be the year, depending on delta. Shift click
512 @samp{delta} to see that it's 0. Below, we see the offending line:
513 @samp{y1=y*delta...} the multiplication should have been a minus sign!
520 Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the
521 command. Everything should now work fine. How about those leap years?
522 Change the code to plot 100 years and see that every 28 years, the
523 sequence of weekdays repeats.
525 @section Lession II: Customization
527 Emacs is probably the most customizable piece of software available, and
528 it would be a shame if you did not make use of this and adapt IDLWAVE to
529 your own preferences. Customizing Emacs or IDLWAVE means that you have
530 to set Lisp variables in the @file{.emacs} file in your home directory.
531 This looks scary to many people because of all the parenthesis.
532 However, you can just cut and paste the examples given here and work
535 Lets first use a boolean variable. These are variables which you turn
536 on or off, much like a checkbox. A value of @samp{t} means on, a
537 value of @samp{nil} means off. Copy the following line into your
538 @file{.emacs} file, exit and restart Emacs.
541 (setq idlwave-reserved-word-upcase t)
544 When this option is turned on, each reserved word you type into an IDL
545 source buffer will be converted to upper case when you press @key{SPC}
546 or @key{RET} right after the word. Try it out! @samp{if} changes to
547 @samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this
548 behavior, remove the option again from your @file{.emacs} file.
550 Now I bet you have your own indentation preferences for IDL code. For
551 example, I like to indent the main block of an IDL program a bit,
552 different from the conventions used by RSI. Also, I'd like to use only
553 3 spaces as indentation between @code{BEGIN} and @code{END}. Try the
554 following lines in @file{.emacs}
557 (setq idlwave-main-block-indent 2)
558 (setq idlwave-block-indent 3)
559 (setq idlwave-end-offset -3)
562 Restart Emacs, take the program we developed in the first part of this
563 tutorial and re-indent it with @kbd{C-c h} and @kbd{M-C-\}. You
564 probably want to keep these lines in @file{.emacs}, with values adjusted
565 to your likings. If you want to get more information about any of these
566 variables, type, e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}.
567 To find which variables can be customized, look for items marked
568 @samp{User Option:} in the manual.
570 If you cannot wrap your head around this Lisp stuff, there is another,
571 more user-friendly way to customize all the IDLWAVE variables. You can
572 access it through the IDLWAVE menu in one of the @file{.pro} buffers,
573 option @code{Customize->Browse IDLWAVE Group}. Here you'll be presented
574 with all the various variables grouped into categories. You can
575 navigate the hierarchy (e.g. Idlwave Code Formatting->Idlwave Main Block
576 Indent), read about the variables, change them, and `Save for Future
577 Sessions'. Few of these variables need customization, but you can
578 exercise considerable control over IDLWAVE's functionality with them.
580 Many people I talk to find the key bindings used for the debugging
581 commands too long and complicated. Do I always have to type @kbd{C-c
582 C-d C-c} to get a single simple command? Due to Emacs rules and
583 conventions I cannot make better bindings by default, but you can.
584 First, there is a way to assign all debugging commands in a single sweep
585 to other combinations. The only problem is that we have to use
586 something which Emacs does not need for other important commands. A
587 good option is to execute debugging commands by holding down
588 @key{CONTROL} and @key{SHIFT} while pressing a single character:
589 @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for compiling the
590 current source file, @kbd{C-S-a} for deleting all breakpoints. You can
594 (setq idlwave-shell-debug-modifiers '(shift control))
597 If you have a special keyboard with for example a @key{HYPER} key, you
601 (setq idlwave-shell-debug-modifiers '(hyper))
604 instead to get compilation on @kbd{H-c}.
606 You can also assign specific commands to function keys. This you must
607 do in the @emph{mode-hook}, a special function which is run when a new
608 buffer gets set up. Keybindings can only be done when the buffer
609 exists. The possibilities for key customization are endless. Here we
610 set function keys f5-f8 to common debugging commands.
613 ;; First for the source buffer
614 (add-hook 'idlwave-mode-hook
616 (local-set-key [f5] 'idlwave-shell-break-here)
617 (local-set-key [f6] 'idlwave-shell-clear-current-bp)
618 (local-set-key [f7] 'idlwave-shell-cont)
619 (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
620 ;; Then for the shell buffer
621 (add-hook 'idlwave-shell-mode-hook
623 (local-set-key [f5] 'idlwave-shell-break-here)
624 (local-set-key [f6] 'idlwave-shell-clear-current-bp)
625 (local-set-key [f7] 'idlwave-shell-cont)
626 (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
629 @section Lession III: Library Catalog
631 We have already used the routine info display in the first part of this
632 tutorial. This was the key @kbd{C-c ?} which displays information about
633 the IDL routine near the cursor position. Wouldn't it be nice
634 to have the same available for your own library routines and for the
635 huge amount of code in major extension libraries like JHUPL or the
636 IDL-Astro library? To do this, you must give IDLWAVE a chance to study
637 these routines first. We call this @emph{Building the library catalog}.
639 From the IDLWAVE entry in the menu bar, select @code{Routine Info/Select
640 Catalog Directories}. If necessary, start the shell first with @kbd{C-c
641 C-s} (@pxref{Starting the Shell}). IDLWAVE will find out about the IDL
642 @code{!PATH} variable and offer a list of directories on the path.
643 Simply select them all (or whichever you want) and click on the
644 @samp{Scan&Save} button. Then go for a cup of coffee while IDLWAVE
645 collects information for each and every IDL routine on your search path.
646 All this information is written to the file @file{.idlcat} in your home
647 directory and will from now one be automatically loaded whenever you use
648 IDLWAVE. Try to use routine info (@kbd{C-c ?}) or completion
649 (@kbd{M-<TAB>}) while on any routine or partial routine name you know to
650 be located in the library. E.g., if you have scanned the IDL-Astro
658 expands to `readfits('. Then try
661 a=readfits(@key{C-c ?}
667 Usage: Result = READFITS(filename, header, heap)
671 I hope you made it until here. Now you are set to work with IDLWAVE.
672 On the way you will want to change other things, and to learn more about
673 the possibilities not discussed in this short tutorial. Read the
674 manual, look at the documentation strings of interesting variables (with
675 @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining
676 questions on @code{comp.lang.idl-pvwave}.
678 @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top
679 @chapter The IDLWAVE Major Mode
680 @cindex IDLWAVE major mode
681 @cindex Major mode, @code{idlwave-mode}
683 The IDLWAVE major mode supports editing IDL and WAVE/CL command files.
684 In this chapter we describe the main features of the mode and how to
688 * Code Formatting:: Making code look nice
689 * Routine Info:: Calling Sequence and Keyword List
690 * Online Help:: One key press from source to help
691 * Completion:: Completing routine names and Keywords
692 * Routine Source:: How to visit the source file of routine XYZ
693 * Resolving Routines:: Force the Shell to compile a routine
694 * Code Templates:: Abbreviations for frequent constructs
695 * Actions:: Changing case, Padding, End checking
696 * Doc Header:: Inserting a standard header
697 * Motion Commands:: Moving through the structure of a program
698 * Misc Options:: Things that fit nowhere else
701 @node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode
702 @section Code Formatting
703 @cindex Code formatting
704 @cindex Formatting, of code
707 * Code Indentation:: Reflecting the logical structure
708 * Comment Indentation:: Special indentation for comment lines
709 * Continuation Lines:: Splitting statements over lines
710 * Syntax Highlighting:: Font-lock support
713 @node Code Indentation, Comment Indentation, Code Formatting, Code Formatting
714 @subsection Code Indentation
715 @cindex Code indentation
718 Like all Emacs programming modes, IDLWAVE performs code indentation.
719 The @key{TAB} key indents the current line relative to context.
720 @key{LFD} insert a newline and indents the new line. The indentation is
721 governed by a number of variables.
723 @cindex Foreign code, adapting
724 @cindex Indentation, of foreign code
726 To re-indent a larger portion of code (e.g. when working with foreign code
727 written with different conventions), use @kbd{M-C-\}
728 (@code{indent-region}) after marking the relevant code. Useful marking
729 commands are @kbd{C-x h} (the entire file) or @kbd{M-C-h} (the
730 current subprogram). @xref{Actions}, for information how to impose
731 additional formatting conventions on foreign code.
733 @defopt idlwave-main-block-indent (@code{0})
734 Extra indentation for the main block of code. That is the block between
735 the FUNCTION/PRO statement and the END statement for that program
739 @defopt idlwave-block-indent (@code{5})
740 Extra indentation applied to block lines. If you change this, you
741 probably also want to change @code{idlwave-end-offset}.
744 @defopt idlwave-end-offset (@code{-4})
745 Extra indentation applied to block END lines. A value equal to negative
746 @code{idlwave-block-indent} will make END lines line up with the block
750 @defopt idlwave-continuation-indent (@code{2})
751 Extra indentation applied to continuation lines and inside unbalanced
755 @node Comment Indentation, Continuation Lines, Code Indentation, Code Formatting
756 @subsection Comment Indentation
757 @cindex Comment indentation
758 @cindex Hanging paragraphs
759 @cindex Paragraphs, filling
760 @cindex Paragraphs, hanging
762 In IDL, lines starting with a @samp{;} are called @emph{comment lines}.
763 Comment lines are indented as follows:
765 @multitable @columnfractions .1 .90
767 @tab The indentation of lines starting with three semicolons remains
770 @tab Lines starting with two semicolons are indented like the surrounding code.
772 @tab Lines starting with a single semicolon are indent to a minimum column.
776 The indentation of comments starting in column 0 is never changed.
778 @defopt idlwave-no-change-comment
779 The indentation of a comment starting with this regexp will not be changed.
782 @defopt idlwave-begin-line-comment
783 A comment anchored at the beginning of line.
786 @defopt idlwave-code-comment
787 A comment that starts with this regexp is indented as if it is a part of
791 @node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting
792 @subsection Continuation Lines and Filling
793 @cindex Continuation lines
794 @cindex Line splitting
795 @cindex String splitting
796 @cindex Splitting, of lines
799 In IDL, a newline character terminates a statement unless preceded by a
800 @samp{$}. If you would like to start a continuation line, use
801 @kbd{M-@key{RET}} which calls the command @code{idlwave-split-line}. It
802 inserts a @samp{$} to indicate that the following line is a continuation
803 of the current line, terminates the line with a newline and indents the
804 new line. The command @kbd{M-@key{RET}} can also be used in the middle
805 of a line to split the line at that point. When used inside a long
806 string constant, the string is split with the @samp{+} concatenation
810 @cindex @code{auto-fill-mode}
811 @cindex Hanging paragraphs
812 When filling comment paragraphs, IDLWAVE overloads the normal filling
813 functions and uses a function which creates hanging paragraphs as they
814 are customary in the IDL routine headers. When @code{auto-fill-mode} is
815 turned on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If
816 the first line of a paragraph is matched by
817 @code{idlwave-hang-indent-regexp}, subsequent lines are indented to
818 after the position of this match, as in the following example.
822 ; x - an array containing
823 ; lots of interesting numbers.
825 ; y - another variable where
826 ; a hanging paragraph is used
831 You also refill a comment paragraph with @kbd{M-q}.
833 @defopt idlwave-fill-comment-line-only (@code{t})
834 Non-@code{nil} means auto fill will only operate on comment lines.
837 @defopt idlwave-auto-fill-split-string (@code{t})
838 Non-@code{nil} means auto fill will split strings with the IDL @samp{+}
842 @defopt idlwave-split-line-string (@code{t})
843 Non-@code{nil} means @code{idlwave-split-line} will split strings with
847 @defopt idlwave-hanging-indent (@code{t})
848 Non-@code{nil} means comment paragraphs are indented under the hanging
849 indent given by @code{idlwave-hang-indent-regexp} match in the first
850 line of the paragraph.
853 @defopt idlwave-hang-indent-regexp
854 Regular expression matching the position of the hanging indent
855 in the first line of a comment paragraph.
858 @defopt idlwave-use-last-hang-indent (@code{nil})
859 Non-@code{nil} means use last match on line for
860 @code{idlwave-indent-regexp}.
863 @node Syntax Highlighting, , Continuation Lines, Code Formatting
864 @subsection Syntax Highlighting
865 @cindex Syntax highlighting
866 @cindex Highlighting of syntax
869 Highlighting of keywords, comments, strings etc. can be accomplished
870 with @code{font-lock}. If you are using @code{global-font-lock-mode}
871 (on Emacs), or have @code{font-lock} turned on in any other buffer in
872 XEmacs, it should also automatically work in IDLWAVE buffers. If not,
873 you can enforce it with the following line in your @file{.emacs}
876 (add-hook 'idlwave-mode-hook 'turn-on-font-lock)
879 IDLWAVE supports 3 levels of syntax highlighting. The variable
880 @code{font-lock-maximum-decoration} determines which level is selected.
882 @defopt idlwave-default-font-lock-items
883 Items which should be fontified on the default fontification level
887 @node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode
888 @section Routine Info
890 @cindex Updating routine info
891 @cindex Scanning buffers for routine info
892 @cindex Buffers, scanning for routine info
893 @cindex Shell, querying for routine info
896 IDL defines more than one thousand procedures, functions and object
897 methods. This large command set makes it difficult to remember the
898 calling sequence and keywords of a command. IDLWAVE contains a list of
899 all builtin routines with calling sequences and keywords@footnote{This
900 list was created by scanning the IDL manual and might contain (very few)
901 errors. Please report any detected errors to the maintainer, so that
902 they can be fixed.}. It also scans Emacs buffers and library files for
903 routine definitions and queries the IDLWAVE-Shell for the properties of
904 modules currently compiled under the shell. This information is updated
905 automatically. If you think the information is not up-to-date, use
906 @kbd{C-c C-i} (@code{idlwave-update-routine-info}) to enforce a global
910 To display the information about a routine, press @kbd{C-c ?} which
911 calls the command @code{idlwave-routine-info}. When the current cursor
912 position is on the name or in the argument list of a procedure or
913 function, information will be displayed about the routine. For example,
914 consider the cursor positions in the following line
917 plot,x,alog(x+5*sin(x) + 2),
921 @cindex Default routine, for info and help
922 On positions 1,2 and 8, information about the @samp{plot} procedure will
923 be shown. On positions 3,4, and 7, the @samp{alog} function will be
924 described, while positions 5 and 6 will select the @samp{sin} function.
925 When you ask for routine information about an object method, and the
926 method exists in several classes, IDLWAVE queries for the class of the
929 @cindex Calling sequences
930 @cindex Keywords of a routine
931 @cindex Routine source information
932 The description displayed contains the calling sequence, the list of
933 keywords and the source location of this routine. It looks like this:
936 Usage: XMANAGER, NAME, ID
937 Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER
938 JUST_REG MODAL NO_BLOCK
939 Source: SystemLib [CSB] /soft1/idl53/lib/xmanager.pro
942 @cindex Categories, of routines
943 @cindex Load-path shadows
944 @cindex Shadows, load-path
945 @cindex IDL variable @code{!PATH}
946 @cindex @code{!PATH}, IDL variable
947 @cindex IDL variable @code{!DIR}
948 @cindex @code{!DIR}, IDL variable
950 If a definition of this routine exists in several files accessible to
951 IDLWAVE, several @samp{Source} lines will point to the different files.
952 This may indicate that your routine is shadowing a library routine,
953 which may or may not be what you want (@pxref{Load-Path Shadows}). The
954 information about the calling sequence and the keywords is derived from
955 the first source listed. Library routines can only be supported if you
956 have scanned the local IDL library (@pxref{Library Catalog}). The source
957 entry consists of a @emph{source category}, a set of @emph{flags} and
958 the path to the @emph{source file}. The following categories
961 @multitable @columnfractions .15 .85
963 @tab A system routine, but we do not know if it is @i{Builtin} or
964 @i{SystemLib}. When the system library has bee scanned
965 (@pxref{Library Catalog}), this category will automatically split into the
968 @tab A builtin routine with no source code available.
970 @tab A library routine in the official lib directory @file{!DIR/lib}.
972 @tab A library routine in the official lib directory @file{!DIR/lib/obsolete}.
974 @tab A file on IDL's search path @code{!PATH}.
976 @tab Any other file not known to be on the search path.
978 @tab The shell lists this routine as unresolved.
981 You can define additional categories based on the file name and path
982 with the variable @code{idlwave-special-lib-alist}.
984 @cindex Flags, in routine info
985 @cindex Duplicate routines
986 @cindex Multiply defined routines
987 @cindex Routine definitions, multiple
988 The flags @code{[CSB]} indicate if the file is known to IDLWAVE from the
989 library catalog (@w{@code{[C--]}}, @pxref{Library Catalog}), from the Shell
990 (@w{@code{[-S-]}}) or from an Emacs buffer (@w{@code{[--B]}}).
991 Combinations are possible. If a file contains multiple definitions of
992 the same routine, the file name will be prefixed with @samp{(Nx)} where
993 @samp{N} is the number of definitions.
995 @cindex Online Help from the routine info buffer
996 @cindex Active text, in routine info
997 @cindex Inserting keywords, from routine info
998 @cindex Source file, access from routine info
999 Some of the text in the @file{*Help*} buffer will be active (it
1000 highlights when you move the mouse over it). Clicking on these items
1001 will have the following effects:
1003 @multitable @columnfractions 0.15 0.85
1005 @tab If online help is installed, a click with the @emph{right} mouse
1006 button on the @i{Usage:} line will access the help for the
1007 routine (@pxref{Online Help}).
1009 @tab Online help about keywords is also available with the
1010 @emph{right} mouse button. Clicking on a keyword with the @emph{middle}
1011 mouse button will insert this keyword in the buffer from where
1012 @code{idlwave-routine-info} was called. Holding down @key{SHIFT} while
1013 clicking also adds the initial @samp{/}.
1015 @tab Clicking with the @emph{middle} mouse button on a @samp{Source} line
1016 finds the source file of the routine and visits it in another window.
1017 Another click on the same line switches back to the buffer from which
1018 @kbd{C-c ?} was called. If you use the @emph{right} mouse button, the
1019 source will not be visited by a buffer, but displayed in the online help
1022 @tab The @i{Classes} line is only included in the routine info window if
1023 the current class inherits from other classes. You can click with the
1024 @emph{middle} mouse button to display routine info about the current
1025 method in other classes on the inheritance chain.
1028 @defopt idlwave-resize-routine-help-window (@code{t})
1029 Non-@code{nil} means, resize the Routine-info @file{*Help*} window to
1033 @defopt idlwave-special-lib-alist
1034 Alist of regular expressions matching special library directories.
1037 @defopt idlwave-rinfo-max-source-lines (@code{5})
1038 Maximum number of source files displayed in the Routine Info window.
1043 @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode
1044 @section Online Help
1047 @cindex @file{idlw-help.txt}
1048 @cindex @file{idlw-help.el}
1049 @cindex IDL manual, ASCII version
1050 @cindex Installing online help
1051 @cindex Online Help, Installation
1052 @cindex Speed, of online help
1053 For IDL system routines, RSI provides extensive documentation. IDLWAVE
1054 can access an ASCII version of this documentation very quickly and
1055 accurately. This is @emph{much} faster than using the IDL online help
1056 application, also because usually IDLWAVE gets you to the right place in
1057 the docs directly, without additional browsing and scrolling. For this
1058 online help to work, you need an ASCII version of the IDL documentation
1059 which is not part of the standard IDLWAVE distribution. The required
1060 files can be downloaded from @uref{@value{IDLWAVE-HOMEPAGE}, the
1061 maintainers webpage}. As the text is extracted from PDF files, the
1062 formatting of the help text is good for normal text, but graphics and
1063 multiline equations will not be well represented. See also
1064 @ref{Documentation Scan}.
1066 @cindex Source code, as online help
1067 @cindex DocLib header, as online help
1068 For routines which are not documented in the IDL manual (for example
1069 your own routines), the source code is used as help text. If the
1070 requested information can be found in a (more or less) standard DocLib
1071 file header, IDLWAVE shows the header. Otherwise the routine definition
1072 statement (@code{pro}/@code{function}) is shown.
1075 In any IDL program, press @kbd{M-?} (@code{idlwave-context-help}) or
1076 click with @kbd{S-mouse-3} to access context sensitive online help. The
1077 following locations are recognized as context:
1079 @cindex Context, for online help
1080 @multitable @columnfractions .25 .75
1081 @item @i{Routine name}
1082 @tab The name of a routine (function, procedure, method).
1083 @item @i{Keyword Parameter}
1084 @tab Keyword parameter of a routine.
1085 @item @i{System Variable}
1086 @tab System variable like @code{!DPI}.
1087 @item @i{IDL Statement}
1088 @tab Like @code{PRO}, @code{REPEAT}, or @code{COMPILE_OPT}.
1089 @item @i{Class name}
1090 @tab Class name in @code{OBJ_NEW} call.
1091 @item @i{Executive Command}
1092 @tab Executive command like @code{.RUN}. Mostly useful in the shell.
1094 @tab The routine that would be selected for routine info display.
1097 @cindex @code{OBJ_NEW}, special online help
1098 Note that the @code{OBJ_NEW} function is special in that the help
1099 displayed depends on the cursor position: If the cursor is on the
1100 @samp{OBJ_NEW}, this function is described. If it is on the class name
1101 inside the quotes, the documentation for the class is pulled up. If the
1102 cursor is @emph{after} the class name, anywhere in the argument list,
1103 the documentation for the corresponding @code{Init} method and its
1104 keywords is targeted.
1106 @noindent Apart from source buffers, there are two more places from
1107 which online help can be accessed.
1111 Online help for routines and keywords can be accessed through the
1112 Routine Info display. Click with @kbd{mouse-3} on an item to see the
1113 corresponding help (@pxref{Routine Info}).
1115 When using completion and Emacs pops up a window with possible
1116 completions, clicking with @kbd{mouse-3} on a completion item invokes
1117 help on that item (@pxref{Completion}).
1120 In both cases, a blue face indicates that the item is documented in the
1125 @cindex Help application, keybindings
1126 @cindex Keybindings, in help application
1127 The help window is normally displayed in a separate frame. The
1128 following commands can be used to navigate inside the help system.
1130 @multitable @columnfractions .15 .85
1131 @item @kbd{@key{SPACE}}
1132 @tab Scroll forward one page.
1133 @item @kbd{@key{RET}}
1134 @tab Scroll forward one line.
1135 @item @kbd{@key{DEL}}
1136 @tab Scroll back one page.
1138 @tab Browse to the next or previous topic (in physical sequence).
1140 @tab Move back and forward through the help topic history.
1142 @tab Clear the history.
1144 @tab Follow a link. Active links are displayed in a different font.
1145 Items under @i{See Also} are active, and classes have links to their
1148 @tab Open a topic. The topic can be selected with completion.
1150 @tab Load the whole help file into Emacs, for global text searches.
1152 @tab Kill the help window.
1156 @noindent When the help text is a source file, the following commands
1158 @multitable @columnfractions .15 .85
1160 @tab Jump to DocLib Header of the routine whose source is displayed
1163 @tab Jump to the first DocLib Header in the file.
1164 @item @kbd{.} @r{(Dot)}
1165 @tab Jump back and forth between the routine definition (the
1166 @code{pro}/@code{function} statement) and the description of the help
1167 item in the DocLib header.
1169 @tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}.
1172 @defopt idlwave-help-directory
1173 The directory where idlw-help.txt and idlw-help.el are stored.
1176 @defopt idlwave-help-use-dedicated-frame (@code{t})
1177 Non-nil means, use a separate frame for Online Help if possible.
1180 @defopt idlwave-help-frame-parameters
1181 The frame parameters for the special Online Help frame.
1184 @defopt idlwave-max-popup-menu-items (@code{20})
1185 Maximum number of items per pane in popup menus.
1188 @defopt idlwave-extra-help-function
1189 Function to call for help if the normal help fails.
1192 @defopt idlwave-help-fontify-source-code (@code{nil})
1193 Non-nil means, fontify source code displayed as help.
1196 @defopt idlwave-help-source-try-header (@code{t})
1197 Non-nil means, try to find help in routine header when displaying source
1201 @defopt idlwave-help-link-face
1202 The face for links to IDLWAVE online help.
1205 @defopt idlwave-help-activate-links-agressively (@code{t})
1206 Non-@code{nil} means, make all possible links in help window active.
1209 @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode
1212 @cindex Keyword completion
1213 @cindex Method completion
1214 @cindex Object method completion
1215 @cindex Class name completion
1216 @cindex Function name completion
1217 @cindex Procedure name completion
1221 IDLWAVE offers completion for class names, routine names and keywords.
1222 As in many programming modes, completion is bound to @kbd{M-@key{TAB}}.
1223 Completion uses the same internal information as routine info, so when
1224 necessary it can be updated with @kbd{C-c C-i}
1225 (@code{idlwave-update-routine-info}).
1227 The completion function is context sensitive and figures out what to
1228 complete at point. Here are example lines and what @kbd{M-@key{TAB}}
1229 would try to complete when the cursor is on the position marked with a
1235 plot,xra* @r{Keyword of @code{plot} procedure}
1236 plot,x,y,/x* @r{Keyword of @code{plot} procedure}
1237 plot,min(* @r{Keyword of @code{min} function}
1238 obj -> a* @r{Object method (procedure)}
1239 a(2,3) = obj -> a* @r{Object method (function)}
1240 x = obj_new('IDL* @r{Class name}
1241 x = obj_new('MyCl',a* @r{Keyword to @code{Init} method in class @code{MyCl}}
1242 pro A* @r{Class name}
1243 pro * @r{Fill in @code{Class::} of first method in this file}
1244 !v* @r{System variable}
1245 !version.t* @r{Structure tag of system variable}
1246 self.g* @r{Class structure tag in methods}
1249 @cindex Scrolling the @file{*Completions*} window
1250 @cindex Completion, scrolling
1251 @cindex Completion, Online Help
1252 @cindex Online Help in @file{*Completions*} buffer
1253 If the list of completions is too long to fit in the
1254 @file{*Completions*} window, the window can be scrolled by pressing
1255 @kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each
1256 possible completion is available by clicking with @kbd{mouse-3} on the
1257 item. Items for which system online help (from the IDL manual) is
1258 available will be displayed in a different font. For other items, the
1259 corresponding source code or DocLib header is available as help text.
1261 @cindex Case of completed words
1262 @cindex Mixed case completion
1263 The case of the completed words is determined by what is already in the
1264 buffer. When the partial word being completed is all lower case, the
1265 completion will be lower case as well. If at least one character is
1266 upper case, the string will be completed in upper case or mixed case.
1267 The default is to use upper case for procedures, functions and keywords,
1268 and mixed case for object class names and methods, similar to the
1269 conventions in the IDL manuals. These defaults can be changed with the
1270 variable @code{idlwave-completion-case}.
1272 @defopt idlwave-completion-case
1273 Association list setting the case (UPPER/lower/Capitalized/...) of completed
1277 @defopt idlwave-completion-force-default-case (@code{nil})
1278 Non-@code{nil} means, completion will always honor the settings in
1279 @code{idlwave-completion-case}. When nil (the default), lower case
1280 strings will be completed to lower case.
1283 @defopt idlwave-complete-empty-string-as-lower-case (@code{nil})
1284 Non-@code{nil} means, the empty string is considered lower case for
1288 @defopt idlwave-keyword-completion-adds-equal (@code{t})
1289 Non-@code{nil} means, completion automatically adds @samp{=} after
1293 @defopt idlwave-function-completion-adds-paren (@code{t})
1294 Non-@code{nil} means, completion automatically adds @samp{(} after
1295 completed function. A value of `2' means, also add the closing
1296 parenthesis and position cursor between the two.
1299 @defopt idlwave-completion-restore-window-configuration (@code{t})
1300 Non-@code{nil} means, restore window configuration after successful
1304 @defopt idlwave-highlight-help-links-in-completion (@code{t})
1305 Non-nil means, highlight completions for which system help is available.
1308 @subsubheading Object Method Completion and Class Ambiguity
1309 @cindex Object methods
1310 @cindex Class ambiguity
1311 @cindex @code{self} object, default class
1312 An object method is not uniquely determined without the object's class.
1313 Since the class part is usually omitted in the source code, IDLWAVE
1314 considers all available methods in all classes as possible completions
1315 of an object method name. For keywords, the combined keywords of the
1316 current method in all available classes will be considered. In the
1317 @file{*Completions*} buffer, the classes allowed for each completion
1318 will be shown next to the item (see option
1319 @code{idlwave-completion-show-classes}). As a special case, the class
1320 of an object called @samp{self} object is always the class of the
1321 current routine. All classes it inherits from are considered as well
1324 @cindex Forcing class query.
1325 @cindex Class query, forcing
1326 You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u
1327 M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to
1328 narrow down the number of possible completions. The variable
1329 @code{idlwave-query-class} can be configured to make this behavior the
1330 default (not recommended). After you have specified the class
1331 for a particular statement (e.g. when completing the method), IDLWAVE
1332 can remember it for the rest of the editing session. Subsequent
1333 completions in the same statement (e.g. keywords) can then reuse this
1334 class information. Remembering the class works by placing a text
1335 property in the object operator @samp{->}. This is not enabled by
1336 default - the variable @code{idlwave-store-inquired-class} can be used
1339 @defopt idlwave-support-inheritance (@code{t})
1340 Non-@code{nil} means, treat inheritance with completion, online help etc.
1343 @defopt idlwave-completion-show-classes (@code{1})
1344 Non-@code{nil} means, show classes in @file{*Completions*} buffer when
1345 completing object methods and keywords.
1348 @defopt idlwave-completion-fontify-classes (@code{t})
1349 Non-@code{nil} means, fontify the classes in completions buffer.
1352 @defopt idlwave-query-class (@code{nil})
1353 Association list governing query for object classes during completion.
1356 @defopt idlwave-store-inquired-class (@code{nil})
1357 Non-@code{nil} means, store class of a method call as text property on
1361 @defopt idlwave-class-arrow-face
1362 Face to highlight object operator arrows @samp{->} which carry a class
1366 @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode
1368 @section Routine Source
1369 @cindex Routine source file
1370 @cindex Module source file
1371 @cindex Source file, of a routine
1373 Apart from clicking on a @i{Source:} line in the routine info window,
1374 there is also another way to find the source file of a routine. The
1375 command @kbd{C-c C-v} (@code{idlwave-find-module}) asks for a module
1376 name, offering the same default as @code{idlwave-routine-info} would
1377 have used. In the minibuffer, specify a complete routine name
1378 (including the class part). IDLWAVE will display the source file in
1381 @cindex Buffers, killing
1382 @cindex Killing autoloaded buffers
1383 Since getting the source of a routine into a buffer is so easy with
1384 IDLWAVE, too many buffers visiting different IDL source files are
1385 sometimes created. The special command @kbd{C-c C-k}
1386 (@code{idlwave-kill-autoloaded-buffers}) can be used to remove these
1389 @node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode
1390 @section Resolving Routines
1391 @cindex @code{RESOLVE_ROUTINE}
1392 @cindex Compiling library modules
1393 @cindex Routines, resolving
1395 The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve}
1396 and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL
1397 in order to resolve (compile) it. The default routine to be resolved is
1398 taken from context, but you get a chance to edit it.
1400 @code{idlwave-resolve} is one way to get a library module within reach
1401 of IDLWAVE's routine info collecting functions. A better way is to
1402 scan (parts of) the library (@pxref{Library Catalog}). Routine info on
1403 library modules will then be available without the need to compile the
1404 modules first, and even without a running shell.
1406 @xref{Sources of Routine Info}, for in-depth information where IDLWAVE
1407 collects data about routines, and how to update this information.
1410 @node Code Templates, Actions, Resolving Routines, The IDLWAVE Major Mode
1411 @section Code Templates
1412 @cindex Code templates
1413 @cindex Abbreviations
1416 IDLWAVE can insert IDL code templates into the buffer. For a few
1417 templates, this is done with direct keybindings:
1419 @multitable @columnfractions .15 .85
1421 @tab @code{CASE} statement template
1423 @tab @code{FOR} loop template
1425 @tab @code{REPEAT} loop template
1427 @tab @code{WHILE} loop template
1430 Otherwise, special abbreviations are used. Emacs abbreviations are
1431 expanded by typing text into the buffer and pressing @key{SPC} or
1432 @key{RET}. The special abbreviations used to insert code templates all
1433 start with a @samp{\} (the backslash). Here are a few examples of
1434 predefined abbreviations. For a full list, use @kbd{M-x
1435 idlwave-list-abbrevs}.
1437 @multitable @columnfractions .15 .85
1439 @tab @code{PROCEDURE} template
1441 @tab @code{FUNCTION} template
1443 @tab @code{CASE} statement template
1445 @tab @code{FOR} loop template
1447 @tab @code{REPEAT} loop template
1449 @tab @code{WHILE} loop template
1451 @tab @code{IF} statement template
1453 @tab @code{IF-ELSE} statement template
1458 The templates are expanded in upper or lower case, depending upon the
1459 variables @code{idlwave-abbrev-change-case} and
1460 @code{idlwave-reserved-word-upcase}.
1462 @defopt idlwave-abbrev-start-char (@code{"\"})
1463 A single character string used to start abbreviations in abbrev
1467 @defopt idlwave-abbrev-move (@code{t})
1468 Non-@code{nil} means the abbrev hook can move point, e.g. to end up
1469 between the parenthesis of a function call.
1472 @node Actions, Doc Header, Code Templates, The IDLWAVE Major Mode
1475 @cindex Coding standards, enforcing
1477 @emph{Actions} are special commands which are executed automatically
1478 while you write code in order to check the structure of the program or
1479 to enforce coding standards. Most actions which have been implemented
1480 in IDLWAVE are turned off by default, assuming that the average user
1481 wants her code the way she writes it. But if you are a lazy typist and
1482 want your code to adhere to certain standards, they can be
1485 Action can be applied in three ways:
1489 Some actions are applied directly while typing. For example, pressing
1490 @samp{=} can run a check to make sure that this operator is surrounded
1491 by spaces and insert these spaces if necessary. Pressing @key{SPC}
1492 after a reserved word can call a command to change the word to upper
1495 When a line is re-indented with @key{TAB}, actions can be applied to the
1496 entire line. To enable this, the variable @code{idlwave-do-actions}
1497 must be non-@code{nil}.
1499 @cindex Foreign code, adapting
1500 @cindex Actions, applied to foreign code
1501 Action can also be applied to a larger piece of code, e.g. in order to
1502 convert foreign code to your own style. To do this, mark the relevant
1503 part of the code and execute @kbd{M-x expand-region-abbrevs}. Useful
1504 marking commands are @kbd{C-x h} (the entire file) or @kbd{M-C-h} (the
1505 current subprogram). @xref{Code Indentation}, for information how to
1506 adjust the indentation of the code.
1509 @defopt idlwave-do-actions (@code{nil})
1510 Non-@code{nil} means performs actions when indenting.
1514 * Block Boundary Check:: Is the END correct
1515 * Padding Operators:: Enforcing space around `=' etc
1516 * Case Changes:: Enforcing upper case keywords
1519 @node Block Boundary Check, Padding Operators, Actions, Actions
1520 @subsection Block Boundary Check
1521 @cindex Block boundary check
1522 @cindex @code{END} type checking
1523 @cindex @code{END}, automatic insertion
1524 @cindex @code{END}, expanding
1525 @cindex Block, closing
1526 @cindex Closing a block
1528 Whenever you type an @code{END} statement, IDLWAVE finds the
1529 corresponding start of the block and the cursor blinks back to that
1530 location for a second. If you have typed a specific @code{END}, like
1531 @code{ENDIF} or @code{ENDCASE}, you get a warning if that kind of END
1532 does not match the type of block it terminates.
1534 Set the variable @code{idlwave-expand-generic-end} in order to have all
1535 generic @code{END} statements automatically expanded to a specific type.
1536 You can also type @kbd{C-c ]} to close the current block by inserting
1537 the appropriate @code{END} statement.
1539 @defopt idlwave-show-block (@code{t})
1540 Non-@code{nil} means point blinks to block beginning for
1541 @code{idlwave-show-begin}.
1544 @defopt idlwave-expand-generic-end (@code{t})
1545 Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc.
1548 @defopt idlwave-reindent-end (@code{t})
1549 Non-nil means re-indent line after END was typed.
1552 @node Padding Operators, Case Changes, Block Boundary Check, Actions
1553 @subsection Padding Operators
1554 @cindex Padding operators with spaces
1555 @cindex Operators, padding with spaces
1556 @cindex Space, around operators
1558 Some operators can be automatically surrounded by spaces. This can
1559 happen when the operator is typed, or also later when the line is
1560 indented. IDLWAVE contains this setting for the operators @samp{&},
1561 @samp{<}, @samp{>}, @samp{,}, @samp{=}, and @samp{->}@footnote{Operators
1562 longer than one character can only be padded during line indentation.},
1563 but the feature is turned off by default. If you want to turn it on,
1564 customize the variables @code{idlwave-surround-by-blank} and
1565 @code{idlwave-do-actions}. You can also define similar actions for
1566 other operators by using the function @code{idlwave-action-and-binding}
1567 in the mode hook. For example, to enforce space padding of the @samp{+}
1568 and @samp{*} operators, try this in @file{.emacs}
1571 (add-hook 'idlwave-mode-hook
1573 (setq idlwave-surround-by-blank t) ; Turn this type of actions on
1574 (idlwave-action-and-binding "*" '(idlwave-surround 1 1))
1575 (idlwave-action-and-binding "+" '(idlwave-surround 1 1))))
1578 @defopt idlwave-surround-by-blank (@code{nil})
1579 Non-@code{nil} means, enable @code{idlwave-surround}. If non-nil,
1580 @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are
1581 surrounded with spaces by @code{idlwave-surround}.
1584 @defopt idlwave-pad-keyword (@code{t})
1585 Non-@code{nil} means pad @samp{=} for keywords like assignments.
1588 @node Case Changes, , Padding Operators, Actions
1589 @subsection Case Changes
1590 @cindex Case changes
1591 @cindex Upcase, enforcing for reserved words
1592 @cindex Downcase, enforcing for reserved words
1594 Actions can be used to change the case of reserved words or expanded
1595 abbreviations by customizing the variables
1596 @code{idlwave-abbrev-change-case} and
1597 @code{idlwave-reserved-word-upcase}. If you want to change the case of
1598 additional words automatically, put something like the following into
1599 your @file{.emacs} file:
1602 (add-hook 'idlwave-mode-hook
1604 ;; Capitalize system vars
1605 (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t)
1606 ;; Capitalize procedure name
1607 (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"
1608 '(capitalize-word 1) t)
1609 ;; Capitalize common block name
1610 (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"
1611 '(capitalize-word 1) t)))
1614 For more information, see the documentation string for the function
1615 @code{idlwave-action-and-binding}.
1617 @defopt idlwave-abbrev-change-case (@code{nil})
1618 Non-@code{nil} means all abbrevs will be forced to either upper or lower
1619 case. Legal values are @code{nil}, @code{t}, and @code{down}.
1622 @defopt idlwave-reserved-word-upcase (@code{nil})
1623 Non-@code{nil} means, reserved words will be made upper case via abbrev
1628 @node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode
1629 @section Documentation Header
1630 @cindex Documentation header
1631 @cindex DocLib header
1632 @cindex Modification timestamp
1633 @cindex Header, for file documentation
1634 @cindex Timestamp, in doc header.
1635 @cindex Changelog, in doc header.
1639 The command @kbd{C-c C-h} inserts a standard routine header into the
1640 buffer, with the usual fields for documentation. One of the keywords is
1641 @samp{MODIFICATION HISTORY} under which the changes to a routine can be
1642 recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION
1643 HISTORY} of the current routine or file and inserts the user
1644 name with a timestamp.
1646 @defopt idlwave-file-header
1647 The doc-header template or a path to a file containing it.
1650 @defopt idlwave-timestamp-hook
1651 The hook function used to update the timestamp of a function.
1654 @defopt idlwave-doc-modifications-keyword
1655 The modifications keyword to use with the log documentation commands.
1658 @defopt idlwave-doclib-start
1659 Regexp matching the start of a document library header.
1662 @defopt idlwave-doclib-end
1663 Regexp matching the start of a document library header.
1666 @node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode
1667 @section Motion Commands
1668 @cindex Motion commands
1669 @cindex Program structure, moving through
1670 @cindex Code structure, moving through
1671 @cindex @file{Func-menu}, XEmacs package
1672 @cindex @file{Imenu}, Emacs package
1673 @cindex Function definitions, jumping to
1674 @cindex Procedure definitions, jumping to
1676 IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages
1677 which make it easy to jump to the definitions of functions and
1678 procedures in the current file.
1680 Several commands allow to move quickly through the structure of an IDL
1683 @multitable @columnfractions .15 .85
1685 @tab Beginning of subprogram
1687 @tab End of subprogram
1689 @tab Beginning of block (stay inside the block)
1691 @tab End of block (stay inside the block)
1693 @tab Forward block (on same level)
1695 @tab Backward block (on same level)
1697 @tab Down block (enters a block)
1699 @tab Backward up block (leaves a block)
1705 @node Misc Options, , Motion Commands, The IDLWAVE Major Mode
1706 @section Miscellaneous Options
1709 @defopt idlwave-help-application
1710 The external application providing reference help for programming.
1713 @defopt idlwave-startup-message (@code{t})
1714 Non-@code{nil} means display a startup message when @code{idlwave-mode}'
1718 @defopt idlwave-mode-hook
1719 Normal hook. Executed when a buffer is put into @code{idlwave-mode}.
1722 @defopt idlwave-load-hook
1723 Normal hook. Executed when @file{idlwave.el} is loaded.
1741 @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top
1742 @chapter The IDLWAVE Shell
1743 @cindex IDLWAVE shell
1744 @cindex Major mode, @code{idlwave-shell-mode}
1745 @cindex IDL, as Emacs subprocess
1746 @cindex Subprocess of Emacs, IDL
1747 @cindex Comint, Emacs package
1752 The IDLWAVE shell is an Emacs major mode which allows to run the IDL
1753 program as an inferior process of Emacs. It can be used to work with
1754 IDL interactively, to compile and run IDL programs in Emacs buffers and
1755 to debug these programs. The IDLWAVE shell uses @file{comint}, an Emacs
1756 packages which handles the communication with the IDL program.
1757 Unfortunately IDL for Windows and MacOS does not allow the interaction
1758 with Emacs@footnote{Please inform the maintainer if you come up with a way
1759 to make the IDLWAVE shell work on these systems.} - so the IDLWAVE shell
1760 only works under Unix.
1763 * Starting the Shell:: How to launch IDL as a subprocess
1764 * Using the Shell:: Interactively working with the Shell
1765 * Debugging IDL Programs:: Compilation/Debugging
1768 @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell
1769 @section Starting the Shell
1770 @cindex Starting the shell
1771 @cindex Shell, starting
1772 @cindex Dedicated frame, for shell buffer
1773 @cindex Frame, for shell buffer
1774 @cindex Subprocess of Emacs, IDL
1777 The IDLWAVE shell can be started with the command @kbd{M-x
1778 idlwave-shell}. In @code{idlwave-mode} the function is bound to
1779 @kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to
1780 interact with the shell. If the shell is already running, @kbd{C-c C-s}
1781 will simple switch to the shell buffer. The command @kbd{C-c C-l}
1782 (@code{idlwave-shell-recenter-shell-window}) displays the
1783 shell window without selecting it.
1785 In order to create a separate frame for the IDLWAVE shell buffer, call
1786 @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or
1787 @kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell
1788 window, configure the variable
1789 @code{idlwave-shell-use-dedicated-frame}.
1791 The shell can also be started automatically when another command tries
1792 to send a command to it. To enable auto start, set the variable
1793 @code{idlwave-shell-automatic-start} to @code{t}.
1795 @defopt idlwave-shell-explicit-file-name
1796 This is the command to run IDL.
1799 @defopt idlwave-shell-command-line-options
1800 A list of command line options for calling the IDL program.
1803 @defopt idlwave-shell-prompt-pattern
1804 Regexp to match IDL prompt at beginning of a line.
1807 @defopt idlwave-shell-process-name
1808 Name to be associated with the IDL process.
1811 @defopt idlwave-shell-automatic-start
1812 Non-@code{nil} means attempt to invoke idlwave-shell if not already
1816 @defopt idlwave-shell-initial-commands
1817 Initial commands, separated by newlines, to send to IDL.
1820 @defopt idlwave-shell-use-dedicated-frame (@code{nil})
1821 Non-@code{nil} means, IDLWAVE should use a special frame to display
1825 @defopt idlwave-shell-frame-parameters
1826 The frame parameters for a dedicated idlwave-shell frame.
1829 @defopt idlwave-shell-temp-pro-prefix
1830 The prefix for temporary IDL files used when compiling regions.
1834 @defopt idlwave-shell-mode-hook
1835 Hook for customizing @code{idlwave-shell-mode}.
1838 @node Using the Shell, Debugging IDL Programs, Starting the Shell, The IDLWAVE Shell
1839 @section Using the Shell
1841 @cindex Shell, basic commands
1843 The IDLWAVE shell works in the same fashion as other shell modes in
1844 Emacs. It provides command history, command line editing and job
1845 control. The @key{UP} and @key{DOWN} arrows cycle through the input
1846 history just like in an X terminal@footnote{This is different from
1847 normal Emacs/Comint behavior, but more like an xterm. If you prefer the
1848 default comint functionality, check the variable
1849 @code{idlwave-shell-arrows-do-history}.}. Here is a list of
1850 commonly used commands.
1852 @multitable @columnfractions .12 .88
1854 @tab Cycle backwards in input history
1856 @tab Cycle forwards in input history
1858 @tab Cycle backwards in input history @emph{matching input}
1860 @tab Cycle forwards in input history @emph{matching input}
1862 @tab Previous input matching a regexp
1864 @tab Next input that matches a regexp
1866 @tab Send input or copy line to current prompt
1868 @tab Beginning of line; skip prompt
1870 @tab Kill input to beginning of line
1872 @tab Kill word before cursor
1880 @tab Delete last batch of process output
1882 @tab Show last batch of process output
1884 @tab List input history
1887 In addition to these standard @file{comint} commands,
1888 @code{idlwave-shell-mode} provides many of the commands which simplify
1889 writing IDL code, including abbreviations, online help, and completion.
1890 See @ref{Routine Info} and @ref{Online Help} and @ref{Completion} for more
1891 information on these commands.
1893 @cindex Completion, in the shell
1894 @cindex Routine info, in the shell
1895 @cindex Online Help, in the shell
1896 @multitable @columnfractions .12 .88
1897 @item @kbd{@key{TAB}}
1898 @tab Completion of file names, routine names and keywords
1899 (@code{idlwave-shell-complete})
1900 @item @kbd{M-@key{TAB}}
1901 @tab Same as @key{TAB}
1903 @tab Routine Info display (@code{idlwave-routine-info})
1905 @tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp})
1907 @tab Update routine info from buffers and shell
1908 (@code{idlwave-update-routine-info})
1910 @tab Find the source file of a routine (@code{idlwave-find-module})
1912 @tab Compile a library routine (@code{idlwave-resolve})
1915 @defopt idlwave-shell-arrows-do-history (@code{t})
1916 Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command
1920 @defopt idlwave-shell-comint-settings
1921 Alist of special settings for the comint variables in the IDLWAVE Shell.
1924 @defopt idlwave-shell-file-name-chars
1925 The characters allowed in file names, as a string. Used for file name
1929 @defopt idlwave-shell-graphics-window-size
1930 Size of IDL graphics windows popped up by special IDLWAVE command.
1934 @cindex Character input mode (Shell)
1935 @cindex Line input mode (Shell)
1936 @cindex Magic spells, for input mode
1937 @cindex Spells, magic
1938 IDLWAVE works in line input mode: You compose a full command line, using
1939 all the power Emacs gives you to do this. When you press @key{RET}, the
1940 whole line is sent to IDL. Sometimes it is necessary to send single
1941 characters (without a newline), for example when an IDL program is
1942 waiting for single character input with the @code{GET_KBRD} function.
1943 You can send a single character to IDL with the command @kbd{C-c C-x}
1944 (@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y}
1945 (@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop
1946 which accepts characters and immediately sends them to IDL. The loop
1947 can be exited with @kbd{C-g}. It terminates also automatically when the
1948 current IDL command is finished. Check the documentation of the two
1949 variables described below for a way to make IDL programs trigger
1950 automatic switches of the input mode.
1952 @defopt idlwave-shell-use-input-mode-magic (@code{nil})
1953 Non-nil means, IDLWAVE should check for input mode spells in output.
1956 @defopt idlwave-shell-input-mode-spells
1957 The three regular expressions which match the magic spells for input
1961 @node Debugging IDL Programs, , Using the Shell, The IDLWAVE Shell
1962 @section Debugging IDL Programs
1964 @cindex Keybindings for debugging
1968 Programs can be compiled, run, and debugged directly from the source
1969 buffer in Emacs. The IDLWAVE shell installs keybindings both in the
1970 shell buffer and in all IDL code buffers of the current Emacs session.
1971 On Emacs versions which support this, it also installs a debugging
1972 toolbar. The display of the toolbar can be toggled with @kbd{C-c C-d
1973 C-t} (@code{idlwave-shell-toggle-toolbar}).
1975 The debugging keybindings are by default on the prefix key @kbd{C-c
1976 C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d
1977 C-b}, compiling a source file with @kbd{C-c C-d C-c}. If you find this
1978 too much work you can choose a combination of modifier keys which is not
1979 used by other commands. For example, if you write in @file{.emacs}
1982 (setq idlwave-shell-debug-modifiers '(control shift))
1985 a breakpoint can be set by pressing @kbd{b} while holding down
1986 @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a
1987 source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}
1988 etc. In the remainder of this chapter we will assume that the @kbd{C-c
1989 C-d} bindings are active, but each of these bindings will have an
1990 equivalent single-keypress shortcut with the modifiers given in the
1991 @code{idlwave-shell-debug-modifiers} variable.
1993 @defopt idlwave-shell-prefix-key (@kbd{C-c C-d})
1994 The prefix key for the debugging map
1995 @code{idlwave-shell-mode-prefix-map}.
1998 @defopt idlwave-shell-activate-prefix-keybindings (@code{t})
1999 Non-@code{nil} means, debug commands will be bound to the prefix
2000 key, like @kbd{C-c C-d C-b}.
2003 @defopt idlwave-shell-debug-modifiers (@code{nil})
2004 List of modifier keys to use for binding debugging commands in the shell
2005 and in source buffers.
2008 @defopt idlwave-shell-use-toolbar (@code{t})
2009 Non-@code{nil} means, use the debugging toolbar in all IDL related
2015 * Compiling Programs:: Compiling buffers under the shell
2016 * Breakpoints and Stepping:: Deciding where to stop and look
2017 * Walking the Calling Stack:: From where was this routine called?
2018 * Examining Variables:: What is the value now?
2021 @node Compiling Programs, Breakpoints and Stepping, Debugging IDL Programs, Debugging IDL Programs
2022 @subsection Compiling Programs
2023 @cindex Compiling programs
2024 @cindex Programs, compiling
2025 @cindex Default command line, executing
2026 @cindex Executing a default command line
2029 In order to compile the current buffer under the IDLWAVE shell, press
2030 @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the
2031 current buffer and then send the command @samp{.run path/to/file} to the
2032 shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in
2033 which case the most recently compiled buffer will be saved and
2036 When developing or debugging a program, it is often necessary to execute
2037 the same command line many times. A convenient way to do this is
2038 @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}).
2039 This command first resets IDL from a state of interrupted execution by
2040 closing all files and returning to the main interpreter level. Then a
2041 default command line is send to the shell. To edit the default command
2042 line, call @code{idlwave-shell-execute-default-command-line} with a
2043 prefix argument: @kbd{C-u C-c C-d C-y}.
2045 @defopt idlwave-shell-mark-stop-line (@code{t})
2046 Non-@code{nil} means, mark the source code line where IDL is currently
2047 stopped. The value decides about the preferred method. Legal values
2048 are @code{nil}, @code{t}, @code{arrow}, and @code{face}.
2051 @defopt idlwave-shell-overlay-arrow (@code{">"})
2052 The overlay arrow to display at source lines where execution
2056 @defopt idlwave-shell-stop-line-face
2057 The face which highlights the source line where IDL is
2061 @node Breakpoints and Stepping, Walking the Calling Stack, Compiling Programs, Debugging IDL Programs
2062 @subsection Breakpoints and Stepping
2065 @cindex Execution, controlled
2069 You can set breakpoints and step through a program with IDLWAVE.
2070 Setting a breakpoint in the current line of the source buffer is done
2071 with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a prefix
2072 arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}, the breakpoint gets a @code{/ONCE}
2073 keyword, meaning that it will be deleted after first use. With a
2074 numeric prefix greater than one, the breakpoint will only be active the
2075 @code{nth} time it is hit. To clear the breakpoint in the current line,
2076 use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When executed
2077 from the shell window, the breakpoint where IDL is currently stopped
2078 will be deleted. To clear all breakpoints, use @kbd{C-c C-d C-a}
2079 (@code{idlwave-clear-all-bp}). Breakpoint lines are highlighted in the
2082 Once the program has stopped somewhere, you can step through it. The
2083 most important stepping commands are @kbd{C-c C-d C-s} to execute one
2084 line of IDL code; @kbd{C-c C-d C-n} to do one step but treat procedure
2085 and function calls as a single step; @kbd{C-c C-d C-h} to continue
2086 execution to the line where the cursor is in and @kbd{C-c C-d C-r} to
2087 continue execution. Here is a summary of the breakpoint and stepping
2090 @multitable @columnfractions .23 .77
2091 @item @kbd{C-c C-d C-b}
2092 @tab Set breakpoint (@code{idlwave-shell-break-here})
2093 @item @kbd{C-c C-d C-i}
2094 @tab Set breakpoint in function named here (@code{idlwave-shell-break-in})
2095 @item @kbd{C-c C-d C-d}
2096 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})
2097 @item @kbd{C-c C-d C-a}
2098 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})
2099 @item @kbd{C-c C-d C-s}
2100 @tab Step, into function calls (@code{idlwave-shell-step})
2101 @item @kbd{C-c C-d C-n}
2102 @tab Step, over function calls (@code{idlwave-shell-stepover})
2103 @item @kbd{C-c C-d C-k}
2104 @tab Skip one statement (@code{idlwave-shell-skip})
2105 @item @kbd{C-c C-d C-u}
2106 @tab Continue to end of block (@code{idlwave-shell-up})
2107 @item @kbd{C-c C-d C-m}
2108 @tab Continue to end of function (@code{idlwave-shell-return})
2109 @item @kbd{C-c C-d C-o}
2110 @tab Continue past end of function (@code{idlwave-shell-out})
2111 @item @kbd{C-c C-d C-h}
2112 @tab Continue to line at cursor position (@code{idlwave-shell-to-here})
2113 @item @kbd{C-c C-d C-r}
2114 @tab Continue execution to next breakpoint (@code{idlwave-shell-cont})
2115 @item @kbd{C-c C-d C-up}
2116 @tab Show higher level in calling stack (@code{idlwave-shell-stack-up})
2117 @item @kbd{C-c C-d C-down}
2118 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down})
2121 @defopt idlwave-shell-mark-breakpoints (@code{t})
2122 Non-@code{nil} means, mark breakpoints in the source file buffers. The
2123 value indicates the preferred method. Legal values are @code{nil},
2124 @code{t}, @code{face}, and @code{glyph}.
2127 @defopt idlwave-shell-breakpoint-face
2128 The face for breakpoint lines in the source code if
2129 @code{idlwave-shell-mark-breakpoints} has the value @code{face}.
2132 @node Walking the Calling Stack, Examining Variables, Breakpoints and Stepping, Debugging IDL Programs
2133 @subsection Walking the Calling Stack
2134 @cindex Calling stack, walking
2136 When debugging a program, it can be very useful to check in what context
2137 the current routine was called, and why the arguments of the call are
2138 the way they are. For this one needs to examine the calling stack. If
2139 execution is stopped somewhere deep in a program, you can use the
2140 commands @kbd{C-c C-d C-@key{UP}} (@code{idlwave-shell-stack-up}) and
2141 @kbd{C-c C-d C-@key{DOWN}} (@code{idlwave-shell-stack-down}) or the
2142 corresponding toolbar buttons to move through the calling stack. The
2143 mode line of the shell window will indicate where you are on the stack
2144 with a token like @samp{[-3:MYPRO]}, and the line of IDL code which did
2145 the current call will be highlighted. When you continue execution,
2146 IDLWAVE will automatically return to the current level. @xref{Examining
2147 Variables} for information how to examine the value of variables and
2148 expressions on higher calling stack levels.
2150 @node Examining Variables, , Walking the Calling Stack, Debugging IDL Programs
2151 @subsection Examining Variables
2152 @cindex @code{PRINT} expressions
2153 @cindex @code{HELP}, on expressions
2154 @cindex Expressions, printing
2155 @cindex Expressions, help
2156 @cindex Printing expressions
2157 @cindex Mouse binding to print expressions
2160 When execution is stopped you can examine the values of variables. The
2161 command @kbd{C-c C-d C-p} prints the expression at point, while @kbd{C-c
2162 C-d ?} shows help on this expression. The expression at point is an
2163 array expression or a function call, or the contents of a pair of
2164 parenthesis. The selected expression becomes highlighted in the source
2165 code for a short time. Calling the above commands with a prefix
2166 argument will prompt for an expression instead of using the one at
2169 It is very convenient to click with the mouse on expressions to retrieve
2170 their value. Use @kbd{S-mouse-2} to print an expression and
2171 @kbd{C-S-mouse-2} to get help on an expression. I.e. you need to hold
2172 down @key{SHIFT} and @key{CONTROL} while clicking with the middle mouse
2175 @cindex Printing expressions, on calling stack
2176 @cindex Restrictions for expression printing
2177 Printing of expressions also works on higher levels of the calling
2178 stack. This means that you can examine the values of variables and
2179 expressions inside the routine which called the current routine etc.
2180 @xref{Walking the Calling Stack} for information on how to step back to
2181 higher levels on the calling stack. Commands which print values of
2182 variables and expressions will then use the values of variables in the
2183 calling routine. The following restrictions apply for all levels except
2188 Array expressions must use the @samp{[ ]} index delimiters. Identifiers
2189 with a @samp{( )} will be interpreted as function calls.
2191 @cindex ROUTINE_NAMES, IDL procedure
2192 Printing values of expressions on higher levels of the calling stack
2193 uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, which may
2194 or may not be available in future versions of IDL.
2197 @defopt idlwave-shell-expression-face
2198 The face for @code{idlwave-shell-expression-overlay}.
2199 Allows you to choose the font, color and other properties for
2200 the expression printed by IDL.
2203 @defopt idlwave-shell-print-expression-function (@code{nil})
2204 A function to handle special display of evaluated expressions.
2207 @node Installation, Acknowledgement, The IDLWAVE Shell, Top
2208 @chapter Installation
2209 @cindex Installation
2212 * Installing IDLWAVE:: How to install the distribution
2213 * Installing Online Help:: Where to get the additional files needed
2214 * Upgrading from idl.el:: Necessary configuration changes
2217 @node Installing IDLWAVE, Installing Online Help, Installation, Installation
2218 @section Installing IDLWAVE
2221 @cindex URL, homepage for IDLWAVE
2222 @cindex Homepage for IDLWAVE
2223 @cindex IDLWAVE, homepage
2224 @cindex XEmacs package IDLWAVE
2225 @cindex Emacs, distributed with IDLWAVE
2226 @cindex Copyright, of IDL manual
2227 IDLWAVE is part of Emacs 21.1 and later. It is also an XEmacs package
2228 and can be installed from
2229 @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site}
2230 with the normal package management system on XEmacs 21. These
2231 pre-installed versions should work out-of-the-box. However, the files
2232 needed for online help are not distributed with XEmacs/Emacs and have to
2233 be installed separately@footnote{Due to copyright reasons, the ASCII
2234 version of the IDL manual cannot be distributed under the GPL.}
2235 (@pxref{Installing Online Help}).
2237 You can also download IDLWAVE and install it yourself from
2238 @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. Follow the
2239 instructions in the INSTALL file.
2241 @node Installing Online Help, Upgrading from idl.el , Installing IDLWAVE, Installation
2242 @section Installing Online Help
2243 @cindex Installing online help
2244 @cindex Online Help, Installation
2246 If you want to use the online help display, two additional files (an
2247 ASCII version of the IDL documentation and a topics/code file) must be
2248 installed. These files can also be downloaded from
2249 @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. You need to
2250 place the files somewhere on your system and tell IDLWAVE where they are
2254 (setq idlwave-help-directory "/path/to/help/files/")
2257 @node Upgrading from idl.el, , Installing Online Help, Installation
2258 @section Upgrading from the old @b{@file{idl.el}} file
2259 @cindex Upgrading from old @b{@file{idl.el}}
2260 @cindex Renaming old variables
2261 @cindex Old variables, renaming
2264 If you have been using the old @file{idl.el} and @file{idl-shell.el}
2265 files and would like to use IDLWAVE, you need to update your
2266 customization in @file{.emacs}.
2270 Change all variable and function prefixes from @samp{idl-} to @samp{idlwave-}.
2272 Remove the now invalid @code{autoload} and @code{auto-mode-alist} forms
2273 pointing to the @file{idl.el} and @file{idl-shell.el} files. Install
2274 the new autoload forms.
2276 If you have been using the hook function recommended in earlier versions
2277 to get a separate frame for the IDL shell, remove that command from your
2278 @code{idlwave-shell-mode-hook}. Instead, set the variable
2279 @code{idlwave-shell-use-dedicated-frame} with
2281 (setq idlwave-shell-use-dedicated-frame t)
2284 The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character.
2285 Like in in many other Emacs modes, @kbd{M-@key{TAB}} now does
2286 completion. Inserting a TAB has therefore been moved to
2287 @kbd{C-@key{TAB}}. On a character based terminal you can also use
2288 @kbd{C-c @key{SPC}}.
2291 @node Acknowledgement, Sources of Routine Info, Installation, Top
2292 @chapter Acknowledgement
2293 @cindex Acknowledgement
2294 @cindex Maintainer, of IDLWAVE
2295 @cindex Authors, of IDLWAVE
2296 @cindex Contributors, to IDLWAVE
2297 @cindex Email address, of Maintainer
2301 The main contributors to the IDLWAVE package have been:
2305 @uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author.
2306 Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them
2310 @uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}}, current author
2311 and maintainer. I have been in charge of the package since version
2312 3.0. I am also responsible for the manual.
2315 @uref{mailto:jdsmith@@astrosun.tn.cornell.edu, @b{J.D. Smith}} has
2316 shaped Object method completion and most new features in version 4.0
2317 with his ideas, bug reports, and patient explanations of IDL internals.
2321 The following people have also contributed to the development of IDLWAVE
2322 with patches, ideas, bug reports and suggestions.
2326 Ulrik Dickow <dickow@@nbi.dk>
2328 Eric E. Dors <edors@@lanl.gov>
2330 Stein Vidar H. Haugan <s.v.h.haugan@@astro.uio.no>
2332 David Huenemoerder <dph@@space.mit.edu>
2334 Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de>
2336 Xuyong Liu <liu@@stsci.edu>
2338 Simon Marshall <Simon.Marshall@@esrin.esa.it>
2340 Craig Markwardt <craigm@@cow.physics.wisc.edu>
2342 Laurent Mugnier <mugnier@@onera.fr>
2344 Lubos Pochman <lubos@@rsinc.com>
2346 Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov>
2348 Marty Ryba <ryba@@ll.mit.edu>
2350 Phil Williams <williams@@irc.chmcc.org>
2352 Phil Sterne <sterne@@dublin.llnl.gov>
2358 @node Sources of Routine Info, Configuration Examples, Acknowledgement, Top
2359 @appendix Sources of Routine Info
2361 @cindex Sources of routine information
2362 In @ref{Routine Info} and @ref{Completion} it was shown how IDLWAVE
2363 displays the calling sequence and keywords of routines, and how it
2364 completes routine names and keywords. For these features to work,
2365 IDLWAVE must know about the accessible routines.
2368 * Routine Definitions:: Where IDL Routines are defined.
2369 * Routine Information Sources:: So how does IDLWAVE know about...
2370 * Library Catalog:: Scanning the Libraries for Routine Info
2371 * Load-Path Shadows:: Routines defined in several places
2372 * Documentation Scan:: Scanning the IDL Manuals
2375 @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info
2376 @section Routine Definitions
2377 @cindex Routine definitions
2378 @cindex IDL variable @code{!PATH}
2379 @cindex @code{!PATH}, IDL variable
2380 @cindex @code{CALL_EXTERNAL}, IDL routine
2381 @cindex @code{LINKIMAGE}, IDL routine
2382 @cindex External routines
2384 Routines which can be used in an IDL program can be defined in several
2389 @emph{Builtin routines} are defined inside IDL itself. The source
2390 code of such routines is not accessible to the user.
2392 Routines @emph{part of the current program} are defined in a file which
2393 is explicitly compiled by the user. This file may or may not be located
2394 on the IDL search path.
2396 @emph{Library routines} are defined in special files which are located
2397 somewhere on IDL's search path. When a library routine is called for
2398 the first time, IDL will find the source file and compile it
2401 External routines written in other languages (like Fortran or C) can be
2402 called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE},
2403 or included as dynamically loaded modules (DLMs). Currently IDLWAVE
2404 cannot provide routine info and completion for external
2408 @node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info
2409 @section Routine Information Sources
2410 @cindex Routine info sources
2411 @cindex Builtin list of routines
2412 @cindex Updating routine info
2413 @cindex Scanning buffers for routine info
2414 @cindex Buffers, scanning for routine info
2415 @cindex Shell, querying for routine info
2417 In oder to know about as many routines as possible, IDLWAVE will do the
2418 following to collect information:
2423 It has a @emph{builtin list} with the properties of the builtin IDL
2424 routines. IDLWAVE @value{VERSION} is distributed with a list of
2425 @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords,
2426 reflecting IDL version @value{IDLVERSION}. This list has been created
2427 by scanning the IDL manuals and is stored in the file
2428 @file{idlw-rinfo.el}. @xref{Documentation Scan}, for
2429 information how to regenerate this file for new versions of IDL.
2432 It @emph{scans} all @emph{buffers} of the current Emacs session for
2433 routine definitions. This is done automatically when routine
2434 information or completion is first requested by the user. Each new
2435 buffer and each buffer which is saved after making changes is also
2436 scanned. The command @kbd{C-c C-i} (@code{idlwave-update-routine-info})
2437 can be used at any time to rescan all buffers.
2440 If you have an IDLWAVE-Shell running as inferior process of the current
2441 Emacs session, IDLWAVE will @emph{query the shell} for compiled routines
2442 and their arguments. This happens automatically when routine
2443 information or completion is first requested by the user, and each time
2444 an Emacs buffer is compiled with @kbd{C-c C-d C-c}. The command
2445 @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used to ask
2446 the shell again at any time.
2449 IDLWAVE can scan all or selected library files and store the result in a
2450 file which will be automatically loaded just like
2451 @file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to
2455 @defopt idlwave-scan-all-buffers-for-routine-info (@code{t})
2456 Non-@code{nil} means, scan all buffers for IDL programs when updating
2460 @defopt idlwave-query-shell-for-routine-info (@code{t})
2461 Non-@code{nil} means query the shell for info about compiled routines.
2464 @defopt idlwave-auto-routine-info-updates
2465 Controls under what circumstances routine info is updated automatically.
2468 @node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
2469 @section Library Catalog
2470 @cindex Library scan
2471 @cindex Library catalog
2472 @cindex IDL library routine info
2476 @cindex IDL variable @code{!DIR}
2477 @cindex @code{!DIR}, IDL variable
2480 IDLWAVE can extract routine information from library modules and store
2481 that information in a file. To do this, the variable
2482 @code{idlwave-libinfo-file} needs to contain the path to a file in an
2483 existing directory (the default is @code{"~/.idlcat.el"}). Since the
2484 file will contain lisp code, its name should end in @file{.el}. Under
2485 Windows and MacOS, you also need to specify the search path for IDL
2486 library files in the variable @code{idlwave-library-path}, and the
2487 location of the IDL directory (the value of the @code{!DIR} system
2488 variable) in the variable @code{idlwave-system-directory}. Under UNIX,
2489 these values will be automatically inferred from an IDLWAVE
2492 The command @kbd{M-x idlwave-create-libinfo-file} can then be used to
2493 scan library files. It brings up a widget in which you can select some
2494 or all directories on the search path. If you only want to have routine
2495 and completion info of some libraries, it is sufficient to scan those
2496 directories. However, if you want IDLWAVE to detect possible name
2497 conflicts with routines defined in other libraries, the whole pass
2500 After selecting directories, click on the @w{@samp{[Scan & Save]}}
2501 button in the widget to scan all files in the selected directories and
2502 write the resulting routine information into the file
2503 @code{idlwave-libinfo-file}. In order to update the library information
2504 from the same directories, call the command
2505 @code{idlwave-update-routine-info} with a double prefix argument:
2506 @w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously
2507 selected directories, write an updated version of the libinfo file and
2508 rebuild IDLWAVEs internal lists.
2510 A note of caution: Depending on your local installation, the IDL
2511 library can be very large. Parsing it for routine information will take
2512 time and loading this information into Emacs can require a
2513 significant amount of memory. However, having this information
2514 available will be a great help.
2516 @defopt idlwave-libinfo-file
2517 File for routine information of the IDL library.
2520 @defopt idlwave-library-path
2521 IDL library path for Windows and MacOS. Not needed under Unix.
2524 @defopt idlwave-system-directory
2525 The IDL system directory for Windows and MacOS. Not needed under UNIX.
2528 @defopt idlwave-special-lib-alist
2529 Alist of regular expressions matching special library directories.
2532 @node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info
2533 @section Load-Path Shadows
2534 @cindex Load-path shadows
2535 @cindex Shadows, load-path
2536 @cindex Duplicate routines
2537 @cindex Multiply defined routines
2538 @cindex Routine definitions, multiple
2539 @cindex Application, testing for shadowing
2540 @cindex Buffer, testing for shadowing
2542 IDLWAVE can compile a list of routines which are defined in several
2543 different files. Since one definition will hide (shadow) the others
2544 depending on which file is compiled first, such multiple definitions are
2545 called "load-path shadows". IDLWAVE has several routines to scan for
2546 load path shadows. The output is placed into the special buffer
2547 @file{*Shadows*}. The format of the output is identical to the source
2548 section of the routine info buffer (@pxref{Routine Info}). The
2549 different definitions of a routine are listed in the sequence of
2550 @emph{likelyhood of use}. So the first entry will be most likely the
2551 one you'll get if an unsuspecting command uses that routine. Before
2552 listing shadows, you should make sure that routine info is up-to-date by
2553 pressing @kbd{C-c C-i}. Here are the different routines:
2556 @item @kbd{M-x idlwave-list-buffer-load-path-shadows}
2557 This commands checks the names of all routines defined in the current
2558 buffer for shadowing conflicts with other routines accessible to
2559 IDLWAVE. The command also has a key binding: @kbd{C-c C-b}
2560 @item @kbd{M-x idlwave-list-shell-load-path-shadows}.
2561 Checks all routines compiled under the shell for shadowing. This is
2562 very useful when you have written a complete application. Just compile
2563 the application, use @code{RESOLVE_ALL} to compile any routines used by
2564 your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and
2565 then check for shadowing.
2566 @item @kbd{M-x idlwave-list-all-load-path-shadows}
2567 This command checks all routines accessible to IDLWAVE for conflicts.
2570 For these commands to work properly you should have scanned the entire
2571 load path, not just selected directories. Also, IDLWAVE should be able to
2572 distinguish between the system library files (normally installed in
2573 @file{/usr/local/rsi/idl/lib}) and any site specific or user specific
2574 files. Therefore, such local files should not be installed
2575 inside the @file{lib} directory of the IDL directory. This is of course
2576 also advisable for many other reasons.
2580 @cindex IDL variable @code{!DIR}
2581 @cindex @code{!DIR}, IDL variable
2582 Users of Windows and MacOS also must set the variable
2583 @code{idlwave-system-directory} to the value of the @code{!DIR} system
2584 variable in IDL. IDLWAVE appends @file{lib} to the value of this
2585 variable and assumes that all files found on that path are system
2588 Another way to find out if a specific routine has multiple definitions
2589 on the load path is routine info display (@pxref{Routine Info}).
2591 @node Documentation Scan, , Load-Path Shadows, Sources of Routine Info
2592 @section Documentation Scan
2593 @cindex @file{get_rinfo}
2594 @cindex @file{idlw-rinfo.el}
2595 @cindex @file{idlw-help.txt}
2596 @cindex @file{idlw-help.el}
2597 @cindex Scanning the documentation
2598 @cindex Perl program, to create @file{idlw-rinfo.el}
2600 IDLWAVE derives it knowledge about system routines from the IDL
2601 manuals. The file @file{idlw-rinfo.el} contains the routine information
2602 for the IDL system routines. The Online Help feature of IDLWAVE
2603 requires ASCII versions of some IDL manuals to be available in a
2604 specific format (@file{idlw-help.txt}), along with an Emacs-Lisp file
2605 @file{idlw-help.el} with supporting code and pointers to the ASCII file.
2607 All 3 files can be derived from the IDL documentation. If you are
2608 lucky, the maintainer of IDLWAVE will always have access to the newest
2609 version of IDL and provide updates. The IDLWAVE distribution also
2610 contains the Perl program @file{get_rinfo} which constructs these files
2611 by scanning selected files from the IDL documentation. Instructions on
2612 how to use @file{get_rinfo} are in the program itself.
2614 @node Configuration Examples, Index, Sources of Routine Info, Top
2615 @appendix Configuration Examples
2616 @cindex Configuration examples
2617 @cindex Example configuration
2618 @cindex @file{.emacs}
2619 @cindex Default settings, of options
2620 @cindex Interview, with the maintainer
2623 @b{Question:} So now you have all these complicated configuration
2624 options in your package, but which ones do @emph{you} as the maintainer
2625 actually set in your own configuration?
2628 @b{Answer:} Hardly any. As the maintainer, I set the default of most
2629 options to what I think is best. However, the default settings do not
2630 turn on features which
2634 are not self-evident (i.e. too magic) when used by an unsuspecting user
2638 will not work properly on all Emacs installations out there
2640 break with widely used standards.
2643 @noindent To see what I mean, here is the @emph{entire} configuration I
2644 have in my @file{.emacs}:
2647 (setq idlwave-shell-debug-modifiers '(control shift)
2648 idlwave-store-inquired-class t
2649 idlwave-shell-automatic-start t
2650 idlwave-main-block-indent 2
2651 idlwave-help-dir "~/lib/emacs/idlwave"
2652 idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib")
2653 ("/jhuapl/" . "JHUAPL-Lib")
2654 ("/dominik/lib/idl/" . "MyLib")))
2657 However, if you are an Emacs power-user and want IDLWAVE to work
2658 completely differently, the options allow you to change almost every
2659 aspect of it. Here is an example of a much more extensive configuration
2660 of IDLWAVE. To say it again - this is not what I recommend, but the
2664 ;;; Settings for IDLWAVE mode
2666 (setq idlwave-block-indent 3) ; Indentation settings
2667 (setq idlwave-main-block-indent 3)
2668 (setq idlwave-end-offset -3)
2669 (setq idlwave-continuation-indent 1)
2670 (setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;"
2671 ; anchored at start of line.
2672 (setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,>
2673 (setq idlwave-pad-keyword nil) ; Remove spaces for keyword '='
2674 (setq idlwave-expand-generic-end t) ; convert END to ENDIF etc...
2675 (setq idlwave-reserved-word-upcase t) ; Make reserved words upper case
2676 ; (with abbrevs only)
2677 (setq idlwave-abbrev-change-case nil) ; Don't force case of expansions
2678 (setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill
2679 (setq idlwave-show-block nil) ; Turn off blinking to begin
2680 (setq idlwave-abbrev-move t) ; Allow abbrevs to move point
2682 ;; Some setting can only be done from a mode hook. Here is an example:
2684 (add-hook 'idlwave-mode-hook
2686 (setq abbrev-mode 1) ; Turn on abbrevs (-1 for off)
2687 (setq case-fold-search nil) ; Make searches case sensitive
2688 ;; Run other functions here
2689 (font-lock-mode 1) ; Turn on font-lock mode
2690 (idlwave-auto-fill-mode 0) ; Turn off auto filling
2692 ;; Pad with with 1 space (if -n is used then make the
2693 ;; padding a minimum of n spaces.) The defaults use -1
2695 (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1))
2696 (idlwave-action-and-binding "<" '(idlwave-surround 1 1))
2697 (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-)))
2698 (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
2700 ;; Only pad after comma and with exactly 1 space
2701 (idlwave-action-and-binding "," '(idlwave-surround nil 1))
2702 (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
2704 ;; Pad only after `->', remove any space before the arrow
2705 (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2))
2707 ;; Set some personal bindings
2708 ;; (In this case, makes `,' have the normal self-insert behavior.)
2709 (local-set-key "," 'self-insert-command)
2710 ;; Create a newline, indenting the original and new line.
2711 ;; A similar function that does _not_ reindent the original
2712 ;; line is on "\C-j" (The default for emacs programming modes).
2713 (local-set-key "\n" 'idlwave-newline)
2714 ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.
2717 ;;; Settings for IDLWAVE SHELL mode
2719 (setq idlwave-shell-overlay-arrow "=>") ; default is ">"
2720 (setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame
2721 (setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> "
2722 (setq idlwave-shell-explicit-file-name "wave")
2723 (setq idlwave-shell-process-name "wave")
2724 (setq idlwave-shell-use-toolbar nil) ; No toolbar
2727 @node Index, , Configuration Examples, Top