Top (GNU Emacs Lisp Reference Manual)

Emacs Lisp

This is the GNU Emacs Lisp Reference Manual corresponding to Emacs version 28.0.50.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being “GNU General Public License,” with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”

• Introduction:		Introduction and conventions used.

• Lisp Data Types:		Data types of objects in Emacs Lisp.
• Numbers:		Numbers and arithmetic functions.
• Strings and Characters:		Strings, and functions that work on them.
• Lists:		Lists, cons cells, and related functions.
• Sequences Arrays Vectors:		Lists, strings and vectors are called sequences. Certain functions act on any kind of sequence. The description of vectors is here as well.
• Records:		Compound objects with programmer-defined types.
• Hash Tables:		Very fast lookup-tables.
• Symbols:		Symbols represent names, uniquely.

• Evaluation:		How Lisp expressions are evaluated.
• Control Structures:		Conditionals, loops, nonlocal exits.
• Variables:		Using symbols in programs to stand for values.
• Functions:		A function is a Lisp program that can be invoked from other functions.
• Macros:		Macros are a way to extend the Lisp language.
• Customization:		Making variables and faces customizable.

• Loading:		Reading files of Lisp code into Lisp.
• Byte Compilation:		Compilation makes programs run faster.
• Debugging:		Tools and tips for debugging Lisp programs.

• Read and Print:		Converting Lisp objects to text and back.
• Minibuffers:		Using the minibuffer to read input.
• Command Loop:		How the editor command loop works, and how you can call its subroutines.
• Keymaps:		Defining the bindings from keys to commands.
• Modes:		Defining major and minor modes.
• Documentation:		Writing and using documentation strings.

• Files:		Accessing files.
• Backups and Auto-Saving:		Controlling how backups and auto-save files are made.
• Buffers:		Creating and using buffer objects.
• Windows:		Manipulating windows and displaying buffers.
• Frames:		Making multiple system-level windows.
• Positions:		Buffer positions and motion functions.
• Markers:		Markers represent positions and update automatically when the text is changed.

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

• Threads:		Concurrency in Emacs Lisp.
• Processes:		Running and communicating with subprocesses.
• Display:		Features for controlling the screen display.
• System Interface:		Getting the user id, system type, environment variables, and other such things.

• Packaging:		Preparing Lisp code for distribution.
Appendices
• Antinews:		Info for users downgrading to Emacs 26.
• GNU Free Documentation License:		The license for this documentation.
• GPL:		Conditions for copying and changing GNU Emacs.
• Tips:		Advice and coding conventions for Emacs Lisp.
• GNU Emacs Internals:		Building and dumping Emacs; internal data structures.
• Standard Errors:		List of some standard error symbols.
• Standard Keymaps:		List of some standard keymaps.
• Standard Hooks:		List of some standard hook variables.

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

— The Detailed Node Listing — ——————————— Here are other nodes that are subnodes of those already listed, mentioned here so you can get to them in one step: Introduction
• Caveats:		Flaws and a request for help.
• Lisp History:		Emacs Lisp is descended from Maclisp.
• Conventions:		How the manual is formatted.
• Version Info:		Which Emacs version is running?
• Acknowledgments:		The authors, editors, and sponsors of this manual.
Conventions
• Some Terms:		Explanation of terms we use in this manual.
• nil and t:		How the symbols `nil` and `t` are used.
• Evaluation Notation:		The format we use for examples of evaluation.
• Printing Notation:		The format we use when examples print text.
• Error Messages:		The format we use for examples of errors.
• Buffer Text Notation:		The format we use for buffer contents in examples.
• Format of Descriptions:		Notation for describing functions, variables, etc.
Format of Descriptions
• A Sample Function Description:		A description of an imaginary function, `foo`.
• A Sample Variable Description:		A description of an imaginary variable, `electric-future-map`.
Lisp Data Types
• Printed Representation:		How Lisp objects are represented as text.
• Special Read Syntax:		An overview of all the special sequences.
• Comments:		Comments and their formatting conventions.
• Programming Types:		Types found in all Lisp systems.
• Editing Types:		Types specific to Emacs.
• Circular Objects:		Read syntax for circular structure.
• Type Predicates:		Tests related to types.
• Equality Predicates:		Tests of equality between any two objects.
Programming Types
• Integer Type:		Numbers without fractional parts.
• Floating-Point Type:		Numbers with fractional parts and with a large range.
• Character Type:		The representation of letters, numbers and control characters.
• Symbol Type:		A multi-use object that refers to a function, variable, or property list, and has a unique identity.
• Sequence Type:		Both lists and arrays are classified as sequences.
• Cons Cell Type:		Cons cells, and lists (which are made from cons cells).
• Array Type:		Arrays include strings and vectors.
• String Type:		An (efficient) array of characters.
• Vector Type:		One-dimensional arrays.
• Char-Table Type:		One-dimensional sparse arrays indexed by characters.
• Bool-Vector Type:		One-dimensional arrays of `t` or `nil`.
• Hash Table Type:		Super-fast lookup tables.
• Function Type:		A piece of executable code you can call from elsewhere.
• Macro Type:		A method of expanding an expression into another expression, more fundamental but less pretty.
• Primitive Function Type:		A function written in C, callable from Lisp.
• Byte-Code Type:		A function written in Lisp, then compiled.
• Record Type:		Compound objects with programmer-defined types.
• Type Descriptors:		Objects holding information about types.
• Autoload Type:		A type used for automatically loading seldom-used functions.
• Finalizer Type:		Runs code when no longer reachable.
Character Type
• Basic Char Syntax:		Syntax for regular characters.
• General Escape Syntax:		How to specify characters by their codes.
• Ctl-Char Syntax:		Syntax for control characters.
• Meta-Char Syntax:		Syntax for meta-characters.
• Other Char Bits:		Syntax for hyper-, super-, and alt-characters.
Cons Cell and List Types
• Box Diagrams:		Drawing pictures of lists.
• Dotted Pair Notation:		A general syntax for cons cells.
• Association List Type:		A specially constructed list.
String Type
• Syntax for Strings:		How to specify Lisp strings.
• Non-ASCII in Strings:		International characters in strings.
• Nonprinting Characters:		Literal unprintable characters in strings.
• Text Props and Strings:		Strings with text properties.
Editing Types
• Buffer Type:		The basic object of editing.
• Marker Type:		A position in a buffer.
• Window Type:		Buffers are displayed in windows.
• Frame Type:		Windows subdivide frames.
• Terminal Type:		A terminal device displays frames.
• Window Configuration Type:		Recording the way a frame is subdivided.
• Frame Configuration Type:		Recording the status of all frames.
• Process Type:		A subprocess of Emacs running on the underlying OS.
• Thread Type:		A thread of Emacs Lisp execution.
• Mutex Type:		An exclusive lock for thread synchronization.
• Condition Variable Type:		Condition variable for thread synchronization.
• Stream Type:		Receive or send characters.
• Keymap Type:		What function a keystroke invokes.
• Overlay Type:		How an overlay is represented.
• Font Type:		Fonts for displaying text.
Numbers
• Integer Basics:		Representation and range of integers.
• Float Basics:		Representation and range of floating point.
• Predicates on Numbers:		Testing for numbers.
• Comparison of Numbers:		Equality and inequality predicates.
• Numeric Conversions:		Converting float to integer and vice versa.
• Arithmetic Operations:		How to add, subtract, multiply and divide.
• Rounding Operations:		Explicitly rounding floating-point numbers.
• Bitwise Operations:		Logical and, or, not, shifting.
• Math Functions:		Trig, exponential and logarithmic functions.
• Random Numbers:		Obtaining random integers, predictable or not.
Strings and Characters
• String Basics:		Basic properties of strings and characters.
• Predicates for Strings:		Testing whether an object is a string or char.
• Creating Strings:		Functions to allocate new strings.
• Modifying Strings:		Altering the contents of an existing string.
• Text Comparison:		Comparing characters or strings.
• String Conversion:		Converting to and from characters and strings.
• Formatting Strings:		`format`: Emacs’s analogue of `printf`.
• Case Conversion:		Case conversion functions.
• Case Tables:		Customizing case conversion.
Lists
• Cons Cells:		How lists are made out of cons cells.
• List-related Predicates:		Is this object a list? Comparing two lists.
• List Elements:		Extracting the pieces of a list.
• Building Lists:		Creating list structure.
• List Variables:		Modifying lists stored in variables.
• Modifying Lists:		Storing new pieces into an existing list.
• Sets And Lists:		A list can represent a finite mathematical set.
• Association Lists:		A list can represent a finite relation or mapping.
• Property Lists:		A list of paired elements.
Modifying Existing List Structure
• Setcar:		Replacing an element in a list.
• Setcdr:		Replacing part of the list backbone. This can be used to remove or add elements.
• Rearrangement:		Reordering the elements in a list; combining lists.
Property Lists
• Plists and Alists:		Comparison of the advantages of property lists and association lists.
• Plist Access:		Accessing property lists stored elsewhere.
Sequences, Arrays, and Vectors
• Sequence Functions:		Functions that accept any kind of sequence.
• Arrays:		Characteristics of arrays in Emacs Lisp.
• Array Functions:		Functions specifically for arrays.
• Vectors:		Special characteristics of Emacs Lisp vectors.
• Vector Functions:		Functions specifically for vectors.
• Char-Tables:		How to work with char-tables.
• Bool-Vectors:		How to work with bool-vectors.
• Rings:		Managing a fixed-size ring of objects.
Records
• Record Functions:		Functions for records.
• Backward Compatibility:		Compatibility for cl-defstruct.
Hash Tables
• Creating Hash:		Functions to create hash tables.
• Hash Access:		Reading and writing the hash table contents.
• Defining Hash:		Defining new comparison methods.
• Other Hash:		Miscellaneous.
Symbols
• Symbol Components:		Symbols have names, values, function definitions and property lists.
• Definitions:		A definition says how a symbol will be used.
• Creating Symbols:		How symbols are kept unique.
• Symbol Properties:		Each symbol has a property list for recording miscellaneous information.
Symbol Properties
• Symbol Plists:		Accessing symbol properties.
• Standard Properties:		Standard meanings of symbol properties.
Evaluation
• Intro Eval:		Evaluation in the scheme of things.
• Forms:		How various sorts of objects are evaluated.
• Quoting:		Avoiding evaluation (to put constants in the program).
• Backquote:		Easier construction of list structure.
• Eval:		How to invoke the Lisp interpreter explicitly.
• Deferred Eval:		Deferred and lazy evaluation of forms.
Kinds of Forms
• Self-Evaluating Forms:		Forms that evaluate to themselves.
• Symbol Forms:		Symbols evaluate as variables.
• Classifying Lists:		How to distinguish various sorts of list forms.
• Function Indirection:		When a symbol appears as the car of a list, we find the real function via the symbol.
• Function Forms:		Forms that call functions.
• Macro Forms:		Forms that call macros.
• Special Forms:		Special forms are idiosyncratic primitives, most of them extremely important.
• Autoloading:		Functions set up to load files containing their real definitions.
Control Structures
• Sequencing:		Evaluation in textual order.
• Conditionals:		`if`, `cond`, `when`, `unless`.
• Combining Conditions:		`and`, `or`, `not`.
• Pattern-Matching Conditional:		How to use `pcase` and friends.
• Iteration:		`while` loops.
• Generators:		Generic sequences and coroutines.
• Nonlocal Exits:		Jumping out of a sequence.
Nonlocal Exits
• Catch and Throw:		Nonlocal exits for the program’s own purposes.
• Examples of Catch:		Showing how such nonlocal exits can be written.
• Errors:		How errors are signaled and handled.
• Cleanups:		Arranging to run a cleanup form if an error happens.
Errors
• Signaling Errors:		How to report an error.
• Processing of Errors:		What Emacs does when you report an error.
• Handling Errors:		How you can trap errors and continue execution.
• Error Symbols:		How errors are classified for trapping them.
Variables
• Global Variables:		Variable values that exist permanently, everywhere.
• Constant Variables:		Variables that never change.
• Local Variables:		Variable values that exist only temporarily.
• Void Variables:		Symbols that lack values.
• Defining Variables:		A definition says a symbol is used as a variable.
• Tips for Defining:		Things you should think about when you define a variable.
• Accessing Variables:		Examining values of variables whose names are known only at run time.
• Setting Variables:		Storing new values in variables.
• Watching Variables:		Running a function when a variable is changed.
• Variable Scoping:		How Lisp chooses among local and global values.
• Buffer-Local Variables:		Variable values in effect only in one buffer.
• File Local Variables:		Handling local variable lists in files.
• Directory Local Variables:		Local variables common to all files in a directory.
• Connection Local Variables:		Local variables common for remote connections.
• Variable Aliases:		Variables that are aliases for other variables.
• Variables with Restricted Values:		Non-constant variables whose value can not be an arbitrary Lisp object.
• Generalized Variables:		Extending the concept of variables.
Scoping Rules for Variable Bindings
• Dynamic Binding:		The default for binding local variables in Emacs.
• Dynamic Binding Tips:		Avoiding problems with dynamic binding.
• Lexical Binding:		A different type of local variable binding.
• Using Lexical Binding:		How to enable lexical binding.
Buffer-Local Variables
• Intro to Buffer-Local:		Introduction and concepts.
• Creating Buffer-Local:		Creating and destroying buffer-local bindings.
• Default Value:		The default value is seen in buffers that don’t have their own buffer-local values.
Generalized Variables
• Setting Generalized Variables:		The `setf` macro.
• Adding Generalized Variables:		Defining new `setf` forms.
Functions
• What Is a Function:		Lisp functions vs. primitives; terminology.
• Lambda Expressions:		How functions are expressed as Lisp objects.
• Function Names:		A symbol can serve as the name of a function.
• Defining Functions:		Lisp expressions for defining functions.
• Calling Functions:		How to use an existing function.
• Mapping Functions:		Applying a function to each element of a list, etc.
• Anonymous Functions:		Lambda expressions are functions with no names.
• Generic Functions:		Polymorphism, Emacs-style.
• Function Cells:		Accessing or setting the function definition of a symbol.
• Closures:		Functions that enclose a lexical environment.
• Advising Functions:		Adding to the definition of a function.
• Obsolete Functions:		Declaring functions obsolete.
• Inline Functions:		Defining functions that the compiler will expand inline.
• Declare Form:		Adding additional information about a function.
• Declaring Functions:		Telling the compiler that a function is defined.
• Function Safety:		Determining whether a function is safe to call.
• Related Topics:		Cross-references to specific Lisp primitives that have a special bearing on how functions work.
Lambda Expressions
• Lambda Components:		The parts of a lambda expression.
• Simple Lambda:		A simple example.
• Argument List:		Details and special features of argument lists.
• Function Documentation:		How to put documentation in a function.
Advising Emacs Lisp Functions
• Core Advising Primitives:		Primitives to manipulate advice.
• Advising Named Functions:		Advising named functions.
• Advice Combinators:		Ways to compose advice.
• Porting Old Advice:		Adapting code using the old defadvice.
Macros
• Simple Macro:		A basic example.
• Expansion:		How, when and why macros are expanded.
• Compiling Macros:		How macros are expanded by the compiler.
• Defining Macros:		How to write a macro definition.
• Problems with Macros:		Don’t evaluate the macro arguments too many times. Don’t hide the user’s variables.
• Indenting Macros:		Specifying how to indent macro calls.
Common Problems Using Macros
• Wrong Time:		Do the work in the expansion, not in the macro.
• Argument Evaluation:		The expansion should evaluate each macro arg once.
• Surprising Local Vars:		Local variable bindings in the expansion require special care.
• Eval During Expansion:		Don’t evaluate them; put them in the expansion.
• Repeated Expansion:		Avoid depending on how many times expansion is done.
Customization Settings
• Common Keywords:		Common keyword arguments for all kinds of customization declarations.
• Group Definitions:		Writing customization group definitions.
• Variable Definitions:		Declaring user options.
• Customization Types:		Specifying the type of a user option.
• Applying Customizations:		Functions to apply customization settings.
• Custom Themes:		Writing Custom themes.
Customization Types
• Simple Types:		Simple customization types: sexp, integer, etc.
• Composite Types:		Build new types from other types or data.
• Splicing into Lists:		Splice elements into list with `:inline`.
• Type Keywords:		Keyword-argument pairs in a customization type.
• Defining New Types:		Give your type a name.
Loading
• How Programs Do Loading:		The `load` function and others.
• Load Suffixes:		Details about the suffixes that `load` tries.
• Library Search:		Finding a library to load.
• Loading Non-ASCII:		Non-ASCII characters in Emacs Lisp files.
• Autoload:		Setting up a function to autoload.
• Repeated Loading:		Precautions about loading a file twice.
• Named Features:		Loading a library if it isn’t already loaded.
• Where Defined:		Finding which file defined a certain symbol.
• Unloading:		How to unload a library that was loaded.
• Hooks for Loading:		Providing code to be run when particular libraries are loaded.
• Dynamic Modules:		Modules provide additional Lisp primitives.
Byte Compilation
• Speed of Byte-Code:		An example of speedup from byte compilation.
• Compilation Functions:		Byte compilation functions.
• Docs and Compilation:		Dynamic loading of documentation strings.
• Dynamic Loading:		Dynamic loading of individual functions.
• Eval During Compile:		Code to be evaluated when you compile.
• Compiler Errors:		Handling compiler error messages.
• Byte-Code Objects:		The data type used for byte-compiled functions.
• Disassembly:		Disassembling byte-code; how to read byte-code.
Debugging Lisp Programs
• Debugger:		A debugger for the Emacs Lisp evaluator.
• Edebug:		A source-level Emacs Lisp debugger.
• Syntax Errors:		How to find syntax errors.
• Test Coverage:		Ensuring you have tested all branches in your code.
• Profiling:		Measuring the resources that your code uses.
The Lisp Debugger
• Error Debugging:		Entering the debugger when an error happens.
• Infinite Loops:		Stopping and debugging a program that doesn’t exit.
• Function Debugging:		Entering it when a certain function is called.
• Variable Debugging:		Entering it when a variable is modified.
• Explicit Debug:		Entering it at a certain point in the program.
• Using Debugger:		What the debugger does.
• Backtraces:		What you see while in the debugger.
• Debugger Commands:		Commands used while in the debugger.
• Invoking the Debugger:		How to call the function `debug`.
• Internals of Debugger:		Subroutines of the debugger, and global variables.
Edebug
• Using Edebug:		Introduction to use of Edebug.
• Instrumenting:		You must instrument your code in order to debug it with Edebug.
• Edebug Execution Modes:		Execution modes, stopping more or less often.
• Jumping:		Commands to jump to a specified place.
• Edebug Misc:		Miscellaneous commands.
• Breaks:		Setting breakpoints to make the program stop.
• Trapping Errors:		Trapping errors with Edebug.
• Edebug Views:		Views inside and outside of Edebug.
• Edebug Eval:		Evaluating expressions within Edebug.
• Eval List:		Expressions whose values are displayed each time you enter Edebug.
• Printing in Edebug:		Customization of printing.
• Trace Buffer:		How to produce trace output in a buffer.
• Coverage Testing:		How to test evaluation coverage.
• The Outside Context:		Data that Edebug saves and restores.
• Edebug and Macros:		Specifying how to handle macro calls.
• Edebug Options:		Option variables for customizing Edebug.
Breaks
• Breakpoints:		Breakpoints at stop points.
• Global Break Condition:		Breaking on an event.
• Source Breakpoints:		Embedding breakpoints in source code.
The Outside Context
• Checking Whether to Stop:		When Edebug decides what to do.
• Edebug Display Update:		When Edebug updates the display.
• Edebug Recursive Edit:		When Edebug stops execution.
Edebug and Macros
• Instrumenting Macro Calls:		The basic problem.
• Specification List:		How to specify complex patterns of evaluation.
• Backtracking:		What Edebug does when matching fails.
• Specification Examples:		To help understand specifications.
Debugging Invalid Lisp Syntax
• Excess Open:		How to find a spurious open paren or missing close.
• Excess Close:		How to find a spurious close paren or missing open.
Reading and Printing Lisp Objects
• Streams Intro:		Overview of streams, reading and printing.
• Input Streams:		Various data types that can be used as input streams.
• Input Functions:		Functions to read Lisp objects from text.
• Output Streams:		Various data types that can be used as output streams.
• Output Functions:		Functions to print Lisp objects as text.
• Output Variables:		Variables that control what the printing functions do.
Minibuffers
• Intro to Minibuffers:		Basic information about minibuffers.
• Text from Minibuffer:		How to read a straight text string.
• Object from Minibuffer:		How to read a Lisp object or expression.
• Minibuffer History:		Recording previous minibuffer inputs so the user can reuse them.
• Initial Input:		Specifying initial contents for the minibuffer.
• Completion:		How to invoke and customize completion.
• Yes-or-No Queries:		Asking a question with a simple answer.
• Multiple Queries:		Asking a series of similar questions.
• Reading a Password:		Reading a password from the terminal.
• Minibuffer Commands:		Commands used as key bindings in minibuffers.
• Minibuffer Windows:		Operating on the special minibuffer windows.
• Minibuffer Contents:		How such commands access the minibuffer text.
• Recursive Mini:		Whether recursive entry to minibuffer is allowed.
• Minibuffer Misc:		Various customization hooks and variables.
Completion
• Basic Completion:		Low-level functions for completing strings.
• Minibuffer Completion:		Invoking the minibuffer with completion.
• Completion Commands:		Minibuffer commands that do completion.
• High-Level Completion:		Convenient special cases of completion (reading buffer names, variable names, etc.).
• Reading File Names:		Using completion to read file names and shell commands.
• Completion Variables:		Variables controlling completion behavior.
• Programmed Completion:		Writing your own completion function.
• Completion in Buffers:		Completing text in ordinary buffers.
Command Loop
• Command Overview:		How the command loop reads commands.
• Defining Commands:		Specifying how a function should read arguments.
• Interactive Call:		Calling a command, so that it will read arguments.
• Distinguish Interactive:		Making a command distinguish interactive calls.
• Command Loop Info:		Variables set by the command loop for you to examine.
• Adjusting Point:		Adjustment of point after a command.
• Input Events:		What input looks like when you read it.
• Reading Input:		How to read input events from the keyboard or mouse.
• Special Events:		Events processed immediately and individually.
• Waiting:		Waiting for user input or elapsed time.
• Quitting:		How `C-g` works. How to catch or defer quitting.
• Prefix Command Arguments:		How the commands to set prefix args work.
• Recursive Editing:		Entering a recursive edit, and why you usually shouldn’t.
• Disabling Commands:		How the command loop handles disabled commands.
• Command History:		How the command history is set up, and how accessed.
• Keyboard Macros:		How keyboard macros are implemented.
Defining Commands
• Using Interactive:		General rules for `interactive`.
• Interactive Codes:		The standard letter-codes for reading arguments in various ways.
• Interactive Examples:		Examples of how to read interactive arguments.
• Generic Commands:		Select among command alternatives.
Input Events
• Keyboard Events:		Ordinary characters – keys with symbols on them.
• Function Keys:		Function keys – keys with names, not symbols.
• Mouse Events:		Overview of mouse events.
• Click Events:		Pushing and releasing a mouse button.
• Drag Events:		Moving the mouse before releasing the button.
• Button-Down Events:		A button was pushed and not yet released.
• Repeat Events:		Double and triple click (or drag, or down).
• Motion Events:		Just moving the mouse, not pushing a button.
• Focus Events:		Moving the mouse between frames.
• Misc Events:		Other events the system can generate.
• Event Examples:		Examples of the lists for mouse events.
• Classifying Events:		Finding the modifier keys in an event symbol. Event types.
• Accessing Mouse:		Functions to extract info from mouse events.
• Accessing Scroll:		Functions to get info from scroll bar events.
• Strings of Events:		Special considerations for putting keyboard character events in a string.
Reading Input
• Key Sequence Input:		How to read one key sequence.
• Reading One Event:		How to read just one event.
• Event Mod:		How Emacs modifies events as they are read.
• Invoking the Input Method:		How reading an event uses the input method.
• Quoted Character Input:		Asking the user to specify a character.
• Event Input Misc:		How to reread or throw away input events.
Keymaps
• Key Sequences:		Key sequences as Lisp objects.
• Keymap Basics:		Basic concepts of keymaps.
• Format of Keymaps:		What a keymap looks like as a Lisp object.
• Creating Keymaps:		Functions to create and copy keymaps.
• Inheritance and Keymaps:		How one keymap can inherit the bindings of another keymap.
• Prefix Keys:		Defining a key with a keymap as its definition.
• Active Keymaps:		How Emacs searches the active keymaps for a key binding.
• Searching Keymaps:		A pseudo-Lisp summary of searching active maps.
• Controlling Active Maps:		Each buffer has a local keymap to override the standard (global) bindings. A minor mode can also override them.
• Key Lookup:		Finding a key’s binding in one keymap.
• Functions for Key Lookup:		How to request key lookup.
• Changing Key Bindings:		Redefining a key in a keymap.
• Remapping Commands:		A keymap can translate one command to another.
• Translation Keymaps:		Keymaps for translating sequences of events.
• Key Binding Commands:		Interactive interfaces for redefining keys.
• Scanning Keymaps:		Looking through all keymaps, for printing help.
• Menu Keymaps:		Defining a menu as a keymap.
Menu Keymaps
• Defining Menus:		How to make a keymap that defines a menu.
• Mouse Menus:		How users actuate the menu with the mouse.
• Keyboard Menus:		How users actuate the menu with the keyboard.
• Menu Example:		Making a simple menu.
• Menu Bar:		How to customize the menu bar.
• Tool Bar:		A tool bar is a row of images.
• Modifying Menus:		How to add new items to a menu.
• Easy Menu:		A convenience macro for defining menus.
Defining Menus
• Simple Menu Items:		A simple kind of menu key binding.
• Extended Menu Items:		More complex menu item definitions.
• Menu Separators:		Drawing a horizontal line through a menu.
• Alias Menu Items:		Using command aliases in menu items.
Major and Minor Modes

• Introduction:

Introduction and conventions used.

• Lisp Data Types:

Data types of objects in Emacs Lisp.

• Numbers:

Numbers and arithmetic functions.

• Strings and Characters:

Strings, and functions that work on them.

• Lists:

Lists, cons cells, and related functions.

• Sequences Arrays Vectors:

Lists, strings and vectors are called sequences. Certain functions act on any kind of sequence. The description of vectors is here as well.

• Records:

Compound objects with programmer-defined types.

• Hash Tables:

Very fast lookup-tables.

• Symbols:

Symbols represent names, uniquely.

• Evaluation:

How Lisp expressions are evaluated.

• Control Structures:

Conditionals, loops, nonlocal exits.

• Variables:

Using symbols in programs to stand for values.

• Functions:

A function is a Lisp program that can be invoked from other functions.

• Macros:

Macros are a way to extend the Lisp language.

• Customization:

Making variables and faces customizable.

• Loading:

Reading files of Lisp code into Lisp.

• Byte Compilation:

Compilation makes programs run faster.

• Debugging:

Tools and tips for debugging Lisp programs.

• Read and Print:

Converting Lisp objects to text and back.

• Minibuffers:

Using the minibuffer to read input.

• Command Loop:

How the editor command loop works, and how you can call its subroutines.

• Keymaps:

Defining the bindings from keys to commands.

• Modes:

Defining major and minor modes.

• Documentation:

Writing and using documentation strings.

• Files:

Accessing files.

• Backups and Auto-Saving:

Controlling how backups and auto-save files are made.

• Buffers:

Creating and using buffer objects.

• Windows:

Manipulating windows and displaying buffers.

• Frames:

Making multiple system-level windows.

• Positions:

Buffer positions and motion functions.

• Markers:

Markers represent positions and update automatically when the text is changed.

• Text:

Examining and changing text in buffers.

• Non-ASCII Characters:

Non-ASCII text in buffers and strings.

• Searching and Matching:

Searching buffers for strings or regexps.

• Syntax Tables:

The syntax table controls word and list parsing.

• Abbrevs:

How Abbrev mode works, and its data structures.

• Threads:

Concurrency in Emacs Lisp.

• Processes:

Running and communicating with subprocesses.

• Display:

Features for controlling the screen display.

• System Interface:

Getting the user id, system type, environment variables, and other such things.

• Packaging:

Preparing Lisp code for distribution.


Appendices

• Antinews:

Info for users downgrading to Emacs 26.

• GNU Free Documentation License:

The license for this documentation.

• GPL:

Conditions for copying and changing GNU Emacs.

• Tips:

Advice and coding conventions for Emacs Lisp.

• GNU Emacs Internals:

Building and dumping Emacs; internal data structures.

• Standard Errors:

List of some standard error symbols.

• Standard Keymaps:

List of some standard keymaps.

• Standard Hooks:

List of some standard hook variables.

• Index:

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

 — The Detailed Node Listing —
 ———————————

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

Introduction

• Caveats:

Flaws and a request for help.

• Lisp History:

Emacs Lisp is descended from Maclisp.

• Conventions:

How the manual is formatted.

• Version Info:

Which Emacs version is running?

• Acknowledgments:

The authors, editors, and sponsors of this manual.


Conventions

• Some Terms:

Explanation of terms we use in this manual.

• nil and t:

How the symbols nil and t are used.

• Evaluation Notation:

The format we use for examples of evaluation.

• Printing Notation:

The format we use when examples print text.

• Error Messages:

The format we use for examples of errors.

• Buffer Text Notation:

The format we use for buffer contents in examples.

• Format of Descriptions:

Notation for describing functions, variables, etc.


Format of Descriptions

• A Sample Function Description:

A description of an imaginary function, foo.

• A Sample Variable Description:

A description of an imaginary variable, electric-future-map.


Lisp Data Types

• Printed Representation:

How Lisp objects are represented as text.

• Special Read Syntax:

An overview of all the special sequences.

• Comments:

Comments and their formatting conventions.

• Programming Types:

Types found in all Lisp systems.

• Editing Types:

Types specific to Emacs.

• Circular Objects:

Read syntax for circular structure.

• Type Predicates:

Tests related to types.

• Equality Predicates:

Tests of equality between any two objects.


Programming Types

• Integer Type:

Numbers without fractional parts.

• Floating-Point Type:

Numbers with fractional parts and with a large range.

• Character Type:

The representation of letters, numbers and control characters.

• Symbol Type:

A multi-use object that refers to a function, variable, or property list, and has a unique identity.

• Sequence Type:

Both lists and arrays are classified as sequences.

• Cons Cell Type:

Cons cells, and lists (which are made from cons cells).

• Array Type:

Arrays include strings and vectors.

• String Type:

An (efficient) array of characters.

• Vector Type:

One-dimensional arrays.

• Char-Table Type:

One-dimensional sparse arrays indexed by characters.

• Bool-Vector Type:

One-dimensional arrays of t or nil.

• Hash Table Type:

Super-fast lookup tables.

• Function Type:

A piece of executable code you can call from elsewhere.

• Macro Type:

A method of expanding an expression into another expression, more fundamental but less pretty.

• Primitive Function Type:

A function written in C, callable from Lisp.

• Byte-Code Type:

A function written in Lisp, then compiled.

• Record Type:

Compound objects with programmer-defined types.

• Type Descriptors:

Objects holding information about types.

• Autoload Type:

A type used for automatically loading seldom-used functions.

• Finalizer Type:

Runs code when no longer reachable.


Character Type

• Basic Char Syntax:

Syntax for regular characters.

• General Escape Syntax:

How to specify characters by their codes.

• Ctl-Char Syntax:

Syntax for control characters.

• Meta-Char Syntax:

Syntax for meta-characters.

• Other Char Bits:

Syntax for hyper-, super-, and alt-characters.


Cons Cell and List Types

• Box Diagrams:

Drawing pictures of lists.

• Dotted Pair Notation:

A general syntax for cons cells.

• Association List Type:

A specially constructed list.


String Type

• Syntax for Strings:

How to specify Lisp strings.

• Non-ASCII in Strings:

International characters in strings.

• Nonprinting Characters:

Literal unprintable characters in strings.

• Text Props and Strings:

Strings with text properties.


Editing Types

• Buffer Type:

The basic object of editing.

• Marker Type:

A position in a buffer.

• Window Type:

Buffers are displayed in windows.

• Frame Type:

Windows subdivide frames.

• Terminal Type:

A terminal device displays frames.

• Window Configuration Type:

Recording the way a frame is subdivided.

• Frame Configuration Type:

Recording the status of all frames.

• Process Type:

A subprocess of Emacs running on the underlying OS.

• Thread Type:

A thread of Emacs Lisp execution.

• Mutex Type:

An exclusive lock for thread synchronization.

• Condition Variable Type:

Condition variable for thread synchronization.

• Stream Type:

Receive or send characters.

• Keymap Type:

What function a keystroke invokes.

• Overlay Type:

How an overlay is represented.

• Font Type:

Fonts for displaying text.


Numbers

• Integer Basics:

Representation and range of integers.

• Float Basics:

Representation and range of floating point.

• Predicates on Numbers:

Testing for numbers.

• Comparison of Numbers:

Equality and inequality predicates.

• Numeric Conversions:

Converting float to integer and vice versa.

• Arithmetic Operations:

How to add, subtract, multiply and divide.

• Rounding Operations:

Explicitly rounding floating-point numbers.

• Bitwise Operations:

Logical and, or, not, shifting.

• Math Functions:

Trig, exponential and logarithmic functions.

• Random Numbers:

Obtaining random integers, predictable or not.


Strings and Characters

• String Basics:

Basic properties of strings and characters.

• Predicates for Strings:

Testing whether an object is a string or char.

• Creating Strings:

Functions to allocate new strings.

• Modifying Strings:

Altering the contents of an existing string.

• Text Comparison:

Comparing characters or strings.

• String Conversion:

Converting to and from characters and strings.

• Formatting Strings:

format: Emacs’s analogue of printf.

• Case Conversion:

Case conversion functions.

• Case Tables:

Customizing case conversion.


Lists

• Cons Cells:

How lists are made out of cons cells.

• List-related Predicates:

Is this object a list? Comparing two lists.

• List Elements:

Extracting the pieces of a list.

• Building Lists:

Creating list structure.

• List Variables:

Modifying lists stored in variables.

• Modifying Lists:

Storing new pieces into an existing list.

• Sets And Lists:

A list can represent a finite mathematical set.

• Association Lists:

A list can represent a finite relation or mapping.

• Property Lists:

A list of paired elements.


Modifying Existing List Structure

• Setcar:

Replacing an element in a list.

• Setcdr:

Replacing part of the list backbone. This can be used to remove or add elements.

• Rearrangement:

Reordering the elements in a list; combining lists.


Property Lists

• Plists and Alists:

Comparison of the advantages of property lists and association lists.

• Plist Access:

Accessing property lists stored elsewhere.


Sequences, Arrays, and Vectors

• Sequence Functions:

Functions that accept any kind of sequence.

• Arrays:

Characteristics of arrays in Emacs Lisp.

• Array Functions:

Functions specifically for arrays.

• Vectors:

Special characteristics of Emacs Lisp vectors.

• Vector Functions:

Functions specifically for vectors.

• Char-Tables:

How to work with char-tables.

• Bool-Vectors:

How to work with bool-vectors.

• Rings:

Managing a fixed-size ring of objects.


Records

• Record Functions:

Functions for records.

• Backward Compatibility:

Compatibility for cl-defstruct.


Hash Tables

• Creating Hash:

Functions to create hash tables.

• Hash Access:

Reading and writing the hash table contents.

• Defining Hash:

Defining new comparison methods.

• Other Hash:

Miscellaneous.


Symbols

• Symbol Components:

Symbols have names, values, function definitions and property lists.

• Definitions:

A definition says how a symbol will be used.

• Creating Symbols:

How symbols are kept unique.

• Symbol Properties:

Each symbol has a property list for recording miscellaneous information.


Symbol Properties

• Symbol Plists:

Accessing symbol properties.

• Standard Properties:

Standard meanings of symbol properties.


Evaluation

• Intro Eval:

Evaluation in the scheme of things.

• Forms:

How various sorts of objects are evaluated.

• Quoting:

Avoiding evaluation (to put constants in the program).

• Backquote:

Easier construction of list structure.

• Eval:

How to invoke the Lisp interpreter explicitly.

• Deferred Eval:

Deferred and lazy evaluation of forms.


Kinds of Forms

• Self-Evaluating Forms:

Forms that evaluate to themselves.

• Symbol Forms:

Symbols evaluate as variables.

• Classifying Lists:

How to distinguish various sorts of list forms.

• Function Indirection:

When a symbol appears as the car of a list, we find the real function via the symbol.

• Function Forms:

Forms that call functions.

• Macro Forms:

Forms that call macros.

• Special Forms:

Special forms are idiosyncratic primitives, most of them extremely important.

• Autoloading:

Functions set up to load files containing their real definitions.


Control Structures

• Sequencing:

Evaluation in textual order.

• Conditionals:

if, cond, when, unless.

• Combining Conditions:

and, or, not.

• Pattern-Matching Conditional:

How to use pcase and friends.

• Iteration:

while loops.

• Generators:

Generic sequences and coroutines.

• Nonlocal Exits:

Jumping out of a sequence.


Nonlocal Exits

• Catch and Throw:

Nonlocal exits for the program’s own purposes.

• Examples of Catch:

Showing how such nonlocal exits can be written.

• Errors:

How errors are signaled and handled.

• Cleanups:

Arranging to run a cleanup form if an error happens.


Errors

• Signaling Errors:

How to report an error.

• Processing of Errors:

What Emacs does when you report an error.

• Handling Errors:

How you can trap errors and continue execution.

• Error Symbols:

How errors are classified for trapping them.


Variables

• Global Variables:

Variable values that exist permanently, everywhere.

• Constant Variables:

Variables that never change.

• Local Variables:

Variable values that exist only temporarily.

• Void Variables:

Symbols that lack values.

• Defining Variables:

A definition says a symbol is used as a variable.

• Tips for Defining:

Things you should think about when you define a variable.

• Accessing Variables:

Examining values of variables whose names are known only at run time.

• Setting Variables:

Storing new values in variables.

• Watching Variables:

Running a function when a variable is changed.

• Variable Scoping:

How Lisp chooses among local and global values.

• Buffer-Local Variables:

Variable values in effect only in one buffer.

• File Local Variables:

Handling local variable lists in files.

• Directory Local Variables:

Local variables common to all files in a directory.

• Connection Local Variables:

Local variables common for remote connections.

• Variable Aliases:

Variables that are aliases for other variables.

• Variables with Restricted Values:

Non-constant variables whose value can not be an arbitrary Lisp object.

• Generalized Variables:

Extending the concept of variables.


Scoping Rules for Variable Bindings

• Dynamic Binding:

The default for binding local variables in Emacs.

• Dynamic Binding Tips:

Avoiding problems with dynamic binding.

• Lexical Binding:

A different type of local variable binding.

• Using Lexical Binding:

How to enable lexical binding.


Buffer-Local Variables

• Intro to Buffer-Local:

Introduction and concepts.

• Creating Buffer-Local:

Creating and destroying buffer-local bindings.

• Default Value:

The default value is seen in buffers that don’t have their own buffer-local values.


Generalized Variables

• Setting Generalized Variables:

The setf macro.

• Adding Generalized Variables:

Defining new setf forms.


Functions

• What Is a Function:

Lisp functions vs. primitives; terminology.

• Lambda Expressions:

How functions are expressed as Lisp objects.

• Function Names:

A symbol can serve as the name of a function.

• Defining Functions:

Lisp expressions for defining functions.

• Calling Functions:

How to use an existing function.

• Mapping Functions:

Applying a function to each element of a list, etc.

• Anonymous Functions:

Lambda expressions are functions with no names.

• Generic Functions:

Polymorphism, Emacs-style.

• Function Cells:

Accessing or setting the function definition of a symbol.

• Closures:

Functions that enclose a lexical environment.

• Advising Functions:

Adding to the definition of a function.

• Obsolete Functions:

Declaring functions obsolete.

• Inline Functions:

Defining functions that the compiler will expand inline.

• Declare Form:

Adding additional information about a function.

• Declaring Functions:

Telling the compiler that a function is defined.

• Function Safety:

Determining whether a function is safe to call.

• Related Topics:

Cross-references to specific Lisp primitives that have a special bearing on how functions work.


Lambda Expressions

• Lambda Components:

The parts of a lambda expression.

• Simple Lambda:

A simple example.

• Argument List:

Details and special features of argument lists.

• Function Documentation:

How to put documentation in a function.


Advising Emacs Lisp Functions

• Core Advising Primitives:

Primitives to manipulate advice.

• Advising Named Functions:

Advising named functions.

• Advice Combinators:

Ways to compose advice.

• Porting Old Advice:

Adapting code using the old defadvice.


Macros

• Simple Macro:

A basic example.

• Expansion:

How, when and why macros are expanded.

• Compiling Macros:

How macros are expanded by the compiler.

• Defining Macros:

How to write a macro definition.

• Problems with Macros:

Don’t evaluate the macro arguments too many times. Don’t hide the user’s variables.

• Indenting Macros:

Specifying how to indent macro calls.


Common Problems Using Macros

• Wrong Time:

Do the work in the expansion, not in the macro.

• Argument Evaluation:

The expansion should evaluate each macro arg once.

• Surprising Local Vars:

Local variable bindings in the expansion require special care.

• Eval During Expansion:

Don’t evaluate them; put them in the expansion.

• Repeated Expansion:

Avoid depending on how many times expansion is done.


Customization Settings

• Common Keywords:

Common keyword arguments for all kinds of customization declarations.

• Group Definitions:

Writing customization group definitions.

• Variable Definitions:

Declaring user options.

• Customization Types:

Specifying the type of a user option.

• Applying Customizations:

Functions to apply customization settings.

• Custom Themes:

Writing Custom themes.


Customization Types

• Simple Types:

Simple customization types: sexp, integer, etc.

• Composite Types:

Build new types from other types or data.

• Splicing into Lists:

Splice elements into list with :inline.

• Type Keywords:

Keyword-argument pairs in a customization type.

• Defining New Types:

Give your type a name.


Loading

• How Programs Do Loading:

The load function and others.

• Load Suffixes:

Details about the suffixes that load tries.

• Library Search:

Finding a library to load.

• Loading Non-ASCII:

Non-ASCII characters in Emacs Lisp files.

• Autoload:

Setting up a function to autoload.

• Repeated Loading:

Precautions about loading a file twice.

• Named Features:

Loading a library if it isn’t already loaded.

• Where Defined:

Finding which file defined a certain symbol.

• Unloading:

How to unload a library that was loaded.

• Hooks for Loading:

Providing code to be run when particular libraries are loaded.

• Dynamic Modules:

Modules provide additional Lisp primitives.


Byte Compilation

• Speed of Byte-Code:

An example of speedup from byte compilation.

• Compilation Functions:

Byte compilation functions.

• Docs and Compilation:

Dynamic loading of documentation strings.

• Dynamic Loading:

Dynamic loading of individual functions.

• Eval During Compile:

Code to be evaluated when you compile.

• Compiler Errors:

Handling compiler error messages.

• Byte-Code Objects:

The data type used for byte-compiled functions.

• Disassembly:

Disassembling byte-code; how to read byte-code.


Debugging Lisp Programs

• Debugger:

A debugger for the Emacs Lisp evaluator.

• Edebug:

A source-level Emacs Lisp debugger.

• Syntax Errors:

How to find syntax errors.

• Test Coverage:

Ensuring you have tested all branches in your code.

• Profiling:

Measuring the resources that your code uses.


The Lisp Debugger

• Error Debugging:

Entering the debugger when an error happens.

• Infinite Loops:

Stopping and debugging a program that doesn’t exit.

• Function Debugging:

Entering it when a certain function is called.

• Variable Debugging:

Entering it when a variable is modified.

• Explicit Debug:

Entering it at a certain point in the program.

• Using Debugger:

What the debugger does.

• Backtraces:

What you see while in the debugger.

• Debugger Commands:

Commands used while in the debugger.

• Invoking the Debugger:

How to call the function debug.

• Internals of Debugger:

Subroutines of the debugger, and global variables.


Edebug

• Using Edebug:

Introduction to use of Edebug.

• Instrumenting:

You must instrument your code in order to debug it with Edebug.

• Edebug Execution Modes:

Execution modes, stopping more or less often.

• Jumping:

Commands to jump to a specified place.

• Edebug Misc:

Miscellaneous commands.

• Breaks:

Setting breakpoints to make the program stop.

• Trapping Errors:

Trapping errors with Edebug.

• Edebug Views:

Views inside and outside of Edebug.

• Edebug Eval:

Evaluating expressions within Edebug.

• Eval List:

Expressions whose values are displayed each time you enter Edebug.

• Printing in Edebug:

Customization of printing.

• Trace Buffer:

How to produce trace output in a buffer.

• Coverage Testing:

How to test evaluation coverage.

• The Outside Context:

Data that Edebug saves and restores.

• Edebug and Macros:

Specifying how to handle macro calls.

• Edebug Options:

Option variables for customizing Edebug.


Breaks

• Breakpoints:

Breakpoints at stop points.

• Global Break Condition:

Breaking on an event.

• Source Breakpoints:

Embedding breakpoints in source code.


The Outside Context

• Checking Whether to Stop:

When Edebug decides what to do.

• Edebug Display Update:

When Edebug updates the display.

• Edebug Recursive Edit:

When Edebug stops execution.


Edebug and Macros

• Instrumenting Macro Calls:

The basic problem.

• Specification List:

How to specify complex patterns of evaluation.

• Backtracking:

What Edebug does when matching fails.

• Specification Examples:

To help understand specifications.


Debugging Invalid Lisp Syntax

• Excess Open:

How to find a spurious open paren or missing close.

• Excess Close:

How to find a spurious close paren or missing open.


Reading and Printing Lisp Objects

• Streams Intro:

Overview of streams, reading and printing.

• Input Streams:

Various data types that can be used as input streams.

• Input Functions:

Functions to read Lisp objects from text.

• Output Streams:

Various data types that can be used as output streams.

• Output Functions:

Functions to print Lisp objects as text.

• Output Variables:

Variables that control what the printing functions do.


Minibuffers

• Intro to Minibuffers:

Basic information about minibuffers.

• Text from Minibuffer:

How to read a straight text string.

• Object from Minibuffer:

How to read a Lisp object or expression.

• Minibuffer History:

Recording previous minibuffer inputs so the user can reuse them.

• Initial Input:

Specifying initial contents for the minibuffer.

• Completion:

How to invoke and customize completion.

• Yes-or-No Queries:

Asking a question with a simple answer.

• Multiple Queries:

Asking a series of similar questions.

• Reading a Password:

Reading a password from the terminal.

• Minibuffer Commands:

Commands used as key bindings in minibuffers.

• Minibuffer Windows:

Operating on the special minibuffer windows.

• Minibuffer Contents:

How such commands access the minibuffer text.

• Recursive Mini:

Whether recursive entry to minibuffer is allowed.

• Minibuffer Misc:

Various customization hooks and variables.


Completion

• Basic Completion:

Low-level functions for completing strings.

• Minibuffer Completion:

Invoking the minibuffer with completion.

• Completion Commands:

Minibuffer commands that do completion.

• High-Level Completion:

Convenient special cases of completion (reading buffer names, variable names, etc.).

• Reading File Names:

Using completion to read file names and shell commands.

• Completion Variables:

Variables controlling completion behavior.

• Programmed Completion:

Writing your own completion function.

• Completion in Buffers:

Completing text in ordinary buffers.


Command Loop

• Command Overview:

How the command loop reads commands.

• Defining Commands:

Specifying how a function should read arguments.

• Interactive Call:

Calling a command, so that it will read arguments.

• Distinguish Interactive:

Making a command distinguish interactive calls.

• Command Loop Info:

Variables set by the command loop for you to examine.

• Adjusting Point:

Adjustment of point after a command.

• Input Events:

What input looks like when you read it.

• Reading Input:

How to read input events from the keyboard or mouse.

• Special Events:

Events processed immediately and individually.

• Waiting:

Waiting for user input or elapsed time.

• Quitting:

How C-g works. How to catch or defer quitting.

• Prefix Command Arguments:

How the commands to set prefix args work.

• Recursive Editing:

Entering a recursive edit, and why you usually shouldn’t.

• Disabling Commands:

How the command loop handles disabled commands.

• Command History:

How the command history is set up, and how accessed.

• Keyboard Macros:

How keyboard macros are implemented.


Defining Commands

• Using Interactive:

General rules for interactive.

• Interactive Codes:

The standard letter-codes for reading arguments in various ways.

• Interactive Examples:

Examples of how to read interactive arguments.

• Generic Commands:

Select among command alternatives.



Input Events

• Keyboard Events:

Ordinary characters – keys with symbols on them.

• Function Keys:

Function keys – keys with names, not symbols.

• Mouse Events:

Overview of mouse events.

• Click Events:

Pushing and releasing a mouse button.

• Drag Events:

Moving the mouse before releasing the button.

• Button-Down Events:

A button was pushed and not yet released.

• Repeat Events:

Double and triple click (or drag, or down).

• Motion Events:

Just moving the mouse, not pushing a button.

• Focus Events:

Moving the mouse between frames.

• Misc Events:

Other events the system can generate.

• Event Examples:

Examples of the lists for mouse events.

• Classifying Events:

Finding the modifier keys in an event symbol. Event types.

• Accessing Mouse:

Functions to extract info from mouse events.

• Accessing Scroll:

Functions to get info from scroll bar events.

• Strings of Events:

Special considerations for putting keyboard character events in a string.


Reading Input

• Key Sequence Input:

How to read one key sequence.

• Reading One Event:

How to read just one event.

• Event Mod:

How Emacs modifies events as they are read.

• Invoking the Input Method:

How reading an event uses the input method.

• Quoted Character Input:

Asking the user to specify a character.

• Event Input Misc:

How to reread or throw away input events.


Keymaps

• Key Sequences:

Key sequences as Lisp objects.

• Keymap Basics:

Basic concepts of keymaps.

• Format of Keymaps:

What a keymap looks like as a Lisp object.

• Creating Keymaps:

Functions to create and copy keymaps.

• Inheritance and Keymaps:

How one keymap can inherit the bindings of another keymap.

• Prefix Keys:

Defining a key with a keymap as its definition.

• Active Keymaps:

How Emacs searches the active keymaps for a key binding.

• Searching Keymaps:

A pseudo-Lisp summary of searching active maps.

• Controlling Active Maps:

Each buffer has a local keymap to override the standard (global) bindings. A minor mode can also override them.

• Key Lookup:

Finding a key’s binding in one keymap.

• Functions for Key Lookup:

How to request key lookup.

• Changing Key Bindings:

Redefining a key in a keymap.

• Remapping Commands:

A keymap can translate one command to another.

• Translation Keymaps:

Keymaps for translating sequences of events.

• Key Binding Commands:

Interactive interfaces for redefining keys.

• Scanning Keymaps:

Looking through all keymaps, for printing help.

• Menu Keymaps:

Defining a menu as a keymap.


Menu Keymaps

• Defining Menus:

How to make a keymap that defines a menu.

• Mouse Menus:

How users actuate the menu with the mouse.

• Keyboard Menus:

How users actuate the menu with the keyboard.

• Menu Example:

Making a simple menu.

• Menu Bar:

How to customize the menu bar.

• Tool Bar:

A tool bar is a row of images.

• Modifying Menus:

How to add new items to a menu.

• Easy Menu:

A convenience macro for defining menus.


Defining Menus

• Simple Menu Items:

A simple kind of menu key binding.

• Extended Menu Items:

More complex menu item definitions.

• Menu Separators:

Drawing a horizontal line through a menu.

• Alias Menu Items:

Using command aliases in menu items.


Major and Minor Modes

• Hooks:

How to use hooks; how to write code that provides hooks.

• Major Modes:

Defining major modes.

• Minor Modes:

Defining minor modes.

• Mode Line Format:

Customizing the text that appears in the mode line.

• Imenu:

Providing a menu of definitions made in a buffer.

• Font Lock Mode:

How modes can highlight text according to syntax.

• Auto-Indentation:

How to teach Emacs to indent for a major mode.

• Desktop Save Mode:

How modes can have buffer state saved between Emacs sessions.


Hooks

• Running Hooks:

How to run a hook.

• Setting Hooks:

How to put functions on a hook, or remove them.


Major Modes

• Major Mode Conventions:

Coding conventions for keymaps, etc.

• Auto Major Mode:

How Emacs chooses the major mode automatically.

• Mode Help:

Finding out how to use a mode.

• Derived Modes:

Defining a new major mode based on another major mode.

• Basic Major Modes:

Modes that other modes are often derived from.

• Mode Hooks:

Hooks run at the end of major mode functions.

• Tabulated List Mode:

Parent mode for buffers containing tabulated data.

• Generic Modes:

Defining a simple major mode that supports comment syntax and Font Lock mode.

• Example Major Modes:

Text mode and Lisp modes.


Minor Modes

• Minor Mode Conventions:

Tips for writing a minor mode.

• Keymaps and Minor Modes:

How a minor mode can have its own keymap.

• Defining Minor Modes:

A convenient facility for defining minor modes.


Mode Line Format

• Mode Line Basics:

Basic ideas of mode line control.

• Mode Line Data:

The data structure that controls the mode line.

• Mode Line Top:

The top level variable, mode-line-format.

• Mode Line Variables:

Variables used in that data structure.

• %-Constructs:

Putting information into a mode line.

• Properties in Mode:

Using text properties in the mode line.

• Header Lines:

Like a mode line, but at the top.

• Emulating Mode Line:

Formatting text as the mode line would.


Font Lock Mode

• Font Lock Basics:

Overview of customizing Font Lock.

• Search-based Fontification:

Fontification based on regexps.

• Customizing Keywords:

Customizing search-based fontification.

• Other Font Lock Variables:

Additional customization facilities.

• Levels of Font Lock:

Each mode can define alternative levels so that the user can select more or less.

• Precalculated Fontification:

How Lisp programs that produce the buffer contents can also specify how to fontify it.

• Faces for Font Lock:

Special faces specifically for Font Lock.

• Syntactic Font Lock:

Fontification based on syntax tables.

• Multiline Font Lock:

How to coerce Font Lock into properly highlighting multiline constructs.


Multiline Font Lock Constructs

• Font Lock Multiline:

Marking multiline chunks with a text property.

• Region to Refontify:

Controlling which region gets refontified after a buffer change.


Automatic Indentation of code

• SMIE:

A simple minded indentation engine.


Simple Minded Indentation Engine

• SMIE setup:

SMIE setup and features.

• Operator Precedence Grammars:

A very simple parsing technique.

• SMIE Grammar:

Defining the grammar of a language.

• SMIE Lexer:

Defining tokens.

• SMIE Tricks:

Working around the parser’s limitations.

• SMIE Indentation:

Specifying indentation rules.

• SMIE Indentation Helpers:

Helper functions for indentation rules.

• SMIE Indentation Example:

Sample indentation rules.

• SMIE Customization:

Customizing indentation.


Documentation

• Documentation Basics:

Where doc strings are defined and stored.

• Accessing Documentation:

How Lisp programs can access doc strings.

• Keys in Documentation:

Substituting current key bindings.

• Text Quoting Style:

Quotation marks in doc strings and messages.

• Describing Characters:

Making printable descriptions of non-printing characters and key sequences.

• Help Functions:

Subroutines used by Emacs help facilities.


Files

• Visiting Files:

Reading files into Emacs buffers for editing.

• Saving Buffers:

Writing changed buffers back into files.

• Reading from Files:

Reading files into buffers without visiting.

• Writing to Files:

Writing new files from parts of buffers.

• File Locks:

Locking and unlocking files, to prevent simultaneous editing by two people.

• Information about Files:

Testing existence, accessibility, size of files.

• Changing Files:

Renaming files, changing permissions, etc.

• File Names:

Decomposing and expanding file names.

• Contents of Directories:

Getting a list of the files in a directory.

• Create/Delete Dirs:

Creating and Deleting Directories.

• Magic File Names:

Special handling for certain file names.

• Format Conversion:

Conversion to and from various file formats.


Visiting Files

• Visiting Functions:

The usual interface functions for visiting.

• Subroutines of Visiting:

Lower-level subroutines that they use.


Information about Files

• Testing Accessibility:

Is a given file readable? Writable?

• Kinds of Files:

Is it a directory? A symbolic link?

• Truenames:

Eliminating symbolic links from a file name.

• File Attributes:

File sizes, modification times, etc.

• Extended Attributes:

Extended file attributes for access control.

• Locating Files:

How to find a file in standard places.


File Names

• File Name Components:

The directory part of a file name, and the rest.

• Relative File Names:

Some file names are relative to a current directory.

• Directory Names:

A directory’s name as a directory is different from its name as a file.

• File Name Expansion:

Converting relative file names to absolute ones.

• Unique File Names:

Generating names for temporary files.

• File Name Completion:

Finding the completions for a given file name.

• Standard File Names:

If your package uses a fixed file name, how to handle various operating systems simply.


File Format Conversion

• Format Conversion Overview:

insert-file-contents and write-region.

• Format Conversion Round-Trip:

Using format-alist.

• Format Conversion Piecemeal:

Specifying non-paired conversion.


Backups and Auto-Saving

• Backup Files:

How backup files are made; how their names are chosen.

• Auto-Saving:

How auto-save files are made; how their names are chosen.

• Reverting:

revert-buffer, and how to customize what it does.


Backup Files

• Making Backups:

How Emacs makes backup files, and when.

• Rename or Copy:

Two alternatives: renaming the old file or copying it.

• Numbered Backups:

Keeping multiple backups for each source file.

• Backup Names:

How backup file names are computed; customization.


Buffers

• Buffer Basics:

What is a buffer?

• Current Buffer:

Designating a buffer as current so that primitives will access its contents.

• Buffer Names:

Accessing and changing buffer names.

• Buffer File Name:

The buffer file name indicates which file is visited.

• Buffer Modification:

A buffer is modified if it needs to be saved.

• Modification Time:

Determining whether the visited file was changed behind Emacs’s back.

• Read Only Buffers:

Modifying text is not allowed in a read-only buffer.

• Buffer List:

How to look at all the existing buffers.

• Creating Buffers:

Functions that create buffers.

• Killing Buffers:

Buffers exist until explicitly killed.

• Indirect Buffers:

An indirect buffer shares text with some other buffer.

• Swapping Text:

Swapping text between two buffers.

• Buffer Gap:

The gap in the buffer.


Windows

• Basic Windows:

Basic information on using windows.

• Windows and Frames:

Relating windows to the frame they appear on.

• Window Sizes:

Accessing a window’s size.

• Resizing Windows:

Changing the sizes of windows.

• Preserving Window Sizes:

Preserving the size of windows.

• Splitting Windows:

Splitting one window into two windows.

• Deleting Windows:

Deleting a window gives its space to other windows.

• Recombining Windows:

Preserving the frame layout when splitting and deleting windows.

• Selecting Windows:

The selected window is the one that you edit in.

• Cyclic Window Ordering:

Moving around the existing windows.

• Buffers and Windows:

Each window displays the contents of a buffer.

• Switching Buffers:

Higher-level functions for switching to a buffer.

• Displaying Buffers:

Displaying a buffer in a suitable window.

• Window History:

Each window remembers the buffers displayed in it.

• Dedicated Windows:

How to avoid displaying another buffer in a specific window.

• Quitting Windows:

How to restore the state prior to displaying a buffer.

• Side Windows:

Special windows on a frame’s sides.

• Atomic Windows:

Preserving parts of the window layout.

• Window Point:

Each window has its own location of point.

• Window Start and End:

Buffer positions indicating which text is on-screen in a window.

• Textual Scrolling:

Moving text up and down through the window.

• Vertical Scrolling:

Moving the contents up and down on the window.

• Horizontal Scrolling:

Moving the contents sideways on the window.

• Coordinates and Windows:

Converting coordinates to windows.

• Mouse Window Auto-selection:

Automatically selecting windows with the mouse.

• Window Configurations:

Saving and restoring the state of the screen.

• Window Parameters:

Associating additional information with windows.

• Window Hooks:

Hooks for scrolling, window size changes, redisplay going past a certain point, or window configuration changes.


Displaying Buffers

• Choosing Window:

How to choose a window for displaying a buffer.

• Buffer Display Action Functions:

Support functions for buffer display.

• Buffer Display Action Alists:

Alists for fine-tuning buffer display action functions.

• Choosing Window Options:

Extra options affecting how buffers are displayed.

• Precedence of Action Functions:

A tutorial explaining the precedence of buffer display action functions.

• The Zen of Buffer Display:

How to avoid that buffers get lost in between windows.


Side Windows

• Displaying Buffers in Side Windows:

An action function for displaying buffers in side windows.

• Side Window Options and Functions:

Further tuning of side windows.

• Frame Layouts with Side Windows:

Setting up frame layouts with side windows.


Frames

• Creating Frames:

Creating additional frames.

• Multiple Terminals:

Displaying on several different devices.

• Frame Geometry:

Geometric properties of frames.

• Frame Parameters:

Controlling frame size, position, font, etc.

• Terminal Parameters:

Parameters common for all frames on terminal.

• Frame Titles:

Automatic updating of frame titles.

• Deleting Frames:

Frames last until explicitly deleted.

• Finding All Frames:

How to examine all existing frames.

• Minibuffers and Frames:

How a frame finds the minibuffer to use.

• Input Focus:

Specifying the selected frame.

• Visibility of Frames:

Frames may be visible or invisible, or icons.

• Raising and Lowering:

Raising, Lowering and Restacking Frames.

• Frame Configurations:

Saving the state of all frames.

• Child Frames:

Making a frame the child of another.

• Mouse Tracking:

Getting events that say when the mouse moves.

• Mouse Position:

Asking where the mouse is, or moving it.

• Pop-Up Menus:

Displaying a menu for the user to select from.

• Dialog Boxes:

Displaying a box to ask yes or no.

• Pointer Shape:

Specifying the shape of the mouse pointer.

• Window System Selections:

Transferring text to and from other X clients.

• Drag and Drop:

Internals of Drag-and-Drop implementation.

• Color Names:

Getting the definitions of color names.

• Text Terminal Colors:

Defining colors for text terminals.

• Resources:

Getting resource values from the server.

• Display Feature Testing:

Determining the features of a terminal.


Frame Geometry

• Frame Layout:

Basic layout of frames.

• Frame Font:

The default font of a frame and how to set it.

• Frame Position:

The position of a frame on its display.

• Frame Size:

Specifying and retrieving a frame’s size.

• Implied Frame Resizing:

Implied resizing of frames and how to prevent it.


Frame Parameters

• Parameter Access:

How to change a frame’s parameters.

• Initial Parameters:

Specifying frame parameters when you make a frame.

• Window Frame Parameters:

List of frame parameters for window systems.

• Geometry:

Parsing geometry specifications.


Window Frame Parameters

• Basic Parameters:

Parameters that are fundamental.

• Position Parameters:

The position of the frame on the screen.

• Size Parameters:

Frame’s size.

• Layout Parameters:

Size of parts of the frame, and enabling or disabling some parts.

• Buffer Parameters:

Which buffers have been or should be shown.

• Frame Interaction Parameters:

Parameters for interacting with other frames.

• Mouse Dragging Parameters:

Parameters for resizing and moving frames with the mouse.

• Management Parameters:

Communicating with the window manager.

• Cursor Parameters:

Controlling the cursor appearance.

• Font and Color Parameters:

Fonts and colors for the frame text.


Positions

• Point:

The special position where editing takes place.

• Motion:

Changing point.

• Excursions:

Temporary motion and buffer changes.

• Narrowing:

Restricting editing to a portion of the buffer.


Motion

• Character Motion:

Moving in terms of characters.

• Word Motion:

Moving in terms of words.

• Buffer End Motion:

Moving to the beginning or end of the buffer.

• Text Lines:

Moving in terms of lines of text.

• Screen Lines:

Moving in terms of lines as displayed.

• List Motion:

Moving by parsing lists and sexps.

• Skipping Characters:

Skipping characters belonging to a certain set.


Markers

• Overview of Markers:

The components of a marker, and how it relocates.

• Predicates on Markers:

Testing whether an object is a marker.

• Creating Markers:

Making empty markers or markers at certain places.

• Information from Markers:

Finding the marker’s buffer or character position.

• Marker Insertion Types:

Two ways a marker can relocate when you insert where it points.

• Moving Markers:

Moving the marker to a new buffer or position.

• The Mark:

How the mark is implemented with a marker.

• The Region:

How to access the region.


Text

• Near Point:

Examining text in the vicinity of point.

• Buffer Contents:

Examining text in a general fashion.

• Comparing Text:

Comparing substrings of buffers.

• Insertion:

Adding new text to a buffer.

• Commands for Insertion:

User-level commands to insert text.

• Deletion:

Removing text from a buffer.

• User-Level Deletion:

User-level commands to delete text.

• The Kill Ring:

Where removed text sometimes is saved for later use.

• Undo:

Undoing changes to the text of a buffer.

• Maintaining Undo:

How to enable and disable undo information. How to control how much information is kept.

• Filling:

Functions for explicit filling.

• Margins:

How to specify margins for filling commands.

• Adaptive Fill:

Adaptive Fill mode chooses a fill prefix from context.

• Auto Filling:

How auto-fill mode is implemented to break lines.

• Sorting:

Functions for sorting parts of the buffer.

• Columns:

Computing horizontal positions, and using them.

• Indentation:

Functions to insert or adjust indentation.

• Case Changes:

Case conversion of parts of the buffer.

• Text Properties:

Assigning Lisp property lists to text characters.

• Substitution:

Replacing a given character wherever it appears.

• Registers:

How registers are implemented. Accessing the text or position stored in a register.

• Transposition:

Swapping two portions of a buffer.

• Decompression:

Dealing with compressed data.

• Base 64:

Conversion to or from base 64 encoding.

• Checksum/Hash:

Computing cryptographic hashes.

• GnuTLS Cryptography:

Cryptographic algorithms imported from GnuTLS.

• Parsing HTML/XML:

Parsing HTML and XML.

• Atomic Changes:

Installing several buffer changes atomically.

• Change Hooks:

Supplying functions to be run when text is changed.


The Kill Ring

• Kill Ring Concepts:

What text looks like in the kill ring.

• Kill Functions:

Functions that kill text.

• Yanking:

How yanking is done.

• Yank Commands:

Commands that access the kill ring.

• Low-Level Kill Ring:

Functions and variables for kill ring access.

• Internals of Kill Ring:

Variables that hold kill ring data.


Indentation

• Primitive Indent:

Functions used to count and insert indentation.

• Mode-Specific Indent:

Customize indentation for different modes.

• Region Indent:

Indent all the lines in a region.

• Relative Indent:

Indent the current line based on previous lines.

• Indent Tabs:

Adjustable, typewriter-like tab stops.

• Motion by Indent:

Move to first non-blank character.


Text Properties

• Examining Properties:

Looking at the properties of one character.

• Changing Properties:

Setting the properties of a range of text.

• Property Search:

Searching for where a property changes value.

• Special Properties:

Particular properties with special meanings.

• Format Properties:

Properties for representing formatting of text.

• Sticky Properties:

How inserted text gets properties from neighboring text.

• Lazy Properties:

Computing text properties in a lazy fashion only when text is examined.

• Clickable Text:

Using text properties to make regions of text do something when you click on them.

• Fields:

The field property defines fields within the buffer.

• Not Intervals:

Why text properties do not use Lisp-visible text intervals.


Parsing HTML and XML

• Document Object Model:

Access, manipulate and search the DOM.


Non-ASCII Characters

• Text Representations:

How Emacs represents text.

• Disabling Multibyte:

Controlling whether to use multibyte characters.

• Converting Representations:

Converting unibyte to multibyte and vice versa.

• Selecting a Representation:

Treating a byte sequence as unibyte or multi.

• Character Codes:

How unibyte and multibyte relate to codes of individual characters.

• Character Properties:

Character attributes that define their behavior and handling.

• Character Sets:

The space of possible character codes is divided into various character sets.

• Scanning Charsets:

Which character sets are used in a buffer?

• Translation of Characters:

Translation tables are used for conversion.

• Coding Systems:

Coding systems are conversions for saving files.

• Input Methods:

Input methods allow users to enter various non-ASCII characters without special keyboards.

• Locales:

Interacting with the POSIX locale.


Coding Systems

• Coding System Basics:

Basic concepts.

• Encoding and I/O:

How file I/O functions handle coding systems.

• Lisp and Coding Systems:

Functions to operate on coding system names.

• User-Chosen Coding Systems:

Asking the user to choose a coding system.

• Default Coding Systems:

Controlling the default choices.

• Specifying Coding Systems:

Requesting a particular coding system for a single file operation.

• Explicit Encoding:

Encoding or decoding text without doing I/O.

• Terminal I/O Encoding:

Use of encoding for terminal I/O.


Searching and Matching

• String Search:

Search for an exact match.

• Searching and Case:

Case-independent or case-significant searching.

• Regular Expressions:

Describing classes of strings.

• Regexp Search:

Searching for a match for a regexp.

• POSIX Regexps:

Searching POSIX-style for the longest match.

• Match Data:

Finding out which part of the text matched, after a string or regexp search.

• Search and Replace:

Commands that loop, searching and replacing.

• Standard Regexps:

Useful regexps for finding sentences, pages,...


Regular Expressions

• Syntax of Regexps:

Rules for writing regular expressions.

• Regexp Example:

Illustrates regular expression syntax.

• Rx Notation:

An alternative, structured regexp notation.

• Regexp Functions:

Functions for operating on regular expressions.


Syntax of Regular Expressions

• Regexp Special:

Special characters in regular expressions.

• Char Classes:

Character classes used in regular expressions.

• Regexp Backslash:

Backslash-sequences in regular expressions.


The Match Data

• Replacing Match:

Replacing a substring that was matched.

• Simple Match Data:

Accessing single items of match data, such as where a particular subexpression started.

• Entire Match Data:

Accessing the entire match data at once, as a list.

• Saving Match Data:

Saving and restoring the match data.


Syntax Tables

• Syntax Basics:

Basic concepts of syntax tables.

• Syntax Descriptors:

How characters are classified.

• Syntax Table Functions:

How to create, examine and alter syntax tables.

• Syntax Properties:

Overriding syntax with text properties.

• Motion and Syntax:

Moving over characters with certain syntaxes.

• Parsing Expressions:

Parsing balanced expressions using the syntax table.

• Syntax Table Internals:

How syntax table information is stored.

• Categories:

Another way of classifying character syntax.


Syntax Descriptors

• Syntax Class Table:

Table of syntax classes.

• Syntax Flags:

Additional flags each character can have.


Parsing Expressions

• Motion via Parsing:

Motion functions that work by parsing.

• Position Parse:

Determining the syntactic state of a position.

• Parser State:

How Emacs represents a syntactic state.

• Low-Level Parsing:

Parsing across a specified region.

• Control Parsing:

Parameters that affect parsing.


Abbrevs and Abbrev Expansion

• Abbrev Tables:

Creating and working with abbrev tables.

• Defining Abbrevs:

Specifying abbreviations and their expansions.

• Abbrev Files:

Saving abbrevs in files.

• Abbrev Expansion:

Controlling expansion; expansion subroutines.

• Standard Abbrev Tables:

Abbrev tables used by various major modes.

• Abbrev Properties:

How to read and set abbrev properties. Which properties have which effect.

• Abbrev Table Properties:

How to read and set abbrev table properties. Which properties have which effect.


Threads

• Basic Thread Functions:

Basic thread functions.

• Mutexes:

Mutexes allow exclusive access to data.

• Condition Variables:

Inter-thread events.

• The Thread List:

Show the active threads.


Processes

• Subprocess Creation:

Functions that start subprocesses.

• Shell Arguments:

Quoting an argument to pass it to a shell.

• Synchronous Processes:

Details of using synchronous subprocesses.

• Asynchronous Processes:

Starting up an asynchronous subprocess.

• Deleting Processes:

Eliminating an asynchronous subprocess.

• Process Information:

Accessing run-status and other attributes.

• Input to Processes:

Sending input to an asynchronous subprocess.

• Signals to Processes:

Stopping, continuing or interrupting an asynchronous subprocess.

• Output from Processes:

Collecting output from an asynchronous subprocess.

• Sentinels:

Sentinels run when process run-status changes.

• Query Before Exit:

Whether to query if exiting will kill a process.

• System Processes:

Accessing other processes running on your system.

• Transaction Queues:

Transaction-based communication with subprocesses.

• Network:

Opening network connections.

• Network Servers:

Network servers let Emacs accept net connections.

• Datagrams:

UDP network connections.

• Low-Level Network:

Lower-level but more general function to create connections and servers.

• Misc Network:

Additional relevant functions for net connections.

• Serial Ports:

Communicating with serial ports.

• Byte Packing:

Using bindat to pack and unpack binary data.


Receiving Output from Processes

• Process Buffers:

By default, output is put in a buffer.

• Filter Functions:

Filter functions accept output from the process.

• Decoding Output:

Filters can get unibyte or multibyte strings.

• Accepting Output:

How to wait until process output arrives.


Low-Level Network Access

• Network Processes:

Using make-network-process.

• Network Options:

Further control over network connections.

• Network Feature Testing:

Determining which network features work on the machine you are using.


Packing and Unpacking Byte Arrays

• Bindat Spec:

Describing data layout.

• Bindat Functions:

Doing the unpacking and packing.


Emacs Display

• Refresh Screen:

Clearing the screen and redrawing everything on it.

• Forcing Redisplay:

Forcing redisplay.

• Truncation:

Folding or wrapping long text lines.

• The Echo Area:

Displaying messages at the bottom of the screen.

• Warnings:

Displaying warning messages for the user.

• Invisible Text:

Hiding part of the buffer text.

• Selective Display:

Hiding part of the buffer text (the old way).

• Temporary Displays:

Displays that go away automatically.

• Overlays:

Use overlays to highlight parts of the buffer.

• Size of Displayed Text:

How large displayed text is.

• Line Height:

Controlling the height of lines.

• Faces:

A face defines a graphics style for text characters: font, colors, etc.

• Fringes:

Controlling window fringes.

• Scroll Bars:

Controlling scroll bars.

• Window Dividers:

Separating windows visually.

• Display Property:

Enabling special display features.

• Images:

Displaying images in Emacs buffers.

• Buttons:

Adding clickable buttons to Emacs buffers.

• Abstract Display:

Emacs’s Widget for Object Collections.

• Blinking:

How Emacs shows the matching open parenthesis.

• Character Display:

How Emacs displays individual characters.

• Beeping:

Audible signal to the user.

• Window Systems:

Which window system is being used.

• Tooltips:

Tooltip display in Emacs.

• Bidirectional Display:

Display of bidirectional scripts, such as Arabic and Farsi.


The Echo Area

• Displaying Messages:

Explicitly displaying text in the echo area.

• Progress:

Informing user about progress of a long operation.

• Logging Messages:

Echo area messages are logged for the user.

• Echo Area Customization:

Controlling the echo area.


Reporting Warnings

• Warning Basics:

Warnings concepts and functions to report them.

• Warning Variables:

Variables programs bind to customize their warnings.

• Warning Options:

Variables users set to control display of warnings.

• Delayed Warnings:

Deferring a warning until the end of a command.


Overlays

• Managing Overlays:

Creating and moving overlays.

• Overlay Properties:

How to read and set properties. What properties do to the screen display.

• Finding Overlays:

Searching for overlays.


Faces

• Face Attributes:

What is in a face?

• Defining Faces:

How to define a face.

• Attribute Functions:

Functions to examine and set face attributes.

• Displaying Faces:

How Emacs combines the faces specified for a character.

• Face Remapping:

Remapping faces to alternative definitions.

• Face Functions:

How to define and examine faces.

• Auto Faces:

Hook for automatic face assignment.

• Basic Faces:

Faces that are defined by default.

• Font Selection:

Finding the best available font for a face.

• Font Lookup:

Looking up the names of available fonts and information about them.

• Fontsets:

A fontset is a collection of fonts that handle a range of character sets.

• Low-Level Font:

Lisp representation for character display fonts.


Fringes

• Fringe Size/Pos:

Specifying where to put the window fringes.

• Fringe Indicators:

Displaying indicator icons in the window fringes.

• Fringe Cursors:

Displaying cursors in the right fringe.

• Fringe Bitmaps:

Specifying bitmaps for fringe indicators.

• Customizing Bitmaps:

Specifying your own bitmaps to use in the fringes.

• Overlay Arrow:

Display of an arrow to indicate position.


The display Property

• Replacing Specs:

Display specs that replace the text.

• Specified Space:

Displaying one space with a specified width.

• Pixel Specification:

Specifying space width or height in pixels.

• Other Display Specs:

Displaying an image; adjusting the height, spacing, and other properties of text.

• Display Margins:

Displaying text or images to the side of the main text.


Images

• Image Formats:

Supported image formats.

• Image Descriptors:

How to specify an image for use in :display.

• XBM Images:

Special features for XBM format.

• XPM Images:

Special features for XPM format.

• ImageMagick Images:

Special features available through ImageMagick.

• Other Image Types:

Various other formats are supported.

• Defining Images:

Convenient ways to define an image for later use.

• Showing Images:

Convenient ways to display an image once it is defined.

• Multi-Frame Images:

Some images contain more than one frame.

• Image Cache:

Internal mechanisms of image display.


Buttons

• Button Properties:

Button properties with special meanings.

• Button Types:

Defining common properties for classes of buttons.

• Making Buttons:

Adding buttons to Emacs buffers.

• Manipulating Buttons:

Getting and setting properties of buttons.

• Button Buffer Commands:

Buffer-wide commands and bindings for buttons.


Abstract Display

• Abstract Display Functions:

Functions in the Ewoc package.

• Abstract Display Example:

Example of using Ewoc.


Character Display

• Usual Display:

The usual conventions for displaying characters.

• Display Tables:

What a display table consists of.

• Active Display Table:

How Emacs selects a display table to use.

• Glyphs:

How to define a glyph, and what glyphs mean.

• Glyphless Chars:

How glyphless characters are drawn.


Operating System Interface

• Starting Up:

Customizing Emacs startup processing.

• Getting Out:

How exiting works (permanent or temporary).

• System Environment:

Distinguish the name and kind of system.

• User Identification:

Finding the name and user id of the user.

• Time of Day:

Getting the current time.

• Time Conversion:

Converting among timestamp forms.

• Time Parsing:

Converting timestamps to text and vice versa.

• Processor Run Time:

Getting the run time used by Emacs.

• Time Calculations:

Adding, subtracting, comparing times, etc.

• Timers:

Setting a timer to call a function at a certain time.

• Idle Timers:

Setting a timer to call a function when Emacs has been idle for a certain length of time.

• Terminal Input:

Accessing and recording terminal input.

• Terminal Output:

Controlling and recording terminal output.

• Sound Output:

Playing sounds on the computer’s speaker.

• X11 Keysyms:

Operating on key symbols for X Windows.

• Batch Mode:

Running Emacs without terminal interaction.

• Session Management:

Saving and restoring state with X Session Management.

• Desktop Notifications:

Desktop notifications.

• File Notifications:

File notifications.

• Dynamic Libraries:

On-demand loading of support libraries.

• Security Considerations:

Running Emacs in an unfriendly environment.


Starting Up Emacs

• Startup Summary:

Sequence of actions Emacs performs at startup.

• Init File:

Details on reading the init file.

• Terminal-Specific:

How the terminal-specific Lisp file is read.

• Command-Line Arguments:

How command-line arguments are processed, and how you can customize them.


Getting Out of Emacs

• Killing Emacs:

Exiting Emacs irreversibly.

• Suspending Emacs:

Exiting Emacs reversibly.


Terminal Input

• Input Modes:

Options for how input is processed.

• Recording Input:

Saving histories of recent or all input events.


Preparing Lisp code for distribution

• Packaging Basics:

The basic concepts of Emacs Lisp packages.

• Simple Packages:

How to package a single .el file.

• Multi-file Packages:

How to package multiple files.

• Package Archives:

Maintaining package archives.


Tips and Conventions

• Coding Conventions:

Conventions for clean and robust programs.

• Key Binding Conventions:

Which keys should be bound by which programs.

• Programming Tips:

Making Emacs code fit smoothly in Emacs.

• Compilation Tips:

Making compiled code run fast.

• Warning Tips:

Turning off compiler warnings.

• Documentation Tips:

Writing readable documentation strings.

• Comment Tips:

Conventions for writing comments.

• Library Headers:

Standard headers for library packages.


GNU Emacs Internals

• Building Emacs:

How the dumped Emacs is made.

• Pure Storage:

Kludge to make preloaded Lisp functions shareable.

• Garbage Collection:

Reclaiming space for Lisp objects no longer used.

• Stack-allocated Objects:

Temporary conses and strings on C stack.

• Memory Usage:

Info about total size of Lisp objects made so far.

• C Dialect:

What C variant Emacs is written in.

• Writing Emacs Primitives:

Writing C code for Emacs.

• Writing Dynamic Modules:

Writing loadable modules for Emacs.

• Object Internals:

Data formats of buffers, windows, processes.

• C Integer Types:

How C integer types are used inside Emacs.


Writing Dynamic Modules

• Module Initialization:

• Module Functions:

• Module Values:

• Module Misc:

• Module Nonlocal:


Object Internals

• Buffer Internals:

Components of a buffer structure.

• Window Internals:

Components of a window structure.

• Process Internals:

Components of a process structure.

GNU Emacs Lisp Reference Manual

Short Table of Contents

Table of Contents

Emacs Lisp