mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-11-23 07:19:15 +00:00
Updated IDLWAVE manual to version 4.7
This commit is contained in:
Carsten Dominik
parent
169fe44e56
commit
aea44e56dc
558
man/idlwave.texi
558
man/idlwave.texi
@ -9,12 +9,12 @@
|
||||
@synindex ky cp
|
||||
@syncodeindex vr cp
|
||||
@syncodeindex fn cp
|
||||
@set VERSION 4.2
|
||||
@set EDITION 4.2
|
||||
@set IDLVERSION 5.3
|
||||
@set NSYSROUTINES 1251
|
||||
@set NSYSKEYWORDS 5287
|
||||
@set DATE June 2000
|
||||
@set VERSION 4.7
|
||||
@set EDITION 4.7
|
||||
@set IDLVERSION 5.4
|
||||
@set NSYSROUTINES 1287
|
||||
@set NSYSKEYWORDS 5724
|
||||
@set DATE December 2000
|
||||
@set AUTHOR Carsten Dominik
|
||||
@set AUTHOR-EMAIL dominik@@astro.uva.nl
|
||||
@set MAINTAINER Carsten Dominik
|
||||
@ -108,6 +108,7 @@ shell.
|
||||
@menu
|
||||
* Introduction:: What IDLWAVE is and what not
|
||||
* IDLWAVE in a Nutshell:: One page quick-start guide
|
||||
* Getting Started:: Tutorial
|
||||
* The IDLWAVE Major Mode:: The mode to edit IDL programs
|
||||
* The IDLWAVE Shell:: The mode to run IDL as inferior program
|
||||
* Installation:: How to Install or Upgrade
|
||||
@ -155,6 +156,7 @@ Debugging IDL Programs
|
||||
|
||||
* Compiling Programs:: Compiling buffers under the shell
|
||||
* Breakpoints and Stepping:: Deciding where to stop and look
|
||||
* Walking the Calling Stack:: From where was this routine called?
|
||||
* Examining Variables:: What is the value now?
|
||||
|
||||
Installation
|
||||
@ -167,7 +169,7 @@ Sources of Routine Info
|
||||
|
||||
* Routine Definitions:: Where IDL Routines are defined.
|
||||
* Routine Information Sources:: So how does IDLWAVE know about...
|
||||
* Library Scan:: Scanning the Libraries for Routine Info
|
||||
* Library Catalog:: Scanning the Libraries for Routine Info
|
||||
* Load-Path Shadows:: Routines defined in several places
|
||||
* Documentation Scan:: Scanning the IDL Manuals
|
||||
|
||||
@ -269,10 +271,8 @@ things. For a full description of what a particular variable does and
|
||||
how to configure it, see the documentation string of that variable.
|
||||
Some configuration examples are also given in the appendix.
|
||||
|
||||
@node IDLWAVE in a Nutshell, The IDLWAVE Major Mode, Introduction, Top
|
||||
@node IDLWAVE in a Nutshell, Getting Started, Introduction, Top
|
||||
@chapter IDLWAVE in a Nutshell
|
||||
@cindex Quick-Start
|
||||
@cindex Getting Started
|
||||
@cindex Summary of important commands
|
||||
@cindex IDLWAVE in a Nutshell
|
||||
@cindex Nutshell, IDLWAVE in a
|
||||
@ -337,18 +337,345 @@ at point.
|
||||
;; Pad some operators with spaces
|
||||
(setq idlwave-do-actions t
|
||||
idlwave-surround-by-blank t)
|
||||
;; Automatically expand END to ENDIF, ENDELSE, ...
|
||||
(setq idlwave-expand-generic-end t)
|
||||
;; Syntax Highlighting
|
||||
(add-hook 'idlwave-mode-hook 'turn-on-font-lock)
|
||||
;; Automatically start the shell when needed, in dedicated frame
|
||||
(setq idlwave-shell-automatic-start t
|
||||
idlwave-shell-use-dedicated-frame t)
|
||||
;; Automatically start the shell when needed
|
||||
(setq idlwave-shell-automatic-start t)
|
||||
;; Bind debugging commands with CONTROL and SHIFT modifiers
|
||||
(setq idlwave-shell-debug-modifiers '(control shift))
|
||||
;; Where are the online help files?
|
||||
(setq idlwave-help-directory "~/.idlwave")
|
||||
@end lisp
|
||||
|
||||
@node The IDLWAVE Major Mode, The IDLWAVE Shell, IDLWAVE in a Nutshell, Top
|
||||
@node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top
|
||||
@chapter Getting Started (Tutorial)
|
||||
@cindex Quick-Start
|
||||
@cindex Tutorial
|
||||
@cindex Getting Started
|
||||
|
||||
@section Lession I: Development Cycle
|
||||
|
||||
The purpose of this tutorial is to guide you through a very basic
|
||||
development cycle with IDLWAVE. We will type a simple program into a
|
||||
buffer and use the shell to compile, debug and run this program. On the
|
||||
way we will use the most important commands in IDLWAVE. Note
|
||||
however that there is much more funtionality available in IDLWAVE than
|
||||
we cover here, and it will pay off greatly if eventually you go further
|
||||
and read the whole manual.
|
||||
|
||||
I assume that you have access to Emacs or XEmacs with the full IDLWAVE
|
||||
package including online help (@pxref{Installation}). I also assume
|
||||
that you are familiar with Emacs and can read the nomenclature of key
|
||||
presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL} and
|
||||
@kbd{M} for @key{META} (often the @key{ALT} key carries this
|
||||
functionality)).
|
||||
|
||||
Open a new source file by typing
|
||||
|
||||
@example
|
||||
@kbd{C-x C-f tutorial.pro @key{RET}}
|
||||
@end example
|
||||
|
||||
A buffer for this file will pop up, and it should be in IDLWAVE mode.
|
||||
You can see this by looking at the mode line, just below the editing
|
||||
window. Also, the menu bar should contain entries @samp{IDLWAVE} and
|
||||
@samp{Debug}.
|
||||
|
||||
Now cut-and-paste the following program, also available as
|
||||
@file{tutorial.pro} in the IDLWAVE distribution.
|
||||
|
||||
@example
|
||||
function daynr,d,m,y
|
||||
;; compute a sequence number for a date
|
||||
;; works 1901-2099.
|
||||
if y lt 100 then y = y+1900
|
||||
if m le 2 then delta = 1 else delta = 0
|
||||
m1 = m + delta*12 + 1
|
||||
y1 = y * delta
|
||||
return, d + floor(m1*30.6)+floor(y1*365.25)+5
|
||||
end
|
||||
|
||||
function weekday,day,month,year
|
||||
;; compute weekday number for date
|
||||
nr = daynr(day,month,year)
|
||||
return, nr mod 7
|
||||
end
|
||||
|
||||
pro plot_wday,day,month
|
||||
;; Plot the weekday of a date in the first 10 years of this century.
|
||||
years = 2000,+indgen(10)
|
||||
wdays = intarr(10)
|
||||
for i=0,n_elements(wdays)-1 do begin
|
||||
wdays[i] = weekday(day,month,years[i])
|
||||
end
|
||||
plot,years,wdays,YS=2,YT="Wday (0=sunday)"
|
||||
end
|
||||
@end example
|
||||
|
||||
The indentation probably looks funny, since it's different from the
|
||||
settings you use, so use the @key{TAB} key in each line to automatically
|
||||
line it up (or more quickly @emph{select} the entire buffer with
|
||||
@kbd{C-x h} followed by @kbd{M-C-\}). Notice how different syntactical
|
||||
elements are highlighted in different colors, if you have set up support
|
||||
for font-lock.
|
||||
|
||||
Let's check out two particular editing features of IDLWAVE. Place the
|
||||
cursor after the @code{end} statement of the @code{for} loop and press
|
||||
@key{SPC}. IDLWAVE blinks back to the beginning of the block and
|
||||
changes the generic @code{end} to the specific @code{endfor}
|
||||
automatically. Now place the cursor in any line you would like to split
|
||||
into two and press @kbd{M-@key{RET}}. The line is split at the cursor
|
||||
position, with the continuation @samp{$} and indentation all taken care
|
||||
of. Use @kbd{C-/} to undo the last change.
|
||||
|
||||
The procedure @code{plot_wday} is supposed to plot the weekday of a given
|
||||
date for the first 10 years of the 21st century. I have put in a few
|
||||
bugs which we are going to fix now.
|
||||
|
||||
First, let's launch the IDLWAVE shell. You do this with the command
|
||||
@kbd{C-c C-s}. The Emacs window will split and display IDL running in a
|
||||
shell interaction buffer. Type a few commands like @code{print,!PI} to
|
||||
convince yourself that you can work there like in an xterminal, or the
|
||||
IDLDE. Use the arrow keys to cycle through your command history. Are
|
||||
we having fun now?
|
||||
|
||||
Now go back to the source window and type @kbd{C-c C-d C-c} to compile
|
||||
the program. If you watch the shell buffer, you see that IDLWAVE types
|
||||
@samp{.run tutorial.pro} for you. But the compilation fails because
|
||||
there is a comma in the line @samp{years=...}. The line with the error
|
||||
is highlighted and the cursor positioned at the error, so remove the
|
||||
comma (you should only need to hit Delete!). Compile again, using the
|
||||
same keystrokes as before. Notice that the file is saved for you. This
|
||||
time everything should work fine, and you should see the three routines
|
||||
compile.
|
||||
|
||||
Now we want to use the command to plot the weekdays for January 1st. We
|
||||
could type the full command ourselves, but why do that? Go back to the
|
||||
shell window, type @samp{plot_} and hit @key{TAB}. After a bit of a
|
||||
delay (while IDLWAVE initializes its routine info database), the window
|
||||
will split to show all procedures it knows starting with that string,
|
||||
and @w{@code{plot_wday}} should be one of them. Saving the buffer was
|
||||
enough to tell IDLWAVE about this new routine. Click with the middle
|
||||
mouse button on @code{plot_wday} and it will be copied to the shell
|
||||
buffer, or if you prefer, add @samp{w} to @samp{plot_} to make it
|
||||
unambiguous, hit @key{TAB}, and the full routine name will be completed.
|
||||
Now provide the two arguments:
|
||||
|
||||
@example
|
||||
plot_wday,1,1
|
||||
@end example
|
||||
|
||||
|
||||
and press @key{RET}. This fails with an error message telling you the
|
||||
@code{YT} keyword to plot is ambiguous. What are the allowed keywords
|
||||
again? Go back to the source window and put the cursor into the `plot'
|
||||
line, and press @kbd{C-c ?}. This pops up the routine info window for
|
||||
the plot routine, which contains a list of keywords, and the argument
|
||||
list. Oh, we wanted @code{YTITLE}. Fix that up. Recompile with
|
||||
@kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press
|
||||
the @key{UP} arrow to recall the previous command and execute again.
|
||||
|
||||
This time we get a plot, but it is pretty ugly -- the points are all
|
||||
connected with a line. Hmm, isn't there a way for @code{plot} to use
|
||||
symbols instead? What was that keyword? Position the cursor on the
|
||||
plot line after a comma (where you'd normally type a keyword), and hit
|
||||
@kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, there
|
||||
it is, @code{PSYM}. Middle click to insert it. An @samp{=} sign is
|
||||
included for you too. Now what were the values of @code{PSYM} supposed
|
||||
to be? With the cursor on or after the keyword, press @kbd{M-?} for
|
||||
online help (alternatively, you could have right clicked on the colored
|
||||
keyword itself in the completion list). The online help window will pop
|
||||
up showing the documentation for the @code{PYSM} keyword. Ok, let's use
|
||||
diamonds=4. Fix this, recompile (you know the command by now: @kbd{C-c
|
||||
C-d C-c}, go back to the shell (if it's vanished, you know the command
|
||||
to recall it by now: @kbd{C-c C-s}) and execute again. Now things look
|
||||
pretty good.
|
||||
|
||||
Lets try a different day - how about April fool's day?
|
||||
|
||||
@example
|
||||
plot_wday,1,4
|
||||
@end example
|
||||
|
||||
Oops, this looks very wrong. All April fool's days cannot be
|
||||
Fridays! We've got a bug in the program, perhaps in the @code{daynr}
|
||||
function. Lets put a breakpoint on the last line there. Position the
|
||||
cursor on the @samp{return, d+...} line and press @kbd{C-c C-d C-b}.
|
||||
IDL sets a breakpoint (as you see in the shell window), and the line is
|
||||
highlighted in some way. Back to the shell buffer, re-execute the
|
||||
previous command. IDL stops at the line with the breakpoint. Now hold
|
||||
down the SHIFT key and click with the middle mouse button on a few
|
||||
variables there: @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe
|
||||
@code{d} isn't the correct type. CONTROL-SHIFT middle-click on it for
|
||||
help. Well, it's an integer, so that's not the problem. Aha, @samp{y1}
|
||||
is zero, but it should be the year, depending on delta. Shift click
|
||||
@samp{delta} to see that it's 0. Below, we see the offending line:
|
||||
@samp{y1=y*delta...} the multiplication should have been a minus sign!
|
||||
So fix the line to
|
||||
|
||||
@example
|
||||
y1 = y - delta
|
||||
@end example
|
||||
|
||||
Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the
|
||||
command. Everything should now work fine. How about those leap years?
|
||||
Change the code to plot 100 years and see that every 28 years, the
|
||||
sequence of weekdays repeats.
|
||||
|
||||
@section Lession II: Customization
|
||||
|
||||
Emacs is probably the most customizable piece of software available, and
|
||||
it would be a shame if you did not make use of this and adapt IDLWAVE to
|
||||
your own preferences. Customizing Emacs or IDLWAVE means that you have
|
||||
to set Lisp variables in the @file{.emacs} file in your home directory.
|
||||
This looks scary to many people because of all the parenthesis.
|
||||
However, you can just cut and paste the examples given here and work
|
||||
from there.
|
||||
|
||||
Lets first use a boolean variable. These are variables which you turn
|
||||
on or off, much like a checkbox. A value of @samp{t} means on, a
|
||||
value of @samp{nil} means off. Copy the following line into your
|
||||
@file{.emacs} file, exit and restart Emacs.
|
||||
|
||||
@lisp
|
||||
(setq idlwave-reserved-word-upcase t)
|
||||
@end lisp
|
||||
|
||||
When this option is turned on, each reserved word you type into an IDL
|
||||
source buffer will be converted to upper case when you press @key{SPC}
|
||||
or @key{RET} right after the word. Try it out! @samp{if} changes to
|
||||
@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this
|
||||
behavior, remove the option again from your @file{.emacs} file.
|
||||
|
||||
Now I bet you have your own indentation preferences for IDL code. For
|
||||
example, I like to indent the main block of an IDL program a bit,
|
||||
different from the conventions used by RSI. Also, I'd like to use only
|
||||
3 spaces as indentation between @code{BEGIN} and @code{END}. Try the
|
||||
following lines in @file{.emacs}
|
||||
|
||||
@lisp
|
||||
(setq idlwave-main-block-indent 2)
|
||||
(setq idlwave-block-indent 3)
|
||||
(setq idlwave-end-offset -3)
|
||||
@end lisp
|
||||
|
||||
Restart Emacs, take the program we developed in the first part of this
|
||||
tutorial and re-indent it with @kbd{C-c h} and @kbd{M-C-\}. You
|
||||
probably want to keep these lines in @file{.emacs}, with values adjusted
|
||||
to your likings. If you want to get more information about any of these
|
||||
variables, type, e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}.
|
||||
To find which variables can be customized, look for items marked
|
||||
@samp{User Option:} in the manual.
|
||||
|
||||
If you cannot wrap your head around this Lisp stuff, there is another,
|
||||
more user-friendly way to customize all the IDLWAVE variables. You can
|
||||
access it through the IDLWAVE menu in one of the @file{.pro} buffers,
|
||||
option @code{Customize->Browse IDLWAVE Group}. Here you'll be presented
|
||||
with all the various variables grouped into categories. You can
|
||||
navigate the hierarchy (e.g. Idlwave Code Formatting->Idlwave Main Block
|
||||
Indent), read about the variables, change them, and `Save for Future
|
||||
Sessions'. Few of these variables need customization, but you can
|
||||
exercise considerable control over IDLWAVE's functionality with them.
|
||||
|
||||
Many people I talk to find the key bindings used for the debugging
|
||||
commands too long and complicated. Do I always have to type @kbd{C-c
|
||||
C-d C-c} to get a single simple command? Due to Emacs rules and
|
||||
conventions I cannot make better bindings by default, but you can.
|
||||
First, there is a way to assign all debugging commands in a single sweep
|
||||
to other combinations. The only problem is that we have to use
|
||||
something which Emacs does not need for other important commands. A
|
||||
good option is to execute debugging commands by holding down
|
||||
@key{CONTROL} and @key{SHIFT} while pressing a single character:
|
||||
@kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for compiling the
|
||||
current source file, @kbd{C-S-a} for deleting all breakpoints. You can
|
||||
have this with
|
||||
|
||||
@lisp
|
||||
(setq idlwave-shell-debug-modifiers '(shift control))
|
||||
@end lisp
|
||||
|
||||
If you have a special keyboard with for example a @key{HYPER} key, you
|
||||
could use
|
||||
|
||||
@lisp
|
||||
(setq idlwave-shell-debug-modifiers '(hyper))
|
||||
@end lisp
|
||||
|
||||
instead to get compilation on @kbd{H-c}.
|
||||
|
||||
You can also assign specific commands to function keys. This you must
|
||||
do in the @emph{mode-hook}, a special function which is run when a new
|
||||
buffer gets set up. Keybindings can only be done when the buffer
|
||||
exists. The possibilities for key customization are endless. Here we
|
||||
set function keys f5-f8 to common debugging commands.
|
||||
|
||||
@lisp
|
||||
;; First for the source buffer
|
||||
(add-hook 'idlwave-mode-hook
|
||||
(lambda ()
|
||||
(local-set-key [f5] 'idlwave-shell-break-here)
|
||||
(local-set-key [f6] 'idlwave-shell-clear-current-bp)
|
||||
(local-set-key [f7] 'idlwave-shell-cont)
|
||||
(local-set-key [f8] 'idlwave-shell-clear-all-bp)))
|
||||
;; Then for the shell buffer
|
||||
(add-hook 'idlwave-shell-mode-hook
|
||||
(lambda ()
|
||||
(local-set-key [f5] 'idlwave-shell-break-here)
|
||||
(local-set-key [f6] 'idlwave-shell-clear-current-bp)
|
||||
(local-set-key [f7] 'idlwave-shell-cont)
|
||||
(local-set-key [f8] 'idlwave-shell-clear-all-bp)))
|
||||
@end lisp
|
||||
|
||||
@section Lession III: Library Catalog
|
||||
|
||||
We have already used the routine info display in the first part of this
|
||||
tutorial. This was the key @kbd{C-c ?} which displays information about
|
||||
the IDL routine near the cursor position. Wouldn't it be nice
|
||||
to have the same available for your own library routines and for the
|
||||
huge amount of code in major extension libraries like JHUPL or the
|
||||
IDL-Astro library? To do this, you must give IDLWAVE a chance to study
|
||||
these routines first. We call this @emph{Building the library catalog}.
|
||||
|
||||
From the IDLWAVE entry in the menu bar, select @code{Routine Info/Select
|
||||
Catalog Directories}. If necessary, start the shell first with @kbd{C-c
|
||||
C-s} (@pxref{Starting the Shell}). IDLWAVE will find out about the IDL
|
||||
@code{!PATH} variable and offer a list of directories on the path.
|
||||
Simply select them all (or whichever you want) and click on the
|
||||
@samp{Scan&Save} button. Then go for a cup of coffee while IDLWAVE
|
||||
collects information for each and every IDL routine on your search path.
|
||||
All this information is written to the file @file{.idlcat} in your home
|
||||
directory and will from now one be automatically loaded whenever you use
|
||||
IDLWAVE. Try to use routine info (@kbd{C-c ?}) or completion
|
||||
(@kbd{M-<TAB>}) while on any routine or partial routine name you know to
|
||||
be located in the library. E.g., if you have scanned the IDL-Astro
|
||||
library:
|
||||
|
||||
@example
|
||||
a=readf@key{M-<TAB>}
|
||||
@end example
|
||||
|
||||
|
||||
expands to `readfits('. Then try
|
||||
|
||||
@example
|
||||
a=readfits(@key{C-c ?}
|
||||
@end example
|
||||
|
||||
and you get:
|
||||
|
||||
@example
|
||||
Usage: Result = READFITS(filename, header, heap)
|
||||
...
|
||||
@end example
|
||||
|
||||
I hope you made it until here. Now you are set to work with IDLWAVE.
|
||||
On the way you will want to change other things, and to learn more about
|
||||
the possibilities not discussed in this short tutorial. Read the
|
||||
manual, look at the documentation strings of interesting variables (with
|
||||
@kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining
|
||||
questions on @code{comp.lang.idl-pvwave}.
|
||||
|
||||
@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top
|
||||
@chapter The IDLWAVE Major Mode
|
||||
@cindex IDLWAVE major mode
|
||||
@cindex Major mode, @code{idlwave-mode}
|
||||
@ -626,7 +953,7 @@ This may indicate that your routine is shadowing a library routine,
|
||||
which may or may not be what you want (@pxref{Load-Path Shadows}). The
|
||||
information about the calling sequence and the keywords is derived from
|
||||
the first source listed. Library routines can only be supported if you
|
||||
have scanned the local IDL library (@pxref{Library Scan}). The source
|
||||
have scanned the local IDL library (@pxref{Library Catalog}). The source
|
||||
entry consists of a @emph{source category}, a set of @emph{flags} and
|
||||
the path to the @emph{source file}. The following categories
|
||||
exist:
|
||||
@ -635,7 +962,7 @@ exist:
|
||||
@item @i{System}
|
||||
@tab A system routine, but we do not know if it is @i{Builtin} or
|
||||
@i{SystemLib}. When the system library has bee scanned
|
||||
(@pxref{Library Scan}), this category will automatically split into the
|
||||
(@pxref{Library Catalog}), this category will automatically split into the
|
||||
next two.
|
||||
@item @i{Builtin}
|
||||
@tab A builtin routine with no source code available.
|
||||
@ -659,7 +986,7 @@ with the variable @code{idlwave-special-lib-alist}.
|
||||
@cindex Multiply defined routines
|
||||
@cindex Routine definitions, multiple
|
||||
The flags @code{[CSB]} indicate if the file is known to IDLWAVE from the
|
||||
library catalog (@w{@code{[C--]}}, @pxref{Library Scan}), from the Shell
|
||||
library catalog (@w{@code{[C--]}}, @pxref{Library Catalog}), from the Shell
|
||||
(@w{@code{[-S-]}}) or from an Emacs buffer (@w{@code{[--B]}}).
|
||||
Combinations are possible. If a file contains multiple definitions of
|
||||
the same routine, the file name will be prefixed with @samp{(Nx)} where
|
||||
@ -691,6 +1018,11 @@ Another click on the same line switches back to the buffer from which
|
||||
@kbd{C-c ?} was called. If you use the @emph{right} mouse button, the
|
||||
source will not be visited by a buffer, but displayed in the online help
|
||||
window.
|
||||
@item @i{Classes}
|
||||
@tab The @i{Classes} line is only included in the routine info window if
|
||||
the current class inherits from other classes. You can click with the
|
||||
@emph{middle} mouse button to display routine info about the current
|
||||
method in other classes on the inheritance chain.
|
||||
@end multitable
|
||||
|
||||
@defopt idlwave-resize-routine-help-window (@code{t})
|
||||
@ -870,6 +1202,10 @@ file.
|
||||
The face for links to IDLWAVE online help.
|
||||
@end defopt
|
||||
|
||||
@defopt idlwave-help-activate-links-agressively (@code{t})
|
||||
Non-@code{nil} means, make all possible links in help window active.
|
||||
@end defopt
|
||||
|
||||
@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode
|
||||
@section Completion
|
||||
@cindex Completion
|
||||
@ -905,6 +1241,9 @@ x = obj_new('IDL* @r{Class name}
|
||||
x = obj_new('MyCl',a* @r{Keyword to @code{Init} method in class @code{MyCl}}
|
||||
pro A* @r{Class name}
|
||||
pro * @r{Fill in @code{Class::} of first method in this file}
|
||||
!v* @r{System variable}
|
||||
!version.t* @r{Structure tag of system variable}
|
||||
self.g* @r{Class structure tag in methods}
|
||||
@end example
|
||||
|
||||
@cindex Scrolling the @file{*Completions*} window
|
||||
@ -979,7 +1318,8 @@ current method in all available classes will be considered. In the
|
||||
will be shown next to the item (see option
|
||||
@code{idlwave-completion-show-classes}). As a special case, the class
|
||||
of an object called @samp{self} object is always the class of the
|
||||
current routine.
|
||||
current routine. All classes it inherits from are considered as well
|
||||
where appropriate.
|
||||
|
||||
@cindex Forcing class query.
|
||||
@cindex Class query, forcing
|
||||
@ -996,6 +1336,10 @@ property in the object operator @samp{->}. This is not enabled by
|
||||
default - the variable @code{idlwave-store-inquired-class} can be used
|
||||
to turn it on.
|
||||
|
||||
@defopt idlwave-support-inheritance (@code{t})
|
||||
Non-@code{nil} means, treat inheritance with completion, online help etc.
|
||||
@end defopt
|
||||
|
||||
@defopt idlwave-completion-show-classes (@code{1})
|
||||
Non-@code{nil} means, show classes in @file{*Completions*} buffer when
|
||||
completing object methods and keywords.
|
||||
@ -1055,7 +1399,7 @@ taken from context, but you get a chance to edit it.
|
||||
|
||||
@code{idlwave-resolve} is one way to get a library module within reach
|
||||
of IDLWAVE's routine info collecting functions. A better way is to
|
||||
scan (parts of) the library (@pxref{Library Scan}). Routine info on
|
||||
scan (parts of) the library (@pxref{Library Catalog}). Routine info on
|
||||
library modules will then be available without the need to compile the
|
||||
modules first, and even without a running shell.
|
||||
|
||||
@ -1115,7 +1459,7 @@ The templates are expanded in upper or lower case, depending upon the
|
||||
variables @code{idlwave-abbrev-change-case} and
|
||||
@code{idlwave-reserved-word-upcase}.
|
||||
|
||||
@defopt idlwave-abbrev-start-char
|
||||
@defopt idlwave-abbrev-start-char (@code{"\"})
|
||||
A single character string used to start abbreviations in abbrev
|
||||
mode.
|
||||
@end defopt
|
||||
@ -1197,7 +1541,7 @@ Non-@code{nil} means point blinks to block beginning for
|
||||
@code{idlwave-show-begin}.
|
||||
@end defopt
|
||||
|
||||
@defopt idlwave-expand-generic-end (@code{nil})
|
||||
@defopt idlwave-expand-generic-end (@code{t})
|
||||
Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc.
|
||||
@end defopt
|
||||
|
||||
@ -1498,13 +1842,22 @@ Hook for customizing @code{idlwave-shell-mode}.
|
||||
|
||||
The IDLWAVE shell works in the same fashion as other shell modes in
|
||||
Emacs. It provides command history, command line editing and job
|
||||
control. Here is a list of commonly used commands.
|
||||
control. The @key{UP} and @key{DOWN} arrows cycle through the input
|
||||
history just like in an X terminal@footnote{This is different from
|
||||
normal Emacs/Comint behavior, but more like an xterm. If you prefer the
|
||||
default comint functionality, check the variable
|
||||
@code{idlwave-shell-arrows-do-history}.}. Here is a list of
|
||||
commonly used commands.
|
||||
|
||||
@multitable @columnfractions .12 .88
|
||||
@item @key{UP}
|
||||
@tab Cycle backwards in input history
|
||||
@item @key{DOWN}
|
||||
@tab Cycle forwards in input history
|
||||
@item @kbd{M-p}
|
||||
@tab Cycle backwards in input history matching input
|
||||
@tab Cycle backwards in input history @emph{matching input}
|
||||
@item @kbd{M-n}
|
||||
@tab Cycle forwards
|
||||
@tab Cycle forwards in input history @emph{matching input}
|
||||
@item @kbd{M-r}
|
||||
@tab Previous input matching a regexp
|
||||
@item @kbd{M-s}
|
||||
@ -1559,12 +1912,24 @@ information on these commands.
|
||||
@tab Compile a library routine (@code{idlwave-resolve})
|
||||
@end multitable
|
||||
|
||||
@defopt idlwave-shell-arrows-do-history (@code{t})
|
||||
Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command
|
||||
history like xterm.
|
||||
@end defopt
|
||||
|
||||
@defopt idlwave-shell-comint-settings
|
||||
Alist of special settings for the comint variables in the IDLWAVE Shell.
|
||||
@end defopt
|
||||
|
||||
@defopt idlwave-shell-file-name-chars
|
||||
The characters allowed in file names, as a string. Used for file name
|
||||
completion.
|
||||
@end defopt
|
||||
|
||||
@page
|
||||
@defopt idlwave-shell-graphics-window-size
|
||||
Size of IDL graphics windows popped up by special IDLWAVE command.
|
||||
@end defopt
|
||||
|
||||
@cindex Input mode
|
||||
@cindex Character input mode (Shell)
|
||||
@cindex Line input mode (Shell)
|
||||
@ -1609,11 +1974,21 @@ C-t} (@code{idlwave-shell-toggle-toolbar}).
|
||||
|
||||
The debugging keybindings are by default on the prefix key @kbd{C-c
|
||||
C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d
|
||||
C-b}. If you find this too much work and your ALT key is still
|
||||
available, turn on the variable
|
||||
@code{idlwave-shell-activate-alt-keybindings} in order to get breakpoint
|
||||
setting on @kbd{A-b}. In the remainder of this chapter we will assume
|
||||
that the @kbd{C-c C-d} bindings are active.
|
||||
C-b}, compiling a source file with @kbd{C-c C-d C-c}. If you find this
|
||||
too much work you can choose a combination of modifier keys which is not
|
||||
used by other commands. For example, if you write in @file{.emacs}
|
||||
|
||||
@lisp
|
||||
(setq idlwave-shell-debug-modifiers '(control shift))
|
||||
@end lisp
|
||||
|
||||
a breakpoint can be set by pressing @kbd{b} while holding down
|
||||
@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a
|
||||
source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}
|
||||
etc. In the remainder of this chapter we will assume that the @kbd{C-c
|
||||
C-d} bindings are active, but each of these bindings will have an
|
||||
equivalent single-keypress shortcut with the modifiers given in the
|
||||
@code{idlwave-shell-debug-modifiers} variable.
|
||||
|
||||
@defopt idlwave-shell-prefix-key (@kbd{C-c C-d})
|
||||
The prefix key for the debugging map
|
||||
@ -1625,9 +2000,9 @@ Non-@code{nil} means, debug commands will be bound to the prefix
|
||||
key, like @kbd{C-c C-d C-b}.
|
||||
@end defopt
|
||||
|
||||
@defopt idlwave-shell-activate-alt-keybindings (@code{nil})
|
||||
Non-@code{nil} means, debug commands will be bound to alternate
|
||||
keys, like @kbd{A-b}.
|
||||
@defopt idlwave-shell-debug-modifiers (@code{nil})
|
||||
List of modifier keys to use for binding debugging commands in the shell
|
||||
and in source buffers.
|
||||
@end defopt
|
||||
|
||||
@defopt idlwave-shell-use-toolbar (@code{t})
|
||||
@ -1639,6 +2014,7 @@ buffers.
|
||||
@menu
|
||||
* Compiling Programs:: Compiling buffers under the shell
|
||||
* Breakpoints and Stepping:: Deciding where to stop and look
|
||||
* Walking the Calling Stack:: From where was this routine called?
|
||||
* Examining Variables:: What is the value now?
|
||||
@end menu
|
||||
|
||||
@ -1682,7 +2058,7 @@ The face which highlights the source line where IDL is
|
||||
stopped.
|
||||
@end defopt
|
||||
|
||||
@node Breakpoints and Stepping, Examining Variables, Compiling Programs, Debugging IDL Programs
|
||||
@node Breakpoints and Stepping, Walking the Calling Stack, Compiling Programs, Debugging IDL Programs
|
||||
@subsection Breakpoints and Stepping
|
||||
@cindex Breakpoints
|
||||
@cindex Stepping
|
||||
@ -1693,16 +2069,23 @@ stopped.
|
||||
You can set breakpoints and step through a program with IDLWAVE.
|
||||
Setting a breakpoint in the current line of the source buffer is done
|
||||
with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a prefix
|
||||
arg of 1, the breakpoint gets a @code{/ONCE} keyword, meaning that it
|
||||
will be deleted after first use. With a numeric prefix greater than
|
||||
one, the breakpoint will only be active the @code{nth} time it is hit.
|
||||
To clear the breakpoint in the current line, use @kbd{C-c C-d C-d}
|
||||
(@code{idlwave-clear-current-bp}). To clear all breakpoints, use
|
||||
@kbd{C-c C-d C-a} (@code{idlwave-clear-all-bp}). Breakpoint lines are
|
||||
highlighted in the source code.
|
||||
arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}, the breakpoint gets a @code{/ONCE}
|
||||
keyword, meaning that it will be deleted after first use. With a
|
||||
numeric prefix greater than one, the breakpoint will only be active the
|
||||
@code{nth} time it is hit. To clear the breakpoint in the current line,
|
||||
use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When executed
|
||||
from the shell window, the breakpoint where IDL is currently stopped
|
||||
will be deleted. To clear all breakpoints, use @kbd{C-c C-d C-a}
|
||||
(@code{idlwave-clear-all-bp}). Breakpoint lines are highlighted in the
|
||||
source code.
|
||||
|
||||
Once the program has stopped somewhere, you can step through it. Here
|
||||
is a summary of the breakpoint and stepping commands:
|
||||
Once the program has stopped somewhere, you can step through it. The
|
||||
most important stepping commands are @kbd{C-c C-d C-s} to execute one
|
||||
line of IDL code; @kbd{C-c C-d C-n} to do one step but treat procedure
|
||||
and function calls as a single step; @kbd{C-c C-d C-h} to continue
|
||||
execution to the line where the cursor is in and @kbd{C-c C-d C-r} to
|
||||
continue execution. Here is a summary of the breakpoint and stepping
|
||||
commands:
|
||||
|
||||
@multitable @columnfractions .23 .77
|
||||
@item @kbd{C-c C-d C-b}
|
||||
@ -1746,12 +2129,31 @@ The face for breakpoint lines in the source code if
|
||||
@code{idlwave-shell-mark-breakpoints} has the value @code{face}.
|
||||
@end defopt
|
||||
|
||||
@node Examining Variables, , Breakpoints and Stepping, Debugging IDL Programs
|
||||
@node Walking the Calling Stack, Examining Variables, Breakpoints and Stepping, Debugging IDL Programs
|
||||
@subsection Walking the Calling Stack
|
||||
@cindex Calling stack, walking
|
||||
|
||||
When debugging a program, it can be very useful to check in what context
|
||||
the current routine was called, and why the arguments of the call are
|
||||
the way they are. For this one needs to examine the calling stack. If
|
||||
execution is stopped somewhere deep in a program, you can use the
|
||||
commands @kbd{C-c C-d C-@key{UP}} (@code{idlwave-shell-stack-up}) and
|
||||
@kbd{C-c C-d C-@key{DOWN}} (@code{idlwave-shell-stack-down}) or the
|
||||
corresponding toolbar buttons to move through the calling stack. The
|
||||
mode line of the shell window will indicate where you are on the stack
|
||||
with a token like @samp{[-3:MYPRO]}, and the line of IDL code which did
|
||||
the current call will be highlighted. When you continue execution,
|
||||
IDLWAVE will automatically return to the current level. @xref{Examining
|
||||
Variables} for information how to examine the value of variables and
|
||||
expressions on higher calling stack levels.
|
||||
|
||||
@node Examining Variables, , Walking the Calling Stack, Debugging IDL Programs
|
||||
@subsection Examining Variables
|
||||
@cindex @code{PRINT} expressions
|
||||
@cindex @code{HELP}, on expressions
|
||||
@cindex Expressions, printing
|
||||
@cindex Expressions, help
|
||||
@cindex Printing expressions
|
||||
@cindex Mouse binding to print expressions
|
||||
|
||||
@kindex C-c C-d C-p
|
||||
@ -1765,23 +2167,21 @@ argument will prompt for an expression instead of using the one at
|
||||
point.
|
||||
|
||||
It is very convenient to click with the mouse on expressions to retrieve
|
||||
their value. Expression printing is also bound to @kbd{S-mouse-2} and
|
||||
expression help to @kbd{C-S-mouse-2}. I.e. you need to hold down
|
||||
@key{SHIFT} and @key{CONTROL} while clicking with the mouse.
|
||||
their value. Use @kbd{S-mouse-2} to print an expression and
|
||||
@kbd{C-S-mouse-2} to get help on an expression. I.e. you need to hold
|
||||
down @key{SHIFT} and @key{CONTROL} while clicking with the middle mouse
|
||||
buton.
|
||||
|
||||
@cindex Calling stack, motion
|
||||
@cindex Printing expressions, on calling stack
|
||||
@cindex Restrictions for expression printing
|
||||
Printing of expressions also works on higher levels of the calling
|
||||
stack. This means that you can examine the values of variables and
|
||||
expressions inside the routine which called the current routine etc.
|
||||
Use the commands @kbd{C-c C-d C-@key{UP}}
|
||||
(@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}}
|
||||
(@code{idlwave-shell-stack-down}) or the corresponding toolbar buttons
|
||||
to move through the calling stack. The mode line of the shell window
|
||||
will indicate the routine and the calling stack level which define the
|
||||
context for printing expressions. The following restrictions apply for
|
||||
all levels except the current:
|
||||
@xref{Walking the Calling Stack} for information on how to step back to
|
||||
higher levels on the calling stack. Commands which print values of
|
||||
variables and expressions will then use the values of variables in the
|
||||
calling routine. The following restrictions apply for all levels except
|
||||
the current:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
@ -1902,14 +2302,14 @@ The main contributors to the IDLWAVE package have been:
|
||||
|
||||
@itemize @minus
|
||||
@item
|
||||
@uref{mailto:chase@@att.com, @b{Chris Chase}} wrote
|
||||
@file{idl.el} and @file{idl-shell.el} and maintained them for several
|
||||
years.
|
||||
@uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author.
|
||||
Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them
|
||||
for several years.
|
||||
|
||||
@item
|
||||
@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} has been in
|
||||
charge of the package since version 3.0. He renamed the package to
|
||||
IDLWAVE, rewrote and added large parts and is the current maintainer.
|
||||
@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}}, current author
|
||||
and maintainer. I have been in charge of the package since version
|
||||
3.0. I am also responsible for the manual.
|
||||
|
||||
@item
|
||||
@uref{mailto:jdsmith@@astrosun.tn.cornell.edu, @b{J.D. Smith}} has
|
||||
@ -1937,6 +2337,8 @@ Xuyong Liu <liu@@stsci.edu>
|
||||
@item
|
||||
Simon Marshall <Simon.Marshall@@esrin.esa.it>
|
||||
@item
|
||||
Craig Markwardt <craigm@@cow.physics.wisc.edu>
|
||||
@item
|
||||
Laurent Mugnier <mugnier@@onera.fr>
|
||||
@item
|
||||
Lubos Pochman <lubos@@rsinc.com>
|
||||
@ -1965,7 +2367,7 @@ IDLWAVE must know about the accessible routines.
|
||||
@menu
|
||||
* Routine Definitions:: Where IDL Routines are defined.
|
||||
* Routine Information Sources:: So how does IDLWAVE know about...
|
||||
* Library Scan:: Scanning the Libraries for Routine Info
|
||||
* Library Catalog:: Scanning the Libraries for Routine Info
|
||||
* Load-Path Shadows:: Routines defined in several places
|
||||
* Documentation Scan:: Scanning the IDL Manuals
|
||||
@end menu
|
||||
@ -2003,7 +2405,7 @@ cannot provide routine info and completion for external
|
||||
routines.
|
||||
@end enumerate
|
||||
|
||||
@node Routine Information Sources, Library Scan, Routine Definitions, Sources of Routine Info
|
||||
@node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info
|
||||
@section Routine Information Sources
|
||||
@cindex Routine info sources
|
||||
@cindex Builtin list of routines
|
||||
@ -2046,7 +2448,7 @@ the shell again at any time.
|
||||
@item
|
||||
IDLWAVE can scan all or selected library files and store the result in a
|
||||
file which will be automatically loaded just like
|
||||
@file{idlw-rinfo.el}. @xref{Library Scan}, for information how to
|
||||
@file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to
|
||||
scan library files.
|
||||
@end enumerate
|
||||
|
||||
@ -2063,9 +2465,10 @@ Non-@code{nil} means query the shell for info about compiled routines.
|
||||
Controls under what circumstances routine info is updated automatically.
|
||||
@end defopt
|
||||
|
||||
@node Library Scan, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
|
||||
@section Library Scan
|
||||
@node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
|
||||
@section Library Catalog
|
||||
@cindex Library scan
|
||||
@cindex Library catalog
|
||||
@cindex IDL library routine info
|
||||
@cindex Windows
|
||||
@cindex MacOS
|
||||
@ -2126,7 +2529,7 @@ The IDL system directory for Windows and MacOS. Not needed under UNIX.
|
||||
Alist of regular expressions matching special library directories.
|
||||
@end defopt
|
||||
|
||||
@node Load-Path Shadows, Documentation Scan, Library Scan, Sources of Routine Info
|
||||
@node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info
|
||||
@section Load-Path Shadows
|
||||
@cindex Load-path shadows
|
||||
@cindex Shadows, load-path
|
||||
@ -2140,11 +2543,14 @@ IDLWAVE can compile a list of routines which are defined in several
|
||||
different files. Since one definition will hide (shadow) the others
|
||||
depending on which file is compiled first, such multiple definitions are
|
||||
called "load-path shadows". IDLWAVE has several routines to scan for
|
||||
load path shadows. The output is placed into s special buffer
|
||||
load path shadows. The output is placed into the special buffer
|
||||
@file{*Shadows*}. The format of the output is identical to the source
|
||||
section of the routine info buffer (@pxref{Routine Info}). Before
|
||||
calling these routines, you should make sure that routine info is
|
||||
up-to-date by pressing @kbd{C-c C-i}. Here are the different routines:
|
||||
section of the routine info buffer (@pxref{Routine Info}). The
|
||||
different definitions of a routine are listed in the sequence of
|
||||
@emph{likelyhood of use}. So the first entry will be most likely the
|
||||
one you'll get if an unsuspecting command uses that routine. Before
|
||||
listing shadows, you should make sure that routine info is up-to-date by
|
||||
pressing @kbd{C-c C-i}. Here are the different routines:
|
||||
|
||||
@table @asis
|
||||
@item @kbd{M-x idlwave-list-buffer-load-path-shadows}
|
||||
@ -2158,8 +2564,7 @@ the application, use @code{RESOLVE_ALL} to compile any routines used by
|
||||
your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and
|
||||
then check for shadowing.
|
||||
@item @kbd{M-x idlwave-list-all-load-path-shadows}
|
||||
This command finally checks all routines accessible to IDLWAVE for
|
||||
shadowing conflicts.
|
||||
This command checks all routines accessible to IDLWAVE for conflicts.
|
||||
@end table
|
||||
|
||||
For these commands to work properly you should have scanned the entire
|
||||
@ -2239,8 +2644,7 @@ break with widely used standards.
|
||||
have in my @file{.emacs}:
|
||||
|
||||
@lisp
|
||||
(setq idlwave-shell-activate-alt-keybindings t
|
||||
idlwave-expand-generic-end t
|
||||
(setq idlwave-shell-debug-modifiers '(control shift)
|
||||
idlwave-store-inquired-class t
|
||||
idlwave-shell-automatic-start t
|
||||
idlwave-main-block-indent 2
|
||||
|
||||
Loading…
Reference in New Issue
Block a user