Digital PDFs

AA-MKB9A-TE

July 1989

316 pages

Original

136MB

Document:	VAX LISP/VMS Program Development Guide
Order Number:	AA-MKB9A-TE
Revision:	000
Pages:	316
Original Filename:

OCR Text

VAX LISP/VMS Program Development Guide
Order Number: AA-MK69A-TE

July 1989
This guide contains information for a LISP language programmer to interpret, compile,
and debug VAX LISP programs on VMS operating system s on DECwindows and terminal
interfaces.

Revision/Update Information:

This is a new manual.

Operating System and Version: VMS Version 5.1
Software Version:

digital equipment corporation
maynard, massachusetts

VAX LISP Version 3.0

First Printing, July 1989
The information in this document is subject to change without notice and should not be
construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation
assu m es no responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be used or
copied only in accordance with the terms of such license.
No responsibility is assum ed for the use or reliability of software on equipment that is not
supplied by Digital Equipment Corporation or its affiliated companies.
© Digital Equipment Corporation 1989.
All rights reserved.
Printed in U.S.A.
The Reader’
s Comments form at the end of this document requests your critical evaluation to
assist us in preparing future documentation.

The following are trademarks of Digital Equipment Corporation:
AI VAXstation
DEC
DECnet
DECUS
Micro VAX
MicroVAX II
MicroVMS

PDP
ULTRIX
ULTRIX-11
ULTRIX—32
UNIBUS
VAX
VAX LISP

VAX LISP/ULTRIX
VAX LISP/VMS
VAXstation
VAXstation II
VMS

X Window System is a trademark of the Massachusetts Institute of Technology.

S828

This document w as prepared using VAX DOCUMENT, Version 1.1.

Contents
P re fa c e ...............................................................................................................................................................

Part I

VAX LISP System Concepts and Facilities for VMS System s

Chapter 1

Introduction to VAX LISP

1.1

Overview of VAX LISP ....................................................................................................
1.1.1
DCL LISP C o m m a n d ..........................................................
1.1.1.1
Interpreter...........................................................
1.1.1.2
Com piler.............................................................
1.1.2
Editor..............................................................................
1.1.3
Error Handler ...................................................................
1.1.4
Inspector ........................................................................
1.1.5
Debugging Facilities............................................................
1.1.6
Pretty Printer.....................................................................
1.1.7
Call-Out Facility.................................................................
1.1.8
Call-Back Facility................................................................
1.1.9
Alien Structure F a cility .........................................................
1.1.10
Interrupt Function Facility .....................................................
1.1.11
VWS Graphics In terfa ce.......................................................
1.1.12
DECwindows In te rfa ce ........................................................
1.1.13
CLX In te rfa ce ...................................................................
1.1.14
System-Building Utility ........................................................
1.1.15
VAX LISP Function, Macro, and Variable Descriptions for V M S .........

1-1
1-2
1-3
1-3
1-3
1-3
1-3
1-4
1-4
1—4
1-4
1-4
1-5
1-5
1-5
1—5
1-5
1—6

1.2

Help F a c ilitie s ....................................................................................................................
1.2.1
DCL H e lp ........................................................................
1.2.2
DECwindows H e l p ..............................................................
1.2.3
LISP H elp ........................................................................

1-6
1-6
1-7
1-7

1.3

VMS File Specifications ...................................................................

1-7

1.4

Logical N a m e s ...................................................................................................................

1-9

1.5

Entering DCL C o m m an d s .................................................................

1-9

Chapter 2
2.1

Invoking LISP ...................................................................................................................

2-1

2.2

Exiting L IS P ........................................................................................................................

2-2

2.3

Entering In p u t ...................................................................................................................

2-2

2.4

Deleting and Editing Input ............................................................................................

2 -2

2.5

Entering the D e b u g g e r.....................................................................

2-3

2.6

Using Control Key C haracters............................................................

2-3

2.7

Creating P ro g ram s...........................................................................................................

2 -4

2.8

Loading F ile s ......................................................................................................................

2 -4

2.9

Compiling Program s........................................................................
2.9.1
Compiling Individual Functionsand Macros .................................
2.9.2
Compiling F i l e s .................................................................
2.9.3
Advantages of Compiling LISPE x p r e s sio n s .................................
2.9.4
Advantage of Not Compiling LISP E x p re ssio n s............................

2-5
2-5
2-6
2-7
2-7

2.10

DCL LISP Command Q u a lifie rs ..........................................................
2.10.1
Three Ways to Use the DCL LISP C o m m a n d ..............................
2.10.2
/C O M PIL E .......................................................................
2.10.3
/CST A CK ........................................................................
2.10.4
/ERROR_ACTION..............................................................
2.10.5
/[NOJINITIALIZE.................................................................
2.10.6
/INTERACTIVE.................................................................
2.10.7
/[NOJLIST........................................................................
2.10.8
/[NO]MACHINE_CODE.........................................................
2.10.9
/MEMORY .......................................................................
2.10.10
/[NOjOPTIMIZE.................................................................
2.10.11
/[NO]OUTPUT_FILE............................................................
2.10.12
/RESUME........................................................................
2.10.13
/[NOJVERBOSE.................................................................
2.10.14
/[NOJWARNINGS................................................................

2-7
2-9
2-10
2-11
2-11
2-12
2-13
2-13
2-14
2-14
2-15
2-15
2-16
2-16
2-17

2.11

Using Suspended S y s te m s ............................................................................................
2.11.1
Creating a Suspended S y s te m ................................................
2.11.2
Resuming a Suspended S y s te m ..............................................

2-18
2-18
2-19

2.12

Using Subprocesses.........................................................................................................
2.12.1
Creating a S u b p r o c e s s .........................................................
2.12.2
Connecting to a S u b p r o c e s s .................................................
2.12.3
Exiting from a S u b p r o c e ss .....................................................

2—19
2-19
2-20
2-20

Chapter 3
3.1

Using VAX LISP

Using the VAX LISP Editor
Introduction to the E d it o r ..................................................................
3.1.1
Editing C y c le .....................................................................
3.1.2
Invoking the E ditor.....................................................

3-2
3-2
3—3

3.1.3

Interacting with the E d ito r .....................................................
3.1.3.1
Getting H e l p .......................................................
3.1.3.2
Input Completion and Alternatives...............................
3.1.3.3
Errors and Other P r o b le m s ......................................
Moving Work Back to L I S P ...................................................
Returning to the LISP Interpreter............................................
Summary of C o m m a n d s ......................................................

3-5
3-6
3—7
3—7
3—8
3-8
3-9

3.2

Editing O p e r a t io n s ..........................................................................
3.2.1
Keypad ...........................................................................
3.2.2
Inserting and Formatting T ext.................................................
3.2.2.1
Inserting Text .....................................................
3.2.2.2
Typing and Formatting LISP C ode ............................
3.2.2.3
Inserting Nongraphic C haracters...............................
3.2.3
Moving the C u r s o r ..............................................................
3.2.3.1
Moving with the Keypad and Arrow K e y s ......................
3.2.3.2
Moving in LISP C o d e ............................................
3.2.3.3
Moving with the Pointer (VWS VAXstation O n ly)............
3.2.4
Modifying T ex t...................................................................
3.2.4.1
Deleting T ext.......................................................
3.2.4.2
Undeleting T e x t ...................................................
3.2.4.3
Cutting and Pasting T e x t........................................
3.2.4.4
Changing C a s e ...................................................
3.2.4.5
Substituting Text .................................................
3.2.4.6
Inserting a File or B uffer........................................
3.2.5
Repeating an Operation ......................................................
3.2.6
Summary of C o m m a n d s .......................................................

3-10
3—10
3-11
3-11
3—12
3-13
3-14
3—14
3—15
3—15
3-15
3—16
3-16
3—17
3—17
3-18
3—18
3—19
3—19

3.3

Using Multiple Buffers and W in d o w s ...................................................
3.3.1
Introduction to Buffers and W in d ow s.........................................
3.3.2
Creating New Buffers from Within the Editor................................
3.3.3
Working with Buffers............................................................
3.3.3.1
Saving Buffer C o n ten ts...........................................
3.3.3.2
Deleting B uffers....................................................
3.3.3.3
Buffer Name Conflicts.............................................
3.3.4
Manipulating Windows ........................................................
3.3.5
Moving Text Between B uffers.................................................
3.3.6
Summary of C o m m a n d s .......................................................

3-23
3—23
3-26
3-26
3-26
3—27
3-27
3—27
3-28
3-28

3.4

R ecoverin g from P r o b l e m s ...............................................................

3-29

3.5

C u stom izin g the E d ito r .....................................................................
3.5.1
Binding Keys to C om m an d s...................................................
3.5.1.1
Binding Within the Editor.........................................
3.5.1.2
Binding from the LISP Interpreter...............................
3.5.1.3
Selecting a Key or Key Sequence .............................
3.5.1.4
Key Binding Context and Shadow ing...........................
3.5.2
Keyboard M a cros...............................................................
3.5.3
Summary of C o m m a n d s .......................................................

3—29
3-30
3—30
3-31
3-33
3-34
3—35
3-36

3.6

U sing the Editor on a VWSVAXstation .................................................
3.6.1
Before You S t a r t ...............................................................
3.6.1.1
Activating Lines in LISPSTART.COM...........................
3.6.1.2
Setting the Terminal Emulator to NOFALLBACK Mode . . . .
3.6.2
Screen Appearance and Behavior............................................

3-36
3-36
3—36
3-37
3-37

3.1.4
3.1.5
3.1.6

3.6.3

3.6.4

C h a p te r 4

Editing with the P ointer........................................................
3.6.3.1
Selecting and Removing Windows .............................
3.6.3.2
Moving the Text Insertion Cursor and Marking T e x t ..........
3.6.3.3
Cutting and P a s t in g ...............................................
3.6.3.4
Invoking the DESCRIBE Function and Matching
P a r e n th e se s.......................................................
3.6.3.5
Information About Pointer E f f e c t s ...............................
Binding Pointer Buttons to C om m an ds.......................................

3—37
3-38
3—38
3—38
3—39
3—39
3—39

D e b u g g in g F a cilities

4.1

Control V a r ia b le s ............................................................................

4-2

4.2

Control S t a c k .................................................................................

4—2

4.3

Break L o o p ...................................................................................
4.3.1
Invoking the Break L o o p ......................................................
4.3.2
Exiting the Break L o o p ........................................................
4.3.3
Using the Break L o o p ..........................................................
4.3.4
Break Loop V ariables..........................................................

4—3
4—3
4—4
4—4
4—5

4.4

D ebu gger ................................................................... ................
4.4.1
Invoking the D e b u g g e r ........................................................
4.4.2
Exiting the D e b u g g e r ..........................................................
4.4.3
Using Debugger C o m m a n d s .................................................
4.4.3.1
A rgu m en ts.........................................................
4.4.3.2
Debugger C om m a n d s.............................................
4.4.4
Using the DEBUG-CALL Function............................................
4.4.5
Sample Debugging S e s s i o n s .................................................

4-5
4-5
4—6
4—7
4—7
4—9
4—12
4—13

4.5

Stepper .........................................................................................
4.5.1
Invoking the Stepper ..........................................................
4.5.2
Exiting the S tep p er..............................................................
4.5.3
Stepper O u tp u t.................................................................
4.5.4
Using Stepper C om m an d s.....................................................
4.5.4.1
A rgu m en ts.........................................................
4.5.4.2
Stepper C o m m a n d s ..............................................
4.5.5
Using Stepper V a ria b les......................................................
4.5.5.1
‘
STEP-FORM* ....................................................
4.5.5.2
‘
STEP-ENVIRONMENT*.........................................
4.5.5.3
Example Use of Stepper V a ria bles............................
4.5.6
Sample Stepper S e s s i o n s .....................................................

4—14
4-14
4—15
4—15
4—17
4-18
4—19
4—20
4-20
4-21
4-21
4-23

4.6

T r a c e r ..........................................................................................
4.6.1
Enabling the T r a c e r ............................................................
4.6.2
Disabling the T ra c e r ............................................................
4.6.3
Tracer O u tp u t...................................................................
4.6.4
Tracer Options .................................................................
4.6.4.1
Invoking the D e b u g g e r ...........................................
4.6.4.2
Adding Information to Tracer O u tp u t..........................
4.6.4.3
Invoking the Stepper ............................................
4.6.4.4
Removing Information from Tracer O u tp u t....................
4.6.4.5
Defining When a Function or Macro Is Traced ..............
4.6.5
Tracer Variables.................................................................
4.6.5.1
*T RACE-CALL*....................................................
4.6.5.2
TRACE-VALUES*.................................................

4-24
4—24
4—25
4—25
4-26
4-27
4-27
4-27
4—27
4—27
4—27
4-28
4-28

4.7

The E d it o r .....................................................................................

4-29

Part II

Using VAX LISP Facilities on the DECwindows Interface

Chapter 5

The DECwindows Interface to VAX LISP

5.1

Invoking VAX L IS P ...........................................................................................................

5-2

5.2

Using the L is te n e r............................................................................................................

5-4

5.3

Using the In s p e c to r..........................................................................................................

5 -6

5.4

Running a Sample F u n c tio n .........................................................................................

5-10

5.5

Using the E d ito r.................................................................................................................

5-10

5.6

Using the D eb u g g er..........................................................................................................

5-17

5.7

Exiting from VAX L I S P ....................................................................................................

5-20

Chapter 6

Starting LISP from DECwindows

6.1

Defining the Display S y s te m .........................................................................................
6.1.1
Displaying LISP on D E C w in dow s............................................
6.1.2
Displaying LISP on a Term inal................................................

6-1
6-1
6—1

6.2

Invoking LISP from DECwindows F ile V ie w ................................................................
6.2.1
Invoking LISP with the LISP.EXE F i l e .......................................
6.2.2
Invoking LISP with the DCL Command Item ................................

6-1
6-2
6-3

6.3

Resuming LISP from DECwindows .............................................................................

6-3

6.4

Compiling a LISP File from DECwindows...................................................................

6-4

Chapter 7

The Listener

7.1

Entering LISP Forms .......................................................................................................

7-2

7.2

Exiting LISP from the Listener.......................................................................................

7-3

7.3

Editing Text and O bjects.................................................................................................
7.3.1
Selecting Text and O b j e c t s ...................................................
7.3.2
Moving Text and Objects to Another L ocation ..............................
7.3.3
VAX LISP Default Key B in d in g s..............................................

7-3
7-3
7—4
7—4

7.4

Working with F ile s ............................................................................................................
7.4.1
Loading a LISP F i l e ............................................................
7.4.2
Compiling a LISP F ile..........................................................
7.4.3
Invoking the Editor on a LISP File ..........................................
7.4.4
Saving the Text of the Transcript R e g io n ...................................
7.4.5
Creating a LISP Suspended Image F ile .....................................
7.4.6
Recording Your Interactive LISP S e s s i o n ...................................

7 -5
7-6
7-7
7-8
7-8
7-9
7-10

7.5

Compiling a F u n ctio n .......................................................................

7-10

7.6

Disassembling a Function...............................................................................................

7-11

7.7

Using the EVAL F u n c tio n ...............................................................................................

7-11

7.8

Invoking Other LISP U tilitie s ..........................................................................................

7-11

7.9

Interrupting a P ro g ra m ....................................................................................................

7-12

7.10

Getting Help ......................................................................................................................
7.10.1
Invoking Help on VAX L IS P ..........................................................................
7.10.2
Invoking Help on Screen O b j e c t s ................................................................
7.10.3
Using the APROPOS and DESCRIBE Functions......................................

7-12
7-12
7-13
7—13

Chapter 8

Using the VAX LISP Editor in DECwindows

8.1

Introduction to the E d it o r .................................................................
8.1.1
Invoking the Editor..............................................................
8.1.1.1
Invoking the Editor from the M enus.............................
8.1.1.2
Invoking the Editor Using a Command L i n e ..................
8.1.2
Entering Text in the Editor.....................................................
8.1.3
Using Editor C o m m a n d s .......................................................
8.1.4
Evaluating Work in the Editor.................................................
8.1.5
Saving Work in the E d ito r.....................................................
8.1.6
Returning to LISP ..............................................................
8.1.7
Returning to the E d ito r ........................................................
8.1.8
Exiting the E ditor................................................................

8-2
8-2
8-2
8-3
8-4
8—4
8-5
8-5
8-6
8-6
8-7

8.2

Getting Help .................................................................................
8.2.1
Using the Help K e y ............................................................
8.2.2
Using the Help M e n u ..........................................................
8.2.2.1
Help on Editor O b je c t s ...........................................
8.2.2.2
Help on R espon ses to P r o m p t s ................................
8.2.2.3
Help on Errors and Other P r o b le m s ...........................

8-8
8-8
8-8
8-8
8-9
8-10

8.3

Editing LISP C o d e ..........................................................................
8.3.1
Using the P ointer...............................................................
8.3.2
Cutting and Pasting T e x t.......................................................
8.3.3
Finding and Replacing T e x t ...................................................
8.3.4
Moving in LISP C o d e ..........................................................
8.3.5
Inserting Nongraphic Characters..............................................
8.3.6
Changing C a s e .................................................................
8.3.7
Inserting a File or B u ffer.......................................................

8-10
8-11
8-11
8-12
8-12
8-13
8-13
8-13

8.4

Using Multiple Buffers and W in d o w s ...................................................
8.4.1
Introduction to Buffers and W in d ow s.........................................
8.4.2
Creating New Buffers from Within the Editor................................
8.4.3
Working with Buffers............................................................
8.4.3.1
Saving Buffer C o n ten ts...........................................
8.4.3.2
Deleting B uffers....................................................
8.4.3.3
Buffer Name Conflicts.............................................
8.4.4
Manipulating Editor W in d o w s.................................................
8.4.5
Moving Text Between B uffers.................................................

8-14
8—14
8-16
8-16
8-17
8—17
8-17
8-17
8-18

8.5

R ecoverin g from P r o b l e m s ...............................................................

8-18

8.6

C u stom izin g the E d it o r .....................................................................

8-19

8.6.1

8.6.2

Chapter 9

Binding Keys to C om m an d s...................................................
8.6.1.1
Binding Within the Editor.........................................
8.6.1.2
Binding from the LISP Interpreter..............................
8.6.1.3
Selecting a Key or Key S equen ce .............................
8.6.1.4
Key Binding Context and Shadow ing...........................
Keyboard M a cros................................................................

6-19
8-20
8-20
8—23
8-23
8-24

Using the VAX LISP Inspector

9.1

Invoking the In s p e c to r....................................................................................................
9.1.1
Asynchronous Mode ..........................................................
9.1.2
Synchronous Mode ............................................................

9-2
9-4
9-5

9.2

Exiting the Inspector ......................................................................................................

9-5

9.3

inspecting O b je c ts ............................................................................................................
9.3.1
Specifying Objects to Inspect ................................................
9.3.2
Managing Inspect Windows .................................................
9.3.2.1
Locking Inspect Windows ........................................
9.3.2.2
Unlocking Inspect Windows ....................................
9.3.2.3
Closing Inspect Windows .......................................
9.3.2.4
Removing Inspected Objects ...................................
9.3.3
Using the History Window ...................................................

9-5
9-6
9-8
9-8
9-8
9-8
9-8
9-9

9.4

Modifying Objects ............................................................................................................
9.4.1
Using the Modify Menu Item .................................................
9.4.2
Using the Clipboard ..........................................................

9-10
9-10
9-11

9.5

Updating the Inspector Display

..................................................................................

9-12

9.6

Returning V a lu e s ..............................................................................................................

9-13

Chapter 10

Using the Debugging Utilities from the DECwindows Interface

10.1

Control V a ria b le s ..............................................................................................................

10-5

10.2

Control S ta c k ......................................................................................................................

10-5

10.3

Break L o o p ........................................................................................................................
10.3.1
Invoking the Break L o o p .......................................................
10.3.2
Exiting the Break L o o p .........................................................
10.3.3
Using the Break L o o p ..........................................................

10-5
10-5
10-6
10—7

10.4

Debugger .....................................................................................
10.4.1
Invoking the Debugger from D E C w in d ow s..................................
10.4.1.1
The Debug I/O Window ..........................................
10.4.1.2
The CallingStack W indow ........................................
10.4.1.3
The Variable Bindings W in d ow ..................................
10.4.1.4
The Debugger Com m ands W indow ............................
10.4.2
Exiting the D e b u g g e r ..........................................................
10.4.3
Using Debugger C o m m a n d s ..................................................
10.4.3.1
A rg u m e n ts.........................................................

10-9
10—9
10—10
10-10
10-11
10-11
10—11
10-12
10-13

10.5

S te p p e r................................................................................................................................
10.5.1
Invoking the Stepper ..........................................................
10.5.2
Stepping Through a F o r m .....................................................

10-14
10—15
10—16
ix

10.5.3
10.5.4
10.5.5
10.6

Appendix A

Exiting the S tep p er..............................................................
Stepper Output ...............................................................
Using Stepper C om m an d s.....................................................

10-16
10—17
10-17

T ra c e r...................................................................................................................................
10.6.1
Enabling the T r a c e r ............................................................
10.6.1.1
Enabling the Tracer from the Operations M en u ...............
10.6.1.2
Enabling the Tracer from a P rom pt............................
10.6.1.3
Clearing the Tracer ..............................................
10.6.1.4
Disabling the T r a c e r ..............................................
10.6.1.5
Disabling the Tracer from the Operations Menu .............
10.6.1.6
Disabling the Tracer from a Prom pt............................
10.6.2
Tracer O u tp u t...................................................................
10.6.3
Modifying Tracer Options from the DialogBox .............................
10.6.3.1
Invoking the Debugger from the Trace Options Dialog
B o x .................................................................
10.6.3.2
Invoking the Stepper from the Trace Options Dialog Box . .
10.6.3.3
Removing Information from Tracer Output from the Trace
Options Dialog Box ..............................................
10.6.3.4
Adding Information to Tracer Output from the Trace Options
Dialog B o x ........................................................
10.6.3.5
Defining When a Function or Macro Is Traced from the
Trace Options Dialog B o x .......................................
10.6.4
Modifying Tracer Options in the Call to the TRACE M a c r o ..............

10-18
10-18
10-18
10—19
10-19
10—20
10-20
10-20
10-20
10-21
10-21
10—22
10—23
10—23
10—23
10—23

Using DECwindows

A.1

Using the M o u s e ...............................................................................................................

A-1

A.2

What Are W indow s?..........................................................................................................

A-2

A.3

Starting a S e s s io n ............................................................................................................

A-3

A.4

Selecting W indow s............................................................................................................

A-4

A.5

Changing the Size of W in d o w s .....................................................................................

A-4

A.6

Shrinking Windows ..........................................................................................................

A -5

A.7

Expanding Icons to W in d o w s ........................................................................................

A-6

A.8

Moving W in d o w s ...............................................................................................................

A-6

A.9

Stacking Overlapping W in d o w s .....................................................................................
A.9.1
Making Overlapping Windows Stick in Place...............................................
A.9.2
Releasing Windows Locked in the Stacking O rder.....................................

A -7
A -7
A-8

A.10

Choosing Items from Pull-Down M e n u s .......................................................................

A-8

A.11

Choosing Items from S u b m e n u s ...................................................................................

A -9

A.12

Choosing Items from Pop-Up M e n u s ............................................................................

A-9

A.13

Choosing Items from Option M enus..............................................................................

A-10

A.14

Supplying Information in Dialog Boxes .......................................................................
A.14.1
Moving and Changing Settings in a Dialog Box..........................................
A.14.2
Making Selections from List B o x e s ..............................................................

A-11
A-12
A-12

A.15

Scrolling

A-13

A.16

Editing T e x t.........................................................................................................................
A.16.1
Selecting T e x t ....................................................................
A. 16.2 Copying T ext.....................................................................
A.16.3
Moving Text Between Windows ..............................................
A.16.4
Deleting Text with Pending D elete.............................................
A.16.5
Editing Text in Dialog Boxes ..................................................

A-14
A-15
A-15
A-16
A-16
A-17

A.17

Composing SpecialC h ara cte rs .......................................................................................

A-17

A.18

Getting Help .........................................
A.18.1
Invoking H e l p ....................................................................
A.18.2
Navigating in H e l p ..............................................................
A.18.3
Searching Help for Titles and K eywords......................................
A.18.4
Exiting from H e lp ................................................................

A-18
A-18
A-19
A-20
A-20

A.19

Putting a Session on Hold .................................................................

A-20

A.20

Ending a S essio n ...............................................................................................................

A-21

Appendix B

Performance Hints
Data S tru c tu re s ...........................................................
B.1.1
In te g e r s.....................................
B.1.2
Floating-Point N um bers....................
B.1.3
R a t i o s .......................................
B.1.4
Complex N u m b ers.........................
B.1.5
C h a ra cte rs..................................
B.1.6
S y m b o ls.....................................
B.1.7
Lists and V ecto rs...........................
B.1.8
Strings, General Vectors, and Bit Vectors
B.1.9
Hash T a b le s ................................
B.1.10
F u n ction s....................................

B-1
B—1
B—2
B—2
B—2
B—2
B—3
B—3
B-4

B.2

Declarations

B-5

B.3

Program S tru c tu re .............................................................................................................

B-7

B.4

Compiler Requirements ....................................................................

B-9

B.1

Appendix C

B -4

B—5

Customizing DECwindows from VAX LISP

C.1

Customizable A ttrib u te s ...................................................................
C.1.1
Common Attributes..............................................................
C.1.2
Specific Attributes and R estriction s...........................................
C.1.2.1
Inspector Attributes ...............................................
C.1.2.2
Listener A ttributes................................................
C.1.2.3
Debugger Attributes...............................................
C.1.2.4
Trace Attributes...................................
C.1.2.5
Editor R estriction s.................................................

C—1
C—1
C—2
C—2
C-3
C—3
C-3
C—3

C.2

Getting Information on Fonts .............................................................
LIST-FONTS FUNCTION.....................................................................

C-4
C-A

C.3

Getting and Modifying A ttributes.........................................................
CUSTOMIZATION FUNCTION..............................................................

C-6
C-6

C.4

Saving Custom izations.....................................................................
SAVE-CUSTOMIZATIONS FUNCTION.....................................................

C-12
C-12

C.5

Recalling C ustom izations..................................................................
LOAD-CUSTOM IZATIONS FUNCTION ...................................................

C-13
C-13

Appendix D

Using the "EMACS" Editor Style

D.1

Introduction to the E d ito r ..................................................................

D-1

D.2

Activating the "EMACS" S ty le .............................................................
D.2.1
Activating "EMACS" as a Minor Style .......................................
D.2.2
Making "EMACS" the Major S t y le .............................................

D-2
D-3
D-3

D.3

"EMACS" Style Key B in d in g s ............................................................

D-3

Appendix E

Editor Commands and Key Bindings

E.1

Editor Command Descriptions.............................................................

E-1

E.2

Editor Key B in d in g s.........................................................................

E-14

5-1

Defining a LISP Function

5-14

3—1

Invoking the Editor.............................................................................

3—3

3—2

The Editor Screen with Help M e s s a g e .....................................................

3—4

Index

Examples

Figures

3-3

Entering Commands at the Editor Prompt ................................................

3-5

3—4

Using APROPOS in the E ditor..............................................................

3-6

3—5

Numeric K e y p a d ..............................................................................

3—12

3-6

The Editor with Two Buffers Open

.........................................................

3-24

3—7

Listing Buffers in the E d ito r ..................................................................

3—25

5—1

Copying a Sample Source F ile...............................................................

5-2

Invoking L I S P ..................................................................................

5-3

5—3

Listener W in d o w ..............................................................................

5—4

Evaluating a LISP Form ......................................................................

5-5

Loading a LISP Source F ile..................................................................

5-6

Inspecting a Structure.........................................................................

5—7

5-7

Choosing the Inspect Menu Item ...........................................................

5-8

5—8

Inspecting a L i s t ...............................................................................

5-8

5-9

Inspector History W in d o w ....................................................................

5-9

5-10

Running a LISP Function ....................................................................

5-10

5-11

Choosing the ED Function....................................................................

5-11

5-12

Editing a File....................................................................................

5—12

5-13

Basic Editing Commands

....................................................................

5-13

5-14

Running the PRINT-RECIPE F u nction......................................................

5-15

5—15

Debugging Dialog B o x ........................................................................

5—16

5-16

Debugging W indow s...........................................................................

5-17

5—17

Using the DOWN C o m m a n d .................................................................

5—18

5-18

Stepping Through a Function.................................................................

5-19

19 Exiting from VAX L I S P ........................................................................

5-20

1 DECwindows FileView-Run Dialog B o x ....................................................

6-2

6— 2 DECwindows FileView-Work in Progress Dialog B o x ....................................

6-3

7— 1 Listener M e n u s ................................................................................

7-1

7—2

Listener W in d o w ...............................................................................

7—2

7-3

File Selection B o x .............................................................................

7-6

7—4

Compile-File File Select B o x ................................................................

7—7

7-5

Save As Dialog B o x ...........................................................................

7-9

7-6

Apropos Dialog B o x ...........................................................................

7-14

7— 7 Describe Dialog B o x ...........................................................................

7-15

8— 1 Editor M enus....................................................................................

8—1

8-2

Editor Window with Two B u ffers.............................................................

8-3

8—3

Editor Window with Two B u ffers.............................................................

8-7

8—4

Apropos Display ...............................................................................

8-9

5 List Buffers Display ...........................................................................

8—15

1 Inspector M e n u s ...............................................................................

9-1

9-2

Invoking the Inspector

........................................................................

9-2

9-3

Inspect and History W in d ow s.................................................................

9-4

Inspecting a Component of an Inspected O b je c t ..........................................

9-7

9-5

Inspecting a Structure..........................................................................

9-7

9-6

Inspector History W in d o w ....................................................................

9-9

9-7

Modify Dialog B o x .............................................................................

9—11

9-8

Inspect Windows Before Updating

..........................................................

9-12

9-9

Inspect Windows After Updating

............................................................

9-13

9— 10 Returning a Value from the Inspector ......................................................

9—14

10-

1 Fatal Error Caution Box ......................................................................

10-1

10-2

Continuable Error Caution B o x ...............................................................

10-2

10—3

Debugging Utilities Pull-Down Menus .......................................................

10—4

10-4

Defining a Variable..............................................................................

10-7

10-5

Invoking the Break L o o p .......................................................................

10-8

10-6

Debug I/O, Calling Stack, Variable Bindings, and Debugger Commands
Windows ......................................................................................

10—10

10—7

The Quit Command Confirmation B o x ......................................................

10—12

10-8

Invoking the Stepper

..........................................................................

10—15

10—9

Stepper Window D isp la y .......................................................................

10—16

10—10 Trace W indow ...................................................................................

10—19

10-11 Trace Options Dialog B o x .....................................................................

10-22

Tables
1-

1 File Specification D efau lts....................................................................

1—8

1 Keys Used in Line Editing....................................................................

2-3

2-2

Control C h aracters.............................................................................

2-4

2-3

DCL LISP Command Q u a lifiers.............................................................

2-8

2— 4 DCL LISP Command Qualifier M o d e s ......................................................

2-9

1 General-Purpose Commands and Key Bindings .........................................

3—9

3—2

Editing Commands and Key B in d in g s......................................................

3—19

3-3

Commands for Manipulating Buffers andWindows

3-4

Characters Generated by Keys

.......................................

3-28

.............................................................

3-31

5 Commands for Customizing the Editor......................................................

3-36

1 Debugging Functions and M a cros...........................................................

4—1

4—2

Debugger C om m an d s.........................................................................

4—7

4-3

Debugger Command M odifiers...............................................................

4-8

4—4

Stepper C o m m a n d s...........................................................................

4—18

1 VAX LISP Default Key B in d in g s.............................................................

7-4

1 Editor Default Pointer Bindings...............................................................

8-11

2 Characters Generated by Keys

8-21

.............................................................

1 Components of Inspectable Data T y p e s ....................................................

9-6

2 Inspector History Status F l a g s ...............................................................

9-9

10— 1 Debugging Functions and M a cros...........................................................

10-3

10—2

Debugger C om m an d s.........................................................................

10—13

10-3

Debugger Command M odifiers...............................................................

10—14

10-4

Stepper C o m m a n d s ...........................................................................

10-17

C-1

Object Keywords for DECW-UTILS:CUSTOMIZATION Function........................

C-6

C-2

Attribute Keywords for Customization Functions .........................................

C—8

D-1

Commands for Manipulating Buffers andWindows

.......................................

D-2

"EMACS" Style Key B indings................................................................

D-4

E-1

Editor Commands and Key B in dings........................................................

E-1

E-2

Editor Key B in d in g s...........................................................................

E-14

Preface
The VAX LISP /VMS Program Development Guide is for developing and debug
ging LISP programs and for compiling and executing LISP programs on the VMS
operating system. It is intended for use on DECwindows and terminal inter
faces. The VAX LISP language elements are described in Common LISP: The
Language.*

Intended Audience
This manual is designed for programmers who have a working knowledge of LISP.
Detailed knowledge of the VMS operating system is helpful but not essential;
familiarity with the Introduction to VMS is recommended.
However, some sections of this manual require more extensive understanding
of the operating system. In such sections, you are directed to the appropriate
manual(s) for additional information.

Structure
An outline of the organization and chapter content of this manual follows:
Part I: VAX LISP System C oncepts and Facilities for VMS System s

Part I consists of four chapters, which explain VAX LISP concepts and describe
the VAX LISP facilities for the terminal interface. Most of the concepts described
in P a rt I a ls o a p p ly to P a r t II.

• Chapter 1, Introduction to VAX LISP, provides an overview of VAX LISP,
explains how to use the help facilities, describes VMS file specifications and
the logical name mechanism, and provides hints on entering DCL commands.
Chapter 1 also describes where in the VAX LISP documentation you can find
information on each of the VAX LISP features.
• Chapter 2, Using VAX LISP, explains how to invoke and exit from VAX
LISP, use control key sequences, enter and delete input, create and compile
programs, load files, and use suspended systems. In addition, Chapter 2
describes the DCL LISP command and its qualifiers.
• Chapter 3, Using the VAX LISP Editor, describes how to use the Editor
provided with VAX LISP to create and edit LISP code.
• Chapter 4, Debugging Facilities, explains how to use the VAX LISP debugging
facilities.
Guy L. Steele, Jr., Common LISP: The Language, Digital Press (1984), Burlington, Massachusetts.

Part II: Using VAX LISP Facilities with the DECwindows Interface

Part II consists of six chapters, which explain how to use the VAX LISP facilities
from the DECwindows interface.
• Chapter 5, The DECwindows Interface to VAX LISP, describes the LISP
utilities that run on the DECwindows interface and how to use them. A
sample LISP programming session is included in the chapter.
• Chapter 6, Starting LISP from DECwindows, describes the different ways
you can invoke LISP to enter an interactive LISP session, compile a file, or
resume a suspended session.
• Chapter 7, The Listener, describes how to use the Listener to enter LISP
forms, select or edit text and objects, work with files, and get help.
• Chapter 8, Using the VAX LISP Editor in DECwindows, describes the dif
ferent editing modes available from the DECwindows interface and how to
access them.
• Chapter 9, Using the VAX LISP Inspector, describes how to invoke the
Inspector and exit from it, inspect and modify objects, update the Inspector
display, and return a value from the Inspector.
• Chapter 10, Using the Debugging Utilities from the DECwindows Interface,
describes how to use the Break loop, the Debugger, the Stepper, and the
Tracer from the DECwindows interface.

A ssociated Documents
The following documents are relevant to VAX LISP programming on VMS sys
tems:
• VAX LISP/VMS Installation Guide
• Common LISP: The Language
• VAX LISP /VMS Editor Programming Guide
• VAX LISP/VMS System Access Guide
• VAX LISP /VMS Interface to VWS Graphics
• VAX LISP/VMS System-Building Guide
• VMS DCL Dictionary
• VAX Architecture Handbook
• VMS V 5.0 Documentation, Programming Subkit
For a complete fist of VMS software documents, see the Overview of VMS
Documentation.

XVI

Conventions
The following conventions are used in this manual:
C o n v e n tio n

M e a n in g

UPPERCASE

D CL commands and qualifiers and VMS file names are printed in
uppercase characters; however, you can enter them in uppercase,
lowercase, or a combination o f uppercase and lowercase characters.
For example:
The exam ples d ir e c t o r (SYS$SYSROOT:[VAXLISP.EXAMPLES] by
default) contains sam ple LISP source files.

UPPERCASE
TYPEWRITER

Defined LISP functions, macros, variables, constants, and other
symbol names are printed in uppercase TYPEWRITER charac
ters; however, you can enter them in uppercase, lowercase, or a
combination of uppercase and lowercase characters. For example:
The CALL-OUT m acro calls a defined external routine....

lo w e r c a se
ty p e w r ite r

LISP forms are printed in the text in lowercase t y p e w r i t e r
characters; however, you can enter them in uppercase, lowercase, or
a combination o f uppercase and lowercase characters. For example:
( s e t f exam ple-1

SANS SERIF

(m ak e- sp a ce) )

Format specifications o f LISP functions and macros are printed in a
sans serif typeface. For example:
CALL-OUT external-routine &REST routine-arguments

ita lics

Lowercase ita lics in format specifications and in text indicate argu
m ents that you supply; however, you can enter them in lowercase,
uppercase, or a combination o f lowercase and uppercase characters.
For example:
The routine-argum ents m ust be com patible with the argum ents
defined in the call to the DEFINE-EXTERNAL-ROUTINE macro.

()

Parentheses UBed in exam ples o f LISP code and in form at spec
ifications indicate the beginning and end o f a LISP form. For
example:
( s e t q name l i s p )

□

Square brackets in format specifications enclose optional elements.
For example:
[doc-string]
Square brackets do not indicate optional elements when they are
used in the syntax o f a directory name in a VMS file specification.
Here, the square bracket characters m ust be included in the syntax.
For example:
(pathname "MIAMI: : DBA1: [ SMITH]LOGIN.COM;4")

In function and m acro format specifications, braces enclose elements
that are considered one unit o f code. For example:
{keyword value}

xvii

C o n v e n tio n

M e a n in g

In function and macro format specifications, braces followed by
an asterisk enclose elem ents that are considered one unit o f code,
which can be repeated zero or m ore times. For example:
{keyword value}*

&OPTIONAL

In function and macro format specifications, the word &OPTIONAL
indicates that the argum ents that follow it are optional. For exam 
ple:
PPRINT object &OPTIONAL stream
Do not specify &OPTIONAL when you invoke a function or m acro
w hose definition includes &OPTIONAL.

&REST

In function and m acro format specifications, the word &REST
indicates that an indefinite number of argum ents may appear. For
example:
CALL-OUT external-routine &REST routine-arguments
Do not specify &REST when you invoke a function or m acro w hose
definition includes &REST.

&KEY

In function and macro format specifications, the word &KEY indi
cates that keyword argum ents are accepted. For example:
COMPILE-FILE input-pathname
&KEY LISTING :MACHINE-CODE OPTIMIZE
:OUTPUT-FILE :VERBOSE WARNINGS
Do not specify &KEY when you invoke a function or macro whose
definition includes &KEY.
A horizontal ellipsis in a format specification m eans that the ele
m ent preceding the ellipsis can be repeated. For example:
function-name . . .
A vertical ellipsis in a code exam ple indicates that all the informa
tion that the system would display in response to the function call
is not shown; or that all the information a user is to enter is not
shown.

|R e t u r n |

A word inside a box indicates that you press a key on the keyboard.
For example:
|R e t u r n

|or |Tab|

In code examples, carriage returns are im plied at the end o f each
line. However, I R e t u r n I is used in som e exam ples to em phasize carriage returns.
[ c tr i« l

Two key names enclosed in a box indicate a control key sequence in
which you hold down Ctrl while you press another key. For example:
IC t r l / C |or |C t r l/ S |

EE3H

A sequence such as | | I x \indicates that you m ust first press and
release the key labeled PF1, then press and release another key.
p f i

C o n v e n tio n

M e a n in g

m ouse

The term mouse refers to any pointing device, such as a mouse, a
puck, or a stylus.

MB1, MB2, MB3

By default, MB1 indicates the left m ouse button, MB2 indicates the
m iddle m ouse button, and MB3 indicates the right m ouse button.
You can rebind the m ouse buttons.

Red print

In interactive examples, user input is shown in red. For example:
Lisp> (cdr ' (a b c))
(B C)
Lisp>

XIX

Parti
VAX LISP System Concepts and Facilities
for VMS System s

Chapter 1

Introduction to VAX LISP
LISP is a general-purpose programming language. The language is used
extensively in the field of artificial intelligence for research and development of
robotics, expert systems, natural-language processing, game playing, and theorem
proving. The LISP language is characterized by:
• Computation with symbolic expressions and numbers
• Simple syntax
• Representation of data by symbolic expressions or multilevel lists
• Representation of LISP programs as LISP data, which enables data
structures to execute as programs and programs to be analyzed as data
• A function named eval, which explicitly invokes the LISP interpreter
• Automatic storage allocation and garbage collection
This manual describes VAX LISP on the VMS operating system, but refers to it
as VAX LISP, where practicable.
This chapter provides an overview of the VAX LISP language. The overview
parallels the structure of this manual and the remaining VAX LISP documenta
tion. The chapter also explains how to get on-line help at the DCL and the LISP
language levels of operation and describes:
• VMS file specifications
• Logical names
•

H in ts for e n te r in g D C L c o m m a n d s

1.1 Overview of VAX LISP
The VAX LISP language is an extended implementation of the Common LISP
language defined in Common LISP: The. Language. In addition to the features
supported by Common LISP, VAX LISP provides the following extensions:
• DCL (Digital Command Language) LISP command
• Extensible editor
• Error handler
• Inspector
• Debugging facilities
• Extensible pretty printer
• Facility for calling out to external routines
Introduction to VAX LISP

1-1

• Facility for calling back to LISP functions from external routines
• Facility for defining non-LISP data structures (alien structures)
• Facility for defining interrupt functions (that is, functions that execute
asynchronously due to VMS AST’
s)
• Access to the VWS capabilities of the VAXstation workstation
• DECwindows Tbolkit interface
• CLX interface to the X Window System
• Utility for creating custom LISP systems
These extensions are described in Section 1.1.1 through Section 1.1.14.
Some of the functions, macros, and facilities defined by Common LISP are
modified for the VAX LISP implementation. VAX LISP Implementation and
Extensions to Common LISP provides implementation-dependent information
about the following topics:
• Data representation
• Pathnames
• Garbage collector
• Input and output
• Asynchronous functions
• Compiler
• Functions and macros
The implementation-dependent functions and macros mentioned in Common
LISP: The Language are defined in VAX LISP/VMS Object Reference Manual.
VAX LISP also supplies a number of functions that are extensions of the
I/O system defined in Common LISP: The Language, as well as a means of
defining new types of streams. These extensions are described in VAX LISP
Implementation and Extensions to Common LISP.

1.1.1

DCL LISP Command
The DCL LISP command invokes VAX LISP from the VMS command level on the
terminal interface. Depending on the qualifier you use with the LISP command,
you can start the LISP interpreter or the LISP compiler. Chapter 2 describes the
LISP command and the qualifiers you can use with it. Chapter 2 also explains
how to:
• Invoke LISP
• Exit LISP
• Create programs
• Load files
• Compile programs
• Use suspended systems
Chapter 6 describes how to invoke LISP from the DECwindows interface.

1-2

Introduction to VAX LISP

1.1.1.1

Interpreter

The VAX LISP interpreter reads an expression, evaluates the expression, and
prints the results. You interact with the interpreter in command line fashion.
While in the interpreter, you can create LISP programs. You can also use pro
grams that are stored in files if you load the files into the interpreter. Chapter 7
explains how to create LISP programs and how to load files into the VAX LISP
interpreter.
1.1.1.2 Compiler

The VAX LISP compiler is a LISP program that translates LISP code from text
to machine code. Because of the translation, compiled programs run faster than
interpreted programs.
You can use the compiler to compile a single function or macro or to compile a
LISP source file. If you are in the LISP interpreter, you can compile a single
function or macro with the compile function (see Chapter 2).
You can compile a source file either at the VMS command level or the LISP level
of operation. If you are at the VMS command level, you must specify the LISP
DCL command with the /COMPILE qualifier; if you are in the LISP interpreter,
you must invoke the com pile -f il e function. Chapter 2 explains how to compile
LISP programs that are stored in files.

1.1.2

Editor
VAX LISP includes a screen-oriented editor. You can use it to edit text files and
functions and macros that are defined in the LISP system. The Editor provides
specialized commands to help you edit LISP code; they balance parentheses,
indent, and evaluate LISP code. Chapter 3 describes how to use the Editor to
write and edit LISP code. Chapter 8 describes how to access the Editor from the
DECwindows interface.
The Editor is written in LISP, so you can extend and customize it for your needs.
The Editor provides predefined commands and several functions, macros, and
data structures, which you can use to create Editor commands. After you create
an Editor command, you can bind it to a key on your keyboard. In this way, you
can build up alternative editing systems or complete applications based on the
Editor. See the VAX LISP/VMS Editor Programming Guide for more information
on programming the Editor.

1.1.3

Error Handler
VAX LISP contains an error handler, which is invoked when errors occur during
the evaluation of a LISP program. VAX LISP Implementation and Extensions to
Common LISP describes the error handler and explains how to create your own
error handler.

1.1.4

Inspector
VAX LISP provides an Inspector, which is an implementation of the Common
LISP i n s p e c t function. The Inspector is only available on the DECwindows
interface. You can use the Inspector to examine and modify data structures.
Chapter 9 explains how to use the Inspector.
Introduction to VAX LISP

1-3

1.1.5 Debugging Facilities
VAX LISP provides several functions and macros that return or display informa
tion you can use when you are debugging a program. VAX LISP also provides
four debugging facilities: the break loop, Debugger, stepper, and tracer.
The functions that return debugging information and the break loop, stepper, and
tracer facilities are defined in Common LISP and are extended in VAX LISP. The
break loop lets you interrupt the evaluation of a program, the stepper lets you
use commands to step through the evaluation of each form in a program, and the
tracer lets you examine the evaluation of a program.
The Debugger is a VAX LISP facility. The facility provides commands that let you
examine and modify the information in the LISP system’
s control stack frames.
Chapter 4 explains how to use the debugging facilities. Chapter 10 explains how
to use the debugging facilities from the DECwindows interface.

1.1.6 Pretty Printer
VAX LISP provides a pretty-printer facility. You can use the facility to control
the format in which LISP objects are printed. The pretty printer can be helpful
in making objects easier to read by means of indentation and spacing. You can
use the pretty printer with the existing defaults, control it with control variables,
or extend it by using special directives with the format function. VAX LISP
Implementation and Extensions to Common LISP explains how to use the pretty
printer in each way.

1.1.7 Call-Out Facility
VAX LISP includes a call-out facility, which lets you call routines written in other
VAX/VMS programming languages as well as run-time library (RTL) routines and
VMS and RMS system services. Chapter 4 of the VAX LISP /VMS System Access
Guide describes the call-out process and explains how to use the call-out facility.

1.1.8 Call-Back Facility
VAX LISP includes a call-back facility, which lets you invoke a LISP function
from an external routine that has been called out to by a LISP call-out. Chapter
4 of the VAX LISP/VMS System Access Guide describes how to use the call-back
facility.

1.1.9 Alien Structure Facility
VAX LISP supplies an alien structure facility. It lets you define, create, and
access VAX data structures that are used to communicate between the VAX LISP
language and other VAX/VMS languages or system services. Chapter 6 of the
VAX LISP/VMS System Access Guide describes the alien structure facility and
explains how to use it.

1—4

Introduction to VAX LISP

1.1.10 Interrupt Function Facility
VAX LISP allows you to define functions that can execute at arbitrary and
unpredictable points in your program, usually as the result of an event in the
operating system. Such functions are called interrupt functions, because they
interrupt the normal flow of program execution. Chapter 7 of the VAX LISP/VMS
System Access Guide describes how to define and use interrupt functions.

1.1.11

VWS Graphics Interface
VAX LISP provides access to the VWS graphics capabilities of the VAXstation
family of workstations. You can create windows on the screen, draw lines and
write text in the windows, track the workstation’
s pointing device and react to
pointer buttons, and create LISP streams to windows. The VAX LISP /VMS
Interface to VWS Graphics describes this interface.

1.1.12 DECwindows Interface
VAX LISP provides access to the DECwindows Toolkit, which is a set of ap
plication development tools and run-time routines that help you implement
DECwindows applications. VAX LISP/VMS DECwindows Programming Guide
describes how to use VAX LISP to access the Toolkit.

1.1.13 CLX Interface
VAX LISP provides an implementation of the CLX (Common LISP X) interface
to the X Window System protocol. CLX is a package of LISP routines that give
you access to the lower level capabilities of the X Window System without having
to explicitly call out to external routines or define non-LISP data structures.
VAX LISP/VMS DECwindows Programming Guide describes the VAX LISP
implementation of the CLX interface to the X Window System.

1.1.14 System-Building Utility
The VAX LISP System-Building Utility lets you create custom VAX LISP systems.
A custom VAX LISP system has the following potential advantages:
• It can exclude various components of VAX LISP, thereby reducing the size of
LISP.
• It can include VAX LISP code that you write.
• It can start execution by calling a function that you specify.
• It can be used as a delivery vehicle for a VAX LISP-based application.
The VAX LISP/VMS System-Building Guide describes the System-Building
Utility.

Introduction to VAX LISP

1-5

1.1.15 VAX LISP Function, Macro, and Variable Descriptions for VMS
VAX LISP contains many functions, macros, and variables that are either not
mentioned or are mentioned but not fully defined in the Common LISP language.
These functions, macros, and variables are divided into the following categories:
• Implementation-dependent objects mentioned but not fully defined in
Common LISP: The Language
• VAX LISP objects that implement the parts of VAX LISP that are described
in this manual
• VAX LISP extensions to the Common LISP I/O system
• Editor-specific objects
• System access-specific objects (pertaining to the call-out, alien structure,
interrupt function, and program synchronization facilities)
• Graphics-specific objects
• Objects that implement the VAX LISP System-Building Utility
These LISP objects let you use the VAX LISP facilities and some VMS facilities
without exiting or calling out from the LISP system.
The LISP objects in the first two categories listed above are described in VAX
LISP/VMS Object Reference Manual. VAX LISP extensions to Common LISP
I/O are described in VAX LISP Implementation and Extensions to Common
LISP and VAX LISP/VMS System Access Guide. Editor-specific objects are
described in Part III of the VAX LISP/VMS Editor Programming Guide. System
access-specific objects are described in the VAX LISP/VMS System Access
Guide. Graphics-specific objects are described in the VAX LISP/VMS Interface
to VWS Graphics and the VAX LISP/VMS DECwindows Programming Guide.
The VAX LISP System-Building Utility is described in the VAX LISP/VMS
System-Building Guide.

1.2 Help Facilities
When using VAX LISP, you can get help at the DCL, DECwindows, and the LISP
levels of operation.

1.2.1

DCL Help
The VMS help facility lets you obtain on-line information about a DCL command,
its parameters, and its qualifiers. Invoke the help facility by entering the HELP
command. When the HELP command is executed, the facility displays the
available information.
To obtain information about VAX LISP, enter the following command:
$ HELP LISP

1-6

Introduction to VAX LISP

1.2.2 DECwindows Help
The Help menu lets you obtain on-line information about any DECwindows
application. Help provides brief information about screen objects, concepts, or
tasks you can perform in applications.
• To get help on tasks in DECwindows applications, choose the Overview menu
item from the application’
s Help menu.
• To get help on objects, such as menus, scroll bars, and dialog boxes, point
to the screen object and press and hold the Help key on your keyboard while
you click MB1. Note that help is not available on all objects in the VAX LISP
development environment.
• To get help on a menu item, press the Help key while you press and hold MBi
on the menu item, then release MBI.
For more detailed information on DECwindows help, see Appendix A.

1.2.3 LISP Help
VAX LISP provides two functions to obtain help during a LISP session: d e s c r ib e
and a p r o p o s . The d e s c r ib e function displays information about a specified
LISP object. The type of information the function displays depends on the
object you specify as its argument. You can use the a p r o p o s function to search
through a package for symbols whose print names contain a specified string. See
Common LISP: The Language for information about packages. Descriptions of
the d e s c r ib e and a p r o p o s functions are provided in the VAX LISP/VMS Object
Reference Manual.

1.3

VMS File Specifications
A VMS file specification indicates the input file to be processed or the output file
to be produced. File specifications have the following format:
node::device\[directory\filename.filetype;version

A file specification has the following components:
node

The name o f a network node. The name can be either an integer or
a string and can include an access control string. The follow ing node
name includes an access control string:
MIAMI"SMITH MYPASSWORD"::
This com ponent applies only to system s that support DECneWVAX.

device

The name of the device on which the file is stored or is to be written.

directory

U ser’
s current default directory

filename

Input— None
Output— Same as input file; if no input file is specified, there is no
default

filetype

Depends on usage:
FAS— Fast-loading file (output from compiler)
LIS— Error listing (output from compiler)
*LSC— Editor checkpointing file
LSP— Source file (input to LISP reader or compiler)
SUS— Suspended system

version

Input— H ighest existing version number
Output— If no existing version, 1; if existing version, highest version
number plus 1

1-8

Introduction to VAX LISP

1.4 Logical Names
The VAX/VMS operating system provides a logical name mechanism that allows
programs to be device and file independent. Programs do not have to specify
the device on which a file resides or the name of the file that contains data if
you use logical names. Logical names provide great flexibility, because you can
associate them not only with a device or a complete file specification but also with
a directory or another logical name.
For more information on logical names, see the VMS DCL Concepts Manual.

1.5 Entering DCL Commands
This section lists hints for entering DCL commands.
• You can abbreviate command and qualifier names to four characters. You can
use fewer than four characters if the abbreviation is unambiguous.
• Precede each qualifier name with a slash (/).
• If you omit a required parameter (for example, a file specification), the DCL
command interpreter prompts you for the parameter.
• You can enter a command on more than one line if you end each continued
line with a hyphen (-).
• Press the Return key after you enter a command; pressing the Return key passes
the command to the system for processing.
• You can delete the current command line by pressing Ctrt/U.
• You can interrupt command execution by pressing CtrlA'. If you do not enter
a command that executes another image, you can resume the interrupted
command by entering the DCL CONTINUE command. To stop processing
completely after pressing Ctrl/Y, enter the DCL STOP command.

Introduction to VAX LISP

1-9

Chapter 2

Using VAX LISP
This chapter describes the DCL LISP command and its qualifiers and explains
the following procedures for the terminal interface and VWS workstation:
• Invoking LISP
• Exiting LISP
• Entering input
• Deleting and editing input
• Entering the Debugger
• Using control key characters
• Creating programs
• Loading files
• Compiling programs
• Using suspended systems
• Using subprocesses
See Chapter 5 for additional information and restrictions on how to perform these
procedures from the DECwindows interface.

2.1 Invoking LISP
You invoke an interactive VAX LISP session by typing the DCL command LISP.
When it is executed, a message identifying the VAX LISP system appears, and
then the LISP prompt (Lisp>) is displayed. For example:
$ LISP

VAX L IS P [TM], V3.0
C o p y r ig h t © D i g i t a l Equipment C o rp o ra tio n . 1989.
A ll R ig h ts R eserv ed
L isp >

See Section 2.10 for descriptions of the qualifiers you can use with the LISP
command.

Using VAX LISP

2-1

2.2 Exiting LISP
You can exit from LISP by using the LISP e x i t function. For example:
L is p >

( ex it)

When you exit the LISP system, you are returned to the DCL level of operation.
If you have used the Editor, modified buffers are not saved on exiting LISP. See
Chapter 3 for information on how to save modified buffers before exiting LISP.
You cannot exit the LISP system by pressing Ctrl/Z, as you can with many other
interactive programs that run on VMS.

2.3 Entering Input
You enter input into the VAX LISP system a line at a time. Once you move to a
new line, you cannot go back to the previous line. However, you can recover an
input expression or an output value by using the following 10 unique variables:
/

//
///

**
***

++
+++

These variables are described in Common LISP: The Language. The following
example illustrates the use of the plus sign (+) variable that is bound to the
expression most recently evaluated:
L is p > (cdr ' (a b c ) )
(B C)
L is p > +
(cdr (q u ote (a b c ) ))
L is p >

2.4 Deleting and Editing Input
The Delete key deletes characters to the left of the cursor on the current fine of
input. Ctrl/U deletes characters from the cursor position back to the beginning of
the line.
If you are using a video terminal, you can use control characters, function keys,
and arrow keys on the terminal to edit the current line of input.
Table 2-1 lists the keys you can use to delete and edit input.
NOTE

You can use the b in d - keyboard - f u n c t io n function to bind most of the
control characters listed in Table 2—1 to a LISP function. Binding a
control character in this way cancels the effect listed for that control
character in Table 2-1.

2-2

Using VAX LISP

Table 2-1:

Keys Used in Line Editing

K ey

E ffe c t

jCtrl/A |or [F14| t

Switches between overstrike and insert m odes in the current
line.

[Ctrl/Bj

or [[j

[Ctri/D|

or FF

Recalls the last line entered.
Moves the cursor one character to the left.
Moves the cursor to the end o f the line.

|Ctrl/E I

or FF

[ctri/F]

Moves the cursor one character to the right.

[ C ii/H ] O r [F12] t

Moves the cursor to the beginning o f the line.

Deletes the character to the left o f the cursor.

ICtrl/Jf

or 1L in e f e e d |or |F13| t

D eletes the word to the left o f the cursor.
D eletes characters from the cursor position back to the begin
ning o f the line.

j Ctrl/U |

t This key is available only on the LK201 or later keyboards.

2.5 Entering the Debugger
If you make an error during an interactive VAX LISP session, the error auto
matically invokes the Debugger, which replaces the LISP prompt (Lisp>) with
the Debugger prompt (Debug l>). For information on how to use the VAX LISP
Debugger, see Chapter 4. For information on how to use the VAX LISP Debugger
from the DECwindows interface, see Chapter 10.
Pressing Ctrl/C is a quick way to exit from the VAX LISP Debugger. If you want
to recover from an error by discarding the expression you typed and start over,
press Ctrl/C. Ctrl/C returns you to the read-eval-print loop, which displays the LISP
prompt (Lisp>).

2.6 Using Control Key Characters
Table 2-2 lists the control characters you can use in VAX LISP. Ctrl/C is the only
one whose listed function is specific to LISP. The other co n tro l c h a r a c te r s perform
standard VMS functions.
NOTE

You can use the b in d - keyboard - f u n c t io n function to bind most of the
control characters listed in Table 2—2 to a LISP function. Binding a
control character in this way cancels the effect listed for that control
character in Table 2-2.
These control characters do not work in the VAX LISP Editor.

Using VAX LISP

2-3

Table 2-2: Control Characters
Control
Character

Function

[Ctri/Cl

Returns you to the top-level loop from any other command level. In
LISP, Ctrl/C invokes the CLEAR-INPUT function on the *TERMINAL-IO*
stream, then calls the ABORT function. If you want to recover from
an error by discarding the expression you typed and start over, press
Ctrl/C. (See ABORT in VAX L IS P 1VMS Object Reference M anual for an
example of changing the behavior o f Ctrl/C.)

|Ctrl/0|

Discards output being sent to the terminal until you press another
Ctrl/O.

|C1r!/Q|

Resum es terminal output that was halted with Ctrl/S.

|Ctrl/R|

Redisplays what is on a line.

|Ctrl/S|

Stops output to the terminal until a Ctrt/Q is pressed.

[cifi7f|

Displays process information. This is useful during a computation to
watch the resources used.

ICtrl/UJ

Deletes characters from the cursor position back to the beginning o f the
current input line. The prom pt is not echoed in LISP.

ICtrl/XI

Deletes all input not yet read from the type-ahead buffer.

fCtfi/Yl

Returns you to the DCL level o f control and purges the type-ahead
buffer.

2.7 Creating Programs
The most common way to create a LISP program is by using a text editor. In
this way, the program exists in a source file that can be loaded into the LISP
environment by the LISP load function.
Although you can compose source programs with any text editor, the VAX LISP
Editor provides facilities to enter and edit LISP source code. For example,
the Editor helps you balance parentheses and maintain proper indentation.
Furthermore, this editor, being integrated into the LISP environment, can be
extended with features that fit your own style of editing. See Chapter 3 for a
description of how to use the Editor.
Another way to create LISP programs is to define them, using the interpreter
in an interactive LISP session. If you define functions with the defun macro or
macros with the defmacro macro, the definitions become a part of the interpreted
LISP environment. You can then invoke your defined functions and macros.
However, since these definitions are not in a permanent text file, your work
is stored only temporarily and disappears when you exit VAX LISP. Entering
programs by typing to the interpreter is only useful for experimenting with small
functions and macros.

2.8 Loading Files
Before you can use the definitions stored in a file in interactive LISP, you must
load the file into the LISP system. The file can be compiled or interpreted;
compiled files tend to load more quickly. You can load a file into the LISP system
in three ways from a terminal interface:
• Load the file by specifying the DCL LISP /INITIALIZE qualifier. For example:
2-4

Using VAX LISP

$ LISP/INITIALIZE=MYINIT.LSP
VAX L IS P [TM], V e r s io n V3.0
C o p y r ig h t © D i g i t a l E qu ipm en t C o r p o r a t io n .
A l l R ig h t s R e s e r v e d .

1989.

L is p >

The LISP prompt indicates the file has been successfully loaded. If the file is
not successfully loaded, an error message indicating the reason appears on
your terminal screen. Include the /VERBOSE qualifier to cause the names of
objects loaded in an initialization file to be fisted at the terminal. For more
information on the /VERBOSE qualifier, see Section 2.10.13.
• Load the file by using the LISP LOAD function when in an interactive LISP
session. For example:
L is p > ( lo a d " t e s t p r o g . l s p " )
; L o a d in g c o n t e n t s o f f i l e DBA1: [JONES]TESTPROG.L S P ;1
;
FACTORIAL
;
FACTORS-OF
; F i n i s h e d l o a d i n g DBA1: [JONES]TESTPROG.LSP;1
T
L is p >

The file name (t e s t p r o g .l s p ) in the example can be a string, symbol, stream,
or pathname, f a c t o r ia l and f a c t o r s - of are the functions contained in the
file TESTPROG.LSP. The final T indicates that the file has been successfully
loaded. For more information on the load function, see VAX LISP /VMS
Object Reference Manual.
• Evaluate the contents of a buffer in the Editor when that buffer contains a
file. See Chapter 3 for more information on this topic.
With the /INITIALIZE qualifier, you can load more than one file at a time. With
the load function, however, you can specify only one file at a time.

2.9 Compiling Programs
You compile LISP programs by compiling the LISP expressions that make up the
programs. You can compile LISP expressions in two ways: individually, by using
the LISP c o m p il e function; or in a file, by using either the LISP c o m p il e - f il e
function within LISP or the LISP verb with the /COMPILE q u a lifie r fro m DCL.

2.9.1

Compiling Individual Functions and Macros
In LISP, the unit of compilation is normally either a function or a macro. You can
compile a function or a macro in a currently running LISP session by using the
c o m p il e function. This function is described in Common LISP: The Language.
You normally call a LISP function first in interpreted form to see if the function
works. Once it works as interpreted, you can test it in compiled form without
having to write the function to a file. Use the c o m p il e function for this purpose.
When you compile a function or a macro that is not in a file, the consequent
compiled definition exists only in the current LISP; the definition is not in
a file. However, you can use the VAX LISP d n co m pile function to retrieve
the interpreted definition. This function, described in VAX LISP/VMS Object
Reference Manual, is useful when debugging programs. Because the interpreted
code shows you more of your function’
s evaluation than the compiled code, you
can find the error more easily. Y ou can modify the function definition in the
Editor to correct the error and also save your corrected version of the function
Using VAX LISP

2-5

in a file. See Chapter 3 for further information on using the Editor to write
interpreted functions to files.

2.9.2 Compiling Files
Any collection of LISP expressions can make up a program and can be stored in a
file. The compiler processes such a file by compiling the LISP expressions in the
file and writing each compiled result to an output file.
At a terminal interface, you can compile VAX LISP files either at DCL level with
the LISP command and the /COMPILE qualifier or in interactive VAX LISP with
the LISP compile-file function. For additional information on compilation from
the DECwindows interface, see Chapter 6.
The /COMPILE qualifier is described in Section 2.10.2. The compile-file
function is described in VAX LISP/VMS Object Reference Manual. The fol
lowing example shows how the /COMPILE qualifier is used to compile the file
MYPROG.LSP at the DCL level:
$ LISP/COMPILE MYPROG.LSP
$

This example produces an output file named MYPROG.FAS.
The next example shows how the compile-fil e function can be used to compile
the file MYPROG.LSP from within the LISP system:
L is p > ( c o m p i l e - f i l e " m y p r o g . ls p " )
S t a r t i n g c o m p il a t io n o f f i l e DBA1: [JONES]MYPROG.LSP;1
FACTORIAL c o m p ile d .
F i n i s h e d c o m p il a t io n o f f i l e
0 E r r o r s , 0 W arnings
"DBA1: [ JONES ]MYPROG.FAS;1"
L is p >

DBA1: [JONES]MYPROG.LSP;1

Both methods of compiling LISP files are equivalent except in their defaults. The
compile-fil e function automatically lists the name of each function it compiles
at the terminal, but the /COMPILE qualifier does not. Both methods produce
fast-loading files (type FAS) that contain code that runs more quickly than code
in uncompiled files. Fast-loading files are automatically placed in the directory
containing the source files from which they are compiled.
The first method of compiling files, using the LISP /COMPILE qualifier, has the
advantage that you can compile several files in one step. For example:
$ LISP/COMPILE FILE1.LSP, FILE2.LSP, FILE3.LSP

When you use the LISP compile-file function, it takes several steps to compile
several files, since you can compile only one file in each call to compile-f il e .
The second method of compiling files, using the LISP compile-fil e function,
has the advantage of enabling you to stay in LISP both during compilation
and afterwards. This method is convenient if you are using the LISP Editor to
create a file and you do not want to leave the LISP environment. The method
is necessary if the compilation depends on changes you have made to the LISP
environment; that is, you have defined some macros or changed a package.
The COMPILE-FILE function returns a namestring corresponding to the output file
it generates. Therefore, immediately after using the compile-file function, you
can load the resulting output file as follows:
L is p >

2-6

Using VAX LISP

( lo a d *)

2.9.3 Advantages of Compiling LISP Expressions
You can use both compiled and uncompiled (interpreted) files and functions
during a LISP session. Both compiled and uncompiled LISP expressions have
their advantages. The advantages of compiling a file, a macro, or a function
follow:
• Compiling a function or a macro is a good initial debugging tool, since the
compilation does static error checking, such as checking the number of
arguments to a function or a macro. For example, consider the following
function definition:
(defun t e s t (x)
( if (> x 0)
(+ 1 x)
( t e s t (try x) x) ) )

In the definition of the function t e s t , the alternate consequent (the false
part) of the IF condition invokes t e s t with two arguments, (try x) and x,
while the function definition of TEST calls for only one argument. Despite this
error, TEST may work correctly as an interpreted (uncompiled) function if the
argument given is a positive number, since it uses only the first consequent
(the true part); so you may not detect the error. But if you compiled the
function, the compiler would detect the error in the second consequent and
issue a warning.
• A compiled file not only loads faster, but the compiled code executes much
faster than the corresponding interpreted code.

2.9.4 Advantage of Not Compiling LISP Expressions
You can debug run-time errors in an interpreted function more easily than you
can debug them in a compiled file or function. For example, if the debugger is
invoked because an error occurred in an interpreted function, you can use the
debugger to find out what code caused the error. If the debugger is invoked
because an error occurred in a compiled function, the code surrounding the form
that caused the error to be signaled may not be accessible. The stepper facility
is also more informative with interpreted than with compiled functions. See
Chapter 4 for information on the debugger and the stepper.

2.10 DCL LISP Command Qualifiers
The LISP command can be specified with several qualifiers according to the
standard VMS conventions. The format of the LISP command with qualifiers
follows:
LISP[/qualifier...]

Some qualifiers have a corresponding negative form, /NOqualifier, which negates
the specified action. Other qualifiers accept values. To specify a qualifier value,
type the qualifier name followed by an equal sign (=) and the value. For example:
/ INITIALIZE=MYPROG.LSP

Qualifier values are surrounded by braces ({ }) when you can choose only one
value from a list. For example:
/ERROR ACTION={EXIT OR DEBUG}

Using VAX LISP

2-7

lb specify a list of qualifier values, enclose the values in parentheses. For
example:
/ INITIALI ZE= (MYPROG1.LSP,MYPROG2.LSP)

You can define DCL symbols to represent LISP command lines that you use
frequently. For example:
$ BIGLISP :== LISP/INITIALIZE=SYS$LOGIN:LISPINIT/MEMORY=20000

Following this command, the DCL symbol BIGLISP, when typed at the DCL
prompt, results in execution of the LISP command line shown.
Section 2.10.2 through Section 2.10.14 describe each qualifier in detail.
Table 2-3:

DCL LISP Command Qualifiers

Qualifier

Function

/COMPILE

Invokes the VAX LISP compiler to compile one or m ore
source files (input argum ents that default to the file type
LSP). /COMPILE is not the default qualifier for the LISP
command; /INTERACTIVE is the default qualifier.

/CSTACI^ n u m b er

Specifies the size of the control stack in the LISP session in
512-byte pages. The default is 185 pages.

/ERROREACTION={EXIT or DEBUG}

EXIT causes your program to exit LISP when an error
occurs. EXIT is the default in batch m ode jobs and in
compile mode (with the /COMPILE qualifier). DEBUG
invokes the VAX LISP debugger when an error occurs.
DEBU G is the default in an interactive LISP session.

/[N0]INITIALIZE=(/iZe-s/>ec,...)

Causes the LISP system to load an initialization file(s).
The default file type for an initialization file is LSP or FAS.
NOINITIALIZE suppresses the loading o f initialization
files.

/INTERACTIVE

Starts an interactive LISP session. /INTERACTIVE is the
default qualifier for the LISP command.

/[NO]LIST=[/iZe-spec]

Specifies that a listing file be created during compilation.
A listing consists of the file name, date of compilation,
names o f the LISP expressions compiled (if the /VERBOSE
qualifier is specified), and w arning and error m essages. The
default file type for a listing file is LIS. /NOLIST suppresses
a listing file and is the default except in batch mode. In
such jobs, /LIST is the default.

/[NOJMACHINE_CODE

Includes VAX LISP machine code in the listing file.
/NOMACHINE_CODE suppresses a listing of the machine
code and is the default.

/MEMORY=numfoer

Specifies the initial amount o f dynamic virtual m emory
LISP allocates in 512-byte pages. The default is 5000 pages.

(continued on next page)

2-8

Using VAX LISP

Table 2-3 (Cont.):

DCL LISP Command Qualifiers

Qualifier

Function

/[NO]OPTIMIZE=(SPEED:n,SPACE:7i,
SAFETY:n,COMPILATION_SPEED:rc)

Tells the com piler that each quality has the correspond
ing value. SPEED is the speed at which the object code
runs, SPACE is the space occupied or used by the code,
SAFETY is the run-time error checking o f the code, and
COMPILATION_SPEED is the speed o f the compilation
process, n is an integer in the range 0 to 3. The value 0 is
the low est priority value; the value 3 is the highest. The
default value for n is 1. See VAX L IS P Implementation and
Extensions to Common L ISP for a description of optim iza
tion declarations.

/[NO]OUTPUT_FILE=[/ZZe-s/>ec]

Causes the name o f the compiled file to be the specified
name. The default output file name is the name o f the
file being compiled. The default output file type is FAS.
/NOOUTPUT_FILE prevents compiled code from being
written to a file. /OUTPUT_FILE is the default.

/RESUME=file

Resum es a suspended LISP system. The default file type for
a suspended LISP system is SUS. See Section 2.11 on U sing
Suspended Systems.

/[NOIVERBOSE

Lists on the output device and the listing file, if any,
the names o f functions and m acros defined in a file.
/NOVERBOSE suppresses a listing o f function and macro
names defined in a file. /NOVERBOSE is the default.

/[NOJWARNINGS

Specifies that the com piler is to produce w arning m es
sages. /NOWARNINGS suppresses w arning messages.
/WARNINGS is the default.

2.10.1

Three Ways to Use the DCL LISP Command
Depending on the qualifier modifying it, you can use the DCL LISP command in
one of the following three ways called modes:
• INTERACTIVE—to invoke an interactive LISP session (the default)
• COMPILE—to compile LISP files
• RESUME—to resume a suspended LISP system
Table 2—4 fists the LISP command qualifiers that apply to each mode. Without
a qualifier, the DCL LISP command puts you in an interactive session (the
default).
Table 2-4:

DCL LISP Command Qualifier Modes

Qualifier

Mode

/COMPILE

COMPILE

/CSTACK

INTERACTIVE or COMPILE

/ERROR_ACTION

INTERACTIVE or COM PILE or RESUM E

/[NOIINITIALIZE

INTERACTIVE or COMPILE

(continued on next page)

Using VAX LISP 2-9

Table 2-4 (Cont.):

DCL LISP Command Qualifier Modes

Qualifier

Mode

/INTERACTIVE

INTERACTIVE

/[NOJLIST

COMPILE

/[NO]MACHINE_CODE

COMPILE

/MEMORY

INTERACTIVE or COMPILE or RESUME

/[NOJOPTIMIZE

COMPILE

/[NO]OUTPUT_FILE

COMPILE

/RESUME

RESUME

/[NOJVERBOSE

INTERACTIVE or COMPILE

/[NOJWARNINGS

COMPILE

2.10.2 /COMPILE
The /COMPILE qualifier invokes the VAX LISP compiler to compile one or more
source files. The compiler creates a fast-loading (FAS) file from each source file.
Unlike other compilers, such as those for BASIC and COBOL, the LISP compiler
does not generate VMS object modules. Consequently, files processed by the LISP
compiler do not have the OBJ file type. FAS is the default file type for a LISP
compiled file. If the /COMPILE qualifier is used with the /NOOUTPUT_FILE
qualifier, the compiler compiles the source file but does not put the compilation
in a file. That method is helpful if your purpose in compiling the file is to check
for errors. See Section 2.10.11 for more information on the /[NO]OUTPUT_FILE
qualifier.
By default, the compiler gives your newly compiled file the same name as your
source file with a FAS file type, puts the new file in your source file ’
s directory,
and returns you to DCL command level when the compiler is finished. If you
want functions to be listed on your output device as they are compiled, you
must specify the /VERBOSE qualifier (see Section 2.10.13). If you want to
compile files with the aid of initialization files, use the /INITIALIZE qualifier (see
Section 2.10.5). For information on how to load files, see Section 2.8.
If you do not specify a file name with the /COMPILE qualifier, DCL prompts you
for a file name. If you use the qualifiers /[NOJLIST, /[NO]MACHINE_CODE,
/OPTIMIZE, /[NO]OUTPUT, /[NOJVERBOSE, and /[NO]WARNINGS with the
/COMPILE qualifier and you specify them before the files to be compiled, the
qualifiers apply to all the files to be compiled. If you use the preceding qualifiers
with the /COMPILE qualifier, but you specify them after a file name, the
qualifiers apply only to the immediately preceding file. If you specify qualifiers
for all the files and a conflicting qualifier for a particular file, the LISP system
uses the qualifier specified for the particular file.
Format
LISP/COMPILE file-speci,...]

Example
$ LISP/COMPILE FACTORIAL.LSP
$

Mode

Compile
2-10

Using VAX LISP

2.10.3 /CSTACK
The /CSTACK qualifier lets you specify the size of the default control stack in
a LISP session in 512-byte pages. The system requires a minimum of 32 pages
to function. If you specify fewer than 32 pages with the /CSTACK qualifier, the
system disregards the requested number of pages and uses 32 pages. The default
number of pages is 185.
You can determine the total space allocated to all stacks from within LISP
with the room or room - a l l o c a t io n function. However, since you cannot use the
/CSTACK qualifier with the /RESUME qualifier, if you want to specify the size
of the control stack, you must do it when you first invoke LISP. For information
on the room and room - a l l o c a t io n functions, see the VAX LISP/VMS Object
Reference Manual.
Format
LISP/CSTACK=number-of-pages
or
LISP/COMPILE/CSTACK=numi>e/--of-pagres file-spec

Example
$

LISP/CSTACK=200

VAX L IS P [TM], V3.0
C o p y r ig h t © D i g i t a l E qu ipm en t C o r p o r a t io n .
A l l R ig h t s R e se r v e d .
L is p >

1989

Mode

Interactive or Compile

2.10.4 /ERROR_ACTION
The /ERROR_ACTION qualifier has two values: EXIT and DEBUG.
• EXIT causes the evaluation of your program to stop and exits LISP if a
fatal or a continuable error occurs (for a complete description of errors and
warnings, see VAX LISP Implementation and Extensions to Common LISP).
EXIT is the default in batch mode and in compile mode, that is, with the
/COMPILE qualifier.
• DEBUG calls the VAX LISP debugger if an error occurs. Once you are in the
VAX LISP debugger, you can look at your error, inspect the control stack, and
continue your program from the point at which it stopped. DEBUG is the
default in an interactive session. See Chapter 4 for more information on the
debugger.
You can use the /ERROR_ACTION qualifier when invoking an interactive LISP
session or when compiling files with the /COMPILE qualifier. The /ERROR_
ACTION qualifier is mainly useful for batch jobs. It is equivalent to the VAX
LISP *e r r o r - a c t io n * variable (see VAX LISP/VMS Object Reference Manual).
Format
LISP/ERROR ACTION=va/ue

Using VAX LISP

2-11

Example
$ LISP/COMPILE/ERROR_ACTION=DEBUG MYPROG.LSP

Mode

Interactive, Compile, or Resume

2.10.5 /[NOJINITIALIZE
The /INITIALIZE qualifier causes the LISP system to load one or more initial
ization files containing LISP source code or compiled code. An initialization file ’
s
purpose is to predefine functions you may want to use in a LISP session. The
default is to have no initialization file.
If the initialization files contain calls to exiting functions or if these files
contain errors and the /ERROR_ACTION qualifier is set to EXIT (/ERROR_
ACTION=EXIT), the LISP system returns to the DCL level without prompting
for interactive input. If the initialization files contain errors and the /ERROR_
ACTION qualifier is set to DEBUG (/ERROR_ACTION=DEBUG), the LISP sys
tem puts you into the debugger. See Section 2.10.4 for more information on the
/ERROR_ACTION qualifier.
The /INITIALIZE qualifier uses the LISP load function to default the proper
type, directory, and other parts of a file specification. For example, you do not
have to specify the file type if your initialization file has a FAS or a LSP file type.
If your directory contains a file name with both a FAS and a LSP file type, the
LISP system selects the most recently created or modified file as the initialization
file. If only a LSP type file or only a FAS type file of a given name and directory
exists, the LISP system selects the type file that exists.
Use the /VERBOSE qualifier (see Section 2.10.13) to display on the terminal
screen the names of any functions or macros in the initialization file.
You can use the /INITIALIZE qualifier when invoking an interactive LISP
session or when compiling files with the /COMPILE qualifier. You cannot use the
/INITIALIZE qualifier with the /RESUME qualifier; if you do so, the /INITIALIZE
qualifier is disregarded.
Format
LISP/INITIALIZE=(fi/e-spec,...)

or
LISP/COMPILE/INITIALIZE=(f//e-spec,...) file-spec

Example
$ LISP/INITIALIZE=MYINIT/VERBOSE

VAX LISP[TM], V e r sio n V3.0
C o p y r ig h t © D i g i t a l Equipment C o r p o r a tio n . 1989
A ll R ig h ts R eserved.
; L oading c o n t e n t s o f f i l e DBA1: [JONES]MYINIT.LSP;1
;
FACTORIAL
;
FACTORS-OF
; F in is h e d lo a d in g DBA1: [JONES]MYINIT.LSP;1
★

In the preceding example, the file type defaults to LSP. fa ctor ia l and fa ctors -

OF are functions that are loaded into the LISP system from Jones’
s initialization

file. The form ( s e t f * to p - ie v e i- p ro m p t* "*") in the initialization file changes
the L isp > prompt to an asterisk (*). The * top - lev el - prompt * variable is de
scribed in VAX LISP /VMS Object Reference Manual.
2-12

Using VAX LISP

The s e t f form and the prompt variable are not listed on an output device when
the file is loaded, because the /VERBOSE qualifier lists only functions and macros
defined in the file.
Mode

Interactive or Compile

2.10.6 /INTERACTIVE
The /INTERACTIVE qualifier, the default, starts an interactive LISP session.
Mode

Interactive

2.10.7 /[NOJLIST
The /LIST qualifier is meaningful only if it is specified with the /COMPILE
qualifier. The /LIST qualifier specifies that the compiler generate a listing file
during compilation. You must specify this qualifier if you want a fisting file. A
fisting includes the name of the file compiled, the date it was compiled, warning
or error messages produced during compilation, and a summary of warning and
error messages. If you specify the /VERBOSE qualifier with the /LIST qualifier,
the fisting also includes the names of the functions compiled.
Specify the /LIST qualifier with a file name value only when you want the fisting
file name to be different from the name of the source file. If you specify the /LIST
qualifier without a file name, the LISP system produces a fisting file with a LIS
file type and the same name as the source file.
The /NOLIST qualifier suppresses a fisting and is the default except in batch
mode. The /LIST qualifier is the default for batch mode operations.
Format
LISP/COMPILE/LIST[=fite-spec] file-spec

Example
$ LISP/COMPILE/LIST=FACTORIAL.LIS/VERBOSE MYPROG.LSP

Sample Listing File
L i s t i n g o u t p u t f o r f i l e DBA1: [ JONES.LIS]MYPROG.LSP;1
C o m p ile d a t 10:33:30 on Monday, 23 Jan uary 1989 b y JONES
L is p V e r s io n V3.0
S t a r t i n g c o m p il a t io n o f f i l e

D B A 1 : [ JONES.LIS]MYPROG.LSP; 1

FACTORIAL c o m p ile d .
F in ish e d c o m p ila tio n o f f i l e
0 E r r o r s , 0 W arnings

D B A 1 : [JONES.L I S ] MYPROG.LSP;!

Mode

Compile

Using VAX LISP

2-13

2.10.8 /[NO]MACHINE_CODE
The /MACHINE_CODE qualifier is meaningful only if it is specified with the
/COMPILE qualifier. The /MACHINE_CODE qualifier requests the compiler to
put a listing of the VAX LISP machine code in a file separate from the FAS file
the compiler generates. The compiler also puts anything usually included in a
listing file in this file (see Section 2.10.7 for a description of a listing file).
VAX LISP machine code is similar to a standard assembly language code.
However, compiling LISP source code does not generate object modules that must
be linked.
The /MACHINE_CODE qualifier has no effect on the production of machine
code; the qualifier produces only a machine-code listing file. The machine-code
listing file generated when you use the /MACHINE_CODE qualifier has the same
name as your source file and has a LIS file type (unless you also used the /LIST
qualifier to specify a different name).
The /NOMACHINE_CODE qualifier, the default, suppresses a listing of LISP
machine code.
Format
LISP/COMPILE/MACHINE_CODE file-spec

Example
S LISP/COMPILE/MACHINE_CODE MYPROG.LSP

Mode

Compile

2.10.9 /MEMORY
The /MEMORY qualifier lets you specify the amount of dynamic virtual memory
the LISP system allocates in 512-byte pages. This system requires a minimum of
5000 pages of dynamic virtual memory to function. This memory is in addition
to the read-only and static memory. Consequently, the default page size for the
dynamic virtual memory is 5000 pages. If you specify fewer than 5000 pages with
the /MEMORY qualifier, the system disregards the requested page size and uses
the default page size. You do not need the /MEMORY qualifier if you intend to
use no more than 5000 pages of dynamic memory.
lb see how many pages of memory are available at any point while you are in
LISP, use the LISP room function. If you need more memory, LISP allocates it for
you automatically.
Format
L\SPMEMORY=number-of-pages

USP/COMPILE/MEMORY=number-o/-papes file-spec

2-14

Using VAX LISP

Example
$ LISP/MEMORY=15000
VAX L IS P [TM], V3.0
C o p y r ig h t © D i g i t a l E gu ipm en t C o r p o r a t io n .
A l l R ig h t s R e s e r v e d

1989.

L is p >

Mode

Interactive, Compile, or Resume

2.10.10 /[NOJOPTIMIZE
The /OPTIMIZE qualifier lets you optimize the results of compilation of your
program according to the following qualities:
• SPEED (execution speed of the code)
• SPACE (space occupied by the code)
• SAFETY (run-time error checking of the code)
• COMPILATIONJ5PEED (speed of the compilation process)
You can optimize your program by setting a priority value for each quality. That
value must be an integer in the range of 0 to 3. The value 0 means the quality
has the lowest priority in relationship to the other qualities; the value 3 means
the quality has the highest priority in relationship to the other qualities. When
you do not specify the /OPTIMIZE qualifier, the qualities each take the default
value of 1. To suppress optimization, use the /NOOPTIMIZE form of this qualifier.
The /OPTIMIZE qualifier is meaningful only if it is specified with the /COMPILE
qualifier. The /OPTIMIZE qualifier affects only the compiler and does nothing
to the interpreter, the debugger, or any other VAX LISP facility. See VAX LISP
Implementation and Extensions to Common LISP, Appendix B of this manual,
and Common LISP: The Language for information on specifying optimization
declarations.
Format
LISP/COMPILE/OPTIMIZE=(qua//ty:i<'a/ue[,...]) file-spec

Example
$ LISP/COMPILE/OPTIMIZE=(SPEED:3 ,SAFETY:2) MYPROG.LSP

or
$ L IS P / C O M P I L E /O P T I M I Z E = S P E E D :3 MYPROG.LSP

Mode

Compile

2.10.11

/[NO]OUTPUT_FILE
The /OUTPUT_FILE qualifier is meaningful only when it is specified with the
/COMPILE qualifier. The /OUTPUT_FILE qualifier tells the compiler to write the
compiled code to a specific file. If you specify the /OUTPUT_FILE qualifier with
a file name, the LISP system puts the compiled code in a file with that specified
name. Use the /OUTPUT_FILE qualifier only when you want to change the name
Using VAX LISP 2-15

of the compiled file so that the source file and the compiled file have different
names.
The /OUTPUT_FILE qualifier does not specify a listing file, only a compiled file.
See the /LIST qualifier (Section 2.10.7) for an explanation of a listing file.
If this qualifier is not specified, the compiler produces a file with the same name
as the source file and a type of FAS.
The /NOOUTPUT_FILE qualifier prevents compiled code from being written
to a file. If you want only to check a file for errors, use this qualifier with the
/COMPILE qualifier.
Format
LISP/COMPILE/OUTPUT_FILE[=ft/e-spec] file-spec

Example
$ LISP/COMPILE/OUTPUT_FILE=TEST.FAS FACTORIAL.LSP

Format
LISP/COMPILE/NOOUTPUT_FILE file-spec

Example
$ LISP/COMPILE/NOOUTPUT_FILE MYPROG.LSP

Mode

Compile

2.10.12 /RESUME
The /RESUME qualifier resumes a suspended LISP system where the suspension
occurred. See Section 2.11 for an explanation of suspended systems. The
/RESUME qualifier cannot be used with the /CSTACK or /INITIALIZE qualifier.
Format
LiSP/RESUME=file-spec

Example
$ LISP/RESUME=MYPROG.SOS
T
L isp >

Mode

Resume

2.10.13 /[NO]VERBOSE
The /VERBOSE qualifier lists on the output device and in the listing file the
names of the functions defined or loaded in an initialization file, and the names of
functions in a file as they are compiled. The /VERBOSE qualifier applies only to
files loaded with /INITIALIZE qualifier or compiled with the /COMPILE qualifier.
The /NOVERBOSE qualifier (the default) prevents the names of functions
compiled with the /COMPILE qualifier or loaded with the /INITIALIZE qualifier
from being listed in a file or at the terminal.
2-16

Using VAX LISP

Format
LISP/VERBOSE/INITIALIZE=ffle-spec

or
LISP/COMPILEA/ERBOSE file-spec

Examples
1.

$ L IS P /VERBOSE/INI T IALIZE=MYINIT.LSP
VAX L IS P [TM] , V3.0
C o p y r ig h t © D i g i t a l E qu ipm en t C o r p o r a t io n .
A l l R ig h t s R e s e r v e d .

1989.

; L o a d in g c o n t e n t s o f f i l e DBA1: [JONES]MYINIT.L S P ;1
;
FACTORIAL
;
FACTORS-OF
; F i n i s h e d l o a d i n g DBA1: [JONES]MYINIT.LSP; 1
L is p >
f a c t o r ia l and f a c t o r s - of are functions that are loaded into the LISP system
from Jones’
s initialization file.

2. $ LISP/VERBOSE/COMPILE MYPROG.LSP
S t a r t in g c o m p ila tio n o f f i l e

DBA1: [JONES]MYPROG.LSP;1

MULT c o m p ile d .
SUB c o m p ile d .
DIV c o m p ile d .
F in ish e d c o m p ila tio n o f f i l e
0 E r r o r s , 0 W arn in gs
$

DBA1: [JONES]MYPROG.LSP; 1

mult , su b , and d i v

are functions compiled in the file, MYPROG.LSP. The
compiled definitions of these functions are written to the file, MYPROG.FAS.

Mode

Interactive or Compile

2.10.14 /[NO]WARNINGS
The /WARNINGS qualifier specifies that the LISP system is to produce warning
messages. Warning messages are the default when you use the /COMPILE
qualifier.
A warning message indicates that the LISP system has detected something that
is likely to be wrong. If warnings are signaled while a file is being compiled
and the value of the * brea k - on - w a rn in g s * variable is n i l (the default), the
compilation continues. But, if errors are signaled, compilation of the expression
causing the error is not continued though the rest of the file is compiled. See VAX
LISP Implementation and Extensions to Common LISP for more information on
the differences between warnings and errors.
The /NOWARNINGS qualifier suppresses warning messages.
The following example of a warning message is the message the compiler displays
for the t e s t function defined in Section 2.9.3.
$ LISP/COMPILE TEST.LSP
W arning in TEST
TEST e a r l i e r c a l l e d w ith 2 a r g s , w an ts a t m o st 1.
$

Using VAX LISP

2-17

Format
LISP/COMPILE/NOWARNINGS file-spec

Example
$ LISP/COMPILE/NOWARNINGS MYPROG.LSP

Mode

Compile

2.11

Using Suspended System s
A suspended system is a binary file that is a copy of the LISP memory in use
during an interactive LISP session up to the point at which you create the
suspended system. The purpose of a suspended system is to save the state of an
interactive LISP session. You may want to do this if your work is incomplete. By
resuming LISP from a suspended system, you can continue your work from the
point at which you stopped.
NOTE

A suspended system can be resumed only by the VAX LISP system
from which it was suspended. The VAX LISP system that resumes a
suspended system must meet these criteria:
1. The VAX LISP system must be the same version of VAX LISP as
the suspending system.
2. A custom VAX LISP system created with the VAX LISP SystemBuilding Utility must be the same system as the suspending system
or a copy of the suspending system. (See the VAX LISP /VMS
System-Building Guide for a description of the System-Building
Utility.)

2.11.1 Creating a Suspended System
The VAX LISP su spen d function puts in a file the LISP memory in use during
an interactive LISP session, enabling you to resume the same LISP session
at a later time. The su spen d function does not stop the current LISP session;
you can continue to use the LISP session after the su spen d function has put a
copy of memory into a file. The su spen d function also automatically invokes a
garbage collection of dynamic memory space. See VAX LISP Implementation and
Extensions to Common LISP for information on garbage collections.
In the following example, the file FILEX.SUS is created and a copy of the memory
in a LISP session is put into that file. The file name can be a string, symbol, or
pathname. See VAX LISP/VMS System Access Guide and Common LISP: The
Language for a description of pathnames.
L is p > (suspend " f i l e x . s u s " )
; S t a r t in g f u l l GC . . .
; . . . F u ll GC f i n i s h e d
NIL
L isp >

After your file is created, the system returns to your interactive LISP session.
You can exit LISP when you see the LISP prompt. Your suspended system file is
placed either in your default directory or in the directory you specified in the file
specification. The file is usable only in an interactive LISP session.
2-18

Using VAX LISP

If you use the Editor before using the su spen d function, Editor buffers that
are associated with files are deleted in the resumed system. Consequently, if
you want to save any material in a buffer, put that material in a file. For a
description of the VAX LISP Editor, see Chapter 3. For a description of the
su spen d function, see VAX LISP/VMS Object Reference Manual.

2.11.2 Resuming a Suspended System
To resume a suspended system, use the LISP command with the /RESUME
qualifier and the name of the file containing the suspended system. Program
execution continues from the point at which you called the su spen d function. See
Section 2.10.12 for an explanation of the /RESUME qualifier.
After it creates a suspended system, the su spen d function returns n i l and
execution continues with the LISP environment exactly as it was before the call
to s u sp e n d . However, when execution resumes as a result of using the /RESUME
qualifier, the su spen d function returns T. Therefore, a program can use the
return value of su spen d to determine if execution is resuming as the result of
the /RESUME qualifier, and take action if necessary. See the su spen d function
in VAX LISP/VMS Object Reference Manual for a description of the effects of
suspending a system.
When resuming a suspended system, VAX LISP checks to make sure that the
resuming system matches the suspending system. The resuming system must be
the same system that suspended or a copy of the file containing the system that
suspended.

2.12

Using S u b p rocesses
A subprocess is a process that you create or go to from the LISP system for
executing Command Language Interpreter (CLI) commands. The purpose of
a subprocess is to permit you to interrupt execution of a LISP process and to
optionally execute the specified CLI command. You may want to do this to read
a mail message or manipulate files while saving the state of an interactive LISP
session.

2.12.1 Creating a Su b process
The VAX LISP spawn function creates a process for executing CLI commands. If
you specify the :pa r a l l el keyword with a value of T, the LISP process continues
to execute while the subprocess is executing. If you do not specify this keyword
or if you specify it with n i l , the LISP process is put into a VMS hibernation state
until the subprocess completes its execution. A hibernation state is one in which
a process is inactive, but can become active at a later time. For a description of
the spawn function, see VAX LISP/VMS Object Reference Manual.
In the following example, the user creates a subprocess to read a mail message,
exits from MAIL, and resumes LISP.
L is p > (spawn : co m m a n d - strin g "m a il" )
MAIL> r e a d
#1
5-OCT-1988
14:38:10.02
From: VLSP: : JONES
To:
Sm ith
CC:
S u b j : T om orrow 's c o m m itte e m e e t in g
We w i l l h o l d to m o r r o w ' s m e e t in g a s s c h e d u le d .
Using VAX LISP

2-19

P . Jones
MAIL> e x i t
L is p >

The value of : command- string must be a DCL command. By default, the spawn
function does not process a command. In this example, because the user did not
specify the :parallel keyword, the LISP process was put into a hibernation state
until the subprocess completed its execution.
NOTE

The VAX LISP spawn function can be used with the DECwindows
interface only if you specify the :parallel keyword with a value of T.

2.12.2 Connecting to a Su b process
The attach function connects your terminal to a process and puts the current
LISP process into a VMS hibernation state. You can use this function to switch
terminal control from one process to another. The attach function is described in
VAX LISP/VMS Object Reference Manual.
In the following example, the call to the spawn creates a subprocess, the DCL
ATTACH command attaches the terminal back to the process SMITH, and the
call to the VAX LISP attach function returns control to the process SMITH_1.
L is p > (spawn)
$ ATTACH SMITH
L is p > ( a tta c h " s m it h _ l" )
%DCL-S-RETDRNED, c o n t r o l r e t u r n e d t o p r o c e s s SMITH_1
$

NOTE

The ATTACK function can be used only if LISP is invoked from DCL on
a terminal interface; it cannot be used if LISP is invoked from another
command language interpreter or from DECwindows.

2.12.3 Exiting from a S u bprocess
If you entered a subprocess with a value assigned to : command-string , exiting
that process returns you to LISP. If you spawned a subprocess without assigning
a value to : command- string , logging out returns you to LISP.

2-20

Using VAX LISP

Chapter 3

Using the VAX LISP Editor
This chapter describes how to use the VAX LISP Editor to edit LISP objects and
files containing LISP code. This chapter provides all the information you need to
edit LISP and general text. If you want to learn more about the Editor or wish
to customize it in ways not covered in this chapter, refer to the VAX LISP /VMS
Editor Programming Guide.
NOTE

This chapter assumes you are using the Editor in its default form to
edit LISP objects or LISP files. That is, the Editor’
s major style is "EDT
E m u la tio n " and its minor style is "VAX l i s p ". If you are using or wish
to use the " e m a c s " style provided with the Editor, see Appendix D.
This chapter is divided as follows:
• Section 3.1 introduces the Editor and explains how to start it, how to get
work into and out of it, and how to return to the LISP interpreter.
• Section 3.2 explains how to edit text, including special features for editing
LISP objects and code.
• Section 3.3 shows how you can have more than one LISP object or file
available for editing at one time and explains how to switch among the
objects or files you are editing.
• Section 3.4 explains how to recover from problems while you are using the
Editor.
• Section 3.5 shows how you can customize the Editor to suit your needs.
Each major section ends with a table of the commands and key bindings that are
covered in that section.
NOTE TO DECWINDOWS USERS

Chapter 8 describes how to use the Editor in the DECwindows
environment.
NOTE TO VWS VAXSTATION USERS

When you use the Editor on a VWS VAXstation, screen behavior
is different, and you can use the pointer to perform some editing
operations. Throughout this chapter, these differences are noted at
appropriate locations. Section 3.6 summarizes Editor behavior and use
on a VWS VAXstation.

Using the VAX LISP Editor

3-1

3.1 Introduction to the Editor
The VAX LISP Editor is a general-purpose text editor. It includes some capabili
ties that make it useful for editing LISP code. For example, the Editor matches
parentheses and indents lines for you. It can also evaluate a LISP function
definition or symbol value that you are editing.
You use the Editor from the LISP environment. The Editor is a part of LISP
and cannot be used outside LISP. You can move freely between the Editor and
the LISP interpreter. When you go from the Editor to the interpreter, the Editor
preserves the state of your work until you return to it.
The Editor works only on a video terminal or a VAXstation. It maintains the
screen at all times to reflect the contents of the LISP object or file. When you
insert text in the middle of fines or between fines, the Editor immediately adjusts
the screen to show your modification.
You communicate with the Editor by using commands. Many commands are
available. Keys or key sequences invoke the most useful commands, so you do
not have to type the command names. Keys on the numeric keypad invoke a set
of commands that emulate the EDT keypad editor, making the VAX LISP Editor
similar to EDT.
The Editor lets you have more than one LISP object or file available for editing at
one time. Each object or file resides in its own buffer. Commands let you switch
from one buffer to another, and you can view more than one buffer at a time or
more than one place in the same buffer.
The rest of this section describes the basics of using the Editor. Section 3.1.6
contains a table of the commands presented in this section.

3.1.1

Editing Cycle
An editing cycle starts when you are using the VAX LISP interpreter and you
want to create or modify a LISP object or a file containing LISP code. The cycle
is as follows:
• You start the Editor by calling the ed function, supplying as an argument
the name of the object or the file specification of the file you wish to create or
modify.
• You use Editor commands to edit the object or file. Most frequently used
Editor commands are invoked by control characters or keys on the numeric
keypad.
• If you are editing a LISP object, you use a command to make your edited
version replace the function definition or value. If you are editing a file, you
use a command to write the new or modified file out to the disk.
• You use a command to pause the Editor, returning you to the LISP inter
preter.
• In the LISP interpreter, you can now use the new function definition or value
of the object or you can load the new or modified file.
• If further modifications are required, you can use the ED function without
arguments to return you to the Editor. Resuming the Editor in this way
brings you back to the Editor state that existed when you paused the Editor.
This cycle can occur as many times and on as many objects or files as needed.

3-2

Using the VAX LISP Editor

3.1.2 Invoking the Editor
The ED function invokes the VAX LISP editor. The first time you invoke the
Editor during a LISP session, be sure to supply an argument to the ED function.
The argument identifies the object or file you want to edit.
To edit a LISP object, give the object’
s symbol as the argument. For example, the
following form edits the function definition of the symbol s h ip -a c ce sso r :
L is p >

(ed ' s h i p - a c c e s s o r )

You can also edit the value of a LISP symbol, rather than its function definition,
by using the i TYPE keyword with the ED function, as shown in this example:
L is p >

(ed ' s h i p - l i s t

: t y p e rva lu e)

l b edit a file, give the file specification as the argument to the ed function. For

example:

L is p >

(ed " c l o c k . l s p " )

The first time you use the ed function, the screen clears. Then, after some
initialization messages appear, the screen appears as shown in Figure 3—1.
Figure 3-1:

Invoking the Editor

Information Area

MLO-002784

NOTE TO VWS VAXSTATION USERS

A new window appears; the window contains the Editor display. The
window is taller than a standard 24-line screen, but otherwise the
display is identical to that seen on a video terminal.

Using the VAX LISP Editor

3-3

Note the following points about this screen display:
• The label strip near the bottom of the screen tells you that you are editing
the function definition of s h i p - a c c e s s o r , you are using the major style called
"EDT E m u la tio n " and the minor style called "VAX LISP", and your current
movement direction is forward. The movement direction is useful to you
while you are editing. You need not concern yourself with styles at this point.
• The information area at the bottom of the screen tells you that you are
editing a new function definition. In general, the information area contains
short informational messages about Editor operations and errors.
• The cursor is positioned at the upper left comer of the screen. The cursor
shows where new text will be inserted.
After you have used the Editor, you can pause it (see Section 3.1.5) and return to
the LISP interpreter. Later, you may want to resume your editing. If you want to
return to the Editor state you left, call the ed function without arguments:
L is p >

(ed)

You can also supply an argument—another LISP symbol or file—when you
resume the Editor. The LISP symbol or file you specify does not replace the
symbol or file you were editing when you paused the Editor. The old symbol or
file is made inactive, although it is still available for editing. See Section 3.3 for
details.
If you use the ed function without arguments to start the Editor, you see the
screen display shown in Figure 3-2.
Figure 3-2: The Editor Screen with Help M essage

This means that the Editor is running but has nothing to edit. You can return to
the LISP interpreter by pressing Ctrl/X Ctrl/Z. Or, you can press Ctrl/Z and enter an
Editor command by name, as described in Section 3.1.3.

3-4

Using the VAX LISP Editor

NOTE

In the interpreter, you can use the b in d - keyboard - f u n c t io n function to
bind a control character (such as Ctrl/E) to the ed function, allowing you
to invoke or resume the Editor asynchronously by pressing the control
character. If you do this, do not specify a value greater than l with the
b in d - keyboard - f u n c t io n :LEVEL keyword. Using a value greater than
l may disrupt the Editor’
s operation.

3.1.3 Interacting with the Editor
You interact with the Editor through commands. Commands do the following:
• Control the operation of the Editor: pause it, change from one buffer to
another, set operating characteristics, and so on.
• Modify the LISP object or file that you are editing.
To enter a command to the Editor, you can type its name or press a key or
sequence of keys that causes the command to be executed. The two ways are
equivalent.
• To type a command by name, first press Ctrl/Z. This causes a prompt to appear
just below the label strip as shown in Figure 3-3.
Figure 3-3:

Entering Commands at the Editor Prompt

Function SHIP-ACCESSOR Forward EDT Emulation ("VAX LISP")
Enter command name!

MLO-002786*•

Type the name of the command, then press Return. While you are typing, you
can use any of the editing keys described in Section 3.2 to edit your input.
You must supply the full name of the command. (However, once you have
typed part of the command, the Editor can complete the name for you or
display a fist of command names that start that way; see Section 3.1.3.2.)
• If a key or key sequence is bound to the command, you can enter the com
mand by pressing that key or key sequence. Most frequently used commands
have keys or key sequences bound to them. You cam use the " L i s t Key
B in d in g s " command to see which keys are currently bound to commands.
For example, to enter the "P a u se E d i t o r " command, you can press Ctrl/Z, type
"P a u se E d i t o r " in response to the command prompt, and press Return. Or, you can
press Ctrl/X Ctrl/Z, which is bound to the "P a u se E d i t o r " command. Both methods
cause the Editor to pause and return you to the LISP interpreter.
If you press Ctrl/Z but then decide that you do not want to type a command, or
if you decide to cancel a command in the middle of its execution, press Ctrl/C.
Ctrl/C stops the current command and makes the Editor ready to accept other
commands.

Using the VAX LISP Editor

3-5

Commands are introduced throughout this chapter. Appendix E contains short
descriptions of the available commands and their key bindings (if any).
3.1.3.1

Getting Help

The Editor provides different kinds of help. You can press the Help key (either
PF2 on the numeric keypad or the Help key on the LK201 or later keyboards) at any
time to get help. A window called <rVAX LISP Editor General Help”appears. It
contains instructions on how to move around in a window and between windows
and how to remove a window from the screen. Tb remove the window containing
this help text from the screen, press Ctrl/X Ctrl/R.
If you press the Help key while the Editor is displaying a prompt—for example,
after you have pressed Ctrl/Z—the Editor displays help on the prompt. Typically,
the help explains the prompt and describes the options you have. Press Ctrl/V to
scroll through this help text. The text will disappear from the screen when you
have entered a response to the prompt and pressed Return.
The Editor also provides the " D e s c r i b e " and " A p r o p o s" commands to obtain
information on Editor objects. These commands are similar to the LISP functions
of the same names. The " D e s c r i b e " command displays a description of an Editor
command (by default) or other Editor object. The " A p r o p o s" command lists all
Editor commands or other specified Editor objects whose names contain a certain
string. For example, using the " A p r o p o s" command for the string “
file”produces
the display shown in Figure 3—4.
Figure 3—4:

Using APROPOS in the Editor

You can also obtain descriptions of LISP symbols through the Editor when you
are editing LISP code. The Ctrl/? key invokes the LISP d e s c r ib e function on the
word at the current cursor position.

3-6

Using the VAX LISP Editor

NOTE TO VWS VAXSTATION USERS

You can also invoke the LISP d e s c r ib e function by moving the pointer
cursor to the symbol to be described and pressing the right pointer
button.
You can use the cursor movement techniques described in Section 3.2.3 to move
around in the window containing help text. When you are done, use the key
sequence Ctrl/X Ctrl/R to remove this window and return to editing.
3.1.3.2

Input Completion and Alternatives

The Editor can help you enter responses to prompts in two ways. The first way
is input completion. If you press Ctrl/Space at any time while you are typing a
response to a prompt, the Editor will attempt to complete your input for you. The
Editor will complete as much of the input as it can and display the status of the
completion.
For example, if to the “
Enter command name”prompt you type the string “
pau”
followed by Ctrl/Space, the Editor will complete the command name "P a u se E d i t o r ”
and inform you that the input is complete. You can now press Return to execute the
command. If, on the other hand, you type the string “
new”followed by Ctrl/Space,
the Editor will be able to complete the input only as far as “
New Li”and will then
report that the input is ambiguous, because more than one command starts with
the string “
New L i”
.
The second way is by listing available alternatives. At any point when entering
information to a prompt, you can obtain a list of the available alternatives by
pressing PF1 PF2 on the numeric keypad. The Editor examines what you have
typed so far and displays a list of all the commands starting that way. For
example, when you have used input completion to get as far as “
New L i”
, you
can press PF1 PF2. The Editor will display a list of the commands beginning with
“
New Li”
. You can choose the command you want, enter enough of it to make
the input unambiguous, and then use input completion Ctrl/Space to complete the
command name.
Input completion and alternatives are not restricted to command names. You
can also use them to fill out file specifications and to obtain a list of all the
files matching a particular template. For example, assume you wish to edit an
existing LISP file but are unsure of the name. You type Ctrl/Z and enter the " E d it
F i l e " command, which then prompts you for a file name. You can type “
.LSP”at
this point, followed by PF1 PF2, to see a list of all files in your current directory
having the file type “
.LSP’
. You can then edit your input by moving the cursor
back to the beginning of the file specification and typing enough of the file name
to distinguish it from other file names. Typing Ctrl/Space at this point fills in the
rest of the file specification.
3.1.3.3

Errors and Other Problems

If you make a minor error, the Editor displays a short error message in the
information area. These error messages are usually enough to let you correct the
problem. If the short message is not enough, the Ctrl/X ? key sequence can display
more information on the error.
If you make a major error or if the Editor encounters an internal error from which
it cannot recover, the Editor reports the error and asks if you wish to attempt to
save your work. Depending on the nature and severity of the error, the Editor
may not be able to save all your work. Section 3.4 contains more information on
how to r e co v e r from th e s e problems.
Using the VAX LISP Editor

3-7

If the screen should become disrupted for some reason—for example, MAIL
messages arriving—use the Ctrl/W key to refresh the screen.

3.1.4 Moving Work Back to LISP
There are several ways to move your work back to the LISP environment. Use
one of the methods described in this section if you want your work to be available
in LISP.
Two commands, "W r ite C u r r e n t B u f f e r " and "W rite M o d if ie d B u f f e r s " , place
your work back in a symbol or file.
• If you were editing the function definition or the value of a symbol, the
commands cause the new function definition or value to replace the existing
function definition or value.
• If you were editing a file, the commands write a new version of the file.
The difference between the two commands is that "W r ite C u r r e n t B u f f e r " affects
only the current buffer; that is, the buffer whose window contained the cursor
when you entered the command. "W rite M o d if ie d B u f f e r s ”affects any buffer
you have worked on since the last time the buffer was written.
Neither of these commands pauses the Editor or alters the contents of your
buffers. After using either command, you can immediately return to editing or
you can use the "P a u se E d i t o r " command to return to the LISP interpreter. If
you were editing the function definition or value of a symbol, the new function
definition or value is immediately available to you in LISP. If you were editing a
file, you will have to load the file before you can use the modifications you made.
You can also move a function definition to the LISP environment by positioning
the cursor in the function definition, then type Ctrl/X Ctrl/Space Ctrl/X Ctrl/A. This
procedure causes the function definition containing the cursor to be evaluated.
You can now return to the LISP interpreter and use the modified function
definition. However, you must eventually include the definition in a file, or the
modification will be lost when you exit LISP. This procedure is useful when you
are editing a file containing a number of definitions and you want to modify only
one of them.
If you are editing a function definition and you want to save it in a file, use the
"W r ite Named F i l e ”command. This command prompts for the name of a file and
then writes the current buffer to the file.

3.1.5 Returning to the LISP Interpreter
When you have finished creating or modifying objects or files, you generally want
to return to the LISP interpreter to test whatever you have written. The "P au se
E d i t o r " command returns control to the LISP interpreter; the key sequence Ctrl/X
Ctrl/Z invokes "P au se E d it o r " . The "P a u se E d i t o r " command saves the state
of your editing session. If you return to the session by calling the ed function
without arguments, the Editor will be as you left it.
The "P a u se E d i t o r " command does not cause any of your buffers to be writ
ten. Before pausing the Editor, you must use one of the methods described in
Section 3.1.4 to make your work available in the LISP environment. Also, if you
pause the Editor without first writing y o u r modified files and then exit LISP,
the work you did on your files will be lost. (See Section 3.4 for information on
partially recovering from this situation.)

3-8

Using the VAX LISP Editor

NOTE TO VWS VAXSTATION USERS

When you pause the Editor, the cursor returns to the LISP window.
In contrast to the "P a u se E d i t o r " command, the " E x it " command shuts down
the Editor. If you use the " E x i t " command, the Editor warns that changes will
be lost and asks if you want to continue. If you type Y, the Editor lets you save
modified buffers on a buffer-by-buffer basis.

3.1.6 Summary of Commands
Table 3—1 provides a summary of the commands presented in this section and
the keys (if any) that invoke those commands. These commands are useful for
controlling the operation of the Editor. Subsequent sections in this chapter
contain tables of commands that are useful in specific situations. Appendix E
provides an alphabetic table of all the commands.
Table 3-1:

General-Purpose Comm ands and Key Bindings

Name

Binding t

Description

Execute Named Com m and

|ctrl/z| or keypad |pfi|PH
or I Do I *

Prompts for the name of a command to execute;
type the name of the command, followed by
|Return|.

List Key Bindings

None

Displays a list o f keys and key sequences cur
rently bound to commands.

Pause Editor

1Ctrl/X1|Ctrl/Z|

Pauses the Editor, saving its state, and returns
to the LISP interpreter.

Write Current Buffer

None

Replaces a LISP symbol’
s function definition or
value with the contents o f the current buffer or
writes a new version o f the file.

Write Modified Buffers

None

Writes the contents of all modified buffers to the
corresponding LISP object or new file version.

Select Outerm ost Form

ICVI/XI |Ctrl/Space |

Highlights the outerm ost LISP form containing
the cursor.

Evaluate LISP Region

ICtrl/X|ICtrl/AI

Evaluates LISP code highlighted by " S e l e c t
O u te rm o st Form" or by other means, m aking
the result available in the LISP interpreter.

Write Named File

None

Prompts for a file name, then writes the current
buffer to that file.

Next Window

[Ctri/Xl |Ctrl/N|

Makes the next window the current window;
useful for m oving into or out of help window.

Remove Current Window

1Ctrl/XI[Ctri/R]

Removes the current window from the screen;
useful for getting rid of help window.

Rem ove Other Windows

None

Removes windows other than the current window
from the screen.

H elp

keypad |PF2| or |Heip| *

D isplays a window with help on your current
situation.

Prom pt Scroll H elp Window

|ctriA/| (only while
responding to prompt)

W hen used while responding to a prompt, causes
the window containing help text to scroll.

t Keys marked with an asterisk (*) are available only on LK201 or later keyboards.

(continued on next page)

Using the VAX LISP Editor 3-9

Table 3-1 (Cont.):

General-Purpose C om m an ds and Key Bindings

Name

Binding t

Description

Prom pt Show Alternatives

Keypad 1 p f i | [ p f | (only
while responding to
prompt)

When used while responding to a prompt,
displays a list o f input alternatives based on the
context and what you have typed so far.

Prom pt Com plete String

i c tr i/ S p a c e

|(onlv while
responding to prompt)

When used while responding to a prompt,
attempts to complete the input based on the
available alternatives and what you have typed
so far.

Describe

None

Displays a description of a comm and or other
Editor object.

Apropos

None

Displays a list o f Editor comm ands or other
Editor objects containing the string you supply.

D escribe Word

(C t r l / ? [

H elp on Editor Error

ic w x im

Redisplay Screen

j C t r l/ W |

Invokes the LISP DESCRIBE function for the
word at the cursor location.
Displays help on the last Editor error that
occurred.
Refreshes the screen.

t Keys marked with an asterisk (*) are available only on LK201 or later keyboards.

3.2

Editing Operations
This section describes editing operations and how to perform them. The
operations are those that you can perform in a single buffer; that is, while editing
one LISP object or file. Section 3.3 explains how to deal with multiple buffers.
This section is divided as follows:
• Section 3.2.1 describes the numeric keypad you use to perform many editing
operations.
• Section 3.2.2 describes how to insert text.
• Section 3.2.3 explains ways to move the cursor.
• Section 3.2.4 shows how you can modify text by deleting it and moving it.
• Section 3.2.5 explains how to cause an operation to occur more than once.
• Section 3.2.6 summarizes the commands described in this section.

3.2.1 Keypad
The Editor incorporates a set of commands and key bindings that cause it to
behave like the EDT text editor. The keys on the numeric keypad are bound to
the EDT-like commands. For the most part, you can use keypad keys as if you
were using EDT, although there are some differences.
Figure 3—5 illustrates the numeric keypad. Each key has three items on it.
Whatever appears on the actual key is shown in the lower right comer of each
key in Figure 3-5. The meaning of the two names is as follows:
• The top name specifies the action that occurs if you press the key by itself.

3-10

Using the VAX LISP Editor

• The bottom name specifies the action that occurs if you press and release the
PFl key (sometimes called the Gold key) before pressing the key.
For example, if you press the 0 key by itself, the Editor moves the cursor to the
beginning of a line. If you first press PFl and then the 0 key, the Editor opens a
new fine at the cursor location.
For the rest of this section, keys will be referred to by the names of the actions
the keys invoke. For example, the o key by itself is called the Beginning of Line
key, while the sequence PFl 0 is called the Open Line key.

3.2.2

Inserting and Formatting Text
This section describes ways you can create new text. Section 3.2.2.1 describes
routine text insertion, Section 3.2.2.2 describes how to type and format LISP code,
and Section 3.2.2.3 describes how to insert nongraphic characters in the text.

3.2.2.1

Inserting Text

lb insert text, simply type. All the keys corresponding to printing characters
cause that character to appear preceding the character at the cursor location. If
the cursor is in the middle of a line, the cursor and the characters to its right will
be displaced further to the right to make room.

Using the VAX LISP Editor

3-11

Figure 3-5:

Numeric Keypad

Gold

Help

Find Next

Del Line

Prefix

Alternatives

Find

Undel Line

53/L

PF4
A
Del Word

Undel Word

Forward

Backward

Cut

Del Char

Bottom

Top

Paste

Undel Char

Word

Char

Chng Case

Spec Insert

Beginning of Line
Open Line

Note: The letters, numbers, and characters in the lower right corners
of the keys are what actually appear on the keys of a VT100
keypad.
7r

MLO-002788

You can start a new line by pressing the Return key. If you press Return while
the cursor is at the end of a line, you get a blank line with the cursor at the
beginning. If the cursor is in the middle of a line, the line is broken in the
middle.
The Open Line key also starts a new line, but leaves the cursor at the end of the
old line instead of the beginning of the new line.
3.2.2.2

Typing and Formatting LISP Code

The Editor includes several commands that help you enter LISP code. Whenever
you are editing a LISP object (either its function definition or value) or a file
containing LISP code, the following key bindings are in effect:
• If you type a right parenthesis, the Editor highlights the corresponding left
parenthesis for a moment. If the corresponding left parenthesis is not on the
screen, the fine that contains it is displayed in the information area with the
parenthesis highlighted.
3-12

Using the VAX LISP Editor

• The key sequence Escape.] or the command " C lo s e Outermost Form" closes the
outermost form by inserting the correct number of parentheses at the cursor
position. (Typing Ctrl/] produces an Escape.)
• The "New l i s p Line" command is similar to Return, but it indents the new line
properly with respect to the preceding line. Ctrl/J is bound to the "New l i s p
Lin e " command. (On a VT100 terminal, pressing the Linefeed key results in
Ctrl/J.)

• The Tab key, " in d e n t l i s p Line", indents the line that currently contains the
cursor, relative to the preceding LISP code.
• The Ctrl/X Tab key sequence or the "Ind en t Outermost Form”command indents
all the lines in the LISP outermost form that contains the cursor.
• Use Ctrl/X ; to start a LISP comment at the end of a line of code. When
you type Ctrl/X ;, the Editor inserts enough spaces to move the cursor to the
comment column, then inserts a semicolon and another space. If there is
already a comment on the line, Ctrl/X ; moves the cursor to the beginning of the
comment.
The commands "In d en t LISP Region", "In d en t Outermost Form", and "In d en t
l i s p L in e" (used in "VAX l i s p " style), normally indent calls to user-defined
macros as data. These commands will indent such calls properly if:
• You include &BODY in the argument list of the macro’
s definition. (Note that
if the macro’
s argument list contains both &BODY and &WHOLE, the Editor
does not properly indent a call to the macro.)
• You load the macro definition into VAX LISP before you indent the macro call
in the Editor.
NOTE TO VWS VAXSTATION USERS

Pressing the right pointer button when the pointer cursor is po
sitioned at a close-parenthesis character highlights the matching
open-parenthesis character.
3.2.2.3

Inserting Nongraphic Characters

You cannot insert some characters directly into your text. For example, you
cannot insert a #\ character by typing Ctrl/X because the Editor interprets that
character as the start of a command. The Editor provides two ways around this
problem. In most cases, you can use the Ctrl/X \ key sequence. After typing this
sequence, the Editor will take the next character you type and insert it without
interpretation. This procedure will handle the case of #\ Ax; for example, type:
[Ctri/Xl

[Ctrittl

The Editor echo for this is
< AX >

In general, the Editor display for a nongraphic character is the LISP representa
tion for the character, surrounded by angle brackets, but minus the leading #\.
For example, Ctrl/X character in LISP prints as # \ AX. The Editor displays this as
< AX>.

Some characters cannot be generated directly from the keyboard. You can use
the Spec(ial) Insert key to insert such characters. Tb use Spec Insert, you must
first supply the decimal ASCII value of the character as a prefix argument (see
Section 3.2.5). The Spec Insert key then inserts the character at the cursor
location.
Using the VAX LISP Editor

3-13

3.2.3 Moving the Cursor
To insert text where you want it to go, you have to move the cursor to that loca
tion first. A number of keys produce movements of various types. Section 3.2.3.1
describes how the keypad and arrow keys move the cursor. Section 3.2.3.2
describes how you can move the cursor within LISP code.
3.2.3.1

Moving with the Keypad and Arrow Keys

The keypad and arrow keys move the cursor nearly identical to EDT. If you
are familiar with EDT, you can skip this section; otherwise, the brief summary'
contained here should get you started.
The action produced by some keys depends on the current direction of movement.
The current direction can be either forward or backward. The Forward key sets
the current direction to forward, and the Backward key sets it to backward. The
label strip at the bottom of the window displays the current direction.
For other keys, the direction is always the same, regardless of the current direc
tion.
The simplest way to move the cursor is with the arrow keys. Each arrow key
moves the cursor one unit in the indicated direction. The left and right arrow
keys move the cursor one character to the left or right, while the up and down
arrow keys move the cursor up or down by one line in the current column. The
arrow keys do not depend on the current direction.
Other keys let you move by line:
• The Beginning of Line key moves the cursor to the beginning of the next
line (if the current direction is forward) or to the beginning of the current or
previous line (if the direction is backward).
• The EOL (End-of-Line) key moves to the end of the current or following line
(if the current direction is forward) or to the end of the previous line (if the
current direction is backward).
•

Ctrl/H moves the cursor to the beginning of the current or previous line,
regardless of the current direction. (On a VT100, pressing the Backspace key
results in Ctrl/H. On the LK201 keyboard, the F12 key produces the same action
as Ctrl/H.)

The Word key moves to the beginning of the next word, if the current direction
is forward, or to the beginning of the current or previous word, if the current
direction is backward. In finding the beginning of the word, the Word key passes
over most LISP syntax characters, such as parentheses, delimiters, single quote
characters, and semicolons. #\newline characters are also passed over. In EDT,
only spaces are passed over in finding the beginning of the next word.
The Screen key scrolls the text in the window. The text moves up if the current
direction is forward and down if the current direction is backward. The amount
of text that scrolls is equal to about two-thirds of the height of the window. The
cursor moves only as much as is necesary to stay in the window. This behavior
also differs from EDT.
The Bottom and Top keys move the cursor to the end or the beginning of whatever
you are editing.

3-14

Using the VAX LISP Editor

You can also move the cursor to a specified text string. The Find key prompts
for a search string. You enter the string and terminate it with Return; the Editor
then finds the first occurrence of that string in the current direction. (EDT lets
you terminate the search string with Forward or Backward; the VAX LISP editor
requires that you first set the current direction, then terminate the search string
with Return or Enter.) The Find Next key finds the next occurrence of whatever
string was last searched for.
3.2.3.2

Moving in LISP C ode

Four bound commands let you move by LISP forms. The key sequence Ctrl/X . is
bound to the command "Next l i s p Form", and the key sequence Ctrl/X , is bound
to " P r e v io u s l i s p Form". These commands move the cursor from form to form
within the current parentheses nesting level. The key sequence Ctrl/X > (bound
to the command "End o f Outermost Form") moves the cursor to the end of the
current or next outermost LISP form. The key sequence Ctrl/X < (bound to the
command "B eg in n in g o f Outermost Form") moves the cursor to the beginning of
the current or previous outermost LISP form.
Four other commands let you move in lists. By default, no key sequences are
bound to them. They are:
Backward Up List
Forward Up List
Beginning of List
End of List
See Appendix E for a brief description of these commands. Section 3.5 explains
how you can bind keys to these (and other) commands.
3.2.3.3

Moving with the Pointer (VWS VAXstation Only)

You can move the cursor by moving the pointer cursor to the desired spot in the
text and pressing the left mouse button.

3.2.4

Modifying Text
In addition to inserting text, you can modify existing text by deleting it, moving
it, and substituting in it. This section describes ways to modify text:
• Section 3.2.4.1 describes ways to delete portions of text.
• Section 3.2.4.2 shows how to undelete text you have just deleted.
• Section 3.2.4.3 explains how to move text from place to place by cutting and
pasting it.
• Section 3.2.4.4 describes commands that modify text by changing its case.
• Section 3.2.4.5 shows two ways to substitute one text string for another.
• Section 3.2.4.6 explains how to insert text from a file or a buffer into your
work.

Using the VAX LISP Editor

3-15

3.2.4.1

Deleting Text

This section describes how to delete parts of your text by using keypad keys and
keys on the main keyboard. Text that you delete disappears from the screen, but
is not immediately discarded. The Editor maintains three areas for deleted text,
one each for the last character, word, and line that you have deleted. The next
section shows how to recover the contents of these areas and how to use them to
move text from one place to another.
Two keys delete characters. The Delete key (with the symbol < 2 on the LK201
and later keyboards) deletes the character just before the cursor. The Del Char
key deletes the character at the cursor.
One or two keys delete words, depending on the terminal you are using. The
Del Word key deletes from the current cursor position to the beginning of the
next word. Tb find the beginning of the next word, the Editor passes over LISP
syntax characters, such as parentheses, delimiters, single quote characters, and
semicolons. Thus, Del Word deletes these syntax characters. Del Word also
passes over and deletes a #\newline character at the end of a line.
If you are editing LISP code using a VT100, there is no key that deletes from
the cursor position to the beginning of the current word. (In EDT, Linefeed and
Ctrl/J do this; when editing LISP, however, Ctrl/J is bound to "New l i s p Line".) If
you are using a terminal with the LK201 or later keyboard, the F13 key deletes
to the beginning of the current word. It passes over LISP syntax characters and
#\ newline characters the same way the Del Word key does.
Three keys delete fines or portions of fines:
• The Del Line key deletes from the current cursor position to the end of the
current fine, including the #\ newline character at the end of the line. If
the cursor is positioned at the end of the line, Del Line simply deletes the
#\ newline character.
• The Del EOL (End of Line) key deletes from the current cursor position to the
end of the current fine, not including the \ #newline character at the end of
the fine. If the cursor is positioned at the end of the fine, Delete Line deletes
the next fine, including the #\newline .
• The Ctrl/U key deletes from the current cursor position to the beginning of
the current line. If the cursor is positioned at the beginning of the line, Ctrl/U
deletes the previous fine.
3.2.4.2

Undeleting Text

Whenever you delete text, the Editor does not immediately discard it. Instead,
the Editor temporarily saves the text, allowing you to put it back if you did not
mean to delete it or to move it somewhere else.
• The Undel(ete) Char key places the last character that was deleted at the
cursor location.
• The Undel(ete) Word key places the last word or word portion that was
deleted at the cursor location.
• The Undel(ete) Line key places the last fine or fine portion that was deleted
at the cursor location.
Thus, if you want to move text from one place to another, you can first use the
appropriate key to delete the text in its original location. Then move the cursor to
the text’
s new location and use the appropriate Undel key to place the text there.

3-16

Using the VAX LISP Editor

Copying text—putting it in a new location while leaving it in its original
location—is similar to moving text, except that you undelete it in its original
location before moving to the new location. You can undelete text as many times
as you want.
3.2.4.3

Cutting and Pasting Text

Cutting and pasting consists of marking a block of text, removing (cutting) it
from its original location, then moving the cursor to a new location and inserting
(pasting) the text in the new location.
Before you cut text, you must mark the text to be cut. You use the Select key and
the cursor movement keys to mark text. Move the cursor to one end of the text
to be cut, then press Select. Move the cursor to the other end of the text to be
cut. The Editor highlights the text between the character at which you pressed
Select and the cursor. The highlighted text is called a select region. If you make
a mistake while you are marking a select region, use the Reset key to cancel the
select region.
You can mark a select region from the outermost LISP form containing the cursor
by pressing Ctrl/X Ctrl/Space.
NOTE TO VWS VAXSTATION USERS

You can mark a select region by moving the pointer cursor to one end
of the region, pressing and holding the left pointer button, moving the
pointer cursor to the other end of the region, and releasing the button.
The Cut key removes all the text in the select region from the screen and places
it in an Editor buffer called the paste buffer, replacing what was there. At this
point, if you wish to replace the text, use Paste. Paste restores the text to its
orginal location but does not remove the text from the paste buffer.
Now move the cursor to the desired location. Use the Paste key to put the text
there. You can paste text as often as needed, until you cut more text.
NOTE TO VWS VAXSTATION USERS

When a select region has been marked, you can cut it by pressing
the middle pointer button. Then move the pointer cursor to the new
location for the text and paste it by pressing and holding the left
pointer button, then pressing the middle button.
The Append key is similar to the Cut key, except instead of replacing the contents
of the paste buffer with the select region, the Append key appends the select
region to the paste buffer contents. Append is convenient when you want to build
a block of text by taking text from different locations.
The Replace key is similar to the Paste Key, except the Replace key requires that
you have defined a select region before you use Replace. The Replace key deletes
the select region and replaces it with the contents of the paste buffer.*•
3.2.4.4

Changing Case

One key and five commands provide ways to change the case of alphabetic
characters in your text. Nonalphabetic characters are not affected.
The Chng Case key changes uppercase letters to lowercase and vice versa. It
works as follows:
• If a select region is defined, Chng Case changes the case of all letters in the
select region.
Using the VAX LISP Editor

3-17

• If no select region is defined, Chng Case changes the case of the character at
the cursor position and advances the cursor one character.
Four commands that let you make all the alphabetic characters in a select region
or word be of one case are "Upcase Region", "Upcase Word", "Downcase Region",
and "Downcase Word". To use the commands that affect a region, first define the
select region, then press Ctrl/Z and enter the command. To use the commands that
affect a word, position the cursor anywhere in the word, then type Ctrl/Z and enter
the command.
Finally, the " C a p i t a l i z e Word" command makes the first character of a word
uppercase. Position the cursor anywhere in the word, then type Ctrl/Z and enter
the command.
3.2.4.5

Substituting Text

Two mechanisms are available for substituting one string for another throughout
text. The first is simpler; the second is more powerful.
The Subs(titute) Key substitutes the contents of the paste buffer for a search
string. To use the Substitute key, first load the paste buffer with the new string
by typing Select, typing the new string, and then typing Cut. Next, search for
the string to be replaced. If the first occurrence is in fact a string that you want
to replace, type Subs. The Editor deletes the search string and replaces it with
the contents of the paste buffer, then automatically moves to the next occurrence
of the search string. If you want to pass over an occurrence of the search string,
type Find Next to move to the next occurrence.
The "Query Search R e p la c e " command is similar to Subs but more versatile.
The command prompts for a search string and a replacement string. At each
occurrence of the search string, the Editor queries you. You can answer as
follows:
|S p a c e |

Replace th is occurrence and m ove to the next one.
Replace th is occurrence and stay here. This option lets you see th e
resu lts o f the change before m oving on. U se N to move to th e next
occurrence.

3.2.4.6

□

Replace th is occurrence and term inate th e command.

Replace th is occurrence and all rem aining occurrences w ithout further
querying.

Do not replace th is occurrence and find the next occurrence.

|C l r l / C |

Do not replace th is occurrence and term inate th e command.

Do not replace th is occurrence and term inate th e operation, returning
the cursor to th e point at which th e search began.

Enter a recursive edit, which you term inate w ith th e " E x it
R e c u r s i v e E d i t " command. The recursive edit lets you clean up
a replacem ent site w ithout losing your place in th e search cycle.

Ü3

D isplay help on the possible responses to th e query.

Inserting a File or Buffer

You can insert the contents of a file or a buffer at the cursor location, using the
" i n s e r t F i l e " or " i n s e r t B u f f e r " command. Each of these commands prompts
for the name of a file or buffer and then inserts the contents of the file or buffer at
the cursor location. You can use the Alternatives key or request input completion
with Ctrl/Space while responding to either prompt. (Section 3.3 contains more
information about buffers.)
3-18

Using the VAX LISP Editor

3.2.5 Repeating an Operation
You can cause the Editor to perform an action more than once by supplying a
numeric prefix argument. The prefix argument causes the next command to be
executed the number of times specified by the argument’
s value. For example, if
the prefix argument is 3 and you press the Beginning of Line key, the cursor will
move three lines instead of one.
You enter a prefix argument by using the Prefix key and then typing the number
in response to the prompt, followed by Return. The prefix affects only the next
command you issue. You can issue the command either by typing Ctrl/Z and the
command name or by typing the key or key sequence bound to the command.
The prefix argument also causes printing characters to be inserted more than
once. For example, to type 32 zeros, you could enter a prefix argument of 32, then
type “
0”once.
For some commands, you can supply a negative prefix argument. In general,
the commands that are sensitive to the current direction will accept a negative
prefix argument. They interpret a negative argument as an instruction to act in
a direction opposite to the current direction. For example, if the current direction
is forward, a prefix argument of -3 followed by the Word key causes the cursor
to move three words backward. If the current direction is backward, a prefix
argument of —3 causes the cursor to move three words forward.

3.2.6 Summary of Commands
Table 3—2 summarizes the commands presented in this section and their key
bindings.
Table 3-2:

Editing Comm ands and Key Bindings

Name

Binding t

Description

Text Insertion Commands
Open Line

Open Line
(keypad [pfT] [T] )

Breaks a lin e a t th e cursor location.

Insert Close Paren and M atch

Inserts a close parenthesis at the cursor and
h ighlights th e m atching open parenthesis.

Close Outerm ost Form

1E s c a p e | | 1 |

C loses th e outerm ost LISP form by in serting
sufficient parentheses at th e cursor position.

Indent LISP Line

[Tab]

N ew LISP Line

| L in e f e e d |

or icirl/l|

Indents the current lin e to th e appropriate position
in relationship to preceding LISP code.

Starts a new line, indenting it in the proper LISP
fashion.

[ciriZTI

Indent Outerm ost Form

[Ctri/Xl [Tab]

Indents all th e lin es in the outerm ost form con
ta in in g th e cursor.

Move to LISP Comm ent

[ C V W C jL lJ

Starts or m oves to a com m ent on the current line.

Quoted Insert

|Ctrl/X| | \ |

C auses th e next character typed to be inserted in
th e text w ithout interpretation by the Editor.

t Keys marked with an asterisk (*) are available only on LK201 and later keyboards.

(continued on next page)

Using the VAX LISP Editor 3-19

Table 3-2 (Cont.):

Editing C om m an ds and Key Bindings
Binding t

Name

Description

Text Insertion Commands
EDT Special Insert

Spec Insert
(keypad [pfT] [T] )

Inserts the character w hose ASCII value is speci
fied by th e prefix argum ent.

Insert File

N one

Prom pts for a file nam e, then in serts th e contents
o f the file a t th e cursor location.

Insert Buffer

N one

Prom pts for a buffer nam e, then in serts the
contents o f th e buffer a t the cursor location.

Cursor Movement Commands
EDT Set Direction Forward

Forward
(keypad [T] )

Sets the current direction to forward.

EDT S et Direction Backward

Backward
(keypad [T ] )

Sets the current direction to backward.

Forward Character

M oves th e cursor to the next character.

N ext Line

B
B
CD

Previous Line

ffl

Moves th e cursor to current colum n in previous
line.

EDT Move Character

Char
(keypad \T] )

MoveB the cursor to th e next or previous character,
depending on current direction.

EDT Move Word

Word
(keypad [T ] )

Moves th e cursor to th e beginning of the next,
current, or previous word, depending on current
direction and starting cursor location.

EDT Beginning of Line

B eginning of Line
(keypad [T ] )

Moves th e cursor to th e beginning of the next,
current, or previous lin e, depending on current
direction and starting cursor location.

EDT End o f Line

EOL
(keypad [T ] )

M oves th e cursor to the end of th e next, current,
or previous line, depending on current direction
and starting cursor location.

or
| or |£Ü] *

M oves th e cursor to th e start of th e current line
or previous lin e, depending on starting cursor
location.

EDT Scroll Window

Screen
(keypad [T ])

Scrolls tex t up or down in the window, depending
on current direction.

Previous Screen

| P rev S c r e e n |

M oves th e cursor up in th e buffer by one screenful.

N ext Screen

| N ex t S c r e e n |

M oves th e cursor down in the buffer by one
screenful.

End of Buffer

Bottom
(keypad [pr ] [7] )

M oves the cursor to the end of the current buffer.

B eginning o f Buffer

Top
(keypad [pfT] [T] )

M oves th e cursor to the beginning o f the current
buffer.

EDT Move Page

Page
(keypad [7] )

M oves the cursor to th e top o f th e next, current, or
previous page, depending on current direction and
startin g cursor location.

Backward Character

EDT Back to Start of Line

Moves th e cursor to the previous character.
M oves th e cursor to current colum n in next line.

| B a ck sp a ce |
|Ctrl/H

t Keys marked with an asterisk (*) are available only on LK201 and later keyboards.

(continued on next page)

3-20

Using the VAX LISP Editor

Table 3-2 (Cont.):

Editing C om m an ds and Key Bindings

Name

Binding t

Description

Cursor Movement Commands
EDT Query Search

Find
(keypad |
or [Find] *

Prom pts for a string and m oves th e cursor to
the first occurrence of th a t strin g in the current
direction.

Find N ext
(keypad [ 5] )

M oves th e cursor to th e first occurrence in the
current direction of th e la st string searched for.

Previous Form

ran

M oves th e cursor to beginning of current or
previous LISP form in th e current n estin g level.

N ext Form

SED

M oves th e cursor to beginning of next LISP form
in th e current n estin g level.

Beginning of O uterm ost Form

[Ctri/Xl m

M oves th e cursor to beginning of enclosing outer
m ost form, or to beginning o f preceding outerm ost
form if th e cursor starts betw een outerm ost forms.

End of O uterm ost Form

I Ctrl/X I m

M oves the cursor to end of enclosing outerm ost
form, or to end of follow ing outerm ost form i f the
cursor starts betw een outerm ost forms.

p f i | |PF3|)

EDT Search Again

p f

Moving by LISP Entities

Text Modification Commands
Deleting
EDT D elete Character
EDT D elete Previous Character

D el Char
(keypad □

D eletes the character a t the cursor location.
)

D eletes th e character before th e cursor location.

|D e l e t e |
< 3

EDT D elete Word

D el Word
(keypad 0

D eletes from cursor location to beginning of next
word.

)

EDT D elete Previous Word

|F13] *

D eletes from cursor location to beginning of
current word.

EDT D elete Line

D el Line
(keypad |PF4| )

D eletes from cursor location to beginning of next
line.

EDT D elete to End of Line

D el EOL
(keypad [p f T) [7] )

D eletes from cursor location to end of lin e, or all of
n ext line if cursor is at end o f line.

EDT D elete Previous Line

|Ctrl/U |

D eletes from cursor location to beginning of
current line, or all of previous lin e if cursor is at
beginning of line.

Undeleting
EDT U nd elete Character

U ndel Char
(keypad [ T] □

)

U ndel Word
(keypad [p f T) 0

)

p f

EDT U nd elete Word
EDT U ndelete Line

Inserts th e la st character deleted at th e cursor
location.
Inserts th e la st word deleted at the cursor location.

U ndel Line
(keypad | | | P F 4 | )

Inserts th e la st lin e deleted a t th e cursor location.

p f i

Keys marked with an asterisk ( * ) are available only on LK201 and later keyboards.

(continued on next page)

Using the VAX LISP Editor

3-21

Table 3-2 (Cont.):

Editing C om m an ds and Key Bindings

Name

Binding t

Description

Text Modification Commands
Cutting, Pasting, and Substituting
S et Select Mark

Select
(keypad [~~|) or
S e le c t [*

U n set Select Mark

R eset
(keypad [pfT] □

D efines one end of a select region.

C ancels a select region.
)

Select O uterm ost Form

|Ctrl/X | | C t r l/ S p a c e |

M akes a select region from th e outerm ost LISP
form containing th e cursor.

EDT Cut

C ut (keypad [T] )
Or | R e m o v e | *

Rem oves the select region from the tex t and
replaces th e contents of the paste buffer w ith the
select region.

EDT Append

Append
(keypad [T] )

R em oves the select region from the text and
appends the select region to th e contents of the
paste buffer.

EDT P aste

P aste
(keypad [pfT) [T] )
Or IIn s e r t | *

Inserts th e contents of th e paste buffer at the
cursor location.

EDT Replace

Replace
(keypad [pfT) [7] )

D eletes th e select region and replaces it w ith the
contents o f the paste buffer.

EDT Substitute

Subs
(keypad |PF1||Enter| )

S u b stitu tes the contents of the p aste buffer for the
search strin g and m oves to th e n ext occurrence of
the search string.

Query Search Replace

N one

Prom pts for old and new strings, and at each
occurrence of the old string prompts for an action;
m ore versatile th an "EDT S u b s t i t u t e " .

E xit Recursive Edit

N one

Term inates a recursive edit and returns to the
editing level from w hich th e recursive ed it w as
initiated.

EDT Change Case

Chng Case
(keypad [pfT][T] )

C hanges th e case of all characters in a select
region or of an individual character.

U pcase Region

N one

M akes all characters in a select region uppercase.

D ow ncase Region

N one

M akes all characters in a select region lowercase.

U pcase Word

N one

M akes all characters in the word a t the cursor
location uppercase.

D ow ncase Word

N one

M akes all characters in the word at the cursor
location lowercase.

C apitalize Word

N one

M akes the first character of th e word a t th e cursor
location uppercase.

Changing Case

General
Supply Prefix A rgum ent

Prefix
(keypad [p f i ] |p f i | )

Prom pts for a num eric prefix argum ent, which
m ay cause the n ext command to repeat its action.

t Keys marked with an asterisk (*) are available only on LK201 and later keyboards.

3-22

Using the VAX LISP Editor

3.3

Using Multiple Buffers and Windows
The Editor can keep track of more than one LISP object or file at a time.
The Editor holds each object or file that you are currently editing in a buffer.
Commands let you move between buffers, create new buffers, and gain access to
buffers through windows on the screen.

3.3.1 Introduction to Buffers and Windows
Buffers are Editor objects that contain the text of the symbol or file that you are
editing and some information about the text—for example, the position of the
cursor when the text is displayed. The Editor displays the contents of buffers
through windows on the screen. The Editor can keep track of many buffers
at once, but normally displays the contents of no more than two buffers it has
created for you at a time.
NOTE TO VWS VAXSTATION USERS

It is important to distinguish between the VAXstation window that
contains the Editor and the Editor windows that display the contents of
buffers. The VAXstation window is equivalent to the screen of a video
terminal. Editor windows appear in the VAXstation window.
The first time you use the e d function, you supply an argument specifying the
symbol or file you want to edit. The Editor creates a buffer having the same
name as this symbol or file and a window on the buffer. You can then enter and
modify the text in the buffer.
If, after you return to the LISP interpreter, you use the e d function with a
different symbol or file, the Editor creates another buffer and window. Both
windows appear on the screen, but the window for the buffer most recently
created is the current window. If you type characters or enter Editor commands,
the buffer viewed through the current window will be affected.
For example, if you first typed
Lisp> (ed ' s h i p - a c c e s s o r )

and then, after pausing the Editor, typed
Lisp> (ed "clock;, l s p " )

the screen might appear as shown in Figure 3-6.

Using the VAX LISP Editor

3-23

Figure 3-6:

The Editor with Two Buffers Open

-- Function SHIP-ACCESSOR Forward
Euse-package "EDITOR")

EDT Emulation ("VAX LISP")---

(define-command (clock-command :display-name"Clock")
(prefix)

n ?»

(let ((buffer (find-buffer"Clock")))
(unless buffer
(setf buffer (make-buffer'' (clock-buffer :display-name"Clock")
:major-style nil:minor-styles nil
:variables nil))

File CLOCK.LSP Forward

EDT Emulation ("VAX LISP")
MLO-002789

Now, two label strips appear, one at the bottom of each window. The reverse-video
label strip and the presence of the cursor in a window show you which window is
current.
To change the current window, use the Ctrl/X Ctrl/N key sequence, making each
window on the screen current in turn. When you change from one window to
another, the cursor moves to the position it occupied when you last edited in that
window.
Windows that display text you are editing are called anchored windows, because
they are fixed at a particular spot on the screen. Unless you use the " S p l i t
window" command, the Editor can by default display no more than two anchored
windows at once. However, you can have more than two LISP objects or files
available for editing at once, each occupying its own buffer. The " L i s t B u f f e r s "
command displays a list of all the buffers in the Editor. For example, if you had
used the ed function three times, the result of the command " L i s t B u f f e r s "
might appear as shown in Figure 3—7.

3-24

Using the VAX LISP Editor

Figure 3-7:

Listing Buffers in the Editor

puffer Name

Lines/Chars

Status

Ckpting

Kill Ring
SHIP-ACCESSOR

Empty
Writable
No
Empty
Writable
NO
Function of symbol SHIP-ACCESSOR
6/262
Modified
No
Help
44/1660
Modified
Yes
CLOCK.LSP
LISP$:[BODGE] CLOCK.LSP;2
General, Prompting
Errpty
Modified
No
SHIP-TONNAGE
Empty
Writable
No
Function of symbol SHIP-TONNAGE

Permanent
Yes
No
Yes
No
Yes
No

Listing of available editor buffers
(prefix)
(let ((buffer (find-buffer"Clock")))
(unless buffer
(setf buffer (make-buffer'(clock-buffer:display-name"Clock")
:major-style n i l :minor-styles nil
:variables nil))
---- File CLOCK.LSP Forward EDT Emulation ("VAX LISP")-----

MLO-002790

The buffers holding the objects and files that you are editing are identified by
an additional line detailing the contents of the buffer. For example, the buffer
named s h i p -ac cessor contains the “
Function of symbol SHIP-ACCESSOR’
’
. The
other buffers listed contain Editor information.
You can select a buffer for editing that is not currently on the screen with the
" S e l e c t B u f f e r " command. This command prompts for the name of a buffer to
edit. You can type part of the name, then use Ctrl/Space to request that the Editor
fill in the rest of the name. If you do not know which buffers are available, use
Alternatives to see a list of their names.
When you select a buffer from among those not currently displayed, the Editor
displays it in a new anchored window. If two anchored windows are already there,
the Editor removes the least current one and replaces it with one displaying the
contents of the buffer just selected.
Removing a window does not delete or modify the contents of the buffer.
Removing a window simply causes the corresponding buffer to be no longer
displayed, until the next time you select it. You can use the Ctrl/X Ctrl/R key se
quence to remove the current window from the screen and the "Remove o t h e r
windows" command to remove all windows other than the current window from
the screen.
In addition to anchored windows, the Editor also has floating windows. Floating
windows may be displayed anywhere on the screen, overlaying and obscuring
the anchored windows that lie under the floating windows. The window in which
help appears is a floating window. For the purpose of commands, these windows
are just like anchored windows; Ctrl/X Ctrl/N moves the cursor to them in turn, Ctrl/X
Ctrl/R removes them when they are current, and "Remove o t h e r windows" removes
them when they are not current.
Using the VAX LISP Editor

3-25

3.3.2

Creating New Buffers from Within the Editor
You do not need to return to the LISP interpreter to create a new buffer. Two
commands let you start editing new LISP objects or files without leaving the
Editor.
The "Ed" command works the same as the ED function. The "Ed" command
prompts for each of the arguments that you would enter to the ED function. If you
supply a symbol name, the Editor asks you to specify whether you want to edit
the function definition or the value of the symbol. If you supply a character string
containing a file specification, the Editor starts editing that file.
The " E d it F i l e " command prompts you for a file to edit. The " E d it F i l e "
command differs from the "Ed" command in that the " E d it F i l e " command lets
you request completion of the file name with Ctrl/Space and a listing of possible file
names with Alternatives. (See Section 3.1.3.2.)

3.3.3

Working with Buffers
Buffers generally take care of themselves. The only three common situations in
which you need to deal directly with buffers are:
• When you need to save the contents of a buffer
• When you need to delete a buffer
• When two buffers have conflicting names
Buffers maintain some information about the state of your editing session with
regard to the LISP object or file contained in the buffer. Specifically, a buffer
keeps track of:
• The position of the cursor in the text
• The select region, if one is active
• Key bindings, if any keys are bound in the context of the buffer (see
Section 3.5.1)
• The major and minor styles that are active in that buffer (see Section 3.5.1)
This information ensures that, when you select a buffer you worked on previously,
it will be in the same state as it was when you left it.

3.3.3.1

Saving Buffer Contents

Three commands save buffer contents. The "Write Current B u f f e r " and "W rite
M o d ifie d B u f f e r s " commands (discussed in Section 3.1) save the contents of the

single current buffer and of all buffers that have been modified, respectively. The
third way to save buffer contents is to use the " E x i t " command and request that
modified buffers be saved.
When you pause the Editor, your buffers are not written, but they are available
to you when you resume the Editor. If, however, you should pause the Editor and
then exit LISP, the contents of your buffers will be lost. (Section 3.4 explains how
you can partially recover from this situation.)

3-26

Using the VAX LISP Editor

3.3.3.2

Deleting Buffers

Two commands delete a buffer. " D e le t e Current B u f fe r " deletes the buffer you
are currently working on; " D e l e t e Named B u f fe r " prompts for a buffer name and
deletes that buffer. Both commands check to see if the buffer has been modified
and, if it has been, ask if you want to write the buffer before deleting it.
If you are editing an existing file and you delete the buffer associated with the
file, the Editor does not delete the file. However, the Editor also does not create
a new version of the file. For example, if you are editing the file CLOCKLSP;l
and you delete the buffer " c lock .l s p ", the file CLOCKLSP;l is not deleted.
However, the file CLOCK LSP;2, which would have been created if you had saved
the buffer contents, is not created.
3.3.3.3

Buffer Name Conflicts

The Editor requires that buffer names be unique. This requirement can cause a
problem in the following situations:
• You are trying to edit the function definition and the value of the same symbol
• You are trying to edit two files having the same name and type but differing
in some other respect (version number, directory, and so on)
When your attempt to edit something creates a buffer name conflict, the Editor
requests a new buffer name. You can type in any name you like. However, if
you should type in no name and just press Return, the Editor deletes the current
contents of the buffer, replacing them with whatever you are trying to edit.

3.3.4

Manipulating Windows
The commands most commonly used to manipulate windows have already been
presented in this chapter:
•
•

•

Ctrl/X Ctrl/N (bound to "Next Window") to make the next -window the current

window

Ctrl/X Ctrl/R (bound to "Remove Current Window") to remove the current window
from the screen
"Remove other windows" to remove windows other than the current window

from the screen

Other commands let you manipulate windows in other ways.
The "Grow window" and "Shrink Window" commands make the current window
larger and smaller, respectively. If no prefix argument is set, they make the
window one line larger or smaller. If a prefix argument is set, they make the
window larger or smaller by the number of lines specified in the prefix argument.
The " S p l i t Window" command lets you open two or more windows on a single
buffer. The command causes the current window to be split in two, with identical
text appearing in the two windows. Once created, the two windows can be treated
as ordinary windows; the window-manipulation commands move between the two
windows and remove them in the normal fashion. Each window maintains its
own cursor position and scrolls separately from the other; but if you type or edit
in one window, the change will appear in the other as well.

U sing the VAX LISP Editor

3-27

Split windows are useful if you want to examine two parts of the same buffer at
one time, or if you want to move text from one place to another in a buffer. To
move text, you would delete it or cut it in one window, move to the other window,
and undelete the text or paste it.
You can have more than two windows on a buffer; just use " S p l i t window"
repeatedly. The number of windows is limited only by the size of the screen; each
window must have at least one line.
Although the "S p lit window" command initially creates two windows on the
same buffer, you can cause one of those windows to switch to another buffer. Use
the " S e l e c t B u f f e r " command and specify a buffer not currently displayed in a
window. By repeatedly splitting windows and selecting new buffers, you can view
as many buffers as you can fit windows on the screen.

3.3.5 Moving Text Between Buffers
It is frequently useful to be able to move or copy text from one buffer to another.
For example, if you have worked on the definition of a function, you may want to
move it to a buffer in which you are editing a file. Two general ways of doing this
are:
• You can delete or cut the text from the source buffer, change to the destination
buffer, and undelete or paste the text in the destination buffer
• To insert an entire buffer in another, use the "Insert Buffer" command

3.3.6 Summary of Commands
Table 3-3 summarizes the commands presented in this section and their key
bindings. (Some of the general-purpose commands in Table 3—1 also pertain to
buffers and windows.)
Table 3-3: Comm ands for Manipulating Buffers and Windows
Name

Binding

Description

S elect Buffer

None

Prom pts for a buffer nam e, then m akes th a t buffer
the current buffer and displays it in a window.

L ist Buffers

N one

D isplays a lis t o f all Editor buffers.

D elete Current Buffer

None

D eletes th e current buffer.

D elete N am ed Buffer

N one

Prom pts for th e nam e of a buffer, then deletes
th a t buffer.

N one

Prom pts for a Bymbol nam e or file specification to
edit, th en creates a new buffer for th e symbol or
file.

E dit File

N one

Prom pts for the nam e o f a file, th en creates a
buffer for th a t file and a w indow into th e buffer.

Grow Window

None

Enlarges th e current w indow by one line or by the
num ber of lin es specified by th e prefix argum ent.

Shrink Window

N one

Shrinks th e current w indow by one lin e or by the
num ber o f lin es specified by th e prefix argum ent.
(c o n tin u e d o n n e x t p a g e)

3-28

Using the VAX LISP Editor

Table 3-3 (Cont.):

C om m an ds for Manipulating Buffers and W indows

Name

Binding

Description

Split Window

N one

Splits the current w indow s into tw o windows on
th e current buffer.

Insert Buffer

N one

Prom pts for th e nam e of a buffer, th en in serts the
contents o f th a t buffer a t the cursor location.

3.4 Recovering from Problems
The Editor provides facilities that let you recover from problems with all or
most of your work intact. Section 3.1.3.3 contains information on how the Editor
responds to minor errors. This section describes checkpointing, by means of
which the Editor protects work in progress.
Whenever you are editing a file, the Editor periodically makes a copy of the
current state of that file. The copy is a separate disk file, called the checkpoint
file. It has the same name as the file you are editing and a file type composed as
follows:
type_versionJ.SC

where typ e and version are the file type and version number, respectively, of the
file you are editing. For example, if you are editing the file CLOCK.LSP;2, the
associated checkpoint file will be named CLOCK.LSP_2_LSC.
While you are using the Editor or the LISP interpreter, an error may occur that
returns you to DCL, or you may inadvertently exit LISP without first saving
your Editor buffers, or the system may crash. In any of these cases, the current
state of your Editor work is lost. However, the checkpoint files for any files you
were editing still remain, reflecting the state of those buffers at the last time
that checkpointing took place. To use a checkpoint file after you have lost the
associated buffer, change its file type back to .LSP. Then use the Editor to edit
the file.
When checkpointing a file, the Editor displays the message “
Checkpointing...”
in the information area. You can continue to type while checkpointing is taking
place but whatever you type will not be displayed until checkpointing is complete.
By default, the Editor checkpoints after every 350 commands that alter text in
buffers. (Each keystroke that inserts a text character counts as a command.)

3.5 Customizing the Editor
You can customize the Editor to make it more convenient or comfortable to use.
This section describes two ways to customize the Editor:
• Section 3.5.1 explains how to bind keys or key sequences to commands. You
can bind keys to commands that have no keys bound to them by default, or
you can change the default bindings.
• Section 3.5.2 describes keyboard macros. A keyboard macro is a sequence of
keystrokes that the Editor captures for you; you can then replay the sequence
at a later time.
The V AX L I S P /V M S E d ito r P ro g ra m m in g G u ide explains how you can customize
t h e E d ito r e v e n fu r th e r b y c r e a tin g n e w c o m m a n d s o r n e w e d it in g s ty le s .

Using the VAX LISP Editor

a-29

3.5.1

Binding Keys to Commands
As previously stated, you interact with the Editor by using commands. Many
commands have keys or key sequences bound to them; others do not. One way
you can customize the Editor is to bind a key or key sequence to a command.
Once you have bound a key or key sequence to a command, typing that key or
key sequence invokes the command.
The two ways to bind a key or key sequence to a command are:
• While using the Editor, you can use the "Bind Command" command.
• While using the LISP interpreter, you can use the b in d - command function.
Your LISP initialization file can contain calls to b in d - command to set up the
Editor.
These two methods are discussed in Section 3.5.1.1 and Section 3.5.1.2, respec
tively.
No matter how you bind keys or key sequences to commands, there are two pieces
of information you must supply and a third that you may supply:
• You must supply the name of the command to be invoked.
• You must supply the key or key sequence to bind to the command.
Section 3.5.1.1 and Section 3.5.1.2 describe how to specify the key or key
sequence. Section 3.5.1.3 contains suggestions on how to select a key or key
sequence to bind.
• You can optionally supply the context in which the binding is effective.
Section 3.5.1.4 explains the key binding context.

3.5.1.1

Binding Within the Editor

The " Bi nd Command" command lets you bind a key or key sequence to a command
while using the Editor. This command prompts you for each of the three items
you need to specify a complete binding.
The "Bind Command" command first prompts you for the name of the command
y o u w is h to h a v e b o u n d . Y ou c a n u s e in p u t c o m p le tio n a n d a lt e r n a t iv e s to g e t a

complete command name.
The second prompt is for the key sequence. Type the actual key or key sequence
that you want to bind to the command—not a LISP representation of the charac
ters. However, you cannot type control characters or function keys unless you use
Ctrl/X \ to quote them. Since most bindings involve control characters or function
keys, you will tend to use Ctrl/X \ most of the time.
For example, assume that you want to bind the key sequence Ctrl/X Ctrl/O to a
command. Both Ctrl/X and Ctrl/O are control characters so they must both be
quoted. In response to the “
Enter key sequence”prompt, you would type:
I Ctrl/X |

1 \

|C trl« |

[~ T~ |

|C trl/O |

After you completed this sequence, the prompting area would echo:
<-'XXA0>

Function keys, arrow keys, and keys on the numeric keypad must also be quoted.
Each of these keys generates more than one character when it is struck, so more
than one character appears in the prompting area. For example, to bind the F12
key to a command, you would type:
fctri« ]

3-30

H ~|

|F12]

Using the VAX LISP Editor

This sequence is echoed in the prompting area as:
< E S C A P E > [24~

The third prompt is for the binding context. The context can be : global (the
default) or a particular style or buffer. Type : style or :buffer , followed by Return,
to specify one of these options. The Editor then prompts for the name of the style
or the buffer. (See Section 3.5.1.4 for more information on binding context.)
3.5.1.2

Binding from the LISP Interpreter

The b i n d - com m an d function lets you establish key bindings while you are using
the LISP interpreter. B IN D - com m and is especially useful in your LISP initialization
file to set up the bindings you use all the time.
The b i n d - com m an d function takes three arguments. The first argument is the
name of the command you wish to have bound, in the form of a character string.
The second argument is the key or key sequence that is to invoke the command.
A single key may be given as a LISP character. A key sequence must be given as
a vector or fist of characters.
For all the keys on the main part of the keyboard—those keys that produce
letters, numbers, and other printing symbols—you may use any valid LISP
representation of the character. For example, “
A”is #\A, “
a”is #\a, and “Ctrl/A”
is #\ '■A. The character transmitted by the Backspace key on a VT100 can be
#\Backspace, #\ b s , or #\AH. The LISP function char- name- table displays a table
of the LISP names for control characters.
The remaining keys on the keyboard—the numeric keypad, arrow keys, edit
ing keys, and function keys—transmit more than one character when struck.
Table 3-4 lists each key and the character sequence it generates. The VT100
keyboard lacks function and editing keypad keys, but the numeric keypad keys
and arrow keys generate the same characters listed in Table 3-4.
Some of the function keys on the LK201 and later keyboards are commonly
associated with particular characters. For example, the F12 key is associated with
Backspace and the Fi 3 key with Linefeed. However, these function keys do not
actually transmit these characters, and the Editor does not treat them as having
transmitted these characters.
Table 3-4: Characters Generated by Keys
Key

Characters Generated
Numeric Keypad Keys (LK201 and VT100)

k e y p a d QT]

#\ ESCAPE # \ 0 # \ p

k e y p a d [7]

#\ESCA PE # \ 0 # \ q

k e y p a d [T]

# \ESCA PE # \ 0 # \ r

k e y p a d [T]

#\ESCA PE # \ 0 # \ s

k e y p a d [T]

#\ESCA PE # \ 0 # \ t

k e y p a d [T]

# \E SC A P E# \0 #\u

k e y p a d [T]

#\ESCA PE # \ 0 # \ v

k e y p a d [T]

# \ESCA PE # \ 0 # \w

(continued on next page)

Using the VAX LISP Editor

3-31

Table 3-4 (Cont.):

Characters Generated by Keys

Key

Characters Generated
Numeric Keypad Keys (LK201 and VT100)

k e y p a d [T]

#\ ESCAPE #\0 #\x

k e y p a d [T]

#\ ESCAPE #\ 0 #\y

keypad □

#\ESCAPE #\0 #\m

keypad□

#\ESCAPE #\ 0 #\ 1

keypad □

#\ESCAPE #\0 #\n

k e y p a d |E nter!

#\ESCAPE #\0 #\M

k e y p a d |pfi |

#\ESCAPE #\0 #\P

k e y p a d |PF2|

#\ESCAPE #\0 #\Q

k e y p a d |PF3[

#\ESCAPE #\0 #\R

k e y p a d |PF4|

#\ESCAPE #\ 0 #\ S
Arrow Keys (LK201 and VT100)

#\ESCAPE #\ [ #\A

ffi

#\ESCAPE #\ [ #\B

#\ESCAPE #\ [ #\C

#\ESCAPE #\ [ #\D
Function, HELP, and DO Keys (LK201)

#\ESCAPE #\ [ #\1 #\7 #\~

#\ESCAPE #\ [ #\1 #\8 #\~

#\ESCAPE #\ [ #\1 #\9 #\~

#\ESCAPE #\ [ #\ 2 #\ 0 #\~

F°1

#\ESCAPE #\ [ #\2 #\1 #\~

ElD

#\ESCAPE #\ [ #\2 #\3 #\~

#\ESCAPE #\ [ #\2 #\4 #\~

#\ESCAPE #\ [ #\2 #\5 #\~

#\ESCAPE #\ [ #\ 2 #\ 6 #\~

iHiipl (FTsI)

#\ESCAPE #\ [ #\2 #\ 8 #\~

m (Eg)

#\ESCAPE #\ [ #\2 #\9 #\~

#\ESCAPE #\ [ #\3 #\1 #\~

EH
EE

#\ESCAPE #\ [ #\ 3 #\ 2 #\~

#\ESCAPE #\ [ #\ 3 #\4 #\~

#\ESCAPE #\ [ #\ 3 #\ 3 #\~

(continued on next page)

3-32

Using the VAX LISP Editor

Table 3-4 (Cont.):

Characters Generated by Keys

Key

C h a ra cters G en erated
E d itin g Keys (LK201)

[Find] (|3 )

#\ESCAPE #\ [ # \ 1 # \~

| In s e r t H e r e | ( [e£] )

#\ESCA PE #\ [ # \ 2 # \~

| R e m o v e |(|E3|)

# \ E S C A P E #\ [ # \ 3 # \ ~

Is5 £ t] ( | 5 | )

#\ E S C A P E # \ [ # \ 4 # \ ~

| P r e v S c r e e n |{(ES|)

#\ E S C A P E # \ [ #\5 # \ ~

|([E6])

#\ESCA PE #\ [ # \ 6 # \~

| N ex t S c r e e n

The third argument to b in d - command, which is optional, specifies the binding
context. If you omit this argument, the context is global; that is, the key binding
is effective everywhere in the Editor. If you include this argument, supply it in
the form
'(:STYLE "style-name")

or
’
(:BUFFER "buffer-name”
)

Section 3.5.1.4 describes binding context in more detail.
The following example binds the key sequence Ctrl/X Ctrl/O to the "Remove o t h e r

Windows”command globally:

(bind-command "remove o t h e r windows" , #(#\'"X #\ '“
O) )

Alternatively, you can globally bind the key sequence PF1 Rem ove (the Remove key
is on the LK201’
s editing keypad) to "Remove o t h e r Windows" as shown here:
(bind-command "remove o t h e r windows"
'# (# \escape #\o #\p # \ e s c a p e #\ ([ #\3 #\~)))

To bind the F12 key on an LK201 keyboard to the " edt Back t o s t a r t o f Line"
command in the " edt Em ulation" style, use the following function:
(bind-command " e d t back t o s t a r t o f l i n e "
'#(# \ esc a p e # \ [ #\2 #\4 #\~)
' (:style

"edt emulation"))

Following execution of this function, the F12 key moves the cursor to the beginning
of the line, but only if the "EDT Emulation" style is active. (This binding is in
effect by default.)
NOTE TO VWS VAXSTATION USERS

You can also bind actions of the pointing device (movement and but
tons) to commands. See the description of the b in d -p o in t e r - command
function in the V A X L I S P /V M S E d ito r P ro g ra m m in g G u ide.
3.5.1.3

Selecting a Key or Key Sequence

You can bind almost any key or key sequence to a command, but be careful that
your selection does not interfere with Editor operation. This section explains
restrictions and provides hints to help you make a selection.

Using the VAX LISP Editor

3-33

The three control characters you must not include anywhere in a key sequence
are:
• The cancel character, Ctrl/C by default, which terminates an Editor operation.
You cannot include Ctrl/C in a key sequence, because pressing Ctrl/C at any time
stops the collection of keystrokes and returns the Editor to the end of the last
completed command.
•

Ctrl/S and Ctrl/Q, which are interpreted by the operating system (they stop
output to the terminal and resume it, respectively), and therefore never reach
the Editor for interpretation.

You should not use any graphic (printing) character to start a key sequence,
although you can use graphic characters elsewhere in the sequence. If you start
a key sequence with, say, the letter A, you will never be able to type the letter
A as part of a word. The Editor, as soon as it sees the A, will recognize it as the
beginning of a key sequence; unless the next character(s) completes the sequence,
the Editor will signal an error and discard the A.
When you include an alphabetic character in a key sequence, remember that
the Editor differentiates between uppercase and lowercase. For example, the
following two key sequences are different:
' #(#\ ''X #\A)
' # ( # \ AX #\a)

By convention, the three keys used to start a key sequence are Ctrl/X, Escape, and
keypad PF1. You can, of course, use others if you choose, as long as they are
nonprinting. (On keyboards that do not have an Escape key, Ctrl/[ transmits the
# \ escape character.)
Finally, do not select a key or key sequence that is already bound to a useful
command. Appendix E contains a list of all the key bindings supplied with the
Editor. Section 3.5.1.4 explains how a single key or key sequence can be bound to
two different commands in different contexts.
3.5.1.4

Key Binding Context and Shadowing

When you bind a key or key sequence to a command, you can specify the context
in w h ic h t h a t b in d in g is e ffe c tiv e . S p e c ify in g a c o n te x t m e a n s t h a t t h e k e y o r k e y

sequence invokes the command only in that particular context.
The three general types of context are:
• The buffer context. If the context is a particular buffer, the key or key
sequence invokes the command only if that buffer is current.
• The style context. If the context is a particular style, the key or key sequence
invokes the command only if that style is the major style or one of the minor
styles that is active in the current buffer.
• The global context. If the context is global, the key or key sequence always
invokes the command. The default context is global.
Styles

A style is a collection of key bindings and of other Editor characteristics that
cause the Editor to behave in a certain way. The two styles that you encounter
in the default Editor are named " edt Em ulation" and "VAX l i s p ". The " edt
Em u latio n " style causes the numeric keypad to generate editing actions similar
to those of EDT. The "vax l i s p " style provides access to the Editor’
s ability to
edit LISP code easily.

3-34

Using the VAX LISP Editor

An Editor buffer can have one major style and one or more minor styles active at
any time. You can tell which styles are active by looking at the label strip for the
buffer. See Section 3.1.2.
The major style is generally established before the Editor is started. Minor styles
are activated automatically, depending on what is being edited. For example,
whenever you edit a LISP object or a file having the type .LSP, the "VAX LISP”
style is activated for that buffer as a minor style.
Shadowing

It is possible to bind the same key or key sequence to two different commands. If
the contexts of the two bindings are the same, then the second binding replaces
the first one. If, however, the two bindings have different contexts, then the key
or key sequence may invoke either command, depending on the situation at the
time. To locate a command to execute when a key is pressed, the Editor checks to
see that the key is:
1. Bound in the context of the current buffer.
2. Bound in the context of one of the current minor styles, examining the most
recently activated style first.
3. Bound in the context of the current major style.
4. Bound in the global context.
As soon as the Editor finds a command to execute, it does so. Therefore, if the
same key or key sequence is bound in, say, the current minor style and the
current major style, the binding in the minor style shadows or takes precedence
over the binding in the major style.
For example, the Ctrl/J key is bound tc " e d t D e le t e P r e v io u s word" in the " e d t
Em ulation" style and to "New l i s p L ine" in the "VAX l i s p " style. When you
are editing LISP code, " e d t Em ulation" is the major style and "VAX l i s p " is
the minor style. Therefore, the binding of Ctrl/J to "New LISP L ine" shadows the
binding to "EDT D e le t e P r e v io u s Word".

3.5.2 Keyboard Macros
A keyboard macro is a series of keystrokes that you ask the Editor to remember
for future use. The keystrokes can be keys that insert characters, keys or key
sequences that invoke editing commands, or even commands that you type in and
that issue additional prompts. A keyboard macro is useful whenever you have a
series of identical, complicated operations to perform.
To begin a keyboard macro, type Ctrl/X (. Everything you type from that point
is executed normally, but is also stored for future use. Typing Ctrl/X ) stops
the storage of keystrokes. To execute a keyboard macro, type Ctrl/X Ctrl/E. This
sequence causes the current keyboard macro to be played back starting at the
current cursor location. A keyboard macro that you define in this way lasts until
you define another keyboard macro.
You can also use the " s t a r t Named Keyboard Macro" command to define a key
board macro having a name. Use the " s t a r t Named Keyboard Macro" command as
you would the Ctrl/X (key sequence. The command prompts you for a name. After
you enter the name, the Editor starts remembering keystrokes. Terminate the
macro with Ctrl/X ). The macro thus defined is the current keyboard macro (you can
invoke it with Ctrl/X Ctrl/E), but it is also a named entity that you can treat like a
command. You can execute it as a named command or bind a key to it. A named
keyboard macro remains accessible by name even after another keyboard macro
has been defined.
U sin g th e VAX LISP Editor

3-35

A keyboard macro may not work properly if the context changes between the time
the macro is created and the time it is executed. For example, if you switch to
a buffer that has a different minor style active, the commands invoked by the
keyboard macro may fail.

3.5.3 Summary of Commands
Table 3—5 summarizes the commands presented in this section and their key
bindings.
Table 3-5: Comm ands for Customizing the Editor

3.6

Name

Binding

Description

Bind Command

N one

Prom pts for a com m and nam e and a key
sequence to bind to it.

Start Keyboard Macro

[ciri/xim

Starts collecting keystrokes for a key
board macro.

Start N am ed Keyboard Macro

N one

Prom pts for a nam e, then starts col
lectin g keystrokes for a keyboard macro
having th a t nam e.

End Keyboard Macro

icwxim

Term inates th e collection of keystrokes
for a keyboard macro.

Execute Keyboard Macro

1Ctrl/X I I Ctrl/EI

E xecutes th e current keyboard macro.

Using the Editor on a VWS VAXstation
The behavior and capabilities of the Editor when operating on a VWS VAXstation
are similar to its operation on an ordinary video terminal. The same commands
are available and the same key bindings are in effect. However, the Editor
incorporates several features that make use of VAXstation capabilities. This
section summarizes those features.

3.6.1 Before You Start
Before using the Editor on a VWS VAXstation, you must do the following:
• Activate specific lines in the VAX LISP startup file, LISPSTART.COM.
• Set the terminal emulator to NOFALLBACK mode.
These topics are discussed in detail in the following sections.
3.6.1.1 Activating Lines in LISPSTART.COM

Two lines in the installation file LISPSTART.COM affect your use of the pointer
when you use the Editor on a VWS VAXstation. These lines must execute when
the system starts up, before any process that runs the Editor is created. The lines
are as follows:
$ DEFINE/SYSTEM/EXECUTIVE UIS$VT_ENABLE_OSC_STRINGS TRUE
$ D E F I N E / S Y S T E M / E X E C U T I V E U I S $ V T _ E N A B L E _ L O C A T O R TRUE

3-36

Using the VAX LISP Editor

The first line defines a logical name that lets the Editor switch the input focus
back to the terminal emulator when the Editor is paused. The second line allows
the VAX LISP Editor to use a locator (mouse) on a VWS VAXstation display.
Comment these lines out if LISP is not running on a VWS VAXstation.
3.6.1.2 Setting the Terminal Emulator to NOFALLBACK Mode

Before you start the Editor on a VWS VAXstation, check that the terminal emu
lator is in NOFALLBACK mode. When the terminal emulator is in FALLBACK
mode, LISP hangs when switching input focus from the Editor to the window in
which the LISP process is running.
Use the DCL command SHOW TERMINAL to show which mode is active. To set
the terminal emulator to NOFALLBACK mode, enter the DCL command SET
TERMINAIVNOFALLBACK

3.6.2

Screen Appearance and Behavior
The most obvious difference in Editor behavior on a VAXstation is that the Editor
occupies a separate window from the LISP interpreter. This window has the
title "VAX l i s p E d ito r " . It is created the first time you start the Editor, and the
cursor is shifted to it from the window containing the LISP prompt. The Editor
window is taller than the 24 lines normally contained in a video terminal but is
otherwise identical to the Editor display described throughout this chapter.
When you pause the Editor, the cursor returns to the LISP prompt. When you
resume the Editor, the cursor moves to the spot it occupied in the Editor window
when you paused the Editor.
If you select the Delete option from the Window Options menu, the Editor exits,
giving you the opportunity to save buffers first.
While you are using the Editor, you cannot use the LISP interpreter, even though
the window containing the LISP prompt is still on the screen. You cannot use the
LISP interpreter until you pause or exit from the Editor.
NOTE

Do not attempt to delete or change the size of the Editor window.
Although these commands are enabled on the Window Options menu,
their use is unsupported and results are unpredictable.
You cannot adjust the width of the Editor window on a VWS
VAXstation, using the " S e t S cre en w idth" command.

3.6.3

Editing with the Pointer
The pointer cursor is the cursor that you move around the screen by moving
the mouse or other pointing device. By contrast, the text insertion cursor is the
blinking cursor that you move around the Editor windows by using conventional
Editor commands.
You can use the pointing device to perform some editing tasks. You can select a
new window to be the current window, move the text insertion cursor within the
current window, and cut and paste text. When you are editing LISP code, you can
also select LISP forms, describe LISP symbols, and match parentheses.

Using the VAX LISP Editor

3-37

The description of initial pointer bindings assumes that the pointing device is
set for right-handed operation (the default). If you have set the pointing device
for left-handed operation (in VAXstation setup mode), reverse the indications
of right and left buttons in the following sections and in the Appendix E icon
representations.
NOTE

Pointer movement is signaled at the character-cell level instead of at
the pixel level. As a result, the Editor does not know the pointer has
moved unless it crosses a character-cell boundary. If you are trying to
establish a select region with the pointer, and the select region fails
to reach the current pointer cursor location, simply move the pointer
cursor over a character-cell boundary. This will signal movement, and
the Editor will update the select region.
3.6.3.1

Selecting and Removing Windows

When the pointer cursor is in a window other than the current window, press the
left pointer button to make that window the current window. The text insertion
cursor is placed where it was the last time that window was current. Press the
middle pointer button in a window other than the current window to remove that
window from the screen.
3.6.3.2

Moving the Text Insertion Cursor and Marking Text

When the pointer cursor is in the current window, press the left pointer button to
move the text insertion cursor to the pointer cursor. If you release the left button
without moving the pointer cursor, the text insertion cursor stays in the same
place. However, you can also leave the left button down and move the pointer
cursor. If you do this, the text insertion cursor also moves. The text between
where you first pressed the left button and where you finally release it is marked
as a select region.
If you are editing LISP code, you can use the left pointer button to mark LISP
forms as select regions. The first time you press the button, the text insertion
cursor moves to the pointer cursor. Each time you press the button without mov
ing the pointer cursor, a LISP form that encloses the pointer cursor is marked.
Enclosing forms are marked until the outermost form is reached.
3.6.3.3

Cutting and Pasting

In the current window, press the middle pointer button to cut text that has been
marked as a select region. Press the middle pointer button with the left pointer
button depressed to paste text from the paste buffer at the pointer cursor position.
Tb cut and paste text, follow these steps:
1.
2.
3.
4.

3-38

Mark the text to be cut, using any method.
Press the middle pointer button to cut the text.
Move the pointer cursor to the position at which you want to paste the text.
Press and hold the left pointer button, then press the middle button.

Using the VAX LISP Editor

3.6.3.4

Invoking the DESCRIBE Function and Matching Parentheses

When you are editing LISP code, you can use the right pointer button to invoke
the LISP d e s c r ibe function. Move the pointer cursor to a symbol, then press the
right button. The Editor’
s help window appears and displays the results of using
the d e s c r ib e function on that symbol.
If you move the pointer cursor to a right parenthesis and press the right pointer
button, the matching left parenthesis is highlighted.
3.6.3.5

Information About Pointer Effects

You can find out what action a pointer button invokes by moving the pointer
cursor to the information area. When you press any pointer button, the name of
the command invoked by that button is displayed in the information area. Note
that the command displayed is the one invoked by that button when the pointer
cursor is in the current window. When you release the button, the command (if
any) invoked by releasing the button is displayed.
Moving the pointer cursor in the information area with the buttons held a certain
way displays the command that is invoked by pointer movement with the buttons
in that state.

3.6.4

Binding Pointer Buttons to Commands
Binding pointer buttons to commands is analogous to binding keys or key
sequences to commands. See the VAX L I S P /V M S E d ito r P ro g ra m m in g G u id e for
information.

Using the VAX LISP Editor

3-39

Chapter 4

Debugging Facilities
Debugging is the process of locating and correcting programming errors. When
an error is signaled, the VAX LISP error handler displays a message, which
states the error type, the name of the function that caused the error, the name
of the function the LISP system used to signal the error, and a description of the
error.
Once you know the name of the function that caused an error, you can use the
VAX LISP debugging functions and macros to locate and correct the programming
error. Table 4—1 lists the debugging functions and macros with a brief description
of each. See the VAX L I S P /V M S O bject R eference M a n u a l for more detailed
descriptions.
Table 4-1:

Debugging Functions and Macros

Name

Function
or Macro

APROPOS

Function

Locates sym bols w hose print nam es contain a
specified string argum ent as a substring and
displays inform ation about each symbol it locates.

APROPOS-LIST

Function

Locates symbols w hose print nam es contain a
specified string argum ent as a substring and
returns a lis t of th e sym bols it locates.

BREAK

Function

Invokes th e break loop.

DEBUG

Function

Invokes the VAX LISP Debugger.

DEBUG-CALL

Function

Returns a lis t representing th e call a t th e current
debug stack frame.

DESCRIBE

Function

D isplays detailed inform ation about a specified
object.

DRIBBLE

Function

Sends the in pu t and the output of an interactive
LISP session to a specified file.

Function

Invokes the VAX LISP Editor.

INSPECT

Function

Invokes th e VAX LISP Inspector.!

ROOM

Function

D isplays inform ation about th e sta te o f internal
storage and its m anagem ent.

STEP

Macro

Invokes th e stepper.

Description

t The Inspector is available only on the DECwindows interface.

(continued on next page)

Debugging Facilities 4-1

Table 4-1 (Cont.):

D ebu ggin g Functions and M acros

Name

Function
or Macro

TIME

Macro

D isplays tim in g inform ation about the evaluation of
a specified form.

TRACE

Macro

Enables the tracer for functions and macros.

UNTRACE

Macro

D isables th e tracer for functions and macros.

Description

This chapter provides the following:
• A list of the functions and macros that provide you with debugging
information
• Descriptions of two variables that control the output of the Debugger, the
stepper, and the tracer facilities
• A description of the VAX LISP control stack
• Explanations of how to use the following debugging facilities:
— Break loop—read-eval-print loop you can invoke while the LISP system is
evaluating a program.
— Debugger—A control stack Debugger you can use interactively to inspect
and modify the LISP system ’
s control stack frames.
— Stepper—A facility you can use interactively to step through a form’
s
evaluation.
— Tracer—A facility you can use to inspect a program’
s evaluation.
— Editor—An extensible editor that lets you edit programs and data
structures.

4.1 Control Variables
VAX LISP provides two variables that control the output of the Debugger,
the stepper, and the tracer facilities: *debug -p r i n t -length * and *debug p r i n t -le v e l *. These variables are analogous to the Common LISP variables
* p r i n t - length * and *p r i n t - level * but are used only in the Debugger.
* DEBUG-PRINT-LENGTH*

Controls the num ber o f displayed elem en ts a t each
level of a nested data object. The variable’s valu e m ust
eith er be an in teger or NIL. The default value is NIL
(no lim it).

* DEBUG-PRINT-LEVEL*

Controls the num ber of displayed levels of a nested
data object. The variable’s value m u st either be an
in teger or NIL. The default valu e is NIL (no lim it).

4.2 Control Stack
The control stack is the part of LISP memory that stores calls to functions,
macros, and special forms. The stack consists of stack frames. Each time you call
a function, macro, or special form, the VAX LISP system does the following:
1. Pushes the name of the function associated with the function, macro, or
special form that is being called onto the stack frame.
4-2

Debugging Facilities

2. Pushes the function’
s arguments onto the stack.
3. Creates a new stack frame.
4. Invokes the function.
Each control stack frame has a frame number, which is displayed as part of the
stack fram e’
s output. Stack frame numbers are displayed in the output of the
Debugger, the stepper, and the tracer.
There is always one active stack frame, and it can be either significant or
insignificant. Significant stack frames are those that invoked documented
and user-created functions. Insignificant stack frames are those that invoked
undocumented functions.
Debugger commands show only significant stack frames unless you specify the
ALL modifier with a Debugger command (see Section 4.4.3.1). Significant stack
frames store one of the following calls:
• A call to a function named by a symbol that is in the current package
• A call to a function that is accessible in the current package and is explicitly
or implicitly called by another function that is in the current package
See C om m on L IS P : The L a n g u a g e for information on packages.

4.3

Break Loop
The break loop is a read-eval-print loop that you can invoke to debug a program.
You can invoke the break loop while a program is being evaluated. If you do, the
evaluation is interrupted and you are placed in the loop.

4.3.1 Invoking the Break Loop
You can invoke the break loop by calling the BREAK function. The two ways of
using the break function to debug a program are:
• Use the VAX LISP b in d - keyboard-function function to bind an ASCII
keyboard control character to the break function. Then, use the control
character to directly invoke the break function while your program is being
evaluated (see the VAX L I S P /V M S O bject R eference M a n u a l for a description
O f the BIND-KEYBOARD-FUNCTION function).
• Put the break function in specific places in your program.
In either case, the break function displays a message (if you specified one in your
form calling the break function) and enters a read-eval-print loop. If you specified
a message, the break function displays the message in the following format:
Break:
your m essage.

After the message is displayed, a prompt is displayed at the left margin of your
terminal:
Break>

Debugging Facilities

4—3

4.3.2

Exiting the Break Loop
When you are ready to exit the break loop and continue your program’
s evalua
tion, invoke the VAX LISP continue function.
Break> (continue)

The continue function causes the evaluation of your program to continue from
the point where the LISP system encountered the break function.
If you are in a nested break loop and you invoke the continue function, you are
placed in the previous break-loop level. A description of the continue function is
provided in the V AX L I S P /V M S O bject R eference M a n u a l.

4.3.3 Using the Break Loop
Once you are in the break loop, you can check what your program is doing by
interacting with the LISP system as though you were in the top-level loop. For
example, suppose you define a variable named »f i r s t * and a function named
counter , which uses the variable »
f i r s t *.
L is p > (defvar »first* 0)
»FIRST*
L is p > (defun counter nil
(if (< »first* 100)
(progn (incf »first»)
»first»))

(counter))

COUNTER

If you bind the break function to a control character, you can interrupt the
function’
s evaluation by typing the control character. For example:
L isp>
T
L isp>

(bind-keyboard-function tV^b #'break)
(counter) |Returnj

ICtrl/BI

Break>

Once you are in the break loop, you can check the value of the variable »f i r s t *.
Break> »first*
16

Break>

If you call the continue function, the evaluation of the function counter contin
ues.
Break> (continue)

After you call the continue function, you can see that the evaluation was
continued by invoking the break loop again and rechecking the value of the
variable »FIRST*.
[Ctrl/B1

Break> »first*
93

Break>

Use the continue function again to complete the function’
s evaluation.
Break> (continue)
C o n tin u in g from Break l o o p . . .
100

4—4

Debugging Facilities

Changes th a t you m ake to global variables and global definitions while you
are in th e b reak loop rem ain in effect after you exit the loop and your program
continues. For example, if you are in the break loop and you find th a t th e value of
th e variable nam ed * f i r s t * has an incorrect value, you can change the variable’s
value. The change rem ains in effect after you exit the break loop and continue
your program ’s evaluation.
NOTE
The forms you type while you a re in the break loop a re evaluated in
a null lexical environm ent, as though they are evaluated a t top level.
Therefore, you cannot exam ine the lexical variables of a program th a t
you in te rru p t w ith the break loop. To exam ine those lexical variables,
invoke the Debugger (see Section 4.4). For inform ation on lexical
environm ents, see C om m on L IS P : The L an g u a g e.

4.3.4 Break Loop Variables
The break loop uses a copy of the top-level-loop variables (plus (+), hyphen (-),
asterisk (*), slash ( / ) , and so on) the sam e way the top-level loop uses them (see
C o m m o n L IS P : The L an gu age). These variables preserve the in p u t expressions
you specify and the output values the VAX LISP system re tu rn s while you are in
the break loop.

4.4 Debugger
The VAX LISP Debugger is a control stack Debugger. You can use it interactively
to inspect and modify the LISP system ’s control stack fram es. The Debugger has
a pointer th a t points to th e current stack fram e. The cu rren t stack fram e is the
la s t fram e for which th e Debugger displayed inform ation. The Debugger provides
several comm ands th a t perform the following:
•

Display help

•

E valuate a form or reevaluate the function call a stack fram e stores

•

H andle errors

•

C h a n g e w h ic h s ta c k fr a m e is c o n sid e r e d c u r r e n t

•

Inspect or modify the function call in a stack fram e

•

Display a sum m ary of the control stack

The Debugger reads its in p u t from and p rin ts its output to the stream bound to
th e * d e b u g - i o * variable.

4.4.1

Invoking the Debugger
The VAX LISP system invokes the Debugger w hen errors occur. You can invoke
th e Debugger by calling the VAX LISP d e b u g function. F or example:
L isp >

(debug)

D e b u g g i n g Facilities

4-5

W hen th e Debugger is invoked, a m essage th a t identifies th e Debugger and the
cu rre n t stack fram e, preceded by “Apply” or “E val”, and th e comm and prom pt are
displayed a t th e left m argin of your term inal in th e following form at:
C o n tro l S ta ck D ebugger
A p p l y #5: (DEBUG)
D ebug n>

The le tte r n in the prom pt represents an integer, which indicates th e num ber of
the nested command level you are in. The value of n increases by one each tim e
the comm and level increases. For example, the top-level read-eval-print loop is
level 0. If an error is invoked from the top-level loop, th e Debugger displays the
prom pt Debug 1>. If you m ake another error while in the Debugger, th a t error
causes the Debugger to display the prom pt Debug 2>.
A fter th e Debugger is invoked, you can use the Debugger comm ands to inspect
and modify the contents of the system ’s control stack.
A description of the d e b u g function is provided in the VAX L I S P /V M S O bject
R eferen ce M a n u a l.

4.4.2 Exiting the Debugger
To exit th e Debugger, use the QUIT Debugger command. It causes the Debugger
to re tu rn control to the previous command level.
D ebug 2> q u i t
D e b u g 1>

If you specify the QUIT command w hen the Debugger command level is 1
(indicated by the prom pt Debug 1>), the comm and causes the Debugger to exit
and re tu rn s you to the system ’s top level. For example:
Debug
L isp >

1> q u i t

By default, th e QUIT command displays a confirm ation m essage before the
Debugger exits if a continuable error causes the Debugger to be invoked. For
example:
D e b u g 1> q u i t
Do y o u r e a l l y

w ant t o

lea v e

th is

debug

e n v iro n m en t?

If you type YES, the Debugger re tu rn s control to th e previous command level.
Do y o u
L isp >

re a lly

w ant to

lea v e

th is

debug e n v iro n m e n t?

yes

If you type NO, the Debugger prom pts you for an o th er command.
Do y o u r e a l l y
D e b u g 1>

w ant to

lea v e

th is

debug e n v iro n m e n t?

You can prevent the Debugger from displaying the confirmation m essage by
specifying th e QUIT command w ith a value other th a n n i l . For example:
D ebug
L isp >

1> q u i t

A description of the QUIT comm and is provided in Section 4.4.3.2.

4—6

D e b u g g i n g Facilities

4.4.3

Using Debugger Commands
The Debugger commands let you inspect and modify th e c u rren t control stack
fram e and move to other stack fram es. You m u st specify m any of the Debugger
commands w ith one or m ore argum ents th a t qualify comm and operations. These
argum ents are listed in Section 4.4.3.1.
You can abbreviate Debugger comm ands to as few characters as you like, as long
as no am biguity is in th e abbreviation.
E n te r a Debugger comm and by typing the comm and nam e or abbreviation and
th en pressing Return. For example:
D ebug 1> b a c k t r a c e

|R e t u r n |

If you press only Return, th e Debugger prom pts you for another command.
Table 4—2 provides a sum m ary of th e Debugger commands. D etailed descriptions
of the commands are in Section 4.4.3.2.
Table 4-2:

Debugger Commands

Command

D e scrip tio n

BACKTRACE

D isplays a backtrace of th e control stack.

BOTTOM

M oves th e current fram e pointer to the first stack fram e on the control
stack.

CONTINUE

C ontinues execution by returning from th e continuable error th a t
invoked th e Debugger.

DOWN

M oves th e current fram e pointer down th e control stack.

ERROR

R edisplays the error m essage th a t w as displayed w hen th e Debugger
w as invoked.

EVALUATE

E valuates a specified form.

GOTO

M oves the pointer to a specified stack frame.

HELP (or) [T]

D isplays help tex t about the D ebugger commands.

QUIT

Exits to th e previous command level.

REDO

Reinvokes the function in th e current stack frame.

RETURN

E valuates its argum ents and causes th e current stack fram e to return
the same values the evaluation returns.

4.4.3.1

Searches th e control stack for a specified function.

SET

Sets th e valu es of th e com ponents in th e current stack frame.

SHOW

D isplays inform ation stored in the current stack frame.

STEP

Invokes the stepper for th e function in th e current stack frame.

TOP

Moves the pointer to th e la st stack fram e in th e control stack.

Moves the pointer up the control stack.

WHERE

R edisplays the argum ent lis t and th e function nam e in th e current
stack fram e.

Arguments
Some Debugger comm ands require an argum ent; other Debugger commands
accept optional argum ents. An argum ent whose value is an integer is usually
optional; an argum ent whose value is a symbol or form is required. If you do
n ot specify an argum ent th a t is required, the Debugger p r o m p ts you for the
argum ent. For example:
Debugging Facilities 4-7

D e b u g 1> r e t u r n
F i r s t V a lu e:

| R etu rn |

The Debugger does not prom pt for argum ents if you specify them in the command
line.
E n te r an argum ent a fter the comm and it qualifies and then press Return. For
example:
Debug

1> dow n a l l

| Ramm|

The types of argum ents you can specify w ith Debugger comm ands are:
•

Debugger command

•

Symbol

•

Form

•

Function nam e

•

Integer

•

Modifier
NOTE
Only parenthesized expressions and argum ents to evaluate (th at is,
argum ents specified w ith the EVALUATE command) are evaluated.

The preceding argum ents are self-explanatory w ith th e exception of the integer
and modifier argum ents.
Integer argum ents rep re sen t control stack fram e num bers. Each stack fram e on
th e control stack h a s a fram e num ber, which th e Debugger displays as p a rt of
the stack fram e’s output. The Debugger reassigns these num bers each tim e it is
invoked. You can specify a fram e num ber in a Debugger command to refer to a
specific stack fram e in th e current debugging session.
Table 4—3 provides a sum m ary of the modifier argum ents you can specify w ith
Debugger commands.
Table 4-3:

Debugger Command Modifiers

Modifier

Command Modification

ALL

Operates on both significant and insignificant stack fram es.

ARGUM ENTS

O perates on th e argum ents specified w ith the function in the current
stack frame.

CALL

O perates on th e call to th e current stack frame.

DOWN

M oves th e pointer down th e control stack.

FUNCTION

O perates on the function object in the current stack frame.

HERE

O perates on the current stack frame.

NORMAL

D isplays the function nam e and th e argum ent list in the control stack
fram es.

(continued on next page)

4-8

D e b u g g i n g hacilities

Table 4-3 (Cont.):

4.4.3.2

D ebu gger Com m and M odifiers

Modifier

Command Modification

QUICK

D isplays th e function nam e in the control stack frames.

TOP

Starts a backtrace a t the top of th e control stack.

Moves the pointer up the control stack.

VERBOSE

D isplays th e function nam e, argum ent list, and som e variable bindings
in th e control stack fram es.

Debugger Commands
The VAX LISP Debugger provides comm ands th a t you can use to move through
and modify the system ’s control stack.
Help Command
HELP
i? I

The HELP command displays help tex t about th e Debugger commands.
You can specify this com m and w ith one argum ent, w hich is th e nam e of
the Debugger command about w hich you w ant help text. If you specify
the HELP com m and w ithout an argum ent, th e D ebugger displays a list
of the D ebugger commands.
You can abbreviate this com m and by u sin g a question m ark (?).

Evaluation Command
You can evaluate LISP expressions w hile you are in th e Debugger.
If you w an t th e LISP system to evaluate a parenthesized form, you
can specify the form and th en press Return. If you w ant th e system to
evaluate a symbol, you m u st use th e EVALUATE command. You can
also evaluate expressions by entering th e break loop. For information
on the break loop, see Section 4.3.

EVALUATE

The EVALUATE command explicitly evaluates a specified form. You
m ust specify th e com m and w ith an argum ent th a t is th e form you w ant
th e LISP system to evaluate. The system evaluates th e form in the
lexical environm ent o f the current stack frame.

Error-Handling Commands
The D ebugger deals w ith errors th a t invoke th e Debugger. Each of th e
following D ebugger com m ands deals w ith errors in a different way.

CONTINUE

The CONTINUE command causes the D ebugger to return N IL , lettin g
you return from a continuable error or from a w arning if the valu e of
the *BREA K-ON-W ARN INGS* variable is T. This command is sim ilar to
the CONTINUE function. See VAX L IS P Implementation and Extensions
to Common L ISP for a description of error types.

QUIT

The QUIT com m and le ts you ex it to th e previous com m and level. I f the
current level o f th e D ebugger is 1, th e com m and causes th e Debugger
to exit to the LISP prompt (Lisp>). You can specify th is command w ith
an optional argum ent. If a continuable error invokes th e D ebugger and
the argum ent is N IL , the D ebugger displays a confirm ation m essage.
If you respond to th e m essage by typing YES, th e com m and returns
control to th e previous com m and level. If the argum ent is not N IL ,
the D ebugger does not display a m essage. The default v alu e for th e
optional argum ent is N IL . This command is sim ilar to the ABORT
function.

D e b u g g i n g Facilities

4—9

Error-Handling Commands
REDO

The REDO command invokes the function in th e current stack frame,
causing the LISP system to reevaluate th e function in th a t frame. This
command is useful for correcting errors th a t are not continuable, such
as unbound variables and undefined functions. To do so, first bind th e
variables or define th e function, then use th e REDO command.

RETURN

The RETURN com m and evaluates its argum ents and causes the
Debugger to force th e current stack fram e to return the sam e v a l
ues th e evaluation returns. If you om it th e argum ent, th e Debugger
prompts you for it. The RETURN command can accept m ultiple argu
m ents, each one an expression to be evaluated. Each evaluated form
produces only one value to be returned.

STEP

The STEP command invokes th e stepper for the function th a t is in the
current stack fram e. W hen th e stepper is invoked, th e LISP system
reevaluates th e function. This command is useful i f you w ant to repeat
an error to get inform ation about the cause of th e error.

Movement Commands
The m ovem ent com m ands m ove th e D ebugger’s pointer to another
stack frame. The D ebugger displays th e new stack fram e’s information.

BOTTOM

The BOTTOM command moveB th e pointer to the first significant
stack fram e on th e control stack. If you specify the ALL modifier
w ith th e BOTTOM command, th e command m oves the pointer to the
first (oldest) stack fram e on th e control stack w hether the fram e is
significant or insignificant.

DOWN

The DOWN com m and m oves th e pointer toward th e bottom of the
control stack, one fram e at a tim e. You can specify thiB command
w ith optional argum ents. One o f the optional argum ents is th e ALL
modifier. If you specify ALL, th e command m oves th e pointer down the
significant and insignificant stack fram es on th e control stack.
You can also specify an optional integer argum ent, w hich indicates
th e num ber of stack fram es down which the command is to move the
pointer.

GOTO

The GOTO com m and m oves the pointer to a specified stack frame. You
m ust specify th is com m and w ith an in teger th a t specifies the num ber
of th e stack frame.

The SEARCH com m and searches th e control stack for a specified
function name. You m u st specify th is command w ith tw o argum ents.
The first argum ent m u st be either th e U P or the DOWN m odifier to
specify the direction o f the com m and’s search. The second argum ent
m ust be the nam e of th e function for which the command is to search.
You can also specify an optional integer argum ent. This argum ent
m u st follow the function nam e argum ent in the command specification.
The integer you specify in dicates the num ber of occurrences of the
specified function nam e th a t you w an t th e command to skip.

TOP

4—10

D e b u g g i n g Facilities

The TOP com m and m oves the pointer to the la st (new est) significant
stack fram e on th e control stack. If you specify th e ALL modifier
w ith th e TOP command, th e command m oves the pointer to th e la st
stack fram e on th e control stack w hether th e fram e is significant or
insignificant.

Movement Commands
UP

The U P com m and m oves th e pointer toward the top of the control
stack. You can specify this command w ith optional argum ents. One
of the optional argum ents is th e ALL modifier. If you specify it, the
com m and m oves th e pointer up the significant and insignificant stack
fram es on the control stack.
You can also specify an optional integer argum ent. It indicates the
num ber o f stack fram es up which th e command is to m ove the pointer.

WHERE

The WHERE command redisplays the function nam e and argum ent list
in the current stack frame.

Inspection and Modification Commands
You can in spect and change the inform ation in a function call before
th e LISP system evaluates th e call. To do th is, use the inspection and
m odification commands.

ERROR

The ERROR command redisplays the error m essage th a t w as displayed
for the error th a t invoked the Debugger.

SET

The SET command sets th e values of the com ponents in th e cur
rent stack frame. You m ust specify this command w ith three argu
m ents. The first argum ent m u st be either the ARGUM ENTS or the
FUNCTION modifier. The modifier determ ines w hat th e command
sets. The follow ing lis t describes w hat is set w hen you specify each
modifier:
ARGUM ENTS

The value of an argum ent in the current stack
frame.

FUNCTION

The function object in th e current stack frame.

If you specify the ARGUMENTS modifier, the second argum ent m ust
be th e symbol th a t nam es the argum ent to be set, and the third
argum ent m u st be a form th a t evaluates to the new value. If you
specify the FUNCTION modifier, th e second argum ent m u st be a
form th a t evaluates to a function or the nam e of a function. The new
function m u st take the sam e num ber of argum ents th e old function
takes.

SHOW

The SHOW command displays inform ation stored in th e current stack
frame. You m ust specify this command w ith th e ARGUMENTS, CALL,
FUNCTION, or HERE modifier. The modifier determ ines w h at the
com m and is to display. The follow ing lis t describes w hat th e command
displays w hen you specify each modifier:
ARGUM ENTS
A lis t of th e argum ents in th e current stack frame.
CALL

The function call th a t created the current stack
frame. The command displays th e function call so
th a t its output is easy to read. The argum ents in
th e call are represented by their values.

FUNCTION

The function in th e current stack frame. The
function can be either interpreted or compiled w ith
th e COMPILE function. The function cannot be
displayed if it is a system function or if it is loaded
from a compiled file.

HERE

A description o f th e current stack frame.

D e b u g g i n g Facilities

4-11

Backtrace Command
BACKTRACE

The BACKTRACE com m and displays th e argum ent lis t of each stack
fram e in th e control stack, startin g from th e top of th e stack. You can
specify th e com m and w ith modifiers to specify the style and extent
of th e backtrace. The m odifiers you can specify are ALL, NORMAL,
QUICK, HERE, TOP, or VERBOSE. By default, th e command uses
th e NORMAL and th e TOP modifiers. The following list describes the
style or exten t th e BACKTRACE command u ses w hen you specify each
modifier:
ALL
D isplays significant and insignificant stack fram es.
NORMAL

D isplays th e function nam e and argum ent list in each
stack frame.

QUICK

D isplays th e function nam e in each stack frame.

HERE

Starts th e backtrace a t th e current stack frame.

TOP

Starts th e backtrace at th e top of th e control stack.

VERBOSE

D isplays the function nam e, argum ent list, and local
variable bindings in each stack frame.

4.4.4 Using the DEBUG-CALL Function
The d e b u g - c a l l function re tu rn s a list representing the call a t the current debug
stack fram e. This function is a debugging tool and takes no argum ents. The list
retu rn ed by d e b u g - c a l l can be used to access the values passed to the function in
the current stack fram e. If used outside the Debugger, d e b u g - c a l l re tu rn s n i l .
The following exam ple shows how to use the function:
L isp >

(d efv ar

a d ju s ta b le -strin g
( m a k e - a r r a y 10 : e l e m e n t - t y p e ' s t r i n g - c h a r
: in itia l- e le m e n t # \sp a c e
: a d j u s t a b l e t ))
A D JU S T A B L E -S T R IN G
L i s p > ( s c h a r a d j u s t a b l e - s t r i n g 3)
E rro r in
A rgum ent

SCHAR:
is not

o f ty p e

(S IM PL E -A R R A Y CHARACTER 1 ) :

C o n tro l S ta ck D ebugger
A p p l y # 6 : (SCHAR "
D eb u g 1> ( t y p e - o f ( s e c o n d

" 3)
( d e b u g - c a l l ) ))

(VECTOR CHARACTER 1 0 )
D eb u g 1> r e t # \ s p a c e
#\SP A C E
L isp >

In this case, the function in th e cu rren t stack fram e is s c h a r . The call to
(DEBUG-CALL) re tu rn s the list ( s c h a r "
" 3 ) . The form ( s e c o n d
( d e b u g -C A L L ) ) re tu rn s the first arg u m en t to s c h a r in the current stack fram e.
Calling t y p e - o f w ith this LISP object determ ines th a t the first argum ent to
s c h a r is of type ( v e c t o r c h a r a c t e r i o ) and not a sim ple string.

4-12

D e b u g g i n g Facilities

4.4.5 Sample Debugging S essio n s
1.

L i s p > ( d e f u n f i r s t - e l e m e n t (x)
F IR S T - E L E M E N T
L is p > ( f i r s t - e l e m e n t 3)
E r r o r i n CAR: A r g u m e n t m u s t b e

(car x ) )

lis t:

C o n tro l S ta ck D ebugger
A p p l y # 8 : (CAR 3 )
D e b u g 1> down
Eval
# 7 : (CAR X)
D e b u g 1> down
Eval
# 6 : (BLOCK F I R S T - E L E M E N T (CAR X ) )
D e b u g 1> down
A p p l y # 4 : (FIRST-ELEM EN T 3 )
D e b u g 1> sh o w h e r e
I t i s an in te r p r e te d fu n c tio n
L a m b d a - l i s t : FIRST-ELEM EN T X
— A rg u m e n ts —
X : 3
D e b u g 1> s e t
T y p e o f SET o p e r a t i o n : a r g u m e n t
A r g u m e n t N am e: x
New V a l u e : ' (1 2 3 )
D ebug 1> w h e re
A p p l y # 4 : (FIRST-ELEM EN T ( 1 2 3 ) )
D e b u g 1> r e d o

1
L isp >

The argum ent in a stack fram e is changed from an integer to a list, and the
function is reevaluated w ith the correct argum ent.
2.

L i s p > ( d e f u n p l u s - y (x) (+ x y ) )
PLU S-Y
L i s p > ( p l u s - y 4)
E r r o r i n PL U S -Y : S y m b o l h a s n o v a l u e :
C o n tro l S ta ck D ebugger
Eval
#8:
Y
D e b u g 1> down
Eval
# 7 : (+ X Y)
D e b u g 1> down
E val
# 6 : (BLOCK P L Ü S - Y
D e b u g 1 > ( s e t f y 1)

(+ X Y ) )

1
D e b u g 1> w h e r e
Eval
# 6 : (BLOCK P L U S - Y
D e b u g 1> e v a l u a t e
E v a lu a te : y

(+ X Y ) )

1
D e b u g 1> down
A p p l y # 4 : ( P L U S - Y 4)
D eb u g 1> r e d o
5
L isp >

The value of the variable y is set w ith th e s e t f m acro, and th e body of the
function P L U S - Y is reevaluated.

D e b u g g i n g Facilities

4—13

L i s p > ( d e f u n o n e - p l u s (x) (1+ x ) )
ONE-PLUS
L isp > (o n e -p lu s '( 1 2 3 4 ))
E r r o r in 1+: A rgum ent m u st b e a n u m b er:

2 3 4)

C o n tro l S ta ck D ebugger
A p p l y # 8 : ( 1 + (1 2 3 4 ) )
D e b u g 1> s e t f u n c t i o n
F u n c tio n : ' c ar
D e b u g 1> w h e r e
A p p l y # 8 : (C A R .(1 2 3 4 ) )
D e b u g 1> d ow n
E v a l # 7 : ( 1 + X)
D e b u g 1> u p
A p p l y # 8 : (CAR (1 2 3 4 ) )
D e b u g 1> r e d o

1
L isp > ( p p r i n t - d e f i n i t i o n ' o n e - p lu s )
(DEFUN ON E-P LU S (X) ( 1 + X ) )
L is p >

This example shows th a t changing the contents of a stack fram e does not
change the contents of other stack fram es or the function th a t was originally
evaluated.

4.5 Stepper
The stepper is a facility you can use to step interactively through the evaluation
of a form. You can control the stepper w ith stepper commands as it displays and
evaluates each subform of a specified form.
The stepper has a pointer th a t points to the current stack fram e on th e system ’s
control stack. The current stack fram e is the la s t fram e for which the stepper
displayed inform ation.
The stepper prints its command interaction and output to the stream bound to
the * d e b u g - i o * variable.

4.5.1

Invoking the Stepper
You can invoke the stepper by calling the s t e p m acro w ith a form as an argum ent.
The following example invokes the stepper w ith a call to a function nam ed
f a c t o r ia l :

L isp >

(ste p

(fa c to ria l

3 ))

W hen th e stepper is invoked, it displays a line of tex t th a t includes th e first
subform of the specified form and the stepper prom pt. The output is displayed a t
the left m argin of your term inal in th e following format:
# 9 : (FACTORIAL 3 )
S tep >

After th e stepper is invoked, you can use th e stepper commands to control the
operations the stepper perform s and th e w ay the stepper displays output.

4—14

D e b u g g i n g Facilities

4.5.2 Exiting the Stepper
Usually, w hen you use the stepper, you press Return until th e stepper steps
through th e entire specified form. If you w ant to exit from the stepper before it
steps through a form, use the QUIT stepper command. This command causes the
stepper to re tu rn control to the previous command level th a t was active w hen the
stepper was invoked.
S tep >
L isp >

q u it

By default, th e QUIT command displays a confirmation m essage before it causes
th e stepper to exit. For example:
S tep > q u i t
Do y o u r e a l l y

w ant to

e x it

th e

ste p p e r?

If you type YES, the stepper exits and re tu rn s control to the command level th a t
w as active w hen the stepper was invoked.
Do y o u
L isp >

re a lly

w ant to

e x it

th e

ste p p e r?

yes

If you type NO, the stepper prom pts you for another command.
Do y o u
S tep >

re a lly

w ant to

e x it

th e

ste p p er?

You can prevent the stepper from displaying the confirmation m essage by
specifying th e QUIT command w ith a value other th an n i l . For example:
S tep >
L isp >

q u it

The QUIT comm and is described in Section 4.5.4.2.

4.5.3 Stepper Output
Once you invoke th e stepper w ith a specified form, the stepper displays two types
of inform ation as the LISP system evaluates the form:
•

A description of each subform of the specified form

•

A description of th e re tu rn value from each subform

If th e subform being evaluated is a symbol, the stepper displays the descriptions
in a line of text th a t includes the following information:
•

The nested level of th e symbol

•

The control stack fram e num ber th a t indicates w here th e symbol and its
re tu rn value are stored

•

The symbol

•

The re tu rn value

The stepper indicates th e nested level of a symbol w ith indentation. W hen the
num ber of nested levels increases, the indentation increases. A fter m aking the
appropriate indentation, the stepper displays th e control stack fram e num ber, the
symbol, and th e re tu rn value in the following format:
#n: symbol => return-value

D e b u g g i n g Facilities

4—15

If th e subform being evaluated is not a symbol, th e stepper displays th e descrip
tions in a line of text th a t includes the following inform ation:
•

The nested level of the subform

•

The control stack fram e num ber th a t indicates w here th e subform is stored

•

The subform

The stepper indicates the nested level of a subform w ith indentation. W hen the
num ber of nested levels increases, the indentation increases. A fter m aking the
appropriate indentation, the stepper displays th e control stack fram e num ber and
the subform in the following format:
#rr. (subform)

The description of a re tu rn value includes the following inform ation:
•

The nested level of the re tu rn value

•

The control stack fram e num ber th a t indicates w here the re tu rn value is
stored

•

The re tu rn value

The stepper also indicates the nested level of each re tu rn value w ith indentation.
The indentation m atches the indentation of the corresponding call. A fter m aking
the appropriate indentation, the stepper displays the control stack fram e num ber
and the re tu rn value in the following format:
#n => return-value

Suppose you define a function nam ed FACTORIAL.
L isp >

(d efu n

fa c to ria l
(if « = n

(n)
1) 1

(* n

(fa c to ria l

1)))))

FA CTORIAL

The following example illu strates th e form at of the o utput the stepper displays
w hen you invoke it w ith the form ( f a c t o r i a l 3 ) :
L isp > ( s te p ( f a c t o r i a l 3 ))
: # 9 : (FA CTO RIAL 3 )
S tep > s t e p
: : # 1 5 : (BLOCK FA CTORIAL ( I F ( < = N 1) 1 (* N
S tep > s t e p
: : : # 2 2 : ( I F ( < = N 1 ) 1 (* N (FACTORIAL
S tep > s t e p
: : : : # 2 8 : (< = N 1)
S tep > s t e p
: : # 3 3 : N #-> #3
: : : : # 2 8 = > # N IL
: : : : # 2 7 : ( * N (FACTORIAL ( - N 1 ) ) )
S tep > s t e p
: : # 3 2 : N#=>#3
: : # 3 1 : (FACTORIAL ( - N 1 ) )
S tep > s t e p
: : : # 3 6 : ( - N 1)

4—16

D e b u g g i n g Facilities

(FA CTO RIAL

(- N 1 ) ) ) ) )

S tep >

ste p

: : : : : : : #41: N#=>#3
: : : : : :
#36=>#2
: : : : : : #37: (BLOCK FACTORIAL ( I F

S tep >

(<=

over

N 1) 1 (* N (FACTORIAL ( - N 1)))))

: : : : : :
#37=>#2
: : : : : #31=>#2
: : : : #27=>#6
:

# 22=>#6

: : #15=>#6
: #9=>#6
6

Note th a t the fa ctoria l function is a recursive function and, in the preceding
example, has three levels of recursion. The stepper indicates the nested level of
each subform w ith an indentation, indicated w ith a colon followed by a space (: ).
The stepper indicates th e num ber of the stack fram e in which a call is stored with
an integer. The integer is preceded by a num ber sign and followed by a colon
(#n:).
The nested level of each re tu rn value m atches th e indentation of the correspond
ing subform. The stepper indicates the num ber of the control stack fram e onto
which the LISP system pushes the value w ith an integer th a t m atches the stack
fram e num ber of the corresponding subform. The integer is preceded by a num ber
sign and followed by an arrow (#n =>) th a t points to the re tu rn value.

4.5.4 Using Stepper Commands
Stepper commands let you use th e stepper to step through the evaluation
of a LISP expression, form by form. You m u st specify some commands w ith
argum ents. They provide the stepper w ith additional inform ation on how to
execute the command.
You can abbreviate stepper commands to as few characters as you like, äs long as
no am biguity is in the abbreviation.
Each tim e a command is executed, the stepper displays a re tu rn value if the
subform re tu rn s a value, displays the next subform, and prom pts you for an 
other command. E n ter a stepper comm and by typing th e command nam e or
abbreviation and then pressing Return. For example:
S t e p > s t e p [ R etu rn ]
: : : # 2 2 : ( I F (<= N 1)
S tep >

(* N

(FA CTO RIAL

(- N 1) )))

If you press only Return, the LISP system evaluates the subform th e stepper
displays. If th e evaluation re tu rn s a value, the stepper displays the value and the
next subform and th en prom pts you for an o th er command.
S tep >

IR e t u r n |

: : : #22:

(IF

(<= N 1) 1 (* N (FA CTO RIAL (- N 1))))

S tep >

Table 4—4 provides a sum m ary of the stepper comm ands. The stepper commands
are described in Section 4.5.4.2.

D e b u g g i n g Facilities

4-17

Table 4-4: Stepper Commands

4.5.4.1

Command

Description

BACKTRACE

D isplays a backtrace of a form’s evaluation.

DEBUG

Invokes the Debugger.

EVALUATE

E valuates a specified form w ith th e stepper disabled.

FIN ISH

F in ish es the evaluation of the form th a t w as specified in the call to the
STEP macro w ith the stepper disabled.

HELP (or) [T ]

D isplays help tex t about th e stepper commands.

OVER

E valuates the subform in th e current stack fram e w ith the stepper
disabled.

QUIT

Exits th e stepper.

RETURN

Forces th e current stack frame to return a value.

SHOW

D isplays th e subform in the current stack frame.

STEP

E valuates the subform in th e current stack fram e w ith the stepper
enabled.

E valuates subforms w ith th e stepper disabled until th e stepper gets
back to a subform th a t contains the subform in th e current stack frame.

Arguments
Stepper comm and argum ents modify the operations the stepper commands
perform. Some stepper commands require an argum ent, and some commands
accept optional argum ents. The argum ents you can specify w ith th e stepper
comm ands are:
•

Integer

•

Form

•

Stepper command
NOTE
O n ly p a r e n t h e s iz e d e x p r e s s io n s a n d a r g u m e n ts to e v a lu a t e (th a t is,
a r g u m e n ts sp e c ifie d w it h t h e E V A L U A T E co m m a n d ) a re e v a lu a te d .

E n te r an argum ent after the command it modifies and press Return. For example:
S te p >

e v alu ate

(<= n

1 ) | R etu rn |

If an arg u m en t is required and you om it it, the stepper prom pts you for the
argum ent. For example:
S t e p > e v a l u a t e | R etu rn ]
E v a l u a t e : (<= N 1)

The stepper does not prom pt for argum ents if you specify them in the command
fine.

4-18

D e b u g g i n g Facilities

4.5.4.2

Stepper Commands
The stepper provides commands th a t let you control how it steps through a form’s
evaluation.
Help Command
HELP
m

The HELP command displays help text about the stepper commands.
You can specify this command w ith one argum ent, the nam e of th e
stepper command about which you w ant help text. If you specify the
HELP command w ithout an argum ent, the stepper displays a list of
the stepper commands. You can abbreviate th is command by u sing a
question m ark (?).

Evaluation Command
You can evaluate expressions w hile you are in the stepper. If you w ant
th e LISP system to evaluate a parenthesized form, you can specify
th e form and then press Return. If you w an t the system to evaluate a
symbol, you m u st use the EVALUATE command.

EVALUATE

The EVALUATE command causes the LISP system to explicitly eval
uate a specified form. If you do not specify th e command w ith an
argum ent, you are prompted for one. The argum ent m ust be the form
you w ant th e system to evaluate. The system evaluates the form in th e
lexical environm ent o f the form currently being stepped.

Debugger Command
DEBUG

The D EBU G command invokes th e D ebugger at the control stack frame
th a t stores the call to th e current form. W hen the Debugger returns
control to th e stepper, th e stepper prompts you for a command.

Display Command
SHOW

The SHOW com m and displays th e subform in the current stack frame.

Exiting Command
QUIT

The QUIT command causes the stepper to exit and return control to
th e command level th a t w as active w hen the stepper w as invoked. You
can specify this command w ith an optional argum ent. If you specify
N IL , th e stepper displays a confirmation m essage before it causes the
stepper to exit. If you respond to the m essage by typing YES, the
stepper exits. If you specify a value other than N IL , the stepper does
not display a m essage. The default value for th e optional argum ent is
N IL.

Backtrace Command
BACKTBACE

The BACKTRACE command lists the subforms of th e form being
stepped through. You can specify th e command w ith an optional
integer, w hich determ ines th e num ber of subforms th a t are to be listed.
The stepper works its w ay back th e specified num ber of subforms and
then lists th e subforms in th e order in w hich they were invoked. If you
do not specify th e argum ent, th e stepper lists all th e subforms the LISP
system is evaluating.

D e b u g g i n g Facilities

4—19

Commands That Continue Evaluation of the Form Being Stepped Through
Several stepper com m ands continue the evaluation o f th e form be
ing stepped through, each command continuing the evaluation in a
different way.

FINISH

The FIN ISH command evaluates th e form you specified in th e call
to the STEP macro. You can specify th e command w ith an optional
argum ent th a t is a form. W hen th e stepper executes th e command,
the LISP system evaluates th e form. I f th e evaluation returns a value
other than N I L , th e stepper steps through th e evaluation of the form
u ntil it reaches th e end of the evaluation. I f th e evaluation returns
N I L , th e LISP system disables th e stepper and then evaluates th e form
you specified in the call to the STEP macro. The default value for the
optional argum ent is N I L .

OVER

The OVER com m and causes th e LISP system to evaluate the subform
in the current stack fram e w ith the stepper disabled.

RETURN

The RETURN command causes th e LISP system to evaluate th e
RETURN com m and’s argum ent and causes th e stepper to force the
current stack fram e to return the valu es returned by th e evaluation. If
you do not specify th e command w ith an argum ent, you are prompted
for one. The argum ent m u st be a form. W hen you execute the com
m and, th e LISP system evaluates th e form. W hen th e evaluation is
com plete, th e current stack fram e returns the valu es returned by the
evaluated form.

STEP

The STEP command causes th e LISP system to evaluate th e subform
in th e current stack fram e w ith th e stepper enabled. This command is
equivalent to pressin g Return.

The U P command causes th e LISP system to evaluate subforms w ith
th e stepper disabled until control returns to th e subform th a t contains
th e subform in th e current stack fram e one level deep. You cannot
specify the command w ith an optional argum ent.

4.5.5 Using Stepper Variables
The stepper facility h a s two special variables th a t are useful debugging tools
w h e n in th e s te p p e r: * s t e p - foem * a n d * s t e p - environment *.

4.5.5.1

‘
STEP-FORM*
The *s t e p - f o r m * variable is bound to the form being evaluated while stepping.
For example, while executing th e form
(step (function-z argl arg2))

th e value of * s t e p - f o r m * is th e list ( f u n c t i o n - z a r g l a r g 2 ). W hen not stepping,
th e value is undefined.

4—20

D e b u g g i n g Facilities

4.5.5.2

‘
STEP-ENVIRONMENT’
The * s t e p - e n v i r o n m e n t * variable is bound to th e lexical environm ent in which
* s t e p - f o r m * is being evaluated. By default in the stepper, the lexical environ
m en t is used if you use th e EVALUATE command. See C om m on L IS P : The
L a n g u a g e for a description of dynam ic and lexical environm ent variables.
Some Common LISP functions (for example, e v a l h o o k , a p p l y h o o k , and
take an optional environm ent argum ent. The value bound to the
* s t e p - e n v i r o n m e n t * variable can be passed as an environm ent to these functions
to allow evaluation of form s in the context of th e stepped form.

m acroexpand)

4.5.5.3

Example Use of Stepper Variables
The following example shows how to use the * s t e p - f o r m * and » s t e p special variables.

e n v ir o n m e n t *

L isp > ( s e t f x " to p l e v e l v a lu e o f x")
" to p le v e l v a lu e o f x"
L i s p > ( d e f u n f i b o n a c c i (x)
( i f « x 3) 1
(+ ( f i b o n a c c i ( - x 1 ) ) ( f i b o n a c c i ( - x 2 ) ) ) ) )
F IB O N A C C I
L isp > ( s te p ( f ib o n a c c i 5 ))
# 4 : (F IB O N A C C I 5)
S tep > s t e p
: # 1 0 : (BLOCK FIB O N A C C I ( I F (< X 3 ) 1
( + ( F IB O N A C C I ( - X 1 ) )
( F IB O N A C C I ( - X 2 ) ) ) ) )
S te p > s te p
: : # 1 4 : ( I F (< X 3 ) 1 (+ ( F IB O N A C C I ( - X 1 ) )
(FIBO NACCI ( - X 2 ) ) ) )
S te p > -step
: : : # 1 8 : « X 3)
S tep > s t e p
: # 2 2 : X => 5
# 1 8 => NIL
# 1 7 : ( + ( F IB O N A C C I ( - X 1 ) )
( F IB O N A C C I ( - X 2 ) ) )
S tep > s t e p
: # 2 1 : ( F IB O N A C C I ( - X 1 ) )
S tep > s t e p
: : # 2 5 : ( - X 1)
S tep > s te p
: : : #29: X => 5
: : # 2 5 => 4
: : # 2 7 : (BLOCK F IB O N A C C I ( I F ( < X 3 ) 1
(+ ( F IB O N A C C I ( - X 1 ) )
(F IB O N A C C I ( - X 2 ) ) ) ) )
S tep > s t e p
: : : # 3 1 : (IF « X 3) 1
( + ( F IB O N A C C I ( - X 1 ) )
( F IB O N A C C I ( - X 2 ) ) ) )
S tep > s t e p
: : : : # 3 5 : (< X 3)
S tep > s t e p
: : : : : # 3 9 : X => 4
: : : : # 3 5 => N IL
: : : : # 3 4 : ( + ( F IB O N A C C I ( - X 1 ) )
( F IB O N A C C I ( - X 2 ) ) )
S tep > s t e p
: : : : : : : :
# 3 8 : ( F IB O N A C C I
S tep > e v a l * ste p -fo rm *
( F IB O N A C C I ( - X 1 ) )

X 1))

D e b u g g i n g Facilities

4-21

S te p >
: : :
S tep >
: : :
: : :
: : :

ste p
: : : : : :
ste p
: : : : : :
: : : : : :
: : : : : :

#42:

( - X 1)

# 4 6 : X => 4
#42 => 3
# 4 4 : (BLOCK F IB O N A C C I
( I F (< X 3 ) 1
(+ ( F IB O N A C C I ( - X 1 ) )
( F IB O N A C C I ( - X 2 ) ) ) ) )
S te p > e v a l * ste p -£ o rm *
(BLOCK F IB O N A C C I
( I F « X 3 ) 1 (+ ( F IB O N A C C I ( - X 1 ) ) ( F IB O N A C C I ( - X 2 ) ) ) ) )
S te p > s t e p
: : : : : : : : : :
# 4 8 : ( I F (< X 3 ) 1
(+ (F IB O N A C C I ( - X 1 ) )
(F IB O N A C C I ( - X 2 ) ) ) )
S te p > s t e p
: : : : : : : : : : :
# 5 2 : « X 3)
S te p > s t e p
: : : : : : : : : : : :
# 5 6 : X => 3
: : : : : : : : : : :
# 5 2 = > NI L
: : : : : : : : : : :
# 5 1 : (+ ( F IB O N A C C I ( - X 1 ) )
(F IB O N A C C I ( - X 2 ) ) )
S tep > s t e p
: : : : : : : : : : : :
# 5 5 : (F IB O N A C C I ( - X 1 ) )
S tep > e v a l x

3
S t e p > ( e v a l ' x)
" to p l e v e l v a lu e o f x"
S tep > e v a l * s te p -fo rm *
(F IB O N A C C I ( - X 1 ) )
S tep > (e v a lh o o k 'x n i l n i l n i l )
" to p l e v e l v a lu e o f x"
S t e p > ( e v a l h o o k ' x n i l n i l * s t e p - e n v i r o n m e n t *)
3
S tep > (e v a lh o o k (c a d r * s te p -fo rm * ) n i l n i l *s te p -e n v iro n m e n t* )

2
S te p >
: : :
S tep >
: : :
: : :
: : :

S te p >
5

ste p
: : :
ste p
: : :
: : :
: : :

:
:
:

#59:
:

X 1)

# 6 3 : X => 3
#59 => 2
# 6 1 : (F IB O N A C C I
( I F (< X 3) 1
( + ( F IB O N A C C I
( F IB O N A C C I

(- X 1))
( - X 2) ) ) ) )

fin is h

This exam ple shows th a t the * s t e p - f o r m * special variable is bound to the
form being evaluated while stepping. The example also shows th a t the * s t e p e n v i r o n m e n t * special variable is bound to the lexical environm ent in which the
currently stepped form is being evaluated.
The call to e v a l h o o k evaluates th e form (- x l) in the lexical environm ent of
the stepper; th a t is, w ith the local binding o f x. A call to e v a l h o o k w ith a null
environm ent specified shows th a t d’s value in the null lexical environm ent differs
from th a t in the stepper. The EVAL comm and uses th e * s t e p - e n v i r o n m e n t *
environm ent; the e v a l function uses the null lexical environm ent.

4-22

D e b u g g i n g Facilities

4.5.6 Sample Stepper S essio n s
1.

L i s p > ( d e f u n f i r s t - e l e m e n t (x) ( c a r x ) )
FIRST-ELEM EN T
L isp > ( s e t f m y - l i s t ' ( f i r s t se c o n d t h i r d ) )
( F I R S T SECOND T HIRD)
L isp > ( s te p ( f i r s t -e le m e n t m y - l i s t ) )
# 1 0 : (F I R S T - E L E M E N T M Y - L I S T )
S tep > s te p
: # 1 5 : M Y - L I S T = > ( F I R S T SECOND THIRD)
: # 1 7 : (BLOCK F I R S T - E L E M E N T (CAR X ) )
S tep > s te p
: : # 2 2 : (CAR X)
S t e p > e v a l u a t e ( c a r x)
FIR ST
S tep > f i n i s h
FIR ST
L isp >

L i s p > ( d e f u n p l u s - y ( x ) (+ x y ) )
PLD S-Y
L i s p > ( s e t f y 5)
5
L isp > ( s te p ( p lu s - y 10))
# 1 0 : (PLU S-Y 1 0 )
S te p > s te p
: # 1 7 : (BLOCK P L U S - Y ( + X Y ) )
S tep > e v a lu a te
E v a l u a t e : (+ x y )
15
S tep > s t e p
: : # 2 2 : ( + X Y)
S tep > b a c k tr a c e
(+ X Y)
(BLOCK P L U S - Y (+ X Y ) )
(PL U S-Y 1 0 )
S t e p > show
<+ X Y)

S te p > o v e r
: : # 2 2 = > 15
: # 1 7 = > 15
# 1 0 => 15
15
L isp >

D e b u g g i n g Facilities

4—23

L i s p > ( d e f u n a d d i t i o n ( x ) (+ x y ) )
A D DIT ION
L i s p > ( s e t f y 5)
5
L isp > ( s te p ( a d d it i o n 4 ))
# 1 0 : (A D D IT IO N 4 )
S tep > s te p
: # 1 7 : (BLOCK A D D IT IO N ( + X Y ) )
S tep > s te p
: : # 2 2 : ( + X Y)
S tep > b a c k t r a c e
(+ X Y)
(BLOCK A D D IT IO N (+ X Y ) )
(A D D IT IO N 4)
S tep > e v a lu a te
E v a l u a t e : (+ x y )
9
S t e p > STEP
: : : # 2 7 : X=>#4
: : : # 2 7 : Y=>#5
: : #22=>#9
: #17=>#9
#10=>#9
9
L isp >

4.6 Tracer
The VAX LISP tracer is a m acro you can use to follow a program ’s evaluation.
The tracer informs you when a function or m acro is called during a program ’s
evaluation by printing inform ation about each call and re tu rn value to th e stream
bound to the *t r a c e - o u t p u t * variable. To use the tracer, you m u st enable it for
each function and m acro you w ant traced.
NOTE
You cannot trace special forms.

4.6.1

Enabling the Tracer
You can enable th e tra c er for one or more functions and/or m acros by specifying
th e function and m acro nam es as argum ents in a call to the t r a c e macro. For
example:
L isp > ( t r a c e f a c t o r i a l a d d i t i o n
(FA CTO RIAL A D D IT IO N COUNTER)

c o u n te r)

The trace m acro re tu rn s a list of the functions and m acros th a t are to be traced.
If you call the t r a c e m acro w ithout an argum ent, it re tu rn s a list of the functions
and m acros for which tracing is enabled. For example:
L isp > ( tr a c e )
(FACTORIAL A D D IT IO N COUNTER)

A description of the t r a c e m acro is provided in the VAX' L I S P /V M S O bject
R eferen ce M a n u a l.

4 -2 4

D e b u g g i n g Facilities

4.6.2 Disabling the Tracer
Tb disable th e tracer for a function or macro, specify the nam e of the function
or m acro in a call to th e untrace macro. It re tu rn s a list of the functions and
m acros for which tracing has ju s t been disabled. For example:
L is p >

(untrace factorial addition counter)

(FA CTO R IA L A D D IT IO N

COUNTER)

You can disable tracing for all the functions for which tracing is enabled by calling
the untrace m acro w ithout a n argum ent.
The untrace m acro is described in C om m on L IS P : The L an g u a g e.

4.6.3 Tracer Output
Once you enable th e tracer for a function or macro, th e tra c er displays two types
of inform ation each tim e th a t function or m acro is called during a program ’s
evaluation:
•

A description of each call to th e specified function or macro

•

A description of each re tu rn value from the specified function or m acro

The description of a call to a function or m acro consists of a line of tex t th a t
includes th e following inform ation:
•

The nested level of th e call

•

The control stack fram e num ber th a t indicates w here th e call is stored

•

The nam e and argum ents of th e function associated w ith the function or
m acro th a t is called

The tracer indicates the nested level of a call w ith indentation. W hen the
num ber of nested levels increases, the indentation increases. A fter m aking the
appropriate indentation, th e tra c er displays th e control stack fram e num ber, the
function nam e, and the argum ents in the following form at:
#n: (function-name arguments)

The tracer also displays a line of tex t for the re tu rn value of each evaluation. The
lin e o f t e x t t h e tr a c e r d is p la y s for e a c h v a lu e in c lu d e s t h e fo llo w in g in fo r m a tio n :

•

The nested level of th e re tu rn value

•

The control stack fram e num ber th a t indicates w here the re tu rn value is
stored

•

The re tu rn value

The tracer indicates th e nested level of each re tu rn value w ith indentation. The
indentation m atches the indentation of the corresponding call. A fter m aking the
indentation, th e tra c er displays th e control stack fram e num ber and the re tu rn
value in the following form at:
#n => return-value

Suppose you define a function nam ed factorial .
Lisp>

(d efu n

fa c to ria l
( i f (< = n

(n)
1) 1

(* n

(fa c to ria l

1)))))

FACTORIAL

D e b u g g i n g Facilities

4-25

The following exam ple illu strates the form at of the output the tracer displays
w hen the function f a c t o r i a l is called w ith the argum ent 3:
L i s p > (factorial 3)
#11: (FACTORIAL 3)
. #27: (FACTORIAL 2)

. . #43: (FACTORIAL 1)
. . #43 = > 1
. #27 = > 2

#11

The f a c t o r i a l function is a recursive one and, in the case of th e preceding
example, h a s three levels of recursion. The tra c er indicates the nested level of
each call w ith indentation. Each level of indentation is indicated w ith a period
followed by a space (. ). The tracer indicates the num ber of th e stack fram e in
which a call is stored w ith an integer. The integer is preceded w ith a num ber
sign and followed by a colon (#«:).
The nested level of each re tu rn value m atches th e indentation of the correspond
ing call. The tracer indicates the num ber of th e control stack fram e onto which
th e LISP system pushes th e value w ith an integer. This integer m atches the
stack fram e num ber of the corresponding call and is preceded w ith a num ber sign
and followed by an arrow (#n =>) th a t points to the re tu rn value.

4.6.4 Tracer Options
You can modify the output of the tracer by specifying options in th e call to the
t r a c e macro. Each option consists of a keyword-value pair. The form at in which
to specify keyword-value pairs for the t r a c e m acro is:
(TRACE (function-name keyword-1 value-1 keyword-2 value-2 ...))

You can also specify options for a list of functions and/or macros. The t r a c e
m acro form at in which to specify the sam e options for a list of functions and
m acros is:
(TRACE ((name-1 name-2 ...) keyword-1 value-1 keyword-2 value-2 ...))

NOTE
Form s the system evaluates ju s t before or ju s t after a call to a function
or m acro for which tracing is enabled are evaluated in a null lexical
environm ent. For inform ation on lexical environm ents, see C om m on
L IS P : The L a n g u a g e .

The keywords you can use to specify options are:
DEBUG-IF

Invoke the D ebugger

PRE-DEBUG-IF
POST-DEBUG-IF

4-26

PRI N T
PRE-PRINT
POST-PRINT

Add inform ation to tracer output

STEP — IF

Invokes the stepper

SUPPRESS-IF

Rem oves inform ation from tracer output

DURING

D eterm ines w hen a function or macro is traced

Debugging Facilities

4.6.4.1

Invoking the D ebu gger

You can cause the tra c e r to invoke th e Debugger by specifying th e :DEBUG-IF,
:p r e - d e b d g - i f , or : P O S T - D E B U G - i f keyword. These keywords m u st be specified
w ith a form. The LISP system evaluates the form before, after, or before and
after each call to the function or m acro being traced. If the form re tu rn s a value
other th an n i l , th e tra c e r invokes the Debugger after each evaluation.
4.6.4.2

Adding Information to Tracer Output
You can add inform ation to tracer output by specifying th e : p r i n t , :p r e - p r i n t , or
:p o s t - p r i n t keyword. You m u st specify these keywords w ith a list of forms. The
LISP system evaluates each form in the list and the tra c er displays th eir re tu rn
values before, after, or before and after each call to the function or m acro being
traced. The tracer displays the values one per line and indents them to m atch
other tra c er output. If the forms to be evaluated cause an error, the Debugger is
invoked.

4.6.4.3

Invoking the Stepper
You can cause the tracer to invoke th e stepper by specifying the : s t e p - i f key
word. You m u st specify this keyword w ith a form. The LISP system evaluates the
form before each call to the function or m acro being traced. If the form re tu rn s a
value other th a n n i l , the tra c er invokes th e stepper.

4.6.4.4

Removing Information from Tracer Output
You can remove inform ation from tracer o utput by specifying the :SUPP R E S S - i f
keyword. You m u st specify this keyword w ith a form. The LISP system evaluates
th e form before each call to the function or m acro being traced. If th e form
re tu rn s a value other th a n n i l , the tracer does not display th e argum ents and
the re tu rn value of th e function or m acro being traced.

4.6.4.5

Defining When a Function or Macro is Traced
You can define w hen a function or macro, for which tracing is enabled, is to be
traced by specifying the : D U R I N G keyword. You m u st specify this keyword w ith a
function or m acro nam e or a list of function and/or m acro nam es. The functions
a n d m a c r o s for w h ic h the tr a c e r is enabled are traced only w hen they are called
(directly or indirectly) from w ithin one of the functions or m acros whose nam es
are specified w ith the keyword.

4.6.5

Tracer Variables
You can use two special variables w ith the t r a c e macro: * t r a c e - c a l l * and
* t r a c e - v a l u e s *. These are helpful debugging tools. W ith these variables and the
preceding tracer options, you can control w hen to debug or step depending on the
argum ents to a function or the re tu rn values from a function.

Debugging Facilities

4—27

4.6.5.1

*TRACE-CALL*
The *trace - call * variable is bound to th e function or macro call being traced.
The following exam ple shows how to use th e variable:
Lisp>

(defun fibon a c c i (x)
(if (< x 3) 1
(+ (fibonacci (- x 1))
FIBON A C C I
Lisp>

(trace

(fibonacci
:pre-debug-if (<
:suppress-if t ) )

(fibonacci

(- x 2)))))

(second *trace-call*)

(FIBONACCI)
L i s p > (fibonacci 5)
Control Stack D e b u g g e r
A p p l y #30: (DEBUG)
D e b u g 1> down
Eva l
#27: (FIBONACCI (- X 2))
D e b u g 1> down
Eva l
#26: (+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2)))
D e b u g 1> down
Eva l #25: (IF (< X 3) 1
(+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2))))
D e b u g 1> down
Eva l #24: (BLOCK FIBON A C C I
(IF (< X 3) 1
(+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2 )))))
D e b u g 1> down
A p p l y #22: (FIBONACCI 3)
D e b u g 1> (cadr ( d e b u g - c a l l ) )
3
D e b u g 1> continue
Control Stack D e b u g g e r
A p p l y #22: (DEBUG)
D e b u g 1> continue
5

4.6.5.2

•

In this example, Fibonacci is first defined.

•

Then, the trace m a cr o is c a lle d for Fibonacci, trace is specified to invoke the
Debugger if the first argum ent to Fibonacci (the function call being traced)
is less th an 2. Since the pre-debug- if option is specified, the Debugger is
invoked before the call to Fibonacci. A s the :Suppress- if option has a value
of T, calls to Fibonacci do not cause any trace output.

•

The DOWN command moves the pointer down th e control stack.

•

The debug-call function re tu rn s a list representing th e current debug fram e
function call. In th is case, the cadr of the list is 3. This accesses the first
argum ent to the function in the c u rren t stack fram e.

•

Finally, the CONTINUE command continues th e evaluation of Fibonacci.

*TRACE-VALUES*
The *trace-values* variable is bound to the list of values retu rn ed by a traced
function. Consequently, the variable can be used only w ith the :POST- options to
the trace macro. Before being bound to th e re tu rn values, th e variable retu rn s
n il . The following exam ple shows how to use th e variable:

4-28

Debugging Facilities

Lisp>

(trace

(fibonacci

:p o s t - d e b u g - i f (> (first *trace-values*)
(FIBONACCI)
L i s p > (fibonacci 5)
#5: (FIBONACCI 5)
. #13: (FIBONACCI 4)
. • #21: (FIBONACCI 3)
. . . #29:
(FIBONACCI 2)
. . . #29 = > 1
. . . #29:
(FIBONACCI 1)
. . . #29=> 1
. . # 21=> 2
. . #21: (FIBONACCI 2)
. . #21=> 1
Cont r o l Sta c k D e b u g g e r
A p p l y #14 : (DEBUG)
D e b u g 1> b a c k t r a c e
—
B a c k t r a c e start —
A p p l y #14 : (DEBUG)
Eval
#11 : (FIBONACCI (- X 1))
Eval
#10 : (+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2)))
Ev a l
#9: (IF « X 3) 1
(+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2))))
Ev a l
#8: (BLOCK F I B O N A C C I
(IF (< X 3) 1
(+ (FIBONACCI (- X 1))
(FIBONACCI (- X 2 )))))
A p p l y #6: (FIBONACCI 5)
Eval
#3: (FIBONACCI 5)
A p p l y #1: (EVAL (FIBONACCI 5))
-- B a c k t r a c e en d —
A p p l y #14 : (DEBUG)
D e b u g 1> continue
. #13 = > 3
. #13: (FIBONACCI 3)
. . #21: (FIBONACCI 2)
.

# 21=>

. . #21:

2)))

1
(FIBONACCI

. . #21=> 1
. #13=> 2
Cont r o l S t a c k D e b u g g e r
A p p l y #6: (DEBUG)
D e b u g 1> conti n u e
#5=> 5
5

is called for F i b o n a c c i (the sam e function as in the previous example) to
s ta rt the Debugger if the value retu rn ed exceeds 2. The value retu rn ed exceeds 2
twice—once w hen it re tu rn s 3 and a t the end w hen it re tu rn s 5.
trace

4.7 The Editor
The VAX LISP E ditor is a powerful, extensible editor th a t lets you create and edit
LISP program s. Once you have located an error and you know which function
in your program is causing the error, you can use the E ditor to correct th e error.
Use the ED function to invoke th e Editor. For a complete description of the ED
function, th e VAX LISP Editor, and instructions on how to use the Editor, see the
V A X L I S P /V M S E d ito r P ro g ra m m in g G u ide.

Debugging Facilities

4—29

Part II
Using VAX LISP Facilities on the
DECwindows Interface

Chapter 5

The DECwindows Interface to VAX LISP
You can ru n VAX LISP on a VAX w orkstation as a DECwindows application. W ith
the DECwindows interface to LISP, you choose commonly used LISP operations
and utilities from pull-down m enus. M ost LISP utilities rim in sep arate windows,
so th a t utility commands and m essages are separate from interactions w ith LISP.
All VAX LISP utilities th a t are provided w ith the term inal interface are also
provided w ith the DECwindows interface. These utilities are:
•

The Listener, which ru n s the r e a d -e v a l - p r i n t loop, accepts LISP forms,
evaluates them , and prints m essages as a resu lt of those forms

•

The Editor, which lets you w rite LISP source code w ithin the LISP
environm ent, load th a t code into LISP, and ru n it

•

The Debugger, which helps you determ ine w here program m ing errors occur

In addition to these utilities, the DECwindows interface provides an Inspector,
which lets you exam ine and modify static LISP objects. This u tility is not
available w ith the term inal interface to LISP.
This chapter takes you through a sam ple program m ing session w ith VAX LISP. It
shows you how to do the following:
•

Load source files and enter LISP forms w ith the L istener

•

Exam ine LISP objects w ith the Inspector

•

Define new functions w ith the E ditor

•

Locate program m ing errors w ith the Debugger

S ubsequent chapters describe each of these utilities in detail.
Throughout the sample session, this chapter uses a simple program to show
each stage of program development. The sam ple program defines LISP objects to
rep resen t ingredients used in recipes. A LISP function calculates th e num ber of
calories per serving for each ingredient or recipe.
W hen VAX LISP is installed, a num ber of sam ple program s are placed in the
directory defined by the logical nam e LISP$EXAMPLES. Among these program s
is a file called RECIPE.LSP, which contains the sam ple program . To try the
exam ples in this chapter, copy th e source file from the LISP$EXAM PLES
directory to your working directory. Figure 5—1 shows the FileView-Copy dialog
box as it would appear when using File View to copy the RECIPE.LSP file from
LISP$EXAMPLES to a working directory called DISK$:[USER],

The DECwindows Interface to VAX LISP

5-1

Figure 5-1: Copying a Sample Source File

FileView - Copy
From:

LISP$EXAMPLES:RECIPE.LSP

To:

DISK $: [USER]

□ Show Log
□ Request Confirmation

□ Concatenate Input Files
□ Replace Existing Files
□ Hide This Dialog
Cancel
MLO-002855

5.1 Invoking VAX LISP
T here are a num ber of ways to invoke VAX LISP:

5-2

•

From a term inal or DECterm window, use the sam e command line you would
use on a regular term inal.

From a FileView window, select DCL Command in the U tilities m enu.
You can then use the sam e command line you would use from an ordinary
term inal or DECterm window.

The DECwindows Interface to VAX LISP

Figure 5—2 shows a stan d ard FileView window th a t you can use to invoke VAX
LISP. See your V M S D E C w in d o w s U ser’s G u ide for inform ation on using FileView
windows. For more inform ation on invoking th e DECwindows interface to VAX
LISP, see C hapter 6.
Figure 5-2: Invoking LISP

FileView - Task Output
DCL Command
-Ö-

$ lisp

StopTaskJ

□

Hold

Dismiss
MLO-002856

The DECwindows Interface to VAX LISP

5—3

5.2 Using the Listener
The L istener is the first utility th a t appears. It occupies its own window, shown
in Figure 5—3.
Figure 5-3:

Listener Window

EÜ1 LISP L istener
File

Edit

Operations

Help

VAX LISP [TM] V3.0
© D i g i t a l Equipment Corporation, 1989.
All Rights Reserved.
Lisp>

MLO-002857

5-4

The DECwindows Interface to VAX LISP

You can e n te r any LISP form a t the Lisp> prom pt. For example, LISP can
evaluate an arithm etic expression such as th e one shown in Figure 5—4.
Figure 5-4:

Evaluating a LISP Form

LISP Listener
File

Edit

Operations

Help

VAX LISP[TM] V3.0
© D i g i t a l Equipment Corporation, 1989.
All Rights Reserved.
L is p >

2
L is p >

< JC

(+ 1 1)

30
MLO-002858

T h e D E C w in d o w s Interlace to VAX LISP

5-5

Commonly used LISP operations are available through pull-down m enus a t the
top of th e L istener window. For example, to load source files, pull down the
File m enu, then choose Load. The Load m enu choice produces a list of LISP
source files displayed in a window called a “file selection dialog box,” shown in
Figure 5—5.
Figure 5-5:

Loading a LISP Source File

File Filter
*.LSP

Files in DISK$:[USER]
Filter

R]HELLOWORLD.LSP
R]RECIPELLSP

<0c

3C>

Selection
DISK$:[USER]RECIPE. LSP
MLO-002859

To select the source file for the sam ple program , scroll through the list of files
u n til th e pointer points to RECIPE.LSP. Click MB1 to highlight th e file nam e.
RECIPE.LSP appears as the selection a t the bottom of the window. Next, you can
e ith e r click on the file nam e again or position the pointer over th e OK button and
click M B l . The file selection dialog box disappears, LISP loads the source file, and
th e L istener window reappears.
For m ore inform ation on the Listener, see C hapter 7.

5.3 Using the Inspector
The sam ple program calculates the num ber of calories for certain foods. Foods
like m ilk, bread, butter, and eggs are “ingredients” th a t can be combined into
“recipes.” The sam ple program uses symbols to rep re sen t ingredients and
stru ctu res to represent recipes. You can exam ine th is d a ta w ith the Inspector.

5-6

The DECwindows Interface to VAX LISP

For example, you can invoke the Inspector from the L istener window w ith the
LISP i n s p e c t function and inspect the c o o k i e s stru ctu re defined in RECIPE.LSP:
L isp >

(in sp e ct

c o o k ie s)

W hen LISP evaluates th is form, it opens an Inspector window and an Inspector
H istory window. The Inspector window, in Figure 5-6, shows th a t the stru ctu re
has th e slots i NAME, : i n g r e d i e n t s , : a m o u n t , and : s e r v i n g s and it shows the
values assigned to those slots for the c o o k i e s recipe.
Figure 5-6:

Inspecting a Structure

71
P\
He

| Inspect
Commands

Edit

The Structure:

NAME
INGREDIENTS
AMOUNT
SERVINGS

< 01

......”

#S(RECIPE :NAME

"C O

"cookies"
(SUGAR MILK BUTT

(2 0.25 1)
36

t =

—JU>
MLO-002860

The DEGwindows Interlace to VAX LISP

You can also use the m ouse to select objects th a t you w ant to inspect. For
example, if you click MBi anyw here w ithin the list ( s u g a r m i l k b u t t e r ) , the
Inspector highlights the list. You can inspect th a t list by choosing Inspect from
th e Com m ands m enu a t the top of the window, as shown in Figure 5-7.
Figure 5-7:

C hoosing the Inspect Menu Item

inspect

| Commands Edit
Heiip
ZT---------------------ire:

#S (RECIPE :NAME "co

"cookies"
(2 0.25 1)
36

<oc
MLO-002861

W hen you choose Inspect from the m enu, the Inspector opens a second window
and displays inform ation about the list, as shown in Figure 5—8.
Figure 5-8:

inspecting a List

| Inspect
Commands

|H |0
Edit

Help
&

The List: (SUGAR MILK BUTTER)
LIST ELT #0
LIST ELT #1
LIST ELT #2
LIST CDR

SUGAR
MILK
BUTTER
NIL

o i

:...- t = _

—

M L O -002862

5-8 The DECwindows Interface to VAX LISP

By default, the Inspector can open up to five Inspect windows a t a tim e. W hen
you inspect more th a n five objects, the Inspector reuses those windows. If you
do not w a n t to reuse a window, so th a t the object in it will rem ain visible, you
can lock it. The Inspector will create more unlocked windows until it reaches its
m axim um of five. You m ay change the m axim um num ber of unlocked windows
th a t the Inspector can open. Appendix B describes how you can customize the
Inspector and the other DECwindows utilities.
In addition to the Inspect windows, the Inspector keeps a running history of the
objects th a t you have inspected. This inform ation is displayed in the Inspector
H istory window. Figure 5-9 shows the H istory window th a t the Inspector
displays for th e objects inspected so far. The asterisk before the object nam e
indicates th a t the window is currently displayed and unlocked.
Figure 5-9:

Inspector History Window

W 1LISP Inspector History
Commands

Edit

Help
A

.m.

*
*

#S(RECIPE :NAME "cookies" : INGRE
(SUGAR MILK BUTTER)

<51

i------------

---- IL>
M L O-002863

For m ore inform ation on the Inspector, see C hapter 9.

T h e D E C w in d o w s Interface to VAX LISP

5-9

5.4 Running a Sample Function
The sam ple program contains a function called c a l o r i e s , which calculates the
num ber of calories per u n it of m easure for an ingredient or per serving for a
recipe. Figure 5-10 shows w hat th e c a l o r i e s function re tu rn s for th e symbol
s u g a r and th e recipe stru ctu re c o o k i e s .
Figure 5-10:

Running a LISP Function

LISP Listener

0 El

File

Edit

Help

L is p >
375
L is p >
27
L is p >

(calories

Operations
'

sugar)

(calories cookies)

MLO—002864

The sam ple program is only the beginning of w hat could be a m enu-planning
application. It contains a small am ount of inform ation about ingredients and
recipes and the form ula for calculating calories. The sections th a t follow describe
how to add a pretty-printing function to this program .

5.5 Using the Editor
VAX LISP h as a built-in editor for creating source files. A lthough you can
create LISP source files with any editor you like, the LISP E ditor contains
language-specific features th a t other editors do not have.

5-10

T h e D E C w in d o w s Interface to VAX LISP

The Tab key indents lines appropriately, according to the cursor’s position w ithin a
LISP form, as follows:
•

N ested LISP forms a re indented below th e ir containing form.

•

Form s a t the sam e level of nesting are aligned.

•

Function argum ents on separate lines a re aligned below each other and
indented below th eir containing form.

The E ditor is also sensitive to parentheses. W henever you type a closing
parenthesis, it highlights the corresponding opening parenthesis. If the opening
parenthesis h as scrolled off th e window, the E ditor displays it in the command
a re a a t the bottom of th e screen.
You can invoke the E ditor from the L i s p > prom pt w ith the ED function, giving the
nam e of the file or function you w ant to edit. This is the only w ay to invoke the
E ditor when using th e term inal interface to VAX LISP.
The DECwindows interface also lets you invoke the E ditor as a m enu choice
from either the File or the O perations m enu. The File m enu item , shown in
Figure 5—11, is sim ilar to Load. I t brings up a file selection box th a t allows
you to specify a file to edit. To add a function definition to RECIPE.LSP, choose
R ECIPE.LSP in th e file selection dialog box.
Figure 5-11: C hoosing the ED Function

Edit

Operations

Load...
Compile File.,
Ed...

a a
Hel 3

sugar)

cookies)

Suspend As.
Dribble
Save As...
Exit

T=r
<0(

»0
MLO-002865

The DECwindows Interface to VAX LISP 5-11

Choosing the ED item from the O perations m enu is sim ilar to ru n n in g the ed
function. Both let you edit the currently selected object.
A fter you invoke the Editor, it places the file or function in a n editing buffer, as
shown in Figure 5—12.
Figure 5-12:

Editing a File

LISP Editor
File

Edit

Commands

Help

rrr

;;; Define the ingredients and calories

(setf
(setf
(setf
(setf
(setf
(setf
(setf
(setf
(setf
(setf
(setf

(get
(get
(get
(get
(get
(get
(get
(get
(get
(get
(get

'sugar '’calories) 375)
'sugar 'units) "cup")
'milk 'calories) 150)
'milk 'units) "cup")
'butter 'calories) 200)
'butter 'units) "oz")
'bread 'units) "slice")
'egg 'calories) 75)
'egg 'units) "egg")
'syrup 'calories) 100)
'syrup 'units) "oz")

File recipe.lsp Forward EDT Emulation ("VAX LISP")

MLO-002866*•

The E ditor displays th e file or function a t the top of the screen in an editing
buffer. Below th e editing buffer is a sta tu s line th a t tells you the nam e of the
file (RECIPE.LSP) or function, the current direction of certain editing commands
(Forward), w h at “m ajor” editing style you are using (EDT Em ulation), and w hat
“m inor” editing style you are using (VAX LISP).
U sing th e default editing styles, you can en ter editing commands in two ways:
•

W hile the E ditor h as the in p u t focus, press Ctrl/Z and e n te r a comm and a t the
prom pt a t th e bottom of the screen.

•

Choose editing commands from the E ditor’s pull-down m enus.

M any com m ands are available as both commands and m enu choices; others are
available only through m enus. Figure 5-13 lists some commonly used editing op
erations, the m enu choices th a t execute them , and their corresponding command
fines, if available.

5-12

T h e D E C w in d o w s Interface to VAX LISP

Figure 5-13:

Basic Editing Commands

Menu Choice
Hie

Command

Description

Edit File

Opens a file for editing.

Write Current
Buffer

Writes the contents of the
buffer to the corresponding
LISP object or file.

No command
equivalent

Places the selected text
in the clipboard and removes
the selected text from its
current location.

No command
equivalent

Places the current contents
of the clipboard at the
cursor location within the
text.

Select Enclosing
Form

Selects the text of the inner
most LISP form containing
the cursor or selected
region.

EDT Query
Search

Searches for a text string
that you specify, either forward
or backward in the file.

Query Search
Replace

Replaces all or single occurrences of a string with another
string.

Write Modified
Buffers

Writes the contents of all
modified buffers to the
corresponding LISP objects or
to new versions of their
corresponding files.

Evaluate LISP
Region

Evaluates the selected text
and makes the results available
to the Listener.

Open...

Hie
Save

Select enclosing form

Search
Find...

Search
Replace...

Commands
Write modified buffers

Commands
Evaluate LISP region

MLO-002867

For m ore inform ation on th e Editor, see C hapter 8 of this m anual.

The DECwindows Interface to VAX LISP 5-13

P ress the Next Screen key u n til’ the cursor is a t the end of th e file. Then, try
entering the P R I N T - R E C I P E function shown in Exam ple 5—1. This function prettyprints the inform ation retu rn ed by c a l o r i e s .
Example 5-1:

Defining a LISP Function

(d efu n p r i n t - r e c i p e (re c ip e )
" p r e t t y - p r i n t a r e c ip e , num ber o f s e r v in g s , and c a l o r i e s / s e r v i n g
(u n less (re c ip e -p re c ip e )
( e r r o r "N o t a r e c i p e : ~S" r e c i p e ) )
( f o r m a t t "~A~2%" ( r e c i p e - n a m e r e c i p e ) )
(m apc # ' ( la m b d a (a u i )
( f o r m a t t " ~ 4 T ~A ~A ~A
( r a t i o n a l i z e a) u i ) )
(rec ip e-a m o u n t re c ip e )
(m apcar
# ' (lam b d a ( i)
(g et i 'u n its ) )
(re c ip e -in g re d ie n ts r e c ip e ))
(re c ip e -in g re d ie n ts r e c ip e ))
( f o r m a t t " ~ % S e r v i n g s : ~A ~%" ( r e c i p e - s e r v i n g s r e c i p e ) )
( f o r m a t t " C a l o r i e s / s e r v i n g : ~A ~2% " ( c a l o r i e s r e c i p e ) ) )

5-14

The DECwindows Interface to VAX LISP

Tb test this function, select the definition w ith the Select O uterm ost Form com
m and, and evaluate it w ith th e E valuate LISP Region command. W hen you use
c o o k i e s as an arg u m en t to p r i n t - r e c i p e , the function prints th e recipe as shown
in Figure 5—14.
Figure 5-14:

Running the PRINT-RECIPE Function

LISP Listener
File

Edit

Operations

Lisp> (print-recipe cookies)
cookies
2 cup SUGAR
1/4 cup MILK
1 O Z BUTTER
Servings: 36
Calories /serving: 27
NIL
Lisp>

Of
MLO-002868

The DECwindows Interface to VAX LISP

5-15

W hen you use f r e n c h - t o a s t as an argum ent, the function generates the error
shown in Figure 5-15. W henever a n error occurs, LISP gives you the opportunity
to use th e Debugger. A m essage box pops up th a t contains a b rief m essage
and two buttons. W hen the error is fatal, th e buttons are labeled DEBUG and
ABORT. ABORT is the default; you can avoid entering the Debugger by pressing
Return. W hen it is a continuable error, the buttons are labeled DEBUG and
CONTINUE. Clicking on the CONTINUE button or pressing Return is the sam e as
enterin g th e Debugger and im m ediately typing c o n t i n u e .
Figure 5-15:

Debugging Dialog Box

n
Error in *: Argument must be a number: NIL
DEBUG

ABORT

|
MLO-0028G9

5-16

The DECwindows Interface to VAX LISP

5.6 Using the Debugger
W hen you click on th e DEBUG button, VAX LISP opens a set of debugging
windows, as shown in Figure 5-16.
Figure 6-16:

Calling Stack

Debugging Windows

»*

Variable Bindings

Function name:

TOP

Frame number:

Syatam: :A : (MIL 1)

MAPCAR
MAPCAR
REDOCE

FLOCK
NUMERATOR
IF
IF

oc
LISP Debugger

CCMD
BLOCK

File

CALORIES
CALORIES

Com m ands

Edit

Operations

Error in *: Argimexit muat a number: MIL

EVAL

Apply #15:

BOTTOM

Debugger Commands

I M
Help

■Cr

(* N IL 1)

Debug 1>

Backtrace
Top

B ack trace...
Top All

Up
W here
Down
Bottom
Error

Up...
Goto ...

Search ...
Step
Redo

D ow n...
Bottom All
S h o w ...
S e t ...
Return ...
E v alu ate...

<?
<c

DC>

Goto^Framej ^CancejJ

<ic

Quit I

Cancel
MLO—002870

The m ain debugging window, LISP Debugger, contains m essages from the
Debugger and lets you e n te r debugging comm ands a t the prompt. Above the
Debugger window is a window th a t displays Variable Bindings. I t shows the
values of th e variables in the current fram e.
The Debugger Com m ands window, to the rig h t of the LISP Debugger window,
contains a set of comm and buttons. You can en ter debugging commands by
clicking on these buttons.
l b th e left of the D ebugger window is th e Calling Stack window. This window
shows a backtrace of the fram es on th e control stack. A double arrow ( » ) points
to th e cu rren t fram e. Debugging commands can move the pointer up and down
th e Calling Stack. You can change the current fram e by selecting a symbol in this
window and clicking on Goto Fram e or by double-clicking on a symbol.

The DECwindows Interface to VAX LISP

5-17

For example, you can click the DOWN button twice in the Com m ands window to
move the pointer to the second invocation of m a p c a r in the Calling Stack window.
Figure 5-17 shows the m essages th a t the Debugger displays w hen you do this.
Figure 5-17:

Calling Stack
TOP

Using the DOWN Command

Variable Bindings
F u n c t i o n n a m e : MAPCAR

-C>

F ra m e n u m b e r : 13

I n t e r p r e t e r f r a m e — C a n 't s e e i n t e r n a l A r g u m e n ts .
MAPCAR
»MAPCAR
jRETCCE
FLOCK.
NUMERATOR
IF
IF
COND
BLOCK
CALORIES
CALORIES
EVAL

5?
Ol
LISP Debugger
File

Com m ands

p
Edit

Operations

Help

E r r o r i n * : A rg u m e n t m u s t a n u m b e r : N IL
O
A p p ly # 1 5 :
(*N IL 1)
D e b u g 1 > DOWN
A p p ly # 1 4 : (M A P C A R #<C copiled F u n c t i o n * #xF 40C 0> (N I
D e b u g 1 > DCWN
E v a l # 1 3 : (MAPCAR (FUNCTION * (MAPCAR (FUNCTION (LAN
D ebug 1>

BOTTOM

Debugger Commands
Backtrace
Top

B a ck trace...
Top All

Up
W here

up Goto ...
Down ...
Bottom All
S h o w ...
Set ...
Return ...
E v alu ate...

Down
Bottom
Error
Search ...
Step
Redo

DO
o
<oc

[ o ü i j JL^ntlnueD Cancel!

Each tim e you issue the DOWN command, the Debugger displays th e function
th a t LISP would evaluate a t th a t point in the Calling Stack. You can then issue
th e STEP command to evaluate the function, one step a t a tim e. For example,
w hen the Calling Stack points to the outer occurrence of MAPCAR, you can click
on th e STEP command to begin reevaluating the function. W hen you invoke the
Stepper, it presents a different set of commands in a Stepper Com m ands window,
th e Calling Stack and Variable Bindings windows disappear, and th e Debugging
window displays th e Step prom pt ra th e r th a n the Debugger prompt.

5-18

The DECwindows Interface to VAX LISP

Figure 5—18 shows w h at the Stepper displays w hen you step through the second
function invocation. Note how the Stepper re tu rn s the resu lt of the form
( g e t i ( q u o t e c a l o r i e s ) ) for each of the elem ents in the list ( b r e a d e g g s y r u p ) .
The value retu rn ed for b r e a d is n i l . This causes the program error—the CALORIES
function expects this value to be a num ber.
map ca r

Figure 5-18:

Stepping Through a Function

To exit from the Stepper, choose Q uit from the Stepper m enu. This closes all
Debugger and Stepper windows and re tu rn s you to the Listener. At the L i s p >
prom pt, you can fix the program by entering the following form to define the
num ber of calories per slice of bread:
L isp >
100

(se tf

(g et

'b r e a d

'c a lo r ie s )

100)

You can check th a t th e program now works correctly by entering the form:
L isp >
275

(c a lo rie s

fre n c h -to a st)

For more inform ation on th e Debugger, see C hapter 10.

The DECwindows Interface to VAX LISP

5-19

5.7 Exiting from VAX LISP
You have now seen how to perform some basic operations w ith the DECwindows
interface to VAX LISP. The chapters th a t follow describe each u tility in detail.
You can exit from LISP by typing ( e x i t ) a t th e L i s p > prom pt or by choosing Exit
from the File m enu, as shown in Figure 5-19. If you choose th e m enu item, a
caution box appears to confirm th a t you w an t to exit. Click on th e Yes button to
exit from LISP.
Figure 5-19:

Edit

Exiting from VAX LISP

Operations

Load...
Compile File.
Ed...

Help

'sugar)
cookies)

Suspend As...

>e cookies)

Dribble

Save

Save As...
Exit

............. -ir- ----—-------

Calories/serving: 27
Lisp>

<](
MLO-002873

5-20

The DECwindows Interface to VAX LISP

Chapter 6

Starting LISP from DECwindows
This chapter describes how to:

6.1

•

Define th e display system (DECwindows or term inal) th a t LISP uses from the
DCL command line

•

Invoke an interactive LISP session from DECwindows

•

Resum e a suspended LISP session from DECwindows

•

Compile a LISP file from DECwindows

Defining the Display System
You can define the interface on which VAX LISP ru n s on a w orkstation w ith the
VMS SET DISPLAY command. You can have VAX LISP ru n w ith th e term inal or
DECwindows interface on your w orkstation. You define the interface you w ant
from your w orkstation or from a term inal th a t is a node in the sam e network.

6.1.1 Displaying LISP on DECwindows
To display VAX LISP on a w orkstation, define th a t w orkstation w ith th e SET
DISPLAY command. For fu rth er inform ation about the SET DISPLAY command,
see V M S Version 5.1 N ew F ea tu res M a n u a l.

6.1.2 Displaying LISP on a Terminal
To display VAX LISP on a term inal, use th e DCL LISP verb as described in
C hapter 2. If th e logical LISP$DISPLAY h as the value "TERMINAL", or if the
logical DECW$DISPLAY has no value, VAX LISP will ru n w ith its term inal
interface.

6.2

invoking LISP from DECwindows FileView
To invoke VAX LISP from DECwindows FileView:
•

Use the LISP.EXE file.

•

Use th e DCL Com m and item in th e U tilities m enu.

Starting LISP from DECwindows

6-1

6.2.1

Invoking LISP with the LISP.EXE File
l b invoke a n interactive session of VAX LISP from FileView w ith the LISP.EXE
file:
•

Select LISP.EXE and choose th e RUN item from the Files M enu.

•

Press MB2 on LISP.EXE and choose the RUN item from the pop-up m enu.

•

Double-click on LISP.EXE.

If you invoke LISP w ith one of the m enu item s, the DECwindows File View-Run
dialog box is displayed on your screen (see Figure 6—1). You can e n te r standard
LISP param eters in the P aram eters field of th is dialog box. Double-clicking
on LISP.EXE invokes LISP w ithout any qualifiers. The next tim e you select
LISP.EXE and choose th e RUN item , the param eters th a t you previously used
appear, and you can edit them for th is invocation. Subsequently, double-clicking
on LISP.EXE invokes LISP w ith the m ost recently supplied param eters.
Figure 6-1:

DECwindows FileView-Run Dialog Box

MLO-002985

6 -2

Starting LISP from DECwindows

Tb continue th e invocation, click on th e OK button, and the FileView-Work in
Progress dialog box (see Figure 6-2) appears on your screen followed by the
LISP L istener w ith th e L is p > prom pt. C hapter 7 describes the L istener in m ore
detail.
Figure 6-2:

DECwindows FileView-Work in Progress Dialog Box

FileView - Work In Progress
Work in Progress

Files

Status

Running LISP.EXE

l/ l

Active

n
Ll
<7
^ h ow O u tp u J

Stop Task I

Dismiss I
MLO-002986

6.2.2 Invoking LISP with the DCL Command Item
You can invoke an interactive session of VAX LISP from the FileView by choosing
th e DCL Command item from th e U tilities m enu. This brings up a FileView
Task O utput dialog box into w hich you can type th e LISP DCL command
w ith qualifiers and argum ents. By default, this causes LISP to display on
your w orkstation. Tb have LISP display on some other node, use the m ethods
described in Section 6.1. E n ter th e commands to define th e node before entering
the LISP command.

6.3 Resuming LISP from DECwindows
A suspended system is a binary file th a t is a copy of the LISP m em ory in
use during a n interactive LISP session up to the point a t which you create
th e suspended system . The state of th e windows th a t were displayed on your
w orkstation screen is not included in th is file. The purpose of a suspended system
is to save th e state of a n interactive LISP session. You m ight w ant to do this if
your work is incom plete. By resum ing LISP from a suspended system , you can
continue your work from the point a t which you stopped.
To resum e a suspended system from DECwindows, type the LISP command w ith
th e /RESUM E qualifier and th e nam e of the file containing th e suspended system
a t any of the previously described places w here you could use the LISP command,
such as the $ prom pt, in th e DCL Command box. Section 6.2.2 describes how
to get to the DCL Com m and box. The LISP L istener is displayed on your
w orkstation screen; you m u st rebuild th e other windows if you w an t to re-create
th e display th a t w as on your screen w hen you suspended the LISP session.
See Section 2.11.1 for detailed inform ation on th e su spen d function.

Starting LISP from DECwindows

6-3

NOTE
A suspended system can be resum ed only by th e VAX LISP system
from which it was suspended. The VAX LISP system th a t resum es a
suspended system m u st m eet these criteria:
•

The VAX LISP system m u st be th e sam e version of VAX LISP as
the suspending system .

•

A custom VAX LISP system created w ith the VAX LISP SystemBuilding U tility m u st be th e sam e system or a copy of th e system.
(See VAX L I S P /V M S S y s te m -B u ild in g G u id e for a description of
the System -Building Utility.)

6.4 Compiling a LISP File from DECwindows
Any collection of LISP expressions can m ake up a program and can be stored in
a file. The compiler processes such a file by compiling th e LISP expressions in
the file and w riting each compiled re su lt to a n output file. See C hapter 2 for a
discussion of the advantages of compiling and not compiling LISP expressions.
Tb compile files from DECwindows:
1.
2.

Select any num ber of .LSP files.
Choose th e COMPILE item on the FileView Program m ing m enu. The
Program m ing m enu is not available by default in th e FileView m enu bar. You
add it w ith the M ENU BAR... item on th e FileView Control m enu.

For each .LSP file you select, a FileView prom pting window is displayed on your
w orkstation screen. You type th e options you w a n t for th e compilation of th a t file
in th e prom pting window. These options are th e qualifiers th a t are allowable w ith
th e /COMPILE qualifier. C hapter 2 provides a table and a detailed description of
each of these options. The options th a t you type in the prom pting box are used
only for th e compilation of th a t file. E ach file is compiled in a sep arate invocation
of LISP.

6—4 Starting LISP from DECwindows

Chapter 7

The Listener
The L istener u tility appears on the screen w hen you invoke LISP in a
DECwindows environm ent. The L istener corresponds to th e top level in a
term inal-based LISP system. W hen you type forms in th e Listener, LISP reads
and evaluates them , and p rin ts the resu lts in the sam e window.
You can access other LISP utilities by using the m enus th e L istener provides.
You can also use the m enus to load, compile, and save LISP files.
Figure 7-1 shows the L istener m enus.
Figure 7-1:

Listener Menus

File

Edit

Operations

Help

Load ...
Compile F ile...
Ed...

Undo

INSPECT
ED
EVAL

Overview
About

Suspend
Suspend As...

Cut
Copy
Paste
Clear

D ribble...
Save
Save As...
Exit

COMPILE
UNCOMPILE
DISASSEMBLE

Apropos
Describe

TRACE
TRACE...
UNTRACE
STEP...
ABORT
BREAK
CONTINUE
DEBUG

MLO-002874

This chapter describes how to:
•

E n te r LISP forms

•

E xit from the L istener

•

E dit tex t and objects

•

Work w ith files

Appendix C provides inform ation on how to custom ize th e Listener.
The Listener

7-1

7.1 Entering LISP Forms
W hen you invoke LISP w ith the DECwindows interface, a L istener window
appears on th e screen. After displaying th e copyright notice, the L i s p > prom pt
and the text cursor appear a t the top left of the w ork area.
The work a re a is divided into two logical portions: th e tra n sc rip t region and the
in p u t region. The transcript region consists of th e text preceding the current
L i s p > prom pt including the current L i s p > prom pt. The input region is the area
following th e current L i s p > prom pt, w here th e tex t insertion point is located.
As you e n te r text, it appears in th e in p u t region. W hen you complete a form and
press Return, the L istener reads and evaluates th e form. The text of th e in p u t form
and the value retu rn ed by LISP become p a rt of th e transcript. Figure 7—2 shows
th e tra n sc rip t region and the in p u t region of a LISP window after you e n te r the
form (+ 4 3) and press Return.
Figure 7-2:

Listener Window

Transcript Region

The tra n sc rip t region is read only. You can select and copy tex t and objects from
th is region b u t you cannot modify it.
T he text you en ter in th e in p u t region rem ains text when it becomes p a rt of the
tran scrip t. I t is not converted to LISP objects. However, if you paste an object
into the in p u t region, you can still select it as a n object both w hen it is in the
in p u t region and w hen it becomes p a rt of th e tra n sc rip t region.

7-2

The Listener

7.2 Exiting LISP from the Listener
l b exit from the Listener, choose the Exit m enu item from the File m enu. A
confirm ation box appears on the screen, l b exit, click on th e OK button. W hen
you exit from the Listener, th e L istener window and any other LISP windows on
th e screen disappear. The LISP im age is now stopped.

7.3 Editing Text and Objects
W hen you use LISP in a DECwindows environm ent, you can move or copy text or
objects:
•

From one location in a window to another.

•

Between windows—for example, from an Inspect window to th e L istener
window.

In addition, LISP defines specific keys to let you perform basic text editing
operations. These keys let you move the cursor and delete text.

7.3.1 Selecting Text and O bjects
Before you can move tex t and objects, you m u st select them w ith the m ouse. You
select text as you do in other DECwindows applications, by pressing MBi and
dragging over the region of text. Section A. 16.1 describes th e basic ways to select
text.
LISP also lets you select larger blocks of text as follows:
U ser A ction

R esu lt

2 MBI dicks

Selects the word indicated by th e pointer.

3 MBI clicks

Selects the line indicated by th e pointer.

4 MBI clicks

Selects th e in pu t or output tex t of th e READ-EVAL-PRINT tran sac
tion.

5 MBI clicks

Selects all tex t in the transcript and in pu t regions.

W hen you move the pointer over a portion of tex t th a t is also an object, the
object is underlined. W hen you move the pointer off th e object, the underlining
disappears.
Tb select a n object, move th e pointer to the underlined object and click MBI. The
object is highlighted to show it is selected. Tb deselect th e object, click MBI again
anyw here in the window.
Tb select th e text instead of the underlined object, move th e pointer to th e first
character of th e tex t you w an t to select and press and drag MBI. Tb deselect the
text, click MBi once anyw here in th e text.

The Listener

7-3

7.3.2 Moving Text and O bjects to Another Location
You can select text and objects and move them to other locations in the LISP
developm ent environm ent, using the E dit m enu.
You move th e selected range by cutting it and then p asting it in a new location.
Tb cut and paste the selected range:
1.

Select the text or objects you w ant, using mouse clicks.

2.
3.

Choose C ut from the E dit m enu.
Place th e cursor w here you w ant the inform ation and choose P aste from the
E dit m enu of the utility to which you are m oving th e text.

I b copy th e selected range instead of cutting it, choose th e Copy item from the
E dit m enu. Then place the cursor w here you w an t th e inform ation and choose
P aste.
For fu rth e r inform ation on copying text in the DECwindows environm ent, see
Sections A.16.2 and A.16.3.

7.3.3 VAX LISP Default Key Bindings
Table 7-1 lists th e default key bindings for VAX LISP. You can use these key
bindings to move th e cursor or delete text while in th e Listener, Inspector, and
Debugger. For inform ation on using key bindings in the Editor, see Section 8.1.3.
Table 7-1:
User Action
|R etu rn ]

or |E n t e r !

VAX LISP Default Key Bindings
Result
Inserts a new line. I f you have com pleted th e input, it w ill be
processed.
Inserts leading w hitespace to correctly in dent current line.
M oves text cursor one character to th e left.

[ S h ift / * —

1Ctrl/«— |

M oves text cursor one word to the left.
Moves text cursor to beginning o f current line.

Replaces input buffer w ith previous in pu t buffer from th e transcript
region.

M oves text cursor one character to th e right.

| S h i f t / — »|

M oves text cursor one word to the right.

| C t r l/ — > |

M oves tex t cursor to th e end of current line.
Replaces input buffer w ith n ext in pu t buffer from th e transcript
region.

M oves text cursor to beginning of in p u t buffer.

|S h tft/ F 1 2 [

M oves tex t cursor to th e end of input buffer.

I D e le te |

D eletes character to th e left o f tex t cursor.

| S h lft/ D e le te l

D eletes character to th e right o f tex t cursor.

1 C W / P e le tT ]

D eletes input buffer. C ontents of buffer cannot be retrieved.

|C trl/ A |

M oves tex t cursor to b eginning o f in pu t line.

(continued on next page)

7-4

The Listener

Table 7-1 (Cont.): VAX LISP Default Key Bindings
U ser A ction

R esu lt

Ic w

Moves text cursor one character to the left.

|CWD|

D eletes th e character to th e right of tex t cursor.

|CW E [

M oves text cursor to th e end o f current line.

[CWPl

Moves text cursor one character to th e right.

I C t r i/ G |

Clears input buffer. C ontents o f buffer cannot be retrieved.

[ C tr i/ H |

Moves text cursor to th e beginning o f in pu t buffer.

lowil

Inserts leading w hitespace to correctly indent current line.

[c w Ä J l

Inserts linefeed and correct am ount o f w hitespace to indent next
line. Places tex t cursor a t th e end o f new w hitespace.

| C t r l/ K |

D eletes all in p u t to the right o f tex t cursor.

|ctn/N|

Moves text cursor to n ext lin e in in p u t buffer.

|C W /0|

Inserts leading w hitespace to correctly indent n ext line. Cursor
rem ains a t the end of current line.

|CW P|

Moves text cursor to previous line in in pu t buffer.

[ÖMÄJI

D eletes all in p u t to th e left of tex t cursor.

| C t r lV W |

Clears in pu t buffer. Contents o f in pu t buffer are stored for retrieval
by Ctrl/Y.
Replaces in pu t buffer w ith in pu t buffer stored by Ctrl/W.

| O t r l/ Y |

7.4 Working with Files
You can perform operations on files by clicking on item s from th e File m enu.
From th e Listener, you can:
•

Load a LISP file

•

Compile a LISP file

•

Invoke th e E ditor on a LISP file

•

Save the text of th e tra n sc rip t region to a file

•

C reate a LISP suspended im age file

•

Record your interactive LISP session to a file

The Listener

7-5

7.4.1

Loading a LISP File
Load a LISP file from the L istener as follows:
1.

Choose th e Load m en u item from the File m enu.
The L isten er displays a File Selection box w ith the nam es of any LISP source
files in th e c u rre n t directory. Figure 7—3 shows a File Selection box.

Figure 7-3:

File Selection Box

File Filter
[USER]*.LSP
Files in DISK$:[USER]
DISK$:[USER]FILE1 .LSP;1
DISK$:[USER]FILE2.LSP;2

30
Selection
1DISK$:[USER]FILE2.LSP;2
MLO-002876

7-6

Select the nam e of the file you w an t to load.

3.
4.

To see a listing of files in another directory, enter the directory nam e in the
File F ilte r field and click on th e F ilter button or press Return. The list box
displays th e files in th a t directory. Tb display specific files in the list box,
en ter a directory nam e and file specification in the File F ilter field.
Click on the OK button, press Return, or double-click on the file.
The L istener clears th e in p u t region of any partial forms and fills it w ith a
call to the l o a d function. As the file is loaded, LISP displays the nam es of
th e functions contained in the file on th e screen. W hen the command finishes
running, the L i s p > prom pt re tu rn s and any p artial form entered before
loading th e file is restored.

The Listener

7.4.2 Compiling a LISP File
You can use the compile - f il e function to compile a LISP file w ithout leaving the
LISP environm ent. To compile a file:
1.

Choose th e Compile File item from th e File m enu.
The L istener displays a File Selection box w ith the nam es of all LISP source
files in th e cu rren t directory. Figure 7 -4 shows the Compile-File File Select
box.

Figure 7-4:

Compile-File File Select Box

Compile File
File Filter
[USER]*.LSP
Files in DISK$:[USER]
DISK$:[USER]FILE1 .LSP;1
DISK$:[USER]FILE2.LSP;2

<11

Selection
1DISK$:[USER]FILE2.LSP;2
MLO-002877

Select the nam e of th e file you w an t to compile.
3. Click on the O K button, press Return, or double-click on th e file.
4. The L istener clears th e in p u t region of any p a rtial form s and fills it w ith
a call to th e compile - f il e function. As th e file compiles, th e nam es of the
functions in the file appear in the L istener window. A fter the file is compiled,
LISP re tu rn s the Lisp> prom pt and restores any p a rtial form th a t was
entered before compiling the file.

The Listener 7 -7

7.4.3 Invoking the Editor on a LISP File
l b invoke the E ditor on a LISP file:
1.

Choose the Ed item from the File m enu. A File Selection box appears on the
screen.
2. Select a file nam e from the list box or e n te r a new file nam e on th e Selection
line.
3. Click on th e OK button.
4. The E ditor window appears. If you selected the nam e of an existing file,
the file is loaded into an E ditor buffer and appears in th e E ditor window. If
you entered th e nam e of a new file, th e E ditor window appears as shown in
Figure 8-2.

7.4.4 Saving the Text of the Transcript Region
l b save the inform ation in the tra n sc rip t region to a text file:
1.

Choose th e Save As . . . item from the File m enu.
The L istener displays the Save As dialog box. A dialog box is shown in
Figure 7-5.

7-8

The Listener

Figure 7-5: Save As Dialog Box

Save As
File Filter
[USER]*.LSP
Files in DISK$:[USER]
DISK$:[USER]FILE1 .LSP;1
DISK$:[USER]FILE2.LSP;2

Filter
OK
Cancel

3C>

Selection

MLO-002878

l b save the tex t to a new file, e n te r the file nam e in th e Selection field and
click on OK or press Return.
Tb save the text to a new version of a file appearing in the list box, click on
the file nam e and th en click on th e OK b utton or press Return.
To see a fisting of files in an o th er directory, type th e directory nam e in the
File F ilter field and click on th e F ilter button. The list box displays the files
in th a t directory. To display specific files in the fist box, en ter a directory
nam e and file specification in the File F ilter field.

A fter you have saved a file w ith Save As, you can save a new version of the file
under the sam e file nam e by choosing the Save m enu item . A m essage indicates
th a t the file is being saved.
If you choose Save before using Save As in th is session, the Save dialog box
appears to prom pt you for a file nam e.

7.4.5 Creating a LISP Suspended Image File
You can use th e suspend function to save th e state of th e LISP system , m aking
it possible to resum e the LISP system a t a la te r tim e. A fter you create the
suspended file, the system re tu rn s you to th e L isp > prom pt. You can continue the
cu rren t LISP session or exit from th e session. For fu rth e r inform ation on creating
and resum ing suspended system s, see Section 2.11.

The Listener

7-9

Tb create a suspended system:
1.
2.

Choose th e Suspend As . . . item from th e File m enu.
The L istener displays a File Selection box and prom pts you for a file name.

Choose a file from the list or type th e file nam e you w an t in th e Selection
field. The suspended system is placed in your default directory or in the
directory you specify in the dialog box.

Click on the OK button or press Return.

Use Suspend . . . th e first tim e you save a file. Then you can choose the Suspend
m enu item to suspend a new version of th e file u n d er th e sam e file name.
The Suspend item rem ains dim m ed u n til you have assigned a file nam e w ith the
Suspend . . . item .

7.4.6 Recording Your Interactive LISP S ession
You can use the d r i b b l e function to save a record of your interactive LISP
session, d r i b b l e sends th e in p u t and output of the L istener window and the
Debug I/O window to a specified file.
You s ta rt th e d r i b b l e function as follows:
1.
2.

Choose th e Dribble item from the File m enu. A Dribble dialog box is dis
played.
E n ter th e nam e of th e file in which you w a n t to save th e session. Click on the
OK button or press Return.

Once you s ta rt the d r i b b l e function, th e m enu item changes to Stop Dribble, l b
stop the d r i b b l e function, choose th is item .
The system continues to copy all in p u t and output to th e dribble file until you
choose Stop Dribble or e n te r the form (dribble) a t th e Lisp> prompt.

7.5

Compiling a Function
You c a n u s e t h e c o m p IL E f u n c t i o n t o c o m p i l e a f u n c t i o n o r a m a c r o f r o m w i t h i n a
currently ru n n in g LISP session.
You norm ally call th e LISP function first in in te rp re te d form to see if it works.
Once it works as interpreted, you can te st it in compiled form w ithout w riting it
to a file.
W hen you compile a function or m acro th a t is not in a file, th e compiled definition
exists only in th e cu rren t LISP session, l b save the compiled definition once you
leave LISP, you m u st w rite the in terp reted function to a file and compile the file.
You can use the u n c o m p i l e function to restore the in terp reted function definition
of a symbol, if the symbol’s definition w as compiled w ith th e COMP IL E function.
l b compile a function or macro:
1.

Select a symbol th a t nam es th e function or m acro you w an t to compile.

Choose th e COMPILE item on th e O perations m enu.
The COMPILE item is dim m ed unless th ere is a selection.

7-10 The Listener

The L istener clears th e in p u t region of any p a rtial form appearing a t th e
L i s p > prom pt and fills it w ith a call to the c o m p i l e function. W hen the
compilation finishes, the L i s p > prom pt re tu rn s and any p a rtial in p u t entered
before the compiling operation is restored.

lb uncompile a function or macro that was compiled with the compile function:
1.
2.

Select the function or m acro you w an t to uncompile.
Choose the UNCOM PILE item on th e O perations m enu. The UNCOMPILE
item is dim m ed unless there is a selection.

7.6 Disassembling a Function
The d i s a s s e m b l e function takes compiled LISP code and “reverse-assem bles” it.
This lets you view th e compiler output and check the efficiency of your code. Tb
disassem ble a function or macro:
1.
2.

Select a symbol th a t nam es th e function or m acro you w an t to disassem ble.
Choose th e DISASSEMBLE item on the O perations m enu. The
DISASSEMBLE item is dimmed unless th ere is a selection.

The L istener clears th e region of any p a rtial form appearing a t th e Lis p >
prom pt and fills it w ith a call to th e d i s a s s e m b l e function. A fter th e compiled
code has been reverse assem bled, the L i s p > prom pt retu rn s, and any p a rtial
in p u t entered before th e disassem bling operation is restored.

7.7 Using the EVAL Function
The e v a l function takes a form as in p u t and evaluates it. You can evaluate a
form by selecting it and choosing the EVAL item as follows:
1.

Select the form you w ant to evaluate. You can do this even if you have a
partially entered form a t th e current L i s p > prom pt.

Choose th e EVAL item from th e O perations m enu. The EVAL item is dimm ed
unless th ere is a selection.

The L istener suspends any p a rtial form and fills the in p u t region w ith the
appropriate calls to th e e v a l function. The evaluation occurs and re tu rn
value appears on th e screen. The L istener displays a new L i s p > prom pt and
restores any p a rtial form to th e in p u t region.

7.8 Invoking Other LISP Utilities
You can invoke th e Inspector, tra c er and E ditor utilities from the L istener by
choosing th e appropriate m enu item from th e O perations m enu. To invoke these
utilities:
1.
2.

Select a strin g or symbol for th e E ditor or tra c er or any object for the
Inspector.
Choose th e appropriate m enu item on th e O perations m enu. The m enu item s
representing the utilities are dim m ed unless th ere is selection.
The u tility window appears on th e screen and h a s in p u t focus.

The Listener

7-11

7.9

Interrupting a Program
You can in te rru p t your program by choosing the a b o r t , b r e a k , or d e b u g functions
from the O perations m enu. These item s call asynchronous functions on the
control stack of your program .
The ABORT function h a lts th e execution of your program , l b h a lt program
execution:
•

Choose the ABORT item from the O perations m enu while your program is
executing. This calls th e a b o r t function on your program ’s stack, as if your
program had called a b o r t directly. See th e description of th e a b o r t function
in the VAX L I S P /V M S O bject R eference M a n u a l.

•

Press Ctrl/C in the L istener window while your program is executing.

You can tem porarily in te rru p t th e execution of your program w ith the BREAK or
DEBUG item on th e O perations m enu. The BREAK item causes a break loop to
be ru n in the L istener (see Section 10.3). The DEBUG item invokes the Debugger
on your program , displaying the fram e w here execution was in terru p ted (see
Section 10.4). Ib in te rru p t your program w ith a break loop or the Debugger,
choose th e appropriate item from th e O perations m enu.

7.10 Getting Help
You can get help in VAX LISP by using the H elp m enu or th e Help key w ith the
pointer. Help provides brief inform ation on th e following:
•

VAX LISP concepts

•

VAX LISP product and version num ber

•

Screen objects

You can also access the VAX LISP functions a p r o p o s and d e s c r i b e from the Help
m enu.

7.10.1

Invoking Help on VAX LISP
l b get help on VAX LISP, choose th e Overview item from the Help m enu. A Help
window opens to display an overview of VAX LISP.
To get inform ation about the product and version num ber, choose th e About
item . You can access the overview inform ation from this screen by clicking on the
Overview item under A dditional Topics.

7-12

The Listener

7.10.2 Invoking Help on Screen Objects
l b get help on screen objects such as m enu nam es and m enu item s:
1.

Point to the screen object.

P ress and hold th e Help key while you click MB1.
Release the Help key.

A Help window opens w ith inform ation on th e screen object.

7.10.3 Using the APROPOS and DESCRIBE Functions
The apropos and d e s c r ib e functions provide inform ation about VAX LISP objects.
The apropos function searches through a package for a symbol whose p rin t nam e
contains a specified string. The d e s c r ib e function displays inform ation about
a specified object. For m ore inform ation about apropos and d e s c r i b e , see VAX
L I S P /V M S O bject R eference M a n u a l.
l b use the apropos or d e s c r ib e function from th e Help m enu:

Select a text strin g or an object. If you select an object for apropo s , it m ust
be a string or a symbol.

T h e L istener

7-13

Choose th e Apropos or Describe item . If th ere is no selection, these item s are
dimmed.
If you click on Apropos, the Apropos dialog box appears on th e screen. It
contains a list of all the symbols accessible from th e current package th a t
contain th e selected text strin g or object. You can use th e scroll b a r to scroll
through the inform ation. Figure 7-6 shows a n Apropos dialog box.

Figure 7-6:

A propos Dialog Box

Apropos of symbol

Symbols in package USER containing the string "symbol":
FIND—SYMBOL, has a definition
DO-ALL-SYMBOLS, has a definition
SYMBOL-PACKAGE, has a definition
DO—EXTERNAL-SYMBOLS, has a definition
FIND-ALL-SYMBOLS, has a definition
SYMBOL
DO-SYMBOLS, has a definition
SYMBOL—PLIST, has a definition
COPY—SYMBOL, hw« a definition
SYNCNYM-STREAM-SYMBOL, has a definition
SYMBOL-FUNCTION, has a definition
<7

30
U pdat^J ^ p r o p o ^ J ^Describe^j

Cancel
MLO-O02879

-1 4

T h e Listener

If you click on Describe, th e Describe dialog box appears on the screen. It con
tain s a description of th e selected tex t string or object. You can use th e scroll bar
to scroll through the inform ation. A Describe dialog box is shown in Figure 7-7.
Figure 7-7:

Describe Dialog Box

Description of DO-ALL-SYMBOLS

It is the symbol DO-ALL-SYMBOLS
Package: COMMON-LISP
Value: unbound
Macro: compiled

DO-ALL-SYMBOLS (var [result-form]) {declaration }"
{tag|statement}"
This macro is similar to DO-SYMBOLS, but executes the body
once for every symbol contained in every package. It is not
in general the case that each symbol is processed only once,
because a symbol may appear in many packages.
<

U pd a tejj ^ p r o p o s j

Describe

Cancel
MLO-002880

You can click on the Cancel button to dism iss to th e dialog box or leave the dialog
box on the screen. The next tim e you select a tex t strin g or object and click on
Apropos or Describe, another dialog box appears.
You can select objects or text in the Apropos or Describe dialog box and then
click on the Apropos or Describe buttons a t th e bottom of th e dialog boxes. The
appropriate dialog box appears w ith inform ation on th a t object.
The Apropos and Describe dialog boxes provide snapshot inform ation about the
selected tex t string or object. The inform ation in the dialog box m ay become
obsolete if you continue to work in LISP while th e dialog box is p resent on th e
screen. To obtain the m ost c u rren t inform ation about th e topic, click on the
U pdate b u tton on th e dialog box.

T h e L istener

7-15

Chapter 8

Using the VAX LISP Editor in DECwindows
VAX LISP provides a built-in editor for creating and editing LISP symbols and
files. The E ditor h a s special featu res th a t aid you in w riting LISP program s, such
as m atching parentheses and indenting lines of code.
W hen you use th e E ditor in a DECwindows environm ent, you can move back and
forth from the E ditor to other LISP utilities w ithout having to en ter commands.
You can also execute m any of th e E ditor comm ands by clicking on m enu item s
instead of typing comm and nam es or key bindings.
Figure 8 -1 shows the E ditor m enus.
Figure 8-1:

Editor Menus

File

Edit

Open ...
View...

Copy
Cut
Paste
Clear

Include...
Save
Save A s ...

■
*:

Select Enclosing Form
Select Outermost Form
Select All

Exit

Help
Overview
About

Commands

Find...
Find Next
Find Previous
Replace...

List Buffers
Select Buffer
Insert Buffer
Delete Current Buffer
Delete Named Buffer
Write Modified Buffers
Write Current Buffer
Split Window
Remove Current Window
Remove Other Windows
Next Window
Evaluate LISP Region
Indent USP Region

Apropos Editor Object
Apropos Word
Describe Editor Object
Describe Word
Alternatives
Last Error

MLO-002970

Using the VAX LISP Editor in DECwindows 8-1

This chapter explains how to use th e E ditor in default mode. T h at is, the E ditor’s
m ajor style is " edt Em u lation " and its m inor style is "VAX l i s p ". If you are using
or wish to use th e "EM&cs" style provided w ith the Editor, see Appendix D.
M any of the E ditor’s capabilities can be modified or extended by w riting new
LISP code. For m ore inform ation on how to custom ize th e Editor, see the VAX
L I S P /V M S E d ito r P ro g r a m m in g G u ide.

8.1

Introduction to the Editor
This section describes the following basic steps in the editing cycle:
•

Invoking the E ditor

•

E ntering text

•

E valuating work in th e Editor

•

Saving work in the E ditor

•

R eturning to LISP to evaluate code

•

R eturning to th e E ditor to m ake changes

•

E xiting the Editor

8.1.1 Invoking the Editor
You norm ally invoke th e E ditor from the L istener utility. The following sections
describe how to invoke the E ditor from the m enus and through a call to the ed
function.
8.1.1.1 Invoking the Editor from the Menus
To s ta rt th e E ditor on a file, use th e Ed m enu item on th e File m enu.
A File Selection box appears. Select a file nam e from the list box or e n te r a new
file nam e on the Selection line and click on th e OK button.
The E ditor window appears. If you selected th e nam e of an existing file, the file
is loaded into an E ditor buffer and appears in the E ditor window. If you entered
th e nam e of a new file, th e E ditor window appears as shown in Figure 8—2.

S-2

U sin g the VAX LISP Editor in D E C w in d o w s

Figure 8-2: Editor Window with Two Buffers

■FfÜ

LISP Editor
File

Edit

Commands

Help

— Function CIRCUMFERENCE Forward EDT Emulation ("VAX LISP") —
I»
Hr

Define the ingredients and calories per some—unit-of-measure

rrr

(setf (get 'sugar 'calories) 375)
(setf (get 'sugar 'units) "cup")
(setf (get 'milk 'calories) 150)
File newfile.lsp Forward EDT Emulation ("VAX LISP")

The cursor appears a t th e top left of th e E ditor window. The label strip n ear the
bottom of th e window displays th e following inform ation:
•

The nam e of the file currently being edited.

•

The direction of movement, eith er forw ard or backw ard, for EDT keypad
comm ands th a t require this inform ation.

•

The m ajor and m inor style currently in use. Figure 8 -2 reflects th e default
values for these item s, EDT E m ulation and VAX LISP, respectively. For more
inform ation on the m ajor and m inor styles, see Section 8.6.1.4.

The inform ation area a t the bottom of the screen provides m essages about the
E ditor operations and errors. For example, th e m essage “New File” appears in
th is a re a when you begin to edit a new file.
Tb invoke th e E ditor on a symbol’s function definition in stead of a file, use the ED
item on th e O perations m enu. Select the symbol whose function definition you
w an t to edit using the m ouse and th en click on th e ED item . An E ditor window
appears. See Figure 8-2.
8.1.1.2

Invoking the Editor Using a Command Line
You can use th e ed function to invoke th e Editor. The first tim e you invoke
th e E ditor during a LISP session, supply an argum ent to th e ed function. The
argum ent identifies th e object or file you w a n t to edit.

U sin g the VAX LISP Editor in D E C w in d o w s

8-3

I b edit a function definition, give a symbol as the argum ent. For example,
you can en ter the following form to edit the function definition of th e symbol
calories :
L isp >

(ed

'c a lo r ie s )

You can also edit the value of a symbol, ra th e r th a n its function definition, by
using the : TYPE keyword w ith the ED function, as shown in this example:
L isp >

(ed

'c a lo r ie s

:ty p e

rv a lu e )

Tb edit a file, give the file specification as the argument to the ed function. For
example:
L isp >

(ed

" n e w file . Is p " )

W hen you finish entering the command line and press Return, an E ditor window
appears. Figure 8—2 shows the E ditor w ith two buffers open: one editing a
function definition and one editing a file.

8.1.2 Entering Text in the Editor
In default mode, the E ditor uses EDT Em ulation, which m eans the keypad
keys function th e sam e as in the EDT editor. If you are not fam iliar w ith the
EDT editor, see Section 3.2, which contains basic instructions for using the EDT
keypad.
You in se rt ordinary text by typing it. You can use Tab to indent the fine of LISP
code currently containing the cursor, w ith respect to the preceding fines of code.
If you type a rig h t parenthesis, th e E ditor highlights the left parenthesis m om en
tarily. If th e left parenthesis has scrolled off the screen, th e E ditor displays the
line th a t contains it in the inform ation a re a w ith th e left parenthesis highlighted.

8.1.3 Using Editor Commands
You can use E ditor commands to form at tex t or select text for fu rth e r editing
operations. You can execute commands in three ways:
•

E n te r th e command by nam e

•

Click on the appropriate m enu item

•

E n te r th e appropriate key bindings

To en ter a comm and by nam e, press Ctrl/Z. The prom pt “E n te r comm and nam e”
appears in the inform ation area. Type the command nam e and press Return. Ib
cancel a command and clear th e inform ation area, press Ctrl/C.
M any commonly used E ditor commands appear on E ditor m enus. W hen you
execute a n E ditor command by choosing a m enu item , th e resu lt is th e sam e as if
you h ad entered the comm and by nam e.
M any comm ands are bound by default to keys or key sequences. If th e comm and
is bound, you can execute it by entering the key binding.

8—4 U sin g the VAX LISP Editor in D E C w in dow s

For example, th e "Select Outer m o s t Form" comm and selects the text a t the
outerm ost LISP form containing th e cursor. You can execute th is command by
clicking on the Select O uterm ost Form item on the O perations m enu. You can
also ru n this command by entering Ctrl/Z and th e command nam e and pressing
Return. A th ird way to execute the command is to press Ctrl/X Ctrl/Space to which the
comm and is bound. In each case, th e resu lt is the same.
Appendix E contains a complete listing of th e E ditor commands and th eir key
bindings.

8.1.4

Evaluating Work in th e Editor
Before trying out or exam ining your code in another utility, you m u st evaluate
it in the Editor. The "Evaluate l i s p Region" command evaluates a region of
LISP code and tran sp o rts it to th e LISP environm ent, l b execute this command,
select th e region you w ant to evaluate and choose the E valuate LISP Region item
on th e Com m ands m enu. As the E ditor evaluates th e code, it displays m essages
inform ing you of th e sta tu s of the evaluation process. A fter th e code h a s been
evaluated, it is available im m ediately in an o th er LISP utility.
You can also use th e "Write Current Buff e r " and "Write M o d i f i e d Buffers"
comm ands to replace an existing function definition or value w ith a new function
definition or value. "Write C urrent Buffer" affects only the current buffer; th a t
is, the buffer whose window contained th e cursor w hen you e n te r the command.
"Write M o d i f i e d Buff e r s " affects any buffer you have worked on since the la st
tim e the buffer was w ritten. Both these commands are available as m enu item s
on the E ditor’s Com m ands m enu.
E valuating code in th e E ditor provides a w ay to try out functions easily in other
utilities. However, w hen you exit the LISP environm ent, all function definitions
are lost. Therefore, before leaving LISP, be sure to save all function definitions to
LISP files.

8.1.5

Saving Work in th e Editor
l b save your work in a file, choose th e Save As item on the File m enu. Type
th e file nam e and press Return. Saving a file th is way is equivalent to typing the
"Write N a m e d File" command.
If you have already saved your work in a file, th e "Write Cur r e n t Buffer" and
"Write M o d i f i e d Buffers" commands provide an o th er way to w rite a new version
of the file. "Write C urr e n t Buffer" affects only the cu rren t buffer; th a t is, the
buffer whose window contained the cursor w hen you e n te r th e command. "Write
M o d i f i e d Buffe r s " affects any buffers you have worked on since the la s t tim e the
buffer w as w ritten. Both these commands are available as m enu item s on the
E ditor’s Com m ands m enu.
Note th a t if you use these commands when you are editing a function definition
or value, they update the existing function definition or value but do not w rite
th e LISP code to a file.

Using the VAX LISP Editor in DECwindows

8-5

8.1.6

R eturning to LISP
You can leave the E ditor to exam ine or ru n your source code in an o th er utility
by clicking on the desired u tility window. If you evaluated code in the Editor, it
is im m ediately available. If you saved your w ork in a file, you m u st load the file
before you can use it.
W hen you go to another utility, th e E ditor window rem ains on the screen. If you
forgot to save your work, you can re tu rn to th e E ditor window and your file or
function will be still available. However, if you exit th e E ditor w ithout saving
your files and th en exit LISP, th e work you did will be lost.
l b end your editing session, use the E xit item on th e E d ito r’s File m enu. See
Section 8.1.8 for more inform ation on exiting th e Editor.

8.1.7

Returning to the Editor
W hen you leave the E ditor w ithout exiting, th e E ditor keeps open th e buffer
containing your LISP object or file. You can resum e your editing session in the
state you left it and m ake fu rth e r modifications to th e code, by sim ply going to
th e Editor window.
l b s ta rt editing a new file in th e E ditor window, proceed as if you w ere invoking
th e Editor for the first tim e. Choose the Ed item on the File m enu in the L istener
or the Open item on the File m enu in th e E ditor to edit a new file or th e ED item
on the O perations m enu to edit a new LISP object.

8-6

Using the VAX LISP Editor in DECwindows

The E ditor opens an o th er buffer and places th e cursor in th a t buffer. Both the
new buffer and the previously opened buffer appear in the E ditor window in
Figure 8-3.
Figure 8-3:

Editor Window with Two Buffers

IPlEtl

LISP Editor
File

Edit

Commands

Help

— Function CIRCUMFERENCE Forward EDT Emulation ("VAX LISP") —

E;;

;;; Define the ingredients and calories per some-unit-of-measure

(setf (get 'sugar 'calories) 375)
(setf (get 'sugar 'units) "cup")
(setf (get 'milk 'calories) 150)
File recipe.Isp Forward EDT Emulation ("VAX LISP”)

MLO-002972

Each buffer h a s its own window and label strip. The buffer containing the cursor
and the reverse-videoed label strip is currently active. For inform ation on how to
move around in buffers and windows, see Section 8.4.

8.1.8

Exiting the Editor
W hen you exit the Editor, th e E ditor window disappears from the screen and you
a re retu rn ed to the window th a t h ad in p u t focus before th e Editor.
exit the Editor, click on the E xit item on th e File m enu or press Ctrl/Z and en ter
the " E x i t ” command. If you have modified buffers, th e E ditor inform s you th a t
all buffers will be lost and asks if you w an t to continue. If you type Y, th e Editor
displays the nam e of each modified buffer one a t a tim e and asks if you w an t to
save it.

If a buffer contains a file, th e E ditor saves a new version of th e file. If a buffer
contains a function, th e E ditor updates th e function definition. The function
definitions will eventually be lost w hen you exit LISP. Tb avoid th is happening,
w rite any function definitions you w an t to save to files before exiting th e E ditor
as described in Section 8.1.5.

Using the VAX LISP Editor in DECwindows

8-7

8.2

Getting Help
The E ditor provides help through the Help key and the Help m enu. By using the
Help key, you can obtain:
•

G eneral help on the Editor

•

H elp on your current situation

•

Help on prom pts

Through th e Help m enu, you can obtain:

8.2.1

•

Help on VAX LISP

•

Inform ation on E ditor objects

•

Help com pleting responses to prom pts

•

Help on errors

Using th e Help Key
You can press Help a t any tim e to get help on your cu rren t situation. A buffer
called "VAX l i s p E d i t o r General Help" appears. I t contains instructions on how
to move around in a window and betw een windows and how to remove a window
from th e screen. Ib remove th e window containing th is help tex t from the screen,
click on the Remove C urrent Window item on the Commands m enu or press Ctrl/X
Ctrl/R.

If you press Help while th e E ditor is displaying a prom pt—for example, after you
have pressed Ctrl/Z—th e E ditor displays help on th e prom pt. Typically, the help
tex t explains th e prom pt and describes th e options you have. P ress ctrl/v to scroll
through th is help text. The text will disappear from th e screen when you have
entered a response to th e prom pt and pressed Return.

8.2.2

Using the Help Menu
You can use th e Overview and About item s on th e E ditor’s Help m en u to obtain
general help and product inform ation on VAX LISP, ju s t as you can from the
Listener. The E ditor’s Help m enu also provides the specialized help on th e E ditor
as described in th e following sections.

8.2.2.1 Help on Editor O bjects
You can use th e Describe E ditor Object and Apropos E ditor Object item s to obtain
inform ation on E ditor objects. These item s are equivalent to th e "Describe" and
"Apropos" comm ands and a re sim ilar to th e LISP functions of the sam e nam es.
The "Describe" command displays a description of an E ditor comm and

8-8

Using the VAX LISP Editor in DECwindows

(by default) or other E ditor object. The " A p r o p o s " comm and lists all Editor
commands or other specified E ditor objects whose nam es contain a certain string.
For example, using th e "Apropos" command for the strin g “file” produces the
display shown in Figure 8-4.
Figure 8-4: A propos Display

LISP Editor
File

Edit

Help

Commands

Edit File
Insert File
Read File
View File
Write Named File|

Apropos of "file" for object type Command

— Function CIRCUMFERENCE Forward

EDT Emulation ("VAX LISP") —

MLO-002973

You can also obtain descriptions of LISP symbols from th e E ditor when you are
editing LISP code. Use the Describe Word item to invoke th e LISP d e s c r i b e
function on the word a t the current cursor position. Use th e Apropos Word item
to invoke the a p r o p o s function on th e word a t th e c u rren t cursor position.
You can move th e cursor around in the window containing help text. W hen you
are done, use the Remove C u rren t Window item on the Com m ands m enu or Ctrl/X
Ctrl/R to remove this window and re tu rn to editing.
8.2.2.2

Help on R espon ses to Prompts
The E ditor can help you en ter responses to prom pts in two ways. The first way
is in p u t completion. If you press Ctrl/Space while you are typing a response to a
prom pt, th e E ditor will a tte m p t to complete your in p u t for you. The E ditor will
complete as m uch of the in p u t as it can and display the sta tu s of th e completion,
For example, if, to the “E n te r comm and nam e” prom pt, you type th e string
“sh r” followed by Ctrl/Space, th e E ditor will complete the comm and nam e "Shrink
Wind o w " and inform you th a t the in p u t is complete. You can now press Return to
execute the command.

Using the VAX LISP Editor in DECwindows

8-9

If, on th e other hand, you type the string “new” followed by Ctrl/Space, the Editor
will be able to complete the in p u t only as far as “New Li” and will th en inform
you th a t th e in p u t is am biguous, because m ore th an one command sta rts w ith the
string “New Li”.
The second way is by listing alternatives. A t any point w hen entering inform ation
to a prom pt, you can obtain a lis t of th e available alternatives by choosing the
A lternatives item on the Help m enu. This is equivalent to pressing PFl PF2.
The E ditor exam ines w hat you have typed so far and displays a list of all the
comm ands s ta rtin g th a t way. For example, when you have used in p u t completion
to get as far as “New Li”, you can click on the A lternatives item and th e Editor
will display a list of th e comm ands beginning w ith “New Li”. You can choose the
comm and you w ant, en ter enough of it to m ake the in p u t unam biguous, and th en
use in p u t completion Ctrl/Space to complete the command name.
In p u t completion and alternatives provide an alternative way to to fill out file
specifications and obtain a list of all files m atching a p articu lar tem plate. For
example, assum e you w ish to edit an existing LISP file b u t a re unsure of the
nam e. You press Ctrl/Z and e n te r th e " E d i t P i l e " command, which then prom pts
you for a file nam e. You can type “.LSP” a t this point and click on Prom pt Show
A lternatives to see a list of all files in your current directory having th e file type
“LSP”. You can th en edit your in p u t by moving the cursor back to the beginning
of the file specification and typing enough of the file nam e to distinguish it
from other file nam es. P ressing Ctrl/Space a t this point fills in th e re st of the file
specification.
8.2.2.3

Help on Errors and Other Problems
If you m ake a m inor error, the E ditor displays a short erro r m essage in the
inform ation area. If th is error m essage is not enough to help you correct the
problem, use Help on the L ast E rro r item or Ctrl/X ? to display m ore inform ation
on th e error.
If you m ake a m ajor error or if the E ditor encounters a n in tern al erro r from which
it cannot recover, th e E ditor reports the error and asks if you w ish to a tte m p t to
save your work. Depending on the n a tu re and severity of the error, th e E ditor
m ay not be able to save all your work. Section 8.5 contains m ore inform ation on
how to recover from these problems.

8.3 Editing LISP C ode
This section describes the E ditor’s default pointer bindings u n d er DECwindows
and some useful ways to edit LISP code, including:

8-10

•

C utting and pastin g text

•

Finding and replacing text

•

Moving the cursor by LISP forms

•

In sertin g nongraphic characters

•

C hanging case

•

In se rtin g a file or buffer

Using the VAX LISP Editor in DECwindows

8.3.1

Using th e P ointer
U nder DECwindows, th e E ditor’s default pointer bindings have been changed
from previous versions of VAX LISP to be compatible w ith the DECwindows style.
Table 8-1 shows th e E ditor’s default pointer bindings u n d er DECwindows.
Table 8-1:

Editor Default Pointer Bindings

Action

Binding

Click MB1

Positions th e tex t cursor.

P ress an d d rag MB1

Selects a region of text.

Click MB3

Copies th e c u rren t prim ary selection to th e click point
an d repositions th e tex t cursor.

P ress an d d rag MB3

Selects th e secondary select region.

Release MB3

Copies th e secondary select region to th e active tex t
insertion point.

MB2 is not bound by default as it is reserved for pop-up m enus. You are still
able to bind E ditor commands to MB2. F or fu rth e r inform ation, see th e VAX
L I S P /V M S E d ito r P ro g ra m m in g G u ide. P ressing MB3, dragging the pointer, and
releasing causes th e secondary selection region (denoted by underlining) to be
copied to th e active tex t insertion point in any other DECwindows application
(including other LISP windows) th a t accept secondary selection input. Note th a t
th is does n ot include th e E ditor window. Form al descriptions of the E ditor pointer
binding comm ands are in P a rt III of the V AX L I S P /V M S E d ito r P ro g ra m m in g

G u id e.

If you w a n t to use the UIS pointer binding syntax, you can change to it w ith
th e set u is P o i n t e r S y n t a x command. To change from th e UIS pointer binding
syntax to th e DECwindows pointer binding syntax, use the Set D E C w i n d o w s
P o i n t e r Syn t a x command.

8.3.2

Cutting and Pasting Text
You can select text and move it to another location w ithin th e E ditor window
or an o th er LISP u tility . You s e l e c t and move th e text by using MB1 or MB3 (see
Section A. 16) or by selecting one of the following on the E dit m enu:
Select All
Select Enclosing
Form

Selects all text in the buffer.
Selects the text of the innermost LISP form containing the cursor.
Equivalent to using the "Select E n c l o s i n g Form" command.

Select
Outermost
Form

Selects the text of the outermost LISP form containing the cursor.
Equivalent to using the "Select O u t e r m o s t Form" command.

N ext, select th e Cut or Copy item from th e E dit m enu. Position th e cursor where
you w a n t to in se rt th e text. Click on P aste in the window, utility, or application
to which you are moving th e text. For example, if you are m oving text from the
E ditor to the Listener, click on P aste on the L isten er’s E d it m enu.

Using the VAX LISP Editor in DECwindows

8-11

8.3.3 Finding and Replacing Text
You can use the Search m enu to search through a tex t region for an occurrence of
tex t or to replace a specified tex t string w ith another.
Tb search for text, choose th e Find item from the Search m enu and type the text
strin g you w an t when the E ditor prom pts you.
The E ditor searches in th e direction specified. If th e text is found, th e cursor
appears a t th e beginning of the text string and the text string is highlighted. If
th e tex t is not found, you receive a m essage. Ib find th e next occurrence of the
sam e string, choose Find N ext or Find Previous from th e Search M enu. If there
is no current search string, the Find N ext and Find Previous item s are dimmed.
Tb replace text, select the Replace . . . item . Type the nam e of the old string and
th e new string w hen th e E ditor prom pts you. A t each occurrence of the search
string, the E ditor prom pts you for a search string and a replacem ent string. You
can answ er as follows:
|

Is p a c e

Replace this occurrence and m ove to the next one.

l~s~|

Replace this occurrence and stay here. This option le ts you see the
resu lts of the change before m oving on. U se N to m ove to th e next
occurrence.

[—1

Replace this occurrence and term in ate th e command.
Replace this occurrence and all rem aining occurrences w ithou t further
querying.

In |

Do not replace th is occurrence and find th e n ext occurrence.

|cwc|

Do not replace th is occurrence and term in ate th e command.

Io I

Do not replace th is occurrence and term inate the operation, returning
th e cursor to the point at which the search began.

1~R~I

Enter a recursive edit, w hich you term inate w ith th e "Exit
Recursive Edit" command. The recursive ed it lets you clean up
a replacem ent site w ithout losing your place in the search cycle.

r?~l

D isplay help on th e possible responses to the queiy.

8.3.4 Moving in LISP Code
You can use E ditor commands to move around by LISP forms. The comm and
"Next l i s p Form" and th e comm and "Previous l i s p Form" move the cursor from
form to form w ithin th e cu rren t p arentheses n esting level. The com m and "End
of Outermost Form" moves the cursor to th e end of th e cu rren t or next outerm ost
LISP form. The comm and "Beginning of Outermost Form" moves th e cursor to
th e beginning of the cu rren t or previous outerm ost LISP form.
Four other comm ands let you move in lists. By default, no key sequences are
bound to them . They are:
Backw ard Up List
Forw ard Up L ist
Beginning of L ist
E nd of List
For inform ation on how to bind these key sequences to comm ands, see
Section 8.6.1.

8 -1 2

Using the VAX LISP Editor in DECwindows

8.3.5 Inserting Nongraphic Characters
You cannot in sert some characters directly into your text. For example, you
cannot in se rt a # \ Ax character by pressing Ctrl/X because th e E ditor in terp rets
th a t character. The E ditor provides two ways around th is problem. In m ost cases,
you can use Ctrl/X \. Then th e E ditor takes the next character you type and in serts
it w ithout interpretation. This procedure handles the case of # \ Ax, for example;
you type:
|CM/X|

|~\— 1

ICtrl/X I

The E ditor echo for this is:
<Ax>
In general, th e E ditor display for a nongraphic character is the LISP rep resen ta
tion for th e character, surrounded by angle brackets w ithout th e leading # \. For
example, th e E ditor graphic display for #\ Ax is <Ax>.

8.3.6 Changing Case
You can use E ditor commands to change th e case of alphabetic characters in your
text. N onalphabetic characters are not affected.
Four comm ands th a t let you m ake all the alphabetic characters in a select region
or word be of one case are "Upcase Region", "Upcase Word", "Downcase Region",
and "Downcase Word". To use the commands th a t affect a region, define the select
region, press Ctrl/Z, and en ter the command. To use the com m ands th a t affect
a word, position the cursor anyw here in th e word, press Ctrl/Z, and e n te r the
command.
Finally, the "Capitalize word” command m akes the first character of a word
uppercase. Position th e cursor anyw here in the word, press Ctrl/Z, and e n te r the
command.

8.3.7 Inserting a File or Buffer
You can in se rt the contents of a file or a buffer a t th e cursor location, using the
"Insert File" or "Insert Buffer" command.
l b in se rt th e contents of a file, choose the Include item on th e File m enu. The
E ditor prom pts you for a file nam e. Type th e nam e of th e file and press Return.
The E ditor in serts the contents of th is file a t the cursor location. You can use the
A lternatives item or request in p u t completion w ith Ctrl/Space w hile responding to
th is prom pt. U sing th e Include item is equivalent to typing the "insert File"
command.
Tb in se rt a buffer, click on the In se rt Buffer item on the Com m ands m enu. The
E ditor prom pts for the nam e of a buffer a n d th en in serts th e contents of the
buffer a t the cursor location. You can use th e A lternatives item or req u est in p u t
completion w ith Ctrl/Space while responding to th is prom pt. Section 8.4 contains
m ore inform ation about buffers.

Using the VAX LISP Editor in DECwindows

8-13

8.4

Using Multiple Buffers and Windows
The E ditor can keep track of m ore th a n one LISP object or file a t a tim e.
The E ditor holds each object or file th a t you are currently editing in a buffer.
Com m ands let you move betw een buffers, create new buffers, and gain access to
buffers through windows on the E ditor window.

8.4.1 Introduction to Buffers and Windows
Buffers are E ditor objects th a t contain the text of the symbol or file th a t you are
editing and some inform ation about the text—for example, the position of the
cursor w hen the text is displayed. The E ditor displays the contents of buffers
through windows inside the Editor window. The E ditor can keep track of m any
buffers a t once, b u t norm ally displays the contents of no more th a n two buffers a t
a tim e.
E ach tim e you invoke the Editor w ith an argum ent, th e E ditor creates a buffer
having the same nam e as the file or LISP object you specify.
The buffer m ost recently created is th e cu rren t window. If you type characters
or enter E ditor commands, th e buffer viewed through th e cu rren t window will be
affected.
To m ake another window current, click on it. The cursor moves to the position
occupied by the mouse. You can also change the cu rren t window by using the
N ext Window item on the Commands m enu (or Ctrl/X Ctrl/N), which m akes each
window on the screen cu rren t in tu rn . W hen you change from one window to
another th is way, the cursor moves to the position it occupied w hen you la st
edited in th a t window.
Windows th a t display tex t you are editing are called anchored windows, because
they are fixed a t a particu lar spot inside the E ditor window. Unless you use the
S plit Window item or the "split window" command, the E ditor can by default
display no m ore th a n two anchored windows a t once.
However, you can have more th a n two LISP objects or files available for editing
a t once, each occupying its own buffer. To obtain a listing of all th e buffers in the
Editor, use the List Buffers item on the Com m ands m enu or th e "List Buffers"
command. For example, if you had invoked th e E ditor on a function and la te r a
file, "List Buffers" m ight re su lt in the display shown in Figure 8—5.

8-14 Using the VAX LISP Editor in DECwindows

Figure &-£:

List Buffers Display

LISP Editor
File

Edit

[puffer Name

Rl m

Commands

Help

Iiines/Chars

Status

Empty
General Prompting
Modified
Basic Introduction
2/58
Modified
Empty
Writable
Kill Ring
CiKLijrtE'jERENCE
Writable
Empty
Function of symbol CXRCUMFERENUE
8/409
Modified
Help
93/2717
Writable
recipe.lsp
I<1SPW$; [JONES.LISP]RECIPE.LSP;2

Ckpting

Permanent

No
No
No
NO

Yes
Yes
Yes
No

No
Yes

Yes
NO

Listing of available editor buffers
— Function CIRCUMFERENCE Forward EDT Emulation ("VAX LISP")—
r rr

;;; Define the ingredients and calories per some-unit-of-measure
rrr

(setf
(set f
(setf
(setf
(setf

(get
(get
(get
(get
(get

'sugar 'calories) 375)
'sugar 'units) "cup")
'milk 'calories) 150)
'milk 'units) "cup")
'butter m'units) "oz")

----- File RECIPE.LSP Forward

EDT Emulation ("VAX LISP")-----

M L O -0 0 2 9 7 4

The buffers holding the objects and files th a t you are editing are identified by an
additional line detailing th e contents of the b u ffe r . For example, the buffer nam ed
c i r c u m f e r e n c e contains th e line “Function of symbol CIRCUM FERENCE”. The
o ther buffers listed contain E ditor inform ation.
You can select a buffer for editing th a t is not currently on th e screen by using th e
Select Buffer item on th e Commands m enu or th e "Select Buffer" command.
The E ditor prom pts for th e nam e of a buffer to edit. You can type p a rt of the
nam e, th en use Ctrl/Space to request th a t the E ditor fill in the re s t of th e nam e. If
you do not know which buffers are available, choose A lternatives to see a list of
th eir nam es.
W hen you select a buffer from among those not currently displayed, th e Editor
displays it in a new anchored window. If two anchored windows a re already
there, th e E ditor rem oves th e older one and replaces it w ith one displaying the
contents of th e buffer ju s t selected.
Removing a window from the E ditor window does not delete or modify the
contents of the buffer. Removing a window simply causes th e corresponding
buffer to be no longer displayed, u n til the next tim e you select it. You can use th e
Remove C urrent Window item or Ctrl/X Ctrl/R to rem ove th e c u rren t window from

Using the VAX LISP Editor in DECwindows S-15

th e screen and the Remove O ther Windows item or th e " R e m o v e o t h e r w i n d o w s "
command to rem ove all windows other th a n th e cu rren t window from the screen.
In addition to anchored windows, th e E ditor also h as floating windows. Floating
windows m ay be displayed anyw here in the E ditor window, overlaying and
obscuring th e anchored windows th a t he u n d er the floating windows. The window
in which help appears is a floating window. For the purpose of commands, these
windows a re ju s t like anchored windows. You can choose N ext Window to move
the cursor to them in tu rn , Remove C u rren t Window to remove them when they
are current, and Remove O ther Windows to rem ove them w hen they are not
current.

8.4.2 Creating New Buffers from Within the Editor
You do not need to re tu rn to LISP to create a new buffer. You can use one of
the following ways to s ta r t editing new LISP objects or files w ithout leaving the
Editor.
Select the Open item from the File m enu. The E ditor prom pts you for a file name.
You can use PF1 PF2 to see a list of files. Type in a file nam e. W hen you press
Return, the E ditor opens a new buffer and window for th a t file. U sing the Open
item is equivalent to entering the " E d i t F i l e " command.
To create a read-only buffer from w ithin th e Editor, choose the View item and
answ er the prom pts.
The " E d " command provides an o th er m ethod of creating a new buffer w ithin the
Editor. The " E d " comm and works in the sam e way as th e e d function. W hen you
type " E d " , th e E ditor prom pts for each of the argum ents th a t you would enter
to the e d function. If you supply a symbol nam e, the E ditor asks you to specify
w h ether you w an t to edit the function definition or th e value of th e symbol. If you
supply a character strin g containing a file specification, th e E ditor sta rts editing
th a t file.

8.4.3 Working with Buffers
Buffers generally take care of them selves. The only three common situations in
which you need to deal directly w ith buffers are:
•

W hen you need to save th e contents of a buffer

•

W hen you need to delete a buffer

•

W hen two buffers have conflicting nam es

Buffers m ain tain some inform ation about the sta te of your editing session w ith
regard to the LISP object or file contained in the buffer. Specifically, a buffer
keeps track of:
•

The position of th e cursor in th e te x t

•

The select region, if one is active

•

Key bindings, if any keys are bound in th e context of th e buffer (see
Section 8.6.1.4)

•

The m ajor and m inor styles th a t a re active in th a t buffer (see Section 8.6.1.3)

This inform ation ensures th a t, w hen you select a buffer you worked on previously,
it will be in the sam e sta te as it was w hen you left it.

8—16

Using the VAX LISP Editor in DECwindows

8.4.3.1

Saving Buffer Contents

You can use three commands to save buffer contents. The " W r i t e c u r r e n t
B u f f e r " and " W r i t e M o d i f i e d B u f f e r s " com m ands (discussed in Section 8.1)
save the contents of th e single cu rren t buffer and of all buffers th a t have been
modified, respectively. The th ird way to save buffer contents is to use the Exit
item or " E x i t " command and request th a t modified buffers be saved.
W hen you leave th e E ditor window to work in another utility, your buffers are not
w ritten, b u t they are available to you w hen you resum e th e Editor. If, however,
you should leave th e E ditor and th en exit LISP, the contents of your buffers will
be lost. Section 8.5 explains how you can partially recover from th is situation.
S.4.3.2

Deleting Buffers
You can use two commands to delete buffers. The " D e l e t e C u r r e n t B u f f e r "
deletes th e buffer you are currently working on; " D e l e t e N a m e d B u f f e r " prom pts
for a buffer nam e and deletes th a t buffer. Both comm ands check to see if the
buffer has been modified and, if it h as been, ask if you w an t to w rite tn e buffer
before deleting it.
If you are editing an existing file and you delete the buffer associated w ith the
file, the E ditor does not delete the file. However, the E ditor also does not create
a new version of the file. For example, if you a re editing th e file RECIPE.LSP;1
and you delete the buffer " r e c i p e . l s p " , the file R E C IPE .L SP jl is not deleted.
However, the file RECIPE.LSP;2, which would have been created if you had saved
th e buffer contents, is not created.

8.4.3.3

Buffer Name Conflicts
The E ditor requires th a t buffer nam es be unique. This requirem ent can cause a
problem in the following situations:
•

You are trying to edit the function definition and th e value of th e sam e
symbol.

•

You a re trying to edit two files having th e sam e nam e and type b u t differing
in some other respect (version num ber, directory, and so on).

W hen your a tte m p t to edit som ething creates a buffer nam e conflict, th e E ditor
requests a new buffer nam e. You c a n t y p e i n a n y n a m e you like. However, if
you should type in no nam e and ju s t press Return, the E ditor deletes the current
contents of the buffer, replacing them w ith w hatever you a re try in g to edit.

8.4.4

Manipulating Editor Windows
The commands m ost commonly used to m anipulate windows have already been
presented in th is chapter:
to m ake th e next window th e c u rren t window

•

" N e x t w in d o w "

•

"R e m o v e C u r r e n t W indow "

to rem ove th e cu rren t window from th e screen

"R em ove o t h e r w in d o w s "

to remove windows other th a n th e c u rren t window

•

from th e screen
O ther comm ands le t you m anipulate windows in other ways.

Using the VAX LISP Editor in DECwindows

8-17

The " G r o w w i n d o w " and " S h r i n k w i n d o w ” comm ands m ake th e current window
larg er and smaller, respectively. If no prefix argum ent is set, they m ake the
window one line larger or smaller. If a prefix arg u m en t is set, they m ake the
window larg er or sm aller by the num ber of lines specified in the prefix argum ent.
The " S p l i t w i n d o w " command or th e Split Window item on th e Commands m enu
let you open two or m ore windows on a single buffer. The command causes
th e current window to be split in two, w ith identical text appearing in the two
windows. Once created, the two windows can be tre a te d as ordinary windows;
th e w indow-m anipulation commands move betw een the two windows and remove
them in the norm al fashion. Each window m ain tain s its own cursor position
and scrolls separately from the other; but, if you type or edit in one window, the
change will appear in th e other as well.
S plit windows are useful if you w ant to exam ine two p a rts of the sam e buffer a t
one tim e, or if you w ant to move text from one place to another in a buffer. To
move text, you would delete it or cut it in one window, move to th e other window,
and undelete the text or paste it.
You can have more th a n two windows on a buffer; ju s t use " S p l i t w i n d o w ”
repeatedly. The num ber of windows is lim ited only by th e size of the screen; each
window m u st have a t least one line.
A lthough th e " S p l i t w i n d o w " command initially creates two windows on the
sam e buffer, you can cause one of those windows to switch to another buffer. Use
th e " S e l e c t B u f f e r " command and specify a buffer not currently displayed in a
window. By repeatedly splitting windows and selecting new buffers, you can view
as m any buffers as you can fit windows in the E ditor window.

8.4.5 Moving Text Between Buffers
You can move or copy text from one buffer to another. For example, if you have
worked on the definition of a function, you can move it to a buffer in which you
a re editing a file. Two ways of doing this are:
•

Delete or cut the text from the source buffer, change to the destination buffer,
and undelete or paste the text in the destination buffer

•

Use the In se rt Buffer item or the " in s e r t B u ffer" comm and to in se rt an
entire buffer in another.

8.5 Recovering from Problems
The E ditor provides facilities th a t let you recover from problem s w ith all or
m ost of your work intact. Section 8.2.2.3 describes how th e E ditor responds to
m inor errors. This section describes checkpointing, by m eans of which the E ditor
protects work in progress.
W henever you are editing a file, th e E ditor periodically m akes a copy of th e
c u rren t sta te of th a t file. The copy is a separate disk file, called th e checkpoint
file. It h a s th e sam e nam e as the file you are editing, and a file type composed as
follows:
type_version_L SC

w here ty p e and versio n are th e file type and version num ber, respectively, of the
file you a re editing. For example, if you are editing th e file RECIPE.LSP;2, the
associated checkpoint file will be nam ed RECIPE .LSP_2_LSC.

8-18

Using the VAX LISP Editor in DECwindows

W hile you a re using the E ditor or the LISP interpreter, a n error m ay occur th a t
re tu rn s you to DCL, or you m ay inadvertently exit LISP w ithout first saving
your E ditor buffers, or th e system m ay crash. In any of these cases, the current
sta te of your E ditor w ork is lost. However, the checkpoint files for any files you
w ere editing still rem ain, reflecting th e sta te of those buffers a t the la st tim e
th a t checkpointing took place. To use a checkpoint file after you have lost the
associated buffer, change its file type back to LSP. Then use the E ditor to edit the
file.
W hen checkpointing a file, the E ditor displays the m essage “Checkpointing...”
in the inform ation area. You can continue to type while checkpointing is taking
place b ut w hatever you type will not be displayed until checkpointing is complete.
By default, th e E ditor checkpoints after every 350 comm ands th a t a lte r text in
buffers. (Each keystroke th a t in serts a text character counts as a command.)

8.6 Customizing the Editor
You can customize th e E ditor by binding keys or key sequences to commands.
You can bind keys to comm ands th a t have no default bindings or change default
bindings th a t exist. Section 8.6.1 describes how to bind keys to commands.
You can define keyboard m acros to execute a series of keystrokes such as
in sertin g key bindings th a t invoke commands. Section 8.6.2 describes how to
define keyboard macros.

8.6.1

W hile using th e Editor, you can use the " B i n d C o m m a n d " command.

•

W hile using the LISP interpreter, you can use the b in d - c o m m a n d function.
Your LISP initialization f i l e can contain calls to b in d - c o m m a n d to set up the
Editor.

These two m ethods a re discussed in Section 8.6.1.1 and Section 8.6.1.2, respec
tively.
No m a tte r how you bind keys or key sequences to commands, th ere are two pieces
of inform ation you m u st supply and a th ird th a t you m ay supply:
•

You m u st supply th e nam e of th e command to be invoked.

•

You m u st supply th e key or key sequence to bind to th e command.
Section 8.6.1.1 and Section 8.6.1.2 describe how to specify the key or key
sequence. Section 8.6.1 describes how to select a key or key sequence to bind.

•

You can optionally supply the context in w hich the binding is effective.
Section 8.6.1.4 explains th e key binding context.

Using the VAX LISP Editor in DECwindows

8-19

8.6.1.1

Binding Within the Editor
The " B i n d C o m m a n d " comm and lets you bind a key or key sequence to a command
while using th e Editor. This com m and prom pts you for each of th e three item s
you need to specify a complete binding.
The " B i n d C o m m a n d " comm and first prom pts you for th e nam e of th e command
you w ish to have bound. You can use in p u t completion and alternatives to get a
complete command nam e.
The second prom pt is for th e key sequence. Type the actual key or key sequence
th a t you w an t to bind to the command — n ot a LISP representation of the charac
ters. However, you cannot type control characters or function keys unless you use
Ctrl/X \ to quote them . Since m ost bindings involve control characters or function
keys, you will tend to use Ctrl/X \ m ost of the tim e.
For example, assum e th a t you w an t to bind Ctrl/X Ctrl/O to a command. Both Ctrl/X
and Ctrl/O a re control characters so they m u st both be quoted. In response to the
“E n te r key sequence” prom pt, you would type:
| C tr l/ X | m

[ctri/xl

fciri/xl

C D

|C t r l / O |

A fter you completed th is sequence, the prom pting area would ap p ear like this:
< AX X A0 >

Function keys, arrow keys, a n d keys on the num eric keypad m u st also be quoted.
Each of these keys generates m ore th a n one character w hen it is struck, so m ore
th a n one character appears in the prom pting area. For example, to bind the F12
key to a command, you would type:
[ C tr i/ X l

[ F 1 2l

This sequence is echoed in th e prom pting area as:
<ESCAPE>[ 2 4 -

The th ird prom pt is for th e binding context. The context can be : g l o b a l (the
default) or a p articu lar style or buffer. Type : s t y l e or : b u f f e r , followed by Return,
to specify one of these options. The E ditor th en prom pts for th e nam e of th e style
or th e buffer. (See Section 8.6.1.4 for more inform ation on binding context.)
8.6.1.2

Binding from the LISP Interpreter
The b in d - c o m m a n d function lets you establish key bindings while you are using
th e LISP interpreter, b in d - c o m m a n d is especially useful in your LISP initialization
file to set up the bindings you use all th e tim e.
The b in d - c o m m a n d function tak es three argum ents. The first argum ent is th e
nam e of th e command you w ish to have bound, in th e form of a character string.
The second argum ent is the key or key sequence th a t is to invoke th e command.
A single key m ay be given as a LISP character. A key sequence m u st be given as
a vector or list of characters.
For all th e keys on the m ain p a rt of the keyboard—those keys th a t produce
letters, num bers, and other prin tin g symbols—you m ay use any valid LISP
representation of th e character. For example, “A” is #\A, “a ” is # \ a , and “Ctrl/A”is
# \ ■'A. The LISP function c h a r - n a m e - t a b l e displays a table of th e LISP nam es for
control characters.

8-20

Using the VAX LISP Editor in DECwindows

The rem aining keys on th e keyboard—th e num eric keypad, arrow keys, edit
ing keys, and function keys—tra n sm it m ore th a n one character w hen struck.
Table 8 -2 lists each key a n d th e character sequence it generates.
Some of th e function keys on th e LK201 keyboard are commonly associated w ith
p articu lar characters. For example, the FI 2 key is associated w ith Backspace and
th e FI 3 key w ith Linefeed. However, these function keys do not actually tra n sm it
these characters, and th e E ditor does not tre a t them as having tran sm itted these
characters.
Table 8-2: Characters Generated by Keys
Key

Characters Generated
Numeric Keypad Keys (LK201 and VTlOO)

k e y p ad PH

# \E S C A P E

# \

0 # \p

k e y p a d H~l

# \E S C A P E

# \

0 # \q

k e y p a d IT]

# \

ESCAPE # \ 0 # \ r

k e y p a d [~3~|

# \

ESCAPE # \ 0 # \ s

k e y p a d |T1

# \

ESCAPE #\0 # \ t

k e y p a d l~ s]

# \

ESCAPE #\0 #\u

k e y p a d fT|

# \

ESCAPE #\0 # \ v

k e y p a d [T]

# \

ESCAPE # \ 0 # \ w

k e y p a d FT]

# \

ESCAPE #\0 # \ x

k e y p a d IT)

# \

ESCAPE # \ 0 # \ y

keypad Q

# \

ESCAPE #\0 #\m

keypad Q

# \

ESCAPE # \ 0 # \ 1

k e y p a d [~ ~ l

# \

ESCAPE #\0 # \ n

k e y p a d 1E n ter |

# \

ESCAPE #\0 #\M

k e y p a d | p fi|

# \

ESCAPE #\0 # \ P

k e y p a d [ p fz ]

# \

ESCAPE# \ 0 # \ Q

k e y p a d |PF3|

# \

ESCAPE #\0 #\R

k e y p a d |p f4 |

# \

ESCAPE #\0 # \ S

Arrow Keys (LK201 and VTlOO)
ED

# \E S C A P E # \ [ # \ A

# \E S C A P E # \ [ # \ B

#\E S C A P E # \ [ # \ C

# \E S C A P E # \ [ # \ D

(continued on next page)

Using the VAX LISP Editor in DECwindows

S-21

Table 8-2 (Cont.):

Characters Generated by Keys

Key

Characters Generated
Function, HELP, and DO Keys (LK201)

# \E S C A P E # \ [ # \ 1 # \ 7 # \ ~

#\E S C A P E # \ [ # \ 1

#\E S C A P E # \ [ # \ 1 # \ 9 # \ ~

# \ 8

# \~

# \ E S C A P E # \ [ #\ 2 # \ 0 # \ ~

F51

# \ E S C A P E # \ [ #\ 2 # \ 1 # \ -

EÜ

# \ E S C A P E # \ [ # \ 2 # \3

# \ E S C A P E # \ [ #\2 # \ 4 # \ ~

# \E S C A P E # \ [ # \ 2 # \ 5 # \ ~

# \ E S C A P E # \ [ #\2 # \ 6 # \ ~

|H5p|(|Fi5|)

# \E S C A P E # \ [ # \ 2 # \ 8 # \ ~

|55| (F ie l)

# \ E S C A P E # \ [ #\2 # \ 9 # \ ~

# \E S C A P E # \ [ # \ 3 # \ 1 # \ ~

# \E S C A P E # \ [ # \ 3 # \ 2 # \ ~

# \E S C A P E # \ [ # \ 3 # \ 3 # \ ~

E H

* \

ESCAPE # \

[ # \ 3

# \

#\~

4 # \~

E diting Keys (LK201)
S ( 1 H ] )
| In s e r t H e r e | (. |E2
| R e m o v e | ( |E3

])

| s 5 i5 5 1 ( P )
| P r e v S c r e e n | ( [E5])
| N e x t S c r e e n | ( |E6|)

# \

ESCAPE # \

[

# \1

# \ ~

# \

ESCAPE # \

# \ 2

# \~

# \

ESCAPE # \

[ # \

3 # \~

# \4 # \ ~
# \ ESCAPE # \ [ # \5 # \ ~
# \ ESCAPE # \ [ # \6 # \ ~
# \

ESCAPE # \

[

The th ird arg u m en t to BIND-COMMAND, which is optional, specifies the binding
context. If you om it this argum ent, the context is global; th a t is, the key binding
is effective everyw here in th e Editor. If you include th is argum ent, supply it in
th e form
’
(:STYLE "style-name")

or
’
(:BUFFER "buffer-name")

Section 8.6.1.4 describes binding context in m ore detail.
The following exam ple binds Ctrl/X Ctrl/O to the "Remove o t h e r Windows" command
globally:
(bind-command "remove o t h e r windows" '#(#\^X # \ A0))

Alternatively, you could globally bind th e key sequence PF1 Remove (the Remove key
is on the LK201’s editing keypad) to "Remove o t h e r Windows" as shown here:
(bind-command "remove o t h e r windows"
' # (#\escape #\0 #\P # \ e s c a p e # \ ([ #\3 #\~))

8-22

Using the VAX LISP Editor in DECwindows

Tb bind the F12 key on an LK201 keyboard to the " e d t B a c k t o s t a r t o f L i n e "
command in the " e d t E m u l a t i o n " style, you use th e following function:
(b in d -co m m an d

"ed t back to s t a r t o f lin e "
' # (# \e s c a p e # \ [ # \2 # \4 # \~ )
' ( : s ty le "e d t e m u la tio n "))

Following execution of th is function, the F12 key moves th e cursor to the beginning
of the line, b ut only if the "E DT E m u l a t i o n " style is active. (This binding is in
effect by default.)
8.6.1.3

Selecting a Key or Key Sequence
You can bind alm ost any key or key sequence to a command, b u t you should be
careful th a t your selection does not interfere w ith E ditor operation. This section
explains restrictions and provides h in ts to help you m ake a selection.
The th ree control characters you m u st not include anyw here in a key sequence
are:
•

The cancel character, Ctrl/C by default, which term in ates an E ditor operation.
You cannot include Ctrl/C in a key sequence because typing Ctrl/C a t any tim e
stops th e collection of keystrokes and re tu rn s th e E ditor to th e end of th e last
completed command.

•

Ctrl/S and Ctrl/Q, which are in terp reted by th e operating system (they stop
output to th e term inal and resum e it, respectively) and therefore never reach
the E ditor for interpretation.

You should not use any graphic (printing) character to s ta r t a key sequence,
although you can use graphic characters elsew here in th e sequence. If you s ta rt
a key sequence with, say, the le tte r A, you will never be able to type the lette r
A as p a rt of a word. The Editor, a s soon as it sees the A, will recognize it as the
beginning of a key sequence; unless the next character(s) completes the sequence,
th e E ditor will signal a n error and discard th e A.
W hen you include a n alphabetic character in a key sequence, rem em ber th a t
th e E ditor differentiates betw een uppercase and lowercase. For example, th e
following two key sequences a re different:
' # ( # \ AX # \ A )
'# ( # \~ X # \ a )

By convention, the three keys used to s ta rt a key sequence a re Ctrl/X, ESCAPE,
and keypad PF1. You can, of course, use others if you choose, as long as they are
nonprinting. (On keyboards th a t do not have a n ESCAPE key, Ctrl/[ tran sm its the
# \ E S C A P E character.)
Finally, be careful not to select a key or key sequence th a t is already bound to
a useful command. Appendix E contains a list of all th e key bindings supplied
w ith the Editor. Section 8.6.1.4 explains how a single key or key sequence can be
bound to two different comm ands in different contexts.
8.6.1.4

Key Binding Context and Shadowing
W hen you bind a key or key sequence to a command, you can specify th e context
in which th a t binding is effective. Specifying a context m eans th a t th e key or key
sequence invokes th e com m and only in th a t p a rticu la r context.
The three general types of context are:
•

The buffer context. If th e context is a p articu lar buffer, th e key or key
sequence invokes th e comm and only if th a t buffer is current.
Using the VAX LISP Editor in DECwindows 8-23

•

The style context. If the context is a particu lar style, th e key or key sequence
invokes the comm and only if th a t style is th e m ajor style or one of the m inor
styles th a t is active in the cu rren t buffer.

•

The global context. If the context is global, th e key or key sequence always
invokes the command. The default context is global.

Styles
A style is a collection of key bindings and of other E ditor characteristics th a t
causes the E ditor to behave in a certain way. The two styles th a t you encounter
in th e default E ditor are nam ed " e d t E m u l a t i o n " and "VAX l i s p " . The " e d t
Em u l a t i o n " style causes th e num eric keypad to generate editing actions sim ilar
to those of EDT. The " v a x l i s p " style provides access to the E ditor’s ability to
edit LISP code easily.
An E ditor buffer can have one m ajor style and one or m ore m inor styles active a t
any tim e. You can tell which styles are active by looking a t the label strip for the
buffer. See Section 8.1.1.1.
The m ajor style is generally established before th e E ditor is started. M inor styles
are activated autom atically, depending on w hat is being edited. For example,
w henever you edit a LISP object or a file having the type LSP, the " v a x l i s p "
style is activated for th a t buffer as a m inor style.
Shadowing
It is possible to bind th e sam e key or key sequence to two different commands. If
th e contexts of the two bindings are the same, th en the second binding replaces
th e first one. If, however, the two bindings have different contexts, then the key
or key sequence m ay invoke e ith e r command, depending on the situation a t the
tim e. I b locate a comm and to execute w hen a key is pressed, th e E ditor first
checks to see if th a t key is:
1.
2.
3.

Bound in th e context of the current buffer.
Bound in th e context of one of the cu rren t m inor styles, exam ining the m ost
recently activated style first.
Bound in th e context of th e current m ajor style.

B o u n d in th e g lo b al c o n te x t.

As soon as the E ditor finds a command to execute, it does so. Therefore, if th e
sam e key or key sequence is bound in, say, the current m inor style and the
cu rren t m ajor style, th e binding in th e m inor style shadows, or takes precedence
over, the binding in the m ajor style.
For example, the Ctrl/J key is bound to " e d t D e l e t e P r e v i o u s W o r d " in the "EDT
style and to "N ew l i s p L i n e " in the "VAX l i s p " style. W hen you
are editing LISP code, " e d t E m u l a t i o n " is the m ajor style and " v a x l i s p " is
th e m inor style. Therefore, the binding of Ctrl/J to "N ew l i s p L i n e ” shadows the
binding to "E DT D e l e t e P r e v i o u s W o r d " .
E m u la tio n "

8.6.2

Keyboard M acros
A keyboard m acro is a series of keystrokes th a t you ask th e E ditor to rem em ber
for fu tu re use. The keystrokes can be keys th a t in sert characters, keys or key
sequences th a t invoke editing comm ands, or even commands th a t you type in and
th a t issue additional prom pts. A keyboard m acro is useful w henever you have a
series of identical, complicated operations to perform.

8-24

Using the VAX LISP Editor in DECwindows

l b begin a keyboard macro, type Ctrl/X (. E verything you type from th a t point
is executed normally, b u t is also stored for fu tu re use. Typing Ctrl/X ) stops
th e storage of keystrokes, l b execute a keyboard macro, type Ctrl/X Ctrl/E. This
sequence causes the current keyboard m acro to be played back sta rtin g a t the
cu rren t cursor location. A keyboard m acro th a t you define in this way lasts until
you define another keyboard macro.
You can also use the " s t a r t N a m e d K e y b o a r d M a c r o " comm and to define a key
board m acro having a nam e. Use th e " s t a r t N a m e d K e y b o a r d M a c r o " command as
you would the Ctrl/X ( key sequence. The command prom pts you for a nam e. After
you enter the nam e, th e E ditor sta rts rem em bering keystrokes. Tterminate the
m acro w ith Ctrl/X ). The m acro th u s defined is th e current keyboard m acro (you can
invoke it w ith Ctrl/X Ctrl/E) b u t it is also a nam ed en tity th a t you can tre a t like a
command. You can execute it as a nam ed command or bind a key to it. A nam ed
keyboard m acro rem ains accessible by nam e even after an o th er keyboard macro
h a s been defined.
A keyboard macro m ay not work properly if the context changes betw een the tim e
th e m acro is created and the tim e it is executed. For example, if you switch to
a buffer th a t has a different m inor style active, th e com m ands invoked by the
keyboard macro m ay fail.

Using the VAX LISP Editor in DECwindows

8-25

Chapter 9

Using the VAX LISP Inspector
The VAX LISP Inspector, a u tility ru n n in g u n d er DECwindows, is used to
exam ine and modify static d a ta structures. The Inspector displays a n object’s
type and components. You can th en select additional objects from this display,
inspect them in tu rn , modify th e modifiable components, and re tu rn the modified
values to th e form in which you called th e i n s p e c t function.
This chapter describes the following operations:
•

Invoking the Inspector

•

Exiting the Inspector

•

Inspecting objects

•

Modifying objects

•

U pdating the Inspector display

•

R eturning a value from th e Inspector

Figure 9 -1 shows the Inspector’s pull-down m enus.
Figure 9-1: inspector Menus

History W indow

Inspect W indows

_________ a .________

■\

Commands
Inspect
Return
C lose
Remove
Lock
Exit Inspector

® 1 Edit
1Copy

'T - f

r
Commands

Edit

Inspect
Update
Modify
Return

Undo
Copy
Paste

Lock
C lose
MLO-002923

The following section explains th e difference betw een H istory and Inspect win
dows. The exam ples in th is chapter are based on the RECIPE program from
C hapter 5. Tb ru n th e examples, load the LISP$EXAM PLES:RECIPE.LSP file as
described in C hapter 5.

Using the VAX LISP Inspector 9-1

9.1 Invoking the Inspector
You can invoke the Inspector from any VAX LISP utility: the Listener, Editor, or
Debugger. The two m ethods for invoking the Inspector are:
•

Choose the IN SPECT item on th e O perations m enu.

•

Call the inspect function in a read-eval-print loop.

The INSPECT item is not available on th e E ditor’s Com m ands m enu, b u t you
can evaluate a form containing th e i n s p e c t function w ith the " E v a l u a t e l i s p
Re g i o n " E ditor command (see C hapter 8).
To use th e INSPECT m enu item , you m u st first select the LISP object to be
exam ined. Then, pull down the O perations m enu and choose INSPECT. W hen
you invoke the Inspector this way, it ru n s asynchronously. See Section 9.1.1 for
details on asynchronous mode. See Section 9.1.2 for details on synchronous mode.
Figure 9-2 illu strates using the L isten er’s O perations m enu to invoke the
Inspector on the symbol cookies, as follows:
1.

R eturn a list of valid recipe stru ctu res by typing menu a t th e L istener
prompt.

Move th e pointer to th e cookies entry in th e list and click MBi. This selects
th e object th a t you w an t to inspect.
Pull down the O perations m enu and choose INSPECT.

Figure 9-2: Invoking the Inspector

9-2

Using the VAX LISP Inspector

Ib use the inspect function, type the object to be examined as its argument, as
in:
L is p >

(inspect

'cookies)

If you do not specify an object w hen you invoke the Inspector for the first time,
nothing is displayed in the H istory and Inspect windows. If the Inspector is
already running, its windows are brought to the front.
W hen you call the inspect function, you can specify w hether th e Inspector rim s
in asynchronous or synchronous mode. The default is : parallel t , which ru n s
th e Inspector in asynchronous mode. Set : parallel to nil to ru n the Inspector
synchronously. See Section 9.1.2 for details on synchronous mode.
Regardless of invocation m ethod, th e Inspector keeps a pointer to each object in
LISP memory. T he Inspector does not m ake its own copy of objects you inspect.
Figure 9-3 shows th e windows th a t appear after invoking the Inspector on the
symbol cookies . The Inspector uses two kinds of windows: LISP Inspect and
LISP Inspector History. Each Inspect window displays the components and value
bindings of an individual object. A t this point, cookies is th e only object th a t
h a s been inspected, so th ere is only one Inspect window. (The Inspect window in
Figure 9 -3 h a s been resized and moved to show m ore of its contents and to fit on
th e page.)
The H istory window shows you a sequential list of all the objects you have
exam ined (again, cookies is the only object a t this point). The sta tu s flag a t
th e left side of the H istory window indicates th a t cookies has an open Inspect
window. Section 9.3 explains in detail how to use these windows.

U sin g the VAX LISP In sp ector

9-3

Figure 9-3:

Inspect and History W indows

LISP Inspector History
C om m ands

r-M

Edit

Help
&

Status
Flag "■

In sp e c t
C om m ands

Edit

The Symbol:

Help
COOKIES

SYMBOL-VALUE
SYMBOL-FUNCTION
SYMBOL-PLIST
SYMBOL-NAME
SYMBOL-PACKAGE

#S(RECIPE :NAME "cookies" :INGREDIENTS '
<«UNDEFINED»>
NIL
"COOKIES"
#<USER PACKAGE>

<01
<

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------P

MLO-002925

You can ru n the Inspector in e ith e r asynchronous or synchronous mode. The
following two sections explain each mode.

9.1.1

A s y n c h r o n o u s M ode
By default, th e Inspector ru n s asynchronously, or concurrently, w ith your other
VAX LISP utilities. The window from which you invoked th e Inspector (in this
case, th e L istener) reta in s in p u t focus, and any program ru n n in g in th a t window
continues to ru n . The Inspector im m ediately re tu rn s the object to which it was
applied; the H istory and Inspect windows are a side effect.
CAUTION
In asynchronous mode, th e VAX LISP Inspector lets you modify data
stru ctu res while you are ru n n in g a program th a t m ay be using those
structures. Be aw are of the effects of such changes on your program
and on th e LISP image. (See Section 9.4 for inform ation on modifying
objects.)
The inform ation displayed by the Inspector is static. Inspect windows are not
autom atically refreshed if an o th er program in your LISP im age changes th e data
stru c tu re being exam ined. You can m ake sure a n Inspect window reflects the
c u rren t sta te of your LISP im age by choosing the U pdate item on th e Commands
m enu (see Section 9.5 for m ore inform ation on updating windows).

9 -4

U sin g the VAX LISP In sp ector

9.1.2 S y n c h r o n o u s M ode
W hen you invoke th e Inspector in synchronous mode, your program is suspended
u n til th e Inspector retu rn s. You ru n the Inspector in synchronous mode by calling
th e in s p e c t function w ith th e : parallel keyword set to n il . The form at of the
INSPECT function is:
IN S P E C T &OPTIONAL o b je c t &KEY PARALLEL

The object m ay be an y LISP object. (The default value for : parallel is T.)
W hen th e Inspector is ru n n in g in synchronous mode, you can specify th e value it
re tu rn s by choosing the R eturn item on the Com m ands m enu (see Section 9.6).
If you do not specify a re tu rn value, th e Inspector re tu rn s the object on which it
w as invoked when you exit the Inspector.
Synchronous mode lets you use the Inspector as a debugging tool. For example,
you could use the following form w ith th e RECIPE program :
L is p >

(calories

(inspect

'toast

:parallel nil))

The c a lo r ies function would suspend, while you used th e Inspector to exam ine
and perhaps modify toast and other data, and resum e w hen you retu rn ed a value
or exited the Inspector.
A fter you re tu rn a value, the Inspector continues to run, b u t in asynchronous
mode.

9.2 Exiting the Inspector
E xit th e Inspector by choosing the E xit Inspector item on the Com m ands m enu.
A caution box appears on your screen to confirm th a t you w ant to exit the
Inspector. Click on the Yes button to exit the Inspector.
E xiting destroys th e Inspector’s pointers to objects exam ined during th e session
you are exiting. Thus, objects th a t only th e Inspector points a t a re freed for
garbage collection a fter you exit the Inspector.
If you are ru n n in g th e Inspector in synchronous mode (: parallel n il ), the
Inspector re tu rn s the object on which it w as invoked w hen you exit th e Inspector.

9.3 inspecting Objects
Once you have invoked the Inspector by one of th e m ethods described in
Section 9.1, you can exam ine the components and values of any object in your
LISP image. Table 9 -1 lists each component th a t th e Inspector displays for each
LISP d a ta type, and w hether th a t component can be modified. Any component
th a t is displayed can itself be inspected.

U sin g the VAX LISP In sp e cto r

9-5

Table 9-1:

C om p on en ts of Inspectable Data Types

Data Type

Displayed
Components

Modifiable
Components

Integer

Integers

N one

Floating-point num ber

Floating-point num bers

N one

Ratio

N um erator
Denom inator

N one

Complex num ber

R eal part
Im aginary part

N one

Symbol

Value
Function
P list
Print nam e
Package

Value
Function
P list

Sim ple String

A ll characters

All characters

Array

All elem ents

Structure

All slot values

A ll slot values

A lien structure

All slot values

A ll slot values

H ash table

R ehash-size
R ehash-threshold
A ssociated array
Size
Count

R ehash-size
R ehash-threshold
A ssociated array

L ist

A ll elem ents

Function

Lam bda-list

N one

W hen LISP prints a sequence, such as a list or array, it displays th e first 75
elem ents of the sequence th en prom pts if you w an t to see more. You can change
th e default num ber of elem ents w ith the cu stom iza tion function described in
Appendix C.
The following sections explain how to:

9.3.1

•

Specify objects to be inspected

•

M anage Inspect windows

•

Use th e H istory window

S p e c ify in g O b je c ts to In s p e c t
You can inspect objects in the H istory or Inspect windows in one of three ways:
•

Select the object in either window and choose th e Inspect item on any
Com m ands m enu.

•

Double click MB1 on th e object.

•

P ress MB2 on th e object and choose th e Inspect item on the pop-up m enu.

Inspectable objects are underlined w hen you move th e pointer cursor over them.
Figure 9 -4 shows th e Inspect window containing th e COOKIES symbol. MB2 has
been pressed on th e symbol-value com ponent to produce a pop-up m enu. The
availability of item s on the pop-up m en u depends on th e sta tu s of the object

9-6

U sing the VAX LISP In sp ector

under the pointer cursor w hen you press MB2. M enu choices a re dimmed when
they a re disabled.
Figure 9-4:

Inspecting a Component of an Inspected Object

inspect

Commands

Edit

The symbol COOKIES
SYMBOL-VALUE
SYMBOL-FUNCTION
SYMBOL-PLIST
SYMBOEL-NAME

SYMBOL-PACKAGE

#S(RECIPE :NAME "cookie
<«UNDEFINED»>
NIL
"COOKIES"
#<USER PACKAGED

<1C
MLO-002926

Figure 9-5 shows the resu lt of inspecting th is structure.
Figure 9-5: Inspecting a Structure

C om m ands

P P

In sp e c t

Help

Edit

The Structure: #S(RECIPE :NAME "cookies" :INGR
NAME
INGREDIENTS
AMOUNT
SERVINGS

O f ............

"cookies"
(SUGAR MILK BUTTER)
(2 0 .2 5 1)
36

=□ 0
MLO-002927

If you specify text to be inspected, the Inspector a tte m p ts to coerce th e selection
into a symbol and inspects th e result, on the assum ption th a t inspecting a string
is not as in terestin g as inspecting th e symbol whose p rin t nam e is th e string.

U sin g the VAX LISP In sp ecto r

9-7

9 .3.2

M a n a g in g In s p e c t W in d o w s
Each Inspect window displays th e inform ation for one inspected object. As you
inspect additional objects, new Inspect windows are created. The default lim it on
th e num ber of Inspect windows you can create in a single session is five. W hen
you exceed this limit, the windows are recycled, w ith the new est object replacing
th e first object. T hat is, w hen you inspect a sixth object, it appears in the window
previously allocated to the first object, a seventh object appears in the second
object’s window, and so on. You can change the lim it on Inspect windows w ith the
customization function (see Appendix C).
The following sections explain how you can lock, unlock, close, and remove
Inspect windows.

9.3.2.1

Locking Inspect Windows
You can ensure th a t an Inspect window will not be recycled for another object by
locking the window. Tb lock an open window, click on the Lock toggle item on the
Com m ands m enu of th a t window, or select the object in the H istory window and
choose th e Lock item on the H istory window’s Commands m enu.
You can lock only open Inspect windows.
Locked windows do not count tow ard the m axim um num ber of Inspect windows
allowed. For example, suppose you have five open Inspect windows and your
lim it is five (the default). If you lock one of them , you can inspect a sixth object
w ithout recycling any of the four open b u t unlocked Inspect windows.

9.3.2.2

Unlocking Inspect Windows
You can unlock a window by tu rn in g off the Lock toggle item on its Commands
m enu, or by selecting the object in th e H istory window and choosing th e Unlock
item on th e H istory window’s Com m ands m enu. The Unlock item is also available
on the pop-up m enu if the pointer is in a locked window.
Unlocked windows a re available for recycling until they are closed, even if they
exceed the lim it on Inspect windows.

9.3.2.3

Closing Inspect Windows
Tb close an Inspect window, choose the Close item on th a t window’s Commands
m enu, or select th e object in the H istory window and choose the Close item on
th e H istory Commands m enu. You can close a window th a t is locked, freeing a
window for the next object you inspect. Closing an object’s Inspect window does
not affect th e Inspector’s pointer to the object. The object is listed w ith a blank
sta tu s flag in the H istory window.
The Close m enu item is available on the Inspector’s pop-up m enu if th e pointer
cursor is over an object th a t has a n open Inspect window.

9.3.2.4

Removing Inspected O bjects
Removing an object from the Inspector H istory frees th e Inspector’s pointer to it
and closes its Inspect window (if any). You can remove any object in the H istory
window, regardless of the statu s of its Inspect window.

9-8 Using the VAX LISP Inspector

You can remove an object by selecting the object in the H istory window and
choosing th e Remove item on the H istory window’s Com m ands m enu. The
Remove m enu item is also available on th e H istory window’s pop-up m enu if the
pointer cursor is over an object th a t has been inspected.
NOTE
W hen you rem ove an object and its Inspect window, the object is
deleted from the H istory window. If the object was pointed to only by
th e Inspector, it is now available for garbage collection.

9.3.3

U sin g th e H isto ry W in d o w
The Inspector H istory window shows a sequential list of all the objects you
have exam ined in an Inspector session. It also shows the sta tu s of each object,
by m eans of a sta tu s flag to the left of th e object. The th ree possible flags are
described in Table 9-2.
Table 9-2:

Inspector History Status Flags

Flag

Meaning

space

The object does not have an open Inspect window.

The object has a n open Inspect window.

The object has a locked Inspect window.

There is a default lim it of five on th e num ber of Inspect windows th a t can be open
a t one tim e. W hen you have exceeded th a t lim it, the windows are recycled to
accom modate the new objects. The sta tu s flag of an object whose Inspect window
h a s been recycled changes from a n asterisk to a blank space. Figure 9-6 shows
the H istory window after inspecting COOKIES, the value component of c o o k i e s ,
and all four components of th a t value. Note th a t the s ta tu s flag for c o o k i e s is a
b lan k b u t the flags for th e five m ost recently inspected objects are asterisks.
Figure 9-6:

Inspector History Window

ES LISP In s p e c to r H isto ry
C om m ands

<M ..

Help

COOKIES
#S(RECIPE :NAME "cookies" : INGREDIENTS ' (SUGAR MILK BUTTER)
"cookies"
(SUGAR MILK BUTTER)
(2 0.25 1)
36

0 1 ________ tiO

*
*
*
*
*

Edit

H t = i _ ---------------------------------- .— u i > _ l
MLO-002628

Using the VAX LISP Inspector 9 -9

You can reinspect a previously inspected object by double-clicking MB1 on the
object in the H istory window. If you w ant to prevent an object’s Inspect window
from being recycled, you can lock it. (See Section 9.3.2.1 for details.)
The H istory window is the only Inspector window th a t h a s a shrink-to-icon
button. Clicking MBi on this b utton removes all Inspector windows from your
screen b u t does not affect the Inspector’s pointers to d a ta structures. The three
ways to expand the existing Inspector windows from th e icon are:
•

Click MBi on the LISP Inspector icon in your Icon Box.

•

Choose th e Inspect m enu item w ithout first selecting an object.

•

Call th e inspect function w ithout passing it a n argum ent.

You can also reinvoke th e Inspector on a new object. This expands th e previous
H istory and Inspect windows b u t also creates an Inspect window for th e new
object. Reinvoking th e Inspector does not create a new H istory window.

9.4 Modifying Objects
You can change th e modifiable components of an object by using th e Modify m enu
item , or by using selection and clipboard operations in its Inspect window. You
can modify only an entire component, not its subelem ents. See Table 9—1 for a
list of the modifiable components of each LISP d a ta type.

9.4.1

U sin g th e M odify M enu Item
l b change th e modifiable components of an object, first select th e component and
th en choose th e Modify item on the Com m ands m enu. A dialog box prom pts you
for th e new value to be assigned to the component you have selected.
For example, suppose you have inspected the stru ctu re th a t is the value bound
to cook ies (see Figure 9-5) and w ant to change th e : in gred ien ts slot from
' (SUGAR MILK BUTTER) to ' (SUGAR FLOUR BUTTER) . If you Select th e : INGREDIENTS
component in the stru c tu re ’s Inspect window, you m u st modify the entire list.
(You c a n n o t modify a subelem ent of a slot.) Therefore, inspect th e list in the
: in gredien ts slot. Then, you can change ju s t one elem ent of th e list by selecting
th a t elem ent in th e list’s Inspect window and choosing th e Modify m enu item .

9 -1 0

Using the VAX LISP Inspector

Figure 9 -7 shows th e Modify dialog box th a t appears w hen you change ju s t one
elem ent in th e list’s Inspect window.
Figure 9-7:

Modify Dialog Box

M odifying th e in s p e c te d o b je c t:
(SUGAR MILK BUTTER)

C o m p o n e n t to m odify:
LIST ELT #1
MILK
N ew v a lu e :

Cancel
M L O -002929

W hen you click on the OK button, th e Inspector first evaluates your new value
and th en tries to set th e value. If th e evaluation or the modification results
in an error, a m essage box describes the error and no modification occurs.
Acknowledging th e error re tu rn s you to the Modify dialog box.
Figure 9 -8 shows th e Inspect windows of the cookies stru ctu re and the
: ingredients list after a successful modification.

9.4.2

U sin g th e C lip b o a rd
You can use th e P aste item of the Inspect window’s E dit m enu to change the
value of a component, w ith th e following steps:
1.

T ransfer th e object you w an t to be the new value to the clipboard (use the Cut
or Copy item on any E d it m enu).
2. Select th e object in th e slot you w an t to change.
3. Choose th e P aste item on th e E dit m enu.
The clipboard contents replace the old slot value.
Im m ediately a fter a P aste operation, th e Undo item on th e corresponding Inspect
window’s E d it m enu is active. Choosing the Undo item causes the slot to revert
to its state before th e P aste operation.

Using the VAX LISP Inspector 9-11

9.5 Updating the Inspector Display
W hen th e Inspector is ru n n in g asynchronously, th e inform ation in your Inspect
windows m ay be obsolete. For example, a LISP program ru nning in your L istener
window could modify a d a ta stru c tu re you have inspected. Similarly, using the
Modify command in one Inspect window could m ake th e p rin t representation of
an object in another window inaccurate. You can refresh th e inform ation in an
Inspect window by choosing th e U pdate item on the Com m ands m enu.
For example, using the RECIPE example, assum e th a t you have inspected
cookies and its : ingredients list, then modified the list (as explained in
Section 9.4). Figure 9 -8 shows the Inspect windows a fter the Modify command
b u t before the U pdate command; Figure 9-9 shows the Inspect windows after the
U pdate command.
Figure 9-8:

Inspect Windows Before Updating

In sp ect
C om m ands

Edit_____________________________

The Structure: #S(RECIPE :NAME "cookies
"cookies"
(SUGAR MILK BUTTER)

NAME
INGREDIENTS
AMOUNT
SERVINGS

In s p e c t
C om m ands

O f

I The List:

■

Edit

Help

(SUGAR FLOUR BUTTER)

LIST ELT #0
LIST ELT #1
LIST ELT #2
LAST CDR

on-

....... :

SUGAR
FLOUR
BUTTER
NIL

bO
M L O -002930

9 -1 2

Using the VAX LISP Inspector

Figure 9-9:

Inspect Windows After Updating

In s p e c t
C om m ands

Edit_____________________________

The Structure: #S(RECIPE :NAME "cookies
"cookies"
(SUGAR FLOUR BUTTER)

NAME
INGREDIENTS
AMOUNT
SERVINGS

0 (

In sp e c t
C om m an d s

Edit

The List:

(SUGAR FLOUR BUTTER)

Help

SUGAR
FLOUR
BUTTER
NIL

LIST ELT #0
LIST ELT #1
LIST ELT #2
LAST CDR

<ut

3C>
M LO -002931

The U pdate comm and is also available on the Inspector’s pop-up m enu. Press MB2
while in the Inspect window you w an t to refresh and choose th e U pdate item .

9.6 Returning Values
W hen you invoke th e Inspector in asynchronous mode, it im m ediately re tu rn s
th e object to which it was applied. However, when you invoke th e Inspector in
synchronous mode (: p a r a l l e l n i l ), you can specify which object you w ant the
Inspector to retu rn . The object is retu rn ed to the form in which you invoked the
Inspector.
Tb re tu rn the value of an object, select the object and th en choose th e R eturn item
on th e Com m ands m enu. If you choose the R eturn m en u item w ithout having
selected an object, th e Inspector re tu rn s th e object on which it was invoked.
For example, suppose you w ant to perform some arithm etic on th e num ber of
servings for th e c o o k i e s recipe. You invoke th e Inspector in synchronous mode as
follows:
Lisp> (+ 5

(in s p e c t

c o o k ie s

rp a ra lle l

n il))

This form invokes the Inspector and suspends th e L istener u n til the Inspector
re tu rn s a value. Ordinarily, the Inspector would re tu rn th e object c o o k i e s . In
th is example, however, you w ant to re tu rn th e value of the s e r v i n g s component.

Using the VAX LISP Inspector 9 -1 3

Tb do this, select the value of th e servings component, th en pull down the
Com m ands m enu and choose R eturn, as shown in Figure 9—10. The inspect
function re tu rn s the num ber 36 to the Listener, which performs the arithm etic
and re tu rn s th e num ber 41.
Figure 9-10:

Returning a Value from the Inspector

Help
In sp e c t
U pdate
M odifv
R eturn
Lock
C lose

:e: #S(RECIPE :NAME "cookies" :IN
"cookies"
(SUGAR MILK BUTTER)
(2 0.25 1)
ES
<?

<71
MLO-002932

A fter you re tu rn a n object, the Inspector continues to run, b u t in asynchronous
mode. The H istory and Inspect windows rem ain visible, and all d a ta structures
are intact, b u t you cannot re tu rn another value because nothing is w aiting for the
Inspector.

9-14

Using the VAX LISP Inspector

Chapter 10

Using the Debugging Utilities from
the DECwindows Interface
Debugging is the process of locating and correcting program m ing errors. W hen
you are in th e L istener and an error is signaled, an erro r m essage is displayed
and a caution box appears on the screen. This error m essage provides you w ith
your in itial debugging inform ation: the error type, the nam e of the function th a t
caused th e error, and a description of the error.
The caution box shows you w hether th e error is fatal or continuable and lets you
choose w hether to re tu rn to th e top-level prom pt in th e L istener or e n te r the
Debugger. I b e n te r th e Debugger, click on th e Debug button. Tb re tu rn to top-level
from a fated error, press Return or click on Abort. To continue from a continuable
error, press Return or click on Continue. Figure 10-1 shows a caution box for a
fatal error. Figure 10-2 shows a caution box for a continuable error.
Figure 10-1:

Fatal Error Caution Box

D
E rror in *: A rg u m e n t m u s t b e a n u m b e r: NIL
DEBUG

ABORT I
MLO-002869

W hen you en ter the Debugger, th e following four windows are displayed on
your w orkstation screen, unless you have closed one or m ore of them in a pre
vious debugging session or w ith th e VAX LISP customization function (see
Appendix C).

Using the Debugging Utilities from the DECwindows Interface

10-1

Figure 10-2: Continuable Error Caution Box

C o n tin u ab ie e rro r in SYSTEM ::REM OVE-OLD-DEFINITIONS:
R edefining COM M ON-LISP fu n c tio n CDR.
If c o n tin u e d : it will b e re d e fin e d
DEBUG

CONTINUE |
M L O -002975 *•

•

Debug I/O

•

Calling Stack

•

Variable Bindings

•

Debugger Com m ands

Figure 10-6 shows th e four windows.
In p u t focus transfers to th e Debug I/O window w here th e error m essage is
displayed.
The Calling Stack window displays a quick backtrace of the control stack. A quick
backtrace is a display of the function nam e in each fram e of th e control stack.
The Variable Bindings window displays th e function nam e, argum ent list, and
local variable bindings for the c u rren t stack fram e.
The Debugger Commands window displays bu tto n s labeled w ith th e commands
th a t you use w ith th e VAX LISP Debugger.

10-2

Using the Debugging Utilities from the DECwindows Interface

Once you know th e nam e of the function th a t caused th e error, you can use the
VAX LISP debugging functions and m acros to locate and correct the program m ing
error. Table 10-1 lists th e debugging functions and m acros w ith a brief descrip
tion of each. See V A X L I S P /V M S O bject R eference M a n u a l for m ore detailed
descriptions. •
Table 10-1:

Debugging Functions and Macros

N am e

T ype

M enu

D e scrip tio n

APROPOS

Function

Help

Locates symbols whose p rin t nam e
contains a specified strin g argum ent or
a substring and displays inform ation
about each symbol i t locates.

APROPOS-LIST

Function

None

Locates symbols whose p rin t nam es
contain a specified strin g argum ent as
a substring and re tu rn s a lis t of the
symbols it locates.

BREAK

Function

O perations

Invokes th e break loop.

DEBUG

Function

O perations

Invokes th e VAX LISP Debugger.

DEBUG-CALL

F unction

None

R eturns a list representing th e call a t
th e cu rren t debug stack fram e.

DESCRIBE

Function

Help

Displays detailed inform ation about a
specified object.

DISASSEMBLE

Function

O perations

Compiled code is reverse assem bled
and printed o u t in symbolic form at.

DRIBBLE

Function

File

Copies th e in p u t an d th e ou tp u t of an
interactive LISP session to a specified
file.

Function

O perations

Invokes or resum es th e VAX LISP
Editor, potentially on th e selection (only
if th e arg u m en t is a strin g will th e ED
function ed it a file—m ost often it will
ed it a symbol’s function definition).

INSPECT

Function

O perations

Invokes or resum es th e VAX LISP
Inspector, potentially on th e selection.

ROOM

Function

None

Displays inform ation about the state of
in tern al storage and its m anagem ent.

STEP
TIME

Macro

O perations

Invokes th e stepper.

Macro

None

D isplays tim ing inform ation about th e
evaluation of a specified form.

TRACE
UNTRACE

Macro

O perations

Enables tracin g functions an d macros.

Macro

O perations

Disables tracin g for functions and
macros.

This chapter provides th e following:
•

A table of the functions and m acros th a t give you debugging inform ation.

•

Illu stratio n s of th e debugging u tility m enus.

•

Descriptions of two variables th a t control th e output of th e Debugger and the
stepper and how to use them .

•

Description of th e control stack th a t stores calls to functions, m acros, and
special forms.

Using the Debugging Utilities from the DECwindows Interface

10-3

•

E xplanations of how to use the following debugging facilities from the
DECwindows interface:
— B reak loop—A read-eval-print loop you can invoke while the LISP system
is evaluating a program
— Debugger—A control stack debugger you can use interactively to inspect
and modify th e LISP system ’s control stack fram es
— Stepper—A facility you can use interactively to step through a form ’s
evaluation
— Tracer—A facility you can use to inspect a program ’s evaluation

The VAX LISP E ditor and VAX LISP Inspector are two other tools th a t you can
use for debugging. For an explanation of how to use th e Editor, see C hapter 8.
For an explanation of how to use the Inspector, see C hapter 9.
Figure 10-3 shows those debugging utilities pull-down m enus th a t differ from
L istener pull-down m enus.
Figure 10-3:

Debugging Utilities Pull-Down Menus

LISP D eb u g g er

LISP S te p p e r

Commands

Commands...
Calling Stack...
Variable Bindings...

Continue
Quit Debug

1111111

LISP T ra c e
Commands
Clear

Copy

Trace
Trace...
Untrace
Close
M L O -002976

10-4 Using the Debugging Utilities from the DECwindows Interface

10.1 Control Variables
VAX LISP provides two variables th a t control th e output of the Debugger,
the stepper, and th e tra c er facilities: *debug-print -length* and »
debugprint -level*. These variables are analogous to the Common LISP variables
»
print -length* and »PRINT-LEVEL* b u t are used only in the Debugger.
»DEBUG-PRINT-LENGTH*

Controls th e num ber of displayed elem ents
a t each level o f a nested data object. The
variable’s valu e m u st be eith er an integer or
NIL. The default value is NIL (no lim it).

»DEBUG-PRINT-LEVEL*

Controls th e num ber of displayed levels of a
nested data object. The variable’s valu e m u st
be either an in teger or NIL. The default value
is NIL (no lim it).

These variables can be changed w ith setf (see Section 4.1).

10.2 Control Stack
The control stack is th e p a rt of LISP m em ory th a t stores calls to functions,
m acros, and special forms. The stack consists of stack fram es. Each tim e you call
a function, macro, or special form, the VAX LISP system does th e following:
1.
2.
3.

Pushes the nam e of th e function associated w ith th e function, macro, or
special form th a t is being called onto the stack fram e.
Pushes the function’s argum ents onto th e stack.
C reates a new stack fram e.

Invokes the function.

Each control stack fram e h a s a fram e num ber, which is displayed as p a rt of the
stack fram e’s output. Stack fram e num bers are displayed in th e output of the
Debugger, the stepper, and the tracer.
T here is always one active stack fram e, and it can be either significant or
insignificant. Significant stack fram es are those th a t invoked documented
and user-created functions. Insignificant stack fram es are those th a t invoked
undocum ented functions.
Debugger commands show only significant stack fram es, unless you specify the
ALL modifier w ith a Debugger command.

10.3 Break Loop
The break loop is a read-eval-print loop th a t you can invoke to debug a program .
You can invoke the break loop while a program is being evaluated. If you do, the
evaluation is in terru p ted and you a re placed in th e loop.

10.3.1

In v o k in g th e B re a k L o o p
You can invoke the break loop by calling th e break function. The th ree ways of
using th e break function to debug a program are:
•

Choose th e BREAK item from th e O perations m enu while your program is
being evaluated.

•

P u t th e BREAK function in specific places in your program .
Using the Debugging Utilities from the DECwindows Interface

10-5

•

Use the VAX LISP bind -keyboard-function function to bind an ASCII
keyboard control character to the break function. Then, use th e control
character to directly invoke the break function w hile your program is being
evaluated (see V A X L I S P /V M S O bject R eference M a n u a l for a description of
the bind -keyboard-function function).

W hen invoked, th e break function displays a m essage (if you specified one in your
form calling th e break function) and enters a read-eval-print loop. If you specified
a m essage, the break function displays th e m essage in the following form at:
B re a k :

y o u r m essa g e

A fter th e m essage is displayed, a prom pt is displayed a t th e left m argin of your
L istener window:
B re ak >

10.3.2

E xiting th e B re a k L o o p
W hen you are ready to exit the break loop and continue your program ’s evalua
tion, invoke the VAX LISP continue function.
•

Choose th e CONTINUE item from the O perations m enu. The CONTINUE
item on the O perations m enu is available only w hen you are in a break loop
and only h as effect w hen the break loop is w aiting for input. The CONTINUE
item does not in te rru p t evaluation of your code. If you w ish to stop evaluation
of code in the break loop, choose the ABORT item first.

•

Type Continue a t the prompt.
B re a k ;

(c o n tin u e )

The continue function causes th e evaluation of your program to continue from
th e point w here the LISP system encountered the BREAK function.

10-6

Using the Debugging Utilities from the DECwindows Interface

10.3.3

U sin g th e B re a k L o o p
Once you are in the break loop, you can check w h at your program is doing by
in teractin g w ith the LISP system as though you w ere in the top-level loop. For
example, suppose you define a variable nam ed * f i r s t * and a function nam ed
c o u n t e r , which uses the variable * f i r s t *.
Figure 10-4:

Defining a Variable

File

E dit

O p e ra tio n s

Help

L i s p > (defvar *first* 0)
★FIRST*
L is p > (defun counter nil

(if (< *first* 100)
(progn (incf *first*)
*first*))

(counter))

COUNTER
L is p >

M L O -002977

Using the Debugging Utilities from the DECwindows Interface

10-7

You can in te rru p t the function’s evaluation by invoking the b reak loop from the
O perations m enu during evaluation. For example:
Figure 10-5:

Invoking the Break Loop

PP
Help
INSPECT
Lisp> (def
ED
*FIRST*
EVAL
Lisp> (def
(if COMPILE
(P*
*fi OISASSEM
COUNTER
Lisp>

<0-

) (counter))

TRACI
TH ,

ABORT
BREAK
CC

DEBUG

M L O -002978

You can check the value of the variable * f i r s t * by typing * f i r s t * a t the Break>
prom pt. The read-eval-print loop evaluates the variable a t the point w here the
BREAK function in te rru p ted evaluation of c o u n t e r .
If you call th e c o n t i n u e function by choosing the C ontinue item from the
O perations m enu or typing C ontinue a t th e Break> prom pt, th e evaluation of
th e function c o u n t e r continues.
A fter you call the c o n t i n u e function, you can see th a t th e evaluation was con
tinued by invoking the b reak loop again and rechecking the value of th e variable
*FIR S T *.

Use th e c o n t i n u e function again to complete th e function’s evaluation.
Changes th a t you m ake to global variables and global definitions w hile you
a re in the break loop rem ain in effect after you exit th e loop and your program
continues. For example, if you are in the b reak loop and you find th a t th e value of
th e variable nam ed * f i r s t * has a n incorrect value, you can change th e variable’s
value. The change rem ains in effect after you exit the b rea k loop and continue
your program ’s evaluation.

10-8

Using the Debugging Utilities from the DECwindows Interface

NOTE
The form s you e n te r w ith the m ouse or by typing while you are in the
b reak loop are evaluated in a null lexical environm ent, as though they
are evaluated a t top level. Therefore, you cannot exam ine the lexical
variables of a program th a t you in te rru p t w ith th e break loop. Tb
exam ine those lexical variables, invoke the debugger (see Section 10.4).
For inform ation on lexical environm ents, see C om m on L IS P : The
L a n g u a g e.

10.4 Debugger
The VAX LISP Debugger is a control stack debugger. You can use it interactively
to inspect and modify the LISP system ’s control stack fram es. The Debugger has
a pointer th a t points to the current stack fram e. The current stack fram e is the
la s t fram e for which the Debugger displayed inform ation. The Debugger provides
several comm ands th a t perform the following:
•

Display help.

•

E valuate a form or reevaluate th e function call a stack fram e stores.

•

H andle errors.

•

Change which stack fram e is considered current.

•

Inspect or modify the function call in a stack fram e.

•

Display a sum m ary of the control stack.

The Debugger reads its in p u t from and p rin ts its o utput to the stream bound to
th e * d e b u g - i o * variable.
Before you use th e Debugger, you should be fam iliar w ith th e VAX LISP control
stack. The control stack is described in detail in Section 4.2.

10.4.1

In v o k in g th e D e b u g g e r fro m D E C w in d o w s
You can invoke the Debugger by:
•

Clicking on the Debug b u tton in one of th e caution boxes

•

E valuating t h e d e b u g function

•

Choosing th e DEBUG item from the Operations m enu

The DEBUG item ignores any objects th a t you have selected before invoking the
debugger.
W hen you invoke th e Debugger, four windows are displayed on your screen: the
Debug I/O window, th e Calling Stack window, the Variable Bindings window, and
th e Debugger Com m ands window. If you have closed th e Calling Stack, Variable
Bindings, or Debugger Com m ands window in a previous debugging session or
w ith th e VAX LISP c u s t o m i z a t i o n function, th a t window is not displayed on your
screen (see Appendix C). Figure 10—6 shows these four windows.

Using the Debugging Utilities from the DECwindows Interface

10-9

Figure 10-6:

Debug I/O, Calling Stack, Variable Bindings, and Debugger Commands Windows

Variable Bindings

! ■

Calling Stack
TOP

F u n c tio n n a u :

»*

S y s t e m : :A :

MAPCÄR
MAPCAR
REDUCE
FLOOR
NUMERATOR
IF
IF
COND
BLOCK
CALORIES
CALORIES
EVAL

F ra m e n u m b a c :

(N IL 1)

OC
LISP D ebugger
Hie

C om m ands

P E I
Edit

Operations

Help

E r r o r i n * : A r g u n a n t m u s t a n u m b e r : N IL
<*NIL 1)
J ^ p ly # 1 5 :
D e b u g 1>

BOTTOM

Debugger Commands
Backtrace
Top
Up
W here
Down
Bottom

B a ck trace...
Top All

Error
Step
Redo

S h o w ...
S e t ...
Return ...
E v alu ate...

| Quit |

s: Cancel

S e a rc h ...

Up...
G o to ...
D ow n...
Bottom All

3C>

<1C

M L O -002870

10.4.1.1

The Debug I/O Window
The Debug I/O window (titled LISP Debugger in Figure 10-6) displays the same
inform ation th a t appears on the term inal screen. W hen you invoke the Debugger,
a m essage th a t identifies the Debugger, a m essage th a t identifies the current
s ta c k fr a m e p r e c e d e d by A p p ly or Eval, and the command prom pt are displayed
in the Debug I/O window in the form at displayed in Figure 10—6.
The integer in the prom pt indicates the num ber of th e nested command level
you are in. Its value increases by one each tim e th e comm and level increases.
For example, the top-level read-eval-print loop is level 0. If an erro r is invoked
from th e top-level loop, th e Debugger displays the prom pt Debug 1>. If you m ake
a m istake again causing an error while in the Debugger, th a t error causes the
Debugger to display the prom pt Debug 2>.

10.4.1.2

The Calling Stack Window
The Calling Stack window displays the function nam e in each fram e of the control
stack. The c u rren t fram e is indicated by two angle brackets a t th e left m argin
of the Calling Stack window. As you move the m ouse pointer up or down in the
stack, th e function nam e a t which you are pointing is underlined. To select a
particu lar fram e, double-click on th a t fram e w ith MB1, or select th a t fram e and
th en click on the Goto F ram e button.

10-10

Using the Debugging Utilities from the DECwindows Interface

You can dism iss this window from your screen w ith th e Cancel button, l b re tu rn
the Calling Stack window to your screen, choose the Calling Stack item from the
pull-down Commands m enu of th e Debug I/O window (see Figure 10-3). The
state of the Calling Stack window (displayed or not displayed) stays the sam e
across invocations of th e Debugger. For example, if you remove th e Calling Stack
window from the screen, you m u st explicitly bring it back, or it will not reappear.
10.4.1.3

The Variable Bindings Window
The Variable Bindings window displays th e function nam e, argum ent b st, and
local variable bindings for the c u rren t stack fram e. As you change the current
stack fram e in the Calling Stack window, th e display changes in the Variable
Bindings window. A new window is not created. The Variable Bindings window is
shown in Figure 10-6.
You can dism iss this window from your screen w ith th e Cancel button. Tb re tu rn
the Variable Bindings window to your screen, choose the Variable Bindings item
from the pull-down Com m ands m enu of th e Debug I/O window. The sta te of the
Variable Bindings window (displayed or not displayed) stays the sam e across
invocations of the Debugger. For example, if you remove th e Variable Bindings
window from the screen, you m u st explicitly bring it back, or it will not reappear.

10.4.1.4

The Debugger Commands Window
The Debugger Com m ands window (see Figure 10-6) displays th e commands
you can use w ith th e VAX LISP Debugger. Some of th e comm ands, for example,
Backtrace, take optional argum ents. W hen a comm and tak es an optional arg u 
m ent, it is followed by an ellipsis. Thus, if you w a n t to invoke th e Backtrace
command w ith a n argum ent, choose the B acktrace... item . The Backtrace... item
brings up a dialog box for you to e n te r th e optional argum ent.
You can dism iss this window from your screen w ith th e Cancel button. Tb re tu rn
the Debugger Com m ands window to your screen, choose the Com m ands item
from the pull-down Com m ands m enu of the Debug I/O window. The state of
th e Debugger Com m ands window (displayed or not displayed) stays the same
across invocations of th e Debugger. For example, if you remove th e Debugger
Commands window from th e screen, you m u st explicitly bring it back, or it will
not reappear.

10.4.2

E xiting th e D e b u g g e r
Tb exit from th e Debugger, do one of th e following:
•

Choose the Q uit item from the
— Debugger Com m ands window
— Pull-down Com m ands m en u of th e Debug I/O window

•

Type Q uit a t th e Debug n> prom pt

These cause th e Debugger to re tu rn control to the previous com m and level.

Using the Debugging Utilities from the DECwindows Interface

10-11

If you specify the Q uit command w hen the D ebugger comm and level is 1 (indi
cated by the prom pt Debug 1>), th e comm and causes the Debugger to exit and
re tu rn s you to th e Listener. Specifying the Q uit comm and a t a higher Debugger
command level re tu rn s the Debugger to the next lower comm and level. If a continuable error caused th e Debugger to be invoked, the Q uit command, by default,
displays a confirmation box on th e screen before the D ebugger exits. Figure 10-7
shows the confirmation box.
Figure 10-7: The Quit Command Confirmation Box

Do y o u really w a n t to le a v e th is d e b u g e n v iro n m e n t?

MLO-002980

If you click on Yes, th e Debugger windows disappear from th e screen, and control
re tu rn s to th e liste n e r.
If you click on No, the Debugger prom pts you for an o th er command.
You can prevent the Debugger from displaying the confirm ation box on the screen
w ith the VAX LISP customization function (see Appendix C). Tb prevent the
Debugger from requesting confirm ation w hen you type th e Q uit comm and a t the
prom pt, specify the Q uit comm and w ith a value other th an n il . For example:
D ebug

1> q u it t

Lisp>

10.4.3

U sin g D e b u g g e r C o m m a n d s
The Debugger commands let you inspect and modify th e cu rren t control stack
fram e and move to other stack fram es. You invoke the Debugger commands from
the Debugger Com m ands window. Some Debugger com m ands tak e argum ents
th a t qualify command operations. C ertain debugging u tility comm ands require
argum ents, others tak e optional argum ents, and some tak e no argum ents. An
argum ent whose value is an integer is usually optional; an arg u m en t whose
value is a symbol or form is required. In the Debugger Com m ands window,
commands taking no argum ents ap p ear only as the comm and nam e w ith no
ellipsis. Com m ands th a t require a n argum ent ap p ear only as th e command
nam e w ith an ellipsis. Com m ands taking optional argum ents appear both as
th e command nam e w ith no ellipsis and as th e command nam e w ith an ellipsis.
(For detailed inform ation about the argum ents to Debugger commands, see
Section 10.4.3.1.)

10-12

Using the Debugging Utilities from the DECwindows interface

W hen you choose a command item w ith no ellipsis, the comm and is executed.
W hen you choose a command item w ith an ellipsis following th e command name,
a dialog box appears on the screen for you to e n te r argum ents to th e command.
Table 10-2 provides a sum m ary of th e comm ands in th e Debugger Commands
window. Table 10-4 describes the stepper comm ands in sim ilar detail. Detailed
descriptions of the commands are provided in Section 4.4.3.2.
Table 10-2:

Debugger Commands

Command
Button Label

Description

BACKTRACE
BA C K T R A C E-

D isplays a backtrace o f th e control stack.

BOTTOM
BOTTOM...

M oves th e current fram e pointer to th e first stack fram e on the control stack.

CONTINUE

C ontinues execution by returning from th e continuable error th a t invoked the
Debugger; causes the D ebugger to return NIL; is only available i f th e Debugger
w as invoked by a continuable error.

DOWN
DOW N-

M oves the current fram e pointer down th e control stack.

ERROR

R edisplays th e error m essage th a t w as displayed w hen the D ebugger w as invoked.

EVALUATE...

E valuates a specified form.

GOTO...

M oves th e pointer to a specified control stack frame.

REDO

R einvokes the function in the current stack frame.

R ETU R N —

E valuates its argum ents and causes th e current stack fram e to return the sam e
valu es th e evaluation returns; rem oves th e D ebugger w indow s from th e screen.

SEARCH...

Searches th e control stack for a fram e containing a specified function.

SET...

S ets th e valu es o f the com ponents in th e current stack frame.

SHOW...

D isplays inform ation stored in th e current stack fram e.

STEP

R esum es execution, single-stepping at th e current frame.

TOP
TO P-

M oves th e pointer to th e la st stack fram e in the control stack.

UP
UP...

M oves the pointer up th e control stack.

WHERE

R edisplays the argum ent list and the function nam e in th e current stack frame.

10.4.3.1

Arguments
Some Debugger comm ands require a n argum ent; other Debugger comm ands
accept optional argum ents. An argum ent whose value is an integer is usually
optional; a n argum ent whose value is a symbol or form is required.
The types of argum ents you can specify w ith Debugger comm ands are:
•

Debugger command

•

Symbol

•

Form

•

Function nam e

•

Integer

•

Modifier

Using the Debugging Utilities from the DECwindows Interface

10-13

NOTE
Only parenthesized expressions and argum ents to evaluate (th at is,
argum ents specified or selected w ith the E valuate command) are
evaluated.
The preceding argum ents are self-explanatory w ith th e exception of the integer
and modifier argum ents.
Integer argum ents rep resen t control stack fram e num bers. Each stack fram e on
th e control stack h as a fram e num ber, which the Debugger displays in the Debug
I/O window as p a rt of th e stack fram e’s output. The Debugger reassigns these
num bers each tim e it is invoked. You can specify a fram e num ber in a Debugger
comm and to refer to a specific stack fram e in th e cu rren t Debugger session.
Table 10-3 provides a sum m ary of the modifier argum ents you can specify w ith
Debugger commands.
Table 10-3:

Debugger Command Modifiers

M odifier

Effect

ALL

Operates on both significant and insignificant stack frames.

ARGUMENTS

O perates on th e argum ents specified w ith th e function in th e cu rren t stack frame.

CALL

O perates on th e call to th e c u rren t stack frame.

DOWN

Moves th e pointer down the control stack.

FUNCTION

O perates on th e function object in th e cu rren t Btack frame.

HERE

O perates on th e c u rre n t stack frame.

NORMAL

Displays th e function nam e and th e argum ent list in th e control stack fram es.

QUICK

Displays th e function nam e in th e control stack frames.

TOP

S ta rts a backtrace a t th e top of th e control stack.

Moves th e pointer up th e control stack.

VERBOSE

D isplays th e function nam e, argum ent list, local variable bindings, and special
variable bindings in th e control stack fram es.

10.5 Stepper
The stepper is a facility you can use to step interactively through the evaluation
of a form. You can control th e stepper w ith commands from th e Stepper
Com m ands dialog box as th e stepper displays and evaluates each subform of a
specified form.
The stepper h a s a pointer th a t points to th e current stack fram e on th e system ’s
control stack. The cu rren t stack fram e is th e la st stack fram e for which the
stepper displayed inform ation.
The stepper p rin ts its comm and interaction and output to th e stream bound to
th e * d e b ü g - i o * variable (the Debug I/O window).

10-14

Using the Debugging Utilities from the DECwindows Interface

10.5.1

In v o k in g th e S te p p e r
You can invoke th e stepper m acro w ith a form as an argum ent. The th ree ways
of invoking the stepper a re as follows:
•

Select a form and choose the Step item from the O perations m enu. If you
do not select the form before choosing the Step item , th e Step item is not
available on th e O perations m enu.

•

Type Step a t a prom pt w ith a form as an argum ent. If you do not include the
form, the system displays an error m essage and invokes the Debugger.

•

Choose th e Step item from the Debugger Commands dialog box.

The exam ple in Figures 10-8 and 10-9 invokes th e stepper from th e O perations
menu with a call to a function named factorial.
Figure 10-8:

ÖH]
File

Invoking the Stepper

LISP L iste n e r
Edit

L isp> i t j

E I
Hel 5

O p e ra tio n s

INSPECT
ED
EVAL
COM PILE
m C Q M P llE
D ISA SSE M B L E
TRA CE

TRACE...
m xm .C E

STE P
^
......................
ABORT
BREAK

c o n t in u e

DEBUG

T=r

MLO-002981

W hen the stepper is invoked, the Debug I/O window and th e Stepper Com m ands
window are displayed on your screen. The stepper displays a line of te x t in the
Debug I/O window th a t includes th e first subform of the specified form and the
stepper prom pt. The o u tp u t is displayed in th e following form at:

Using the Debugging Utilities from the DECwindows Interface

10-15

Figure 10-9:

Stepper W indow Display

A fter the stepper is invoked, you can use the stepper commands (see Section 10.5.5)
to control the operations th e stepper performs and th e way the stepper displays
output.

10.5.2

S te p p in g T h ro u g h a F o rm
W hen you use the stepper, you can step through a n entire specified form by doing
eith er of the following:

10.5.3

•

C ontinually choosing the Step item from the Stepper Com m ands window.
The Stepper Com m ands window appears on the screen by default w hen the
stepper is invoked.

•

C ontinually pressing th e Return key.

E xiting th e S te p p e r
If you w a n t to exit from the stepper before i t steps through a form, you can:
•

Choose th e Q uit comm and from the Stepper Com m ands window.

•

Type Q uit a t the prom pt.

The Q uit command causes th e stepper to re tu rn control to the previous command
level and window th a t was active when the stepper w as invoked. By default, the
Q uit comm and requires confirm ation before th e stepper exits. If you invoked the
stepper from the L istener window, the Debug I/O window disappears from the
screen.
You can prevent the stepper from displaying th e confirmation box on th e screen
w ith th e VAX LISP c u s t o m i z a t i o n function (see A ppendix C). l b prevent the

10-16

Using the Debugging Utilities from the DECwindows Interface

stepper from displaying the dialog box w hen you type th e Q uit comm and a t the
prom pt, specify th e Q uit comm and w ith a value other th a n n i l . For example:
S te p >
L is p >

10.5 .4

q u it t

S te p p e r O u tp u t
Stepper output in th e Debug I/O window is the sam e as stepper ou tp u t on a
term inal screen. For a description of stepper output and a sam ple session, see
Section 4.5.3.

1 0.5.5

U sin g S te p p e r C o m m a n d s
Stepper commands let you use th e stepper to step through th e evaluation
of a LISP expression, form by form. You m u st specify some comm ands w ith
argum ents. They provide th e stepper w ith additional inform ation on how to
execute the command.
Each tim e a command is executed, the stepper displays a re tu rn value if the
subform retu rn s a value, displays the next subform, and prom pts you for another
command. You en ter stepper comm ands from th e S tepper Com m ands window.
Figure 10-9 shows the Stepper Com m ands window.
C ertain stepper comm ands require argum ents, others take optional argum ents,
and some take no argum ents. In th e Stepper Com m ands window, th e commands
th a t require argum ents have an ellipsis following th e comm and nam e, and the
commands th a t tak e no argum ents appear only as th e comm and nam e w ith no
ellipsis. Commands th a t take optional argum ents ap p ear both as th e command
nam e and as the comm and nam e w ith an ellipsis. Table 10—4 provides a sum m ary
of the stepper comm ands. Descriptions of th e stepper com m ands are provided in
C hapter 4.

Table 10-4:

Stepper Commands

Com m and

D escription

BACKTRACE

D isplays a backtrace o f th e current form’s evaluation.

BACKTRACE . . .
DEBUG

Invokes th e Debugger.

EV A L U A T E . . .

E valuates a specified form w ith th e stepper disabled.

FIN ISH
F IN ISH T

Com pletes evaluation of th e form th a t w as specified or selected in th e call to th e
ST E P macro w ith the stepper disabled.

OVER

E valuates the subform in th e current stack fram e w ith th e stepper disabled.

QUIT

Exits th e stepper.

RETURN . . .

Returns the specified values and rem oves th e D ebug I/O w indow and Stepper
Commands window from th e screen.

SHOW

D isplays th e subform in th e current stack fram e w ithout abbreviation.

STEP

Evaluates the subform in th e current stack fram e w ith th e stepper enabled.

E valuates subforms w ith th e stepper disabled u ntil th e stepper gets back to a
subform th a t contains the subform in th e current stack frame.

Using the Debugging Utilities from the DECwindows Interface

10-17

10.6 Tracer
The VAX LISP tracer is a m acro th a t you can use to follow a program ’s evaluation.
The tracer inform s you when a function or m acro is called during a program ’s
evaluation by prin tin g inform ation about each call and re tu rn value to the stream
bound to th e * t r a c e - o u t p ü t * variable. By default, this output is displayed in the
Trace window. Tb use the tracer, you m u st enable it for each function and macro
you w an t traced.
NOTE
You cannot trace special forms.

10.6.1

E n a b lin g th e T ra c e r
You can enable the tracer from a window for one or m ore functions and/or macros
as follows:
•

Select one or m ore functions and/or m acros and choose th e TRACE or
TRACE... item s from the O perations m enu.

•

Type th e t r a c e macro a t the prom pt, specifying one or m ore function and/or
m acro nam es as argum ents.
NOTE
If you redefine a function or m acro a fter tracing it (for example, by
loading it from a file or by evaluating it from the Editor), you m u st
call t r a c e on it again. O therw ise, the tra c er only traces the form er
definition.

10.6.1.1

Enabling the Tracer from the Operations Menu
You can enable the tra c er w ithout setting or modifying options by choosing the
TRACE item . Figure 10-10 shows a Trace window. Choosing the TRACE item
a fte r selecting a function or macro creates the Trace window if it did not already
exist and adds the function or m acro nam e to the Trace List if it did not already
ap p ear there. The Trace List is a list of the symbols being traced; it is located
im m ediately below the m enu b a r in th e Trace window.
You can enable the tracer from the O perations m enu and set or modify tra c er
options by choosing the TRACE... item . Choosing the TRACE... item w ith no
function or m acro selected displays th e Trace window a t the front of your screen.
Choosing th e TRACE... item a fter selecting a function or m acro displays the
Trace Options dialog box, which lets you set options and invoke the trace. The
Trace Options dialog box is shown in Figure 10—11. You invoke th e trace from the
dialog box by clicking on th e OK button after setting options.
N ote th a t if you invoke the tra c er on the sam e function or m acro w ith the TRACE
item after you invoked it w ith the TRACE... item and set options for th e tracer,
tra c e r ou tp u t is no longer modified by those options.
A description of th e t r a c e m acro is provided in V A X L I S P /V M S O b ject R eference
M a n u a l.

10-18

Using the Debugging Utilities from the DECwindows Interface

Figure 10-10:

Trace Window

IS3 LISP T ra c e
C om m an d s

H lS l
E dit

Help

< M .................

No functions being traced.

< 1 1 ______ ___ ___ __

_______ ____ 1 0

MLO-002983

10.6.1.2

Enabling the Tracer from a Prompt
You can enable the tracer from the L istener or Debug I/O windows for one or more
functions or m acros by specifying the function and m acro nam es as argum ents
in a call to the t r a c e macro. The t r a c e macro re tu rn s a list of traced functions
and macros. I t adds the function or macro nam es you specified to th e Trace List
if they are not already there, and if the Trace window already exists.
If you type t r a c e a t th e prom pt w ithout specifying a function or macro, t r a c e
re tu rn s a list of traced functions. If there are no functions currently being traced,
TRACE re tu rn s a n em pty list.
Note th a t t r a c e typed a t a prom pt ignores any objects you selected w ith th e
m ouse; it is only affected by th e argum ents you type a t the prompt.

10.6.1.3

Clearing the Tracer
You should periodically clear th e stored and visible inform ation from th e Trace
O u tp u t a re a of th e Trace window. The Trace O utput a re a is located im m ediately
below th e Trace List. You clear th e inform ation from the Trace O utput area by
choosing the C lear item from the Commands m enu. C learing the stored and
visible inform ation from Trace O utput allows the space used by Trace O utput to
be freed and allows th e objects to which pointers have been k e p t to be garbage
collected. If object recording is tu rn ed on and you do not perform the Clear
operation occasionally, th e objects recorded will not be collected, and th e LISP
process could ru n out of virtu al memory.
Using the Debugging Utilities from the DECwindows Interface

10-19

10.6.1.4

Disabling the Tracer
You can disable the tracer from a window for one or m ore functions and/or m acros
as follows:

10.6.1.5

•

Select a function or macro and choose the UNTRACE item from the
O perations m enu; if you choose the UNTRACE item w ith no selection, the
tracer is disabled for all functions and macros.

•

Type the UNTRACE m acro a t the prom pt, specifying one or m ore function and/or
m acro nam es as argum ents.

Disabling the Tracer from the Operations Menu
You can disable the tracer from the O perations m enu by choosing the UNTRACE
item .
To disable the tra c er for a specific function or macro, select the function or macro
and choose the U ntrace command item . U ntrace rem oves the function or macro
nam e from the Trace List. U ntrace displays th e Trace window on your screen if
it is not already displayed b u t does not move the Trace window to the top of the
stack.
To disable th e tra c er for all functions and macros, choose th e U ntrace command
item w ithout selecting a function or macro. By default, a caution box is displayed
on your screen.
Note th a t th e UNTRACE item is dimm ed w hen no function or m acro is being
traced.

10.6.1.6

Disabling the Tracer from a Prompt
l b disable the tracer from a prom pt for specific functions or m acros, specify the
nam es of th e functions or m acros in a call to the UNTRACE macro. Tracing stops
for these functions and macros, and th eir nam es are rem oved from the Trace List.
You can disable tracing for all the functions for which tracing is enabled by
calling th e u n t r a c e macro w ithout any argum ents. U ntrace rem oves all traced
item s from the Trace List.
Note th a t u n t r a c e typed a t a prom pt ignores any objects you selected w ith the
m ouse; it is only affected by the argum ents you type a t the prompt.
The u n t r a c e m acro is described in C om m on L IS P : The L a n g u a g e.

10.6.2

T ra c e r O u tp u t
Tracer output appears in th e Trace window below th e Trace List—the list of all
item s being traced.
Once you enable the tracer for a function or macro, th e tra c e r displays in the
Trace window two types of inform ation each tim e th a t function or m acro is called
during a program ’s evaluation:

IP-20

•

A description of each call to th e specified function or macro

•

A description of each re tu rn value from the specified function or macro

Using the Debugging Utilities from the DECwindows Interface

The description of a call to a function or m acro consists of a line of text th a t
includes th e following information:
•

The nested level of the call

•

The control stack fram e num ber th a t indicates w here th e call is stored

•

The nam e and argum ents of th e function associated w ith the function or
m acro th a t is called

The tra c e r indicates th e nested level of a call w ith indentation. W hen the
num ber of nested levels increases, the indentation increases. A fter m aking the
appropriate indentation, the tracer displays th e control stack fram e num ber, the
function nam e, and the argum ents in the following form at:
#n: (function-name arguments)

T he tra c e r also displays a line of text for the re tu rn value of each evaluation.
The line of text th a t the tracer displays for each value includes th e following
inform ation:
•

The nested level of the re tu rn value

•

The control stack fram e num ber th a t indicates w here the re tu rn value is
stored

•

The re tu rn value

The tra c er indicates the nested level of each re tu rn value w ith indentation. The
indentation m atches th e indentation of the corresponding call. A fter m aking the
indentation, th e tra c er displays the control stack fram e num ber and the re tu rn
value in the following form at:
#n => return-value

C hapter 4 h a s exam ples illu stratin g the form at of tra c er output.

10.6.3

M odifying T ra c e r O p tio n s fro m th e D ialog B ox
You can modify th e output of the tracer w hen you call it w ith the TRACE... m enu
item by specifying options in the Trace Options dialog box. The Trace Options
dialog box is shown in Figure 10-11. W hen you use th e Trace Options dialog box,
you can specify options for only o n e f u n c t i o n o r macro a t a tim e.
NOTE
Form s th e system evaluates ju s t before or ju s t a fter a call to a function
or m acro for which tracing is enabled are evaluated in a null lexical
environm ent. For inform ation on lexical environm ents, see C om m on
L IS P : The L an g u a g e.

10.6.3.1

invoking the Debugger from the Trace Options Dialog Box
Typing a LISP form in one of the th ree text fields u n d er Invoke th e Debugger if
re su lt is non-NIL invokes the debugger if the form re tu rn s a value o ther th an
n i l . The LISP system evaluates the form before, after, or before and after each
call to th e function or m acro being traced.

Using the Debugging Utilities from the DECwindows Interface

10-21

Figure 10-11:

Trace O ptions Dialog Box

T ra c e O p tio n s fo r FACTORIAL:
Invoke th e D e b u g g e r if re s u lt is n o n -N IL :
B efore Call
A fter Call [
A round Call
Invoke th e S tep »per if re s u lt is n o n -N IL :
B efore Call
S u p p r e s s tra c e o u tp u t if re s u lt is n o n -N IL :
B efore Call
P rint re su lt:
B efore Call
A fter Call

A round Call
O nly tra c e d u rin g c a lls in

Cancel

MLO-002984

10.6.3.2

Invoking the Stepper from the Trace Options Dialog Box
Typing a LISP form in the Before call tex t field under Invoke th e Stepper if resu lt
is non-NIL invokes the stepper if the form re tu rn s a value other th a n n i l . The
LISP system evaluates the form before each call to th e function or m acro being
traced.

10-22

Using the Debugging Utilities from the DECwindows Interface

10.6.3.3

Removing Information from Tracer Output from the Trace Options Dialog Box
Taping a LISP form in the Before call text field under Suppress trace output if
re su lt is non-NIL suppresses trace output if th e form re tu rn s a value other than
re su lt N I L . The LISP system evaluates the form before each call to the function
or m acro being traced. If the form re tu rn s a value other th a n n i l , the tracer does
not display th e argum ents and the re tu rn value of the function or m acro being
traced.

10.6.3.4

Adding information to Tracer Output from the Trace Options Dialog Box
Typing a list of LISP forms in one of the three tex t fields under P rin t resu lt adds
inform ation to tracer output. The LISP system evaluates each form in the list
and the tracer displays th e re tu rn value, before, after, or before and after each
call to th e function or macro being traced. The tracer displays th e values one per
fine and indents them to m atch o ther tra c e r output. If th e forms to be evaluated
cause a n error, the Debugger is invoked.

10.6.3.5

Defining When a Function or Macro Is Traced from the Trace Options Dialog Box
Typing a function or m acro nam e or a list of function and/or m acro nam es in the
te x t field next to Only trace during calls in defines w hen a function or macro, for
which tracing is enabled, is to be traced. The functions and m acros for which the
tra c e r is enabled are traced only w hen they are called (directly or indirectly) from
w ithin one of the functions or m acros whose nam e is specified in the text field.

10.6.4

M odifying T ra c e r O p tio n s in th e Call to th e TR A CE M acro
You can modify the output of th e tracer by specifying options in th e call to the
t r a c e m acro. Each option consists of a keyword-value pair. The form at in which
to specify keyword-value pairs for th e t r a c e m acro is:
(T race

(fu n c tio n -n a m e keyw ord-1
keyw ord-2 v a lu e -2
...))

v a lu e -1

In th e call to the t r a c e macro, you can also specify options for a lis t of functions
and/or m acros. The t r a c e m acro form at in which to specify th e sam e options for
a lis t of functions and m acros is:
(T race

((nam e-1

n a m e -2 ...)

keyw ord-1 v a lu e -1
keyw ord-2 v a lu e -2

...))
Specifying options a t th e prom pt in a window is th e sam e as specifying options a t
th e prom pt on a term inal interface. For a detailed explanation of how to do this,
see Section 4.6.4.

Using the Debugging Utilities from the DECwindows Interface

10-23

Appendix A

Using DECwindows
You work w ith m ost DECwindows applications by using the sam e handful
of mouse and windowing techniques. This appendix sum m arizes some basic
techniques you’ll use in DECwindows—from clicking and dragging to editing text.

A.1 Using the Mouse
The m ouse—the hand-held pointing device attached to your w orkstation
m onitor—m akes using DECwindows as easy as pointing to an object on your
screen and clicking a button. You use the m ouse to choose comm ands from a
m enu, to expand and shrink windows, and to rearran g e windows on your screen.
The m ouse has three buttons. U nless you specify otherwise, MB1 (for “mouse
button 1”) is on th e left, MB2 is in th e middle, and MB3 is on th e right. This button
arran g em en t natu rally suits right-handed users. If you are left handed, you can
easily rearrange this configuration by changing the b u tton arrangem ent setting
in the Session M anager’s Customize Pointer dialog box.

Using DECwindows

A-1

You can do all your work w ith DECwindows by m astering th e following m ouse
techniques:
•

Point: U sing the mouse, move th e cursor to where you w an t the next action
to occur.

•

Click: Quickly press and release MB1 . You should h e a r and feel a fain t click.

•

Press: Point to th e m enu nam e, stepping arrow, or w herever you w ant the
action to occur. W ithout m oving the mouse, press and hold MB1 or MB2. If you
are pointing a t a m enu nam e, pressing MB1 pulls down a m enu and keeps it
down u n til you release MBI.

•

Drag: P ress and hold MB1, move th e pointer, and release MB1. For example,
you move a window to another location on the screen by dragging its outline.
Tb cancel a drag in progress, click MB3 before releasing MB1. If you are
displaying a pull-down m enu, cancel the drag by moving the pointer outside
th e m enu and releasing MBI.

•

Double click: Point to the object and click MBi twice in quick succession.

•

Shift click:

Point to the object. P ress and hold the Shift key and click MBI.
Release the Shift key.

A.2 What Are Windows?
A window is a n area on your w orkstation screen th a t represents all or p a rt of an
application. For example, M ail’s C reate window is ju st one of several windows
available in the M ail application. •

A-2

•

The title b a r a t the top identifies the window.

•

The m enu b ar directly b eneath the title b a r lets you access the application’s
commands.

Using DECwindows

The work area in the space rem aining displays the application’s text and
graphics.

A.3 Starting a S ession
If the system sta rtu p procedure h a s been successful, your screen looks like this:

S ta r t S e s s i o n
U s e rn a m e

[I___________

P a s s w o r d []______________________

C lear

The S ta rt Session dialog box prom pts you for your u se r nam e and password.
DECwindows displays a dialog box w henever it needs inform ation from you.
You type your user nam e and passw ord in the appropriate text e n try fields. A
te x t insertion cursor is visible in each field. The text cursor in th e U sernam e
field blinks to indicate this field h as in p u t focus. W hen a text field or window
h a s in p u t focus, you see your keystrokes echoed there. The tex t cursor in the
Passw ord field is dimmed, indicating th a t you cannot currently e n te r text in it.
To s ta rt a session:
1.

Type your user nam e.
If you m ake a typing m istake, press the Delete key ( O ) to erase the character
to th e left of the text cursor, l b in se rt a character in th e m iddle of tex t you
already typed, point where you w ant th e text inserted and click MB1. Or, use
th e rig h t and left arrow keys to move the tex t cursor rig h t or left. The new
characters you type push existing ones to th e right.

Select the Passw ord field by pointing to th e Passw ord field and clicking MB1.
You alw ays select the object or inform ation you w a n t to w ork on next. You
can also move to the Passw ord field by sim ply pressing Tab. The text cursor in
th e Passw ord field blinks to indicate this field now h a s in p u t focus.

Type your password.
l b preserve th e secrecy of your password, the lette rs you type are not
displayed on the screen.
If you m ake a typing m istake, click on the C lear button. This erases all text
in both the U sernam e and Passw ord fields so you can retype your inform ation
correctly. Clicking on buttons in dialog boxes lets you tell DECwindows w hat
to do w ith the inform ation you supplied.

Click on the OK b utton or press Return.

Using DECwindows

A -3

The double outline around the OK button in th e S ta rt Session dialog box indicates
it is the default option. D efault options are those you will choose m ost frequently.
DECwindows provides you w ith a shortcut to choose default options: W henever
you see a button w ith a double outline, pressing the Return key achieves th e same
resu lts as clicking on th a t button.
If you provide wrong inform ation or m ake a typing m istake and do not correct
it, DECwindows does not let you s ta r t a session. Instead, it displays a Problem
Report dialog box a s a w arning th a t some inform ation is incorrect.
Click on th e Acknowledged b utton in the Problem Report dialog box or press the
Return key to try again.
If the inform ation you supplied is correct, your session begins.

A.4 Selecting Windows
W hen you have m ore th a n one window open, DECwindows needs to know which
one you are currently working on so th a t th e commands you choose and the text
you type end up in th e rig h t place. You tell DECwindows which window you w ant
to work w ith by selecting it. W hen you select a window, it moves to the front of
th e “stack” of overlapping windows. Its title b ar is highlighted to indicate it has
in p u t focus. Any keystrokes you type appear in this window. W hen you select
another window, th e new window is given in p u t focus. Only one window can have
in p u t focus a t a tim e.

Window with Input Focus
JÜ| RleVlew - W ORK: [JONES]_______________________________________________ S M

Window Without Input Focus
p l l FllsVtoW - WORK : [JONES]
Z K -0 5 8 1 A -G E

l b select a window:
1.

Point to a location in th e window or title bar.
In th e FileView window, point to the title bar.

Click M B i.

A.5 Changing the Size of Windows
Som etim es you w a n t to m ake one window very large so you can see everything
in it. O ther tim es, you m ight w an t to work w ith sm all windows, such as when
several applications are ru nning sim ultaneously. You can change the size of your
windows to su it your needs by using the resize button.

H Ma!l:Reed-1 [□] MAIL INBOX #2
ZK -0 5 6 3 A -G E

A -4

Using DECwindows

To change the size of a window:
1.

Point to the window’s resize button.

P ress a n d h o ld MB1.
The pointer changes into a sm all resize cursor.

D rag the resize cursor to th e size you w ant.
To m ake th e window larger, drag the resize cursor beyond the window border.
To m ake th e window smaller, drag th e resize cursor beyond the window
border and then back in. The outline stops moving when the window is as
small as it can get.

Release MBi.

You can change the size of a window in one dimension (height or w idth) or in both
dim ensions sim ultaneously. To change the size in one dimension, drag the resize
cursor across one border of th e window. As long as you cross only one border,
the outline th a t follows the resize cursor changes in only one dimension. If after
crossing one border you cross an adjacent border, you see an outline th a t can
change in both dimensions.
If you drag the resize cursor through one border and th en through th e o p posite
border, the first border you crossed reverts to its original location, and the other
border becomes an outline th a t follows the resize cursor.
To cancel a window-resizing operation in progress, click another m ouse button
before releasing MBI. The outline disappears, and the window reta in s its original
size.

A.6 Shrinking Windows
W hen you s ta rt an application, its icon appears in the Icon Box. You shrink
a window to an icon if you w ant to free up space on your screen to ru n other
applications w ithout exiting from th e application. W hen you shrink a window to
an icon, the application it represents continues to ru n in m em ory and rem ains
easily accessible. Any processes continue to execute while the application is
stored as a n icon.
S h r in k - t o I c o n Button

B FileView - WORK:[JONES]
ZK -0 5 6 5 A -G E

W hen th e application is ru n n in g in a window, its icon is dimmed. The icon
appears bold w hen the application is stored in th e Icon Box. If the Icon Box
contains more icons th a n can be displayed a t once, scroll b ars appear. You use
scroll bars to view th e tex t th a t does not fit in a single window.
To shrink a window to an icon:
1.

Point to the window’s shrink-to-icon button.

Click M B i.
The window closes and its icon in the Icon Box appears bold.

You cannot shrink th e Icon Box to an icon.

Using DECwindows

A -5

As you stop applications, your Icon Box develops gaps w here icons used to be.
You can rearran g e the icons in the Icon Box in two ways:
•

By m oving the icons, lb move an icon, drag it to a new location.

•

By clicking on the Icon Box’s shrink-to-icon button. Clicking on th is button in
an application window shrinks the window to an icon. Clicking on th is button
in the Icon Box, however, elim inates th e gaps betw een icons th a t m ay develop
w hen you stop applications.

A.7 Expanding Icons to Windows
W hen you expand an application icon, you open a window for th a t application. If
you have more th an one window open and expand an icon to a window, th a t new
window is placed a t the front of the stack of overlapping windows. If the window
accepts text entry, it is also given in p u t focus.
To expand an icon to a window:
1.

Point to th e icon in the Icon Box.

Click MB 1.

A.8 Moving Windows
If one window partially obscures another, you m ight w ant to arran g e them so
th a t each is completely visible. To move a window, drag it by its title bar.
n tie Bar-

[Hi Mall:Read-1 [D] MAIL INBOX #2
ZK -0 5 7 9 A -G E

To move a window:
1.

Position the pointer anyw here in th e window’s title b a r (except in the
shrink-to-icon, push-to-back, or resize buttons).

P ress and hold MB1.
An outline of th e window appears.

D rag the window to the new location.

Release MB1.
If th e window was p artially obscured by o ther windows, it moves to the front
of the stack of windows and is given in p u t focus.

Ib cancel a window-moving operation in progress, click another m ouse button
before releasing MB1. The outline disappears and the window is not moved.

A -6

U sing D E C w in dow s

A.9 Stacking Overlapping Windows
W hen you are w orking w ith stacked windows and select a window, it moves to
the front of th e stack and is given in p u t focus. B ut if a larg er window completely
obscures a sm aller window, you cannot select th a t sm all window w ithout moving
th e larger window out of th e way. If you use the title b a r to move th e larger
window, you disru p t your window arrangem ent.
By clicking on th e visible window’s push-to-back button, you can push th a t
wipdow to the back of th e stack and expose the window underneath. W ithout
moving the windows to an o th er location on the screen, you can push one window
out of th e way or retrieve an o th er to work with.
P U 8 h - to B a c k B u tt o n

|R£| S ession Manager JO N E S on HUBBUB

mm.

i
ZK -0 5 6 4 A -G E

To push the frontm ost window to th e back of a stack of overlapping windows:
1.

Point to th e frontm ost window’s push-to-back button.

Click MBl.

If you try this repeatedly w ith th ree or more windows, you see th a t th e windows
cycle through th e stacking order, moving up one position in th e stack each tim e a
window is moved to th e back of the stack.

A.9.1

Making O verlapping W indow s Stick in Place
W hen you are w orking w ith overlapping windows and select one window, it moves
to the front of th e stack of windows and is given in p u t focus. You can, however,
prevent a p artially obscured window from moving to th e front of th e stack w hen
you select it by arran g in g th e windows to display only w h at you need to see and
th en securing them in place.
For example, if you are w orking w ith a D ECterm , Notepad, M ail, and File View
windows, you m ight a rra n g e them so th a t only the portions you need to work
w ith are visible. In the D EC term window, you probably need to see only the last
few lines so you can e n te r comm ands. Once you secure th e windows in place,
you can switch from one window to another w ithout d isturbing th eir order in the
stack.
To lock overlapping windows in th e stacking order:
1.

Point to a window’s push-to-back button.

Shift click on th e button.
T h at window is pushed to the back of the stack.

The lower rig ht-hand corner of th e push-to-back b utton is filled to indicate th a t
th e window is fixed in th e stacking order. A lthough th e window is given input
focus w hen you select it, it does not pop to the front of th e stack.

U sin g D E C w in d o w s

A-7

You can still, however, push to the back or bring to the front an y window th a t
you have fixed in th e stacking order to see it unobscured. Clicking on a window’s
filled push-to-back b utton moves th a t window to the opposite position in the
stack, b u t does not give it in p u t focus. Clicking on a filled push-to-back button
pushes an unobscured window to the back of the stack. Clicking on a filled
push-to-back button moves a partially obscured window to the front of th e stack.

A.9.2

R eleasing W indow s Locked in th e Stacking Order
To release a window locked in th e stacking order, shift click again on its push-toback button. If th e window w as a t the back of the stack, it moves to the front; if
th e window was a t the front, it is pushed to th e back. If you look a t the window’s
push-to-back button, you will notice th a t it is no longer filled.

A.10 Choosing Items from Pull-Down Menus
The nam es of m enus available in an application appear on th e m enu bar. W hen
you press MB1 on a m enu nam e, the m enu’s contents are displayed or pulled down.

BMI

FileV iew - W O R K :[JO N E S ]

| C ontrol

C u sto m ize

V iew s

F iles

U tilitie s

n e ip

B o o k re a d e r

C a lc u la to r
C alen d ar
C ardfiler
C lock
DDIF V iew er
Mall
N o tep ad
P ain t

ZK-0234A-GE

Some pull-down m enus list comm ands. O thers lis t the nam es of item s you can
work w ith. You tell DECwindows w h a t you w an t to do or w h at you w an t to work
w ith by choosing comm ands or item s from pull-down m enus. Any m enu item
followed by three periods (...) is your cue th a t a dialog box will be displayed if you
choose th a t m enu item .
To choose a n item from a pull-down m enu:
1.

On th e m enu bar, point to th e nam e of the m enu you w ant to display.

P ress and hold MB1.
This highlights th e m enu nam e and pulls down a m enu.

W hile holding MB1, drag to th e m enu item you w ant.

Release MB1.

If you change your m ind while looking a t a pull-down m enu, drag outside the
m enu and release M B l . The m enu disappears and no action is taken.

A -8

U sin g D E C w in d o w s

Some applications offer rectangular push buttons to duplicate frequently used
commands th a t are also available as m enu item s. P ush buttons are usually found
u n d ern eath an application’s work area. To execute these commands quickly, click
MBl on the push button.

A.11 Choosing Items from Submenus
A m enu item w ith a subm enu icon—an arrow pointing to the rig h t—indicates
th a t a corresponding subm enu is available. If you choose th a t m enu item , you
need to refine your choice by displaying its subm enu and choosing a m enu item
from th a t subm enu.
Font
Size
Style

E
E

Courier
Times
Helvetica
ZK-0529A-GE

l b display a subm enu and choose a m en u item from it:
1.

On th e m enu bar, point to th e nam e of th e m enu you w ant to display.

P ress and hold M B l.

D rag to th e m enu item you w ant.

D rag onto the subm enu icon.
A subm enu is displayed to th e rig h t of th e m enu.

D rag to th e m enu item you w an t to choose from the subm enu.

Release MBl.

A.12 Choosing Items from Pop-Up Menus
DECwindows provides pop-up m enus to m ake it easier for you to work w ith files
and applications. Pop-up m enus duplicate comm ands an d functions available
on pull-down m enus. Unlike pull-down m enus, which require you to move
th e pointer to the m enu bar, you can display a pop-up m enu anyw here in an
application’s work area. By reducing your use of the m ouse, pop-up m enus give
you quick, direct access to an application’s com m ands and functions.

U sin g D E C w in dow s

A-9

I I FIteVJ*w - WORK:[JONE8]
Control

C u sto m iz e

V iew s

F lics

U tilities

A pplications

File Filter: []__
D irecto ry : | W ORK :[JON ES]I
AI
[ .MAIL]
[ . SCHEDULES]
[ .STAFF]

! N one

S e le c te d : 0
T o ta l F lie s: 60

1992_ISSU ES.PS
BKUSSELS_CONTACTS. LIS
C U R R E N C ^ l^ ^ ^ J l

——

EJ25329E33' ^°fni>arB I
EMBARGOES. TXT
C opy
FORECAST 1 .DDIF
F0RECAST2.DDIF
F0RECAST3.DDIF
IMPORT_TARIFFS
LOGIN.COM
MUNICH_CONTACT
MY_CALENDAR.DW
PRODUCTION.DIS
PR0DUCTI0N_PR0<
RCME_C0NTACTS.LIS
SALES_PLAN.PS
TRADE BARRIERS. TXT

Pop-Up Menu

ZK-0574A-GE

To display a pop-up m enu:
1.

P ress and hold MB2 on the application’s work area.
In th e FileView window, press and hold MB2 on th e file type whose pop-up
m enu you w ant to display.

D rag to th e m enu item you w ant.

Release MB2.

If you change your m ind while looking a t a pop-up m enu, drag outside the m enu
and release MB2. The m enu disappears and no action is taken.

A.13 Choosing Items from Option Menus
An option m enu is a pop-up m enu th a t appears in a dialog box. An option m enu
lets you choose one option from many. In the dialog box, only th e current option
is displayed. To see the other options from which you can choose, you display the
option m enu.

O rie n ta tio n

D e fa u lt

O rie n ta tio n
P o rtra it
L a n d sc a p e

Z K -0 5 6 2 A -G E

To display an option m enu:
1.

P ress and hold MB1 on the cu rren t option.
The option m enu is displayed.

A-10

D rag to th e m enu item you w ant.

Release MB1.

U sin g D E C w in dow s

The option m enu disappears. The option you chose is now the cu rren t option.
If you decide not to change th e original option, drag outside the m enu and release
MBi. The m enu disappears and no changes occur.

A.14 Supplying Information in Dialog B oxes
DECwindows displays a dialog box w henever it needs additional inform ation from
you to carry out a task. Som etim es you need to type text; other tim es, you need
only click on a button to change a setting. Some dialog boxes display settings you
chose earlier.

T oggle
B u tto n -

Custom ize S ession M anager
S ta r t u p S t a t e \ ^
, # W indow
O Ico n

m C re a te FNeVlew W indow
g ] C o n firm Q u it S e s s io n

S c a le
w ith S lid e r

T erm in al W in d o w s

M e s s a g e R eg io n

i m ~ .... ......
S c ro lle d L in es S a v e d

T e x t E n try F ield
J

1M essages]:
H ead er Text

P u sh
B u tto n | A pply |

| C an c el ]
ZK-0550A-GE

Dialog boxes offer various ways to supply inform ation to an application:
•

By typing text in a text e n try field. The blinking tex t cursor shows you w here
the text you type will appear. W hat you type appears to the left of th e text
cursor.

•

By clicking on option buttons or square toggle buttons. Option buttons 1st you
select one option from many. Toggle bu tto n s let you tu rn a setting on or off.

•

By dragging th e slider in a scale. Dialog boxes often contain a scale and
slider when you need to supply a num eric value. The arrow in the slider
points to the cu rren t value.

•

By selecting choices, for example, file nam es, from a list box. A lis t box
contains a list of item s from which you can choose. Scroll b a rs appear if the
choices do not fit in th e list box.

•

By clicking on push buttons. P ush buttons, such as OK, Cancel, or Filter, let
you tell DECwindows w hat to do w ith th e inform ation you supplied in the
dialog box.
In a dialog box, the OK b u tton is usually the default option. You can press
the Return key to achieve the sam e resu lt as clicking on OK.

A.14.1

M oving a n d C h a n g in g S e ttin g s in a D ialog B ox
How you move in a dialog box depends on th e object, for example, a toggle button
or tex t field, you w ant to work w ith. The following table describes th e ways in
which you can move and change settings in a dialog box.

Using DECwindows

A-11

D o th is

Move forward betw een tex t fields

Press th e Tab key or point to th e field to w hich you w an t to move
and click MB1.

Move backward betw een tex t fields

P ress th e [ShjftTTgj] keys or point to th e field to w hich you w an t to
m ove and click MB1.

Move the tex t cursor w ithin a tex t
field

Point to w here you w ant th e tex t in serted and click MB1 or u se the
right and left arrow keys to m ove th e tex t cursor right or left. N ew
characters push existing ones to th e right.

C hange the num eric valu e on a
scale

D rag the slider on the scale right or le ft or point to another location
on the scale and click MB1.

Change an option or toggle button
settin g

Point to the option or toggle button and click MB1.

Once you change the settings you w ant, click on e ith e r the OK, Apply, or Cancel
buttons.

A .14.2

C lick o n

Record your choices and d ism iss th e dialog box.

Apply

Record your choices w ithout d ism issin g th e dialog box.

C ancel

D ism iss th e dialog box w ithout changing any settings. If you
m ade any changes w ithout applying them , clicking on th e Cancel
button cancels those changes.

M aking S e le c tio n s fro m L ist B o x e s
A list box is p a rt of a dialog box th a t contains a list of item s, often file names,
from which you can choose. M any applications display a list box w hen you open
or save a file.
Tb select an item from a list box, point to th e item and click MB1. The item you
select is highlighted.

File Filter
|* .t x t |
F ile s in W O R K :[JO N ES]
S]CURRENCY.TXT ;3

■Ct

B1D IRECTI0N S.TX T ;5
S]EM BARGO ES.TX T;1
L ist

S]TRAD E_BA RRIERS.TXT;1

Cancel

Box

V
< 0 1 = 3

m o □

S e le c tio n
| W O R K :[JO N ES]PIR EC TIO N S.TX T;5l

Z K -0 5 4 8 A -G E

A-12

Using DECwindows

If you selected a file nam e, you can click OK to open th e file. DECwindows also
gives you a shortcut for opening files from list boxes: Double clicking on the file
nam e produces the sam e resu lts as selecting th a t file nam e and clicking on O K
If you w ant to w ork w ith a file th a t does not ap p ear in th e list box, type the nam e
of the file in the Selection tex t e n try field and click on O K Or, use the File F ilter
text entry field to list a subset of files th a t you can th en select from. For example,
to list all the files in an o th er directory w ith th e file type TXT, en ter the complete
directory specification— [JO NES .LETTERS]* .TXT—in the File F ilter text entry
field and click on th e F ilter button. The list of files th a t m eet the qualifications
are displayed. Double click on the nam e of the file you w a n t to open.

A.15 Scrolling
Some windows display scroll bars, which let you view the tex t th a t does not fit in
a single window. Some windows have both horizontal and vertical scroll bars.
A scroll b ar consists of stepping arrow s a t e ith e r end of th e scroll region. The
slider is the thicker box th a t overlays th e scroll region. If th e slider is a t the top
of the scroll region, th e beginning of th e file or list is visible. If th e slider is a t
th e bottom of th e scroll region, th e end of th e file or list is visible.
Si] FlfaVlww - W O R K :[JO N ES]
Control

C u r to m l»

V iew »

F lla t

Utllltl»*

A pplication«

Help

FHo F ilter |___________________________________
D irecto ry : | W ORK:[JONESH______________________

I ** I □ □ JE l
[.MAIL]
[.SCHEDULES]
[.STAFF]

Supping
Arrow

1992_ISSU ES.PS
BRUSSELS_CONTACTS.LIS
CURRENCY.TXT
DIRECTIONS. TXT
EMBARGOES. TXT
FORECAST 1 .DDIF
FORECAST2 .DDIF
FORECAST3 .DDIF
3MPORTJTARIFFS. PS
LOGIN.COM
MUNICH_CONTACTS. L IS
MY_CALENDAR. DWC
PRODUCTION. DIS
PRCDUCTION_PROCEDURES. IMP
ROME_OONTACTS.LIS

StaUr

Sorol
Region

SUpping
A rrow

Scroll Bar

ZK-0557A-GE

The size of th e slider is relative to the total am ount of tex t in th e docum ent and
indicates how m uch m ore tex t rem ains to be displayed. For example, a sm all
slider indicates th a t m uch tex t rem ains to be displayed. A large slider th a t
completely fills th e scroll b a r indicates th a t all th e text is displayed.
The following table describes how to use scroll bars.
To scroll

Do this

One lin e at a tim e

Click MB1 on th e stepping arrows.

Forward one windowful of tex t a t a tim e

P oin t to th e scroll region below th e slider and click MB1.

Back one windowful of tex t a t a tim e

P oin t to th e scroll region above th e slider and click MB1.

Using DECwindows A -1 3

To s c r o ll

D o th is

C ontinuously through th e lis t or file one
lin e a t a tim e

Press and hold MB1 on either stepping arrow.

C ontinuously through the lis t or file one
window ful o f tex t a t a tim e

Press and hold MB1 in the scroll region.

To another location in th e lis t or file

Drag th e slider to a position in the scroll region that corre
sponds to th e general location you w ant to see. If th e slider is
a t th e top o f th e scroll region, you are view ing th e beginning of
th e list or file. I f the slider is in th e m iddle o f th e scroll region,
you are view ing the m iddle of the list or file. Cancel th e drag
by clicking another m ouse button before releasin g MB1.

A.16 Editing Text
DECwindows provides m any ways to edit text, which saves you from retyping
long file nam es or large blocks of text. M ost applications let you move and copy
text
•

From one place in a window to another.

•

From one window to another window. For example, you can copy text from
one Create-Send window in M ail to another.

•

From one application to another application. For example, you can move a
picture from P a in t onto a C ardfiler card.

In addition, m ost applications provide an E dit m enu th a t lets you cut, copy, and
p aste text and graphics. See the V M S D E C w in d o w s D esk to p A p p lic a tio n s G u ide
for m ore inform ation about using the E d it m enu in specific applications.
Finally, m ost applications define specific keys to let you perform basic text editing.
These keys let you move the cursor and delete small am ounts of text efficiently.

A.16.1

S e le c tin g T ext
Before you can copy or move text to other locations in a window or betw een
windows, you m u st select th e text. You can copy text in any am ount, including
a word, a line, or a parag rap h a t a tim e. Successive clicks of MB1 increase the
am ount of text you a re selecting. The following table describes how to select text.

D o th is

P osition th e cursor w here you w ant th e
selection to start

Point to th e location and click MB1.

S elect a word

Point to th e word and double click MB1.

S elect a lin e

Point to th e lin e and triple click MB1.

S elect continuous text, from th e original
selection point to th e point w here th e
button is released

Press and hold MB1 and drag the pointer through the text,

Extend the current selection

Sim ultaneously press and hold the Shift key and MB1 w hile
dragging th e pointer through the additional text.

Extend th e current selection to w here th e
pointer is positioned

Press and hold th e Shift key and click MB1.

A-14

Using DECwindows

In addition, some applications provide a way for you to select larger blocks of text
a t a tim e. For example, you can select a paragraph of text in EVE by pointing to
the paragraph and clicking MB1 four tim es. You can select an entire m ail m essage
or the contents of a N otepad file by pointing to the text and clicking MB1 five
tim es.
You can select only one piece of text a t a tim e. By selecting text in one applica
tion, you cancel any other text selection established in th e sam e window or in
an o th er application.

A .16.2

C o p y in g T ext
If you can type text in a window, you can select and copy th a t text from one place
to another in the sam e window, betw een windows of the sam e application or
betw een different applications.
You can also copy text from a FileView window—including FileView’s file list—to
an application th a t supports tex t entry.
To copy tex t in a window, betw een windows in the sam e application, or betw een
applications:
1.

Select th e text you w ant to copy, using the text selection techniques described
in Section A. 16.1.

Position th e cursor w here you w ant the tex t copied by pointing and clicking
MB1.

Click MB3.
The text is copied to the new location.

The window from which you selected text takes in p u t focus. If you copied th a t
tex t back to your cu rren t window, you had to reestablish in p u t focus for th a t
window. Sometimes, however, you ju s t w an t to grab a piece of text from another
window w ithout w orrying about which window h as in p u t focus. T h a t is where
QuickCopy comes in handy: You use QuickCopy to copy text from another window
to your c u rre n t window w ithout losing in p u t focus in your current window.
To use QuickCopy:
1.

In the current window, position th e cursor w here you w an t th e text copied by
pointing and clicking MB1.

In the other window, point to the text you w an t to copy.

P ress and hold MB3.

D rag across the tex t you w an t to copy.
The text is underlined as you drag across it.

Release MB3.
The text is copied to the new location in your current window.

Using DECwindows

A-15

A .16.3

M oving T ext B e tw e e n W in d o w s
DECwindows also lets you work in one window, select text from another, and
move th a t text to the cu rren t window w ithout losing in p u t focus in your current
window. The text is deleted from its original location.
To move text from one window to another:
1.

In th e cu rren t window, position the cursor w here you w ant th e text pasted by
pointing and clicking MB1.
M ake sure th e window h a s in p u t focus.

In the other window, point to the text you w an t to move.

P ress and hold Ctrl/MB3.

D rag across th e tex t you w ant to move.
The tex t is underlined as you drag across it.

Release CM/MB3.
The tex t is moved to the new location and deleted from th e old.

A .16.4

D eletin g T ext w ith P e n d in g D elete
W hen you m a rk tex t for pending delete, you can delete large blocks of text w ith
one keystroke instead of pressing the Delete key repeatedly. You m ark tex t for
pending delete by selecting it as described in Section A. 16.1. The selected text is
deleted w hen you press any key. You can th en type new text.
To cancel a pending delete selection (once you select th e tex t b u t before you press
a key), point to th e selected text and click MBi.

A .16.5

E d itin g T ext in D ialog B o x e s
You can use th e text editing techniques described in th e following table to move
th e cursor or delete text in dialog boxes in any DECwindows application. Use the
arrow keys to move the cursor one character a t a tim e.

Press

Move th e cursor to the n ext word

1S h ift

Move th e cursor to th e previous word

| Shltt/<— |

Move th e cursor to th e b eginning of the
lin e

[f TS!

Move th e cursor to th e end o f th e line

| Sh ltl/F I 2 | or [c w e !

/—>|
or |Clrl/H |

Move th e cursor forward b etw een text
fields
Move th e cursor backward b etw een text
fields

| Sh itt/T a b |

D elete th e character to th e left o f the
cursor and m ove all text to th e right of
th e deleted character one space to the
left

A -16

Using DECwindows

P ress

D elete th e ch aracter a fte r th e cursor and
move all te x t to th e rig h t of th e deleted
ch aracter one space to th e left

| S h itt/ < £ l

Delete all characters to th e s ta rt of the
line

I Ctrl/U 1

I In overstrike mode, I S h i t t / < 5 1 deletes th e character
un d er th e block cursor. Not enabled in EVE.

A.17 C om posing Special Characters
In DECwindows, you can use compose sequences to create special characters. A
compose sequence is a series of keystrokes th a t creates characters th a t do not
exist as stan d ard keys on your keyboard. See the list of ISO L atin -1 compose
sequences in th e V M S D E C w in d o w s D esk to p A p p lic a tio n s G u ide.
D epending on the keyboard type, you compose characters in eith er of the
following ways:
•

U sing three-stroke sequences on a VT200- or VT300-series keyboard.

•

U sing two-stroke sequences on any VT200-series keyboard except N orth
Am erican.

Tb compose a character, using th e list of compose sequences in th e V M S
D E C w in d o w s D e sk to p A p p lic a tio n s G u id e :

F ind th e character you w an t to create in column 1.

To compose a three-stroke sequence, press and hold the Compose key while you
press the space bar, and th en type th e two characters in column 2.
Tb compose a two-stroke sequence, type th e two characters in column 3. The
desired character is displayed.

Tb cancel a compose sequence, press and hold the Compose key while you press the
space bar, or press th e Delete key, Tab key, Return key, or Enter key.
See. th e V M S D E C w in d o w s D e sk to p A p p lic a tio n s G u ide for inform ation about
composing characters in D ECterm .

A.18 Getting Help
You can get help in any DECwindows application by using the Help m enu.
Help provides b rief inform ation about screen objects, concepts, or task s you can
perform in applications. Some applications also le t you get help on specific screen
objects, for example, scroll b ars and m enu item s, by using th e Help key and MB1.
Help is designed to let you req u est general inform ation on an application and
quickly narrow the focus of your inquiry. In Help, you can
•

N avigate quickly through help topics. Help keeps tra c k of the p a th you used
to get to a particu lar topic, which m akes it easy for you to retrace your steps
and follow a different path.

•

Search Help for a keyword or topic supplied by the application.

Using DECwindows

A-17

A.18.1

In v o k in g H elp
l b get help on task s in DECwindows applications, choose Overview from the
application’s Help m enu.
A help window opens w ith the Overview topic displayed, including a list of
additional topics th a t explain how to do common tasks.

[SS|| H elp o n C a le n d ar
File

Edit

V iew

S e a rc h

Help

DECwindows C alendar
This is th e O verview to p ic fo r th e DECwindows C alendar
Help lib r a r y . The C alendar p ro vid es a s irrp le f a c i l i t y
fo r re c o rd in g your m eetings and o th e r e v e n ts . L ik e a
paper c a le n d a r, s e v e ra l d iffe r e n t view s a re a v a ila b le .
F o r exam ple, i t can d is p la y th e whole y e a r in a window,
o r ju s t one day, w ith a l l it s appointm ents.
Help >
T opics

You can use th e H elp lib r a r y as a source o f ta s k o rie n te d o r d e s c rip tiv e in fo rm a tio n . T a s k -o rie n te d Help
d escrib es how to use th e fe a tu re s o f C alendar to c a rry
o ut s p e c ific ta s k s . For a l i s t o f th e ta s k s , s e le c t
Using C alend ar from th e l i s t o f a d d itio n a l to p ic s . Each
C alend ar fe a tu re is a ls o d escrib ed . F eatu res a re lis te d
below . Much o f th e in fo rm a tio n found h ere can be
accessed more q u ic k ly u sin g c o n te x t-s e n s itiv e H e lp .
F o r in fo rm a tio n about u sin g H elp , choose th e O verview
menu ite m from th e H elp menu.

A dditional to p ic s :

Additional >
Topics
"

‘v

Using C alendar
Menus
DECwindows C alendar D isplays
B r ie f H is to ry o f th e G regorian C alendar
J u lia n P e rio d
G o B a ck

Exit
ZK-0498A-GE

•

The help topic describes the task or object about which you requested help.
Scroll b ars ap p ear if th e text does not fit in one fram e.

•

The A dditional topics list contains related topics th a t you can select to display
more inform ation. You select these topics by pointing to them and double
clicking MB1.

•

The help buttons, Go Back and Exit, let you display the previous help fram e
or exit from Help.

l b get help on screen objects, such as m enu nam es, scroll bars, and dialog boxes,
point to the screen object and press and hold the Help key on your keyboard while
you click MBi. N ote th a t help on objects is not available in all DECwindows
applications.
To get help on a menu item, press the Help key while you press and hold MBi on
the menu item, then release MBI.
A help window opens, displaying inform ation on the object you specified.
You can display product inform ation about your application, such as the software
version num ber, by choosing About from th e application’s Help m enu. In some
applications, th e Help m enu also contains a Glossary m enu item , which you can
use to look up term s specific to your application.

A-18

Using DECwindows

For more inform ation about using Help, choose Help from th e Help m enu in each
application’s help window.

A .18.2

N a v ig atin g in H elp
W hen you select a topic from the Additional topics list in th e Overview window,
you s ta rt down a p a th th a t is lim ited only by your own curiosity. You can follow
a p ath of topics by continuing to select additional topics, retrace your steps and
branch off to a different topic, or re tu rn to the Overview fram e and s ta rt down
another path.
To display an additional topic:
1.

Select the item from th e list of additional topics.

Choose Go To from th e View m enu.

F a ste r still, ju s t double click on th e topic you w ant. Double clicking on a topic is
a shortcut for selecting th e topic and choosing Go Tb.
Help displays th e selected topic. You can continue to select other topics from the
Additional topics list or redisplay th e topic you la st saw by clicking on the Go
Back button.
If you w an t to display th e cu rren t topic and a new topic sim ultaneously:
1.

Select another topic from the list of additional topics.

Choose Visit from the View m enu.

Instead of replacing th e cu rren t help topic w ith the new topic, another help
window opens displaying inform ation about th e new topic. You can th en explore
other topics from the new help window and keep the current topic open for
reference.
Tb see the p ath you followed to get to your cu rren t topic:
1.

Choose History... from Help’s Search m enu.
Help displays a dialog box th a t lists the topics you have already seen.

Double click on a topic to replace the current topic or select a topic and
click on th e Visit b utton to open another help window w ithout replacing the
cu rren t topic.

W hen you finish looking a t a topic and w ant to close the help window, click on the
E xit button. I b re tu rn to th e Overview fram e, choose Go l b Overview from the
View m enu in any help window.

A .18.3

S e a r c h in g H elp fo r T itle s a n d K e y w o rd s
You can search Help for words or phrases to see w hether they appear in topic
titles or in help text. For example, you m ight w an t to see w hether th ere is a topic
title in M ail th a t contains the word “Sending”, or a topic in which the phrase
“m essage” appears.
l b search for a word or p hrase contained in a topic title:
1.

Choose Title... from H elp’s Search m enu.
Help displays a dialog box.

In the Title text field, type th e word or phrase you w an t to search for.
Using DECwindows

A-19

Leave this field em pty if you w an t Help to display a list of every topic title.
3.

Click on Apply.
Help displays th e topics whose titles contain the word or phrase you specified.

To display the topic whose title contains the word or phrase you searched for,
double click on th e topic or select it and click on the Visit button. Help displays
th e topic in another window. The Search Topic Titles dialog box rem ains open for
you to continue your topic search.
Help for each application h as predefined words or phrases called keywords th a t
you can search for. To search for a keyword used in a topic:
1.

Choose Keyword... from H elp’s Search m enu.
Help displays a dialog box th a t lists the keywords defined for th a t application.

Double click on the keyword you w ant to search for.
Help lists the topics in which the keyword is used.

To display the topic in which the keyword is used, double click on the topic or
select it and click on th e Visit button. Help displays the topic in another window.
The Search Topic Keywords dialog box rem ains open for you to continue your
keyword search.

A .18.4

E xiting fro m H elp
l b exit from Help, click on th e E xit button. If you have m ultiple help windows
open, you m u st close each one.

A.19 Putting a S ession on Hold
A t any tim e, you can p u t your c u rren t session on hold indefinitely and lock your
w orkstation w ithout ending your session. W hen you p u t your session on hold,
your screen is cleared, b ut your session is m aintained exactly as it was. Any
applications you sta rte d continue to run.
l b p u t your cu rren t session on hold, choose P ause from th e Session M anager’s
Session m enu. Your screen is cleared and the C ontinue Session dialog box is
displayed.

Tb continue your session, type your passw ord and press Return. Once th e system
verifies your password, your session resum es. If the C ontinue Session dialog box
A-20

Using DECwindows

rem ains on your screen^ you probably m ade a typing m istake. Click on the C lear
button and type your passw ord again.

A.20 Ending a S ession
You can end a session a t any tim e. W hen you end a session, DECwindows stops
all applications and clears the screen.
To end your session:
1.

Choose Q uit from th e Session M anager’s Session m enu.
The Session M anager displays a dialog box asking you to confirm th a t you
w ant to end the session.

Click on OK or press Return.

Using DECwindows

A-21

Appendix B

Performance Hints
LISP code norm ally does m uch type checking a t runtim e. You can reduce
execution tim e and am ount of mem ory required by using d a ta stru ctu res more
efficiently and by using certain program m ing an d debugging techniques.
This appendix lists w h at you can do to optimize the speed of execution of your
LISP code and the am ount of m em ory required. The sections also give the
following inform ation:
•

N um ber of instructions executed by certain functions

•

R elative speed of certain functions compared w ith others th a t can be used to
achieve th e sam e resu lt

•

E xplanations of why certain functions and operations require m ore tim e or
m em ory

•

D ata stru c tu re representations

This inform ation can help you choose the m ost efficient w ay to code a program .
Some VAX instructions a re m entioned in this appendix. Refer to th e V AX
A rc h ite c tu re H a n d b o o k for m ore inform ation on the VAX in struction set.

B.1 Data Structures
This section describes how to optimize the use of d a ta stru ctu res in your code.

B.1.1

I n te g e rs
Fixnum arithm etic is m uch faster th a n bignum arithm etic. Therefore, if possible,
use num bers in th e ran g e -2**28 to 2**28-l. The m o s t -n e g a t i v e -f i x n u m is
-268435456; the m o s t -p o s i t i v e -f i x n u m is 268435455. (The range of integers
represented as fixnum s in V3.0 was cut in h a lf from V2.2.) You m u st use fixnum
declarations for each argum ent to an arithm etic function and for the resu lt
as well to generate fixnum-only in-line VAX instructions. The re s u lt m u st be
declared to be type fixnum, and even though all in p u t values for a n arithm etic
function m ay be fixnum s, the resu lt m ay not be. (T hat is, fixnum s are not closed
under arith m etic operations.)
W hen fixnum declarations a re used, fixnum arithm etic takes one instruction for
each addition or subtraction operation and two instructions for each m ultiplica
tion and division operation. Fixnum comparisons consist of a CMPL instruction
and th e appropriate branch; the resu lt’s type need not be declared since it m u st
be e ith e r T or n i l .

Performance Hints

B-1

Fixnum s are never allocated (they are im m ediate: they a re always m anipulated
directly, ra th e r th an through pointers). Therefore, fixnum arithm etic requires
less m em ory and less tim e for garbage collection th an arithm etic w ith bignums.
Bignum s require one longword for a header and enough space to represent
th e num ber in two’s com plem ent form at w ith a m inim um of two longwords.
Therefore, w orking w ith bignum s consumes m uch m ore tim e and space th an
working w ith fixnum s. For example, to p rin t 1000 factorial takes m uch longer
th a n to compute it. M uch more garbage is produced while calculating the prin t
representation th an in calculating the result.

B .1.2

F lo a tin g -P o in t N u m b e rs
W hen using floating-point arithm etic, th e system allocates new space for the
results. In-line code is generated only w hen both argum ents to an arithm etic
function are declared to be of the same floating-point type. In-line conversions
(CVTxx) are not done. The VMS m ath library routines are used for complicated
functions, such as trigonom etric functions.
Floating-point num bers alw ays have a 1-longword header.

B .1.3

R a tio s
W hen w orking w ith ratios, the system calls th e GCD function after each ratio
is created and stores the ratio in canonical form. Use th e TRUNCATE or REM
function w hen you do not need exact answ ers or w hen you w ant a rem ainder. The
truncate function executes faster if you can declare the resu lt to be a fixnum.
The truncate and rem functions are faster th an the floor and mod functions.
These in tu rn are faster th a n the round function.
Ratios occupy two longwords; they have a 1-longword header.

B .1.4

C o m p le x N u m b e rs
The real p a rt and the im aginary p a rt of any complex num ber m u st be of the same
type: both m u st be integers, single-floats, double-floats, or long-floats. Complex
num bers occupy 2 longwords; they have a 1-longword header.

B .1.5

C h a r a c te r s
S trin g characters use a n 8-bit code th a t is compatible w ith the ASCII and Digital
m u ltinational stan d ard s and w ith the VAX architecture.
The char= function used w ithout type checking is th e sam e as th e eq function.
The char<, char<=, char>, and char>= functions generate th e sam e code as the
fixnum com parisons w hen no type checking is required because declarations
w ere used. This code consists of a CMPL instruction followed by the appropriate
branch. Like fixnums, characters are never allocated (they are im m ediate),
thereby requiring less m em ory and less tim e for garbage collection.

B-2

Performance Hints

B .1.6

S y m b o ls
Symbols let you easily associate d a ta w ith a nam e. Symbols are interned w hen
read by the r e a d function, and rem ain interned u n til they are un in tem ed from all
packages using them . So, w hen you create anonym ous variables and functions,
use uninterned symbols (created using the m a k e - s y m b o l or g e n s y m function).
For VAX LISP, accessing a dynam ic variable m ay require several instructions,
depending on the declarations and optim izations used. Normally, accessing
a dynamic variable is slower th a n accessing local variables or closed-over
lexical variables. A local variable can be accessed quickly because it is stored
on the stack. A closed-over variable is stored in a vector and passed to other
functions th a t use them . Therefore, to access a closed-over variable m ay require
several instructions. To reduce the overhead of dynamic variable access to
one instruction, set th e optim ization declaration s p e e d to 3 and s a f e t y to 0,
elim inating unbound variable checking and th u s reducing execution time.
W hen a special variable is bound to a new value, LISP saves the symbol and its
old value on th e binding stack and stores the new value in th e value cell of the
symbol. This procedure requires eith er four or five instructions. U nbinding a
special variable requires one instruction. Accessing the p a rts of a symbol, such as
its name, property list, package, and value, requires only one instruction each, if
you have used the appropriate declarations to declare the variable as a symbol.
Symbols occupy six longwords each.

B .1.7

L is ts a n d V e c to rs
Use lists w hen the num ber of elem ents changes often. Typically, you push
elem ents onto and pop elem ents off the front of the list to sim ulate a stack.
Conses are convenient for creating tree structures, especially w hen you need
values only a t the leaves. If you m u st access m any values a t each in tern al node
of a tree, use stru ctu res ra th e r th a n lists. Conses require two longwords.
Use vectors w hen you m u st access elem ents often a t any position. Vectors use
h a lf as m uch space as lists and can cause less paging w hen accessed, because
vector elem ents are stored in adjacent m em ory locations. A simple-vector h a s a
single-longword header.
Use th e noncopying (or destructive) versions of the sequence and list functions
w henever possible. For example, the n c o n c function is fa ste r th a n th e a p p e n d
function and th e n s t r i n g - u p c a s e function is faste r th a n th e s t r i n g -u p c a s e
function. You can use the form ( n r e v e r s e ( t h e l i s t x ) ) ra th e r th a n the copying
version (the r e v e r s e function) to get elem ents back to th e ir original order if
you are ju s t gathering the resu lts in a list. To copy in p u t lists or strings once
and th en do destructive operations is m ore efficient th a n to alw ays use copying
versions of functions.
Copying vectors by using the c o e r c e or s u b s e q function resu lts in simple vectors
(of the type s i m p l e - v e c t o r , s i m p l e - s t r i n g , s i m p l e -b i t -v e c t o r , or s i m p l e a r r a y ), which can be m anipulated by simpler, faster operations. Therefore, you
can copy a vector to m an ipulate it quickly thereafter. However, to avoid num erous
garbage collections, do not use copying versions of functions unless you m ust.
NOTE
Use destructive versions of functions w ith care, as shared d a ta m ay be
modified.

Performance Hints

B-3

c a r , c d r , and the other list-m anipulating functions by default alw ays check th eir
argum ents to m ake sure they are lists and not atom s. Tb increase the speed of
list-intensive applications, properly declare all lists and use the optim ization
declaration s p e e d = 2 or use s p e e d = 3 and s a f e t y = 0. The c a r , c d r , r p l a c a , and
RPLACD functions each require one instruction when used w ith these declarations.

If you frequently splice or concatenate lists, use a pointer to the m iddle or end
of the list. This procedure is faster th an using th e n t h c d r , m e m b e r , a p p e n d , and
n c o n c functions on the entire list, as they always process from the beginning of
the list. The faste st tests for the m e m b e r , a s s o c , and r a s s o c functions are e q and
EQL, not e q u a l or = . The default te st is EQL.
U se property lists w hen you w ant values for keys to be global in scope. Do not
use property lists if th e num ber of keys is fairly constant and know n in advance.
Instead, use structures and include a slot in the stru ctu re for a list to be used
like a property list for keys th a t are unknow n when the stru ctu re is defined.
Use association lists w hen you w ant values for keys to be dynam ic in scope, since
pushing en tries onto the front of an association list shadows la te r entries. You
can use dynamic variables as pointers into association lists to help you recall
additions to th e lists, and autom atically restore the values.

B .1.8

S trin g s , G e n e ra l V e c to rs, a n d Bit V e c to rs
Sim ple array s of one dimension, [ ( s i m p l e - a r r a y * 1 ) ], a re processed faster
th a n nonsim ple vectors (vectors w ith fill pointers, adjustable vectors, or displaced
vectors). Vectors th a t are simple take less space since they do not have separate
a rra y headers and th ey are created faster.
Avoid using lists of characters when m anipulating symbol nam es (th a t is, never
im plem ent th e EXPLODE or i m p l o d e functions of earlier dialects of LISP). Strings
a re fully supported in this language, unlike these earlier dialects. Some common
operations on sim ple strings use the VAX character instructions.
M any d a ta structures th a t used to be im plem ented w ith lists can be more
efficiently im plem ented w ith simple-vectors or w ith structures. If th e dom ain of
a set is fixed and set operations are frequent, using simple bit vectors is m uch
faster th a n using lists. Accessing or updating slots of a declared stru ctu re takes
only one instruction given the appropriate declarations. Accessing or updating
ch aracters in a simple string or bits in a sim ple bit vector is slightly slower
th a n accessing or updating elem ents of a simple-vector. W hen accessing or
up d atin g characters in a simple strin g or bits in a simple b it vector, d a ta m u st
be converted betw een th e in tern al representation and th e LISP representation.
F or both characters and fixnums, th is involves a t least an ASHL instruction.
However, th ere are specialized routines for handling sim ple strings and simple bit
vectors (for example, th e s t r i n g - u p c a s e and b i t - a n d functions w ith th e proper
declarations).
These representations tak e less space th a n simple general vectors th a t hold
characters or bits.

B .1.9

H a s h T a b le s
H ash tables provide a good way of storing and accessing a rb itra ry objects.
A lthough some overhead is required for each access or store, th e total tim e
required is usually reasonable even for large num bers of objects. VAX LISP h ash
tables use chains to resolve collisions.

B—4 Performance Hints

You can access h ash tables th a t use the e q and e q l functions faster th an h ash
tables th a t use the e q u a l function, because the comparisons are faster. However,
h ash tables th a t use th e e q and EQL functions m u st be completely rehashed upon
first use a fte r any garbage collection. H ash tables are preferable to lists and
b it vectors for representing sets, w hen th e num ber of objects m ay be large and
extrem ely variable.

B .1.10

F u n c tio n s
Compiled code is faste r th a n in te rp re te d code; w hen in terpreted code is evaluated,
m uch consing occurs.
Calling a compiled function th a t is a closure takes several instructions more th a n
calling a compiled function th a t is not a closure. A function is a closure w hen it
h a s free lexical variable references.
You can compile single functions a t any tim e w ithout using files. For example, to
compile a function you have ju s t defined, you can use ( c o m p i l e ' f u n c t i o n - n a m e )
or ( c o m p i l e n i l ' ( l a m b d a ( ) , . . . ) if you w an t to create anonym ous code to be
stored and executed later. You can use the f t y p e type specifier in a declaration
or proclam ation to inform the compiler about th e types of th e argum ents and the
re tu rn type of a function.

B.2 Declarations
This section describes how to use declarations to optimize LISP code.
By default, m ost stan d ard VAX LISP functions check th eir argum ents for type
and other attrib u tes. The compiler can generate m uch faster code for m any
simple operations by assum ing the argum ents are of the correct type. Therefore,
use declarations to supply th is inform ation.
W hether th e compiler tak es advantage of declarations and to w hat extent it
does, is controlled by th e o p t i m i z e declaration. Depending on the values of the
optim ization qualities, different code m ay be generated, given th e presence of
type declarations or the assum ption of such type declarations.
The form at for using th e o p t i m i z e declaration and its qualities w ith the p r o c l a i m
and d e c l a r e forms i s as follows:
(PROCLAIM ’
(OPTIMIZE (SPEED x) (SAFETY y) (SPACE z)))

or
(DECLARE (OPTIMIZE (SPEED x) (SAFETY y) (SPACE z)))

The possible switch values are:
x = l,y = l, z = l

(the default)

No p articu lar optim izations done. Generally, type checking will be done
on all argum ents to LISP functions.

x= 2 y< 2

Observes user-Bupplied declarations. Useful w hen some variables are
guaranteed to be of th e declared type and speed is desired, b u t w hen
not all variables (such as function argum ents) can be guaranteed to be
correct. Some m acros (such as DOTIMES and D O L I S T ) expand into code
w ith th ese declarations already supplied.

* > 1 , y= 0

Skips bounds checking for vector and arra y references.

Performance Hints

B-5

x= 3 ,y= 0

Assumes correct argument types to many functions, such as CAR,
SYMBOL-NAME, and SCHAR. Useful for guaranteed correct and debugged
functions. Special variable references do not check for unbound values.
Explicit type checking is ignored.

x>y

Does tail recursion removal, if it can.
The THE function generates tests for objects being the specified type.
Useful for fixnum declarations to detect overflows into bignums.

y= 3

Tries to open-cods some sequence functions. Observes in-line declara
tions.

x>z

Use fixnum and floating-point declarations for fast arithm etic. The compiler
needs to know the types of all the argum ents (and for fixnums, the resu lt
type, too) before it can generate the fast, type-specific code available on a VAX.
Floating-point operations w ith operands (and therefore results) of th e sam e type
can also generate fast code.
Use sim ple-vector and sim ilar a rra y declarations for fast sequence and a rra y
operations. For example,
( l e t ( ( v . . .) )
( d e c la r e (ty p e

(sim p le -a rra y

(u n sig n e d -b y te -8 )

v) )
(th e

fix n u m

(aref v
(aref v

0)
1))))

only takes a few instructions w hen compiled w ith the ( o p t i m i z e ( s p e e d 3) ( s a f e t y
0)) declarations. D eclaring stru ctu res is equally helpful.
The p r o c l a i m and DECLARE forms m ay be used to declare a function’s argum ents
and resu lts w henever th e function is called. For example, w hen th e proclam ation
( p r o c l a i m ' ( f t y p e ( f u n c t i o n ( f i x n u m ) s i n g l e - f l o a t ) m y f u n c t i o n ) ) is used,
each tim e m y f u n c t i o n is called th e argum ents are autom atically declared to
be fixnum s and its resu lt is autom atically declared to be a single-float. An
f t y p e declaration does not autom atically provide declaration of the l a m b d a - l i s t
variable in th e function definition.
It is im p o rtan t to provide type declarations, especially for the s i m p l e - v e c t o r ,
s i m p l e - s t r i n g , and s i m p l e - b i t - v e c t o r types, for the argum ents to sequence
functions. The compiler can generate fast code for m ost common cases. Even
if th e elem ent type is not known a t compile tim e, adding ( s i m p l e - a r r a y * l )
declarations helps.
M ultidim ensional a rra y operations benefit from declarations. U nlike the vector
operations, m ultidim ensional array s need the actual (fixnum) bounds for each
dim ension a t compile-time to generate efficient array-indexing code. In these
cases, it is helpful to use th e d e f t y p e macro.
The functions defined in th e following exam ples will be compiled w ith eith er (1)
type-checking code if s p e e d is less th a n 2 or (2) non-type-checking code if s p e e d
equals 3 and s a f e t y equals 0. However, the second exam ple produces code th a t
does not check th e type o f* b u t does check the type of ( c d r x ) , w hen s p e e d
equals 2 and s a f e t y is less th a n 2. This is because th ere is a declaration allowing
th e optim ization of th e CDR operation b u t no declaration for the c a r operation.
(d e fu n e x am p lel
(cadr x ) )

(x)

( d e f u n e x a m p l e 2 (x)
(d e c la re ( l i s t x ) )
(cadr x ) )

B-6

Performance Hints

In the following exam ples, a call to EXAMPLE3 alw ays produces generic code, since
it is not known th a t the resu lt of th e addition will necessarily be a fixnum. The
declaration in e x a m p l e 4 provides th a t inform ation, a n d th e arithm etic operation
is fixnum specific.
( d e f u n e x a m p le 3 (x y)
( d e c l a r e (fix n u m x y ) )
(+ x y ) )
( d e f u n e x a m p le 4 (x y)
( d e c l a r e (fix n u m x y ) )
( t h e f i x n u m (+ x y ) ) )

The next exam ple re tu rn s a list of the first, indexed, and la s t characters. With
s p e e d g rea ter th a n or equal to 2 and s a f e t y equal to 0, all th e character fetching
from the s t r i n g argum ent will be very fast. The l e n g t h operation will also be
very fast, since it need not check for the type of the arg u m en t as th e generic
sequence function norm ally would. (This also m eans executing th e form (l e n g t h
( t h e l i s t x ) ) is faste r th a n executing th e form ( l e n g t h x ) .) If s a f e t y is
greater th a n 0, bounds checking is still done, b u t type checking (of th e string, for
example) m ay not be, depending on w hat optim izations are used.
(d e fu n e x am p le5 ( s t r i n g in d e x )
(d e clare
(sim p le -strin g s trin g )
(fix n u m i n d e x ) )
( l i s t ( a r e f s t r i n g 0)
(c h ar s t r i n g in d ex )
(sc h a r s t r i n g (1- (le n g th

strin g )))))

A rray access is fast in the following code:
(e v a l-w h e n (c o m p ile lo a d e v a l)
( d e f c o n s t a n t i - s i z e 3)
( d e f c o n s t a n t j - s i z e 4)
( d e f c o n s t a n t k - s i z e 5)
(d e fty p e f o o a r r a y (& o p tio n a l e le m e n t-ty p e )
'( s im p le - a r r a y , e le m e n t-ty p e ( , i - s i z e , j - s i z e

( d e f u n f o o ()
( d e c la re (ty p e
(ty p e

(fooarray
(fo o array

t ) x)
strin g -c h a r)

(d o tim e s ( i i - s i z e )
(d o tim e s (j j - s i z e )
( d o t i m e s (k k - s i z e )
( s e t f ( a r e f x i j k)
(ch ar-u p case (a re f

y i

,k -s iz e ))))

y ))

k ) ))))))

B.3 Program Structure
In tig h t in n er loops, use m acros or in-line functions r a th e r th a n called functions.
Always compile m acro definitions, functions proclaim ed in-line, a n d calls to the
DE FSTRUCT m acro before compiling code th a t uses them . Normally, you proclaim
a function in-line ju s t before defining it. Any calls to th a t function will then
have th e body expanded in-line a t th e calling site, unless you use th e n o t i n l i n e
declaration. If you declare or proclaim a function, using th e i n l i n e declaration
a fte r providing a definition, a compiler w arning will re su lt because th e compiler
will not have remembered the definition for the in-line function.

P e rform a n ce Hints

B -7

The Funcall and apply functions are slower th a n calls to functions whose nam es
are known a t compile tim e, because the LISP system m u st check th e following:
•

W hether the object is a function

•

W hat kind of function (by symbol or function object, in terp reted or compiled)

•

The num ber of argum ents th e function takes

U sing apply to call a function is usually two to three tim es slower th an a
compiled call to a nam ed function w ith a fixed num ber of argum ents.
The catch special form and operations th a t use the catch-throw m echanism are
slower th a n a function call.
U sing the &OPTIONAL keyword in a lam bda-list costs a few instructions. However,
an &rest variable causes a list to be created for those argum ents passed after
th e required and &optional argum ents. &key argum ents a re the slowest; there
is run-tim e code to parse the argum ent list and assign th e proper values for the
given keywords, and evaluate the defaults for th e unsupplied keywords.
U sing m ultiple values requires less tim e and space th a n consing a list or vector
of results. Both m ethods are slower th a n ju s t retu rn in g single values. (Consing
requires garbage collections later.)
The read function is slower th a n the read-line or read-char function, since
read has to parse the in p u t according to the current LISP read er syntax, create
num bers, and in tern symbols. The read-char function is slower th a n the
read-line function, due to th e general overhead of doing any I/O.
Sim ilarly for output, calls to write, print , p r in i , and princ are slower th a n calls
to write-char, write-line , an d write- string due to th e need to determ ine w hat
is being printed.
The format and pprint functions are slower th a n calls to th e write, print , princ ,
and PRINI functions when p retty prin tin g and *print -circle * are disabled.
U sing the xxx- to-string functions for getting a string representation of a
LISP object is faster th an using th e with-output-to- string function. The
with-output-to- string function m u st create a stream and use th e usual stream
functions. The read-from- string and parse- integer functions are faste r th a n
th e with- input-from- string function for th e sam e reason.
The compiler compiles each top-level form in a file w hen it compiles a file by
surrounding a rb itra ry forms in the following m anner:
(P R O G N (DEFUN #:TOP-LEVEL-FUNCTION () arbitrary-top-level-form )
(#:TOP-LEVEL-FUNCTION))

An a rb itra ry -to p -le v e l-fo rm is any LISP form other th a n a call to the eval-when
or progn special form, th e defun or defmacro macro, th e proclaim function, or
a package function. Creating, compiling, dum ping, and loading these tem porary
functions takes time, so it is wise to gath er m any a rb itra ry forms into functions of
reasonable size. Typically, such form s can be calls to d a ta initialization functions
(such as ( s e t f ( g e t . . . ) . . . ) ) . Tb have these function calls inside a function
definition anyway is desirable so th a t you can do selective initialization from the
program w ithout having to reload th e file.

B -8

P erform a n ce Hints

B.4 Compiler Requirements
The PROCLAIM, PROVIDE, require, and package functions like use-package and
in-package m u st be used a t top level for the compiler to recognize them . A
top-level form is defined as a form w ithout surrounding parentheses, or a form
a t top level w ithin a call to either the eval-when or progn special form. Uses of
th e d e f u n macro and anonymous lam bdas th a t would get evaluated in code get
compiled as separate functions (closures if they use closed-over lexical variables).
This is tru e in the following call to the defun m acro and to the anonymous
lam bda th a t follows.
(le t

( (c o u n te r

0 ))

(d efu n

(try

# ' (lam b d a

(x)

(p rin t

x ) ))

()

(in cf

c o u n te r)))

If you w an t functions as d a ta objects (th a t is, in d a ta stru ctu res w here they would
not be processed during norm al evaluation), you m u st compile them explicitly.
This is exemplified by the difference betw een the following:
(lis t

# ' (lam b d a
# ' (lam b d a

()
()

(fo o ))
(b ar))

)

and
' ( # ' (lam b d a
# ' (lam b d a

()
()

(fo o ))
(b ar))

)

In the first case, th e compiler recognizes the functions and creates compiledfunction objects for them . In th e second case, th e compiler does not notice the
functions since th e entire form is quoted.
If you leave th e code in th e list a t ru n time, the explicit calls to th e f u n c a l l
function on each elem ent of the list would ru n the code interpretively. So, to have
compiled code in th e list, you m u st fill it w ith compiled functions. You can do this
a t ru n tim e by using the c o m p i l e function w ith n i l as th e first argum ent, or you
can fill the lis t w ith compiled functions once, when loading. Or, you can compile
a file, using m acros th a t expand into definitions of functions w ith nam es created
using the g e n s y m function. Then, have an initialization function fill up th e list
w ith those compiled functions a t load time.

P erform a n ce Hints

B -9

Appendix C

Customizing DECwindows from VAX LISP
This appendix describes how to customize the DECwindows-based developm ent
environm ent in VAX LISP V3.0.

C.1 Customizable Attributes
Your DECwindows-based developm ent environm ent h a s a particu lar look. This
look is m ade up of certain attrib u tes, such as color, font, and the position of
th e windows. You can change th e look of the DECwindows-based developm ent
environm ent by custom izing th e common attrib u tes for all utilities and some
specific a ttrib u tes for a given utility. The a ttrib u tes are independent of the
syntax used for changing them . (See Section C.3 for inform ation on syntax.) This
section describes all th e attrib u tes.

C.1.1

C o m m o n A ttrib u te s
W ith the exceptions noted, you can set th e following attrib u tes for each utility,
potentially for each window in a utility.

Geometry
The position, w idth, and height in pixels of the m ain window in a utility. For
th e Inspector, you can set only the geom etry for the Inspector H istory window;
th e Inspect windows have more specific a ttrib u tes (see Section C .l.2.1). For the
Editor, you cannot set th e geom etry a rb itrarily —th ere are m ore specific attrib u tes
for it (see Section C. 1.2.5).

Color
The color of the foreground and background of each of the windows. On color sys
tem s, you can set these to a rb itra ry values, w ithin th e constraints of th e num ber
of colors available on your system . This setting is ignored on monochrome
system s. The defaults are the values th a t you set w ith th e DECwindows
Session M anager. For inform ation on nam ed colors available to you, see V M S
D E C w in d o w s G u id e to XLib P ro g ra m m in g .

Monochrome reverse
Reverses the foreground a n d background colors on monochrome system s, black
foreground on a light background or vice versa. This setting is ignored on color
system s. The default is n i l —no change.
Font
The font used for all in p u t and output in a utility. Individual windows in a utility
can have different fonts. If you have specified a font description th a t does not
exist on the server w here LISP is displayed, the specified font is ignored a n d the

C u sto m izin g D E C w in d o w s from VAX LISP

C-1

server’s default font is used. If you change to a variable-w idth font, text m ay
not ap p ear to be column aligned as it is by default. The default for all utilities
except the E ditor is Courier Bold 14. The default for th e E ditor is Term inal 14,
which is the same as the sm all D EC term font. The E ditor disallows th e use of a
variable-w idth font. For inform ation on how to find th e font nam es th a t exist on
your c u rren t system , see Section C.2.
Object recording
W ith object recording tu rn ed on, th e position of an object is stored w hen it is
w ritten to the screen and pointer feedback is displayed. T urning off this a ttrib u te
decreases the am ount of system overhead for w riting to th e window. T urning off
object recording in th e Inspector, Trace List, Debugger Calling Stack, or Debugger
Variable Bindings windows is not useful, because th e ir syntax and function
fundam entally rely on object inform ation. This a ttrib u te is useful only for the
Listener, Debug I/O window, and the Trace O utput region of th e Trace window.
This a ttrib u te does not apply to the E ditor because it does not do object recording.
The default is t — object recording is tu rn e d on.

C .1.2

S p e c ific A ttrib u te s a n d R e s tric tio n s
Some utilities have additional attrib u tes th a t you can customize. The E ditor
h a s restrictions on custom izing common attrib u tes. These specific custom izable
a ttrib u tes and restrictions are described below.

C.1.2.1

Inspector Attributes
Inspect windows count
An integer representing the num ber of Inspect windows th a t th e Inspector ro tates
through as you perform subsequent inspections. The default is 5.
Inspect windows geometry
The size of th e Inspect windows w hen they a re first created and th e position of
th e first Inspect window. The positions of subsequent windows are calculated
ffom th is position and the Inspect window geometry offset attrib u te.
If you resize, close, and reopen a window (th a t is, rem ove th e window w ith the
Close item and bring it back through a la te r call to i n s p e c t ), it comes up the size
to which you resized it. If you change the position portions of this value, only
windows created after the change will be affected.
Inspect windows position offsets
The value in pixels indicating w here subsequent windows are draw n relative to
th e in itial Inspect window. For example, if the in itial position is 800,100 and the
offset is -50,100, th e first window appears tow ard th e upper rig h t corner of your
w orkstation screen (assum ing it is 1024 pixels wide). The next window appears
lower and to the left, a t position 750,200. The next window is draw n along the
sam e line, a t 700,300.
Sequence length threshold
An integer indicating how m any elem ents of a sequence to inspect before prom pt
ing you to continue. Only elem ents up to the threshold are computed and printed,
a t which tim e you are prom pted for w hether you would like to see more. The
default is 75.

C-2

Customizing DECwindows from VAX LISP

C.1.2.2

Listener Attributes
Evaluation history limit
An integer value denoting how m any evaluations to store for command-line recall.
If you raise th e lim it, your tra n sc rip t and comm and recall rin g grow. If you lower
th e lim it, the oldest (OLD-VALUE—NEW-VALUE) evaluations are im m ediately
rem oved from the tran scrip t and th e recall ring. The default is 40.
Prompt on Exit
W hen th is a ttrib u te is tu rn ed on, you are prom pted w hen you tiy to exit the
L istener through the File m enu E xit item . The default is for you to be prompted.

C.1.2.3

Debugger Attributes
Evaluation history limit
An integer value denoting how m any evaluations to store for comm and-line recall.
The default is 40.
Auxiliary windows initial states
Open or closed for th e three Debugger auxiliary windows: Control Stack, Variable
Bindings, and Debugger Commands, these values apply only to th e first tim e you
e n te r th e Debugger. If you open or close any of them d u ring a debugging session,
th e ir sta te as you leave the Debugger is how they will ap p ear w hen you reenter
it. The default is to have each window open.
Prompt on entry
True or false denoting w hether you a re prom pted about entering the Debugger
w hen an error or continuable erro r is signaled. The default is true, you are
prom pted about entering the Debugger.
Prompt on exit
True or false denoting w hether you are prom pted w hen you try to q uit the
Debugger through a m enu item , comm and button, or w ithout specifying the T
arg u m en t to th e Debugger quit command. The default is true, you are prom pted
about q u itting the Debugger.

C. 1.2.4

Trace Attri butes
Prompt on untrace all
True or false denoting w hether you a re prom pted w hen you choose th e U ntrace
m enu item w ith no selection. The default is true, you are prom pted about u n trac
ing all item s in the Trace List.

C.1.2.5

Editor Restrictions
The E ditor does not have additional custom izable attrib u tes; rath er, th ere are
some restrictions on E ditor custom ization.
Restrictions on Common Customizations
E ditor w idth and height are specified in character-cell rows and columns, not in
pixels. The E ditor cannot handle a window th a t is not aligned on character cell
boundaries. The font m u st be fixed w idth. The E ditor does not correctly display
tex t or draw the cursor, using a variable-w idth font.

C u sto m izin g D E C w in d o w s from VAX LISP

C -3

LIST-FONTS function
Conflict with Older Editor Customizations Through LISP
For backw ard compatibility, any custom izations m ade to the E ditor through the
DECwindows interface are overridden by any LISP initializations as supported in
earlier versions of VAX LISP. For example, suppose th a t you change the default
E ditor screen w idth through custom ization. If, however, you still have a form like
(se tf

( e d ito r :sc ree n -w id th )

132)

in a LISP file th a t you load, th en 132 is your E ditor screen w idth, regardless of
custom ization settings. If you w ant your stored custom ization settings to take
precedence, you m u st remove all the LISP forms th a t set editor variables or setf
forms th a t modify the E d ito r’s appearance.

C.2 Getting Information on Fonts
VAX LISP provides the l is t -fonts function to get information on fonts.

LIST-FONTS function
You can use th e l is t -fonts function to find out which font nam es exist on the
cu rren t system . E lem ents in th is list are legal new values for the setf forms w ith
DECW-UTILS: CUSTOMIZE and the :FONT a ttrib u te argum ent. This function should
be used only for custom izing th e developm ent environm ent. For w riting CLX
program s you should use CLX:l is t -font-names w ith the appropriate argum ents,
since the CLX:display used by your program m ay not be the sam e one used by
th e developm ent environm ent.

F o rm a t
DECW -UTILS:LIST-FONTS

&OPTIONAL fon tn am e

fontname
A string th a t nam es a font. The string m ay contain m ultiple occurrences of the
wildcard character ( * ) to avoid supplying all components of the font nam e. Case
is ignored.

C-4

C u sto m izin g D E C w in d o w s from VAX LISP

LIST-FONTS function

R e tu rn V alue
A list of strings th a t nam e the fonts available on the c u rren t X server whose
nam es m atch th e specified fo n tn a m e, if supplied. Otherwise, all fonts known to
th e server are listed.

E x a m p le s
1.

L isp > ( d e c w - u t i ls : l i s t - f o n t s " * h e lv e tic a * - 1 2 -* " )
(" -A d o b e -H e lv e tic a -M e d iu m -R -N o rm a l— 1 2 -1 2 0 -7 5 -7 5 -P -6 7 -IS O 8 8 5 9 -1 "
" -A d o b e -H e lv e tic a -B o ld -R -N o rm a l— 1 2 -1 2 0 -7 5 -7 5 -P -7 0 -IS 0 8 8 5 9 -1 "
" -A d o b e -H e lv e tic a -B o ld -0 -N o rm a l— 1 2 -1 2 0 -7 5 -7 5 -P - 6 9 - IS 0 8 859-1"
" -A d o b e -H e lv e tic a -M e d iu m -O -N o rm a l— 1 2 - 1 2 0 -7 5 -7 5 -P -6 7 -IS O 8 8 5 9 -1 " )

This example asks for all th e 12-point fonts in th e Helvetica family. The order
in which they are retu rn ed is dependent on the X server, so you should not
count on it to always be th e same. (The R m eans Roman and th e 0 m eans
Oblique.)
2.

L isp > ( d e c w - u t i ls : l i s t - f o n t s " * - b o ld - i- * - 8 - * " )
( " -A dobe-N ew C e n tu r y S c h o o lb o o k - B o ld - I - N o r m a l— 8 - 8 0 - 7 5 - 7 5 - P - 5 6 - 1 S 0 8 8 5 9 -1 "
" -A d o b e -T im es-B o ld -I-N o rm a l— 8 -8 0 -7 5 -7 5 -P -4 7 -IS 0 8 8 5 9 -1 ")

This exam ple asks for all th e bold and italic 8-point fonts.

C u sto m izin g D E C w in d o w s from VAX LISP

C -5

CUSTOMIZATION function

C.3 Getting and Modifying Attributes
VAX LISP provides the customization function to modify the screen display.

CUSTOMIZATION function
This function re tu rn s the value of the a ttrib u te specified by its argum ents. You
can use it w ith setf to change th e value. W ith th e exceptions noted below, when
you use this routine w ith setf , the appearance of th e associated window changes
im m ediately (if it is visible—if not, th e change is ap p a re n t the next tim e th e
window is brought up). Changing the geometry w ith th e pointer and the window
m anager is the sam e as doing it by calling the setf form. Subsquent calls to the
function will show this new value.

F o rm a t
DECW -UTILS:CUSTOMIZATION

ob ject-k ey w ord attribute-keyword

object-keyw ord
This arg u m en t m u st be a keyword th a t specifies some object in th e user interface
(either a utility, a group of windows, a window, or a region of a window). The
value of th is argum ent restricts which attrib u te-k eyw o rd , is applicable, as follows:
Table C—1: Object Keywords for DECW-UTILS:CUSTOMIZATION Function
Object Keyword

Attribute Keyword

:DEBUGGER

:FONT
:FOREGROUND-COLOR
: BACKGROUND-COLOR

:MONOCHROME-REVERSE
:GEOMETRY
:OBJECT-RECORDING
:EVALUATION-HISTORY-LIMIT
:PROMPT-ON-ENTRY
:PROMPT-ON-EXIT

:CALLING-STACK-WINDOW

:FONT
:FOREGROUND-COLOR
:BACKGROUND-COLOR
:MONOCHROME-REVERSE
:GEOMETRY
sINITIAL-STATE

:VARIABLE-BINDINGS-WINDOW

:FONT
:FOREGROUND-COLOR
:BACKGROUND-COLOR
:MONOCHROME-REVERSE
:GEOMETRY
: INITIAL-STATE
(continued on next page)

C-6

Customizing DECwindows from VAX LISP

CUSTOMIZATION function
Table C-1 (Cont.): Object Keywords for DECW-UTILS:CUSTOMIZATION
Function
Object Keyword

Attribute Keyword

:DEBUGGER-COMMANDS-BOX

FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE
POSITION
INITIAL-STATE
FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE
POSITION
INITIAL-STATE
FONT
BOLD-FONT
FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE
POSITION
FONT
FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE
GEOMETRY
SEQUENCE-LENGTH-THRESHOLD
FONT
FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE
GEOMETRY
POSITION-OFFSETS
COUNT

:STEPPER-COMMANDS-BOX

: EDI TOR

: INSPECTOR

: INSPECT-WINDOWS

:LISTENER

:APROPOS-WINDOWS

FONT
FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE
GEOMETRY
OBJECT-RECORDING
EVALUATION-HISTORY-LIMIT
PROMPT-ON-EXIT
FONT
FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE
GEOMETRY
POSITION-OFFSETS
(continued on next page)

C u sto m izin g D E C w in d o w s from VAX LISP

C-7

CUSTOMIZATION function

Table C-1 (Cont.): Object Keywords for DECW-UTILS:CUSTOMIZATION
Function
Object Keyword

Attribute Keyword

:DESCRIBE-WINDOWS

FONT
FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE
GEOMETRY
POSITION-OFFSETS
FONT
FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE
GEOMETRY
OBJECT-RECORDING
PROMPT-ON-UNTRACE-ALL
FONT
FOREGROUND-COLOR
BACKGROUND-COLOR
MONOCHROME-REVERSE

:TRACE

:TRACE-LIST

attribute-keyword
This argument must be a keyword that specifies an attribute. The value of this
argument restricts the type of new value allowed when this function is used with
setf. The following table shows both the o b ject-k eyw o rd with which each possible
a ttr ib u te -k e y w o r d can be used, as well as the types allowable for new values.
Table C-2:

Attribute Keywords for Customization Functions

Attribute Keyword

Object Keywordt

New Value Type

:FONT

All objects except:
:DEBUGGER-COMMANDS-BOX
:STEPPER-COMMANDS-BOX

A CLX:FONT or string
naming a font (wildcard
characters allowed).

:BOLD-FONT

:EDITOR

:FOREGROUND-COLOR

All objects.

A CLX:FONT or string
naming a font (wildcard
characters allowed).
Either a CLX:COLOR,
CLX:PIXEL, or string
naming a color.

:BACKGROUND-COLOR

All objects.

Either a CLX: COLOR,
CLX:PIXEL, or string
naming a color.

:MONOCHROME-REVERSE

All objects.

T or NIL.

t "All objects" indicates all allowable values for th e object-keyword.

(continued on next page)

C -8

Customizing DECwindows from VAX LISP

CUSTOMIZATION function
Table C—2 (Cont.): Attribute Keywords for Customization Functions
Attribute Keyword

Object Keywordt

New Value Type

: GEOMETRY

A ll o b je c ts e x cep t:
: EDITOR
: DEBUGGER-COMMANDS-BOX
: STEPPER-COMMANDS-BOX
: TR A C E-LIST

(x y w id th h e ig h t) w h e re
e a c h sy m b o l’s v a lu e is a
fix n u m .

rPO SIT IO N

: EDITOR
: DEBUGGER-COMMANDS-BOX
: STEPPER-COMMANDS-BOX

(x y) w h e r e e a c h sy m b o l’s
v a lu e is a fix n u m .

r PO SITION -O FFSETS:):

: INSPECT-WINDOWS
: APROPOS-WINDOWS
: DESCRIBE-WINDOWS

(d e lta -x d e lta -y ) w h e re
e a c h sy m b o l’s v a lu e is a
fix n u m .

: OBJECT-RECORDING

: DEBUGGER
: LISTENER
: TRACE

T o r N IL .

: EVALUATI O N -H IS TO RY -LIM IT

: DEBUGGER
: LISTEN ER

A fix n u m .

: PROMPT-ON-ENTRY

: DEBUGGER

T o r N IL .

: PROM PT-ON-EXIT

: DEBUGGER
rLISTEN ER

T o r N IL .

: PROMPT-ON-UNTRACE-ALL

: TRACE

T o r N IL .

: IN IT IA L -S T A T E t

: CALLING-STACK-WINDOW
: VARIABLE-BINDINGS-WINDOW
: DEBUGGER-COMMANDS-BOX
: STEPPER-COMMANDS-BOX

O n e o f t h e k e y w o rd s
rOPEN o r : CLOSED.

: SEQUENCE-LENGTH-THRESHOLDt

: INSPECTOR

A fix n u m .

: COUNTj

: INSPECT-WINDOWS

A fix n u m .

t "AH objects" indicates all allowable values for th e object-keyword.
t This a ttrib u te does no t im m ediately affect th e appearance of any window.

R e tu rn V alue
T he re tu rn value of the function depends on th e a ttr ib u te -k e y w o rd (see
Table C-2).

E x a m p le s
1.

L is p > ( d e c w - u t i l s : c u s t o m i z a t i o n : l i s t e n e r : f o n t )
#<Font -Adobe-Courier-Medium-R-Normal--14-140-75-75-M-90-IS08859-l>
L is p > ( s e t f ( d e c w - u t i l s : c u s t o m i z a t i o n : l i s t e n e r r f o n t )
" * c o u r i e r - b o l d - * 14 * " )

"* co u rier- b o ld - * 1 4 *"
L isp > ( d e c w - u t i l s : c u s t o m i z a t i o n : l i s t e n e r r f o n t )
#<Font -A dobe-Courier-B old-R -N orm al— 14-140-75-75-M-90-IS08859-l>

The first evaluation re tu rn s th e font currently being used by the Listener, the
next evaluation sets th is to a new font, and th e la s t evaluation re tu rn s the
new font.
C u sto m izin g D E C w in d o w s from VAX LISP

C -9

CUSTOMIZATION function
2.

L i s p > ( d e c w - u t i l s :c u s t o m i z a t i o n
(2 0 0 2 0 0 7 50 5 0 0 )

:l i s t e n e r

:g e o m e t r y )

This shows w here your listen er is located. If you move it by hand, you m ight
see:
3.

L i s p > ( d e c w - u t i l s :c u s t o m i z a t i o n
(2 0 3 2 4 5 750 5 0 0 )

:liste n e r

:g e o m e try )

This gives you th e exact window position. I t is h a rd to move the windows
exactly and in this case you actually moved to th e rig h t by 3 pixels. If you
w anted to move a window down by exactly 50 pixels, it is m ore accurate to do
it through the form, as follows:
4.

L isp >

(2 0 0

( d e c w - u t i l s :c u s t o m i z a t i o n :l i s t e n e r : g e o m e try )
( le t ( (g e o m e try -list
( d e c w - u tils : c u s to m iz a tio n : l i s t e n e r :g e o m e try )))
( i n c f ( s e c o n d g e o m e t r y - l i s t ) 50)
g e o m e try -list))
750 500)

(se tf

250

H ere you get the re tu rn value; modify and use it to set the new value. The
window will move im m ediately to the new position.
5.

L isp >
(2 0 0

(se tf
0 750

(d e c w -u tils : c u sto m iz a tio n
' (n il 0 n il n i l ) )
500)

:liste n e r

:g e o m e try )

This exam ple uses n i l to indicate th a t this field of the geom etry list should
be unchanged. In this example, the window is moved to the left edge of the
screen.
6.

L isp > ( d e c w - u t i ls : c u s to m iz a tio n : l i s t e n e r
# < C o lo r r e d : 0 .0 0 : g r e e n 0 .0 0 : b lu e 0 .0 0 >

:fo reg ro u n d -c o lo r)

This exam ple shows th a t the L istener is w riting tex t in black.
7.

L isp >

(se tf

( d e c w - u t i l s :c u s t o m i z a t i o n
"b lu e")

:l i s t e n e r

"b lu e"
L isp > ( d e c w - u t i l s : c u s to m iz a tio n : l i s t e n e r
# < C o lo r r e d : 0 .0 0 :g r e e n 0 .0 0 : b lu e 0 .9 8 >

:fo re g ro u n d -c o lo r)

:fo reg ro u n d -c o lo r)

This m ight be the resu lt if you tried to set the L istener foreground to blue.
The exact color set depends on the server im plem entation and how m any
colors rem ain unallocated in th e default colormap.
8.

L isp >

(se tf

(d e c w -u tils : c u sto m iz a tio n : l i s t e n e r
( c lx :m a k e - c o lo r : r e d .9 : g r e e n . 9 ) )
# < C o lo r r e d : 0 .9 0 : g r e e n 0 . 9 0 :b lu e 0 .0 0 >

:b a c k g ro u n d -c o lo r)

This exam ple sets a color to an a rb itra ry m ix of RGB values. Again, th e exact
color depends on the server.

C-10

C u sto m izin g D E C w in d o w s from VAX LISP

CUSTOMIZATION function
9.

L isp >
239

(setf

( d e c w - u tils :c u s to m iz a tio n

:liste n e r

:b a ck grou n d - co lor)

239)

In this case, if you got the c l x : p i x e l value 239 from some other window
or w idget th a t used th e default colormap, it would change th e L istener
background to this color.
10.

L isp >

(setf

( d e c w - u tils :c u sto m iz a tio n

rlisten er

:m o n o c h r o m e - r e v e r s e )

On a monochrome system , this exam ple reverses the cu rre n t light-on-dark or
dark-on-light appearance of th e window.
11.

L i s p > ( d e c w - u t i l s :c u s t o m iz a t i o n : in s p e c t- w in d o w :cou n t)
5
L is p > ( s e t f ( d e c w - u t i ls : c u s t o m iz a t i o n : in s p e c t- w in d o w :cou n t)
3

This exam ple shows how to determ ine and change the num ber of Inspect
windows used in the Inspector.
12.

L isp >

(setf

( d e c w - u tils :c u sto m iz a tio n :ca llin g - sta ck - w in d o w
:in itia l- sta te )
( d e c w - u t i l s :c u s t o m i z a t i o n :v a r ia b le - b in d in g s - w in d o w
:in it ia l- s t a t e ) )

: CLOSED

This exam ple sets th e Debugger Calling Stack window’s initial state to the
sam e value as the initial state of the Debugger Variable Bindings window.

Customizing DECwindows from VAX LISP

C-11

SAVE-CUSTOMIZATIONS function

C.4 Saving Customizations
VAX LISP provides the save-customizations function to save current customiza
tions.

SAVE-CUSTOMIZATIONS function
This function saves all the current custom izations into th e file specified by
m erging file ag ain st its default. You can load files w ritte n out by the function by
using D E C W -U T IL S :L O A D -C U S T O M IZ A T IO N S .

Form at
DECW-UTILS:SAVE-CUSTOMIZATIONS

&KEY f ile

file
A string or p athnam e th a t nam es a file or directory into which your custom iza
tions should be w ritten. The default value is
"DECW$USER_DEFAULTS:LISP$DEFAULTS.DAT".

R eturn Value
The nam estrin g of th e file actually w ritten.

E xam ples
1.

L isp >

(d e c w -u tils :sa v e -c u sto m iz a tio n s)

"LISPZ$: [ JONES] LISP$DEFAULTS. DAT;3"

This exam ple overw rites previously saved custom izations in the default file.
2.

L isp > ( d e c w - u t i l s : s a v e - c u s to m iz a tio n s : f i l e " d e f d i r : " )
" L I S P Z $ : [JO N E S .D E F A U L T S ]L IS P $D E F A U L T S .D A T ;1"

This exam ple specifies a directory to keep defaults.
3.

L isp > ( d e c w - u t i l s : s a v e - c u s to m iz a tio n s
" L I S P Z $ : [JO N E S ]L IS P -B IG F O N T S .D A T ;4 2 ”

:file

" lisp -b ig fo n ts " )

This exam ple w rites out a specialized defaults file.
4.

L isp >

(d e c w -u tils :sa v e -c u sto m iz a tio n s
: f i l e " d e f d i r : lisp -w id e w in d o w s. i n i t " )
” L I S P Z $ : [J O N E S - D E F A U L T S ] L I S P - W I D E W I N D O W S . I N I T ; 3 "

This exam ple w rites out a specialized defaults file for a certain geom etry
setup and pu ts it in a preferred directory.

C -12

Customizing DECwindows from VAX LISP

LOAD-CUSTOMIZATIONS function

C.5 Recalling Customizations
Every tim e LISP s ta rts up it reads th e previously saved inform ation. If no
u ser custom izations have been stored, the system defaults are read from
DECW$SYSTEM_DEFAULTS:LISP$DEFAULTS.DAT. If you m ake modifi
cations and would like to rese t to your previously saved settings, use the
LOAD-CUSTOMIZATIONS function.

LOAD-CUSTOMIZATIONS function
This function loads custom izations previously saved w ith d e c w - u t i l s : s a v e c u s t o m i z a t i o n s. By default, th is function searches, in order, the default di
rectory, DECW$USER_DEFAULTS: and DECW$SYSTEM_DEFAULTS: for
the file LISP$DEFAULTS.DAT. (By default, th is function should alw ays find
DECW$SYSTEM_DEFAULTS:LISP$DEFAULTS.DAT, which is supplied by the
VAX LISP system.) If file is supplied, it is m erged ag ain st "DECW$USER_
DEFAULTS:LISP$DEFAULTS.DAT". If th e re su lt specifies a directory, only th a t
directory is searched; otherwise, th e search p a th described above is used. If
th e file is not found, an error is signaled. This function is called autom atically,
w ithout argum ents, every tim e the developm ent environm ent is started. If you
have previously saved your custom izations into LISP$DEFAULTS.DAT in either
your default directory or DECW$USER_DEFAULTS: w ith DECW-UTILS: SAVEc u s t o m i z a t i o n s , your saved custom izations are in effect from the start.

Form at
DECW-UTILS:LOAD-CUSTOMIZATIONS

&KEY f ile

file
A string or pathnam e th a t nam es a file into w hich your custom izations have
been w ritten. If you do not nam e a file, th e function loads custom izations from
eith er DECW$USER_DEFAULTS:LISP$DEFAULTS.DAT or DECW$SYSTEM_
DEFAULTS:LISP$DEFAULTS.DAT, which is supplied by VAX LISP.

R eturn Value
The nam estring of th e file actually read.

E xam ples
(These exam ples refer to inform ation in th e exam ples in th e d e c w routine description.)

u t i l s :SAV e - c u s t o m i z a t i o n s

L isp > ( lo a d - cu sto m iza tio n s)
"DECW$SYSTEMJ5EFAULTS: L I SP $DEFAULTS. D A T ; 1"

This is the resu lt if you never previously saved custom izations.

Customizing DECwindows from VAX LISP

C-13

LOAD-CUSTOMIZATIONS function
2.

L isp > ( lo a d - cu sto m iza tio n s)
" L I S P Z $ : [JO N E S]L ISP $ D E F A U LT S.D A T ;1"

This is the resu lt if you saved custom izations into th e default file.
3.

L isp > ( loa d - cu sto m iza tion s : f i l e " lis p - b ig fo n t s " )
" L I S P Z $ : [J O N E S ] L IS P - B IG F O N T S .D A T ;42"

This exam ple loads the specialized defaults file.
4.

L i s p > ( l o a d - c u s t o m i z a t i o n s : f i l e " d e f d i r : l i s p - w i d e w i n d o w s . i n i t ")
" L I S P Z $ : [JON ES.D EFAU LTS]LISP-W IDEW INDOW S.IN IT;3 "

This example loads the specialized geometry.

C-14 Customizing DECwindows from VAX LISP

Appendix D

Using the "EMACS" Editor Style
This appendix provides inform ation on th e "EMACS" E ditor style. The " e m a c s "
style consists of a collection of key bindings th a t causes the E ditor to behave
like the EMACS editor. This appendix lists these bindings and explains how
to activate the " e m a c s " style in the Editor b u t does not provide any tutorial
inform ation on using EMACS. Additional EMACS related exam ples are in
LISP$EXAMPLES:EDINIT.
This appendix is organized as follows:

D.l

•

Section D .l explains to a new user how to learn about the Editor.

•

Section D.2 describes how to activate th e " e m a c s " style as a m inor or m ajor
style, th u s m aking the " e m a c s " key bindings available to you.

•

Section D.3 lists th e key bindings in th e " e m a c s " style.

Introduction to the Editor
To learn about using th e Editor from a term inal interface, read C hapter 3. To
lea rn about using the E ditor in the DECwindows environm ent, rea d C hapter 8.
M ost of th e inform ation in these chapters is also tru e w hen you are using the
"EMACS" style. The chief difference when you are using th e " e m a c s " style lies
in the key bindings. In m any instances, keys or key sequences th a t invoke one
comm and when you are not using the " e m a c s " style invoke a different command
w hen the " e m a c s " style is active. Table D—1 com pares default E ditor key bindings
w ith EMACS key bindings, showing w here differences exist. W hen reading in
C hapter 3, keep these key binding differences in m ind. Table D—1 is arranged
in the approxim ate order th a t the key bindings and comm ands a re presented in
C hapter 3. (Table D—1 lists only those comm ands listed in C hapter 3. The full set
of "EMACS" style key bindings is presented in Section D.3.)
Section 3.2.1 contains inform ation on editing using the num eric keypad. Keys
and key sequences on th e num eric keypad a re set up to em ulate the EDT editor.
If you are using the " e m a c s " style, you still can use th e keypad keys to do
editing (as long as the " e d t E m u l a t i o n " style is active). However, the operations
perform ed by these keys, while sim ilar to EMACS editing operations, m ay be
different enough to produce confusion in a seasoned EMACS user.

Using the "EMACS" Editor Style

D-1

Table D-1: ' C om m an ds for Manipulating Buffers and W indows
D efau lt B in d in g

’
EM A CS" B in d in g

C om m an d

G eneral-P urpose C om m an ds
|Ctrl/Z|

| Escape | | x |

ICtrl/XI |Ctrl/Z|

|Ctrl/G|

P a u s e E d ito r

N one

|Ctrl/X| [~s~]

W rite C u r r e n t B u ffe r

N one

ICtrl/XI ICtrl/M|

W rite M o d ified B u ffe rs

N one

ICtri/X| |Ctri/W|

W rite N a m e d F ile

fCtrÜXl fCWNl

N e x t W in d o w

|Ctrl/X| |Ctrl/R|

ictri/x i r s n

R e m o v e C u r r e n t W in d o w

N one

[C tr i/X im

R e m o v e O th e r W in d o w s

(Ctrl/W|

fc w q

R e d is p la y S c re e n

E x e c u te N a m e d C o m m a n d

E d itin g C om m an ds
N one

ICtrl/XI Ictrffil

I n s e r t F ile

N one

I Escape 11 q |

Q u e ry S e a rc h R e p la c e

N one

| Escape | |Ctrl/G|

E x it R e c u rs iv e E d it

N one

| Escape||

U p c a s e W o rd

N one

| Escape| \1 |

D o w n c a se W o rd

N one

IEscape 11 c |

C a p ita liz e W ord

B uffer an d W indow C om m an ds
N one

ICtrt/X| | b |

S e le c t B u ffe r

N one

Ictrl/X! ICWBl

L i s t B u ffe rs

N one

|Ctrl/X| |Ctrl/D|

D e le te C u r r e n t B u ffe r

N one

Ictrl/XI ICtrl/EI

N one

ICtrl/X| |ctri771

E d it F ile

N one

1Ctrl/XI m

G ro w W in d o w

N one

Ictrl/XI [ctri/Zl

S h r i n k W in d o w

N one

ICtrl/X11 2 I

S p lit W in d o w

C u sto m izin g C om m an ds
|ctri/x| IcvTTel

ICtrl/X| |T 1

E x e c u te K e y b o a rd M a c ro

D.2 Activating the "EMACS" Style
By default, th e E ditor h as " e d t E m u l a t i o n ” as its m ajor style and "VAX l i s p ” as
its only m inor style. (If you are not editing LISP code, th e ”v a x l i s p " style will
not be active.) Section 3.5.1.4 contains inform ation about styles. Tb sum m arize:
W henever you press a key, the E ditor looks in various places to see if th a t key is
bound to a command. The E ditor first checks the cu rren t buffer; th en checks the
m inor styles, looking a t the m ost recently activated m inor style first; then checks
th e m ajor style; and finally checks to see if th e key is bound globally. This m eans
th a t key bindings in m inor styles tak e precedence over or “shadow” key bindings
in the m ajor style or global key bindings.

D-2 Using the "EMACS" Editor Style

You can activate the " e m a c s " style as e ith e r a m inor or th e m ajor style:

D.2.1

•

If you leave " e d t E m u l a t i o n " as th e m ajor style an d activate " e m a c s " as
a m inor style, key binding conflicts betw een " e d t E m u l a t i o n " and " e m a c s "
(such as ctrl/u and Ctrl/W) will be settled in favor of " e m a c s ".

•

If you m ake " e m a c s " the m ajor style and activate " e d t E m u l a t i o n " as a m inor
style, key binding conflicts will be settled in favor of "EDT E m u l a t i o n " .

•

If you m ake " e m a c s " the m ajor style and do not activate "EDT E m u l a t i o n " as
a m inor style, you will not have access to th e keypad editing capabilities of
"EDT E m u l a t i o n " . However, you can bind th e keypad keys to any commands
you like in the " e m a c s " style; see Section 3.5.1.

Activating "EMACS” a s a Minor Style
You can activate "EMACS" as a m inor style from w ithin th e E ditor by using the
" A c t i v a t e M i n o r s t y l e " command. This comm and activates a m inor style for the
cu rren t buffer only. However, use of th is comm and m ay cause problem s if you are
editing LISP code, because " e m a c s " will become th e m ost recently activated style;
thus, " e m a c s " key bindings will take precedence over conflicting "VAX l i s p " key
bindings.
A better approach is to m ake " e m a c s " a default m inor style, which will cause
" e m a c s " to be activated before th e "VAX l i s p " style w hen you s ta rt editing LISP
code, l b m ake " e m a c s " a default m inor style, call the following function from the
LISP in te rp re te r or in your LISP initialization file:
(push

D.2.2

"em acs"

( e d i t o r :v a r i a b l e - v a l u e

"d efa u lt

m in or

sty les") )

Making "EMACS" the Major Style
To m ake " e m a c s " the E d ito r’s m ajor style, call the following function from the
LISP in te rp re te r or in your LISP initialization file:
(setf

( e d i t o r :v a r i a b l e - v a l u e

"d efa u lt

m a jo r

sty le ")

"em acs")

This call causes " e m a c s " to replace " e d t E m u l a t i o n " as th e E ditor’s m ajor style.
If you w ish to rein sta te "EDT E m u l a t i o n " as one of the m inor styles, call the
following:
(push

" e d t em u la tio n "
( e d ito r:v a ria b le - v a lu e

"d efa u lt

m in or

sty les") )

D.3 "EMACS" Style Key Bindings
Table D -2 lists the key bindings supplied in th e " e m a c s " style. Appendix E
contains short descriptions of th e available com m ands and a list of the key
bindings supplied w ith th e Editor. The table of key bindings in Appendix E is
especially useful for finding key binding conflicts; th a t is, w here the same key or
key sequence is bound to two or m ore different commands in different contexts.
Key sequences containing alphabetic characters are case sensitive; you m ust
e n te r the alphabetic character in th e case shown.
Use Ctrl/[ to generate an # \ e s c a p e character from keyboards not possessing an
E scape key.

Using the "EMACS" Editor Style

D-3

Table D-2:

"EMACS" Style Key Bindings

Key(s)

C om m an d
C u rso r M ovem en t

|Ctrl/F|

F o rw a rd C h a r a c te r

[cwbI

B a c k w a rd C h a r a c t e r

!Escape[| f |

F o rw a rd W ord

| Escape|| b |

B a c k w a rd W o rd

| Ctrl/A|

B e g in n in g o f L in e

[owe]

E n d o f L in e

[cwpI

P re v io u s L in e

1Ctri/N]

N e x t L in e

| Escape 11 a |

B e g in n in g o f P a r a g r a p h

| Escape| | e |

E nd of P a ra g ra p h

IEscape11 p |

P re v io u s P a r a g r a p h

| Escape | | n |

N ext P a ra g ra p h

| Escape11 v |

P re v io u s S c re e n

ICtriAT|

N e x t S c re e n

| Escape11 < |

B e g in n in g o f B u ffe r

| Escape|j > |

E n d o f B u ffe r

1Escape|| , |

B e g in n in g o f W in d o w

| Escape| | . |

E n d o f W in d o w

[CWZ|

S cro ll W in d o w D o w n

| Escape| j z |

S cro ll W in d o w U p

|Escapc[ [ J ]

L in e to Top o f W in d o w

S e a rch in g
[CMÄ1

E M A C S F o r w a r d S e a rc h

|Ctrl/R|

E M A C S B a c k w a r d S e a rc h

D e le tin g
| Delete |

D e le te P re v io u s C h a r a c t e r

Ictrl/D|

D e le te N e x t C h a r a c te r

| Escape | | Delete |

D e le te P re v io u s W o rd

| E scap e1 1 d |

D e le te N e x t W o rd

| E s c a p e | | Ctrl/D |

D e le te W h ite s p a c e

(continued on next page)

D—4 Using the "EMACS" Editor Style

Table D-2 (Cont.):
Key(s)

"EMACS" Style Key Bindings
C om m an d
Killing, Yanking, an d R e g io n s

|Ctrl/Kj

Kill Line

| E s c a p e 11 k |

Kill Paragraph

| Ctrl/W |

Kill Region

[cwy|

Yank

| E sc a p e 11 y |

Yank Previous

| E sc a p e ] |Ctr1/Y|

Yank Replace Previous

| E sc a p e | | Ctrl/W |

Undo Previous Yank

| C trl/Space |

S et Select Mark

| E sc a p e 11 C trl/Space |

U n set Select Mark

!Ctrl/X | |ctri/X |

Exchange Point and Select Mark

Text In se rtio n an d M odification
| C trl/ 0 |

Open Line

Quoted Insert

IC trl/ X | FcwTfl

Insert Pile

| E s c a p e 11 c |

Capitalize Word

D ow ncase Word

| E scape | 1 |
| E s c a p e 11 u

U pcase Word

I C tr l/ r j

Transpose Previous Characters

IE s c a p e 11 t I

Transpose Previous Words

1E s c a p e \ \ J ]

Query Search Replace

M ultiple W indow s an d B uffers
ICtrl/X | | n |

Previous Window

[c w x im

N ext Window

ic w x ] m

Rem ove Current Window

[CW Xl m

Rem ove Other Windows

fcw « i m

Grow Window

fctrw cl [ctri/Zl

Shrink Window

| E s c a p e | j Ctrl A/ j

Page N ex t Window

ICtrWCI IT!

Split Window

i c tr i/x i r n

Select Buffer

[CtrtÖcl fcSTBl

L ist Buffers

[C trix l Fc STd I

D elete Current Buffer

(continued on next page)

Using the "EMACS” Editor Style

D -5

Table D-2 (Cont.):
Key(s)

"EMACS" Style Key Bindings
Command
Starting and Saving Work

1Ctrl/X I ICtrl/Ef

[cS w cl fctriTT]

Edit File

[Ctri/X] |Ctrl/R|

Read File

1C trl« I | Ctrl/F |

View File

1Ctrl/X | m

Write Current Buffer

1Ctrl/X I ICtrl/M I

Write Modified Buffers

| Ctrl/X | | Ctrl/W |

Write N am ed File

Editor Control
| E sc a p e 11 x |

E xecute N am ed Command

[Ctri'/al

P ause Editor

| E sc a p e | jCtri/G |

E xit Recursive Edit

[ctrilL l

R edisplay Screen

| E sc a p e | |Ctri/U |

Supply Prefix A rgum ent

|Ctrl/U |

Supply EMACS Prefix

!Ctrl/X I m

Execute Keyboard Macro

I C t r t x l [CtriTfl

Show Time

isHsin

W hat Cursor P osition

D-6 Using the "EMACS" Editor Style

Appendix E

Editor Commands and Key Bindings
This appendix briefly describes the Editor commands and lists the key bindings
th a t are supplied w ith th e Editor. The appendix is organized as follows:

E.l

•

Section E .l lists th e E ditor commands, along w ith each comm and’s key
bindings and a b rief description of the command.

•

Section E.2 lists the keys and key sequences th a t are bound to commands and
explains how to determ ine to which command a key or key sequence is bound
in a given context.

Editor Command Descriptions
Table E - l alphabetically lists the Editor commands. The second column of the
table lists th e keys or key sequences th a t are bound to th a t command (if any)
and the context in which they are bound. The th ird colum n contains a brief
description of th e command. For a full description of each command, see the VAX
L I S P /V M S E d ito r P ro g ra m m in g G u ide.

Table E-1: Editor Comm ands and Key Bindings
Name

Bmding(s)

Description

A ctivate Minor
Style

None

Prom pts for th e nam e o f a m inor style and then
activates th a t style as a m inor style in the current
buffer.

Apropos

N one

Prompts for a string, th en displays the nam es of
objects of a specified typ e containing th a t string.

Apropos Word

( : STYLE "VAX L I S P " ) ! E s c a p e | p H

D isplays the resu lt of evalu atin g th e APROPOS
function w ith th e word a t th e cursor location as
the argum ent.

Backward
Character

: GLOBAL [ 3
( : STYLE "E MACS") [CW BI

Moves th e cursor backward one character or by
the num ber o f characters specified by th e prefix
argum ent.

Backward Kill
Ring

N one

Rotates the kill ring backward by one elem ent or
by the num ber of elem en ts specified by th e prefix
argum ent.

_ o « _ j P ointer b u tto n transition: o b u tto n up; • b u tto n held down; ! b u tto n pressed; T b u tto n released.
° •o —* pointer m ovem ent w ith b u tto n s in specified state.
Pointer buttons invoke command only w hen po in ter cursor is in th e cu rren t window.

(continued on next page)

Editor Commands and Key Bindings E-1

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

Name

Binding(s)

Description

Backward Page

N one

M oves th e cursor to the previous page break or to
the preceding page break specified by the prefix
argum ent.

Backward Search

None

Prom pts for a search string, th e n m oves the cursor
to th e beginning o f the first preceding occurrence
o f th a t strin g or to the preceding occurrence
specified by the prefix argum ent.

Backward Word

(;STYLE "EMACS") 1E s c a p e |[ V I

M oves th e cursor to the end of the previous word
or to th e end o f the preceding word specified by
the prefix argum ent.

(: STYLE "EDT E m u l a t i o n " )

M oves th e cursor to the b eginning o f the buffer.

B egin nin g of
Buffer

IE E 3 G D ( : STYLE "E MACS") [E s c a p e ]
CD

B egin nin g of Line

(:STYLE "EMACS") |Ctrl/A|

M oves th e cursor to the beginning o f the current
lin e or to th e beginning of th e following line
specified by th e prefix argum ent.

B egin nin g of
O uterm ost Form

(:STYLE "VAX L I S P " ) [ c 5 w n m

M oves th e cursor to th e b eginning of the outerm ost
form currently containing it or, i f th e cursor is not
currently contained in a form, to th e beginning of
th e preceding outerm ost form.

B egin nin g of
Paragraph

(:STYLE "EMACS") IE s c a p e | [X|

Moves th e cursor to the beginning of the current
paragraph.

B egin nin g of
Window

(:STYLE "EMACS") IE s c a p e l l T I

M oves the cursor to the top o f th e current window.

Bind Command

None

Prom pts for a command nam e, a key sequence
to bind to th e command, and a context in which
to bind th e key sequence, th en binds the key
sequence to th e command.

C apitalize Region

None

C apitalizes th e first letter of each word in the
current select region.

C apitalize Word

(:STYLE "EMACS") |E s c a p e | [T|

C apitalizes th e first letter of th e word at the
cursor location.

Close O uterm ost
Form

(:.STYLE "VAX L I S P " ) lEscapeim

Com pletes th e outerm ost LISP form by inserting
close-parenthesis characters a t th e cursor position.

Copy from
Pointer2

:GLOBAL | 0 0 T 1

S ets th e end of secondaiy selection and copies the
tex t to th e window th a t has in pu t focus; check that
in pu t focus is correctly set before in itia tin g this
command.

Available only in DECwindows Pointer Syntax.
J. » | Pointer b u tto n transition: o b u tto n up; • b u tto n h eld down; J. b u tto n pressed; j b u tto n released.
» o | —* pointer m ovem ent w ith b u tto n s in specified state.
Pointer b uttons invoke com m and only w hen pointer cursor is in th e cu rre n t window.
o

(continued on next page)

E-2

Editor Commands and Key Bindings

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

Name

Bmding(s)

Description

Copy to P ointer2

: GLOBAL I o o J. |

M oves the current buffer point to th e position
indicated by th e pointer and in serts th e tex t from
th e primary selection at th a t location. If pointer
is beyond th e end of a line, in serts th e text at the
end of the line. I f pointer is beyond the end of the
buffer region, in serts th e tex t a t th e end of the
buffer region.

D eactivate Minor
Style

N one

Prom pts for th e nam e of a m inor style, then
deactivates th a t m inor style in th e current buffer.

D elete Current
Buffer

( : STYLE

D elete Line

N one

D eletes everything b etw een th e cursor and th e end
o f th e current lin e or to th e end of th e following
lin e specified by the prefix argum ent.

D elete Nam ed
Buffer

N one

Prom pts for th e nam e o f a buffer, th en deletes
th a t buffer, i f th e buffer is modified, asks if the
contents o f th e buffer should first be saved.

D elete N ext
Character

( : STY LE

" E M A C S " ) [CtFi/D]

D eletes th e character follow ing th e cursor or the
num ber of follow ing characters specified by the
prefix argum ent.

D elete N ext Word

( : STY LE

" E M A C S " ) | Escape | [""51

D eletes everything from th e cursor position to th e
end of th e current word or th e num ber of following
words specified by the prefix argum ent.

D elete Previous
Character

( : STY LE

" E M A C S " ! | D elete |

D elete Previous
Word

( : STY LE

" E M A C S " ) I Escape 1 1Delete |

D eletes everything from th e cursor position to th e
beginning o f th e current word or th e num ber of
preceding w ords specified by th e prefix argum ent.

D elete
W hitespace

( : STY LE

" E M A C S " ) 1Escape | [cffl/Dl

D eletes w hitespace characters follow ing th e cursor
location up to th e n ext nonw hitespace character.

D elete Word

N one

D eletes everything from th e cursor position to th e
beginning o f th e next word, including w hitespace,
or deletes th e num ber o f follow ing words specified
by th e prefix argum ent.

Describe

N one

Prom pts for th e nam e and type of an object, then
displays a description o f th a t object.

Describe Word

( : STY LE

" V A X L I S P " ) fctri/7|

Describe Word at
Pointer3

( : STY LE

"V A X L I S P " ) I o o l

D eletes th e current buffer; for modified buffers,
asks if th e contents o f th e buffer should first be
saved.

" E M A C S " ) [ctri/x] [ctriTo]

D eletes th e character preceding th e cursor position
or th e num ber of preceding characters specified by
th e prefix argum ent.

: GLOBAL | Delete |

C alls th e D E S C R IB E function w ith th e word a t the
cursor position as the argum ent.
|

C alls t h e D E S C R IB E f u n c t i o n w i t h t h e w o r d a t t h e
p o in te r p o sitio n a s t h e a r g u m e n t.

2 Available only in DECwindows P o in ter Syntax.
3 Available only in U IS P o in ter Syntax.
c ; » I P ointer b u tto n tran sitio n : o b u tto n up; • b u tto n held down; J. b u tto n pressed; T b u tto n released.
o « o | —* pointer m ovem ent w ith b u tto n s in specified state.
Pointer b uttons invoke comm and only w hen pointer cursor is in th e c u rre n t window.

(continued on next page)

Editor Commands and Key Bindings E-3

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

Name

Binding! s)

Description

D ow ncase Region

None

M akes all alphabetic characters in th e current
select region lowercase.

D ow ncase Word

(: STYLE "EMACS ") IE s c a p e | [T|

M akes all alphabetic characters in th e word at the
cursor position lowercase.

(: STYLE "EMACS " )[CtrW(l [ciri/E]

Prompts for a LISP object to edit and', if th e object
is a symbol, w hether to ed it its function definition
or its value.

E dit F ile

(: STYLE "EMACS ") ICtrwH icwvl

Prom pts for the specification of a file to edit;
completion and alternatives are available during
your response to the prompt.

ED T Append

(:STYLE "EDT E m u l a t i o n " )

Appends th e current select region to th e contents
of the paste buffer.

keypad [T]
ED T Back to
Start o f Line

ED T B eginning of
Line

ED T Change
C ase

ED T C ut

(:STYLE "EDT E m u l a t i o n ” )
IB a c k sp a ce | “ a n d |F12| 4

Moves the cursor to the beginning o f the current
line or to the beginning o f th e previous line, if
the cursor is already at th e beginning of a line; or
m oves back th e num ber of lines specified by the
prefix argum ent.

(:STYLE "EDT E m u la tio n ")[Ö]

Moves the cursor to th e beginning of the next
line, i f the current direction is forward, or to th e
beginning of th e current or previous line, if the
current direction is backward; m oves the num ber
o f lines specified by the prefix argum ent.

(:STYLE "EDT E m u l a t i o n " )

Changes from low ercase to uppercase (or vice
versa) all characters in th e select region or, i f no
select region is defined, th e character at the cursor
position.

|Ctrl/H| a n d

!pfT1 k e y p a d

[7]

(:STYLE "EDT E m u l a t i o n ” )
keypad HT] and 1R em ove | 4and

D eletes the current select region and replaces the
contents of the paste buffer w ith it.

1 0 -I 0 13
EDT D elete
Character

(:STYLE "E DT E m u l a t i o n " )
keypad □

D eletes the character at th e cursor position and
stores it in th e deleted character area; deletes
the num ber o f characters specified by the prefix
argument.

ED T D elete Line

(: STYLE "EDT E m u l a t i o n " ) [pm]

D eletes from th e cursor position to the beginning
of the next lin e and stores the deleted line in
the deleted line area; deletes th e num ber of lines
specified by th e prefix argum ent.

ED T D elete
Previous
Character

(: STYLE "E DT E m u l a t i o n " )
| Delete |

D eletes the character preceding th e cursor and
stores it in th e deleted character area; deletes
the num ber of characters specified by the prefix
argument.

8 Available only in UIS Pointer Syntax.
4 Key available only on LK201 keyboard.
6 Key available only on VT100 term inal.
| Pointer b u tto n transition: o b u tto n up; • b u tto n held down; j. b u tto n pressed; ] b u tto n released.
> pointer m ovem ent w ith b u tto n s in specified state.
Pointer buttons invoke com m and only w hen po in ter cursor is in th e cu rren t window.

(continued on next page)

E—4

Editor Commands and Key Bindings

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

Name

Bmding(s)

Description

EDT D elete
Previous Line

( : STYLE "E DT E m u l a t i o n " )
|Ctrl/U|

D eletes from th e cursor position to th e beginning
of th e current line or, if the cursor is at the be
ginning of a line, to the beginning o f the previous
line; stores th e resu lt in the deleted lin e area;
d eletes th e num ber of lin es specified by the prefix
argum ent.

EDT D elete
Previous Word

( : STYLE "EDT E m u l a t i o n " )
|C trl/J | a n d I Linefeed | “ a n d |F 1 3 | 4

D eletes from th e cursor position to the begin
ning o f th e current word or, if th e cursor is
betw een words, to th e beginning of the previous
word; stores th e resu lt in the deleted word area;
d eletes th e num ber o f lin es specified by the prefix
argum ent.

EDT D elete to
End of Line

|p f i | k e y p a d

( : STYLE "EDT E m u l a t i o n " )
[T]

D eletes from th e cursor position to the end of the
current lin e or, if th e cursor is at the end of a line,
to the end o f th e next line; stores the resu lt in
th e deleted lin e area; d eletes th e num ber of lines
specified by th e prefix argum ent.

EDT D elete Word

( : STYLE "EDT E m u l a t i o n " )
keypad Q

D eletes from th e cursor position to the beginning
of th e n ext word; stores th e result in th e deleted
word area; d eletes th e num ber of words specified
by th e prefix argum ent.

EDT D eselect

( : STYLE "EDT E m u l a t i o n " )
|p f i | k e y p a d j ~ ]

Cancels th e current select region; equivalent to

EDT End o f Line

( : STYLE "E DT E m u l a t i o n " )
k e y p a d [T]

M oves th e cursor to the end o f the current, next,
or previous line, depending on starting cursor
position and current direction; m oves th e num ber
of fines specified by th e prefix argum ent.

EDT Move

( : STYLE "EDT E m u l a t i o n " )
k e y p a d [T]

M oves th e cursor forward or backward by one
character, according to the current direction;
m oves th e num ber o f characters specified by the
prefix argum ent.

EDT Move Page

( : STYLE "EDT E m u l a t i o n " )
k e y p a d [T]

M oves the cursor to th e preceding or following
page break, depending on th e current direction;
m oves th e num ber o f pages specified by th e prefix
argum ent.

EDT Move Word

( : STYLE "E DT E m u l a t i o n " )

M oves th e cursor to th e beginning o f the next,
current, or preceding word, depending on current
direction and cursor startin g position; m oves the
num ber of words specified by the prefix argum ent.

C h a rac te r

k e y p a d [7]

EDT P aste

( : STYLE "E DT E m u l a t i o n " )
P H a n d | Insert H ere 1

Inserts th e contents of the paste buffer a t the
cursor location.

( : STYLE "E D T E m u l a t i o n " )

Inserts th e contents of th e paste buffer at the
pointer cursor location.

|P F 1 | k e y p a d

EDT P aste at
Pointer3

" U n s e t S e l e c t M ark".

1 * -I 0 1

3 Available only in U IS P o in ter Syntax.
4 Key available only on LK201 keyboard.
5 Key available only on VT100 term inal.
1 » | P ointer b u tto n transition: o b u tto n up; • b u tto n h eld down; 1 b u tto n pressed; f b u tto n released.
—> p ointer m ovem ent w ith b u tto n s in specified state.
Poin ter b u tto n s invoke command only w hen pointer cursor is in th e cu rre n t window.
o

m o

(continued on next page)

Editor Commands and Key Bindings E -5

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

N am e

Binding(s)

D e scrip tio n

E D T Q u e ry
S e a rc h

( : STYLE "EDT E m u l a t i o n " )
[p f TI fPFäl a n d [ f i n d ] 4

Prom pts for a search string and moves th e cursor
to the following or preceding occurrence of the
string, depending on th e c u rren t direction; moves
to the occurrence specified by th e prefix argum ent.

|p f i | k e y p a d

( : STYLE "EDT E m u l a t i o n " )
[T]

Replaces th e cu rren t select region w ith th e con
ten ts of th e paste buffer.

E D T S croll
W in d o w

( : STYLE "EDT E m u l a t i o n " )
keypad[3

Scrolls the window in th e direction indicated by
the cu rrent direction.

E D T S e a rc h
A g a in

( : STYLE "EDT E m u l a t i o n " ) [PF3]

Searches for th e next or previous occurrence of the
search string th a t was la st entered, according to
th e cu rren t direction.

E D T S e le c t

( : STYLE "EDT E m u l a t i o n " )
k e v o a d m a n d |S e ie c t| 4

Places a m ark a t th e cursor position to indicate
one end of a select region; equivalent to " S e t

E D T Set
D ire c tio n
B a c k w a rd

( : STYLE "EDT E m u l a t i o n " )
k e y p a d [T]

Sets the c u rren t direction to backward.

ED T Set
D ire c tio n
F o rw a rd

( : STYLE "EDT E m u l a t i o n " )
k e y p a d [7 ]

Sets the c u rren t direction to forward.

( : STYLE "EDT E m u l a t i o n " )
[7 ]

Inserts th e character whose ASCII code is specified
by th e prefix arg u m en t a t th e cursor position.

E D T S u b s titu te

( : STYLE "EDT E m u l a t i o n " )
IpfH [Enter]

If th e cursor is located a t th e beginning of the
cu rrent search string, replaces th e search string
w ith the contents of th e paste buffer, th en finds
the next occurrence of th e search string.

E D T U n d e le te
C h a r a c te r

( : STYLE "EDT E m u l a t i o n " )
[p f i | k e y p a d [7]

Inserts th e contents of th e deleted character area
a t the cursor location.

E D T U n d e le te
L in e

( : STYLE "EDT E m u l a t i o n " )
[p f T) [PF4|

Inserts th e contents of th e deleted line area a t th e
cursor location.

E D T U n d e le te
W ord

( : STYLE "EDT E m u l a t i o n " )
EE3 k e y p a d 0

Inserts th e contents of th e deleted word area a t
th e cursor location.

EM ACS
B a c k w a r d S e a rc h

( : STYLE "EMACS") [Ctri/R[

S e a rc h e s b a c k w a r d fo r t h e f i r s t o c c u rre n c e o f th e
s e a r c h s t r in g sp e c ifie d i n th e p re v io u s c o m m a n d ;
p ro m p ts fo r a s e a r c h s t r in g i f t h e p re v io u s com 
m a n d w a s n o t a s e a r c h in g c o m m a n d ; s e a r c h e s fo r
th e o c c u rre n c e o f t h e s e a r c h B trin g sp ecifie d b y th e
p re fix a r g u m e n t.

E M A C S F o rw a rd
S e a rc h

( : STYLE "EMACS") [CWÄ]

Searches forward for th e first occurrence of the
search string specified in th e previous command;
prom pts for a search strin g if th e previous com
m and was not a searching command; searches for
th e occurrence of th e search strin g specified by the
prefix argum ent.

E D T R e p la c e

S e l e c t M a rk " .

E D T S p e c ia l
In se rt

|p f i | k e y p a d

4 Key available only on LK201 keyboard.
1 « j Pointer b u tto n transition: o b u tto n up; • b u tto n held down; . b u tto n pressed; ' b u tto n released,
pointer m ovem ent w ith b u tto n s in specified state.
Pointer buttons invoke comm and only w hen pointer cursor is in th e cu rren t window.

(continued on next page)

E-6

Editor Commands and Key Bindings

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

N am e

Binding(s)

D e scrip tio n

E nd Keyboard
Macro

: GLOBAL [CM/x| |T1

Ends the collection of keystrokes for a keyboard
macro.

( : STYLE

Moves th e cursor to th e end of th e buffer.

E nd of Buffer

|p f i |

"E DT E m u l a t i o n ” )

keypad [7]

( : STYLE

"E MACS") | EscapeIfT]

E nd of Line

( : STYLE

"EMACS” ) [o w e ]

Moves the cursor to th e end of th e cu rren t line or
forw ard th e num ber of lines specified by th e prefix
argum ent and th e n to th e end of th e line.

E nd of O uterm ost
Form

( : STYLE

"VAX L I S P " ) [ctri/xlfTl

Moves th e cursor to th e outerm ost form currently
surrounding th e cursor or, if th e cursor is betw een
outerm ost forms, to th e end of th e following
outerm ost form.

E nd of P arag rap h

( : STYLE

"EMACS") | Escape| | T |

Moves th e cursor to th e end of th e cu rren t p a ra 
graph.

E nd of Window

( : STYLE

"E MACS") | Escape11“ 1

Moves th e cursor to th e end of th e tex t in the
cu rren t window.

E v alu ate LISP
Region

( : STYLE "VAX L I S P ” )
1Ctrl/XI Ictrl/AI

E valuates th e select region as LISP code; displays
the re su lt of th e evaluation in th e inform ation
area.

Exchange Point
an d Select M ark

( : STYLE

Moves th e cursor to th e other end of th e cu rren t
select region, and th e m a rk delim iting the select
region to th e old cursor position; in other words,
preserves th e select region b u t places th e cursor a t
the other end of it.

E xecute Keyboard
M acro

( : STYLE

Execute N am ed
C om m and

( : STYLE

"EMACS " ) [ctri/xl [cvi/xl

: GLOBAL [Ctri7x] [Ctri/E|

"E MACS") |Ctrl/x| | e |

: GLOBAL [ctFi/z]

|p f i I

and [55] 4

"E DT E m u l a t i o n " )

keypad [7]

Executes th e c u rren t keyboard m acro once of th e
num ber of tim es specified by th e prefix argum ent.
Prom pts for th e nam e of a com m and to execute;
in p u t completion and altern ativ es are available
during your response to th e prom pt.

STYLE "E MACS") [E sc ape im

(

E xit

None

E x it Recursive
E d it

( : STYLE

R eturns control to th e LISP interpreter, discarding
th e cu rren t E ditor state; asks if modified buffers
should first be saved.
"E MACS") | Escape| [CtFiTol

Term inates a recursive edit or pauses th e E ditor if
not doing a recursive edit.

F orw ard
C h aracter

F orw ard Kill Ring

None

R otates th e kill ring forw ard by one elem ent or
by the num ber of elem ents specified by th e prefix
argum ent.

F orw ard Page

None

Moves the cursor to th e next page break or to
th e following page break specified by th e prefix
argum ent.

: GLOBAL R ]

Moves the cursor forw ard one character.

STYLE "E MACS") [Ctti/F]

4 Key available only on LK201 keyboard.
1 » I P ointer b u tto n transition: o b u tto n up; • b u tto n held down; 1 b u tto n pressed; f b u tto n released.
o « o I —» pointer m ovem ent w ith b u tto n s in specified state.
P oin ter b u tto n s invoke command only w hen pointer cursor is in th e cu rre n t window.
o

(continued on next page)

Editor Commands and Key Bindings E-7

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

Name

Bmding(s)

Description

Forward Search

N one

Prom pts for a search string, th en m oves th e cursor
forward to th e end o f the first occurrence of th e
string; m oves th e cursor to th e occurrence of the
string specified by th e prefix argum ent.

Forward Word

( : S T Y L E " E M A C S " ) I Escape | [Tl

M oves th e cursor to the beginning of the next word
or the beginning o f the word specified by the prefix
argum ent.

Grow Window

( : STY LE " e m a c s " ) ic w x irri

Increases th e heigh t of the current window by
one row or by th e num ber of rows specified by the
prefix argum ent.

Help

: G L O B A L |PF2| and |Help[ 4

D isplays help on your current situation.

Help on Editor
Error

: G L O B A L [Cvi/x| [T l

D isplays inform ation on th e la st Editor error th a t
occurred.

Illegal Operation

N one

Signals an Editor error; u se to disable a key
binding locally w ithin a style or buffer.

Indent LISP Line

( : S T Y L E "V A X L I S P " ) [Tab]

Adjusts th e current LISP lin e so th a t it is indented
properly in th e context of the program.

Indent LISP
Region

None

Adjusts th e indentation of th e LISP code in the
current select region.

Indent O uterm ost
Form

( : S T Y L E " V A X L I S P " ) [ctrtöclfrab]

Indents each lin e in the outerm ost LISP form
containing th e cursor.

Insert Buffer

None

Prom pts for a buffer nam e, th en in serts the
contents of th e specified buffer at th e cursor
location.

Insert Close
P aren and Match

( : S T Y L E "V A X L I S P " ) Q ]

Inserts a close-parenthesis character a t the
cursor location and h ighlights th e corresponding
open-parenthesis character.

Insert File

( : S T Y L E "E M A C S " ) fctrt/xl [cw il

Prom pts for a file specification, th en in serts the
contents o f th e file at the cursor location; input
com pletion and alternatives are available during
your response to th e prompt.

Kill Enclosing
L ist

N one

D eletes the LISP lis t th a t encloses th e cursor
and adds it to th e current kill-ring region if the
previous command w as a kill-ring command, or
creates a new kill-ring region to hold th e deleted
list; d eletes the num ber of enclosing listB specified
by th e prefix argum ent.

Kill Line

( : S T Y L E " E M A C S " ) [Ciri/Kl

D eletes the rest o f th e current lin e and adds it
to th e current kill-ring region i f th e previous
com m and w as a kill-ring com m and, or creates
a new kill-ring region to hold th e deleted line;
d eletes th e num ber o f lin es specified by the prefix
argum ent.

4 Key available only on LK201 keyboard.
I ° « 1 Pointer b u tto n tran sitio n : o b u tto n up; • b u tto n h eld down; \ b u tto n pressed; f b u tto n released.
1 o » o I —> pointer m ovem ent w ith b u tto n s in specified state.
Pointer b u tto n s invoke com m and only w hen pointer cursor is in th e cu rre n t window.

( c o n tin u e d o n n e x t p a g e )

E-8 Editor Commands and Key Bindings

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

N am e

B inding! s)

D e scrip tio n

Kill N ext Form

None

D eletes th e LISP form im m ediately following
the cursor and adds it to the current kill-ring
region if th e previous com m and w as a kill-ring
command, or creates a new kill-ring region to hold
the deleted form; d eletes th e num ber of following
forms specified by th e prefix argum ent w ithin the
current parentheses n estin g level.

Kill Paragraph

(: STYLE "EMACS "1 | E s c a p e | HTl

D eletes the rest of th e current paragraph and adds
it to the current kill-ring region i f th e previous
command w as a kill-ring command, or creates a
new kill-ring region to hold th e deleted paragraph;
deletes th e num ber o f paragraphs specified by th e
prefix argum ent.

Kill Previous
Form

N one

D eletes the L IS P form im m ediately preceding
th e cursor and adds it to th e current kill-ring
region i f th e previous command w as a kill-ring
command, or creates a new kill-ring region to hold
the deleted form; d eletes th e num ber of preceding
forms specified by th e prefix argum ent w ithin the
current parentheses n estin g level.

Kill Region

(: STYLE "EMACS ")
Ictri/w| and 1 o 1 o 3

D eletes th e current select region and adds it to th e
current kill-ring region i f th e previous command
w as a kill-ring command, or creates a new kill-ring
region to hold the deleted region.

Kill R est of L ist

None

D eletes the rest of th e enclosing list and adds
it to th e current kill-ring region i f th e previous
command w as a kill-ring command, or creates
a new kill-ring region to hold th e deleted list
fragm ent.

Line to Top of
Window

(: STYLE "EMACS ") | E s c a p e | | 1|

Moves th e lin e containing the cursor to th e top of
th e window.

L ist Buffers

(: STYLE "EMACS ") |Ctrl/X| |Ctrl/B|

D isplays a lis t of all buffers.

L ist Key Bindings

None

D isplays a lis t of all visible key bindings or of all
keys bound in a specified context.

Maybe R eset
Select a t Pointer1

: GLOBAL i T ° °

If th e pointer cursor h as not moved, cancels the
select region th a t w as started w ith 1 l o o |; if
th e pointer cursor has m oved since 1 i o o | , does
nothing.

Move P oint and
S elect Region1

: GLOBAL I •o o

Move P oin t to
P ointer1

: GLOBAL 1 t o o

-*■

Moves the tex t cursor w ith th e pointer cursor,
m arking a select region.
Moves the tex t cursor to th e pointer cursor.

1 Available in both DECwindows and U IS P o in ter Syntax.
3 Available only in UIS P ointer Syntax.
P ointer b u tto n transition: o b u tto n up; •b u tto n held down; j b u tto n pressed; I b u tto n released,
o »o I —* pointer m ovem ent w ith b u tto n s in specified state.
-P oin ter b uttons invoke command only w hen p ointer cursor is in th e cu rre n t window.

(continued on next page)

Editor Commands and Key Bindings

E-9

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

Name

Binding(s)

Description

Move to LISP
C om m ent

( : S T Y L E " V A X L I S P " ) | C tr l/ x | [ ; |

If there is no com m ent on the current line, m oves
the cursor to the com m ent column and in serts a
semicolon and space; if there is a com m ent, m oves
the cursor to th e comment.

: G L O B A L I Return |

Breaks a lin e a t th e cursor position, leaving the
cursor at th e start of the new line.

N ew Line

( : BUFFER " G e n e r a l P r o m p t i n g
)L in e fe e d |
( : S T Y L E "E M A C S " ) | R e t u r n |

N ew LISP Line

( : S T Y L E "V A X L I S P " ) IL in e fse d |

Breaks a line at th e cursor position and indents
the new lin e by th e appropriate am ount in the
context of th e program.

N ext Form

( : S T Y L E " V A X L I S P " ) fctüöcl f l

Moves th e cursor to th e end of th e next form
or to th e end of the following form specified by
the prefix argum ent; does not move outside the
current parentheses n estin g level.

: GLOBAL j j

Moves the cursor to the next lin e or down the
num ber of lin es specified by the prefix argum ent,
keeping th e cursor in the sam e colum n if possible.

N ext Line

( : S T Y L E "E M A C S " ) [cw Tn]

N ext Paragraph

( : STY L E "E M A C S ") | E s c a p e | [ T l

M oves the cursor to th e beginning of the next
paragraph or to th e follow ing paragraph specified
by th e prefix argum ent.

N ext Screen

: G LO BA L | N ext S c r e e n | 4

Moves th e window down in th e buffer by one
screenful or by as m any screenfuls as are specified
by th e prefix argum ent.

: G L O B A L | Ctrl/X 1ICtrl/N 1

Selects another w indow on th e screen to be the
current window; eventually circulates through all
th e windows on th e screen.

N ex t Window

( : S T Y L E "E M A C S " ) |Ctrl/X|| P 1

Open Line

( : STYLE "ED T E m u l a t i o n " )
|p f i | k e y p a d [T ]

Breaks a lin e at th e cursor location, leaving the
cursor at th e end of th e old line.

( : S T Y L E " E M A C S ” ) [CM/Ö]

Page N ext
Window
P ause Editor

( : S T Y L E " E M A C S " ) | E s c a p e | Ictri/v)

Scrolls th e n ext window on the screen down one
page; or, i f a prefix argum ent is supplied, scrolls
the next w indow th a t m any rows.

: G L O B A L 1Ctrl/X I [CtH/zl

Saves th e Editor state and returns control to the
LISP interpreter.

( : S T Y L E "E M A C S " ) [ c t r i / G l

Previous Form

Previous Line

( : S T Y L E "V A X L I S P " ) Ictri/xHTI

Moves th e cursor to the beginning of th e previous
form or to th e beginning o f the preceding form
specified by the prefix argum ent; does not move
outside th e current parentheses n estin g level.

: G L O B A L Q]

M oves the cursor to th e previous lin e or up the
num ber o f lin es specified by the prefix argument;
keeps the cursor in th e sam e colum n if possible.

( : S T Y L E " E M A C S " ) [c w p !

4 Key available only on LK201 keyboard.
1 o I » | Pointer b u tto n tran sitio n : o b u tto n up; • b u tto n held down; 1 b u tto n pressed; f b u tto n released.
I o » o [—
» pointer m ovem ent w ith b u tto n s in specified state.
Pointer buttons invoke command only w hen pointer cursor is in th e cu rre n t window.

(continued on next page)

E-10 Editor Commands and Key Bindings

Table E-1 (Coni.):

Editor C om m an ds and Key Bindings

Name

Binding! s)

Previous
Paragraph

Previous Screen

STYLE "EMACS") IE s c a p e | [~p~l

Description
M oves the cursor to th e end of th e previous para
graph or to the end of the preceding paragraph
specified by th e prefix argum ent.

: GLOBAL | P rev S c r e e n ] 4

M oves the cursor up in th e buffer by one screenful

(: STYLE "EMACS ") IE s c a p e |py]

o r a s m a n y sc r e e n fu ls a s a r e s p e c ifie d b y t h e p re fix

argum ent.
Previous Window

( : STYLE "EMACS") |ctri/x[[~n~|

Prom pt Complete
String

( : BUFFER " G e n e r a l P r o m p t i n g " ) A ttem pts to complete your response to a prompt,
| Ctri/Space |
based on w hat you have typed already and th e

M akes another window on the screen into the
current window; eventually circulates through all
w indow s on the screen.

choices available in the situation.
Prom pt Help

(:B U F F E R " G e n e r a l P r o m p t i n g " ) D isplays inform ation for w hatever is being

prompted.

|P F 2 |

Prom pt Read and
Validate

[R e t u r n

Prom pt Scroll
H elp Window

I C tr l

Prom pt Show
A lternatives

[pfTI [pf2 |

in response to the current prompt, based on w hat
you have typed already.

( : STYLE "EM A CS") [Escape| |~g~|

Prom pts for a search string and a replacement;
offers a num ber of options at each replacem ent
opportunity.

: GLOBAL [cwx] [T]

Inserts th e next character typed a t th e cursor
location w ithout Editor interpretation.

Query Search
Replace
Quoted Insert

( : BUFFER " G e n e r a l P r o m p t i n g " ) U sed to term inate prompt input.

| and I E n t e r |

( : BUFFER " G e n e r a l P r o m p t i n g " ) Scrolls th e Help window down w hile another

At|

( : BUFFER " G e n e r a l P r o m p t i n g " ) D isplays a lis t of alternatives th a t can be entered

( : STYLE "EM A CS") [ c w x H ü

Read File

R edisplay Screen

buffer is current; supplied to le t you Bcroll the
H elp window w hile responding to a prompt.

( : STYLE "EM A CS") retrial fcWRl

Prom pts for a file specification, th en replaces
th e contents of th e current buffer w ith th e file;
i f th e current buffer is modified, prompts for
confirmation.

( : STYLE "EDT E m u l a t i o n " )

E rases and redisplays everything on the Bcreen.

ICtrl AV |

( : STYLE "EM A CS") [cwl !

Remove Current
Window

: GLOBAL |ctri/x1 | Ctrl/R |
( : STYLE "EMACS " ) fetri«] f~d~|

Rem oves th e current w indow from th e screen; does
not delete th e associated buffer.

Rem ove Other
Windows

( : STYLE "EM A CS") [ctri/x] p H

Rem oves all windows but th e current window from
th e screen.

Scroll Window
Down

( : STYLE "EM A CS") tcwzl

Scrolls th e current w indow down in th e buffer by
one row or th e num ber o f rows specified by the
prefix argum ent.

Scroll Window U p

( : STYLE "EM A CS") [ E s c a p e ] [7]

Scrolls th e current w indow up in th e buffer by one
row or by num ber of rows specified by th e prefix
argum ent.

4 Key available only on LK201 keyboard.
o 1 » I P o in ter b u tto n transition: o b u tto n up; • b u tto n held down; | b u tto n pressed; t b u tto n released.
o •o —* p ointer m ovem ent w ith b u tto n s in specified state.
P ointer b u tto n s invoke command only w hen p ointer cursor is in th e cu rren t window.

(continued on next page)

Editor Commands and Key Bindings E-11

Table E—1 (Cont.):

Editor C om m an ds and Key Bindings

Name

Bindmg(s)

Description

Secondary Select
R egion2

: GLOBAL I o o • |

S ets th e beginning of secondary selection (used in
Copy from P ointer command).

S elect Buffer

( : STYLE "EM A CS") [Ctri/xllTl

Prom pts for a buffer nam e, then m akes th a t
buffer the current buffer; creates a new buffer if
necessary.

S elect Enclosing
Form at Pointer1

( : STYLE "VAX L I S P " ) 1 1 o o |

Places th e form enclosing th e cursor in a select
region; if th e cursor is already in a select region,
expands th e region to th e next outerm ost form.

S elect O uterm ost
Form

( : STYLE "VAX L I S P " )
ICtrl/XI | CtrlSpace |

M akes the outerm ost LISP form containing the
cursor into a select region.

S e lf Insert

: GLOBAL All graphic characters

Inserts th e la st character typed a t the cursor
location.

S et DECwindows
Pointer S yntax

N one

U nbinds th e U IS pointer bindings and binds the
DECwindows pointer bindings.

S et U IS P ointer
S yntax

N one

U nbinds th e DECwindows pointer bindings and
binds th e U IS pointer bindings.

S et Screen H eight

N one

S ets th e screen h eig h t to th e num ber of rows
specified by th e prefix argum ent; prompts for
h eigh t i f no prefix argum ent is defined.

S et Screen Width

None

S ets th e screen w idth to the num ber of colum ns
specified by th e prefix argum ent; prompts for th e
w idth i f no prefix argum ent is defined.

( : STYLE "EOT E m u l a t i o n " )

Places a m ark at th e cursor position to indicate
one end of a select region.

S et Select Mark

keypad □
( : STYLE "EM A CS") I C t r l / S p a c e |

Show Time

( : STYLE "EMACS " ) ictri/xl [Ctri/f]

D isplays th e tim e and date in th e inform ation
area.

Shrink Window

( : STYLE "EM A CS") [ctrf*l [ctri/z]

Shrinks th e current w indow by one row or the
num ber of rows specified by the prefix argum ent.

Split Window

( : STYLE "EM A CS") 1555x1 IT]

Splits th e current w indow into tw o identical
windows.

Start Keyboard
Macro

: GLOBAL [Ciri/Xl [71

Starts collecting keystrokes for a keyboard macro,
replacing any unnam ed keyboard macro that
already exists.

Start N am ed
Keyboard Macro

N one

Prom pts for a name, then starts collecting
keystrokes for a keyboard macro; the resulting
keyboard macro is cataloged under th e nam e you
give and can be treated as a command.

Supply EMACS
Prefix

( : STYLE "EM A CS") |Ctfi70]

S ets th e prefix argum ent to four if no prefix
argum ent w as defined, or to four tim es its former
valu e i f a prefix argum ent w as defined.

1 Available in both DECwindows an d UIS P ointer Syntax.
2 Available only in DECwindows P ointer Syntax.
I Pointer b u tto n transition: o b u tto n up; • b u tto n h eld down; [ b u tto n pressed; T b u tto n released.
* pointer m ovem ent w ith b u tto n s in specified state.
Pointer buttons invoke comm and only w hen pointer cursor is in th e cu rre n t window.

( c o n tin u e d o n n e x t p a g e )

E-12

Editor Commands and Key Bindings

Table E-1 (Cont.):

Editor C om m an ds and Key Bindings

Name

Bmding(s)

Description

Supply Prefix
A rgum ent

( : S T Y L E "ED T E m u l a t i o n " )
F ilfP F il

Prom pts for a prefix argum ent; if a prefix ar
gum ent is already defined, m ultiplies it by the
num ber you enter.

( : S T Y L E " E M A C S " ) | Escape | [CtFiÄJl

Transpose
Previous
Characters

( : S T Y L E " E M A C S " ) fctriTf]

Transposes th e two characters preceding the
cursor.

Transpose
Previous Words

( : S T Y L E " E M A C S " ) | Escapei m

Transposes th e words at and preceding the cursor.

U ndo Previous
Yank

( : S T Y L E " E M A C S " ) |E scape| [Ctri/W]

D eletes the previously yanked region w ithout
pushing it onto th e kill ring; more generally,
deletes the select region w ithout pushing it onto
the kill ring.

( : S T Y L E "ED T E m u l a t i o n " )

Cancels the current select region.

U n se t Select
Mark

U pcase Region

N one

C hanges all alphabetic characters in the current
select region to uppercase.

U pcase Word

( : S T Y L E " E M A C S " ) fEscape| ["VI

C hanges all alphabetic characters in the word at
the cursor location to uppercase.

V iew P ile

( : S T Y L E "E M A C S " ) |CtriÖ<] [Ctri/F]

Prom pts for a file specification, th en reads the
specified file into a read-only buffer.

W hat Cursor
P osition

( : STYLE " e m a c s ") rs w x irri

D isplays inform ation about th e cursor location.

W rite Current
Buffer

( : S T Y L E " E M A C S " ) [C W X lfT l

W rites out th e current buffer; creates a new
file version or updates the LISP symbol w hose
function or valu e slot is being edited.

Write Modified
Buffers

( : S T Y L E "E M A C S " ) fCWXl [CtriTMl

Performs th e " W r i t e C u r r e n t B u f f e r " operation
for each buffer th a t h as been modified.

Write N am ed Pile

( : S T Y L E " EM A C S " ) [ciFi/Xl [Ctri/Wl

Prom pts for a file specification, th en creates a file
having th a t specification from th e contents of the
current buffer.

Yank

( : S T Y L E " E M A C S " ) ICtrWl

Inserts the current kill-ring region at th e cursor
location; in serts as m any copies as are specified by
th e prefix argum ent.

Yank at Pointer3

( : STY LE "E M A C S") | • X o |

Inserts th e current kill-ring region a t the pointer
cursor location.

Yank Previous

( : S T Y L E " E M A C S " ) [Escape! f y l

R otates the k ill ring forward, th en in serts the
new current kill-ring region a t the cursor location;
in serts as m any copies a s are specified by th e
prefix argum ent.

8 Available only in UIS Pointer Syntax.
o

i » I Pointer button transition: o button up; • button held down; j button pressed; | button released.

o » o I —» pointer movement with buttons in specified state.

Pointer buttons invoke command only when pointer cursor is in the current window.

(continued on next page)

Editor Commands and Key Bindings E - 1 3

Table E-1 (Cent.):

Editor C om m an ds and Key Bindings

Name

Binding! s)

Description

Yank Replace
Previous

( : S T Y L E "E M A C S " ) I E scape! IctFiTvl

D eletes the previously yanked region, rotates the
kill ring forward, and in serts the new current k ill
ring region at the cursor location; inserts as m any
copies as are specified by the prefix argum ent.

o J » | Pointer button transition: o button up; • button held down; J. button pressed; ] button released.
o » o | —» pointer movement with buttons in specified state.

Pointer buttons invoke command only when pointer cursor is in the current window.

E.2 Editor Key Bindings
Table E -2 lists the keys and key sequences th a t are bound to E ditor commands
and the context in which they are bound. Some keys or key sequences are bound
to more th a n one command. To find out which command a key or key sequence
will invoke, use the following procedure:

Table E-2:

If your current buffer is " G e n e r a l P r o m p t i n g " (th a t is, you are typing in
response to a prom pt) and the key or key sequence is bound to a command in
the context ( : b u f f e r " G e n e r a l P r o m p t i n g " ) , then the key or key sequence
invokes th a t command. If you have bound a key or key sequence to a
command in the context of a p articu lar buffer, and th a t buffer is the current
buffer, th en th e key or key sequence invokes th a t command.

Otherwise, if th e key or key sequence is bound to a command in one or more
m inor styles, th en th e key or key sequence invokes the command to which it
is bound in the m ost recently activated m inor style. You can tell which m inor
style was activated m ost recently by exam ining th e window’s label strip. The
label strip contains a list of th e active m inor styles, w ith the m ost recently
activated style a t the front of th e list.

Otherwise, if th e key or key sequence is bound to a command in the current
m ajor style, then the key or key sequence invokes th a t command. You can
identify the m ajor style by looking a t the label strip; it precedes the list
of m inor styles. (If the lis t of m inor styles is too long, the m ajor style is
om itted.)

Otherwise, if th e key or key sequence is bound to a comm and in the : g l o b a l
context, then the key or key sequence invokes th a t command.

Otherwise, the key or key sequence is unbound; typing it resu lts in an error.

Editor Key Bindings
Command

Context

Key(s)

Single Keys
| C trl/S pace |

!Ctrl/A 1

( : STYLE "EM A CS")

Prompt Complete String
S et Select Mark

( : STYLE "EM A CS")

Beginning o f Line

( : BUFFER " G e n e r a l P r o m p t i n g " )

(continued on next page)

E-14

Editor Commands and Key Bindings

Table E-2 (Cont.):

Editor Key Bindings

Key(s)

Context

Command
Single Keys

[Ciri/Bj

(: STYLE "EM A CS")

Backward Character

|Otrl/D|

(: STYLE "EM A CS")

D elete N ex t Character

[Ctri/E]

(: STYLE "EM A CS")

End o f Line

[Ctrl/F|

(: STYLE "EM A CS")

Forward C haracter

ICtrl/G|

(: STYLE "EM A CS")

P ause Editor

|Ctrl/H| or | Backspace |

(: STYLE "ED T E m u l a t i o n " )

EDT Back to Start of Line

[Tab) or |Ctrl/l|

(: STYLE "VAX L I S P " )

In dent LISP Line

|Ctrl/J| or | Linefeed |

( : BUFFER " G e n e r a l P r o m p t i n g " )
(: STYLE "VAX L I S P " )
(: STYLE "ED T E m u l a t i o n " )

N ew Line
N ew LISP Line
EDT D elete Previous Word

|Ctrl/K1

(: STYLE "EM A CS")

Kill Line

|Clrl/L|

(: STYLE "EM A CS")

R edisplay Screen

| Return| or |Ctrl/M|

( : BUFFER " G e n e r a l P r o m p t i n g " )
( : STYLE "EM A CS")
: GLOBAL

Prom pt Read and Validate
N ew Line
N ew Line

ICtrl/N|

( : STYLE "EM A CS")

N ex t Line

|Ctrl/O|

( : STYLE "EM A CS")

Open Line

|CW/P|

( : STYLE "EM A CS")

Previous Line

ICtrl/Rl

'(: STYLE "EM A CS")

Backward Search

[ctri/f]

(: STYLE "EM A CS")

Transpose Previous Characters

|ctn/u|

(: STYLE "EM A CS")
(: STYLE "EDT E m u l a t i o n " )

Supply EM ACS Prefix
EDT D elete Previous Line

|Ctrl/V|

( : BUFFER " G e n e r a l P r o m p t i n g " )
(: STYLE "EM A CS")

Prom pt Scroll H elp Window
N ex t Screen

|Ctrl/W|

( : STYLE "EM A CS")
( : STYLE "EDT E m u l a t i o n " )

Kill Region
R edisplay Screen

1Ctrl/VI

(: STYLE "EM A CS")

Yank

jctrl/Z |

(: STYLE "EM A CS")
: GLOBAL

Scroll Window Down
Execute N am ed Command

fctriÄ]

(■•STYLE "EM A CS")

EMACS Forward Search

[Ctrl/?]

(: STYLE "VAX L I S P " )

D escribe Word

1D elete Ior < 3

( : STYLE "EM A CS")
( : STYLE "EDT E m u l a t i o n ” )
: GLOBAL

D elete Previous Character
D elete Previous Character
D elete Previous Character

m
keyp ad[T ]

(••STYLE "VAX L I S P " )

In sert Close Paren and Match

(: STYLE "ED T E m u l a t i o n " )

EDT B eginning of Line

keypad QH

(: STYLE "EDT E m u l a t i o n " )

EDT Move Word

keypad [T]

(: STYLE "EDT E m u l a t i o n " )

EDT End o f Line

keypad [T]

(: STYLE ” EDT E m u l a t i o n " )

EDT Move C haracter

keypad [T]

( : STYLE "EDT E m u l a t i o n " )

EDT Set D irection Forward

keypad [T]

(: STYLE "ED T E m u l a t i o n " )

EDT Set D irection Backward

(continued on next page)

Editor Com m ands and Key Bindings

E-15

Table E-2 (Cont.):

Editor Key Bindings

Key(s)

Context

Command
Single Keys

( : STYLE "EDT E m u l a t i o n " )

EDT Cut

keypad [T]

(.•STY LE "EDT E m u l a t i o n " )

EDT Move Page

keypad [T]

( : STYLE "EDT E m u l a t i o n " )

EDT Scroll Window

keypad [T]

( : STYLE "EDT E m u l a t i o n " )

EDT Append

keypad [7]

( : STYLE "EDT E m u l a t i o n " )

S et Select Mark

keypad I Enter |

( : BUFFER " G e n e r a l P r o m p t i n g " )

Prompt Read and Validate

k e y p a d [7]

(: STYLE "EDT E m u l a t i o n " )

EDT D elete Character

keypad Q

( : STYLE "EDT E m u l a t i o n " )

EDT D elete Word

keypad [pf2]

(: BUFFER " G e n e r a l P r o m p t i n g " )
(: STYLE "ED T E m u l a t i o n " )
: GLOBAL

Prompt Help
Help
Help

keypad |PF3|

( : STYLE "EDT E m u l a t i o n " )

EDT Search A gain

keypad ]pf*|

( : STYLE "EDT E m u l a t i o n " )

EDT D elete Line

: GLOBAL

Previous Line

: GLOBAL

N ext Line

: GLOBAL

Forward C haracter

: GLOBAL

Backward Character

: GLOBAL

S elf Insert

keypad [T]

E)
All graphics
characters

Single Keys (LK201 Keyboard Only)
EÜ

( : STYLE "EDT E m u l a t i o n " )

EDT Back to Start o f Line

[ÜH

(:S T Y L E "EDT E m u l a t i o n " )

EDT D elete Previous Word

: GLOBAL

Help

@
EEH

: GLOBAL

Execute N am ed Command

( : STYLE "ED T E m u l a t i o n " )

EDT Query Search

| Insert H ere |

( : STYLE "ED T E m u l a t i o n " )

EDT P aste

| R em ove |

( : STYLE "EDT E m u l a t i o n " )

EDT Cut

| S e le c t |

( : STYLE "EDT E m u l a t i o n " )

EDT Select

| P rev S c re e n |

: GLOBAL

Previous Screen

| Next S c re e n |

: GLOBAL

N ext Screen

(continued on next page)

E-16

Editor Commands and Key Bindings

Table E-2 (Cont.):

Editor Key Bindings

Key(s)

Context

Command

Two-Key Sequences Starting with Ctrl/X
|C tr l/ X 11 C t r l / S p a c e |

(: STYLE "VAX LISP")

Select O uterm ost Form

1C tr l/ X I I C trl/ A I

(: STYLE "VAX LISP")

E valuate LISP Region

I C trl/ X | |C tr l/ B I

(:STYLE "EMACS")

L ist Buffers

I C tr l/ X | |C tr l/ D |

(: STYLE "EMACS")

Delete C u rren t Buffer

(: STYLE "EMACS")
:GLOBAL

Ed
Execute Keyboard Macro

(:STYLE "EMACS")

View File

(:STYLE "EMACS")
(: STYLE "VAX LISP")

In se rt File
In d e n t O uterm ost Form

|or

(: STYLE "EMACS")

W rite Modified Buffers

IC tr l/ X I IC tr l/ E I

IC tr l/ X I I C tr l/ F l

|C tr l/ X | |Tab|

I C tr l/ X I IC trl/ ll
|C tr l/ X | | R e t u r n
I C tr l/ X

||C trl/M |

I C tr l/ X

|[ C trl/ N I

: GLOBAL

N ext Window

(:STYLE "EMACS")
:GLOBAL

Read File
Remove C u rren t Window

(:STYLE "EMACS")

Show Time

I C tr l/ X | C tr l/ R

IC tr l/ X I IC tr l/ T I

||C trl/ V |

(:STYLE "EMACS”)

E d it File

I C tr l/ X | | C lrl/ W |

(:STYLE "EMACS")

W rite Nam ed File

||C tr l/ X I

(:STYLE "EMACS")

Exchange Point and Select M ark

|C tr l/ X ||C trl/Z |

(:STYLE "EMACS")
:GLOBAL

S h rin k Window
P ause Editor

12HE1LU
1C tr l/ X 11 ) |

:GLOBAL

S ta rt Keyboard Macro

:GLOBAL

E nd Keyboard Macro

1Ctrl/X 11, |

(: STYLE "VAX LISP")

Previous Form

|. |

(: STYLE "VAX LISP")

N ext Form

(: STYLE "EMACS")

Remove O th er Windows

ICtrl/X | | 2 |

(: STYLE "EMACS")

Split Window

I C tr l/ X

1C tr l/ X

ICtrl/X |

|C trl/X | |

ICtrl/XI I

(: STYLE "VAX LISP")

Move to LISP Comment

|C trl/X | |

(: STYLE "VAX LISP")

Beginning of O uterm ost Form

|C trl/X | |

(: STYLE "VAX LISP")

End of O uterm ost Form

ICtrl/X ]|. |

(: STYLE "EMACS")

W hat C ursor Position

|Ctrl/X || ? |

:GLOBAL

Help on E ditor E rror

1Ctrl/X ||\ |

:GLOBAL

Quoted In se rt

|Ctrl/X ||b |

(:STYLE "EMACS")

Select Buffer

ICtrl/X 11d |

(:STYLE "EMACS")

Remove C u rren t Window

: GLOBAL

Execute Keyboard Macro

ICtrl/X II n I

(:STYLE "EMACS")

Previous Window

|p |

(:STYLE "EMACS")

N ext Window

ICtrl/XI

|C trl/X |

Ie I

(:STYLE "EMACS")

Quoted In sert

ICtrl/XI I s I

(:STYLE "EMACS")

W rite C u rren t Buffer

ICtrl/X | | z I

(:STYLE "EMACS")

Grow Window

ICtrl/XI I

(continued on next page)

Editor C o m m a n d s and Key Bindings

E-17

Table E-2 (Cont.):

Editor Key Bindings

Key(s)

Context

Command

Two-Key Sequences Starting with Escape
I E sc a p e

|C trl/Space |

(:STYLE "EMACS")

U n set Select M ark

| E sc a p e

ICtrl/D |

(:STYLE "EMACS")

Delete W hitespace

| E sc a p e

| Ctrl/G |
ICtrl/U |

(:STYLE "EMACS")
(:STYLE "EMACS")

E xit Recursive Edit

| E sc a p e
| E sc a p e

|Ctrl/Vj

Page N ext Window

|E sc a p e ICtrl/WI
|E sc a p e jctrl/YI

(:STYLE "EMACS")
(:STYLE "EMACS")
(:STYLE "EMACS")

Yank Previous Replace

|E sc a p e m

(:STYLE "EMACS")

Line to Top of Window

□
|E sc a p e □
[E sc a p e ED

(:STYLE "EMACS")
(:STYLE "EMACS")

Beginning of Window

(:STYLE "EMACS")

Beginning of Buffer

| E sc a p e

ED
|E sc a p e c n
j E sc a p e m

(:STYLE "EMACS")

E nd of Buffer
Apropos Word

| E sc a p e

(:STYLE "VAX LISP")
(:STYLE "VAX LISP")
(:STYLE "EMACS")
(:STYLE "EMACS")
(:STYLE "EMACS")
(:STYLE "EMACS")

Delete N ext Word

| E sc a p e

s
1b |

1c 1
)E scape l d l

t E sc a p e

Supply Prefix A rgum ent
Undo Previous Yank

E nd of Window

Close O uterm ost Form
Beginning of P arag rap h
Backw ard Word
Capitalize Word

161

(:STYLE "EMACS")

E nd of P arag rap h

| E sc a p e

Forw ard Word

| E sc a p e

(:STYLE "EMACS")
(:STYLE "EMACS")
(:STYLE "EMACS")
(:STYLE "EMACS")

Downcase Word

(:STYLE "EMACS")
(:STYLE "EMACS")
(:STYLE "EMACS")
(:STYLE "EMACS”)

Previous P arag rap h

(: STYLE "EMACS")
(: STYLE "EMACS")

Previous Screen

(:STYLE "EMACS")
(:STYLE "EMACS")

Yank Previous

(:STYLE "EMACS")

D elete Previous Word

| E sc a p e

| E sc a p e

H
|E sc a p e m
j E sc a p e

Kill P arag rap h
N ext P arag rap h
Query Search Replace
Transpose Previous Words
U pcase Word
Execute N am ed Command
Scroll Window Up

(continued on next page)

E-18

Editor C o m m a n d s an d Key Bindings

Table E-2 (Cont.):

Editor Key Bindings

Key(s)

Context

Command

Two-Key Sequences Starting with Keypad PFl
k e y p a d [pfT] |T ]

(:STYLE "EDT Em ulation")

O p e n L in e

k e y p a d [pfT] [7 ]

(:STYLE "EDT Em ulation")

E D T C h a n g e C a se

k e y p a d | p fi | IT]

(:STYLE "EDT Em ulation")

E D T D e le te to E n d o f L in e

k e y p a d [pfT] [7 ]

(:STYLE "EDT Em ulation")

E D T S p e c ia l I n s e r t

k e y p a d [pfT] [7 ]

(:STYLE "EDT Em ulation")

E n d o f B u ffe r

k e y p a d [p fi | |~sl

(:STYLE "EDT Em ulation")

B e g in n in g o f B u ffe r

k e y p a d | p f i | |~6~|

(:STYLE "EDT Em ulation")

E D T P a s te

k e y p a d [pfT] [7 ]

(:STYLE "EDT Em ulation")

E x e c u te N a m e d C o m m a n d

k e y p a d | p f i | IT]

(:STYLE "EDT Em ulation")

E D T R e p la c e

k e y p a d ]pfi| |~|

(:STYLE "EDT Em ulation")

U n s e t S e le c t M a rk

k e y p a d [pfT| | E n t e r |

(:STYLE "EDT Em ulation")

E D T S u b s titu te

k e y p a d | p f i | [~T1

(:STYLE "EDT Em ulation")

E D T U n d e le te C h a r a c te r

k e y p a d | p f i | p*l

(:STYLE "EDT Em ulation")

E D T U n d e le te W ord

k e y p a d |pfi | |p f i |

(:STYLE "EDT Em ulation")

S u p p ly P re fix A r g u m e n t

k e y p a d [pfT] [pfS]

(:BUFFER "G en era l Prom pting")

P r o m p t S h o w A lte r n a tiv e s

k e y p a d [pfT] [pf|]

(:STYLE "EDT Em ulation")

E D T Q u e ry S e a rc h

k e y p a d [pfT] [pfä]

(:STYLE "EDT Em ulation")

E D T U n d e le te L in e

Editor C o m m a n d s an d Key Bindings

E-19

Index
BACKTRACE
stepper command (cont’
d.)

?
Debugger command
description, 4-9
Stepper command
description, 4-19

A___________________ _
" A c t iv a te Minor S t y le " Editor command
using, D-3
Alien structure facility, 1-4
ALL
Debugger command modifier, 4-8
with BACKTRACE command, 4-12
with BOTTOM command, 4-10
with DECwindows, 10-5
with DOWN command, 4-10
with TOP command, 4-10
with UP command, 4-11
Alternatives
Editor prompt input, 3-7, 8-10
files, 3-7, 8-10
Anchored windows, 3-24, 8-14
Applications
moving between, A-4
running
a s icons, A-5
APROPOS function
debugging information, 4—1
help, 1-7
invoking from DECwindows, 7-13
"A propos" Editor command, 3-6, 8-8
APROPOS-LIST function
debugging information, 4-1
ARGUMENTS
Debugger command modifier, 4-8
with SET command, 4-11
with SHOW command, 4—11
Arrow keys
Editor usage, 3-14
specifying in BIND-COMMAND function, 3-31,

8-21

B
BACKTRACE
Debugger command
description, 4—12
(table), 4-7
stepper command
description, 4-19

(table), 4-18

"Backward C h a ra cte r" Editor command
"EMACS" style binding, D—4
"Backward Word" Editor command
"EMACS" style binding, D-4
"B egin n in g o f B u ffe r " Editor command
"EMACS" style binding, D-4
"B egin n in g o f L in e" Editor command
"EMACS" style binding, D—4
"B egin n in g o f P aragraph" Editor command
"EMACS " style binding, D—4
"B egin n in g o f Window" Editor command
"EMACS " style binding, D-4
"B ind Command" Editor command, 3—30, 8-20
specifying context, 3-31,8-20
specifying keys, 3-30, 8-20
BIND-COMMAND function, 3-31, 8-20
specifying context, 3-33, 8-22
specifying keys, 3-31,8-20
BIND-KEYBOARD-FUNCTION function
and ED function, 3-5
invoking the break loop, 4-3
BOTTOM
Debugger command
description, 4-10
(table), 4-7
BREAK function
debugging information, 4-1
invoking th e b re a k loop, 4-3
Break loop, 1-4, 4-3 to 4—5
exiting, 4—4
from DECwindows, 10-6
invoking, 4-3
from DECwindows, 10-5
m essage, 4-3
prompt, 4-3
using, 4-4
from DECwindows, 10-7
variables, 4-5
*BREAK-ON-WARNINGS* variable, 4-9
Buffers
Editor
S e e Editor buffers
Button
defined, A-3

lndex-1

c_______________
CALL
Debugger command modifier, 4-8
with SHOW command, 4-11
Call-back facility, 1-4
Call-out facility, 1—4
Calling stack window
description, 10-10
making it disappear, 10-11
making it reappear, 10-11
" C a p i t a l i z e W o r d " Editor command
"EM ACS" style binding, D-5
Characters
changing ca se with editor, 3—17,8-13
creating special keyboard, A-17
nongraphic
Editor representation, 3-13, 8-13
inserting with Editor, 3-13, 8-13
specifying in " B i n d C o m m a n d ", 3-30,

8-20
Checkpoint file, 3-29,8-18
Clear
menu item
clearing trace output, 10-19
Clicking
defined, A-2
C lose menu item
Inspector, 9-8
CLX windows interface, 1-5
Command levels
Debugger, 4-6
stepper, 4-19
tracer, 4-25
Command modifiers
S e e Debugger
Commands
Editor
S e e Editor commands
Comments
LISP
inserting with Editor, 3-13
COMMON LISP, 1-1
COMPILE function, 1—
3
compiling functions and macros, 2-5
invoking from DECwindows, 7-10
/COMPILE qualifier, 1-2
compiling files, 2-6
description, 2-10
modes, 2-10
(table), 2-8
with/ERROR_ACTION qualifier, 2-11
with /INITIALIZE qualifier, 2-12
with /LIST qualifier, 2-13
with /MACHINE_CODE qualifier, 2-14
with/NOOUTPUT_FILE qualifier, 2-16
with/OPTIMIZE qualifier, 2-15
with /OUTPUT_FILE qualifier, 2-16
with/VERBOSE qualifier, 2-16
with/WARNINGS qualifier, 2-17
C O M P IL E -F IL E function, 1-3
compiling files, 2-6
compiling files in DECwindows, 7-7
Compiler, 1-3
o p tim izatio n s,

2—15

Compiling
LISP files from DECwindows,

lndex-2

6-4

Completion
Editor prompt input, 3-7, 8-9
files, 3-7, 8-10
C om pose sequence
defined, A-17
CONTINUE
DCL command, 1-9
Debugger command
description, 4-9
(table), 4-7
CONTINUE function
exiting the break loop, 4-4
Control characters
Editor representation, 3-13, 8-13
inserting with Editor, 3-13, 8-13
specifying in " B i n d C o m m a n d ", 3—30, 8-20
specifying in BIND-COMMAND function, 3-31
(table), 2-4
Control stack, 4-2
Debugger, 4-5
stack frame
S e e Stack frame
/CSTACK qualifier
default size, 2-11
description, 2-11
minimum size, 2-11
(table), 2-8
Ctrl/C
prohibition in Editor key binding, 3-34, 8-23
recovering from an error, 2-4
to cancel Editor command, 3-5
Ctrl/O, 2-4
Ctrl/Q, 2-4
prohibition in Editor key bindinq, 3-34, 8-23
Ctrl/R, 2-4
Ctrl/S, 2-4
prohibition in Editor key binding, 3-34, 8-23
Ctrl/T, 2-4
Ctrl/U, 1-9, 2-4
Ctrl/X, 2-4
Ctrl/Y, 1-9, 2-4
Current direction
Editor, 3-14
Current stack frame, 4-5
Cursor
moving, A-17

D________________ _ _ _ _ _
Data
structure, 1-1
DCL commands
CONTINUE, 1-9
entering, 1-9
LISP, 1-2, 2-1
STOP, 1-9
DEBUG
stepper command
description, 4-19
(table), 4-18
DEBUG function
debugging information, 4-1
invoking the Debugger, 4-5
Debug I/O Window
description, 10-10
DEBUG-CALL function, 4-12

DEBUG-CALL function (cont'd.)

DEFMACRO m acro

debugging information, 4 -1
: DEBUG-IF keyword
TRACE macro, 4-27
*DEBU G-IO* variable
Debugger, 4-5
stepper, 4-14
*DEBUG-PRINT-LENGTH*
control variable
and DECwindows, 10-5
*DEBUG-PRINT-LENGTH* variable
controlling output, 4-2
*DEBUG-PRINT-LEVEL*
control variable
and DECwindows, 10-5
*DEBUG-PRINT-LEVEL* variable
controlling output, 4-2
Debugger, 1-4, 4—5 to 4-14
caution box
entering Debugger from, 10-1
returning to top-level from, 10-1
commands
arguments, 4-8
entering, 4-8
descriptions, 4-9 to 4-12
modifiers (table), 4-8
(table), 4-7
exiting, 4-6, 4-9
from the DECwindows interface, 10-11
invoking, 4-5,4-19,4-27
from DECwindows, 10-9
from the Trace Options Dialog Box, 10-21
prompt, 4-6
sam ple sessions, 4-13
using, 4-7
Debugger commands
invoking with optional arguments
from the DECwindows interface, 10-11
modifiers, 10-14
taking arguments
invoking from DECwindows, 10-13
taking no arguments
invoking from DECwindows, 10-13
types of arguments, 10-13
using
from the DECwindows interface, 10-12
Debugger commands window
description of, 10-11
making it disappear, 10-11
making it reappear, 10-11
Debugging facilities, 1-4

creating programs, 2-4
DEFUN macro
creating programs, 2-4
" D e l e t e C u r r e n t B u f f e r " Editor command,
3-27, 8-17
"EMACS" style binding, D-5
Delete key, 2-3
" D e l e t e N a m e d B u f f e r " Editor command,
3-27, 8-17
" D e l e t e N e x t C h a r a c t e r " Editor command
"EMACS” style binding, D-4
" D e l e t e N e x t W o rd " Editor command
"EMACS" style binding, D-4
" D e l e t e P r e v i o u s C h a r a c t e r " Editor
command
"EM ACS" style binding, D-4
" D e l e t e P r e v i o u s W o r d " Editor command
"EMACS" style binding, D—4
" D e l e t e W h i t e s p a c e " Editor command
"EMACS" style binding, D—4
D E SC R IB E function
debugging information, 4-1
help, 1—7
invoking from DECwindows, 7-13
invoking from Editor, 3-6, 8-9
using pointer, 3-39
" D e s c r i b e " Editor command, 3-6, 8-8
Device, 1-7
Dialog box
components of, A-11
moving within, A-12
Directory, 1-7
Display
defining, 6-1
with SET DISPLAY, 6-1
Double clicking
defined, A-2
DOWN
Debugger command
description, 4-10
(table), 4-7
Debugger command modifier, 4-8
with SEARCH command, 4-10
" D o w n c a s e W o rd " Editor command
"EM ACS" style binding, D -5
Dragging
defined, A-2
D R IB B L E function
debugging information, 4—1
invoking from DECwindows, 7-10
: DURING keyword
TRACE macro, 4-27
Dynamic memory, 2-14

S e e also Break loop, Debugger, Stepper, Tracer,
Editor
Debugging functions and macros (table), 4-1
Debugging utilities
using
from DECwindows, 10-1 to 10—23
DECwindows
and Debugger commands, 10-12
DECwindows interface
SET DISPLAY command, 6-1
DECwindows utilities
invoking, 7-11
DECwindows XUI Toolkit, 1-5
Default option
choosing, A-4, A-11

E________________________
ED function
and B IN D -K EY BO A RD -FU N CTIO N ,
debugging information, 4-1
resuming Editor with, 3-4
starting Editor with, 3-3, 8-3
" E d " Editor command, 3-26,8-16
"EM ACS" style binding, D-6
" E d i t F i l e " Editor command, 3-26
"EM ACS" style binding, D-6

3-5

Index-

Editing keys
specifying in BIND-COMMAND function,

Editor (cont'd.)
3-31,

8-21
Editor, 1-3
checkpointing, 3-29,8-18
checkpointing file
file type, 1-9
copying text, 3-17
creating programs, 2-4
cursor movement, 3-14
by LISP entities, 3-15
current direction, 3-14
moving by lines, 3-14
moving by words, 3-14
searching, 3-15
using pointer, 3-38
customizing, 3-29
debugging facility, 4-29
DECwindows default pointer bindings, 8-11
errors while using, 3-7,8-10
evaluating cod e
in the DECwindows environment, 8-5
exiting, 3-9
by deleting VWS VAXstation window, 3-37
from the DECwindows environment, 8-7
getting help, 3-6, 8-8
in the DECwindows environment, 8-8
help menu
in the DECwindows environment, 8-8
help on Editor objects
in the DECwindows environment, 8-8
help window, 3-6, 8-8
removing, 3-6, 8-8
scrolling, 3-6, 8-8
information area, 3-4
invoking, 3-3
invoking from DECwindows menus, 8-2
invoking in DECwindows, 8-3
keyboard macros, 3-35, 8-24
label strip, 3-4
loading files, 2-5
menus, 8-1
modifying function and macro definitions, 2-6
moving text, 3-16, 3—17
using pointer, 3-38
overview of operation, 3-2
pausing, 3-8
on VWS VAXstation, 3-37
protection against work loss, 3-29, 8-18
refreshing the screen, 3-8
repeating operations, 3-19
restoring deleted text, 3-16
resuming, 3—4
in the DECwindows environment, 8-6
returning to LISP
in the DECwindows environment, 8-6
saving work, 3-8
in the DECwindows environment, 8-5
searching, 3-15
substituting in text, 3-18
table of commands, E-1
text deletion, 3-16
by characters, 3-16
bylines, 3-16
bywords, 3-16
text insertion, 3-11
in the DECwindows environment, 8-4

Index-4

typing LISP code, 3-12
undeleting text, 3-16
using on VWS VAXstation, 3-36
editing with pointer, 3-37
Editor buffers, 3-23, 8-14
as context, 3-34, 8-23
creating, 3-23, 8-14
from within Editor, 3-26, 8-16
current buffer, 3-23, 8-14
changing, 3-24, 8-14
deleting, 3-27, 8-17
displaying more than two, 3-28, 8-18
" G e n e r a l P r o m p t i n g " , E-14
information maintained by, 3-26, 8-16
inserting into other buffers, 3-18, 8-13
listing, 3-24,8-14
moving text between, 3-28, 8-18
moving to endpoints, 3-14
name conflicts, 3-27,8-17
saving contents, 3-26,8-17
selecting, 3-25, 8-15
Editor commands, 3-5
binding keys to, 3-30, 8-19
conflicts in "EMACS" style, D-1
from LISP interpreter, 3-31,8-20
key binding shadowing, 3-35, 8-24
multiple bindings, E-14
table of bindings, E-1
table of bindings by key, E-14
within Editor, 3-30, 8-20
buffer and window
summary, 3-28
canceling, 3-5
capturing seq u en ces of, 3-35, 8-24
creating
with " S t a r t N a m e d K e y b o a r d M a c r o "
3-35, 8-25
customizing
summary, 3-36
descriptions, E-1
editing
summary, 3-19
general-purpose
summary, 3-9
invoking with keys, 3-5
issuing, 3-5
repeating, 3-19
typing, 3-5
using
in the DECwindows environment, 8-4
Editor context
buffer, 3-34, 8-23
effect on key bindings, 3-34, 8-23
effect on keyboard macro execution, 3-36, 8-25
global, 3-34, 8-24
order of search, 3-35, 8-24
specifying
in " B i n d Com m and", 3-31, 8-20
styles, 3-34,8-24
Editor styles, 3-34, 8-24
as context, 3-34, 8-24
major style, 3-35, 8-24
minor style, 3-35, 8-24
order of search, 3-35, 8-24

Editor window
with two buffers

EVALUATE
stepper command (cont’
d.)

in the DECwindows environment, 8-7
Editor windows, 3-23,8-14
anchored windows, 3-24,8-14
changing size, 3-27,8-18
creating, 3-23, 8-14
current window, 3-23,8-14
changing, 3-24, 8-14
changing with pointer, 3-38
floating windows, 3-25, 8-16
removing, 3-25, 8-15
with pointer, 3-38
scrolling text in, 3-14
splitting, 3-27, 8-18
"E D T E m u l a t i o n " Editor style, 3-34, 8-24
"EMACS B a c k w a r d S e a r c h " Editor command
"EMACS" style binding, D-4
"EMACS F o r w a r d S e a r c h " Editor command
"EMACS" style binding, D-4
"EM ACS" Editor style, D-1
activating, D-2
a s major style, D-3
a s minor style, D-3
key binding conflicts, D-1
key bindings, D-3
" E n d o f B u f f e r " Editor command
"EMACS" style binding, D-4
" E n d o f L i n e " Editor command
"EMACS" style binding, D-4
" E n d o f P a r a g r a p h ” Editor command
"EMACS" style binding, D-4
" E n d o f W in d o w ” Editor command
"EMACS" style binding, D-4
Error
listing
file type, 1-9
m essa ges
Debugger, 4-11
warnings, 2-17

(table), 4-18
" E x c h a n g e P o i n t a n d S e l e c t M a r k " Editor
command
"EM ACS" style binding, D-5
" E x e c u t e K e y b o a r d M a c r o " Editor command
"EMACS " style binding, D-6
" E x e c u t e N a m e d C o m m a n d " Editor command
"EMACS" style binding, D-6
E X IT function
exiting LISP, 2-2
exiting LISP in DECwindows, 7-3
" E x i t R e c u r s i v e E d i t " Editor command
"EMACS" style binding, D-6
" E x i t " Editor command, 3-9, 3-26, 8-17

ERROR
Debugger command
description, 4-11
(table), 4-7
Error handler, 1-3
debugging information, 4-1
Error m essa ges
Editor, 3-7,8-10
Errors
Editor protection against file loss,
while using Editor, 3-7, 8-10
/ERROR_ACTION qualifier, 2-11

3-29, 8-18

S e e also *E R R O R -A C T IO N * variable
description, 2-11
modes, 2-10
(table), 2-8
with/INITIALIZE qualifier, 2-12
ESCAPE character
transmitting, 3-34, 8-23
EVAL function, 1-1
invoking from DECwindows, 7-11
EVALUATE
Debugger command
description, 4—9
(table), 4-7
stepper command
description, 4—19

F_________________________
Fast-loading file, 2-6, 2-10
file type, 1-9
File
compiling, 2-6
loading, 2-4
name, 1-8
specification
S e e also Pathnames, Namestrings
components, 1-7 to 1-8
defaults (table), 1-9
format, 1-7
type, 1-8
version number, 1-8
Files
creating
from Editor, 3-8
editing with Editor, 3-3, 8-4
saving edited version, 3-8
Editor checkpoint file, 3-29, 8-18
Editor input completion, 3-7,8-10
Editor protection against loss, 3-29, 8-18
inserting in Editor buffer, 3-18, 8-13
FINISH stepper command
description, 4-20
(table), 4-18
Floating windows, 3-25, 8-16
" F o r w a r d C h a r a c t e r " Editor command
"EMACS" style binding, D—4
" F o r w a r d W o rd " Editor command
"EMACS" style binding, D-4
Function
compiling, 2-5
defining, 2-4
modifying, 2-6
FUNCTION
Debugger command modifier, 4-8
with SET command, 4—11
with SHOW command, 4-11
Function keys
specifying
in " B i n d C o m m a n d " Editor command,
3-30, 8-20
in BIND-COMMAND function, 3-31,8-21
Functions
editing definition, 3-3, 8-4
moving back to LISP, 3-8
evaluating
in Editor,

3 -8

lndex-5

G________________________
Garbage collection
Inspector, 9-5
Garbage collector
suspended systems, 2-18
" G e n e r a l P r o m p t i n g " Editor buffer, E—14
Global
definitions, 4-5
variables, 4-5
GOTO
Debugger command
description, 4—10
(table), 4-7
Graphics interface, 1-5
" G ro w W in d o w " Editor command, 3—27,8—18
"EM ACS" style binding, D-5

H________________________
Help
choosing topics, A-19
DECwindows, 1-7
Editor, 3-6
in the DECwindows environment, 8-8
invoking, A-18
with Help key and MB1, A-19
navigating, A-19
requesting on objects, A-18
screen objects, 7-13
searching, A-20
HELP
Debugger command
description, 4-9
(table), 4-7
stepper command
description, 4-19
(table), 4-18
Help command, A-18
Help facilities
DCL, 1-6
Debugger, 4-9
in DECwindows, 7-12
LISP, 1-7
stepper, 4-19
Help key
using, A-19
HELP or ?
Debugger command
(table), 4-7
HELP stepper command
(table), 4-18
Help window
illustrated, A-18
HERE
Debugger command modifier, 4-8
with BACKTRACE command, 4-12
with SHOW command, 4-11
History window, 9-9 to 9-10

I___________________________________
Icon
expanding to a window,
Icon Box
storing icon in, A-5
Information area, 3-4

Index-6

A-6

/INITIALIZE qualifier
description, 2-12
modes, 2-10
(table), 2-8
with/COMPILE qualifier, 2-10
with/RESUME qualifier, 2-16
with /VERBOSE qualifier, 2-16
Input focus
defined, A-3
giving to a window, A-4, A-7
" I n s e r t B u f f e r " Editor command, 3-18, 3-28,
8-13, 8-18
" I n s e r t F i l e " Editor command, 3-18,8-13
"EMACS" style binding, D-5
Insignificant stack frame, 4-3
IN S P E C T function, 9-3, 9-5
S e e also Inspector
debugging information, 4—1
Inspector
asynchronous mode, 9-4
closing windows, 9-8
default m ode of operation, 9-4
description, 1-3, 9-1
Exit command, 9-5
exiting, 9-5
garbage collection, 9-5
History window, 9-9 to 9-10
inspect windows, 9-8 to 9-9
inspectable data types (table), 9-6
inspecting objects, 9-5 to 9-9
invoking, 9-2
locking windows, 9-8
m odes of operation, 9-4 to 9-5
modifying objects, 9-10 to 9-11
pointers, 9-3, 9—4
removing objects, 9-8 to 9-9
returning values, 9-13 to 9-14
status flag, 9-3, 9-9
synchronous mode, 9-5
unlocking windows, 9—8
updating, 9-12 to 9-13
/INTERACTIVE qualifier, 1-2
description, 2-13
modes, 2-10
(table), 2-8
Interpreter, 1-3
creating programs, 2-4
Interrupt function facility, 1-5

K__________________________
Keyboard macros, 3-35, 8-24
named, 3-35, 8-25
Keypad
numeric
S e e Numeric keypad
Keys
binding to commands, 3-30, 8-19
binding to Editor commands
conflicts in "EM ACS" style, D-1
from LISP interpreter, 3-31,8-20
key binding shadowing, 3-35, 8-24
multiple bindings, E-14
selecting key or sequence, 3-33, 8-23
specifying in " B i n d C o m m a n d ", 3-30,

8-20

Keys
binding to Editor commands (cont'd.)
specifying in BIND-COMMAND function,
3-31,8-20
table of bindings, E-14
table of bindings by command, E-1
within Editor, 3-30, 8-20
function
S e e Function keys
,
text editing, A-17
" K i l l L i n e " Editor command
"EM ACS" style binding, D-5
" K i l l P a r a g r a p h " Editor command
"EM ACS" style binding, D-5
" K i l l R e g i o n " Editor command
"EM ACS" style binding, D-5

L_________________________
Label strip, 3-4
Limit
on Inspect windows, 9-8
" L i n e t o T o p o f W in d o w " Editor command
"EM ACS” style binding, D-4
LISP
command, 1-2, 2-1
qualifier descriptions, 2-7 to 2-18
qualifier m odes (table), 2-9
qualifiers (table), 2-8
exiting, 2-2
invocation from DECwindows, 6-1
invoking, 2—1
invoking with LISP.EXE, 6-2
program, 1-1
compiling, 2-5
creating, 2-4
loading
S e e File
programming language, 1-1
prompt, 2-1
storage allocation, 1-1
S e e also Memory
suspended systems, 2-18
LISP code
indenting with Editor, 3-13
typing a n d fo rm attin g with Editor,

3—12

LISP.EXE
for LISP invocation, 6-2
List box
selecting from, A-12
" L i s t B u f f e r s " Editor command, 3-24,8-14
"EM ACS" style binding, D-5
" L i s t K e y B i n d i n g s " Editor command, 3—5
/LIST qualifier
description, 2-13
modes, 2-10
(table), 2-8
with/COMPILE qualifier, 2-10
Listener
compiling files, 7-7
editing objects, 7-2
editing text, 7-2
entering LISP forms, 7-2
evaluating expressions, 7-1
file selection box, 7-6
help menu, 7-12

Listener (cont'd.)
input region, 7-2
invoking the Editor, 7-8
loading files, 7-6
program interruption, 7-12
saving text, 7-8
selecting objects, 7-2, 7-3
selecting text, 7-2, 7-3
transcript region, 7-2
Listing file, 2-13
LOAD function, 2-5,2-12
Lock menu item
Inspector, 9-8
Logical names, 1-9

M_____________________ ____
Machine-code listing, 2-14
/MACHINE_CODE qualifier, 2-14
modes, 2-10
(table), 2-8
with/COMPILE qualifier, 2-10
Macro
compiling, 2-5
defining, 2-4
modifying, 2-6
Major style, 3-35, 8-24
default, D-3
establishing default, D-3
MB1, MB2, MB3
defined, A-1
Memory
control stack, 4-2
dynamic, 2-14
read-only, 2-14
static, 2-14
/MEMORY qualifier
description, 2-14
modes, 2-10
(table), 2-8
Menu
S e e Option menu; Pop-up menu; Pull-down menu;
Submenu
Minor style, 3-35, 8-24
activating
from Editor, D-3
from LISP interpreter, D-3
activation, 3-35, 8-24
default, D-3
determining most recently activated, E-14
Modifiers
S e e Debugger
Modify menu item
Inspector, 9-10
Mouse
illustrated, A-1
using, A-1

N__________________________
"N ew L I S P L i n e " Editor command, 3-13
" N e x t L i n e " Editor command
"EMACS" style binding, D-4
" N e x t P a r a g r a p h " Editor command
"EM ACS" style binding, D-4
" N e x t S c r e e n " Editor command
"EM ACS" style binding, D-4

lndex-7

/OUTPUT_FILE qualifier (cont’
d.)

" N e x t W in d o w " Editor command
"EM ACS" style binding, D-5
Node, 1-7
/NOINITIALI2E qualifier
modes, 2-10
/NOLIST qualifier
description, 2-13
modes, 2-10
(table), 2-8
with /COMPILE qualifier, 2-10
with /MACHINE_CODE qualifier, 2-14
/NOMACH!NE_CODE qualifier
description, 2-14
modes, 2-10
(table), 2-8
with/COMPILE qualifier, 2-10
/NOOPTIMIZE qualifier
modes, 2-10
/NOOUTPUT_FILE qualifier
description, 2-16
modes, 2-10
(table), 2-9
with/COMPILE qualifier, 2-10
NORMAL
Debugger command modifier, 4-8
with BACKTRACE command, 4-12
/NOVERBOSE qualifier
description, 2-16
modes, 2-10
(table), 2-9
with/COMPILE qualifier, 2-10
/NOWARNINGS qualifier
description, 2-17
modes, 2-10
(table), 2-9
with/COMPILE qualifier, 2-10
Null lexical environment
break loop, 4-5
tracer, 4-26
Numeric keypad
Editor use of, 3-10
illustration, 3-12
Numeric keypad keys
sp ecify in g in BIND-COM M AND function,

with/COMPILE qualifier,
OVER stepper command
description, 4—20
(table), 4-18

P________________________

3—3 1 ,

8-21

o ___________________________
" O p e n L i n e " Editor command
"EM ACS" style binding, D-5
/OPTIMIZE qualifier
description, 2-15
modes, 2-10
(table), 2-8
with /COMPILE qualifier, 2-10
Option button
defined, A-11
using, A-12
Option menu
displaying, A-10
Outermost form
making select region from, 3-17
/OUTPUT_FILE qualifier
description, 2-16
modes, 2—10
(table), 2-9

lndex-8

2-10

" P a g e N e x t W in d o w " Editor command
"EMACS " style binding, D -5
: PARALLEL keyword
IN SPECT function, 9-3, 9-5
Parentheses
matching with Editor, 3-12
using pointer, 3-39
Password, A-3
Paste buffer, 3—17
appending text to, 3 -1 7
Paste menu item
Inspector, 9-11
" P a u s e E d i t o r " Editor command, 3 - 8
effect on buffers, 3 -2 6
"EMACS" style binding, D-6
Pending delete
defined, A-16
Pointer
determining Editor com m ands bound to, 3-39
Pointers
Inspector, 9-4
Pointing
defined, A-2
Pointing device
VWS VAXstation
using in Editor, 3-37
Pop-up menu
displaying, A-9
: P O S T -D E B U G -IF keyword
TRACE macro, 4—27
: P O S T -P R IN T keyword
TRACE macro, 4—27
:P R E -D E B U G -IF keyword
TRACE macro, 4-27
: P R E -P R IN T keyword
TRACE macro, 4—27
Prefix argument, 3-19
entering, 3-19
negative, 3-19
Pressing
defined, A-2
Pretty printer, 1-4
" P r e v i o u s L i n e " Editor command
"EMACS " style binding, D-4
" P r e v i o u s P a r a g r a p h " Editor command
"EMACS" style binding, D-4
" P r e v i o u s S c r e e n " Editor command
"EMACS" style binding, D—4
" P r e v i o u s W in d o w " Editor command
"EMACS" style binding, D-5
: P R IN T keyword
TRACE macro, 4-27
Problem Report dialog box
illustrated, A—4
Prompt
break loop, 4-3
Debugger, 4—6
Editor
completing input, 3-7, 8-9

RETURN (cont'd.)
key

Prompt
Editor (cont’
d.)
displaying alternative choices,
help on, 3-6, 8-8
LISP, 2-1
stepper, 4-14
top-level, 2-1
Pull-down menu
displaying, A-8
Push button
defined, A-11
Push-to-back button, A-7 to A-8
using, A-7

3—7, 8-10

Q________________________
"Qu e r y S e a r c h Repl a c e " Editor command,
3-18
"EMACS" style binding, D-5
QUICK
Debugger command modifier, 4-9
with BACKTRACE command, 4—12
QuickCopy
copying text with, A-16
QUIT
Debugger command, 4-6
description, 4-9
(table), 4-7
stepper command
description, 4-19
exiting stepper, 4-15
(table), 4-18
"Qu o t e d Insert" Editor command
"EMACS" style binding, D-5

R________________________
"Read File" Editor command
"EMACS" style binding, D-6
Read-only memory, 2-14
" R e d i s p l a y Screen" Editor command
"EMACS" style binding, D-6
REDO
Debugger command
description, 4—10
(table), 4—7
"Remove Curr e n t W i n d o w " Editor command
"EMACS" style binding, D-5
Rem ove menu item
Inspector, 9-8 to 9-9
"Remove O t h e r W i n d o w s " Editor command,
3-25, 8-15
"EMACS”style binding, D-5
R esize button
using, A-4
R esize cursor, A-4
/RESUME qualifier, 2-19
description, 2-16
modes, 2-10
(table), 2-9
with/INITIALIZE qualifier, 2-12
with /MEMORY qualifier, 2-14
RETURN
Debugger command
description, 4-10
(table), 4-7

a s a stepper command, 4-20
stepper command
description, 4-20
(table), 4-18
Return key
entering
Debugger command arguments,
Debugger commands, 4-7
stepper commands, 4-17
Returning values
from the Inspector, 9-13 to 9-14
R O O M function
debugging information, 4-1
specifying memory, 2-14

4-7

s____________________
Scale
defined, A-11
using, A-12
Screen
refreshing, in Editor, 3-8
Screen object
defined, A-19
Scroll bar
using, A-13
Scroll region, A-13
"Scroll W i n d o w Down" Editor command
"EMACS" style binding, D—4
"Scroll W i n d o w Up" Editor command
"EMACS" style binding, D-4
Scrolling, A-13
SEARCH
Debugger command
description, 4-10
(table), 4—7
"Select Buffer" Editor command, 3-25,8-15
"EMACS" style binding, D-5
Select region
canceling, 3-17
changing ca se of, 3-17
defining, in Editor, 3-17
from outermost form, 3-17
marking with pointer, 3-38
replacing with paste buffer, 3-17
Selecting
text fields, A-3
S ession
ending, A-21
putting on hold, A-20
starting, A-3
S ession Manager, A-21
SET
Debugger command
description, 4-11
(table), 4-7
SET DISPLAY
command
for defining display, 6-1
"Set Select Mark" Editor command
"EMACS" style binding, D-5
Shift clicking
defined, A-2

lndex-9

SHOW
Debugger command

Stepper commands
requiring arguments

description, 4-11
(table), 4-7
stepper command
description, 4—19
(table), 4-18
" Show T im e " Editor command
"EMACS" style binding, D-6
"Shrink Wind o w " Editor command, 3-27, &-18
"EMACS" style binding, D-5
Shrink-to-icon button, A-5
Significant stack frame, 4-3
Slider
using in scroll bar, A-13
Source file
file type, 1-9
" Split Wind o w " Editor command, 3-27, 8-18
"EMACS" style binding, D-5
Stack frame, 4-3
current, 4-5
insignificant, 4-3
number
Debugger command argument, 4-8
stepper output, 4-15
tracer output, 4-25
significant, 4-3
Stack frames
insignificant
showing from DECwindows, 10-5
"Start N a m e d K e y b o a r d Macro" Editor
command, 3-35, 8-25
Static memory, 2-14
Status flag
Inspector, 9-3, 9-9
STEP
Debugger command
description, 4-10
(table), 4-7
stepper command
description, 4-20
(table), 4-18
STEP macro
debugging information, 4-1
invoking stepper, 4-14
* STEP-ENVIRONMENT* variable, 4-21
* STEP-FORM* variable, 4-20
: S T E P - IF keyword
TRACE macro, 4-27
Stepper, 1-4, 4-14 to 4-24
commands
arguments, 4-18
descriptions, 4-19 to 4-20
(table), 4-18
exiting, 4-15,4-19
from DECwindows, 10-16
invoking, 4-10,4-14,4-27
from the DECwindows interface, 10-15
from the Trace Options Dialog Box, 10-22
output, 4-15
prompt, 4-14
sam ple sessions, 4-23
stepping through a form, 10-16
using, 4—17
from the DECwindows interface, 10-14

D ECwindows display, 10-17
taking no arguments
DECwindows display, 10-17
taking optional arguments
DECwindows display, 10-17
using
from the DECwindows interface,
Stepping arrow, A-13
STOP command, 1-9
Storage allocation, 1-1

lndex-10

10-17

S e e also Memory
String
searching for
with Editor, 3-15
Submenu
displaying, A-9
Subprocess
exiting from, 2-20
S u bprocesses
connecting to, 2-20
creating, 2-19
using, 2-19
"Su p p l y EMA C S P r e f i x " Editor command
"EMACS " style binding, D-6
"Supply P r e f i x A r g u m e n t " Editor command
"EMACS" style binding, D-6
:S U P P R E S S - I F keyword
TRACE macro, 4-27
SUSPEND function
creating suspended systems, 2-18
invoking from DECwindows, 7-9
Suspended system
creating, 2-18
creating in DECwindows, 7-9
file type, 1-9
garbage collector, 2-18
resuming, 2-16,2-19
Symbolic expressions, 1-1
Symbols
editing function definition, 3-3, 8—4
moving back to LISP, 3-8
editing value, 3-3, 8-4
moving back to LISP, 3-8
System
suspended
S e e Suspended system

T_____________________
"ox:
changing c a se of characters, 3-17, 8-13
copying, A-15 to A-16
between windows, A-15 to A-16
copying with Editor, 3-17
cutting and pasting, 3-17
deleting, A-17
deleting with Editor, 3-16
restoring deleted, 3-16
editing, A-14, A-17
inserting with Editor, 3-11
starting new line, 3-12
moving between Editor buffers, 3-28, 8-18
moving between windows, A-16
moving with Editor, 3-16, 3-17

Text (cont’
d.)
selecting, A-15, A-16
substituting in, 3-18
Text entry fields
defined, A-3
moving between, A-12
selecting, A-3
typing in, A-11
TIME macro
debugging information, 4-2
Title bar
moving a window with, A-6
Toggle button
defined, A-11
using, A-12
TOP
Debugger command
description, 4-10
(table), 4-7
Debugger command modifier, 4—9
with BACKTRACE command, 4—12
Top-level loop
prompt, 2-1
variables, 2-2
Trace
Operations menu item, 10-18
TRACE macro
debugging information, 4-2
enabling the tracer, 4-24
options, 4-26
Trace Options Dialog Box, 10-21
* TRACE - CALL * variable, 4-28
* TRACE-OUTPUT* variable
tracer, 4-24
* TRACE-VALUES* variable, 4-28
Trace...
Operations menu item, 10-18
Tracer, 1-4, 4-24 to 4-29
clearing trace output, 10-19
disabling, 4-25
from a command line in DECwindows, 10-20
from the DECwindows interface, 10-20
enabling, 4-24
from the DECwindows interface, 10-18
with the Operations menu, 10-18
options
ad d in g to o u tp u t,

4 —2 7

defining when to trace a function, 4-27
invoking the Debugger, 4-27
invoking the stepper, 4-27
removing information from output, 4-27
output, 4-25
using
with the DECwindows interface, 10-18 to
10-23
Tracer options
specifying
from the DECwindows interface, 10-21
Tracer output
adding information to
with the DECwindows interface, 10-23
modifying
from the DECwindows interface, 10-21
removing information from
with the DECwindows interface, 10-23

"Transpose P r e v i o u s Chara c t e r s " Editor
command
"EMACS" style binding, D-5
"Transpose P r e v i o u s W o r d s " Editor command
"EMACS" style binding, D-5

u _____________________________
UNCOMPILE function
retrieving interpreted definitions, 2-6
Undo menu item
Inspector, 9-11
"Undo P r e v i o u s Yank" Editor command
"EMACS" style binding, D-5
Unlock menu item
Inspector, 9-8
"Unset Select Mark" Editor command
"EMACS" style binding, D-5
U N T R A C E macro
debugging information, 4-2
disabling the tracer, 4-25
invoking from a menu, 10-20
UP
Debugger command
description, 4-11
(table), 4-7
Debugger command modifier, 4-9
SEARCH Debugger command, 4-10
stepper command
description, 4-20
(table), 4-18
"Upcase Word" Editor command
"EMACS" style binding, D-5
Update command
Inspector, 9-12 to 9-13
User name, A-3

V _____________________________________
Variable bindings window
description of, 10-11
making it disappear, 10-11
making it reappear, 10-11
"VAX L I S P " Editor style, 3 -3 4 , 8 -2 4
automatic activation, 3 -3 5 , 8 -2 4
VAXstation
VWS
using Editor, 3-36
using pointing device in Editor, 3-37
VERBOSE
Debugger command modifier, 4-9
with BACKTRACE command, 4-12
/VERBOSE qualifier
description, 2-16
loading files, 2-5
modes, 2-10
(table), 2-9
with /COMPILE qualifier, 2-10
with/INITIALIZE qualifier, 2-12
with /LIST qualifier, 2-13
Version number, 1-8
" V ie w F i l e " Editor command
"EM ACS" style binding, D-6
VMS file specification
S e e File

lndex-11

w__________________
/WARNINGS qualifier
description, 2-17
modes, 2-10
(table), 2-9
with /COMPILE qualifier, 2-10
" W h a t C u r s o r P o s i t i o n " Editor command
"EM ACS" style binding, D-6
WHERE
Debugger command
description, 4-11
(table), 4-7
Window
See also Windows
defined, A-2
directing typing to, A-4
locking in the stacking order, A-7
moving, A-6
moving to front of stack, A-7
releasing from a fixed stacking order, A-8
resizing, A-4
selecting, A-4, A-7
shrinking, A-5
Windows
copying text between, A-15 to A-16

Index-12

Editor
See Editor windows
moving text between, A-16
overlapping, A-7
stacking, A-7
Workstation
locking, A-20
Editor command,
3-8, 3-26, 8-17
"EMACS" style binding, D-6

" W rite C u r r e n t B u f f e r "

" W rite M o d if ie d B u f f e r s " E d i t o r

command, 3-8, 3-26, 8-17
"EM ACS" style binding, D-6
" W r i t e N a m e d F i l e " Editor command,
"EMACS" style binding, D-6

3-8

Y________________________
" Y a n k P r e v i o u s " Editor command
"EMACS" style binding, D-5
" Y a n k R e p l a c e P r e v i o u s " Editor command
"EMACS" style binding, D-5
" Y a n k " Editor command
"EM ACS" style binding, D-5

HOW TO ORDER ADDITIO NAL DOCUM ENTATION
From

Call

W rite

A laska, Haw aii,
or New H am pshire

603-884-6660

D igital E quipm ent Corporation
P.O. Box CS2008
N ash u a NH 03061

R est of U .SA .
a n d Puerto Rico1

800-DIGITAL

1P repaid orders from P u erto Rico, call D igital’s local subsidiary (809—754—7575)

C anada

800-267-6219
(for software
docum entation)

D igital E quipm ent of C anada Ltd.
100 H erzberg Road
K an ata, O ntario, C anada K2K 2A6
A ttn: Direct O rder Desk

613-592-5111
(for hardw are
docum entation)

In tern al orders
(for software
docum entation)

—

Softw are Supply B usiness (SSB)
D igital E quipm ent Corporation
W estm inster MA 01473

In te rn al orders
(for hardw are
docum entation)

DTN: 234-^323
508-351-4323

Publishing & Circulation Services (P&CS)
N R 03-1/W 3
D igital E quipm ent Corporation
N orthboro MA 01532

Reader’
s Comments

VAX LISP/VMS Program Development Guide

AA-MK69A-TE

Your comments and suggestions will help us improve the quality of our future documentation. Please note
th at this form is for comments on documentation only.
I r a t e t h is m a n u a l’s:
Accuracy (product works as described)
C om pleteness (enough inform ation)
Clarity (easy to understand)
O rganization (structure of subject m atter)
F igures (useful)
E xam ples (useful)
Index (ability to find topic)
Page layout (easy to find information)

E xcellent
□
□
□
□
□
□
□
□

Good
□
□
□
□
□
□
□
□

Fair
□
□
□
□
□
□
□
□

What I like best about this manual:
What I like least about this manual:

I found the following errors in this manual:
Page
Description

My additional comments or suggestions for improving this manual:

Please indicate the type of user/reader that you most nearly represent:
□ Administrative Support
□ Computer Operator
□ Educator/Trainer
□ Programmer/Analyst
□ Sales

Name/Title ___
Company ____
Mailing Address

□ Scientist/Engineer
□ Software Support
□ System Manager
□ Other (please specify)

Dept. _____
______ Date
Phone

10/87

Poor
□
□
□
□
□
□
□
□

—

Do N ot T ear — Fold Here and Tape
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

BUSINESS REPLY MAIL
FI R S T C L A S S PERMI T N0.33 MA Y N A R D MASS.
P OS TAGE WILL BE PAID BY A D D R E S S E E

DIGITAL EQ U IPM EN T C O R PO R A TIO N
C O R P O R A T E U SE R PU BLICA TIO N S
PK O 3-1/30D
129 PA R K ER ST R E E T
MAYNARD, MA 0 1 7 5 4 -2 1 9 8

—

Do Not Tear — Fold Here

Cut Along Dotted Line

—