An Introduction to Programming in Emacs Lisp

The GNU Emacs website is at https://www.gnu.org/software/emacs/.
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 30.2.

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

Printed copies available from https://shop.fsf.org/. Published by:

GNU Press,                        https://www.fsf.org/licensing/gnu-press/
a division of the                 email: sales@fsf.org
Free Software Foundation, Inc.    Tel: +1 (617) 542-5942
31 Milk Street, # 960789          Fax: +1 (617) 542-2652
Boston, MA 02196 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.

Table of Contents

• Preface

  • Why Study Emacs Lisp?
  • On Reading this Text
  • For Whom This is Written
  • Lisp History
  • A Note for Novices
  • Thank You

• 1 List Processing

  • 1.1 Lisp Lists

    • Numbers, Lists inside of Lists
    • 1.1.1 Lisp Atoms
    • 1.1.2 Whitespace in Lists
    • 1.1.3 GNU Emacs Helps You Type Lists

  • 1.2 Run a Program

  • 1.3 Generate an Error Message

  • 1.4 Symbol Names and Function Definitions

  • 1.5 The Lisp Interpreter

    • Complications
    • 1.5.1 Byte Compiling

  • 1.6 Evaluation

    • How the Lisp Interpreter Acts
    • 1.6.1 Evaluating Inner Lists

  • 1.7 Variables

    • fill-column, an Example Variable
    • 1.7.1 Error Message for a Symbol Without a Function
    • 1.7.2 Error Message for a Symbol Without a Value

  • 1.8 Arguments

    • 1.8.1 Arguments’ Data Types
    • 1.8.2 An Argument as the Value of a Variable or List
    • 1.8.3 Variable Number of Arguments
    • 1.8.4 Using the Wrong Type Object as an Argument
    • 1.8.5 The message Function

  • 1.9 Setting the Value of a Variable

    • 1.9.1 Using setq
    • 1.9.2 Counting

  • 1.10 Summary

  • 1.11 Exercises

• 2 Practicing Evaluation

  • How to Evaluate
  • 2.1 Buffer Names
  • 2.2 Getting Buffers
  • 2.3 Switching Buffers
  • 2.4 Buffer Size and the Location of Point
  • 2.5 Exercise

• 3 How To Write Function Definitions

  • An Aside about Primitive Functions

  • 3.1 The defun Macro

  • 3.2 Install a Function Definition

    • The effect of installation
    • 3.2.1 Change a Function Definition

  • 3.3 Make a Function Interactive

    • An Interactive multiply-by-seven, An Overview
    • 3.3.1 An Interactive multiply-by-seven

  • 3.4 Different Options for interactive

  • 3.5 Install Code Permanently

  • 3.6 let

    • let Prevents Confusion

    • 3.6.1 The Parts of a let Expression

    • 3.6.2 Sample let Expression

    • 3.6.3 Uninitialized Variables in a let Statement

    • 3.6.4 How let Binds Variables

      • Differences Between Lexical and Dynamic Binding
      • Example of Lexical vs. Dynamic Binding

  • 3.7 The if Special Form

    • if in more detail
    • 3.7.1 The type-of-animal Function in Detail

  • 3.8 If–then–else Expressions

  • 3.9 Truth and Falsehood in Emacs Lisp

    • An explanation of nil

  • 3.10 save-excursion

    • Point and Mark
    • 3.10.1 Template for a save-excursion Expression

  • 3.11 Review

  • 3.12 Exercises

• 4 A Few Buffer-Related Functions

  • 4.1 Finding More Information

  • 4.2 A Simplified beginning-of-buffer Definition

  • 4.3 The Definition of mark-whole-buffer

    • An overview of mark-whole-buffer
    • 4.3.1 Body of mark-whole-buffer

  • 4.4 The Definition of append-to-buffer

    • An Overview of append-to-buffer
    • 4.4.1 The append-to-buffer Interactive Expression
    • 4.4.2 The Body of append-to-buffer
    • 4.4.3 save-excursion in append-to-buffer

  • 4.5 Review

  • 4.6 Exercises

• 5 A Few More Complex Functions

  • 5.1 The Definition of copy-to-buffer

  • 5.2 The Definition of insert-buffer

    • The Code for insert-buffer

    • 5.2.1 The Interactive Expression in insert-buffer

      • A Read-only Buffer
      • ‘b’ in an Interactive Expression

    • 5.2.2 The Body of the insert-buffer Function

    • 5.2.3 insert-buffer With an if Instead of an or

    • 5.2.4 The or in the Body

    • 5.2.5 The let Expression in insert-buffer

    • 5.2.6 New Body for insert-buffer

  • 5.3 Complete Definition of beginning-of-buffer

    • 5.3.1 Optional Arguments

    • 5.3.2 beginning-of-buffer with an Argument

      • Disentangle beginning-of-buffer
      • What happens in a large buffer
      • What happens in a small buffer

    • 5.3.3 The Complete beginning-of-buffer

  • 5.4 Review

  • 5.5 optional Argument Exercise

• 6 Narrowing and Widening

  • The Advantages of Narrowing
  • 6.1 The save-restriction Special Form
  • 6.2 what-line
  • 6.3 Exercise with Narrowing

• 7 car, cdr, cons: Fundamental Functions

  • Strange Names

  • 7.1 car and cdr

  • 7.2 cons

    • Build a list
    • 7.2.1 Find the Length of a List: length

  • 7.3 nthcdr

  • 7.4 nth

  • 7.5 setcar

  • 7.6 setcdr

  • 7.7 Exercise

• 8 Cutting and Storing Text

  • Storing Text in a List

  • 8.1 zap-to-char

    • The Complete zap-to-char Implementation
    • 8.1.1 The interactive Expression
    • 8.1.2 The Body of zap-to-char
    • 8.1.3 The search-forward Function
    • 8.1.4 The progn Special Form
    • 8.1.5 Summing up zap-to-char

  • 8.2 kill-region

    • The Complete kill-region Definition
    • 8.2.1 condition-case
    • 8.2.2 Lisp macro

  • 8.3 copy-region-as-kill

    • The complete copy-region-as-kill function definition

    • 8.3.1 The Body of copy-region-as-kill

      • last-command and this-command
      • The kill-append function
      • The kill-new function

  • 8.4 Digression into C

  • 8.5 Initializing a Variable with defvar

    • Seeing the Current Value of a Variable
    • 8.5.1 defvar and an asterisk

  • 8.6 Review

  • 8.7 Searching Exercises

• 9 How Lists are Implemented

  • Lists diagrammed
  • 9.1 Symbols as a Chest of Drawers
  • 9.2 Exercise

• 10 Yanking Text Back

  • 10.1 Kill Ring Overview
  • 10.2 The kill-ring-yank-pointer Variable
  • 10.3 Exercises with yank and nthcdr

• 11 Loops and Recursion

  • 11.1 while

    • Looping with while

    • 11.1.1 A while Loop and a List

    • 11.1.2 An Example: print-elements-of-list

    • 11.1.3 A Loop with an Incrementing Counter

    • Details of an Incrementing Loop

      • Example with incrementing counter
      • The parts of the function definition
      • Putting the function definition together

    • 11.1.4 Loop with a Decrementing Counter

      • Example with decrementing counter
      • The parts of the function definition
      • Putting the function definition together

  • 11.2 Save your time: dolist and dotimes

    • The dolist Macro
    • The dotimes Macro

  • 11.3 Recursion

    • 11.3.1 Building Robots: Extending the Metaphor

    • 11.3.2 The Parts of a Recursive Definition

    • 11.3.3 Recursion with a List

    • 11.3.4 Recursion in Place of a Counter

      • An argument of 1 or 2
      • An argument of 3 or 4

    • 11.3.5 Recursion Example Using cond

    • 11.3.6 Recursive Patterns

      • Recursive Pattern: every
      • Recursive Pattern: accumulate
      • Recursive Pattern: keep

    • 11.3.7 Recursion without Deferments

    • 11.3.8 No Deferment Solution

  • 11.4 Looping Exercise

• 12 Regular Expression Searches

  • 12.1 The Regular Expression for sentence-end

  • 12.2 The re-search-forward Function

  • 12.3 forward-sentence

    • Complete forward-sentence function definition
    • The while loops
    • The regular expression search

  • 12.4 forward-paragraph: a Goldmine of Functions

    • Shortened forward-paragraph function definition
    • The let* expression
    • The forward motion while loop

  • 12.5 Review

  • 12.6 Exercises with re-search-forward

• 13 Counting via Repetition and Regexps

  • Counting words

  • 13.1 The count-words-example Function

    • Designing count-words-example
    • 13.1.1 The Whitespace Bug in count-words-example

  • 13.2 Count Words Recursively

  • 13.3 Exercise: Counting Punctuation

• 14 Counting Words in a defun

  • Divide and Conquer

  • 14.1 What to Count?

  • 14.2 What Constitutes a Word or Symbol?

  • 14.3 The count-words-in-defun Function

  • 14.4 Count Several defuns Within a File

  • 14.5 Find a File

  • 14.6 lengths-list-file in Detail

  • 14.7 Count Words in defuns in Different Files

    • Determine the lengths of defuns
    • 14.7.1 The append Function

  • 14.8 Recursively Count Words in Different Files

  • 14.9 Prepare the Data for Display in a Graph

    • The Data for Display in Detail
    • 14.9.1 Sorting Lists
    • 14.9.2 Making a List of Files
    • 14.9.3 Counting function definitions

• 15 Readying a Graph

  • Printing the Columns of a Graph
  • 15.1 The graph-body-print Function
  • 15.2 The recursive-graph-body-print Function
  • 15.3 Need for Printed Axes
  • 15.4 Exercise

• 16 Your .emacs File

  • Emacs’s Default Configuration
  • 16.1 Site-wide Initialization Files
  • 16.2 Specifying Variables using defcustom
  • 16.3 Beginning a .emacs File
  • 16.4 Text and Auto Fill Mode
  • 16.5 Mail Aliases
  • 16.6 Indent Tabs Mode
  • 16.7 Some Key Bindings
    • 16.7.1 Legacy Global Key Binding Commands
  • 16.8 Keymaps
  • 16.9 Loading Files
  • 16.10 Autoloading
  • 16.11 A Simple Extension: line-to-top-of-window
  • 16.12 X11 Colors
  • 16.13 Miscellaneous Settings for a .emacs File
  • 16.14 A Modified Mode Line

• 17 Debugging

  • 17.1 debug
  • 17.2 debug-on-entry
  • 17.3 debug-on-quit and (debug)
  • 17.4 The edebug Source Level Debugger
  • 17.5 Debugging Exercises

• 18 Conclusion

• Appendix A The the-the Function

• Appendix B Handling the Kill Ring

  • What the Kill Ring Does

  • B.1 The current-kill Function

    • The code for current-kill

    • current-kill in Outline

      • The Body of current-kill
      • Digression about the word “error”
      • Determining the Element

  • B.2 yank

  • B.3 yank-pop

  • B.4 The ring.el File

• Appendix C A Graph with Labeled Axes

  • Labeled Example Graph

  • C.1 The print-graph Varlist

  • C.2 The print-Y-axis Function

    • The print-Y-axis Function in Detail
    • What height should the label be?
    • C.2.1 Side Trip: Compute a Remainder
    • C.2.2 Construct a Y Axis Element
    • C.2.3 Create a Y Axis Column
    • C.2.4 The Not Quite Final Version of print-Y-axis

  • C.3 The print-X-axis Function

    • Similarities and differences
    • C.3.1 X Axis Tic Marks

  • C.4 Printing the Whole Graph

    • Changes for the Final Version
    • C.4.1 Testing print-graph
    • C.4.2 Graphing Numbers of Words and Symbols
    • C.4.3 A lambda Expression: Useful Anonymity
    • C.4.4 The mapcar Function
    • C.4.5 Another Bug … Most Insidious
    • C.4.6 The Printed Graph

• Appendix D Free Software and Free Manuals

• Appendix E GNU Free Documentation License

• Index

• About the Author