Digital PDFs

AA-Y923D-TE

May 1989

484 pages

Original

212MB

Document:	VAX LISP/VMS Editor Programming Guide
Order Number:	AA-Y923D-TE
Revision:	000
Pages:	484
Original Filename:

OCR Text

VAX LISP/VMS Editor Programming Guide
Order Number: AA-Y923D-TE

This document contains information required by a LISP language programmer to write
programs that extend the VAX LISP Editor.

Revision/Update Information:

This is a revised manual.

Operating System and Version: VMS 5.1
Software Version:

digital equipment corporation
maynard, massachusetts

VAX LISP 3.0

First Printing, May 1986
Revised, August 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 assumes no responsibility for any errors that may appear in
this document.
The software, if any, 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 assumed
for the use or reliability of software or equipment that is not supplied by Digital Equipment
Corporation or its affiliated companies.
© Digital Equipment Corporation 1986, 1989.
All rights reserved.
Printed in U.S.A.
The postpaid Reader’s Comments form at the end of this document requests your critical
evaluation to assist 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

ML-S836
This document was prepared using VAX DOCUMENT, Version 1.1

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

Part I

xix

Guide to Editor Programming

Chapter 1

Editor Overview

1.1

Some Common Editor Extensions...........................................................................
1.1.1
Changing the Frequency of Checkpointing..............................................
1.1.2
Changing the Number of Windows Displayed.........................................
1.1.3
Changing the Default Major S ty le ............................................................
1.1.4
Binding a Command to a Key Sequence................................................
1.1.5
Defining a Command to Change Screen W id th .......................................

1-1
1-2
1-2
1-3
1-3
1-3

1.2

Editor Components ...................................................................................................
1.2.1
Text Operations.........................................................................................
1.2.2
Window and Display Operations...............................................................
1.2.3
Binding C ontexts.......................................................................................
1.2.4
Other Subsystems and Utilities.................................................................

1-4
1—4
1-5
1-5
1-6

1.3

Referencing Editor O bjects.......................................................................................
1.3.1
Functions, Macros, and LISP V ariables...................................................
1.3.2
Editor O bjects............................................................................................
1.3.3
Named and Unnamed Editor Objects .....................................................
1.3.3.1
Referencing Unnamed O b jects ...............................................
1.3.3.2
Referencing Named Objects ..................................................
1.3.3.3
A Note on Efficiency................................................................
1.3.4
Context-Independent and Context-Dependent Editor O bjects.................
1.3.4.1
Referencing Context-Independent O b je c ts .............................
1.3.4.2
Referencing Context-Dependent O b je c ts ...............................
1.3.5
The Editor Package ................................................................................
1.3.5.1
The Package P re fix ................................................................
1.3.5.2
Using USE-PACKAGE ...........................................................
1.3.5.3
Using IN-PACKAGE................................................................

1-6
1-7
1-7
1-7
1—8
1-8
1-9
1-10
1-10
1-10
1-11
1-11
1-11
1-12

Chapter 2

Creating Editor Commands

2.1

Commands and Their Associated Functions..........................................................

2-1

2.2

Using DEFINE-COMMAND.........................................................................................
2.2.1
Specifying the Names................................................................................
2.2.2
Specifying the Argument L is t ....................................................................
2.2.3
Supplying Documentation S trin g s ............................................................

2-1
2-2
2-3
2-3
iii

2.2.4
2.2.5
2.2.6
2.3

Chapter 3

Specifying the A c tio n ................................................................................
Modular Definition of C om m ands............................................................
Commands and C o n te xt...........................................................................

2-4
2-5
2-6

Some Special Command Facilities...........................................................................
2.3.1
Errors .......................................................................................................
2.3.1.1
Getting the User's Attention...................................................
2.3.1.2
Signaling an E r r o r ..................................................................
2.3.1.3
Error Handling.........................................................................
2.3.2
Prompting...................................................................................................
2.3.2.1
Simple Prompting....................................................................
2.3.2.2
General Prompting.................................................................
2.3.3
Command Categories................................................................................

2-7
2-7
2-7
2-8
2-8
2-9
2-10
2-11
2-12

Binding Commands to Keys and Pointer Actions

3.1

Using BIND-COMMAND..............................................................................................

3-2

3.2

The Command to Be B o u n d ....................................................................................

3-2

3.3

The Key or Key Sequence to BeBound...................................................................
3.3.1
Choosing a Key or Sequence .................................................................
3.3.2
Specifying a Character Key or Sequence................................................
3.3.3
Specifying a Function Key, Keypad Key,or S equence............................

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

3.4

The Binding Context...................................................................................................
3.4.1
Specifying the Binding Context.................................................................
3.4.1.1
G lo b a l......................................................................................
3.4.1.2
S ty le ........................................................................................
3.4.1.3
Buffer........................................................................................
3.4.2
Search Order and Shadowing .................................................................

3-5
3-5
3-5
3-6
3-6
3-6

3.5

Using BIND-POINTER-COMMAND ...........................................................................
3.5.1
Specifying a Pointer A c tio n ......................................................................
3.5.1.1
Pointer Cursor M ovem ent.......................................................
3.5.1.2
Pointer Button Transitions in U I S ........................................
3.5.1.3
Pointer Button Transitions inDECwindows..............................
3.5.2
Specifying a Button S ta te ........................................................................
3.5.3
Getting the State of the P o in te r...............................................................
3.5.3.1
Testing Pointer State ............................................................
3.5.3.2
Accessing Pointer-State Inform ation......................................

3-7
3-7
3-8
3-8
3-8
3-9
3-10
3-10
3-11

Chapter 4

Text Operations

4.1

Operations on a Character P o s itio n ..................
4.1.1
Retrieving and Changing a Character
4.1.2
Inserting a C h a racter........................
4.1.3
Inserting a String of Characters . . . .
4.1.4
Deleting C haracters..........................

4-2
4-2
4-2
4-3
4-3

4.2

Operations on a Group of Characters ....................................................................
4.2.1
Inserting a R e g io n ......................................................................................
4.2.2
Copying a R e g io n .....................................................................................
4.2.3
Deleting a R e g io n .....................................................................................
4.2.4
Writing a Region to a F ile ........................................................................

4-4
4—4
4—5
4—5
4-5

4.2.5

Operating on Buffers .................................................................................
4.2.5.1
Deleting the Text in a Buffer .................................................
4.2.5.2
Inserting One Buffer into A n o th e r.........................................
4.2.5.3
Writing a Buffer to a F ile .......................................................
4.2.5.4
Inserting a File into a Buffer ................................................

4-6
4-6
4-6
4-6
4-6

4.3

Moving and Searching Operations...........................................................................
4.3.1
Moving by Character Positions.................................................................
4.3.2
Searching by P a tte rn .................................................................................
4.3.2.1
Making a Search Pattern........................................................
4.3.2.2
Locating a Search Pattern......................................................
4.3.2.3
Replacing a P a ttern...............................................................
4.3.3
Searching by Attribute ..............................................................................
4.3.3.1
Using LOCATE-ATTRIBUTE .................................................
4.3.3.2
Mark and Cursor Behavior.....................................................
4.3.3.3
Using LOCATE-ATTRIBUTE Repeatedly .............................

4-7
4—7
4-8
4-8
4-8
4-9
4-9
4-10
4-11
4-13

4.4

Miscellaneous Text O perations................................................................................
4.4.1
Creating M a rk s .........................................................................................
4.4.1.1
Mark Types and Their B ehavior.............................................
4.4.1.2
Using COPY-MARK................................................................
4.4.1.3
Using WITH-MARK ................................................................
4.4.2
Operating on Lines......................................................................................
4.4.2.1
Retrieving and Altering the Text in a Line.............................
4.4.2.2
Retrieving and Altering a Single Character............................
4.4.2.3
Moving by L in e ......................................................................
4.4.2.4
Testing Relative Line Positions..............................................
4.4.2.5
Retrieving and Testing Mark Positions..................................
4.4.2.6
Example of an Operation on L in e s .......................................

4-13
4—14
4-14
4-15
4-15
4—16
4-16
4-17
4—17
4-17
4-17
4-18

Chapter 5

Window and Display Operations

5.1

Accessing W indows...................................................................................................
5.1.1
The Current Window ................................................................................
5.1.2
The Windows onto a B uffer......................................................................
5.1.3
All the Windows on the Screen ...............................................................
5.1.4
The "Next” W in d o w ..................................................................................

5-2
5-2
5-2
5-3
5-3

5.2

W indow C o n te n t ..........................................................................................................

Window Position in a Buffer......................................................................
The Window P o in t....................................................................................
Moving a Window in the Buffer ...............................................................
5.2.3.1
Scrolling...................................................................................
5.2.3.2
Moving to a SpecifiedPosition...............................................
Wrapping the Lines in a W in d o w ............................................................

5—4
5-4
5-5
5-6
5-6
5-6
5-7

5.3

Window Appearance...................................................................................................
5.3.1
Altering Window Rendition........................................................................
5.3.2
Making Highlight R e g io n s........................................................................
5.3.3
Operations on Window Labels and B o rd e rs ...........................................
5.3.3.1
Borders, Labels, andLabelC o n te n t........................................
5.3.3.2
Label Position........................................................................
5.3.3.3
Label Rendition......................................................................

5-8
5-8
5-9
5-10
5-11
5-12
5-13

5.4

Display Management ................................................................................................

5-13

5.2.1
5.2.2
5.2.3

5.2.4

5.4.1

The Display A re a .......................................................................................
5.4.1.1
Display Area Dimensions .......................................................
5.4.1.2
Reserved Display A re a ............................................................
5.4.1.3
Available Display A r e a ...........................................................
Window Types and Their B ehavior..........................................................
5.4.2.1
Display Behavior by Window T y p e .......................................
5.4.2.2
Window Size and Display Behavior.......................................
5.4.2.3
Window Position and DisplayB e h a vio r.................................
5.4.2.4
Window Borders and DisplayB e h a v io r.................................
Displaying and Removing Windows......................................
5.4.3.1
Using SHOW-WINDOW .........................................................
5.4.3.2
Using PUSH-WINDOW..........................................................
5.4.3.3
Using REMOVE-WINDOW.....................................................

5-14
5-15
5-16
5-17
5-17
5—18
5-18
5—19
5-21
5-21
5-22
5-22
5-23

5.5

Making and Deleting Windows..................................................................................

5-23

5.6

Example of Window and Display Operations ........................................................

5-24

5.4.2

5.4.3

Chapter 6

Operations on Styles

6.1

Activating and Deactivating Styles...........................................................................
6.1.1
Styles in a New B u ffe r..............................................................................
6.1.2
Editor’s Default Styles................................................................................
6.1.2.1
Default Major Style...................................................................
6.1.2.2
Default Minor Style(s)..............................................................
6.1.2.3
Default Minor Style(s) by Type of Buffer.................................
6.1.2.4
Example of Activating Default S tyle s......................................
6.1.3
Styles in an Existing B u ffe r......................................................................
6.1.3.1
A Buffer's Major S tyle..............................................................
6.1.3.2
A Buffer’s Minor S tyle(s).........................................................

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

6.2

Modifying a Style Provided by Digital ....................................................................
6.2.1
Binding Keys and Pointer Actions.............................................................
6.2.1.1
Finding Key B indings..............................................................
6.2.1.2
Review of BIND-COMMAND..................................................
6.2.1.3
Choosing Commands to Bind..................................................
6.2.2
Binding Variables and Setting VariableValues ...........................................
6.2.2.1
Finding Style Variables............................................................
6.2.2.2
Altering Variable Values ........................................................
6.2.2.3
Binding a Variable in a S ty le ................................................
6.2.2.4
Defining New Variables..........................................................
6.2.3
Binding Attributes and Setting AttributeV a lu e s ........................................
6.2.3.1
Finding Style Attributes..........................................................
6.2.3.2
Altering Attribute V a lu e s ........................................................
6.2.3.3
Binding an Attribute in a S ty le ..............................................
6.2.3.4
Defining New Attributes..........................................................

6-7
6-7
6-7
6-8
6-8
6—8
6-9
6-9
6-10
6-10
6-11
6-12
6-12
6-13
6-14

6.3

Creating a New S t y le .................................................................................................
6.3.1
Making a Style Object ..............................................................................
6.3.2
Style Activation and Deactivation Hooks ................................................
6.3.3
Adding Capabilities to the S ty le ...............................................................
6.3.4
Activating the Style ..................................................................................

6-15
6-15
6-15
6-16
6-18

Part II

Concepts in Editor Programming
ATTRIBUTES...............................................................................................................Concepts-3
BUFFERS ....................................................................................................................Concepts-4
CHARACTERS.............................................................................................................Concepts-5
CHECKPOINTING........................................................................................................Concepts-5
COMMANDS................................................................................................................. Concepts-6
C O N T E X T ....................................................................................................................Concepts-7
DEBUGGING SUPPORT.............................................................................................. Concepts-10
EDITOR VARIABLES...................................................................................................Concepts-10
E R R O R S ...................................................................................................................... Concepts-11
H O O K S ........................................................................................................................ Concepts-12
INFORMATION AREA ................................................................................................ Concepts-13
L IN E S ...........................................................................................................................Concepts-14
M A R K S ........................................................................................................................ Concepts-14
NAMED EDITOR OBJECTS .......................................................................................Concepts-16
PROMPTING ...............................................................................................................Concepts-17
REGIONS...................................................................................................................... Concepts-19
RINGS...........................................................................................................................Concepts-20
S T R E A M S ....................................................................................................................Concepts—21
STRING TABLES.......................................................................................................... Concepts-21
STYLES........................................................................................................................ Concepts—22
W INDOW S....................................................................................................................Concepts-25

Part III

Editor Object Descriptions
ACTIVATE MINOR STYLE COM M AND...................................................................... Objects-31
ALTER-WINDOW-HEIGHT FUNCTIO N...................................................................... Objects-32
ANCHORED WINDOW SHOW LIMIT EDITOR VARIABLE........................................ Objects-32
APROPOS COMMAND................................................................................................ Objects-33
APROPOS-STRING-TABLE FUNCTION ....................................................................Objects-34
APROPOS WORD C O M M AN D .................................................................................. Objects-34
ATTENTION FUNCTION................................................................................................Objects-35
ATTRIBUTE-NAME FUNCTION....................................................................................Objects-35
BACKWARD CHARACTER COMMAND........................................................................Objects-36
BACKWARD KILL RING COMMAND ........................................................................ Objects-36
BACKWARD PAGE COMMAND................................................................................... Objects-37
BACKWARD SEARCH COMMAND...............................................................................Objects-37
BACKWARD WORD COM M AND................................................................................. Objects-38
BACKWARD-WORD-COMMAND FUNCTION..............................................................Objects-39
BEGINNING OF BUFFER COMMAND ........................................................................ Objects-39
BEGINNING OF LINE COM M AND............................................................................... Objects-40
BEGINNING OF OUTERMOST FORM COMMAND..................................................... Objects-40
BEGINNING OF PARAGRAPH COM M AND................................................................. Objects-41
BEGINNING OF WINDOW COMMAND........................................................................ Objects-42
BIND-ATTRIBUTE FUNCTION......................................................................................Objecte-^2
BIND COMMAND COMMAND..................................................................................... Objects-^3
BIND-COMMAND FUNCTION..................................................................................... Objects-44
BIND-POINTER-COMMAND FUNCTION.....................................................................Objects-44
BIND-VARIABLE FUNCTION........................................................................................Objects-^5
BREAK-LINE FU N C TIO N.............................................................................................Objects-46
BUFFER-CHECKPOINTED FUNCTION.......................................................................Objects-47
BUFFER-CHECKPOINTED-TIME FUNCTION............................................................. Objects-47
BUFFER CREATION HOOK EDITOR VARIABLE ..................................................... Objects-48
BUFFER-CREATION-TIME FUNCTION.......................................................................Objects-^8

vii

BUFFER DELETION HOOK EDITOR VARIABLE ....................................................... Objects-49
BUFFER-END FUNCTION..............................................................................................Objects-^9
BUFFER ENTRY HOOK EDITOR VARIABLE.............................................................. Objects-50
BUFFER EXIT HOOK EDITOR VARIABLE................................................................... Objects-50
BUFFER-HIGHLIGHT-REG IONS FUNCTION.............................................................. Objects-50
BUFFER-MAJOR-STYLE FUNCTION........................................................................ Objects-51
BUFFER-MINOR-STYLE-ACTIVE FUNCTION............................................................ Objects-51
BUFFER-MINOR-STYLE-LIST FUNCTION................................................................... Objects-52
BUFFER-MODIFIED-P FUNCTION............................................................................... Objects-52
BUFFER-NAME FUNCTION .........................................................................................Objects-53
BUFFER NAME HOOK EDITOR VARIABLE.................................................................Objects-53
BUFFER-OBJECT FUNCTION...................................................................................... Objects-54
BUFFER OBJECT HOOK EDITOR VARIABLE............................................................Objects-54
BUFFER-PERMANENT FU N CTIO N.............................................................................Objects-54
BUFFER-POINT FUNCTION.........................................................................................Objects-55
BUFFER-REGION FUNCTION...................................................................................... Objects-55
BUFFER RIGHT MARGIN EDITOR VARIABLE............................................................ Objects-56
BUFFER SELECT MARK EDITOR VARIABLE............................................................ Objects-56
BUFFER SELECT REGION EDITOR VARIABLE..........................................................Objects-57
BUFFER-START FUNCTION.........................................................................................Objects-57
BUFFER-TYPE FUNCTION........................................................................................... Objects-57
BUFFER-VARIABLES FUNCTION ............................................................................... Objects-58
BUFFER-WINDOWS FUNCTION..................................................................................Objects-58
BUFFER-WRITABLE FUNCTION..................................................................................Objects-59
BUFFER-WRITTEN-TIME FUNCTION.......................................................................... Objects-59
BUFFERP FUNCTIO N.................................................................................................. Objects-60
CANCEL-CHARACTER FU N CTIO N.............................................................................Objects-60
CAPITALIZE REGION COM MAND............................................................................. Objects-61
CAPITALIZE WORD C O M M AN D ............................................................................... Objects-61
CATEGORY-COMMANDS FUNCTION...........................................................................Objects-62
CENTER-WINDOW FUNCTION.................................................................................... Objects-62
CHARACTER-ATTRIBUTE FUNCTION........................................................................ Objects-63
CHARACTER ATTRIBUTE HOOK EDITOR VARIABLE ............................................. Objects-63
CHARACTER-OFFSET FUNCTION ............................................................................. Objects-64
CHECKPOINT-BUFFER FUNCTION............................................................................. Objects-64
CHECKPOINT-FREQUENCY FUNCTION......................................................................Objects-65
CLEAR-INFORMATION-AREA FUNCTION................................................................... Objects-65
CLOSE OUTERMOST FORM COMMAND................................................................... Objects-66
COMMAND-CATEGORIES FUNCTION........................................................................ Objects-66
COMMAND-NAME FUNCTION .................................................................................... Objects-67
COMPLETE-STRING FUNCTION..................................................................................Objects-67
COPY FROM POINTER COMMAND............................................................................. Objects-68
COPY-MARK FUN C TIO N ..............................................................................................Objects-69
COPY-REGION FUNCTION........................................................................................... Objects-69
COPY TO POINTER COMMAND..................................................................................Objects-70
COUNT-REGION FUNCTION.........................................................................................Objects-70
CURRENT-BUFFER FUNCTION ..................................................................................Objects-71
CURRENT-BUFFER-POINT FUNCTION ......................................................................Objects-71
XURRENT-COMMAND-FUNCTION* VARIABLE..........................................................Objects-72
CURRENT-WINDOW FUNCTION..................................................................................Objects-72
DEACTIVATE MINOR STYLE COMMAND................................................................... Objects-72
DEFAULT BUFFER VARIABLES EDITOR VARIABLE...................................................Objects-73
DEFAULT FILETYPE MINOR STYLES EDITOR VARIABLE ...................................... Objects-73
DEFAULT LISP OBJECT MINOR STYLES EDITOR VARIABLE................................. Objects-74
DEFAULT MAJOR STYLE EDITOR VARIABLE............................................................ Objects-74
DEFAULT MINOR STYLES EDITOR VARIABLE..........................................................Objects-75
DEFAULT SEARCH CASE EDITOR VARIABLE ..........................................................Objects-75

DEFAULT WINDOW LABEL EDITOR VARIABLE....................................................... Objects-75
DEFAULT WINDOW LABEL EDGE EDITOR VARIABLE........................................... Objects-76
DEFAULT WINDOW LABEL OFFSET EDITOR VARIABLE...................................... Objects-76
DEFAULT WINDOW LABEL RENDITION EDITOR VARIABLE..................................Objects-76
DEFAULT WINDOW LINES WRAP EDITOR VARIABLE........................................... Objects-77
DEFAULT WINDOW RENDITION EDITOR VARIABLE............ ................................. Objects-77
DEFAULT WINDOW TRUNCATE CHAR EDITOR VAR IA B LE ..................................Objects-78
DEFAULT WINDOW TYPE EDITOR VARIABLE....................................................... Objects-78
DEFAULT WINDOW WIDTH EDITOR VAR IABLE..................................................... Objects-78
DEFAULT WINDOW WRAP CHAR EDITOR VARIABLE........................................... Objects-79
DEFINE-ATTRIBUTE M A C R O .................................................................................... Objects-79
DEFINE-COMMAND MACRO .................................................................................... Objects-80
DEFINE-EDITOR-VARIABLE M AC R O ........................................................................ Objects-81
DEFINE-KEYBOARD-MACRO FUNCTION................................................................. Objects-82
DELETE-AND-SAVE-REGION FUNCTION................................................................. Objects-82
DELETE-BUFFER FUNCTION.................................................................................... Objects-83
DELETE-CHARACTERS FUNCTION...........................................................................Objects-83
DELETE CURRENT BUFFER COMMAND................................................................. Objects-84
DELETE LINE C O M M AN D ......................................................................................... Objects-84
DELETE-MARK FUNCTION......................................................................................... Objects-85
DELETE NAMED BUFFER COMMAND......................................................................Objects-86
DELETE NEXT CHARACTER COMMAND................................................................. Objects-86
DELETE NEXT WORD C O M M AN D ............................................................................ Objects-87
DELETE PREVIOUS CHARACTER COMMAND....................................................... Objects-88
DELETE PREVIOUS WORD COMMAND..................................................................... Objects-88
DELETE-REGION FUNCTION...................................................................................... Objects-89
DELETE WHITESPACE COMMAND............................................................................ Objects-89
DELETE-WINDOW FU NCTIO N................................................................................... Objects-90
DELETE WORD COMMAND........................................................................................ Objects-90
DESCRIBE C O M M A N D ............................................................................................... Objects-91
DESCRIBE-OBJECT-COMMAND FUNCTION..............................................................Objects-92
DESCRIBE WORD COMMAND................................................................................... Objects-92
DESCRIBE WORD AT POINTER COMMAND ..........................................................Objects-92
DOWNCASE REGION COMMAND.............................................................................. Objects-93
DOWNCASE WORD COMMAND.................................................................................Objects-94
ED COMMAND..............................................................................................................Objects-94
ED FUNCTIO N..............................................................................................................Objects-95
EDIT FILE COMMAND..................................................................................................Objects-96
EDIT-LISP-OBJECT-COMMAND FUNCTION ............................................................ Objects-97
*EDITOR-ATTRIBUTE-NAMES* VAR IA B LE ................................................................Objects-97
‘ EDITOR-BUFFER-NAMES* VARIABLE....................................................................... Objects-97
‘ EDITOR-COMMAND-NAMES* VARIABLE.................................................................. Objects-97
‘ EDITOR-DEFAULT-BUFFER* VARIABLE ................................................................. Objects-97
EDITOR ENTRY HOOK EDITOR VAR IABLE............................................................. Objects-98
EDITOR-ERROR FUNCTION........................................................................................Objects-98
EDITOR-ERROR-WITH-HELP FUNCTION.................................................................. Objects-99
EDITOR EXIT HOOK EDITOR VARIABLE.................................................................. Objects-99
EDITOR-HELP-BUFFER BUFFER ............................................................................. Objects-100
EDITOR INITIALIZATION HOOK EDITOR VARIABLE ..............................................Objects-100
‘ EDITOR-KEYBOARD-MACRO-NAMES* VARIABLE................................................. Objects-100
EDITOR-LISTEN FUNCTION........................................................................................Objects-101
EDITOR PAUSE HOOK EDITOR VARIABLE ............................................................ Objects-101
EDITOR-PROMPTING-BUFFER B U F F E R ..................................................................Objects-101
EDITOR-READ-CHAR FUNCTION..............................................................................Objects-102
EDITOR-READ-CHAR-NO-HANG FUNCTION............................................................. Objects-102
EDITOR RECURSIVE ENTRY HOOK EDITOR VARIABLE....................................... Objects-102
‘ EDITOR-RETAIN-SCREEN-STATE* VARIABLE........................................................ Objects-103
ix

*EDITOR-STYLE-NAMES* VARIABLE...........................................................................Objects-103
EDITOR-UNREAD-CHAR FUNCTION...........................................................................Objects-103
*EDITOR-VARIABLE-NAMES* VA R IA B LE ................................................................... Objects-104
’ EDITOR-WORKSTATION-BANNER* VARIABLE..........................................................Objects-104
EDT APPEND C O M M A N D ............................................................................................Objects-104
EDT BACK TO START OF LINE COMMAND...............................................................Objects-105
EDT BEGINNING OF LINE COMMAND........................................................................ Objects-105
EDT CHANGE CASE COMMAND ................................................................................Objects-106
EDT CUT COMMAND ...................................................................................................Objects-107
EDT DELETE CHARACTER COMMAND...................................................................... Objects-107
EDT DELETE LINE COMMAND.................................................................................... Objects-108
EDT DELETE PREVIOUS CHARACTER COMMAND ................................................ Objects-108
EDT DELETE PREVIOUS LINE COMMAND ...............................................................Objects-109
EDT DELETE PREVIOUS WORD COMMAND............................................................ Objects-110
EDT DELETE TO END OF LINE COMMAND...............................................................Objects-110
EDT DELETE WORD C O M M A N D ............................................................................. Objects-111
EDT DELETED CHARACTER EDITOR VARIABLE...................................................Objects-111
EDT DELETED LINE EDITOR VARIABLE................................................................... Objects-112
EDT DELETED WORD EDITOR VARIABLE................................................................. Objects-112
EDT DESELECT COMMAND......................................................................................... Objects-112
EDT DIRECTION MODE EDITOR VARIABLE...............................................................Objects-113
EDT EMULATION S T Y L E .............................................................................................. Objects-113
EDT END OF LINE COMMAND.................................................................................... Objects-113
EDT MOVE CHARACTER CO M M AND........................................................................ Objects-114
EDT MOVE PAGE COMMAND .................................................................................... Objects-115
EDT MOVE WORD COMMAND.................................................................................... Objects-115
EDT PASTE COMMAND................................................................................................ Objects-116
EDT PASTE AT POINTER COM M AND........................................................................ Objects-116
EDT PASTE BUFFER EDITOR VARIABLE....................................................................Objects-117
EDT QUERY SEARCH COMMAND ............................................................................. Objects-117
EDT REPLACE COMMAND ......................................................................................... Objects-118
EDT SCROLL WINDOW C O M M A N D ...........................................................................Objects-119
EDT SEARCH AGAIN COM MAND................................................................................Objects-119
EDT SELECT COMMAND.............................................................................................. Objects-120
EDT SET DIRECTION BACKWARD COMMAND.......................................................... Objects-120
EDT SET DIRECTION FORWARD COMMAND............................................................ Objects-121
EDT SPECIAL INSERT CO M M AND............................................................................. Objects-121
EDT SUBSTITUTE CO M M AND.................................................................................... Objects-122
EDT UNDELETE CHARACTER COMMAND................................................................. Objects-122
EDT UNDELETE LINE COMMAND................................................................................Objects-123
EDT UNDELETE WORD C O M M AND...........................................................................Objects-124
EMACS S T Y LE ...............................................................................................................Objects-124
EMACS BACKWARD SEARCH COMMAND................................................................. Objects-125
EMACS FORWARD SEARCH COMMAND....................................................................Objects-125
EMPTY-BUFFER-P FUN C TIO N .................................................................................... Objects-126
EMPTY-LINE-P FUNCTION............................................................................................Objects-127
EMPTY-REGION-P FUN C TIO N.................................................................................... Objects-127
END KEYBOARD MACRO COMMAND........................................................................ Objects-128
END-KEYBOARD-MACRO FUNCTION........................................................................ Objects-128
END OF BUFFER COMMAND.......................................................................................Objects-129
END OF LINE COMMAND ............................................................................................Objects-129
END-OF-LINE-P FUNCTION......................................................................................... Objects-130
END OF OUTERMOST FORM COM M AND................................................................. Objects-130
END OF PARAGRAPH COMMAND ............................................................................. Objects-131
END OF WINDOW CO M M AND.................................................................................... Objects-131
ENQUEUE-EDITOR-COMMAND FU NCTIO N...............................................................Objects-132
EVALUATE LISP REGION CO M M AND ........................................................................ Objects-132

EXCHANGE POINT AND SELECT MARK COMMAND ..............................................Objects-133
EXECUTE KEYBOARD MACRO COMMAND............................................................ Objects-134
EXECUTE NAMED COMMAND COMMAND................................................................. Objects-134
EXIT COMMAND.............................................................................................................Objects-135
EXIT-EDITOR-COMMAND FUNCTION ........................................................................ Objects-135
EXIT RECURSIVE EDIT COMMAND ........................................................................... Objects-135
FIND-AMBIGUOUS FUNCTION.................................................................................... Objects-136
FIND-ATTRIBUTE FUNCTION.......................................................................................Objects-137
FIND-BUFFER FUN C TIO N............................................................................................Objects-137
FIND-COMMAND FU N CTIO N.....................................................................................Objects-138
FIND-STYLE FUNCTION .............................................................................................. Objects-138
FIND-VARIABLE FUNCTION......................................................................................... Objects-139
FIRST-LINE-P FUNCTION.............................................................................................. Objects-139
FORWARD CHARACTER COMMAND ...................................................................... Objects-140
FORWARD KILL RING COMMAND ...........................................................................Objects-140
FORWARD PAGE COMMAND.....................................................................................Objects-141
FORWARD SEARCH COMMAND................................................................................Objects-141
FORWARD WORD CO M M AND.................................................................................. Objects-142
FORWARD-WORD-COMMAND FUNCTION...............................................................Objects-143
GENERAL PROMPTING B U F F E R ............................................................................. Objects-143
GET-BOUND-COMMAND-FUNCTION FUNCTION....................................................... Objects-144
GET-POINTER-STATE FUNCTION............................................................................. Objects-144
GET-STRING-TABLE-VALUE FUNCTION....................................................................Objects-145
GROW WINDOW COM MAND.....................................................................................Objects-146
HELP B U FFE R .............................................................................................................Objects-147
HELP CO M M AND........................................................................................................Objects-147
HELP ON EDITOR ERROR COM M AND....................................................................Objects-148
HELP TEXT EDITOR VARIABLE................................................................................Objects-148
HIGHLIGHT-REGION-P FUNCTION........................................................................... Objects-149
ILLEGAL OPERATION COMMAND..............................................................................Objects-149
INDENT LISP LINE COMMAND...................................................................................Objects-150
INDENT LISP REGION C O M M AND........................................................................... Objects-150
INDENT OUTERMOST FORM COMMAND ...............................................................Objects-151
INFORMATION-AREA-HEIGHT FUNCTION............................................................... Objects-151
‘ INFORMATION-AREA-OUTPUT-STREAM* VARIABLE............................................Objects-152
INITIALIZE-EDITOR FUNCTION...................................................................................Objects-152
INSERT BUFFER COMMAND..................................................................................... Objects-152
INSERT-CHARACTER FUNCTION..............................................................................Objects-153
INSERT CLOSE PAREN AND MATCH COMMAND................................................... Objects-154
INSERT FILE COMMAND............................................................................................ Objects-154
INSERT-FILE-AT-MARK FUNCTION........................................................................... Objects-155
INSERT-REGION FUNCTION .....................................................................................Objects-156
INSERT-STRING FUNCTION....................................................................................... Objects-156
INVOKE-HOOK FUNCTION..........................................................................................Objects-157
KILL ENCLOSING LIST COMMAND........................................................................... Objects-157
KILL LIST C O M M AN D .................................................................................................Objects-158
KILL NEXT FORM COMMAND .................................................................................. Objects-159
KILL PARAGRAPH CO M M AND.................................................................................. Objects-159
KILL PREVIOUS FORM COMMAND...........................................................................Objects-160
KILL REGION COMMAND ......................................................................................... Objects-161
KILL REST OF LIST COMMAND................................................................................Objects-162
‘ LAST-CHARACTER-TYPED* VARIABLE................................................................... Objects-162
LAST-LINE-P FUNCTION............................................................................................Objects-162
LAST SEARCH DIRECTION EDITOR VARIABLE..................................................... Objects-163
LAST SEARCH PATTERN EDITOR VARIABLE..........................................................Objects-163
LAST SEARCH STRING EDITOR VARIABLE............................................................ Objects-164
LINE-BUFFER FUNCTION ......................................................................................... Objects-164
xi

LINE-CHARACTER FUNCTION..................................................................................Objects-164
LINE-END FUNCTIO N................................................................................................ Objects-165
LINE-LENGTH FU N C TIO N ......................................................................................... Objects-165
LINE-NEXT FUNCTION ..............................................................................................Objects-166
LINE-OFFSET FUNCTION ......................................................................................... Objects-166
LINE-PREVIOUS FUNCTION.......................................................................................Objects-167
LINE-START FUNCTION..............................................................................................Objects-167
LINE-STRING FUNCTION........................................................................................... Objects-168
LINE-TO-REGION FUNCTION.................................................................................... Objects-168
LINE TO TOP OF WINDOW COMMAND................................................................... Objects-169
UNEP FUNCTION....................................................................................................... Objects-169
LINES-RELATED-P FUNCTION..................................................................................Objects-170
LINE/= FUNCTION........................................................................................................Objects-170
LINE< FUNCTION....................................................................................................... Objects-171
LINE<= FUNCTIO N..................................................................................................... Objects-171
LINE= FUNCTION....................................................................................................... Objects-172
LINE> FUNCTION........................................................................................................Objects-172
LINE>= FUNCTIO N..................................................................................................... Objects-173
LISP COMMENT COLUMN EDITOR VARIABLE....................................................... Objects-173
LISP EVALUATION RESULT EDITOR VARIABLE..................................................... Objects-174
LISP SYNTAX ATTRIBUTE......................................................................................... Objects-174
LIST BUFFERS C O M M A N D .......................................................................................Objects-175
LIST KEY BINDINGS COMMAND .............................................................................Objects-176
LOCATE-ATTRIBUTE FUNCTION............................................................................... Objects-177
LOCATE-PATTERN FUNCTION..................................................................................Objects-178
MAJOR STYLE ACTIVATION HOOK EDITOR VARIABLE.........................................Objects-179
MAKE-BUFFER FUNCTION .......................................................................................Objects-179
MAKE-COMMAND FUNCTION.................................................................................... Objects-180
MAKE-EDITOR-STREAM-FROM-REGION FUNCTION..............................................Objects-181
MAKE-EDITOR-STREAM-TO-MARK FUNCTION....................................................... Objects-181
MAKE-EMPTY-REGION FUNCTION...........................................................................Objects-182
MAKE-HIGHLIGHT-REGION FUNCTION................................................................... Objects-182
MAKE-MARK FUNCTION........................................................................................... Objects-183
MAKE-REGION FUNCTION......................................................................................... Objects-184
MAKE-RING FUNCTION..............................................................................................Objects-184
MAKE-SEARCH-PATTERN FUNCTION......................................................................Objects-185
MAKE-STRING-TABLE FUNCTION............................................................................. Objects-185
MAKE-STYLE M ACRO ................................................................................................ Objects-186
MAKE-WINDOW FUNCTION.......................................................................................Objects-186
MAP-BINDINGS FUN C TIO N.......................................................................................Objects-188
MAP-BUFFERS FUNCTION .......................................................................................Objects-188
MAP-STRINGS FUNCTION......................................................................................... Objects-189
MARK-CHARPOS FUNCTION.................................................................................... Objects-189
MARK-COLUMN FUNCTION.......................................................................................Objects-190
MARK-LINE FUNCTION..............................................................................................Objects-190
MARK-TYPE FUNCTION ........................................................................................... Objects-191
MARK-VISIBLE-P FUN C TIO N.................................................................................... Objects-191
MARK-WINDOW-POSITION FUNCTION................................................................... Objects-192
MARKP FUNCTION..................................................................................................... Objects-192
MARK/= FUNCTION..................................................................................................... Objects-193
MARK< FUNCTION..................................................................................................... Objects-193
MARK<= FUNCTION...................................................................................................Objects-194
MARK= FUNCTION..................................................................................................... Objects-194
MARK> FUNCTION..................................................................................................... Objects-195
MARK>= FUNCTION...................................................................................................Objects-195
MAYBE RESET SELECT AT POINTER COMMAND ................................................ Objects-196
MINOR STYLE ACTIVATION HOOK EDITOR VARIABLE......................................... Objects-196

MOVE-MARK FUNCTION..............................................................................................Objects-197
MOVE-MARK-AFTER FUNCTION..................................................................................Objects-197
MOVE-MARK-BEFORE FU NCTIO N............................................................................. Objects-198
MOVE-MARK-TO-POSITION FUNCTION......................................................................Objects-198
MOVE POINT AND SELECT REGION COMMAND.....................................................Objects-199
MOVE POINT TO POINTER COMMAND......................................................................Objects-199
MOVE TO LISP COMMENT COMMAND......................................................................Objects-200
MOVE-WINDOW FUNCTION.........................................................................................Objects-201
NEW LINE COMMAND................................................................................................ Objects-201
NEW LISP LINE COMMAND.......................................................................................Objects-202
NEXT-CHARACTER FUNCTION ..................................................................................Objects-202
NEXT FORM COM MAND..............................................................................................Objects-203
NEXT LINE CO M M AND................................................................................................ Objects-204
NEXT-LISP-FORM FUNCTION...................................................................................... Objects-204
NEXT PARAGRAPH COM M AND..................................................................................Objects-205
NEXT SCREEN CO M M AND.......................................................................................Object&-206
NEXT WINDOW COMMAND.......................................................................................Objects-206
NEXT-WINDOW FUNCTION.........................................................................................Objects-207
OPEN LINE COMMAND..............................................................................................Objects-208
PAGE DELIMITER ATTRIBUTE..................................................................................Objects-208
PAGE NEXT WINDOW C O M M AN D ...........................................................................Objects-209
PAGE-OFFSET FUNCTION......................................................................................... Objects-209
PAGE PREVIOUS WINDOW COMMAND................................................................... Objects-210
PAUSE EDITOR COMMAND.......................................................................................Objects-210
POINTER-STATE-ACTION FU NCTIO N......................................................................Objects-211
POINTER-STATE-BUTTONS FUNCTION................................................................... Objects-212
POINTER-STATE-P FUNCTION..................................................................................Objects-212
POINTER-STATE-TEXT-POSITION FUNCTION ....................................................... Objects-213
POINTER-STATE-WINDOW-POSITION FUNCTION...................................................Objects-213
POSITION-WINDOW-TO-MARK FUNCTION...............................................................Objects-214
PREFIX-ARGUMENT FUNCTION............................................................................... Objects-215
PREVIOUS-CHARACTER FUNCTION........................................................................ Objects-215
‘ PREVIOUS-COMMAND-FUNCTION* VARIABLE..................................................... Objects-216
PREVIOUS FORM C O M M AN D ..................................................................................Objects-216
PREVIOUS LINE COMMAND .................................................................................... Objects-217
PREVIOUS-LISP-FORM FUNCTION........................................................................... Objects-218
PREVIOUS PARAGRAPH COMMAND ......................................................................Objects-218
PREVIOUS SCREEN COMMAND ............................................................................. Objects-219
PREVIOUS WINDOW COM M AND............................................................................. Objects-220
PRINT REPRESENTATION ATTRIBUTE....................................................................Objects-220
PROMPT ALTERNATIVES EDITOR VARIABLE.......................................................... Objects-221
PROMPT ALTERNATIVES ARGUMENTS EDITOR VARIABLE ............................... Objects-221
PROMPT COMPLETE STRING COMMAND...............................................................Objects-221
PROMPT COMPLETION EDITOR VARIABLE............................................................ Objects-222
PROMPT COMPLETION ARGUMENTS EDITOR VARIABLE ..................................Objects-222
PROMPT DEFAULT EDITOR VARIABLE......................................................................Objects-223
PROMPT ERROR MESSAGE EDITOR VARIABLE.....................................................Objects-223
PROMPT ERROR MESSAGE ARGUMENTS EDITOR VARIABLE.......................... Objects-223
PROMPT-FOR-INPUT FUNCTION............................................................................. Objects-224
PROMPT HELP CO M M AND......................................................................................... Objects-226
PROMPT HELP EDITOR VARIABLE.............................................................................Objects-227
PROMPT HELP ARGUMENTS EDITOR VARIABLE ................................................ Objects-227
PROMPT HELP CALLED EDITOR VARIABLE............................................................ Objects-227
PROMPT READ AND VALIDATE COMMAND.............................................................. Objects-228
PROMPT RENDITION COMPLEMENT EDITOR VARIABLE...................................... Objects-228
PROMPT RENDITION SET EDITOR VARIABLE..........................................................Objects-229
PROMPT REQUIRED EDITOR VARIABLE................................................................... Objects-229
xiii

PROMPT SCROLL HELP WINDOW COMMAND ....................................................... Objects-229
PROMPT SHOW ALTERNATIVES COMMAND............................................................ Objects-230
PROMPT START EDITOR VARIABLE...........................................................................Objects-231
PROMPT VALIDATION EDITOR VARIABLE................................................................. Objects-231
PUSH-WINDOW FUNCTION......................................................................................... Objects-231
QUERY SEARCH REPLACE COMMAND ................................................................... Objects-232
QUOTED INSERT COMMAND.......................................................................................Objects-234
READ FILE CO M M AN D ................................................................................................ Objects-234
REDISPLAY SCREEN COMMAND............................................................................... Objects-235
REDISPLAY-SCREEN FU N C TIO N ............................................................................... Objects-235
REGION-END FUNCTION..............................................................................................Objects-236
REGION-READ-POINT FUNCTION............................................................................... Objects-236
REGION-START FUNCTION......................................................................................... Objects-237
REGION-TO-STRING FUNCTION..................................................................................Objects-237
REGIONP FU N C TIO N ...................................................................................................Objects-238
REMOVE CURRENT WINDOW COMMAND................................................................. Objects-238
REMOVE-HIGHLIGHT-REGION FUNCTION................................................................. Objects-239
REMOVE OTHER WINDOWS COMMAND................................................................... Objects-239
REMOVE-STRING-TABLE-ENTRY FUNCTION............................................................ Objects-240
REMOVE-WINDOW FUNCTION.................................................................................... Objects-240
REPLACE-PATTERN FUNCTION.................................................................................. Objects-241
RETURN-FROM-EDITOR M A C R O ................................................................................Objects-242
REVERSE-INVOKE-HOOK FUNCTION........................................................................ Objects-242
RING-LENGTH FUNCTION............................................................................................Objects-243
RING-POP FUNCTION...................................................................................................Objects-243
RING-PUSH FUNCTION................................................................................................ Objects-244
RING-REF FUNCTION...................................................................................................Objects-244
RING-ROTATE FUNCTION............................................................................................Objects-245
RINGP FUNCTION ........................................................................................................Objects-245
SAME-LINE-P FUNCTION.............................................................................................. Objects-246
SCREEN-HEIGHT FUNCTION.......................................................................................Objects-246
SCREEN MODIFICATION HOOK EDITOR VARIABLE................................................ Objects-247
SCREEN-WIDTH FUNCTION......................................................................................... Objects-247
SCROLL-WINDOW FUNCTION.................................................................................... Objects-248
SCROLL WINDOW DOWN COMMAND........................................................................ Objects-248
SCROLL WINDOW UP C O M M AN D ............................................................................. Objects-249
SECONDARY SELECT REGION COMMAND...............................................................Objects-250
SELECT BUFFER COMMAND.......................................................................................Objects-250
SELECT ENCLOSING FORM AT POINTER C O M M AN D ........................................... Objects-251
SELECT OUTERMOST FORM COM M AND................................................................. Objects-252
SELECT REGION RENDITION COMPLEMENT EDITOR VAR IABLE........................ Objects-252
SELECT REGION RENDITION SET EDITOR VARIABLE........................................... Objects-253
SELF INSERT C O M M AN D............................................................................................Objects-253
SET DECWINDOWS POINTER SYNTAX CO M M AND................................................ Objects-254
SET SCREEN HEIGHT COMMAND............................................................................. Objects-254
SET SCREEN WIDTH COMMAND................................................................................Objects-255
SET SELECT MARK COMMAND.................................................................................. Objects-256
SET UIS POINTER SYNTAX COMMAND ................................................................... Objects-257
SHOW-MARK FUNCTION.............................................................................................. Objects-258
SHOW TIME C O M M A N D .............................................................................................. Objects-258
SHOW-WINDOW FUNCTION .......................................................................................Objects-259
SHRINK WINDOW C O M M AND.................................................................................... Objects-260
SIMPLE-PROMPT-FOR-INPUT FUNCTIO N................................................................. Objects-260
SPLIT WINDOW COMMAND......................................................................................... Objects-261
START KEYBOARD MACRO C O M M AN D ................................................................... Objects-262
START NAMED KEYBOARD MACRO C O M M AN D .....................................................Objects-262
START-OF-LINE-P FUNCTION.......................................................................................Objects-263

STRING-TABLE-P FUNCTION...................................................................................... Objects-263
STRING-TO-REGION FUNCTION..................................................................................Objects-264
STYLE-NAME FUNCTION..............................................................................................Objects-264
STYLE-VARIABLES FUNCTION.................................................................................... Objects-265
STYLEP FUNCTION ..................................................................................................... Objects-265
SUPPLY EMACS PREFIX C O M M A N D ........................................................................ Objects-266
SUPPLY PREFIX ARGUMENT COM M AND................................................................. Objects-266
SWITCH WINDOW HOOK EDITOR VARIABLE ..........................................................Objects-267
TARGET COLUMN EDITOR VARIABLE ......................................................................Objects-267
TEXT OVERSTRIKE MODE EDITOR VARIABLE ....................................................... Objects-268
TRANSPOSE PREVIOUS CHARACTERS COMMAND................................................ Objects-268
TRANSPOSE PREVIOUS WORDS CO M M AND..........................................................Objects-269
UNBIND-ATTRIBUTE FUNCTION..................................................................................Objects-269
UNBIND-COMMAND FUNCTION..................................................................................Objects-270
UNBIND-POINTER-COMMAND FUNCTION................................................................. Objects-270
UNBIND-VARIABLE FUNCTION.................................................................................... Objects-271
UNDO PREVIOUS YANK COMMAND...........................................................................Objects-271
UNSET SELECT MARK COMMAND............................................................................. Objects-272
UPCASE REGION COMMAND .................................................................................... Objects-273
UPCASE WORD COMMAND......................................................................................... Objects-273
UPDATE-DISPLAY FUNCTION .................................................................................... Objects-274
UPDATE-WINDOW-LABEL FUNCTION........................................................................ Objects-274
VARIABLE-BOUNDP FUNCTION..................................................................................Objects-275
VARIABLE-FBOUNDP FUNCTION............................................................................... Objects-275
VARIABLE-FUNCTION FUNCTION...............................................................
Objects-276
VARIABLE-NAME FUNCTION.......................................................................................Objects-276
VARIABLE-VALUE FUNCTION.......................................................................................Objects-277
VAX LISP STYLE .......................................................................................................... Objects-277
VIEW FILE COMMAND ................................................................................................ Objects-278
VISIBLE-WINDOWS FUNCTION ..................................................................................Objects-279
WHAT CURSOR POSITION COMMAND......................................................................Objects-279
WHITESPACE ATTRIBUTE........................................................................................... Objects-280
WHITESPACE-AFTER-P FUNCTION ...........................................................................Objects-280
WHITESPACE-BEFORE-P FU NCTIO N........................................................................ Objects-281
WHITESPACE-BETWEEN-P FUNCTION......................................................................Objects-281
WHITESPACE-LINE-P FUNCTION................................................................................Objects-282
WINDOW-BUFFER FUNCTION.................................................................................... Objects-282
WINDOW BUFFER HOOK EDITOR VARIABLE ..........................................................Objects-283
WINDOW CREATION HOOK EDITOR VARIABLE....................................................... Objects-283
WINDOW-CREATION-TIME FUNCTION ...................................................................... Objects-283
WINDOW DELETION HOOK EDITOR VARIABLE....................................................... Objects-284
WINDOW-DISPLAY-COLUMN FUNCTION................................................................... Objects-284
WINDOW-DISPLAY-END FUNCTION ...........................................................................Objects-285
WINDOW-DISPLAY-ROW FUNCTION...........................................................................Objects-285
WINDOW-DISPLAY-START FUNCTION........................................................................ Objects-286
WINDOW-HEIGHT FUNCTION .................................................................................... Objects-286
WINDOW-LABEL FUNCTION .......................................................................................Objects-287
WINDOW-LABEL-EDGE FUNCTION............................................................................. Objects-287
WINDOW-LABEL-OFFSET FUNCTION........................................................................ Objects-288
WINDOW-LABEL-RENDITION FUNCTION................................................................... Objects-288
WINDOW-LINES-WRAP-P FUNCTION ........................................................................ Objects-289
WINDOW MODIFICATION HOOK EDITOR VARIABLE................................................ Objects-289
WINDOW-POINT FUNCTION......................................................................................... Objects-289
WINDOW-RENDITION FUNCTION............................................................................... Objects-290
WINDOW-TRUNCATE-CHAR FUNCTION ................................................................... Objects-290
WINDOW-TYPE FU N C TIO N......................................................................................... Objects-291
WINDOW-WIDTH FU N CTIO N ...................................................................................... Objects-291
XV

WINDOW-WRAP-CHAR FUNCTION............................................................................. Objects-292
WIN DOW P FUNCTION...................................................................................................Objects-292
WITH-INPUT-FROM-REGION M A C R O ........................................................................ Objects-293
WITH-MARK MACRO..................................................................................................... Objects-293
WITH-OUTPUT-TO-MARK MACRO............................................................................... Objects-294
WITH-SCREEN-UPDATE M A C R O ................................................................................Objects-294
WORD DELIMITER ATTRIBUTE ..................................................................................Objects-295
WORD-OFFSET FUNCTION......................................................................................... Objects-295
WRITE CURRENT BUFFER COMMAND......................................................................Objects-296
W RITE- FIL E-FROM- REG ION FUNCTION ................................................................... Objects-296
WRITE MODIFIED BUFFERS COMMAND................................................................... Objects-297
WRITE NAMED FILE COMMAND.................................................................................. Objects-298
YANK CO M M AND.......................................................................................................... Objects-298
YANK AT POINTER COMMAND ..................................................................................Objects-299
YANK PREVIOUS COMMAND.......................................................................................Objects-300
YANK REPLACE PREVIOUS CO M M AND................................................................... Objects-300

Appendixes

Appendix A

xvi

Editor Objects by Category

A.1

Attributes .....................................................................................................................

A-2

A.2

Attributes Provided with VAX LISP ..........................................................................

A-2

A.3

B u ffe r s ..........................................................................................................................

A-2

A.4

Buffers Provided with VAX L IS P ...............................................................................

A-3

A.5

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

A-3

A.6

Commands Provided with VAX LISP ........................................................................

A-4

A.7

D is p la y ..........................................................................................................................

A—7

A.8

Editor V a ria b le s ............................................................................................................

A-7

A.9

Editor Variables Provided with VAX L IS P ................................................................

A-7

A.10

Error Signaling and D e b u g g in g .................................................................................

A-9

A.11

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

A-9

A.12

H e lp ...............................................................................................................................

A-9

A.13

H o o k s .............................................................................................................................

A-9

A.14

Hook Variables Provided with VAX LIS P .........................................................

A-10

A.15

Invoking and Exiting the E d ito r.................................................................................

A-10

A.16

Kill Ring ........................................................................................................................

A-10

A.17

L in e s ...............................................................................................................................

A-11

LISP S y n ta x .................................................................................................................

A-11

A.20

M is c e lla n e o u s ............................................................................................................

A-13

A.21

Pointing D e v ic e ..........................................................................................................

A-13

A.22

Prompting and Terminal In p u t..................................................................................

A-14

A.23

R egions........................................................................................................................

A-14

A.25

Searching ...................................................................................................................

A-15

A.26

String T a b le s ..............................................................................................................

A-15

A.27

String Tables Provided with VAX L IS P ...................................................................

A-16

A.29

Styles Provided with VAX L IS P ...............................................................................

A-16

A.30

Style Bindings, "EDT Emulation" S ty le ...................................................................

A-16

A.31

Style Bindings, "EMACS" S ty le ...............................................................................

A-17

A.32

Style Bindings, "VAX LISP" S tyle .............................................................................

A-19

A.33

Text O p e ra tio n s ..........................................................................................................

A-19

A.34

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

A-20

A.18
A.19

A.24

A.28

Appendix B

Editor Commands and Bindings

A p p e n d ix C

B o u n d K eys and Key Sequences

Appendix D

Function Keys and Keypad Keys

Index

Figures
4-1

Before Moving the M a rk ..............................................................................................

4-11

4-2

Moving a Mark Forward ..............................................................................................

4—12

4 -3

Moving a Mark B ackw ard...........................................................................................

4-12

5 -1

Display Area C oordinates...........................................................................................

5-14

5-2

Altered Display Area Dim ensions...............................................................................

5-15

5-3

A Window Display P o sitio n .........................................................................................

5-20

Concepts-1

Hierarchy of Named O b je cts.............................................................................Concepts-9
xvii

Concepts-2

Before Deleting Region

Concepts-15

Concepts-3

After Deleting Region .

Concepts-16

Objects-1

LISP Syntax Attribute Values .............................................................................Objects-174

Tables
B-1

Editor Commands and Key Bindings.................................................................................

B-1

C—1

Editor Key B indings............................................................................................................

C-1

D-1

Characters Generated by Keys ........................................................................................

D-1

Preface
The VAX LISP /VMS Editor Programming Guide provides the information needed
to program the VAX LISP Editor in order to extend and customize its capabilities.

Intended Audience
Readers of this manual are assumed to have a working knowledge of LISP
programming and to be able to use the VAX LISP Editor as provided.
• The VAX LISP language elements are described in Common LISP: The
Language}
• Instructions for using the VAX LISP Editor appear in the VAX LISP /VMS
Program Development Guide.
Readers who are not familiar with LISP programming can use the VAX LISP
Editor as provided but should not attempt to customize it.

Structure
An outline of the organization and chapter content of this manual follows.
Part I: Guide to Editor Programming

This part introduces the techniques of Editor programming in a task-oriented
fashion. It contains six chapters, each covering a major area of Editor program
ming.
• Chapter 1 provides an overview of the subsystems of the Editor and of the
data types that each subsystem contains. It also describes the methods of
accessing Editor objects.
• Chapter 2 describes the techniques of creating Editor commands.
• Chapter 3 describes the techniques of binding Editor commands to keyboard
keys and pointer actions.
• Chapter 4 introduces the Editor’
s text operations subsystem and the tech
niques of extending it.
• Chapter 5 introduces the Editor’
s window and display operations subsystem
and the techniques of extending it.
• Chapter 6 describes the techniques of modifying the Editor’
s styles and of
creating new styles.
1 Guy L. Steele, Jr., Common LISP: The Language, Digital Press (1984), Burlington, Massachusetts.

xix

Part II: Concepts in Editor Programming

This part contains programming information arranged for quick reference.
Separate, alphabetically arranged articles on each of the major concepts and
data types used in Editor programming are included.
Part Hi: Editor Object Descriptions

Part III describes the individual functions, variables, and other objects provided
with the Editor. The descriptions are arranged alphabetically by object name.
Appendixes

This manual also contains four appendixes.
• Appendix A contains lists of the functions, variables, and other objects pro
vided with the Editor, categorized by the major concepts and data types used
in Editor programming.
• Appendixes B, C, and D list all the commands provided with the Editor, all
bound keys, and other information useful in binding Editor commands to keys
and key sequences. These appendixes also appear in the VAX LISP/VMS
Program Development Guide.

Associated Documents
The following documents are relevant to programming the VAX LISP Editor:
• VAX' LISP/VMS Program Development Guide presents information on using
the VAX LISP Editor as provided. This manual also provides general infor
mation about using VAX LISP, and serves as a guide to generally helpful VMS
documentation.
• Common LISP: The Language provides a definition of the Common LISP
language.
• VAX LISP Interface to VWS Graphics explains the use of the VAX LISP
programming interface to VAXstation graphics.

Conventions
Convention

M eaning

U PPER CA SE

Defined LISP functions, macros, variables, constants, and other
symbol names are printed in uppercase TY PE W RITER charac
ters; however, you can enter them in uppercase, lowercase, or a
combination of uppercase and lowercase characters. For example:

TY PEW RITER

The CA LL-OUT macro calls a defined external routine ....
lowercase
typewriter

LISP forms are printed in the text in lowercase t y p e w r it e r
characters; however, you can enter them in uppercase, lowercase, or
a combination of uppercase and lowercase characters. For example:
(setf example-1 (make-space))

SANS SERIF

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

Convention

M eaning

italics

Lowercase italics in format specifications and in text indicate argu
ments that you supply; however, you can enter them in lowercase,
uppercase, or a combination of lowercase and uppercase characters.
For example:
The routine-arguments must be compatible with the arguments
defined in the call to the D E F IN E - E X T E R N A L - R O U T IN E macro.

()

Parentheses used in examples of LISP code and in format spec
ifications indicate the beginning and end of a LISP form. For
example:
( setq name lis p )

[]

Square brackets in format specifications enclose optional elements.
For example:
[doc-string]

In function and macro format specifications, braces enclose elements
that are considered one unit of code. For example:
{keyword value}

{}*

In function and macro format specifications, braces followed by
an asterisk enclose elements that are considered one unit of code,
which can be repeated zero or more times. For example:
{keyword value}'

&OPTIONAL

In function and macro format specifications, the word &OPTIONAL
indicates that the arguments that follow it are optional. For exam
ple:
PPRINT object &OPTIONAL package
Do not specify &OPTIONAL when you invoke a function or macro
whose definition includes &OPTIONAL.

&REST

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

&KEY

In function and macro format specifications, the word &KEY indi
cates that keyword arguments 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 means that the ele
ment preceding the ellipsis can be repeated. For example:
function-name . . .

xxi

Convention

Meaning
A vertical ellipsis in a code example 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.

| Return |

| Ctrl/JC j

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:
| Ctrl/C |or |Ctrl/S|

The system echoes control key sequences as ' ' x ; therefore, in exam
ples of output, |ctri/ac| may be shown as ''x. For example:
a C ot

EE3IZ]

A sequence such as |pfi | |~3c~| indicates that you must first press and
release the key labeled PF1, then press and release another key.

mouse

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 mouse button, MB2 indicates the
middle mouse button, and MB3 indicates the right mouse button.
You can rebind the mouse buttons.

Red print

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

XXII

(cdr ' (a b c))

Parti
Guide to Editor Programming

Chapter 1

Editor Overview
The VAX LISP Editor is an interactive LISP program that enables the user to
insert, display, and manipulate text. Editor behavior and capabilities as they
appear to the interactive user are described in the VAX LISP /VMS Program
Development Guide.
The Editor is designed to be modified and extended easily. Since the Editor is
written entirely in LISP, you can alter it by writing new LISP code that performs
several tasks:
• Modifies the behavior of Editor commands
• Binds commands to key sequences or actions of a pointing device
• Modifies the Editor’
s initial features, such as the labeling of its windows, the
frequency of checkpointing, the size of the information area, and so on
• Adds new capabilities, such as justification of text, parsing of LISP code,
recognition of the syntax of another programming language, and so on
Tb write Editor-related code, you use the same functions and data types that
were used to develop the Editor originally. These include some specially defined
“
Editor objects”
; you can also use any object defined in VAX LISP.
This chapter provides an overview of the Editor as a LISP program and of its data
types. The intent is to orient you to the process of extending the Editor and to
the range of possible extensions. This chapter also gives some basic programming
information that is needed to follow the discussion in later chapters.
T h is ch ap ter con tain s the follow in g features:

• Illustrations of simple Editor extensions
• Overview of the Editor’
s subsystems and utilities
• Introduction to Editor data types and the means of referencing them

1.1 Some Common Editor Extensions
This section includes the LISP code that implements several different kinds of
Editor extensions. These simple examples illustrate the process of programming
the Editor.
The following Editor extensions are shown:
• Changing the frequency of checkpointing
• Changing the number of windows that the Editor normally displays at one
time

Editor Overview

1-1

• Changing the default major style
• Binding a command supplied by Digital to a key sequence
• Defining a new command to change the width of the terminal screen
If you wish to make any of these changes in your own Editor, you simply execute
the forms as shown. You can execute them either by typing them at top-level
LISP or by loading them from a file.
In these examples the symbols for objects supplied by Digital that relate to the
Editor are referenced with the package prefix e d i t o r :. For a full discussion of
the package location of Editor objects, see Section 1.3.5.

1.1.1

Changing the Frequency of Checkpointing
The Editor checkpoints buffers associated with files after every 350 commands
that alter text (see VAX LISP/VMS Program Development Guide). If you would
like checkpointing to occur either more or less frequently, you can change this by
using s e t f with the function c h e c k p o i n t -f r e q u e n c y .
(setf (editor:checkpoint-frequency) 1000)

After you have executed this form, the Editor will checkpoint after every 1000
commands that alter text.
To disable checkpointing completely, set the value to n i l :
(setf (editor:checkpoint-frequency) nil)

1.1.2

Changing the Number of Windows Displayed
The Editor normally displays up to two anchored windows at a time. If you call
for a third anchored window (by selecting another buffer or editing another file or
LISP object), the Editor removes a window from the screen to make room for the
new window. (See VAX LISP/VMS Program Development Guide.)
If you would like the Editor to show up to three windows at a time, you change
the value of an Editor variable called " A n c h o r e d w i n d o w show Limit" from 2 to 3.
If you want only one window shown at a time, you set the value to l .
An Editor variable differs slightly from a LISP variable (see Section 1.3.4).
You reference an Editor variable by means of a specifier (symbol or a string
called a display name), and you access the variable’
s value with the function
v a r i a b l e -v a l u e . Using s e t f , you can then change the value of the Editor
variable.
The code that changes the number of anchored windows that the Editor can show
is:
(setf (editor:variable-value "Anchored Window Show Limit") 3)

After you have executed this form, the Editor will show up to three anchored
windows at a time. If you call for a fourth anchored window, the Editor will
remove a window from the screen to accommodate the new window.

1-2

Editor Overview

1.1.3

Changing the Default Major Style
The Editor activates EDT Emulation as the major style in all the buffers that
it creates for editing files and LISP objects. If you prefer the behavior and key
bindings of an editor based on EMACS, you can make EMACS style the default
major style instead. (See VAX LISP/VMS Program Development Guide.)
The default is stored as the value of the Editor variable "Default Major style".
The possible values are Editor objects called styles, which, like Editor variables,
can be referenced by either their symbols or their display names.
The following form changes the Editor’
s default major style to EMACS:
(setf (editor:variable-value "Default Major Style") "EMACS")

Any new buffers the Editor creates after you have executed this form will have
"EMACS" as their major style. Already-existing buffers are not affected.

1.1.4

Binding a Command to a Key Sequence
Many commands provided by Digital are not bound to keys or key sequences and
must therefore be invoked by name (see VAX LISP/VMS Program Development
Guide). You might wish to bind keys to the commands you use frequently, such
as "Write Current Buffer".
To establish a key binding, you can use the function b i n d -c o m m a n d and the
display name of an Editor command. To specify the key or keys, you can use the
normal LISP syntax for a character or a vector containing characters, (b i n d c o m m a n d is one of the few Editor-related symbols accessible in the user package;
you need not prefix it with the e d i t o r : package qualifier.)
(bind-command "Write Current Buffer" '#(#\AX #\AW))

The sequence Ctrl/X Ctrl/W will now execute "Write Current Buffer" in the Editor.
To ensure that the key sequence you choose is not already bound to an Editor
command, you can consult Appendix C, which lists the keys bound in the Editor
as provided.

1.1.5

Defining a Command to Change Screen Width
In editing LISP code, you might occasionally want your terminal screen to display
more than 80 columns so that lines do not truncate. One way to do this is to
execute the command "Set Screen width" after specifying a prefix argument
(such as 132). If you adjust screen width frequently, you might prefer to have a
command that you can execute in one step.1
To implement a new command, use the macro d e f i n e -c o m m a n d . A possible
implementation for a command that widens the screen to 132 columns is:

(editor:define-command (widen-screen-command :display-name "Widen Screen")
(prefix)
(setf (editor:variable-value "Default Window Truncate Char") nil)
(setf (editor:screen-width) (or prefix 132)))

1 On Digital terminals without the Advanced Video Option, widening the screen reduces available screen height to 12
rows.

Editor Overview

1-3

The function s c r e e n -w i d t h returns the current width of the screen. Using s e t f ,
you change the value to 132 or to a prefix value that you can supply interactively.
(If no prefix value is supplied interactively, the Editor automatically passes a n i l
value for this parameter, and the o r form will then return the value 132.)
This example also sets the value of the Editor variable "Default window Truncate
char" to n i l .This action dispenses with the character that normally appears on
the screen to indicate line truncation, d e f i n e -c o m m a n d creates a command named
"Widen Screen" that executes these two s e t f forms.
To have another command that sets the screen back to 80 columns and reestab
lishes > as the truncation character, you could write:
(editor:define-command (shrink-screen-command :display-name "Shrink Screen")
(prefix)
(setf (editor:variable-value "Default Window Truncate Char") #\>)
(setf (editor:screen-width) (or prefix 80)))

The new commands created by these d e f i n e -c o m m a n d forms can be invoked by
name within the Editor. To make the commands accessible from the keyboard,
you could bind them to key sequences:
(bind-command "Widen Screen" '#(#\escape #\w))
(bind-command "Shrink Screen" '#(#\escape #\s))

The new commands can now be invoked from the keyboard by means of Escape w
and Escape s.

1.2

Editor Components
This section introduces the various subsystems and utilities of the Editor. The
purpose is to indicate the range of Editor behavior that can be programmed and
to introduce the data types that each subsystem contains.
Section 1.3 discusses the nature of the Editor data types and the means of
referencing them.

1.2.1 Text Operations
Text in the Editor is made up of the 256 characters in the ASCII 8-bit extended
character set (DEC Multinational Character Set). The Editor’
s text operations
are the operations that insert, copy, and delete text and indicate any given text
position (for positioning the cursor, for instance).
The text operations subsystem contains the following specially defined data types,
along with functions and macros that operate on them:
• Objects that contain text: buffers, regions, lines
• Objects that indicate text positions: marks
• Objects that distinguish among characters for the purpose of searching
through text: Editor attributes
The text operations subsystem also contains Editor variables and several LISP
global variables.
Information on programming text operations appears in Chapter 4 and in the
descriptions of the preceding data types in Part II.

1-4

Editor Overview

1.2.2

Window and Display Operations
The Editor’
s window operations create, delete, and manipulate windows that open
onto the contents of buffers. The display operations make windows (and thus
buffer contents) visible on the screen or remove windows from the screen. Display
operations also manage the allocation of the total screen area and the use of the
information area at the bottom of the screen.
The window and display operations subsystem contains the following data types,
along with the functions and macros that operate on them:
• Text-containing objects that can be displayed: buffers
• Objects that translate text into displayable form: windows
The subsystem also contains Editor variables and LISP global variables, as well
as functions that operate on the information area.
Information on programming window and display operations appears in
Chapter 5 and in the descriptions of the preceding data types in Part III.

1.2.3

Binding Contexts
Contexts are separate programming environments within the Editor where
bindings can take place. Certain types of objects may have different bindings
simultaneously in different contexts:
• Editor variables
• Editor attributes
An Editor variable or an Editor attribute can reference more than one value
if the variable or attribute is bound in more than one Editor context. The
bindings of keyboard keys and pointer actions to Editor commands are also
context-dependent.
Two Editor data types can serve as binding contexts:
• Any buffer
• Any style
In addition, the Editor supports a global binding context.
To determine which of several bindings to use in a given situation, the Editor
searches through the contexts in a predetermined order and uses the first binding
it encounters. The search order is:
1. The current buffer
2. The styles active in the current buffer, beginning with the most recently
activated minor style, if any, and ending with the major style, if any (see VAX
LISP /VMS Program Development Guide)
3. The global Editor context
When you reference a context-dependent object in LISP code, you can specify the
appropriate context.
Editor contexts implement a form of scoping unlike either the dynamic or lexical
scoping of Common LISP (see Common LISP: The Language). The binding
context determines the scope of Editor variables, Editor attributes, keys, and
pointer actions.
Editor Overview

1-5

The extent of these context-dependent objects is indefinite (see Common LISP:
The Language). That is, the objects have extent that begins when they are bound
in a context and ends when they are unbound from that context. To “
bind”an
Editor variable or an Editor attribute is to establish it as usable in a certain
context. You cannot assign values unless the variable or attribute is bound
(“
established”
) in one or more contexts—buffer, style, or global.
You use binding contexts extensively in Editor programming. Find further detail
and examples, especially in Chapters 3 and 6. See also the discussion of the
context subsystem in Part II.

1.2.4 Other Subsystems and Utilities
The smaller subsystems of the Editor consist mainly of functions that allow you
to control certain types of Editor behavior:
• Prompting the user for a value necessary for the execution of a command—
discussed in Section 2.3.2 and Part II
• Signaling errors in command execution and handling LISP errors—discussed
in Section 2.3.1 and Part II
• Checkpointing buffers to save their contents in the event of system failure—
discussed in Part II
In addition, the Editor has several low-level tools and utilities. The following
items are all discussed in Part II:
• Input and output streams: LISP streams that permit normal Common LISP
input and output operations to be performed within the Editor.
• String tables: specialized hash tables that store information indexed by a
string (such as the display name of a command or other Editor object).
• Hooks: functions that are invoked automatically by certain Editor operations,
such as activating a style or making a buffer or window.
• Rings: circular caches of values that are used, for instance, to store deleted
text. Rings are used to implement the kill ring—a facility like those in certain
EMACS editors that store deleted text.

1.3

Referencing Editor Objects
The objects provided with the Editor include several new data types. The Editor
also contains definitions of LISP functions, macros, and global variables. All
these objects are LISP objects that can be referenced in any LISP code.
This section provides information on how to access these various kinds of objects.
It introduces:
• Functions, macros, and variables
• Editor-specific data types
— Named and unnamed objects
— Context-independent and context-dependent objects
• The package location of Editor symbols

1-6

Editor Overview

1.3.1

Functions, Macros, and LISP Variables
The Editor contains definitions of LISP functions, macros, and global variables.
All the normal Common LISP rules concerning scope and extent apply to the
identifiers of these objects.

1.3.2

Editor Objects
The specially defined Editor data types are:
• Editor attributes
• Buffers
• Commands
• Lines
• Marks
• Regions
• Rings
• String tables
• Styles
• Editor variables
• Windows
The methods of accessing Editor objects differ according to whether the object in
question is:
• Named or unnamed
• Context-independent or context-dependent
These methods are outlined in the two sections that follow.

1.3.3

Named and Unnamed Editor Objects
Named objects are Editor objects that can have two special specifiers: a string
called a display name and a symbol. The specifiers are associated with a named
object at the time it is defined, and they serve to access the object under certain
circumstances.
It is important to recognize that the symbol specifier of a named Editor object
cannot be treated as an ordinary LISP symbol. That is, the Editor object is not
the symbol-value of the symbol. Editor object specifiers behave somewhat like the
symbol and string specifiers of LISP packages. The function f i n d -p a c k a g e can
take, for instance, the symbol u s e r : or the string "u s e r " and return the package
object; the symbol u s e r : itself does not evaluate to the package object.
The reference list in Part III of this manual identifies both the display name and
the symbol of all named objects provided with the Editor. Section 1.3.3.2 outlines
the use of these specifiers in accessing named Editor objects.
The “
named”object types are:
• Editor attribute
• Buffer
Editor Overview

1-7

• Command
• Style
• Editor variable
The other Editor object types are “
unnamed.”Unnamed Editor objects have no
distinct specifiers.
• Line
• Mark
• Region
• Ring
• String table
• Window
1.3.3.1

Referencing Unnamed Objects

Any Editor object—named or unnamed—can be accessed in the usual LISP way:
that is, by means of a form that evaluates to the object. Unnamed objects can be
accessed only in this way.
For instance, the function c u r r e n t -w i n d o w takes no arguments and returns the
window that is current in the Editor. You can access the current window (an
unnamed object) by writing:
(editor:current-window)

Similarly, you can access a string table by referencing the LISP global variable to
which it is bound. For instance, evaluating
editor:*editor-command-names*

returns the string table that contains the names of the commands currently
defined in the Editor.
1.3.3.2

Referencing Named Objects

Named Editor objects can be accessed in the same way as unnamed objects: by
means of an expression that returns the object. For instance, the form
(editor:current-buffer)

returns the buffer (a named object) current in the Editor.
You can also reference named Editor objects by means of their specifiers (symbols
or display names) in certain circumstances:
• Interactively, when the Editor prompts for the name of a command, buffer, or
style, you supply the appropriate display name.
• In LISP code, when calling a function that takes a named Editor object
specifier as an argument, you can supply any of three specifiers of the named
object:

1-8

Editor Overview

The display name

The symbol

Any form that evaluates to the object

In contrast, some functions take a named Editor object but not a specifier. When
calling these functions, you must supply a form that evaluates to the object. The
function descriptions in Part III distinguish between functions that can take
specifiers (including objects) and functions that can only take objects.
For instance, the following functions can take specifier arguments:
COMMAND-CATEGORIES
VARIABLE-VALUE
BUFFER-MAJOR-STYLE
FIND-STYLE
BIND-ATTRIBUTE

The following examples show how you can call each of these functions from LISP
code with the specifier of a named Editor object as the argument. In each case,
you could use either the symbol or the display name of the named object; you
could also, of course, use any form that evaluates to the object in question.
• Using a command specifier:
(editor:command-categories

'editor:end-of-line-command)

(editor:command-categories

"End of Line")

• Using an Editor variable specifier:
(editor:variable-value 'editor:target-column)
(editor:variable-value "Target Column")

• Using a buffer specifier:
(editor:buffer-major-style 'editor:editor-help-buffer)
(editor:buffer-major-style "Help")

• Using a style specifier:
(editor:find-style 'editor:edt-emulation)

(editor:find-style "EDT Emulation")

• Using an Editor attribute specifier:
(editor:bind-attribute 'editor:word-delimiter)
(editor:bind-attribute "Word Delimiter")

Because these functions evaluate their arguments, the argument can also be a
form that evaluates to a specifier of a named Editor object. For instance, the
f o llo w in g p a ir o f fo r m s h a s the s a m e effect a s the c a lls to BUFFER-MAJOR-STYLE
shown above:
(setf b "Help")
(editor:buffer-major-style b)

1.3.3.3

A Note on Efficiency

The display names of named Editor objects are included for the convenience of the
programmer and the Editor user. If you wish to maximize the efficiency of your
program, however, you should realize that accessing an object by using its display
name is less efficient than using its symbol. Further, using either specifier is less
efficient than using an expression that evaluates to the object.
For example, the following three forms are equivalent when the buffer named
"Mybuffer.txt" is the current buffer. The forms are listed in order from the least
to the most efficient:

Editor Overview

1-9

(editor:buffer-major-style "Mybuffer.txt")
(editor:buffer-major-style 'mybuffer.txt)
(editor:buffer-major-style (editor:current-buffer))

The code examples in this manual frequently use display names for convenience
and readability. When you reference named objects in your own code, however,
you should consider the tradeoff between convenience and efficiency in each
instance.

1.3.4

Context-Independent and Context-Dependent Editor Objects
Editor objects are either context-independent or context-dependent. “
Contextdependent”objects are actually specifiers that may be associated with different
objects in different Editor contexts (the contexts are individual buffers, individual
styles, and global).
“
Context-independent”objects exist independently of Editor context. These
objects are accessed according to the scoping rules defined in Common LISP: The
Language.

1.3.4.1

Referencing Context-Independent Objects

All the unnamed Editor objects and most of the named objects (buffers, com
mands, and styles) are context-independent. Once it is created, a contextindependent object exists within the Editor as a unique object, and the accessing
functions appropriate to the data type locate and return that unique object.
For instance:

1.3.4.2

(editor:find-buffer 'factorial)

/Finds and returns the buffer
/object named factorial

(editor:find-style "VAX LISP")

/Finds and returns the style
/object named "VAX LISP"

(editor:next-window)

/Finds and returns a unique
/window object (unnamed)

Referencing Context-Dependent Objects

The context-dependent Editor objects are Editor attributes and Editor variables.
Attributes and variables are not unique objects. That is, a specifier can be
associated with different values (or, in the case of variables, also with different
functions) in different Editor contexts.
It is important to recognize that these multiple associations can exist simultane
ously; leaving an Editor context makes an association temporarily inaccessible,
but it does not destroy it.
The following functions are used to access a value or function associated with a
context-dependent object:
•

v a r ia b l e - v a lu e

ta k e s a v a r ia b le s p e c ifie r a n d a n o p tio n a l c o n te x t a n d r e tu r n s

t h e v a l u e ( if a n y ) o f t h a t v a r i a b l e i n t h a t c o n t e x t .
•

v a r ia b l e - f u n c t io n

ta k e s a v a r ia b le s p e c ifie r a n d a n o p tio n a l c o n te x t a n d

r e t u r n s t h e f u n c t i o n d e f i n i t i o n ( if a n y ) o f t h a t v a r i a b l e i n t h a t c o n t e x t .

• character-attribute takes an attribute specifier, a character, and an op
tional context and returns that character’
s value (if any) for that attribute in
that context.

1-10

Editor Overview

The functions f i n d - a t t r i b u t e and f i n d - v a r i a b l e are different from the f i n d object-type functions for the context-independent data types. The f i n d - objecttype functions for context-dependent objects take a specifier (symbol or display
name) and return the symbol of an attribute or variable. They do not return a
value or function object associated with the specifier.
Chapters 3 and 6 contain code examples that illustrate the nature and use of
context-dependent objects. Further explanation also appears in Part II.

1.3.5

The Editor Package
The symbols for the objects defined in the Editor are located in the editor package
and are external in that package.
Most of these symbols are not exported to the user package. (Only the functions
e d and b i n d - c o m m a n d are accessible in the user package.) Any other symbols
supplied by Digital for Editor objects must be referenced in the editor package
when you use them in writing extensions.
There are three ways to reference symbols located in the editor package;
• By using the package prefix
• By e x e c u t i n g a u s e - p a c k a g e f o r m
• By executing an i n - p a c k a g e form
This section describes these three methods and their appropriate uses.

1.3.5.1

The Package Prefix

When working in the user package, you can reference any symbol in the editor
package by prefixing it with the package qualifier EDITOR:. For instance, if you
want to call v a r i a b l e - v a l u e with the symbol of an Editor variable, you would
prefix both symbols with e d i t o r : .
(editor:variable-value

'editor:default-major-style)

This expression references two symbols in the editor package, but it can be
evaluated in the user package.
Note that using the display name of a named Editor object instead of its symbol
avoids the problem of package location, although efficiency suffers;
(editor:variable-value

1.3.5.2

"Default Major Style")

Using USE-PACKAGE

To avoid the inconvenience of using qualified names, you can reference all the
external symbols in the editor package by executing either of the forms:
(use-package "EDITOR")

(use-package 'editor)

Note that the string argument ( " e d i t o r ") must be uppercase.
Executing either of these forms makes all symbols related to Editor accessible in
the user package for the remainder of your current LISP session.
However, before executing a u s e - p a c k a g e form, you should consider whether
you will also be using symbols from other packages in the same LISP session.
Because of possible name conflicts among packages, you should use qualified
names in sessions in which you will be referencing symbols in more than one

Editor Overview

1-11

package. In particular, there are several name conflicts in VAX LISP between the
editor package and the UIS package (see VAX LISP Interface to VWS Graphics).
If you begin the file containing your completed Editor extensions with a u s e p a c k a g e form, you should end the file with a call to u n u s e -p a c k a g e .A call to u s e -

p a c k a g e in your initialization file makes all symbols in that package accessible
throughout every LISP session; these symbols may then interfere with symbols
you want to use from other packages.

1.3.5.3

Using IN-PACKAGE

It is generally good programming practice to place your newly defined symbols
in an appropriate package. You can place your completed Editor extensions in a
specified package by heading the file that contains the extensions with a call to
i n -p a c k a g e .An i n -p a c k a g e form makes the specified package current while your
file is being loaded into LISP; it then returns you to the u s e r : package for the
remainder of your session.
You can place your completed Editor extensions in the e d i t o r : package by
heading your file with either of the forms:
(in-package "EDITOR")

(in-package 'editor)

However, this use of the e d i t o r : package allows for possible name conflicts
(overwriting) between user-defined extensions and present or future objects
supplied by Digital.
You can avoid overwriting by placing your extensions in a new, user-defined
package. To do so, and to have the e d i t o r : package symbols accessible in the
new package, you begin the file with the following forms:
(in-package "EDITOR-EXTENSIONS")
(use-package "EDITOR")

These forms place your extensions in the e d i t o r -e x t e n s i o n s : package and make
the symbols from the e d i t o r : package accessible in that package. They do not
make the symbols from either of these packages accessible in the u s e r : package.

1-12

Editor Overview

Chapter 2

Creating Editor Commands
You control the VAX LISP Editor in an interactive session through commands. By
executing commands, you insert and revise text, display text or other information,
activate a style, or bring about any other Editor operation. (See VAX LISP/VMS
Program Development Guide.)
The primary way to customize the Editor is to alter its commands: that is,
replace existing commands or create entirely new ones. This chapter introduces
the techniques of implementing Editor commands. The topics it covers are:
• Commands and their associated LISP functions
• Creating commands with d e f i n e -c o m m a n d
• Including some special features in a new command
The techniques of binding commands to keyboard keys and pointer actions are
covered in Chapter 3.

2.1

Commands and Their Associated Functions
A command is a named Editor object associated with a particular LISP function.
For instance, the command "Forward Word" is associated with the function
FORWARD-WORD-COMMAND, and the command "Execute Named Command" is associated
with the function e x e c u t e -n a m e d -c o m m a n d -c o m m a n d .(The nature of named Editor
objects is discussed in Section 1.3.3.)
Whenever you execute a command during an interactive Editor session, the
Editor calls the associated function. Evaluating this function brings about the
specified chatige in the Editor. For instance, when you execute the command
"Forward Word" in the Editor, either by name or by means of the key sequence
bound to it, the Editor invokes the function f o r w a r d -w o r d -c o m m a n d .The result
you see is that the cursor moves to the next word in the text.
To implement an Editor command, you create both a new LISP function and a
named Editor command associated with it. Both these operations are performed
by the macro d e f i n e -c o m m a n d .

2.2 Using DEFINE-COMMAND
The DEFINE-COMMAND macro is similar to d e f u n in that it creates a new LISP
function from the specified argument list and forms. In addition, it creates a new
Editor command with the specifiers (display name and symbol) that you supply.
The new command definition is a side effect of a call to d e f i n e -c o m m a n d ; the
return value is the associated function definition.

Creating Editor Commands

2-1

The format of d e f i n e -c o m m a n d is also similar to that of d e f u n :
DEFINE-COMMAND n a m e a r g list
&OPTIONAL c o m m a n d - d o c u m e n t a t io n
&BODY fo r m s

An example follows of a d e f i n e -c o m m a n d expression that implements a new
Editor command named "My Next Screen". (This command differs slightly from
the "Next screen" command supplied by Digital; the difference is clarified in
Section 2.2.4.) The remainder of this section discusses the purpose and use of
each of the parameters of d e f i n e -c o m m a n d , using this expression as an example.
Recall that the symbols for Editor objects provided by Digital must be referenced
in the e d i t o r : package (see Section 1.3).
(define-command
(my-next-screen-command :display-name "My Next Screen")
(prefix Soptional (window (current-window)))
" Scrolls the current window down one screen. If a
positive integer prefix is supplied, it scrolls down
by that many screens (up if prefix is negative)
"

MY-NEXT-SCREEN-COMMAND prefix &OPTIONAL window

;name
;arglist
;com-doc

;func-doc

This function has an optional argument window which
defaults to the current Editor window. It scrolls the
window down one screen if the prefix argument is NIL.
If a positive integer prefix is supplied, it scrolls
down by that many screens (up if prefix is negative).
The modified window point is returned."
(scroll-window window (* (or prefix 1)
(1- (window-height window)))))

2.2.1

/forms

Specifying the Names
A command can have two distinct specifiers: a display name, which is a string,
and a symbol, which is identical to the symbol of the function defined in the same
form.
The display name of a command is provided as a convenience for the interactive
user. For instance, it invokes a command within the Editor. In LISP code, you
can use either the display name or the symbol of a command, as well as the
associated function itself, as an argument to a function that takes a command
specifier argument. (See Section 1.3.3 for referencing named Editor objects,
including commands.)
You specify the names of a new command and function in the name parameter to
d e f i n e -c o m m a n d .The name argument can be a symbol or a list of the form:
( s y m b o l :DISPLAY-NAME string)

The symbol argument serves the same purpose as the name argument for d e f u n —
it names the function being defined. In a call to d e f i n e -c o m m a n d ,symbol also
becomes the symbol specifier of the new command. The string argument becomes
the display name of the new command.
For example:
(define-command
(my-next-screen-command :display-name "My Next Screen")

2-2

Creating Editor Commands

/name

This form creates a LISP function named m y -n e x t -s c r e e n -c o m m a n d . It also
creates an Editor command with the display name "My Next Screen" and the
symbol m y -n e x t -s c r e e n -c o m m a n d .
The display name can be any string you want to specify. For commands supplied
by Digital, the convention is that display names are identical to the associated
symbols except for case and the omission of the hyphens and the final element
-c o m m a n d , If you do not specify a display name, the default is the print name
of the symbol. In this example, the default display name would be "my-nextscreen-command", a less convenient specifier than "My Next Screen".

2.2.2

Specifying the Argument List
When you execute a command within the Editor, the Editor always calls the
associated function with exactly one argument. This is the prefix argument,
which can be an integer or n i l .You can supply a prefix value by previously
executing the command "Supply Prefix Argument". If you execute a command
without supplying a prefix value, the Editor passes n i l .
Because the Editor always passes one argument, the argument-list of every
d e f i n e -c o m m a n d expression must have at least one parameter. By convention,
the first parameter is designated as p r e f i x . If you supply other parameters,
they must be optional. (You can supply values for optional arguments only when
calling the new function from LISP code, not when executing the new command
in the Editor.)
The argument-list for m y -n e x t -s c r e e n -c o m m a n d specifies that this function can
take two arguments: a prefix and a window.

(define-command
(my-next-screen-command :display-name "My Next Screen")
(prefix fioptional (window (current-window)))

;name
/arglist

The prefix argument usually means the number of times the action is to be
repeated, although other meanings are possible. (In fact, the difference between
"My Next Screen" and the "Next Screen" command supplied by Digital is in the
use they make of the prefix.) As with any function parameter, the meaning of
the prefix argument to any particular command is specified in the body of that
command’
s definition.
If you call the function m y -n e x t -s c r e e n -c o m m a n d from LISP code, you can also
specify the window that is to be operated upon. If you do not specify a window,
the function c u r r e n t -w i n d o w will be evaluated and will return the current
window. Since you cannot specify a window argument when you execute "My Next
Screen" in the Editor, the Editor always applies the command’
s action to the
current window.

2.2.3

Supplying Documentation Strings
The d e f i n e -c o m m a n d macro takes two optional documentation strings. The first is
associated with the new command; the second, which is actually part of the body,
is associated with the new function. If you supply only one documentation string,
it becomes the command-documentation.

Creating Editor Commands

2-3

Normally, the command-documentation is used to describe the behavior of the
Editor when you execute the new command. You can retrieve this documentation
within the Editor by means of the "Describe" command, using the display name
of the command in question. To retrieve documentation at top-level LISP, you
can call either the describe function or the documentation function and pass
it to the symbol of the command. (If you use documentation, the doc-type is
EDITOR-COMMAND.)

The function documentation is like the documentation string for d e f u n : it
normally gives the function’
s format and return value and describes its behavior
when called from LISP code. You can retrieve this documentation at top-level
LISP by means of d e s c r i b e or d o c u m e n t a t i o n , with the symbol of the function.
(The doc-type is f u n c t i o n .)
The two kinds of documentation string—one addressed to the user executing the
command and the other to the user calling the function—are illustrated below:
(define-command
(my-next-screen-command :display-name "My Next Screen")
(prefix Soptional (window (current-window)))
" Scrolls the current window down one screen. If a
positive integer prefix is supplied, it scrolls down
by that many screens (up if prefix is negative)
"

MY-NEXT-SCREEN-COMMAND prefix &OPTIONAL window

;name
;arglist
;com-doc

;func-doc

Note the placement of w h i t e s p a c e and n e w l i n e characters in both the docu
mentation strings in this example. As with d e f u n , you use these characters to
affect the appearance of a string when it is displayed in response to "Describe",
DESCRIBE, Or DOCUMENTATION.

2.2.4

Specifying the Action
The forms that you supply to d e f i n e -c o m m a n d are identical in purpose to the
forms for d e f u n : they constitute the body of the LISP function that will be
invoked when you execute the new command. The forms include the function
documentation, if any, and they may include declarations.
Including the forms completes the definition of "My Next Screen":

(define-command
(my-next-screen-command :display-name "My Next Screen")
(prefix Soptional (window (current-window)))
" Scrolls the current window down one screen. If a
positive integer prefix is supplied, it scrolls down
by that many screens (up if prefix is negative)."
"

MY-NEXT-SCREEN-COMMAND prefix &OPTIONAL window

2-4

Creating Editor Commands

;name
;arglist
;com-doc

;func-doc

(s c ro ll-w in d o w

w in d o w

(o r

p r e f ix

; fo rm s

(1- (window-height window)))))

This example uses the Common LISP functions *, o r , and l - and the Editor
functions s c r o l l - w in d o w and w i n d o w - h e i g h t :
•

•

s c r o l l - w i n d o w takes a window and a count. It scrolls the specified window
by the number of rows indicated by the count and returns the window point.
(The window point is an object that indicates the position of the screen cursor
in the current window; see Section 5.2.2.)
w in d o w - h e i g h t

t a k e s a w i n d o w a n d r e t u r n s t h e h e i g h t ( in r o w s ) o f t h a t

w in d o w .

The action of the function m y - n e x t - s c r e e n - c o m m a n d is to scroll the specified
window (or default window) by a number of rows that equals one less than the
height of the window. That is, the last row of the current text display becomes
the first row of the new text display. If you supply a prefix argument, the action
is repeated that many times. Because s c r o l l - w i n d o w moves the window point,
the cursor will appear within the new text display when you execute "My Next
Screen".

To see the difference between "My Next Screen" and the "Next Screen" command
supplied by Digital, compare the last form in the above example with the last
form in the definition of "Next Screen":
(scroll-window window
(or prefix (1- (window-height window))))

The prefix value in "My Next Screen" serves as a repetition count. In "Next
Screen" the prefix value is an alternative to the window height in determining
how many rows to scroll the window.

2.2.5

Modular Definition of Commands
You can define Editor commands of any degree of complexity. When defining a
complex command, it is good programming practice to write the code in modules.
You can, for instance, use d e f u n to create a new function and then use that
function in a d e f i n e - c o m m a n d expression.
For example:
(defun print-time (stream)
"

PRINT-TIME stream

Formats a record of the current date and time and
writes that record to the specified stream."
(multiple-value-bind
(second minute hour date month year day-of-week)
(get-decoded-t ime)
(format stream
"~D :~2,'OD:~2, 'OD on ~[Monday-;Tuesday-;Wednesday~;Thursday~;Friday~;~Saturday~;Sunday-], ~
~D ~ [~;January-;February-;March-;April-;May-;June~;July-;August-;September-;October~;November-.•December-], ~D"

hour minute second day-of-week date month year)))

This form creates the function p r i n t - t i m e , which writes the current date and
time to a specified stream. To include this action in an Editor command, you
might write:

Creating Editor Commands

2-5

(define-command (show-time-command :display-name "Show Time")
(prefix)
" Displays the current time and date in the information area."
" SHOW-TIME-COMMAND prefix
Displays the current time and date in the information area.
The prefix argument is ignored."
(declare (ignore prefix))
(clear-information-area)
(print-time *information-area-output-stream*))

This form creates an Editor command named "show Time". When you execute
"Show Time", the Editor clears the information area of any previous text and then
directs the record formatted b y p r i n t - t i m e to the information area. Note the
declaration that the prefix is ignored, since the prefix parameter is not used in
the body of the expression.

2.2.6

Commands and Context
Many commands are normally used within a single Editor context (buffer, style,
or global), but commands are not context-dependent objects. That is, commands
are not bound in Editor contexts, as keyboard keys and pointer actions are: any
command can be invoked by name no matter which contexts are visible in the
Editor. For instance, the command "e d t change Case" usually is used in "e d t
Emulation" style, but it could also be used in "e m a c s " or "v a x l i s p " styles.
However, the definition of a command may reference another object that is
context-dependent: an Editor variable or an Editor attribute. (See Section 1.3.4
for a discussion of context-dependent objects.) If so, the command behaves
differently when you execute it in contexts in which the context-dependent object
is bound differently or not bound.
An example is the command "e d t Move Word", which moves the cursor by
one or more words. The body of this command begins with a test of whether
the Editor variable "EDT Direction Mode" is set to :f o r w a r d . If so, it invokes
f o r w a r d -w o r d -c o m m a n d :

(if (eq (variable-value "EDT Direction Mode")

:forward)

(forward-word-command prefix)

If you execute this command outside of "e d t Emulation" style, it will not invoke

f o r w a r d -w o r d -c o m m a n d because "e d t Direction Mode" is unbound.

The behavior of f o r w a r d -w o r d -c o m m a n d also varies in different contexts. This
function references the Editor attribute "Word Delimiter", whose values are
context-dependent. "Forward Word" behaves differently in "e d t Emulation",
"e m a c s ", and "v a x l i s p " styles because different characters are recognized as
word delimiters in these styles.
NOTE

Unlike commands themselves, the key and pointer bindings of Editor
commands are context-dependent (see Section 3.4). "e d t change Case"
can be invoked by name anywhere within the Editor, but, as provided,
it is only in "e d t Emulation" style that this command can be invoked
by means of keypad PF1 1.

2-6

Creating Editor Commands

2.3

Some Special Command Facilities
Most of the new commands that you implement are likely to pertain to text
operations or to window and display management. Regardless of the command’
s
primary purpose, however, you may also want to include in it such features as
a prompt or a particular error response. You can also include the command in a
command category, which facilitates certain kinds of testing that may take place
during command processing.
This section introduces the following command subsystems/facilities:
• Errors
• Prompting
• Command categories

2.3.1 Errors
By using functions from the Editor’
s error subsystem, you can implement
commands that take some action in response to errors in command processing. In
addition, you can use the LISP variable * u n i v e r s a l - e r r o r - h a n d l e r * to modify
the way the Editor handles LISP errors.
This section introduces the following error-related objects:
• The a t t e n t i o n function
• The e d i t o r - e r r o r function
• The *u n i v e r s a l - e r r o r - h a n d l e r * variable
2.3.1.1

Getting the User’s Attention

The a t t e n t i o n function, the simplest of the error-related functions, can be
included in the body of a command to gain the user’
s attention if the command’
s
action is not performed. On Digital VT100- and VT200-series terminals and the
AI VAXstation, the action of a t t e n t i o n is to ring the bell.
An e x a m p l e o f t h e u s e o f a t t e n t i o n i s :
(define-command (forward-word-command :display-name "Forward Word")
(prefix)
" Moves the buffer point forward one word. If a prefix argument
is supplied, the point is moved forward that many words (backward
if the prefix is negative)."
(unless
(word-offset (current-buffer-point)
(attention))

(or prefix 1))

(current-buffer-point))

The command "Forward Word" invokes the function w o r d -o f f s e t , which
moves the current buffer point by one or more words. If this action cannot
be performed—if too few words remain in the buffer, for instance—then the
a t t e n t i o n function is called to alert the user.
A c o m m a n d c o n t i n u e s p r o c e s s i n g a f t e r e v a l u a t i n g a t t e n t i o n . In t h i s c a s e , t h e
n e x t fo rm , a c a ll to

cu r r en t-b u f f e r - p o in t , is

e v a lu a te d to r e tu r n th e b u ffe r

p o in t.

Creating Editor Commands

2-7

2.3.1.2

Signaling an Error

The most generally useful error-signaling function is e d i t o r -e r r o r .This function
typically is used to indicate an invalid command operation, invalid or incomplete
user input, or some other error that allows the Editor to continue operation after
ceasing to process the currently executing command.
The e d i t o r -e r r o r function invokes a t t e n t i o n to signal a problem in command
processing. In addition, it can display an optional line of text in the information
area to explain the nature of the problem. The arguments to e d i t o r -e r r o r are
analogous to those for the LISP e r r o r function. However, e d i t o r -e r r o r allows
the user to remain in the Editor after it is called, rather than being placed in the
Debugger.
Unlike a t t e n t i o n , which allows the Editor to continue processing the command,
e d i t o r -e r r o r terminates the processing of the current command. The Editor
then awaits the next command.
The use of e d i t o r -e r r o r is illustrated in the command "e d t Special insert"
supplied by Digital. This command must be invoked with a prefix; it inserts as
text the character whose ASCII (extended) code is the prefix value supplied.
(define-command (edt-special-insert-command
:display-name "EDT Special Insert")
(prefix)
" Takes the prefix value and inserts the character whose
ASCII code is that value at the current buffer point."
(unless prefix
(editor-error "Character code not supplied"))
(unless (and (integerp prefix)
(<= 0 prefix 255))
(editor-error "Invalid character code ~A" prefix))
(insert-character (current-buffer-point)
(code-char prefix)))

Two errors that can occur when you invoke this command are: (1) no prefix
value supplied, and (2) prefix value supplied that is not a valid ASCII (extended)
character code. Before attempting to evaluate the i n s e r t -c h a r a c t e r form, the
c o m m a n d tests for each of these possible errors. If an error has occurred, the
appropriate explanation string is displayed in the information area and the
processing of this command stops.
A somewhat more complex error-signaling function is e d i t o r -e r r o r -w i t h -h e l p .
This function resembles e d i t o r -e r r o r except that it takes an additional optional
string argument. The additional string supplies further information about the
error; it is displayed if the user executes the command "Help on Editor Error"
(see Part III).
2.3.1.3

Error Handling

When implementing a command, you can also modify the way the Editor handles
LISP errors that occur during command processing.
As provided, the Editor responds to a LISP error by clearing the screen, display
ing the error message, and asking if you want to save modified buffers. It then
gives you the choice of entering the Debugger or returning to top-level LISP.
You can a lte r this behavior by defining a new error-handling function and binding
it to the variable *u n i v e r s a l -e r r o r -h a n d l e r * (see VAX LISP/VMS Program

Development Guide). You can then reference this variable in a command defini
tion to invoke the new error-handling function.
2-8

Creating Editor Commands

For instance, suppose that you want to alter the command "Insert File" to
respond in a particular way when your response to the prompt is not a valid file
name. To achieve this, you define a new error-handling function, and then write
a file-insertion command that invokes this function if it receives an invalid file
name.
The following example shows a skeletal version of a function to be invoked when
the Editor cannot insert a file:
(defun insert-file-error-handler (&rest args)
(with-output-to-mark
(‘error-output* (buffer-point (find-buffer "Error Record")))
(apply #'print-signaled-error args))
(editor-error "Error reading file..."))

This function creates an output stream by means of the macro w i t h -o u t p u t t o -m a r k and binds it to the variable *e r r o r -o u t p u t *. This stream is directed
to a user-defined buffer named "Error Record". The VAX LISP function p r i n t s i g n a l e d -e r r o r formats an error message from the supplied arguments and
writes that message to *e r r o r -o u t p u t *. The message text is thus inserted at the
buffer point of the "Error Record" buffer. Once the formatting is done, i n s e r t f i l e -e r r o r -h a n d l e r calls e d i t o r -e r r o r to print a brief explanation and return
to the Editor command loop.
To write a new command that invokes i n s e r t -f i l e -e r r o r -h a n d l e r instead of
the Editor’
s default error handler when a LISP error occurs, you bind this new
function to *u n i v e r s a l -e r r o r -h a n d l e r * in the definition of the command. For
instance, the relevant portion of a file-inserting command might look like this:
(define-command (my-insert-file-command ...) (prefix)

(let ((‘universal-error-handler* #'insert-file-error-handler))
(insert-file-at-mark (pathname...)
(current-buffer-point)))

This command invokes the Editor function insert-file-at-mark to insert a
specified file at the current buffer point. This action occurs within the scope of a
let

f o r m t h a t b in d s *u n iv e r s a l - e r r o r - h a n d l e r * t o

in s e r t -f i l e - er r o r - handler.

If any LISP error occurs during the file-insertion operation, the error system calls
insert-file-error-handler instead of the default error handler.

2.3.2

Prompting
The Editor’
s prompting subsystem enables you to write commands that prompt
for any additional user input needed for their execution. For example, when you
invoke the command "Select Buffer", the Editor prompts for the name of the
buffer that is to become current.
Commands prompt by invoking one of the following functions:
•

SIMPLE-PROMPT-FOR-INPUT

•

PROMPT-FOR-INPUT

Creating Editor Commands

2-9

Both functions display a prompt in the prompting window, which is a window
onto the buffer "General Prompting" supplied by Digital. User interaction,
including editing the response to the prompt, occurs in this buffer. The more
versatile of the two functions, p r o m p t -f o r -i n p u t , also enables you to include
some additional prompt-related behavior, such as input completion, alternatives,
and help.
2.3.2.1

Simple Prompting

The siMPLE-PROMPT-FOR- i n p u t function is less versatile than pr o m p t -f o r - i n p u t ,
but it is generally more straightforward, s i m p l e -p r o m p t -f o r - i n p u t prompts for
input and returns the user’
s input as a string. Its format is:
SIMPLE-PROMPT-FOR-INPUT &OPTIONAL p r o m p t d e fa u lt

The prompt argument is a string to be displayed as the prompt; the default
argument is a string to be returned by s i m p l e -p r o m p t -f o r -i n p u t if the user
presses Return without typing any input. The default value for both arguments is
a null string.
An example of a new command that invokes s i m p l e -p r o m p t -f o r -i n p u t is "Visit
File". This command is similar to the "view File" command supplied by Digital,
except that it allows the user to edit the specified file.
(define-command (visit-file-command :display-name "Visit File")
(prefix fioptional (file-name nil))
" Prompts for a file name and then edits the specified file.
If the specified file is associated with a buffer, it simply
switches to that buffer; otherwise a new buffer is created."
(declare

(ignore p r e f i x ) )

(unless file-name
(setf file-name
(simple-prompt-for-input "Enter file name:

")))

(edit-file-command nil file-name))

The function v i s i t -f i l e -c o m m a n d , when called from LISP code, takes an optional
file-name argument that can be a pathname or a string. When you invoke "visit
File" in the Editor, however, you cannot supply this argument. To obtain the
value, the command displays the specified prompt, “
Enter file name:”
, simplep r o m p t -f o r - i n p u t returns your response to the prompt as a simple string.
The string is bound to the variable f i l e -n a m e and then passed to the function
e d i t -f i l e -c o m m a n d .

Even though s i m p l e -p r o m p t -f o r - i n p u t always returns a simple string, you can
use this function when the argument needed is some other data type. In such a
case, the command must coerce the user’
s input into the appropriate data type.
For example, in c o m m a n d s _ s i g n a l i n g _ e r r o r shown above, the command "e d t
Special insert" takes an integer argument. If you fail to execute "Supply
Prefix Argument" beforehand, "e d t Special Insert" displays an error message
and stops processing. You could rewrite this command to prompt for the needed
value instead of signaling an error. The code for such a command might be:
(define-command (my-special-insert-command
:display-name "My Special Insert")
(prefix)
" Takes the prefix value and inserts the character whose
ASCII code is that value at the current buffer point. If
no prefix value is supplied, it prompts for a value."

2-10

Creating Editor Commands

(unless prefix
(setf prefix
(read-from-string
(simple-prompt-for-input " Enter ASCII code:

") )) )

(if (and (integerp prefix) (<= 0 prefix 255))
(insert-character (current-buffer-point)
(code-char prefix))
(editor-error "Invalid character code: -A" prefix)))

The Common LISP function r e a d - f r o m - s t r i n g is used here to coerce the user’
s
input string to an integer. This integer is then bound to p r e f i x and passed
to c o d e - c h a r . Only if the input supplied does not convert into a valid ASCII
extended character code will this command display an error message.
2.3.2.2

General Prompting

General prompting differs from simple prompting in that: (1) the prompting
function can return any data type (not only a string), and (2) you can include
a greater range of prompt-related behavior by specifying a number of keyword
arguments. The function you use for general prompting is p r o m p t - f o r - i n p u t .
What follows is a brief introduction to the use of p r o m p t - f o r - i n p u t . Part III
contains a fuller description of this function and its keyword arguments.
The b a s i c f o r m a t o f p r o m p t - f o r - i n p u t i s :
PROMPT-FOR-INPUT v a lid a tio n

The one required argument to p r o m p t - f o r - i n p u t is a validation function. This
function takes the user’
s input string and returns a value that will be returned
by p r o m p t - f o r - i n p u t . If the validation function returns n i l , p r o m p t - f o r - i n p u t
signals an error and awaits further input.
For instance:
(prompt-for-input #'find-buffer)

This form prompts the user with a default prompting message and passes the
user’
s input string to the function f i n d - b u f f e r . If the input string is not a valid
buffer name, f i n d - b u f f e r returns n i l . p r o m p t - f o r - i n p u t then displays a default
error message and waits for a valid buffer name before command processing
continues.
p r o m p t - f o r - i n p u t can also make available the facilities for input completion and
alternatives to assist the user. By providing string tables as arguments to the
keywords c o m p l e t i o n and :a l t e r n a t i v e s , you specify that those string tables
are to be searched if the user requests assistance from either of these facilities.
In the above example, the appropriate string table is bound to the variable
* e d i t o r - b u f f e r - n a m e s *, and the form would look like this:

(prompt-for-input #'find-buffer
:completion *editor-buffer-names*
:alternatives *editor-buffer-names*)

(These two keyword arguments can also be values other than string tables; see
the description of p r o m p t - f o r - i n p u t in Part III.)
Other keywords allow you to specify, for instance:
• The prompt to be displayed
• An e r r o r m e s s a g e t o b e d i s p l a y e d i f t h e v a l i d a t i o n f u n c t i o n r e t u r n s n i l
• Help text to be displayed if the user requests it
• Whether user input is required
Creating Editor Commands

2-11

• A default value to be returned if you specify that user input is not required
These and other arguments to p r o m p t -f o r - i n p u t are described in full in Part III.
What follows is a comparatively simple example of this function, using only a few
of its possible keyword arguments. The new command "My insert Buffer" calls
p r o m p t -f o r - i n p u t to prompt for a buffer name. The command then inserts the
text of that buffer into the current buffer. Its code is:
(define-command (my-insert-buffer-command :display-name "My Insert Buffer")
(prefix)
(declare (ignore prefix)
(insert-region (current-buffer-point)
(buffer-region
(prompt-for-input #'find-buffer
rprompt "Enter Buffer Name: "
:required t
:completion *editor-buffer-names*
:alternatives *editor-buffer-names*))))

This command displays the string argument to : p r o m p t in the prompting window.
Because the value of :r e q u i r e d is T, the user must enter a string for the action
to continue (no default value can be returned by p r o m p t -f o r - i n p u t ). As in the
example above, the string table arguments to :c o m p l e t i o n and a l t e r n a t i v e s
make available to the user the names of all existing buffers.
The user’
s input string is passed to the validation function, f i n d -b u f f e r ,which
returns a buffer object if the input is a valid buffer name. The buffer object
returned by f i n d -b u f f e r is passed to b u f f e r -r e g i o n , which returns the textcontaining region of that buffer. The region is passed to i n s e r t -r e g i o n , which
inserts it at the buffer point of the current buffer. (The region-manipulating
functions and other text operations objects are described in Chapter 4 of this
manual.)

2.3.3

Command Categories
A command category indicates some property of a command that another
command may need to examine. The test is performed by checking whether the
command is a member of a specified category.
For example, the command "e m a c s Forward Search" checks to see if the last
command executed was in the category :e m a c s -s e a r c h . If so, it means that
the command was also a search command and the user has already entered a
search string, "e m a c s Forward Search" will therefore use the previous string
rather than prompt again for one. If the last command executed was not in the
:e m a c s -s e a r c h category, then "e m a c s Forward Search" prompts for a search
string.
The categories provided with the Editor are:
:GENERAL-PROMPTING
:LINE-MOTION
:MOVE-TO-POINTER
:EMACS-SEARCH
:EMACS-PREFIX
:KILL-RING

Categories can also be user-defined.

2-12

Creating Editor Commands

You can place a command in one or more categories by including the keyword
:c a t e g o r y and a symbol or list of symbols as part of the name argument of a
d e f i n e -c o m m a n d form. You can use existing categories, or you can define new
categories simply by specifying their symbols. For example:
(d e f i n e - c o m m a n d

(e m a c s - b a c k w a r d - s e a r c h - c o m m a n d

:display-name "EMACS Backward Search"
: c a te g o ry

: e m a cs-se a rch )

or
(define-command (my-new-command-command
:display-name "My New Command"
:category (:line-motion 'my-new-category)

lb check whether a given command is included in a specified category, you call
the function c o m m a n d -c a t e g o r i e s . This function takes a command specifier and
returns a list of the categories that include that command (or n i l if none is
found). The variable *p r e v i o u s -c o m m a n d -f u n c t i o n * is bound to the function
associated with the last command executed; this variable is a command specifier
acceptable to c o m m a n d -c a t e g o r i e s .
For instance, the following form tests whether the previous command executed
was in the category :e m a c s -s e a r c h .
(if (member :emacs-search
(command-categories *previous-command-function*)
:test #'eq)

What follows is a full command definition that illustrates both (1) placing a
command in a category, and (2) testing the previously executed command for
membership in that category. The example, "My EMACS Forward Search", is a
simplified version of the command "EMACS Forward Search" supplied by Digital.
(define-command (my-emacs-forward-search-command
:display-name "My EMACS Forward Search"
:category :emacs-search)
(prefix)
" Searches forward once or the number of times specified
by the prefix argument. Prompts for a search string only
if the previous command was not a searching command."
(if (member :emacs-search
(command-categories *previous-command-function*)
:test #'eq)
(forward-search-command
prefix
(variable-value "Last Search String"))
(forward-search-command prefix)))

The Editor sets the user’
s response to a search-command prompt to the value
of the Editor variable "Last Search String". "My EMACS Forward Search" calls
f o r w a r d -s e a r c h -c o m m a n d , but only after determining whether the previous
command executed in the Editor was also in the category :e m a c s -s e a r c h .

Creating Editor Commands

2-13

• If SO, "My EMACS Forward Search" calls FORWARD-SEARCH-COMMAND with two
arguments: the prefix and a string that is the current value of "Last Search
String".

• If n o t , "My EMACS Forward Search" C a l l s FORWARD-SEARCH-COMMAND w i t h o n l y a
p r e fix a r g u m e n t, th u s r e q u ir in g fo r w a r d - se a r c h - c o m m a n d to p r o m p t fo r th e
n e e d e d s t r in g .

2-14

Creating Editor Commands

Chapter 3

Binding Commands to Keys and Pointer Actions
The most common way to extend the VAX LISP Editor is to bind Editor
commands to keys and key sequences. You can then use the bound keys or
sequences to invoke the commands within the Editor.
Many of the commands provided with the Editor are bound. The bindings may be
to graphic or control characters, keyboard escape sequences, function or keypad
keys, or some combination of these keys. Commands can also be bound to actions
of a pointing device provided with the AI VAXstation. All bindings supplied by
Digital are listed in Appendixes B and C, arranged both by command name and
by key or key sequence.
A key binding or pointer-action binding exists within an Editor context (that is,
within a particular style or buffer or in the global Editor context). The key or
pointer action will invoke the command only when the appropriate context is
active in the Editor. If more than one context is active at a time and if a key or
pointer action is bound to different commands in these contexts, only one binding
will be visible. (See VAX LISP/VMS Program Development Guide for a discussion
of context and shadowing as they appear to the interactive user.)
You can change the bindings supplied by Digital and bind commands that are not
currently bound.
• To bind a key or key sequence to an Editor command, you call the function
b i n d -c o m m a n d from LISP code. To delete a key binding, call u n b i n d -c o m m a n d .
• To bind a pointer action to an Editor command, you call the function
b i n d -p o i n t e r -c o m m a n d from LISP code. To delete a pointer-action binding,
call u n b i n d -p o i n t e r -c o m m a n d .
This chapter introduces the techniques of binding commands with these two
functions. The topics covered are:
• Using b i n d -c o m m a n d
— The command to be bound
— The key or key sequence to be bound
— The binding context
• Using b i n d -p o i n t e r -c o m m a n d
— Specifying a pointer action
— Specifying a button state
— Getting the state of the pointer

Binding Commands to Keys and Pointer Actions

3-1

NOTE

The Editor’
s cancel character—initially Ctrl/C— is not established with
b i n d -c o m m a n d and is not context-dependent. This global association
cannot be shadowed by Editor command bindings to the same
character. Tb change the Editor’
s cancel character, you use s e t f with
the function c a n c e l -c h a r a c t e r (see Part III for a description of this
function).

3.1 Using BIND-COMMAND
b i n d -c o m m a n d takes a command specifier, a key or key sequence, and an optional
context specifier. Its format is:

BIND-COMMAND c o m m a n d k e y - s e q u e n c e &OPTIONAL c o n t e x t
b i n d -c o m m a n d binds the key-sequence to the command in the specified (or default)
context. For example:

(bind-command "View File" #\AV)

This form binds the key Ctrl/V to the command "View File" supplied by Digital,
which has no binding in the Editor as provided. Since no context argument is
specified, the binding is global by default.
Note that b i n d -c o m m a n d is one of the few symbols related to the Editor accessible
in the u s e r package. If you include any other symbols related to the Editor
in a b i n d -c o m m a n d form, you must reference them in the e d i t o r package (see
Section 1.3.5).
The sections that follow discuss each of the parameters of b i n d -c o m m a n d in turn:
• The command to be bound
• The key or sequence to be bound
• The binding context

3.2 The Command to Be Bound
You can specify any Editor command as an argument to b i n d -c o m m a n d ,including:
• New user-defined commands
• Commands defined by Digital that are not bound
• Any command currently bound to another key or sequence.
You reference the command to be bound by means of any of the three kinds of
command specifier (see Section 1.3.3.2):
• The command’
s display name
• The command’
s symbol
• A form that evaluates to the function associated with the command

3-2

Binding Commands to Keys and Pointer Actions

For instance, the following three forms are equivalent. All three bind the
command "View File" to CtriV in the global context. (The first and third o f these
forms are equal in efficiency; the middle form, which uses the symbol specifier, is
very slightly faster.)
(bind-command "View File" #\AV)
(bind-command 'view-file-command #\AV)
(bind-command (find-command "View File") #\AV)

You change an existing binding to a command in the same way that you establish
a new binding. You may prefer to delete the old binding (using the function
unbind-command) before rebinding a command, but this is not required. For
instance, if you were to bind the command "P a u s e Editor" to Ctrl/A, then both
Ctrl/A and the original binding, Ctrl/X Ctrl/Z, would invoke "P a u s e Editor".
However, if you overwrite a command supplied by Digital, any key bindings
to the original command continue to invoke the function associated with the
original command rather than the function associated with the new command.
For instance, if you were to implement your own version of a "Next window"
command, the sequence Ctrl/X Ctrl/N would continue to invoke the function NEXTWINDOW-command supplied by Digital. To have the sequence Ctrl/X Ctrl/N invoke the
function associated with your new "Next window" command, you would need to
rebind that key sequence to the new command by means of a subsequent call to
BIND-COMMAND.

3.3 The Key or Key Sequence to Be Bound
Commands are actually bound not to keys but to the characters generated by
those keys. Most keyboard keys generate single characters; function keys and
keypad keys generate sequences of characters.
You can bind a command to any character in the 8-bit extended ASCII character
set (the DEC Multinational Character Set), with the few exceptions noted below.
You can also bind a command to any valid LISP sequence of these characters.
LISP sequences include lists and vectors containing characters, as well as strings.
The remainder of this section discusses the key-sequence argument to b i n d command:

•

How to choose a key or sequence to bind

• How to specify character keys, function and keypad keys, and combinations of
these keys

3.3.1

Choosing a Key or Sequence
In choosing a character key or key sequence to bind to a command, keep in mind
several considerations:
• You cannot bind the characters As and AQ, which lock and unlock your
terminal. This is a limitation of the operating system.
• You should not bind the current cancel character, which is initially Ac.
• It is generally not good practice to bind graphic characters or sequences that
begin with graphic characters. Every graphic character key is bound to the
command "Self insert", which inserts that character as text. Rebinding a
character will supersede the "Self insert" binding and leave you unable to
insert that character as text except by quoting it.
Binding Commands to Keys and Pointer Actions

3-3

As the last item suggests, the operation of b i n d -c o m m a n d destructively modifies
any previous binding of a key or sequence to a command (in the same context).
For instance, if you were to rebind the sequence Ctrl/X Ctrl/Z to a new command
(assuming the global context), then that sequence will no longer invoke "Pause
Editor". In choosing keys to bind, take care not to modify any previous bindings
that you wish to keep.
Similarly, you will lose bindings if you bind a key or sequence that begins another
bound sequence. For instance, if you were to bind Ctrl/X to a command, then the
bindings supplied by Digital (in the same context) that begin with Ctrl/X (such as
Ctrl/X Ctrl/Z for "Pause Editor") will be inaccessible.

3.3.2

Specifying a Character Key or Sequence
A character key can be specified with the usual LISP character syntax. For
control characters and other nongraphic characters, you use the printed represen
tation. For example, to bind the graphic character A, you write:
(bind-command "Self Insert" #\A)

l b bind the nongraphic character aa, you write:
(bind-command "Transpose Previous Characters" #\AA)

To bind a sequence of characters, you use the LISP syntax for the LISP sequence
you intend to use: vector, string, or list. A character sequence can include a
graphic character without interfering with the "Self insert" binding as long as
the graphic character does not begin the sequence. The following two examples
show vectors that combine graphic and nongraphic characters:
(bind-command "Name of Command" '#(#\AX #\w))
(bind-command "Name of Command" '#(#\escape #\a))

The first form binds the specified command to the sequence Ctrl/X w; the second
binds it to the sequence Escape a.
Note that case does not matter in specifying the printed representations of
nongraphic characters (such as Ax and ESCAPE). Case does matter, however, in
specifying graphic characters (such as w and a).

3.3.3

Specifying a Function Key, Keypad Key, or Sequence
There is no essential difference between binding a command to a character
sequence and binding it to a function key or keypad key (or sequence), since these
keys generate sequences of characters.
Appendix D identifies the character sequences generated by the function keys
and keypad keys on Digital VT100 and LK-201 keyboards. You can specify these
sequences as vectors (or other LISP sequences) in b i n d -c o m m a n d forms, as shown
in the previous section.
For instance, the Gold key (keypad PFl) generates the character sequence e s c a p e

o p and keypad 1 generates e s c a p e o q .The form that binds the sequence keypad

PFl 1 to the command "EDT Change Case" is:

(bind-command "EDT Change Case" '#(#\escape #\0 #\P #\escape #\0 #\q))

Note that this binding takes place in the Editor’
s global context, rather than
in "e d t Emulation" style. See Section 3.4 for the means of specifying a context
argument to b i n d -c o m m a n d .

3-4

Binding Commands to Keys and Pointer Actions

You can also combine character keys and function or keypad keys in a LISP
sequence and pass that sequence to b i n d -c o m m a n d . For instance, the following
form binds a vector that contains the characters generated by keypad PF1 and
keyboard h:
(bind-command "Name of Command" '#(#\escape #\0 #\P #\h))
The command w ill now be invoked by pressing the key sequence PF1 h.

3.4 The Binding Context
b i n d -c o m m a n d binds a key or sequence to a command within a particular Editor

context. The key or sequence will invoke the specified command only when that
context is active in the Editor. For instance, if you try to use "e d t Emulation"
keypad bindings when only "e m a c s " style is active, the Editor will consider the
keys unbound.
The binding context can be any one of the following:
• Global, the default context, which means that the key binding exists
universally within the Editor
• A style, which means that the key will invoke the specified command only
when that style is active in the current buffer
• A buffer, which means that the key will invoke the specified command only
when that buffer is current in the Editor
Since more than one context is often active in the Editor at any given time—
global, a major style, one or more minor styles, and a buffer, for instance—some
command bindings can be shadowed by other bindings to the same keys
in different contexts. The Editor searches through the active contexts in a
predetermined order to identify the correct command for a key sequence.
This section describes the means of specifying a context in LISP code, as well as
the Editor’
s search hierarchy for locating the correct binding when you use a key
sequence to invoke a command.

3.4.1

Specifying the Binding Context
The context a r g u m e n t t o b i n d - c o m m a n d i s s p e c i f i e d i n o n e o f t h e s e w a y s :
• The k e y w o r d : g l o b a l
• A list beginning with the keyword : s t y l e followed by a style specifier
• A list beginning with the keyword :b u f f e r followed by a buffer specifier
can take only one context argument at a time. To bind a command
in more than one style or other context, you need to write a b i n d - c o m m a n d form
for each context.
b i n d - com m and

3.4.1.1

Global

The global context is used for very basic Editor commands that enable you to
function in the Editor even with no style active. Examples are the commands
bound to the arrow keys, the Return key, and the Delete key, as well as "Self
Insert", "Pause Editor", and "Execute Named Command".

Binding Commands to Keys and Pointer Actions

3-5

Since : g l o b a l is the default context argument for b i n d -c o m m a n d , the following
two examples are equivalent:
(bind-command "Pause Editor" '#(#\AX #\AZ) :global)
(bind-c o m m a n d "Pause Edit o r "

' # (#\AX # \ AZ))

The two forms are also equal in efficiency.
3.4.1.2

Style

Styles are the most commonly used binding contexts. Your major style usually
would include bindings to all the commands you commonly invoke for general
editing. Minor styles can be seen as smaller sets of special-purpose bindings,
such as those you use only for editing the syntax of a particular language.
A style argument to b i n d -c o m m a n d is specified as a list beginning with the
keyword : s t y l e followed by a style specifier. For example:
'(:style "EDT Emulation")
' (:style edt-emulation)
(list .-style (variable-value "Default Major Style"))
'(:style , (variable-value "Default Major Style"))

The Editor variable "Default Major style" is set to a particular style object
(initially, "EDT Emulation").
3.4.1.3

Buffer

Some commands may be used only in the context of a certain buffer, and it may
be convenient to have their key bindings local to that buffer. For instance, the
buffer "General Prompting", supplied by Digital, contains buffer-local bindings
of commands that pertain to interactive user input, such as "Prompt Complete
String" and "Prompt Help".
A buffer argument to BIND-c o m m a n d is specified as a list beginning with the
keyword :b u f f e r followed by a buffer specifier. For example:
'

(sbuffer "Gen e r a l Prompting")

' (:buffer editor-prompting-buffer)
(list tbuffer (current-buffer))

The function c u r r e n t -b u f f e r returns the buffer current in the Editor.

3.4.2

Search Order and Shadowing
To locate the correct command binding for a key sequence, the Editor searches
through all the active contexts in the following order:
1. Current buffer
2. Minor styles active in that buffer beginning with the most recently activated
3. Major style of that buffer
4. Global context
The Editor will use the first command binding that it encounters in this search;
any other bindings will be shadowed.

3-6

Binding Commands to Keys and Pointer Actions

For instance, if you have "EMACS" style active in the current buffer, as either
major or minor style, you cannot use the global binding of Ctrl/Z to invoke "Execute
Named Command". Because style precedes global in the search order, the "emacs"
binding of Ctrl/Z to "Scroll window Down" shadows the global binding.
For keys that lack multiple bindings in the active contexts, no shadowing occurs.
For instance, the sequence Ctrl/X Ctrl/N invokes its global binding, "Next Window",
even when you have "edt Emulation" active as major style and both "EMACS" and
"VAX lisp" as minor styles. None of these styles has a conflicting binding for that
sequence.
Because of the small number of conflicting bindings involved, it is feasible to
use all three styles provided by Digital— "e d t Emulation", "e m a c s ", and "VAX
l i s p "— at once. If only "e d t Emulation" and "v a x l i s p " are active, then most
global bindings are visible as well, "e m a c s ", however, shadows a greater number
of global bindings.

3.5 Using BIND-POINTER-COMMAND
By calling b i n d -p o i n t e r -c o m m a n d , you can bind various actions of a mouse or
other pointing device to Editor commands. When the pointer cursor is in the
current Editor window, the Editor will respond to pointer actions by invoking the
bound commands. You cannot program the Editor to respond to pointer actions
that occur when the pointer cursor is outside the current Editor window.
b i n d -p o i n t e r -c o m m a n d must be referenced in the e d i t o r package.

Its format is:

BIND-POINTER-COMMAND c o m m a n d p o in te r - a c tio n &KEY CONTEXT :BUTTON-STATE

The command argument is a specifier of the command to be bound. Any valid
command argument for b i n d -c o m m a n d can also be used with b i n d -p o i n t e r c o m m a n d (see Section 3.2).
The possible values for the : c o n t e x t keyword are identical to those for the
context parameter to b i n d -c o m m a n d (see Section 3.4). The default binding context
is

: GLOBAL.

For instance, to invoke a command by means of a specified pointer action in "VAX
l i s p " style, you would write:
(BIND-POINTER-COMMAND "Describe Word at Pointer" p o in te r - a c tio n
:CONTEXT '(:STYLE "VAX LISP"))

The remainder of this section discusses the pointer-action parameter and the
:b u t t o n -s t a t e keyword. This section also explains the procedure for storing and
retrieving the state of the pointing device at a given time.

3.5.1

Specifying a Pointer Action
The pointer actions you can use to invoke Editor commands are:
• A movement of the pointer cursor
• A transition (depressing or releasing) of a pointer button

Binding Commands to Keys and Pointer Actions 3-7

3.5.1.1

Pointer Cursor Movement

A pointer movement in the Editor is defined as a movement across at least one
character in any direction. Small movements of the pointer cursor (within a
character) are not significant.
You specify movement of the pointer cursor by supplying the keyword :m o v e m e n t
as the pointer-action argument. For instance:
(bind-pointer-command "Name of Command" :movement)

If you want to have the command invoked by a movement only when one or more
buttons are depressed, you supply a value for :b u t t o n - s t a t e . See Section 3.5.2.
3.5.1.2

Pointer Button Transitions in UIS

The buttons on a supported pointing device are indicated by the symbols for
button constants. The symbols are in the package uis, and they take the form
P O iN T E R -B U T T O N -n , beginning with p o i n t e r - b u t t o n - i for the leftmost button.
(See VAX LISP Interface to VWS Graphics for further information on button
constants.)
NOTE

The description of pointer buttons assumes 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 for this discussion and in
the Appendix B icon representations.
To specify a downward transition of a particular button, you simply supply the
appropriate button constant as the pointer-action argument. For instance, to
bind a command to a downward transition of the middle button on a three-button
mouse, you would write:
(editor:bind-pointer-command "Name of Command" uis:pointer-button-2)

Note that this form uses symbols from both the e d i t o r package and the u i s
package.
To specify an upward transition, you supply a list of one element that is the
appropriate button constant. For instance, to bind a command to an upward
transition of the middle button on a three-button mouse, you would write:
(editor:bind-pointer-command "Name of Command" (list uis:pointer-button-2))

or
(editor:bind-pointer-command "Name of Command" '(,uis:pointer-button-2))

These are the most common methods of specifying button transitions. For other
methods, see the description of b i n d - p o i n t e r - c o m m a n d in Part III.
3.5.1.3

Pointer Button Transitions in DECwindows

The description of pointer button transitions under UIS works under DECwindows
if UIS is present in your LISP. If not, you should use the keywords :b u t t o n - l,
: b u t t o n - 2 . . . :BUTTON-5 instead of the uis:poiNTER-BUTTON-n symbols. Use of
these keywords will not work under UIS.

3-8

Binding Commands to Keys and Pointer Actions

3.5.2

Specifying a Button State
In the examples above, the assumption is that all pointer buttons except one
specified in the pointer-action argument are in the up state. The :b u t t o n -s t a t e
keyword permits chording of pointer buttons to invoke commands. That is, you
can specify that the pointer-action argument is to invoke the command only if one
or more pointer buttons are depressed when the pointer action occurs.
For instance, in the Editor as provided under UIS, the following actions occur:
• Depressing the middle button invokes the command "e d t Cut" (in "e d t
Emulation" Style)
• Depressing the middle button while the left button is depressed invokes the
command "EDT Paste at Pointer" (in "EDT Emulation" style)
For UIS, the value for the :b u t t o n -s t a t e keyword is a button constant or the
l o g a n d of two or more button constants. For DECwindows, it is a button keyword
or a list of button keywords. These keywords indicate the button(s) that must be
in a down state when the specified pointer-action occurs.
For instance:
• Tb specify that the left button is depressed under UIS:
:button-state

uis:pointer-button-1

under DECwindows:
:button-state :button-l

• To specify that the left and right buttons are depressed under UIS:
:button-state

(logand

uis:pointer-button-1
uis:pointer-button-3)

under DECwindows:
:button-state '(:button-l :button-3)

If the pointer-action argument is a button transition, then any value supplied for
that button in the :b u t t o n -s t a t e argument is ignored.
The binding of "EDT Paste at Pointer" under UIS—depressing the middle button
while the left button is depressed— is established by:
(editor:bind-pointer-command "EDT Paste at Pointer"
uis:pointer-button-2
:button-state uis:pointer-button-1
:context '(:style "EDT Emulation"))

The global binding of "Move Point and Select Region" \inder UIS—move pointer
while the left button is depressed—is established by:
(editor:bind-pointer-command "Move Point and Select Region"
:movement
:button-state uis:pointer-button-1)

The button state in a chorded pointer binding is a static state of the button
or buttons indicated. You should, however, consider the transitions (prior
pressing and subsequent releasing) that establish and end that state. Either of
these transitions might be bound to a command supplied by Digital (see VAX
LISP/VMS Program Development Guide for initial pointer bindings). Or, you
might wish to bind one or both transitions to commands.

Binding Commands to Keys and Pointer Actions 3-9

3.5.3

Getting the State of the Pointer
You can retrieve the state of the pointing device—which includes the position of
the pointer cursor, the up-or-down state of each button, and other information—
for a given point in time by calling g e t -p o i n t e r -s t a t e .This function is described
in full in Part III.
g e t -p o i n t e r -s t a t e returns a pointer-state object that contains information about
the state of the pointer at the time the function is called. If g e t -p o i n t e r -s t a t e
is called from within an Editor command and if that command was invoked by a
pointer action, the function returns the state of the pointer that existed when the
pointer action occurred. If the pointer action that invoked the command was a
button transition, the pointer-state object contains the state of the buttons at the
end of the transition.

3.5.3.1

Testing Pointer State
g e t -p o i n t e r -s t a t e is useful in commands that take different actions depend
ing on some feature of the pointer state. For instance, the command "Yank
at Pointer", supplied by Digital, tests to find whether the pointer cursor is
indicating a text position (line and character position).

• If so, "Yank at Pointer" moves the current buffer point to that text position
and inserts the current region in the kill ring at the modified buffer point.
• If the pointer cursor is indicating an empty position in a line, "Yank at
Pointer" moves the current buffer point to the last character position in that
line and inserts the kill region.
• If the pointer cursor is not indicating a line, "Yank at Pointer" moves the
current buffer point to the last character position in the current buffer and
inserts the kill region.
"Yank at Pointer" calls g e t -p o i n t e r -s t a t e to store the pointer-state informa
tion, and calls p o i n t e r -s t a t e -t e x t -p o s i t i o n to retrieve the text position (line
and character position) stored in the pointer-state object. A possible way to
implement "Yank at Pointer" is:
(define-command (yank-at-pointer-command :display-name "Yank at Pointer")
(prefix)
(declare (ignore prefix))
(let ((state (get-pointer-state)))
;; Get the text position of the pointer cursor and bind the two values
;; to LINE and CHARPOS.
(multiple-value-bind (line charpos)
(pointer-state-text-position state)
;; If there is a line, move buffer point to the CHARPOS or to the end
;; of that line.
(if line
(move-mark-to-position (current-buffer-point)
(or charpos (line-length line))
line)
;; If there is no line, move buffer point to end of the buffer.
(buffer-end (current-buffer-point)))
;; After the buffer point is modified, call YANK-COMMAND.
(yank-command nil))))

3-10

Binding Commands to Keys and Pointer Actions

If "Yank at Pointer" has been invoked by means of its pointer binding in "e m a c s "
style (depress middle button while left button is depressed), the command uses
the pointer state that existed when this pointer action occurred. If "Yank at
Pointer" has been invoked by name, it uses the pointer state in existence when
the command executes.
3.5.3.2

Accessing Pointer-State information

The command "Yank at Pointer" calls p o i n t e r -s t a t e -t e x t -p o s i t i o n to retrieve
the line and character position of the pointer cursor. Other information contained
in the pointer-state object and the corresponding accessing functions are:
• The window position (display row and display column in a given window)—
POINTER-STATE-WINDOW-POSITION

• The pointer action, if any, that invoked the currently executing command—
POINTER-STATE-ACTION

• The state of the pointer buttons at the time g e t -p o i n t e r -s t a t e was called—
POINTER-STATE-BUTTONS

Further information on g e t -p o i n t e r -s t a t e and on each of these accessing
functions appears in Part III.
Note that the function p o i n t e r -s t a t e -b u t t o n s can be used to implement chording in pointer bindings. When called from within an Editor command, the form
(pointer-state-buttons (get-pointer-state))

returns the state (up or down) of each pointer button at the time the command
was invoked (see Part III). You can use this information to have the command
take different actions, depending on whether a specified button was depressed
when a pointer action invoked the command.

Binding Commands to Keys and Pointer Actions 3-11

Chapter 4

Text Operations
Text consists of the characters you normally see when you enter the Editor and
display a buffer. The essential operations any editor must allow you to perform
on text are:
• Indicating the position occupied by any given character
• Inserting, deleting, and changing characters
• Moving from one character position to another
This chapter introduces the data types and functions you use to program these
kinds of operations in the VAX LISP Editor.
You can envision text in the VAX LISP Editor as a group or region of contiguous
characters. The characters can be any of those in the ASCII 8-bit extended
set (the DEC Multinational Character Set); they can include whitespace and
nongraphic characters as well as alphanumeric characters.
Each character in the Editor occupies a specifiable position. You can access
characters either individually (that is, at one position) or in groups (that is,
between two positions). You can also manipulate characters—insert them, delete
them, copy them—either individually or in groups. Finally, you can move around
within text either by accessing specified character positions or by searching for
particular characters or sequences of characters.
These sets of text-related capabilities in the VAX LISP Editor are introduced in
the following order:
1.

Operations on a p articu lar character position

2. Operations on a group of contiguous characters
3. Moving and searching operations
4. Miscellaneous operations
This chapter introduces the following Editor data types:
• Marks
• Regions
• Attributes
• Lines
Part II describes these objects in more detail. Reference information concerning
the functions and macros that operate on these objects appears in Part III.

Text Operations 4-1

Buffers are another relevant Editor data type: most text is contained in buffers.
However, most text operations are not operations on a buffer object, but rather
on marks, regions, lines, or characters that may be contained in a buffer object.
Operations on buffers are covered in Section 4.2.5 and in Part II.
Recall that the symbols for Editor objects provided by Digital must be referenced
in the e d i t o r : package.

4.1

Operations on a Character Position
Editor objects called “
marks”are used to reference the position of any character
in text. An example of a mark is the buffer point, which is the point of attention
in each buffer at which most text operations occur. In the current buffer, this
mark—the current buffer point—is tracked by the screen cursor.
Every buffer you enter or create in the Editor contains at least three marks.
Besides the buffer point, each buffer contains two marks that point to the
beginning and end of text in that buffer. Tb reference positions in text, you can
use the existing marks, or you can create new marks. Creating marks is covered
in Section 4.4.1.
By using a mark, you can perform several operations:
• Retrieve and change a character
• Insert a character
• Insert a string of characters
• Delete one or more characters
In the examples in this section, the variable m a r k is assumed to be bound to an
Editor mark.

4.1.1 Retrieving and Changing a Character
For the purpose of text operations, you should think of a mark as pointing
between two adjacent characters. A mark can also point before the first character
in a buffer or after the last character.
You can retrieve the characters on either side of a mark by means of the functions
n e x t -c h a r a c t e r and p r e v i o u s -c h a r a c t e r . Using s e t f ,you can also change the
specified character.
(setf (next-character mark) #\W)

This form changes the character to the right of the mark to w. If your text consists
of a b cd and the mark is pointing between b and c, this form changes the c to a w.
The text then reads a b w d .

4.1.2 Inserting a Character
You can add a new character to text by means of the function i n s e r t -c h a r a c t e r ,
i n s e r t -c h a r a c t e r takes a mark and a character. It inserts the specified charac
ter at the mark—that is, between existing characters.
For instance:
(insert-character mark #\W)

4-2

Text Operations

If t h e m a r k i s p o i n t i n g b e t w e e n b a n d c i n t h e t e x t a b c d , e x e c u t i n g t h i s f o r m
c h a n g e s th e te x t to abw cd.

To p e r f o r m t h e s a m e o p e r a t i o n a t t h e c u r r e n t b u f f e r p o i n t , y o u c o u l d r e f e r e n c e
t h a t m a r k b y c a llin g th e fu n c tio n

c u r r e n t - b u f f e r -p o in t

w ith n o a r g u m e n ts :

(insert-character (current-buffer-point) #\W)

4.1.3

Inserting a String of Characters
allows you to insert only one character at a time. By using
you can insert any number of characters at the specified mark.

in s e r t - ch a ra cter
in s e r t - s t r in g ,

(insert-string mark "ABCD EFGH IJKL")

If your text consists of xx and the mark is pointing between the two characters,
this form changes the text to x a b c d e f g h i j k l x .
If t h e s t r i n g a r g u m e n t t o i n s e r t - s t r i n g c o n t a i n s n e w l i n e c h a r a c t e r s , m u l t i p l e
lin e s o f te x t a r e in se r te d .

(insert-string mark "ABCD
EFGH")

This form inserts a b c d at the mark, breaks the line, and inserts e f g h at the
beginning of the next line. Any text following the mark in the original line will
appear after e f g h .
An example of a string that might be inserted in text is the string you enter in
response to a prompt. For instance:
(insert-string (current-buffer-point)
(simple-prompt-for-input "Enter input; "))

This form takes the user’
s response to the prompt and inserts it as text at the
current buffer point.

4.1.4

Deleting Characters
The function d e l e t e - c h a r a c t e r s takes a mark and an optional integer that
defaults to l. It deletes the specified number of characters after the mark, or
before the mark if the integer is negative. If there are not enough characters
after (or before) the mark, d e l e t e - c h a r a c t e r s does not modify the text.
For example, to delete the next five characters after a specified mark, you would
write:
(delete-characters mark 5)

To delete the character preceding the current buffer point, you would write:
(delete-characters (current-buffer-point) -1)

When deleting a character, you may want to save the character so that you can
reinsert it later. The following forms show a “
delete and save”operation and a
subsequent reinsertion operation:
;;; Define a variable to which to bind a deleted character.
(defvar *saved-character*)
; ;; Bind the character following the current buffer point to the
;;; variable.
(setf *saved-character* (next-character (current-buffer-point)))
Text Operations

4-3

;;; Delete the character following the current buffer point,
(delete-characters (current-buffer-point))

;;; Later, insert the character bound to the variable at the
;;; then-current buffer point.
(insert-character (current-buffer-point) *saved-character*)

4.2

Operations on a Group of Characters
Editor objects called regions indicate groups of contiguous characters. The text in
a region can be accessed and manipulated as a unit.
A region is defined by two marks that indicate the character positions where the
region begins and ends. To create a region, you write:
(make-region markl mark2)

Every buffer contains at least one region, which is defined by the marks that
indicate the positions where text begins and ends in that buffer. This region is
called the buffer region.
Any number of regions can be created within a buffer region. They may overlap
in arbitrary ways, and one may be completely contained within another. Since
regions may share text, any alterations you do to the text in one region will affect
other regions that share that text.
Using regions, you can do these operations:
• Insert a block of text
• Copy a block of text
• Delete a block of text
• Delete and save a block of text
• Write a block of text to a file
You can perform these operations on any region, lb perform these operations on
a buffer, you perform them on the buffer region of that buffer.

4.2.1 Inserting a Region
The function i n s e r t -r e g i o n enables you to insert a specified block of text as a
unit, i n s e r t -r e g i o n takes a region and a mark at which to insert that region in
text. The text inserted is a copy of the specified region; the original region is not
altered.
For example:
(insert-region (current-buffer-point)

(make-region markl mark2))

This form defines a region from the two specified marks, which allows you to
treat the text between those marks as a single unit. The text in this region is
copied, and the copy is inserted at the current buffer point.

4-4

Text Operations

4.2.2

Copying a Region
The function c o p y - r e g i o n takes a region and returns a new region that contains
a copy of the text in the specified region. The new region is disembodied, in that
it is not contained in a buffer. Operations performed on the copy do not affect the
original region, and vice versa.
The following forms illustrate the process of copying and saving a specified region
for later insertion elsewhere. The original region is not deleted or otherwise
altered.
;;; Define a variable to which to bind a region.
(defvar *saved-region*)
;;; Copy a region and bind it to the variable.
(setf *saved-region* (copy-region (make-region markl mark2)))
;;; Later, insert the copied region at the current buffer point.
(insert-region (current-buffer-point) *saved-region*)

4.2.3

Deleting a Region
Regions are used commonly to indicate blocks of text to be deleted. You can delete
the text in a region by calling either d e l e t e -r e g i o n or d e l e t e -a n d -s a v e -r e g i o n
with a region argument.
The function d e l e t e -r e g i o n takes a region and deletes the text in it, leaving an
empty region. It returns n i l .
(delete-region (make-region markl mark2))

If you wish to retain a copy of the text in a deleted region so that you can reinsert
it elsewhere, you call d e l e t e -a n d -s a v e -r e g i o n . This function deletes the text in
a region and returns a disembodied region that contains a copy of the deleted
text.
(insert-region (current-buffer-point)
(delete-and-save-region (make-region markl mark2)))

In this example, d e l e t e -a n d -s a v e -r e g i o n deletes the text in the region between
and MARK2 and returns a copy of the deleted text. The disembodied region
containing the copied text is passed to i n s e r t -r e g i o n , which inserts it at the
current buffer point.

marki

4.2.4

Writing a Region to a File
The function w r i t e -f i l e -f r o m -r e g i o n takes a file name (pathname or
namestring) and a region. It writes the specified region to the specified file.
For instance:
(write-file-from-region "Myfile.lsp" (make-region markl mark2))

This form writes the text between the specified marks to a file named
MYFILE.LSP.

Text Operations

4-5

4.2.5

Operating on Buffers
Text operations that appear to be performed on buffers actually are performed on
the buffer regions of those buffers. Some operations you can perform on buffer
regions include:
• Deleting the text in a buffer
• Inserting the contents of one buffer into another
• Writing the contents of a buffer to a file
• Inserting the contents of a file into a buffer
These operations use the same region-manipulating functions that apply to
smaller regions within a buffer. The difference here is that the region argument
you supply is the buffer region. The function b u f f e r - r e g i o n takes a buffer and
returns the buffer region of that buffer.

4.2.5.1

Deleting the Text in a Buffer

To delete all the text in a buffer, you simply delete the text in the associated
buffer region.
(delete-region (buffer-region (current-buffer)))

This form deletes the text in the current buffer. The buffer itself and the empty
buffer region remain.
4.2.5.2

Inserting One Buffer into Another

To insert the text from one buffer into another buffer, you call the function
i n s e r t - r e g i o n . As arguments, you supply a mark in one buffer and the buffer
region of another buffer.
(insert-region (current-buffer-point)

(buffer-region buffer2))

This form inserts a copy of the buffer region of BU FFER2 into the current buffer at
the current buffer point. The content of BUFFER2 is not affected by this operation,
and subsequent changes to the text in BU FFER2 and in the inserted region do not
affect one another.
4.2.5.3

Writing a Buffer to a File

To w r i t e a b u f f e r t o a f i l e , y o u c a l l w r i t e - f i l e - f r o m - r e g i o n a n d p a s s i t a f i l e
n a m e ( p a t h n a m e o r n a m e s t r in g ) a n d t h e b u f f e r r e g i o n o f a s p e c i f i e d b u ffe r .

(write-file-from-region "Myfile.lsp" (buffer-region (current-buffer)))

This form writes the contents of the current buffer to a file named MYFILE.LSP.
4.2.5.4

Inserting a File into a Buffer

The function i n s e r t - f i l e - a t - m a r k is similar to i n s e r t - s t r i n g , in that it inserts
text at a specified mark. The mark can indicate any text position in a buffer or
disembodied region; the text inserted is the content of a specified file, i n s e r t f i l e - a t - m a r k is used commonly to insert a file into a buffer.
For example:
(insert-file-at-mark "Myfile.lsp" (current-buffer-point))

4-6

Text Operations

This form inserts the contents of the file MYFILE.LSP into the current buffer at
the current buffer point.

4.3

Moving and Searching Operations
A number of functions exist that “
move”marks. That is, these functions modify a
mark so that it specifies a different text position.
There are three basic ways to move marks:
• By specifying a new character position
• By searching for a specified string of characters
• By searching for a character with a particular property

4.3.1 Moving by Character Positions
Several functions take a mark and alter it to point to a specified character
position. The character position can be specified either by “
counting”from the
m ark’
s initial position or by referencing another mark.
To move a mark one or more character positions away from its current position,
you call:
•

m ov e-m ark-a f t e r

m o v e s a m a r k to th e p o s it io n th a t fo llo w s its in itia l p o s itio n

•

m ov e-m ark-b e f o r e

m o v e s a m a r k to th e p o s it io n th a t p r e c e d e s it s in itia l

p o s it io n
•

ch a ra cter-o f f se t

ta k e s a c o u n t a n d m o v e s th e m a r k fo rw a rd th a t m a n y

p o s it io n s ( b a c k w a r d i f th e c o u n t is n e g a tiv e )

You can also move a mark to point to the position specified by another mark.
Some functions you can use are:
•

b u f f e r - end

m o v e s a m a r k t o t h e e n d o f t h e t e x t in a s p e c ifie d b u ffe r

•

bu ffer-start

•

m o v e - m ark

m o v e s a m a r k to th e b e g in n in g o f th e te x t in a s p e c ifie d b u ffe r

m o v e s a m a r k to th e p o s itio n o c c u p ie d b y a n y o th e r s p e c ifie d m a r k

M oving by character position is illu strated in a new function th a t transposes the

pair of characters before a specified mark. This function also illustrates accessing
and manipulating individual characters.
(defun transpose-characters (mark)
" Transposes the pair of characters before the specified mark."
;; Access the character before the mark and bind it to CHAR2.
(let ((char2 (previous-character mark)))
;; If there is a character before the mark, delete that character.
(when char2
(delete-characters mark -1)
;; If there is a character in the position now preceding the mark,
;; move to the position preceding that character and reinsert the
;; deleted character.
(cond ((previous-character mark)
(insert-character (move-mark-before mark) char2)
;; Move the mark back to its initial position.
(move-mark-after mark))

Text Operations

4-7

;; If there is no character in the position preceding the mark,
;; reinsert the deleted character at its initial position.
(t (insert-character mark char2))))))

The action of this function differs slightly from that of the command "Transpose
Previous Characters" supplied by Digital. One difference is that the command
supplied by Digital suppresses screen display of the separate text operations,
showing only the completed action. Display-related operations are discussed in
Section 5.4. Also, the command supplied by Digital creates a new mark for the
operation and disposes of the mark after the operation is completed. Creating
marks is discussed in Section 4.4.1.

4.3.2

Searching by Pattern
Searching by pattern enables you to move a mark to a specified string of char
acters within a region of text. The search can be forward or backward from the
m ark’
s initial position, and it can either consider or ignore case in determining
whether a text string matches the search string.
Ib perform a search by pattern, you call two functions:
•

m ake- s e a r c h -p a t t e r n

c o m p u t e s a p a ttern , in c lu d in g th e s t r in g to b e m a tch ed ,

th e d ir e c t io n o f th e se a rch , a n d w h e t h e r th e s e a r c h is c a s e - se n sitiv e
•

lo ca te-pattern

in itia te s a s e a r c h o p e r a tio n b e g in n in g a t a s p e c ifie d m a rk

a n d s e a r c h in g a c c o r d in g to th e p a r a m e te r s o f th e s p e c ifie d p a tte r n

This section illustrates the use of these functions to implement search operations.
4.3.2.1

Making a Search Pattern

Before beginning a search operation, you call m a k e - s e a r c h - p a t t e r n , which
computes and returns a search pattern. Its format is:
MAKE-SEARCH-PATTERN k in d d ir e c t io n str in g
&OPTIONAL r e u s e - p a tte r n

The kind argument can be either : c a s e - s e n s i t i v e or : c a s e - i n s e n s i t i v e . The
direction argument can be either :f o r w a r d or :b a c k w a r d . The string argument is
the string to be searched for. (The optional reuse-pattern argument is described in
Part III.)
For instance, to search forward for the string a b c d e , disregarding case, you could
begin with the following pattern:
(make-search-pattern :case-insensitive :forward "abcde")

4.3.2.2

Locating a Search Pattern

Tb initiate the search, you call l o c a t e - p a t t e r n . This function takes a search
pattern, such as that specified above, as well as a mark at which to begin the
search:
LOCATE-PATTERN m a rk s e a r c h - p a tte r n

searches for a text string that matches the specified search
pattern. If one is found, it changes the mark to point to the beginning of the
matched string.

lo ca te-pattern

4-8

Text Operations

A very simple search operation is illustrated by the following command:
(define-command (my-simple-search-command
:display-name "My Simple Search")
(prefix)
(declare (ignore prefix))
(locate-pattern (current-buffer-point)
(make-search-pattern
:case-insensitive
:forward
(simple-prompt-for-input
"Search for: "))))
"My simple Search" prompts for a search string, which it uses in making a search
pattern. It then searches forward for that string, beginning at the current buffer
point and disregarding case.

Note that this command searches only once. Tb locate more than one occurrence
of the string, you would need to invoke the command repeatedly. To search in the
opposite direction, you would need to write another command with :b a c k w a r d as
the direction argument to m a k e -s e a r c h -p a t t e r n .
4.3.2.3

Replacing a Pattern

You can also program the Editor to replace strings it locates through a search
operation. The function r e p l a c e -p a t t e r n is similar to l o c a t e -p a t t e r n except
that it takes a replacement argument—a new string with which to replace the
string it locates in the text:
REPLACE-PATTERN m ark search -pattern re p la c e m e n t
&OPTIONAL n

For example:
(replace-pattern (current-buffer-point)
(make-search-pattern
:case-sensitive
:backward
"This is a")
"This is not a")

This form searches backward through text from the current buffer point for
every case-matched instance of the search string. It deletes each matching string
and replaces it w ith the specified replacem ent string. (U n lik e l o c a t e - p a t t e r n ,
replace-pattern does not move the mark.)

The optional n argument to r e p l a c e -p a t t e r n allows you to specify how many
occurrences of the string should be replaced (see the full description of r e p l a c e p a t t e r n in Part III). The default action is to replace every instance in the
direction specified in the search pattern.

4.3.3

Searching by Attribute
Searching by attribute enables you to locate text entities such as words, whitespace, LISP forms, and so on. The Editor recognizes these entities by the
characters that define or delimit them. For instance, the Editor locates a word by
searching for a character that it recognizes as a word delimiter.
Characters acquire these added properties by means of Editor objects called
attributes. Some attributes provided with the Editor are "Word Delimiter",
"whitespace", and "l i s p Syntax". (Attributes can also be user-defined.) Once

Text Operations

4-9

an attribute is established in the Editor, all 256 characters have a value for that
attribute.
NOTE

Editor attributes should not be confused with character attributes
in Common LISP. The Editor ignores all Common LISP bit and
font information about characters. Editor attributes capture other
information specific to the Editor about the meaning of individual
characters.
You can think of Editor attributes on the analogy of a social attribute, such as
“
Political Party Member.”In contexts where you apply this attribute to people,
every person has a value for it. The values might be specified as r e p u b l i c a n ,
d e m o c r a t , w h i g , To r y , and so on. Another possible value is n o t -a -m e m b e r .
Similarly, every character in the Editor has a value for the attribute
"Whitespace". The possible values in this case are l and o, which you can
think of as i s -w h i t e s p a c e and i s -n o t -w h i t e s p a c e , respectively.
To carry out a search by attribute, the Editor tests each character in turn until it
locates one that has a particular value for the specified attribute. For example:
• To skip over whitespace to the next non-whitespace character, the
Editor searches for the next character with the value o for the attribute
"Whitespace".

• To find word breaks, the Editor searches for characters with the value l for
the attribute "Word Delimiter".
• To find the next list in LISP code, the Editor searches for the next character
with the value :LIST-i n i t i a t o r for the attribute "l i s p syntax".
To search by attribute in the Editor, you call the function l o c a t e -a t t r i b u t e .This
section introduces the following topics:
• Using LOCATE-ATTRIBUTE
• Mark and cursor behavior in an attribute search
• Using l o c a t e -a t t r i b u t e repeatedly
This discussion focuses on using attributes and attribute values supplied by
Digital. Information on creating new attributes and on changing attribute values
appears in Section 6.2.3 and in Part II.
4.3.3.1

Using LOCATE-ATTRIBUTE

The function l o c a t e -a t t r i b u t e is used to locate a character with a particular
attribute value. This function is described in full in Part III of this manual. Its
format, with only a few of its parameters, is:
LOCATE-ATTRIBUTE m a rk attribute
&KEY :TEST DIRECTION
l o c a t e -a t t r i b u t e scans the text in the specified direction to find a character
with a particular value for the specified attribute. The value of interest is one for
which the specified test function returns a non-NiL value. If such a character is
found, l o c a t e -a t t r i b u t e moves the mark to point to that character. The default
value for the keyword argument :DIRECTION is :FORWARD; the default function
used as the :TEST is p l u s p .

4-10

Text Operations

For example, to find the next word delimiter in a region of text, you could write:
(locate-attribute (current-buffer-point)
"Word Delimiter"
:test #'plusp
:direction :forward)

This form moves the current buffer point forward to the next character whose
"Word Delimiter" value is 1. The values are tested by passing them to the
predicate function p l u s p .The p l u s p function returns n i l if its argument is o and
T if its argument is greater than 0. The first character whose "Word Delimiter"
value is l satisfies the test, and the search stops.
behaves the same way when called with the argument
: b a c k w a r d ,but the search direction is reversed.

l o c a t e -a t t r i b u t e

(locate-attribute (current-buffer-point)
"Word Delimiter"
:direction :backward)

In this case, l o c a t e -a t t r i b u t e moves the current buffer point backward to the
first character whose "Word Delimiter" value satisfies the default test p l u s p .
To find the next character that is not a word delimiter, you change the test
function:
(locate-attribute (current-buffer-point)
"Word Delimiter"
:test #'zerop)

This form m oves the current buffer point to the next character that has the "Word
Delimiter" value o. The function zerop returns non-NiL only when its argument
is o.

4.3.3.2

Mark and Cursor Behavior

When using l o c a t e -a t t r i b u t e to move a mark, it is important to remember that
marks point between characters rather than to characters. Depending on the
direction of the search, the modified (or “
m oved”
) mark points either just before
or just after the character that has satisfied the test. The screen cursor, on the
other hand, always appears on the character just after the mark it is tracking
(the current buffer point).
A m ark’s behavior in an attrib u te search is sym m etrical— “m irror-im age”—

forward and backward. The cursor’
s behavior is not symmetrical.
For instance, imagine that the text string contains the current buffer point in
the position between j and K and that the cursor appears on K, as shown in
Figure 4—1.
Figure 4-1:

Before Moving the Mark

A B C D

E F G H

I jjß L

M N O P
MLO-002991

Text Operations

4-11

Then call l o c a t e -a t t r i b u t e (with its default arguments) to search ahead for the
first character with the value l for the attribute "Word Delimiter".
(locate-attribute (current-buffer-point) "Word Delimiter")

The test succeeds at the s p a c e after L, and the search stops. The mark is left
pointing just before the s p a c e , and the cursor is on it, as shown in Figure 4-2.
Figure 4-2:

Moving a Mark Forward

A B C D

N O P

E F G H

MLO-002992

If you evaluate the form again, l o c a t e -a t t r i b u t e does not move the mark. It
may appear, since the cursor is on the s p a c e , that the next word delimiter is the
s p a c e after p. However, the mark actually is positioned just before the s p a c e
indicated by the cursor. This character satisfies the test. (The following section
discusses how to call l o c a t e -a t t r i b u t e repeatedly.)
The backward-searching behavior of l o c a t e -a t t r i b u t e is a mirror image of its
forward-searching behavior. The symmetry is apparent when you consider mark
positions, but less apparent when you consider only cursor positions.
For instance:
(locate-attribute (current-buffer-point)
"Word Delimiter"
:direction :backward)

If the mark points, as before, between J and k, the first character to satisfy the
test is the space between h and i. Because the search direction is backward,
l o c a t e - a t t r ib u t e

m o v e s th e m a r k to th e p o s it io n b e t w e e n th e

spa ce

a n d t h e I.

The mark indicates the space character to its left, but the cursor, which is always
to the right of the mark, stops on the I (see Figure 4-3). Compare this cursor
behavior with the cursor behavior when locate-attribute searches forward.
Again, locate-attribute does not move the mark if called a second time. The
character that the mark is indicating is the space, which satisfies the test.
Figure 4-3:

A B C D

Moving a Mark Backward

M N 0 P
MLO-002993

4-12

Text Operations

4.3.3.3

Using LOCATE-ATTRIBUTE Repeatedly

Some higher-level functions and commands may invoke l o c a t e - a t t r i b u t e more
than once. For instance, w o r d - o f f s e t takes an optional count that indicates the
number of word breaks to be located. It invokes l o c a t e - a t t r i b u t e the number of
times specified.
When you invoke l o c a t e - a t t r i b u t e repeatedly, you need to consider the c a s e s
in which the mark already is indicating a character with the attribute value in
question. As shown above, l o c a t e - a t t r i b u t e does not move the mark when the
first character in the specified direction satisfies the test.
It is necessary, therefore, to include a test of the mark’
s position before invoking
An example of such a test follows:

l o c a t e -a t t r ib u t e .

(defmacro next-char-in-word-p (mark)
'(let ((next (next-character ,mark)))
(and next
(zerop (the fixnum (character-attribute "Word Delimiter" next))))))

The macro n e x t - c h a r - i n - w o r d - p tests whether the character after the mark
is part of a word, and thus not a word delimiter. That is, it tests whether that
character has the value o for the attribute "Word Delimiter".
Using this test, you can now write a command that invokes l o c a t e - a t t r i b u t e :
(define-command (capitalize-word-and-travel-command
:display-name "Capitalize Word and Travel")
(prefix)
;; Repeat the action if a prefix argument is supplied.
(dotimes (index (or prefix 1))
;; If the next character is a word delimiter, find the next
;; one after it that is not a word delimiter.
(unless (next-char-in-word-p (current-buffer-point))
(locate-attribute (current-buffer-point)
"Word Delimiter"
itest #'zerop))
;; If the next character is not a word delimiter, capitalize
;; the word that contains it and move to the next word.
(when (next-char-in-word-p (current-buffer-point))
(capitalize-word-command 1)
(forward-word-command 1))))

4.4 Miscellaneous Text Operations
The preceding sections have assumed that you are working with existing marks.
You can, however, create new marks when you are programming text operations.
For some operations, you can also work with lines as text-containing objects.
Lines are sometimes less convenient to use than marks and regions, but line
operations may be more efficient to execute.
This section introduces these techniques:
• Creating marks
• Operating on lines

Text Operations

4-13

4.4.1

Creating Marks
Marks are used primarily to indicate positions for insertions and deletions in text.
A single mark can indicate the position for an insertion operation; a pair of marks
can indicate a region of text to be deleted or inserted.
The Editor supplies a number of marks automatically—buffer points and the
marks that indicate the limits of buffer regions. If none of these marks is suitable
for the operation you want to perform, you can create one or more new marks.
New marks are most often created by “
copying”existing marks. Both the function
c o p y -m a r k and the macro w i t h -m a r k create a new mark that indicates the same
text position as a specified mark. You can also specify the type of mark you want
to create; a mark’
s type determines its behavior in a text operation.
This section introduces these topics:
• Mark types and their behavior
• Using COPY-MARK
• Using WITH-MARK

4.4.1.1

Mark Types and Their Behavior

Whenever you create a new mark, you must consider what becomes of that mark
after a text operation is performed on it. Marks are of two basic types:
• “
Temporary”marks, which become invalid after any operation upon them
• “
Permanent”marks, which remain valid after any operation upon them
Temporary marks are useful for one-time operations; after any operation that
affects the mark or the text to which it points, the mark becomes invalid and
should not be reused. Temporary marks are more efficient than permanent marks
for some applications because they require less overhead to make and use.
Permanent marks remain valid after any operation on them, including deletion
of the text to which they point. For instance, the current buffer point and the
two marks that indicate the beginning and end of text in a buffer are permanent
marks. If you delete all the text in a buffer, these three marks (and any other
permanent marks in that buffer) continue to point into that (empty) buffer.
Permanent marks can be removed only with the function d e l e t e -m a r k .
When you insert text at a permanent mark, the mark’
s behavior depends on
whether it is left-inserting or right-inserting:
• A“
left-inserting”mark appears at the end of a new insertion. That is, new
text is inserted to the left of the mark. The current buffer point and the
buffer-end mark are permanent left-inserting marks.
• A“
right-inserting”mark appears at the beginning of a new insertion. That
is, new text is inserted to the right of the mark. The buffer-start mark is a
permanent right-inserting mark.
You can specify the type of mark you want to create when you call c o p y -m a r k
or w i t h -m a r k . Each takes an optional mark-type argument, which may be
iTEMPORARY, :LEFT-INSERTING, Or :RIGHT-INSERTING.

4-14

Text Operations

4.4.1.2

Using COPY-MARK

The function c o p y - m a r k creates and returns a new mark that points to the same
position as a specified mark.
COPY-MARK m ark &OPTIONAL mark-type

For instance:
(copy-mark (current-buffer-point)

:temporary)

This form creates a new temporary mark that specifies the same text position as
the current buffer point.
If no mark-type argument is specified, the new mark is of the same type as
the specified mark. In the following example, the new mark is a permanent
left-inserting mark (like the current buffer point).
(copy-mark (current-buffer-point))
c o p y - m a r k is used often in defining a region between the current buffer point and
some other character position in the buffer. The procedure follows:

1. Indicate the position of the buffer point by placing a new mark there.
2.

Move the buffer point with any of the mark-moving functions.

3. Define a region from the new mark and the modified buffer point.
For instance, to make a region from the current buffer point to the end of a buffer,
you could write:
(make-region (copy-mark (current-buffer-point))
(buffer-end (current-buffer-point)))

This form copies the current buffer point and then moves the buffer point to the
end of the buffer. It uses the copied mark and the altered buffer point to define a
region.
If you perform an operation on this region, both marks will remain valid because
both are permanent marks. For instance:
(delete-region
(make-region (copy-mark (current-buffer-point))
(buffer-end (current-buffer-point))))

This form deletes all the text between the initial position of the current buffer
point and the end of the buffer. Both the buffer point and the new mark are left
pointing to the end of the buffer. However, because d e l e t e - r e g i o n returns N IL ,
you have no access to either the new mark or the new region.
4.4.1.3

Using WITH-MARK

When you are programming text operations, you may want to dispose of a new
mark after it has served its purpose. In this situation, you can create the mark
with the macro w i t h - m a r k .
copies a mark and binds the new mark to a specified variable. The
new mark can be of any mark type; the default is : t e m p o r a r y . The variable can
be referenced within the body of the macro. Upon exit from the form, the mark is
deleted and the variable becomes unbound.
w it h - m ark

is analogous to the Common LISP macro w i t h - o p e n - f i l e . Its use
guarantees that the overhead of creating a mark ends on exit from the macro.

w it h - m ark

Text Operations

4-15

An example of the use of w i t h -m a r k follows. This form copies the current buffer
point for a file-insertion operation. Inserting a file moves the current buffer point
to the right and leaves it at the end of the new insertion. If you want the current
buffer point to end up at the beginning of the new insertion, you could write:
;; Place a new right-inserting mark at the same position as the current
;; buffer point.
(with-mark ((new-mark (current-buffer-point)

:right-inserting))

;; Insert the file at the current buffer point.
(insert-file-at-mark file (current-buffer-point))
;; Move the current buffer point back to the position of the new mark.
(move-mark (current-buffer-point) new-mark))

This form creates a new mark, bound to the variable n e w -m a r k .Because n e w -m a r k
is right-inserting, it remains in its initial position when you insert a file. The
current buffer point, which is left-inserting, moves to the end of the new text.
After the insertion, the buffer point moves back to the position indicated by the
new mark. When the action is completed, n e w -m a r k becomes unbound and the
new mark is deleted.

4.4.2

Operating on Lines
A“
line”is an Editor object that points to a string of characters. The text string
in a line normally corresponds to the line of text displayed on the screen. A line
also contains pointers to the lines that precede and follow it.
All text operations result, directly or indirectly, in the alteration of fines or of
their relative positions. For instance, marks point into fines, and operations on
marks alter the fines into which they point. Also, the two marks that define a
region point into the same or different fines, and operations on the region alter
the fine, or fines, that the region contains.
You may find it efficient to perform some text operations directly on fines. These
operations include:
• Retrieving and altering the string of text in a fine
•

R etrieving and alterin g a p articu lar character

• Moving from one fine to another
• Testing the relative positions of fines
Lines are created as a result (side effect) of Editor operations such as reading
files, breaking fines, and so on. In the following examples, the variables line,
linei, and line2 are assumed to be bound to Editor fines.
4.4.2.1

Retrieving and Altering the Text in a Line

The function l i n e -s t r i n g takes a fine and returns the string that is the text
contained in that fine.
(line-string line)

This form returns the text in the specified fine as a string.
You can use s e t f with l i n e -s t r i n g to modify the text in a fine.
(setf (line-string line) "abode")

This form accesses the text in l i n e and replaces it with abode.

4-16

Text Operations

To change the text from abode to a b o d e , you could write:
(setf (line-string line)

(nstring-upcase (line-string line)))

Note that you must use s e t f to have the destructive operation performed by
n s t r i n g - u p c a s e appropriately reflected in l i n e .
4.4.2.2

Retrieving and Altering a Single Character

The function l i n e - c h a r a c t e r takes a line and an integer that indicates a char
acter position in that line. The character positions are numbered from the left
beginning with o (zero), l i n e - c h a r a c t e r returns the character in the specified
position (or n i l if no character is found). You can use s e t f with this function to
alter the specified character.
For example:
(setf (line-character line 4) #\W)

In this form, l i n e - c h a r a c t e r returns the character in position 4 in L IN E . Setting
that value to w changes the text string in l i n e from a b c d e to a b c d w .
You can break a line, and thus create a new line, by replacing a character with a
n e w l i n e character:
(setf (line-character line 2) #\newline)

This form replaces the c in l i n e with a n e w l i n e character. The result of this
operation is two lines, one containing the text a b and the next containing the text
DW.

4.4.2.3

Moving by Line

A line contains pointers to the lines that precede and follow it. You can move
from line to line by following these links, l i n e -n e x t and l i n e -p r e v i o u s take a
line and return the next line or the previous line (or n i l if no line is found).
For example, assume that l i n e i is followed b y L IN E 2 . Then,

4.4.2.4

(line-next linei)

/returnsLINE2

(line-previous line2)

/returnsLINEI

Testing Relative Line Positions

To check the relative positions of two lines, or to see if the two are the same line,
you use the functions l i n e =, l i n e < , l i n e >= , and so on. These functions are listed
in Appendix A and described in full in Part III.
For instance, the following form returns T only if l i n e i follows L IN E 2 :
(line> linei line2)

Because L IN E 2 is the second of the two lines in the example, this form returns
N IL .

4.4.2.5

Retrieving and Testing Mark Positions

Marks have been introduced as objects that indicate positions in text. A mark
indicates a text position by pointing to a line and to an integer that is a character
position in that line. (Recall that character positions are numbered from the left
beginning with 0 (zero).)

Text Operations 4-17

You can determine a mark’
s position with the functions m a r k - l i n e and m a r k ch arpos:

•

m ark- l in e

t a k e s a m a r k a n d r e t u r n s t h e lin e in t o w h ic h t h a t m a r k p o in ts.

•

m ark- c h a r p o s

takes a mark and returns its character position—that is, the
number of characters to the left of the mark in the same line.

To check the relative positions of two marks, you call a function such as m a r k =,
m a r k >, and so on. These functions are listed in Appendix A and described in full
in Part III.
4A 2.6

Example of an Operation on Lines

The following example implements a function that performs a text operation
directly on lines. The new function, p r e f i x - l i n e s , takes a string and a region;
it adds the specified string to the front of each line in the specified region. This
function could be used, for instance, to indent text (by inserting a specified
number of spaces at the beginning of each line) or to indicate comments in any
code (by inserting the appropriate comment delimiters and spaces).
(defun prefix-lines (string region)
" Adds the specified string to the beginning of each line
in the specified region."
;; Access each line in turn, beginning with the line that
;; contains the mark that starts the region.
(do* ((line (mark-line (region-start region))
(line-next line)))
;; When LINE contains the mark that ends the region,
;; end the loop.
((or (null line)
(line> line (mark-line (region-end region)))))
;; Prefix each line with the specified string.
(setf (line-string line)
(concatenate 'string string (line-string line)))))

4-18

Text Operations

Chapter 5

Window and Display Operations
Whenever you enter the VAX LISP Editor and select a buffer, the Editor makes a
window onto that buffer and displays it on the screen. A “
window”is an Editor
object that translates some portion of the text in a buffer into a displayable form.
Displaying the window makes that text visible.
NOTE

Editor windows are similar to virtual displays in the VMS screen
management facility, SMG. (See VAX/VMS Run-Time Library Routines
Reference Manual.) Creating a window is a separate operation from
displaying it, and windows can exist without being displayed. As
these features suggest, Editor windows are different from windows in
traditional EMACS editors, where a window is a section of the screen.
During an interactive session, the Editor makes and displays windows as a result
of executing certain commands. For instance, a window appears whenever you
edit a file or function, select a buffer, or execute "Help" or "Describe". Each of
these windows is an Editor object that includes certain information, such as its
size, screen position, display type (anchored versus floating), and the content
and position of its label. In LISP code, you can alter the features of a particular
window, and you can program the Editor to make windows with the features you
specify.
When multiple windows are displayed, a display manager within the Editor
determines how they are arranged on the screen. Depending on the number of
windows and their display types, some windows may overlap others, and some
may be resized or repositioned on the screen. In all situations, space at the
bottom of the screen is reserved for the information area, which the Editor uses
to report on its activities and to signal errors, and for the prompting window.
A few Editor commands provided by Digital allow you to operate directly on
windows or to override the automatic display management. For instance, you can
resize, scroll, and split the window you are working in; you can resize the display
area or remove windows from it; and you can move the cursor from one window
to another. If you want to exert finer control over window and display operations,
you can use the functions and other objects in the E ditor’
s display subsystem to
implement new commands.
This chapter introduces the techniques of programming the Editor to perform
window and display operations. It also covers operations on the display area
(screen) and on the information area (a section of the screen).
The topics covered in this chapter follow:
• Accessing windows
• Window content
Window and Display Operations

5-1

• Window appearance
• Window management
• Making and deleting windows
Part III contains more detailed information concerning the individual objects
in the display subsystem. An extended example at the end of this chapter
(Section 5.6) illustrates the use of many of these objects.

5.1

Accessing Windows
Windows are not named Editor objects; that is, you can access an Editor window
only with an expression that evaluates to that window object. This section
introduces the functions that you use to access some particular windows in LISP
code:
• The current window
• The windows onto a buffer
• All the windows on the screen
• The “
next”window on the screen
Many of the examples in this chapter use these functions to access windows.
Otherwise, the variables w i n d o w , w i n d o w i , w i n d o w 2, and so on, are assumed to be
bound to Editor windows.
Recall that the symbols for Editor objects provided by Digital must be referenced

in the EDITOR package.

5.1.1 The Current Window
Windows are always associated with buffers, and more than one window can open
onto a single buffer. One window onto the current buffer is the current window.
This is the window that contains the cursor; it is the “
active”window where text
operations commands are executed.
The current window is returned by the function c u r r e n t -w i n d o w , which takes no
arguments. You can use s e t f with c u r r e n t -w i n d o w to make another window the
current window:
(setf (current-window) window2)

This form makes WINDOW2 the current window. If w i n d o w 2 is not displayed already,
the display manager makes it visible on the screen. The buffer associated with
WINDOW2 becomes the current buffer, and the cursor moves to w i n d o w 2.

5.1.2 The Windows onto a Buffer
The function b u f f e r -w i n d o w s returns a list of the windows that open onto a
specified buffer. The list contains all windows onto that buffer, including any that
are not displayed currently.
For instance, another way to access the current window is:
(first (buffer-windows (current-buffer)))

The current window is always the first element in the list of windows onto the
current buffer.
5-2

Window and Display Operations

5.1.3

All the Windows on the Screen
The function v i s i b l e -w i n d o w s returns a list of all windows that are displayed
currently, regardless of what buffers they open onto. Visible windows are those
that have been displayed but not removed. Even if a window is completely
overlapped by other windows, it is still considered “
visible”and is in the list
returned by v i s i b l e -w i n d o w s .
An example using v i s i b l e -w i n d o w s is the command "Remove other windows"
supplied by Digital. This command checks each element of the list returned by
v i s i b l e -w i n d o w s to determine if that window is the current one. (The current
window may be anywhere on the list.) Each window that is not the current
window is removed from the screen by means of the function r e m o v e -w i n d o w .
(define-command (remove-other-windows-command
:display-name "Remove Other Windows")
(prefix)
" Removes all windows from the screen except the current window."
(declare (ignore prefix))
;; Display only the result of the operation, not intermediate states.
(with-screen-update
(let ((current (current-window)))
(dolist (window (visible-windows))
(unless (eq window current)
(remove-window window)))))
t)

5.1.4

The “Next” Window
The function n e x t -w i n d o w returns a visible window other than the current
window (or n i l ,if no other window is found). The format of n e x t -w i n d o w is:
NEXT-WINDOW &OPTIONAL w indow -type co u n t

The sequence in which windows are accessed is undefined, except that you can
limit the search to windows of a given window-type. The window-type argument
:a n c h o r e d or :f l o a t i n g causes n e x t -w i n d o w to return a window of that type (or
n i l , if none is found). The default argument T causes n e x t -w i n d o w to return a
window of the same type as the current window; if no such window is visible, then
n e x t -w i n d o w returns one of the opposite type. If only one window is displayed,
then n e x t -w i n d o w with argument T returns NIL (the prompting window is not
considered as a possible return value).
The optional count argument is an integer specifying the number of windows to
advance in the sequence to find the window to return. The default count is 1.
An argument of 0 returns the current window; a negative argument advances
through the sequence of windows in reverse order.
If called repeatedly with the same arguments, n e x t -w i n d o w returns the same
window—it does not advance through the sequence of windows. However, you can
circulate through all the displayed windows, or through all those of a specified
type, by repeatedly setting the current window to the “
next”window. This is
the action of the command "Next window" provided by Digital, which moves the
cursor to another window on the screen. A possible implementation is:

Window and Display Operations

5-3

(define-command (next-window-command :display-name "Next Window")
(prefix)
" Switches the current window to be the next visible window
on the screen. If a prefix argument n is supplied, it goes
to the nth visible window."
(setf (current-window)
(next-window t (or prefix 1))))

Since the window-type argument to n e x t -w i n d o w is T, this command circulates
through all the visible windows when you execute it repeatedly.
The command "Previous Window" circulates in reverse order. Its implementation
is identical to that for "Next window" except that the count argument to n e x t w i n d o w is negative:
(next-window t (- (or prefix 1)))

5.2 Window Content
You can think of a window as a rectangular opening onto a portion of text in
a buffer: the window opens onto a group of contiguous lines and a maximum
number of characters per line. That portion of text is the “
content”of the window.
To view other text in the buffer—either other lines or more characters per
line—you perform certain operations on the window, not on the text.
The operations you can perform on window content are:
• Retrieving window position in the buffer—that is, determining where in the
buffer the window begins and ends
• Repositioning a window within a buffer—that is, “
moving”a window so it
contains different text lines
• Wrapping text within a window—that is, altering a window so it contains all
the characters in text lines that extend beyond the window
Another way you can view text that overflows a window, either in length or in
width, is to alter the dimensions of the window—making it higher or wider.
However, depending on screen size, window type, and the number of windows
to be displayed at once, the E ditor’
s display manager may limit or override a
window’
s specified dimensions. The techniques of resizing windows are covered in
Section 5.4, along with a discussion of display management.

5.2.1

Window Position in a Buffer
The portion of text included in a window is delimited by two marks. These marks
are returned by the functions w i n d o w -d i s p l a y -s t a r t and w i n d o w -d i s p l a y -e n d ;
both take a window argument.
Like all marks (see Section 4.4.1.1), each of these marks indicates a character
position in a buffer:
• The display-start mark points to the beginning (character position 0) of the
first line in the window.
• The display-end mark points just after the last character in the window.
The text between these two marks is the portion of the buffer’
s text that the
window translates into displayable form.

5-4

Window and Display Operations

You can use the display-start and display-end marks to indicate text positions
to which to move another mark. For instance, the commands "Beginning of
Window" and "End of window" supplied by Digital move the current buffer point
to coincide with the display-start mark and the display-end mark, respectively, of
the current window. A possible implementation of "Beginning of window" is:
(define-command (beginning-of-window-command
:display-name "Beginning of Window")
(prefix Soptional (mark (current-buffer-point))
(window (current-window)))
"Moves the cursor to the beginning of the current window."
(declare (ignore prefix))
(move-mark mark (window-display-start window)))

The code for "End of window" can be the same except that it calls w i n d o w d i s p l a y -e n d .

You cannot move a window to a different position in the buffer by moving the
display-start and display-end marks. For the techniques of moving windows, see
Section 5.2.3.

5.2.2

The Window Point
In addition to the display-start and display-end marks, each window also contains
a third mark called the “
window point.”This mark is created when the window
is created, and you can access it by means of the function w i n d o w -p o i n t .The
window point of a window always indicates a character position within the text
contained in the window.
When the window is current, its window point is the same mark as the current
buffer point. That is, the following form always evaluates to T:
(eq (window-point (current-window))
(current-buffer-point))

The screen cursor, which is always visible in the current window, tracks the
position of this mark.
When the window is not current, its window point is not the same mark as the
buffer point of the associated buffer. Instead, the window point indicates the last
position occupied by the current buffer point when the window was current. If
the window becomes current again, the buffer point (and therefore the cursor)
moves to the position indicated by the window point.
You can move the window point by means of any of the mark-moving functions
described in Section 4.4.1. If you move the window point to a text position not
within the window, the Editor moves the window so that it always contains the
window point. For instance:
(buffer-start (current-buffer-point))

or
(buffer-start (window-point (next-window t)))

Both these forms move the window point to the first text position in the window’
s
associated buffer. If this position is not within the window, the window moves
automatically so that it does contain this text position:
• In the first form, the cursor remains visible in the current window because
the window content changes.

Window and Display Operations

5-5

• In the second form, window content changes on the screen; if you immediately
make this window current, the cursor appears at the new window-point
position at the beginning of the buffer.

5.2.3

Moving a Window in the Buffer
When the text in a buffer is longer (that is, has more lines) than a window
opening onto it, the window can be moved forward or backward through the
buffer. It appears that the text is moving past the window, but in the VAX LISP
Editor, actually the window is moving.
As shown in the preceding section, you can cause a window to move within
the buffer by operating on its window point. You can also operate directly on a
window to alter the portion of a buffer’
s text that it opens onto. There are two
ways to move a window:
• Scrolling, or moving line-by-line in the buffer
• Moving to a specified position in the buffer

5.2.3.1

Scrolling

The function s c r o l l - w i n d o w moves a specified window within its buffer by a
specified number of rows. This action changes the text line that appears in the
first row of the window. A positive count argument to s c r o l l - w i n d o w indicates
the number of rows to move forward in the buffer; a negative count indicates
backward movement.
For instance:
(scroll-window (current-window) -20)

This form scrolls the current window backward through the text (text moves down
on the screen) for 20 rows. If this action moves the window beyond the position
indicated by the current buffer point, the Editor automatically moves that mark
to a position within the new content of the window. The position of the updated
mark is near the center of the window.
T h e •window t o b e s c r o l le d n e e d n o t b e t h e c u r r e n t w in d o w , o f c o u r s e . F o r e x a m 
p le:

(scroll-window (next-window) 10)

This form scrolls the “
next”window on the screen forward by 10 rows. If this
action moves the window beyond the position indicated by its window point,
the Editor automatically moves that mark to indicate a position within the new
window content (again, near the center of the window).
5.2.3.2

Moving to a Specified Position

You can also move a window to a specified position within its associated buffer.
The function p o s i t i o n - w i n d o w - t o - m a r k moves a specified window to the line that
contains a specified mark. That is, the line containing the mark is placed in the
first row of the window.
For instance:
(position-window-to-mark (current-window)
(region-start (buffer-region (current-buffer))))

5-6

Window and Display Operations

This form moves the current window to the beginning of the current buffer. If
necessary, the Editor automatically updates the window point to keep it within
the window.

5.2.4

Wrapping the Lines in a Window
A window can be narrower (fewer characters per line) than the text it opens onto.
Windows always include the beginnings of lines; that is, the display-start mark
is always at character position 0 (zero) of the line it indicates. Any lines that are
longer than the width of the window are, by default, truncated on the right.
To view text in positions beyond the width of the window, you cannot move the
window to the right. Instead, you set the window to “
wrap”text lines onto one or
more additional window rows.
The function w i n d o w -l i n e s -w r a p -p takes a window and returns n i l if that
window truncates lines or t if it wraps lines. Using s e t f , you can change the
behavior of a specified window:
(setf (window-lines-wrap-p (current-window)) t)
(setf (window-lines-wrap-p (current-window)) nil)

The first form causes the current window to wrap lines that are wider than the
window. The second form resets the current window to truncate lines.
The above examples alter a particular existing window. If you want to specify the
line-handling behavior of newly created windows, you can reset the value of the
Editor variable "Default window Lines Wrap". Its possible values are T and NIL,
which indicate wrapping and truncating, respectively:
(setf (variable-value "Default Window Lines Wrap") t)

This form causes all newly created windows to wrap lines unless otherwise
specified.
Truncation and wrapping in a window are indicated by certain characters that
appear at the end of an affected line. The default characters are an underlined >
for truncation and an underlined < for wrapping. You can change these characters
for a specified window using the functions window-truncate-char and windowwrap-char. Both these functions take a window and return a character, and both
c a n b e u s e d w it h

setf:

(setf (window-truncate-char windowl) #\+)
(setf (window-wrap-char window2) #\/)

Assuming that w i n d o w i is set to truncate, the first form establishes an underlined
+ as the character that signals that a line has been truncated. Assuming that
WINDOW2 is set to wrap, the second form establishes an underlined / to signal
wrapping.
To change the truncation or wrapping characters in newly created windows, you
can reset the Editor variables "Default Window Truncate Char" and "Default
Window Wrap char". For example:
(setf (variable-value "Default Window Truncate Char") #\+)
(setf (variable-value "Default Window Wrap Char") #\/)

The underlining is a special video rendition of the selected characters; you cannot
change this feature. On terminals without advanced video capabilities, the
characters appear in reverse video instead of underlined.

Window and Display Operations

5-7

5.3 Window Appearance
Window appearance refers to the “
look”of a window when it is displayed: its
video rendition and whether it is bordered and labeled. All these features are
included in the window object itself. You can change a window’
s appearance by
using the functions and variables introduced in this section.
Most windows the Editor creates are shown with no special video rendition—they
share the video setting (dark-on-light or light-on-dark) of the terminal or other
display device. The window onto the "Help" buffer, however, is shown in bold.
Depending on the video capabilities of your display device, you can specify that
a window be shown in reverse video (the reverse of terminal setting) or that the
text in the window appear bold, underlined, or blinking.
You can see all these video options on a VT200-series terminal, an AI VAXstation,
and on VTlOO-series terminals with the Advanced Video Option. For the video
rendition capabilities of foreign terminals that are supported by the VAX LISP
Editor, consult your terminal manual.
You can also specify the video rendition of a region of text. The special rendition
of a region can be either:
• Relative to the window that contains the region—for instance, bold if the
window is not bold and vice versa
• Absolute—for instance, always bold or always not bold, regardless of the
window rendition
Finally, you can specify whether a window is to have borders and a label when it
is displayed. You can also determine the content of a window’
s label, the label’
s
position on the window, and the label’
s video rendition.
This section introduces the following techniques:
• Altering window rendition
• Making highlight regions
• Operating on window labels and borders

5.3.1

Altering Window Rendition
The function w i n d o w -r e n d i t i o n takes a window and returns a keyword or a
list of keywords that define the video characteristics of that window when it is
displayed. The keywords are :n o r m a l , zBLINK, :BOLD, r e v e r s e , and .-u n d e r l i n e .
You can use s e t f to change the rendition of a specified window to one or more of
the possible values. For instance:
(setf (window-rendition (current-window))

:underline)

or
(setf (window-rendition (next-window :floating)) '(sreverse :blink))

The first form changes the rendition of the current window to underlined. The
second form alters the “
next”floating window on the screen to reverse video (the
reverse of the terminal setting) with blinking.

5-8

Window and Display Operations

You can also specify the default window rendition features of newly created
windows, including those that the Editor creates automatically. Tb do so, you
set the value of the Editor variable "Default window Rendition" to the desired
keyword or list of keywords:
(setf (variable-value "Default Window Rendition"
' (:buffer "Help"))
:reverse)

; context argument

This buffer-local binding causes all newly created windows onto the "Help" buffer
to have the rendition value :r e v e r s e unless otherwise specified. (The global
binding of this variable in the Editor as provided is :n o r m a l . )
Recall that removing a window from the screen does not delete the window object.
If a window onto the "Help" buffer already exists, changing the value of "Default
window Rendition" does not affect the rendition of that window.

5.3.2

Making Highlight Regions
Sometimes you might want to alter the rendition of a particular block of text in a
window, rather than the entire window. For example, the select regions that the
Editor makes in "e d t Emulation" and "e m a c s " styles are shown in reverse video
(the reverse of the window).
Tb alter the rendition of a block of contiguous text, you use the function m a k e h i g h l i g h t - r e g i o n . This function is similar to m a k e - r e g i o n (described in
Section 4.2) except that it allows you to specify the video rendition that the
region will have when a window containing it is displayed. Highlight regions can
be used and treated like any other Editor region, and all the region-manipulating
functions operate on them.
The format of m a k e - h i g h l i g h t - r e g i o n is :
MAKE-HIGHLIGHT-REGION s ta r t e n d s e t c o m p l e m e n t

Like m a k e - r e g i o n , m a k e - h i g h l i g h t - r e g i o n takes two marks that indicate the
text positions where the region begins and ends. If you do not supply optional
arguments, the function makes a region with no special video features.
The optional set and complement arguments specify the rendition feature, or
features, that you want the region to have. They can be any of the keywords
: b o l d , : b l i n k , : r e v e r s e , or : u n d e r l i n e , or a list of these keywords. (The default
for both is n i l .) In deciding whether to provide a set argument, a complement
argument, or both, you need to consider the desired rendition of the region in
relation to the rendition of the window where the region will be displayed.
You can think of a set argument with no complement argument as turning “
on”
the specified feature in a highlight region. The region will have that video feature
regardless of the rendition of the window that contains the region.
For instance:
(make-highlight-region markl mark2 :reverse)

This form makes a reverse-video region of the text between the two specified
marks. If this region is displayed in a reverse-video window, then no difference
will be apparent between the region and the other text in the window—all text in
the window will appear in reverse video. If this region is displayed in a blinking
window, then all the text in the window will blink, including that in the highlight
region. (In the latter case, the region will be distinguished from the other text by
its reverse video.)

Window and Display Operations

5-9

You can achieve finer control over the video rendition of highlight regions by
providing a complement argument, either alone or in conjunction with a set
argument.
You use the complement parameter alone if you want the region to contrast
with the window rendition on the specified feature or features but to share the
window’
s value for any other rendition features. For instance:
(make-highlight-region (copy-mark (current-buffer-point)
(current-buffer-point)
nil :reverse)

:right-inserting)

This form is essentially the definition of the select regions that the Editor makes.
The form makes a new right-inserting mark at the same position as the current
buffer point and then makes a highlight region from that mark and the buffer
point. If you then move the buffer point, the text in the region between the two
marks is always shown in reverse video with respect to the window that contains
the region. That is, if the window is dark-on-light, the region is light-on-dark,
and vice versa. The region shares any other special video characteristics of the
window—bold, blink, or underline. (Note that moving one of the region-defining
marks causes the display of the region to track the m ark’
s position.)
If, on the other hand, you want the highlight region not to share specified
rendition features that a window might happen to have—in this example, the
bold, blink, and underline—you use the set and complement parameters in
conjunction. You can think of the complement argument as turning off a video
feature that is turned on elsewhere—either in the set argument or in the window
that contains the region.
For instance:
(make-highlight-region markl mark2
'(:bold :blink :underline)
'(:bold :blink runderline :reverse))

In this form, the :r e v e r s e value of the region “
complements”the value of the
window for this feature, as in the form above. The other three features are turned
“
on”by the set argument, but then turned off by the complement argument. They
remain off regardless of window rendition; that is, if this region is displayed in a
blinking window, the text in the highlight region does not blink.
Like any regions, highlight regions can overlap or one can be contained within
another. The effect of overlapping on the video rendition of the text shared
between the regions is, however, unpredictable.
Ib remove the highlighting of a region, you use the function r e m o v e - h i g h l i g h t This function takes a highlight region and deletes the region object. The
text in the region is not affected by this operation, but its special video rendition
is removed.
r e g io n .

If y o u u s e t h e n o r m a l r e g i o n - d e l e t i n g f u n c t i o n s , d e l e t e - r e g i o n a n d d e l e t e - a n d s a v e - r e g io n

w ith a h ig h lig h t r e g io n , t h e t e x t is r e m o v e d f r o m th e r e g io n b u t

t h e h ig h lig h t r e g io n r e m a in s .

If y o u i n s e r t n e w t e x t i n t o t h e r e g i o n , i t w i l l b e

d is p la y e d w it h th e s p e c ifie d r e n d it io n f e a t u r e s o f th e r e g io n .

5.3.3

Operations on Window Labels and Borders
Editor windows can have borders on all four sides and a label on one of these
borders. A border is a solid line that surrounds the text-displaying area of the
window. The border occupies the screen rows above and below the window’
s text
area and the screen columns to the right and left of the text area. A window label
is a string of text that overlays part or all of one of the window borders.

5-10

Window and Display Operations

Most windows that the Editor makes have borders and labels. However, depend
ing on window size, window type, and the number of windows on the screen at
once, one or more of the borders—including the one with the label—may “
spill
o ff the display area or be obscured by another window. Nonvisible borders and
labels still exist as part of the window object, however, and they might be made
visible under other display circumstances. In contrast, the prompting window,
which appears near the bottom of the screen, has no borders and no label.
This section introduces the functions and Editor variables that enable you to
perform operations on window borders and labels. Section 5.4.2.4 below identifies
the circumstances under which a border or label may be obscured when a window
is displayed.
Some operations you can perform on window borders and labels follow:
• Adding and removing borders and labels
• Specifying label content
• Specifying label position
• Specifying label rendition
5.3.3.1

Borders, Labels, and Label Content

The function w i n d o w - l a b e l takes a window and returns either a string, a func
tion, or n i l . The value returned indicates whether the specified window has
borders, whether it has a label, and, if it has a label, what text that label con
tains.
You can use s e t f with w i n d o w - l a b e l to alter any of these features for a specified
window. That is, you can add or remove borders, add or remove a label, and
specify label content for an existing window. The meaning of each possible return
value of w i n d o w - l a b e l is shown in the following examples.
• If y o u s u p p l y t h e v a l u e n i l , t h e s p e c i f i e d w i n d o w h a s n o b o r d e r s a n d n o l a b e l :
(setf (window-label windowl)
nil)

; Windowl has no borders and no label.

• If you supply a null string, the window has borders but no label:
(setf (window-label window2)
"")

; Window2 has borders but no label.

• If you specify label content, the window has borders and a label with the
content specified. One way to specify label content is to specify the actual
string you want the label to contain:
(setf (window-label window3)
"String")

; Window3 has borders and a label
; that contains the specified string.

It is usually more useful, however, to have window label contents vary according
to the buffer the window opens onto. The label can state, for instance, the name
of the file or function being edited in the buffer, and it can list the styles active in
the buffer. To achieve this, you specify a function that returns a string; the string
becomes the window label.
For instance, the following d e f u n form defines a simple function named l a b e l e r ,
which returns a string, l a b e l e r then is used with s e t f and w i n d o w - l a b e l in a
form corresponding to those shown above:

Window and Display Operations 5-11

(defun labeler (window)
(let ((buffer (window-buffer window)))
(format nil "LISP EDITOR ~A"
(buffer-name buffer))))
(setf (window-label window4) #'labeler)
l a b e l e r invokes w i n d o w -b u f f e r to access the buffer object associated with the

specified window and b u f f e r -n a m e to find the name of that buffer, l a b e l e r
returns a string that looks like “
LISP EDITOR Name-of-Buffer”
. The s e t f form
labels WINDOW4 with the string returned by l a b e l e r for that window.
The above examples all deal with alterations to a single existing window. By
resetting the value of the Editor variable "Default window Label", you can make
corresponding specifications for newly created windows. For example:
(setf (variable-value "Default Window Label" :global) 'labeler)

The possible values of "Default window Label"— n i l , a null string, a string, or a
function—have the same meanings they have as return values of w i n d o w -l a b e l .
(Note that the function l a b e l e r in this example is set to the value slot of the
variable.) In the Editor as provided, the value of this variable is set to different
functions in "EDT Emulation" style and "e m a c s " style.
5.3.3.2

Label Position

For a given window that has a label, you can specify which border the label
is on and where on the border the label is placed. The relevant functions are
WINDOW-LABEL-EDGE and WINDOW-LABEL-OFFSET.
In deciding where to place window labels, you need to consider whether the
border you choose will be visible when the window is displayed and, if so, whether
the entire label will be visible on the border. For instance, the top borders of
anchored windows are never visible; a label placed on that border can never be
seen. Or, a floating window that spills off the screen on the right may “
lose”
the end of a label placed on its top or bottom border. These considerations are
outlined in Section 5.4 on display management.
w i n d o w -l a b e l -e d g e takes a window and returns the border on which that win

dow’
s label appears. The possible values are :TOP, :b o t t o m , :LEFT, and :r i g h t .
You can use s e t f with this function to alter the placement of the label:
(setf (window-label-edge windowl)

:top)

Assuming that w i n d o w i has a label, this form places the label on the top border of
WINDOWl.

The function w i n d o w -l a b e l -o f f s e t ,used with s e t f , allows you to specify where
on a border the label is to appear. The value n i l causes the label to be cen
tered on the border; a nonnegative integer value indicates how many character
positions the label is offset from the beginning of the border.
For instance, to center the label of w i n d o w i (which the previous example placed
on that window’
s top border), you would write:
(setf (window-label-offset windowl) nil)

lb place a label flush left (if it is on a top or bottom border) or to make the label
begin at the top of a side border, you would write:
(setf (window-label-offset window) 0)

5-12

Window and Display Operations

The above examples all deal with label placement in a single existing window.
To change the default label placement in windows created in the future, you
use the Editor variables "Default Window Label Edge" and "Default Window
Label offset". The global bindings of these variables in the Editor as provided
are : b o t t o m and n i l , respectively. Thus, window labels appear centered on the
bottom border of a window unless otherwise specified.
5.3.3.3

Label Rendition

For a given window that has a label, you can retrieve and alter the video ren
dition of that label. The function w i n d o w - l a b e l - r e n d i t i o n takes a window and
returns one of the keywords i NORMAL, :R e v e r s e , i BLINK, :BOLD, or : u n d e r l i n e , or
a list of those keywords.
The rendition of a window label is an absolute value that is not relative to the
rendition of the window itself. For instance, the rendition of a reverse-video label
is always the reverse of the terminal setting (light-on-dark or dark-on-light),
regardless of whether the window rendition is normal or reverse. A window label
set to blink will always blink, regardless of whether the window also blinks.
w in d o w - l a b e l - r e n d i t i o n

is a c c e p ta b le to

setf:

(setf (window-label-rendition window)

underline)

This form underlines the label of w i n d o w .
To change the default rendition of the labels of newly created windows, you reset
the value of the Editor variable "Default window Label Rendition". The possible
values are any of the keywords listed above, or a list of those keywords. The
global binding in the Editor as provided is :r e v e r s e .

5.4 Display Management
Once a window exists as an Editor object, you can make it visible on the screen.
You can also remove a window from the screen without destroying the window
object, and you can redisplay that window at any time. Each window object
contains information concerning its size and the screen position it occupies when
it is displayed.
However, the E ditor’
s display manager retains control over many display-related
d e c is io n s . T h e E d it o r g u a r a n t e e s , f o r in s t a n c e , t h a t t h e d i s p la y a r e a i s a lw a y s

filled, and that anchored windows do not obscure each other’
s text content. The
display manager will reposition, resize, and even remove some windows from the
screen to meet these requirements.
Within the constraints set by the display manager, you have considerable freedom
to determine the total appearance of the screen: the size of the display area,
the number of windows displayed, and the size and screen positions of some
individual windows.
This section introduces the following sets of techniques, each in conjunction with
the constraints set by the E ditor’
s automatic display management:
• Operations on the display area—including the information area and the
prompting window
• Window types and their behavior—visibility, size, and screen position as they
relate to a window’
s display type
• Displaying windows and removing windows from the display

Window and Display Operations

5-13

5.4.1

The Display Area
The E ditor’
s display area is the total space available on your display device for
showing Editor windows and the information area. On VT100- and VT200-series
terminals, the display area is, by default, the full terminal screen. Both these
terminal screens are 24 rows in height, and both permit screen widths of 80 or
132 columns.2
The AI VAXstation permits an Editor display area of up to 66 rows by 167
columns. The Editor display area provided by default on the AI VAXstation is 50
rows by 80 columns.
You can think of the display area as an X-Y coordinate system. You use these
coordinates to specify the screen positions at which windows are displayed. Both
the columns (X coordinate) and the rows (Y coordinate) are numbered from the
upper-left corner beginning with 1 (see Figure 5-1).
Figure 5-1:

Display Area Coordinates

You have some latitude to alter the dimensions of the E ditor’
s display area, and
thus the total screen area available for displays related to the Editor. Within this
total area, the Editor always reserves some space for the information area and
for the prompting window. The space that remains in the display area after the
prompting window and the information area are accounted for is the total space
available for displaying other windows.
This section introduces the following concepts and techniques:
• Display area dimensions—retrieving and altering the height and width of the
display area

2 For screen sizes of foreign (non-Digital) terminals supported by the VAX LISP Editor, consult your terminal manual.

5-14

Window and Display Operations

• The reserved display area—operating on the information area and the
prompting window
• The available display area—displaying and removing other Editor windows
5.4.1.1

Display Area Dimensions

The functions s c r e e n -h e i g h t and s c r e e n -w i d t h return integers that are the
number of rows and columns, respectively, in the display area. The dimensions
returned are not necessarily those of the screen. By default, the display area
occupies the full screen on Digital terminals, but you can use s e t f with s c r e e n h e i g h t and s c r e e n -w i d t h to alter either dimension:
(setf (screen-height) 20)
(setf (screen-width)

60)

If you execute these two forms, the display area is reduced to the dimensions
shown in Figure 5-2:
Figure 5-2:

Altered Display Area Dimensions

MLO-002995

The coordinate numbering does not change when you change the dimensions
of the display area. The rows and columns that become unavailable are those
at the bottom and on the right. The upper-left comer of the display area still
corresponds to the upper-left comer of the screen, and the upper-left position is
still designated as 1,1.
You cannot make the display area larger than the screen. If you supply a value
in either of the above s e t f forms larger than the maximum screen dimension, the
display area dimension is altered to the maximum screen dimension.

Window and Display Operations

5-15

You can, however, use s e t f with s c r e e n -w i d t h to alter the width setting of the
screen on Digital terminals; the width setting can be either 80 columns (“
norm al”
)
or 132 columns (“
w ide”
). Widening the screen makes more columns available for
the E ditor’
s display area. Note that if your terminal does not have the Advanced
Video Option, widening the screen limits screen height to 12 rows.
Suppose that your terminal is set to the “
normal”width of 80 columns. Then
execute:
(setf (screen-width) 120)

This form resets VT100- and VT200-series terminals to “
wide”width—132
columns; at the same time, it makes 120 of those columns available as the
display area. The 12 rightmost columns of the screen will be blank.
On the AI VAXstation, this form simply sets the display area width to 120
columns out of the 167 columns available on the screen.
With the AI VAXstation, you can adjust display area dimensions before the Editor
is started (using s e t f with s c r e e n -h e i g h t or s c r e e n -w i d t h ). When you start the
Editor, its display area will be the size you specified. Performing such operations
on a VT100- or VT200-series terminal before the Editor is started produces no
effect.
5.4.1.2

Reserved Display Area

The Editor always reserves some part of the total display area for the information
area and the prompting window. The information area is always at the bottom of
the display area, and the prompting window is always just above the information
area. By default, both these areas are the full width of the display area, and each
is 1 row in height.
The information area is managed directly by the E ditor’
s display manager, which
uses it to display error messages and to report on Editor activity. The information
area is not an Editor window, and none of the window-related functions operate
on it. You cannot delete the information area, and no Editor windows can overlap
it. It is, therefore, an area of guaranteed visibility within the display area.
You can, however, increase the space allotted for the information area, and you
can direct output to it.
The function i n f o r m a t i o n -a r e a -h e i g h t returns the height (in screen rows) of the
information area. Using s e t f , you can increase the height to more than 1 row,
but you cannot decrease it to 0 rows.
Ib direct output to the information area, you can use the LISP global variable
*i n f o r m a t i o n -a r e a -o u t p u t -s t r e a m *. This variable is bound to an output stream
directed to the information area. You can use the variable as the stream argu
ment to any of the LISP functions that take a stream, such as w r i t e -s t r i n g ,
f o r m a t , or p r i n c .For example:
(write-string "Operation completed. "
*information-area-output-stream*)

Some other functions that operate on the information area are c l e a r i n f o r m a t i o n -a r e a , which removes any current text, and e d i t o r -e r r o r , which
directs error messages to the information area, e d i t o r -e r r o r is discussed in
Section 2.3.1.2.
The prompting window is displayed permanently also. The full prompting area
consists of a small section of the screen where prompts are displayed, followed on
the same row by an Editor window where user input is displayed. By default, the
full prompting area is 1 row in height and the full width of the display area.
5-16

Window and Display Operations

Although the prompting window is an Editor window, some of the window-related
functions do not operate on it. The display manager ignores any attempt to
remove this window from the screen, to reposition it on the screen, or to overlap
it with another window. Thus, the prompting area is also an area of guaranteed
visibility.
You can, however, alter the appearance of the prompting window by using the
functions described in the previous section. (The screen area where prompts are
displayed is not affected by operations on the prompting window.)
To alter the video rendition of the prompting window, you might write:
(setf (window-rendition
(first (buffer-windows (find-buffer "General Prompting"))))
sreverse)

This form alters the rendition of the prompting window to reverse video. The
rendition of the area where prompts are displayed can be altered by resetting the
Editor variables "Prompt Rendition Set" and "Prompt Rendition Complement"
(see Part III).
You can also alter the dimensions of the prompting window, in the same way
that you resize other windows. See Section 5.4.2.2 for the techniques of resizing
windows.
The screen space—number of rows—that you have allotted to the prompting
window and the information area always is reserved for them, and thus not
available for displaying other windows.
5.4.1.3

Available Display Area

Whatever space is not reserved for the information area and the prompting
window is the “
available display area.”This is the area you use to display Editor
windows, and its dimensions constrain your decisions on sizing and positioning
windows if you do not want them to overlap one another or overflow the screen.
In the following sections on displaying, sizing, and positioning windows, the term
“
display area”refers to the available display area.

5.4.2

Window Types and Their Behavior
There are two types of Editor windows: anchored and floating. The Editor
normally provides anchored windows for ordinary text editing. Floating windows
are used for displaying information or for other special purposes. For instance,
the windows onto the "Help" and "General Prompting" buffers are floating
windows.
The content and appearance of a window are not affected by the display type of
that window. The distinction between the two types lies in how they are treated
in display management. This section outlines the effect of window type on three
aspects of display management behavior:
• Display behavior by window type
• Window size and display behavior
• Window position and display behavior

Window and Display Operations

5-17

You can access or change the type of a specified window. The function w i n d o w t y p e takes a window and returns a keyword, which can be either :a n c h o r e d or
:f l o a t i n g .Using s e t f , you can change the window’
s type:
(setf (window-type window)

:floating)

The Editor variable "Default window Type", which specifies the default type of
newly created windows, can be set to either of these keywords. In the Editor as
provided, the default window type is :a n c h o r e d .
In the examples that follow, the variable a n c h o r e d -w i n d o w is assumed to be
bound to an anchored window, and f l o a t i n g -w i n d o w is assumed to be bound to a
floating window.
5.4.2.1

Display Behavior by Window Type

The major difference between anchored and floating windows lies in whether they
can overlap, or be overlapped, by other windows:
• A floating window can overlap or completely obscure any other window in the
available display area, either anchored or floating.
• An anchored window never obscures the text area of another window, either
anchored or floating.
When a floating window is displayed, it appears in the size and at the screen
position contained in the window object. Any other windows that occupy any part
of that space are overlapped.
If more than one anchored window is displayed at once, the display manager
moves and resizes them as necessary so that no text is obscured. The size and
screen position contained in the window object are ignored.
The Editor’
s display rules concerning window size and screen position follow from
this basic rule concerning window overlaps. Thus, automatic display manage
ment relates to anchored windows only; floating windows, which need not avoid
overlaps, are under the user’
s control and not subject to automatic resizing and
repositioning.
5.4.2.2

Window Size and Display Behavior

Each window object has height (number of rows) and width (number of columns)
features. You can retrieve and alter these features in any window, but it is only
in floating windows that the features have significance.
You can access window dimensions with the functions w i n d o w -h e i g h t and
w i n d o w -w i d t h , and you can use s e t f to alter these dimensions:
(setf (window-height floating-window) 12)
(setf (window-width floating-window) 40)

These forms alter the specified floating window to be 12 rows in height and
40 columns wide. The dimensions of a window refer to the text area only; if
the window has borders, the borders occupy 2 additional rows and 2 additional
columns outside the text area.
The minimum size for a floating window is 1 row by 2 columns. If you attempt
to alter either dimension to less than the minimum, an error is signaled. If you
make either dimension larger than the available display area, the window will
overflow the display area to the right or to the bottom.

5-18

Window and Display Operations

For anchored windows, the dimensions contained in a window object are ignored
by the Editor’
s display manager. An anchored window always occupies the full
width of the display area. The window’
s height depends on how many anchored
windows are visible at once.
If an anchored window is the only anchored window displayed, its text area oc
cupies the full height of the available display area, minus 1 row for the window’
s
bottom border, if any. (The top and side borders of anchored windows are always
obscured.) You cannot adjust the height of an anchored window when it is the
only anchored window on the screen.
If two or more anchored windows are displayed at once, the Editor automatically
adjusts their heights to be nearly equal. You can override this adjustment for a
specified window by means of the function a l t e r -w i n d o w -h e i g h t .This function
takes a window and a positive or negative integer that is the number of rows
by which to adjust the window’
s height. (The argument window need not be
visible at the time the form is evaluated, and it can be either an anchored or a
floating window.) The integer argument specifies a change in size, rather than an
absolute size as does the return value of w i n d o w -h e i g h t .
(alter-window-height anchored-window -2)

This form makes the specified anchored window (when displayed with at least
one other anchored window) two rows shorter than the height determined by the
display manager. The display manager adjusts the height of any other visible
anchored windows to accommodate the altered height of the argument window
and still fill the display area.
The minimum height to which you can adjust an anchored window is 1 row of text
area. (If the window is bordered, a second screen row is reserved for the bottom
border.) The maximum height is determined by the rule that no anchored window
can obscure another’
s text. The argument window cannot be made so high that
another visible anchored window would be reduced to less than 1 text row (or
2 screen rows if bordered). If the integer argument to a l t e r -w i n d o w -h e i g h t
violates these rules, the Editor adjusts the argument window only as much as
possible.
5A 2.3

Window Position and Display Behavior

Editor windows contain information on the screen position at which they are to
be displayed. Display position is specified as the X-Y coordinates of the screen
position occupied by the top-left character in the window. (Recall that the X-Y
coordinate numbering of the screen and the display area begin at the same point
in the upper-left corner.)
You can retrieve the screen position of a specified window by means of the
functions w i n d o w -d i s p l a y -c o l u m n and w i n d o w -d i s p l a y -r o w . (The argument
window need not be currently visible.)
(window-display-column window)
(window-display-row window)

If these forms return 10 and 5, respectively, then the upper-left corner of the
window’
s text area is displayed at column 10, row 5 of the display area (see
Figure 5-3). If the window is bordered, the borders lie outside this position.

Window and Display Operations

5-19

Figure 5-3:

A Window Display Position

X=9

X=1
Y=1

/ Y=4

Border

J
\
X = 10
Y =5
Window
Border

MLO-002996

As with window size, the values that indicate window display position are sig
nificant only for floating windows. Anchored windows are always displayed
beginning in column 1. The display row position of an anchored window is
determined by the display manager.
You can alter the display position of a floating window by means of the function
m o v e -w i n d o w ,m o v e -w i n d o w takes a window and a row and column to which to
move the upper-left comer of that window’
s text area:
(move-window floating-window 8 25)

This form alters the floating window’
s values for display row and display column
to those specified. If the window is displayed, it moves to that position; if the
window is not displayed, it appears at that position when it is next displayed.
An example using m o v e -w i n d o w is a function m y -m o v e -w i n d o w -v e r t i c a l l y .This
function moves a window’
s display row by the number of rows specified, or by
fewer rows if the specified offset value would result in spilling the window (or its
border) off the display area. Its code is:
(defun my-move-window-vertically (window offset)
;; Compute the new display row.
(let ((new-row (+ (window-display-row window) offset)))
;; Move the window to the display row, or as far as possible
;; without overflowing. Retain the window's display column.
(move-window window
(min (max new-row 1)
(- (screen-height) (window-height window)
(if (window-label window)
1

0)) )

(window-display-column window))))

5-20

Window and Display Operations

To use this function in an Editor command, you could write:
(define-command (my-move-window-up-command
:display-name "My Move Window Up")
(prefix)
" Moves the current window up one or more rows, without
spilling it off the screen. Cannot be used with
anchored windows."
(if (eq (window-type (current-window) ifloating))
(my-move-window-vertically (current-window)
(- (or prefix 1)))
(attention)))

You could write a similar function to move a window horizontally, and similar
commands to move a window down, right, and left.
5.4.2.4

Window Borders and Display Behavior

The Editor’
s display rules concerning the overlapping of window text areas do
not apply to window borders. A bordered window can sometimes be sized or
positioned in a way that obscures one or more of its borders.
The top and side borders of anchored windows are never visible. If an anchored
window with a border is the only anchored window displayed, its text area fills
the available display area, leaving 1 row for its bottom border. Its top and side
borders overflow the display area. For this reason, you should always place the
labels of anchored windows on their bottom borders.
If 2 or more anchored windows with borders are displayed at once, the bottom
border of one window obscures the top border of the window displayed below it.
The bottom border of an anchored window never overflows the display area, and
it cannot be obscured by another anchored window. It can, however, be obscured
by a floating window.
The borders of floating windows are visible more often since floating windows
can be sized and positioned well within the display area. However, if a floating
window equals or exceeds the size of the display area, then any or all of its
borders can spill off. The "Help" window, for instance, is the full width of the
display area but shorter in height. Therefore, its top and bottom borders are
visible, but its side borders are not visible. If a floating window, regardless of its
size, is positioned on the screen in such a way that it overflows the display area,
then the border of the affected edge cannot be seen.

5.4.3

Displaying and Removing Windows
The following functions enable you to display and remove windows from the
screen:
•

SHOW-WINDOW

•

PUSH-WINDOW

•

REMOVE-WINDOW

The behavior of these functions varies with the display type of the argument
window and of other visible windows. This section introduces these behavior
variations: you can find further information in the description of each function in
Part III.

Window and Display Operations

5-21

5.4.3.1

Using SHOW -W INDOW
s h o w -w i n d o w takes a window and displays it on the screen.

Its format is:

SHOW-WINDOW w in d o w &OPTIONAL r o w c o lu m n
If the window is a floating window, you can supply an optional row and column
at which its upper-left character will appear. If you do not specify a position, the
window is placed at the position contained in the window object.
A newly displayed floating window obscures any other window that is currently
displayed in the same position. If the argument (floating) window is already
displayed but is obscured by one or more windows, s h o w -w i n d o w redisplays it on
top of the obscuring window(s).
If the argument window is an anchored window, its position is determined by the
display manager. If you supply row and column arguments, they are ignored.
You can continue to add anchored windows to the screen with s h o w -w i n d o w
up to the number that is the value of the Editor variable "Anchored window
show Limit". For instance, if the value is 2 (the global default), you can show
2 anchored windows on the screen at a given time. Adding a third anchored
window with s h o w -w i n d o w causes the least recently used anchored window to be
removed.
A newly displayed anchored window appears at the bottom of the screen, and any
other anchored windows that remain on the screen are moved up. All the visible
anchored windows are resized so that they are about equal in height. If a window
is removed to accommodate the newly displayed window, the new window is made
the same size as the one that was removed.
5.4.3.2

Using PUSH-WINDOW
p u s h -w i n d o w is like s h o w -w i n d o w , except that it does not automatically remove

anchored windows when their number exceeds the value of "Anchored window
show Limit". Also, p u s h -w i n d o w takes two optional arguments that enable you to
override some features of the Editor’
s automatic treatment of anchored windows.

The f o r m a t o f p u s h - w in d o w i s :
PUSH-W INDO W window &OPTIONAL companion insert-above

If the argument window is floating, p u s h - w in d o w has the same effect as s h o w except that you cannot specify a display position. The window appears
at the position contained in the window object. If you supply optional arguments,
they are ignored.

w in d o w ,

If the argument window is anchored, p u s h -w i n d o w adds it to the display without
removing any previously displayed anchored windows. The Editor resizes all the
visible anchored windows to make them about equal in height.
The optional arguments enable you to specify the position of a newly displayed
anchored window in relation to a visible anchored window. If you specify a
companion argument—a visible anchored window—the newly displayed window
appears just below the companion. If you supply both a companion argument and
an insert-above argument of T, the new window appears just above the companion
window.

5-22

Window and Display Operations

5.4.3.3

Using REMOVE-WINDOW
r e m o v e - w in d o w

removes a window from the display. Its format i s :

REMOVE-WINDOW w in d o w &OPTIONAL n e w - cu rr e n t

If the argument window is floating, r e m o v e -w i n d o w has no effect on the remaining
visible windows. If the argument window is anchored, the Editor automatically
resizes and repositions the remaining anchored windows so that they fill the
available display area.
If the window being removed is the current window, you can supply a new-current
argument to specify the window that is to become current. If you do not supply a
new-current argument, then the Editor invokes n e x t -w i n d o w (with argument t ) to
identify the window that becomes current.
By using r e m o v e -w i n d o w repeatedly, you can remove from the available display
area all but one of the visible windows. You cannot empty the available display
area completely, however; the one window that will remain opens onto the buffer
bound to the variable *e d i t o r -d e f a u l t -b u f f e r *. If you have not bound a buffer
to this variable, the Editor displays a window onto the "Basic introduction"
buffer when it has nothing else to show.

5.5 Making and Deleting Windows
Most of the windows that the Editor displays are made by the Editor as a result
of executing certain commands. You can, however, make a window directly in
LISP code, and you can specify all the features you want that window to have. If
the new window is an anchored window, its specified size and screen position are
ignored by the Editor’
s display manager.
To create a new window, you call the function m a k e -w i n d o w . Its format is:
MAKE-WINDOW b u ffer-or-m a rk &KEY :HEIGHT :WIDTH
:DISPLAY-ROW :DISPLAY-COLUMN
:TYPE
:LINES-WRAP
:LABEL

The one required argument to m a k e -w i n d o w is buffer-or-mark. This argument
indicates the text content of the window; that is, it indicates the buffer onto
which the window opens, as well as the text position within that buffer where the
window begins.
• If the argument is a buffer, the window opens onto that buffer, beginning with
the line that contains the buffer point.
• If the argument is a mark, the window opens onto the buffer that contains
that mark, beginning with the line that the mark indicates.
For instance:
(make-window (find-buffer "Help"))

or
(make-window (window-point (first (buffer-windows "Buffer"))))

The first form makes a window onto the "Help" buffer, starting with the line that
contains the buffer point of that buffer. The second form makes a window onto
the buffer associated with another window, beginning with the line indicated by
the window point of the other window.

Window and Display Operations

5-23

Some of the keyword arguments to m a k e - w i n d o w — sTYPE, : L I N E S - w r a p , and
: l a b e l — have defaults that are the values of the corresponding Editor variables.
For instance, the default window type is :a n c h o r e d —the global value of the
Editor variable "Default Window Type".
The keyword arguments that pertain to window size and screen position all
take integer values. These values are significant only for floating windows. For
anchored windows, any values you supply are ignored by the display manager.
•

: h e ig h t i s t h e n u m b e r o f r o w s o f t e x t in t h e w in d o w , e x c lu d in g b o r d e r s .

The default is the height of the available display area (minus one row if the
window is bordered).
•

: w i d t h is the number of columns of text in the window, excluding borders.
The default is the value of the Editor variable "Default window width".

•

: d i s p l a y - r o w and : d i s p l a y - c o l u m n indicate the screen position of the upperleft corner of the window’
s text area (excluding borders) when the window
is displayed. The defaults are l and 1. You can override these values by
supplying row and column arguments to s h o w - w i n d o w .

To delete a window object, you call the function d e l e t e - w in d o w and pass it a
window argument. The window can be visible or not visible; if it is visible,
d e l e t e - w in d o w first removes it from the display and then deletes it. When an
Editor window is deleted, it is destroyed and cannot be used again.

5.6 Example of Window and Display Operations
The following example illustrates the Editor objects that you can use to create,
display, and remove a window. The d e f i n e - c o m m a n d form implements a new
command named "Clock", which displays a window that contains the current
date and time. The command obtains the current date and time by calling the
function f o r m a t - c l o c k , whose code is shown afterward.
(define-command (clock-command :display-name "Clock")
(prefix)
" Displays the current date and time in a window."
(declare (ignore prefix))
;; Find or make a buffer named "Clock".
(let ((buffer (find-buffer "Clock")))
(unless buffer
(setf buffer
(make-buffer ' (clock-buffer :display-name "Clock")
:major-style nil
:minor-styles nil
svariables nil)))
;; Find or make a window onto the "Clock" buffer.
(let ((window (first (buffer-windows buffer))))
(unless window
(setf window
(make-window buffer
:type :floating
:height 2 :width 30
:label "Clock"
:display-row 2 :display-column 48))
(setf (window-label-edge window) stop)
(setf (window-label-rendition window) sblink)
(setf (window-rendition window) sbold))
;; Delete any previous text in the "Clock" buffer,
(delete-region (buffer-region buffer))
5-24

Window and Display Operations

;; Insert the string returned by FORMAT-CLOCK onto
;; "Clock" at the buffer point.
(insert-string (buffer-point buffer)
;; Display the window.

(format-clock))

(show-window window 2 48)
;; Force the window to reflect the current contents of
;; the buffer.
(update-display)
;; Leave the window on the screen for 3 seconds and
;; then remove it.
(sleep 3.0)
(remove-window window))))

Note the redundancy in this form: the window’
s display position is specified both
in the m a k e - w in d o w form and in the s h o w - w i n d o w form. You can choose either
place to make this specification.
The function m a k e - b u f f e r , which creates and returns a new buffer, is described
in Section 6.1.1 and in Part III.
f o r m a t - c l o c k , w h ic h

r e t u r n s a s t r i n g c o n t a i n i n g t h e c u r r e n t d a y , d a t e , a n d tim e ,

c o u ld b e im p le m e n t e d a s fo llo w s :

(defun format-clock ()
" Returns the current time of day and the current date."
(multiple-value-bind (second minute hour day month year week-day)
(get-decoded-time)
(declare (fixnum second minute hour day month year week-day))
(let ((months '#( "Jan" "Feb" "Mar" "Apr" "May" "Jun"
"Jul" "Aug" "Sep" "Oct" "Nov" "Dec"))
(week-days '#( "Monday" "Tuesday" "Wednesday"
"Thursday" "Friday" "Saturday"
"Sunday"))
(display-hour (if (= hour 12)
hour
(mod hour 12))))
(declare (simple-vector months week-days)
(fixnum display-hour))
(format nil
"~A ~2D-~A— 4D~%~2D:~2,'0D:~2,'0D"
(svref week-days week-day)
day
(svref months (1- month))
year hour minute second))))

Window and Display Operations

5-25

Chapter 6

Operations on Styles
Styles in the VAX LISP Editor act as sets of Editor capabilities that you can turn
on and off in the buffers where you are editing. For instance, in "e d t Emulation"
style, you use the same key sequences as with D igital’
s EDT editor to execute
similar Editor commands. If you prefer the behavior and key bindings of an
editor based on EMACS, you can use the Editor’
s "e m a c s " style instead in any
or all buffers. When "VAX l i s p " style is also active, the Editor recognizes LISP
syntax, knows how to indent LISP code, can evaluate selected regions of code,
and so on. (See VAX LISP/VMS Program Development Guide.)
In programming terms, a style is a named Editor object that serves as a binding
context. A style object can contain bindings for:
• Editor variables
• Editor attributes
• Keyboard keys and pointer actions
The particular bindings of variables, attributes, keys, and pointer actions within
a style are responsible for the Editor’
s distinctive behavior when that style is
active.
The difference in key bindings from one style to another is obvious: the Linefeed
key, for instance, invokes "e d t Delete Previous Word" in "EDT Emulation" style,
but in "VAX l i s p " style, it invokes "New l i s p Line". The differences in variable
and attribute bindings are less obvious when you are using the Editor, but they
are equally important in determining the Editor’
s behavior. For instance:
• When "e d t Emulation" style is active, the Editor “
knows”in what direction
it is to execute movement and search commands by the current value of the
Editor variable "e d t Direction Mode" (:f o r w a r d or :b a c k w a r d ). Outside of
"e d t Emulation" style, this variable is unbound and you must provide needed
directional information in some other way.
• When "VAX l i s p " style is active, the Editor “
knows”that a semicolon is
the beginning of a LISP comment because this character has the value
:c o m m e n t -d e l i m i t e r for the Editor attribute "LISP Syntax". Outside of "VAX
l i s p " style, this attribute is unbound and the Editor does not recognize any
characters as significant in LISP syntax.
The Editor’
s distinctive behavior in a style also arises from the particular
commands that you normally invoke in that style. For instance, the command
"EDT Delete Previous Word" differs slightly from the "Delete Previous Word"
command bound in "e m a c s ", just as the text-deleting commands in D igital’
s EDT
differ slightly from the delete commands in EMACS editors. While commands
themselves are not context-dependent, many commands are normally used only
within a particular style:
Operations on Styles

6-1

• Commands frequently are invoked by means of key sequences or pointer
actions, and these bindings are context-dependent (see Section 3.4).
• Many commands reference Editor variables and Editor attributes, which are
also context-dependent. Such a command will behave differently where the
context-dependent object is unbound or bound differently (see Section 2.2.6).
This chapter introduces several kinds of operations that you can perform on
styles when you are customizing the VAX LISP Editor. You can:
• Choose the styles that are active in any or all buffers
• Modify or extend a style provided by Digital
• Create a new Editor style
More information about styles can be found in Part II.
Recall that the symbols for Editor objects Digital provides must be referenced in
the editor package. For the methods of specifying named Editor objects, including
styles, see Section 1.3.3.2.

6.1 Activating and Deactivating Styles
For the bindings in a style to be visible in an interactive session, that style must
be active in the current buffer. Styles are activated in each buffer when the buffer
is created; you can later access and change the active styles in a buffer at any
time.
A buffer can have zero or one major style and zero or more minor styles. There
is no inherent difference in style objects that makes them major or minor. The
difference arises from the way a style is activated in a buffer. The difference
between major and minor activation becomes significant when the Editor
searches for the proper binding of a key sequence, a pointer action, a variable, or
an attribute.
In searching for the proper binding for a context-dependent object, the Editor
searches the currently active contexts in the following order:
1. The current buffer
2. The minor styles of the current buffer, if any, beginning with the most
recently activated
3. The major style, if any, of the current buffer
4. The global Editor context
The Editor uses the first binding it encounters in this search for the object in
question. If the object is bound in more than one of these contexts, then all but
one of the bindings are inaccessible, or shadowed. For instance, if you have "e d t
Emulation" active as the major style and "VAX l i s p " active as a minor style,
the Linefeed key will invoke "New l i s p Line". The binding of that key in "EDT
Emulation" style ("EDT Delete Previous Word") is shadowed.
Further information on context search and shadowing can be found in Part II of
this manual and in the VAX LISP/VMS Program Development Guide.
This search order suggests that, in general, your major style should be a generalpurpose style that determines a wide range of Editor capabilities—h ow the Editor
manipulates text, moves the cursor, manages the display, reads in and writes to
files, and so on. The two styles Digital provides that are suitable for use as major
styles are "e d t Emulation" and "e m a c s ".
6-2

Operations on Styles

A minor style is typically a more limited set of bindings that you use to alter
some details of the major style in particular circumstances. "VAX l i s p " style,
for instance, enhances either "e d t Emulation" or "e m a c s " to enable you to edit
LISP code. The general-purpose style is activated as the major style so that it is
the last style searched for bindings. The special-purpose style (added as a minor
style) can add variations to the major style because it shadows the major style.
This section outlines the methods of activating styles in buffers:
• Activating styles in a newly created buffer
• Setting the Editor’
s default styles
• Accessing and altering the styles in an existing buffer

6.1.1

Styles in a New Buffer
Most buffers are created automatically by the Editor whenever you begin to edit a
file or function. You can also make buffers yourself in LISP code. In either case,
the new buffer can be created with specified style(s) active.
The function m a k e -b u f f e r takes a buffer-name and returns a new buffer and t (or
The optional keywords :m a j o r -s t y l e
and :m i n o r -s t y l e s let you specify the styles that are to be active in the new
buffer.
n i l if a buffer of that name already exists).

• The name argument can be a symbol or a list containing a symbol and a
string argument to the keyword :d i s p l a y -n a m e .(This naming convention is
the same for all named Editor objects; for further detail, see the discussion of
naming Editor commands in Section 2.2.1.)
• The :m a j o r -s t y l e argument can be a style specifier or n i l .
• The :m i n o r -s t y l e s argument can be a list of style specifiers or n i l .
For example:
(make-buffer ' (mybuffer :display-name "Mybuffer.lsp")
:major-style "EDT Emulation"
:minor-styles '("VAX LISP"))

This form creates a buffer named mybuffer, with the alternative specifier
" M y b u f f e r .lsp". Its major style is "e d t E m u l a t i o n " and its one minor style is
"VAX LISP".

If you do not specify style arguments, the Editor supplies default values. If
you want the buffer to have no minor styles (or no major style), you supply the
argument n i l to the appropriate keyword. The defaults, and the techniques of
changing them, are presented in the next section.

6.1.2

Editor’s Default Styles
The Editor supplies default values for the major and minor styles of a newly
created buffer unless otherwise specified in the m a k e -b u f f e r form. You can access
and change these default values.
Note that changing a default value does not affect buffers that already exist.
Only buffers created after the default has changed will have the new default
styles active.

Operations on Styles

6-3

6.1.2.1

Default Major Style

The Editor’
s default major style is stored as the value of the Editor variable
"Default Major Style". In the Editor as provided, this value is "EDT Emulation".
You can use s e t f to change the default major style:
(setf (variable-value "Default Major Style") "EMACS")

Note that only the global value of this variable is used.
6.1.2.2

Default Minor Style(s)

The Editor’
s default minor styles are stored as the value of the Editor variable
"Default Minor styles". The possible values are a list of style specifiers or n i l .
In the Editor as provided, this variable is used only globally, and its value is n i l .
You can establish a default minor style by resetting the value of "Default Minor
styles". If, for instance, you want to retain "e d t Emulation" as the Editor’
s
default major style but add "e m a c s " as the default minor style, you could write:
(setf (variable-value "Default Minor Styles") '("EMACS"))

Note, however, that if you had established a default minor style previously,
the form as written would remove that style as the default and replace it with
"e m a c s ". To add "e m a c s " without removing the previous default, you could use
PUSH.
(push "EMACS" (variable-value "Default Minor Styles"))

This form adds "e m a c s " to the front of the list of default minor styles. The minor
styles are activated in a buffer in reverse order to their position in the list. That
is, the first style in the list is the last activated and thus the first searched when
the Editor conducts a context search. In this example, "e m a c s " will shadow other
minor styles (as well as the major style) active in the same buffer.
You can access and change the entire minor style list if you want to change the
order of the elements or add another style somewhere other than to the front of
the list. For instance, suppose you have established "VAX l i s p " as the default
minor style and you now want to add "e m a c s ". If you added "e m a c s " with p u s h ,it
would shadow "v a x l i s p ". To have "VAX l i s p " shadow "e m a c s ", you would write:
(setf (variable-value "Default Minor Styles")
' ("VAX LISP" "EMACS"))

This form makes "v a x l i s p " the last-activated (and therefore the first-searched)
of the minor styles in any buffer that has the default minor styles.
6.1.2.3

Default Minor Style(s) by Type of Buffer

If a minor style is a special-purpose style, you may want to have it active only in
the buffers where the special capabilities are needed. For instance, "v a x l i s p "
style is activated automatically in buffers that are associated with LISP objects
or with files of the file type .LSP.
If you want to activate a minor style in buffers associated with a LISP object, you
reset the value of the Editor variable "Default l i s p Object Minor styles". The
value is a list of style specifiers, such as:
(setf (variable-value "Default LISP Object Minor Styles")
' ("My New Style" "VAX LISP"))

6-4

Operations on Styles

This form specifies that two minor styles, "My New style" and "VAX l i s p ", are
to be activated in any buffer associated with a LISP object. These styles will
be searched in the order shown; they will be searched before any styles in the
"Default Minor Styles" list.
If you want to activate a minor style in buffers associated with a specified type of
file, you reset the value of the Editor variable "Default Filetype Minor styles".
The value is an association list of the form:
((filetype-string . minor-style-list)

... )

For instance, the initial value of this variable is:
("LSP" . "VAX LISP")

Again, minor styles specified by this variable are activated after any styles
specified by "Default Minor styles", and are therefore searched first.
6.1.2.4

Example of Activating Default Styles

This section illustrates the activation of multiple default styles in several buffers.
The search order, which is the reverse of the order of activation, is then shown for
each buffer.
Suppose you have five styles to work with: " e d t Emulation", " e m a c s " , " v a x
l i s p " , and two user-defined styles, " l i s p Variation" and " f o r t r a n " . One way to
set your default activation values is as follows:
(setf (variable-value "Default Major Style") "EDT Emulation")
(setf (variable-value "Default Minor Styles") '("EMACS"))
(setf (variable-value "Default LISP Object Minor Styles") '("VAX LISP"))
(setf (variable-value "Default Filetype Minor Styles")
'(("lsp" . ("LISP Variation" "VAX LISP"))
("for" . "FORTRAN")))

In buffers that have the default styles, the search order is as follows:
In a buffer named "Myfile.txt":
1.

"EMACS"

"EDT Emulation"

In a b u f f e r n a m e d l i s p - f u n c t i o n :
1.

"VAX LISP"

"EMACS"

"EDT Emulation"

In a buffer named "Myfile .lsp":
1.

"LISP Variation"

"VAX LISP"

"EMACS"

"EDT Emulation"

In a buffer named "Myfile.for":
1.

"FORTRAN"

"EMACS"

"EDT Emulation"
Operations on Styles 6-5

6.1.3

Styles in an Existing Buffer
You can access and change the styles in a specified buffer at any time.
Note that changing the active style(s) in one buffer has no effect on any other
buffer.

6.1.3.1

A Buffer’s Major Style

The function b u f f e r - m a j o r - s t y l e takes a buffer specifier and returns the major
style of that buffer (or n i l if the buffer has no major style). You can use s e t f
with this function to change the major style active in a buffer:
(setf (buffer-major-style "Mybuffer.txt") "EMACS")

This form deactivates the major style, if any, of "Mybuffer.txt" and activates
" e m a c s " instead.
6.1.3.2

A Buffer’s Minor Style(s)

You can also access and alter the minor style or styles active in a specified buffer.
To determine whether a specified buffer has minor styles active, you can use
the function b u f f e r - m i n o r - s t y l e - l i s t . This function takes a buffer object and
returns a list of the minor styles active in that buffer:
(buffer-minor-style-list (find-buffer "Mybuffer.txt"))
b u f f e r - m i n o r - s t y l e - l i s t is an accessing function only. Because it is not a place
form acceptable to s e t f , you cannot use it to alter the list of minor styles active
in a buffer.

To alter the list, you use the function b u f f e r - m i n o r - s t y l e - a c t i v e . This function
takes a buffer specifier and a style specifier. It returns T if the specified style is
active as a minor style in the specified buffer; otherwise n i l . This function can be
used with s e t f to add or remove a style from the minor style list of the buffer.
For instance, to activate " v a x l i s p " as a minor style in the current buffer, you
could write:
(setf (buffer-minor-style-active (current-buffer) "VAX LISP") t)

This form adds "VAX L I S P " to the front of the minor style list for the current
buffer, " v a x l i s p " will then shadow all other active styles. This form is the
essential action of the command "Activate Minor style", provided by Digital,
which prompts for a style name and activates that style as a minor style in the
current buffer.
To d e a c t i v a t e "VAX l i s p " y o u w o u l d e n d t h e a b o v e s e t f f o r m w i t h n i l :
(setf (buffer-minor-style-active (current-buffer) "VAX LISP") nil)

This form is the essential action of the command "Deactivate Minor style"
Digital provides.
If you activate a minor style that is already active in the specified buffer, the
style moves to the front of the minor style list. The action actually deactivates
and then reactivates the style, making it the most recently activated (and thus
the first-searched).

6-6

Operations on Styles

6.2 Modifying a Style Provided by Digital
The three styles provided with the Editor can be extended and customized in any
way you like. The operations that you can perform to modify a style are:
• Binding keys and pointer actions in the style
• Binding Editor variables in the style and assigning values or function
definitions to them
• Binding Editor attributes in the style and assigning values for each attribute
to all characters
You can also define new variables and attributes and bind them in any style.
Only when an Editor variable or an Editor attribute is bound in a style can you
assign values (see Sections 6.2.2.3 and 6.2.3.3).

6.2.1

Binding Keys and Pointer Actions
A common way to extend a style is to bind keys or pointer actions to commands
in that style. The command to be invoked can be:
• A new user-defined command
• A command provided by Digital not currently bound in the style
• Any command that is currently bound to another key or pointer action in the
style

6.2.1.1

Finding Key Bindings

A complete list of the key bindings in the Editor as provided appears in Appendix
C. This list is organized by key or sequence, and it includes all bindings for each
key (buffer, style(s), and global).
To find the current key bindings in the Editor, including any you have added or
changed, you can execute the command "List Key Bindings". The Editor displays
all visible bindings unless you specify a style (or other context) in response to the
prompt.
If you want to find the current key bindings from the LISP interpreter, you can
call the function m a p -b i n d i n g s . (This function is described in full in Part III.)
Basically, m a p -b i n d i n g s finds all key bindings and applies to them a function
that you supply as its argument. To get a list of the bindings, you would supply a
printing function.
For instance, if you wanted to print a list of the bindings in "v a x l i s p " style, you
could start by defining a new function such as:
(defun lisp-bindings (key command context)
(when (equal context (list :style (find-style "VAX LISP")))
(format t "~% ~{ ~:C~) ~30,10T ~A"
(coerce key 'list) (command-name command))))

You then call m a p -b i n d i n g s with the new function as its argument:
(map-bindings #'lisp-bindings)

The result is a screen display of all the keys and key sequences bound in "v a x
l i s p " style, along with the name of the command bound to each.

Operations on Styles

6-7

6.2.1.2

Review of BIND-COMMAND

You bind keys in a style according to the procedures outlined in Section 3.4.1. You
call the function b i n d -c o m m a n d with the command, key, and context arguments
that you want. Recall that to specify a style as a context argument, you supply a
list that begins with the keyword : s t y l e ,followed by a style specifier (symbol or
display name). For instance:
'(:style "EMACS")

or,
(list :style 'VAX-LISP)

To bind the key Ctrl/V to "view File" in "e d t Emulation" style, you would write:
(bind-command "View File" #\AV ' (:style "EDT Emulation"))

The binding procedure is the same regardless of whether the key sequence or the
command is bound in the style already. Rebinding a key sequence destroys any
previous binding of the key sequence; binding another key sequence to a command
leaves the previous key binding to that command intact (see Section 3.4.2).
The procedure for binding pointer actions is similar. See the discussion of b i n d p o i n t e r -c o m m a n d in Section 3.5.
6.2.1.3

Choosing Commands to Bind

When binding a key or pointer action to a command in a style, you should
first invoke the command by name in that style to make sure that it behaves
as expected. Any command can be bound in any style, but a command that
references a context-dependent object (an Editor variable or an Editor attribute)
may behave differently in different contexts.
For instance, if you invoke "e d t Move Word" in "e m a c s " style, the command does
not behave as it does in "e d t Emulation" style, "e d t Move Word" references
both the Editor variable "EDT Direction Mode" and the Editor attribute "Word
Delimiter"; both are unbound in "EMACS" style. It would not be worthwhile,
therefore, to bind a key to "e d t Move Word" in "e m a c s " style.
You can also define new commands with a particular style in mind and then bind
keys to them in that style. These procedures are explained in detail in Chapters
2 and 3.

6.2.2

Binding Variables and Setting Variable Values
Both the value slot and the function slot of an Editor variable can be set in the
context of a style, but only if the variable is first bound in that style. Binding an
Editor variable in a context establishes the variable as usable in that context.
Only then can its value or function definition be set.
The function slot is commonly used for hook functions, which are discussed in
Part II.
This section discusses several topics:
• Finding which variables are bound in a style
• Altering variable values in a style
• Binding a variable in a style
You can also define a new Editor variable and bind it in a style.

6-8

Operations on Styles

6.2.2.1

Finding Style Variables

The function s t y l e -v a r i a b l e s takes a style object and returns a list of the
variables that are bound in that style. For instance, the form
(style-variables (find-style "EDT Emulation"))

returns the list
(edt-deleted-line edt-deleted-word edt-deleted-character
select-region-rendition-set select-region-rendition-complement
edt-direction-mode default-window-label edt-paste-buffer)

To check whether a specified variable is bound in a specified style, you can use
v a r i a b l e -b o u n d p .This function takes a variable specifier and an optional context
that defaults to the current context. It returns T if the variable is bound in the
context; otherwise, n i l .
For instance, the first form below returns t ; the second returns n i l :
(variable-boundp "EDT Paste Buffer" ' (:style "EDT Emulation"))
(variable-boundp "EDT Paste Buffer" '(:style "EMACS"))

6.2.2.2

Altering Variable Values

To access the current value of an Editor variable bound in a specified style, you
call the function v a r i a b l e -v a l u e . Depending on the variable, the value might be
any object, including a function. (The function v a r i a b l e -f u n c t i o n accesses the
function slot; see Part III.)
For instance, to determine the current value of the variable "Select Region
Rendition Complement" in "EDT Emulation" style, you would write:
(variable-value "Select Region Rendition Complement"
' (:style "EDT Emulation"))

In the Editor as provided, this form returns :REVERSE.
Using s e t f , you can change the value of any variable in a specified style. In
the example above, you can change the video rendition of select regions in "e d t
Emulation" style. (See Section 5.3.1 for the meaning of the various region rendi
tion values.) To make select regions appear in bold if the window where they are
displayed is nonbold, and vice versa, you would write:
(setf (variable-value "Select Region Rendition Complement"
' (:style "EDT Emulation"))
:bold)

If the value of a variable is a function, you proceed in the same way. You access
the value with v a r i a b l e -v a l u e :
(variable-value "Default Window Label" ' (:style "EMACS"))

This form returns the function e m a c s -w i n d o w -l a b e l . This function could be
defined as follows:
(defun emacs-window-label (window)
(let ((buffer (window-buffer window)))
(format nil " ~A ~@[(~{~S~A ~}) ~]"
(if (eq (buffer-type buffer) :file)
(namestring (buffer-object buffer))
(buffer-name buffer))
(mapcar #'style-name (buffer-minor-style-list buffer)))))

Operations on Styles

6-9

This function specifies the default label content for any new windows created
in buffers where the style "e m a c s " is active (and not shadowed). It labels new
windows with the name of the buffer (namestring or object name) and with any
minor styles active in that buffer.
You can rewrite this function in any way you like or define an entirely new
labeling function, lb set the value of "Default window Label" in "e m a c s " style to
the new function, you would write:
(setf (variable-value "Default Window Label" '(:style "EMACS"))
'my-emacs-labeler)

6.2.2.3

Binding a Variable in a Style

A variable cannot have a value (or function definition) in a style unless the
variable itself is first bound in that style.
If a given variable is not bound in a style initially, you can include it with the
function b i n d -v a r i a b l e .Its format, with only a few of its keywords, is as follows:
BIND-VARIABLE s y m b o l &KEY :CONTEXT :INITIAL-VALUE

The symbol argument is an Editor variable specifier (symbol or display name).
The optional keyword arguments are a context specifier (the default is :g l o b a l )
and an initial value for the variable in the context (the default is n i l ).
For instance, suppose you want the Editor to show only one anchored window
at a time in "v a x l i s p " style, but up to two when you are not using "v a x l i s p "
style. The maximum number of anchored windows the Editor shows at a time is
determined by the value of the Editor variable "Anchored window show Limit".
In the Editor as provided, this variable is bound globally and its value is 2; the
variable is not bound in any other context.
If you want "Anchored Window Show Limit" to have the value 1 in "VAX LISP"
style, you must bind the variable in that style:
(bind-variable "Anchored Window Show Limit"
:context ' (:style "VAX LISP")
:initial-value 1)
T h is fo rm b inds "Anch o r e d W i n d o w S h o w Limit" in "VAX LISP" style w ith the

initial value l. If you later want to change the value to 3, you need only use s e tf
because the variable is already bound in the style:
(setf (variable-value "Anchored Window Show Limit"
'(:style "VAX LISP"))
3)

This form changes the value of the specified variable to 3 in "VAX l i s p " style.
The Editor will show up to three anchored windows at once when this style is
active. When "v a x l i s p " style is not active, the effective value of the variable
will be its global value, 2, unless you also bind it in other contexts.
6.2.2.4

Defining New Variables

If some action that you want the Editor to perform requires a new Editor variable,
you can create a variable with the macro d e f i n e -e d i t o r -v a r i a b l e .Y o u then
proceed as above to bind the variable in one or more contexts and to adjust its
value as you like.

6-10

Operations on Styles

DEFiNE-EDiTOR-v a r i a b l e is described in full in Part III. Basically, it creates
a variable with the specified name and an optional documentation string. For
instance:
(define-editor-variable (lisp-comment-column
:display-name "LISP Comment Column")
" When bound in \"VAX LISP\" style, this variable specifies an
integer value that indicates the position in a line where a LISP
comment should begin.")

This form is the one used to create the Editor variable "LISP Comment Column"
provided by Digital.
The naming convention for Editor variables is the same as that used for all
named Editor objects. For more detail on specifying names, see the discussion of
naming Editor commands in Section 2.2.1.
Before you can use a new variable, you must bind it in a context. For instance:
(bind-variable "LISP Comment Column"
:context ' (rstyle "VAX LISP")
:initial-value 49)

This form binds the variable in "VAX l i s p " style and gives it an initial value. The
variable now can be referenced by functions and commands in "VAX l i s p " style.
b i n d -v a r i a b l e

Part III.

6.2.3

also allows you to set the function slot of the variable. See

Binding Attributes and Setting Attribute Values
Another way to modify a style is to alter the treatment of Editor attributes in the
context of that style.
Like Editor variables, any attribute can be bound in any context. (An exception
is "Print Representation", which can only be bound globally.)
Once an Editor attribute is bound in a style (or other context), every character
has a value for that attribute in that context. The values for an attribute serve
to distinguish characters from one another for the purpose of searching through
text.
For instance, to find whitespace the Editor passes over every character with
the value 0 for the attribute "Whitespace" and accepts the first character with
the value l for this attribute. (See the discussion of searching by attribute in
Section 4.3.3.)
You can access and change the value that a character has for a specified attribute
in a specified style—but, as with Editor variables, you can do this only if the
attribute is itself bound in the style. This section discusses several topics:
• Finding the attributes and attribute values in a style
• Altering attribute values in a style
• Binding an attribute in a style
You can also define a new Editor attribute and bind it in a style.

Operations on Styles

6-11

6.2.3.1

Finding Style Attributes

The function character-attribute takes an attribute specifier, a character, and
an optional context. It returns the value that the character has for the attribute
in the context. (If you do not supply a context argument, the Editor performs a
normal context search to find the proper attribute value.)
The Editor provides no attribute-related functions similar to s t y l e - v a r i a b l e s
or m a p - b i n d i n g s . That is, there is no way provided to determine which Editor
attributes are bound in a style or what values all the characters have for an
attribute in a style.
To obtain this information, you might define a new function such as the following:
(defun list-attribute-values (attribute context)
;; Print a heading.
(format t "~%ATTRIBUTE VALUES OF ~S IN CONTEXT ~S ~2%"
attribute context)
;; Define a local error handler in case attribute in unbound.
(let ((*universal-error-handler*
#'(lambda (Srest args)
(declare (ignore args))
(format t
"~% The attribute ~S is not bound in ~
context ~S.~%"
attribute context)
(return-from list-attribute-values
(values)))))
;; Print the value of each character for the attribute in
;; the context.
(dotimes (index 255)
(format t "~C~15,5T<=>
~S ~%"
(code-char index)
(character-attribute attribute index context)))
(values)))

The new function l i s t - a t t r i b u t e - v a l u e s takes an attribute specifier and a style
(or other context) specifier. If you execute it at top-level LISP, it displays on the
screen a list of the values of all 256 characters for that attribute in that context.
If no values are found, the result is a screen message that the attribute is not
bound in the specified context. For instance:
(list-attribute-values "LISP Syntax" ' (:style "VAX LISP"))
(list-attribute-values "LISP Syntax" :global)

The first form results in a screen display of the values of all characters for
the attribute "l i s p Syntax" in "v a x l i s p " style. The second form results in a
message that the attribute "l i s p Syntax" is not bound globally.
Note the use of *u n i v e r s a l -e r r o r -h a n d l e r * in this form. If no special error
handler were defined, the function would call the VAX LISP error handler when
it encountered an unbound attribute. The default error handler places you in the
Debugger; this error handler returns you to top-level LISP.
6.2.3.2

Altering Attribute Values
character-attribute is a place form acceptable to setf. You can use it to change
the value that a character has for a specified attribute in a specified style.

For instance, the Editor recognizes a hyphen as a word delimiter in the global
context but not in ”e d t Emulation" style. If you want the hyphen to be a word
delimiter in "e d t Emulation", you change the value of that character for that
attribute in that style from 0 to l :

6-12

Operations on Styles

(setf (character-attribute "Word Delimiter" #\'(:style "EDT Emulation"))
1 )

After you execute this form, the Editor will recognize the hyphen as a word
delimiter in "e d t Emulation" style.
The attribute "l i s p Syntax" differs slightly from "Word Delimiter" in that
its values are keywords. Most characters in "VAX l i s p " style have the value
:c o n s t i t u e n t for the attribute "l i s p Syntax"—they can be constituents of LISP
symbols, but they have no syntactical significance. The characters that are signif
icant as LISP syntax have appropriate keyword values: the open parenthesis has
the value :l i s t - i n i t i a t o r , the backquote has the value :r e a d -m a c r o , and so on.
(The values for "l i s p Syntax" are listed in Part III.)
These keyword values can be altered in the same way as the zero-one values
illustrated above. For instance, if you want to use square brackets instead of
parentheses around LISP forms, you could write:
(setf (character-attribute "LISP Syntax" #\[ ' (:style "VAX LISP"))
:list-initiator)

and,
(setf (character-attribute "LISP Syntax" #\< ' (:style "VAX LISP"))
:constituent)

These forms, along with comparable forms for the close bracket and close paren
thesis, make the Editor recognize the brackets as the characters that initiate
and terminate a list in "VAX l i s p " style. The Editor will no longer recognize
parentheses as significant in LISP syntax.
6.2.3.3

Binding an Attribute in a Style

Characters cannot have values for an attribute in a style unless the attribute is
bound in that style.
If a given attribute is not bound in a style initially, you can include it with the
function b i n d -a t t r i b u t e . Its format is:
BIND-ATTRIBUTE attribu te &KEY :TYPE CONTEXT :INITIAL-VALUE

In addition to the desired attribute and context specifiers, you can supply to
b i n d -a t t r i b u t e a :t y p e argument and an : i n i t i a l -v a l u e argument. The type
argument defines the data types of the possible values of the attribute in the
context. The argument can be any LISP type specification (see Common LISP:
The Language)-, the default is (mod 2).
The initial-value argument becomes the value of all 256 characters for the spec
ified attribute in the specified context. You can then use s e t f with c h a r a c t e r a t t r i b u t e to change the value assigned to any of the characters.
For instance, suppose you have established "e d t Emulation" as your default
major style and "e m a c s " as your default minor style. This action makes the
Editor behave like an EMACS editor that has an EDT keypad. Any conflicting
bindings will be resolved in favor of "e m a c s ".
However, the Editor attribute "Word Delimiter" is not bound in "e m a c s " style.
When "e m a c s " is the only style active, the global values for this attribute are
visible. When "e d t Emulation" is interposed in the search order between "e m a c s "
and the global context, then references to "Word Delimiter" produce the "e d t
Emulation" values. As a result, the Editor recognizes words the way D igital’
s
EDT does, rather than the way that EMACS editors do.

Operations on Styles

6-13

You can alter this behavior by binding "Word Delimiter" in "EMACS" style and
assigning the characters the values you want them to have, lb bind the attribute,
you write:
(bind-attribute "Word Delimiter" :type ' (mod 2)
:context '(:style "EMACS")
:initial-value 0)

When you execute this form, "Word Delimiter" becomes bound in "emacs" style,
and all characters have the value o for this attribute in this context. You need not
include the :type argument in this form since (mod 2) is the default; it specifies
that the possible values for the attribute are o and l .
You then select the characters that you want the Editor to recognize as word
delimiters and change their values to 1. If you want the values to be set as they
are in the Editor’
s global context, you can get a list of those values by calling
l i s t -a t t r i b u t e -v a l u e s (see Section 6.2.3.1) with the context argument : g l o b a l .
For instance, many punctuation marks are word delimiters in the global context
but not in "EDT Emulation". To have these characters be word delimiters in
"EMACS", you write the following form for each:
(setf (character-attribute "Word Delimiter" #\; '(:style "EMACS"))
1 )

You perform no operation on characters that you do not want recognized as word
delimiters in "emacs". These characters already have the value 0 (the initial
value) for this attribute in this style.
6.2.3.4

Defining New Attributes

If some action that you want the Editor to perform requires a new Editor at
tribute, you can create an attribute with the macro d e f i n e -a t t r i b u t e . This
macro is similar to d e f i n e -e d i t o r -v a r i a b l e : it creates a new object with the
specified name and optional documentation string. You then proceed as above to
bind the attribute in one or more contexts and to adjust characters’
values for the
attribute as you like.
The following form is the one used to create the Editor attribute "Page
Delimiter" provided by Digital:
(define-attribute (page-delimiter :display-name "Page Delimiter")
" When bound, this attribute can have the value 1 for characters
that separate pages.")

This form creates the attribute "Page Delimiter". The attribute cannot be used,
however, until it is bound in some context. For instance:
(bind-attribute "Page Delimiter" :initial-value 0)

This form binds "Page Delimiter" in the default context (global) with the default
type specification (mod 2). The initial value for all characters in the global
context for this attribute is 0.
To distinguish the character(s) that you want the Editor to recognize as page
delimiters, you change their values from o to l :
(setf (character-attribute "Page Delimiter" #\formfeed) 1)

This form gives the f o r m f e e d character ('■l ) the value l for "Page Delimiter" in
the global context. When the Editor performs an attribute search to find the next
page delimiter, the f o r m f e e d character will satisfy the test (see Section 4.3.3).

6-14

Operations on Styles

6.3

Creating a New Style
To create a new Editor style, you first make a new style object. You then bind in
the new style all the features that you want it to have.
Creating a new style brings together all the techniques discussed so far in this
manual:
• Defining new commands, variables, and attributes as necessary to perform
text operations, display operations, and other Editor operations
• Binding keys, pointer actions, variables, and attributes in the new style
• Activating the new style in any or all buffers
You can also include in a new style some specially defined functions that are
invoked whenever the style is activated or deactivated in a buffer. These “
hook
functions”create some useful feature in buffers where the style is active and
remove that feature whenever the style is deactivated.
All these procedures are illustrated in this section in relation to a new Editor
style.

6.3.1 Making a Style Object
To create a new style object, you use the macro m a k e -s t y l e . This macro is
described in full in Part III. Its format is:
MAKE-STYLE n a m e &OPTIONAL d o c u m e n t a tio n
&KEY :ACTIVATION-HOOK :DEACTIVATION-HOOK

For example:
(make-style (text-mode :display-name "Text")
" Used when editing narrative text. It emulates the
behavior of word-processing programs in formatting text.")

If you evaluate this form, the Editor will have a new style named t e x t -m o d e
or "Text". The style will contain no bindings until you add them with calls to
BIND-VARIABLE, BIND-ATTRIBUTE, BIND-COMMAND, or BIND-POINTER-COMMAND.
Before you make the style, however, you should decide whether you want it to
have activation and deactivation hooks. These functions can be attached to a
style in the m a k e -s t y l e form; they cannot be added later.

6.3.2 Style Activation and Deactivation Hooks
A style activation hook can be used to perform some operation that you want
done every time the style is activated.
For instance, in a text-related style you need to be able to set margins—the
character positions in each line where text is to begin and end. You can define
new Editor variables to store margin settings and then bind the variables in each
buffer that has "Text" style active. This action enables each buffer to store its
own margin settings.

Operations on Styles

6-15

The new variables might look like this:
(define-editor-variable (local-left-margin :display-name "Local Left Margin")
,f Specifies the first character position where text can begin in each line.")

and,
(define-editor-variable (local-right-margin :display-name "Local Right Margin")
"

Specifies the last character position that text can occupy in each line.")

It would be convenient to have these variables bound automatically in each buffer
that has "Text" style active. To achieve this, you can define a function that binds
the variables in a buffer and then specify that function as the activation hook of
the style "Text".
The style activation hook is invoked whenever its style is activated in a buffer.
The hook function is called with two arguments—the style and the buffer. A
function that binds the above variables on a per-buffer basis might look like this:
(defun bind-margins (style buffer)
;; The function does not use the STYLE parameter.
(declare (ignore style))
;; CONTEXT is the buffer where the style is being activated.
(let ((context (list sbuffer buffer)))
;; Make the left margin 0 in the buffer.
(bind-variable "Local Left Margin"
:context context
:initial-value 0)
;; Make the right margin 1 less than the screen width in
;; the buffer.
(bind-variable "Local Right Margin"
:context context
:initial-value (1- (screen-width)))))

A style deactivation hook is similar: it is invoked whenever a style is made
inactive in a buffer. If you deactivate "Text" style in a given buffer, you would
have no further use for the margin settings. A deactivation hook that unbinds
the margin variables might look like this:
(defun unbind-margins (style buffer)
(declare (ignore style))
(let ((context (list ibuffer buffer)))
(unbind-variable "Local Left Margin" context)
(unbind-variable "Local Right Margin" context)))

Once you have defined the hook functions and the variables they reference, you
are ready to create the new style "Text":
(make-style (text-mode :display-name "Text")
" Used when editing narrative text. It emulates the
behavior of word-processing programs in formatting text."
:activation-hook #'bind-margins
:deactivation-hook #'unbind-margins)

This form creates the new "Text" style and establishes b i n d -m a r g i n s and
u n b i n d -m a r g i n s as its activation and deactivation hooks.

6.3.3

Adding Capabilities to the Style
Once you have created a new style, you can add features to it at any time. You
can add capabilities to a style with the following procedures:
• Binding keys or pointer actions to commands in that style. This may involve
defining new functions and commands; you can also use existing commands.

6-16

Operations on Styles

• Binding Editor variables in the style. The variables to be bound can be new
or existing variables. Any variable referenced by a command used in the
new style must be bound in that style, unless a binding will be visible from
another context when the style is active.
• Binding Editor attributes in the style. The attributes to be bound can be new
or existing attributes. Any attribute referenced by a command used in the
new style must be bound in that style, unless a binding will be visible from
another context when the style is active.
For instance, the "Text" style might include a key binding for a command that
allows you to reset the margins in any buffer. The new Editor variables "Local
Left Margin" and "Local Right Margin" serve to store margin settings once
they are bound in a buffer. The activation hook function b i n d -m a r g i n s binds
these variables in a buffer and sets their initial values whenever "Text" style is
activated in the buffer.
To implement a command called "Set Margins", you can use the new margin
variables, along with various Editor objects and other LISP objects. Such a
command might look like this:
(define-command (set-margins-command :display-name "Set Margins")
(prefix)
" Prompts for new margin values and resets the left and right
margins to the new values."
(declare (ignore prefix))
(let ((new-margin (or "Local Left Margin" 0)))
(setq new-margin
(simple-prompt-for-input
(format nil
"Current left margin at ~D. Enter new value: "
new-margin)
new-margin))
(unless (integerp new-margin)
(setf (variable-value "Local Left Margin")
(parse-integer new-margin)))
(setq new-margin (or "Local Right Margin"
(1- (screen-width)))
new-margin
(simple-prompt-for-input
(format nil
"Current right margin at ~D.
new-margin)

Enter new value: "

new-margin))

(unless (integerp new-margin)
(setf (variable-value "Local Right Margin")
(parse-integer new-margin)))
(clear-information-area)
(format *information-area-output-stream*
"Left margin ~D, right margin ~D"
"Local Left Margin" "Local Right Margin")))

With the new text-formatting style in mind, you could also write commands that
wrap text, that move to the left margin to begin new lines, and that fill and
justify text to the right margin.

Operations on Styles

6-17

Once the new commands are defined, you can bind keys to them in "Text" style:
(let ((context (list :style "Text")))
(bind-command "Set Margins" '#(#\X #\M) context)
(bind-command ... )
(bind-command ... ))

6.3.4

Activating the Style
Once your style has enough capabilities bound in it to be useful, you can then
decide how and where you want to activate the style.
As a special-purpose style, "Text" is suitable for minor activation. You would not
want to assign it to "Default Minor styles”, since its behavior (wrapping, filling,
and so on) is inappropriate for most code editing. It would be best to activate
"Text" in buffers associated with the file types you normally use for narrative
text editing.
Recall that the value of "Default Filetype Minor styles" is an association list.
You can add items to this list with p u s h :
(push ' ("txt" . "Text")

(variable-value "Default Filetype Minor Styles"))

(push ' ("rno" . "Text")

(variable-value "Default Filetype Minor Styles"))

These forms establish "Text" as the last-activated (first-searched) of the minor
styles in buffers associated with file types .TXT and .RNO.

6-18

Operations on Styles

Part II
Concepts in Editor Programming

Concepts in Editor Programming
This part is an “
encyclopedia”of the major concepts and data types used in
programming the VAX LISP Editor. It consists of separate, alphabetically
arranged articles on the following topics:
Attributes
Buffers
Characters
Checkpointing
Commands
Context
Debugging Support
Editor Variables
Errors
Hooks
Information Area
Lines
Marks
Named Editor Objects
Prompting
Regions
Rings
Streams
String Tables
Styles
Windows
See Appendix A for a list of the functions and other Editor objects that relate to
each of the object types described in this part.

Attributes
Attributes make up the primary character-related information stored by the
Editor. An attribute is a named Editor object having a LISP type specification
in some context. Each of the 256 characters can be assigned a value of the
specified type for an attribute. The function l o c a t e -a t t r i b u t e is used to locate a
character that satisfies a test on the value it has for an attribute.
For example, the following form defines an Editor attribute called whitespace or
"Whitespace":
(define-attribute (whitespace :display-name "Whitespace")
" Used to determine which characters can be considered
word delimiters.")

You can then bind this attribute in a context. For instance:
(bind-attribute 'whitespace
:type ' (mod 2)
:context :global
:initial-value 0)

This form creates an instance of the "Whitespace" attribute that can take on the
values 0 or l.
If we set
(setf (character-attribute 'whitespace #\space) 1)
(setf (character-attribute 'whitespace #\tab) 1)
Concepts-3

Concepts in Editor Programming
then executing
(locate-attribute text-position "Whitespace" :test #'plusp)
lo c a te s th e fir st

space

tab

c h a r a c t e r f o llo w in g t h e s p e c if ie d te x t- p o sitio n .

Attributes are powerful tools in processing syntax-dependent text. An attribute
value can be of any LISP data type. However, the test function may assume that
attribute values are of a certain type. For instance, the values for the attribute
"l i s p syntax" are keywords, whereas other attributes provided by Digital have
integer values. The test functions for the latter are normally one-argument
predicates.
Attributes, like Editor variables, can be bound in any Editor context. In the
example above, an Editor style might create a new binding of the "Whitespace"
attribute. This new binding would shadow the global binding of "Whitespace".
When the style was later made inactive, the global definition would be in effect
again.

Buffers
A buffer is the only Editor object that can be displayed and that can be associated
with a file or a LISP object.
The text contained in a buffer is defined by a region associated with the buffer—
the buffer region. Although there may be many regions that mark off sections of
the buffer’
s text, it is the buffer region that defines the beginning and end of the
text in a buffer. It is an error to alter the marks that define the buffer region.
Each buffer has a permanent mark associated with it called the b u f f e r p o i n t .
The buffer point is a left-inserting mark that is a point of attention for the buffer
(where most text operations commands are executed). The underlying display
functions of the Editor cause the screen cursor to track the buffer point when that
buffer is the current one. Moving the cursor therefore is accomplished by moving
the buffer point mark. Most normal character insertion and deletion operations
are performed with respect to the buffer point. It is an error to change the type
of the buffer point or to change the point so that it points to text not contained in
the buffer.
The Editor can maintain a number of buffers simultaneously. The limit on the
number of buffers depends on the size of available LISP dynamic space. It is also
possible to display simultaneously portions of more than one buffer or different
portions of the same buffer.
The current buffer is the buffer you are currently working on. The screen cursor
is always displayed in one of the display windows for the current buffer. The
concept of the current buffer is important because dynamic context is determined
by the setting of that buffer.

Concepts—4

Concepts in Editor Programming

Characters
Characters in the Editor are normal VAX LISP string characters; that is, s t r i n g Characters are not,
however, independent atomic objects in the context of the Editor; they are always
constituents of Editor lines.
c h a r -p returns T for all characters stored in Editor buffers.

VAX LISP recognizes and accepts all characters from the 8-bit extended ASCII
character set. All Common LISP font and bit information is ignored by the Editor.
Not all characters can be displayed directly on a terminal, of course. Any char
acter that cannot be displayed directly on a screen is converted to a string of
printing characters. Such a string is displayed on the terminal as a represen
tation of the actual character. For example, the ASCII ESCAPE character is
displayed as <ESCAPE>. See the description of the "Print Representation"
attribute in Part III for more detail.

Checkpointing
The VAX LISP Editor provides a mechanism for protecting the results of an
editing session from catastrophic failure such as a system crash. Without such
protection you could lose the results of many hours of work if the system were
to fail. The protection mechanism adopted by the VAX LISP Editor is called
“
checkpointing.”
Checkpointing involves writing to disk the full contents of any buffer that was
modified since the last checkpoint. The buffer is written to a file that has a
different (and distinctive) name from the file name associated with the buffer
source. By default, the checkpoint file name is:
SOURCE.FILETYPE_VERSION_LSC

where SOURCE, FILETYPE, and VERSION correspond to the file name of the
source file being edited. For example, the name of the checkpoint file created
when you are editing version 2 of a file named MYPROG.LSP is:
MYPROG.LSP_2_LSC

Buffers that are not associated with files do not, by default, have checkpoint files
associated with them.
You can set or change the checkpoint file name explicitly by using s e t f with the
b u f f e r -c h e c k p o i n t e d function. If you change the checkpoint file name to n i l ,
checkpointing is not performed for that buffer. The checkpoint file name is also
changed automatically whenever the pathname of the buffer’
s associated file is
changed.
The Editor determines when to checkpoint by maintaining a count of the number
of commands that caused modifications in the buffer text. The count is kept on
a global basis (otherwise many modified files might never be checkpointed). You
can determine the frequency (number of commands) of checkpointing by calling
the function c h e c k p o i n t -f r e q u e n c y .This function is also a s e t f form that allows
you to change checkpoint frequency. The default value is 350. If it is set to n i l ,
all checkpointing is disabled.

Concepts-5

Concepts in Editor Programming
Should there be a catastrophic failure of the system during an editing session,
you can recover a file in its most current state by looking for its checkpoint file.
Checkpoint files are deleted when modified buffers are written. If a checkpoint
file exists, it is guaranteed to be the latest available copy of the buffer contents.
The user can rename a checkpoint file to the buffer file name. Editing this file
gets the most recent information that was in the Editor before the crash. Only
modifications made to text between the time of the last checkpoint and the system
failure are lost.

Commands
Commands are similar to function objects in that they can be invoked to produce
changes in the state of the Editor. They are unlike ordinary LISP functions
in how they are invoked and in the context rules for their execution. Every
command is associated with a LISP function; invoking a command within the
Editor causes the Editor to invoke the command’
s associated function.
Binding an Editor command can be thought of as creating a bridge between a
character or sequence of characters and a command in a particular context. You
accomplish this by executing the b i n d -c o m m a n d function. If you then enter a key
or key sequence from the terminal, the Editor makes a normal context search
to find the correct command to execute. You can also bind actions of a pointing
device to Editor commands by using the function b i n d -p o i n t e r -c o m m a n d .
Invoking Editor Commands

There are three ways to invoke an Editor command:
• Entering a previously bound character or sequence of characters from the
keyboard, or performing a pointer action, when you are in the Editor
• Using the "Execute Named Command" command and specifying the name of a
command when you are in the Editor
• Calling the associated function directly from LISP
The first of these is the fastest method. These methods are discussed individually.
Using Bound Keys: The b i n d -c o m m a n d function is used to bind an Editor
command to a character or sequence of characters in a particular context. When
you enter this character or sequence of characters, the Editor initiates a normal
context search for a command object bound to that sequence. For example, by
default, all the individual graphic characters are bound to the command named
"Self insert" in the global context. If you type any of these characters, a
function that inserts the characters at the buffer point of the current buffer
executes.

The action of b i n d -p o i n t e r -c o m m a n d is similar except that the specified command
is invoked by an action of the pointing device, such as depressing a particular
button or moving the pointer cursor. As with bound characters, the Editor
performs a context search to determine which command to invoke in response to
a pointer action.

Concepts-6

Concepts in Editor Programming
The binding of a command, like that of a variable or an attribute, can be shad
owed by another binding to the same key (or key sequence) in a local context.
For example, when "VAX l i s p " style is active in the current buffer, the close
parenthesis character is bound to a function that finds and displays the matching
open parenthesis before inserting the right parenthesis. This binding shadows
the binding of the right parenthesis to "Self Insert" in the global context.
NOTE

If you redefine a command that is bound in some context, you must
rebind the appropriate key sequence or pointer action to that command
in order to have the new command executed.
Using Execute Named Command: Some commands (such as "Delete current
Buffer") are either infrequently used or are potentially too dangerous to be

bound to keys (where they might be invoked by accident). The VAX LISP Editor
has a command, "Execute Named Command", that allows you to enter the name of
a command and have the corresponding function executed.
The third method used to invoke a command is
to call the associated LISP function directly from another LISP function. To make
use of existing commands when writing a new Editor command, you must use the
function associated with the command.

Calling Associated Functions:

Command Categories

Commands can also have a list of categories associated with them. These cat
egories are user-defined and can be retrieved, tested, and altered. Examples of
command categories are :g e n e r a l -p r o m p t i n g and -.l i n e -m o t i o n .A command
might examine the categories of itself or of a previously invoked command and
perform different actions depending on the categories found.
Prefix Argument

Every function that implements a command takes at least one argument. This
argument is called the prefix argument, and it usually tells the function how
many times the operation is to be done. For example, if the "Self insert”
command is called with a prefix argument of 5, it inserts the most recently typed
character five times. The prefix argument is reset automatically to n i l each time
through the command loop. You use the "Supply Prefix Argument" command to
set the prefix argument for the next command to be executed.

Context
The VAX LISP Editor maintains a hierarchical search space to locate all Editor
key bindings, pointer action binds, variables, and attributes. The Editor must
search this hierarchy in order to determine the correct command for a key
sequence or pointer action, the correct value or function of an Editor variable, or
the correct value of an attribute.
The binding of commands, variables, and attributes must take place in some
context. The context can be as follows:
• Global, which means that the object is always defined

Concepts-7

Concepts in Editor Programming
• A style, which means that the object is defined in buffers that use the style as
either the major style or a minor style
• Specific to a particular buffer
Here is the search order of the hierarchy:
1. Current buffer
2. Minor styles active in that buffer in the order of most recently activated to
least recently activated
3. Major style of that buffer
4. Global Editor context
Only if the entire search fails is the command, variable, or attribute considered
unbound.
By default, the standard order is used to locate the value of an object. It is
possible to specify an explicit context for an accessing function (for example,
v a r i a b l e -v a l u e ). In this case, the normal searching operation is bypassed, and
the object is accessed in the specified context only. Every function that binds an
Editor object has an optional argument to define the context in which the created
object is stored for later access. In such situations, a context argument is always
specified with one of the following:
• The keyword : g l o b a l - The object is bound in the global context and is
universally accessible.
• A two-element list consisting of the keyword : s t y l e followed by a style speci
fier. The object is bound in the context of the specified style. For example:
'(:style "EDT Emulation")

• A two-element list consisting of the keyword :b u f f e r followed by a buffer
specifier. The object is bound in the context of the specified buffer; that is, it
is local to that buffer.
'(:buffer "Filename.lsp")

or
(list ibuffer (current-buffer))

where the function c u r r e n t -b u f f e r returns an Editor buffer.
As a result of the context and searching rules, the named objects can be thought
of as forming a hierarchy shown in Figure Concepts-!.

Concepts-8

Concepts in Editor Programming
Figure Concepts-1:

Hierarchy of Named Objects

Buffers

Commands

Variables

Attributes
MLO-002997

That is:
• Buffers can include active styles and bindings of commands, variables, and
attributes, but not other buffers.
• Styles can include bindings of commands, variables, and attributes, but not
buffers or other styles.
• Commands, variables, and attributes cannot contain bindings of one another.
Use of Context

A few conventions regarding the use of context by different users of the Editor
follow:
The global context is established by Digital when the
Editor is built. You can, of course, alter it, but you must be aware of any hook
functions or default variables that are supplied with the Editor. Styles sup
plied with the Editor often assume the existence of certain variables and hook
functions. Such assumptions are listed with the descriptions of the appropriate
The Global Context:

variables and commands.

If you want to alter the global context, you should check for any predefined
hooks or variables and ensure that they are either retained, or their use is not
necessary.
A Style Context: Styles are the province of writers of Editor extensions. A
writer of an extension should feel free to make whatever alterations, bindings,
variables, or attributes appropriate for implementing the desired style. A style
should not alter global context or local buffer context without care. In particular,
command bindings should be established only within the style.
A Buffer Context: Buffer-local bindings should be used for special-purpose
buffers such as "General Prompting". These buffers exist to provide special
capabilities not needed during normal text editing. The commands related to
help, alternatives, and completion are bound locally in the "General Prompting"
buffer because these commands have meaning only while the user is being
prompted.

Concepts-9

Concepts in Editor Programming
It can, however, be appropriate to bind Editor variables locally in a buffer. Such
bindings are proper when certain information necessary to the operation of a style
needs to be kept in each buffer.
"Buffer Select Mark" is an example of such an Editor variable. The "e d t
Emulation" style must keep track of any selected regions in each buffer that has

the style active. A style-local variable cannot be used because it would lose its
value whenever a region was selected in some other buffer. Each buffer, therefore,
keeps its own binding of "Buffer Select Mark".

Debugging Support
The normal action taken by the Editor’
s display subsystem when you execute
the command "Pause Editor" is to save the current state of the screen and clear
the screen. Conversely, when the Editor resumes after a pause, the current state
of the screen is lost and the display is reset to the appearance it had when the
pause went into effect.
This is reasonable behavior for a user who is doing normal editing operations.
It becomes a problem, however, for anyone implementing new Editor commands,
because it means that Editor functions cannot reasonably be called from the LISP
top level. The previous screen state is lost, and any windows created from top
level are lost when the Editor is reentered.
In order to have effective debugging support for Editor command implementers,
the Editor provides the variable *e d i t o r -r e t a i n -s c r e e n -s t a t e *. This LISP
special variable controls the action taken by the display subsystem when an
Editor pause is executed. If the value is n i l (the default), the display subsystem
takes its normal action of saving the current state and clearing the screen; if the
value is non-NiL, it does not save the screen state and clear the screen.
The display subsystem clears the screen and restores the old state only if the dis
play was saved at the last pause. This behavior allows a command implementer
to call Editor commands and functions from the LISP top level without losing
changes made when the Editor resumes (by means of a call to the e d function).
NOTE

In the DECwindows development environment, the "Pause Editor"
command does nothing because the Editor and the Listener each have
a separate window. The *e d i t o r -r e t a i n -s c r e e n -s t a t e * variable is
ignored under DECwindows.

Editor Variables
Editor variables are distinct from VAX LISP special variables. They are similar
to VAX LISP variables in that they can have both values and functions attached
to them. The scope and extent rules for Editor variables, however, are different
from LISP variables.
The scope of an Editor variable is defined by the Editor context-searching rules.
An Editor variable has extent that begins when it is bound in some context and
ends when it is unbound from that context.

Concepts-10

Concepts in Editor Programming
Editor variables are named objects, and special functions exist for accessing and
setting the value and function slots of variable objects. You can use the functions
v a r i a b l e -v a l u e and v a r i a b l e -f u n c t i o n for accessing the value or function
associated with an Editor variable. You can use them with s e t f to change the
value or function definition.
The LISP symbol corresponding to the Editor variable (the variable name) has its
value and function slots set according to the current context—that is, the symbol
can be used as a special variable. Its value changes according to the current
context. It becomes unbound in any context in which the Editor variable is not
bound. By using the LISP symbol, you can improve the access time to the value
or function of an Editor variable.
Similarly, the LISP symbol can be used as a LISP function inside an Editor
command. The function slot of the symbol is set to the function of the Editor
variable bound in the current context. If there is no function definition, the LISP
symbol has no function definition (f b o u n d p is n i l ).

Errors
In your extensions to the Editor, the Editor’
s error subsystem lets you handle
errors during the execution of Editor commands and notify the user of such
errors. In addition, a facility is provided to handle errors at the LISP level
(signaled from e r r o r or c e r r o r , for example) and place the user in a usable
debugging environment.
Errors Signaled from LISP

When you invoke the Editor (by means of the e d function), the variable
*u n i v e r s a l -e r r o r -h a n d l e r * is bound to an Editor function that intercepts
any LISP errors that occur (those signaled by e r r o r , c e r r o r , and a s s e r t , for
example). This function first asks you if modified buffers should be saved. If you
reply “
Y”
, the Editor attempts to save any buffers that were modified, although
the nature of the error may prevent some or all buffers from being saved. The
Editor then asks if you want to enter the VAX LISP Debugger. If you reply “
Y”
,
the Debugger is invoked; you have access to all the normal Debugger features. If
you reply “
N”
, control returns to the LISP top level.
You treat this error just as you would a LISP error at top level. You can take
whatever actions are appropriate to the error signaled. Throwing to top level
(by pressing ctrl/c or quitting the Debugger) causes the Editor to quit the current
command and pause. Continuing a continuable error causes a return to the
interrupted Editor function. The Editor screen state is not updated automatically,
but the display device is placed back in the mode required for operation of the
Editor.
Errors Signaled from the Editor

The Editor provides two error functions that you can use when writing Editor
commands—e d i t o r -e r r o r and e d i t o r -e r r o r -w i t h -h e l p .e d i t o r -e r r o r is similar
to the LISP e r r o r function but is more appropriate to the Editor environment.
When called, the function displays an optional line of text in the information area
of the screen, calls the a t t e n t i o n function to alert the user to a problem, and
executes a t h r o w to the top-level command loop of the Editor.

Concept&-11

Concepts in Editor Programming
This function is used typically to indicate an illegal command operation, invalid
user input, or some other such error that allows the Editor to continue normal
operation after it has discarded some improper data.
The second error function used by the Editor is similar to the VAX LISP c e r r o r
function. The e d i t o r -e r r o r -w i t h -h e l p function looks like e d i t o r -e r r o r but
takes an additional format string, which is used to provide additional information
to a user about the error that has occurred, You can retrieve this additional
formatted string by using the "Help on Editor Error" command.
For example, when the Editor is writing a file, an error might occur such as the
quota being exceeded. The Editor signals an error and displays a message in the
information area notifying the user of that fact. The e d i t o r -e r r o r -w i t h -h e l p
function formats detailed information about the error (the RMS error message),
which the user can retrieve if the problem is unknown by using the "Help on
Editor Error" command.

Hooks
When you are writing extensions to the Editor, it is often desirable to have
operations performed automatically when some particular part of the Editor state
changes. Such automatically executed operations are called hooks; the functions
that implement them are called hook functions.
The VAX LISP Editor implements hooks by attaching these functions to the
function slots of Editor variables. Such variables are called hook variables, and
their names, by convention, end with -h o o k .Any binding of a hook variable in
an Editor context can have only one function associated with it (not a list of
functions).
Two functions allow you to treat an ordinary Editor variable as a hook variable:
i n v o k e -h o o k and r e v e r s e - i n v o k e -h o o k . The arguments for each of these func
tions are an Editor variable optionally followed by additional arguments to be
passed to the hook functions.
Normally, reference to an Editor variable results in a context search to locate a
single instance of a variable. The invoking of a hook produces different behavior.
A context search is made to locate all the instances of the hook variable in the
context search list (buffer local, minor styles, major style, and global). Then a l l
the functions (if any) attached to the instances of these variables are called in the
i n v o k e -h o o k or r e v e r s e - i n v o k e -h o o k call. This is a major difference between
hook variables and other Editor variables.
It is important to note that in the normal case (a call to i n v o k e -h o o k ) the func
tions are called in the reverse order of the context search—global, major style,
minor styles (from oldest to newest), and buffer local. The purpose of this order
ing is to allow writers of styles and individual Editor users to modify effects of
more global hook changes rather than to supplant them completely.
The r e v e r s e -i n v o k e -h o o k function behaves identically to i n v o k e -h o o k except
that it calls the functions in normal context search order. All hooks built into the
VAX LISP Editor are called with the i n v o k e -h o o k function.
Setting a hook variable to a function in an Editor context will result in the loss of
any previous setting of the function slot of that variable in that context.

Concepts—12

Concepts in Editor Programming
To set hook variables to new functions without losing existing hooks, you can
set the variables in the context of a user-defined style. (See Section 6.3 for
information on creating styles.) When the new style is active, a reference to a
hook variable results in evaluating the new hook function as well as any other
hooks that are attached to that variable in other active contexts.
For instance, you can create a new style called "My l i s p Hooks" or "My Text
Hooks". You then define the hook functions you want and set them to the function
slots of the appropriate hook variables in the new style.

;;; Create a style to serve as a binding context.
(make-style (my-lisp-hooks :display-name "My LISP Hooks")
"

This style contains hooks related to editing LISP code.")

;;; Define hook functions.
(defun hook-1
(defun hook-2

... )
... )

;;; Bind the appropriate hook variables in the new style,
;;; specifying the initial function definitions.
(bind-variable "Name of Hook Variable"
:context ' (:style "My LISP Hooks")
:initial-function #'hook-1)
;;; Once the hook variables are bound in the style, they
;;; can be changed at any time using setf.
(setf (variable-function "Name of Hook Variable"
'(:style "My LISP Hooks"))
#'hook-2)

You can activate the new style in any given buffer by executing "Activate Minor
style" command. You can also have the style activated automatically by adding
it to the lists that are the values of the Editor variables "Default Minor styles",
"Default LISP Object Minor Styles", or "Default Filetype Minor Styles".

Information Area
The Editor supports a dynamic multiwindow display. Windows can be displayed
and moved to arbitrary locations. There is a reserved area at the bottom of the
screen, however, that is never deleted or overlapped by an Editor window. This
is the information area. This area is always at least one row in height and is the
full width of the screen; its size can be increased.
The purpose of the information area is to have a location with guaranteed vis
ibility where data can be displayed. Error messages are displayed here, as are
other messages such as those telling you what file was just written. There is a
global variable, *i n f o r m a t i o n -a r e a -o u t p u t -s t r e a m *, bound to an output stream
for this area.
The information area is not an Editor window and cannot be treated as such.
This means that there are no key bindings or Editor buffers associated with
it. The Editor window functions do not operate on the information area. The
information area should be used primarily as an information display area for the
user.

Concepts-13

Concepts in Editor Programming
The CLEAR- informat ion -area function erases any text currently in the informa
tion area.
The information -area- height function tells you the current height of the infor
mation area (in number of rows). You can change this value by using setf with
this form.

Lines
The line is the basic unit of text in the Editor; it contains a character string that
normally corresponds to a single displayed line of text. The string is exactly what
would be returned if you executed a read-line function on a text file. A line also
contains information concerning its own relative position within a group of lines,
as well as within a buffer that m ight contain a group of lines.
Execution of m ost of the Editor functions results, directly or indirectly, in the
alteration of either lines or their relations to other lines. The display subsystem
of the Editor displays groups o f specified lines.
Lines are created as by-products of certain Editor operations (such as making
empty regions, breaking lines, and reading files). They can be accessed either
through m arks that point into them or through following the forward and back
ward links between lines. You can alter lines by inserting or deleting characters
in the line, replacing individual characters in the line, deleting a region that is
a portion of a line, or replacing the entire text of a line. You can delete lines by
deleting regions that encom pass them.
A line is never shared am ong buffers or disem bodied regions. Altering or re
m oving a line in one buffer cannot affect lines in another buffer. But because
it is possible for regions to overlap or be contained com pletely in other regions,
altering or rem oving lines in one region can affect the contents of another region
in the sam e buffer or disem bodied region.

Marks
The ability to indicate any given position in text is central to the operation of any
editor. The V A X LISP Editor has a special type of LISP object, known as a mark,
for this purpose.
A mark contains two item s of information that allow Editor functions to access
specific characters in the text— a pointer to a line, and a number indicating the
character position on the line. I f you think of a single line of text as beginning
at the leftm ost position on the screen, then you can think of the representation
of a character position as the number of characters “
to the left”of the character
position of interest.
For purposes of text manipulation, you should think o f the mark as pointing
between two characters. Any character inserted at the position o f a mark is
always placed between the characters. With respect to the number representing
the character position, the mark points between positions re and n+1. The mark
can also point between the beginning of a line and the first character (re = 0), or
between the last character of a line and the end of the line.
Marks are of two types— permanent and temporary.

Concepts-14

Concepts in Editor Programming
There are two kinds of permanent marks. They differ with respect to whether
text is inserted following the mark (right-inserting) or preceding the mark (leftinserting). The two kinds of permanent marks are designated by the keywords
:l e f t - i n s e r t i n g and :r i g h t - i n s e r t i n g .Regardless of text insertions or dele
tions made before or after them, a right-inserting mark remains “
attached”to the
character that was to its left just prior to the operation; and a left-inserting mark
remains “
attached”to the character that was to its right.
A temporary mark, on the other hand, becomes invalid after any operation
affecting the character it points to. You define a temporary mark by using the
keyword :t e m p o r a r y . Temporary marks are used primarily in operations that
require a mark to be used just once. They are used because these marks require
less overhead in their creation and use than do permanent marks, and so are
much more efficient in some applications.
If the line that a temporary mark points into is deleted, the mark becomes invalid
and should no longer be used. If the line that contains a temporary mark is
affected by insertion, being copied, deletion, or being relocated, the temporary
mark becomes invalid and should no longer be used.
Marks are used primarily to indicate positions for character insertions or dele
tions. Unlike many LISP functions, the functions that manipulate marks are
usually destructive operations on the mark. Moving a mark, for example, al
ters the mark so that it points to a new location. Only the accessing functions
m a r k -l i n e and m a r k -c h a r p o s do not alter the mark. Marks can be shared among
regions. A given mark can be used to delimit any number of regions.
When a region of text is deleted, any permanent marks within that region
(including the beginning and ending marks of the deleted region) then point to
the location that is the junction of the text that preceded the deleted text and the
text that followed the deleted text.
Figure Concepts-2 shows marks 1, 2, and 3 pointing to the indicated positions.
Figure Concepts-2:

Before Deleting Region

A B C/ \D E F/ \ G H I J/ \ K L M N
1

MLO-002998

Concepts-15

Concepts in Editor Programming
If the region defined by marks 1 and 3 is deleted, the resulting text and mark
positions appear as shown in Figure Concepts-3.
Figure Concepts-3:

ABC

After Deleting Region

K L M N
/ \ / \ / \

1 2 3

MLO-002999

Named Editor Objects
Several types of Editor object are called named objects. A named object is a
special kind of LISP object. Once a named object is created, it can be referred to
in any of three ways:
• By means of an expression whose evaluation results in the actual object. For
example, (stylep variable) is true if, and only if, the value of the variable is
an Editor style.
• By m eans of a symbol defined at the time the object was created. For exam
ple, (find-command 'write-current-buffer-command) returns non-N IL only
if write-current-buffer-command was specified as the name of a command
when the command was created.

• By means of a string that is the display name defined at the time the object
was created. For example, (find-buffer "Jones.lsp") returns non-Nil only
if the string "Jones.lsp" was specified as a display name when the buffer
was created.
The specification of the name when you are creating a named object is the same
for each of the different types:
nam e

| (n a m e :DISPLAY-NAME str in g)

w here the following conditions exist:

• The name argument is a symbol.
• The string argument is a character string that can be specified as an alternate
access string to the object. If a display name is not specified, the print name
of the symbol is used as a display name.
Each named object can have a documentation string associated with it. Such a
string appears when the symbol of the object is described, or the d o c u m e n t a t i o n
function is used. The following documentation type is used in getting the docu
mentation string of a specified named Editor object:
(EDITOR)-(ype

where type is one of the types of named Editor objects (as listed below).

Concepts-16

Concepts in Editor Programming
The display nam es of all created named objects are stored in string tables. The
string table associated with each type of named object is bound to a special
variable of the form, *EDITOR-£ype-NAMES*. Use the string tables to find the
symbol associated with a given display name.

The following object types are named Editor objects:
• Editor Attribute
• Buffer
• Command
• Style
• Editor Variable
Buffers, styles, and commands are context-independent LISP objects—that is,
their creation functions (m a k e -b u f f e r , m a k e -s t y l e , and m a k e -c o m m a n d ) create and
return LISP objects of these types. The other two named object types (Editor
variables and Editor attributes) are context-dependent objects. That is, once
defined, they must be bound in a specific Editor context before they are used. In
addition, the current value of these objects depends on the current Editor context.

Prompting
Often, the user must be prompted for information necessary to the operation
of some function or command. The operation involves first telling the user what
information is needed and then soliciting the input data. For example, the "Write
Named File" command needs to ask the user to specify a file for the contents of
the buffer to be written to.
The VAX LISP Editor makes two functions available to you for creating a prompt:
PROMPT-FOR-INPUT and SIMPLE-PROMPT-FOR-INPUT.
Both functions make full use of the Editor capabilities for text processing and
display. They assume the ava ila b ility of a buffer with the display name "General
Prompting". This is a normal Editor buffer created with the value of the Editor
variable "Default Major style" as its major style. You can change this style as
you can for any other Editor buffer. This buffer also has a number of buffer-local
command bindings and Editor variables that alter its normal behavior to provide
additional prompting services to the user.
There is a window associated with the "General Prompting" buffer. This window
is always visible in the Editor (in the row or rows above the information area),
and most user interaction occurs in this window. Although the window is a
normal Editor window, only a few of the Editor window functions operate on it.
Specifically, the prompting window cannot be removed from the screen or moved
to a different screen position.

Concepts—17

Concepts in Editor Programming
Simple Prompting

The function s i m p l e - p r o m p t - f o r - i n p u t is the more basic of the prompting
mechanisms. It displays an optional string in the prompting window and solicits
a response from the user, which echoes in the prompting window. The prompt
function reads and returns the user’
s input as a simple string; there is no Editor
interpretation of the individual characters. If the user supplies a null input
string, an optional default argument is returned.
General Prompting

A much more general mechanism is provided with the p r o m p t - f o r - i n p u t func
tion. This function has special capabilities that you can use to develop elaborate
prompting schemes when you are creating commands.
Validating User Input: The one required argument to p r o m p t - f o r - i n p u t is the
validation function. This must be a function that accepts a string argument and
produces some value that will be returned by the p r o m p t - f o r - i n p u t function.

The validation function indicates that the input string is invalid by returning n i l .
In such an instance, p r o m p t - f o r - i n p u t signals an error to the user and awaits
further input. If the string input is a null string, and the value of the .‘R e q u i r e d
keyword is n i l , the value of the :d e f a u l t keyword parameter is returned. You
actually can allow the validation function to return n i l as a valid value by
returning multiple values of n i l and t .
An example of a function you can use for validation is f i n d - c o m m a n d . This func
tion returns a command function if the string is the name of a command, and
returns n i l if the string is not the name of a command.
Providing Input Completion: The p r o m p t - f o r - i n p u t function provides you with
facilities that can attempt to complete partial user input. For example, the user
might be generally familiar with a set of Editor commands, but not remember the
exact display name of the one needed. By using the completion facility, the user
can type a portion of the name of a command and ask the facility to complete the
name automatically. The user normally requests input completion by typing a
Ctrl/Space (the null character).

There are three ways you can supply such completion assistance to a user:
• If t h e a r g u m e n t t o t h e : c o m p l e t i o n k e y w o r d i s a s t r i n g , i t i s j u s t i n s e r t e d
i n t o t h e p r o m p t i n g b u ffe r .

• If the argument to the : c o m p l e t i o n keyword is a string table, the completion
function uses the text entered by the user as the key to the string table and
attempts to return a completed string that will be inserted automatically into
the prompting buffer.
The string table routines complete as much of the text as they can—supplying
the rest of the text string or only as much of it as is uniquely identifiable.
The user is informed of whether the input is now complete or if other entries
can be found starting with the same string. If no entry can be found to match
the user input, the facility deletes characters from the end of the user input
until some entry (possibly ambiguous) can be found in the string table. This
mechanism is used in the "Execute Named Command" command.

Concepts-18

Concepts in Editor Programming
• If the argument given to the : completion keyword is a function, that function
is called and passed any arguments specified in the : completion-arguments
keyword. You have complete control over the displayed contents of the
prompting buffer. This method is used by the "Edit File" command, which
attempts to complete user input by performing a directory search for a
matching file name.
Providing Alternatives: The alternatives option to general prompting is designed
to help the user choose among a set of alternative possibilities. For example,
when asked for a command name, the user might not know the exact spelling
of the name. Upon entering some input and asking for completion help, if the
Editor cannot respond with an exact command name, the user needs to be able to
get a list of possible names based upon the typed input. In such an instance, the
calling of the alternatives option—pressing keypad PF1 PF2—yields a displayed
list of commands whose names begin with the typed string.

The general prompting facility uses the :ALTERNATiVES and :ALTERNATivESarguments arguments to enable this form of help. The argument to :alternatives
can be a string table or a function. If the argument is a string table, that table is
searched to find all possible entries that start with the string the user has typed.
The list is automatically displayed in the "Help" buffer.
If the argument is a function, that function is called and passed any arguments
that were given in the :a l t e r n a t i v e s -a r g u m e n t s argument. This function can
perform any operations it needs and should provide a display of the user’
s options
appropriate to the command. For example, such a function might do a wild-card
directory search for possible file names.
If, at any point in p r o m p t -f o r - i n p u t , the user invokes the
"Prompt Help" command—presses keypad PF2—the function takes action based on

Providing Help:

the value of the : h e l p keyword. If the value is a string, that string is displayed
in the information area or in the "Help" buffer if the text has more lines than
will fit in the information area.
If the value is a function, that function is called and passed any arguments
that were specified in the :h e l p -a r g u m e n t s keyword. This method, like that
for completion, gives you, the command writer, all the flexibility necessary for
supplying assistance tailored to the needs of the user and the command.

Regions
A region contains a portion of text, which can be part or all of one or more lines
in a group of related lines. The region is defined by two marks, which indicate
the beginning and ending positions of the region. Regions are treated as blocks of
text that can be manipulated as units—deleted or inserted, for example.
The marks that delimit a region can be either temporary or permanent. You can
use temporary marks for one-time operations on regions. If you use permanent
marks, delimit the beginning of the region with a right-inserting mark and the
end of the region with a left-inserting mark. If you use a left-inserting mark at
the beginning of a region or a right-inserting mark at the end, and if you insert
text at the beginning or end, the results can be unpredictable.

Concepts-19

Concepts in Editor Programming
Regions can be of two types. The most commonly used region is a portion of text
inside a buffer. The region is defined by beginning and ending marks. Regions
of this type can share text with other regions. Regions can overlap in arbitrary
ways or be contained entirely within other regions. Since the text of multiple
regions can be shared, any alterations done in one region affect the text of any
other region containing the same text.
The second type of region is a disembodied region—a region of text not associated
with any buffer. This type of region can be created only by means of the m a k e e m p t y -r e g i o n or d e l e t e -a n d -s a v e -r e g i o n function. It can be used with any of
the normal text manipulation functions; for instance, i n s e r t -c h a r a c t e r would
work if given a mark that points into a disembodied region. Such a region cannot,
however, be displayed. Disembodied regions are often used as storage areas for
deleted text such as traditional cut-and-paste regions.
Highlight Regions

A highlight region is a special type of region that can be defined only for text in
a buffer. A highlight region can be used just as any other region in the Editor
is, and all the region manipulation functions operate on them. In addition, when
any of the text defined by the highlight region is visible in a window, that text
is displayed with any special display attributes specified when the region was
created.
The possible highlight attributes are any combination of reverse video, bold,
blinking, or underline. Highlight regions can overlap, but the resulting display
attribute for the overlapped section is not predictable. If either the beginning or
ending mark of a highlight region is moved, the display of the region tracks the
motion of the mark.
Special functions are available to you for creating and removing highlight regions.
Once created, the highlighting remains in effect until the region is removed by
means of r e m o v e -h i g h l i g h t -r e g i o n or deleted by means of either d e l e t e -r e g i o n
or d e l e t e -a n d -s a v e -r e g i o n . Removing a highlight region does not alter the text
of the region, but only the display attributes of the text.

Rings
A ring is a specialized data structure that implements a circular cache of data
values. Items of data can be retrieved either from the start of the ring (Last
In/First Out) or from the end of the ring (First In/First Out). In addition, since
the ring is circular, it can be rotated so as to move its start/end position.
Rings have general utility in editors—for example, to store a record of deleted
text. A set of utility routines is included to let you create and manipulate
ring structures. Rings and ring functions can also be used outside the Editor
environment.

Concepts-20

Concepts in Editor Programming

Streams
VAX LISP I/O can be directed into and out of Editor regions by the creation of
streams to these objects.
Establishing an Editor input stream allows text to be read from a region with
standard LISP read operations. All normal LISP input functions can be used.
The usual Common LISP end-of-file action is taken whenever an attempt to read
past the end of the region occurs.
An Editor output stream allows normal VAX LISP write operations to put text
into a region at a particular mark. All normal LISP output functions can be used.
You can create a new line in the region by using the t e r p r i function or by writing
a n e w l i n e character. Writing a r e t u r n — l i n e f e e d pair does not automatically
break a line. These characters are inserted as ordinary nonprinting characters.
There are two additional functions that direct file operations into and out of
Editor regions. The i n s e r t -f i l e -a t -m a r k function inserts the contents of a
file at the designated mark. The w r i t e -f i l e -f r o m -r e g i o n function writes the
contents of an Editor region to a file.

String Tables
String tables are specialized hash tables used to store information indexed by a
string. String tables are of general utility (they can be used outside the Editor
environment) and are used for such actions as completing partial user input (of
a command name, for example). There are functions that access these tables to
retrieve data based on a specified string. The mapping of Editor names to LISP
objects is accomplished through use of these tables.
The following special variables are bound to tables holding information on named
Editor objects:
•

*EDITOR-ATTRIBUTE-NAMES*

•

*EDITOR-BUFFER-NAMES*

•

*EDITOR-COMMAND-NAMES*

•

*EDITOR-STYLE-NAMES*

•

*EDITOR-VARIABLE-NAMES*

In addition to accessing information by means of the entire string, you can use
functions to do a search based on a partial string (for example, the first four
letters of a buffer name). These functions help in writing commands that attempt
to complete a partial string that is specified.
For example, you might want to execute a named command. The Editor can
accept a partial command name and, by means of the string table *e d i t o r c o m m a n d -n a m e s *, complete the partial name; or the function might complete the
string only to the point at which it becomes ambiguous.

Concepts-21

Concepts in Editor Programming
Example

If you are prompted for a command and enter Del, you can type a Ctrl/Space. There
are two commands that begin with Del— "Delete Buffer" and "Delete Window".
The Editor therefore completes the string as far as Delete. You then have to
enter at least B or w (indicating an unambiguous command) before typing Ctrl/Space
again.
You are not limited to this set of string tables. The facility is general and there
are functions for creating new string tables. Strings are case-sensitive when
stored or returned, but case-insensitive during string matching.

Styles
A style is a collection of bindings of Editor keys, pointer actions, variables, and
attributes, coupled with functions executed when a style is either activated or
deactivated.
When a style is active in a buffer, it alters the current behavior of the Editor.
An example of a style is one that causes the Editor to recognize the structure
and syntax rules of LISP code. This behavior is appropriate only when you are
editing LISP source code. Properly editing code written in FORTRAN or PL/I
would require different Editor styles to be active.
Any number of styles can be active at one time when you are editing in a particu
lar buffer. The styles can interact with one another to some extent, but one style
can also shadow (hide) the behavior of another.
For example, you might be using the style called "VAX l i s p " for editing LISP
code, but you would like to specify your own command for indenting LISP text.
The new indent command can be bound in another style called "l i s p indent" and
"l i s p indent" can be made active in the current buffer. The binding of the indent
command in "l i s p indent" shadows the binding of the indent command in "v a x
l i s p ", but all other commands defined by "VAX l i s p " are visible. Deactivating
"l i s p indent" would “
unshadow”the original indent command binding and make
it visible again.
General Style Writing

The writer of an Editor style must take steps to ensure that any needed Editor
support is present. For example, if the new style needs Editor variables bound in
the style or in any buffers that use the style, the style must bind them directly
or through use of a b u f f e r -c r e a t i o n -h o o k function defined in that style. Editor
variables defined with the VAX LISP Editor can be bound freely where needed.
A variable should be bound in a style whenever the style writer wants to retain
information that can be used in any buffer having that style active. For example,
the variable "EDT Paste Buffer" is bound in "EDT Emulation style". With this
binding, any text that is cut from one buffer using "e d t Emulation" style can be
pasted into any other buffer that also has "e d t Emulation" style.
Command bindings defined for a style should be considered recommendations.
The user may change the bindings local to that style. This means, for example,
that help functions associated with a style should not assume that a particular
key sequence is bound to a particular command.

Concepts-22

Concepts in Editor Programming
Major/Minor Style Distinction

Any Editor Style can be bound as a major or minor style on a per-buffer basis.
The decision is made normally on the basis of the extent of behavior changes
introduced by the style. You make this decision when you bind the style to a
buffer. A buffer can have only one major style active at a time, but any number
of minor styles active at the same time.
The set of global bindings of commands is extremely limited in the VAX LISP
Editor. This fact implies that any generally useful editing session must have a
powerful major style bound for each buffer. As supplied in the VAX LISP Editor,
the default major style is "e d t Emulation", which supplies a set of commands and
bindings that make the Editor behave as EDT does. You may want to replace this
default style with "e m a c s " or with one of your own that would make the Editor
behave in a different manner.
Minor styles are intended to be variations of the major style (or other minor
styles) that tailor the Editor behavior to more specific needs. For example, the
Editor comes with a "VAX l i s p " style, which modifies the Editor so that it has
more knowledge of the syntax of LISP. When this style is active, typing the close
parenthesis key not only inserts the character but also locates and displays the
corresponding open parenthesis character. Most of the editing capabilities are
still vested in the major style of the buffer.
Activation of Styles

There are two methods by which styles can be activated automatically when a
new buffer is created. One method works for all created buffers; the other method
can be tailored for specific attributes of buffers.
The first method involves the Editor variables "Default Major style" and
"Default Minor styles". When a buffer is created, its major style is set to the
current value of "Default Major style". As supplied, the value of this variable
is "EDT Emulation". If you change this value, it changes the major style of the
"Help" and "General Prompting" buffers to the new style. The minor styles
of the new buffer are set from the list of styles contained in "Default Minor
styles". The global value of this variable is initially n i l .

The second method allows you to activate minor styles in a new buffer either
according to the file type of the associated file or whenever a LISP object is being
edited in the buffer.
The Editor variable "Default File Type Minor styles" contains an association
list (a-list). Each key in the a-list is a string that is compared with the file type
of the new buffer’
s associated file. Each element contains a list of minor styles to
activate in any buffer with a file type matching the key. As supplied, this variable
is bound in the global context and has a single element of the form:
("LSP" . ("VAX LISP"))

This means that "VAX l i s p " style is activated in any buffer containing a file that
has a file type of .LSP.
A second Editor variable, "Default l i s p object Minor styles", contains a list of
minor styles to be activated in any buffer having an object being edited directly
from LISP. As supplied, this variable is bound in the global context and contains
the list:

Concepts-23

Concepts in Editor Programming
("VAX LISP")

This means that "VAX l i s p " style is activated automatically in any buffer used to
edit a LISP function.
Order of Activation: When a buffer is created, first the major style is activated
from the current value of "Default Major style" (unless the major style is
otherwise specified). Note that only the global value of this variable is used. The
minor styles are then activated from the list found in "Default Minor styles".
The order of activation is in reverse order of the list. When the operation is
complete, the order of search of the minor styles is the same as that of the list.

If the buffer contains a LISP object, the minor styles in the "Default l i s p object
Minor styles" list are next activated in reverse order. Any styles present in this
list will be searched before any of the styles found in the "Default Minor styles"

list.

If the buffer has an associated file, the association list contained in "Default
File Type Minor styles" is searched for an entry whose key matches the file type
of the associated file. The styles contained in the entry are activated in reverse
order so that the expected search order is maintained. Any styles present in this
list will be searched before any of the styles found in the "Default Minor styles"
list.
Activation and Deactivation Functions: Activation and deactivation functions
are associated with each style. WHhen a style is made active, its activation func
tion is executed; when a style is made inactive, its deactivation function is exe
cuted. You make a style active by using the SETF macro with b u f f e r -m a j o r -s t y l e
or b u f f e r -m i n o r -s t y l e -a c t i v e .

If the "e d t Emulation" major style is defined, and it is activated as the major
style in a given buffer by means of
(setf (buffer-major-style "Typeset.lsp") "EDT Emulation")

the deactivation function of the old major style and the activation function of the
new major style are executed. This process occurs unless the new and old styles
are the same. Setting the major style to n i l causes the old major style to become
inactive.
If "VAX LISP" style is made active as a minor style in a given buffer by means of
(setf (buffer-minor-style-active 'factorial "VAX LISP") t)

its activation function is executed, and the new style is pushed onto the front of
the list of active minor styles.
If an active minor style is again activated, and it is not the most recently acti
vated minor style, the following actions occur:
• The deactivation function associated with the style is executed.
• The original entry for the style is deleted from the list of active minor styles.
• The activation function associated with the style is executed.
• The style is pushed onto the front of the list of active minor styles.
If a style that is active in any Editor buffer is modified (for example, if a new
variable is bound in that style), the modifications take effect in those buffers
immediately.
Concepts-24

Concepts in Editor Programming

Windows
A window is both an Editor object and the display mechanism of the Editor. Each
window is a rectangular “
opening”into a portion of an Editor buffer. This opening
can be displayed on the screen of your display device, thereby showing you the
current state of text within viewing range. As windows are Editor objects, they
can be manipulated by various Editor functions.
Windows need not be the full height or width of the screen. Multiple windows can
be on the screen at the same time. Moreover, windows can fully or partially over
lap one another. The dimensions of a window are dynamic and can be changed
either automatically by the Editor or under program control by a function you
write.
Only text that lies within a buffer region can be displayed. A buffer can have
multiple independent windows pointing into it. Since the text contained within a
buffer can be both longer than a window (more lines) and wider (more characters
per line), some provisions have been made to handle both circumstances.
Windows that are shorter than a buffer can be “
moved”forward and backward
through the buffer. This is known as s c r o l l i n g . In the VAX LISP Editor, it
is the window that scrolls in the direction you specify and not the text. For
example, when you scroll the window down (or forward) through the buffer, the
text appears to move up to accommodate the new window display; actually, the
window is moving down in the buffer. Windows can also be positioned absolutely
in a buffer (at the beginning or end of a buffer, or at a particular line).
A window that is narrower than the text of the buffer is treated differently.
The displayed text lines are either truncated on the right wherever the window
ends (that is, only as many characters as will fit in the width of a window are
displayed); or the lines “
wrap around”(that is, the entire line of text is displayed
even if it overflows onto one or more additional rows). Truncation and wrapping
are indicated by special characters at the end of an affected line. The default is
an underlined > for truncation, and an underlined < for wrapping, but you can
specify different characters for any window.
The physical location of a window on the screen can be moved w ithout affecting

the portion of the buffer that the window is displaying; that is, you affect only
where the text is displayed, not what is being displayed. A window can also
exist as an Editor object but not be displayed currently. The Editor provides
mechanisms for placing windows in and removing windows from the display
automatically. You can also do this under the control of your program.
A window has an optional label—a line of text that accompanies the window and
is displayed with it. The line can be displayed at the top, bottom, or either side
of a window. By default, the label is placed at the bottom of the window and can
be of any length up to the length of whatever edge of the window the label is
displayed on. It can contain any text you want—for example, a buffer name or
file name.
The label can be highlighted to give a visual separation from the buffer text being
displayed. By default, this is done with reverse video on terminals that support
this feature (VTlOO-compatible). The highlighting can be changed under program
control. By default, the label is centered on whatever edge of the window is
used for this display. You can control the label’
s position on a line, however, by
specifying a starting position for the label—an offset value that is the number of
Concepts—25

Concepts in Editor Programming
characters from the start of the window side (from the top of the window, if the
label is on the right or left; or from the left-hand side, if the label is on the top or
bottom).

Editor windows are of two types—floating and anchored. Display of text in a
window is unaffected by the type of the window. The distinction between the two
lies in how they are treated by the display subsystem.
The simplest distinction is that floating windows are always displayed “
on top”of
(overlaying) any anchored windows, possibly obscuring them.
NOTE

With such overlaying, it is possible that the cursor that appears to be
in the floating window is, in fact, indicating a position in the overlaid
anchored window.
An anchored window cannot obscure a floating window. Another difference
between anchored and floating windows is that anchored windows are subject to
automatic resizing and repositioning by the display subsystem. Floating windows
are treated independently of other windows.
The two types of windows are identified with the keywords : f l o a t i n g and
:a n c h o r e d . By default, created windows are anchored if they are the full width
of the screen and are displayed starting in column 1 (the left-hand side of the
screen). Otherwise, they are floating. You can specify a type for any window you
create, and you can also change the type of an existing window.
The display subsystem allows you to gain full control over the treatment of
windows on the display—which are displayed, where they are, and what they
overlap. You can allow the display subsystem to exercise automatic control over
the display of anchored windows. Floating windows are always assumed to be
under program control.
The automatic treatment of anchored windows follows the rules given below:
• Text in one anchored window is never obscured by text in another anchored
window.

• The bottom border of an anchored window is never obscured by another
anchored window, but the top and side borders can be obscured.
• Anchored windows are adjusted automatically in height when other anchored
windows are added to, or removed from, the display. The adjustment ensures
that the text areas of anchored windows do not overlap one another, and the
total height of all the anchored windows on the screen is the full height of the
screen minus the height of the information area and the prompting window.
• Any of the functions that manipulate windows on the screen assume that,
unless explicit directions are given for the treatment of anchored windows
(such as specifying height or relative position), all the currently displayed
anchored windows are subject to automatic manipulation.
A record is also kept of the time a window is created. You can retrieve this
information with the w i n d o w -c r e a t i o n -t i m e function. It returns a value in
universal time.

Concepts-26

Partlll
Editor Object Descriptions

This part describes each of the objects provided with the VAX LISP Editor. The
objects are listed by name in alphabetical order.
The Editor objects listed include the following types:
• Functions
• Macros
• LISP global variables
• Named Editor objects
— Buffers
— Commands
— Editor attributes
— Editor variables
— Styles
The other objects provided with the Editor—lines, marks, regions, string tables,
streams, and windows—are unnamed objects. The instances of unnamed objects
are not described here, except for those that are bound to LISP variables. For
instance, the string table bound to *e d i t o r -c o m m a n d -n a m e s * and the stream
bound to *i n f o r m a t i o n -a r e a -o u t p u t -s t r e a m * are described here.
Conventions Used in This Part

Several conventions are used in the individual object descriptions in this part.
These conventions pertain to:
• Named Editor Objects
• Functions Associated with Commands
• Functions That Take Named Editor Objects
These conventions are described separately here.
Named Editor Objects

Named Editor objects can have both a symbol and a display name, which is a
string. For instance:
• e d t -e m u l a t i o n and "e d t Emulation" both refer to the same style object.
•

EDITOR-PROMPTING-BUFFER and "General Prompting" both refer to the Same

buffer object.

The description of each named Editor object identifies both its symbol and its
display name. The descriptions are alphabetized according to the objects’display
names.
Functions Associated with Commands

The functions associated with commands are listed according to the display
names of the commands. For instance, the function i n d e n t -l i s p -r e g i o n -c o m m a n d
is described along with the command "indent l i s p Region". The symbol of the
function and the symbol name of the command are identical.

Objects-29

The command descriptions give the full format of the associated functions, in
cluding all optional arguments. Whether you can supply values for optional
arguments depends on whether you are executing a command in the Editor or
calling its associated function from LISP code:
• When executing a command within the Editor, you can supply a value only
for the prefix parameter (by previously executing a command such as "Supply
Prefix Argument" or "Supply e m a c s Prefix"). If the Editor needs additional
values to execute the command, it will either use default values or prompt for
a needed value.
• When calling a command-associated function from LISP code, you can supply
a value for any parameter.
Functions That Take Named Editor Objects

Functions that take named Editor objects as arguments are of two kinds: those
that can take an object specifier and those that can take only the object itself.
The function descriptions in this part distinguish between the two kinds of
function by identifying the argument as either object-type or object-type specifier.
For instance,
• The buffer argument to the function buffer-writable is identified as “
An
Editor buffer.”
• The buffer argument to the function b u f f e r -m a j o r -s t y l e is identified as “
An
Editor buffer specifier.”
Object specifiers include the display names and the symbols of named Editor
objects. Functions that take objects (not object specifiers) cannot take a display
name or symbol specifier. Recall that the symbol of a named Editor object does
not evaluate to the object (see Section 1.3.3).
The difference in how you call functions that take only objects and functions that
take specifiers is illustrated by buffer-writable and buffer-major-style:
• buffer-writable takes an Editor buffer. The argument can be specified only
by a form that evaluates to a buffer object. For instance:
(buffer-writable (current-buffer))

or
(buffer-writable (find-buffer 'editor-help-buffer))

or
(buffer-writable *editor-default-buffer*)

• buffer-major-style takes an Editor buffer specifier. The argument can be
specified by any of the following:
• A buffer display name
(buffer-major-style "Mybuffer.lsp")

• A buffer symbol
(buffer-major-style 'editor-help-buffer)

Editor Object Descriptions
• A form that evaluates to a buffer object, such as
(buffer-major-style (current-buffer))

or
(buffer-major-style (find-buffer 'editor-help-buffer))

or
(buffer-major-style *editor-default-buffer*)

ACTIVATE MINOR STYLE Command
Prompts the user for the name of a style and then activates that style as a minor
style in the current buffer. Alternatives and completion are available during the
prompt.

Category
:GENERAL-PROMPTING
Display Name Format
Activate Minor Style
Function Format
ACTIVATE-MINOR-STYLE-COMMAND prefix
Arguments
prefix

Ignored

Return Value
The new minor style

Objects-31

Editor Object Descriptions

ALTER-WINDOW-HEIGHT Function
Increases (for a positive delta-value argument) or decreases (for a negative deltavalue argument) the height of the specified window by the specified number of
rows.
If the window is currently displayed and is of the anchored type, the heights
of other displayed anchored windows are adjusted accordingly. The new height
of the window cannot be less than 1. If the new height is too large to fit on
the screen with the other displayed anchored windows, the height is set to
the maximum height permissible. Calling this function causes the "Window
Modification Hook" to be invoked.

Format
ALTER-WINDOW-HEIGHT w indow delta-value
Arguments
window
An Editor window. It need not be displayed currently.
delta-value
An integer

Return Value
The new height of the window

ANCHORED WINDOW SHOW LIMIT Editor Variable
Specifies the maximum number of Editor windows that can be displayed simulta
neously by repeated calls to the function s h o w -w i n d o w .If the number of anchored
windows already displayed is greater than or equal to the value of this variable,
then s h o w -w i n d o w will remove the least recently used window when it displays
another window. The default global value is 2.
The action of p u s h -w i n d o w is not affected by this variable.

Display Name Format
Anchored Window Show Limit

Objects-32

Editor Object Descriptions

Symbol Format
ANCHORED-WINDOW-SHOW-LIMIT

APROPOS Command
Displays a list of objects of the specified type in the "Help" buffer. Only objects
whose name contains the specified string are listed. If the object type or string
is nil, the user is prompted for it in the Editor prompting window. An object
type of t signifies that all Editor objects containing the specified string are to be
displayed.

Category
:GENERAL-PROMPTING
Display Name Format
Apropos
Function Format
APROPOS-COMMAND p re fix &OPTIONAL type string
Arguments
prefix
Ignored

type
Three possibilities:

• A named Editor object type (a t t r i b u t e ,b u f f e r , c o m m a n d , v a r i a b l e , or s t y l e )
•

s y m b o l to search all LISP objects

•

t to search all named Editor objects

string
The string to be matched in the object names

Return Value
None

Objects-33

Editor Object Descriptions

APROPOS-STRING-TABLE Function
Searches the specified string table for all entries whose key contains the specified
string as a substring. It returns a list of all such keys in alphabetical order. If
the string is of zero length, all the keys in the string table are returned.

Format
APROPOS-STRING-TABLE string string-table
Arguments
string
A string to be used as a search string
string-table
A string table to be searched

Return Value
An alphabetical list of keys

APROPOS WORD Command
Does an a p r o p o s of the word at the mark and displays the result in the "Help"
buffer. If the mark is not supplied, it defaults to the current buffer point.

Display Name Format
Apropos Word
Function Format
APROPOS-WORD-COMMAND prefix &OPTIONAL m ark
Arguments
prefix

Ignored
mark
An Editor mark that defaults to the current buffer point

Objects-34

Editor Object Descriptions

Return Value
Undefined

ATTENTION Function
Gains the attention of the user.

Format
ATTENTION
Arguments
None

Return Value
NIL

ATTRIBUTE-NAME Function
Takes an attribute specifier as an argument and returns the display name of the
attribute.

Format
ATTRIBUTE-NAME attribute

Arguments
attribute
An attribute specifier

Return Value
A string that is the display name of the attribute

Objects-35

Editor Object Descriptions

BACKWARD CHARACTER Command
Moves the point in the current window back one character if the prefix argument
is n i l . If you specify an integer prefix argument, the point is moved backward (or
forward, if the prefix is negative) by the number of characters you indicated. An
error is signaled if the point is at the beginning of a buffer.

Display Name Format
Backward Character
Function Format
BACKWARD-CHARACTER-COMMAND prefix
Arguments
prefix
A fixnum specifying how many characters to move

Return Value
The updated buffer point mark

BACKWARD KILL RING Command
Rotates the kill ring backward by the number of elements specified by the prefix.

Category
:KILL-RING
Display Name Format
Backward Kill Ring
Function Format
BACKWARD-KILL-RING-COMMAND prefix

Objects-36

Editor Object Descriptions

Arguments
prefix
An integer or n i l

Return Value
Undefined

BACKWARD PAGE Command
Moves the point in the current buffer backward one page if prefix is n i l . If you
specify an integer prefix argument, the point is moved backward (or forward, if
prefix is negative) by the number of pages you indicated. A page delimiter is a
character that has a "Page Delimiter" attribute value of l.

Display Name Format
Backward Page
Function Format
BACKWARD-PAGE-COMMAND prefix
Arguments
prefix
A fixnum specifying how many pages to move

Return Value
The updated buffer point mark

BACKWARD SEARCH Command
Prompts for an argument string if the user does not supply one. The string is
used as the pattern for a backward search. If the search is successful, the buffer
point is moved to the beginning of the first matching string. If the user does
not specify a string when prompted, the command takes the value of the Editor
variable "Last Search string". If the user specifies a prefix argument, n, this
command looks for the nth occurrence of the pattern.

Objects-37

Editor Object Descriptions

Display Name Format
Backward Search
Function Format
BACKWARD-SEARCH-COMMAND prefix &OPTIONAL String
Arguments
prefix
The fixnum repeat count
string
The string to search for. If you do not specify a string when prompted, string
defaults to the value of the Editor variable "Last Search string".

Return Value
The modified point

BACKWARD WORD Command
Moves the point back to the end of the preceding word. If you specify an integer
prefix argument, the point is moved back the number of words you indicate.
Words are delimited by characters having a "Word Delimiter" attribute value of
l.

Display Name Format
Backward Word
Function Format
BACKWARD-WORD-COMMAND prefix
Arguments
prefix
A positive integer or NIL

Objects-38

Editor Object Descriptions

Return Value
The modified point

BACKWARD-WORD-COMMAND Function
Moves the point backward to indicate the last character of the preceding word
(or the nth preceding word if a prefix n was supplied). This function takes an
optional mark argument that defaults to the current buffer point. It moves the
mark backward to indicate the word delimiter character that precedes the present
word (or the preceding word, if the mark is initially indicating a word delimiter).
If a prefix n is supplied, this function moves the mark backward to indicate the
word delimiter preceding the nth word.

Format
BACKWARD-WORD-COMMAND prefix &OPTIONAL m ark
Arguments
prefix
An integer or n i l
mark
An Editor mark that defaults to the current buffer point

Return Value
The modified mark

BEGINNING OF BUFFER Command
Moves the point to the beginning of the current buffer.

Display Name Format
Beginning of Buffer
Function Format
BEGINNING-OF-BUFFER-COMMAND p refix

Objects-39

Editor Object Descriptions

Arguments
prefix
Ignored

Return Value
The modified point

BEGINNING OF LINE Command
Moves the point to the beginning of the current line. If you specify an integer
prefix argument, the point is moved down the number of lines you indicated (or
up, if the prefix is negative) and then to the beginning of the new line.

Display Name Format
Beginning of Line
Function Format
BEGINNING-OF-LINE-COMMAND prefix
Arguments
prefix
An integer or n i l

Return Value
The updated buffer point mark

BEGINNING OF OUTERMOST FORM Command
Moves the buffer point from inside a LISP form to the beginning of the outermost
form surrounding it. If the point is in between two outer forms, it is moved to
the beginning of the preceding one. If there is no preceding outer form, an Editor
error is signaled. An outermost form is one whose opening parenthesis is in the
leftmost column on the screen.

Display Name Format
Beginning of Outermost Form

Objects-40

Editor Object Descriptions

Function Format
BEGINNING-OF-OUTERMOST-FORM-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
The updated buffer point

BEGINNING OF PARAGRAPH Command
Moves the specified mark to the beginning of the paragraph. The mark defaults
to the current buffer point.

Display Name Format
Beginning of Paragraph
Function Format
BEGINNING-OF-PARAGRAPH-COMMAND p re fix &OPTIONAL m ark
Arguments
prefix
Ignored
mark
An Editor mark that defaults to the current buffer point

Return Value
The updated mark

Objects-41

Editor Object Descriptions

BEGINNING OF WINDOW Command
Moves the cursor to the beginning of the current window.

Display Name Format
Beginning of Window
Function Format
BEGINNING-OF-WINDOW-COMMAND prefix &OPTIONAL m ark window
Arguments
prefix

Ignored
mark
The mark to be placed at the beginning of the window. It defaults to the current
buffer point.
window
The window in which the mark is to be moved. It defaults to the current window.

Return Value
The current buffer point

BIND-ATTRIBUTE Function
Takes a defined Editor attribute as an argument and creates a binding of that
attribute in the specified context with the specified type and value.

Format
BIND-ATTRIBUTE a ttrib u te d KEY :TYPE :CONTEXT :INITIAL-VALUE
Arguments
attribute
An Editor attribute specifier
:TYPE

A LISP type specifier. The default is (mod 2).

Objects-42

Editor Object Descriptions
:CONTEXT
An Editor context specifier. The default is :g l o b a l .
:INITIAL-VALUE
The attribute value that all characters will initially have for this attribute in this
context. It must be of the type specified by i TYPE. The default is o.

Return Value
The attribute symbol

BIND COMMAND Command
Prompts the user for a command name, a key sequence, and a binding context.
This command is useful for binding commands to keys without leaving the context
of the Editor. Completion and alternatives are available for the command name
and for the style or buffer name depending on the desired binding context. The
key sequence must be entered literally as the sequence of characters to bind. This
frequently requires the quoting of control characters.

Category
:GENERAL-PROMPTING
Display Name Format
Bind Command
Function Format
BIND-COMMAND-COMMAND prefix
Arguments
prefix

Ignored

Return Value
The function associated with the command

Objects-43

Editor Object Descriptions

BIND-COMMAND Function
Binds the specified key-sequence to the specified command in the specified con
text.

Format
BIND-COMMAND com m and key-sequence &OPTIONAL context
Arguments
com m and
An Editor command specifier command
key-sequence
A character or a sequence of characters. The key sequence cannot contain the
characters Ctrl/S or Ctrl/Q. It should not contain the current cancel character Ctrl/C
(by default).
context
The context in which to bind the command. The argument context defaults to
: GLOBAL.

Return Value
The function associated with the command

BIND-POINTER-COMMAND Function
Binds the specified action of the pointing device to the specified command in
the specified context. The possible actions of the pointing device are a button
transition (depressing or releasing) or a movement of the pointer cursor. The
Editor invokes the bound command in response to a pointer action only when the
pointer cursor is in the current window.
The :b u t t o n - s t a t e parameter is used to indicate that one or more pointer
buttons must be in a down state for the specified pointer-action to invoke the
command. If the pointer-action argument is a button transition, then any value
in the :b u t t o n - s t a t e argument that corresponds to that button is ignored.

Format
BIND-POINTER-COMMAND com m and pointer-action
&KEY :CONTEXT :BUTTON-STATE

Object s-44

Editor Object Descriptions

Arguments
command
An Editor command specifier
pointer-action
A keyword, a button constant, or a list. The possible values are:
: MOVEMENT

The command is invoked by any movement of the pointer cursor
within the current window. Cursor movement is defined as a
movement across at least one character in any direction.

:BUTTON-1, . . .
,:BUTTON-5

Under DECwindows, the command is invoked by depressing the
pointer button that corresponds to the keyword. The keywords are
specified as : BUTTON -n, starting with keyword : B U TT O N - 1 for the
leftm ost button.

A button constant

Under UIS, the command is invoked by depressing the pointer but
ton that corresponds to the constant. The constants are specified as
U I S : P O IN T E R -B U T T O N -n , starting with U I S : P O IN T E R -B U T T O N - 1
for the left-most button. Note that the symbols for button constants
are located in the " U I S " package; see VAX LISP Interface to VWS
Graphics for more information.

A l i s t w h o s e CAR i s

If t h e CADR is n on - N IL , t h e c o m m a n d i s i n v o k e d w h e n t h e p o i n t e r

a b u tto n co n sta n t

b u t t o n c o r r e s p o n d i n g t o t h e CAR i s d e p r e s s e d .

o r b u tton k ey w ord

If t h e CADR i s N IL , t h e c o m m a n d i s i n v o k e d w h e n t h e p o i n t e r b u t t o n
c o r r e s p o n d i n g t o t h e CAR i s r e l e a s e d .

:CONTEXT value
A context specifier. The default is ■.g l o b a l .
:BUTTON-STATE value
Under UIS, a button constant, or the l o g a n d of two or more button constants.
Under DECwindows, a button keyword or list of button keywords. The button(s)
indicated must be in a down state for the specified pointer-action to invoke the
command.
If a button transition is specified as the pointer-action argument, any value that
corresponds to that button in the :b u t t o n - s t a t e argument is ignored.

Return Value
The function associated with the command

BIND-VARIABLE Function
Binds the specified Editor variable in the specified context. You get a warning
if you attempt to bind a variable in a context in which it is already bound. The
function specified in the :b i n d - h o o k argument of d e f i n e - e d i t o r - v a r i a b l e is
called and passed the symbol and the binding context.

Objects-45

Editor Object Descriptions

Format
BIND-VARIABLE sym bol & KEY :CONTEXT :SET-VALU E-HOOK
:SET-FUNCTION-HOOK :INITIAL-VALUE
rINITIAL-FUNCTION
Arguments
sy m b o l

An Editor variable specifier
:CONTEXT
An Editor context specifier that defaults to : g l o b a l
:SET-VALUE-HOOK
A function invoked whenever the value of the variable is set in the specified
context. The function is called with three arguments—the variable, the context of
the variable, and the new value. It defaults to n i l .
:SET-FUNCTION-HOOK
A function invoked whenever the function slot is changed in the specified context.
The function is called with three arguments—the variable, the context of the
variable, and the new function. It defaults to n i l .
:INITIAL-VALUE
The value given to the binding of the variable created in the specified context. It
defaults to n i l .
:INITIAL-FUNCTION
The function bound to the variable in the specified context. It defaults to n i l .

Return Value
The symbol that names the variable

BREAK-LINE Function
Breaks a line at the position pointed to by the specified mark.

Format
BREAK-LINE m ark

Objects—46

Editor Object Descriptions

Arguments
mark
A mark specifying the position at which a line is to be broken. If the mark is
left-inserting, the mark is moved to the beginning of the new line. If the mark is
right-inserting, the mark remains at the end of the original line.

Return Value
The updated mark

BUFFER-CHECKPOINTED Function
Returns the pathname of the file where checkpoints of the specified buffer will be
written, or n i l if the buffer is not being checkpointed. You can change either the
file to which the buffer is checkpointed or make the buffer not checkpointed by
using this form with s e t f . When changing the value, you can set three possible
values:
•

n il

m a k e s t h e b u ff e r n o t c h e c k p o in te d .

• A pathname writes the buffer to that file.
•

T writes the buffer checkpoints to a file name the Editor creates from the
name of the object being edited.

Format
BUFFER-CHECKPOINTED bu ffer
Arguments
buffer
An Editor buffer

Return Value
A p a th n a m e o r n il

BUFFER-CHECKPOINTED-TIME Function
Returns the universal time that the buffer was last checkpointed; or n i l , if it has
not been checkpointed.

Objects-47

Editor Object Descriptions

Format
BUFFER-CHECKPOINTED-TIME bu ffer
Arguments
buffer

An Editor buffer

Return Value
A v a lu e in u n iv e r s a l tim e o r n il

BUFFER CREATION HOOK Editor Variable
Specifies a hook function that is called whenever a new buffer is created. The
hook function is passed one argument—the new buffer. The function is called
after the complete buffer context is created, and in the context of the new buffer.

Display Name Format
Buffer Creation Hook
Symbol Format
BUFFER-CREATION-HOOK

BUFFER-CREATION-TIME Function
Returns the universal time at which the specified buffer was created. For infor
mation on universal time, see Common LISP: The Language,

Format
BUFFER-CREATION-TIME bu ffer
Arguments
buffer
The buffer for which the time is desired

Objects—48

Editor Object Descriptions

Return Value
The universal time at which the buffer was created

BUFFER DELETION HOOK Editor Variable
Specifies a hook function called just before a buffer is deleted. It is called in the
context of the buffer to be deleted and before any alterations are made to the
buffer. It is passed one argument—the buffer to be deleted.

Display Name Format
Buffer Deletion Hook

Symbol Format
BUFFER-DELETION-HOOK

BUFFER-END Function
Changes the specified mark so that it points to the end of the buffer.

Format
BUFFER-END m ark &OPTIONAL buffer
Arguments
mark
An Editor mark
buffer
An Editor buffer. This defaults to the buffer the mark is pointing into.

Return Value
The modified mark

Objects-49

Editor Object Descriptions

BUFFER ENTRY HOOK Editor Variable
Specifies a hook function invoked whenever a different buffer becomes current.
The function is called with one argument—the new buffer—and is evaluated in
the context of the new buffer.

Display Name Format
Buffer Entry Hook
Symbol Format
BUFFER-ENTRY-HOOK

BUFFER EXIT HOOK Editor Variable
Specifies a hook function invoked whenever a different buffer becomes current.
The function is called with one argument—the old buffer—and is evaluated in the
context of the old buffer.

Display Name Format
Buffer Exit Hook
Symbol Format
BUFFER-EXIT-HOOK

BUFFER-HIGHLIGHT-REGIONS Function
Returns a list of the highlight regions associated with the specified buffer, or n i l
if there are no such regions.

Format
BUFFER-HIGHLIGHT-REGIONS buffer

Object s-50

Editor Object Descriptions

Arguments
buffer
An Editor buffer

Return Value
A lis t o f h ig h lig h t r e g io n s o r n il

BUFFER-MAJOR-STYLE Function
Returns the major style associated with the specified buffer, or n i l if there is
none. You can use s e t f with b u f f e r -m a j o r -s t y l e to change the major style of a
buffer. This action causes the "Major style Activation Hook" to be invoked.

Format
BUFFER-MAJOR-STYLE bu ffer
Arguments
buffer
An Editor buffer specifier

Return Value
The major style of the buffer, or n i l

BUFFER-MINOR-STYLE-ACTIVE Function
Returns T if the specified style is active in the specified buffer. You can use setf
with b u f f e r -m i n o r -s t y l e -a c t i v e to add minor styles to, or delete them from, a
buffer. This action causes the "Minor style Activation Hook" to be invoked.

Format
BUFFER-MINOR-STYLE-ACTIVE b u ffe r style
Arguments
buffer
An Editor buffer specifier

Objects-51

Editor Object Descriptions
style
An Editor style specifier

Return Value
T o r N IL

BUFFER-MINOR-STYLE-LIST Function
Returns a list of the minor styles active in the specified buffer. The order of the
styles is the same as the search order.

Format
BUFFER-MINOR-STYLE-LIST bu ffe r
Arguments
buffer
An Editor buffer specifier

Return Value
A list of the minor styles

BUFFER-MODIFIED-P Function
Is a predicate that returns T if the buffer has been modified and n i l if it has not.
You can use s e t f with b u f f e r - m o d i f i e d - p to change the status of whether or not
the buffer is considered to be modified.

Format
BUFFER-MODIFIED-P bu ffer
Arguments
buffer
An Editor buffer

Objects-52

Editor Object Descriptions

Return Value
T or NIL

BUFFER-NAME Function
Returns the name of the buffer you specify. You can use s e t f with b u f f e r - n a m e
to change the name of the buffer. This action causes the " B u f f e r N am e H o o k " to
be invoked.

Format
BUFFER-NAME bu ffer
Arguments
buffer
An Editor buffer

Return Value
The buffer name

BUFFER NAME HOOK Editor Variable
Is a hook function called with the buffer and the new name as arguments when
the name of a buffer is changed.

Display Name Format
Buffer Name Hook

Symbol Format
BUFFER-NAME-HOOK

Objects-53

Editor Object Descriptions

BUFFER-OBJECT Function
Returns the object being edited in the buffer you specify. This object is a path
name in the case of a file, a symbol in the case of a LISP function or the value of
a symbol, or the form of a generalized variable. You can use s e t f with b u f f e r o b j e c t to change the object being edited in the buffer. This action causes the
" B u f f e r O b j e c t H o o k " to be invoked.

Format
BUFFER-OBJECT buffer
Arguments
buffer
An Editor buffer

Return Value
The object being edited in the buffer

BUFFER OBJECT HOOK Editor Variable
Is a hook function called with the buffer and the new object as arguments when
the object associated with a buffer is changed.

Display Name Format
Buffer Object Hook

Symbol Format
BUFFER-OBJECT-HOOK

BUFFER-PERMANENT Function
Is a predicate that returns t if the specified buffer is permanent (that is, if it
cannot be deleted by the d e l e t e - b u f f e r function). It returns n i l otherwise. You
can change the permanent status of a buffer by using the s e t f macro with this
form.

Objects-54

Editor Object Descriptions

Format
BUFFER-PERMANENT buffer
Arguments
buffer
An Editor buffer

Return Value
T o r N IL

BUFFER-POINT Function
Returns the point of the buffer you specify.

Format
BUFFER-POINT buffer
Arguments
buffer
An Editor buffer

Return Value
A m ark that is the poin t for the buffer

BUFFER-REGION Function
Returns the region of the buffer you specify.

Format
BUFFER-REGION bu ffer
Arguments
buffer
An Editor buffer

Objects-55

Editor Object Descriptions

Return Value
The buffer region

BUFFER RIGHT MARGIN Editor Variable
Can be set to an integer that specifies the last character position at which text
can be inserted in each line by means of the commands "Self insert" and
"Quoted insert". If more text is inserted than will fit on a line of this length,
then the line is automatically broken at the last word break within the right
margin. In the default Editor, this variable is bound globally and set to NIL.
Note that this variable does not affect the operation of other text-inserting
commands, such as "e d t Paste" and "Yank".

Display Name Format
Buffer Right Margin
Symbol Format
BUFFER-RIGHT-MARGIN

BUFFER SELECT MARK Editor Variable
Is used by a number of commands that need to retain a special mark indicating a
p osition in a buffer. It is bou nd to a m ark by com m an ds that select region s o f a

buffer. See also "Buffer Select Region".

Display Name Format
Buffer Select Mark
Symbol Format
BUFFER-SELECT-MARK

Objects-56

Editor Object Descriptions

BUFFER SELECT REGION Editor Variable
Is bound by several commands to a “
selected”region in a buffer. This variable is
created as a local variable to each buffer. See also "Buffer Select Mark".

Display Name Format
Buffer Select Region
Symbol Format
BUFFER-SELECT-REGION

BUFFER-START Function
Changes mark so it points to the beginning of the buffer.

Format
BUFFER-START m ark &OPTIONAL bu ffer
Arguments
mark
buffer
A buffer. If no buffer is specified, the default is the buffer the mark points into.

Return Value
The modified mark

BUFFER-TYPE Function
Returns a keyword indicating the type of object being edited in the specified
buffer. This function returns n i l if there is no LISP object or file associated with
the buffer.

Format
BUFFER-TYPE bu ffer

Objects-57

Editor Object Descriptions

Arguments
buffer
An Editor buffer

Return Value
One of the following keywords or n i l :
:FiLE. The object is a file.

: f u n c t i o n . The object is the function definition of a symbol.
: v a l u e . The object i s

the value of a symbol.

: s e t f - f o r m . The object is a generalized variable acceptable to s e t f .

BUFFER-VARIABLES Function
Returns a list of Editor variables bound in the specified buffer.

Format
BUFFER-VARIABLES bu ffer
Arguments
buffer
An Editor buffer

Return Value
A list of Editor variables (symbols)

BUFFER-WINDOWS Function
Returns a list of the windows that are associated with the specified buffer. This
list can include windows that are not visible.

Format
BUFFER-WINDOWS bu ffer
Arguments
buffer

An Editor buffer

Objects-58

Editor Object Descriptions

Return Value
A list of the windows that open into the buffer

BUFFER-WRITABLE Function
Returns t if modifications to the specified buffer can be written back as a new
version of the file being edited or an update of the LISP object being edited, or
n i l if they cannot. You can use s e t f with b u f f e r -w r i t a b l e to change the status
of whether or not buffer modifications can be written.

Format
BUFFER-WRITABLE b u ffe r
Arguments
buffer
An Editor buffer

Return Value
T o r N IL

BUFFER-WRITTEN-TIME Function
Returns the universal time that the buffer you specify was last “
written”by the
"Write Current Buffer" or "Write Modified Buffers" command, Or NIL if the
buffer has never been written. If the buffer is associated with a file, this function
returns the time when the buffer contents were last written to the file. If the
buffer is associated with a symbol or a setf form, the time is the last time that
the buffer contents were evaluated. (See Common LISP: The Language for a
description of universal time.)

Format
BUFFER-WRITTEN-TIME bu ffer
Arguments
buffer
The buffer for which you want the time

Objects-59

Editor Object Descriptions

Return Value
Universal time that the buffer was last written, or n i l

BUFFERP Function
Is a predicate that returns T if its argument is a buffer.

Format
BUFFERP object
Arguments
object
Anything

Return Value
T o r N IL

CANCEL-CHARACTER Function
Returns the character that, if typed while in the Editor, causes the current action
to be terminated. The initial value is #\ AC. You can change the cancel character
by using this form with s e t f .
NOTE

The cancel character must be an ASCII control character whose
character code is in the range 0 to 31. Also, it cannot be #\ Return,
#\Linefeed, #\ Escape, #\AQ or #\AS.

Format
CANCEL-CHARACTER
Arguments
None

Objects-60

Editor Object Descriptions

Return Value
The current cancel character

CAPITALIZE REGION Command
Capitalizes all the words in the current select region.

Display Name Format
Capitalize Region
Function Format
CAPITALIZE-REGION-COMMAND prefix &OPTIONAL region
Arguments
prefix
Ignored
region

A region that defaults to the value of the "Buffer Select Region" Editor variable

Return Value
The modified region

CAPITALIZE WORD Command
Capitalizes the current word.

Display Name Format
Capitalize Word
Function Format
CAPITALIZE-WORD-COMMAND p refix &OPTIONAL m ark

Objects-61

Editor Object Descriptions

Arguments
prefix

Ignored
mark
An Editor mark that defaults to the current buffer point

Return Value
A region containing the capitalized word

CATEGORY-COMMANDS Function
Returns a list of Editor commands cataloged under the specified category.

Format
CATEGORY-COMMANDS category
Arguments
category
A symbol used as a command category

Return Value
A list of Editor command symbols

CENTER-WINDOW Function
Causes the display in the specified window to be adjusted so the line pointed to
by the specified mark is centered in the display window.

Format
CENTER-WINDOW w indow m ark
Arguments
window
An Editor window

Objects-62

Editor Object Descriptions
mark
An Editor mark that must point into the same buffer the window is associated
with

Return Value
The mark

CHARACTER-ATTRIBUTE Function
Looks up and returns the value the specified attribute has for the character. You
can use s e t f with c h a r a c t e r -a t t r i b u t e to modify the attributes of a character.
Changing the value of a character attribute causes the "character Attribute
Hook" to be invoked.

Format
CHARACTER-ATTRIBUTE attribute character & OPTIONAL context
Arguments
attribute
An Editor attribute
character
The character whose attribute value you want
context
A context specifier. Defaults to the current context, unless the function is used
with s e t f in which case the context defaults to : g l o b a l .

Return Value
The attribute value for the specified character

CHARACTER ATTRIBUTE HOOK Editor Variable
Is a hook function called with the attribute, character, context, and new value as
arguments, just before the value of a character attribute is changed.

Display Name Format
Character Attribute Hook

Objects-63

Editor Object Descriptions

Symbol Format
CHARACTER-ATTRIBUTE-HOOK

CHARACTER-OFFSET Function
Changes the specified mark so that it points n characters after its former position
(or before its former position, if n is negative). If there are not n characters after
the mark position (or before, if n is negative), mark is not modified, and n il is
returned.

Format
CHARACTER-OFFSET m ark n
Arguments
mark
An Editor mark
n
A fixnum

Return Value
The modified mark or NIL

CHECKPOINT-BUFFER Function
Checkpoints the specified buffer to the specified file, which defaults to the check
point file previously specified for the buffer.

Format
CHECKPOINT-BUFFER b u ffe r &OPTIONAL pathnam e
Arguments
buffer
An Editor buffer

pathname
An optional pathname specifier that defaults to the checkpoint pathname specified
earlier for the buffer

Objects-64

Editor Object Descriptions

Return Value
Two values:
1. The true name of the checkpoint file written to, or n i l if no pathname
existed. (For an explanation of the true name of a file, see the explanation of
pathname in Common LISP: The Language.)
2. The number of records written to the file.

CHECKPOINT-FREQUENCY Function
Returns an integer that gives the frequency at which file checkpointing is being
performed. The frequency is measured in keystrokes, but only those that modify
a buffer. If checkpointing has been disabled, the function returns n i l . The default
frequency is 350. You can use s e t f with c h e c k p o i n t - f r e q u e n c y to change the
default value. Ib disable checkpointing, specify a value of n i l .

Format
CHECKPOINT-FREQUENCY
Arguments
None

Return Value
The checkpointing frequency or n i l

CLEAR-INFORMATION-AREA Function
Clears the text in the Editor information area.

Format
CLEAR-INFORMATION-AREA
Arguments
None

Objects-65

Editor Object Descriptions

Return Value
None

CLOSE OUTERMOST FORM Command
Inserts at the mark the number of list-terminator characters needed to close
the outermost LISP form. The mark defaults to the current buffer point. If the
outermost form is already closed or if no outermost form is found, a message is
displayed and no action occurs. (See "l i s p syntax" attribute, especially the value
:LIST-TERMINATOR.)

Display Name Format
Close Outermost Form
Function Format
CLOSE-OUTERMOST-FORM-COMMAND p re fix &OPTIONAL m ark
Arguments
prefix

Ignored
mark
An Editor mark that defaults to the current buffer point

Return Value
Undefined

COMMAND-CATEGORIES Function
Returns a list of the categories for the specified Editor command or n i l if there
are no categories for this command. See Section 2.3.3 on categories.

Format
COMMAND-CATEGORIES com m and

Objects-66

Editor Object Descriptions

Arguments
com m and
An Editor command specifier

Return Value
A lis t o f c a te g o r ie s o r n il

COMMAND-NAME Function
Takes an Editor command specifier and returns the display name of the com
mand.

Format
COMMAND-NAME com m and
Arguments
com m and
An Editor command specifier (display name or symbol)

Return Value
The display name of the command

COMPLETE-STRING Function
Searches through all strings in the specified Editor string table for those having
the string argument as an initial substring. The searching is case insensitive.

Format
COMPLETE-STRING string table
Arguments
string
The character string to be searched for
table
An Editor string table

Objects-67

Editor Object Descriptions

Return Value
Four values:
1. A string that is the maximum beginning portion common to all the strings
found that match the string argument.
2. The value of a corresponding entry if a unique match was found; n il other

wise.

T, if the second returned value is valid, or n i l , if the second returned value is
not valid. (This allows n i l to be a valid value for a string table entry.)

T, if there are additional entries that start with the specified string. This is
helpful to distinguish the case where a string is the key for a specific entry,
and there are additional keys that begin with this string. For example, " E d "
and " E d i t F i l e " are both valid commands.

COPY FROM POINTER Command
Establishes the end of a DECwindows secondary selection and copies the text
to the window that has input focus. You should make sure that input focus is
correctly set before initiating c o p y f r o m p o i n t e r .

Display Name Format
Copy from Pointer
Function Format
COPY-FROM-POINTER p re fix
Arguments
prefix

Ignored

Return Value
Undefined

Objects-68

Editor Object Descriptions

COPY-MARK Function
Returns a new mark pointing to the same position as the specified mark.

Format
COPY-MARK m a rk &OPTIONAL m ark-type
Arguments
mark

An Editor mark
mark-type

Either : l e f t - i n s e r t i n g , :r i g h t -i n s e r t i n g , or : t e m p o r a r y . The default is the
type of the mark specified.

Return Value
A new Editor mark

COPY-REGION Function
Takes an Editor region as an argument and returns a new disembodied region
that contains a copy of the text of the region you specified. The new region does
not share any lines with the original region.

Format
COPY-REGION region
Arguments
region

An Editor region

Return Value
A new Editor region

Objects-69

Editor Object Descriptions

COPY TO POINTER Command
Moves the current buffer point to the position indicated by the pointer and then
inserts at that location the text from the DECwindows primary selection. If the
pointer is beyond the end of a line, the region is inserted at the end of that line.
If the pointer is beyond the end of the buffer region, the text is inserted at the
end of the buffer region.

Display Name Format
Copy to Pointer
Function Format
COPY-TO-POINTER prefix
Arguments
prefix

Ignored

Return Value
The current buffer point

COUNT-REGION Function
Returns both the number of characters that are in the specified region and the
number of lines that are in the region. A break between lines counts as a single
character. The line count is always at least 1.

Format
COUNT-REGION region
Arguments
region

An Editor region

Objects-70

Editor Object Descriptions

Return Value
Two values:
1. The number of characters in the region
2. The number of lines in the region

CURRENT-BUFFER Function
Returns the currently active Editor buffer. You can use s e t f with c u r r e n t b u f f e r to change the buffer that is considered current. Changing the value of
CURRENT-BUFFER causes the "Buffer Exit Hook" and the "Buffer Entry Hook" to
be invoked.

Format
CURRENT-BUFFER
Arguments
None

Return Value
The current Editor buffer

CURRENT-BUFFER-POINT Function
Returns the mark that is the point for the current buffer. Calling this function is
substantially faster than using the form (buffer-point (current-buffer)).

Format
CURRENT-BUFFER-POINT
Arguments
None

Return Value
The buffer point of the current buffer

Objects-71

Editor Object Descriptions

*CURRENT-COMMAND-FUNCTION* Variable
Is bound to the Editor command function currently being executed. The binding
is established just before the function is called. Is bound to the function e d in
recursive calls to e d .The binding is established just before the function is called.

CURRENT-WINDOW Function
Returns the currently active Editor window. You can use s e t f with c u r r e n t w i n d o w to change the window considered current. Changing the value of c u r r e n t w i n d o w causes the "Switch window Hook" to be invoked. This change also may
cause the value of (current-buffer) to be changed; if SO, the "Buffer Exit Hook"
and the "Buffer Entry Hook" also are invoked.

Format
CURRENT-WINDOW
Arguments
None

Return Value
The current Editor window

DEACTIVATE MINOR STYLE Command
Prompts the user for the name of a minor style active in the current buffer. It
then deactivates that style in the current buffer. Alternatives and completion are
available during the prompt. An Editor error is signaled if the style is not active.

Category
:GENERAL-PROMPTING
Display Name Format
Deactivate Minor Style

Objects—72

Editor Object Descriptions

Function Format
DEACTIVATE-MINOR-STYLE-COMMAND prefix
Arguments
prefix

Ignored

Return Value
The style that was deactivated

DEFAULT BUFFER VARIABLES Editor Variable
Is bound to a list of Editor variables that are to have local bindings in newly
created buffers. Each element of the list is of the form:
v a r ia b le - n a m e \ ( v a r ia b le - n a m e initial-value initial-function)

Each of the Editor variables listed is bound in the context of the new buffer.
The initial value and function of this variable are n i l unless specified in a list
element.

Display Name Format
Default Buffer Variables
Symbol Format
DEFAULT-BUFFER-VARIABLES

DEFAULT FILETYPE MINOR STYLES Editor Variable
Specifies an association list that maps file types to Editor styles. When a file is
associated with a buffer (for example, in the "Edit File" command), the file type
is looked up in this association list. If an entry is found, it must specify a style or
list of styles to be activated as minor styles in the buffer. The default is the list
(("l s p " . "VAX l i s p ") ). This means that a file type of .LSP activates the "VAX
l i s p " minor style.

Objects-73

Editor Object Descriptions

Display Name Format
Default Filetype Minor Styles

Symbol Format
DEFAULT-FILETYPE-MINOR-STYLES

DEFAULT LISP OBJECT MINOR STYLES Editor Variable
Specifies a list of minor styles to be activated in a buffer used to edit a LISP
object. The default list is ("v a x l i s p "), which means the "v a x l i s p " style is
activated.

Display Name Format
Default LISP Object Styles
Symbol Format
DEFAULT-LISP-OBJECT-MINOR-STYLES

DEFAULT MAJOR STYLE Editor Variable
Is bound to the Editor style that is the default major style for a newly created
buffer. The initial value is "e d t Emulation" style. You can use s e t f with the
v a r ia b l e -v a l u e function to change this default. Changing the value of this
variable changes the major style for the "Help" and "General Prompting" buffers.
Any previously created buffers retain their original major styles.

Display Name Format
Default Major Style

Symbol Format
DEFAULT-MAJOR-STYLE

Objects-74

Editor Object Descriptions

DEFAULT MINOR STYLES Editor Variable
Is bound to a list of Editor styles that are the default minor styles for a newly
created buffer. The initial value of this variable is n i l .Any previously created
buffers retain their original minor styles.

Display Name Format
Default Minor Styles
Symbol Format
DEFAULT-MINOR-STYLES

DEFAULT SEARCH CASE Editor Variable
Is bound to a keyword that specifies whether differences in case are to be ignored
in searches. If the keyword is : c a s e -s e n s i t i v e , the search commands perform
case-sensitive searches; if the keyword is : c a s e -i n s e n s i t i v e , the search com
mands perform case-insensitive searches. Initially, the value of this variable is
:CASE-INSENSITIVE.

Display Name Format
Default Search Case
Symbol Format
DEFAULT SEARCH CASE

DEFAULT WINDOW LABEL Editor Variable
Is bound to a string, a function, or n i l that is used by m a k e -w i n d o w as the default
window label. If it is a function, it must have one argument (a window). If the
value is the null string (""), the window is bordered but has no label. If the value
is n i l , the window is unbordered.

Display Name Format
Default Window Label

Objects-75

Editor Object Descriptions

Symbol Format
DEFAULT-WINDOW-LABEL

DEFAULT WINDOW LABEL EDGE Editor Variable
Is bound to keyword that specifies which edge of a window the label text will be
displayed on. The variable is globally bound to :b o t t o m .

Display Name Format
Default Window Label Edge

Symbol Format
DEFAULT-WINDOW-LABEL-EDGE

DEFAULT WINDOW LABEL OFFSET Editor Variable
Is bound to a positive integer or NIL. The value specifies the default offset value
to be used for the label position of a newly created window. The global binding is
n i l ,which causes labels to be centered.

D isp la y N am e F orm at

Default Window Label Offset
Symbol Format
DEFAULT-WINDOW-LABEL-OFFSET

DEFAULT WINDOW LABEL RENDITION Editor Variable
Is bound to a keyword or a list of keywords that specify the default video rendi
tion to be applied to the label of a newly created window. The keyword can be
any of :normal, :reverse, underline, :B0 ld, or :blink. The global binding is
:REVERSE.

Objects-76

Editor Object Descriptions

Display Name Format
Default Window Label Rendition

Symbol Format
DEFAULT-WINDOW-LABEL-RENDITION

DEFAULT WINDOW LINES WRAP Editor Variable
Is used to determine whether lines in a newly created window should wrap or
truncate. A value of n i l indicates that lines should truncate; otherwise, lines
wrap. The global binding is n i l .

Display Name Format
Default Window Lines Wrap
Symbol Format
DEFAULT-WINDOW-LINES-WRAP

DEFAULT WINDOW RENDITION Editor Variable
Is bound to a keyword or a list of keywords that specify the default video rendi
tion to be applied to a newly created window. The keyword can be any of :n o r m a l ,
: REVERSE, : UNDERLINE, : BOLD, O r : BLIN K. The global binding is :NORMAL.

Display Name Format
Default Window Rendition
Symbol Format
DEFAULT-WINDOW-RENDITION

Objects-77

Editor Object Descriptions

DEFAULT WINDOW TRUNCATE CHAR Editor Variable
Is bound to a character used to indicate the truncation of a displayed line. This
variable is globally bound to the #\ > character.

Display Name Format
Default Window Truncate Char
Symbol Format
DEFAULT-WINDOW-TRUNCATE-CHAR

DEFAULT WINDOW TYPE Editor Variable
Is bound to a keyword that specifies the default type of a created window.
Possible values are :a n c h o r e d or :f l o a t i n g . The global binding is :ANCH0r e d .

Display Name Format
Default Window Type
Symbol Format
DEFAULT-WINDOW-TYPE

DEFAULT WINDOW WIDTH Editor Variable
Is bound to a value that is the default width of a newly created window. The
global value of this variable is set to be the width of the screen. If the screen
width is altered, the value of this variable is changed by the global "Screen
Modification Hook" function.

Display Name Format
Default Window Width

Objects-78

Editor Object Descriptions

Symbol Format
DEFAULT-WINDOW-WIDTH

DEFAULT WINDOW WRAP CHAR Editor Variable
Is bound to the default character used to indicate wrapping of text in a window.
The variable is globally bound to #\ <.

Display Name Format
Default Window Wrap Char

Symbol Format
DEFAULT-WINDOW-WRAP-CHAR

DEFINE-ATTRIBUTE Macro
Creates a new attribute that has the specified name and documentation string.
Note that the type of the attribute is not defined until it is bound.

Format
DEFINE-ATTRIBUTE nam e &OPTIONAL docum entation
Arguments
nam e

The name of the attribute. This can be specified as either a symbol or a list of the
form
( s y m b o l :DISPLAY-NAME string)

where “
string”is used as an alternate reference to this attribute.
docum entation

A string that is the documentation text for this attribute

Return Value
The symbol of the attribute

Objects-79

Editor Object Descriptions

DEFINE-COMMAND Macro
Creates a new Editor command by making a new LISP function from the specified
argument list and forms.
As a rule, commands have names of the form n a m e -o f -c o m m a n d -c o m m a n d and
display names of the form "Name of Command". The command can be executed only
in the Editor, either through a key binding or as the argument of the command
"Execute Named Command" (bound to Ctrl/Z globally or PF1 7 in EDT Emulation
style). The created function can be called from any LISP code.

Format
DEFINE-COMMAND nam e arglist
&OPTIONAL com m and-docum entation
&BODY form s
Arguments
nam e

The symbol that will name the command. This can be specified as either a symbol
or a list of the form
(s y m b o l {keyw ord-value-pair))

The acceptable keywords are:
:DISPLAY-NAME
string

The display name for the command, which will be entered in the
*EDI TOR-COMMAND-NAMES* string table.

:CATEGORY categories

The categories must be a symbol or a list of symbols that are userdefined categories the command is cataloged under. The list can be
referenced using the COMMAND-CATEGORIES command. A list of all
commands belonging to a specific category can be obtained with the
CATEGORY-COMMANDS function.

arglist

The list of formal parameters of the command. This is identical to the argument
list in d e f u n .There must be at least one argument, however.
com m and-docum entation

An optional documentation string associated with the command. This string is
associated with the command name and has a documentation type of e d i t o r command.

form s

A list of forms that make up the body of the function executed when the command
is invoked. These forms are identical to the forms given to DEFUN and can include
a function documentation string and declarations.

Objects-80

Editor Object Descriptions

Return Value
The function associated with the command

DEFINE-EDITOR-VARIABLE Macro
Defines an Editor variable. The symbol is interned in the current package and
proclaimed to be a special variable. This definition must appear prior to any
bindings or other uses of the variable.

Format
DEFINE-EDITOR-VARIABLE nam e
&OPTIONAL docum entation
&KEY :BIND-HOOK :UNBIND-HOOK
Arguments
nam e

The name may be specified as either a symbol or a list of the form
(symbol:DISPLAY-n a m e string), where string is a user-defined name for the
variable. The print name of the symbol and the display name (if supplied) are
entered as a key into the *e d i t o r -v a r i a b l e -n a m e s * string table with the symbol
placed into the data slot of the table.
docum entation

A string included in the documentation of the symbol with a documentation type
of E D IT O R -V A R IA B L E .
:BIND-HOOK
A function invoked w h en ev er the variable is bou nd in a context. The function is

called with two arguments—the symbol and the context in which the variable is
being bound.
:UNBIND-HOOK
A function called when the binding of the variable is removed in the context. The
function is called with two arguments—the variable and the context. It defaults
to NIL.

Return Value
The symbol of the Editor variable

Objects-81

Editor Object Descriptions

DEFINE-KEYBOARD-MACRO Function
Causes the Editor to start remembering keystrokes as they are typed at the
terminal until a call is made to the e n d -k e y b o a r d -m a c r o function. If an optional
string is supplied, a keyboard macro is created and returned as if that string were
a sequence of characters that had been entered and remembered previously. The
Editor does not remember entered keystrokes if a string argument is supplied.

Format
DEFINE-KEYBOARD-MACRO &OPTIONAL string
Arguments
string

An optional string used in place of a sequence of keystrokes

Return Value
A function, that when called, will execute the keyboard macro if a string argu
ment is supplied, otherwise T

DELETE-AND-SAVE-REGION Function
Deletes the region and returns a copy of the region containing the deleted text.

Format
DELETE-AND-SAVE-REGION region
Arguments
region

An Editor region

Return Value
A copy of the region that was deleted

Objects-82

Editor Object Descriptions

DELETE-BUFFER Function
Deletes the specified buffer. The calling of this function causes the "Buffer
Deletion Hook" to be invoked. If you delete the current buffer and do not specify
a value for new-current, the current buffer is set by the same rules used in the

n e x t -w i n d o w function, provided other buffers are displayed.

If none is displayed, the Editor chooses arbitrarily. If there are no other usercreated buffers, the Editor returns to an initial state as if it had been invoked
originally by the typing of (ed) with no arguments.

Format
DELETE-BUFFER b u ffe r &OPTIONAL new -current
Arguments
buffer

An Editor buffer or Editor buffer specifier
new-current

An Editor buffer that becomes the new current buffer

Return Value
The symbol naming the Editor buffer

DELETE-CHARACTERS Function
Deletes a specified number of characters after the specified mark (or before it, if
the number is negative). If there are not enough characters after (or before) the
mark, the buffer is not modified.

Format
DELETE-CHARACTERS m ark &OPTIONAL n
Arguments
mark

An Editor mark
n

A fixnum, which defaults to 1, specifying the number of characters to delete.

Objects-83

Editor Object Descriptions

Return Value
The number of characters deleted, or n i l if there were not n characters to delete.

DELETE CURRENT BUFFER Command
Deletes the current buffer. If the buffer is modified, the user is asked whether
to save the contents of the buffer. If another buffer is visible on the screen, that
buffer becomes the new current buffer. If not, the Editor makes an arbitrary
choice of another buffer to be the new current buffer.

Display Name Format
Delete Current Buffer
Function Format
DELETE-CURRENT-BUFFER-COMMAND prefix b u ffe r new -current
Arguments
prefix
Ignored
buffer

The buffer to delete. Default is the current buffer.
new-current

The buffer that becomes the new current buffer. The default is as specified above.

Return Value
T

DELETE LINE Command
Deletes lines or parts of lines, depending on the prefix argument and the location
of the current buffer point:
• If the prefix is n i l , the command deletes between the current buffer point and
the end of the line. If there are non-whitespace characters before the end of
the line, the command deletes those characters and does not delete the newline character. If there are no characters or only whitespace characters before
the end of the line, the command deletes to the end of the line, including the
newline character.

Object s-84

Editor Object Descriptions
• If the prefix is an integer, the command deletes the characters between the
beginning of the line indicated by the prefix and the current buffer point. A
prefix of 0 indicates the current line, l indicates the next line, -l indicates
the previous line, and so on.

Display Name Format
Delete Line
Function Format
DELETE-LINE-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
A disembodied region containing the deleted text

DELETE-MARK Function
Deletes the specified Editor mark. You use this function primarily to remove per
manent marks when they are no longer needed. If the mark being deleted is the
buffer point of a buffer, the window point of a window, the display beginning or
end of a window, or a mark defining a buffer region, the results are unpredictable.

Format
DELETE-MARK m ark
Arguments
mark

An Editor mark

Return Value
N IL

Objects-85

Editor Object Descriptions

DELETE NAMED BUFFER Command
Deletes the specified Editor buffer and any windows associated with it. The
appropriate hook functions are invoked. If the name is n i l , the user is prompted
for a name.

Category
:GENERAL-PROMPTING
Display Name Format
Delete Named Buffer
Function Format
DELETE-NAMED-BUFFER-COMMAND prefix &OPTIONAL nam e
Arguments
prefix

Ignored
nam e

The name of the buffer to delete. It defaults to n i l .

Return Value
T

DELETE NEXT CHARACTER Command
Causes the character following the point in the current window to be deleted. If
you specify an integer prefix argument, characters following the point are deleted
in the amount indicated.

Display Name Format
Delete Next Character

Objects-86

Editor Object Descriptions

Function Format
DELETE-NEXT-CHARACTER-COMMAND p re fix
Arguments
prefix

A p o s itiv e in t e g e r o r n il

Return Value
The number of characters deleted

DELETE NEXT WORD Command
Deletes the next word. If you supply an integer prefix argument, the command
deletes as many words as you specify.

Display Name Format
Delete Next Word
Function Format
DELETE-NEXT-WORD-COMMAND p re fix &OPTIONAL m ark
A r g u m e n ts
prefix

A p o s i t i v e i n t e g e r o r N IL
mark

An Editor mark that defaults to the current buffer point

Return Value
The region containing the word(s) deleted

Objects-87

Editor Object Descriptions

DELETE PREVIOUS CHARACTER Command
Deletes the character preceding the point in the current window if the prefix
argument is n i l . If you specify an integer prefix argument, characters preceding
the point (or following it, if the prefix is negative) are deleted in the amount
indicated.

Display Name Format
Delete Previous Character

Function Format
DELETE-PREVIOUS-CHARACTER-COMMAND p refix
Arguments
prefix

An integer or NIL

Return Value
Undefined

DELETE PREVIOUS WORD Command
Deletes the previous word. If you supply an integer prefix, the command deletes
as many words as you specify.

Display Name Format
Delete Previous Word
Function Format
DELETE-PREVIOUS-WORD-COMMAND prefix &OPTIONAL m ark
Arguments
prefix

A positive integer or NIL

Objects-88

Editor Object Descriptions
mark

An Editor mark that defaults to the current buffer point

Return Value
The region containing the word(s) deleted

DELETE-REGION Function
Deletes the text in the specified region; the empty region remains.

Format
DELETE-REGION region
Arguments
region

An Editor region

Return Value
NIL

DELETE WHITESPACE Command
Deletes the whitespace characters following the current buffer point.

Display Name Format
Delete Whitespace
Function Format
DELETE-WHITESPACE-COMMAND p re fix &OPTIONAL m ark
Arguments
prefix

Ignored
mark

An Editor mark that defaults to the current buffer point

Objects-89

Editor Object Descriptions

Return Value
NIL

DELETE-WINDOW Function
Deletes a window from the Editor. If the window is displayed, it is removed from
the display and then deleted. If the window is the current window, a new current
window is selected from any other currently displayed windows. If there are
none, a new window is displayed from other available buffers. The functions in
"window Deletion Hook" are called prior to any alterations of the window.

Format
DELETE-WINDOW w indow
Arguments
window

An Editor window

Return Value
T

DELETE WORD Command
Deletes the characters from the current point to the beginning of the next word.
If you specify an integer prefix argument, n, characters from the current point to
the end of the nth word are deleted.

Display Name Format
Delete Word
Function Format
DELETE-WORD-COMMAND prefix
Arguments
prefix
A positive integer or n i l

Objects-90

Editor Object Descriptions

Return Value
Undefined

DESCRIBE Command
Displays in the "Help" buffer the documentation string of the specified object.
If the type or name is n i l , the command prompts the user for it in the Editor
prompting window.

Category
:GENERAL-PROMPTING
Display Name Format
Describe
Function Format
DESCRIBE-OBJECT-COMMAND prefix &OPTIONAL type nam e
Arguments
prefix

Ignored
type

A n a m e d o b j e c t t y p e s p e c i f i e r t h a t d e f a u l t s t o n i l — a t t r i b u t e , co m m a n d , b u f f e r ,
STY LE, V ARIABLE, KEYBOARD-MACRO, OT SYMBOL

nam e

The symbol or display name of a named Editor object of the appropriate type

Return Value
None

Objects-91

Editor Object Descriptions

DESCRIBE-OBJECT-COMMAND Function
See "Describe" command.

DESCRIBE WORD Command
Does a LISP d e s c r i b e operation on the word at the argument mark and displays
the result in the "Help" buffer. The mark defaults to the current buffer point.

Display Name Format
Describe Word
Function Format
DESCRIBE-WORD-COMMAND p re fix & OPTIONAL m ark
Arguments
prefix

Ignored
mark

An Editor mark that defaults to the current buffer point
Return Value
Undefined

DESCRIBE WORD AT POINTER Command
Does a LISP d e s c r i b e operation on the symbol indicated by the pointer. If the
pointer indicates a character that is a list terminator, this command momentarily
highlights the matching list-initiator character. If the list initiator is not visible
in the window, the line containing it is displayed in the information area, and the
matching list initiator is highlighted. (See "l i s p Syntax" attribute, especially the
values : CONSTITUENT, :LIST-TERMINATOR, and :LIST-INITIATOR.)

Display Name Format
Describe Word at Pointer

Objects-92

Editor Object Descriptions

Function Format
DESCRIBE-WORD-AT-POINTER-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

DOWNCASE REGION Command
Makes all alphabetic characters in the current buffer select region lowercase.

Display Name Format
Downcase Region

Function Format
DOWNCASE-REGION-COMMAND prefix &OPTIONAL region
Arguments
prefix
Ignored
region

An Editor region that defaults to the buffer select region

Return Value
The region

Object s-93

Editor Object Descriptions

DOWNCASE WORD Command
Makes all alphabetic characters in the current word lowercase.

Display Name Format
Downcase Word
Function Format
DOWNCASE-WORD-COMMAND prefix &OPTIONAL m ark
Arguments
prefix

Ignored
mark

An Editor mark that defaults to the current buffer point

Return Value
The region containing the word that was made all lowercase, or n i l

ED Command
Performs the same actions as the ed function, but you can use it from within the
Editor. If you do not specify an object or a type, the command prompts you for it.

Category
:GENERAL-PROMPTING
Display Name Format
Ed
Function Format
EDIT-LISP-OBJECT-COMMAND prefix &OPTIONAL o b je c t type

Objects-94

Editor Object Descriptions

Arguments
prefix

Ignored
o b je ct

Any object valid for the e d function
type

Any keyword that is a valid value for the : t y p e keyword to the ED function—that
is, : f u n c t i o n or :v a l u e .This is valid only if the object argument is a symbol.

Return Value
Undefined

ED Function
Invokes the VAX LISP Editor. This function takes an optional x argument that
specifies what is to be edited. The value can be a namestring, pathname, or
symbol. In the VAX LISP implementation, the value can also be a list.
This function can be called recursively. This is helpful when implementing
commands such as "Query Search Replace".

Format
ED &OPTIONAL x&KEY :TYPE :READ-ONLY
Arguments
X

A namestring, pathname, symbol, or list that specifies what is to be edited.
A namestring or pathname specifies a file. A symbol specifies a LISP symbol.
If you supply a symbol argument, then you can also specify a :TYPE keyword
argument, : f u n c t i o n or :v a l u e , which tells the Editor whether you want to edit
the symbol’
s function/macro definition or its value.
If you specify a list, the list must be a generalized variable that can be specified
in a call to the s e t f macro. The list is evaluated, and it returns a value to edit.
When you write the buffer containing the value, the Editor replaces the value of
the generalized variable with the new value.
:TYPE keyw ord
You can specify this argument only if the x argument is a symbol. The possible
values are:

Objects-95

Editor Object Descriptions

default)

: FU N CTIO N (the

The Editor is invoked to edit the function or macro definition
associated with the specified symbol.

: VALUE

The Editor is invoked to edit the specified sym bol’
s value.

:READ-ONLY value
You can specify this argument to indicate whether modifications to the buffer can
be written back as a new version of the file being edited or an update of the LISP
object being edited. (See description of b u f f e r - w r i t a b l e .) The possible values
are:
N I L (the default)

Modifications can be written.

Non-NIL

Modifications cannot be written.

Return Value
None ( b y default). See r e t u r n - f r o m - e d i t o r for returning values from a call to
ED.

EDIT FILE Command
Prompts for a file name if the user does not supply one. If there is a buffer
containing that file, the command switches you to it. Otherwise, a new buffer is
created whose name is the name of the file, the named file is read into the buffer,
and the command switches you to that buffer. If there is a buffer with the same
name as the file, but that buffer’
s file is a different file (for example, same name
but in a different directory), the user is prompted for a new buffer name. If the
user does not supply a new buffer name, the old buffer is reused.

Category
:GENERAL-PROMPTING
Display Name Format
Edit File
Function Format
EDIT-FILE-COMMAND p re fix & OPTIONAL file
Arguments
prefix

Ignored

Object s-96

Editor Object Descriptions
file

A p a th n a m e , n a m e s t r in g , str e a m , o r n i l .

Return Value
The buffer

EDIT-LISP-OBJECT-COMMAND Function
See "Ed" command.

*EDITOR-ATTRIBUTE-NAMES* Variable
Specifies a string table that contains the names of all the defined Editor at
tributes.

*EDITOR-BUFFER-NAMES* Variable
Specifies a string table that contains the names of all the existing Editor buffers.

*EDITOR-COMMAND-NAMES* Variable
Specifies a string table that contains the names of commands currently defined in
the Editor.

*EDITOR-DEFAULT-BUFFER* Variable
Can be set to a buffer specifier. When the Editor has no other windows to display,
it will display a window into the specified buffer. If the value of this variable
is n i l (the default) or if the specified buffer does not exist, then the Editor will
display a window into the buffer "Basic introduction" when it has nothing else
to show.
This variable is useful, for example, to set up a LISP “
scratch pad”buffer to be
used when you are not editing files.

Objects-97

Editor Object Descriptions

EDITOR ENTRY HOOK Editor Variable
Specifies a hook function that is called when entering the Editor; that is, when ED
is called from LISP top level.

Display Name Format
Editor Entry Hook

Symbol Format
EDITOR-ENTRY-HOOK

EDITOR-ERROR Function
Is the error-signaling mechanism for the Editor. This function creates an error
message by applying f o r m a t to the format string and the remaining arguments.
It writes this message in the information area, calls the a t t e n t i o n function, and
returns to the Editor command level.

Format
EDITOR-ERROR &OPTIONAL form at-string &REST args
Arguments
format-string

The control string for the f o r m a t function
a rg s

Arguments to be passed to f o r m a t

Return Value
None

Objects-98

Editor Object Descriptions

EDITOR-ERROR-WITH-HELP Function
Is similar to the e d i t o r -e r r o r function but can provide the user with additional
information on the error that has occurred. This function applies f o r m a t to the
error string and the remaining arguments to obtain an error message displayed
in the information area. It calls the a t t e n t i o n function and returns to the Editor
command loop. In addition, it applies f o r m a t to the information string and the
remaining arguments to obtain another string that is saved for later display to
the user.
The initial error message should be brief and give the experienced user enough in
formation to understand the problem. The information message can be tailored to
the less experienced user or can be used to provide more extensive supplemental
information on the nature of the error.

Format
EDITOR-ERROR-WITH-HELP inform ation-string error-string &REST args
Arguments
information-string

A format control string to be applied to the args to produce additional information
error-string

A format control string to be applied to the args to produce a brief error message
a rg s

Used as a source of parameters for format directives for both control strings.

Return Value
None

EDITOR EXIT HOOK Editor Variable
Specifies a hook function that is invoked when you exit from the Editor. The
function is called immediately after the execution of an "Exit" command. The
context searching order is what was in effect at the start of the "Exit" command.

Display Name Format
Editor Exit Hook

Objects-99

Editor Object Descriptions

Symbol Format
EDITOR-EXIT-HOOK

EDITOR-HELP-BUFFER Buffer
See "Help" buffer.

EDITOR INITIALIZATION HOOK Editor Variable
Can be set (using s e t f with v a r i a b l e -f u n c t i o n ) to a hook function of no argu
ments that is called whenever the Editor is initialized. The Editor is initialized
the first time you call the e d function in a LISP session, and anytime you call ed
after having exited the Editor.
Note that when this hook function is called, the Editor state is not fully estab
lished. In particular, c u r r e n t -b u f f e r , c u r r e n t -b u f f e r -p o i n t , and c u r r e n t w i n d o w return no values.
Also, no Editor style is active when this function is called. Therefore, only the
global binding of the variable is meaningful.
This variable has no initial function definition.

Display Name Format
Editor Initialization Hook
Symbol Format
EDITOR-INITIALIZATION-HOOK

‘ EDITOR-KEYBOARD-MACRO-NAMES* Variable
Is a string table that contains the names of all named keyboard macros.

Objects-100

Editor Object Descriptions

EDITOR-LISTEN Function
Returns T if there is another character available immediately from the terminal
while you are using the Editor. This function returns n i l otherwise.

Format
EDITOR-LISTEN
Arguments
None

Return Value
T or NIL

EDITOR PAUSE HOOK Editor Variable
Specifies a hook function that is invoked when you pause the Editor. The function
is called immediately after the execution of a "Pause" command. The context
searching order is what was in effect at the start of the "Pause" command.

Display Name Format
Editor Pause Hook
Symbol Format
EDITOR-PAUSE-HOOK

EDITOR-PROMPTING-BUFFER Buffer
See "General Prompting" buffer.

Objects-101

Editor Object Descriptions

EDITOR-READ-CHAR Function
Returns the next character read from the terminal. You can call this function
only when the Editor is active.

Format
EDITOR-READ-CHAR
Arguments
None

Return Value
A character

EDITOR-READ-CHAR-NO-HANG Function
Returns the next character typed at the terminal if a character is available
immediately. The function returns n i l otherwise.

Format
EDITOR-READ-CHAR-NO-HANG
Arguments
None

Return Value
A ch ara cter; or n il , if n o n e is a v a ila b le

EDITOR RECURSIVE ENTRY HOOK Editor Variable
Specifies a function that is called during recursive calls to the e d function.

Display Name Format
Editor Recursive Entry Hook

Objects—102

Editor Object Descriptions

Symbol Format
EDITOR-RECURSIVE-ENTRY-HOOK

‘ EDITOR-RETAIN-SCREEN-STATE* Variable
Specifies whether or not the state of the screen is to be retained when you cause
the Editor to pause. The default value is n i l , which means that the screen is
erased when the Editor pauses and is restored to its previous state when the
Editor is reentered.
When you are debugging new commands, however, it may be desirable for you to
alter this behavior. When the variable is set to T, the screen is not erased when
the Editor pauses.

*EDITOR-STYLE-NAMES* Variable
Specifies a string table that contains the names of all the defined Editor styles.

EDITOR-UNREAD-CHAR Function
Unreads the last character read from the terminal while in the Editor. See
Common LISP: The Language for more information about unreading.

Format
EDITOR-UNREAD-CHAR character
Arguments
character
The last character read from the terminal

Return Value
NIL

Objects-103

Editor Object Descriptions

*EDITOR-VARIABLE-NAMES* Variable
Specifies a string table that contains the names of all the defined Editor variables.

*EDITOR-WORKSTATION-BANNER* Variable
Is bound to a string that contains the text of the Editor window banner on the
VAXstation. The initial binding is “
VAX LISP Editor”
.

EDT APPEND Command
Deletes the current select region of text (the region defined from the current
buffer point and the mark in the "Buffer Select Mark" variable) and stores the
deleted region in the Editor variable "e d t Paste Buffer". The region is inserted
at the end of the current contents, if any, of the paste buffer.
A select region is a region established by executing the command "e d t Select"
(or "Set select Region"), "e d t Append" can add to text that was previously
deleted and stored by execution of either "e d t cut" or "e d t Append".

Display Name Format
EDT Append
Function Format
EDT-APPEND-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

O b jects-1 04

Editor Object Descriptions

EDT BACK TO START OF LINE Command
Moves the current buffer point to the beginning of the current line. If the point
is already at the beginning of a line, it is moved to the beginning of the previous
line. If a positive integer prefix is supplied, the point is moved backward the
number of lines indicated.

Display Name Format
EDT Back to Start of Line
Function Format
EDT-BACK-TO-START-OF-LINE-COMMAND p refix
Arguments
prefix

An integer or n i l

Return Value
The modified point

EDT BEGINNING OF LINE Command
Moves the point of the current buffer to the beginning of the next line if the prefix
argument is NIL, and if "EDT D i r e c t i o n Mod e " is :FORWARD. If "EDT D i r e c t i o n
Mode" is : b a c k w a r d , the point is moved backward to the nearest beginning of a
line.
If you specify a positive integer prefix argument, n, the point is moved to the
nth beginning of a line in the direction indicated by "EDT Direction Mode". If
you specify a negative integer prefix argument, n, the point is moved to the nth
beginning of a line in the direction opposite that indicated by "EDT-DirectionMode".

Display Name Format
EDT Beginning of Line

O bjects-1 05

Editor Object Descriptions

Function Format
EDT-BEGINNING-OF-LINE-COMMAND prefix
Arguments
prefix

A fix n u m o r n il

Return Value
The modified point

EDT CHANGE CASE Command
Changes the case of any characters in the region specified by the "Buffer Select
Region" Editor variable or the character at the current buffer point if no region is
specified.

Display Name Format
EDT Change Case
Function Format
EDT-CHANGE-CASE-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

O b jects-1 06

Editor Object Descriptions

EDT CUT Command
Deletes the current select region of text (the region defined from the current
buffer point and the mark in the "Buffer Select Mark" variable) and stores the
deleted region in the Editor variable "e d t Paste Buffer". The previous contents
of the paste buffer are lost.
A select region is a region established by executing the command "e d t Select"
(or "Set Select Mark").

Display Name Format
EDT Cut
Function Format
EDT-CUT-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

EDT DELETE CHARACTER Command
Deletes the character at the position of the cursor (that is, at the position imme
diately following the point in the current buffer) if the prefix argument is n i l .If
you specify a positive integer prefix argument, characters following the point are
deleted in the amount indicated. The Editor variable "e d t Deleted Character" is
set to the last character deleted.

Display Name Format
EDT Delete Character
Function Format
EDT-DELETE-CHARACTER-COMMAND prefix

Objects-107

Editor Object Descriptions

Arguments
prefix

An i n t e g e r o r N I L

Return Value
The last character deleted

EDT DELETE LINE Command
Deletes the line of text starting at the current buffer point and extending to the
beginning of the next line. If you specify an integer prefix argument, lines are
deleted in the amount indicated (in a forward direction if integer is positive, in
a backward direction if integer is negative). The Editor variable "e d t Deleted
Line" is set to the last line deleted.

Display Name Format
EDT Delete Line
Function Format
EDT-DELETE-LINE-COMMAND prefix
Arguments
prefix

An i n t e g e r o r n i l

Return Value
A region containing the last line deleted

EDT DELETE PREVIOUS CHARACTER Command
Deletes the character preceding the current buffer point. If a prefix argument is
supplied, the command deletes the number of previous characters specified by the
argument. The value of the "e d t Deleted Character" Editor variable is set to the
last character deleted.

Objects-108

Editor Object Descriptions

Display Name Format
EDT Delete Previous Character
Function Format
EDT-DELETE-PREVIOUS-CHARACTER-COMMAND prefix
Arguments
prefix

An i n t e g e r o r n i l

Return Value
The last character deleted

EDT DELETE PREVIOUS LINE Command
Deletes from the current buffer point back to the beginning of the current line.
If the point was already at the beginning of a line, the command deletes back to
the beginning of the previous line. If a prefix argument, n, is supplied, n lines are
deleted. The value of the "e d t Deleted Line" Editor variable is set to a region
containing the last line deleted.

Display Name Format
EDT Delete Previous Line
Function Format
EDT-DELETE-PREVIOUS-LINE-COMMAND p re fix
Arguments
prefix

An integer or NIL

Return Value
A region containing the last deleted line

Objects-109

Editor Object Descriptions

EDT DELETE PREVIOUS WORD Command
Deletes from the current buffer point back to the beginning of the current word.
If the point was already at the beginning of a word, the command deletes back
to the beginning of the previous word. If a prefix argument, n, is supplied, n
words are deleted. The value of the "e d t Deleted Word" Editor variable is set to
a region containing the last word deleted.

Display Name Format
EDT Delete Previous Word
Function Format
EDT-DELETE-PREVIOUS-WORD-COMMAND prefix
Arguments
prefix

An integer or nil

Return Value
A region containing the last deleted word

EDT DELETE TO END OF LINE Command
Deletes all characters found between the point of the current buffer and the
end of the current line. If you specify a positive integer prefix argument, n, all
characters found between the buffer point and the nth end-of-line following the
point are deleted. If you specify a negative integer prefix argument, n, the sign is
ignored and the absolute value of the argument is used. The value of the Editor
variable "e d t Deleted Line" is set to the last line deleted.

Display Name Format
EDT Delete to End of Line
Function Format
EDT-DELETE-TO-END-OF-LINE-COMMAND p refix

Objects-110

Editor Object Descriptions

Arguments
prefix

An integer o r n i l

Return Value
The line that was deleted

EDT DELETE WORD Command
Deletes all characters between the point of the current buffer and the next end
of a word. If you specify a positive integer prefix argument, n, the characters
between the current buffer point and the end of the nth following word are
deleted. If you specify a negative integer prefix argument, the sign is ignored and
the absolute value is used. The Editor variable "e d t Deleted Word" is set to the
last word deleted.

Display Name Format
EDT Delete Word

Function Format
EDT-DELETE-WORD-COMMAND prefix
Arguments
prefix

An integer or NIL

Return Value
The deleted word

EDT DELETED CHARACTER Editor Variable
Is bound to the last character deleted by the "e d t Delete Character" command.

Display Name Format
EDT Deleted Character

Objects-111

Editor Object Descriptions

Symbol Format
EDT-DELETED-CHARACTER

EDT DELETED LINE Editor Variable
Is bound to the region containing the last line deleted by the "e d t Delete Line"
command or by the "e d t Delete to End of Line" command.

Display Name Format
EDT Deleted Line
Symbol Format
EDT-DELETED-LINE

EDT DELETED WORD Editor Variable
Is bound to the region containing the last word deleted by the "e d t Delete Word"
command.

Display Name Format
EDT Deleted Word
Symbol Format
EDT-DELETED-WORD

EDT DESELECT Command
See "Unset Select Mark" command.

O bjects-1 12

Editor Object Descriptions

EDT DIRECTION MODE Editor Variable
Specifies the direction in which certain commands in "e d t Emulation" style are
to operate. The possible values are :f o r w a r d and :b a c k w a r d .

Display Name Format
EDT Direction Mode
Symbol Format
EDT-DIRECTION-MODE

EDT EMULATION Style
Is the default major style for the VAX LISP Editor. This style is designed to
imitate the basic keypad behavior of the VMS EDT Editor.

Display Name Format
EDT Emulation
Symbol Format
EDT-EMULATION

EDT END OF LINE Command
Moves the current buffer point to the next end-of-line if "e d t Direction Mode" is
:FORWARD or to the previous end-of-line if "EDT Direction Mode" is :BACKWARD. If
you specify an integer prefix argument, n, the point is moved to the nth end of a
line in the direction indicated by "e d t Direction Mode"; if the integer is negative,
the direction is opposite to that indicated by "e d t Direction Mode".

Display Name Format
EDT End of Line

Objects-113

Editor Object Descriptions

Function Format
EDT-END-OF-LINE-COMMAND prefix
Arguments
prefix
An integer o r n i l

Return Value
The modified point

EDT MOVE CHARACTER Command
Moves the point of the current buffer by one character if prefix is n i l . If the value
of "e d t Direction Mode" is :f o r w a r d , the point is moved forward; if : BACKWARD,
it is moved backward. If you specify an integer prefix argument, the point is
moved in the direction of "e d t Direction Mode" by the number of characters
indicated. If you specify a positive integer prefix argument, n, the point is moved
n characters in the direction indicated by "e d t Direction Mode". If you specify
a negative integer prefix argument, n, the point is moved n characters in the
direction opposite to that indicated by "EDT Direction Mode".

Display Name Format
EDT Move Character
Function Format
EDT-MOVE-CHARACTER-COMMAND prefix
Arguments
prefix
A fixnum o r n i l

Return Value
The modified point

Objects-114

Editor Object Descriptions

EDT MOVE PAGE Command
Moves the point one page in the direction of "EDT Direction Mode" if the prefix
argument is n i l . If you specify a positive integer prefix argument, the point is
moved in the direction of "e d t Direction Mode" by the number of pages indicated;
if the integer is negative, the direction is opposite to that of "e d t Direction
Mode".

Display Name Format
EDT Move Page
Function Format
EDT-MOVE-PAGE-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The modified point

EDT MOVE WORD Command
Moves the current buffer point to the next or previous beginning of a word in
the direction indicated by "EDT Direction Mode" if the prefix argument is n i l . If

you specify a positive integer prefix argument, the point is moved in the direction
of "e d t Direction Mode" by the number of words indicated; if the integer is
negative, the direction is opposite to that of "e d t Direction Mode".

Display Name Format
EDT Move Word
Function Format
EDT-MOVE-WORD-COMMAND prefix

Objects-115

Editor Object Descriptions

Arguments
prefix

An integer or n i l

Return Value
The current buffer point

EDT PASTE Command
Inserts the contents of the region bound to the Editor variable "e d t Paste

Buffer" at the current buffer point.

Display Name Format
EDT Paste
Function Format
EDT-PASTE-COMMAND prefix
Arguments
prefix

Ignored

Return Value
The inserted region

EDT PASTE AT POINTER Command
Moves the current buffer point to the position indicated by the pointer and then
inserts at that location the region contained in the paste buffer. If the pointer
is beyond the end of a line, the region is inserted at the end of that line. If the
pointer is beyond the end of the buffer region, the paste region is inserted at the
end of the buffer region.

Display Name Format
EDT Paste at Pointer

Objects-116

Editor Object Descriptions

Function Format
EDT-PASTE-AT-POINTER-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
The inserted region

EDT PASTE BUFFER Editor Variable
Is bound in the "e d t Emulation" style. The value of this variable is the region
most recently deleted by the "e d t cut" command.

Display Name Format
EDT Paste Buffer

Symbol Format
EDT-PASTE-BUFFER

EDT QUERY SEARCH Command
Prompts for a string to use as a pattern in a search. The search is forward if "e d t
Direction Mode" is :FORWARD; backward, if "EDT Direction Mode" is :BACKWARD.

The point is moved to the end of the first matching string if the search is forward,
or to the beginning of the first matching string if the search is backward. If the
prefix argument is an integer, n, the command searches for the nth occurrence of
the string. If n is negative, the command searches in the direction opposite to the
setting of "EDT Direction Mode".

Display Name Format
EDT Query Search

Objects-117

Editor Object Descriptions

Function Format
EDT-QUERY-SEARCH-COMMAND prefix &OPTIONAL string
Arguments
prefix

An integer o r n i l
string

The string to search for

Return Value
The modified point

EDT REPLACE Command
Deletes the current select region of text (the region defined from the current
buffer point and the mark in the "Buffer Select Mark" variable) and replaces it
with the region stored in the Editor variable "EDT Paste Buffer".
A select region is a region established by executing the command "e d t Select"
(or "Set Select Region"). The replacement text is text placed in the paste buffer
by means of either "e d t Cut" or "e d t Append".

Display Name Format
EDT Replace
Function Format
EDT-REPLACE-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

O b jects—118

Editor Object Descriptions

EDT SCROLL WINDOW Command
Scrolls the current window in the direction indicated by "e d t Direction Mode" by
a distance that is two-thirds the height of the window, if the prefix argument is
n i l .If prefix is positive, the window is scrolled in the direction of "e d t Direction
Mode" by a distance of prefix times half the height of the window; if prefix is
negative, the window is scrolled in the direction opposite to the setting of "e d t
Direction Mode" by a distance of prefix times half the height of the window.

Display Name Format
EDT Scroll Window
Function Format
EDT-SCROLL-WINDOW-COMMAND prefix
Arguments
prefix

A f i x n u m o r N IL

Return Value
The new point

EDT SEARCH AGAIN Command
Searches for text that matches the search string saved in the "Last Search
string" Editor variable. If "e d t Direction Mode" is : f o r w a r d , the direction of
the search is forward; if "e d t Direction Mode" is : b a c k w a r d , the direction of the
search is backward.

Display Name Format
EDT Search Again
Function Format
EDT-SEARCH-AGAIN-COMMAND prefix

Object&-119

Editor Object Descriptions

Arguments
prefix

Ignored

Return Value
The modified point

EDT SELECT Command
See "Set Select Mark" command.

EDT SET DIRECTION BACKWARD Command
Sets the value of the Editor variable "e d t Direction Mode" to :b a c k w a r d .The
prefix argument is ignored.

Display Name Format
EDT Set Direction Backward
Function Format
EDT-SET-DIRECTION-BACKWARD-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
:BACKWARD

O b jects-1 20

Editor Object Descriptions

EDTSET DIRECTION FORWARD Command
Sets the value of the Editor variable "e d t D i r e c t i o n Mod e " to :f o r w a r d . The
prefix argument is ignored.

Display Name Format
EDT Set Direction Forward
Function Format
EDT-SET-DIRECTION-FORWARD-COMMAND prefix
Arguments
prefix

Ignored

Return Value
:FORWARD

EDT SPECIAL INSERT Command
Inserts the character at the current buffer point whose character code is specified
by the prefix argument. For example, to insert a d e l e t e character, you specify a
prefix argument of 127. The character is inserted with no special interpretation
by the Editor.

Display Name Format
EDT Special Insert
Function Format
EDT-SPECIAL-INSERT-COMMAND prefix
Arguments
prefix

The prefix argument is interpreted as the character code of a character to be
inserted.

Objects-121

Editor Object Descriptions

Return Value
The character

EDT SUBSTITUTE Command
Causes the text in the "e d t Paste Buffer" Editor variable to replace a string just
located in the text by the "EDT Query Search" or "EDT Search Again" command.
After the text is replaced, the command searches for the next occurrence of the
search string. If a prefix argument is supplied, the command is executed the
number of times indicated.

Display Name Format
EDT Substitute
Function Format
EDT-SUBSTITUTE-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
Undefined

EDT UNDELETE CHARACTER Command
Restores the character last deleted by the "e d t Delete Character" command
(that is, the value of the Editor variable "e d t Deleted Character") to the posi
tion of the current buffer point if prefix is n i l . If you specify an integer prefix
argument, the character is inserted the number of times indicated.

Display Name Format
EDT Undelete Character

O bjects-1 22

Editor Object Descriptions

Function Format
EDT-UNDELETE-CHARACTER-COMMAND prefix
Arguments
prefix

A p o sitiv e in te g e r o r n il

Return Value
The inserted character

EDT UNDELETE LINE Command
Restores the line last deleted by the "e d t Delete Line" or "e d t Delete to End of
Line" command (that is, the value of the Editor variable "e d t Deleted Line") to

the position of the current buffer point if prefix is n i l . If you specify an integer
prefix argument, the line is inserted the number of times indicated.

Display Name Format
EDT Undelete Line
Function Format
EDT-UNDELETE-LINE-COMMAND prefix
Arguments
prefix

A positive integer or n i l

Return Value
The inserted region

Objects-123

Editor Object Descriptions

EDT UNDELETE WORD Command
Restores the word last deleted by the "e d t Delete Word" command (that is, the
value of the Editor variable "e d t Deleted Word") to the position of the current
buffer point if prefix is n i l . If you specify an integer prefix argument, the word is
inserted the number of times indicated.

Display Name Format
EDT Undelete Word
Function Format
EDT-UNDELETE-WORD-COMMAND prefix
Arguments
prefix

A positive integer or n i l

Return Value
The inserted region

EMACS Style
Is an Editor style designed to imitate the functions and key bindings of an editor
based on EMACS.

Display Name Format
EMACS

Symbol Format
EMACS

O bjects-1 24

Editor Object Descriptions

EMACS BACKWARD SEARCH Command
Searches backward for the search string specified in the last command. If the last
command was not a searching command, the "e m a c s Backward Search" command
prompts for a search string. If no prefix is supplied, this command searches for
the first occurrence of the search string. For a prefix n, the command searches for
the nth occurrence of the string.

Category
:EMACS-SEARCH

Display Name Format
EMACS Backward Search
Function Format
EMACS-BACKWARD-SEARCH-COMMAND p refix
Arguments
prefix

An integer or n i l

Return Value
The updated current buffer point

EMACS FORWARD SEARCH Command
Searches forward for the search string specified in the last command. If the last
command was not a searching command, the "e m a c s Forward Search" command
prompts for a search string. If no prefix is supplied, this command searches for
the first occurrence of the search string. For a prefix n, the command searches for
the nth occurrence of the string.

Category
:EMACS-SEARCH

Objects-125

Editor Object Descriptions

Display Name Format
EMACS Forward Search
Function Format
EMACS-FORWARD-SEARCH-COMMAND p re fix &OPTIONAL string
Arguments
prefix
An integer or n i l
string

A string

Return Value
The updated current buffer point

EMPTY-BUFFER-P Function
Returns t if the argument buffer is empty; otherwise, returns n i l .

Format
EMPTY-BUFFER-P b u ffer
Arguments
buffer
An Editor buffer

Return Value
T o r N IL

Objects-126

Editor Object Descriptions

EMPTY-LINE-P Function
Returns t if the specified mark points into a line having no characters; otherwise,
the function returns n i l .

Format
EMPTY-LINE-P m ark
Arguments
mark
An Editor mark

Return Value
T o r N IL

EMPTY-REGION-P Function
Returns t if the argument buffer is empty; otherwise, returns n i l .

Format
EMPTY-REGION-P region
Arguments
region

An Editor region

Return Value
T o r NIL

Objects-127

Editor Object Descriptions

END KEYBOARD MACRO Command
Ends the keyboard macro started with the "start Keyboard Macro" command.
After this command is executed, the keyboard macro can be executed by means of
the "Execute Keyboard Macro" command.

Display Name Format
End Keyboard Macro
Function Format
END-KEYBOARD-MACRO-COMMAND prefix
Arguments
prefix

Ignored

Return Value
A function that, if called, executes the keyboard macro

END-KEYBOARD-MACRO Function
Terminates the keyboard macro started with the s t a r t -k e y b o a r d -m a c r o function.
This function returns a function that, when called, executes the keyboard macro.

Format
END-KEYBOARD-MACRO
Arguments
None

Return Value
A function

Objects-128

Editor Object Descriptions

END OF BUFFER Command
Moves the buffer point to the end of the current buffer.

Display Name Format
End of Buffer
Function Format
END-OF-BUFFER-COMMAND prefix
Arguments
prefix

Ignored

Return Value
The updated buffer point

END OF LINE Command
Moves the point to the end of the current line if the prefix argument is n i l . If you
specify an integer prefix argument, the point is moved down the number of lines
indicated (or up, if the prefix is negative) and then to the end of the line.

Display Name Format
End of Line
Function Format
END-OF-LINE-COMMAND prefix
Arguments
prefix

An integer or n i l

Objects-129

Editor Object Descriptions

Return Value
The modified point

END-OF-LINE-P Function
Returns T if the specified mark points to the position immediately following the
last character on a line; otherwise, the function returns NIL.

Format
END-OF-LINE-P m ark
Arguments
mark

An Editor mark

Return Value
T or NIL

END OF OUTERMOST FORM Command
Moves the buffer point from inside a LISP form to the end of the outermost form
surrounding it. If the point is between two outer forms, it is moved to the end of
the following one. An outermost form is one whose opening parenthesis is in the
leftmost column on the screen.

Display Name Format
End of Outermost Form
Function Format
END-OF-OUTERMOST-FORM-COMMAND prefix
Arguments
prefix

Ignored

Objects-130

Editor Object Descriptions

Return Value
The updated buffer point mark

END OF PARAGRAPH Command
Moves the mark to the end of the paragraph. If the mark is not supplied, it
defaults to the current buffer point.

Display Name Format
End of Paragraph
Function Format
END-OF-PARAGRAPH-COMMAND prefix &OPTIONAL m ark
Arguments
prefix

Ignored
mark

An Editor mark that defaults to the current buffer point

Return Value
The updated mark

END OF WINDOW Command
Moves the cursor to the end of the current window.

Display Name Format
End of Window
Function Format
END-OF-WINDOW-COMMAND prefix

Objects-131

Editor Object Descriptions

Arguments
prefix

Ignored

Return Value
The updated current buffer point

ENQUEUE-EDITOR-COMMAND Function
Places the argument function onto the queue for later processing by the Editor.
The function can be any LISP function; it will be called in the correct time
relation to commands invoked from the keyboard and from the pointing device.
The value of the keyword :a r g u m e n t s can be a list of arguments to be passed to
the argument function.

Format
ENQUEUE-EDITOR-COMMAND function &KEY ARGUMENTS
Arguments
function

Any LISP function
:ARGUMENTS
A list of arguments to be passed to the argument function. The default is n i l .

Return Value
The argument function

EVALUATE LISP REGION Command
Causes the text in the region bound to the "Buffer Select Region" variable to be
evaluated as LISP code. The result of the evaluation is printed in the information
area. The result is also bound to the "l i s p Evaluation Result" variable.

Display Name Format
Evaluate LISP Region

Objects-132

Editor Object Descriptions

Function Format
EVALUATE-LISP-REGION-COMMAND prefix
Arguments
prefix

Ignored

Return Value
A list of the values returned from the region evaluated

EXCHANGE POINT AND SELECT MARK Command
Moves the cursor to the location bound to the "Buffer Select Mark" variable in
the current buffer and sets the "Buffer Select Mark" variable to point to the old
cursor position. The command function returns the updated buffer select mark or
n i l if no mark was selected.

Display Name Format
Exchange Point and Select Mark
Function Format
EXCHANGE-POINT-AND-SELECT-MARK-COMMAND prefix
Arguments
prefix

Ignored

Return Value
The updated buffer select mark or n i l

Objects-133

Editor Object Descriptions

EXECUTE KEYBOARD MACRO Command
Executes the most recently defined keyboard macro once if the prefix argument
is n i l . If you specify an integer prefix argument, the command is executed the
number of times indicated.

Display Name Format
Execute Keyboard Macro
Function Format
EXECUTE-KEYBOARD-MACRO-COMMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The value returned by the last function executed in the keyboard macro

EXECUTE NAMED COMMAND Command
Prompts the user for the name of an Editor command to execute if you do not
specify one. The prefix argument is passed to the command you want executed.

Display Name Format
Execute Named Command
Function Format
EXECUTE-NAMED-COMMAND-COMMAND prefix
Arguments
prefix

An integer or n i l

Objects-134

Editor Object Descriptions

Return Value
The value returned by the named command

EXIT Command
Returns control to LISP, and the Editor state is lost. If there are modified buffers,
the Editor asks the user if the buffers should be saved. If the response is yes, the
Editor executes the "Write Modified Buffers" command.

Display Name Format
Exit
Function Format
EXIT-EDITOR-COMMAND prefix
Arguments
prefix

Ignored

Return Value
None

EXIT-EDITOR-COMMAND Function
See "Exit" command.

EXIT RECURSIVE EDIT Command
Causes the Editor to exit one level of calls to the e d function, returning no values
from e d .You must use this command to return from a recursive call to e d . If
invoked from the Editor’
s top level, the command has the same effect as "Pause
Editor".

This command is commonly used in conjunction with the command "Query search
Replace".

Objects-135

Editor Object Descriptions

Display Name Format
Exit Recursive Edit
Function Format
EXIT-RECURSIVE-EDIT-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
Undefined

FIND-AMBIGUOUS Function
Returns a list of those strings in the string table that begin with the specified
string. The list is in alphabetical order. String comparisons are case-insensitive.

Format
FIND-AMBIGUOUS string string-table
Arguments
string

A string to be compared with the string-table entries
string-table

An Editor string table

Return Value
An alphabetically ordered list of those strings in the string table that begin with
the specified string, or n i l if none

Objects-136

Editor Object Descriptions

FIND-ATTRIBUTE Function
Returns the symbol that names the specified attribute if the argument is a
defined attribute, or n i l otherwise.

Format
FIND-ATTRIBUTE attribute
Arguments
attribute

An attribute specifier

Return Value
A sy m b o l o r n il

FIND-BUFFER Function
Returns the buffer if the argument is a buffer specifier, or n i l otherwise.

Format
FIND-BUFFER buffer
Arguments
buffer

An Editor buffer specifier

Return Value
An Editor buffer or n i l

O bjects-1 37

Editor Object Descriptions

FIND-COMMAND Function
Returns the associated function if the argument is a command specifier, or n i l
otherwise.

Format
FIND-COMMAND com m and
Arguments
com m an d

An Editor command specifier

Return Value
The function associated with the command or n i l

FIND-STYLE Function
Returns an Editor style if the argument is a style specifier, or n i l otherwise.

Format
FIND-STYLE style
Arguments
style

An Editor style specifier

Return Value
An Editor style or n i l

Objects-138

Editor Object Descriptions

FIND-VARIABLE Function
Returns an Editor variable symbol if the argument is an Editor variable, the
symbol that names an Editor variable specifier, or n i l otherwise.

Format
FIND-VARIABLE variable
Arguments
variable

An Editor variable specifier

Return Value
The symbol that names the Editor variable, or n i l

FIRST-LINE-P Function
Is a predicate that returns T if the mark points into the first line in a buffer or a
disembodied region.

Format
FIRST-LINE-P m ark
A rgum en ts
mark
An Editor mark

Return Value
T o r N IL

O bjects-1 39

Editor Object Descriptions

FORWARD CHARACTER Command
Moves the point in the current window forward by one character if the prefix
argument is n i l .If you specify an integer prefix argument, the point is moved
forward by the number of characters indicated (or backward, if the prefix is
negative).

Display Name Format
Forward Character
Function Format
FORWARD-CHARACTER-COMMAND p re fix
Arguments
prefix

An integer specifying how many characters to move

Return Value
The updated buffer point mark

FORWARD KILL RING Command
Rotates the kill ring forward by the number of elements specified by the prefix
argument. The prefix defaults to l.

Category
:KILL-RING
Display Name Format
Forward Kill Ring
Function Format
FORWARD-KILL-RING-COMMAND p refix

Objects-140

Editor Object Descriptions

Arguments
prefix

An integer o r n i l

Return Value
Undefined

FORWARD PAGE Command
Moves the point forward one page. A page is delimited by any character having a
"Page Delimiter" attribute value of l. If you specify an integer prefix argument,
the point is moved forward the number of pages indicated.

Display Name Format
Forward Page
Function Format
FORWARD-PAGE-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
Updated buffer point

FORWARD SEARCH Command
Prompts the user for a string to use as a pattern for a forward search. The string
defaults to the value of the Editor variable "Last Search string". The buffer
point is moved to the end of the matching string. If the user specifies a prefix
argument, n, the search occurs n times.

Display Name Format
Forward Search

Objects-141

Editor Object Descriptions

Function Format
FORWARD-SEARCH-COMMAND prefix &OPTIONAL string
Arguments
prefix

An integer o r n i l
string

A string that defaults to the value of the Editor variable " L a s t s e a r c h s t r i n g "

Return Value
A modified buffer point

FORWARD WORD Command
Moves the point forward to the beginning of the next word. A word is delimited
by a character having a "Word Delimiter" attribute value of l. If you specify
an integer prefix argument, the point is moved forward the number of words
indicated.

Display Name Format
Forward Word
Function Format
FORWARD-WORD-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
A modified buffer point

Objects-142

Editor Object Descriptions

FORWARD-WORD-COMMAND Function
Moves the point forward to the first character of the next word (or nth word
if the prefix n was supplied). This function takes an optional mark argument
that defaults to the current buffer point. It moves the mark forward to indicate
the word delimiter character that follows the present word (or the next word, if
the mark is initially indicating a word delimiter). If a prefix n is supplied, this
function moves the mark forward to indicate the word delimiter following the nth
word.

Format
FORWARD-WORD-COMMAND p re fix &OPTIONAL m ark
Arguments
prefix

An integer or n i l
mark

An Editor mark that defaults to the current buffer point

Return Value
The modified mark

GENERAL PROMPTING Buffer
Is used by the general prompting facility to display prompts and obtain input
from the user. A floating window is associated with this buffer. The following
commands are bound locally in this buffer:
•

"Prompt Help"

•

"Prompt Read and Validate"

•

"Prompt Show Alternatives"

•

"Prompt Complete String"

Display Name Format
General Prompting

Objects-143

Editor Object Descriptions

Symbol Format
EDITOR-PROMPTING-BUFFER

GET-BOUND-COMMAND-FUNCTION Function
Returns the function of the command currently bound to the specified keysequence; or, if you specify a context, bound to the specified key-sequence in that
context. If the specified sequence is ambiguous, the keyword :p r e f i x is returned.

Format
GET-BOUND-COMMAND-FUNCTION key-sequence &OPTIONAL context
Arguments
k ey-sequ en ce

A character or vector of characters
con text

An Editor context specifier that defaults to the current context

Return Value
A function, : P R E F i x , or n i l

GET-POINTER-STATE Function
Returns an object that contains the state of the pointing device at some point in
time. The pointer-state information includes:
• The text position (line and character position) indicated by the pointer cursor.
• The window position (column and row coordinates in a particular Editor
window) indicated by the pointer cursor.
• The state (up or down) of each button on the pointing device. If a button was
in transition (being depressed or released) at the point in time for which the
pointer state is stored, the button state is the state of the buttons at the end
of the transition.
• In some cases, a particular previous action of the pointing device (see below).
If called from within an Editor command and if that command was invoked by an
action of the pointing device, g e t -p o i n t e r - s t a t e returns an object containing the
pointer state at the time of the pointer action that invoked the command.

O b jects—144

Editor Object Descriptions
In this case the action information in the pointer-state object is the action that
invoked the currently executing command (see b i n d - p o i n t e r - c o m m a n d for infor
mation on pointer actions). If the command was not invoked by a pointer action,
G E T - P O IN T E R - S T A T E returns the current state of the pointing device.
If called from outside the active Editor environment, this function returns an
object that contains the current state of the pointing device: text position, window
position, and button state. In this case the action information in the pointerstate object is n i l . If the pointer cursor is outside the Editor’
s display area,
G E T - P O IN T E R - S T A T E returns N IL .
g e t -p o in t e r - s t a t e

is u s e fu l in c o m m a n d s th a t p e r fo r m d iffe r e n t a c tio n s d e p e n d

i n g o n s o m e fe a t u r e o f t h e p o in t e r s t a t e o t h e r th a n th e p a r t ic u la r p o in t e r a c tio n
t h a t in v o k e d th em .

The information contained in the pointer-state object can be accessed by means of
the functions p o i n t e r - s t a t e - t e x t - p o s i t i o n , p o i n t e r - s t a t e - w i n d o w - p o s i t i o n ,
P O IN T E R -S T A T E -B U T T O N S , a n d P O IN T E R -S T A T E -A C T IO N .

Format
GET-POINTER-STATE
Arguments
None

Return Value
A p o in te r - s ta te o b je c t o r n il

GET-STRING-TABLE-VALUE Function
Searches the specified string table for an entry whose key matches the string
argument. You can use this function with s e t f to modify the contents of the
string table.

Format
GET-STRING-TABLE-VALUE string string-table
Arguments
string

A character string
string-table

An Editor string table

Objects-145

Editor Object Descriptions

Return Value
Two values:
1. The first value is the entry found, or n i l .
2. The second value is T if the first value is valid.

GROW WINDOW Command
Increases the height of the specified window (or current window, if none is
specified) by one line. If the window is anchored, at least one other window must
be displayed on the screen. Other displayed windows that are anchored decrease
in height proportionately, except any window having only one line. Floating
windows can always grow or shrink within the range of one line to the height of
the screen.
If the prefix is a positive integer, the window grows by the number of lines
indicated. If the prefix is a negative integer, the window shrinks by the number
of lines indicated.

Display Name Format
Grow Window
Function Format
GROW-WINDOW-COMMAND p re fix & OPTIONAL w indow
Arguments
prefix

An integer or n i l
w indow

An Editor window

Return Value
The new window height

Objects-146

Editor Object Descriptions

HELP Buffer
Is used to display Help information. A floating window is associated with this
buffer. The buffer is used by the Editor "Help" command and by the prompting
facility. It can also be used by user-defined commands.

Display Name Format
Help
Symbol Format
EDITOR-HELP-BUFFER

HELP Command
Is used to supply assistance to the user while the Editor is being used. This
command makes a window into the "Help" buffer visible. It inserts the text of
the help-string argument, if supplied, or the text of the current value of the "Help
Text" Editor variable. If both are n i l , the command signals an Editor error with
the message "No Help Available".

Display Name Format
Help
Function Format
HELP-COMMAND p re fix & OPTIONAL help-string
Arguments
prefix

Ignored
help-string

An optional string for use as the current help text

Return Value
None

Objects-147

Editor Object Descriptions

HELP ON EDITOR ERROR Command
Displays the last message created by the e d i t o r -e r r o r -w i t h -h e l p function in a
window into the "Help" buffer.

Display Name Format
Help on Editor Error
Function Format
HELP-ON-EDITOR-ERROR-COMMAND prefix
Arguments
prefix

Ignored

Return Value
None

HELP TEXT Editor Variable
Specifies the help text to be displayed by the "Help" command. The value of
this variable must be a string, a function of no arguments that returns a string,
or n i l .The global binding of this variable contains the default help text for the
Editor.

Display Name Format
Help Text
Symbol Format
HELP-TEXT

Objects-148

Editor Object Descriptions

HIGHLIGHT-REGION-P Function
Returns T if the argument is a highlight region and N IL otherwise.

Format
HIGHLIGHT-REGION-P object
Arguments
o b je ct

Any LISP object

Return Value
T o r N IL

ILLEGAL OPERATION Command
Signals an Editor error with the message "illegal Operation". This command
is used to disable a command locally within a style or buffer. For example, to
disable "Self Insert" for a particular character, bind the character to "illegal
Operation".

Display Name Format
Illegal Operation
Function Format
ILLEGAL-OPERATION-COMMAND prefix
Arguments
prefix

Ignored

Return Value
None

Objects-149

Editor Object Descriptions

INDENT LISP LINE Command
Adjusts the indentation of the current LISP source line so it is indented appropri
ately in the program context.

Display Name Format
Indent LISP Line
Function Format
INDENT-LISP-LINE-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

INDENT LISP REGION Command
Adjusts the indentation of the LISP text in the region in the Editor variable
"Buffer Select Region", so that the text lines up appropriately in the program
context.

Display Name Format
Indent LISP Region
Function Format
INDENT-LISP-REGION-COMMAND prefix
Arguments
prefix

Ignored

Objects-150

Editor Object Descriptions

Return Value
None

INDENT OUTERMOST FORM Command
Determines the outermost LISP form that surrounds the current buffer point
and indents each line in the form appropriately. An outermost form is one whose
opening parenthesis is in the leftmost column on the screen.

Display Name Format
Indent Outermost Form
Function Format
INDENT-OUTERMOST-FORM-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
Undefined

INFORMATION-AREA-HEIGHT Function
Returns the number of lines occupied by the information area at the bottom of
the screen. You can use this function with s e t f to modify the number of lines,
but you cannot set that number to less than 1. When you alter the height of the
information area, the heights of any anchored windows are adjusted accordingly.

Format
INFORMATION-AREA-HEIGHT
Arguments
None

Objects-151

Editor Object Descriptions

Return Value
The number of lines occupied by the information area

‘ INFORMATION-AREA-OUTPUT-STREAM* Variable
Is bound to an output stream that can be used to write to the information area.
Lines written to the information area are truncated if they are longer than
the screen is wide. A t e r p r i executed to this stream scrolls the lines in the
information area.

INITIALIZE-EDITOR Function
Initializes the Editor without actually entering it. The screen management
system and all standard Editor buffers are initialized. The function is called
automatically when the Editor is first invoked. This function must be called prior
to the use of any window creation or manipulation functions. If, for example, you
want to create Editor windows in an initialization file, you must include a call to
this function in the initialization file.

Format
INITIALIZE-EDITOR
Arguments
None

Return Value
T, if the Editor is actually initialized by this call; or n i l , if it had already been

initialized.

INSERT BUFFER Command
Prompts the user for a buffer name if one is not supplied and inserts the text of
the buffer specified into the current buffer at the buffer point. The point is left at
the end of the inserted text.

Category
iGENERAL-PROMPTING

Objects-152

Editor Object Descriptions

Display Name Format
Insert Buffer
Function Format
INSERT-BUFFER-COMMAND p re fix &OPTIONAL nam e
Arguments
prefix

Ignored
nam e

An Editor buffer

Return Value
The modified point

INSERT-CHARACTER Function
Inserts the specified character at the position of the specified mark. If the
character is a # \ n e w l i n e , the line is broken into two lines.

Format
INSERT-CHARACTER m ark character
Arguments
mark

An Editor mark
character

A character

Return Value
The character

Objects-153

Editor Object Descriptions

INSERT CLOSE PAREN AND MATCH Command
Inserts the last character typed at the current buffer point. If the character is a
list terminator, this command finds and momentarily highlights the matching list
initiator. If the list initiator is not visible in the window, the line containing it is
displayed in the information area, and the matching list initiator is highlighted.
If there is no matching list initiator, an Editor error is signaled. (See " l i s p
S y n t a x ” attribute, especially the values :l i s t - t e r m i n a t o r and l i s t - i n i t i a t o r .)

Display Name Format
Insert Close Paren and Match
Function Format
INSERT-CLOSE-PAREN-AND-MATCH-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
N IL

INSERT FILE Command
Prompts the user for the name of a file if none is specified and inserts the file at
the current buffer point. The point is left at the end of the inserted text.

Category
rGENERAL-PROMPTING
Display Name Format
insert File

O b jects-1 54

Editor Object Descriptions

Function Format
INSERT-FILE-COMMAND p re fix &OPTIONAL file-nam e
Arguments
prefix

Ignored
file-name

A pathname, namestring, or stream

Return Value
The updated buffer point

INSERT-FILE-AT-MARK Function
Inserts the specified file into a buffer at the position of the specified mark. This
function checks to see if there is enough dynamic memory available to load the
file and signals an Editor error if there is not. There is an implied # \ n e w l i n e
character at the end of the file, but not at the beginning.

Format
INSERT-FILE-AT-MARK pathnam e m ark
Arguments
pathnam e

A pathname, namestring, or stream
mark

An Editor mark

Return Value
The mark

Objects-155

Editor Object Descriptions

INSERT-REGION Function
Inserts the specified region at the position of the specified mark. The region text
is copied in the process.

Format
INSERT-REGION m a rk region
Arguments
mark

An Editor mark
region

An Editor region

Return Value
The region

INSERT-STRING Function
Inserts a string at the position of the specified mark. Embedded newline char
acters cause additional Editor lines to be inserted. The string is copied. The
optional start and end arguments allow you to specify a substring to be inserted.

Format
INSERT-STRING m ark string &OPTIONAL sta rt end
Arguments
mark

An Editor mark
string

A string
start

An integer that iB an index into the string. The default is zero.
en d

An integer that is an index into the string. The default is the length of the string.

Objects-156

Editor Object Descriptions

Return Value
The string

INVOKE-HOOK Function
Searches the entire current context, in the reverse of the usual search order, for
occurrences of the variable (that is, the search occurs in the order—the global
definition, the major style of the current buffer, the minor styles in reverse
order, and the local variables of the current buffer). The function then applies
to the specified args arguments all the functions bound to each occurrence of the
specified Editor variable.

Format
INVOKE-HOOK nam e &REST args
Arguments
nam e

An Editor variable specifier
a rg s

The arguments to be passed to the hook function

Return Value
The value that the last hook function returns

KILL ENCLOSING LIST Command
Deletes the list that immediately encloses the argument mark and returns a dis
embodied region that contains the deleted text. The mark defaults to the current
buffer point. If the mark is located within a symbol, the list that immediately
encloses the symbol is deleted. The mark is left at the location where the deleted
text appeared.
If a positive prefix argument n is specified, the next n enclosing lists are deleted
and returned as a disembodied region. If a zero or negative prefix argument is
specified, no action occurs and n i l is returned. If the list to be deleted cannot be
determined because of missing text, no action occurs and n i l is returned.

Display Name Format
Kill Enclosing List

Objects-157

Editor Object Descriptions

Function Format
KILL-ENCLOSING-LIST-COMMAND p re fix &OPTIONAL m ark
Arguments
prefix

An integer o r n i l
mark

An Editor mark that defaults to the current buffer point

Return Value
A d is e m b o d ie d r e g io n o r n il

KILL LIST Command
Deletes the rest of the current line and adds it to the end of the current kill-ring
region if the previous command was in the category k i l l - r i n g ; or, creates a new
kill-ring region. If you supply a positive integer prefix n, the command deletes the
rest of the current line and n—1 lines following the current line; the line following
the last line deleted is appended to the beginning portion of the current line. If
you supply a negative integer prefix -n, the command deletes the portion of the
current line preceding the point and n-1 lines preceding the current line; the rest
of the current line is appended to the line preceding the first line deleted.

C ategory

:KILL-RING
Display Name Format
Kill Line
Function Format
KILL-LINE-COMMAND prefix
Arguments
prefix

An integer or n i l

Objects-158

Editor Object Descriptions

Return Value
Undefined

KILL NEXT FORM Command
Deletes the LISP form immediately after the mark at the current parenthesis
nesting level and returns a disembodied region that contains the deleted text.
The mark defaults to the current buffer point. If a positive prefix argument n is
specified, then the next n LISP objects at the current parenthesis nesting level
are deleted and returned as a disembodied region. If no next form is found within
the innermost enclosing list or if a negative prefix argument is supplied, no action
occurs and nil is returned.

Display Name Format
Kill Next Form
Function Format
KILL-NEXT-FORM-COMMAND p re fix & OPTIONAL m a rk
Arguments
prefix

A positive integer or n i l
mark

An Editor mark that defaults to the current buffer point

Return Value
A d is e m b o d ie d r e g io n o r n il

KILL PARAGRAPH Command
Deletes the rest of the current paragraph and adds it to the end of the current

kill-ring region if the previous command was in the category :kill -ring ; or,

creates a new kill-ring region. If a prefix argument n is supplied, the command
deletes the rest of the current paragraph and the next n—1 paragraphs.

Objects-159

Editor Object Descriptions

Category
:KILL-RING
Display Name Format
Kill Paragraph
Function Format
KILL-PARAGRAPH-COMMAND p refix
Arguments
prefix

Positive integer or n i l

Return Value
Undefined

KILL PREVIOUS FORM Command
Deletes the LISP form immediately before the mark at the current parenthesis
nesting level and returns a disembodied region that contains the deleted text.
The mark defaults to the current buffer point. If a positive prefix argument n
is specified, then the previous n LISP objects at the current parenthesis nesting
level are deleted and returned as a disembodied region. If no previous form is
found within the innermost enclosing list or if a negative prefix argument is
supplied, no action occurs and n i l is returned.

Display Name Format
Kill Previous Form
Function Format
KILL-PREVIOUS-FORM-COMMAND p re fix & OPTIONAL m ark

O b jects-1 60

Editor Object Descriptions

Arguments
prefix

A positive integer or n i l
mark

An Editor mark that defaults to the current buffer point

Return Value
A disembodied region or n i l

KILL REGION Command
Deletes a region and adds it to the end of the current kill-ring region if the
previous command was in the category :k i l l -r i n g ; or, creates a new kill-ring
region. If the region is not supplied, it defaults to the region between the buffer
select mark and the current buffer point.

Category
:KILL-RING

Display Name Format
Kill Region
Function Format
KILL-REGION-COMMAND prefix &OPTIONAL region
Arguments
prefix

Ignored
region

An Editor region that defaults to the buffer-select-region

Return Value
Undefined

Objects-161

Editor Object Descriptions

KILL REST OF LIST Command
Deletes the part of the list that immediately follows the argument mark and
returns a disembodied region that contains the deleted text. The mark defaults
to the current buffer point. If the mark is not in a list or if the list terminator
cannot be found, no action occurs and N I L is returned.

Display Name Format
Kill Rest of List
Function Format
KILL-REST-OF-LIST-COMMAND prefix &OPTIONAL m ark
Arguments
prefix

Ignored
mark
An Editor mark that defaults to the current buffer point

Return Value
A d is e m b o d ie d r e g io n o r n il

* LAST-CHARACTER-TYPED* Variable
Is bound to the last character typed by the user.

LAST-LINE-P Function
Is a p r e d i c a t e t h a t r e t u r n s t i f t h e s p e c i f i e d m a r k p o i n t s t o t h e l a s t l i n e i n a
b u ff e r o r a d is e m b o d ie d r e g io n .

Format
LAST-LINE-P m ark

O b jects-1 62

Editor Object Descriptions

Arguments
mark

An Editor mark

Return Value
T o r N IL

LAST SEARCH DIRECTION Editor Variable
Indicates the direction of the most recent search by means of a keyword having
the value of either :f o r w a r d or b a c k w a r d .

Display Name Format
Last Search Direction

Symbol Format
LAST-SEARCH-DIRECTION

LAST SEARCH PATTERN Editor Variable
Specifies the search pattern last used with the search commands.

Display Name Format
Last Search Pattern
Symbol Format
LAST-SEARCH-PATTERN

Objects—163

Editor Object Descriptions

LAST SEARCH STRING Editor Variable
Specifies the string last used with the search commands.

Display Name Format
Last Search String

Symbol Format
LAST-SEARCH-STRING

LINE-BUFFER Function
Returns the buffer associated with the Editor line. This function returns N I L if
the line is not associated with any buffer.

Format
LINE-BUFFER line
Arguments
line

An Editor line

Return Value
An Editor buffer or n i l

LINE-CHARACTER Function
Returns the character in the text of the specified line at the position indicated by
the specified index (the first character is specified by o, the second by l, and so
on). The function returns n i l if there is no character at that position. It returns
the # \ n e w l i n e character if the specified position is at the end of the line. You can
use this function with s e t f to change the character at that position.

Format
LINE-CHARACTER line index

Objects-164

Editor Object Descriptions

Arguments
line

An Editor line
Index

A fixnum

Return Value
A c h a r a c te r o r n il

LINE-END Function
Changes the specified mark so it points to the end of the line.

Format
LINE-END m ark &OPTIONAL line
Arguments
mark

An Editor mark
line

An Editor line that defaults to the line that the mark points into

Return Value
The modified mark

LINE-LENGTH Function
Returns an integer that is the number of characters contained in the Editor line.
The line break is not included.

Format
LINE-LENGTH line

Objects-165

Editor Object Descriptions

Arguments
line
An Editor line

Return Value
An integer

LINE-NEXT Function
Returns the line following the specified line.

Format
LINE-NEXT line
Arguments
line

An Editor line

Return Value
An Editor line, or n i l if there is no following line

LINE-OFFSET Function
Changes the specified mark so that it points n lines after the line it currently
points into (or n lines before, if n is negative). The function attempts to have
the mark in the new line point to the same position it pointed to in the old line.
If you do not want the mark to point to that position, you can specify another
position in the new line by supplying a value for the index argument.
If there are not enough characters in the new fine for a specified or defaulted
position to exist, the mark is positioned at the end of the line. If there are not
enough lines after (or before) the mark to satisfy the n argument, the mark is not
modified, and NIL is returned.

Format
LINE-OFFSET m a rk n &OPTIONAL index

O b jects—166

Editor Object Descriptions

Arguments
mark

An Editor mark
n

A fixnum
index

A fixnum that defaults to the character position of mark

Return Value
The modified mark, or n i l

LINE-PREVIOUS Function
Returns the line preceding the specified line.

Format
LINE-PREVIOUS line
Arguments
line

An Editor line

Return Value
A line, o r n i l i f th e r e is n o p r e c e d in g lin e

LINE-START Function
Changes the specified mark so that it points to the beginning of the line.

Format
LINE-START m ark &OPTIONAL line
Arguments
mark

An Editor mark

Objects—167

Editor Object Descriptions
line

An Editor line that defaults to the line that the mark points into

Return Value
The modified mark

LINE-STRING Function
Returns a character string that is the text contained in the Editor line. You can
use l i n e -s t r i n g with the s e t f macro to modify the text contained in an Editor
line. In particular, if you do any destructive operations on the string (for example,
using the l i s p n s t r i n g -u p c a s e function to make a portion of the text uppercase),
you must use s e t f to have the change appropriately reflected.

Format
LINE-STRING line
Arguments
line

An Editor line

Return Value
A string

LINE-TO-REGION Function
Returns a region consisting of either the specified line if the argument is a line or
the line that the mark points into if the argument is a mark.

Format
LINE-TO-REGION line-or-m ark
Arguments
line-or-mark

An Editor line or an Editor mark

Objecls-168

Editor Object Descriptions

Return Value
A region containing the specified line

LINE TO TOP OF WINDOW Command
Moves the line that the buffer point points into, so that it is the first displayed
line in the current window.

Display Name Format
Line to Top of Window
Function Format
LINE-TO-TOP-OF-WINDOW-COMMAND prefix &OPTIONAL m ark w indow
Arguments
prefix

Ignored
mark

A mark pointing into the line to go to the top of the window. The default is the
current buffer point.
window

The window in which the specified line is to be the top line. The default is the
current window.

Return Value
None

LINEP Function
Is a predicate that returns T if object is an Editor line.

Format
LINEP object

Objects-169

Editor Object Descriptions

Arguments
o b je ct
A ny L IS P object

Return Value
T o r N IL

LINES-RELATED-P Function
R etu rns t if the tw o specified lin es are in eith er the sam e buffer or the sam e
d isem b od ied region.

Format
LINES-RELATED-P lin e l \ine2
Arguments
lin el

An Editor line
Iine2

Another Editor line

Return Value
T o r N IL

LINE/= Function
Returns T if linel and line2 are not the same. The two lines need not be in the
same buffer.

Format
LINE/= linel Iine2
Arguments
lin el

An Editor line

Objects-170

Editor Object Descriptions
Une2

Another Editor line

Return Value
T o r N IL

LINE< Function
Returns t if linel precedes line2. The two lines must be in the same buffer.

Format
LINE< lin e l Iine2
Arguments
lin el

An Editor line
Ilne2

Another Editor line

Return Value
T o r N IL

LINE<= Function
Returns t if linel precedes line2 or is the same line as line2. The two lines must
be in the same buffer.

Format
LINE<= lin e l Iine2
Arguments
lin el

An Editor line
Ilne2

Another Editor line

Objects-171

Editor Object Descriptions

Return Value
T o r N IL

LINE= Function
Returns T if linel and line2 are the same line. The two lines do not have to be in
the same buffer.

Format
LINE= lin e l \ine2
Arguments
lin el

An Editor line
Ilne2

Another Editor line

Return Value
T o r N IL

LINE> Function
Returns T if linel follows line2. The two lines must be in the same buffer.

Format
LINE> lin e l \ine2
Arguments
lin el

An Editor line
Une2

Another Editor line

Objects-172

Editor Object Descriptions

Return Value
T o r N IL

LINE>= Function
Returns T if linel follows line2 or if they are the same line. The two lines must
be in the same buffer.

Format
LINE>= lin e l Iine2
Arguments
linel
An Editor line
Ilne2

Another Editor line

Return Value
T o r N IL

LISP COMMENT COLUMN Editor Variable
Is bound in "VAX l i s p " style to an integer that indicates the column in which a
LISP comment begins on a line. This Editor variable is used by the indentation
commands as well as by the "Move to l i s p Comment" command. By default, LISP
comments begin at column 49. You can change the LISP comment column by
using the s e t f macro.

Display Name Format
LISP Comment Column
Symbol Format
LISP-COMMENT-COLUMN

Objects-173

Editor Object Descriptions

LISP EVALUATION RESULT Editor Variable
Is bound to a list of the values returned when a LISP region is evaluated in the
Editor.

Display Name Format
LISP Evaluation Result
Symbol Format
LISP-EVALUATION-RESULT

LISP SYNTAX Attribute
Used in "VAX l i s p " style to determine the structure of the LISP source being
edited. The value of this attribute for a given character defines the role (if any)
that character plays in the syntax of LISP. The table below lists the values this
attribute can take and shows a sample character for each attribute value. You
can modify the value of this attribute for a given character by using the SETF
macro on a c h a r a c t e r -a t t r i b u t e form.

Display Name Format
LISP S yn ta x

Symbol Format
LISP-SYNTAX
Table Objects-1: LISP Syntax Attribute Values
Value

Character( a )

D escription

:LIST-INITIATOR

#\<

A character that signifies the beginning of a
list

:LIST-TERMINATOR

#\>

A character that signifies the end of a list

:COMMENT-DELIMITER

#\;

A character that signifies the beginning of a
comment

(continued on next page)

Objects-174

Editor Object Descriptions

Table Objects-i (Cont.):

LISP Syntax Attribute Values

Value

Characterf s )

D escription

:STRING-DELIMITER

#\"

A character that delimits the beginning and
end of a string

:SINGLE-ESCAPE

#\\

A character used as a single escape character

:MULTIPLE-ESCAPE

#\l

A character used as a multiple escape
character

:WORD-DELIMITER

# \space and
others

A character used to separate words

:READ-MACRO

A macro character that the LISP READ
function accepts

:CONSTITUENT

#\A and others

A character used as a constituent character

You can use the l o c a t e -a t t r i b u t e function in conjunction with the "l i s p
Syntax" attribute to find an instance of a particular LISP syntactic element.
For example, the following function call finds the first occurrence of a string
delimiter beyond the current buffer point:
(locate-attribute (current-buffer-point)
"LISP Syntax")
:test #' (lambda (x) (eq x :string-delimiter))))

NOTE

Characters whose "l i s p Syntax" attribute value is :Li s t - i n i t i a t o r ,
:LIST-TERMINATOR, :COMMENT-DELIMITER, :STRING-DELIMITER, and
:r e a d -m a c r o are also considered to delimit words, in addition to the
characters whose value is :w o r d -d e l i m i t e r .

LIST BUFFERS Command
Causes a list of the current buffers to be displayed in the Help window.

Display Name Format
List Buffers
Function Format
LIST-BUFFERS-COMMAND p re fix
Arguments
prefix

Ignored

Objects-175

Editor Object Descriptions

Return Value
N IL

LIST KEY BINDINGS Command
Prompts the user for a context in which to search for key bindings. If none is
specified, all the currently visible bindings are used. The command formats and
displays a list that includes the key sequence, the associated command name, and
the context of the binding. Key sequences that are bound to the "Self insert"
command are not included in the list.

Category
:GENERAL-PROMPTING
Display Name Format
List Key Bindings
Function Format
LIST-KEY-BINDINGS-COMMAND p re fix &OPTIONAL context
Arguments
prefix

Ignored
con text

The context in which to search for bindings. If the value of the context argument
is n i l , the user is prompted for a context; if the value is T, the entire visible set
of bindings is used.

Return Value
None

Objects-176

Editor Object Descriptions

LOCATE-ATTRIBUTE Function
Locates a character in a region or string whose value for the specified attribute
satisfies the given test.
If the argument you specify is a mark, the function begins searching at the mark
and proceeds in the direction specified by the :d i r e c t i o n keyword (:f o r w a r d ,
the default, or :b a c k w a r d ). The search continues until: (1) a suitable character
is found; (2) there are no more characters; (3) the mark specified by the :l i m i t
keyword is reached. If a character is found, the mark is updated to point to that
character. If no character is found, the function returns n i l .
If the argument you specify is a string, the string is searched starting at the
beginning of the string or at the position indicated by : s t a r t if the : s t a r t
keyword is specified. If a character is found that satisfies the test, the function
returns the position of the character in the string. If no suitable character is
found, the function returns n i l .

Format
LOCATE-ATTRIBUTE m ark-or-string attribute & KEY :TEST :CONTEXT
:DIRECTION :LIMIT :START
:END
Arguments
mark-or-string

Either a mark that specifies the starting position or a string to be searched
attribute

An attribute specifier
:TEST
A predicate function of one argument used to test the attribute value of each
character. iTEST returns non-NiL if the argument that specifies the attribute
value of the character matches a character during the search. The default is
I'p l o s p ,which is often used with a 0 or l value for a character attribute. The
attribute value may be any LISP object. The test function must accept objects of
the appropriate type.
:CONTEXT
An Editor context specifier for the character attribute. The default is the current
context.
:DIRECTION
The direction to scan for a character satisfying the attribute test. Values can be
:f o r w a r d or :b a c k w a r d .The default is :f o r w a r d .

Objects-177

Editor Object Descriptions
:LIMIT
Used only when you specify a mark for the mark-or-string argument. :l i m i t
must be a mark that points into the same buffer or disembodied region as the
mark you specify for the mark-or-string argument. If no character is found
that satisfies the test before the : l i m i t mark is reached, the search fails. (The
character pointed to by :l i m i t is included in the search.) If the search direction
is forward, the limit mark must be located after the starting mark; otherwise, the
limit mark must be located before the starting mark.
:START
Used only when you specify a string for the mark-or-string argument. : start
is an integer that specifies the character position in the string where the search
begins. The default value for : start is o. The : start argument is ignored if you
specify a mark for the mark-or-string argument.
:END
Used only when you specify a string for the mark-or-string argument. :END is
an integer that specifies the character position in the string where the search
ends. The default value for e n d is the length of the string. The :e n d argument
is ignored if you specify a mark for the mark-or-string argument.

Return Value
Three values:
1. The modified mark, if the argument for mark-or-string is a mark and the
search is successful; or, if the mark-or-string argument specified is a string,
an integer that represents the character’
s position in the string; or n i l if no
character is found (the search is unsuccessful).
2. The character at the position of the mark.
3. The value of the attribute for that character.

LOCATE-PATTERN Function
Searches for a text string that matches the specified search pattern. You create
search patterns by means of the m a k e -s e a r c h -p a t t e r n function. The mark is
changed so that it points to the beginning of the located text.

Format
LOCATE-PATTERN m ark search-pattern
Arguments
mark

An Editor mark

Objects-178

Editor Object Descriptions
search-pattern

An Editor search pattern

Return Value
The number of characters matched, or n i l

MAJOR STYLE ACTIVATION HOOK Editor Variable
Specifies a hook function that is called whenever a major style is activated in a
buffer. The function is called with two arguments, the style and the buffer.

Display Name Format
Major Style Activation Hook

Symbol Format
MAJOR-STYLE-ACTIVATION-HOOK

MAKE-BUFFER Function
Takes a name specifier and creates a buffer of the specified name. The calling of
this function causes the "Buffer Creation Hook" to be invoked. If a buffer that
has the specified name already exists, it is returned.

Format
MAKE-BUFFER buffer-nam e &KEY :DOCUMENTATION :MAJOR-STYLE
:MINOR-STYLES :VARIABLES :OBJECT
:TYPE :PERMANENT
Arguments
buffer-name

The name for the new buffer. This can be specified as either a symbol or a list of
a symbol with the keyword :DISPLa y -n a m e and a string; that is,
nam e

| (n a m e :DISPLAY-NAME string)

:DOCUMENTATION

A string used as the documentation string for the buffer.

Objects-179

Editor Object Descriptions
■.MAJOR-STYLE
An Editor style that is to be the major style of the buffer. This defaults to the
global value of the "Default Major style" Editor variable.
:MINOR-STYLES
A list of Editor styles that are to be the minor styles of the buffer. This defaults
to the global value of the "Default Minor styles" Editor buffer.
VARIABLES
A list of Editor variables that are to be bound in the buffer. This defaults to the
global value of the "Default Buffer Variables" Editor variable.
:OBJECT
The object to be edited in the buffer. This can be a pathname, a symbol, or a list
that is a form acceptable to the s e t f macro.
:TYPE
The type of the object being edited. This can be specified only if the object is a
symbol. The possible values are : f u n c t i o n (the default) and :v a l u e .
:PERMANENT
If non-NiL, the buffer is created as a permanent buffer. A permanent buffer
cannot be deleted with d e l e t e - b u f f e r , it remains in the Editor across a suspend/resume cycle, and i t remains if you exit the Editor. The default is n i l .

Return Value
Two values:
1. An Editor buffer
2.

t , if

t h is is a n e w b u ffe r; n i l , i f th e b u ff e r a lr e a d y e x is t e d

MAKE-COMMAND Function
Is used to turn an existing LISP function into an Editor command. The name op
tions to the m a k e - c o m m a n d function are the same as those for the d e f i n e - c o m m a n d
macro and can include a display name, and a category or list of categories.
The supplied function must be a function of at least one argument. The prefix
argument is passed when the command is executed as a function.

Format
MAKE-COMMAND nam e function &OPTIONAL docum entation
Arguments
nam e

A command name specifier

Objects-180

Editor Object Descriptions
function

A LISP function that is to become an Editor command
docum entation

The documentation string that will be used to describe the Editor command (not
the function documentation)

Return Value
The function

MAKE-EDITOR-STREAM-FROM-REGION Function
Takes an Editor region and returns an Editor input stream.

Format
MAKE-EDITOR-STREAM-FROM-REGION region
Arguments
region

An Editor region

Return Value
An input stream

MAKE-EDITOR-STREAM-TO-MARK Function
Returns an Editor output stream that causes all output to be inserted at the
specified mark.

Format
MAKE-EDITOR-STREAM-TO-MARK m ark
Arguments
mark

An Editor mark

Objects-181

Editor Object Descriptions

Return Value
An output stream

MAKE-EMPTY-REGION Function
Returns a new disembodied Editor region with permanent marks pointing into
a line with no characters. The starting mark is right-inserting, and the ending
mark is left-inserting.

Format
MAKE-EMPTY-REGION
Arguments
None

Return Value
An Editor region

MAKE-HIGHLIGHT-REGION Function
Returns a new highlight region. Whenever any of the text in the region is visible
in a window, the display of the text is given the specified video rendition. The
rendition can be specified as a keyword or list of keywords. The possible values
are :BOLD, :b l i n k , :r e v e r s e , and :u n d e r l i n e .
When specifying highlight regions, you must be aware of the background ren
dition of the window where the region will be visible. For example, specifying
reverse video when the window is already in reverse video will have no apparent
effect.
The set and complement arguments let you adjust the rendition of the display
so that you can achieve the desired rendition. The attributes specified in the
set argument will always be turned on when visible. The attributes specified by
the complement argument will complement the existing display values, including
any that were turned on by the set argument. So to turn off reverse video in
the highlight region, you must specify :r e v e r s e in both the set and complement
arguments.
The highlight region can also be used as a normal region by any Editor function
that takes a region as an argument.

Objects-182

Editor Object Descriptions

Format
MAKE-HIGHLIGHT-REGION start end &OPTIONAL s e t com plem ent
Arguments
start

An Editor mark that indicates the beginning of the region
en d

An Editor mark that indicates the end of the region
set

A keyword or list of keywords specifying the video renditions to be turned on in
the display when visible. The default is n i l .
com plem en t

A keyword or list of keywords specifying the video renditions to be complemented
in the display when visible. The default is n i l .

MAKE-MARK Function
Returns a new mark that points to the specified line at the position specified by
the index argument.

Format
MAKE-MARK line index &OPTIONAL m ark-type
Arguments
line

An Editor line
Index

An integer in the range of 0 to the length of the line
mark-type

The type of the mark to create— :l e f t -i n s e r t i n g , :r i g h t - i n s e r t i n g , or
:t e m p o r a r y .The default is : t e m p o r a r y .

Return Value
A new Editor mark

Objects-183

Editor Object Descriptions

MAKE-REGION Function
Creates an Editor region that starts and ends at the specified marks. Both marks
must be in the same buffer or disembodied region.

Format
MAKE-REGION start-m ark end-m ark
Arguments
start-mark

A mark for defining the beginning of a region
end-mark

A mark for defining the end of a region

Return Value
A new region

MAKE-RING Function
Creates a ring buffer of the size specified by the integer argument.

Format
MAKE-RING integer &OPTIONAL delete-function
Arguments
Integer

A positive integer, the maximum size of the ring
delete-function

A function called any time an item is deleted from the ring, either by r i n g p u s h or by the application of s e t f to r i n g -r e f .The function is called with two
arguments—the item being deleted and the ring. The default is n i l .

Return Value
The new ring

Objects-184

Editor Object Descriptions

MAKE-SEARCH-PATTERN Function
Creates a new search pattern you can use in subsequent searching operations.

Format
MAKE-SEARCH-PATTERN kind direction string &OPTIONAL reuse-pattern
Arguments
kind

A search pattern type, either :c a s e -s e n s i t i v e or : c a s e -i n s e n s i t i v e
direction

A direction to search in—either :FORWARD or : b a c k w a r d
string

The string to be searched for
reuse-pattern

A previously computed search pattern that will be modified destructively to create
the new pattern

Return Value
A new search pattern

MAKE-STRING-TABLE Function
R etu rns a new strin g table that h as no en tries

Format
MAKE-STRING-TABLE
Arguments
None

Return Value
An empty string table

Objects-185

Editor Object Descriptions

MAKE-STYLE Macro
Creates a new Editor style. The style will have no attribute, variable, or com
mand bindings. If there is already a style of the specified name, the new style
(with no bindings) will replace the old one. Note that any bindings present in the
old style are lost.

Format
MAKE-STYLE nam e &OPTIONAL docum entation
&KEY :ACTIVATION-HOOK :DEACTIVATION-HOOK
Arguments
nam e

A symbol that names the style or a list of a symbol, the keyword :DISPLAY-n a m e ,
and a string that will become the style’
s display name
docum entation

A documentation string for the style
:ACTIVATION-HOOK
A function that will be invoked whenever this style is activated in a buffer. The
function is called with two arguments—the style and the buffer that the style is
activated in.
:DE ACTIVATION-HOOK
A function that will be invoked whenever the style is made inactive in a buffer.
The function is called with two arguments—the style and the buffer that the style
is activated in.

Return Value
The new style

MAKE-WINDOW Function
Takes a buffer or a mark and returns a new window. If the argument is a mark,
the window opens into the buffer that contains the mark, and the display starts
with the line that the mark points into. If the argument is a buffer, the window
opens into that buffer, and the display starts with the line pointed to by the buffer
point. The window is not displayed automatically.
The calling of this function invokes the "Window Creation Hook".

Objects-186

Editor Object Descriptions

Format
MAKE-WINDOW buffer-or-m ark &KEY :HEIGHT :WIDTH :DISPLAY-ROW
:DISPLAY-COLUMN :TYPE :LINES-WRAP
:LABEL
Arguments
buffer-or-mark

An Editor buffer or mark
:HEIGHT
The number of rows to be contained in the window. The minimum value is one.
This value is significant only if the window type is :f l o a t i n g .
:WIDTH
The number of characters that can be displayed horizontally in a window. The
minimum value is two. The maximum value (and default) is the width of the
available display area. This value has significance only if the window type is

:FLOATING.

:DISPLAY-ROW
The screen row (y position) at which to start displaying the text of the win
dow. The top row is 1. This value has significance only if the window type is
:FLOATING.

:DISPLAY-COLUMN
The screen column (x position) at which to start displaying the text of the window.
The left-hand column is 1. This value has significance only if the window type is

:FLOATING.

:TYPE
The display type of the window. Can be either :a n c h o r e d or :f l o a t i n g . The
default is the value of the Editor variable "Default window Type".
:LINES-WRAP
If T, specifies that displayed lines are continued on the next line of the display if
the length of the Editor line exceeds the width of the window. The default is the
value of the Editor variable "Default Window Lines Wrap".
:LABEL
A string, a function that returns a string, or n i l . If the value is a string or a
function that returns a string, the string is used as the label for the window.
Only as much of the string as will fit on the specified side will be displayed. An
empty string ("") means that the window is unlabeled. A value of n i l means that
the window is not bordered. The default is the value of "Default window Label".

Objects-187

Editor Object Descriptions

Return Value
The new window

MAP-BINDINGS Function
Calls, with the following three arguments, the specified function for each key
sequence that has a binding in the specified context:
1. The sequence of characters bound
2. The command function the sequence is bound to
3. The context specification in which the binding was found. If an optional
context is specified, only the key bindings in that context are mapped. If no
context is provided, the map is done over all the currently visible bindings.

Format
MAP-BINDINGS function &OPTIONAL context
Arguments
function

A function of three arguments
con text

An optional context specification. The default is n i l .
R eturn Value
NIL

MAP-BUFFERS Function
Applies the specified function to each buffer in the Editor along with any addi
tional arguments supplied. The specified function must be a function of at least
one argument. The first argument will always be an Editor buffer object.

Format
MAP-BUFFERS function &REST args

Objects-188

Editor Object Descriptions

Arguments
function
A function to be called for each buffer. The function must accept at least one
argument, a buffer.
args
Any additional arguments that must be passed to the specified function on each
call

Return Value
N IL

MAP-STRINGS Function
Calls the specified function for each entry in the specified string table. That
function is called with two arguments—the string that is the key of the entry and
the value of the entry.

Format
MAP-STRINGS function table
Arguments
function

A function of two arguments
table

A string table

Return Value
NIL

MARK-CHARPOS Function
Returns the number of characters in the line of text preceding the specified mark.

Format
MARK-CHARPOS m ark

Objects-189

Editor Object Descriptions

Arguments
mark

An Editor mark

Return Value
A nonnegative fixnum

MARK-COLUMN Function
Returns the column (position n) at which the specified mark would be displayed,
based on the "Print Representation" attribute of each character, if the screen
were wide enough. This number is often different from the result of m a r k -c h a r p o s
because some characters take up more than one column when they are displayed.
For example, tab characters usually are not displayed as single blank characters.
The first character of a line is at display position 1.

Format
MARK-COLUMN m ark
Arguments
mark

An Editor mark

Return Value
A positive fixnum

MARK-LINE Function
Returns the line that the specified mark points into.

Format
MARK-LINE m ark
Arguments
mark

An Editor mark

Objects-190

Editor Object Descriptions

Return Value
An Editor line

MARK-TYPE Function
Returns the type of the specified mark. You can use this function with s e t f to
change the type of a mark.

Format
MARK-TYPE m ark
Arguments
mark

An Editor mark

Return Value
The type of the specified mark— :l e f t -i n s e r t i n g , :r i g h t - i n s e r t i n g , or
:TEMPORARY.

MARK-VISIBLE-P Function
Returns T if the mark position lies within the text contained in the window;
returns n i l if it is not.

Format
MARK-VISIBLE-P m ark window
Arguments
mark

An Editor mark
w indow

An Editor window

Objects—191

Editor Object Descriptions

Return Value
T or NIL

MARK-WINDOW-POSITION Function
Returns n i l if the specified mark position does not lie within the text contained
in the window; returns multiple values of the column and row positions of the
specified mark if it is visible. The upper-left comer position of a window is
specified as 1,1.

Format
MARK-WINDOW-POSITION m ark w indow
Arguments
mark

An Editor mark
window

An Editor window

Return Value
Either n i l or the column and row position at which the mark is displayed

MARKP Function
Returns t if the argument is a mark; returns n i l if it is not.

Format
MARKP object
Arguments
o b je ct

Any LISP object

Objects-192

Editor Object Descriptions

Return Value
T or NIL

MARK/= Function
Returns T if markl and mark2 point to different positions; returns n i l otherwise.
The marks can point into different buffers.

Format
MARK/= m a rk l m ark2
Arguments
m arkl

An Editor mark
mark2

Another Editor mark

Return Value
T or NIL

MARK< Function
Returns T if markl points to a character preceding mark2\ returns n i l otherwise.
An error occurs if the marks point to different buffers.

Format
MARK< m a rk l m ark2
Arguments
m arkl

An Editor mark
mark2

Another Editor mark

Objects-193

Editor Object Descriptions

Return Value
T o r N IL

MARK<= Function
Returns T if markl points to a character preceding mark2, or if they point to
the same position; returns n i l otherwise. An error occurs if the marks point to
different buffers.

Format
MARK<= m a rk l m ark2
Arguments
m arkl

An Editor mark
mark2

Another Editor mark

Return Value
T o r N IL

MARK= Function
Returns T if markl and mark2 point to the same position; returns n i l otherwise.
The marks can point into different buffers.

Format
MARK= m a rk l m ark2
Arguments
m arkl

An Editor mark
mark2

Another Editor mark

Objects-194

Editor Object Descriptions

Return Value
T o r NIL

MARK> Function
Returns t if markl points to a character following mark2\ returns n i l otherwise.
An error occurs if the marks point to different buffers.

Format
MARK> m a rk l m ark2
Arguments
m arkl

An Editor mark
mark2

Another Editor mark

Return Value
T o r N IL

MARK>= Function
Returns T if markl points to a character following mark2, or if they point to
the same position; returns n i l otherwise. An error occurs if the marks point to
different buffers.

Format
MARK>= m a rk l m ark2
Arguments
m arkl

An Editor mark
mark2

Another Editor mark

Objects-195

Editor Object Descriptions

Return Value
T or NIL

MAYBE RESET SELECT AT POINTER Command
Removes a previously set select mark, and thus a select region, if the current
buffer point, the buffer select mark, and the pointer all indicate the same text
position. If any of these conditions is not met, this command takes no action.

Display Name Format
Maybe Reset Select at Pointer
Function Format
MAYBE-RESET-SELECT-AT-POINTER-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

MINOR STYLE ACTIVATION HOOK Editor Variable
Specifies a hook function that is called whenever a minor style is activated in a
buffer. The function is called with two arguments, the style and the buffer.

Display Name Format
Minor Style Activation Hook
Symbol Format
MINOR-STYLE-ACTIVATION-HOOK

Objects-196

Editor Object Descriptions

MOVE-MARK Function
Changes markl so that it points to the same position as mark2. The marks do
not have to point into the same buffer or disembodied region.

Format
MOVE-MARK m a rk l m ark2
Arguments
m arkl

An Editor mark
mark2

Another Editor mark

Return Value
The updated markl

MOVE-MARK-AFTER Function
Changes the specified mark so that it points to the character following its current
position. If mark points to the last character in the buffer, it is not modified, and
n i l is returned.

Format
MOVE-MARK-AFTER m ark
Arguments
mark

An Editor mark

Return Value
The modified mark or n i l

Objects-197

Editor Object Descriptions

MOVE-MARK-BEFORE Function
Changes the mark so that it points to the character preceding its current position.
If the mark points to the first character in the buffer, it is not modified, and n i l
is returned.

Format
MOVE-MARK-BEFORE m ark
Arguments
mark

An Editor mark

Return Value
The modified mark, or n i l

MOVE-MARK-TO-POSITION Function
Changes the specified mark so that it points into the specified line at the charac
ter position indicated by the specified integer index.

Format
MOVE-MARK-TO-POSITION m ark index &OPTIONAL line
Arguments
mark

An Editor mark
Index

A nonnegative fixnum less than or equal to the length of the line
line

An Editor line that defaults to the line that the mark points into

Return Value
The modified mark

Objects-198

Editor Object Descriptions

MOVE POINT AND SELECT REGION Command
Moves the current buffer point to the position indicated by the pointer. In addi
tion, if the previous command executed was in the category :MOVe -t o -p o i n t e r
and there was no select region, this command sets a buffer select mark and
establishes a select region before moving the buffer point.

Display Name Format
Move Point and Select Region
Function Format
MOVE-POINT-AND-SELECT-REGION-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

MOVE POINT TO POINTER Command
Moves the current buffer point to the position indicated by the pointer. If the
pointer is beyond the end of a line, the buffer point is moved to the end of that
line. If the pointer is beyond the end of the buffer region, the buffer point is
moved to the end of the buffer region.

Category
:MOVE-TO-POINTER
Display Name Format
Move Point to Pointer

Objects-199

Editor Object Descriptions

Function Format
MOVE-POINT-TO-POINTER-COMMAND prefix
Arguments
prefix

Ignored

Return Value
The modified buffer point

MOVE TO LISP COMMENT Command
Moves the cursor to the comment part of the current line. If there is a comment
on the current line, the cursor is moved to the comment delimiter. If there is no
comment delimiter on the current line, blanks are inserted between the end of
any executable LISP code on the line and the LISP comment column, a comment
delimiter and a space are inserted at the LISP comment column, and the cursor is
moved to the end of the line. If the length of executable code in the line does not
allow for a clear separation of the executable code from the comment, a number
of spaces are inserted before the comment delimiter.
This command makes use of the "l i s p Comment Column" Editor variable and
should only be used if that variable is bound in the current context.

D isp la y N a m e Form at

Move to LISP Comment
Function Format
MOVE-TO-LISP-COMMENT-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
The new buffer point

Objects-200

Editor Object Descriptions

MOVE-WINDOW Function
Moves the displayed position of a window so that the upper left corner of the
text area is at the specified row and column. If the window is visible, the display
is altered immediately. If the window is not currently visible, it appears at the
specified position when it is next shown (unless it is an anchored window being
treated automatically).

Format
MOVE-WINDOW w indow row colum n
Arguments
window

An Editor window
row

The row where the text display of the window should appear. The top row of the
screen is 1.
colum n

The column where the text display of the window should appear. The left-hand
column of the screen is 1.

Return Value
The window

NEW LINE Command
Breaks a line at the current buffer point. The resulting position of the buffer
point is the beginning of the new line. If you specify a prefix argument, n, the
command creates n lines.

Display Name Format
New Line
Function Format
NEW-LINE-COMMAND prefix

Objects-201

Editor Object Descriptions

Arguments
prefix

A positive f i x n u m or n i l

Return Value
The updated buffer point mark

NEW LISP LINE Command
Creates a new line beginning at a column appropriate to the current indentation
for LISP code. The point is moved to the position following the new line and
indentation.

Display Name Format
New LISP Line
Function Format
NEW-LISP-LINE-COMMAND prefix
Arguments
prefix
Ignored

Return Value
The new buffer point

NEXT-CHARACTER Function
Returns the character immediately following the position of the mark. If there is
no following character, the function returns n i l . Y o u can use this function with
the s e t f macro to change the character following the mark.

Format
NEXT-CHARACTER m a rk

Objects-202

Editor Object Descriptions

Arguments
mark

An Editor mark

Return Value
A character, or n i l if there is n o following character

NEXT FORM Command
Moves the current buffer point forward by the number of forms specified with
the prefix argument, within the current parenthesis nesting level. The current
buffer point is moved to the location immediately following the specified number
of forms, and the new buffer point is returned. If a negative prefix argument is
specified, the current buffer point is moved backward past the specified number
of forms.
If the end of the current buffer or an outermost form is found before the end
of the specified number of forms is reached, the Editor displays a message and
returns n i l , and the point is not moved. If there are fewer forms at the current
nesting level than the number specified by the prefix argument, the point is
placed immediately before the list terminator character of the innermost list that
encloses the point, and n i l is returned.

Display Name Format
Next Form
Function Format
NEXT-FORM-COMMAND p refix
Arguments
prefix

Integer or n i l

Return Value
The new buffer point or n i l
NOTE

Do not try to execute the "Next Form" command when the buffer point
is located within a string or a multiple escape sequence. The results of
a "Next Form" command in these circumstances can be incorrect.

Objects-203

Editor Object Descriptions

NEXT LINE Command
Moves the point down one line. The relative horizontal character position (not
the displayed position) of the point in the old line is maintained unless the end of
the new line is to the left of that position. In such a case, the point will be at the
end of the new line. If you specify an integer prefix argument, the point is moved
down the number of lines indicated (or up, if the prefix is negative).

Category
:LINE-MOTION
Display Name Format
Next Line
Function Format
NEXT-LINE-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The new buffer point

NEXT-LISP-FORM Function
Moves the mark supplied as an argument to a point immediately following the
end of the next form at the parenthesis nesting level of the mark. The updated
mark is returned. If the mark is located within a symbol, it is moved to the end
of the symbol. If an outermost form is found before the end of the next form, the
function returns :o u t e r m o s t - f o r m and does not move the mark. If no objects
are found at the parenthesis level of the mark, the function moves the mark to
a point immediately before the end of the innermost enclosing list and returns
:e n d - o f - l i s t . If the end of the buffer is found before the end of the next form,
the function returns : E N D - o f - b u f f e r and does not move the mark.

Objects-204

Editor Object Descriptions

Format
NEXT-LISP-FORM m ark
Arguments
mark

An Editor mark

Return Value
The updated mark; or :e n d - o f - l i s t , :o u t e r m o s t - f o r m , or : E N D - o f - b u f f e r

NEXT PARAGRAPH Command
Moves the mark to the beginning of the next paragraph. A paragraph is delimited
by a whitespace line (see w h i t e s p a c e - l i n e - p function). The mark defaults to the
current buffer point. If a prefix argument is supplied, the command moves the
mark forward that many paragraphs.

Display Name Format
Next Paragraph
Function Format
NEXT-PARAGRAPH-COMMAND prefix & OPTIONAL m ark
Arguments
prefix

An integer or n i l
mark

An Editor mark that defaults to the current buffer point.

Return Value
The updated mark

Objects-205

Editor Object Descriptions

NEXT SCREEN Command
Scrolls the window down a distance equal to the height of the window if the prefix
argument is n i l . If you specify an integer prefix argument, the window is scrolled
down the number of lines indicated (or up, if prefix is negative).

Display Name Format
Next Screen
Function Format
NEXT-SCREEN-COMMAND p refix &OPTIONAL window
Arguments
prefix

An integer or N I L
w indow

An Editor window that defaults to the current window

Return Value
The new buffer point

NEXT WINDOW Command
Moves the cursor from the current window to the window below it; that is, the
current window is redefined. The cursor is then located at the window point of
the new current window. If you specify an integer prefix argument, the command
is executed the number of times indicated. The command circulates through all
displayed windows regardless of window type.

Display Name Format
Next Window
Function Format
NEXT-WINDOW-COMMAND p re fix

Objects-206

Editor Object Descriptions

Arguments
prefix

An integer or n i l

Return Value
The new current window

NEXT-WINDOW Function
Returns a window that is the “
next”displayed window in sequence from the
current window. If the window type argument is T, this function selects the next
window that has the type of the current window. If the function is at the end
of the list of that type, it switches to the opposite type of window and continues
through that list. If the window type argument is either :f l o a t i n g or :a n c h o r e d ,
the selection of the next window is made from only that type of window. The
function returns n i l if there is not a window of the appropriate type currently
displayed.
The optional count argument tells the function how many times to look for a next
window. The argument can be positive or negative. A zero argument returns the
current window. Repeatedly setting the current window to the next window with
a window type of t results in circulation through all displayed windows.

Format
NEXT-WINDOW &OPTIONAL w indow -type count
Arguments
window-type

The type of the next window desired. One of :f l o a t i n g , :a n c h o r e d , or T. The
default is T.
cou n t

An integer specifying the number of windows to advance. The default is 1.

Return Value
The next window or n i l , if there are no windows of the specified type

Objects-207

Editor Object Descriptions

OPEN LINE Command
Breaks a line at the current buffer point. The resulting point position is the end
of the old line.

Display Name Format
Open Line
Function Format
OPEN-LINE-COMMAND prefix
Arguments
prefix

Ignored

Return Value
The new buffer point

PAGE DELIMITER Attribute
Has a value of l for characters that separate pages, and o for all other characters.

Display Name Format
Page Delimiter

Symbol Format
PAGE-DELIMITER

Objects-208

Editor Object Descriptions

PAGE NEXT WINDOW Command
Scrolls the next window forward the number of lines indicated by the prefix
argument or (without a prefix argument) scrolls the window forward to the next
page.

Display Name Format
Page Next Window
Function Format
PAGE-NEXT-WINDOW-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The window point of the next window

PAGE-OFFSET Function
Updates the specified mark so that it points to the position of the next page break
character (a character that has a " P a g e D e l i m i t e r " attribute value of l). An
o p t io n a l c o u n t a r g u m e n t l e t s y o u s p e c if y t h e n u m b e r o f p a g e b r e a k s t o b e lo c a t e d

forward in the buffer if count is positive, and backward in the buffer if count is
negative.

Format
PAGE-OFFSET m ark &OPTIONAL count
Arguments
mark

The mark to be updated
cou n t

The number of page breaks to be located

Objects-209

Editor Object Descriptions

Return Value
The updated mark

PAGE PREVIOUS WINDOW Command
Scrolls the previous window forward to the next page. If an integer prefix argu
ment is supplied, it scrolls the window by that many rows.

Display Name Format
Page Previous Window
Function Format
PAGE-PREVIOUS-WINDOW-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
Undefined

PAUSE EDITOR Command
Returns control from the Editor to LISP at the point at which the Editor was
called. The current Editor state is saved, and the Editor restarts in that state the
next time you call the e d function. Any changes to values or functions of symbols
while the control is with the Editor are not reflected in LISP unless buffers have
been evaluated explicitly.
NOTE

In the DECwindows development environment, the "Pause Editor"
command does nothing because the Editor and Listener each have a
separate window.

Display Name Format
Pause Editor

Objects-210

Editor Object Descriptions

Function Format
PAUSE-EDITOR-COMMAND prefix
Arguments
prefix

Ignored

Return Value
None

POINTER-STATE-ACTION Function
Takes a pointer-state object and returns the pointer-action information contained
in the object, or N I L if there is none. The pointer-action information can be:
•

:m o v e m e n t if the action w a s to m o v e t h e pointer cursor

• A button constant if the action was to depress or release a button on the
pointing device. (See b i n d - p o i n t e r - c o m m a n d for information on button con
stants.) In this case, p o i n t e r - s t a t e - a c t i o n also returns a second value: T if
the action was to depress the button, or n i l if the action was to release the
button. If UIS is not present, a keyword of the form :b u t t o n -;* is returned as
the first value.
The pointer-action value(s) in a pointer-state object define the pointer action,
if any, that invoked a command which in turn called g e t - p o i n t e r - s t a t e . See
g e t - p o i n t e r - s t a t e for further information.

Format
POINTER-STATE-ACTION pointer-state
Arguments
pointer-state

A pointer-state object (as r e t u r n e d b y g e t - p o i n t e r - s t a t e )

Return Value
Multiple values:
1. The keyword :m o v e m e n t , a button constant, or button keyword
2. If a button constant is returned, p o i n t e r - s t a t e - a c t i o n also returns t or n i l .

Objects-211

Editor Object Descriptions

POINTER-STATE-BUTTONS Function
Takes a pointer-state object and returns the button-state information con
tained in the object. The button-state information indicates, for each button
on the supported pointing device, whether the button was up or down. See g e t p o i n t e r - s t ä t e for information on the time at which the button state is captured
in a pointer-state object. If a button was in transition (being depressed or re
leased) at the point in time for which the pointer state is stored, the button-state
information is the state of the buttons at the end of the transition.

Format
POINTER-STATE-BUTTONS pointer-state
Arguments
pointer-state

A pointer-state object (as r e t u r n e d b y g e t - p o i n t e r - s t a t e )

Return Value
If UIS is present, a fixnum representing the state of the buttons. See the
description of u i s :g e t - b u t t o n s in the VAX LISP Interface to VWS Graphics for
more information. If UIS is not present, a list of button keywords denoting which
buttons are depressed.

POINTER-STATE-P Function
Takes a LISP object and returns T if that object is a pointer-state object, or n i l if
it is not. See g e t - p o i n t e r - s t a t e for information on pointer-state objects.

Format
POINTER-STATE-P object
Arguments
o b je ct

Any LISP object

Objects-212

Editor Object Descriptions

Return Value
T or N I L

POINTER-STATE-TEXT-POSITION Function
Takes a pointer-state object and returns the line and the character position
contained in the object. These values define the text position indicated by the
pointer cursor when the pointer-state object was created. See g e t - p o i n t e r s t a t e for information on the time at which the pointer state is captured in a
pointer-state object.

Format
POINTER-STATE-TEXT-POSITION pointer-state
Arguments
pointer-state

A pointer-state object (as r e t u r n e d b y g e t - p o i n t e r - s t a t e )

Return Value
Two values:
1. The line indicated b y the pointer cursor, or n i l if the pointer cursor was not
indicating a line
2. The character position indicated b y the pointer cursor, or n i l if the pointer
cursor was not indicating a character position

POINTER-STATE-WINDOW-POSITION Function
Takes a pointer-state object and returns an Editor window, along with integers
that are the x and y coordinates of a display position in that window. These
values define the window position indicated by the pointer cursor at the time the
pointer-state object was created. See g e t - p o i n t e r - s t a t e for information on the
time at which the pointer state is captured in a pointer-state object.

Format
POINTER-STATE-WINDOW-POSITION pointer-state

Objects-213

Editor Object Descriptions

Arguments
pointer-state

A pointer-state object (as r e t u r n e d b y g e t - p o i n t e r - s t a t e )

Return Value
Three values if the pointer cursor was indicating an Editor window at the time
the pointer-state object was created:
1. The Editor window indicated by the pointer cursor
2. An integer that is the window column position indicated by the pointer cursor
3. An integer that is the window row position indicated by the pointer cursor
If the pointer cursor was not indicating an Editor window at the time the
pointer-state object was created, p o i n t e r - s t a t e - w i n d o w - p o s i t i o n returns n i l .

POSITION-WINDOW-TO-MARK Function
Repositions the specified window within its associated buffer to the line that
contains the specified mark. This line becomes the first line displayed in the
window. The mark’
s character position is ignored.
The window’
s screen position is not affected. The window point of the window
remains at the same text position if possible; otherwise, it moves to a position
within the window (usually the center).
This function replaces the operation, in previous releases of the Editor, of reposi
tioning a window by moving its window display start mark.

Format
POSITION-WINDOW-TO-MARK w indow m ark
Arguments
window

An Editor window
mark

An Editor mark

Return Value
The window point of the window

Objects-214

Editor Object Descriptions

PREFIX-ARGUMENT Function
Returns the current value of the prefix argument. You can set a new value for the
prefix argument by using the s e t f macro with this function. The new value can
be either n i l or a fixnum. Setting the value causes that value to be passed as the
prefix argument to the next command executed.

Format
PREFIX-ARGUMENT
Arguments
None

Return Value
A f i x n u m or n i l

PREVIOUS-CHARACTER Function
Returns the character immediately preceding the position of the mark. If there
is no previous character, the function returns n i l . This function can be used with
the s e t f macro to change the character preceding the mark.

Format
PREVIOUS-CHARACTER m ark
Arguments
mark

An Editor mark

Return Value
A char a c t e r or n i l

Objects-215

Editor Object Descriptions

*PREVIOUS-COMMAND-FUNCTION* Variable
Is bound to the last Editor command function invoked.

PREVIOUS FORM Command
Moves the current buffer point backward by the number of forms specified with
the prefix argument, within the current parenthesis nesting level. The current
buffer point is moved to the location immediately before the specified number
of forms, and the new buffer point is returned. If a negative prefix argument is
specified, the current buffer point is moved forward past the specified number of
forms.
If the beginning of the current buffer or an outermost form is found before the
beginning of the specified number of forms is reached, the Editor displays a
message and returns n i l , and the point is not moved. If there are fewer forms at
the current nesting level than the number specified by the prefix argument, the
point is placed immediately before the list initiator character of the innermost list
that encloses the point, and n i l is returned.

Display Name Format
Previous Form
Function Format
PREVIOUS-FORM-COMMAND p re fix
Arguments
prefix

Integer or n i l

Return Value
The n e w buffer point or n i l
NOTE

Do not try to execute the "Previous Form" command when the buffer
point is located within a string or a multiple escape sequence. The
results of a "Previous Form" command in these circumstances are
incorrect.

Objects-216

Editor Object Descriptions
Also, when using unmatched multiple escape characters or unmatched
string delimiter characters in a comment, you should include a back
slash (\) before these characters. Otherwise, the "Previous Form"
command may fail, because the comment delimiter will be interpreted
as part of a string or multiple escape sequence.

PREVIOUS LINE Command
Moves the point of the current buffer to the previous line. The relative horizontal
character position (not the displayed position) of the point in the old line is
maintained unless the end of the new line is to the left of that position. In such a
case, the point will be at the end of the new line.
If you specify an integer prefix argument, the point is moved up the number of
times indicated (or down, if the prefix is negative). If there is no previous line,
the point is moved to the beginning of the first line.

Category
:LINE-MOTION
Display Name Format
Previous Line
Function Format
PREVIOUS-LINE-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The new buffer point

Objects-217

Editor Object Descriptions

PREVIOUS-LISP-FORM Function
Moves the mark supplied as an argument to a point immediately preceding the
beginning of the previous form at the parenthesis nesting level of the mark.
The updated mark is returned. If the mark is located within a symbol, it is
moved to the beginning of the symbol. If an outermost form is found before the
beginning of the previous form, the function returns :o u t e r m o s t - f o r m and does
not move the mark. If no forms are found at the parenthesis level of the mark,
the function moves the mark to the beginning of the innermost enclosing list and
returns :b e g i n n i n g - o f - l i s t . If the beginning of the buffer is found before the
beginning of the previous form, the function returns : B E G I N N I N G - o f - b u f f e r and
does not move the mark. If the function detects an error due to an unmatched
string delimiter or multiple escape character in a comment, the function returns
:f a i l u r e and does not move the mark.

Format
PREVIOUS-LISP-FORM m ark
Arguments
mark

An Editor mark

Return Value
The updated mark; or :b e g i n n i n g - o f - l i s t , :o u t e r m o s t - f o r m , iF A I L U R E , or
:B E G I N N I N G - O F - B U F F E R

PREVIOUS PARAGRAPH Command
Moves the mark to the end of the previous paragraph. A paragraph is delimited
by a whitespace line (see w h i t e s p a c e - l i n e - p function). The mark defaults to the
current buffer point. If a prefix argument is supplied, the command moves the
mark backward that many paragraphs.

Display Name Format
Previous Paragraph
Function Format
PREVIOUS-PARAGRAPH-COMMAND p re fix &OPTIONAL m a rk

Objects-218

Editor Object Descriptions

Arguments
prefix

An integer or n i l
mark

An Editor mark that defaults to the current buffer point

Return Value
The updated mark

PREVIOUS SCREEN Command
Scrolls the specified window (or the current window, if none is specified) up
a distance equal to the height of the window. If you specify an integer prefix
argument, the window is scrolled up the number of lines indicated (or down, if
the prefix is negative).

Display Name Format
Previous Screen
Function Format
PREVIOUS-SCREEN-COMMAND p r e fix &OPTIONAL w indow
Arguments
prefix

An integer or n i l
w indow

An Editor window that defaults to the current window

Return Value
The new buffer point

Objects-219

Editor Object Descriptions

PREVIOUS WINDOW Command
Moves the cursor from the current window to the window above it; that is, the
current window is redefined. The cursor is then located at the window point of
the new current window. If you specify an integer prefix argument, the command
is executed the number of times indicated. The command circulates through all
displayed windows regardless of window type.

Display Name Format
Previous Window
Function Format
PREVIOUS-WINDOW-COMMAND p re fix
Arguments
prefix

An integer or n i l

Return Value
The new current window

PRINT REPRESENTATION Attribute
Determines how a character is displayed on the screen. If the value of this
attribute is n i l , the character is given no special treatment. If the value is a
string, the string is displayed as the character representation. If it is a vector, the
current column is used as an index into the vector to obtain a string to display.
Using a vector is useful for displaying characters whose print representation is
column dependent (such as tabs).
If the value is a function, then that function is called with two arguments - the
current column and the character—to obtain a string.
The print representation attribute cannot be bound in any context other than
:GLOBAL.

Display Name Format
Print Representation

Objects-220

Editor Object Descriptions

Symbol Format
PRINT-REPRESENTATION

PROMPT ALTERNATIVES Editor Variable
Is bound to the alternatives argument for the general prompt currently in
progress.

Display Name Format
Prompt Alternatives

Symbol Format
PROMPT-ALTERNATIVES

PROMPT ALTERNATIVES ARGUMENTS Editor Variable
Is bound to the alternatives arguments for the general prompt currently in
progress.

Display Name Format
Prompt Alternatives Arguments
Symbol Format
PROMPT-ALTERNATIVES-ARGUMENTS

PROMPT COMPLETE STRING Command
Is used b y the p r o m p t - f o r - i n p u t function to complete user input to a
prompt. The command uses the information supplied b y the : c o m p l e t i o n and
:c o m p l e t i o n - a r g u m e n t s arguments of the p r o m p t - f o r - i n p u t function.
NOTE
This command is an integral part of the p r o m p t - f o r - i n p u t function
and should not be used in any context other than that of the "General
Prompting" buffer. It can be rebound in that context to any desired key
sequence.
Objects-221

Editor Object Descriptions

Display Name Format
Prompt Complete String
Function Format
PROMPT-COMPLETE-STRING-COMMAND prefix
Arguments
prefix

Ignored

Return Value
None

PROMPT COMPLETION Editor Variable
Is bound to the completion argument for the general prompt currently in progress.

Display Name Format
Prompt Completion
Symbol Format
PROMPT-COMPLETION

PROMPT COMPLETION ARGUMENTS Editor Variable
Is bound to the list of completion function arguments for the general prompt that
is currently in progress.

Display Name Format
Prompt Completion Arguments

Objects-222

Editor Object Descriptions

Symbol Format
PROMPT-COMPLETION-ARGUMENTS

PROMPT DEFAULT Editor Variable
Is bound to the default value for the general prompt currently in progress.

Display Name Format
Prompt Default
Symbol Format
PROMPT-DEFAULT

PROMPT ERROR MESSAGE Editor Variable
Is bound to the error message argument of the general prompt currently in
progress.

Display Name Format
Prompt Error Message
Symbol Format
PROMPT-ERROR-MESSAGE

PROMPT ERROR MESSAGE ARGUMENTS Editor
Variable
Is bound to the error message arguments for the general prompt currently in
progress.

Display Name Format
Prompt Error Message Arguments

Objects-223

Editor Object Descriptions

Symbol Format
PROMPT-ERROR-MESSAGE-ARGUMENTS

PROMPT-FOR-INPUT Function
Prompts for input, invokes the v a l i d a t i o n function with the user’
s input string
as the argument, and returns the return value of the validation function. If the
user enters no input (a null string), p r o m p t - f o r - i n p u t can either return a default
value or prompt again for input. If the u ser’
s input is invalid, p r o m p t - f o r - i n p u t
signals an error and awaits further input.
You can specify a prompting message and a value to be returned if the user
enters no input. You can also provide alternatives, completion, and help to the
user during the prompt.

Format
PROMPT-FOR-INPUT validation &KEY :PROMPT :REQUIRED :DEFAULT
:DEFAU LT-M ESS AG E :ALTERNATIVES
:ALTERNATIVES-ARGUMENTS
:COMPLETION
:COMPLETION-ARGUMENTS
:HELP :HELP-ARGUMENTS
:ERROR-MESSAGE
■.ERROR-MESSAGE-ARGUMENTS
:SAVE-WIN DOW-STATE
Arguments
validation

A function of one argument. This function operates on the u ser’
s input string and
returns the value that will be returned by p r o m p t - f o r - i n p u t . An example of a
validation function might be f i n d - b u f f e r , which returns the buffer specified by
the string or n i l if there is no buffer with that display name.
If the validation function returns n i l , the user’
s input is not valid. In this case,
signals an error and awaits further input, n i l can be a valid
value if the validation function returns multiple values of n i l and t .
PROMPT-FOR-i n p u t

:PROMPT
A string or a function that returns a string. This argument specifies the prompt
ing message. The default is “
Enter input.”
:REQUIRED
T or n i l . This argument specifies the action to be taken if the user enters no

input (a null string) in response to the prompt. If T, p r o m p t - f o r - i n p u t prints
“
Input required”in the information area and awaits further input. If n i l (the
default), P R O M P T - F O R - i n p u t returns the value of the :d e f a u l t argument.
Objects-224

Editor Object Descriptions
iDEFAULT
This argument specifies the value to be returned by p r o m p t -f o r -i n p u t if the user
enters no input and if the value of :r e q u i r e d is n i l . The default is n i l .
:DEFAULT-MESSAGE
n i l , t , a string, or a function of one argument that returns a string.

This
argument specifies a message to be displayed in the information area at the start
of the prompt. Its purpose is to inform the user of a default return value.

If the argument is n i l (the default), no message is displayed. If T, the value of
:d e f a u l t is printed. If a string, the string is used as the control-string argument
in a call to f o r m a t , and the result is printed. The value of : d e f a u l t is used as
the data argument to f o r m a t .If a function, it is passed the value of :d e f a u l t and
the string that the function returns is printed.
:ALTERNATIVES
A string, a string table, or a function of at least one argument to be called if
the user requests input alternatives. If the argument is a function, it is passed
the string the user has typed so far and any additional arguments supplied
as :ALTERNATIVES-ARGUMENTS. The default is the string "No alternatives
available".

:ALTERNATIVES-ARGUMENTS
A list of arguments for the a l t e r n a t i v e s function. The default is n i l .
:COMPLETION
n i l , a string, a string table, or a function of at least one argument to be called

if the user requests input completion. If the argument is a function, it is passed
the string the user has typed so far and any additional arguments supplied
as :c o m p l e t i o n -a r g u m e n t s . If the argument is n i l (the default) and the user
requests input completion, an Editor error is signaled.
:COMPLETION-ARGUMENTS
A list of arguments for the :C0MPLETI0n function. The default is n i l .
:HELP

n i l , a string, or a function to be called if the user requests help.

The default is

"No help available". If the value is a string, it is displayed in the information

area; if the string contains more lines than will fit in the information area, it is
displayed in the "Help" buffer. If the argument is a function, it is called with any
arguments supplied as : h e l p -a r g u m e n t s .
:HELP-ARGUMENTS
A list of arguments for the iHELP function. The default is n i l .
:ERROR-MESSAGE
A string or a function that returns a string. This argument specifies the error
message to be displayed if the user’
s input is invalid. If the argument is a
function, it is called with any arguments supplied as :e r r o r -m e s s a g e -a r g u m e n t s .
:ERROR-MESSAGE-ARGUMENTS
A list of arguments for the :e r r o r -m e s s a g e function. The default is n i l .

Objects-225

Editor Object Descriptions
:SAVE-WINDOW-STATE
n i l or non-NiL. N o n - N i L specifies that t h e

"General Prompting" buffer r e m a i n s

t h e c u r r e n t buffer w h e n the p r o m p t is c o m p leted. (This is helpful w h e n writing
c o m m a n d s that p r o m p t for m o r e t h a n o n e value.) n i l (the default) specifies that
t h e buffer that w a s curren t w h e n t h e p r o m p t w a s initiated is to b e c o m e current
a g a i n w h e n the p r o m p t is completed.

Return Value
The value returned by the validation function or the : d e f a u l t value

PROMPT HELP Command
Is used by the p r o m p t -f o r -i n p u t function to display help when the user is being
prompted. The help information is taken from the :HELP and :h e l p -a r g u m e n t s
arguments of p r o m p t -f o r - i n p u t .
NOTE

This command is an integral part of the p r o m p t -f o r -i n p u t function
and should not be used in any context other than that of the "General
Prompting" buffer. It can be rebound in that context to any desired key
sequence.

Display Name Format
Prompt Help
Function Format
PROMPT-HELP-COMMAND prefix
Arguments
prefix

Ignored

Return Value
None

Objects-226

Editor Object Descriptions

PROMPT HELP Editor Variable
Is bound to the help argument for the general prompt currently in progress.

Display Name Format
Prompt Help
Symbol Format
PROMPT-HELP

PROMPT HELP ARGUMENTS Editor Variable
Is bound to the help function arguments for the general prompt currently in
progress.

Display Name Format
Prompt Help Arguments

Symbol Format
PROMPT-HELP-ARGUMENTS

PROMPT HELP CALLED Editor Variable
Specifies whether or not a help function has been called during the general
prompt currently in progress. If the value of this variable is non-NlL at the
completion of a prompt, the displayed help window is removed from the display.

Display Name Format
Prompt Help Called
Symbol Format
PROMPT-HELP-CALLED

Objects-227

Editor Object Descriptions

PROMPT READ AND VALIDATE Command
Is used by the p r o m p t -f o r - i n p u t function to obtain and validate the current
user response to a prompt. The validation function is taken from the validation
function argument of the p r o m p t -f o r - i n p u t function. If the validation function
succeeds, the value is returned by the p r o m p t -f o r - i n p u t function. Otherwise,
this command signals an Editor error and waits for the user to correct the
problem.
NOTE

This command is an integral part of the p r o m p t -f o r - i n p u t function
and should not be used in any context other than that of the "General
Prompting" buffer. It can be rebound in that context to any desired key
sequence.

Display Name Format
Prompt Read and Validate
Function Format
PROMPT-READ-AND-VALIDATE-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
The return value of the validation function

PROMPT RENDITION COMPLEMENT Editor Variable
Set to a keyword or a list of keywords that specifies the video rendition of prompt
ing messages. The rendition specified is relative to the terminal rendition setting.
The keywords are :N0r m a l , :REVe r s e , :B0l d , :UNDERLiNE, and :b l i n k .The default
is :UNDERLINE.

Display Name Format
Prompt Rendition Complement

Objects-228

Editor Object Descriptions

Symbol Format
PROMPT-RENDITION-COMPLEMENT

PROMPT RENDITION SET Editor Variable
Set to a keyword or a list of keywords that specifies the video rendition of
prompting messages. The rendition specified is absolute, rather than relative
to the terminal rendition setting. The keywords are :n o r m a l , :r e v e r s e , :BOLD,
:u n d e r l i n e , and :b l i n k .The default is :NORMAL.

Display Name Format
Prompt Rendition Set
Symbol Format
PROMPT-RENDITION-SET

PROMPT REQUIRED Editor Variable
Specifies whether an input value is required for the general prompt currently in
progress.

Display Name Format
P r o m p t R eq u ired

Symbol Name
PROMPT-REQUIRED

PROMPT SCROLL HELP WINDOW Command
Scrolls the Help window while in another window. When the scrolling reaches
the end of the "Help" buffer, the window is reset to the beginning of the "Help"
buffer. The command is bound in the "General Prompting" buffer so that prompt
help can be scrolled without leaving the prompting window.

Objects-229

Editor Object Descriptions

Display Name Format
Prompt Scroll Help Window
Function Format
PROMPT-SCROLL-HELP-WINDOW-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

PROMPT SHOW ALTERNATIVES Command
Is used by the p r o m p t -f o r -i n p o t function to supply the user with a list of
alternatives based on current input. The information for this command is sup
plied with the :a l t e r n a t i v e s and :a l t e r n a t i v e s -a r g u m e n t s arguments of the
PROMPT-FOR-i n p u t function.
NOTE

Display Name Format
Prompt Show Alternatives
Function Format
PROMPT-SHOW-ALTERNATIVES-COMMAND prefix
Arguments
prefix

Ignored

Objects-230

Editor Object Descriptions

Return Value
None

PROMPT START Editor Variable
Is bound to a right-inserting mark that points to the starting position of the
u ser’
s input in the prompt buffer. This description applies to the general prompt
currently in progress. The user’
s input is defined as the region between this mark
and the buffer point of the "General Prompting" buffer.

Display Name Format
Prompt Start
Symbol Format
PROMPT-START

PROMPT VALIDATION Editor Variable
Is bound to the validation function for the general prompt currently in progress.

Display Name Format
Prompt Validation
Symbol Format
PROMPT-VALIDATION

PUSH-WINDOW Function
Makes the specified window visible on the screen without removing any other
windows. If the type of the window is : f l o a t i n g , the function has the same effect
as the s h o w -w i n d o w function. If the window is :a n c h o r e d , the window is added
to the list of currently visible anchored windows, and its height and those of the
other anchored windows are adjusted so as to make them all about the same
height. See also s h o w -w i n d o w , which might remove another anchored window to
make room for the new one.

Objects-231

Editor Object Descriptions
The optional arguments allow some control over the relative vertical positioning
of an anchored window. If the companion argument is supplied, it must be
another visible anchored window. The new window is placed on the screen just
below the companion window. If the optional insert-above argument is T, the
new window is inserted on the screen just above the position of the companion
window.

Format
PUSH-WINDOW w in d o w &OPTIONAL com panion insert-above
Arguments
w indow

An Editor window to display
com pan ion

A currently visible anchored window or n i l
Insert-above

If n i l , the new window will be below the companion; if not n i l , it will appear
above the companion.

Return Value
The window

QUERY SEARCH REPLACE Command
Prompts the user for a string to search for and a second string to replace oc
currences of the first one. Completion is available during both prompts. The
completion command inserts the string last searched for or the last replacement
string, as appropriate. Once these strings are established, the command repeat
edly searches for occurrences of the first string. At each one, the command stops
and asks the user to enter one of several options about how to proceed. The
options follow:
space

Replace this occurrence and find the next one.

S or s

Replace this occurrence and stay here. The purpose of this is to
let you examine the results of the change and perhaps decide to
continue, quit, or do a recursive edit.
Replace this occurrence and then quit.

Objects-232

Replace all the remaining occurrences without asking. At the end
the Editor will put out a message telling how many occurrences
were replaced.

N or n

D o n ot rep la ce th is occu rren ce b u t do find th e n ext one.

Editor Object Descriptions

Ctrl/C (or the
current cancel
character)

Do not replace this occurrence and do quit.

Q or q

Do not replace this occurrence and do quit, returning to the point at
which the search began.

R or r

Enter a recursive edit. Exit the recursion with Ctrl/C (or the current
cancel character). A recursive edit is designed to let you do any
editing you need to do and then return to your original place in the
search/replace cycle.

Display an abbreviated version of this text.

Category
rGENERAL-PROMPTING
Display Name Format
Query Search Replace
Function Format
QUERY-SEARCH-REPLACE-COMMAND p re fix &OPTIONAL search-string
replace-string

Arguments
prefix

Ignored
search-string

The string to be replaced. If this argument is not supplied, the user is prompted
for a string.
replace-string

The string to replace the search-string with. If this argument is not supplied, the
user is prompted for a string.

Return Value
None

Objects-233

Editor Object Descriptions

QUOTED INSERT Command
Causes the next character typed to be inserted in the current buffer without
interpretation by the Editor. If you specify an integer prefix argument, the
character is inserted the number of times indicated.

Display Name Format
Quoted insert
Function Format
QUOTED-INSERT-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The character or string inserted

READ FILE Command
R ep la ces the current bu ffer con ten ts by rea d in g in a file. I f a file is not specified,

the command prompts for a file name.

Display Name Format
Read File
Function Format
READ-FILE-COMMAND p re fix &OPTIONAL pathnam e
Arguments
prefix
Ign ored

Objects-234

Editor Object Descriptions
pathnam e

The pathname specifier or n i l

Return Value
The current buffer point

REDISPLAY SCREEN Command
Erases and redisplays everything on the screen.

Display Name Format
Redisplay Screen
Function Format
REDISPLAY-SCREEN-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
None

REDISPLAY-SCREEN Function
Erases and redisplays the entire screen. This function is used when the terminal
display has been altered by broadcast or garbage-collection messages.

Format
REDISPLAY-SCREEN
Arguments
None

Objects-235

Editor Object Descriptions

Return Value
None

REGION-END Function
Returns a mark that points to the end of the region. Altering the position of the
end of a buffer region can lead to unpredictable results.

Format
REGION-END region
Arguments
region

An Editor region

Return Value
The ending mark of the region

REGION-READ-POINT Function
Returns a mark that specifies the next character to be read from an Editor region
input stream. (See description of m a k e -e d i t o r -s t r e a m -f r o m -r e g i o n function.)
T h e m ark is a new m ark u n less the option al mark argu m en t is supplied; if
a mark is specified, that mark is destructively modified to point to the next
character to be read from the stream. Altering the returned mark does not affect
the operation of the stream in any way.

Format
REGION-READ-POINT stream &OPTIONAL m ark
Arguments
stream

An Editor region input stream
mark

An Editor mark

Objects-236

Editor Object Descriptions

Return Value
An Editor mark

REGION-START Function
Returns a mark that points to the beginning of the specified region. Altering the
position of the beginning of a buffer region can lead to unpredictable results.

Format
REGION-START region
Arguments
region

An Editor region

Return Value
The starting mark of the region

REGION-TO-STRING Function
Returns a string that contains the characters in the region. Line breaks in the
region are interpreted as newline characters.

Format
REGION-TO-STRING region
Arguments
region

An Editor region

Return Value
A simple string

Objects-237

Editor Object Descriptions

REGIONP Function
Returns T if the argument is an Editor region, or n i l if it is not.

Format
REGIONP object
Arguments
o b je ct

Any LISP object

Return Value
T or N I L

REMOVE CURRENT WINDOW Command
Removes the current window from the screen. The window is not deleted, but
is no longer visible. The new current window will be one chosen according to
the rules for the n e x t - w i n d o w function. If there are no other windows visible,
the Editor returns to its initial state. See r e m o v e - w i n d o w and * e d i t o r - d e f a u l t BUFFER*.

Display Name Format
Remove Current Window
Function Format
REMOVE-CURRENT-WINDOW-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
T

Objects-238

Editor Object Descriptions

REMOVE-HIGHLIGHT-REGION Function
Alters destructively the specified highlight region object so that it no longer
affects the video display characteristics of the text contained in the region. The
text in the region is not affected by this operation. The highlight region object,
however, is destroyed and cannot be reused.

Format
REMOVE-HIGHLIGHT-REGION region
Arguments
region

An Editor highlight region

Return Value
T

REMOVE OTHER WINDOWS Command
Removes all windows but the current window. The appropriate hook functions
are invoked. The windows are not deleted.

Display Name Format
Remove Other Windows
Function Format
REMOVE-OTHER-WINDOWS p re fix
Arguments
prefix

Ignored

Return Value

Objects-239

Editor Object Descriptions

REMOVE-STRING-TABLE-ENTRY Function
Removes an entry that has the specified key from the specified string table. This
function is also a predicate that returns T if there was an entry for the specified
key, and n i l if there was not.

Format
REMOVE-STRING-TABLE-ENTRY key-string string-table
Arguments
key-string

The string that is the key of the entry to remove
string-table

The string table from which to remove the entry

Return Value
T or NIL

REMOVE-WINDOW Function
Removes the specified window from the display area. This function does not
delete the window.
If the window being removed is the current window, the new-current argument
can be used to specify the window that is to become current. If no value is
specified, the n e x t -w i n d o w function is called to select a new current window. If
there are no other windows visible, the screen is restored to an initial state. (See
NOTE below.)
The resize-remainder parameter in earlier versions of the Editor is obsolete and
any value supplied is ignored. If the window being removed is an anchored
window, the sizes of other visible anchored windows are always adjusted to fill
the available display area.

Format
REMOVE-WINDOW w indow &OPTIONAL resize-rem ainder new -current
Arguments
w indow

A visible Editor window

Objects-240

Editor Object Descriptions
resize-rem ainder

Obsolete. Any value supplied is ignored.
new-current

An Editor window. It need not be currently visible. The default is a visible
window selected by the n e x t - w i n d o w function.

Return Value
T if the w i n d o w w a s d i splayed a n d h a s b e e n r e m o v e d f r o m t h e display, or n i l if
t h e w i n d o w w a s n o t displayed.

NOTE

The r e m o v e - w i n d o w function will not remove the window associated
with the buffer specified by * e d i t o r - d e f a u l t - b u f f e r * . This is the
window that appears when you call the Editor without specifying a
string, pathname, symbol, or list, and it normally appears only when
the Editor has no other window to display. Displaying any other
window will cover this window. If the value of * e d i t o r - d e f a u l t BUFFER* is NIL, a window to the buffer "Basic Introduction" is shown
when the Editor has nothing else to display.

REPLACE-PATTERN Function
Replaces n occurrences of the text matched by the search-pattern with the string
replacement. The search starts at the specified mark. If n is n i l , all occurrences
of the search-pattern following the mark are replaced.

Format
REPLACE-PATTERN m a rk search-pattern replacem ent &OPTIONAL n
Arguments
mark

An Editor mark
search-pattern

An Editor search pattern previously computed with m a k e - s e a r c h - p a t t e r n
replacem ent

A string that will replace the old pattern in the text
n

A f i x n u m or n i l

Objects-241

Editor Object Descriptions

Return Value
The number of occurrences replaced

RETURN-FROM-EDITOR Macro
Causes the e d function to return the value or values returned by the result form.
If e d has been called recursively (for instance, by a command within the Editor),
R E T U R N - F R O M - E D I T O R returns a result from the innermost call to ED.
This macro is useful for returning results from a recursive call to the Editor, as is
done in the function p r o m p t - f o r - i n p u t .
NOTE

In the DECwindows development environment, where the e d function
returns immediately, the r e t u r n - f r o m - e d i t o r macro is useful for
recursive editing only.

Format
RETURN-FROM-EDITOR &OPTIONAL result
Arguments
result

A f o r m tha t defaults to n i l

Return Value
Not applicable

REVERSE-INVOKE-HOOK Function
Calls all the hook functions in the specified hook variable and passes the specified
arguments. The order of invocation of the hook functions is the same as the
normal context searching order. See also i n v o k e - h o o k .

Format
REVERSE-INVOKE-HOOK hook-variable &REST args

Objects-242

Editor Object Descriptions

Arguments
hook-variable

An Editor variable specifier
a rg s

Any additional arguments that may need to be passed to the hook functions

Return Value
Undefined

RING-LENGTH Function
Returns two integers. The first is the number of slots used in the ring; the second
is the maximum number of slots in the ring.

Format
RING-LENGTH ring
Arguments
ring

An Editor ring

Return Value
Two values:
• The number of slots used in the ring
• The maximum number of slots in the ring

RING-POP Function
Deletes the object at the zero position of the ring and returns it. The ring deletefunction is not called. This decreases the current length of the ring by 1.

Format
RING-POP ring

Objects-243

Editor Object Descriptions

Arguments
ring

An Editor ring

Return Value
The object at the current position of the ring

RING-PUSH Function
Pushes the object onto the ring, deleting the oldest element if the ring is full. The
ring delete-function is called if an object is deleted. This function is called with
two arguments—the object being deleted and the ring.

Format
RING-PUSH ring object
Arguments
ring

An Editor ring
o b je ct

Any LISP object

Return Value
The object that was pushed

RING-REF Function
Returns an element of the specified ring as specified by an integer index. You can
specify any integer. A negative number is the number of slots backward from the
end. If the absolute value of the integer is greater than the size of the ring, the
integer is taken modulo the size of the ring. This function can be used with the
s e t f macro to replace an element of a ring. When replacing an element, the ring
delete-function is called with two arguments—the entry being replaced and the
ring.

Format
RING-REF ring &OPTIONAL index

Objects-244

Editor Object Descriptions

Arguments
ring

An Editor ring
index

An integer specifying the element of the ring to be returned. The default is 0.

Return Value
Two values:
1. The specified object in the ring
2. The positive index number of the referenced ring slot modulo the length of
the ring

RING-ROTATE Function
Rotates a ring forward if the offset is positive, or backward if the offset is neg
ative. For example, with an offset of +1, the second element would become the
first; with an offset of -1, the last element would become the first.

Format
RING-ROTATE ring offset
Arguments
ring

An Editor ring
offset

An integer

Return Value
The object at the new zero position in the ring

RINGP Function
Returns t if the argument is an Editor ring; otherwise, returns n i l .

Objects-245

Editor Object Descriptions

Format
RINGP object
Arguments
o b je ct

Any LISP object

Return Value
T or N I L

SAME-LINE-P Function
Returns t if markl and mark2 point into the same line; returns n i l otherwise.

Format
SAME-LINE-P m a rk l m ark2
Arguments
m arkl

An Editor mark
mark2

Another Editor mark

Return Value
T or N I L

SCREEN-HEIGHT Function
Returns the current available height of the display device (screen). This number
can be less than the height of the physical device. It is the height used by the
Editor as the maximum displayable height. This value can be changed by using
the s e t f macro. The value returned by s c r e e n - h e i g h t can be less than the
specified value if the physical device cannot accommodate the specified new
height. Any anchored windows will be adjusted to fit the new height.

Objects-246

Editor Object Descriptions

Format
SCREEN-HEIGHT
Arguments
None

Return Value
The current screen height

SCREEN MODIFICATION HOOK Editor Variable
Is a hook variable called whenever the screen height or width is changed, after
all screen and window modifications have been made.

Display Name Format
Screen Modification Hook

Symbol Format
SCREEN-MODIFICATION-HOOK

SCREEN-WIDTH Function
Returns the current available width of the display device (screen). This number
can be less than the width of the physical device. It is the width used by the
Editor as the maximum displayable width. This value can be changed by using
the s e t f macro. The value returned by s c r e e n - w i d t h can be less than the
specified value if the physical device cannot accommodate the specified new
width. Any anchored windows will be adjusted to fit the new width.
This function can only be used on VT100 and VT2xx terminals. Do not use this
function on VAXstations.

Format
SCREEN-WIDTH

Objects-247

Editor Object Descriptions

Arguments
None

Return Value
The current screen width

SCROLL-WINDOW Function
Scrolls the specified window by a certain number of lines. If the count is positive,
the window scrolls down through the text, making the lines appear to be moving
upward on the screen. The window is scrolled up through the buffer if the count
is negative. The buffer point stays at the same position whenever possible;
otherwise, it is centered on the screen.

Format
SCROLL-WINDOW w indow count
Arguments
window

An Editor window
cou n t

An integer

Return Value
The buffer point of the window

SCROLL WINDOW DOWN Command
Scrolls the indicated or current window down (moves the text up) the number of
lines indicated by the prefix.

Display Name Format
Scroll Window Down

Objects-248

Editor Object Descriptions

Function Format
SCROLL-WINDOW-DOWN-COMMAND prefix &OPTIONAL w indow
Arguments
prefix

An integer or n i l
window

An Editor window that defaults to the current window

Return Value
The buffer point of the window

SCROLL WINDOW UP Command
Scrolls the indicated or current window up (moves the text down) the number of
lines indicated by the prefix argument.

Display Name Format
Scroll Window Up
Function Format
SCROLL-WINDOW-UP-COMMAND p refix &OPTIONAL w indow
Arguments
prefix

An integer or NIL
w indow

An Editor window that defaults to the current window

Return Value
The buffer point of the window

Objects-249

Editor Object Descriptions

SECONDARY SELECT REGION Command
Establishes the beginning of a DECwindows secondary selection (used in c o p y
F R O M POINTER.)

Display Name Format
Secondary Select Region
Function Format
SECONDARY-SELECT-REGION prefix
Arguments
prefix

Ignored

Return Value
Undefined

SELECT BUFFER Command
Makes the specified buffer the current buffer. If the buffer is not specified, the
function prompts for a buffer name. If the buffer does not exist, a new buffer is
created with the name you enter in response to the prompt.

Category
:GENERAL-PROMPTING
Display Name Format
Select Buffer
Function Format
SELECT-BUFFER-COMMAND p refix &OPTIONAL bu ffer

Objects-250

Editor Object Descriptions

Arguments
prefix

Ignored
buffer

An Editor buffer

Return Value
The new current buffer

SELECT ENCLOSING FORM AT POINTER Command
Creates a select region that encompasses the LISP form indicated by the pointer.
If the pointer is indicating a symbol, the region contains the symbol; if the pointer
is indicating a list initiator or a list terminator, the region contains the list. If the
command is invoked repeatedly, the select region expands to include that number
of forms enclosing the one indicated by the pointer, stopping when it reaches an
outermost form.

Display Name Format
Select Enclosing Form at Pointer
Function Format
SELECT-ENCLOSING-FORM-AT-POINTER-COMMAND p re fix
Arguments
prefix

Ignored

Return Value
Undefined

Objects-251

Editor Object Descriptions

SELECT OUTERMOST FORM Command
Creates and returns a region containing the outermost list (a list with its opening
parenthesis in the leftmost screen column) that encloses the buffer point of
the current buffer. If there is no outermost list enclosing the buffer point, the
command selects the outermost list following the point if there is one, and
otherwise selects the preceding outermost list. The command moves the point
to the left parenthesis of the appropriate list and creates a mark at the right
parenthesis of the same list. The created mark is bound to the "Buffer Select
Mark" Editor variable. The region is bound to the "Buffer Select Region" Editor
variable.

Display Name Format
Select Outermost Form
Function Format
SELECT-OUTERMOST-FORM-COMMAND prefix
Arguments
prefix

Ignored

Return Value
An Editor region containing the form

SELECT REGION RENDITION COMPLEMENT Editor
Variable
Set to a keyword or a list of keywords that specifies the video rendition of an
Editor select region. The rendition specified is relative to the rendition of the
window where the region is displayed. The keywords are :n o r m a l , :B0l d , :b l i n k ,
:r e v e r s e , and :u n d e r l i n e .The value is set to n i l in the global context, and to
:REVERSE in "EDT Emulation" and "EMACS" styles.
The values correspond to the possible values of the complement argument to

MAKE-HIGHLIGHT-REGION. See also "Select Region Rendition Set" and "Buffer
Select Region".

Objects-252

Editor Object Descriptions

Display Name Format
Select Region Rendition Complement

Symbol Format
SELECT-REGION-RENDITION-COMPLEMENT

SELECT REGION RENDITION SET Editor Variable
Set to a keyword or a list of keywords that specifies the video rendition of an
Editor select region. The rendition specified is absolute, rather than relative to
the rendition of the window where the region is displayed. The keywords are
:NORMAL, :BOLD, :BLINK, :REVERSE, and : UNDERLINE. The value is Set globally to
NIL.

The values correspond to the possible values of the set argument to m a k e h i g h l i g h t -r e g i o n .See also "Select Region Rendition Complement" and "Buffer
Select Region".

Display Name Format
Select Region Rendition Set
Symbol Format
SELECT-REGION-RENDITION-SET

SELF INSERT Command
Causes the last character typed to be inserted in the current buffer as text. If
the prefix is an integer, the character is inserted the number of times indicated.
This command is useful only when bound to keyboard characters that are to be
inserted as ordinary text. All graphic characters are self-inserting.

Display Name Format
Self Insert

Objects-253

Editor Object Descriptions

Function Format
SELF-INSERT-COMMAND p refix
Arguments
prefix

An integer or N I L

Return Value
The character or string of repeated characters

SET DECWINDOWS POINTER SYNTAX Command
Unbinds the UIS pointer bindings and binds the DECwindows pointer bindings.

Display Name Format
Set DECwindows Pointer Syntax
Function Name
SET-DECWINDOWS-POINTER-SYNTAX p refix
Arguments
prefix

Ignored

Return Value
None

SET SCREEN HEIGHT Command
Prompts for a height if no prefix argument is supplied. The command sets the
height of the screen to the number of rows specified.

Objects-254

Editor Object Descriptions

Display Name Format
Set Screen Height
Function Format
SET-SCREEN-HEIGHT-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The new screen height

SET SCREEN WIDTH Command
Prompts for a width if no prefix argument is supplied. The command sets the
width of the screen to the number of columns specified.

Display Name Format
Set Screen Width
F u n ction F orm at

SET-SCREEN-WIDTH-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The new screen width
NOTE

If you set the screen width of a terminal that does not have the
Advanced Video Option to greater than 80, the screen height is limited
to 12 lines. Therefore, you must also set the height of the screen to 12.

Objects-255

Editor Object Descriptions

SET SELECT MARK Command
Selects and highlights a region of text for other commands to operate upon. This
command sets the value of the Editor variable "Buffer select Mark" to a mark
that indicates the same position as the current buffer point. It then makes a
highlight region between the select mark and the buffer point and sets the value
of the Editor variable "Buffer Select Region" to that region. The next command
you execute that requires a select region will use the current value of "Buffer
Select Region".

You can control the video rendition of the select region with the Editor variables
"Select Region Rendition Set" and "Select Region Rendition Complement".

Objects-256

Editor Object Descriptions

Display Name Format
Set Select Mark
or

EDT Select
Function Format
SET-SELECT-MARK-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

SET UIS POINTER SYNTAX Command
Unbinds the DECwindows pointer bindings and binds the UIS pointer bindings.

Display Name Format
Set UIS Pointer Syntax
Format
SET-UIS-POINTER-SYNTAX prefix
Arguments
prefix

Ignored

Return Value
None

Objects-257

Editor Object Descriptions

SHOW-MARK Function
Highlights the position of the specified mark within the specified window for
a certain length of time. Time is in units of seconds, and defaults to 0.5. The
function terminates before the number of seconds specified in the time argument
elapses if any input is typed on the terminal. If the mark’
s position is not visible
on the terminal, s h o w - m a r k returns n i l ; otherwise, it returns T.

Format
SHOW-MARK m ark w indow &OPTIONAL time
Arguments
mark

An Editor mark
window

An Editor window
time

A positive number indicating the number of seconds the mark will be highlighted.
The default is 0.5.

Return Value
T or N I L

SHOW TIME Command
Displays the current time and date in the information area.

Display Name Format
Show Time
Function Format
SHOW-TIME-COMMAND prefix
Arguments
prefix

Ignored

Objects-258

Editor Object Descriptions

Return Value
Undefined

SHOW-WINDOW Function
Makes a window visible on the screen. The behavior of this function differs
according to whether its argument is an anchored window or a floating window.
1. If the window is a floating window, it is placed at the screen row and column
specified when the window was created unless this placement is overridden
by an explicit specification of a row or column argument. This window will
obscure any anchored or floating windows in its area. Its new row and column
are remembered so that the window will always return to that spot unless
moved or reshown with different row or column arguments.
2. If the window is a floating window that is displayed already but obscured by
another floating window, this function places the specified window “
on top of’
the obscuring one(s).
3. If the window is an anchored window and it is already on the screen, no
action occurs.
4. If the window is an anchored window and it is not on the screen, then any
row or column argument is ignored and the following events occur:
a. If there is no other anchored window on the screen, the height of the
window is set to the maximum allowable on the screen and it is made
visible.
b. If the number of anchored windows already on the screen is greater than
zero but less than the value of the Editor variable "Anchored window show
Limit", then the heights of the new and existing windows are adjusted
so that all will have about equal space on the screen. The new window is
made visible below the old.
c.

If the number of anchored windows already on the screen is greater
than or equal to the value of the Editor variable "Anchored Window show
Limit", then the least recently used window is removed from the screen.
The height of the new window is adjusted to fit the height of the window
being removed, and the new window is made visible in the same position
as the one being removed.

Format
SHOW-WINDOW w indow &OPTIONAL ro w colum n
Arguments
w indow

An Editor window

Objects-259

Editor Object Descriptions
row

An integer that specifies the screen row where the topmost line of text of the
window is to appear. The top row of the screen is row 1.
colum n

An integer that specifies the screen column where the leftmost text of the window
is to appear. The left column of the screen is column 1.

Return Value
The window

SHRINK WINDOW Command
Causes the current window to decrease in height by one line. If the window is
an anchored window, the heights of other anchored windows are increased. If the
prefix is a positive integer, the window shrinks by the number of lines indicated.
If the prefix is negative, the window grows by the number of lines indicated.

Display Name Format
Shrink Window
Function Format
SHRINK-WINDOW-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The new window height

SIMPLE-PROMPT-FOR-INPUT Function
Prompts for input in the prompting window and returns the u ser’
s input as a
string. The optional prompt argument specifies a prompting message. If the
user enters a null string, the function returns the value of the optional default
argument.

Objects-260

Editor Object Descriptions

Format
SIMPLE-PROMPT-FOR-INPUT &OPTIONAL prom p t default
Arguments
prom pt

A string. The default is a null string.
default

A value to be returned if the user enters a null string. The default is a null
string.

Return Value
A string as entered by the user or the value of the default argument

SPLIT WINDOW Command
Creates and returns a new Editor window by duplicating the current window and
displaying both. If the original window is anchored, the heights of all anchored
windows (including the new one) are adjusted.

Display Name Format
Split Window
Function Format
SPLIT-WINDOW-COMMAND prefix
Arguments
prefix

Ignored

Return Value
New window

O bjects-261

Editor Object Descriptions

START KEYBOARD MACRO Command
Starts an Editor keyboard macro. Each keystroke entered following this command
is remembered, and all commands are executed. The keyboard macro can be
ended with e n d -k e y b o a r d -m a c r o -c o m m a n d .

Display Name Format
Start Keyboard Macro
Function Format
START-KEYBOARD-MACRO-COMMAND prefix
Arguments
prefix

Ignored

Return Value
None

START NAMED KEYBOARD MACRO Command
Prompts the user for a name under which to catalog a new keyboard macro.
Each keystroke entered following this command is remembered, as in a normal
keyboard macro (see "start Keyboard Macro" description). When the macro
is completed (by "End Keyboard Macro"), it becomes the new current keyboard
macro. It is also cataloged as a new named command by the system and can
be treated just as any other named command. Its name is also entered in the
*EDITOR-KEYBOARD-MACRO-NAMES* string table.

Category
:GENERAL-PROMPTING

Objects-262

Editor Object Descriptions

Display Name Format
Start Named Keyboard Macro
Function Format
START-NAMED-KEYBOARD-MACRO-COMMAND prefix
Arguments
prefix

Ignored

Return Value
NIL

START-OF-LINE-P Function
Is a predicate that r e t u r n s T if t h e specified m a r k points to the b e g i n n i n g of a line
and

nil

otherwise.

Format
START-OF-LINE-P m a rk
Arguments
mark

An Editor mark

Return Value
T or N I L

STRING-TABLE-P Function
Returns T if the argument is an Editor string table; n i l if it is not.

Objects-263

Editor Object Descriptions

Format
STRING-TABLE-P object
Arguments
o b je ct

Any LISP object

Return Value
T or N I L

STRING-TO-REGION Function
Returns a disembodied region containing the characters in the specified string.

Format
STRING-TO-REGION string
Arguments
string

A string
Return Value
A new region

STYLE-NAME Function
Takes an Editor style specifier and returns the display name of the style.

Format
STYLE-NAME style
Arguments
style

An Editor style specifier

Objects-264

Editor Object Descriptions

Return Value
The string that is the display name of the style

STYLE-VARIABLES Function
Returns a list of symbols representing the Editor variables bound in a specified
style.

Format
STYLE-VARIABLES style
Arguments
style

An Editor style

Return Value
A list of symbols that name the Editor variables bound in the style

STYLEP Function
Returns T if the argument is an Editor style, and N I L if it is not.

Format
STYLEP ob ject
Arguments
o b je ct

Any LISP object

Return Value
T or N I L

O bjects-265

Editor Object Descriptions

SUPPLY EMACS PREFIX Command
Sets the repetition count to four times its former value and returns the new
count. That is, if the current prefix value is l, this command sets the value to 4 if
executed once, to 1 6 if executed twice, and so on.

Category
:EMACS-PREFIX

Display Name Format
Supply EMACS Prefix
Function Format
SUPPLY-EMACS-PREFIX-COMMAND prefix
Arguments
prefix

An integer or n i l

Return Value
The repetition count

SUPPLY PREFIX ARGUMENT Command
Prompts the user for an integer and uses the response as a prefix argument for
the next command invoked. The user terminates the prompt by pressing the
r e t u r n key. If a prefix argument is supplied for this command, it multiplies the
number entered as the response to the prompt.

Display Name Format
Supply Prefix Argument
Function Format
SUPPLY-PREFIX-ARGUMENT-COMMAND p re fix

Objects-266

Editor Object Descriptions

Arguments
prefix

The prefix argument for this command is an integer or n i l . It should not be
confused with the prefix integer that this command returns for the subsequent
command.

Return Value
The prefix integer for the next command invoked

SWITCH WINDOW HOOK Editor Variable
Is a hook function that is called with the new window as an argument before the
value of c u r r e n t -w i n d o w changes. If the change of c u r r e n t -w i n d o w causes the
value of CURRENT-BUFFER to change, the hooks "Buffer Entry Hook" and "Buffer
Exit Hook" are also invoked.

Display Name Format
Switch Window Hook
Symbol Format
SWITCH-WINDOW-HOOK

TARGET COLUMN Editor Variable
Maintains the screen column for commands that have the :l i n e -m o v e m e n t
category (the "Previous Line" and "Next Line" commands, bound to the up
arrow and down arrow, respectively). When one of these commands is entered,
it checks the category of the previous command. If the previous command was
not in the :l i n e -m o v e m e n t category, the current command sets the "Target
Column" variable to the current column before moving the cursor. If the previous
command was a :l i n e -m o v e m e n t command, the current command uses the value
of the "Target Column" variable to position the cursor. This allows a series of
:l i n e -m o v e m e n t commands to return the cursor to the original column after
traversing one or more short lines.

Display Name Format
Target Column

Objects-267

Editor Object Descriptions

Symbol Format
TARGET-COLUMN

TEXT OVERSTRIKE MODE Editor Variable
When set to T, causes characters inserted by means of "Self insert" and "Quoted
insert" to replace any characters (except newline characters) previously located
at the same positions. Text inserted at a newline character is inserted at the
end of the same line (that is, the newline character is moved to the right). When
this variable is set to n i l , newly inserted characters appear between previous
characters. In the default Editor, this variable is bound globally and set to n i l .
Note that this variable does not affect the operation of other text-inserting
commands, such as "e d t Paste" and "Yank".

Display Name Format
Text Overstrike Mode
Symbol Format
TEXT-OVERSTRIKE-MODE

TRANSPOSE PREVIOUS CHARACTERS Command
Transposes the pair of characters before the cursor (the current buffer point).

Display Name Format
Transpose Previous Characters

Function Format
TRANSPOSE-PREVIOUS-CHARACTERS-COMMAND prefix
Arguments
prefix

Ignored

Objects-268

Editor Object Descriptions

Return Value
Undefined

TRANSPOSE PREVIOUS WORDS Command
Transposes the pair of words at and before the cursor (the current buffer point).

Display Name Format
Transpose Previous Words
Function Format
TRANSPOSE-PREVIOUS-WORDS-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

UNBIND-ATTRIBUTE Function
Unbinds the specified attribute from the specified context. T h e u n b in d h o o k
function defined for the attribute is called with two arguments—the attribute and
the context.

Format
UNBIND-ATTRIBUTE attribute &OPTIONAL context
Arguments
attribute

An attribute specifier
con text

The context from which to unbind the attribute. The default is : g l o b a l .

O bjects-269

Editor Object Descriptions

Return Value
NIL

UNBIND-COMMAND Function
Deletes the binding of a key sequence to a command in the specified context.

Format
UNBIND-COMMAND key-sequence &OPTIONAL context
Arguments
k ey-sequ en ce

A sequence of characters
con text

An Editor context specifier that defaults to : g l o b a l

Return Value
The function that was bound, or n i l if no binding was found

UNBIND-POINTER-COMMAND Function
Deletes the binding o f a p o in t e r a c t io n t o a c o m m a n d in the specified context.

Format
UNBIND-POINTER-COMMAND pointer-action &OPTIONAL context
Arguments
pointer-action

A keyword, a button constant, a button keyword, or a list that specifies an action
of a supported pointing device. See b i n d - p o i n t e r - c o m m a n d for the possible
values.
con text

A context specifier. The default is :g l o b a l .

Objects-270

Editor Object Descriptions

Return Value
The function associated with the command that was bound, or n i l if no binding
was found

UNBIND-VARIABLE Function
Unbinds the specified Editor variable from the specified context. The unbind hook
function defined for the variable is called with two arguments—the variable and
the context.

Format
UNBIND-VARIABLE variable &OPTIONAL context
Arguments
variable

An Editor variable specifier
con text

The context from which to unbind the variable. The default is :g l o b a l .

Return Value
NIL

UNDO PREVIOUS YANK Command
Deletes the previously yanked region but does not push this region onto the kill
ring. More generally, this command deletes a region without pushing it onto the
kill ring. The region is either the currently selected region (the region associated
with the "Buffer Select Region" Editor variable) or, if no currently selected
region exists, a region defined by the buffer select mark and the current buffer
mark.

Display Name Format
Undo Previous Yank
Function Format
UNDO-PREVIOUS-YANK-COMMAND prefix

Objects-271

Editor Object Descriptions

Arguments
prefix

Ignored

Return Value
NIL

UNSET SELECT MARK Command
Deletes the select mark and removes the select region in the current buffer. That
is, it cancels the action of the command "Set Select Mark" (or "EDT Select")
by setting the value of the Editor variables "Buffer Select Mark" and "Buffer
Select Region" to NIL.
Any text contained in the select region is not affected.

Display Name Format
Unset Select Mark
or

EDT Deselect
Function Format
UNSET-SELECT-MARK-COMMAND prefix
Arguments
prefix

Ignored

Return Value
Undefined

Objects-272

Editor Object Descriptions

UPCASE REGION Command
Makes the alphabetic characters in the region supplied as an argument all
uppercase. If no argument is supplied, the command uses the current select
region.

Display Name Format
Upcase Region
Function Format
UPCASE-REGION-COMMAND prefix &OPTIONAL region
Arguments
prefix

Ignored
region

An Editor region that defaults to the buffer select region

Return Value
Undefined

UPCASE WORD Command
Makes the alphabetic characters in the word around the specified mark all
uppercase. The mark defaults to the current buffer point.

Display Name Format
Upcase Word
Function Format
UPCASE-WORD-COMMAND prefix &OPTIONAL m ark

Objects—273

Editor Object Descriptions

Arguments
prefix

Ignored
mark

An Editor mark that defaults to the current buffer point

Return Value
A region containing the word

UPDATE-DISPLAY Function
Updates any Editor windows that have changed and turns off batching of screen
updates. This function does not detect messages issued by VMS (such as operator
messages) and therefore might not erase them.

Format
UPDATE-DISPLAY
Arguments
None

Return Value
None

UPDATE-WINDOW-LABEL Function
Updates the label of a window and returns the new label as a string. This
function is useful when you must force the window to change at times other than
when the display manger needs to change it.

Format
UPDATE-WINDOW-LABEL window
Arguments
w indow

An Editor window

Objects-274

Editor Object Descriptions

Return Value
The new label for the window

VARIABLE-BOUNDP Function
Returns T if the specified Editor variable has a value, and n i l if it does not.

Format
VARIABLE-BOUNDP editor-variable &OPTIONAL context
Arguments
editor-variable

An Editor variable specifier
con text

An optional context specifier. Defaults to the current context.

Return Value
T or N I L

VARIABLE-FBOUNDP Function
Returns T if the specified Editor variable has a function definition, and n i l if it
does not.

Format
VARIABLE-FBOUNDP editor-variable &OPTIONAL context
Arguments
editor-variable

An Editor variable specifier
con text

An optional context specifier. Defaults to the current context.

O bjects-275

Editor Object Descriptions

Return Value
T or NIL

VARIABLE-FUNCTION Function
Returns the function definition of the Editor variable in the specified context. An
error is signaled if the argument symbol is not a defined Editor variable in the
specified context.
You can use this function with the s e t f macro to change the function definition of
an Editor variable. If the function definition of an Editor variable is set, all the
set hook functions associated with that variable are called.

Format
VARIABLE-FUNCTION variable &OPTIONAL context
Arguments
variable

An Editor variable specifier
con text

A context specifier that defaults to the current context

Return Value
The function definition of the E d ito r variable

VARIABLE-NAME Function
Returns the display name of the specified Editor variable.

Format
VARIABLE-NAME variable
Arguments
variable

An Editor variable specifier

Objects-276

Editor Object Descriptions

Return Value
The display name of the variable

VARIABLE-VALUE Function
Returns the value of the specified Editor variable in the specified context. An
error is signaled if the argument symbol is not a defined Editor variable in the
specified context. You can use this function with the s e t f macro to change the
value of a symbol. If the variable value of an Editor variable is set, all the set
hook functions associated with that variable are called.

Format
VARIABLE-VALUE variable &OPTIONAL context
Arguments
variable

An Editor variable specifier
con text

A context specifier that defaults to the current context

Return Value
The value of the Editor variable

VAX LISP Style
Is the default minor style for editing any LISP objects or for editing files with an
extension of ,LSP.

Display Name Format
VAX LISP

Objects-277

Editor Object Descriptions

Symbol Format
VAX-LISP

VIEW FILE Command
Prompts the user for the name of a file, if one is not supplied, and reads that
file into a read-only buffer. A window into the buffer is created and becomes the
new current window. If a buffer exists with that file, that buffer becomes the
current one and is set to be read-only. An Editor error is signaled if any attempt
to modify the buffer occurs.

Category
:GENERAL-PROMPTING
Display Name Format
View File
Function Format
VIEW-FILE-COMMAND prefix &OPTIONAL file
Arguments
prefix

Ignored
file

A pathname, namestring, or stream

Return Value
The new buffer

Objects-278

Editor Object Descriptions

VISIBLE-WINDOWS Function
Returns a list of the windows currently visible on the screen. A window is
considered “
visible”if it has been displayed and not removed; thus, a window that
is completely hidden by another window is still considered visible.

Format
VISIBLE-WINDOWS
Arguments
None

Return Value
A list of the windows currently visible on the screen

WHAT CURSOR POSITION Command
Displays the following information about the current buffer point in the informa
tion area:
X = column
Y = row
L = line number (% of total)
C = character number (% of total)
W = window start-line number; window end-line number
CH = char-code of current character

Display Name Format
What Cursor Position

Function Format
WHAT-CURSOR-POSITION-COMMAND prefix
Arguments
prefix

Ignored

Objects-279

Editor Object Descriptions

Return Value
NIL

WHITESPACE Attribute
Has a value of l for whitespace characters and 0 for all other characters.

Display Name Format
Whitespace
Symbol Format
WHITESPACE

WHITESPACE-AFTER-P Function
Is a predicate that returns T if all the characters following mark on the line have
a "Whitespace" attribute value of l; otherwise, it returns n i l .

Format
WHITESPACE-AFTER-P m a rk
Arguments
mark

An Editor mark

Return Value
T or NIL

Objects-280

Editor Object Descriptions

WHITESPACE-BEFORE-P Function
Is a predicate that returns T if all the characters preceding mark on the line have
a "Whitespace" attribute of l or if the line is empty; otherwise, it returns n i l .

Format
WHITESPACE-BEFORE-P m ark
Arguments
mark

An Editor mark

Return Value
T or N I L

WHITESPACE-BETWEEN-P Function
Is a predicate that returns t if all the characters between the two marks have
a "Whitespace" attribute value of l. A mark at the end of a line precedes the
\Newiine character; a mark at the beginning of a line follows the \Newline char
acter. It is an error for the marks to point into different buffers or disembodied
regions.

Format
WHITESPACE-BETWEEN-P start-m ark end-m ark
Arguments
start-mark

An Editor mark pointing to the character that should start the scan
end-mark

An Editor mark pointing to the character that should end the whitespace scan.
The character at the end is not included in the scan.

Return Value
T or N I L

Objects-281

Editor Object Descriptions

WHITESPACE-LINE-P Function
Is a predicate that returns T if every character in the line has a "Whitespace"
attribute of 1 (or if the line is empty); otherwise, it returns n i l .

Format
WHITESPACE-LINE-P line
Arguments
line

An Editor line

Return Value
T or N I L

WINDOW-BUFFER Function
Returns the buffer associated with a window. You can use this function as a place
indicator with the s e t f macro to change the buffer associated with a window.
Changing the value of w i n d o w -b u f f e r causes the "Window Buffer Hook" to be
invoked.

Format
WINDOW-BUFFER w indow
Arguments
w indow

An Editor window

Return Value
An Editor buffer

Objects-282

Editor Object Descriptions

WINDOW BUFFER HOOK Editor Variable
Is a hook function called with the window and new buffer as arguments whenever
a window is to be associated with a different buffer.

Display Name Format
Window Buffer Hook
Symbol Format
WINDOW-BUFFER-HOOK

WINDOW CREATION HOOK Editor Variable
Is a hook function called with a new window as an argument whenever a new
window is created.

Display Name Format
Window Creation Hook

Symbol Format
WINDOW-CREATION-HOOK

WINDOW-CREATION-TIME Function
Returns the universal time at which the specified window was created. For
information on universal time, see Common LISP: The Language.

Format
WINDOW-CREATION-TIME w indow
Arguments
w indow

An Editor window

Objects—283

Editor Object Descriptions

Return Value
The universal time at which the window was created

WINDOW DELETION HOOK Editor Variable
Is a hook function that is called with a window as an argument before it is
deleted.

Display Name Format
Window Deletion Hook

Symbol Format
WINDOW-DELETION-HOOK

WINDOW-DISPLAY-COLUMN Function
Returns the physical screen column that the first text character of the specified
window is displayed in. Columns are numbered beginning with 1. This function
is not a place form acceptable to the s e t f macro.

Format
WINDOW-DISPLAY-COLUMN w indow
Arguments
w indow

The window whose display column is to be returned

Return Value
An integer specifying the column

Objects-284

Editor Object Descriptions

WINDOW-DISPLAY-END Function
Returns a mark that points to the position just after the last position displayed in
the window. Altering the position of this mark can have unpredictable results.

Format
WINDOW-DISPLAY-END w indow
Arguments
window

An Editor window

Return Value
An Editor mark

WINDOW-DISPLAY-ROW Function
Returns the physical screen row that the first text character of the specified
window is displayed in. Rows are numbered beginning with 1. This function is
not a place form acceptable to the s e t f macro.

Format
WINDOW-DISPLAY-ROW w indow
Arguments
window

The window whose display row is to be returned

Return Value
An integer specifying the row

Objects-285

Editor Object Descriptions

WINDOW-DISPLAY-START Function
This function returns a mark that points to the first position displayed in the
window. This mark must always point to the beginning of a line (that is, its
character position must be 0).

Format
WINDOW-DISPLAY-START w indow
Arguments
window

An Editor window

Return Value
A mark

WINDOW-HEIGHT Function
Returns the height of the window as an integer. You can use this function as a
place indicator to the s e t f macro to change the height of a window. Changing the
value of WINDOW-HEIGHT causes the "Window Modification Hook" to be invoked.

Form at

WINDOW-HEIGHT w indow
Arguments
window

An Editor window

Return Value
An integer

Objects-286

Editor Object Descriptions

WINDOW-LABEL Function
Returns either a string to be used as the window label or a function used to create
the label string for a window. You can use this function with the s e t f macro to
change the label of a window.

Format
WINDOW-LABEL w indow
Arguments
window

An Editor window

Return Value
A string, a function, or n i l

WINDOW-LABEL-EDGE Function
Returns the edge of the window that the label is on. The value can be :TOP,
:b o t t o m , :l e f t , or : r i g h t . The default is :b o t t o m .This corresponds to the
:l a b e l -e d g e option of m a k e -w i n d o w .You can use this function with the s e tf
macro to change the edge of the window that the label is on.

Format
WINDOW-LABEL-EDGE w indow
Arguments
w indow

An Editor window

Return Value
The keyword indicating the edge the label is on

O bjects-287

Editor Object Descriptions

WINDOW-LABEL-OFFSET Function
Returns a nonnegative integer or n i l . If n i l , the label is centered on the specified
side. If a number, the beginning of the label is offset by the number of characters
from the start of the specified side. You can use this function with the s e t f macro
to change the offset of the label.

Format
WINDOW-LABEL-OFFSET w indow
Arguments
window

An Editor window

Return Value
A positive integer or n i l

WINDOW-LABEL-RENDITION Function
Returns a keyword or a list of keywords specifying the video rendition for
a window’
s label. The keywords are :n o r m a l , :b l i n k , :BOLD, :r e v e r s e , and
:u n d e r l i n e . This function is acceptable as a place form to s e t f . The new value
can be a single keyword or a list of keywords.

Format
WINDOW-LABEL-RENDITION w indow
Arguments
window

The window whose label’
s video rendition is desired

Return Value
A list of keywords as described above

Objects-288

Editor Object Descriptions

WINDOW-LINES-WRAP-P Function
Returns T if lines that are longer than the window is wide are wrapped, or n i l if
they are truncated. This function is acceptable as a place form to the s e t f macro
to make lines truncated or wrapped in a window.

Format
WINDOW-LINES-WRAP-P w indow
Arguments
w indow

An Editor window

Return Value
T or N I L

WINDOW MODIFICATION HOOK Editor Variable
Is a hook function called with the modified window as an argument whenever the
height, type, or width of the window changes. It is called at the completion of the
modification.

Display Name Format
W in d o w M odification H o o k

Symbol Format
WINDOW-MODIFICATION-HOOK

WINDOW-POINT Function
Returns a mark that retains the buffer point for a specified window. You can use
this mark to alter the display for a window other than the current window.

Format
WINDOW-POINT w indow

Objects-289

Editor Object Descriptions

Arguments
window

An Editor window

Return Value
An Editor mark

WINDOW-RENDITION Function
Returns a list of keywords specifying the video rendition for an entire window.
The keywords are :n o r m a l , :b l i n k , :B0l d , :r e v e r s e , and :u n d e r l i n e . This
function is acceptable as a place form to s e t f . The new value can be a single
keyword or a list of keywords.

Format
WINDOW-RENDITION w indow
Arguments
w indow

An Editor window

Return Value
A lis t of keywords

WINDOW-TRUNCATE-CHAR Function
Returns the character used to indicate that a line is truncated. The default
character is >. This function can be vised as a place indicator with the s e t f macro
to change the truncation indicator character. Changing this character causes the
window image to be recomputed if w i n d o w -l i n e s -w r a p -p is n i l .

Format
WINDOW-TRUNCATE-CHAR w indow
Arguments
window

An Editor window

Objects-290

Editor Object Descriptions

Return Value
A character

WINDOW-TYPE Function
Returns a keyword indicating the type of the window. You can change the type of
a window by using this form with s e t f .

Format
WINDOW-TYPE w indow
Arguments
w indow

An Editor window

Return Value
:FLOATING or :ANCHORED

WINDOW-WIDTH Function
Returns the width of the window as an integer. This function can be used with
the s e t f macro to change the width of a window. Changing the value of w i n d o w w i d t h causes the "Window Modification Hook" to be invoked.

Format
WINDOW-WIDTH w indow
Arguments
w indow

An Editor window

Return Value
The width of the window

Objects-291

Editor Object Descriptions

WINDOW-WRAP-CHAR Function
Returns the character used to indicate that the lines wrapped. The default
character is <. This function can be used as a place indicator with the s e t f
macro to change the wrap indicator character. Changing this character causes
the window image to be recomputed if w i n d o w - l i n e s - w r a p - p is T.

Format
WINDOW-WRAP-CHAR w indow
Arguments
window

An Editor window

Return Value
A character

WINDOWP Function
Returns T if its argument is an Editor window, and n i l if it is not.

Format
WINDOWP object
Arguments
o b je ct

Any LISP object

Return Value
T or N I L

Objects-292

Editor Object Descriptions

WITH-INPUT-FROM-REGION Macro
Makes an input stream from region and evaluates the forms as an implicit progn
with the stream bound to the argument var. On exit from the macro, the stream
is closed.

Format
WITH-INPUT-FROM-REGION (v a rre g io n ) {declaration}* {form }*
Arguments
var

The variable var is bound to the input stream.
region

An Editor region

Return Value
The value of the last evaluated form

WITH-MARK Macro
Evaluates the forms of the body with the variables bound to copies of the specified
marks. The copied marks are deleted upon exit from the form.

Format
WITH-MARK ({(var m a rk [type])}*) form *
Arguments
(var mark [type])

Each variable is bound to a copy of the mark. The new mark will be of type
:t e m p o r a r y unless otherwise specified by the type.
form s

A list of f o r m s e v a l u a t e d as a n implicit p r o g n

Return Value
The value of the last evaluated form

Objects-293

Editor Object Descriptions

WITH-OUTPUT-TO-MARK Macro
Creates an output stream to mark and evaluates the forms as an implicit progn
with the stream bound to the argument var. On exit from the macro, the stream
is closed.

Format
WITH-OUTPUT-TO-MARK (var mark) {d e cla ra tio n }*{fo rm }*
Arguments
var

The variable that will be bound to the output stream
mark

An Editor mark where output from the stream will be inserted

Return Value
The value of the last evaluated form

WITH-SCREEN-UPDATE Macro
Used to batch any changes made to the screen until all the specified forms have
completed. This form is especially useful when an Editor command makes a
large number of changes to the screen, such as removing and showing several
windows as part of one command. No alterations will appear on the screen until
the specified forms complete, when the screen will change to reflect the final
configuration.
Prompts written to the screen (by using either of the prompting functions or
writing to the information area) will not appear on the screen while inside this
macro.
You may not change the screen height or width while inside this macro.

Format
WITH-SCREEN-UPDATE &REST {form }*
Arguments
form

One or more forms to be evaluated before the screen update occurs

Objects-294

Editor Object Descriptions

Return Value
The value of the last form executed

WORD DELIMITER Attribute
Has a value of l for characters that separate words, and 0 for all other characters.

Display Name Format
Word Delimiter

Symbol Format
WORD-DELIMITER

WORD-OFFSET Function
Updates a mark so that it points to the next word—that is, to the next nonword-delimiting character beyond the next word-delimiting character. A word
delimiting character is a character that has a "Word Delimiter" attribute value
of l. The count value specifies the number of word breaks that are to be located,
going forward if positive and backward if negative.

Format
W O R D -O FFSET m ark cou n t

Arguments
mark

The mark to be updated
cou n t

The number of word breaks to be located

Return Value
The updated mark

Objects—295

Editor Object Descriptions

WRITE CURRENT BUFFER Command
Writes the current buffer or the buffer specified as the optional argument. If the
buffer is associated with a file, the resulting file is one with the same specification
and the highest version number. The associated checkpoint file, if there is one, is
deleted. If the buffer was created from a LISP object, the buffer contents are read
(and evaluated, if the contents are a LISP function) to produce a new object. For
example, if the buffer contained a function definition, the definition is changed.

Display Name Format
Write Current Buffer
Function Format
WRITE-CURRENT-BUFFER-COMMAND prefix &OPTIONAL bu ffe r
Arguments
prefix

Ignored
buffer

An Editor buffer that defaults to the current buffer

Return Value
The pathname of the file th at the buffer was w ritten to; or the value read from
the buffer

WRITE-FILE-FROM-REGION Function
Writes the specified region to a specified file. The region can begin or end in the
middle of a line. Only the text in the region is written to the file. Each line in the
region corresponds to a record in the file.

Format
WRITE-FILE-FROM-REGION pathnam e region

Objects-296

Editor Object Descriptions

Arguments
pathnam e

A pathname or namestring
region

An Editor region

Return Value
Two values:
• The truename of the file written. (For an explanation of the truename of a
file, see Common LISP: The Language.)
• The count of the number of records written to the file.

WRITE MODIFIED BUFFERS Command
Performs the same operations as "Write Current Buffer" for each buffer contain
ing an object (that is, a file or a LISP object) being edited.

Display Name Format
Write Modified Buffers
Function Format
WRITE-MODIFIED-BUFFERS-COMMAND prefix
Arguments
prefix

Ignored

Return Value
NIL

Objects-297

Editor Object Descriptions

WRITE NAMED FILE Command
Prompts for a file name if it is not supplied. The function writes the current
Editor buffer to the file.

Category
:GENERAL-PROMPTING
Display Name Format
Write Named File
Function Format
WRITE-NAMED-FILE-COMMAND p re fix &OPTIONAL filenam e
Arguments
prefix

Ignored
filename

A pathname, namestring, string, or stream

Return Value
The pathname to which the buffer was written

YANK Command
Copies the current region of the kill ring into the indicated buffer at the argu
ment mark. The mark defaults to the current buffer point. If an integer prefix
argument is supplied, that many copies of the kill-ring region are inserted.

Display Name Format
Yank

Objects-298

Editor Object Descriptions

Function Format
YANK-COMMAND p refix &OPTIONAL m ark
Arguments
prefix

An integer or NIL
mark

An Editor mark that defaults to the current buffer point

Return Value
NIL

YANK AT POINTER Command
Moves the current buffer point to the position indicated by the pointer and then
inserts at that location the first region saved on the kill ring. If the pointer is
beyond the end of a line, the region is inserted at the end of that line. If the
pointer is beyond the end of the buffer region, the kill region is inserted at the
end of the buffer region.

Display Name Format
Yank at Pointer
Function Format
YANK-AT-POINTER-COMMAND prefix
Arguments
prefix

Ignored

Return Value
The current buffer point

Objects-299

Editor Object Descriptions

YANK PREVIOUS Command
Rotates the kill ring forward, and copies the new current kill-ring region into the
buffer at the argument mark. The mark defaults to the current buffer point. The
prefix defaults to l and specifies how many copies are to be inserted (not how
much to rotate the ring).

Display Name Format
Yank Previous
Function Format
YANK-PREVIOUS-COMMAND prefix &OPTIONAL m a rk
Arguments
prefix

An integer or n i l
mark
An Editor mark that defaults to the current buffer point

Return Value
NIL

YANK REPLACE PREVIOUS Command
Deletes the previously yanked region, rotates the kill ring forward and copies
the new current kill-ring region into the current buffer at the current point. The
prefix defaults to l and specifies how many copies are to be inserted.

Display Name Format
Yank Replace Previous
Function Format
YANK-REPLACE-PREVIOUS-COMMAND prefix

Objects-300

Editor Object Descriptions

Arguments
prefix

An integer or n i l

Return Value
None

Objects-301

Appendixes

Appendix A

Editor Objects by Category
This appendix lists the Editor objects—functions, variables, commands, and so
on—that pertain to each of the categories listed below. The categories are the
major data types, subsystems, and utilities provided with the Editor.
Attributes
Attributes provided with VAX LISP
Buffers
Buffers provided with VAX LISP
Commands
Commands provided with VAX LISP
Display
Editor variables
Editor variables provided with VAX LISP
Error signaling and debugging
Files
Help
Hooks
Hook variables provided with VAX LISP
Invoking and exiting the Editor
Kill ring
Lines
LISP syntax
Marks
Miscellaneous
Pointing device
Prompting and terminal input
Regions
Rings
Searching
String tables
String tables provided with VAX LISP
Styles
Styles provided with VAX LISP
Style bindings, "e d t Emulation" style
Style bindings, "EMACS" style
Style bindings, "v a x l i s p " style
Text operations
Windows

Editor Objects by Category

A-1

A.1 Attributes
ATTRIBUTE-NAME function
BIND-ATTRIBUTE function
CHARACTER-ATTRIBUTE function
"Character Attribute Hook" Editor variable
DEFINE-ATTRIBUTE macro
* E D I t o r - a t t r i b u t e - n a m e s * variable
F I N D - A T T R I B U T E function
L O C A T E - A T T R I B U T E function
U N B I N D - A T T R I B U T E function
W H I T E S P A C E - A F T E R - P function
W H I T E S P A C E - B E F O R E - P function
W H I T E S P A C E - B E T W E E N - P function
w h i t e s p a c e -l i n e - p

function

A.2 Attributes Provided with VAX LISP
"LISP Syntax"
"Page Delimiter"
"Print Representation"
"Whitespace"
"Word Delimiter"

A.3 Buffers
"Beginning of Buffer" command
BUFFER-CHECKPOINTED function
b u f f e r -c h e c k p o i n t e d -t i m e

function

"Buffer Creation Hook" Editor variable
BUFFER-CREATION-TIME function
"Buffer Deletion Hook" Editor variable
"Buffer Entry Hook" Editor variable
"Buffer Exit Hook" Editor variable
BUFFER-HIGHLIGHT-REGIONS function
BUFFER-MAJOR-STYLE function
BUFFER-MINOR-STYLE-ACTIVE function
BUFFER-MINOR-STYLE-LIST function
BUFFER-MODIFIED-P function
BUFFER-NAME function
"Buffer Name Hook" Editor variable
b u f f e r - o b j e c t function

"Buffer Object Hook" Editor variable
BUFFER-PERMANENT function
buffer-point

function

b u f f e r - r e g i o n function

BUFFER-TYPE function
BUFFER-VARIABLES function
buffer-windows

function

BUFFER-WRITABLE function
BUFFER-WRITTEN-TIME function
BUFFERP function
A-2

Editor Objects by Category

C H E C K P O I N T - B U F F E R function
C U R R E N T - B U F F E R function
C U R R E N T - B U F F E R - P O I N T function

"Default Buffer Variables" Editor variable
"Default Major style" Editor variable
"Default Minor styles" Editor variable
D E L E T E - B U F F E R function

"Delete Current Buffer" command
"Delete Named Buffer" c o m m a n d
» E D I T O R - B U F F E R - N A M E S * variable
* E D I T O R - D E F A U L T - B U F F E R * variable

"End of Buffer" c o m m a n d
F I N D - B U F F E R function

"List Buffers" command
M A K E - B U F F E R function
m a p -b u f f e r s

function

"Maybe Reset Select at Pointer" c o m m a n d
"Move Point and Select Region" C o m m a n d
"Move Point to Pointer" c o m m a n d
"Select Buffer" c o m m a n d
"Set Select Mark" c o m m a n d
"Unset Select Mark" c o m m a n d

A.4 Buffers Provided with VAX LISP
"General Prompting" buffer
"Help" buffer

A.5 Commands
"Bind Command" c o m m a n d
BIND-COMMAND function
BIND-POINTER-COMMAND function
CATEGORY-COMMANDS function
COMMAND-CATEGORIES f u n c t i o n

COMMAND-NAME function
*CURRENT-COMMAND-FUNCTION* variable
DEFINE-COMMAND m a c r o
DEFINE-KEYBOARD-MACRO function
* e d I t o r - c o m m a n d - n a m e s * variable

*EDITOR-KEYBOARD-MACRO-NAMES* variable
e n d - k e y b o a r d -m a c r o

function

ENQUEUE-EDITOR-COMMAND function
"Execute Keyboard Macro" c o m m a n d
"Execute Named Command" c o m m a n d
f i n d - c o m m a n d function

GET-BOUND-COMMAND-FUNCTION function
"List Key Bindings" c o m m a n d
MAP-BINDINGS function
MAKE-COMMAND function
» p r e v i o u s - c o m m a n d - f u n c t i o n * variable

"Start Keyboard Macro" c o m m a n d
"Start Named Keyboard Macro" c o m m a n d

Editor Objects by Category

A-3

"Supply EMACS Prefix" command
"Supply Prefix Argument" command
UNBIND-COMMAND function
UNBIND-POINTER-COMMAND function

A.6 Commands Provided with VAX LISP
"Activate Minor Style"
"Apropos"
"Apropos Word"
"Backward Character"
"Backward Kill Ring"
"Backward Page"
"Backward Search"
"Backward Word"
"Beginning of Buffer"
"Beginning of Line"
"Beginning of Outermost Form"
"Beginning of Paragraph"
"Beginning of Window"
"Bind Command"
"Capitalize Region"
"Capitalize Word"
"Close Outermost Form"
"Deactivate Minor Style"
"Delete Current Buffer"
"Delete Line"
"Delete Named Buffer"
"Delete Next Character"
"Delete Next Word"
"Delete Previous Character"
"Delete Previous Word"
"Delete Whitespace"
"Delete Word"
"Describe"
"Describe Word"
"Describe Word at Pointer"
"Downcase Region"
"Downcase Word"
"Ed"
"Edit File"
"EDT Append"
"EDT Back to Start of Line"
"EDT Beginning of Line"
"EDT Capitalize"
"EDT Cut"
"EDT Delete Character"
"EDT Delete Line"
"EDT Delete Previous Character"
"EDT Delete Previous Line"
"EDT Delete Previous Word"
"EDT Delete to End of Line"
"EDT Delete Word"
"EDT Deselect"
"EDT End of Line"

A—4

Editor Objects by Category

"EDT Move Character"
"EDT Move Page"
"EDT Move Word"
"EDT Paste"
"EDT Paste at Pointer"
"EDT Query Search"
"EDT Replace"
"EDT Scroll Window"
"EDT Search Again"
"EDT Select"
"EDT Set Direction Advance"
"EDT Set Direction Reverse"
"EDT Special Insert"
"EDT Substitute"
"EDT Undelete Character"
"EDT Undelete Line"
"EDT Undelete Word"
"EMACS Backward Search"
"EMACS Forward Search"
"End Keyboard Macro"
"End of Buffer"
"End of Line"
"End of Outermost Form"
"End of Paragraph"
"End of Window"
"Evaluate LISP Region"
"Exchange Point and Select Mark"
"Execute Keyboard Macro"
"Execute Named Command"
"Exit"
"Exit Recursive Edit"
"Forward Character"
"Forward Kill Ring"
"Forward Page"
"Forward Search"
"Forward Word"
"Grow Window"
"Help"
"Help on Editor Error"
"Illegal Operation"
"Indent LISP Line"
"Indent LISP Region"
"Indent Outermost Form"
"Insert Buffer"
"Insert Close Paren and Match"
"Insert File"
"Kill Enclosing List"
"Kill Line"
"Kill Next Form"
"Kill Paragraph"
"Kill Previous Form"
"Kill Region"
"Kill Rest of List"
"Line to Top of Window"
"List Buffers"
"List Key Bindings"
"Maybe Reset Select at Pointer"
Editor Objects by Category

A-5

"Move Point and Select Region"
"Move Point to Pointer"
"Move to Lisp Comment"
"New Line"
"New LISP Line"
"Next Form"
"Next Line"
"Next Paragraph"
"Next Screen"
"Next Window"
"Open Line"
"Page Next Window"
"Page Previous Window"
"Pause"
"Previous Form"
"Previous Line"
"Previous Paragraph"
"Previous Screen"
"Previous Window"
"Prompt Complete String"
"Prompt Help"
"Prompt Read and Validate"
"Prompt Scroll Help Window"
"Prompt Show Alternatives"
"Query Search Replace”
"Quoted Insert"
"Read File"
"Redisplay Screen"
"Remove Current Window"
"Remove Other Windows"
"Scroll Window Down"
"Scroll Window Up"
"Select Buffer"
"Select Enclosing Form at Pointer"
"Select Outermost Form"
"Self Insert"
"Set Select Mark"
"Show Time"
"Shrink Window"
"Split Window"
"Start Keyboard Macro"
"Start Named Keyboard Macro"
"Supply EMACS Prefix"
"Supply Prefix Argument"
"Transpose Previous Characters"
"Transpose Previous Words"
"Undo Previous Yank"
"Unset Select Mark"
"Upcase Region"
"Upcase Word"
"View File"
"What Cursor Position"
"Write Current Buffer"
"Write Modified Buffers"
"Write Named File"
"Yank"
"Yank at Pointer"
A -6

Editor Objects by Category

Yank Previous"
Yank Replace Previous

A.7 Display
CLEAR-INFORMATION-AREA function
*EDITOR-RETAIN-SCREEN-STATE* variable
INFORMAT ION-AREA-HEIGHT function
*INFORMATION-AREA-OUTPUT-STREAM* variable
"Redisplay Screen" c o m m a n d
REDISPLAY-SCREEN function
s c r e e n - h e i g h t function

"Screen Modification Hook" Editor variable
s c r e e n -w i d t h

function

"Set Screen Height" command
"Set Screen Width" command
u p d a t e -d i s p l a y

function

w i t h -s c r e e n -u p d a t e

macro

A.8 Editor Variables
b i n d -v a r i a b l e

function

d e f i n e - e d i t o r -v a r i a b l e

macro

♦ e d i t o r - v a r i a b l e - n a m e s * variable
f i n d -v a r i a b l e

function

u n b i n d -v a r i a b l e

function

V A R I A B L E - B O U N D P function
v a r i a b l e -FBOUNDP

function

V A R I A B L E - F U N C T I O N function
V A R I A B L E - N A M E function
V A R I A B L E - V A L U E function

A.9 Editor Variables Provided with VAX LISP
"Anchored Window Show Limit"
"Buffer Creation Hook"
"Buffer Deletion Hook"
"Buffer Entry Hook"
"Buffer Exit Hook"
"Buffer Name Hook"
"Buffer Object Hook"
"Buffer Right Margin"
"Buffer Select Mark"
"Buffer Select Region"
"Character Attribute Hook"
"Current Window Pointer Pattern"
"Current Window Pointer Pattern X
"Current Window Pointer Pattern Y"
"Default Buffer Variables"
"Default Filetype Minor Styles"
"Default LISP Object Minor Styles"
"Default Major Style"
Editor Objects by Category

A-7

"Default Minor Styles"
"Default Search Case"
"Default Window Label"
"Default Window Label Edge"
"Default Window Label Offset"
"Default Window Label Rendition"
"Default Window Lines Wrap"
"Default Window Rendition"
"Default Window Truncate Char"
"Default Window Type"
"Default Window Width"
"Default Window Wrap Char"
"Editor Entry Hook"
"Editor Exit Hook"
"Editor Initialization Hook"
"Editor Pause Hook"
"EDT Deleted Character"
"EDT Deleted Line"
"EDT Deleted Word"
"EDT Direction Mode"
"EDT Paste Buffer"
"Help Text"
"Information Area Pointer Pattern"
"Information Area Pointer Pattern X"
"Information Area Pointer Pattern Y"
"Last Search Direction"
"Last Search Pattern"
"Last Search String"
"LISP Comment Column"
"LISP Evaluation Result"
"Major Style Activation Hook"
"Minor Style Activation Hook"
"Noncurrent Window Pointer Pattern"
"Noncurrent Window Pointer Pattern X"
"Noncurrent Window Pointer Pattern Y"
"Prompt Alternatives"
"Prompt Alternatives Arguments"
"Prompt Completion"
"Prompt Completion Arguments"
"Prompt Default"
"Prompt Error Message"
"Prompt Error Message Arguments"
"Prompt Help"
"Prompt Help Arguments"
"Prompt Help Called"
"Prompt Rendition Complement"
"Prompt Rendition Set"
"Prompt Required"
"Prompt Start"
"Prompt Validation"
"Screen Modification Hook"
"Select Region Rendition Complement"
"Select Region Rendition Set"
"Switch Window Hook"
"Target Column"
"Text Overstrike Mode"
"Window Buffer Hook"
A -8

Editor Objects by Category

"Window Creation Hook"
"Window Deletion Hook"
"Window Modification Hook"

A.10 Error Signaling and Debugging
attention

function

e d i t o r -e r r o r

function

E D I T O R - E R R O R - W I T H - H E L P function
* E D I T O R - R E T A I N - S C R E E N - S T A T E * variable

"Illegal Operation" c o m m a n d

A.11 Files
BUFFER-CHECKPOINTED function
CHECKPOINT-FREQUENCY function
"Edit File" c o m m a n d
"insert File" c o m m a n d
INSERT-FILE-AT-MARK function
"Read File" c o m m a n d
"view File" c o m m a n d
"Write Current Buffer" c o m m a n d
WRITE-FILE-FROM-REGION function
"Write Modified Buffers" c o m m a n d
"Write Named File" c o m m a n d

A.12 Help
"Apropos" c o m m a n d
APROPOS-STRING-TABLE function
"Apropos Word" c o m m a n d
"Describe" c o m m a n d
"Describe Word" c o m m a n d
"Describe Word at Pointer" c o m m a n d
"Editor Help" c o m m a n d
EDITOR-HELP-BUFFER buffer
"Help" buffer
"Help" c o m m a n d
"Help on Editor Error" c o m m a n d
"Help Text" E d i t o r variable
"Prompt Complete String" c o m m a n d
"Prompt Help" c o m m a n d
"Prompt Scroll Help Window" C o m m a n d
"Prompt Show Alternatives" c o m m a n d

A.13 Hooks
i n v o k e -h o o k

function

R E V E R S E - I N V O K E - H O O K function

Editor Objects by Category

A-9

A.14 Hook Variables Provided with VAX LISP
"Buffer Creation Hook"
"Buffer Deletion Hook"
"Buffer Entry Hook"
"Buffer Exit Hook"
"Buffer Name Hook"
"Buffer Object Hook"
"Character Attribute Hook"
"Editor Entry Hook"
"Editor Exit Hook"
"Editor Initialization Hook"
"Editor Pause Hook"
"Major Style Activation Hook"
"Minor Style Activation Hook"
"Screen Modification Hook"
"Switch Window Hook"
"Window Buffer Hook"
"Window Creation Hook"
"Window Deletion Hook"
"Window Modification Hook"

A.15 Invoking and Exiting the Editor
"Ed" c o m m a n d
e d function

"Editor Entry Hook" Editor variable
"Editor Exit Hook" Editor variable
"Editor Initialization Hook" Editor variable
"Editor Pause Hook" Editor variable
"Exit Editor" command
"Exit Recursive Edit" command
INITIALIZE-ED I TOR fu n ctio n

"Pause Editor" command

RETURN-FROM-EDITOR macro

A.16 Kill Ring
"Backward Kill Ring" C o m m a n d
"Forward Kill Ring" c o m m a n d
"Kill Line" c o m m a n d
"Kill Paragraph" c o m m a n d
"Kill Region" c o m m a n d
"Undo Previous Yank" c o m m a n d
"Yank" c o m m a n d
"Yank at Pointer" c o m m a n d
"Yank Previous" c o m m a n d
"Yank Replace Previous" C o m m a n d

A-10

Editor Objects by Category

A.17 Lines
"Beginning of Line" c o m m a n d
B R E A K - L I N E function

"Delete Line" c o m m a n d
empty-line -p function

"End of Line" command

e n d - o f -l i n e - p
l i n e /=
lin e <

function

l i n e <=

function

line=

function

l ine >

function

l i n e >=

function

l i n e -b u f f e r

function

L I N E - C H A R A C T E R function
L I N E - E N D function

line -length function
line -next function
l i n e -o f f s e t

function

l i n e -p r e v i o u s

function

L I N E - S T A R T function
L I N E - S T R I N G function
l i n e -t o -r e g i o n

function

"Line to Top of Window" command
linep

function

L I N E S - R E L A T E D - P function

"New Line" command
"New l i s p Line" c o m m a n d
"Next Line" c o m m a n d
"Open Line" c o m m a n d
"Previous Line" c o m m a n d

A.18 LISP Syntax
"Beginning of Outermost Form" command
"Close Outermost Form" command
"Delete Whitespace" Command
"Describe Word" command
"Describe Word at Pointer" Command
"End of Outermost Form" command
"Evaluate LISP Region" Command
"Indent LISP Line" Command
"Indent LISP Region" command
"Indent Outermost Form" command
"Insert Close Paren and Match" command
"Kill Enclosing List" command
"Kill Next Form" command
"Kill Previous Form" command
"Kill Rest of List" command
"lisp Comment Column" Editor variable
"lisp Evaluation Result” Editor variable
"lisp syntax" Editor attribute
"Move to LISP Comment" command
Editor Objects by Category

A-11

"New l i s p Line" c o m m a n d
"Next Form" c o m m a n d
n e x t - l i s p - f o r m function

"Previous Form" c o m m a n d
p r e v i o u s -l i s p - f o r m

function

"Select Enclosing Form at Pointer" c o m m a n d
"Select Outermost Form" c o m m a n d

A.19 Marks
"Beginning of Paragraph" c o m m a n d
"Beginning of Window" C o m m a n d
BUFFER-END function
b u f f e r - p o i n t function

"Buffer Select Mark" E d i t o r variable
b u f f e r - s t a r t function
c h a r a c t e r - o f f s e t function
c o p y - m a r k function
c u r r e n t - b u f f e r - p o i n t function
d e l e t e - m a r k function
e n d - o f - l i n e - p function

"End of Paragraph" c o m m a n d
"End of window" c o m m a n d
"Exchange Point and Select Mark" c o m m a n d
f i r s t - l i n e -p

function

L A S T - L I N E - P function
l i n e -o f f s e t

function

m a k e -e d i t o r - s t r e a m - t o - m a r k

function

M A K E - m a r k function
M A R K - V I S I B L E - P function
m a r k /=
mar k <

function

M A R K < = function
mar k =

function

m a r k >

function

m a r k >=

function

m a r k -c h a r p o s
m a r k -c o l u m n

function
function

m a r k -l i n e

function

m a r k -t y p e

function

m a r k -w i n d o w - p o s i t i o n
markp

function

m o v e -m a r k

function

M O V E - M A R K - A F T E R function
M O V E - M A R K - B E F O R E function
M O V E - M A R K - T O - P O S I T I O N function

"Move to LISP Comment" c o m m a n d
N E X T - C H A R A C T E R function

Form" c o m m a n d
"Next Line" c o m m a n d
" N e x t Paragraph" c o m m a n d
"Next

"Next Screen" c o m m a n d
" N e x t window" c o m m a n d
" P a g e N e x t Window" c o m m a n d
"Page Previous Window" c o m m a n d

A -1 2

Editor Objects by Category

p a g e - o f f s e t function

PREVIOUS-CHARACTER function
"Previous Form" c o m m a n d
"Previous Line" c o m m a n d
"Previous Paragraph" c o m m a n d
"Previous Screen" c o m m a n d
"Previous Window" c o m m a n d
r e g i o n - e n d function
r e g i o n - s t a r t function

SAME-LINE-P function
"Scroll Window Down" c o m m a n d
"Scroll window Up" c o m m a n d
SHOW-MARK function
START-OF-LINE-P function
"What Cursor Position" c o m m a n d
w i n d o w -p o i n t

function

WITH-MARK macro
w i t h - o u t p u t - t o -m a r k
w o r d -o f f s e t

macro

function

A.20 Miscellaneous
CANCEL-CHARACTER function
"Show Time" c o m m a n d

A.21

Pointing Device
BIND-POINTER-COMMAND function
"Copy from Pointer" command
"Copy to Pointer" command
"Current Window Pointer Pattern" Editor variable
"Current Window Pointer Pattern X" Editor variable
"Current Window Pointer Pattern Y" Editor variable
"Describe Word at Pointer" command
" E d t Cut" c o m m a n d
" E D T Paste at Pointer" c o m m a n d
G E T - P O I N T E R - S T A T E function

"Information Area Pointer Pattern" Editor variable
"Information Area Pointer Pattern X" Editor variable
"Information Area Pointer Pattern Y" Editor variable
"Kill Region" command
"Maybe Reset Select at Pointer" command
"Move Point and Select Region" command
"Move Point to Pointer" command
"Noncurrent Window Pointer Pattern" Editor variable
"Noncurrent Window Pointer Pattern X" Editor variable
"Noncurrent Window Pointer Pattern Y" Editor Variable
POINTER-STATE-ACTION function
POINTER-STATE-BUTTONS function
pointer-state-p

function

POINTER-STATE-TEXT-POSITION function
POINTER-STATE-WINDOW-POSITION function
"Secondary Select Region" command

Editor Objects by Category

A-13

"Select Enclosing Form at Pointer" command
UNBIND-POINTER-COMMAND function
"Yank at Pointer" command

A.22 Prompting and Terminal Input
EDITOR-LISTEN function
EDITOR-PROMPTING-BUFFER buffer
EDITOR-READ-CHAR function
EDITOR-READ-CHAR-NOHANG function
EDITOR-UNREAD-CHAR function
"General Prompting" buffer
*INFORMATION-AREA-OUTPUT-STREAM* variable
* l a s t - c h a r a c t e r - t y p e d * variable

"Prompt Alternatives" Editor variable
"Prompt Alternatives Arguments" Editor variable
"Prompt Complete String" command
"Prompt Completion" Editor variable
"Prompt Completion Arguments" Editor variable
"Prompt Default" Editor variable
"Prompt Error Message" Editor variable
"Prompt Error Message Arguments" Editor variable
p r o m p t -f o r - i n p u t

function

"Prompt Help" command
"Prompt Help" Editor variable
"Prompt Help Arguments" Editor variable
"Prompt Help Called" Editor variable
"Prompt Read and Validate" command
"Prompt Rendition Complement" Editor variable
"Prompt Rendition Set" Editor variable
"Prompt Required" Editor variable
"Prompt Scroll Help Window" command
"Prompt Show Alternatives" command
"Prompt start" Editor variable
"Prompt Validation" Editor variable
SIMPLE-PROMPT-FOR-INPUT function

A.23 Regions
"Buffer Select Region" Editor variable
COPY-REGION function
count-region

function

DELETE-AND-SAVE-REGION function
DELETE-REGION function
HIGHLIGHT-REGION-P function
MAKE-EDITOR-STREAM-FROM-REGIONfunction
MAKE-EMPTY-REGION function
MAKE-HIGHLIGHT-REGION function
MAKE-REGION function
"Maybe Reset Select at Pointer" c o m m a n d
"Move Point and Select Region" c o m m a n d
r e g i o n - e n d function

REGION-READ-POINT function

A-14

Editor Objects by Category

r e g i o n -s t a r t

function

R E G I O N - T O - S T R I N G function
regionp

function

R E M O V E - H I G H L I G H T - R E G I O N function

"Select Region Rendition Complement" Editor variable
"Select Region Rendition Set" Editor variable
"Set select Mark" c o m m a n d
S T R I N G - T O - R E G I O N function

"Unset Select Mark" c o m m a n d
WITH-INPUT-FROM-REGION macro

A.24 Rings
M A K E - R I N G function
R I N G - L E N G T H function
r i n g -p o p

function

r i n g -p u s h

function

R I N G - R E F function
ringp

function

r o t a t e -r i n g

function

A.25 Searching
"Backward Search" command
"Default Search Case" Editor variable
"EMACS Backward Search" Command
"EMACS Forward Search" Command
"Forward Search" command
"Last Search Direction" Editor variable
"Last Search Pattern" Editor variable
"Last Search String" Editor variable
LOCATE-PATTERN function
MAKE-SEARCH-PATTERN function
"Query Search Replace" Command
REPLACE-PATTERN function

A.26 String Tables
A P R O P O S - S T R I N G - T A B L E function
C O M P L E T E - S T R I N G function
f i n d -a m b i g u o u s

function

G E T - S T R I N G - T A B L E - V A L U E function
M A K E - S T R I N G - T A B L E function
m a p -s t r i n g s

function

R E M O V E - S T R I N G - T A B L E - E N T R Y function
S T R I N G - T A B L E - P function

Editor Objects by Category

A-15

A.27 String Tables Provided with VAX LISP
*EDITOR-ATTRIBUTE-NAMES*
*EDITOR-STYLE-NAMES*
*EDITOR-KEYBOARD-MACRO-NAMES *
*EDITOR-COMMAND-NAMES*
*EDITOR-BUFFER-NAMES*
*EDITOR-VARIABLE-NAMES*

A.28 Styles
"Activate Minor Style" c o m m a n d
B U F F E R - M A J O R - S T Y L E function
B U F F E R - M I N O R - S T Y L E - A C T I V E function
B U F F E R - M I N O R - S T Y L E - L I S T function

"Deactivate Minor Style" c o m m a n d
"Default Filetype Minor Styles" Editor variable
"Default LISP Object Minor Styles" Editor variable
"Default Major style" Editor variable
"Default Minor styles" Editor variable

*editor-style-names* variable
"EDT

Emulation" style

f i n d -s t y l e

function

"Major Style Activation Hook" Editor variable
make-style

macro

"Minor Style Activation Hook" Editor variable
S T Y L E - N A M E function
stylep

function

STYLE-VARIABLES function
"VAX l is p " style

A.29 Styles Provided with VAX LISP
"EDT Emulation" style
" e m a c s " style
" V A X l i s p " style

A.30 Style Bindings, "EDT Emulation" Style
"Default window Label" Editor variable
" E D T Append" c o m m a n d

Back to Start of Line" c o m m a n d
Beginning of Line" c o m m a n d
"EDT Change Case" c o m m a n d
" e d t Cut" c o m m a n d
"EDT Delete Character" c o m m a n d
"EDT Delete Line" Command
"EDT Delete Previous Character" command
"EDT Delete Previous Line" C o m m a n d
" E D T Delete Previous Word" c o m m a n d
"EDT
"EDT

A -1 6

Editor Objects by Category

"EDT Delete to End of Line" Command
" E D T Delete Word" c o m m a n d
"EDT Deleted Character" Editor variable
"e d t Deleted Line" Editor variable
" e d t Deleted Word" Editor variable
" e d t Deselect" c o m m a n d
" e d t Direction Mode" Editor variable
"EDT End of Line" co m m a n d
"EDT Move Character" C o m m a n d
" E D T Move Page" c o m m a n d
" E D T Move Word" c o m m a n d
" e d t Paste" c o m m a n d
" E D T Paste at Pointer" c o m m a n d
" e d t Paste Buffer” Editor variable
"EDT Query Search" c o m m a n d
" e d t Replace" c o m m a n d
"EDT Scroll Window" c o m m a n d
" E D T Search Again" c o m m a n d
" e d t select" c o m m a n d
"EDT Set Direction Backward" command
"EDT Set Direction Forward" command
" E D T Special Insert" c o m m a n d
" e d t Substitute" c o m m a n d
"EDT Undelete Character" C o m m a n d
"EDT Undelete Line" C o m m a n d
" E D T Undelete Word" c o m m a n d
"Select Region Rendition Complement" Editor variable
"Select Region Rendition Set" Editor variable
"Word Delimiter" Editor attribute

A.31

Style Bindings, "EMACS" Style
"Apropos Word" com m an d
"Backward Character" com m an d
"Backward Word" com m an d
"Beginning of Buffer" com m an d
"Beginning of Line" co m m a n d
"Beginning of Paragraph" Command
"Beginning of Window" Command
"Capitalize Word" com m an d
"Default Window Label" Editor variable
"Delete Current Buffer" com m an d
"Delete Next Character" com m an d
"Delete Previous Character" com m an d
"Delete Previous Word" com m an d
"Delete Next Word" Com m and
"Delete Whitespace" Command
"Describe Word" Command
"Downcase Word" Command
"Ed" com m an d
"Edit File" com m an d
"EMACS Backward Search” com m an d
"EMACS Forward Search" Command
"End of Buffer" com m an d
"End of Line" com m an d
Editor Objects by Category

A-17

"End of Paragraph" command
"End of window" command
"Exchange Point and Select Mark" command
"Execute Keyboard Macro" Command
"Execute Named Command" command
"Exit Recursive Edit" Command
"Forward Character" command
"Forward Word" command
"Grow window" command
"insert File" command
"Kill Line" command
"Kill Paragraph" command
"Kill Region" command
"Line to Top of Window" command
"List Buffers" command
"New Line" command
"Next Line" command
"Next Paragraph" command
"Next Screen" command
"Next window" command
"Open Line" command
"Page Next Window" command
"Pause Editor" command
"Previous Line" command
"Previous Paragraph" command
"Previous Screen" command
"Previous Window" command
"Query Search Replace" command
"Quoted insert" command
"Read File" command
"Redisplay Screen" command
"Remove Current Window" command
"Remove Other Windows" command
"Scroll Window Down" command
"Scroll window Up" command
"Select Buffer" command
"Select Region Rendition Complement" Editor variable
"Select Region Rendition Set" Editor variable
"Set Select Mark" command
"Show Time" command
"Shrink Window" Command
"Split window" command
"Supply EMACS Prefix" command
"Supply Prefix Argument" command
"Transpose Previous Characters" command
"Transpose Previous Words" command
"Undo Previous Yank" command
"Unset Select Mark" command
"Upcase Word" command
"view File" command
"What Cursor Position" command
"Write Current Buffer" command
"Write Modified Buffers" command
"Write Named File" command
"Yank" command
"Yank at Pointer" command
"Yank Previous" command
A -1 8

Editor Objects by Category

Yank R e p la c e P r e v i o u s " command

A.32 Style Bindings, "VAX LISP” Style
"Beginning of Outermost Form" command
"Close Outermost Form" command
"Describe Word at Pointer" Command
"End of Outermost Form" command
"Evaluate LISP Region" command
"Indent LISP Line" command
"Indent Outermost Form" command
"Insert Close Paren and Match" command
"l i s p Comment Column" Editor variable
"LISP Evaluation Result" Editor variable
"LISP Syntax" Editor attribute
"Move to LISP Comment" command
"New l i s p Line" command
"Next Form" command
"Previous Form" command
"Select Enclosing Form at Pointer" command
"Select Outermost Form" command
"Word Delimiter" Editor attribute

A.33 Text Operations
"Backward Character" command
"Backward Page" command
"Backward Word" command
"Beginning of Paragraph" command
"Beginning of Window" command
"Buffer Right Margin" Editor variable
"Capitalize Region" command
"Capitalize Word" command
DELETE-AND-SAVE-REGION function
DELETE-CHARACTERS function
"Delete Next Character" Command
"Delete Next Word" command
"Delete Previous Character" command
"Delete Previous Word" Command
DELETE-REGION function
"Delete Word" command
"Downcase Region" command
"Downcase Word" command
"End of Paragraph" command
"Forward Character" command
"Forward Page" command
"Forward Word" command
"Insert Buffer" command
INSERT-CHARACTER function
"insert File" command
INSERT-FILE-AT-MARK function
i n s e r t -r e g i o n function
i n s e r t -s t r i n g function

Editor Objects by Category

A -19

"Kill Line" command
"Kill Paragraph" command
"Kill Region" command

NEXT-CHARACTER function
"Next Paragraph" command
PREVIOUS-CHARACTER function
"Previous Paragraph" command
"Quoted insert" command
"Self insert" command
"Text Overstrike Mode" Editor variable
"Transpose Previous Characters" command
"Transpose Previous Words" command
"Undo Previous Yank" command
"Upcase Region" command
"Upcase Word" command
"Yank" command
"Yank at Pointer" command
"Yank Previous" command
"Yank Replace Previous" command

A.34 Windows
A L T E R - W I N D O W - H E I G H T function

"Anchored Window Show Limit" Editor variable
"Beginning of Window" c o m m a n d
B U F F E R - H I G H L I G H T - R E G I O N S function
b u f f e r -w i n d o w s
c e n t e r -w i n d o w

function
function

C U R R E N T - W I N D O W function

"Default window Label" Editor variable
"Default window Label Edge" Editor variable
"Default window Label Offset" Editor variable
"Default Window Label Rendition" Editor variable
"Default Window Lines Wrap" Editor variable
"Default W i n d o w R e n d i t i o n " Editor variable
"Default Window Truncate Char" Editor variable
"Default window Type" Editor variable
"Default window width" Editor variable
"Default Window Wrap Char" Editor Variable
D E L E T E - W I N D O W function

Scroll Window" c o m m a n d
"End of window" c o m m a n d
"Grow window" command
"EDT

H I G H L I G H T - R E G I O N - P function

"Line to Top of Window" c o m m a n d
M A K E - H I G H L I G H T - R E G I O N function
m a k e -w i n d o w

function

M A R K - W I N D O W - P O S I T I O N function
m o v e -w i n d o w

function

"Next Screen" c o m m a n d
"Next Window" c o m m a n d
n e x t -w i n d o w

function

"Page Next Window" command
"Page Previous Window" command
"Previous Screen" command
A-20

Editor Objects by Category

"Previous Window" C o m m a n d
"Prompt Scroll Help Window" c o m m a n d
p u s h -w i n d o w

function

"Remove Current Window" C o m m a n d
R E M O V E - H I G H L I G H T - R E G I O N function

"Remove Other Windows" c o m m a n d
r e m o v e -w i n d o w

function

s c r o l l -w i n d o w

function

"Scroll Window Down" c o m m a n d
"Scroll window Up" c o m m a n d
s h o w -w i n d o w

function

"Shrink Window" c o m m a n d
"Split window" command
"Switch Window Hook" Editor variable
u p d a t e -d i s p l a y

function

UPDATE-WINDOW-LABEL function
visible-windows

function

w i n d o w - b u f f e r function

"Window Buffer Hook" Editor variable
"Window Creation Hook" Editor variable
WINDOW-CREATION-TIME function
"Window Deletion Hook" Editor variable
w i n d o w - d i s p l a y - c o l u m n function

W I N D O W - D I S P L A Y - E N D function
w i n d o w - d i s p l a y -r o w

function

W I N D O W - D I S P L A Y - S T A R T function
w i n d o w -h e i g h t
w i n d o w -l a b e l

function
function

W I N D O W - L A B E L - E D G E function
w i n d o w -l a b e l -o f f s e t

function

W I N D O W - L A B E L - R E N D I T I O N function
w i n d o w - l i n e s -w r a p - p

function

"Window Modification Hook" Editor variable
WINDOW-POINT function
w i n d o w -r e n d i t i o n

function

w i n d o w -t r u n c a t e - c h a r

function

W I N D O W - T Y P E function
w i n d o w -w i d t h

function

w i n d o w -w r a p - c h a r
windowp

function

Appendix B

Editor Commands and Bindings
This appendix lists and briefly describes all the commands supplied with the VAX
LISP Editor. Key bindings, pointer bindings, and binding contexts are also listed
where applicable.
The following table also appears in the VAX LISP/VMS Program Development
Guide.
Table B -1: Editor Commands and Key Bindings
Name

Binding(s)

D escription

Activate Minor
Style

None

Prom pts for the name o f a m inor style and
then activates that style as a m inor style in the
current buffer.

Apropos

None

Prom pts for a string, then displays the names of
objects o f a specified type containing that string.

Apropos Word

(: STYLE "VAX LISP") |Escape|p H

Displays the result o f evaluating the APROPOS
function with the word at the cursor location as
the argument.

Backward
Character

:GLOBAL 0
(: STYLE "EMACS") [Ctri/Il

Moves the cursor backward one character or by
the num ber o f characters specified by the prefix
argument.

Backward Kill
Ring

None

Rotates the kill ring backward by one elem ent or
by the number o f elem ents specified by the prefix
argument.

Backward Page

None

Moves the cursor to the previous page break
or to the preceding page break specified by the
prefix argument.

Backward Search

None

Prom pts for a search string then m oves the
cursor to the beginning o f the first preceding
occurrence o f that string or to the preceding
occurrence specified by the prefix argument.

Backward Word

(: STYLE "EMACS") |EscapeIfbl

Moves the cursor to the end o f the previous word
or to the end o f the preceding word specified by
the prefix argument.

Pointer button transition: o button up; •button held down; { button pressed; | button released.
—> pointer movement with buttons in specified state.
Pointer buttons invoke command only when pointer cursor is in the current window.
o •o

(continued on next page)

Editor Commands and Bindings

B-1

Table B-1 (Cont.):

Editor Commands and Key Bindings

N am e

Binding(s)

D escription

B eginning o f
Buffer

( : STYLE "EDT Emulation")
IPPiimC: STYLE "EMACS") IEscape |
GO
( : STYLE "EMACS") [c55Ä|

Moves the cursor to the beginning o f the buffer.

Beginning o f Line

Moves the cursor to the beginning o f the current
line or to the beginning o f the following line
specified by the prefix argument.

B eginning of
O uterm ost Form

(: STYLE "VAX LISP")fCtri/Xim

Moves the cursor to the beginning o f the out
erm ost form currently containing it or, if the
cursor is not currently contained in a form, to
the beginning o f the preceding outerm ost form.

Beginning of
Paragraph

(: STYLE "EMACS") Escapeim

Moves the cursor to the beginning o f the current
paragraph.

Beginning of
Window

(: STYLE "EMACS ") [Escape] IT]

Moves the cursor to the top o f the current
window.

Bind Com m and

None

Prom pts for a com m and name, a key sequence
to bind to the command, and a context in which
to bind the key sequence, then binds the key
sequence to the command.

Capitalize Region

None

Capitalizes the first letter of each word in the
current select region.

Capitalize Word

(: STYLE "EMACS") |Escape |m

Capitalizes the first letter o f the word at the
cursor location.

C lose Outerm ost
Form

(: STYLE "VAX LISP") |Escape|fTl

Com pletes the outerm ost LISP form by insert
in g close-parenthesis characters at the cursor
position.

Copy from
Pointer2

: GLOBAL

Sets the end of secondary selection and copies
the text to the window that has input focus;
check that input focus is correctly set before
initiating this command.

Copy to Pointer2

: GLOBAL 1 °0 I 1

Moves the current buffer point to the position
indicated by the pointer and inserts the text
from the primary selection at that location. If
pointer is beyond the end o f a line, inserts the
text at the end o f the line. If pointer is beyond
the end o f the buffer region, inserts the text at
the end o f the buffer region.

Deactivate Minor
Style

None

Prom pts for the name o f a m inor style, then
deactivates that m inor style in the current
buffer.

D elete Current
Buffer

( : STYLE "EMACS ") [ctrwcl[CWD|

D eletes the current buffer; for modified buffers,
asks if the contents o f the buffer should first be
saved.

2Available only in DECwindows Pointer Syntax.
o j »I Pointer button transition: o button up; •button held down; J. button pressed; j button released.
I —► pointer movement with buttons in specified state.
Pointer buttons invoke command only when pointer cursor is in the current window.
o »o

(continued on n e xt page)

B-2

Editor Commands and Bindings

Table B-1 (Cont.):

Editor Commands and Key Bindings

N am e

Bmding(s)

D e scrip tio n

Delete Line

None

Deletes everything betw een the cursor and the
end o f the current line, or to the end o f the
following line specified by the prefix argument.

Delete Named
Buffer

None

Prom pts for the name o f a buffer, then deletes
that buffer; if the buffer is modified, asks if the
contents o f the buffer should first be saved.

Delete Next
Character

(:STYLE "EMACS") |Ctrl/D|

D eletes the character follow ing the cursor or the
number o f following characters specified by the
prefix argument.

Delete Next Word

(: STYLE "EMACS")|E s c a p a | | d |

D eletes everything from the cursor position to
the end o f the current word or the number o f
following w ords specified by the prefix argument.

Delete Previous
Character

:GLOBAL | Delete |
(:STYLE "EMACS ") | Delete |

D eletes the character preceding the cursor
position or the number o f preceding characters
specified by the prefix argument.

Delete Previous
Word

(:STYLE "EMACS ") |E8cape| | Delete |

Deletes everything from the cursor position
to the beginning of the current word or the
number o f preceding words specified by the
prefix argument.

Delete
W hitespace

(:STYLE "EMACS") | Escape 11Ctrl/D |

Deletes w hitespace characters follow ing the
cursor location up to the next nonwhitespace
character.

Delete Word

None

Deletes everything from the cursor position
to the beginning o f the next word, including
whitespace, or deletes the number o f following
words specified by the prefix argument.

Describe

None

Prom pts for the name and type o f an object, then
displays a description o f that object.

D escribe Word

( : STYLE "VAX LISP") few?]

Calls the DESCRIBE function with the word at

D escribe Word at
Pointer3

( : STYLE "VAX LISP") I o o 1 |

Downcase Region

None

Makes all alphabetic characters in the current
select region lowercase.

Downcase Word

(:STYLE "EMACS") |Escape|(T1

Makes all alphabetic characters in the word at
the cursor position lowercase.

( : STYLE "EMACS") [Ctrt/Xl [C?Te1

Prom pts for a LISP object to edit and, if the
object is a symbol, whether to edit its function
definition or its value.

Edit File

( : STYLE "EMACS ") fctfi/xl fcvWl

Prom pts for the specification o f a file to edit;
completion and alternatives are available during
your response to the prompt.

ED T Append

(: STYLE "EDT Emulation")

Appends the current select region to the contents
o f the paste buffer.

the cursor position as the argument.
Calls the DESCRIBE function with the word at
the pointer position as the argument.

keypad [T]

3Available only in UIS Pointer Syntax.
Pointer button transition: o button up; •button held down; J, button pressed; | button released,
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 Bindings

B-3

Table B-1 (Cont.):

Editor Commands and Key Bindings

N am e

Binding(s)

D e sc rip tio n

E D T Back to
Start o f Line

(:STYLE "EDT Emulation")
|Ctrl/H| and IBackspace |6 and |F12|4

Moves the cursor to the beginning o f the current
line or to the beginning o f the previous line, if
the cursor is already at the beginning o f a line;
or m oves back the num ber o f lines specified by
the prefix argument.

E D T Beginning o f
Line

(:STYLE "EDT Emulation")fÖ~l

Moves the cursor to the beginning of the next
line, if the current direction is forward, or to the
beginning o f the current or previous line, if the
current direction is backward; m oves the number
o f lines specified by the prefix argument.

E D T Change

(: STYLE "EDT Emulation")
[pFT]keypad [T]

Changes from low ercase to uppercase (or vice
versa), all characters in the select region or, if
no select region is defined, the character at the
cursor position.

ED T Cut

(:STYLE "EDT Emulation")
keypad pH and 1Remove |4 and
1 O I o 13

D eletes the current select region and replaces
the contents o f the paste buffer with it.

E D T Delete
Character

(:STYLE "EDT Emulation")
keypad Q

D eletes the character at the cursor position and
stores it in the deleted character area; deletes
the number o f characters specified by the prefix
argument.

ED T Delete Line

(: STYLE "EDT Emulation") [p m ]

D eletes from the cursor position to the beginning
o f the next line and stores the deleted line in
the deleted line area; deletes the number o f lines
specified by the prefix argument.

E D T Delete
Previous
Character

(:STYLE "EDT Emulation") |Delete|

D eletes the character preceding the cursor and
stores it in the deleted character area; deletes
the number o f characters specified by the prefix
argument.

E D T Delete
Previous Line

(: STYLE "EDT Emulation") fctRTU]

D eletes from the cursor position to the beginning
o f the current line or, if the cursor is at the
beginning o f a line, to the beginning o f the
previous line; stores the result in the deleted line
area; deletes the num ber o f lines specified by the
prefix argument.

(: STYLE "EDT Emulation")

D eletes from the cursor position to the beginning
o f the current word or, if the cursor is between
words, to the beginning o f the previous word;
stores the result in the deleted word area;
deletes the number o f lines specified by the
prefix argument.

Case

E D T Delete
Previous Word

|CtriW| and |Linefeed |5 and [F13] 4

3Available only in UIS Pointer Syntax.
4Key available only on LK201 keyboard.
® Key available only on VT100 terminal.
Pointer button transition: o button up; •button held down; 1 button pressed; t button released.
—* pointer movement with buttons in specified state.
Pointer buttons invoke command only when pointer cursor is in the current window.
o

o »o

(continued on n e xt page)

B-4

Editor Commands and Bindings

Table B-1 (Cont.):

Editor Commands and Key Bindings

N am e

Bm ding(s)

D e sc rip tio n

ED T Delete to
End o f Line

(: STYLE "EDT Emulation")
|p f i | keypad [T]

D eletes from the cursor position to the end o f the
current line or, if the cursor is at the end of a
line, to the end o f the next line; stores the result
in the deleted line area; deletes the number of
lines specified by the prefix argument.

E D T Delete Word

(:STYLE "EDT Emulation")
keypad Q]

D eletes from the cursor position to the beginning
o f the next word; stores the result in the deleted
word area; deletes the number o f words specified
by the prefix argument.

ED T D eselect

(:STYLE "EDT Emulation")
tEED keypad □

Cancels the current select region; equivalent to

ED T End o f Line

(: STYLE "EDT Emulation")
keypad [T]

Moves the cursor to the end of the current, next,
or previous line, depending on starting cursor
position and current direction; m oves the number
o f lines specified by the prefix argument.

ED T Move
Character

(:STYLE "EDT Emulation")
keypad |T]

Moves the cursor forward or backward by one
character, according to the current direction;
m oves the number o f characters specified by the
prefix argument.

ED T Move Page

(:STYLE "EDT Emulation")
keypad [7]

Moves the cursor to the preceding or following
page break, depending on the current direction;
m oves the number o f pages specified by the
prefix argument.

ED T Move Word

(: STYLE "EDT Emulation")
keypad [7]

Moves the cursor to the beginning of the next,
current, or preceding word, depending on current
direction and cursor starting position; m oves
the num ber o f w ords specified by the prefix
argument.

ED T Paste

(: STYLE "EDT Emulation")
[PFilkeypad m and |insert hots I

Inserts the contents o f the paste buffer at the
cursor location.

E D T Paste at
Pointer3

(:STYLE "EDT Emulation")
1 * J-0 i
(:STYLE "EDT Emulation")
[P F il iPFäl and [find] 4

Inserts the contents o f the paste buffer at the
pointer cursor location.

ED T Replace

(: STYLE "EDT Emulation")
|pR1 keypad \±\

Replaces the current select region with the
contents o f the paste buffer.

ED T Scroll
Window

(:STYLE "EDT Emulation")
keypad [T]

Scrolls the window in the direction indicated by
the current direction.

E D T Search
Again

(: STYLE "EDT Emulation")

Searches for the next or previous occurrence of
the search string that was last entered, according
to the current direction.

ED T Query
Search

"Unset Select Mark".

Prom pts for a search string and m oves the
cursor to the following or preceding occurrence
o f the string, depending on the current direction;
m oves to the occurrence specified by the prefix
argument.

3Available only in TJIS Pointer Syntax.
4Key available only on LK201 keyboard.
Pointer button transition: o button up; •button held down; j button pressed; t button released.
—* pointer movement with buttons in specified state.
Pointer buttons invoke command only when pointer cursor is in the current window.
o »o

(continued on next page)

Editor Commands and Bindings

B-5

Table B-1 (Cont.): Editor Commands and Key Bindings
Name

Binding!«)

D escription

E D T S elect

( : STYLE "EDT Emulation")
keypad n~l and |s»i»ct|4

P laces a m a rk a t th e cu rso r p o s itio n to in d ic a te
one end o f a select re g io n ; e q u iv a le n t to " Set

Select Mark".
E D T S et
D ire c tio n
B a ckw a rd

( : STYLE "EDT Emulation")
keypad [T]

Sets th e c u rre n t d ire c tio n to b ackw ard.

E D T S et
D ire c tio n
F o rw a rd

( : STYLE "EDT Emulation")

Sets th e c u rre n t d ire c tio n to fo rw a rd .

E D T S pecial
In s e rt

(: STYLE "EDT Emulation")
[PFfike yp a d [7]

In s e rts th e ch a ra c te r w hose A S C II code is
sp e cifie d by th e p re fix a rg u m e n t a t th e cu rso r
p o sitio n .

E D T S u b s titu te

( : STYLE "EDT Emulation")
(PFil[Entsrl

I f th e cu rs o r is lo ca te d a t th e b e g in n in g o f th e
c u rre n t search s trin g , replaces th e search s trin g
w ith th e co n te n ts o f th e paste b u ffe r, th e n fin d s
th e n e x t occurrence o f th e search s trin g .

E D T U n d e le te
C h a ra c te r

( : STYLE "EDT Emulation")
(pfT| ke yp a d [7]

In s e rts th e co n te n ts o f th e d e le te d ch a ra cte r area
a t th e cu rs o r lo ca tio n .

E D T U n d e le te
L in e

(:STYLE "EDT Emulation")
[PPiliPF4!

In s e rts th e co n te n ts o f th e de le te d lin e area a t
th e cu rso r lo ca tio n .

E D T U n d e le te
W ord

( : STYLE "EDT Emulation")
|p fi| ke yp a d Q ]

In s e rts th e co n te n ts o f th e d e le te d w o rd area a t
th e cu rso r lo ca tio n .

EM ACS
B a ckw a rd S earch

( : STYLE "EMACS") |CWRj

Searches b a ckw a rd fo r th e fir s t occurrence o f th e
search s trin g specified in th e pre vio u s com m and;
p ro m p ts fo r a search s trin g i f th e p re vio u s com 
m and w as n o t a se a rch in g com m and; searches
fo r th e occurrence o f th e search s trin g specified
b y th e p re fix a rg u m e n t.

E M A C S F o rw a rd
S earch

( : STYLE "EMACS") |cflÄ|

Searches fo rw a rd fo r th e fir s t occurrence o f th e
search s trin g specified in th e p re vio u s com m and;
p ro m p ts fo r a search s trin g i f th e p re vio u s com
m and w as n o t a se a rch in g com m and; searches
fo r th e occurrence o f th e search s trin g specified
b y th e p re fix a rg u m e n t.

E n d K e yb o a rd
M a cro

: GLOBAL [CWXl IT!

E nds th e c o lle ctio n o f ke ystro ke s fo r a keyboard
m acro.

E n d o f B u ffe r

( : STYLE "EDT Emulation")
|p f i| ke yp a d [ 3
( : STYLE "EMACS " ) [Escape!|T|

M oves th e cu rso r to th e end o f th e b u ffe r.

E n d o f L in e

( : STYLE "EMACS " ) [CWE]

M oves th e cu rso r to th e end o f th e c u rre n t lin e
o r fo rw a rd th e n u m b e r o f lin e s specified b y th e
p re fix a rg u m e n t and th e n to th e end o f th e lin e .

keypad [7]

4Key available only on LK201 keyboard.
_ o _ ^ ^ 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)

B-6

Editor Commands and Bindings

Table B-1 (Cont.):

Editor Commands and Key Bindings

N am e

Binding(s)

D e scrip tio n

E n d o f O u te rm o st
F o rm

( : STYLE "VAX L I S P " ) [CWX|(T

M oves th e cu rs o r to th e o u te rm o st fo rm c u rre n tly
s u rro u n d in g th e cu rso r or, i f th e cu rso r is
betw een o u te rm o st fo rm s, to th e end o f th e
fo llo w in g o u te rm o st fo rm .

E n d o f P a ra g ra p h

( : STYLE "EMACS ")|E sc ap o |[T l

M oves th e cu rso r to th e end o f th e c u rre n t
p a ra g ra p h .

E n d o f W in d o w

( : STYLE "EM A C S") |Escape[ fT™!

M oves th e c u rs o r to th e end o f th e te x t in th e
c u rre n t w indow .

E v a lu a te L IS P
R egion

( : STYLE "VAX L I S P " )

|ctri/x| (cml

E va lu a te s th e select re g io n as L IS P code;
d isp la ys th e re s u lt o f th e e v a lu a tio n in th e
in fo rm a tio n area.

E xchange P o in t
and S elect M a rk

( : STYLE "E M A C S") [CWXl [CWXl

M oves th e cu rso r to th e o th e r end o f th e c u rre n t
select re g io n , and th e m a rk d e lim itin g th e select
re g io n to th e o ld cu rso r p o s itio n ; in o th e r w ords,
preserves th e select re g io n b u t places th e cu rso r
a t th e o th e r end o f it .

E xe cu te K eyb o a rd
M a cro

: GLOBAL icwxj |ctri/E|
( : STYLE "EMACS " ) jctü/xl [~«~|

E xecutes th e c u rre n t ke yb o a rd m acro once o r
th e n u m b e r o f tim e s sp e cified b y th e p re fix
a rg u m e n t.

E xe cu te N am ed
C om m and

:GLOBAL [cgj/z] and @ 4
(: STYLE "EDT Emulation")
|pfi |keypad fT|
(: STYLE "EMACS") [fS3pä] (T]

P ro m p ts fo r th e nam e o f a com m and to execute;
in p u t co m p le tio n and a lte rn a tiv e s are a v a ila b le
d u rin g y o u r response to th e p ro m p t.

E x it

N one

R e tu rn s c o n tro l to th e L IS P in te rp re te r, d isca rd 
in g th e c u rre n t E d ito r sta te ; asks i f m o d ifie d
b u ffe rs sh o u ld fir s t be saved.

E x it R ecursive
E d it

( : STYLE "E M A C S") |Escape| [CWG]

T e rm in a te s a re c u rs iv e e d it o r pauses th e E d ito r
i f n o t d o in g a re c u rs iv e e d it.

F o rw a rd
C h a ra c te r

: GLOBAL F»1
( : STYLE "EMACS") [ctrüg .

M oves th e cu rs o r fo rw a rd one ch a ra cte r.

F o rw a rd K ill R in g

N one

R otates th e k ill rin g fo rw a rd by one e le m e n t o r
b y th e n u m b e r o f ele m e n ts sp e cified by th e p re fix
a rg u m e n t.

Forward Page

None

M oves th e cu rsor to th e n ext p a ge b reak or to
th e fo llo w in g page b re a k sp ecified by th e p re fix
a rg u m e n t.

F o rw a rd S earch

N one

P ro m p ts fo r a search s trin g , th e n m oves th e
cu rso r fo rw a rd to th e end o f th e fir s t occurrence
o f th e s trin g ; m oves th e cu rso r to th e occurrence
o f th e s trin g sp e cified b y th e p re fix a rg u m e n t.

F o rw a rd W ord

( : STYLE "EMACS") TE»cap«lHI

M oves th e c u rs o r to th e b e g in n in g o f th e n e xt
w o rd o r th e b e g in n in g o f th e w o rd specified by
th e p re fix a rg u m e n t.

4Key available only on LK201 keyboard.
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 Bindings

B-7

Table B-1 (Cont.): Editor Commands and Key Bindings
Name

Binding(s)

D escription

G ro w W in d o w

(:STYLE "EMACS" ) |cwx| | z |

Increases th e h e ig h t o f th e c u rre n t w in d o w by
one ro w o r b y th e n u m b e r o f row s sp ecified by
th e p re fix a rg u m e n t.

H e lp

:GLOBAL |PF2]and IHSifl4

D is p la y s h e lp on y o u r c u rre n t s itu a tio n .

H e lp on E d ito r
E rro r

:GLOBAL fcwTxlm

D is p la y s in fo rm a tio n on th e la s t E d ito r e rro r
th a t occurred.

Ille g a l O p e ra tio n

N one

S ig n a ls a n E d ito r e rro r; use to d isa b le a key
b in d in g lo c a lly w ith in a s ty le o r b u ffe r.

In d e n t L IS P L in e

(:STYLE "VAX LISP") [HE]

A d ju s ts th e c u rre n t L IS P lin e so th a t i t is
in d e n te d p ro p e rly in th e co n te x t o f th e p rogram .

In d e n t L IS P
R egion

N one

A d ju s ts th e in d e n ta tio n o f th e L IS P code in th e
c u rre n t select re g io n .

In d e n t O u te rm o s t
F o rm

(:STYLE "VAX LISP") fCWÖClpfSbl

In d e n ts each lin e in th e o u te rm o s t L IS P fo rm
c o n ta in in g th e cursor.

In s e rt B u ffe r

N one

P ro m p ts fo r a b u ffe r nam e, th e n in s e rts th e
co n te n ts o f th e sp e cifie d b u ffe r a t th e cu rso r
lo c a tio n .

In s e rt C lose
P a re n a n d M a tc h

(:STYLE "VAX LISP") [T)

In s e rts a clo se -p a re n th e sis c h a ra c te r a t th e
cu rso r lo c a tio n and h ig h lig h ts th e co rre sp o nd in g
o p e n -p a re n th e sis ch a ra cte r.

In s e rt F ile

(:STYLE "EMACS ") [ctrf/xl[c5Fil

P ro m p ts fo r a file sp e cifica tio n , th e n in s e rts th e
co n te n ts o f th e file a t th e cu rso r lo ca tio n ; in p u t
co m p le tio n and a lte rn a tiv e s a re a v a ila b le d u rin g
y o u r response to th e p ro m p t.

K ill E n clo sin g
L is t

None

D eletes th e L IS P lis t th a t encloses th e cu rso r
a n d adds i t to th e c u rre n t k ill- r in g re g io n i f th e
p re vio u s com m and w as a k ill- r in g com m and,
o r creates a new k ill- r in g re g io n to h o ld th e
d e le te d lis t; deletes th e n u m b e r o f e n closing lis ts
sp e cifie d b y th e p re fix a rg u m e n t.

K ill L in e

(:STYLE "EMACS") [CWK]

D eletes th e re s t o f th e c u rre n t lin e and adds i t
to th e c u rre n t k ill- r in g re g io n i f th e p re vio u s
com m and w as a k ill- r in g com m and, o r creates
a new k ill- r in g re g io n to h o ld th e d e le te d lin e ;
deletes th e n u m b e r o f lin e s sp ecified by th e
p re fix a rg u m e n t.

K ill N e x t F o rm

N one

D eletes th e L IS P fo rm im m e d ia te ly fo llo w in g
th e cu rso r and adds i t to th e c u rre n t k ill- r in g
re g io n i f th e p re vio u s com m and w as a k ill- r in g
com m and, o r creates a new k ill- r in g re g io n to
h o ld th e d e le te d fo rm ; deletes th e n u m b e r o f
fo llo w in g fo rm s sp e cified b y th e p re fix a rg u m e n t
w ith in th e c u rre n t parentheses n e s tin g le ve l.

4Key available only on LK201 keyboard.
Pointer button transition: o button up; •button held down; j button pressed; f button released.
o»o —► pointer movement with buttons in specified state.
Pointer buttons invoke command only when pointer cursor is in the current window.

(continued on next page)

B-8

Editor Commands and Bindings

Table B-1 (Cont.): Editor Commands and Key Bindings
N am e

Binding(s)

D escription

K ill P a ra g ra p h

(:STYLE "EMACS") |Eseape| ITT]

D eletes th e re s t o f th e c u rre n t p a ra g ra p h and
adds i t to th e c u rre n t k ill- r in g re g io n i f th e
p re vio u s com m and w as a k ill- r in g com m and, o r
creates a new k ill- r in g re g io n to h o ld th e d eleted
p a ra g ra p h ; deletes th e n u m b e r o f p a ra g rap h s
sp ecified b y th e p re fix a rg u m e n t.

K ill P re vio u s
F o rm

N one

D eletes th e L IS P fo rm im m e d ia te ly preceding
th e cu rso r a n d adds i t to th e c u rre n t k ill- r in g
re g io n i f th e p re vio u s com m and w as a k ill- r in g
com m and, o r creates a new k ill- r in g re g io n to
h o ld th e d e le te d fo rm ; deletes th e n u m b e r o f
pre ce d in g fo rm s sp e cifie d by th e p re fix a rg u m e n t
w ith in th e c u rre n t parentheses n e stin g le ve l.

(:STYLE "EMACS")
|3

D eletes th e c u rre n t se le ct re g io n and adds i t
to th e c u rre n t k ill- r in g re g io n i f th e pre vio u s
com m and w as a k ill- r in g com m and, o r creates a
new k ill- r in g re g io n to h o ld th e d e le te d re g io n .

K ill R est o f L is t

N one

D eletes th e re s t o f th e e n clo sin g lis t and adds
i t to th e c u rre n t k ill- r in g re g io n i f th e previous
com m and w as a k ill- r in g com m and, o r creates
a new k ill- r in g re g io n to h o ld th e d eleted lis t
fra g m e n t.

L in e to Top o f
W in d o w

(:STYLE "EMACS") |Escape||T"1

M oves th e lin e c o n ta in in g th e cu rso r to th e to p o f
th e w indow .

L is t B u ffe rs

(:STYLE "EMACS ") [ciri/x|[CtrÜBl

D isp la y s a lis t o f a ll b u ffe rs.

L is t K e y B in d in g s

N one

D isp la y s a lis t o f a ll v is ib le ke y b in d in g s o r o f a ll
keys bound in a sp e cifie d co n te xt.

M aybe R eset
S e le ct a t P o in te r1

:GLOBAL 1 T o o |

I f th e p o in te r cu rso r has n o t m oved, cancels th e
select re g io n th a t w as s ta rte d w ith 1 l oo |;i f
th e p o in te r cu rso r has m oved since 1 1 o o |, does
n o th in g .

M ove P o in t and
S elect R egion1

:GLOBAL| t o o |->

M oves th e te x t cu rs o r w ith th e p o in te r cursor,
m a rk in g a select re g io n .

M ove P o in t to
P o in te r1

:GLOBAL I • o o |

M oves th e te x t cu rso r to th e p o in te r cursor.

M ove to L IS P
C om m ent

(: STYLE "VAX LISP") fcwxim

I f th e re is no com m ent on th e c u rre n t lin e , moves
th e cu rso r to th e com m ent co lu m n and in s e rts
a sem icolon and space; i f th e re is a com m ent,
m oves th e cu rs o r to th e com m ent.

N ew L in e

:GLOBAL IReturn |
(:BUFFER "General Prompting")

B re a ks a lin e a t th e cu rs o r p o s itio n , le a v in g th e
cu rso r a t th e s ta rt o f th e new lin e .

K ill R egion

ictri/wi and I o ] o

| Linefeed |

(:STYLE "EMACS") |Return|
'Available in both DECwindows and UIS Pointer Syntax.
3Available only in UIS Pointer Syntax.
Pointer button transition: o button up; •button held down; J. button pressed; I button released.
—»pointer movement with buttons in specified state.
Pointer buttons invoke command only when pointer cursor is in the current window.
o •o

(continued on next page)

Editor Commands and Bindings

B-9

Table B-1 (Cont.):

Editor Commands and Key Bindings

Name

Bindmg(s)

Description

N ew L IS P L in e

( : STYLE "VAX L I S P " ) |Unef«d|

B re a ks a lin e a t th e cu rso r p o s itio n and in d e n ts
th e new lin e b y th e a p p ro p ria te a m o u n t in th e
co n te x t o f th e p ro g ra m .

N e x t F o rm

( : STYLE "VAX LISP") [cTOxllTI

M oves th e cu rso r to th e end o f th e n e x t fo rm
o r to th e end o f th e fo llo w in g fo rm specified by
th e p re fix a rg u m e n t; does n o t m ove o u tsid e th e
c u rre n t parentheses n e s tin g le ve l.

N e x t L in e

: GLOBAL Q]
( : STYLE "EM A C S") [Ctri/N|

M oves th e cu rso r to th e n e x t lin e o r dow n
th e n u m b e r o f lin e s specified b y th e p re fix
a rg u m e n t, ke e p in g th e cu rso r in th e same
co lu m n i f possible.

N e x t P a ra g ra p h

( : STYLE "EM A C S") |Escape| (T l

M oves th e cu rso r to th e b e g in n in g o f th e n e xt
p a ra g ra p h o r to th e fo llo w in g p a ra g ra p h specified
b y th e p re fix a rg u m e n t.

N e x t Screen

: GLOBAL | Next Screen | 4

M oves th e w in d o w dow n in th e b u ffe r by one
scre e n fu l o r b y as m a n y screenfuls as are
specified by th e p re fix a rg u m e n t.

N e x t W indow

: GLOBAL |c5i/xl[ctri/Nl
(:S T Y L E "EM A CS") |CWX|| p |

S elects a n o th e r w in d o w on th e screen to be th e
c u rre n t w in d o w ; e v e n tu a lly c irc u la te s th ro u g h
a ll th e w in d o w s on th e screen.

O pen L in e

( : STYLE "EDT Emulation")
|pfi | keypad [~5~|

B re a ks a lin e a t th e cu rso r lo c a tio n , le a v in g th e
cu rso r a t th e end o f th e o ld lin e .

( : STYLE "EM A C S") (cSvo]

Page N e x t
W indow

( : STYLE "EMACS " ) IEscape | [Ctri/Vl

S cro lls th e n e x t w in d o w on th e screen dow n one
page; or, i f a p re fix a rg u m e n t is su p p lie d , scro lls
th e n e xt w in d o w th a t m a n y row s.

Pause E d ito r

: GLOBAL [cffl/xl [CM/Z)
( : STYLE "EM A C S") [ctri/G|

Saves th e E d ito r sta te and re tu rn s co n tro l to th e
L IS P in te rp re te r.

P re vio u s F o rm

( : STYLE "VAX L I S P " ) |Ctri7x|m

M oves th e cu rs o r to th e b e g in n in g o f th e previous
fo rm o r to th e b e g in n in g o f th e preceding fo rm
sp ecified by th e p re fix a rg u m e n t; does n o t move
o u tsid e th e c u rre n t parentheses n e stin g le ve l.

P re vio u s L in e

: GLOBAL [fj
( : STYLE "EM A C S") [ctri/p]

M oves th e cu rso r to th e p re vio u s lin e o r up th e
n u m b e r o f lin e s specified by th e p re fix a rg u m e n t;
keeps th e cu rs o r in th e same colum n i f possible.

P re vio u s
P a ra g ra p h

( : STYLE "EM A CS") IEscape | H I

M oves th e cu rso r to th e end o f th e pre vio u s p a ra 
g ra p h o r to th e end o f th e prece d in g p a ra g ra p h
sp ecified b y th e p re fix a rg u m e n t.

: GLOBAL | Prev Screen | 4

M oves th e cu rso r u p in th e b u ffe r by one screen
fu l o r as m a n y scre e n fu ls as a re specified by th e
p re fix a rg u m e n t.

P re vio u s Screen

( : STYLE "EMACS " ) |Escape| | v |

P re vio u s W indow

( : STYLE "EMACS " ) [ctri/x]frT]

M akes a n o th e r w in d o w on th e screen in to th e
c u rre n t w in d o w ; e v e n tu a lly c irc u la te s th ro u g h
a ll w in d o w s on th e screen.

4Key available only on LK201 keyboard.
o I » Pointer button transition: o button up; •button held down; 1 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)

B-10

Editor Commands and Bindings

Table B-1 (Cont.): Editor Commands and Key Bindings
N am e

Binding(s)

D e scrip tio n

P ro m p t C om plete
S trin g

A tte m p ts to com plete y o u r response to a p ro m p t,
based on w h a t you have typ e d a lre a d y and th e
choices a v a ila b le in th e s itu a tio n .

P ro m p t H e lp

D isp la ys in fo rm a tio n fo r w h a te v e r is being
prom pted.

P ro m p t Read and
V a lid a te

(:BUFFER "General Prompting")
[ÜD
(:BUFFER "General Prompting")
|Return| and |Enter|

P ro m p t S cro ll
H e lp W indow

(:BUFFER "General Prompting")
[Ctri/vj

S cro lls th e H e lp w in d o w dow n w h ile a n o th e r
b u ffe r is c u rre n t; su p p lie d to le t yo u s c ro ll th e
H e lp w in d o w w h ile re sp o n d in g to a p ro m p t.

P ro m p t Show
A lte rn a tiv e s

(:BUFFER "General Prompting")
|PFi]fPF2]

D isp la y s a lis t o f a lte rn a tiv e s th a t can be entered
in response to th e c u rre n t p ro m p t, based on w h a t
yo u have ty p e d already.

Q u e ry S earch
R eplace

(:STYLE "EMACS") |Escape|m

P ro m p ts fo r a search s trin g and a re p la ce m e n t;
o ffe rs a n u m b e r o f o p tio n s a t each re p la ce m e n t
o p p o rtu n ity .

Q uoted In s e rt

:GLOBAL [CtFi7xlIT]
(: STYLE "EMACS ") |CWX| |q |

In s e rts th e n e x t c h a ra c te r typ e d a t th e cu rso r
lo c a tio n w ith o u t E d ito r in te rp re ta tio n .

R ead F ile

(: STYLE "EMACS ") [Ctri7x|[cffi/R]

P ro m p ts fo r a file sp e cifica tio n , th e n replaces
th e co n te n ts o f th e c u rre n t b u ffe r w ith th e file ;
i f th e c u rre n t b u ffe r is m o d ifie d , p ro m p ts fo r
c o n firm a tio n .

R e d isp la y Screen

( : STYLE "ED T E m u l a t i o n " ) [ c w w [
( : STYLE "EM A C S") [cw q

E rases and re d is p la y s e v e ry th in g on th e screen.

Rem ove C u rre n t
W in d o w

: GLOBAL [Ctri/x] [Ctri/R]
( : STYLE "EM A C S") |CWX| | d |

Removes th e c u rre n t w in d o w fro m th e screen;
does n o t d e le te th e associated b u ffe r.

Rem ove O th e r
W indow s

( : STYLE "EMACS " ) [Ctrt/X] |T ]

Removes a ll w in d o w s b u t th e c u rre n t w in d o w
fro m th e screen.

S c ro ll W indow
D ow n

( : STYLE "EM A CS") [ctrÜZl

S cro lls th e c u rre n t w in d o w dow n in th e b u ffe r by
one ro w o r th e n u m b e r o f row s specified b y th e
p re fix a rg u m e n t.

S c ro ll W in d o w U p

( : STYLE "EM A C S") |Escape| f z ]

S cro lls th e c u rre n t w in d o w u p in th e b u ffe r by
one ro w o r by n u m b e r o f row s specified by th e
p re fix a rg u m e n t.

S econdary S elect
R egion2

i GLOBAL | o o t |

Sets th e b e g in n in g o f secondary se le ctio n (used
in C opy fro m P o in te r com m and).

S e le ct B u ffe r

( : STYLE "EM A C S") [Ctrt/x|n>l

P ro m p ts fo r a b u ffe r nam e, th e n m akes th a t
b u ffe r th e c u rre n t b u ffe r; creates a new b u ffe r i f
necessary.

S elect E n clo sin g
F o rm a t P o in te r1

( : STYLE "VAX L I S P " ) i i o o |

Places th e fo rm e n clo sin g th e cu rso r in a select
re g io n ; i f th e cu rso r is a lre a d y in a select re g io n ,
expands th e re g io n to th e n e x t o u te rm o s t fo rm .

U sed to te rm in a te p ro m p t in p u t.

Available in both DECwindows and UIS Pointer Syntax.
2Available only in DECwindows Pointer Syntax.
Pointer button transition: o button up; •button held down; | button pressed; ] button released,
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 Bindings

B-11

Table B-1 (Cont.):

Editor Commands and Key Bindings

Name

Binding(s)

D escription

S e le ct O u te rm o s t
F o rm

(: STYLE "VAX LISP")
|Ctrl/X||Ctrl/Space|

M akes th e o u te rm o st L IS P fo rm c o n ta in in g th e
cu rs o r in to a se le ct re g io n .

S e lf In s e rt

: GLOBAL A ll g ra p h ic ch a ra cte rs

In s e rts th e la s t ch a ra c te r ty p e d a t th e cu rso r
lo ca tio n .

S e t D E C w indow s
P o in te r S yn ta x

None

U n b in d s th e U IS p o in te r b in d in g s and b in d s th e
D E C w in d o w s p o in te r b in d in g s.

S et U IS P o in te r
S yn ta x

None

U n b in d s th e D E C w in d o w s p o in te r b in d in g s and
b in d s th e U IS p o in te r b in d in g s.

S et S creen H e ig h t

N one

Sets th e screen h e ig h t to th e n u m b e r o f row s
sp ecified b y th e p re fix a rg u m e n t; p ro m p ts fo r
h e ig h t i f no p re fix a rg u m e n t is defined.

S et S creen W id th

N one

Sets th e screen w id th to th e n u m b e r o f colum ns
sp ecified b y th e p re fix a rg u m e n t; p ro m p ts fo r th e
w id th i f no p re fix a rg u m e n t is defined.

S e t S elect M a rk

(: STYLE "EDT Emulation")
keypad QJ
(: STYLE "EMACS") ICtrl/Space|

P laces a m a rk a t th e c u rs o r p o s itio n to in d ic a te
one end o f a select re g io n .

Show T im e

(: STYLE "EMACS") [Ctri/Xl[StriTTl

D isp la y s th e tim e and d a te in th e in fo rm a tio n
area.

S h rin k W indow

(: STYLE "EMACS " ) [ctri/)<l[Ctri/Zl

S h rin k s th e c u rre n t w in d o w b y one ro w o r th e
n u m b e r o f ro w s sp e cified by th e p re fix a rg u m e nt.

S p lit W in d o w

(: STYLE "EMACS ") [ctri/xl|T1

S p lits th e c u rre n t w in d o w in to tw o id e n tic a l
w indow s.

S ta rt K eyb o a rd
M acro

•GLOBAL |Ctrl/X11( |

S ta rts c o lle c tin g ke ystro ke s fo r a ke yb o a rd
m acro, re p la c in g an y un n a m e d ke yb o a rd m acro
th a t a lre a d y e xists.

S ta rt N am ed
K e yb o a rd M acro

None

P ro m p ts fo r a nam e, th e n s ta rts co lle c tin g
ke ystro ke s fo r a ke yb o a rd m acro; th e re s u ltin g
ke yb o a rd m acro is cataloged u n d e r th e nam e you
give and can be tre a te d as a com m and.

S u p p ly E M A C S
P re fix

(: STYLE "EMACS ") fCtHTu]

Sets th e p re fix a rg u m e n t to fo u r i f no p re fix
a rg u m e n t w as d e fin e d , o r to fo u r tim e s its fo rm e r
va lu e i f a p re fix a rg u m e n t w as defined.

S u p p ly P re fix
A rg u m e n t

(: STYLE "EDT Emulation")

P ro m p ts fo r a p re fix a rg u m e n t; i f a p re fix
a rg u m e n t is a lre a d y d e fin e d , m u ltip lie s i t by th e
n u m b e r yo u e nter.

EEHEÜI
(: STYLE "EMACS") |Escape|[CWiT|

T ranspose
P re vio u s
C h a ra cte rs

(: STYLE "EMACS") [ctriTfl

Transposes th e tw o ch a ra cte rs prece d in g th e
cursor.

T ranspose
P re vio u s W ords

(: STYLE "EMACS") |Escape|(T1

Transposes th e w o rd s a t and prece d in g th e
cursor.

°1 »I Pointer button transition: o button up; •button held down; 1 button pressed; f 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)

B -12

Editor Commands and Bindings

Table B-1 (Cont.):

Editor Commands and Key Bindings

N am e

BindLng(s)

D e sc rip tio n

U n d o P re vio u s
Y ank

(:STYLE "EMACS ")| Escape | |ctrl/W|

D eletes th e p re v io u s ly ya n ke d re g io n w ith o u t
p u sh in g i t onto th e k ill rin g ; m ore g e n e ra lly,
deletes th e se le ct re g io n w ith o u t p u s h in g i t onto
th e k ill rin g .

U n s e t S elect
M a rk

(:STYLE "EDT Emulation")
|pfi|ke yp a d f~ l
(:STYLE "EMACS")

C ancels th e c u rre n t select re g io n .

| Escape 11 Ctrl/Space |

U pcase R egion

N one

C hanges a ll a lp h a b e tic ch a ra cte rs in th e c u rre n t
select re g io n to uppercase.

U pcase W ord

(:STYLE "EMACS") lEscapelHD

C hanges a ll a lp h a b e tic ch a ra cte rs in th e w o rd a t
th e cu rso r lo c a tio n to uppercase.

V ie w F ile

(:STYLE "EMACS") [C W X!|CW F|

P ro m p ts fo r a file sp e cifica tio n , th e n reads th e
sp ecified file in to a re a d -o n ly b u ffe r.

W h a t C u rs o r
P o s itio n

(:STYLE "EMACS ") [cffl/xl r-1

D isp la y s in fo rm a tio n a b o u t th e cu rs o r lo c a tio n .

W rite C u rre n t
B u ffe r

(:STYLE "EMACS") [C tF i/X liT I

W rite s o u t th e c u rre n t b u ffe r; creates a new
file ve rs io n o r updates th e L IS P sym bol w hose
fu n c tio n o r va lu e s lo t is b e in g e d ite d .

W rite M o d ifie d
B u ffe rs

(:STYLE "EMACS ") [CWXl ICtrl/MI

P e rfo rm s th e "Write Current Buffer" opera
tio n fo r each b u ffe r th a t has been m o d ifie d .

W rite N am ed F ile

(:STYLE "EMACS") [Ctfi7xl|Ctri/W|

P ro m p ts fo r a file sp e c ific a tio n , th e n creates a
file h a v in g th a t sp e c ific a tio n fro m th e co n te n ts o f
th e c u rre n t b u ffe r.

Y ank

(:STYLE "EMACS") [Ctri/Yj

In s e rts th e c u rre n t k ill- r in g re g io n a t th e cu rso r
lo c a tio n ; in s e rts as m a n y copies as are specified
b y th e p re fix a rg u m e n t.

Y a n k a t P o in te r3

(:STYLE "EMACS") | • ! o |

In s e rts th e c u rre n t k ill- r in g re g io n a t th e p o in te r
cu rso r lo c a tio n .

Y a n k P re vio u s

(:STYLE "EMACS") |EscapeIITI

R otates th e k ill rin g fo rw a rd , th e n in s e rts
th e new c u rre n t k ill- r in g re g io n a t th e cu rso r
lo c a tio n ; in s e rts as m a n y copies as are specified
by th e p re fix a rg u m e n t.

Yank Replace

(: S T Y L E

" S M A C S " ) |Escap»| |ctri/y[

P re vio u s

D eletes the previously yanked region, rotates the
k ill rin g fo rw a rd , a n d in s e rts th e new c u rre n t
k ill- r in g re g io n a t th e cu rs o r lo c a tio n ; in s e rts
as m a n y copies as are specified by th e p re fix
a rg u m e n t.

3Available only in UIS Pointer Syntax.
Pointer button transition: o button up; •button held down; | button pressed; f button released,
pointer movement with buttons in specified state.
Pointer buttons invoke command only when pointer cursor is in the current window.

Editor Commands and Bindings

B-13

Appendix C

Bound Keys and Key Sequences
This appendix lists all the keys and key sequences bound to commands in the
VAX LISP Editor, along with the context in which each binding occurs.
If a key or key sequence is bound in more than one context, all but one of
the bindings are “
shadowed”or inaccessible. The Editor searches through the
contexts in the following order and accepts the first binding it encounters:
1. Current buffer
2. Minor styles active in the current buffer, beginning with the most recently
activated
3. Major style active in the current buffer
4. Global Editor context
The following table also appears in the VAX LISP/VMS Program Development
Guide.
Table C -1 : Editor Key Bindings
Key(s)

Com m and

Context
Single Keys

| Ctri/Space |

( : BUFFER "General Prompting")
( : STYLE "EMACS")

P ro m p t C om plete S trin g
S et S elect M a rk

[Ctrj/Ä]

( : STYLE "EMACS")

B e g in n in g o f L in e

| Ctri/B |

(:STYLE "EMACS")

B a ckw a rd C h a ra cte r

|cm/o|

(:STYLE "EMACS")

D e lete N e x t C h a ra c te r

[OWE]

( : STYLE "EMACS")

E n d o f L in e

|C?j/Fl

( : STYLE "EMACS")

F o rw a rd C h a ra c te r

[cfflröl

( : STYLE "EMACS")

Pause E d ito r

|Ctrl/H| o r | Backspace |

( : STYLE "EDT Emulation")

E D T B ack to S ta rt o f L in e

ffäb] o r |Ctrl/l |

( : STYLE "VAX LISP")

In d e n t L IS P L in e

|C trl/j| o r | Linefeed |

( : BUFFER "General Prompting")
( : STYLE "VAX LISP")
( : STYLE "EDT Emulation")

N ew L in e
N ew L IS P L in e
E D T D e lete P re vio u s W ord

[Ctri/Kl

( : STYLE "EMACS")

K ill L in e

[CWLl

( : STYLE "EMACS")

R e d isp la y Screen

(continued on next page)

Bound Keys and Key Sequences

C-1

Table C-1 (Cont.):

Editor Key Bindings

Key(s)

Context

Command
Single Keys

| Return | OT |Ctrl/M|

( : BUFFER "General Prompting")
( : STYLE "EMACS")
: GLOBAL

P ro m p t Read and V a lid a te
N ew L in e
N ew L in e

| Ctrl/N |

( : STYLE "EMACS")

N e x t L in e

| Ctrl/O |

( : STYLE "EMACS")

O pen L in e

| Ctrl/P |

( : STYLE "EMACS")

P re vio u s L in e

|Ctrl/R|

( : STYLE "EMACS")

B a ckw a rd S earch

[CtrFD

( : STYLE "EMACS")

T ranspose P re vio u s C h a ra cte rs

| Ctrl/U |

( : STYLE "EMACS")
( : STYLE "EDT Emulation")

S u p p ly E M A C S P re fix
E D T D e lete P re vio u s L in e

[CWVl

( : BUFFER "General Prompting")
( : STYLE "EMACS")

P ro m p t S cro ll H e lp W indow
N e x t Screen

1Ctrl/W I

( : STYLE "EMACS")
( : STYLE "EDT Emulation")

K ill R egion
R e d isp la y Screen

jCtrl/Y|

( : STYLE "EMACS")

Y ank

[cWZ\

( : STYLE "EMACS")
: GLOBAL

S cro ll W in d o w D ow n
E xecute N am ed C om m and

IciFiÄ)

( : STYLE "EMACS")

E M A C S F o rw a rd S earch

|CW7|

( : STYLE "VAX LISP")

D escribe W ord

| Delete | OT O

( : STYLE "EMACS")
( : STYLE "EDT Emulation")
: GLOBAL

D e lete P re vio u s C h a ra c te r
D e lete P re vio u s C h a ra c te r
D e lete P re vio u s C h a ra c te r

m
ke yp a d [T ]

( : STYLE "VAX LISP")

In s e rt C lose P a re n a n d M a tch

( : STYLE "EDT Emulation")

E D T B e g in n in g o f L in e

ke yp a d [T ]

( : STYLE "EDT Emulation")

E D T M ove W ord

ke yp a d [7 ]

( : STYLE "EDT Emulation")

E D T E n d o f L in e

ke yp a d [7 ]

(:STYLE "EDT Emulation")

E D T M ove C h a ra cte r

ke yp a d [7 ]

( : STYLE "EDT Emulation")

E D T S et D ire c tio n F o rw a rd

ke yp a d |T ]

( : STYLE "EDT Emulation")

E D T S et D ire c tio n B a ckw a rd

ke yp a d [T ]

( : STYLE "EDT Emulation")

EDT C ut

ke yp a d [7 ]

(:STYLE "EDT Emulation")

E D T M ove Page

ke yp a d [TQ

(:STYLE "EDT Emulation")

E D T S cro ll W indow

ke yp a d [7 ]

(:STYLE "EDT Emulation")

E D T A ppend

keypad□

(:STYLE "EDT Emulation")

S e t S elect M a rk

ke yp a d |Enter[

(:BUFFER "General Prompting")

P ro m p t R ead and V a lid a te

keypad□

(:STYLE "EDT Emulation")

E D T D e lete C h a ra cte r

ke yp a d □

(: STYLE "EDT Emulation")

E D T D e lete W ord

ke yp a d [PFf]

(:BUFFER "General Prompting")
(:STYLE "EDT Emulation"
:GLOBAL

P ro m p t H e lp
H e lp
H e lp

ke yp a d |PF3|

(:STYLE "EDT Emulation")

E D T S earch A g a in

(continued on next page)

C-2

Bound Keys and Key Sequences

Table C-1 (Cont.):

Editor Key Bindings

Key(s)

Context

Com m and
Single Keys

ke yp a d [PF4]

(:STYLE "EDT Emulation")

E D T D e lete L in e

Efl
Si

:GLOBAL

P re vio u s L in e

:GLOBAL

N e x t L in e

:GLOBAL

F o rw a rd C h a ra c te r

:GLOBAL

B a ckw a rd C h a ra c te r

A ll g ra p h ics
ch a ra cte rs

:GLOBAL

S e lf In s e rt

Single Keys (LK201 K eyboard Only)
EH

(:STYLE "EDT Emulation")

E D T B a ck to S ta rt o f L in e

(:STYLE "EDT Emulation")

E D T D e lete P re vio u s W ord

[H iipl

:GLOBAL

H e lp

:GLOBAL

E xe cu te N am ed C om m and

(:STYLE "EDT Emulation")

E D T Q u e ry S earch

| Insert Here |

(: STYLE "EDT Emulation")

E D T P aste

| Remove |

(:STYLE "EDT Emulation")

EDT C ut

|Select|

(: STYLE "EDT Emulation")

E D T S elect

|Prev Screen |

:GLOBAL

P re vio u s Screen

| Next Screen |

:GLOBAL

N e x t Screen

(continued on next page)

Bound Keys and Key Sequences

C-3

Table C-1 (Cont.):

Editor Key Bindings

Key(s)

Context

Com m and
Two-Key Sequences Starting w ith Ctrl/X

fcw/xl|Ctrl/Space1

(:STYLE "VAX LISP")

S elect O u te rm o st F o rm

ICtri/XI|Ctrt/A|

(:STYLE "VAX LISP")

E va lu a te L IS P R egion

[Ctri«|[Ctri/Bl

(:STYLE "EMACS")

L is t B u ffe rs

|Ctri/X||Ctri/D|

(:STYLE "EMACS")

D elete C u rre n t B u ffe r

[CtrPxl[CtriTEl

(:STYLE "EMACS")
:GLOBAL

Ed
E xecute K e yb o a rd M acro

[Cfri/Xl[Ctt/Fl

(:STYLE "EMACS")

V ie w F ile

[ctrwT||täb1 o r
ICtri/XI|Ctri/l|

(:STYLE "EMACS")
(:STYLE "VAX LISP")

In s e rt F ile
In d e n t O u te rm o st F o rm

ICtri/X11Return| o r
ICtrt/X||Ctri/M|

(: STYLE "EMACS")

W rite M o d ifie d B u ffe rs

ICtri/XIICtri/NI

:GLOBAL

N e x t W indow

ICtri/X11Ctrl/R|

(:STYLE "EMACS")
:GLOBAL

R ead F ile
Rem ove C u rre n t W indow

ICtri/X||Ctri/T|

(:STYLE "EMACS")

Show T im e

|CtrW<|[Ctri/Vl

(:STYLE "EMACS")

E d it F ile

ICtri/X||Ctrl/W|

(:STYLE "EMACS")

W rite N am ed F ile

[ctMlIcw/xl

(:STYLE "EMACS")

E xchange P o in t and S elect M a rk

[Ctri/Xl[Ctri/Zl

(:STYLE "EMACS")
:GLOBAL

S h rin k W indow
Pause E d ito r

[CtriÖfim

:GLOBAL

S ta rt K eyb o a rd M acro

[cHxim

:GLOBAL

E n d K eyb o a rd M acro

|Ctri/X||,|

(:STYLE "VAX LISP")

P re vio u s F o rm

Ictrt^jLj

(:STYLE "VAX LISP")

N e x t F o rm

ICtrl/X11 1 |

(:STYLE "EMACS")

Rem ove O th e r W indow s

|Ctri/X||2 |

(•■STYLE "EMACS")

S p lit W indow

|Ctrt/X|| ;|

(:STYLE "VAX LISP")

M ove to L IS P C om m ent

icffi/xim

(:STYLE "VAX LISP")

B e g in n in g o f O u te rm o st F o rm

[cwxim

(:STYLE "VAX LISP")

E n d o f O u te rm o st F o rm

ictriöqm

(: STYLE "EMACS")

W h a t C u rs o r P o s itio n

[Ctt«][Xl
[ctMim

:GLOBAL

H e lp on E d ito r E rro r

:GLOBAL

Q uoted In s e rt

|c5w<l[T1

(:STYLE "EMACS")

S elect B u ffe r

fc5«<im

(:STYLE "EMACS")

Rem ove C u rre n t W indow

[cwgH
icw/xinn

:GLOBAL

E xecute K e yb o a rd M acro

(:STYLE "EMACS")

P re vio u s W indow

[c5w<i[n

(:STYLE "EMACS")

N e x t W indow

[cMlE]
icwxi m

(:STYLE "EMACS")

Q uoted In s e rt

(:STYLE "EMACS")

W rite C u rre n t B u ffe r

fcwocim

(:STYLE "EMACS")

G row W indow

(continued on next page)

C-4

Bound Keys and Key Sequences

Table C-1 (Cont.):

Editor Key Bindings

Key(s)

Context

Com m and

Two-Key Sequences Starting w ith E scape
| Escape 11 Ctrl/Space |

( : STYLE

"EM A CS")

U n s e t S elect M a rk

| Escape | |Ctri/D|

( : STYLE

"EM A CS")

D e le te W hitespace

|Escape] |Ctrl/G|

( : STYLE

"EM A CS")

E x it R ecursive E d it

| Escape| |Ctr1/U|

( : STYLE

"EM A CS")

S u p p ly P re fix A rg u m e n t

| Escape | |Ctrl/V|

( : STYLE

"EM A C S")

Page N e x t W indow

|Escape) |Cfrl/W|

( : STYLE

"EM A CS")

U ndo P re vio u s Y a n k

| Escape | JCtrlA'I

( : STYLE

"EM A CS")

Y a n k P re vio u s R eplace

|Escape) | 1 |

( : STYLE

"EM A CS")

L in e to Top o f W indow

| Escape 11 , |

( : STYLE

"EM A CS")

B e g in n in g o f W indow

| Escape 11 . |

( : STYLE

"EM A CS")

E n d o f W indow

I Escape|[ < |

( : STYLE

"EM A CS")

B e g in n in g o f B u ffe r

1Escape 11 > I

( : STYLE

"EM A CS")

E n d o f B u ffe r

1Escape 11 ? I

( : STYLE

"VAX L I S P " )

A propos W ord

| Escape 11 ] |

( : STYLE

"VAX L I S P " )

C lose O u te rm o st F o rm

| Escape 11 a |

( : STYLE

"EM A CS")

B e g in n in g o f P a ra g ra p h

| Escape11 b |

( : STYLE

"EM A CS")

B a ckw a rd W ord

1Escape11 c I

( : STYLE

"EM A CS")

C a p ita liz e W ord

| Escape 11 d |

( : STYLE "EM A CS")

D e le te N e x t W ord

| Escape11 e |

( : STYLE "EM A CS")

E n d o f P a ra g ra p h

| Escape 11 f |

( : STYLE "EM A CS")

F o rw a rd W ord

| Escape11k |

( : STYLE "EM A CS")

K ill P a ra g ra p h

| Escape 11 1|

( : STYLE "EM A CS")

D owncase W ord

| Escape11n |

( : STYLE "EM A CS")

N e x t P a ra g ra p h

| Escape i m

( : STYLE "EM A CS")

P re vio u s P a ra g ra p h

| Escape | m

( : STYLE "EM A CS")

Q u e ry S earch R eplace

| Escape 11 t |

( : STYLE "EM A CS")

T ranspose P re vio u s W ords

| Escape | | u |

( : STYLE "EM A CS")

U pcase W ord

| Escape 11v |

( : STYLE "EM A CS")

P re vio u s Screen

| Escape11 x |

( : STYLE "EM A CS")

E xecute N am ed C om m and

| Escape 11 y \

( : STYLE "EM A CS")

Y a n k P re vio u s

| Escape|| z |

( : STYLE "EM A CS")

S c ro ll W in d o w U p

| Escape 11Delete | o r

( : STYLE "EM A CS")

D elete P re vio u s W ord

| Escape |

(continued on next page)

Bound K eys and Key S e q u e n c e s

C-5

Table C-1 (Cont.):

Editor Key Bindings

Key(s)

Context

Com m and

Two-Key Sequences Starting w ith Keypad PF1
k e y p a d |PFij |~5~|

(:STYLE "EDT Emulation")

O p e n L in e

k e y p a d |pfi ||~i~|

(:STYLE "EDT Emulation")

E D T C h a n ge C ase

k e y p a d |pfi |[T]

(:STYLE "EDT Emulation")

E D T D e le t e t o E n d o f L in e

k e y p a d [pfT] [T]

(: STYLE "EDT Emulation")

E D T S p e c ia l I n s e r t

k e y p a d |pfi |[~4~|

(:STYLE "EDT Emulation")

E n d o f B u ffe r

k e y p a d |p f i |[~5~|

(:STYLE "EDT Emulation")

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 Emulation")

E D T P a s te

k e y p a d [PFT] [7]

(:STYLE "EDT Emulation")

E x e c u te N a m e d C o m m a n d

k e y p a d [pfi |pi~l

(:STYLE "EDT Emulation")

E D T R e p la c e

k e y p a d |pfi |[7~|

(:STYLE "EDT Emulation")

U n s e t S e le c t M a rk

k e y p a d [pfT| |E n te r |

(:STYLE "EDT Emulation")

E D T S u b s titu te

k e y p a d [PFi| [71

(:STYLE "EDT Emulation")

E D T U n d e le t e C h a r a c te r

k e y p a d |PFi| [~~]

(:STYLE "EDT Emulation")

E D T U n d e le t e W o rd

k e y p a d |PFi| |pfi ]

(:STYLE "EDT Emulation")

S u p p ly P r e fix A r g u m e n t

k e y p a d |pfi |]pf3|

(:BUFFER "General Prompting")

P r o m p t S h o w A lte r n a tiv e s

k e y p a d |pfi ||PF3|

(:STYLE "EDT Emulation")

E D T Q u e r y S e a r ch

k e y p a d [ p f T ] [pf4]

(: STYLE "EDT Emulation")

E D T U n d e le t e L in e

C-6

Bound Keys and Key Sequences

Appendix D

Function Keys and Keypad Keys
This appendix provides information needed to specify the function keys and
keypad keys on Digital keyboards in LISP code. The table below lists the actual
character sequence generated by each function key and keypad key.
You can include these character sequences in a LISP sequence (vector, list, or
string) and pass the LISP sequence as the key-sequence argument in a call to
BIND-COMMAND.

The following table also appears in the VAX LISP /VMS Program Development
Guide.
Table D -1: Characters Generated by Keys
Key

Characters Generated
Num eric K eypad Keys (LK201 and VT100)

keypad [T]

#\ESCAPE #\0 #\p

keypad [7]

#\ESCAPE #\0 #\q

keypad [T]

#\ESCAPE #\0 #\r

keypad |T]

#\ESCAPE #\0 #\s

keypad [7]

#\ESCAPE #\0 #\t

keypad [T]

#\ESCAPE #\0 #\u

keypad [T]

#\ESCAPE #\0 #\v

keypad [7]

#\ESCAPE #\0 #\w

keypad[7]

#\ESCAPE #\0 #\x

keypad [T]

#\ESCAPE #\0 #\y

keypad 0

#\ESCAPE #\0 #\m

keypad□

#\ESCAPE #\0 #\1

keypad [ 7 ]

#\ESCAPE #\0 #\n

keypad |Enter|

#\ESCAPE #\0 #\M

keypad |pfi|

#\ESCAPE #\0 #\p

keypad |PFg|

#\ESCAPE #\0 #\Q

keypad [PF3]

#\ESCAPE #\0 #\R

keypad [PR]

#\ESCAPE #\0 #\S

(continued on next page)

Function Kays and Keypad Keys

D-1

Table D-1 (Cont.):

Characters Generated by Keys

Key

Characters Generated
Arrow Keys (LK201 and VT100)

EÖ
Q
13

[ # \A
# \E S C A P E # \ [ # \ B
# \E S C A P E #\[ # \ C
# \E S C A P E #\[ # \ D
# \E S C A P E # \

Function, HELP, and DO Keys (LK201)

0
0
B
0
EH
Em
EH
EH
EH
[Hiipl(Eisl)
EKEH)
EH
EH
EH
EH

#\[ #\1 #\7 #\~
# \E S C A P E #\[ #\1 #\8 #\~
# \E S C A P E #\[ #\1 #\9 #\~
# \E S C A P E #\[ #\2 #\0 #\~
# \E S C A P E #\[ #\2 #\1 #\~
# \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 #\~
# \E S C A P E #\[ #\2 #\8 #\~
# \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 S C A P E #\[ #\3 #\4 #\~
# \E S C A P E

E diting Keys (LK201)

EHKÜ1)
| Insert Hero I (.|E2|)

|Remove | ( |E3|)
fSeiectl ([E 4 ])
| Prev Screen | ( [E5|)
| Next Screen | ( |E6| )

D-2 Function Keys and Keypad Keys

#\[ #\1 #\~
# \E S C A P E #\[ #\2 #\~
# \E S C A P E #\[ #\3 #\~
# \E S C A P E # \ [ #\4 #\~
# \E S C A P E # \ [ #\5 #\~
# \E S C A P E # \ [ #\6 #\~
# \E S C A P E

Index
A________________________
Anchored window display, 1-2
Attributes, 4-9,6-11 to 6-14, Concepts-3
See also Searching through text
binding, 6-11,6-13
creating, 6-14
provided with VAX LISP, A-2
referencing, 1-10
related functions and variables, A-2
setting values for, 6-11, 6-12

B________________________
BACKWARD-WORD-COMMAND Function, Objects-39
BIND-COMMAND function

command argument, 3-2
context argument, 3-5
key-sequence argument, 3-3
Binding
attributes, 6-11
commands, 3-1
variables, 6-8
Binding contexts
See Contexts
Bindings, 6-7 to 6-15
See also Commands, Attributes, and Editor
variables
finding attribute bindings and values, 6-12
finding Editor variable bindings and values, 6-9
finding key bindings, 6-7
in "EDT Emulation" style, A-16
in "EMACS" style, A-17
in "VAX LISP" style, A-19
BIND-POINTER-COMMAND function
:BUTTON-STATE argument, 3-9
package location, 3-7
pointer-action argument, 3-7
Buffer point
See Buffers
Buffers, Concepts-4
See also Regions and Styles
as a binding context, 1-5, 3-6
buffer point, 4-2, Concepts-4
creating, 6-3
current buffer, Concepts-4
major style, 6-6
making windows onto, 5-23
minor style, 6-6
provided with VAX LISP, A-3
related functions, commands, and variables, A-2

Button state
specifying, 3-9

c________________

Characters, Concepts-5
See also Attributes
accessing, 4-2
binding commands to, 3-3
DEC Multinational Character Set, 3-3, 4-1
deleting, 4-3
inserting, 4-2
window truncation, 5-7
window wrapping, 5-7
Checkpointing subsystem, Concepts-5 to
Concepts-6
Chorded bindings
See BIND-POINTER-COMMAND function
Commands, 2-1 to 2-6, Concepts-6 to
Concepts-7
and context, 2-6
associated functions, 2-1,2-4, 3-3, Objects-29
binding to keys, 3-2
binding to pointer actions, 3-7
categories, 2-12, Concepts-7
documenting, 2-3
invoking, Concepts-6
modular definition, 2-5
naming, 2-2
optional arguments, 2—
3
prefix argument, 2-3, Concepts-7
provided with VAX LISP, A-4
related functions, commands, and variables, A-3
Context-dependent objects, Concepts-17
referencing, 1-10
scope and extent, 1-6
Context-independent objects, Concepts-17
referencing, 1-10
Contexts, 2-6, 3-5 to 3-7, Concepts-7 to
Concepts-10
See also Buffers and Styles
conventions for use, Concepts-9
effect on command behavior, 2-6
search order, 1-5, 3-6, 6-2, 6-4, 6-5, 6-6,
Concepts-8
search order for hook variables, Concepts-12
specifying, 3-5, Concepts-8
subsystem overview, 1-5
Current buffer point
See Buffers and Marks

Index-1

p___________
Data types
See Editor data types
Debugging support, Concepts-10

related functions, commands, and variables,

DESCRIBE-OBJECT-COMMAND function
See "Describe" command

F________________________
A -9

Display, 5-1
See also Windows and Information area
display area, 5-14
available, 5-17
coordinates, 5-14
dimensions, 5—15
reserved, 5-16
display management, 5-1, 5-13, 5-22, 5-24
by window display types, 5-17
prompting window, 5-16
window screen position, 5-22
window size, 5-18
related functions, commands, and variables, A—7
subsystem overview, 1-5
Display operations, 1-5

E___________________________________
EDIT-LISP-OBJECT-COMMAND function
See "Ed" command
EDITOR: package

See Packages
Editor attributes
See Attributes
Editor data types
listed, 1-7

EDITOR-HELP-BUFFER buffer
See "Help" buffer

Editor objects, 1-6 to 1-11
context-dependent, 1-10
referencing, 1-10
context-independent, 1-10
referencing, 1-10
maximizing efficiency, 1-9
named, 1-7
referencing, 1-8
unnamed, 1-7
referencing, 1-8

EDITOR-PROMPTING-BUFFER buffer
See "General Prompting" buffer
EDITOR RECURSIVE ENTRY HOOK Editor
Variable, Objects-102

Editor variables, Concepts-10 to Concepts-11
binding, 6—
8, 6—10, 6—16
creating, 6-10
provided with VAX LISP, A-7
referencing, 1-10
related functions and variables, A-7
setting, 6—8, 6—
9, 6—11
setting the value to a function, 6-9
EMPTY-BUFFER-P Function, Objects-126
EMPTY-REGION-P Function, Objects-127
Errors, 2-7 to 2-9, Concepts-11 to Concepts-12
implementing error responses, 2-7
related functions, commands, and variables, A-9
signaled from LISP, 2-8, Concepts-11
signaled from the Editor, 2-7, Concepts-11

lndex-2

EXIT-EDITOR-COMMAND function
See "E xit" command

Files

See also Checkpointing subsystem
inserting in buffers, 4-6
related functions and commands, A-9
writing buffers to, 4-6
FORWARD-WORD-COMMAND Function, Objects-143
Functions associated with commands
See Commands, associated functions

H________________________
Help
related functions, commands, and variables, A-9
Hooks, 1-6, Concepts-12 to Concepts-13
related functions, A-9
setting, 6-8
style activation, 6-15
Hook variables, Concepts-12
provided with VAX LISP, A-10
using, Concepts-13

I___________________________
Information area, 5-16, Concepts-13 to
Concepts-14
clearing, 5-16
directing output to, 5-16
size, 5-16
Invoking and exiting the Editor
related functions, commands, and variables, A-10

K________________________
Kill ring, 1-6
related commands, A-10

L________________________
Lines, 4-16 to 4-18, Concepts-14
moving by, 4-17
operations on, 4-16
related functions and commands, A-11
testing relative positions, 4-17
LISP syntax
related functions, commands, and variables, A-11

M________________________
Marks, 4-14 to 4—16, Concepts-14 to
Concepts-16
accessing mark positions, 4-17
behavior when searching, 4-11
creating, 4-14
current buffer point, 4-2
defining regions, 4-4, 5-9
making windows at, 5-23
operations on, 4-2
related functions, commands, and variables, A-12
testing relative positions, 4-17
types, 4-14
window display, 5-4
window point, 5-5

Mouse
See Pointing device

N_________________________
Named Editor objects, Concepts-16 to Concepts-17
in string tables, Concepts-16
listed, 1-7
naming, Concepts-16
specifying, 1-7, Concepts-16, Objects-29,
Objects-30

P_________________________
Packages

EDITOR:, 1-11
for user-defined extensions, 1-12
using IN-PACKAGE, 1-12
using package prefixes, 1-11
using USE-PACKAGE, 1-11
Pointer actions, 3-7
Pointer button transitions
DECwindows, 3-8
UIS, 3-8
Pointer cursor movement, 3-8
Pointer-state object
See GET-POINTER-STATE function
Pointing device
See also BIND-POINTER-COMMAND and
GET-POINTER-STATE functions

Searching through text, 4-7
and replacing text, 4—9
by attribute, 4-9
by character positions, 4-7
by pattern, 4-8
related functions, commands, and variables, A-15
Shadowing
See Contexts, search order
Streams, 1-6, Concepts-21
String tables, 1-6, Concepts-21 to Concepts-22
provided with VAX LISP, A-16
related functions, A-15
Style
default major, 1-3
Styles, Concepts-22 to Concepts-24
accessing active styles, 6-6
activating, 6-2, 6-15, 6-18, Concepts-23
by default, 6-3
in a new buffer, 6—3
in an existing buffer, 6-6
major, 6-2, Concepts-23
minor, 6-2, Concepts-23
activation hooks, 6-15
as a binding context, 1-5, 3-6, 6-1, 6-15, 6-16
creating, 6-15, Concepts-13
modifying, 6—7
operations on, 6-2
provided with VAX LISP, A-16
related functions, commands, and variables, A-16

button state, 3-9
button transitions, 3-8
movement of, 3-8
related functions and commands, A-13
state of, 3-10
"Print Representation" attribute, 6-11
Prompting, 2-9 to 2-12, Concepts-17 to
Concepts—19
providing alternatives, 2-11, Concepts-19
providing help, Concepts-19
providing input completion, 2-11, Concepts-18,
Concepts-21
related functions, commands, and variables, A-14
validating user input, 2-11, Concepts-18

T_________________________

R_________________________

V___________________________

Regions, 4-4 to 4-5, Concepts-19 to Concepts-20
buffer regions, 4-4, 4-6, Concepts-4
copying, 4—5
creating, 4-4, 5-9
deleting, 4-5
highlight regions, 5-9, Concepts-20
inserting, 4—4
operations on, 4-4
related functions, commands, and variables, A-14
writing to files, 4-5
Rings, 1-6, Concepts-20
related functions, A-15

Variables
See Editor variables
Virtual displays
compared to Editor windows, 5-1

s___________________
Screen width
changing, 1-3
Scrolling
See Windows

Text operations, 4-1 to 4-2
on a group of characters, 4—4
on characters, 4-2
on lines, 4-16
related data types, 4—1
related functions, commands, and variables, A—19
subsystem overview, 1-4

u_____________________________
Unnamed Editor objects
listed, 1-8

w___________________
Windows, 5-1, Concepts-25 to Concepts-26
See also Display
accessing, 5-2
anchored, 1-2
borders, 5-10,5-18,5-21
compared to virtual displays, 5-1
creating, 5-23
current window, 5-2, 5-23
deleting, 5-24
displaying, 5-21,5-22
display types, 5-3, 5-17, 5-18, 5-21,5-24
anchored, 5-17

Index-3

Windows
display types (cont'd.)
floating, 5-17
labels, 5—10
moving in a buffer, 5-5, 5-6
moving on the screen, 5-20
overlapping,

5 -1 8 ,5 -2 1

position in a buffer, 5—4
position on the screen, 5-19,5-24,5-25

lndex-4

prompting window, 2-9,5-16
related functions, commands, and variables, A-20
removing, 5-23
scrolling, 5-6
size, 5-18, 5-24
truncating text in, 5-7
video rendition, 5-8
window point, 5-5
wrapping text in, 5-7

HOW TO ORDER ADDITIONAL DOCUMENTATION
From

Call

603-884-6660
Alaska, Hawaii,
or New Hampshire
Rest of U.S.A.
and Puerto Rico1

Write
Digital Equipment Corporation
P.O. Box CS2008
Nashua NH 03061

800-DIGITAL

1Prepaid orders from Puerto Rico, call Digital’
s local subsidiary (809-754-7575)

Canada

800-267-6219
(for software
documentation)

Digital Equipment of Canada Ltd.
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6
Attn: Direct Order Desk

613-592-5111
(for hardware
documentation)

Internal orders
(for software
documentation)

—

Internal orders
(for hardware
documentation)

DTN: 234-4323
508-351-4323

Software Supply Business (SSB)
Digital Equipment Corporation
Westminster MA 01473
Publishing & Circulation Services (P&CS)
NR03-1/W3
Digital Equipment Corporation
Northboro MA 01532

v_^

Reader’s Comments

VAX USP/VMS Editor Programming Guide
AA-Y923D-TE

Y o u r com m ents and suggestions w ill h e lp us im p ro v e th e q u a lity o f o u r fu tu re d o cu m e n ta tio n . Please note
th a t th is fo rm is fo r com m ents on d o cu m e n ta tio n only.

I rate this manual’
s:
Accuracy (product works as described)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent
□
□
□
□
□
□
□
□

Good
□
□
□
□
□
□
□
□

Fair
□
□
□
□
□
□
□
□

Poor
□
□
□
□
□
□
□
□

W h a t I lik e b e st a b o u t th is m a n u a l:

W h a t I lik e le a s t a b o u t th is m a n u a l:

I fo u n d th e fo llo w in g e rro rs in th is m a n u a l:
Page

D e s c rip tio n

M y a d d itio n a l com m ents o r suggestions fo r im p ro v in g th is m a n u a l:

Please in d ic a te th e ty p e o f u s e r/re a d e r th a t yo u m o st n e a rly re p re se n t:
□ A d m in is tra tiv e S u p p o rt

□ S c ie n tis t/E n g in e e r

□ C o m p u te r O p e ra to r
□ E d u c a to r/T ra in e r
□ P ro g ra m m e r/A n a ly s t
□ Sales

□ S o ftw a re S u p p o rt
□ S ystem M a n a g e r
□ O th e r (please sp e cify)

N a m e /T itle

___

D e p t.

______

C om pany

_____

_______

D a te

M a ilin g A ddress
Phone
10/87

—

D o N o t T e a r — F old H ere and Tape

SDIDQSO

NO POSTAGE
NECESSARY
IF MAILED
INTHE
UNITED STATES

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
CORPORATE USER PUBLICATIONS
PKO3-1/30D
129 PARKER STREET
MAYNARD, MA 01754-2198

—

Do N ot T e a r — F old Here