GNU Emacs Lisp Reference Manual

This Info file contains edition 2.8 of the GNU Emacs Lisp Reference Manual, corresponding to GNU Emacs version 21.2.

1. Introduction		Introduction and conventions used.
D.1 Emacs Lisp Coding Conventions		Coding conventions for Emacs Lisp.

2. Lisp Data Types		Data types of objects in Emacs Lisp.
3. Numbers		Numbers and arithmetic functions.
4. Strings and Characters		Strings, and functions that work on them.
5. Lists		Lists, cons cells, and related functions.
6. Sequences, Arrays, and Vectors		Lists, strings and vectors are called sequences. Certain functions act on any kind of sequence. The description of vectors is here as well.
7. Hash Tables		Very fast lookup-tables.
8. Symbols		Symbols represent names, uniquely.

9. Evaluation		How Lisp expressions are evaluated.
10. Control Structures		Conditionals, loops, nonlocal exits.
11. Variables		Using symbols in programs to stand for values.
12. Functions		A function is a Lisp program that can be invoked from other functions.
13. Macros		Macros are a way to extend the Lisp language.
14. Writing Customization Definitions		Writing customization declarations.

15. Loading		Reading files of Lisp code into Lisp.
16. Byte Compilation		Compilation makes programs run faster.
17. Advising Emacs Lisp Functions		Adding to the definition of a function.
18. Debugging Lisp Programs		Tools and tips for debugging Lisp programs.

19. Reading and Printing Lisp Objects		Converting Lisp objects to text and back.
20. Minibuffers		Using the minibuffer to read input.
21. Command Loop		How the editor command loop works, and how you can call its subroutines.
22. Keymaps		Defining the bindings from keys to commands.
23. Major and Minor Modes		Defining major and minor modes.
24. Documentation		Writing and using documentation strings.

25. Files		Accessing files.
26. Backups and Auto-Saving		Controlling how backups and auto-save files are made.
27. Buffers		Creating and using buffer objects.
28. Windows		Manipulating windows and displaying buffers.
29. Frames		Making multiple X windows.
30. Positions		Buffer positions and motion functions.
31. Markers		Markers represent positions and update automatically when the text is changed.

32. Text		Examining and changing text in buffers.
33. Non-ASCII Characters		Non-ASCII text in buffers and strings.
34. Searching and Matching		Searching buffers for strings or regexps.
35. Syntax Tables		The syntax table controls word and list parsing.
36. Abbrevs and Abbrev Expansion		How Abbrev mode works, and its data structures.

37. Processes		Running and communicating with subprocesses.
38. Emacs Display		Features for controlling the screen display.
39. Customizing the Calendar and Diary		Customizing the calendar and diary.
40. Operating System Interface		Getting the user id, system type, environment variables, and other such things.

Appendices

A. Emacs 20 Antinews		Info for users downgrading to Emacs 20.
B. GNU Free Documentation License		The license for this documentation
C. GNU General Public License		Conditions for copying and changing GNU Emacs.
D. Tips and Conventions		Advice and coding conventions for Emacs Lisp.
E. GNU Emacs Internals		Building and dumping Emacs; internal data structures.
F. Standard Errors		List of all error symbols.
G. Buffer-Local Variables		List of variables buffer-local in all buffers.
H. Standard Keymaps		List of standard keymaps.
I. Standard Hooks		List of standard hook variables.

Index

Index including concepts, functions, variables, and other terms.

New Symbols Since the Previous Edition

New functions and variables in Emacs 21.

      -- The Detailed Node Listing ---

Here are other nodes that are inferiors of those already listed,
mentioned here so you can get to them in one step:

Introduction

1.1 Caveats		Flaws and a request for help.
1.2 Lisp History		Emacs Lisp is descended from Maclisp.
1.3 Conventions		How the manual is formatted.
1.5 Acknowledgements		The authors, editors, and sponsors of this manual.

Conventions

1.3.1 Some Terms		Explanation of terms we use in this manual.
1.3.2 nil and t		How the symbols nil and t are used.
1.3.3 Evaluation Notation		The format we use for examples of evaluation.
1.3.4 Printing Notation		The format we use for examples that print output.
1.3.5 Error Messages		The format we use for examples of errors.
1.3.6 Buffer Text Notation		The format we use for buffer contents in examples.
1.3.7 Format of Descriptions		Notation for describing functions, variables, etc.

Tips and Conventions

D.1 Emacs Lisp Coding Conventions		Conventions for clean and robust programs.
D.2 Tips for Making Compiled Code Fast		Making compiled code run fast.
D.3 Tips for Documentation Strings		Writing readable documentation strings.
D.4 Tips on Writing Comments		Conventions for writing comments.
D.5 Conventional Headers for Emacs Libraries		Standard headers for library packages.

Format of Descriptions

1.3.7.1 A Sample Function Description
1.3.7.2 A Sample Variable Description

Lisp Data Types

2.1 Printed Representation and Read Syntax		How Lisp objects are represented as text.
2.2 Comments		Comments and their formatting conventions.
2.3 Programming Types		Types found in all Lisp systems.
2.4 Editing Types		Types specific to Emacs.
2.6 Type Predicates		Tests related to types.
2.7 Equality Predicates		Tests of equality between any two objects.

Programming Types

2.3.1 Integer Type		Numbers without fractional parts.
2.3.2 Floating Point Type		Numbers with fractional parts and with a large range.
2.3.3 Character Type		The representation of letters, numbers and control characters.
2.3.5 Sequence Types		Both lists and arrays are classified as sequences.
2.3.6 Cons Cell and List Types		Cons cells, and lists (which are made from cons cells).
2.3.7 Array Type		Arrays include strings and vectors.
2.3.8 String Type		An (efficient) array of characters.
2.3.9 Vector Type		One-dimensional arrays.
2.3.4 Symbol Type		A multi-use object that refers to a function, variable, property list, or itself.
2.3.13 Function Type		A piece of executable code you can call from elsewhere.
2.3.14 Macro Type		A method of expanding an expression into another expression, more fundamental but less pretty.
2.3.15 Primitive Function Type		A function written in C, callable from Lisp.
2.3.16 Byte-Code Function Type		A function written in Lisp, then compiled.
2.3.17 Autoload Type		A type used for automatically loading seldom-used functions.

List Type

2.3.6.1 Dotted Pair Notation		An alternative syntax for lists.
2.3.6.2 Association List Type		A specially constructed list.

Editing Types

2.4.1 Buffer Type		The basic object of editing.
2.4.3 Window Type		What makes buffers visible.
2.4.5 Window Configuration Type		Save what the screen looks like.
2.4.2 Marker Type		A position in a buffer.
2.4.7 Process Type		A process running on the underlying OS.
2.4.8 Stream Type		Receive or send characters.
2.4.9 Keymap Type		What function a keystroke invokes.
2.4.10 Overlay Type		How an overlay is represented.

Numbers

3.1 Integer Basics		Representation and range of integers.
3.2 Floating Point Basics		Representation and range of floating point.
3.3 Type Predicates for Numbers		Testing for numbers.
3.4 Comparison of Numbers		Equality and inequality predicates.
3.6 Arithmetic Operations		How to add, subtract, multiply and divide.
3.8 Bitwise Operations on Integers		Logical and, or, not, shifting.
3.5 Numeric Conversions		Converting float to integer and vice versa.
3.9 Standard Mathematical Functions		Trig, exponential and logarithmic functions.
3.10 Random Numbers		Obtaining random integers, predictable or not.

Strings and Characters

4.1 String and Character Basics		Basic properties of strings and characters.
4.2 The Predicates for Strings		Testing whether an object is a string or char.
4.3 Creating Strings		Functions to allocate new strings.
4.5 Comparison of Characters and Strings		Comparing characters or strings.
4.6 Conversion of Characters and Strings		Converting characters or strings and vice versa.
4.7 Formatting Strings		format: Emacs's analogue of printf.
4.8 Case Conversion in Lisp		Case conversion functions.

Lists

5.1 Lists and Cons Cells		How lists are made out of cons cells.
5.2 Lists as Linked Pairs of Boxes		Graphical notation to explain lists.
5.3 Predicates on Lists		Is this object a list? Comparing two lists.
5.4 Accessing Elements of Lists		Extracting the pieces of a list.
5.5 Building Cons Cells and Lists		Creating list structure.
5.6 Modifying Existing List Structure		Storing new pieces into an existing list.
5.7 Using Lists as Sets		A list can represent a finite mathematical set.
5.8 Association Lists		A list can represent a finite relation or mapping.

Modifying Existing List Structure

5.6.1 Altering List Elements with setcar		Replacing an element in a list.
5.6.2 Altering the CDR of a List		Replacing part of the list backbone. This can be used to remove or add elements.
5.6.3 Functions that Rearrange Lists		Reordering the elements in a list; combining lists.

Sequences, Arrays, and Vectors

6.1 Sequences		Functions that accept any kind of sequence.
6.2 Arrays		Characteristics of arrays in Emacs Lisp.
6.3 Functions that Operate on Arrays		Functions specifically for arrays.
6.4 Vectors		Functions specifically for vectors.

Symbols

8.1 Symbol Components		Symbols have names, values, function definitions and property lists.
8.2 Defining Symbols		A definition says how a symbol will be used.
8.3 Creating and Interning Symbols		How symbols are kept unique.
8.4 Property Lists		Each symbol has a property list for recording miscellaneous information.

Evaluation

9.1 Introduction to Evaluation		Evaluation in the scheme of things.
9.4 Eval		How to invoke the Lisp interpreter explicitly.
9.2 Kinds of Forms		How various sorts of objects are evaluated.
9.3 Quoting		Avoiding evaluation (to put constants in the program).

Kinds of Forms

9.2.1 Self-Evaluating Forms		Forms that evaluate to themselves.
9.2.2 Symbol Forms		Symbols evaluate as variables.
9.2.3 Classification of List Forms		How to distinguish various sorts of list forms.
9.2.5 Evaluation of Function Forms		Forms that call functions.
9.2.6 Lisp Macro Evaluation		Forms that call macros.
9.2.7 Special Forms		"Special forms" are idiosyncratic primitives, most of them extremely important.
9.2.8 Autoloading		Functions set up to load files containing their real definitions.

Control Structures

10.1 Sequencing		Evaluation in textual order.
10.2 Conditionals		if, cond.
10.3 Constructs for Combining Conditions		and, or, not.
10.4 Iteration		while loops.
10.5 Nonlocal Exits		Jumping out of a sequence.

Nonlocal Exits

10.5.1 Explicit Nonlocal Exits: catch and throw		Nonlocal exits for the program's own purposes.
10.5.2 Examples of catch and throw		Showing how such nonlocal exits can be written.
10.5.3 Errors		How errors are signaled and handled.
10.5.4 Cleaning Up from Nonlocal Exits		Arranging to run a cleanup form if an error happens.

Errors

10.5.3.1 How to Signal an Error		How to report an error.
10.5.3.2 How Emacs Processes Errors		What Emacs does when you report an error.
10.5.3.3 Writing Code to Handle Errors		How you can trap errors and continue execution.
10.5.3.4 Error Symbols and Condition Names		How errors are classified for trapping them.

Variables

11.1 Global Variables		Variable values that exist permanently, everywhere.
11.2 Variables that Never Change		Certain "variables" have values that never change.
11.3 Local Variables		Variable values that exist only temporarily.
11.4 When a Variable is "Void"		Symbols that lack values.
11.5 Defining Global Variables		A definition says a symbol is used as a variable.
11.7 Accessing Variable Values		Examining values of variables whose names are known only at run time.
11.8 How to Alter a Variable Value		Storing new values in variables.
11.9 Scoping Rules for Variable Bindings		How Lisp chooses among local and global values.
11.10 Buffer-Local Variables		Variable values in effect only in one buffer.

Scoping Rules for Variable Bindings

11.9.1 Scope		Scope means where in the program a value is visible. Comparison with other languages.
11.9.2 Extent		Extent means how long in time a value exists.
11.9.3 Implementation of Dynamic Scoping		Two ways to implement dynamic scoping.
11.9.4 Proper Use of Dynamic Scoping		How to use dynamic scoping carefully and avoid problems.

Buffer-Local Variables

11.10.1 Introduction to Buffer-Local Variables		Introduction and concepts.
11.10.2 Creating and Deleting Buffer-Local Bindings		Creating and destroying buffer-local bindings.
11.10.3 The Default Value of a Buffer-Local Variable		The default value is seen in buffers that don't have their own buffer-local values.

Functions

12.1 What Is a Function?		Lisp functions vs primitives; terminology.
12.2 Lambda Expressions		How functions are expressed as Lisp objects.
12.3 Naming a Function		A symbol can serve as the name of a function.
12.4 Defining Functions		Lisp expressions for defining functions.
12.5 Calling Functions		How to use an existing function.
12.6 Mapping Functions		Applying a function to each element of a list, etc.
12.7 Anonymous Functions		Lambda-expressions are functions with no names.
12.8 Accessing Function Cell Contents		Accessing or setting the function definition of a symbol.
12.10 Other Topics Related to Functions		Cross-references to specific Lisp primitives that have a special bearing on how functions work.

Lambda Expressions

12.2.1 Components of a Lambda Expression		The parts of a lambda expression.
12.2.2 A Simple Lambda-Expression Example		A simple example.
12.2.3 Other Features of Argument Lists		Details and special features of argument lists.
12.2.4 Documentation Strings of Functions		How to put documentation in a function.

Macros

13.1 A Simple Example of a Macro		A basic example.
13.2 Expansion of a Macro Call		How, when and why macros are expanded.
13.3 Macros and Byte Compilation		How macros are expanded by the compiler.
13.4 Defining Macros		How to write a macro definition.
13.5 Backquote		Easier construction of list structure.
13.6 Common Problems Using Macros		Don't evaluate the macro arguments too many times. Don't hide the user's variables.

Loading

15.1 How Programs Do Loading		The load function and others.
15.4 Autoload		Setting up a function to autoload.
15.6 Features		Loading a library if it isn't already loaded.
15.5 Repeated Loading		Precautions about loading a file twice.

Byte Compilation

16.2 The Compilation Functions		Byte compilation functions.
16.7 Disassembled Byte-Code		Disassembling byte-code; how to read byte-code.

Advising Functions

17.1 A Simple Advice Example		A simple example to explain the basics of advice.
17.2 Defining Advice		Detailed description of defadvice.
17.4 Computed Advice		...is to defadvice as fset is to defun.
17.5 Activation of Advice		Advice doesn't do anything until you activate it.
17.6 Enabling and Disabling Advice		You can enable or disable each piece of advice.
17.7 Preactivation		Preactivation is a way of speeding up the loading of compiled advice.
17.8 Argument Access in Advice		How advice can access the function's arguments.
17.9 Definition of Subr Argument Lists		Accessing arguments when advising a primitive.
17.10 The Combined Definition		How advice is implemented.

Debugging Lisp Programs

18.1 The Lisp Debugger		How the Emacs Lisp debugger is implemented.
18.3 Debugging Invalid Lisp Syntax		How to find syntax errors.
18.4 Debugging Problems in Compilation		How to find errors that show up in byte compilation.
18.2 Edebug		A source-level Emacs Lisp debugger.

                                
The Lisp Debugger

18.1.1 Entering the Debugger on an Error		Entering the debugger when an error happens.
18.1.3 Entering the Debugger on a Function Call		Entering it when a certain function is called.
18.1.4 Explicit Entry to the Debugger		Entering it at a certain point in the program.
18.1.5 Using the Debugger		What the debugger does; what you see while in it.
18.1.6 Debugger Commands		Commands used while in the debugger.
18.1.7 Invoking the Debugger		How to call the function debug.
18.1.8 Internals of the Debugger		Subroutines of the debugger, and global variables.

Debugging Invalid Lisp Syntax

18.3.1 Excess Open Parentheses		How to find a spurious open paren or missing close.
18.3.2 Excess Close Parentheses		How to find a spurious close paren or missing open.

Reading and Printing Lisp Objects

19.1 Introduction to Reading and Printing		Overview of streams, reading and printing.
19.2 Input Streams		Various data types that can be used as input streams.
19.3 Input Functions		Functions to read Lisp objects from text.
19.4 Output Streams		Various data types that can be used as output streams.
19.5 Output Functions		Functions to print Lisp objects as text.

Minibuffers

20.1 Introduction to Minibuffers		Basic information about minibuffers.
20.2 Reading Text Strings with the Minibuffer		How to read a straight text string.
20.3 Reading Lisp Objects with the Minibuffer		How to read a Lisp object or expression.
20.5 Completion		How to invoke and customize completion.
20.6 Yes-or-No Queries		Asking a question with a simple answer.
20.9 Minibuffer Miscellany		Various customization hooks and variables.

Completion

20.5.1 Basic Completion Functions

Low-level functions for completing strings.

                              (These are too low level to use the minibuffer.)

20.5.2 Completion and the Minibuffer		Invoking the minibuffer with completion.
20.5.3 Minibuffer Commands that Do Completion		Minibuffer commands that do completion.
20.5.4 High-Level Completion Functions		Convenient special cases of completion

                              (reading buffer name, file name, etc.)

20.5.5 Reading File Names		Using completion to read file names.
20.5.6 Programmed Completion		Finding the completions for a given file name.

Command Loop

21.1 Command Loop Overview		How the command loop reads commands.
21.2 Defining Commands		Specifying how a function should read arguments.
21.3 Interactive Call		Calling a command, so that it will read arguments.
21.4 Information from the Command Loop		Variables set by the command loop for you to examine.
21.6 Input Events		What input looks like when you read it.
21.7 Reading Input		How to read input events from the keyboard or mouse.
21.9 Waiting for Elapsed Time or Input		Waiting for user input or elapsed time.
21.10 Quitting		How C-g works. How to catch or defer quitting.
21.11 Prefix Command Arguments		How the commands to set prefix args work.
21.12 Recursive Editing		Entering a recursive edit, and why you usually shouldn't.
21.13 Disabling Commands		How the command loop handles disabled commands.
21.14 Command History		How the command history is set up, and how accessed.
21.15 Keyboard Macros		How keyboard macros are implemented.

Defining Commands

21.2.1 Using interactive		General rules for interactive.
21.2.2 Code Characters for interactive		The standard letter-codes for reading arguments in various ways.
21.2.3 Examples of Using interactive		Examples of how to read interactive arguments.

Keymaps

22.1 Keymap Terminology		Definitions of terms pertaining to keymaps.
22.2 Format of Keymaps		What a keymap looks like as a Lisp object.
22.3 Creating Keymaps		Functions to create and copy keymaps.
22.4 Inheritance and Keymaps		How one keymap can inherit the bindings of another keymap.
22.5 Prefix Keys		Defining a key with a keymap as its definition.
22.12 Menu Keymaps		A keymap can define a menu for X or for use from the terminal.
22.6 Active Keymaps		Each buffer has a local keymap to override the standard (global) bindings. Each minor mode can also override them.
22.7 Key Lookup		How extracting elements from keymaps works.
22.8 Functions for Key Lookup		How to request key lookup.
22.9 Changing Key Bindings		Redefining a key in a keymap.
22.10 Commands for Binding Keys		Interactive interfaces for redefining keys.
22.11 Scanning Keymaps		Looking through all keymaps, for printing help.

Major and Minor Modes

23.1 Major Modes		Defining major modes.
23.2 Minor Modes		Defining minor modes.
23.3 Mode Line Format		Customizing the text that appears in the mode line.
23.6 Hooks		How to use hooks; how to write code that provides hooks.

Major Modes

23.1.1 Major Mode Conventions		Coding conventions for keymaps, etc.
23.1.2 Major Mode Examples		Text mode and Lisp modes.
23.1.3 How Emacs Chooses a Major Mode		How Emacs chooses the major mode automatically.
23.1.4 Getting Help about a Major Mode		Finding out how to use a mode.

Minor Modes

23.2.1 Conventions for Writing Minor Modes		Tips for writing a minor mode.
23.2.2 Keymaps and Minor Modes		How a minor mode can have its own keymap.

Mode Line Format

23.3.1 The Data Structure of the Mode Line		The data structure that controls the mode line.
23.3.2 Variables Used in the Mode Line		Variables used in that data structure.
23.3.3 %-Constructs in the Mode Line		Putting information into a mode line.

Documentation

24.1 Documentation Basics		Good style for doc strings. Where to put them. How Emacs stores them.
24.2 Access to Documentation Strings		How Lisp programs can access doc strings.
24.3 Substituting Key Bindings in Documentation		Substituting current key bindings.
24.4 Describing Characters for Help Messages		Making printable descriptions of non-printing characters and key sequences.
24.5 Help Functions		Subroutines used by Emacs help facilities.

Files

25.1 Visiting Files		Reading files into Emacs buffers for editing.
25.2 Saving Buffers		Writing changed buffers back into files.
25.3 Reading from Files		Reading files into other buffers.
25.4 Writing to Files		Writing new files from parts of buffers.
25.5 File Locks		Locking and unlocking files, to prevent simultaneous editing by two people.
25.6 Information about Files		Testing existence, accessibility, size of files.
25.9 Contents of Directories		Getting a list of the files in a directory.
25.7 Changing File Names and Attributes		Renaming files, changing protection, etc.
25.8 File Names		Decomposing and expanding file names.

Visiting Files

25.1.1 Functions for Visiting Files		The usual interface functions for visiting.
25.1.2 Subroutines of Visiting		Lower-level subroutines that they use.

Information about Files

25.6.1 Testing Accessibility		Is a given file readable? Writable?
25.6.2 Distinguishing Kinds of Files		Is it a directory? A link?
25.6.4 Other Information about Files		How large is it? Any other names? Etc.

File Names

25.8.1 File Name Components		The directory part of a file name, and the rest.
25.8.2 Directory Names		A directory's name as a directory is different from its name as a file.
25.8.3 Absolute and Relative File Names		Some file names are relative to a current directory.
25.8.4 Functions that Expand Filenames		Converting relative file names to absolute ones.
25.8.5 Generating Unique File Names		Generating names for temporary files.
25.8.6 File Name Completion		Finding the completions for a given file name.

Backups and Auto-Saving

26.1 Backup Files		How backup files are made; how their names are chosen.
26.2 Auto-Saving		How auto-save files are made; how their names are chosen.
26.3 Reverting		revert-buffer, and how to customize what it does.

Backup Files

26.1.1 Making Backup Files		How Emacs makes backup files, and when.
26.1.2 Backup by Renaming or by Copying?		Two alternatives: renaming the old file or copying it.
26.1.3 Making and Deleting Numbered Backup Files		Keeping multiple backups for each source file.
26.1.4 Naming Backup Files		How backup file names are computed; customization.

Buffers

27.1 Buffer Basics		What is a buffer?
27.3 Buffer Names		Accessing and changing buffer names.
27.4 Buffer File Name		The buffer file name indicates which file is visited.
27.5 Buffer Modification		A buffer is modified if it needs to be saved.
27.6 Comparison of Modification Time		Determining whether the visited file was changed

                              "behind Emacs's back".

27.7 Read-Only Buffers		Modifying text is not allowed in a read-only buffer.
27.8 The Buffer List		How to look at all the existing buffers.
27.9 Creating Buffers		Functions that create buffers.
27.10 Killing Buffers		Buffers exist until explicitly killed.
27.2 The Current Buffer		Designating a buffer as current so primitives will access its contents.

Windows

28.1 Basic Concepts of Emacs Windows		Basic information on using windows.
28.2 Splitting Windows		Splitting one window into two windows.
28.3 Deleting Windows		Deleting a window gives its space to other windows.
28.4 Selecting Windows		The selected window is the one that you edit in.
28.5 Cyclic Ordering of Windows		Moving around the existing windows.
28.6 Buffers and Windows		Each window displays the contents of a buffer.
28.7 Displaying Buffers in Windows		Higher-lever functions for displaying a buffer and choosing a window for it.
28.9 Windows and Point		Each window has its own location of point.
28.10 The Window Start Position		The display-start position controls which text is on-screen in the window.
28.12 Vertical Fractional Scrolling		Moving text up and down in the window.
28.13 Horizontal Scrolling		Moving text sideways on the window.
28.14 The Size of a Window		Accessing the size of a window.
28.15 Changing the Size of a Window		Changing the size of a window.
28.17 Window Configurations		Saving and restoring the state of the screen.

Frames

29.1 Creating Frames		Creating additional frames.
29.2 Multiple Displays		Creating frames on other X displays.
29.3 Frame Parameters		Controlling frame size, position, font, etc.
29.4 Frame Titles		Automatic updating of frame titles.
29.5 Deleting Frames		Frames last until explicitly deleted.
29.6 Finding All Frames		How to examine all existing frames.
29.7 Frames and Windows		A frame contains windows; display of text always works through windows.
29.8 Minibuffers and Frames		How a frame finds the minibuffer to use.
29.9 Input Focus		Specifying the selected frame.
29.10 Visibility of Frames		Frames may be visible or invisible, or icons.
29.11 Raising and Lowering Frames		Raising a frame makes it hide other X windows; lowering it puts it underneath the others.
29.12 Frame Configurations		Saving the state of all frames.
29.13 Mouse Tracking		Getting events that say when the mouse moves.
29.14 Mouse Position		Asking where the mouse is, or moving it.
29.15 Pop-Up Menus		Displaying a menu for the user to select from.
29.16 Dialog Boxes		Displaying a box to ask yes or no.
29.17 Pointer Shapes		Specifying the shape of the mouse pointer.
29.18 Window System Selections		Transferring text to and from other windows.
29.19 Color Names		Getting the definitions of color names.
29.21 X Resources		Getting resource values from the server.
29.22 Display Feature Testing		Determining the features of a terminal.

Positions

30.1 Point		The special position where editing takes place.
30.2 Motion		Changing point.
30.3 Excursions		Temporary motion and buffer changes.
30.4 Narrowing		Restricting editing to a portion of the buffer.

Motion

30.2.1 Motion by Characters		Moving in terms of characters.
30.2.2 Motion by Words		Moving in terms of words.
30.2.3 Motion to an End of the Buffer		Moving to the beginning or end of the buffer.
30.2.4 Motion by Text Lines		Moving in terms of lines of text.
30.2.5 Motion by Screen Lines		Moving in terms of lines as displayed.
30.2.6 Moving over Balanced Expressions		Moving by parsing lists and sexps.
30.2.7 Skipping Characters		Skipping characters belonging to a certain set.

Markers

31.1 Overview of Markers		The components of a marker, and how it relocates.
31.2 Predicates on Markers		Testing whether an object is a marker.
31.3 Functions that Create Markers		Making empty markers or markers at certain places.
31.4 Information from Markers		Finding the marker's buffer or character position.
31.6 Moving Marker Positions		Moving the marker to a new buffer or position.
31.7 The Mark		How "the mark" is implemented with a marker.
31.8 The Region		How to access "the region".

Text

32.1 Examining Text Near Point		Examining text in the vicinity of point.
32.2 Examining Buffer Contents		Examining text in a general fashion.
32.4 Inserting Text		Adding new text to a buffer.
32.5 User-Level Insertion Commands		User-level commands to insert text.
32.6 Deleting Text		Removing text from a buffer.
32.7 User-Level Deletion Commands		User-level commands to delete text.
32.8 The Kill Ring		Where removed text sometimes is saved for later use.
32.9 Undo		Undoing changes to the text of a buffer.
32.14 Auto Filling		How auto-fill mode is implemented to break lines.
32.11 Filling		Functions for explicit filling.
32.12 Margins for Filling		How to specify margins for filling commands.
32.15 Sorting Text		Functions for sorting parts of the buffer.
32.17 Indentation		Functions to insert or adjust indentation.
32.16 Counting Columns		Computing horizontal positions, and using them.
32.18 Case Changes		Case conversion of parts of the buffer.
32.19 Text Properties		Assigning Lisp property lists to text characters.
32.20 Substituting for a Character Code		Replacing a given character wherever it appears.
32.22 Transposition of Text		Swapping two portions of a buffer.
32.21 Registers		How registers are implemented. Accessing the text or position stored in a register.
32.25 Change Hooks		Supplying functions to be run when text is changed.

                              
The Kill Ring

32.8.1 Kill Ring Concepts		What text looks like in the kill ring.
32.8.2 Functions for Killing		Functions that kill text.
32.8.3 Functions for Yanking		Commands that access the kill ring.
32.8.4 Low-Level Kill Ring		Functions and variables for kill ring access.
32.8.5 Internals of the Kill Ring		Variables that hold kill-ring data.

Indentation

32.17.1 Indentation Primitives		Functions used to count and insert indentation.
32.17.2 Indentation Controlled by Major Mode		Customize indentation for different modes.
32.17.3 Indenting an Entire Region		Indent all the lines in a region.
32.17.4 Indentation Relative to Previous Lines		Indent the current line based on previous lines.
32.17.5 Adjustable "Tab Stops"		Adjustable, typewriter-like tab stops.
32.17.6 Indentation-Based Motion Commands		Move to first non-blank character.

Text Properties

32.19.1 Examining Text Properties		Looking at the properties of one character.
32.19.2 Changing Text Properties		Setting the properties of a range of text.
32.19.3 Text Property Search Functions		Searching for where a property changes value.
32.19.4 Properties with Special Meanings		Particular properties with special meanings.
32.19.5 Formatted Text Properties		Properties for representing formatting of text.
32.19.6 Stickiness of Text Properties		How inserted text gets properties from neighboring text.
32.19.7 Saving Text Properties in Files		Saving text properties in files, and reading them back.
32.19.8 Lazy Computation of Text Properties		Computing text properties in a lazy fashion only when text is examined.
32.19.9 Defining Clickable Text		Using text properties to make regions of text do something when you click on them.
32.19.10 Defining and Using Fields		The field property defines fields within the buffer.
32.19.11 Why Text Properties are not Intervals		Why text properties do not use Lisp-visible text intervals.

Non-ASCII Characters

33.1 Text Representations		Unibyte and multibyte representations
33.2 Converting Text Representations		Converting unibyte to multibyte and vice versa.
33.3 Selecting a Representation		Treating a byte sequence as unibyte or multi.
33.4 Character Codes		How unibyte and multibyte relate to codes of individual characters.
33.5 Character Sets		The space of possible characters codes is divided into various character sets.
33.6 Characters and Bytes		More information about multibyte encodings.
33.7 Splitting Characters		Converting a character to its byte sequence.
33.8 Scanning for Character Sets		Which character sets are used in a buffer?
33.9 Translation of Characters		Translation tables are used for conversion.
33.10 Coding Systems		Coding systems are conversions for saving files.
33.11 Input Methods		Input methods allow users to enter various non-ASCII characters without special keyboards.
33.12 Locales		Interacting with the POSIX locale.

Searching and Matching

34.1 Searching for Strings		Search for an exact match.
34.2 Regular Expressions		Describing classes of strings.
34.3 Regular Expression Searching		Searching for a match for a regexp.
34.6 The Match Data		Finding out which part of the text matched various parts of a regexp, after regexp search.
34.6.4 Saving and Restoring the Match Data		Saving and restoring this information.
34.8 Standard Regular Expressions Used in Editing		Useful regexps for finding sentences, pages,...
34.7 Searching and Case		Case-independent or case-significant searching.

Regular Expressions

34.2.1 Syntax of Regular Expressions		Rules for writing regular expressions.
34.2.2 Complex Regexp Example		Illustrates regular expression syntax.

Syntax Tables

35.2 Syntax Descriptors		How characters are classified.
35.3 Syntax Table Functions		How to create, examine and alter syntax tables.
35.6 Parsing Balanced Expressions		Parsing balanced expressions using the syntax table.
35.7 Some Standard Syntax Tables		Syntax tables used by various major modes.
35.8 Syntax Table Internals		How syntax table information is stored.

Syntax Descriptors

35.2.1 Table of Syntax Classes		Table of syntax classes.
35.2.2 Syntax Flags		Additional flags each character can have.

Abbrevs And Abbrev Expansion

36.1 Setting Up Abbrev Mode		Setting up Emacs for abbreviation.
36.2 Abbrev Tables		Creating and working with abbrev tables.
36.3 Defining Abbrevs		Specifying abbreviations and their expansions.
36.4 Saving Abbrevs in Files		Saving abbrevs in files.
36.5 Looking Up and Expanding Abbreviations		Controlling expansion; expansion subroutines.
36.6 Standard Abbrev Tables		Abbrev tables used by various major modes.

Processes

37.1 Functions that Create Subprocesses		Functions that start subprocesses.
37.3 Creating a Synchronous Process		Details of using synchronous subprocesses.
37.4 Creating an Asynchronous Process		Starting up an asynchronous subprocess.
37.5 Deleting Processes		Eliminating an asynchronous subprocess.
37.6 Process Information		Accessing run-status and other attributes.
37.7 Sending Input to Processes		Sending input to an asynchronous subprocess.
37.8 Sending Signals to Processes		Stopping, continuing or interrupting an asynchronous subprocess.
37.9 Receiving Output from Processes		Collecting output from an asynchronous subprocess.
37.10 Sentinels: Detecting Process Status Changes		Sentinels run when process run-status changes.
37.12 Network Connections		Opening network connections.

Receiving Output from Processes

37.9.1 Process Buffers		If no filter, output is put in a buffer.
37.9.2 Process Filter Functions		Filter functions accept output from the process.
37.9.3 Accepting Output from Processes		How to wait until process output arrives.

Operating System Interface

40.1 Starting Up Emacs		Customizing Emacs start-up processing.
40.2 Getting Out of Emacs		How exiting works (permanent or temporary).
40.3 Operating System Environment		Distinguish the name and kind of system.
40.8 Terminal Input		Recording terminal input for debugging.
40.9 Terminal Output		Recording terminal output for debugging.
40.12 Flow Control		How to turn output flow control on or off.
40.13 Batch Mode		Running Emacs without terminal interaction.

Starting Up Emacs

40.1.1 Summary: Sequence of Actions at Startup		Sequence of actions Emacs performs at start-up.
40.1.2 The Init File, `.emacs'		Details on reading the init file (`.emacs').
40.1.3 Terminal-Specific Initialization		How the terminal-specific Lisp file is read.
40.1.4 Command-Line Arguments		How command line arguments are processed, and how you can customize them.

Getting out of Emacs

40.2.1 Killing Emacs		Exiting Emacs irreversibly.
40.2.2 Suspending Emacs		Exiting Emacs reversibly.

Emacs Display

38.1 Refreshing the Screen		Clearing the screen and redrawing everything on it.
38.3 Truncation		Folding or wrapping long text lines.
38.4 The Echo Area		Where messages are displayed.
38.6 Selective Display		Hiding part of the buffer text.
38.7 The Overlay Arrow		Display of an arrow to indicate position.
38.8 Temporary Displays		Displays that go away automatically.
21.9 Waiting for Elapsed Time or Input		Forcing display update and waiting for user.
38.14 Blinking Parentheses		How Emacs shows the matching open parenthesis.
38.16 Usual Display Conventions		How control characters are displayed.
38.18 Beeping		Audible signal to the user.
38.19 Window Systems		Which window system is being used.

GNU Emacs Internals

E.1 Building Emacs		How to preload Lisp libraries into Emacs.
E.2 Pure Storage		A kludge to make preloaded Lisp functions sharable.
E.3 Garbage Collection		Reclaiming space for Lisp objects no longer used.
E.6 Object Internals		Data formats of buffers, windows, processes.
E.5 Writing Emacs Primitives		Writing C code for Emacs.

Object Internals

E.6.1 Buffer Internals		Components of a buffer structure.
E.6.2 Window Internals		Components of a window structure.
E.6.3 Process Internals		Components of a process structure.

1. Introduction

Most of the GNU Emacs text editor is written in the programming language called Emacs Lisp. You can write new code in Emacs Lisp and install it as an extension to the editor. However, Emacs Lisp is more than a mere "extension language"; it is a full computer programming language in its own right. You can use it as you would any other programming language.

Because Emacs Lisp is designed for use in an editor, it has special features for scanning and parsing text as well as features for handling files, buffers, displays, subprocesses, and so on. Emacs Lisp is closely integrated with the editing facilities; thus, editing commands are functions that can also conveniently be called from Lisp programs, and parameters for customization are ordinary Lisp variables.

This manual attempts to be a full description of Emacs Lisp. For a beginner's introduction to Emacs Lisp, see An Introduction to Emacs Lisp Programming, by Bob Chassell, also published by the Free Software Foundation. This manual presumes considerable familiarity with the use of Emacs for editing; see The GNU Emacs Manual for this basic information.

Generally speaking, the earlier chapters describe features of Emacs Lisp that have counterparts in many programming languages, and later chapters describe features that are peculiar to Emacs Lisp or relate specifically to editing.

This is edition 2.8.

1.1 Caveats		Flaws and a request for help.
1.2 Lisp History		Emacs Lisp is descended from Maclisp.
1.3 Conventions		How the manual is formatted.
1.4 Version Information		Which Emacs version is running?
1.5 Acknowledgements		The authors, editors, and sponsors of this manual.

1.1 Caveats

This manual has gone through numerous drafts. It is nearly complete but not flawless. There are a few topics that are not covered, either because we consider them secondary (such as most of the individual modes) or because they are yet to be written. Because we are not able to deal with them completely, we have left out several parts intentionally. This includes most information about usage on VMS.

The manual should be fully correct in what it does cover, and it is therefore open to criticism on anything it says--from specific examples and descriptive text, to the ordering of chapters and sections. If something is confusing, or you find that you have to look at the sources or experiment to learn something not covered in the manual, then perhaps the manual should be fixed. Please let us know.

As you use this manual, we ask that you send corrections as soon as you find them. If you think of a simple, real life example for a function or group of functions, please make an effort to write it up and send it in. Please reference any comments to the node name and function or variable name, as appropriate. Also state the number of the edition you are criticizing.

Please mail comments and corrections to

bug-lisp-manual@gnu.org

We let mail to this list accumulate unread until someone decides to apply the corrections. Months, and sometimes years, go by between updates. So please attach no significance to the lack of a reply--your mail will be acted on in due time. If you want to contact the Emacs maintainers more quickly, send mail to bug-gnu-emacs@gnu.org.

1.2 Lisp History

Lisp (LISt Processing language) was first developed in the late 1950s at the Massachusetts Institute of Technology for research in artificial intelligence. The great power of the Lisp language makes it ideal for other purposes as well, such as writing editing commands.

Dozens of Lisp implementations have been built over the years, each with its own idiosyncrasies. Many of them were inspired by Maclisp, which was written in the 1960s at MIT's Project MAC. Eventually the implementors of the descendants of Maclisp came together and developed a standard for Lisp systems, called Common Lisp. In the meantime, Gerry Sussman and Guy Steele at MIT developed a simplified but very powerful dialect of Lisp, called Scheme.

GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common Lisp. If you know Common Lisp, you will notice many similarities. However, many features of Common Lisp have been omitted or simplified in order to reduce the memory requirements of GNU Emacs. Sometimes the simplifications are so drastic that a Common Lisp user might be very confused. We will occasionally point out how GNU Emacs Lisp differs from Common Lisp. If you don't know Common Lisp, don't worry about it; this manual is self-contained.

A certain amount of Common Lisp emulation is available via the `cl' library. See section `Common Lisp Extension' in Common Lisp Extensions.

Emacs Lisp is not at all influenced by Scheme; but the GNU project has an implementation of Scheme, called Guile. We use Guile in all new GNU software that calls for extensibility.

1.3 Conventions

This section explains the notational conventions that are used in this manual. You may want to skip this section and refer back to it later.

1.3.1 Some Terms		Explanation of terms we use in this manual.
1.3.2 nil and t		How the symbols nil and t are used.
1.3.3 Evaluation Notation		The format we use for examples of evaluation.
1.3.4 Printing Notation		The format we use when examples print text.
1.3.5 Error Messages		The format we use for examples of errors.
1.3.6 Buffer Text Notation		The format we use for buffer contents in examples.
1.3.7 Format of Descriptions		Notation for describing functions, variables, etc.

1.3.1 Some Terms

Throughout this manual, the phrases "the Lisp reader" and "the Lisp printer" refer to those routines in Lisp that convert textual representations of Lisp objects into actual Lisp objects, and vice versa. See section 2.1 Printed Representation and Read Syntax, for more details. You, the person reading this manual, are thought of as "the programmer" and are addressed as "you". "The user" is the person who uses Lisp programs, including those you write.

Examples of Lisp code are formatted like this: (list 1 2 3). Names that represent metasyntactic variables, or arguments to a function being described, are formatted like this: first-number.

1.3.2 nil and t

In Lisp, the symbol nil has three separate meanings: it is a symbol with the name `nil'; it is the logical truth value false; and it is the empty list--the list of zero elements. When used as a variable, nil always has the value nil.

As far as the Lisp reader is concerned, `()' and `nil' are identical: they stand for the same object, the symbol nil. The different ways of writing the symbol are intended entirely for human readers. After the Lisp reader has read either `()' or `nil', there is no way to determine which representation was actually written by the programmer.

In this manual, we use () when we wish to emphasize that it means the empty list, and we use nil when we wish to emphasize that it means the truth value false. That is a good convention to use in Lisp programs also.

(cons 'foo ()) ; Emphasize the empty list (not nil) ; Emphasize the truth value false

In contexts where a truth value is expected, any non-nil value is considered to be true. However, t is the preferred way to represent the truth value true. When you need to choose a value which represents true, and there is no other basis for choosing, use t. The symbol t always has the value t.

In Emacs Lisp, nil and t are special symbols that always evaluate to themselves. This is so that you do not need to quote them to use them as constants in a program. An attempt to change their values results in a setting-constant error. The same is true of any symbol whose name starts with a colon (`:'). See section 11.2 Variables that Never Change.

1.3.3 Evaluation Notation

A Lisp expression that you can evaluate is called a form. Evaluating a form always produces a result, which is a Lisp object. In the examples in this manual, this is indicated with `=>':

(car '(1 2)) => 1

You can read this as "(car '(1 2)) evaluates to 1".

When a form is a macro call, it expands into a new form for Lisp to evaluate. We show the result of the expansion with `==>'. We may or may not show the result of the evaluation of the expanded form.

(third '(a b c)) ==> (car (cdr (cdr '(a b c)))) => c

Sometimes to help describe one form we show another form that produces identical results. The exact equivalence of two forms is indicated with `=='.

(make-sparse-keymap) == (list 'keymap)

1.3.4 Printing Notation

Many of the examples in this manual print text when they are evaluated. If you execute example code in a Lisp Interaction buffer (such as the buffer `*scratch*'), the printed text is inserted into the buffer. If you execute the example by other means (such as by evaluating the function eval-region), the printed text is displayed in the echo area.

Examples in this manual indicate printed text with `-|', irrespective of where that text goes. The value returned by evaluating the form (here bar) follows on a separate line.

(progn (print 'foo) (print 'bar)) -| foo -| bar => bar

1.3.5 Error Messages

Some examples signal errors. This normally displays an error message in the echo area. We show the error message on a line starting with `error-->'. Note that `error-->' itself does not appear in the echo area.

(+ 23 'x) error--> Wrong type argument: number-or-marker-p, x

1.3.6 Buffer Text Notation

Some examples describe modifications to the contents of a buffer, by showing the "before" and "after" versions of the text. These examples show the contents of the buffer in question between two lines of dashes containing the buffer name. In addition, `-!-' indicates the location of point. (The symbol for point, of course, is not part of the text in the buffer; it indicates the place between two characters where point is currently located.)

---------- Buffer: foo ---------- This is the -!-contents of foo. ---------- Buffer: foo ---------- (insert "changed ") => nil ---------- Buffer: foo ---------- This is the changed -!-contents of foo. ---------- Buffer: foo ----------

1.3.7 Format of Descriptions

Functions, variables, macros, commands, user options, and special forms are described in this manual in a uniform format. The first line of a description contains the name of the item followed by its arguments, if any. The category--function, variable, or whatever--appears at the beginning of the line. The description follows on succeeding lines, sometimes with examples.

1.3.7.1 A Sample Function Description		A description of an imaginary function, foo.
1.3.7.2 A Sample Variable Description		A description of an imaginary variable,

                                          electric-future-map.  

1.3.7.1 A Sample Function Description

In a function description, the name of the function being described appears first. It is followed on the same line by a list of argument names. These names are also used in the body of the description, to stand for the values of the arguments.

The appearance of the keyword &optional in the argument list indicates that the subsequent arguments may be omitted (omitted arguments default to nil). Do not write &optional when you call the function.

The keyword &rest (which must be followed by a single argument name) indicates that any number of arguments can follow. The single following argument name will have a value, as a variable, which is a list of all these remaining arguments. Do not write &rest when you call the function.

Here is a description of an imaginary function foo:

Function: foo integer1 &optional integer2 &rest integers

The function foo subtracts integer1 from integer2, then adds all the rest of the arguments to the result. If integer2 is not supplied, then the number 19 is used by default.

(foo 1 5 3 9) => 16 (foo 5) => 14

More generally,

(foo w x y...) == (+ (- x w) y...)

Any argument whose name contains the name of a type (e.g., integer, integer1 or buffer) is expected to be of that type. A plural of a type (such as buffers) often means a list of objects of that type. Arguments named object may be of any type. (See section 2. Lisp Data Types, for a list of Emacs object types.) Arguments with other sorts of names (e.g., new-file) are discussed specifically in the description of the function. In some sections, features common to the arguments of several functions are described at the beginning.

See section 12.2 Lambda Expressions, for a more complete description of optional and rest arguments.

Command, macro, and special form descriptions have the same format, but the word `Function' is replaced by `Command', `Macro', or `Special Form', respectively. Commands are simply functions that may be called interactively; macros process their arguments differently from functions (the arguments are not evaluated), but are presented the same way.

Special form descriptions use a more complex notation to specify optional and repeated arguments because they can break the argument list down into separate arguments in more complicated ways. `[optional-arg]' means that optional-arg is optional and `repeated-args...' stands for zero or more arguments. Parentheses are used when several arguments are grouped into additional levels of list structure. Here is an example:

Special Form: count-loop (var [from to [inc]]) body...

This imaginary special form implements a loop that executes the body forms and then increments the variable var on each iteration. On the first iteration, the variable has the value from; on subsequent iterations, it is incremented by one (or by inc if that is given). The loop exits before executing body if var equals to. Here is an example:

(count-loop (i 0 10) (prin1 i) (princ " ") (prin1 (aref vector i)) (terpri))

If from and to are omitted, var is bound to nil before the loop begins, and the loop exits if var is non-nil at the beginning of an iteration. Here is an example:

(count-loop (done) (if (pending) (fixit) (setq done t)))

In this special form, the arguments from and to are optional, but must both be present or both absent. If they are present, inc may optionally be specified as well. These arguments are grouped with the argument var into a list, to distinguish them from body, which includes all remaining elements of the form.

1.3.7.2 A Sample Variable Description

A variable is a name that can hold a value. Although any variable can be set by the user, certain variables that exist specifically so that users can change them are called user options. Ordinary variables and user options are described using a format like that for functions except that there are no arguments.

Here is a description of the imaginary electric-future-map variable.

Variable: electric-future-map

The value of this variable is a full keymap used by Electric Command Future mode. The functions in this map allow you to edit commands you have not yet thought about executing.

User option descriptions have the same format, but `Variable' is replaced by `User Option'.

1.4 Version Information

These facilities provide information about which version of Emacs is in use.

Command: emacs-version

This function returns a string describing the version of Emacs that is running. It is useful to include this string in bug reports.

(emacs-version) => "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit) of Sat Feb 14 1998 on psilocin.gnu.org"

Called interactively, the function prints the same information in the echo area.

Variable: emacs-build-time

The value of this variable indicates the time at which Emacs was built at the local site. It is a list of three integers, like the value of current-time (see section 40.5 Time of Day).

emacs-build-time => (13623 62065 344633)

Variable: emacs-version

The value of this variable is the version of Emacs being run. It is a string such as "20.3.1". The last number in this string is not really part of the Emacs release version number; it is incremented each time you build Emacs in any given directory. A value with four numeric components, such as "20.3.9.1", indicates an unreleased test version.

The following two variables have existed since Emacs version 19.23:

Variable: emacs-major-version

The major version number of Emacs, as an integer. For Emacs version 20.3, the value is 20.

Variable: emacs-minor-version

The minor version number of Emacs, as an integer. For Emacs version 20.3, the value is 3.

1.5 Acknowledgements

This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, Richard M. Stallman and Chris Welty, the volunteers of the GNU manual group, in an effort extending over several years. Robert J. Chassell helped to review and edit the manual, with the support of the Defense Advanced Research Projects Agency, ARPA Order 6082, arranged by Warren A. Hunt, Jr. of Computational Logic, Inc.

Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Per Starbäck, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.

2. Lisp Data Types

A Lisp object is a piece of data used and manipulated by Lisp programs. For our purposes, a type or data type is a set of possible objects.

Every object belongs to at least one type. Objects of the same type have similar structures and may usually be used in the same contexts. Types can overlap, and objects can belong to two or more types. Consequently, we can ask whether an object belongs to a particular type, but not for "the" type of an object.

A few fundamental object types are built into Emacs. These, from which all other types are constructed, are called primitive types. Each object belongs to one and only one primitive type. These types include integer, float, cons, symbol, string, vector, hash-table, subr, and byte-code function, plus several special types, such as buffer, that are related to editing. (See section 2.4 Editing Types.)

Each primitive type has a corresponding Lisp function that checks whether an object is a member of that type.

Note that Lisp is unlike many other languages in that Lisp objects are self-typing: the primitive type of the object is implicit in the object itself. For example, if an object is a vector, nothing can treat it as a number; Lisp knows it is a vector, not a number.

In most languages, the programmer must declare the data type of each variable, and the type is known by the compiler but not represented in the data. Such type declarations do not exist in Emacs Lisp. A Lisp variable can have any type of value, and it remembers whatever value you store in it, type and all.

This chapter describes the purpose, printed representation, and read syntax of each of the standard types in GNU Emacs Lisp. Details on how to use these types can be found in later chapters.

2.1 Printed Representation and Read Syntax		How Lisp objects are represented as text.
2.2 Comments		Comments and their formatting conventions.
2.3 Programming Types		Types found in all Lisp systems.
2.4 Editing Types		Types specific to Emacs.
2.5 Read Syntax for Circular Objects		Read syntax for circular structure.
2.6 Type Predicates		Tests related to types.
2.7 Equality Predicates		Tests of equality between any two objects.

2.1 Printed Representation and Read Syntax

The printed representation of an object is the format of the output generated by the Lisp printer (the function prin1) for that object. The read syntax of an object is the format of the input accepted by the Lisp reader (the function read) for that object. See section 19. Reading and Printing Lisp Objects.

Most objects have more than one possible read syntax. Some types of object have no read syntax, since it may not make sense to enter objects of these types directly in a Lisp program. Except for these cases, the printed representation of an object is also a read syntax for it.

In other languages, an expression is text; it has no other form. In Lisp, an expression is primarily a Lisp object and only secondarily the text that is the object's read syntax. Often there is no need to emphasize this distinction, but you must keep it in the back of your mind, or you will occasionally be very confused.

Every type has a printed representation. Some types have no read syntax--for example, the buffer type has none. Objects of these types are printed in hash notation: the characters `#<' followed by a descriptive string (typically the type name followed by the name of the object), and closed with a matching `>'. Hash notation cannot be read at all, so the Lisp reader signals the error invalid-read-syntax whenever it encounters `#<'.

(current-buffer) => #<buffer objects.texi>

When you evaluate an expression interactively, the Lisp interpreter first reads the textual representation of it, producing a Lisp object, and then evaluates that object (see section 9. Evaluation). However, evaluation and reading are separate activities. Reading returns the Lisp object represented by the text that is read; the object may or may not be evaluated later. See section 19.3 Input Functions, for a description of read, the basic function for reading objects.

2.2 Comments

A comment is text that is written in a program only for the sake of humans that read the program, and that has no effect on the meaning of the program. In Lisp, a semicolon (`;') starts a comment if it is not within a string or character constant. The comment continues to the end of line. The Lisp reader discards comments; they do not become part of the Lisp objects which represent the program within the Lisp system.

The `#@count' construct, which skips the next count characters, is useful for program-generated comments containing binary data. The Emacs Lisp byte compiler uses this in its output files (see section 16. Byte Compilation). It isn't meant for source files, however.

See section D.4 Tips on Writing Comments, for conventions for formatting comments.

2.3 Programming Types

There are two general categories of types in Emacs Lisp: those having to do with Lisp programming, and those having to do with editing. The former exist in many Lisp implementations, in one form or another. The latter are unique to Emacs Lisp.

2.3.1 Integer Type		Numbers without fractional parts.
2.3.2 Floating Point Type		Numbers with fractional parts and with a large range.
2.3.3 Character Type		The representation of letters, numbers and control characters.
2.3.4 Symbol Type		A multi-use object that refers to a function, variable, or property list, and has a unique identity.
2.3.5 Sequence Types		Both lists and arrays are classified as sequences.
2.3.6 Cons Cell and List Types		Cons cells, and lists (which are made from cons cells).
2.3.7 Array Type		Arrays include strings and vectors.
2.3.8 String Type		An (efficient) array of characters.
2.3.9 Vector Type		One-dimensional arrays.
2.3.10 Char-Table Type		One-dimensional sparse arrays indexed by characters.
2.3.11 Bool-Vector Type		One-dimensional arrays of t or nil.
2.3.12 Hash Table Type		Super-fast lookup tables.
2.3.13 Function Type		A piece of executable code you can call from elsewhere.
2.3.14 Macro Type		A method of expanding an expression into another expression, more fundamental but less pretty.
2.3.15 Primitive Function Type		A function written in C, callable from Lisp.
2.3.16 Byte-Code Function Type		A function written in Lisp, then compiled.
2.3.17 Autoload Type		A type used for automatically loading seldom-used functions.

2.3.1 Integer Type

The range of values for integers in Emacs Lisp is -134217728 to 134217727 (28 bits; i.e., -2**27 to 2**27 - 1) on most machines. (Some machines may provide a wider range.) It is important to note that the Emacs Lisp arithmetic functions do not check for overflow. Thus (1+ 134217727) is -134217728 on most machines.

The read syntax for integers is a sequence of (base ten) digits with an optional sign at the beginning and an optional period at the end. The printed representation produced by the Lisp interpreter never has a leading `+' or a final `.'.

-1 ; The integer -1. 1 ; The integer 1. 1. ; Also the integer 1. +1 ; Also the integer 1. 268435457 ; Also the integer 1 on a 28-bit implementation.

See section 3. Numbers, for more information.

2.3.2 Floating Point Type

Floating point numbers are the computer equivalent of scientific notation. The precise number of significant figures and the range of possible exponents is machine-specific; Emacs always uses the C data type double to store the value.

The printed representation for floating point numbers requires either a decimal point (with at least one digit following), an exponent, or both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4' are five ways of writing a floating point number whose value is 1500. They are all equivalent.

See section 3. Numbers, for more information.

2.3.3 Character Type

A character in Emacs Lisp is nothing more than an integer. In other words, characters are represented by their character codes. For example, the character A is represented as the integer 65.

Individual characters are not often used in programs. It is far more common to work with strings, which are sequences composed of characters. See section 2.3.8 String Type.

Characters in strings, buffers, and files are currently limited to the range of 0 to 524287--nineteen bits. But not all values in that range are valid character codes. Codes 0 through 127 are ASCII codes; the rest are non-ASCII (see section 33. Non-ASCII Characters). Characters that represent keyboard input have a much wider range, to encode modifier keys such as Control, Meta and Shift.

Since characters are really integers, the printed representation of a character is a decimal number. This is also a possible read syntax for a character, but writing characters that way in Lisp programs is a very bad idea. You should always use the special read syntax formats that Emacs Lisp provides for characters. These syntax formats start with a question mark.

The usual read syntax for alphanumeric characters is a question mark followed by the character; thus, `?A' for the character A, `?B' for the character B, and `?a' for the character a.

For example:

?Q => 81 ?q => 113

You can use the same syntax for punctuation characters, but it is often a good idea to add a `\' so that the Emacs commands for editing Lisp code don't get confused. For example, `?\ ' is the way to write the space character. If the character is `\', you must use a second `\' to quote it: `?\\'.

You can express the characters Control-g, backspace, tab, newline, vertical tab, formfeed, return, del, and escape as `?\a', `?\b', `?\t', `?\n', `?\v', `?\f', `?\r', `?\d', and `?\e', respectively. Thus,

?\a => 7 ; C-g ?\b => 8 ; backspace, BS, C-h ?\t => 9 ; tab, TAB, C-i ?\n => 10 ; newline, C-j ?\v => 11 ; vertical tab, C-k ?\f => 12 ; formfeed character, C-l ?\r => 13 ; carriage return, RET, C-m ?\e => 27 ; escape character, ESC, C-[ ?\\ => 92 ; backslash character, \ ?\d => 127 ; delete character, DEL

These sequences which start with backslash are also known as escape sequences, because backslash plays the role of an escape character; this usage has nothing to do with the character ESC.

Control characters may be represented using yet another read syntax. This consists of a question mark followed by a backslash, caret, and the corresponding non-control character, in either upper or lower case. For example, both `?\^I' and `?\^i' are valid read syntax for the character C-i, the character whose value is 9.

Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to `?\^I' and to `?\^i':

?\^I => 9 ?\C-I => 9

In strings and buffers, the only control characters allowed are those that exist in ASCII; but for keyboard input purposes, you can turn any character into a control character with `C-'. The character codes for these non-ASCII control characters include the 2**26 bit as well as the code for the corresponding non-control character. Ordinary terminals have no way of generating non-ASCII control characters, but you can generate them straightforwardly using X and other window systems.

For historical reasons, Emacs treats the DEL character as the control equivalent of ?:

?\^? => 127 ?\C-? => 127

As a result, it is currently not possible to represent the character Control-?, which is a meaningful input character under X, using `\C-'. It is not easy to change this, as various Lisp files refer to DEL in this way.

For representing control characters to be found in files or strings, we recommend the `^' syntax; for control characters in keyboard input, we prefer the `C-' syntax. Which one you use does not affect the meaning of the program, but may guide the understanding of people who read it.

A meta character is a character typed with the META modifier key. The integer that represents such a character has the 2**27 bit set (which on most machines makes it a negative number). We use high bits for this and other modifiers to make possible a wide range of basic character codes.

In a string, the 2**7 bit attached to an ASCII character indicates a meta character; thus, the meta characters that can fit in a string have codes in the range from 128 to 255, and are the meta versions of the ordinary ASCII characters. (In Emacs versions 18 and older, this convention was used for characters outside of strings as well.)

The read syntax for meta characters uses `\M-'. For example, `?\M-A' stands for M-A. You can use `\M-' together with octal character codes (see below), with `\C-', or with any other syntax for a character. Thus, you can write M-A as `?\M-A', or as `?\M-\101'. Likewise, you can write C-M-b as `?\M-\C-b', `?\C-\M-b', or `?\M-\002'.

The case of a graphic character is indicated by its character code; for example, ASCII distinguishes between the characters `a' and `A'. But ASCII has no way to represent whether a control character is upper case or lower case. Emacs uses the 2**25 bit to indicate that the shift key was used in typing a control character. This distinction is possible only when you use X terminals or other special terminals; ordinary terminals do not report the distinction to the computer in any way. The Lisp syntax for the shift bit is `\S-'; thus, `?\C-\S-o' or `?\C-\S-O' represents the shifted-control-o character.

The X Window System defines three other modifier bits that can be set in a character: hyper, super and alt. The syntaxes for these bits are `\H-', `\s-' and `\A-'. (Case is significant in these prefixes.) Thus, `?\H-\M-\A-x' represents Alt-Hyper-Meta-x. Numerically, the bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.

Finally, the most general read syntax for a character represents the character code in either octal or hex. To use octal, write a question mark followed by a backslash and the octal character code (up to three octal digits); thus, `?\101' for the character A, `?\001' for the character C-a, and ?\002 for the character C-b. Although this syntax can represent any ASCII character, it is preferred only when the precise octal value is more important than the ASCII representation.

?\012 => 10 ?\n => 10 ?\C-j => 10 ?\101 => 65 ?A => 65

To use hex, write a question mark followed by a backslash, `x', and the hexadecimal character code. You can use any number of hex digits, so you can represent any character code in this way. Thus, `?\x41' for the character A, `?\x1' for the character C-a, and ?\x8e0 for the Latin-1 character `a' with grave accent.

A backslash is allowed, and harmless, preceding any character without a special escape meaning; thus, `?\+' is equivalent to `?+'. There is no reason to add a backslash before most characters. However, you should add a backslash before any of the characters `()\|;'`"#.,' to avoid confusing the Emacs commands for editing Lisp code. Also add a backslash before whitespace characters such as space, tab, newline and formfeed. However, it is cleaner to use one of the easily readable escape sequences, such as `\t', instead of an actual whitespace character such as a tab.

2.3.4 Symbol Type

A symbol in GNU Emacs Lisp is an object with a name. The symbol name serves as the printed representation of the symbol. In ordinary use, the name is unique--no two symbols have the same name.

A symbol can serve as a variable, as a function name, or to hold a property list. Or it may serve only to be distinct from all other Lisp objects, so that its presence in a data structure may be recognized reliably. In a given context, usually only one of these uses is intended. But you can use one symbol in all of these ways, independently.

A symbol whose name starts with a colon (`:') is called a keyword symbol. These symbols automatically act as constants, and are normally used only by comparing an unknown symbol with a few specific alternatives.

A symbol name can contain any characters whatever. Most symbol names are written with letters, digits, and the punctuation characters `-+=*/'. Such names require no special punctuation; the characters of the name suffice as long as the name does not look like a number. (If it does, write a `\' at the beginning of the name to force interpretation as a symbol.) The characters `_~!@$%^&:<>{}?' are less often used but also require no special punctuation. Any other characters may be included in a symbol's name by escaping them with a backslash. In contrast to its use in strings, however, a backslash in the name of a symbol simply quotes the single character that follows the backslash. For example, in a string, `\t' represents a tab character; in the name of a symbol, however, `\t' merely quotes the letter `t'. To have a symbol with a tab character in its name, you must actually use a tab (preceded with a backslash). But it's rare to do such a thing.

Common Lisp note: In Common Lisp, lower case letters are always "folded" to upper case, unless they are explicitly escaped. In Emacs Lisp, upper case and lower case letters are distinct.

Here are several examples of symbol names. Note that the `+' in the fifth example is escaped to prevent it from being read as a number. This is not necessary in the sixth example because the rest of the name makes it invalid as a number.

foo ; A symbol named `foo'. FOO ; A symbol named `FOO', different from `foo'. char-to-string ; A symbol named `char-to-string'. 1+ ; A symbol named `1+' ; (not `+1', which is an integer). \+1 ; A symbol named `+1' ; (not a very readable name). \(*\ 1\ 2\) ; A symbol named `(* 1 2)' (a worse name). +-*/_~!@$%^&=:<>{} ; A symbol named `+-*/_~!@$%^&=:<>{}'. ; These characters need not be escaped.

Normally the Lisp reader interns all symbols (see section 8.3 Creating and Interning Symbols). To prevent interning, you can write `#:' before the name of the symbol.

2.3.5 Sequence Types

A sequence is a Lisp object that represents an ordered set of elements. There are two kinds of sequence in Emacs Lisp, lists and arrays. Thus, an object of type list or of type array is also considered a sequence.

Arrays are further subdivided into strings, vectors, char-tables and bool-vectors. Vectors can hold elements of any type, but string elements must be characters, and bool-vector elements must be t or nil. Char-tables are like vectors except that they are indexed by any valid character code. The characters in a string can have text properties like characters in a buffer (see section 32.19 Text Properties), but vectors do not support text properties, even when their elements happen to be characters.

Lists, strings and the other array types are different, but they have important similarities. For example, all have a length l, and all have elements which can be indexed from zero to l minus one. Several functions, called sequence functions, accept any kind of sequence. For example, the function elt can be used to extract an element of a sequence, given its index. See section 6. Sequences, Arrays, and Vectors.

It is generally impossible to read the same sequence twice, since sequences are always created anew upon reading. If you read the read syntax for a sequence twice, you get two sequences with equal contents. There is one exception: the empty list () always stands for the same object, nil.

2.3.6 Cons Cell and List Types

A cons cell is an object that consists of two slots, called the CAR slot and the CDR slot. Each slot can hold or refer to any Lisp object. We also say that "the CAR of this cons cell is" whatever object its CAR slot currently holds, and likewise for the CDR.

A note to C programmers: in Lisp, we do not distinguish between "holding" a value and "pointing to" the value, because pointers in Lisp are implicit.

A list is a series of cons cells, linked together so that the CDR slot of each cons cell holds either the next cons cell or the empty list. See section 5. Lists, for functions that work on lists. Because most cons cells are used as part of lists, the phrase list structure has come to refer to any structure made out of cons cells.

The names CAR and CDR derive from the history of Lisp. The original Lisp implementation ran on an IBM 704 computer which divided words into two parts, called the "address" part and the "decrement"; CAR was an instruction to extract the contents of the address part of a register, and CDR an instruction to extract the contents of the decrement. By contrast, "cons cells" are named for the function cons that creates them, which in turn was named for its purpose, the construction of cells.

Because cons cells are so central to Lisp, we also have a word for "an object which is not a cons cell". These objects are called atoms.

The read syntax and printed representation for lists are identical, and consist of a left parenthesis, an arbitrary number of elements, and a right parenthesis.

Upon reading, each object inside the parentheses becomes an element of the list. That is, a cons cell is made for each element. The CAR slot of the cons cell holds the element, and its CDR slot refers to the next cons cell of the list, which holds the next element in the list. The CDR slot of the last cons cell is set to hold nil.

A list can be illustrated by a diagram in which the cons cells are shown as pairs of boxes, like dominoes. (The Lisp reader cannot read such an illustration; unlike the textual notation, which can be understood by both humans and computers, the box illustrations can be understood only by humans.) This picture represents the three-element list (rose violet buttercup):

--- --- --- --- --- --- | | |--> | | |--> | | |--> nil --- --- --- --- --- --- | | | | | | --> rose --> violet --> buttercup

In this diagram, each box represents a slot that can hold or refer to any Lisp object. Each pair of boxes represents a cons cell. Each arrow represents a reference to a Lisp object, either an atom or another cons cell.

In this example, the first box, which holds the CAR of the first cons cell, refers to or "holds" rose (a symbol). The second box, holding the CDR of the first cons cell, refers to the next pair of boxes, the second cons cell. The CAR of the second cons cell is violet, and its CDR is the third cons cell. The CDR of the third (and last) cons cell is nil.

Here is another diagram of the same list, (rose violet buttercup), sketched in a different manner:

--------------- ---------------- ------------------- | car | cdr | | car | cdr | | car | cdr | | rose | o-------->| violet | o-------->| buttercup | nil | | | | | | | | | | --------------- ---------------- -------------------

A list with no elements in it is the empty list; it is identical to the symbol nil. In other words, nil is both a symbol and a list.

Here are examples of lists written in Lisp syntax:

(A 2 "A") ; A list of three elements. () ; A list of no elements (the empty list). nil ; A list of no elements (the empty list). ("A ()") ; A list of one element: the string "A ()". (A ()) ; A list of two elements: A and the empty list. (A nil) ; Equivalent to the previous. ((A B C)) ; A list of one element ; (which is a list of three elements).

Here is the list (A ()), or equivalently (A nil), depicted with boxes and arrows:

--- --- --- --- | | |--> | | |--> nil --- --- --- --- | | | | --> A --> nil

2.3.6.1 Dotted Pair Notation		An alternative syntax for lists.
2.3.6.2 Association List Type		A specially constructed list.

2.3.6.1 Dotted Pair Notation

Dotted pair notation is an alternative syntax for cons cells that represents the CAR and CDR explicitly. In this syntax, (a . b) stands for a cons cell whose CAR is the object a, and whose CDR is the object b. Dotted pair notation is therefore more general than list syntax. In the dotted pair notation, the list `(1 2 3)' is written as `(1 . (2 . (3 . nil)))'. For nil-terminated lists, you can use either notation, but list notation is usually clearer and more convenient. When printing a list, the dotted pair notation is only used if the CDR of a cons cell is not a list.

Here's an example using boxes to illustrate dotted pair notation. This example shows the pair (rose . violet):

--- --- | | |--> violet --- --- | | --> rose

You can combine dotted pair notation with list notation to represent conveniently a chain of cons cells with a non-nil final CDR. You write a dot after the last element of the list, followed by the CDR of the final cons cell. For example, (rose violet . buttercup) is equivalent to (rose . (violet . buttercup)). The object looks like this:

--- --- --- --- | | |--> | | |--> buttercup --- --- --- --- | | | | --> rose --> violet

The syntax (rose . violet . buttercup) is invalid because there is nothing that it could mean. If anything, it would say to put buttercup in the CDR of a cons cell whose CDR is already used for violet.

The list (rose violet) is equivalent to (rose . (violet)), and looks like this:

--- --- --- --- | | |--> | | |--> nil --- --- --- --- | | | | --> rose --> violet

Similarly, the three-element list (rose violet buttercup) is equivalent to (rose . (violet . (buttercup))). It looks like this:

--- --- --- --- --- --- | | |--> | | |--> | | |--> nil --- --- --- --- --- --- | | | | | | --> rose --> violet --> buttercup

2.3.6.2 Association List Type

An association list or alist is a specially-constructed list whose elements are cons cells. In each element, the CAR is considered a key, and the CDR is considered an associated value. (In some cases, the associated value is stored in the CAR of the CDR.) Association lists are often used as stacks, since it is easy to add or remove associations at the front of the list.

For example,

(setq alist-of-colors '((rose . red) (lily . white) (buttercup . yellow)))

sets the variable alist-of-colors to an alist of three elements. In the first element, rose is the key and red is the value.

See section 5.8 Association Lists, for a further explanation of alists and for functions that work on alists. See section 7. Hash Tables, for another kind of lookup table, which is much faster for handling a large number of keys.

2.3.7 Array Type

An array is composed of an arbitrary number of slots for holding or referring to other Lisp objects, arranged in a contiguous block of memory. Accessing any element of an array takes approximately the same amount of time. In contrast, accessing an element of a list requires time proportional to the position of the element in the list. (Elements at the end of a list take longer to access than elements at the beginning of a list.)

Emacs defines four types of array: strings, vectors, bool-vectors, and char-tables.

A string is an array of characters and a vector is an array of arbitrary objects. A bool-vector can hold only t or nil. These kinds of array may have any length up to the largest integer. Char-tables are sparse arrays indexed by any valid character code; they can hold arbitrary objects.

The first element of an array has index zero, the second element has index 1, and so on. This is called zero-origin indexing. For example, an array of four elements has indices 0, 1, 2, and 3. The largest possible index value is one less than the length of the array. Once an array is created, its length is fixed.

All Emacs Lisp arrays are one-dimensional. (Most other programming languages support multidimensional arrays, but they are not essential; you can get the same effect with an array of arrays.) Each type of array has its own read syntax; see the following sections for details.

The array type is contained in the sequence type and contains the string type, the vector type, the bool-vector type, and the char-table type.

2.3.8 String Type

A string is an array of characters. Strings are used for many purposes in Emacs, as can be expected in a text editor; for example, as the names of Lisp symbols, as messages for the user, and to represent text extracted from buffers. Strings in Lisp are constants: evaluation of a string returns the same string.

See section 4. Strings and Characters, for functions that operate on strings.

2.3.8.1 Syntax for Strings
2.3.8.2 Non-ASCII Characters in Strings
2.3.8.3 Nonprinting Characters in Strings
2.3.8.4 Text Properties in Strings

2.3.8.1 Syntax for Strings

The read syntax for strings is a double-quote, an arbitrary number of characters, and another double-quote, "like this". To include a double-quote in a string, precede it with a backslash; thus, "\"" is a string containing just a single double-quote character. Likewise, you can include a backslash by preceding it with another backslash, like this: "this \\ is a single embedded backslash".

The newline character is not special in the read syntax for strings; if you write a new line between the double-quotes, it becomes a character in the string. But an escaped newline--one that is preceded by `\'---does not become part of the string; i.e., the Lisp reader ignores an escaped newline while reading a string. An escaped space `\ ' is likewise ignored.

"It is useful to include newlines in documentation strings, but the newline is \ ignored if escaped." => "It is useful to include newlines in documentation strings, but the newline is ignored if escaped."

2.3.8.2 Non-ASCII Characters in Strings

You can include a non-ASCII international character in a string constant by writing it literally. There are two text representations for non-ASCII characters in Emacs strings (and in buffers): unibyte and multibyte. If the string constant is read from a multibyte source, such as a multibyte buffer or string, or a file that would be visited as multibyte, then the character is read as a multibyte character, and that makes the string multibyte. If the string constant is read from a unibyte source, then the character is read as unibyte and that makes the string unibyte.

You can also represent a multibyte non-ASCII character with its character code: use a hex escape, `\xnnnnnnn', with as many digits as necessary. (Multibyte non-ASCII character codes are all greater than 256.) Any character which is not a valid hex digit terminates this construct. If the next character in the string could be interpreted as a hex digit, write `\ ' (backslash and space) to terminate the hex escape--for example, `\x8e0\ ' represents one character, `a' with grave accent. `\ ' in a string constant is just like backslash-newline; it does not contribute any character to the string, but it does terminate the preceding hex escape.

Using a multibyte hex escape forces the string to multibyte. You can represent a unibyte non-ASCII character with its character code, which must be in the range from 128 (0200 octal) to 255 (0377 octal). This forces a unibyte string. See section 33.1 Text Representations, for more information about the two text representations.

2.3.8.3 Nonprinting Characters in Strings

You can use the same backslash escape-sequences in a string constant as in character literals (but do not use the question mark that begins a character constant). For example, you can write a string containing the nonprinting characters tab and C-a, with commas and spaces between them, like this: "\t, \C-a". See section 2.3.3 Character Type, for a description of the read syntax for characters.

However, not all of the characters you can write with backslash escape-sequences are valid in strings. The only control characters that a string can hold are the ASCII control characters. Strings do not distinguish case in ASCII control characters.

Properly speaking, strings cannot hold meta characters; but when a string is to be used as a key sequence, there is a special convention that provides a way to represent meta versions of ASCII characters in a string. If you use the `\M-' syntax to indicate a meta character in a string constant, this sets the 2**7 bit of the character in the string. If the string is used in define-key or lookup-key, this numeric code is translated into the equivalent meta character. See section 2.3.3 Character Type.

Strings cannot hold characters that have the hyper, super, or alt modifiers.

2.3.8.4 Text Properties in Strings

A string can hold properties for the characters it contains, in addition to the characters themselves. This enables programs that copy text between strings and buffers to copy the text's properties with no special effort. See section 32.19 Text Properties, for an explanation of what text properties mean. Strings with text properties use a special read and print syntax:

#("characters" property-data...)

where property-data consists of zero or more elements, in groups of three as follows:

beg end plist

The elements beg and end are integers, and together specify a range of indices in the string; plist is the property list for that range. For example,

#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))

represents a string whose textual contents are `foo bar', in which the first three characters have a face property with value bold, and the last three have a face property with value italic. (The fourth character has no text properties, so its property list is nil. It is not actually necessary to mention ranges with nil as the property list, since any characters not mentioned in any range will default to having no properties.)

2.3.9 Vector Type

A vector is a one-dimensional array of elements of any type. It takes a constant amount of time to access any element of a vector. (In a list, the access time of an element is proportional to the distance of the element from the beginning of the list.)

The printed representation of a vector consists of a left square bracket, the elements, and a right square bracket. This is also the read syntax. Like numbers and strings, vectors are considered constants for evaluation.

[1 "two" (three)] ; A vector of three elements. => [1 "two" (three)]

See section 6.4 Vectors, for functions that work with vectors.

2.3.10 Char-Table Type

A char-table is a one-dimensional array of elements of any type, indexed by character codes. Char-tables have certain extra features to make them more useful for many jobs that involve assigning information to character codes--for example, a char-table can have a parent to inherit from, a default value, and a small number of extra slots to use for special purposes. A char-table can also specify a single value for a whole character set.

The printed representation of a char-table is like a vector except that there is an extra `#^' at the beginning.

See section 6.6 Char-Tables, for special functions to operate on char-tables. Uses of char-tables include:

• Case tables (see section 4.9 The Case Table).

• Character category tables (see section 35.9 Categories).

• Display tables (see section 38.17 Display Tables).

• Syntax tables (see section 35. Syntax Tables).

2.3.11 Bool-Vector Type

A bool-vector is a one-dimensional array of elements that must be t or nil.

The printed representation of a bool-vector is like a string, except that it begins with `#&' followed by the length. The string constant that follows actually specifies the contents of the bool-vector as a bitmap--each "character" in the string contains 8 bits, which specify the next 8 elements of the bool-vector (1 stands for t, and 0 for nil). The least significant bits of the character correspond to the lowest indices in the bool-vector. If the length is not a multiple of 8, the printed representation shows extra elements, but these extras really make no difference.

(make-bool-vector 3 t) => #&3"\007" (make-bool-vector 3 nil) => #&3"\0" ;; These are equal since only the first 3 bits are used. (equal #&3"\377" #&3"\007") => t

2.3.12 Hash Table Type

A hash table is a very fast kind of lookup table, somewhat like an alist in that it maps keys to corresponding values, but much faster. Hash tables are a new feature in Emacs 21; they have no read syntax, and print using hash notation. See section 7. Hash Tables.

(make-hash-table) => #<hash-table 'eql nil 0/65 0x83af980>

2.3.13 Function Type

Just as functions in other programming languages are executable, Lisp function objects are pieces of executable code. However, functions in Lisp are primarily Lisp objects, and only secondarily the text which represents them. These Lisp objects are lambda expressions: lists whose first element is the symbol lambda (see section 12.2 Lambda Expressions).

In most programming languages, it is impossible to have a function without a name. In Lisp, a function has no intrinsic name. A lambda expression is also called an anonymous function (see section 12.7 Anonymous Functions). A named function in Lisp is actually a symbol with a valid function in its function cell (see section 12.4 Defining Functions).

Most of the time, functions are called when their names are written in Lisp expressions in Lisp programs. However, you can construct or obtain a function object at run time and then call it with the primitive functions funcall and apply. See section 12.5 Calling Functions.

2.3.14 Macro Type

A Lisp macro is a user-defined construct that extends the Lisp language. It is represented as an object much like a function, but with different argument-passing semantics. A Lisp macro has the form of a list whose first element is the symbol macro and whose CDR is a Lisp function object, including the lambda symbol.

Lisp macro objects are usually defined with the built-in defmacro function, but any list that begins with macro is a macro as far as Emacs is concerned. See section 13. Macros, for an explanation of how to write a macro.

Warning: Lisp macros and keyboard macros (see section 21.15 Keyboard Macros) are entirely different things. When we use the word "macro" without qualification, we mean a Lisp macro, not a keyboard macro.

2.3.15 Primitive Function Type

A primitive function is a function callable from Lisp but written in the C programming language. Primitive functions are also called subrs or built-in functions. (The word "subr" is derived from "subroutine".) Most primitive functions evaluate all their arguments when they are called. A primitive function that does not evaluate all its arguments is called a special form (see section 9.2.7 Special Forms).

It does not matter to the caller of a function whether the function is primitive. However, this does matter if you try to redefine a primitive with a function written in Lisp. The reason is that the primitive function may be called directly from C code. Calls to the redefined function from Lisp will use the new definition, but calls from C code may still use the built-in definition. Therefore, we discourage redefinition of primitive functions.

The term function refers to all Emacs functions, whether written in Lisp or C. See section 2.3.13 Function Type, for information about the functions written in Lisp.

Primitive functions have no read syntax and print in hash notation with the name of the subroutine.

(symbol-function 'car) ; Access the function cell ; of the symbol. => #<subr car> (subrp (symbol-function 'car)) ; Is this a primitive function? => t ; Yes.

2.3.16 Byte-Code Function Type

The byte compiler produces byte-code function objects. Internally, a byte-code function object is much like a vector; however, the evaluator handles this data type specially when it appears as a function to be called. See section 16. Byte Compilation, for information about the byte compiler.

The printed representation and read syntax for a byte-code function object is like that for a vector, with an additional `#' before the opening `['.

2.3.17 Autoload Type

An autoload object is a list whose first element is the symbol autoload. It is stored as the function definition of a symbol, where it serves as a placeholder for the real definition. The autoload object says that the real definition is found in a file of Lisp code that should be loaded when necessary. It contains the name of the file, plus some other information about the real definition.

After the file has been loaded, the symbol should have a new function definition that is not an autoload object. The new definition is then called as if it had been there to begin with. From the user's point of view, the function call works as expected, using the function definition in the loaded file.

An autoload object is usually created with the function autoload, which stores the object in the function cell of a symbol. See section 15.4 Autoload, for more details.

2.4 Editing Types

The types in the previous section are used for general programming purposes, and most of them are common to most Lisp dialects. Emacs Lisp provides several additional data types for purposes connected with editing.

2.4.1 Buffer Type		The basic object of editing.
2.4.2 Marker Type		A position in a buffer.
2.4.3 Window Type		Buffers are displayed in windows.
2.4.4 Frame Type		Windows subdivide frames.
2.4.5 Window Configuration Type		Recording the way a frame is subdivided.
2.4.6 Frame Configuration Type		Recording the status of all frames.
2.4.7 Process Type		A process running on the underlying OS.
2.4.8 Stream Type		Receive or send characters.
2.4.9 Keymap Type		What function a keystroke invokes.
2.4.10 Overlay Type		How an overlay is represented.

2.4.1 Buffer Type

A buffer is an object that holds text that can be edited (see section 27. Buffers). Most buffers hold the contents of a disk file (see section 25. Files) so they can be edited, but some are used for other purposes. Most buffers are also meant to be seen by the user, and therefore displayed, at some time, in a window (see section 28. Windows). But a buffer need not be displayed in any window.

The contents of a buffer are much like a string, but buffers are not used like strings in Emacs Lisp, and the available operations are different. For example, you can insert text efficiently into an existing buffer, altering the buffer's contents, whereas "inserting" text into a string requires concatenating substrings, and the result is an entirely new string object.

Each buffer has a designated position called point (see section 30. Positions). At any time, one buffer is the current buffer. Most editing commands act on the contents of the current buffer in the neighborhood of point. Many of the standard Emacs functions manipulate or test the characters in the current buffer; a whole chapter in this manual is devoted to describing these functions (see section 32. Text).

Several other data structures are associated with each buffer:

• a local syntax table (see section 35. Syntax Tables);

• a local keymap (see section 22. Keymaps); and,

• a list of buffer-local variable bindings (see section 11.10 Buffer-Local Variables).

• overlays (see section 38.9 Overlays).

• text properties for the text in the buffer (see section 32.19 Text Properties).

The local keymap and variable list contain entries that individually override global bindings or values. These are used to customize the behavior of programs in different buffers, without actually changing the programs.

A buffer may be indirect, which means it shares the text of another buffer, but presents it differently. See section 27.11 Indirect Buffers.

Buffers have no read syntax. They print in hash notation, showing the buffer name.

(current-buffer) => #<buffer objects.texi>

2.4.2 Marker Type

A marker denotes a position in a specific buffer. Markers therefore have two components: one for the buffer, and one for the position. Changes in the buffer's text automatically relocate the position value as necessary to ensure that the marker always points between the same two characters in the buffer.

Markers have no read syntax. They print in hash notation, giving the current character position and the name of the buffer.

(point-marker) => #<marker at 10779 in objects.texi>

See section 31. Markers, for information on how to test, create, copy, and move markers.

2.4.3 Window Type

A window describes the portion of the terminal screen that Emacs uses to display a buffer. Every window has one associated buffer, whose contents appear in the window. By contrast, a given buffer may appear in one window, no window, or several windows.

Though many windows may exist simultaneously, at any time one window is designated the selected window. This is the window where the cursor is (usually) displayed when Emacs is ready for a command. The selected window usually displays the current buffer, but this is not necessarily the case.

Windows are grouped on the screen into frames; each window belongs to one and only one frame. See section 2.4.4 Frame Type.

Windows have no read syntax. They print in hash notation, giving the window number and the name of the buffer being displayed. The window numbers exist to identify windows uniquely, since the buffer displayed in any given window can change frequently.

(selected-window) => #<window 1 on objects.texi>

See section 28. Windows, for a description of the functions that work on windows.

2.4.4 Frame Type

A frame is a rectangle on the screen that contains one or more Emacs windows. A frame initially contains a single main window (plus perhaps a minibuffer window) which you can subdivide vertically or horizontally into smaller windows.

Frames have no read syntax. They print in hash notation, giving the frame's title, plus its address in core (useful to identify the frame uniquely).

(selected-frame) => #<frame emacs@psilocin.gnu.org 0xdac80>

See section 29. Frames, for a description of the functions that work on frames.

2.4.5 Window Configuration Type

A window configuration stores information about the positions, sizes, and contents of the windows in a frame, so you can recreate the same arrangement of windows later.

Window configurations do not have a read syntax; their print syntax looks like `#<window-configuration>'. See section 28.17 Window Configurations, for a description of several functions related to window configurations.

2.4.6 Frame Configuration Type

A frame configuration stores information about the positions, sizes, and contents of the windows in all frames. It is actually a list whose CAR is frame-configuration and whose CDR is an alist. Each alist element describes one frame, which appears as the CAR of that element.

See section 29.12 Frame Configurations, for a description of several functions related to frame configurations.

2.4.7 Process Type

The word process usually means a running program. Emacs itself runs in a process of this sort. However, in Emacs Lisp, a process is a Lisp object that designates a subprocess created by the Emacs process. Programs such as shells, GDB, ftp, and compilers, running in subprocesses of Emacs, extend the capabilities of Emacs.

An Emacs subprocess takes textual input from Emacs and returns textual output to Emacs for further manipulation. Emacs can also send signals to the subprocess.

Process objects have no read syntax. They print in hash notation, giving the name of the process:

(process-list) => (#<process shell>)

See section 37. Processes, for information about functions that create, delete, return information about, send input or signals to, and receive output from processes.

2.4.8 Stream Type

A stream is an object that can be used as a source or sink for characters--either to supply characters for input or to accept them as output. Many different types can be used this way: markers, buffers, strings, and functions. Most often, input streams (character sources) obtain characters from the keyboard, a buffer, or a file, and output streams (character sinks) send characters to a buffer, such as a `*Help*' buffer, or to the echo area.

The object nil, in addition to its other meanings, may be used as a stream. It stands for the value of the variable standard-input or standard-output. Also, the object t as a stream specifies input using the minibuffer (see section 20. Minibuffers) or output in the echo area (see section 38.4 The Echo Area).

Streams have no special printed representation or read syntax, and print as whatever primitive type they are.

See section 19. Reading and Printing Lisp Objects, for a description of functions related to streams, including parsing and printing functions.

2.4.9 Keymap Type

A keymap maps keys typed by the user to commands. This mapping controls how the user's command input is executed. A keymap is actually a list whose CAR is the symbol keymap.

See section 22. Keymaps, for information about creating keymaps, handling prefix keys, local as well as global keymaps, and changing key bindings.

2.4.10 Overlay Type

An overlay specifies properties that apply to a part of a buffer. Each overlay applies to a specified range of the buffer, and contains a property list (a list whose elements are alternating property names and values). Overlay properties are used to present parts of the buffer temporarily in a different display style. Overlays have no read syntax, and print in hash notation, giving the buffer name and range of positions.

See section 38.9 Overlays, for how to create and use overlays.

2.5 Read Syntax for Circular Objects

In Emacs 21, to represent shared or circular structure within a complex of Lisp objects, you can use the reader constructs `#n=' and `#n#'.

Use #n= before an object to label it for later reference; subsequently, you can use #n# to refer the same object in another place. Here, n is some integer. For example, here is how to make a list in which the first element recurs as the third element:

(#1=(a) b #1#)

This differs from ordinary syntax such as this

((a) b (a))

which would result in a list whose first and third elements look alike but are not the same Lisp object. This shows the difference:

(prog1 nil (setq x '(#1=(a) b #1#))) (eq (nth 0 x) (nth 2 x)) => t (setq x '((a) b (a))) (eq (nth 0 x) (nth 2 x)) => nil

You can also use the same syntax to make a circular structure, which appears as an "element" within itself. Here is an example:

#1=(a #1#)

This makes a list whose second element is the list itself. Here's how you can see that it really works:

(prog1 nil (setq x '#1=(a #1#))) (eq x (cadr x)) => t

The Lisp printer can produce this syntax to record circular and shared structure in a Lisp object, if you bind the variable print-circle to a non-nil value. See section 19.6 Variables Affecting Output.

2.6 Type Predicates

The Emacs Lisp interpreter itself does not perform type checking on the actual arguments passed to functions when they are called. It could not do so, since function arguments in Lisp do not have declared data types, as they do in other programming languages. It is therefore up to the individual function to test whether each actual argument belongs to a type that the function can use.

All built-in functions do check the types of their actual arguments when appropriate, and signal a wrong-type-argument error if an argument is of the wrong type. For example, here is what happens if you pass an argument to + that it cannot handle:

(+ 2 'a) error--> Wrong type argument: number-or-marker-p, a

If you want your program to handle different types differently, you must do explicit type checking. The most common way to check the type of an object is to call a type predicate function. Emacs has a type predicate for each type, as well as some predicates for combinations of types.

A type predicate function takes one argument; it returns t if the argument belongs to the appropriate type, and nil otherwise. Following a general Lisp convention for predicate functions, most type predicates' names end with `p'.

Here is an example which uses the predicates listp to check for a list and symbolp to check for a symbol.

(defun add-on (x) (cond ((symbolp x) ;; If X is a symbol, put it on LIST. (setq list (cons x list))) ((listp x) ;; If X is a list, add its elements to LIST. (setq list (append x list))) (t ;; We handle only symbols and lists. (error "Invalid argument %s in add-on" x))))

Here is a table of predefined type predicates, in alphabetical order, with references to further information.

atom

See section atom.

arrayp

See section arrayp.

bool-vector-p

See section bool-vector-p.

bufferp

See section bufferp.

byte-code-function-p

See section byte-code-function-p.

case-table-p

See section case-table-p.

char-or-string-p

See section char-or-string-p.

char-table-p

See section char-table-p.

commandp

See section commandp.

consp

See section consp.

display-table-p

See section display-table-p.

floatp

See section floatp.

frame-configuration-p

See section frame-configuration-p.

frame-live-p

See section frame-live-p.

framep

See section framep.

functionp

See section functionp.

integer-or-marker-p

See section integer-or-marker-p.

integerp

See section integerp.

keymapp

See section keymapp.

keywordp

See section 11.2 Variables that Never Change.

listp

See section listp.

markerp

See section markerp.

wholenump

See section wholenump.

nlistp

See section nlistp.

numberp

See section numberp.

number-or-marker-p

See section number-or-marker-p.

overlayp

See section overlayp.

processp

See section processp.

sequencep

See section sequencep.

stringp

See section stringp.

subrp

See section subrp.

symbolp

See section symbolp.

syntax-table-p

See section syntax-table-p.

user-variable-p

See section user-variable-p.

vectorp

See section vectorp.

window-configuration-p

See section window-configuration-p.

window-live-p

See section window-live-p.

windowp

See section windowp.

The most general way to check the type of an object is to call the function type-of. Recall that each object belongs to one and only one primitive type; type-of tells you which one (see section 2. Lisp Data Types). But type-of knows nothing about non-primitive types. In most cases, it is more convenient to use type predicates than type-of.

Function: type-of object

This function returns a symbol naming the primitive type of object. The value is one of the symbols symbol, integer, float, string, cons, vector, char-table, bool-vector, hash-table, subr, compiled-function, marker, overlay, window, buffer, frame, process, or window-configuration.

(type-of 1) => integer (type-of 'nil) => symbol (type-of '()) ; () is nil. => symbol (type-of '(x)) => cons

2.7 Equality Predicates

Here we describe two functions that test for equality between any two objects. Other functions test equality between objects of specific types, e.g., strings. For these predicates, see the appropriate chapter describing the data type.

Function: eq object1 object2

This function returns t if object1 and object2 are the same object, nil otherwise. The "same object" means that a change in one will be reflected by the same change in the other.

eq returns t if object1 and object2 are integers with the same value. Also, since symbol names are normally unique, if the arguments are symbols with the same name, they are eq. For other types (e.g., lists, vectors, strings), two arguments with the same contents or elements are not necessarily eq to each other: they are eq only if they are the same object.

(eq 'foo 'foo) => t (eq 456 456) => t (eq "asdf" "asdf") => nil (eq '(1 (2 (3))) '(1 (2 (3)))) => nil (setq foo '(1 (2 (3)))) => (1 (2 (3))) (eq foo foo) => t (eq foo '(1 (2 (3)))) => nil (eq [(1 2) 3] [(1 2) 3]) => nil (eq (point-marker) (point-marker)) => nil

The make-symbol function returns an uninterned symbol, distinct from the symbol that is used if you write the name in a Lisp expression. Distinct symbols with the same name are not eq. See section 8.3 Creating and Interning Symbols.

(eq (make-symbol "foo") 'foo) => nil

Function: equal object1 object2

This function returns t if object1 and object2 have equal components, nil otherwise. Whereas eq tests if its arguments are the same object, equal looks inside nonidentical arguments to see if their elements or contents are the same. So, if two objects are eq, they are equal, but the converse is not always true.

(equal 'foo 'foo) => t (equal 456 456) => t (equal "asdf" "asdf") => t (eq "asdf" "asdf") => nil (equal '(1 (2 (3))) '(1 (2 (3)))) => t (eq '(1 (2 (3))) '(1 (2 (3)))) => nil (equal [(1 2) 3] [(1 2) 3]) => t (eq [(1 2) 3] [(1 2) 3]) => nil (equal (point-marker) (point-marker)) => t (eq (point-marker) (point-marker)) => nil

Comparison of strings is case-sensitive, but does not take account of text properties--it compares only the characters in the strings. A unibyte string never equals a multibyte string unless the contents are entirely ASCII (see section 33.1 Text Representations).

(equal "asdf" "ASDF") => nil

However, two distinct buffers are never considered equal, even if their textual contents are the same.

The test for equality is implemented recursively; for example, given two cons cells x and y, (equal x y) returns t if and only if both the expressions below return t:

(equal (car x) (car y)) (equal (cdr x) (cdr y))

Because of this recursive method, circular lists may therefore cause infinite recursion (leading to an error).

3. Numbers

GNU Emacs supports two numeric data types: integers and floating point numbers. Integers are whole numbers such as -3, 0, 7, 13, and 511. Their values are exact. Floating point numbers are numbers with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be expressed in exponential notation: 1.5e2 equals 150; in this example, `e2' stands for ten to the second power, and that is multiplied by 1.5. Floating point values are not exact; they have a fixed, limited amount of precision.

3.1 Integer Basics		Representation and range of integers.
3.2 Floating Point Basics		Representation and range of floating point.
3.3 Type Predicates for Numbers		Testing for numbers.
3.4 Comparison of Numbers		Equality and inequality predicates.
3.5 Numeric Conversions		Converting float to integer and vice versa.
3.6 Arithmetic Operations		How to add, subtract, multiply and divide.
3.7 Rounding Operations		Explicitly rounding floating point numbers.
3.8 Bitwise Operations on Integers		Logical and, or, not, shifting.
3.9 Standard Mathematical Functions		Trig, exponential and logarithmic functions.
3.10 Random Numbers		Obtaining random integers, predictable or not.

3.1 Integer Basics

The range of values for an integer depends on the machine. The minimum range is -134217728 to 134217727 (28 bits; i.e., -2**27 to 2**27 - 1), but some machines may provide a wider range. Many examples in this chapter assume an integer has 28 bits.

The Lisp reader reads an integer as a sequence of digits with optional initial sign and optional final period.

1 ; The integer 1. 1. ; The integer 1. +1 ; Also the integer 1. -1 ; The integer -1. 268435457 ; Also the integer 1, due to overflow. 0 ; The integer 0. -0 ; The integer 0.

In addition, the Lisp reader recognizes a syntax for integers in bases other than 10: `#Binteger' reads integer in binary (radix 2), `#Ointeger' reads integer in octal (radix 8), `#Xinteger' reads integer in hexadecimal (radix 16), and `#radixrinteger' reads integer in radix radix (where radix is between 2 and 36, inclusivley). Case is not significant for the letter after `#' (`B', `O', etc.) that denotes the radix.

To understand how various functions work on integers, especially the bitwise operators (see section 3.8 Bitwise Operations on Integers), it is often helpful to view the numbers in their binary form.

In 28-bit binary, the decimal integer 5 looks like this:

0000 0000 0000 0000 0000 0000 0101

(We have inserted spaces between groups of 4 bits, and two spaces between groups of 8 bits, to make the binary integer easier to read.)

The integer -1 looks like this:

1111 1111 1111 1111 1111 1111 1111

-1 is represented as 28 ones. (This is called two's complement notation.)

The negative integer, -5, is creating by subtracting 4 from -1. In binary, the decimal integer 4 is 100. Consequently, -5 looks like this:

1111 1111 1111 1111 1111 1111 1011

In this implementation, the largest 28-bit binary integer value is 134,217,727 in decimal. In binary, it looks like this:

0111 1111 1111 1111 1111 1111 1111

Since the arithmetic functions do not check whether integers go outside their range, when you add 1 to 134,217,727, the value is the negative integer -134,217,728:

(+ 1 134217727) => -134217728 => 1000 0000 0000 0000 0000 0000 0000

Many of the functions described in this chapter accept markers for arguments in place of numbers. (See section 31. Markers.) Since the actual arguments to such functions may be either numbers or markers, we often give these arguments the name number-or-marker. When the argument value is a marker, its position value is used and its buffer is ignored.

3.2 Floating Point Basics

Floating point numbers are useful for representing numbers that are not integral. The precise range of floating point numbers is machine-specific; it is the same as the range of the C data type double on the machine you are using.

The read-syntax for floating point numbers requires either a decimal point (with at least one digit following), an exponent, or both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4' are five ways of writing a floating point number whose value is 1500. They are all equivalent. You can also use a minus sign to write negative floating point numbers, as in `-1.0'.

Most modern computers support the IEEE floating point standard, which provides for positive infinity and negative infinity as floating point values. It also provides for a class of values called NaN or "not-a-number"; numerical functions return such values in cases where there is no correct answer. For example, (sqrt -1.0) returns a NaN. For practical purposes, there's no significant difference between different NaN values in Emacs Lisp, and there's no rule for precisely which NaN value should be used in a particular case, so Emacs Lisp doesn't try to distinguish them. Here are the read syntaxes for these special floating point values:

positive infinity

`1.0e+INF'

negative infinity

`-1.0e+INF'

Not-a-number

`0.0e+NaN'.

In addition, the value -0.0 is distinguishable from ordinary zero in IEEE floating point (although equal and = consider them equal values).

You can use logb to extract the binary exponent of a floating point number (or estimate the logarithm of an integer):

Function: logb number

This function returns the binary exponent of number. More precisely, the value is the logarithm of number base 2, rounded down to an integer.

(logb 10) => 3 (logb 10.0e20) => 69

3.3 Type Predicates for Numbers

The functions in this section test whether the argument is a number or whether it is a certain sort of number. The functions integerp and floatp can take any type of Lisp object as argument (the predicates would not be of much use otherwise); but the zerop predicate requires a number as its argument. See also integer-or-marker-p and number-or-marker-p, in 31.2 Predicates on Markers.

Function: floatp object

This predicate tests whether its argument is a floating point number and returns t if so, nil otherwise.

floatp does not exist in Emacs versions 18 and earlier.

Function: integerp object

This predicate tests whether its argument is an integer, and returns t if so, nil otherwise.

Function: numberp object

This predicate tests whether its argument is a number (either integer or floating point), and returns t if so, nil otherwise.

Function: wholenump object

The wholenump predicate (whose name comes from the phrase "whole-number-p") tests to see whether its argument is a nonnegative integer, and returns t if so, nil otherwise. 0 is considered non-negative.

natnump is an obsolete synonym for wholenump.

Function: zerop number

This predicate tests whether its argument is zero, and returns t if so, nil otherwise. The argument must be a number.

These two forms are equivalent: (zerop x) == (= x 0).

3.4 Comparison of Numbers

To test numbers for numerical equality, you should normally use =, not eq. There can be many distinct floating point number objects with the same numeric value. If you use eq to compare them, then you test whether two values are the same object. By contrast, = compares only the numeric values of the objects.

At present, each integer value has a unique Lisp object in Emacs Lisp. Therefore, eq is equivalent to = where integers are concerned. It is sometimes convenient to use eq for comparing an unknown value with an integer, because eq does not report an error if the unknown value is not a number--it accepts arguments of any type. By contrast, = signals an error if the arguments are not numbers or markers. However, it is a good idea to use = if you can, even for comparing integers, just in case we change the representation of integers in a future Emacs version.

Sometimes it is useful to compare numbers with equal; it treats two numbers as equal if they have the same data type (both integers, or both floating point) and the same value. By contrast, = can treat an integer and a floating point number as equal.

There is another wrinkle: because floating point arithmetic is not exact, it is often a bad idea to check for equality of two floating point values. Usually it is better to test for approximate equality. Here's a function to do this:

(defvar fuzz-factor 1.0e-6) (defun approx-equal (x y) (or (and (= x 0) (= y 0)) (< (/ (abs (- x y)) (max (abs x) (abs y))) fuzz-factor)))

Common Lisp note: Comparing numbers in Common Lisp always requires = because Common Lisp implements multi-word integers, and two distinct integer objects can have the same numeric value. Emacs Lisp can have just one integer object for any given value because it has a limited range of integer values.

Function: = number-or-marker1 number-or-marker2

This function tests whether its arguments are numerically equal, and returns t if so, nil otherwise.

Function: /= number-or-marker1 number-or-marker2

This function tests whether its arguments are numerically equal, and returns t if they are not, and nil if they are.

Function: < number-or-marker1 number-or-marker2

This function tests whether its first argument is strictly less than its second argument. It returns t if so, nil otherwise.

Function: <= number-or-marker1 number-or-marker2

This function tests whether its first argument is less than or equal to its second argument. It returns t if so, nil otherwise.

Function: > number-or-marker1 number-or-marker2

This function tests whether its first argument is strictly greater than its second argument. It returns t if so, nil otherwise.

Function: >= number-or-marker1 number-or-marker2

This function tests whether its first argument is greater than or equal to its second argument. It returns t if so, nil otherwise.

Function: max number-or-marker &rest numbers-or-markers

This function returns the largest of its arguments. If any of the argument is floating-point, the value is returned as floating point, even if it was given as an integer.

(max 20) => 20 (max 1 2.5) => 2.5 (max 1 3 2.5) => 3.0

Function: min number-or-marker &rest numbers-or-markers

This function returns the smallest of its arguments. If any of the argument is floating-point, the value is returned as floating point, even if it was given as an integer.

(min -4 1) => -4

Function: abs number

This function returns the absolute value of number.

3.5 Numeric Conversions

To convert an integer to floating point, use the function float.

Function: float number

This returns number converted to floating point. If number is already a floating point number, float returns it unchanged.

There are four functions to convert floating point numbers to integers; they differ in how they round. These functions accept integer arguments also, and return such arguments unchanged.

Function: truncate number

This returns number, converted to an integer by rounding towards zero.

(truncate 1.2) => 1 (truncate 1.7) => 1 (truncate -1.2) => -1 (truncate -1.7) => -1

Function: floor number &optional divisor

This returns number, converted to an integer by rounding downward (towards negative infinity).

If divisor is specified, floor divides number by divisor and then converts to an integer; this uses the kind of division operation that corresponds to mod, rounding downward. An arith-error results if divisor is 0.

(floor 1.2) => 1 (floor 1.7) => 1 (floor -1.2) => -2 (floor -1.7) => -2 (floor 5.99 3) => 1

Function: ceiling number

This returns number, converted to an integer by rounding upward (towards positive infinity).

(ceiling 1.2) => 2 (ceiling 1.7) => 2 (ceiling -1.2) => -1 (ceiling -1.7) => -1

Function: round number

This returns number, converted to an integer by rounding towards the nearest integer. Rounding a value equidistant between two integers may choose the integer closer to zero, or it may prefer an even integer, depending on your machine.

(round 1.2) => 1 (round 1.7) => 2 (round -1.2) => -1 (round -1.7) => -2

3.6 Arithmetic Operations

Emacs Lisp provides the traditional four arithmetic operations: addition, subtraction, multiplication, and division. Remainder and modulus functions supplement the division functions. The functions to add or subtract 1 are provided because they are traditional in Lisp and commonly used.

All of these functions except % return a floating point value if any argument is floating.

It is important to note that in Emacs Lisp, arithmetic functions do not check for overflow. Thus (1+ 134217727) may evaluate to -134217728, depending on your hardware.

Function: 1+ number-or-marker

This function returns number-or-marker plus 1. For example,

(setq foo 4) => 4 (1+ foo) => 5

This function is not analogous to the C operator ++---it does not increment a variable. It just computes a sum. Thus, if we continue,

foo => 4

If you want to increment the variable, you must use setq, like this:

(setq foo (1+ foo)) => 5

Function: 1- number-or-marker

This function returns number-or-marker minus 1.

Function: + &rest numbers-or-markers

This function adds its arguments together. When given no arguments, + returns 0.

(+) => 0 (+ 1) => 1 (+ 1 2 3 4) => 10

Function: - &optional number-or-marker &rest more-numbers-or-markers

The - function serves two purposes: negation and subtraction. When - has a single argument, the value is the negative of the argument. When there are multiple arguments, - subtracts each of the more-numbers-or-markers from number-or-marker, cumulatively. If there are no arguments, the result is 0.

(- 10 1 2 3 4) => 0 (- 10) => -10 (-) => 0

Function: * &rest numbers-or-markers

This function multiplies its arguments together, and returns the product. When given no arguments, * returns 1.

(*) => 1 (* 1) => 1 (* 1 2 3 4) => 24

Function: / dividend divisor &rest divisors

This function divides dividend by divisor and returns the quotient. If there are additional arguments divisors, then it divides dividend by each divisor in turn. Each argument may be a number or a marker.

If all the arguments are integers, then the result is an integer too. This means the result has to be rounded. On most machines, the result is rounded towards zero after each division, but some machines may round differently with negative arguments. This is because the Lisp function / is implemented using the C division operator, which also permits machine-dependent rounding. As a practical matter, all known machines round in the standard fashion.

If you divide an integer by 0, an arith-error error is signaled. (See section 10.5.3 Errors.) Floating point division by zero returns either infinity or a NaN if your machine supports IEEE floating point; otherwise, it signals an arith-error error.

(/ 6 2) => 3 (/ 5 2) => 2 (/ 5.0 2) => 2.5 (/ 5 2.0) => 2.5 (/ 5.0 2.0) => 2.5 (/ 25 3 2) => 4 (/ -17 6) => -2

The result of (/ -17 6) could in principle be -3 on some machines.

Function: % dividend divisor

This function returns the integer remainder after division of dividend by divisor. The arguments must be integers or markers.

For negative arguments, the remainder is in principle machine-dependent since the quotient is; but in practice, all known machines behave alike.

An arith-error results if divisor is 0.

(% 9 4) => 1 (% -9 4) => -1 (% 9 -4) => 1 (% -9 -4) => -1

For any two integers dividend and divisor,

(+ (% dividend divisor) (* (/ dividend divisor) divisor))

always equals dividend.

Function: mod dividend divisor

This function returns the value of dividend modulo divisor; in other words, the remainder after division of dividend by divisor, but with the same sign as divisor. The arguments must be numbers or markers.

Unlike %, mod returns a well-defined result for negative arguments. It also permits floating point arguments; it rounds the quotient downward (towards minus infinity) to an integer, and uses that quotient to compute the remainder.

An arith-error results if divisor is 0.

(mod 9 4) => 1 (mod -9 4) => 3 (mod 9 -4) => -3 (mod -9 -4) => -1 (mod 5.5 2.5) => .5

For any two numbers dividend and divisor,

(+ (mod dividend divisor) (* (floor dividend divisor) divisor))

always equals dividend, subject to rounding error if either argument is floating point. For floor, see 3.5 Numeric Conversions.

3.7 Rounding Operations

The functions ffloor, fceiling, fround, and ftruncate take a floating point argument and return a floating point result whose value is a nearby integer. ffloor returns the nearest integer below; fceiling, the nearest integer above; ftruncate, the nearest integer in the direction towards zero; fround, the nearest integer.

Function: ffloor float

This function rounds float to the next lower integral value, and returns that value as a floating point number.

Function: fceiling float

This function rounds float to the next higher integral value, and returns that value as a floating point number.

Function: ftruncate float

This function rounds float towards zero to an integral value, and returns that value as a floating point number.

Function: fround float

This function rounds float to the nearest integral value, and returns that value as a floating point number.

3.8 Bitwise Operations on Integers

In a computer, an integer is represented as a binary number, a sequence of bits (digits which are either zero or one). A bitwise operation acts on the individual bits of such a sequence. For example, shifting moves the whole sequence left or right one or more places, reproducing the same pattern "moved over".

The bitwise operations in Emacs Lisp apply only to integers.

Function: lsh integer1 count

lsh, which is an abbreviation for logical shift, shifts the bits in integer1 to the left count places, or to the right if count is negative, bringing zeros into the vacated bits. If count is negative, lsh shifts zeros into the leftmost (most-significant) bit, producing a positive result even if integer1 is negative. Contrast this with ash, below.

Here are two examples of lsh, shifting a pattern of bits one place to the left. We show only the low-order eight bits of the binary pattern; the rest are all zero.

(lsh 5 1) => 10 ;; Decimal 5 becomes decimal 10. 00000101 => 00001010 (lsh 7 1) => 14 ;; Decimal 7 becomes decimal 14. 00000111 => 00001110

As the examples illustrate, shifting the pattern of bits one place to the left produces a number that is twice the value of the previous number.

Shifting a pattern of bits two places to the left produces results like this (with 8-bit binary numbers):

(lsh 3 2) => 12 ;; Decimal 3 becomes decimal 12. 00000011 => 00001100

On the other hand, shifting one place to the right looks like this:

(lsh 6 -1) => 3 ;; Decimal 6 becomes decimal 3. 00000110 => 00000011 (lsh 5 -1) => 2 ;; Decimal 5 becomes decimal 2. 00000101 => 00000010

As the example illustrates, shifting one place to the right divides the value of a positive integer by two, rounding downward.

The function lsh, like all Emacs Lisp arithmetic functions, does not check for overflow, so shifting left can discard significant bits and change the sign of the number. For example, left shifting 134,217,727 produces -2 on a 28-bit machine:

(lsh 134217727 1) ; left shift => -2

In binary, in the 28-bit implementation, the argument looks like this:

;; Decimal 134,217,727 0111 1111 1111 1111 1111 1111 1111

which becomes the following when left shifted:

;; Decimal -2 1111 1111 1111 1111 1111 1111 1110

Function: ash integer1 count

ash (arithmetic shift) shifts the bits in integer1 to the left count places, or to the right if count is negative.

ash gives the same results as lsh except when integer1 and count are both negative. In that case, ash puts ones in the empty bit positions on the left, while lsh puts zeros in those bit positions.

Thus, with ash, shifting the pattern of bits one place to the right looks like this:

(ash -6 -1) => -3 ;; Decimal -6 becomes decimal -3. 1111 1111 1111 1111 1111 1111 1010 => 1111 1111 1111 1111 1111 1111 1101

In contrast, shifting the pattern of bits one place to the right with lsh looks like this:

(lsh -6 -1) => 134217725 ;; Decimal -6 becomes decimal 134,217,725. 1111 1111 1111 1111 1111 1111 1010 => 0111 1111 1111 1111 1111 1111 1101

Here are other examples:

; 28-bit binary values (lsh 5 2) ; 5 = 0000 0000 0000 0000 0000 0000 0101 => 20 ; = 0000 0000 0000 0000 0000 0001 0100 (ash 5 2) => 20 (lsh -5 2) ; -5 = 1111 1111 1111 1111 1111 1111 1011 => -20 ; = 1111 1111 1111 1111 1111 1110 1100 (ash -5 2) => -20 (lsh 5 -2) ; 5 = 0000 0000 0000 0000 0000 0000 0101 => 1 ; = 0000 0000 0000 0000 0000 0000 0001 (ash 5 -2) => 1 (lsh -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011 => 4194302 ; = 0011 1111 1111 1111 1111 1111 1110 (ash -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011 => -2 ; = 1111 1111 1111 1111 1111 1111 1110

Function: logand &rest ints-or-markers

This function returns the "logical and" of the arguments: the nth bit is set in the result if, and only if, the nth bit is set in all the arguments. ("Set" means that the value of the bit is 1 rather than 0.)

For example, using 4-bit binary numbers, the "logical and" of 13 and 12 is 12: 1101 combined with 1100 produces 1100. In both the binary numbers, the leftmost two bits are set (i.e., they are 1's), so the leftmost two bits of the returned value are set. However, for the rightmost two bits, each is zero in at least one of the arguments, so the rightmost two bits of the returned value are 0's.

Therefore,

(logand 13 12) => 12

If logand is not passed any argument, it returns a value of -1. This number is an identity element for logand because its binary representation consists entirely of ones. If logand is passed just one argument, it returns that argument.

; 28-bit binary values (logand 14 13) ; 14 = 0000 0000 0000 0000 0000 0000 1110 ; 13 = 0000 0000 0000 0000 0000 0000 1101 => 12 ; 12 = 0000 0000 0000 0000 0000 0000 1100 (logand 14 13 4) ; 14 = 0000 0000 0000 0000 0000 0000 1110 ; 13 = 0000 0000 0000 0000 0000 0000 1101 ; 4 = 0000 0000 0000 0000 0000 0000 0100 => 4 ; 4 = 0000 0000 0000 0000 0000 0000 0100 (logand) => -1 ; -1 = 1111 1111 1111 1111 1111 1111 1111

Function: logior &rest ints-or-markers

This function returns the "inclusive or" of its arguments: the nth bit is set in the result if, and only if, the nth bit is set in at least one of the arguments. If there are no arguments, the result is zero, which is an identity element for this operation. If logior is passed just one argument, it returns that argument.

; 28-bit binary values (logior 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100 ; 5 = 0000 0000 0000 0000 0000 0000 0101 => 13 ; 13 = 0000 0000 0000 0000 0000 0000 1101 (logior 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100 ; 5 = 0000 0000 0000 0000 0000 0000 0101 ; 7 = 0000 0000 0000 0000 0000 0000 0111 => 15 ; 15 = 0000 0000 0000 0000 0000 0000 1111

Function: logxor &rest ints-or-markers

This function returns the "exclusive or" of its arguments: the nth bit is set in the result if, and only if, the nth bit is set in an odd number of the arguments. If there are no arguments, the result is 0, which is an identity element for this operation. If logxor is passed just one argument, it returns that argument.

; 28-bit binary values (logxor 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100 ; 5 = 0000 0000 0000 0000 0000 0000 0101 => 9 ; 9 = 0000 0000 0000 0000 0000 0000 1001 (logxor 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100 ; 5 = 0000 0000 0000 0000 0000 0000 0101 ; 7 = 0000 0000 0000 0000 0000 0000 0111 => 14 ; 14 = 0000 0000 0000 0000 0000 0000 1110

Function: lognot integer

This function returns the logical complement of its argument: the nth bit is one in the result if, and only if, the nth bit is zero in integer, and vice-versa.

(lognot 5) => -6 ;; 5 = 0000 0000 0000 0000 0000 0000 0101 ;; becomes ;; -6 = 1111 1111 1111 1111 1111 1111 1010

3.9 Standard Mathematical Functions

These mathematical functions allow integers as well as floating point numbers as arguments.

Function: sin arg

Function: cos arg

Function: tan arg

These are the ordinary trigonometric functions, with argument measured in radians.

Function: asin arg

The value of (asin arg) is a number between -pi/2 and pi/2 (inclusive) whose sine is arg; if, however, arg is out of range (outside [-1, 1]), then the result is a NaN.

Function: acos arg

The value of (acos arg) is a number between 0 and pi (inclusive) whose cosine is arg; if, however, arg is out of range (outside [-1, 1]), then the result is a NaN.

Function: atan arg

The value of (atan arg) is a number between -pi/2 and pi/2 (exclusive) whose tangent is arg.

Function: exp arg

This is the exponential function; it returns e to the power arg. e is a fundamental mathematical constant also called the base of natural logarithms.

Function: log arg &optional base

This function returns the logarithm of arg, with base base. If you don't specify base, the base e is used. If arg is negative, the result is a NaN.

Function: log10 arg

This function returns the logarithm of arg, with base 10. If arg is negative, the result is a NaN. (log10 x) == (log x 10), at least approximately.

Function: expt x y

This function returns x raised to power y. If both arguments are integers and y is positive, the result is an integer; in this case, it is truncated to fit the range of possible integer values.

Function: sqrt arg

This returns the square root of arg. If arg is negative, the value is a NaN.

3.10 Random Numbers

A deterministic computer program cannot generate true random numbers. For most purposes, pseudo-random numbers suffice. A series of pseudo-random numbers is generated in a deterministic fashion. The numbers are not truly random, but they have certain properties that mimic a random series. For example, all possible values occur equally often in a pseudo-random series.

In Emacs, pseudo-random numbers are generated from a "seed" number. Starting from any given seed, the random function always generates the same sequence of numbers. Emacs always starts with the same seed value, so the sequence of values of random is actually the same in each Emacs run! For example, in one operating system, the first call to (random) after you start Emacs always returns -1457731, and the second one always returns -7692030. This repeatability is helpful for debugging.

If you want random numbers that don't always come out the same, execute (random t). This chooses a new seed based on the current time of day and on Emacs's process ID number.

Function: random &optional limit

This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers.

If limit is a positive integer, the value is chosen to be nonnegative and less than limit.

If limit is t, it means to choose a new seed based on the current time of day and on Emacs's process ID number.

On some machines, any integer representable in Lisp may be the result of random. On other machines, the result can never be larger than a certain maximum or less than a certain (negative) minimum.

4. Strings and Characters

A string in Emacs Lisp is an array that contains an ordered sequence of characters. Strings are used as names of symbols, buffers, and files; to send messages to users; to hold text being copied between buffers; and for many other purposes. Because strings are so important, Emacs Lisp has many functions expressly for manipulating them. Emacs Lisp programs use strings more often than individual characters.

See section 21.6.14 Putting Keyboard Events in Strings, for special considerations for strings of keyboard character events.

4.1 String and Character Basics		Basic properties of strings and characters.
4.2 The Predicates for Strings		Testing whether an object is a string or char.
4.3 Creating Strings		Functions to allocate new strings.
4.4 Modifying Strings		Altering the contents of an existing string.
4.5 Comparison of Characters and Strings		Comparing characters or strings.
4.6 Conversion of Characters and Strings		Converting to and from characters and strings.
4.7 Formatting Strings		format: Emacs's analogue of printf.
4.8 Case Conversion in Lisp		Case conversion functions.
4.9 The Case Table		Customizing case conversion.