comparison lispintro/emacs-lisp-intro.texi @ 73854:55e5dc416293

Copy descriptions from detailed master menu to menus within body.

73853:fb904438445a

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

@code{let}

* Prevent confusion::
* Parts of let Expression::

* Lisp macro::

@code{copy-region-as-kill}

* Complete copy-region-as-kill::  The complete function definition.
* copy-region-as-kill body::    The body of @code{copy-region-as-kill}.

The Body of @code{copy-region-as-kill}

* last-command & this-command::
* kill-append function::

and phases of the moon, simplify polynomials, debug code, manage
files, read letters, write books---all these activities are kinds of
editing in the most general sense of the word.)

@menu
* Why::
* On Reading this Text::
* Who You Are::
* Lisp History::
* Note for Novices::
* Thank You::
@end menu

@node Why, On Reading this Text, Preface, Preface
@ifnottex

mark is an abbreviation for the function @code{quote}; you need not
think about functions now; functions are defined in @ref{Making
Errors, , Generate an Error Message}.}  Lists are the basis of Lisp.

@menu
* Lisp Lists::
* Run a Program::
* Making Errors::
* Names & Definitions::
* Lisp Interpreter::
* Evaluation::
* Variables::
* Arguments::
* set & setq::
* Summary::
* Error Message Exercises::
@end menu

@node Lisp Lists, Run a Program, List Processing, List Processing
@comment  node-name,  next,  previous,  up

separated from each other by whitespace and surrounded by parentheses,
like flowers in a field with a stone wall around them.
@cindex Flowers in a field

@menu
* Numbers Lists::
* Lisp Atoms::
* Whitespace in Lists::
* Typing Lists::
@end menu

@node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
@ifnottex
@unnumberedsubsec Numbers, Lists inside of Lists

write Lisp programs, you need to know how to write function definitions
and attach them to names, and how to do this without confusing either
yourself or the computer.

@menu
* Complications::
* Byte Compiling::
@end menu

@node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
@ifnottex
@unnumberedsubsec Complications

The word comes from its use in everyday language, `to ascertain the
value or amount of; to appraise', according to @cite{Webster's New
Collegiate Dictionary}.

@menu
* How the Interpreter Acts::
* Evaluating Inner Lists::
@end menu

@node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation
@ifnottex
@unnumberedsubsec How the Lisp Interpreter Acts

changed without affecting the contents of the drawer holding the
function definition, and vice-verse.

@menu
* fill-column Example::
* Void Function::
* Void Variable::
@end menu

@node fill-column Example, Void Function, Variables, Variables
@ifnottex
@unnumberedsubsec @code{fill-column}, an Example Variable

(Note here that the English word has two different definitions attached
to it at the same time.  By contrast, in Emacs Lisp, a symbol cannot
have two different function definitions at the same time.)}

@menu
* Data types::
* Args as Variable or List::
* Variable Number of Arguments::
* Wrong Type of Argument::
* message::
@end menu

@node Data types, Args as Variable or List, Arguments, Arguments
@comment  node-name,  next,  previous,  up
@subsection Arguments' Data Types

The following sections not only describe how @code{set} and @code{setq}
work but also illustrate how arguments are passed.

@menu
* Using set::
* Using setq::
* Counting::
@end menu

@node Using set, Using setq, set & setq, set & setq
@comment  node-name,  next,  previous,  up
@subsection Using @code{set}

will start with those.  In this section, we will evaluate a few of
these.  In another section, we will study the code of several other
buffer-related functions, to see how they were written.

@menu
* How to Evaluate::
* Buffer Names::
* Getting Buffers::
* Switching Buffers::
* Buffer Size & Locations::
* Evaluation Exercise::
@end menu

@node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
@ifnottex

(although, properly speaking, the definition is the function and the
symbol refers to it.)

@menu
* Primitive Functions::
* defun::
* Install::
* Interactive::
* Interactive Options::
* Permanent Installation::
* let::
* if::
* else::
* Truth & Falsehood::
* save-excursion::
* Review::
* defun Exercises::
@end menu

@node Primitive Functions, defun, Writing Defuns, Writing Defuns

Emacs.  To reload code automatically whenever you start Emacs, see
@ref{Permanent Installation, , Installing Code Permanently}.)

@menu
* Effect of installation::
* Change a defun::
@end menu

@node Effect of installation, Change a defun, Install, Install
@ifnottex
@unnumberedsubsec The effect of installation

effects, such as moving forward by a word or line, and not for the
value returned.  If the returned value were displayed in the echo area
each time you typed a key, it would be very distracting.

@menu
* Interactive multiply-by-seven::
* multiply-by-seven in detail::
@end menu

@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
@ifnottex
@unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview

expression is not evaluated.  For example, you might make a decision
such as, ``if it is warm and sunny, then go to the beach!''

@menu
* if in more detail::
* type-of-animal in detail::
@end menu

@node if in more detail, type-of-animal in detail, if, if
@ifnottex
@unnumberedsubsec @code{if} in more detail

returned is a number such as 47, a string such as @code{"hello"}, or a
symbol (other than @code{nil}) such as @code{flowers}, or a list (so
long as it is not empty), or even a buffer!

@menu
* nil explained::
@end menu

@node nil explained,  , Truth & Falsehood, Truth & Falsehood
@ifnottex
@unnumberedsubsec An explanation of @code{nil}

their previous positions if their locations were changed.  Its primary
purpose is to keep the user from being surprised and disturbed by
unexpected movement of point or mark.

@menu
* Point and mark::
* Template for save-excursion::
@end menu

@node Point and mark, Template for save-excursion, save-excursion, save-excursion
@ifnottex

show the actual code used in GNU Emacs.  You can learn a great deal from
these definitions.  The functions described here are all related to
buffers.  Later, we will study other functions.

@menu
* Finding More::
* simplified-beginning-of-buffer::
* mark-whole-buffer::
* append-to-buffer::
* Buffer Related Review::
* Buffer Exercises::
@end menu

@node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through
@section Finding More Information

a mark at the end of the buffer.  It is generally bound to @kbd{C-x
h}.

@menu
* mark-whole-buffer overview::
* Body of mark-whole-buffer::
@end menu

@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
@ifnottex
@unnumberedsubsec An overview of @code{mark-whole-buffer}

(that is, the part of the buffer between point and mark) from the
current buffer to a specified buffer.

@menu
* append-to-buffer overview::
* append interactive::
* append-to-buffer body::
* append save-excursion::
@end menu

@node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
@ifnottex
@unnumberedsubsec An Overview of @code{append-to-buffer}

use of an asterisk in an @code{interactive} expression, use of
@code{or}, and the important distinction between a name and the object
to which the name refers.

@menu
* copy-to-buffer::
* insert-buffer::
* beginning-of-buffer::
* Second Buffer Related Review::
* optional Exercise::
@end menu

@node copy-to-buffer, insert-buffer, More Complex, More Complex

buffer that might be @dfn{read-only} and the important distinction
between the name of an object and the object actually referred to.

@menu
* insert-buffer code::
* insert-buffer interactive::
* insert-buffer body::
* if & or::
* Insert or::
* Insert let::
* New insert-buffer::
@end menu

@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
@ifnottex

In @code{insert-buffer}, the argument to the @code{interactive}
declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
buffer:@: }.

@menu
* Read-only buffer::
* b for interactive::
@end menu

@node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
@comment  node-name,  next,  previous,  up
@unnumberedsubsubsec A Read-only Buffer

The @code{beginning-of-buffer} function can be called with or without an
argument.  The use of the argument is optional.

@menu
* Optional Arguments::
* beginning-of-buffer opt arg::
* beginning-of-buffer complete::
@end menu

@node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer
@subsection Optional Arguments

on a specific part of a buffer, and work without accidentally changing
other parts.  Narrowing is normally disabled since it can confuse
novices.

@menu
* Narrowing advantages::
* save-restriction::
* what-line::
* narrow Exercise::
@end menu

@node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening
@ifnottex

In the walk through of the @code{copy-region-as-kill} function, we
will see @code{cons} as well as two variants on @code{cdr},
namely, @code{setcdr} and @code{nthcdr}.  (@xref{copy-region-as-kill}.)

@menu
* Strange Names::
* car & cdr::
* cons::
* nthcdr::
* nth::
* setcar::
* setcdr::
* cons Exercise::
@end menu

@node Strange Names, car & cdr, car cdr & cons, car cdr & cons
@ifnottex

Like @code{car} and @code{cdr}, @code{cons} is non-destructive.

@menu
* Build a list::
* length::
@end menu

@node Build a list, length, cons, cons
@ifnottex
@unnumberedsubsec Build a list

put it into storage from which it can be brought back.  I have often
been tempted to replace globally all occurrences of `kill' in the Emacs
sources with `clip' and all occurrences of `killed' with `clipped'.)

@menu
* Storing Text::
* zap-to-char::
* kill-region::
* copy-region-as-kill::
* Digression into C::
* defvar::
* cons & search-fwd Review::
* search Exercises::
@end menu

@node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text

that of error handling.  We will walk through the function.

But first, let us look at the interactive @code{zap-to-char} function.

@menu
* Complete zap-to-char::
* zap-to-char interactive::
* zap-to-char body::
* search-forward::
* progn::
* Summing up zap-to-char::
@end menu

@node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
@ifnottex
@unnumberedsubsec The Complete @code{zap-to-char} Implementation

the first argument does nothing.  The second argument contains the
code that does the work when all goes well.  The third argument
contains the code that is called in the event of an error.

@menu
* Complete kill-region::
* condition-case::
* Lisp macro::
@end menu

@node Complete kill-region, condition-case, kill-region, kill-region
@ifnottex

get it all, from both this and the previous operation.  On the other
hand, if some other command precedes the @code{copy-region-as-kill},
the function copies the text into a separate entry in the kill ring.

@menu
* Complete copy-region-as-kill::
* copy-region-as-kill body::
@end menu

@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
@ifnottex
@unnumberedsubsec The complete @code{copy-region-as-kill} function definition

A pointer itself is quite simply the electronic address of what is
pointed to.  Hence, a list is kept as a series of electronic addresses.

@menu
* Lists diagrammed::
* Symbols as Chest::
* List Exercise::
@end menu

@node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation
@ifnottex

@xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
list is handled as a ring.)

@menu
* Kill Ring Overview::
* kill-ring-yank-pointer::
* yank nthcdr Exercises::
@end menu

@node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
@comment  node-name,  next,  previous,  up
@section Kill Ring Overview

increase the values of @code{max-specpdl-size} and
@code{max-lisp-eval-depth}.  In my @file{.emacs} file, I set them to
15 and 30 times their default value.}.

@menu
* while::
* dolist dotimes::
* Recursion::
* Looping exercise::
@end menu

@node while, dolist dotimes, Loops & Recursion, Loops & Recursion
@comment  node-name,  next,  previous,  up

  @var{body}@dots{})
@end group
@end smallexample

@menu
* Looping with while::
* Loop Example::
* print-elements-of-list::
* Incrementing Loop::
* Incrementing Loop Details::
* Decrementing Loop::
@end menu

@node Looping with while, Loop Example, while, while
@ifnottex
@unnumberedsubsec Looping with @code{while}

@noindent
Note that you need to set the initial value of @code{count}; usually it
is set to 1.

@menu
* Incrementing Example::
* Inc Example parts::
* Inc Example altogether::
@end menu

@node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details
@unnumberedsubsubsec  Example with incrementing counter

  (setq counter (1- counter)))          ; @r{decrementer}
@end group
@end smallexample

@menu
* Decrementing Example::
* Dec Example parts::
* Dec Example altogether::
@end menu

@node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
@unnumberedsubsubsec Example with decrementing counter

Eventually, if the program is written correctly, the `slightly
different arguments' will become sufficiently different from the first
arguments that the final instance will stop.

@menu
* Building Robots::
* Recursive Definition Parts::
* Recursion with list::
* Recursive triangle function::
* Recursion with cond::
* Recursive Patterns::
* No Deferment::
* No deferment solution::
@end menu

@node Building Robots, Recursive Definition Parts, Recursion, Recursion
@comment  node-name,  next,  previous,  up

@code{forward-paragraph} function is described in the last section of
this chapter.  @code{forward-paragraph} is a complex function that
introduces several new features.

@menu
* sentence-end::
* re-search-forward::
* forward-sentence::
* forward-paragraph::
* etags::
* Regexp Review::
* re-search Exercises::
@end menu

@node sentence-end, re-search-forward, Regexp Search, Regexp Search

and, optionally, over more than one sentence.  The function is usually
bound to the key command @kbd{M-e}.

@menu
* Complete forward-sentence::
* fwd-sentence while loops::
* fwd-sentence re-search::
@end menu

@node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
@ifnottex
@unnumberedsubsec Complete @code{forward-sentence} function definition

Moreover, it is sometimes practical to ignore a fill prefix that
exists, especially when blank lines separate paragraphs.
This is an added complication.

@menu
* forward-paragraph in brief::
* fwd-para let::
* fwd-para while::
@end menu

@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
@ifnottex
@unnumberedsubsec Shortened @code{forward-paragraph} function definition

the use of regular expression searches through the construction of
word count commands using @code{while} loops and recursion.

@menu
* Why Count Words::
* count-words-region::
* recursive-count-words::
* Counting Exercise::
@end menu

@node Why Count Words, count-words-region, Counting Words, Counting Words
@ifnottex

word, then the third word, and so on, until you reach the end of the
region.  This means that word counting is ideally suited to recursion
or to a @code{while} loop.

@menu
* Design count-words-region::
* Whitespace Bug::
@end menu

@node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
@ifnottex
@unnumberedsubsec Designing @code{count-words-region}

and so on.  I have often been curious how long a typical function is,
and this will tell.

@menu
* Divide and Conquer::
* Words and Symbols::
* Syntax::
* count-words-in-defun::
* Several defuns::
* Find a File::
* lengths-list-file::
* Several files::
* Several files recursively::
* Prepare the data::
@end menu

@node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
@ifnottex
@unnumberedsec Divide and Conquer

Working on each of a list of files is a repetitious act, so we can use
either a @code{while} loop or recursion.

@menu
* lengths-list-many-files::
* append::
@end menu

@node lengths-list-many-files, append, Several files, Several files
@ifnottex
@unnumberedsubsec Determine the lengths of @code{defuns}

of defuns within each range of lengths, and produce a list of those
numbers.

@menu
* Data for Display in Detail::
* Sorting::
* Files List::
* Counting function definitions::
@end menu

@node Data for Display in Detail, Sorting, Prepare the data, Prepare the data
@ifnottex

After scouting the terrain, we will feel more confident and enhance
the function to label the axes automatically.

@menu
* Columns of a graph::
* graph-body-print::
* recursive-graph-body-print::
* Printed Axes::
* Line Graph Exercise::
@end menu

GNU Emacs is mostly written in Emacs Lisp; this means that by writing
expressions in Emacs Lisp you can change or extend Emacs.

@menu
* Default Configuration::
* Site-wide Init::
* defcustom::
* Beginning a .emacs File::
* Text and Auto-fill::
* Mail Aliases::
* Indent Tabs Mode::
* Keybindings::
* Keymaps::
* Loading Files::
* Autoload::
* Simple Extension::
* X11 Colors::
* Miscellaneous::
* Mode Line::
@end menu

@node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
@ifnottex
@unnumberedsec Emacs' Default Configuration

Both debuggers are described extensively in @ref{Debugging, ,
Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
In this chapter, I will walk through a short example of each.

@menu
* debug::
* debug-on-entry::
* debug-on-quit::
* edebug::
* Debugging Exercises::
@end menu

@node debug, debug-on-entry, Debugging, Debugging
@section @code{debug}

consider the workings of the kill ring.

@menu
* What the Kill Ring Does::
* current-kill::
* yank::
* yank-pop::
* ring file::
@end menu

@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring
@ifnottex

This function takes two arguments, one of which is optional.  It has a
documentation string.  It is @emph{not} interactive.

@menu
* Body of current-kill::
* Digression concerning error::
* Determining the Element::
@end menu

@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill
@ifnottex

for printing and labelling vertical and horizontal axes, along with the
body itself.

@menu
* Labelled Example::
* print-graph Varlist::
* print-Y-axis::
* print-X-axis::
* Print Whole Graph::
@end menu

@node Labelled Example, print-graph Varlist, Full Graph, Full Graph
@ifnottex
@unnumberedsec Labelled Example Graph

The function should be passed the height of the graph, and then should
construct and insert the appropriate numbers and marks.

@menu
* print-Y-axis in Detail::
* Height of label::
* Compute a Remainder::
* Y Axis Element::
* Y-axis-column::
* print-Y-axis Penultimate::
@end menu

@node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis
@ifnottex
@unnumberedsubsec The @code{print-Y-axis} Function in Detail

measured in units of @code{symbol-width}, since you may want to change
the width of the symbols that you are using to print the body of the
graph without changing the ways the graph is labelled.

@menu
* Similarities differences::
* X Axis Tic Marks::
@end menu

@node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
@ifnottex
@unnumberedsubsec Similarities and differences

    (print-X-axis @dots{} )))
@end group
@end smallexample

@menu
* The final version::
* Test print-graph::
* Graphing words in defuns::
* lambda::
* mapcar::
* Another Bug::
* Final printed graph::
@end menu

@node The final version, Test print-graph, Print Whole Graph, Print Whole Graph
@ifnottex
@unnumberedsubsec Changes for the Final Version

73854:55e5dc416293

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

@code{let}

* Prevent confusion::
* Parts of let Expression::

* Lisp macro::

@code{copy-region-as-kill}

* Complete copy-region-as-kill::  The complete function definition.
* copy-region-as-kill body::      The body of @code{copy-region-as-kill}.

The Body of @code{copy-region-as-kill}

* last-command & this-command::
* kill-append function::

and phases of the moon, simplify polynomials, debug code, manage
files, read letters, write books---all these activities are kinds of
editing in the most general sense of the word.)

@menu
* 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::
@end menu

@node Why, On Reading this Text, Preface, Preface
@ifnottex

mark is an abbreviation for the function @code{quote}; you need not
think about functions now; functions are defined in @ref{Making
Errors, , Generate an Error Message}.}  Lists are the basis of Lisp.

@menu
* 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::
@end menu

@node Lisp Lists, Run a Program, List Processing, List Processing
@comment  node-name,  next,  previous,  up

separated from each other by whitespace and surrounded by parentheses,
like flowers in a field with a stone wall around them.
@cindex Flowers in a field

@menu
* 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.
@end menu

@node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
@ifnottex
@unnumberedsubsec Numbers, Lists inside of Lists

write Lisp programs, you need to know how to write function definitions
and attach them to names, and how to do this without confusing either
yourself or the computer.

@menu
* Complications::               Variables, Special forms, Lists within.
* Byte Compiling::              Specially processing code for speed.
@end menu

@node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
@ifnottex
@unnumberedsubsec Complications

The word comes from its use in everyday language, `to ascertain the
value or amount of; to appraise', according to @cite{Webster's New
Collegiate Dictionary}.

@menu
* How the Interpreter Acts::    Returns and Side Effects...
* Evaluating Inner Lists::      Lists within lists...
@end menu

@node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation
@ifnottex
@unnumberedsubsec How the Lisp Interpreter Acts

changed without affecting the contents of the drawer holding the
function definition, and vice-verse.

@menu
* 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.
@end menu

@node fill-column Example, Void Function, Variables, Variables
@ifnottex
@unnumberedsubsec @code{fill-column}, an Example Variable

(Note here that the English word has two different definitions attached
to it at the same time.  By contrast, in Emacs Lisp, a symbol cannot
have two different function definitions at the same time.)}

@menu
* 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.
@end menu

@node Data types, Args as Variable or List, Arguments, Arguments
@comment  node-name,  next,  previous,  up
@subsection Arguments' Data Types

The following sections not only describe how @code{set} and @code{setq}
work but also illustrate how arguments are passed.

@menu
* Using set::                  Setting values.
* Using setq::                 Setting a quoted value.
* Counting::                   Using @code{setq} to count.
@end menu

@node Using set, Using setq, set & setq, set & setq
@comment  node-name,  next,  previous,  up
@subsection Using @code{set}

will start with those.  In this section, we will evaluate a few of
these.  In another section, we will study the code of several other
buffer-related functions, to see how they were written.

@menu
* How to Evaluate::            Typing editing commands or @kbd{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::
@end menu

@node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation
@ifnottex

(although, properly speaking, the definition is the function and the
symbol refers to it.)

@menu
* Primitive Functions::
* defun::                        The @code{defun} special form.
* Install::                      Install a function definition.
* Interactive::                  Making a function interactive.
* Interactive Options::          Different options for @code{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::
@end menu

@node Primitive Functions, defun, Writing Defuns, Writing Defuns

Emacs.  To reload code automatically whenever you start Emacs, see
@ref{Permanent Installation, , Installing Code Permanently}.)

@menu
* Effect of installation::
* Change a defun::              How to change a function definition.
@end menu

@node Effect of installation, Change a defun, Install, Install
@ifnottex
@unnumberedsubsec The effect of installation

effects, such as moving forward by a word or line, and not for the
value returned.  If the returned value were displayed in the echo area
each time you typed a key, it would be very distracting.

@menu
* Interactive multiply-by-seven::  An overview.
* multiply-by-seven in detail::    The interactive version.
@end menu

@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
@ifnottex
@unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview

expression is not evaluated.  For example, you might make a decision
such as, ``if it is warm and sunny, then go to the beach!''

@menu
* if in more detail::
* type-of-animal in detail::    An example of an @code{if} expression.
@end menu

@node if in more detail, type-of-animal in detail, if, if
@ifnottex
@unnumberedsubsec @code{if} in more detail

returned is a number such as 47, a string such as @code{"hello"}, or a
symbol (other than @code{nil}) such as @code{flowers}, or a list (so
long as it is not empty), or even a buffer!

@menu
* nil explained::               @code{nil} has two meanings.
@end menu

@node nil explained,  , Truth & Falsehood, Truth & Falsehood
@ifnottex
@unnumberedsubsec An explanation of @code{nil}

their previous positions if their locations were changed.  Its primary
purpose is to keep the user from being surprised and disturbed by
unexpected movement of point or mark.

@menu
* Point and mark::              A review of various locations.
* Template for save-excursion::
@end menu

@node Point and mark, Template for save-excursion, save-excursion, save-excursion
@ifnottex

show the actual code used in GNU Emacs.  You can learn a great deal from
these definitions.  The functions described here are all related to
buffers.  Later, we will study other functions.

@menu
* Finding More::                How to find more information.
* simplified-beginning-of-buffer::  Shows @code{goto-char},
                                @code{point-min}, and @code{push-mark}.
* mark-whole-buffer::           Almost the same as @code{beginning-of-buffer}.
* append-to-buffer::            Uses @code{save-excursion} and
                                @code{insert-buffer-substring}.
* Buffer Related Review::       Review.
* Buffer Exercises::
@end menu

@node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through
@section Finding More Information

a mark at the end of the buffer.  It is generally bound to @kbd{C-x
h}.

@menu
* mark-whole-buffer overview::
* Body of mark-whole-buffer::   Only three lines of code.
@end menu

@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
@ifnottex
@unnumberedsubsec An overview of @code{mark-whole-buffer}

(that is, the part of the buffer between point and mark) from the
current buffer to a specified buffer.

@menu
* append-to-buffer overview::
* append interactive::          A two part interactive expression.
* append-to-buffer body::       Incorporates a @code{let} expression.
* append save-excursion::       How the @code{save-excursion} works.
@end menu

@node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
@ifnottex
@unnumberedsubsec An Overview of @code{append-to-buffer}

use of an asterisk in an @code{interactive} expression, use of
@code{or}, and the important distinction between a name and the object
to which the name refers.

@menu
* copy-to-buffer::              With @code{set-buffer}, @code{get-buffer-create}.
* insert-buffer::               Read-only, and with @code{or}.
* beginning-of-buffer::         Shows @code{goto-char},
                                @code{point-min}, and @code{push-mark}.
* Second Buffer Related Review::
* optional Exercise::
@end menu

@node copy-to-buffer, insert-buffer, More Complex, More Complex

buffer that might be @dfn{read-only} and the important distinction
between the name of an object and the object actually referred to.

@menu
* insert-buffer code::
* insert-buffer interactive::   When you can read, but not write.
* insert-buffer body::          The body has an @code{or} and a @code{let}.
* if & or::                     Using an @code{if} instead of an @code{or}.
* Insert or::                   How the @code{or} expression works.
* Insert let::                  Two @code{save-excursion} expressions.
* New insert-buffer::
@end menu

@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
@ifnottex

In @code{insert-buffer}, the argument to the @code{interactive}
declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert
buffer:@: }.

@menu
* Read-only buffer::            When a buffer cannot be modified.
* b for interactive::           An existing buffer or else its name.
@end menu

@node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
@comment  node-name,  next,  previous,  up
@unnumberedsubsubsec A Read-only Buffer

The @code{beginning-of-buffer} function can be called with or without an
argument.  The use of the argument is optional.

@menu
* Optional Arguments::
* beginning-of-buffer opt arg::  Example with optional argument.
* beginning-of-buffer complete::
@end menu

@node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer
@subsection Optional Arguments

on a specific part of a buffer, and work without accidentally changing
other parts.  Narrowing is normally disabled since it can confuse
novices.

@menu
* Narrowing advantages::        The advantages of narrowing
* save-restriction::            The @code{save-restriction} special form.
* what-line::                   The number of the line that point is on.
* narrow Exercise::
@end menu

@node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening
@ifnottex

In the walk through of the @code{copy-region-as-kill} function, we
will see @code{cons} as well as two variants on @code{cdr},
namely, @code{setcdr} and @code{nthcdr}.  (@xref{copy-region-as-kill}.)

@menu
* Strange Names::               An historical aside: why the strange names?
* car & cdr::                   Functions for extracting part of a list.
* cons::                        Constructing a list.
* nthcdr::                      Calling @code{cdr} repeatedly.
* nth::
* setcar::                      Changing the first element of a list.
* setcdr::                      Changing the rest of a list.
* cons Exercise::
@end menu

@node Strange Names, car & cdr, car cdr & cons, car cdr & cons
@ifnottex

Like @code{car} and @code{cdr}, @code{cons} is non-destructive.

@menu
* Build a list::
* length::                      How to find the length of a list.
@end menu

@node Build a list, length, cons, cons
@ifnottex
@unnumberedsubsec Build a list

put it into storage from which it can be brought back.  I have often
been tempted to replace globally all occurrences of `kill' in the Emacs
sources with `clip' and all occurrences of `killed' with `clipped'.)

@menu
* 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::
@end menu

@node Storing Text, zap-to-char, Cutting & Storing Text, Cutting & Storing Text

that of error handling.  We will walk through the function.

But first, let us look at the interactive @code{zap-to-char} function.

@menu
* 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 @code{progn} special form.
* Summing up zap-to-char::      Using @code{point} and @code{search-forward}.
@end menu

@node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
@ifnottex
@unnumberedsubsec The Complete @code{zap-to-char} Implementation

the first argument does nothing.  The second argument contains the
code that does the work when all goes well.  The third argument
contains the code that is called in the event of an error.

@menu
* Complete kill-region::        The function definition.
* condition-case::              Dealing with a problem.
* Lisp macro::
@end menu

@node Complete kill-region, condition-case, kill-region, kill-region
@ifnottex

get it all, from both this and the previous operation.  On the other
hand, if some other command precedes the @code{copy-region-as-kill},
the function copies the text into a separate entry in the kill ring.

@menu
* Complete copy-region-as-kill::  The complete function definition.
* copy-region-as-kill body::      The body of @code{copy-region-as-kill}.
@end menu

@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
@ifnottex
@unnumberedsubsec The complete @code{copy-region-as-kill} function definition

A pointer itself is quite simply the electronic address of what is
pointed to.  Hence, a list is kept as a series of electronic addresses.

@menu
* Lists diagrammed::
* Symbols as Chest::            Exploring a powerful metaphor.
* List Exercise::
@end menu

@node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation
@ifnottex

@xref{Kill Ring, , Handling the Kill Ring}, for the details of how the
list is handled as a ring.)

@menu
* Kill Ring Overview::
* kill-ring-yank-pointer::      The kill ring is a list.
* yank nthcdr Exercises::       The @code{kill-ring-yank-pointer} variable.
@end menu

@node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking
@comment  node-name,  next,  previous,  up
@section Kill Ring Overview

increase the values of @code{max-specpdl-size} and
@code{max-lisp-eval-depth}.  In my @file{.emacs} file, I set them to
15 and 30 times their default value.}.

@menu
* while::                       Causing a stretch of code to repeat.
* dolist dotimes::
* Recursion::                   Causing a function to call itself.
* Looping exercise::
@end menu

@node while, dolist dotimes, Loops & Recursion, Loops & Recursion
@comment  node-name,  next,  previous,  up

  @var{body}@dots{})
@end group
@end smallexample

@menu
* Looping with while::          Repeat so long as test returns true.
* Loop Example::                A @code{while} loop that uses a list.
* print-elements-of-list::      Uses @code{while}, @code{car}, @code{cdr}.
* Incrementing Loop::           A loop with an incrementing counter.
* Incrementing Loop Details::
* Decrementing Loop::           A loop with a decrementing counter.
@end menu

@node Looping with while, Loop Example, while, while
@ifnottex
@unnumberedsubsec Looping with @code{while}

@noindent
Note that you need to set the initial value of @code{count}; usually it
is set to 1.

@menu
* Incrementing Example::        Counting pebbles in a triangle.
* Inc Example parts::           The parts of the function definition.
* Inc Example altogether::      Putting the function definition together.
@end menu

@node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details
@unnumberedsubsubsec  Example with incrementing counter

  (setq counter (1- counter)))          ; @r{decrementer}
@end group
@end smallexample

@menu
* Decrementing Example::        More pebbles on the beach.
* Dec Example parts::           The parts of the function definition.
* Dec Example altogether::      Putting the function definition together.
@end menu

@node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
@unnumberedsubsubsec Example with decrementing counter

Eventually, if the program is written correctly, the `slightly
different arguments' will become sufficiently different from the first
arguments that the final instance will stop.

@menu
* 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::
@end menu

@node Building Robots, Recursive Definition Parts, Recursion, Recursion
@comment  node-name,  next,  previous,  up

@code{forward-paragraph} function is described in the last section of
this chapter.  @code{forward-paragraph} is a complex function that
introduces several new features.

@menu
* sentence-end::                The regular expression for @code{sentence-end}.
* re-search-forward::           Very similar to @code{search-forward}.
* forward-sentence::            A straightforward example of regexp search.
* forward-paragraph::           A somewhat complex example.
* etags::                       How to create your own @file{TAGS} table.
* Regexp Review::
* re-search Exercises::
@end menu

@node sentence-end, re-search-forward, Regexp Search, Regexp Search

and, optionally, over more than one sentence.  The function is usually
bound to the key command @kbd{M-e}.

@menu
* Complete forward-sentence::
* fwd-sentence while loops::    Two @code{while} loops.
* fwd-sentence re-search::      A regular expression search.
@end menu

@node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
@ifnottex
@unnumberedsubsec Complete @code{forward-sentence} function definition

Moreover, it is sometimes practical to ignore a fill prefix that
exists, especially when blank lines separate paragraphs.
This is an added complication.

@menu
* forward-paragraph in brief::  Key parts of the function definition.
* fwd-para let::                The @code{let*} expression.
* fwd-para while::              The forward motion @code{while} loop.
@end menu

@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
@ifnottex
@unnumberedsubsec Shortened @code{forward-paragraph} function definition

the use of regular expression searches through the construction of
word count commands using @code{while} loops and recursion.

@menu
* 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::
@end menu

@node Why Count Words, count-words-region, Counting Words, Counting Words
@ifnottex

word, then the third word, and so on, until you reach the end of the
region.  This means that word counting is ideally suited to recursion
or to a @code{while} loop.

@menu
* Design count-words-region::   The definition using a @code{while} loop.
* Whitespace Bug::              The Whitespace Bug in @code{count-words-region}.
@end menu

@node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
@ifnottex
@unnumberedsubsec Designing @code{count-words-region}

and so on.  I have often been curious how long a typical function is,
and this will tell.

@menu
* Divide and Conquer::
* Words and Symbols::           What to count?
* Syntax::                      What constitutes a word or symbol?
* count-words-in-defun::        Very like @code{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.
@end menu

@node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
@ifnottex
@unnumberedsec Divide and Conquer

Working on each of a list of files is a repetitious act, so we can use
either a @code{while} loop or recursion.

@menu
* lengths-list-many-files::     Return a list of the lengths of defuns.
* append::                      Attach one list to another.
@end menu

@node lengths-list-many-files, append, Several files, Several files
@ifnottex
@unnumberedsubsec Determine the lengths of @code{defuns}

of defuns within each range of lengths, and produce a list of those
numbers.

@menu
* Data for Display in Detail::
* Sorting::                     Sorting lists.
* Files List::                  Making a list of files.
* Counting function definitions::
@end menu

@node Data for Display in Detail, Sorting, Prepare the data, Prepare the data
@ifnottex

After scouting the terrain, we will feel more confident and enhance
the function to label the axes automatically.

@menu
* Columns of a graph::
* graph-body-print::            How to print the body of a graph.
* recursive-graph-body-print::
* Printed Axes::
* Line Graph Exercise::
@end menu

GNU Emacs is mostly written in Emacs Lisp; this means that by writing
expressions in Emacs Lisp you can change or extend Emacs.

@menu
* 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 @code{.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.
@end menu

@node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
@ifnottex
@unnumberedsec Emacs' Default Configuration

Both debuggers are described extensively in @ref{Debugging, ,
Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}.
In this chapter, I will walk through a short example of each.

@menu
* 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 @kbd{C-g}.
* edebug::                      How to use Edebug, a source level debugger.
* Debugging Exercises::
@end menu

@node debug, debug-on-entry, Debugging, Debugging
@section @code{debug}

consider the workings of the kill ring.

@menu
* What the Kill Ring Does::
* current-kill::
* yank::                        Paste a copy of a clipped element.
* yank-pop::                    Insert element pointed to.
* ring file::
@end menu

@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring
@ifnottex

This function takes two arguments, one of which is optional.  It has a
documentation string.  It is @emph{not} interactive.

@menu
* Body of current-kill::
* Digression concerning error::  How to mislead humans, but not computers.
* Determining the Element::
@end menu

@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill
@ifnottex

for printing and labelling vertical and horizontal axes, along with the
body itself.

@menu
* Labelled Example::
* print-graph Varlist::         @code{let} expression in @code{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.
@end menu

@node Labelled Example, print-graph Varlist, Full Graph, Full Graph
@ifnottex
@unnumberedsec Labelled Example Graph

The function should be passed the height of the graph, and then should
construct and insert the appropriate numbers and marks.

@menu
* 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.
@end menu

@node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis
@ifnottex
@unnumberedsubsec The @code{print-Y-axis} Function in Detail

measured in units of @code{symbol-width}, since you may want to change
the width of the symbols that you are using to print the body of the
graph without changing the ways the graph is labelled.

@menu
* Similarities differences::    Much like @code{print-Y-axis}, but not exactly.
* X Axis Tic Marks::            Create tic marks for the horizontal axis.
@end menu

@node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
@ifnottex
@unnumberedsubsec Similarities and differences

    (print-X-axis @dots{} )))
@end group
@end smallexample

@menu
* 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 @dots{} most insidious.
* Final printed graph::         The graph itself!
@end menu

@node The final version, Test print-graph, Print Whole Graph, Print Whole Graph
@ifnottex
@unnumberedsubsec Changes for the Final Version