Programming in Emacs Lisp

An Introduction to Programming in Emacs Lisp

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

Published by the:

     GNU Press,                          Website: http://www.gnupress.org
     a division of the                   General: press@gnu.org
     Free Software Foundation, Inc.      Orders:  sales@gnu.org
     51 Franklin Street, Fifth Floor     Tel: +1 (617) 542-5942
     Boston, MA 02110-1301 USA           Fax: +1 (617) 542-2652

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 labelled axes.
• Free Software and Free Manuals
• GNU Free Documentation License
• Index
• About the Author

--- The Detailed Node Listing ---

Preface

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

Evaluation

• How the Interpreter Acts: Returns and Side Effects...
• Evaluating Inner Lists: Lists within lists...

Variables

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

Arguments

• 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 special form.
• 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, mark, and buffer.
• Review
• 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.

let

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

save-excursion

• 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.
• nth
• setcar: Changing the first element of a list.
• setcdr: Changing the rest of a list.
• cons Exercise

cons

• 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

zap-to-char

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

kill-region

• Complete kill-region: The function definition.
• condition-case: Dealing with a problem.
• Lisp macro

copy-region-as-kill

• 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

while

• 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

• dolist
• dotimes

Recursion

• 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

• Every
• Accumulate
• Keep

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.
• etags: How to create your own TAGS table.
• Regexp Review
• re-search Exercises

forward-sentence

• 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-region: Use a regexp, but find a problem.
• recursive-count-words: Start with case of no words in region.
• Counting Exercise

The count-words-region Function

• Design count-words-region: The definition using a while loop.
• Whitespace Bug: The Whitespace Bug in count-words-region.

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.
• 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.
• recursive-graph-body-print
• 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 a .emacs File: How to write a .emacs 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.
• Miscellaneous
• Mode Line: How to customize your mode line.

Debugging

• 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
• current-kill
• 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 Labelled Axes

• Labelled 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!