Top (GNU Emacs Lisp Reference Manual)

Emacs Lisp

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

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 25.
• 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.
• 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.
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`.
• Iteration		`while` loops.
• Generators		Generic sequences and coroutines.
• Nonlocal Exits		Jumping out of a sequence.
Conditionals
• Pattern matching case statement		How to use `pcase`.
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; what you see while in it.
• 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.

• 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 25.

• 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.

• 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.


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.

• Iteration

while loops.

• Generators

Generic sequences and coroutines.

• Nonlocal Exits

Jumping out of a sequence.


Conditionals

• Pattern matching case statement

How to use pcase.


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; what you see while in it.

• 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.

• Choosing Window

How to choose a window for displaying a buffer.

• Display Action Functions

Subroutines for display-buffer.

• Choosing Window Options

Extra options affecting how buffers are displayed.

• 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.


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.

• 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.


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.

• Bindat Examples

Samples of what bindat.el can do for you!


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 a time from numeric form to calendrical data and vice versa.

• Time Parsing

Converting a time from numeric form 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.

• Object Internals

Data formats of buffers, windows, processes.

• C Integer Types

How C integer types are used inside Emacs.


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