An Introduction to Programming in Emacs Lisp

The homepage for GNU Emacs is at
To view this manual in other formats, click here.

This is an Introduction to Programming in Emacs Lisp, for people who are not programmers.

Distributed with Emacs version 25.2.

Copyright © 1990–1995, 1997, 2001–2017 Free Software Foundation, Inc.

Printed copies available from Published by:

     GNU Press,              
     a division of the                 email:
     Free Software Foundation, Inc.    Tel: +1 (617) 542-5942
     51 Franklin Street, Fifth Floor   Fax: +1 (617) 542-2652
     Boston, MA 02110-1301 USA

ISBN 1-882114-43-4
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; there being no Invariant Section, 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.”

This master menu first lists each chapter and index; then it lists every node in every chapter.

Preface What to look for.
List Processing What is Lisp?
Practicing Evaluation Running several programs.
Writing Defuns How to write function definitions.
Buffer Walk Through Exploring a few buffer-related functions.
More Complex A few, even more complex functions.
Narrowing & Widening Restricting your and Emacs attention to a region.
car cdr & cons Fundamental functions in Lisp.
Cutting & Storing Text Removing text and saving it.
List Implementation How lists are implemented in the computer.
Yanking Pasting stored text.
Loops & Recursion How to repeat a process.
Regexp Search Regular expression searches.
Counting Words A review of repetition and regexps.
Words in a defun Counting words in a defun.
Readying a Graph A prototype graph printing function.
Emacs Initialization How to write a .emacs file.
Debugging How to run the Emacs Lisp debuggers.
Conclusion Now you have the basics.
the-the An appendix: how to find reduplicated words.
Kill Ring An appendix: how the kill ring works.
Full Graph How to create a graph with labeled axes.
Free Software and Free Manuals
GNU Free Documentation License
About the Author

Detailed Node Listing

Why Why learn Emacs Lisp?
On Reading this Text Read, gain familiarity, pick up habits....
Who You Are For whom this is written.
Lisp History
Note for Novices You can read this as a novice.
Thank You
List Processing
Lisp Lists What are lists?
Run a Program Any list in Lisp is a program ready to run.
Making Errors Generating an error message.
Names & Definitions Names of symbols and function definitions.
Lisp Interpreter What the Lisp interpreter does.
Evaluation Running a program.
Variables Returning a value from a variable.
Arguments Passing information to a function.
set & setq Setting the value of a variable.
Summary The major points.
Error Message Exercises
Lisp Lists
Numbers Lists List have numbers, other lists, in them.
Lisp Atoms Elemental entities.
Whitespace in Lists Formatting lists to be readable.
Typing Lists How GNU Emacs helps you type lists.
The Lisp Interpreter
Complications Variables, Special forms, Lists within.
Byte Compiling Specially processing code for speed.
How the Interpreter Acts Returns and Side Effects...
Evaluating Inner Lists Lists within lists...
fill-column Example
Void Function The error message for a symbol without a function.
Void Variable The error message for a symbol without a value.
Data types Types of data passed to a function.
Args as Variable or List An argument can be the value of a variable or list.
Variable Number of Arguments Some functions may take a variable number of arguments.
Wrong Type of Argument Passing an argument of the wrong type to a function.
message A useful function for sending messages.
Setting the Value of a Variable
Using set Setting values.
Using setq Setting a quoted value.
Counting Using setq to count.
Practicing Evaluation
How to Evaluate Typing editing commands or C-x C-e causes evaluation.
Buffer Names Buffers and files are different.
Getting Buffers Getting a buffer itself, not merely its name.
Switching Buffers How to change to another buffer.
Buffer Size & Locations Where point is located and the size of the buffer.
Evaluation Exercise
How To Write Function Definitions
Primitive Functions
defun The defun macro.
Install Install a function definition.
Interactive Making a function interactive.
Interactive Options Different options for interactive.
Permanent Installation Installing code permanently.
let Creating and initializing local variables.
if What if?
else If--then--else expressions.
Truth & Falsehood What Lisp considers false and true.
save-excursion Keeping track of point and buffer.
defun Exercises
Install a Function Definition
Effect of installation
Change a defun How to change a function definition.
Make a Function Interactive
Interactive multiply-by-seven An overview.
multiply-by-seven in detail The interactive version.
Prevent confusion
Parts of let Expression
Sample let Expression
Uninitialized let Variables
The if Special Form
if in more detail
type-of-animal in detail An example of an if expression.
Truth and Falsehood in Emacs Lisp
nil explained nil has two meanings.
Point and mark A review of various locations.
Template for save-excursion
A Few Buffer-Related Functions
Finding More How to find more information.
simplified-beginning-of-buffer Shows goto-char, point-min, and push-mark.
mark-whole-buffer Almost the same as beginning-of-buffer.
append-to-buffer Uses save-excursion and insert-buffer-substring.
Buffer Related Review Review.
Buffer Exercises
The Definition of mark-whole-buffer
mark-whole-buffer overview
Body of mark-whole-buffer Only three lines of code.
The Definition of append-to-buffer
append-to-buffer overview
append interactive A two part interactive expression.
append-to-buffer body Incorporates a let expression.
append save-excursion How the save-excursion works.
A Few More Complex Functions
copy-to-buffer With set-buffer, get-buffer-create.
insert-buffer Read-only, and with or.
beginning-of-buffer Shows goto-char, point-min, and push-mark.
Second Buffer Related Review
optional Exercise
The Definition of insert-buffer
insert-buffer code
insert-buffer interactive When you can read, but not write.
insert-buffer body The body has an or and a let.
if & or Using an if instead of an or.
Insert or How the or expression works.
Insert let Two save-excursion expressions.
New insert-buffer
The Interactive Expression in insert-buffer
Read-only buffer When a buffer cannot be modified.
b for interactive An existing buffer or else its name.
Complete Definition of beginning-of-buffer
Optional Arguments
beginning-of-buffer opt arg Example with optional argument.
beginning-of-buffer complete
beginning-of-buffer with an Argument
Disentangle beginning-of-buffer
Large buffer case
Small buffer case
Narrowing and Widening
Narrowing advantages The advantages of narrowing
save-restriction The save-restriction special form.
what-line The number of the line that point is on.
narrow Exercise
car, cdr, cons: Fundamental Functions
Strange Names An historical aside: why the strange names?
car & cdr Functions for extracting part of a list.
cons Constructing a list.
nthcdr Calling cdr repeatedly.
setcar Changing the first element of a list.
setcdr Changing the rest of a list.
cons Exercise
Build a list
length How to find the length of a list.
Cutting and Storing Text
Storing Text Text is stored in a list.
zap-to-char Cutting out text up to a character.
kill-region Cutting text out of a region.
copy-region-as-kill A definition for copying text.
Digression into C Minor note on C programming language macros.
defvar How to give a variable an initial value.
cons & search-fwd Review
search Exercises
Complete zap-to-char The complete implementation.
zap-to-char interactive A three part interactive expression.
zap-to-char body A short overview.
search-forward How to search for a string.
progn The progn special form.
Summing up zap-to-char Using point and search-forward.
Complete kill-region The function definition.
condition-case Dealing with a problem.
Lisp macro
Complete copy-region-as-kill The complete function definition.
copy-region-as-kill body The body of copy-region-as-kill.
The Body of copy-region-as-kill
last-command & this-command
kill-append function
kill-new function
Initializing a Variable with defvar
See variable current value
defvar and asterisk
How Lists are Implemented
Lists diagrammed
Symbols as Chest Exploring a powerful metaphor.
List Exercise
Yanking Text Back
Kill Ring Overview
kill-ring-yank-pointer The kill ring is a list.
yank nthcdr Exercises The kill-ring-yank-pointer variable.
Loops and Recursion
while Causing a stretch of code to repeat.
dolist dotimes
Recursion Causing a function to call itself.
Looping exercise
Looping with while Repeat so long as test returns true.
Loop Example A while loop that uses a list.
print-elements-of-list Uses while, car, cdr.
Incrementing Loop A loop with an incrementing counter.
Incrementing Loop Details
Decrementing Loop A loop with a decrementing counter.
Details of an Incrementing Loop
Incrementing Example Counting pebbles in a triangle.
Inc Example parts The parts of the function definition.
Inc Example altogether Putting the function definition together.
Loop with a Decrementing Counter
Decrementing Example More pebbles on the beach.
Dec Example parts The parts of the function definition.
Dec Example altogether Putting the function definition together.
Save your time: dolist and dotimes
Building Robots Same model, different serial number ...
Recursive Definition Parts Walk until you stop ...
Recursion with list Using a list as the test whether to recurse.
Recursive triangle function
Recursion with cond
Recursive Patterns Often used templates.
No Deferment Don't store up work ...
No deferment solution
Recursion in Place of a Counter
Recursive Example arg of 1 or 2
Recursive Example arg of 3 or 4
Recursive Patterns
Regular Expression Searches
sentence-end The regular expression for sentence-end.
re-search-forward Very similar to search-forward.
forward-sentence A straightforward example of regexp search.
forward-paragraph A somewhat complex example.
Regexp Review
re-search Exercises
Complete forward-sentence
fwd-sentence while loops Two while loops.
fwd-sentence re-search A regular expression search.
forward-paragraph: a Goldmine of Functions
forward-paragraph in brief Key parts of the function definition.
fwd-para let The let* expression.
fwd-para while The forward motion while loop.
Counting: Repetition and Regexps
Why Count Words
count-words-example Use a regexp, but find a problem.
recursive-count-words Start with case of no words in region.
Counting Exercise
The count-words-example Function
Design count-words-example The definition using a while loop.
Whitespace Bug The Whitespace Bug in count-words-example.
Counting Words in a defun
Divide and Conquer
Words and Symbols What to count?
Syntax What constitutes a word or symbol?
count-words-in-defun Very like count-words-example.
Several defuns Counting several defuns in a file.
Find a File Do you want to look at a file?
lengths-list-file A list of the lengths of many definitions.
Several files Counting in definitions in different files.
Several files recursively Recursively counting in different files.
Prepare the data Prepare the data for display in a graph.
Count Words in defuns in Different Files
lengths-list-many-files Return a list of the lengths of defuns.
append Attach one list to another.
Prepare the Data for Display in a Graph
Data for Display in Detail
Sorting Sorting lists.
Files List Making a list of files.
Counting function definitions
Readying a Graph
Columns of a graph
graph-body-print How to print the body of a graph.
Printed Axes
Line Graph Exercise
Your .emacs File
Default Configuration
Site-wide Init You can write site-wide init files.
defcustom Emacs will write code for you.
Beginning init File How to write a .emacs init file.
Text and Auto-fill Automatically wrap lines.
Mail Aliases Use abbreviations for email addresses.
Indent Tabs Mode Don't use tabs with TeX
Keybindings Create some personal keybindings.
Keymaps More about key binding.
Loading Files Load (i.e., evaluate) files automatically.
Autoload Make functions available.
Simple Extension Define a function; bind it to a key.
X11 Colors Colors in X.
Mode Line How to customize your mode line.
debug How to use the built-in debugger.
debug-on-entry Start debugging when you call a function.
debug-on-quit Start debugging when you quit with C-g.
edebug How to use Edebug, a source level debugger.
Debugging Exercises
Handling the Kill Ring
What the Kill Ring Does
yank Paste a copy of a clipped element.
yank-pop Insert element pointed to.
ring file
The current-kill Function
Code for current-kill
Understanding current-kill
current-kill in Outline
Body of current-kill
Digression concerning error How to mislead humans, but not computers.
Determining the Element
A Graph with Labeled Axes
Labeled Example
print-graph Varlist let expression in print-graph.
print-Y-axis Print a label for the vertical axis.
print-X-axis Print a horizontal label.
Print Whole Graph The function to print a complete graph.
The print-Y-axis Function
print-Y-axis in Detail
Height of label What height for the Y axis?
Compute a Remainder How to compute the remainder of a division.
Y Axis Element Construct a line for the Y axis.
Y-axis-column Generate a list of Y axis labels.
print-Y-axis Penultimate A not quite final version.
The print-X-axis Function
Similarities differences Much like print-Y-axis, but not exactly.
X Axis Tic Marks Create tic marks for the horizontal axis.
Printing the Whole Graph
The final version A few changes.
Test print-graph Run a short test.
Graphing words in defuns Executing the final code.
lambda How to write an anonymous function.
mapcar Apply a function to elements of a list.
Another Bug Yet another bug ... most insidious.
Final printed graph The graph itself!