Programming in Emacs Lisp

@insertcopying

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

Preface		What to look for.
1. List Processing		What is Lisp?
2. Practicing Evaluation		Running several programs.
3. How To Write Function Definitions		How to write function definitions.
4. A Few Buffer--Related Functions		Exploring a few buffer-related functions.
5. A Few More Complex Functions		A few, even more complex functions.
6. Narrowing and Widening		Restricting your and Emacs attention to a region.
7. car, cdr, cons: Fundamental Functions		Fundamental functions in Lisp.
8. Cutting and Storing Text		Removing text and saving it.
9. How Lists are Implemented		How lists are implemented in the computer.
10. Yanking Text Back		Pasting stored text.
11. Loops and Recursion		How to repeat a process.
12. Regular Expression Searches		Regular expression searches.
13. Counting: Repetition and Regexps		A review of repetition and regexps.
14. Counting Words in a defun		Counting words in a defun.
15. Readying a Graph		A prototype graph printing function.
16. Your `.emacs' File		How to write a `.emacs' file.
17. Debugging		How to run the Emacs Lisp debuggers.
18. Conclusion		Now you have the basics.
A. The the-the Function		An appendix: how to find reduplicated words.
B. Handling the Kill Ring		An appendix: how the kill ring works.
C. A Graph with Labelled Axes		How to create a graph with labelled axes.
D. Free Software and Free Manuals
E. GNU Free Documentation License
Index
About the Author

 -- The Detailed Node Listing ---

Preface

Why Study Emacs Lisp?		Why learn Emacs Lisp?
On Reading this Text		Read, gain familiarity, pick up habits....
For Whom This is Written		For whom this is written.
Lisp History
A Note for Novices		You can read this as a novice.
Thank You

List Processing

1.1 Lisp Lists		What are lists?
1.2 Run a Program		Any list in Lisp is a program ready to run.
1.3 Generate an Error Message		Generating an error message.
1.4 Symbol Names and Function Definitions		Names of symbols and function definitions.
1.5 The Lisp Interpreter		What the Lisp interpreter does.
1.6 Evaluation		Running a program.
1.7 Variables		Returning a value from a variable.
1.8 Arguments		Passing information to a function.
1.9 Setting the Value of a Variable		Setting the value of a variable.
1.10 Summary		The major points.
1.11 Exercises

Lisp Lists

Numbers, Lists inside of Lists		List have numbers, other lists, in them.
1.1.1 Lisp Atoms		Elemental entities.
1.1.2 Whitespace in Lists		Formatting lists to be readable.
1.1.3 GNU Emacs Helps You Type Lists		How GNU Emacs helps you type lists.

The Lisp Interpreter

Complications		Variables, Special forms, Lists within.
1.5.1 Byte Compiling		Specially processing code for speed.

Evaluation

How the Lisp Interpreter Acts		Returns and Side Effects...
1.6.1 Evaluating Inner Lists		Lists within lists...

Variables

fill-column, an Example Variable
1.7.1 Error Message for a Symbol Without a Function		The error message for a symbol without a function.
1.7.2 Error Message for a Symbol Without a Value		The error message for a symbol without a value.

Arguments

1.8.1 Arguments' Data Types		Types of data passed to a function.
1.8.2 An Argument as the Value of a Variable or List		An argument can be the value of a variable or list.
1.8.3 Variable Number of Arguments		Some functions may take a variable number of arguments.
1.8.4 Using the Wrong Type Object as an Argument		Passing an argument of the wrong type to a function.
1.8.5 The message Function		A useful function for sending messages.

Setting the Value of a Variable

1.9.1 Using set		Setting values.
1.9.2 Using setq		Setting a quoted value.
1.9.3 Counting		Using setq to count.

Practicing Evaluation

How to Evaluate		Typing editing commands or C-x C-e causes evaluation.
2.1 Buffer Names		Buffers and files are different.
2.2 Getting Buffers		Getting a buffer itself, not merely its name.
2.3 Switching Buffers		How to change to another buffer.
2.4 Buffer Size and the Location of Point		Where point is located and the size of the buffer.
2.5 Exercise

How To Write Function Definitions

An Aside about Primitive Functions
3.1 The defun Special Form		The defun special form.
3.2 Install a Function Definition		Install a function definition.
3.3 Make a Function Interactive		Making a function interactive.
3.4 Different Options for interactive		Different options for interactive.
3.5 Install Code Permanently		Installing code permanently.
3.6 let		Creating and initializing local variables.
3.7 The if Special Form		What if?
3.8 If--then--else Expressions		If--then--else expressions.
3.9 Truth and Falsehood in Emacs Lisp		What Lisp considers false and true.
3.10 save-excursion		Keeping track of point, mark, and buffer.
3.11 Review
3.12 Exercises

Install a Function Definition

The effect of installation
3.2.1 Change a Function Definition		How to change a function definition.

Make a Function Interactive

An Interactive multiply-by-seven, An Overview		An overview.
3.3.1 An Interactive multiply-by-seven		The interactive version.

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

The if Special Form

if in more detail
3.7.1 The type-of-animal Function in Detail		An example of an if expression.

Truth and Falsehood in Emacs Lisp

An explanation of nil

nil has two meanings.

save-excursion

Point and Mark		A review of various locations.
3.10.1 Template for a save-excursion Expression

A Few Buffer--Related Functions

4.1 Finding More Information		How to find more information.
4.2 A Simplified beginning-of-buffer Definition		Shows goto-char,

                                point-min, and push-mark.

4.3 The Definition of mark-whole-buffer		Almost the same as beginning-of-buffer.
4.4 The Definition of append-to-buffer		Uses save-excursion and

                                insert-buffer-substring.

4.5 Review
4.6 Exercises

The Definition of mark-whole-buffer

An overview of mark-whole-buffer
4.3.1 Body of mark-whole-buffer		Only three lines of code.

The Definition of append-to-buffer

An Overview of append-to-buffer
4.4.1 The append-to-buffer Interactive Expression		A two part interactive expression.
4.4.2 The Body of append-to-buffer		Incorporates a let expression.
4.4.3 save-excursion in append-to-buffer		How the save-excursion works.

A Few More Complex Functions

5.1 The Definition of copy-to-buffer		With set-buffer, get-buffer-create.
5.2 The Definition of insert-buffer		Read-only, and with or.
5.3 Complete Definition of beginning-of-buffer		Shows goto-char,

                                point-min, and push-mark.

5.4 Review
5.5 optional Argument Exercise

The Definition of insert-buffer

The Code for insert-buffer
5.2.1 The Interactive Expression in insert-buffer		When you can read, but not write.
5.2.2 The Body of the insert-buffer Function		The body has an or and a let.
5.2.3 insert-buffer With an if Instead of an or		Using an if instead of an or.
5.2.4 The or in the Body		How the or expression works.
5.2.5 The let Expression in insert-buffer		Two save-excursion expressions.
5.2.6 New Body for insert-buffer

The Interactive Expression in insert-buffer

A Read-only Buffer		When a buffer cannot be modified.
`b' in an Interactive Expression		An existing buffer or else its name.

Complete Definition of beginning-of-buffer

5.3.1 Optional Arguments
5.3.2 beginning-of-buffer with an Argument		Example with optional argument.
5.3.3 The Complete beginning-of-buffer

beginning-of-buffer with an Argument

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

Narrowing and Widening

The Advantages of Narrowing		The advantages of narrowing
6.1 The save-restriction Special Form		The save-restriction special form.
6.2 what-line		The number of the line that point is on.
6.3 Exercise with Narrowing

car, cdr, cons: Fundamental Functions

Strange Names		An historical aside: why the strange names?
7.1 car and cdr		Functions for extracting part of a list.
7.2 cons		Constructing a list.
7.3 nthcdr		Calling cdr repeatedly.
7.4 nth
7.5 setcar		Changing the first element of a list.
7.6 setcdr		Changing the rest of a list.
7.7 Exercise

cons

Build a list
7.2.1 Find the Length of a List: length		How to find the length of a list.

Cutting and Storing Text

Storing Text in a List		Text is stored in a list.
8.1 zap-to-char		Cutting out text up to a character.
8.2 kill-region		Cutting text out of a region.
8.3 copy-region-as-kill		A definition for copying text.
8.4 Digression into C		Minor note on C programming language macros.
8.5 Initializing a Variable with defvar		How to give a variable an initial value.
8.6 Review
8.7 Searching Exercises

zap-to-char

The Complete zap-to-char Implementation		The complete implementation.
8.1.1 The interactive Expression		A three part interactive expression.
8.1.2 The Body of zap-to-char		A short overview.
8.1.3 The search-forward Function		How to search for a string.
8.1.4 The progn Special Form		The progn special form.
8.1.5 Summing up zap-to-char		Using point and search-forward.

kill-region

The Complete kill-region Definition		The function definition.
8.2.1 condition-case		Dealing with a problem.
8.2.2 Lisp macro

copy-region-as-kill

The complete copy-region-as-kill function definition		The complete function definition.
8.3.1 The Body of copy-region-as-kill		The body of copy-region-as-kill.

The Body of copy-region-as-kill

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

Initializing a Variable with defvar

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

How Lists are Implemented

Lists diagrammed
9.1 Symbols as a Chest of Drawers		Exploring a powerful metaphor.
9.2 Exercise

Yanking Text Back

10.1 Kill Ring Overview
10.2 The kill-ring-yank-pointer Variable		The kill ring is a list.
10.3 Exercises with yank and nthcdr		The kill-ring-yank-pointer variable.

Loops and Recursion

11.1 while		Causing a stretch of code to repeat.
11.2 Save your time: dolist and dotimes
11.3 Recursion		Causing a function to call itself.
11.4 Looping Exercise

while

Looping with while		Repeat so long as test returns true.
11.1.1 A while Loop and a List		A while loop that uses a list.
11.1.2 An Example: print-elements-of-list		Uses while, car, cdr.
11.1.3 A Loop with an Incrementing Counter		A loop with an incrementing counter.
Details of an Incrementing Loop
11.1.4 Loop with a Decrementing Counter		A loop with a decrementing counter.

Details of an Incrementing Loop

Example with incrementing counter		Counting pebbles in a triangle.
The parts of the function definition
Putting the function definition together

Loop with a Decrementing Counter

Example with decrementing counter		More pebbles on the beach.
The parts of the function definition
Putting the function definition together

Save your time: dolist and dotimes

The dolist Macro
The dotimes Macro

Recursion

11.3.1 Building Robots: Extending the Metaphor		Same model, different serial number ...
11.3.2 The Parts of a Recursive Definition		Walk until you stop ...
11.3.3 Recursion with a List		Using a list as the test whether to recurse.
11.3.4 Recursion in Place of a Counter
11.3.5 Recursion Example Using cond
11.3.6 Recursive Patterns		Often used templates.
11.3.7 Recursion without Deferments		Don't store up work ...
11.3.8 No Deferment Solution

Recursion in Place of a Counter

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

Recursive Patterns

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

Regular Expression Searches

12.1 The Regular Expression for sentence-end		The regular expression for sentence-end.
12.2 The re-search-forward Function		Very similar to search-forward.
12.3 forward-sentence		A straightforward example of regexp search.
12.4 forward-paragraph: a Goldmine of Functions		A somewhat complex example.
12.5 Create Your Own `TAGS' File		How to create your own `TAGS' table.
12.6 Review
12.7 Exercises with re-search-forward

forward-sentence

Complete forward-sentence function definition
The while loops		Two while loops.
The regular expression search		A regular expression search.

forward-paragraph: a Goldmine of Functions

Shortened forward-paragraph function definition		Key parts of the function definition.
The let* expression
The forward motion while loop

Counting: Repetition and Regexps

Counting words
13.1 The count-words-region Function		Use a regexp, but find a problem.
13.2 Count Words Recursively		Start with case of no words in region.
13.3 Exercise: Counting Punctuation

The count-words-region Function

Designing count-words-region		The definition using a while loop.
13.1.1 The Whitespace Bug in count-words-region

Counting Words in a defun

Divide and Conquer
14.1 What to Count?		What to count?
14.2 What Constitutes a Word or Symbol?		What constitutes a word or symbol?
14.3 The count-words-in-defun Function		Very like count-words.
14.4 Count Several defuns Within a File		Counting several defuns in a file.
14.5 Find a File		Do you want to look at a file?
14.6 lengths-list-file in Detail		A list of the lengths of many definitions.
14.7 Count Words in defuns in Different Files		Counting in definitions in different files.
14.8 Recursively Count Words in Different Files		Recursively counting in different files.
14.9 Prepare the Data for Display in a Graph		Prepare the data for display in a graph.

Count Words in defuns in Different Files

Determine the lengths of defuns		Return a list of the lengths of defuns.
14.7.1 The append Function		Attach one list to another.

Prepare the Data for Display in a Graph

The Data for Display in Detail
14.9.1 Sorting Lists		Sorting lists.
14.9.2 Making a List of Files		Making a list of files.
14.9.3 Counting function definitions

Readying a Graph

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

Your `.emacs' File

Emacs' Default Configuration
16.1 Site-wide Initialization Files		You can write site-wide init files.
16.2 Specifying Variables using defcustom		Emacs will write code for you.
16.3 Beginning a `.emacs' File		How to write a .emacs file.
16.4 Text and Auto Fill Mode		Automatically wrap lines.
16.5 Mail Aliases		Use abbreviations for email addresses.
16.6 Indent Tabs Mode		Don't use tabs with TeX
16.7 Some Keybindings		Create some personal keybindings.
16.8 Keymaps		More about key binding.
16.9 Loading Files		Load (i.e., evaluate) files automatically.
16.10 Autoloading		Make functions available.
16.11 A Simple Extension: line-to-top-of-window		Define a function; bind it to a key.
16.12 X11 Colors		Colors in X.
16.13 Miscellaneous Settings for a `.emacs' File
16.14 A Modified Mode Line		How to customize your mode line.

Debugging

17.1 debug		How to use the built-in debugger.
17.2 debug-on-entry		Start debugging when you call a function.
17.3 debug-on-quit and (debug)		Start debugging when you quit with C-g.
17.4 The edebug Source Level Debugger		How to use Edebug, a source level debugger.
17.5 Debugging Exercises

Handling the Kill Ring

What the Kill Ring Does
B.1 The current-kill Function
B.2 yank		Paste a copy of a clipped element.
B.3 yank-pop		Insert element pointed to.
B.4 The `ring.el' File

The current-kill Function

current-kill in Outline

current-kill in Outline

The Body of current-kill
Digression about the word `error'		How to mislead humans, but not computers.
Determining the Element

A Graph with Labelled Axes

Labelled Example Graph
C.1 The print-graph Varlist		let expression in print-graph.
C.2 The print-Y-axis Function		Print a label for the vertical axis.
C.3 The print-X-axis Function		Print a horizontal label.
C.4 Printing the Whole Graph		The function to print a complete graph.

The print-Y-axis Function

The print-Y-axis Function in Detail
What height should the label be?		What height for the Y axis?
C.2.1 Side Trip: Compute a Remainder		How to compute the remainder of a division.
C.2.2 Construct a Y Axis Element		Construct a line for the Y axis.
C.2.3 Create a Y Axis Column		Generate a list of Y axis labels.
C.2.4 The Not Quite Final Version of print-Y-axis		A not quite final version.

The print-X-axis Function

Similarities and differences		Much like print-Y-axis, but not exactly.
C.3.1 X Axis Tic Marks		Create tic marks for the horizontal axis.

Printing the Whole Graph

Changes for the Final Version		A few changes.
C.4.1 Testing print-graph		Run a short test.
C.4.2 Graphing Numbers of Words and Symbols		Executing the final code.
C.4.3 A lambda Expression: Useful Anonymity		How to write an anonymous function.
C.4.4 The mapcar Function		Apply a function to elements of a list.
C.4.5 Another Bug ... Most Insidious		Yet another bug ... most insidious.
C.4.6 The Printed Graph		The graph itself!

mail: