elispelem.texi

\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename elispelem.info
@settitle Emacs Lisp Elements
@documentencoding UTF-8
@documentlanguage en
@set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage}
@set MAINTAINER Protesilaos Stavrou
@set MAINTAINEREMAIL @email{info@protesilaos.com}
@set MAINTAINERCONTACT @uref{mailto:info@protesilaos.com,contact the maintainer}
@c %**end of header

@copying
Copyright (C) 2025 Protesilaos Stavrou

@quotation
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; with no
Invariant Sections, 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.”

@end quotation
@end copying

@dircategory Emacs misc features
@direntry
* Emacs Lisp Elements: (elispelem). A big picture view of Emacs Lisp.
@end direntry

@finalout
@titlepage
@title Emacs Lisp Elements
@author Protesilaos Stavrou (@email{info@@protesilaos.com})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnottex
@node Top
@top Emacs Lisp Elements

@insertcopying

This book, written by Protesilaos Stavrou, also known as ``Prot'',
provides a big picture view of the Emacs Lisp programming language.

The information furnished herein corresponds to stable version
2.0.0, released on 2025-12-10.

@itemize
@item
Official page: @uref{https://protesilaos.com/emacs/emacs-lisp-elements}
@item
Git repository: @uref{https://github.com/protesilaos/emacs-lisp-elements}
@end itemize

@end ifnottex

@menu
* Getting started with Emacs Lisp::
* Basics of how Lisp works::
* Evaluate Emacs Lisp::
* Introspecting Emacs::
* Side effect and return value::
* Symbols, balanced expressions, and quoting: Symbols balanced expressions and quoting. 
* Buffers as data::
* Text has its own properties::
* Add metadata to symbols::
* What are major and minor modes::
* Hooks and the advice mechanism::
* Evaluate some elements inside of a list::
* Evaluation inside of a macro or special form::
* Mapping over a list of elements::
* The match data of the last search::
* Switching to another buffer, window, or narrowed state: Switching to another buffer window or narrowed state. 
* Basic control flow with @code{if}, @code{cond}, and others: Basic control flow with @code{if} @code{cond} and others. 
* Control flow with @code{if-let*} and friends::
* Autoloading symbols::
* Pattern match with @code{pcase} and related::
* Run some code or fall back to some other code::
* When to use a named function or a lambda function::
* Make your interactive function also work from Lisp calls::
* Emacs as a computing environment::
* Acknowledgements::
* GNU Free Documentation License::
* Indices::

@detailmenu
--- The Detailed Node Listing ---

Indices

* Function index::
* Variable index::
* Concept index::

@end detailmenu
@end menu

@node Getting started with Emacs Lisp
@chapter Getting started with Emacs Lisp

The purpose of this book is to provide you with a big picture view of
Emacs Lisp, also known as ``Elisp'' (@ref{Basics of how Lisp works}). This is
the programming language you use to extend Emacs. Emacs is a
programmable text editor: it interprets Emacs Lisp and behaves
accordingly. You can use Emacs without ever writing a single line of
code: it already has lots of features. Though you can, at any time,
program it to do exactly what you want by evaluating some Elisp that
either you wrote yourself or got from another person, such as in the
form of a package.

Programming your own text editor is both useful and fun. You can, for
example, streamline a sequence of actions you keep doing by combining
them into a single command that you then assign to a key binding: type
the key and---bam!---perform all the intermediate tasks in one go.
This makes you more efficient while it turns the editor into a
comfortable working environment.

The fun part is how you go about writing the code. There are no duties
you have to conform with. None! You program for the sake of
programming. It is a recreational activity that expands your horizons.
Plus, you cultivate your Elisp skills, which can prove helpful in the
future, should you choose to modify some behaviour of Emacs in a more
refined way.

Tinkering with Emacs is part of the experience. It teaches you to be
unapologetically opinionated about how your editor works. The key is
to know enough Elisp so that you do not spend too much time getting
frustrated because something trivial does not work. I am writing this
as a tinkerer myself with no background in computer science or
neighbouring studies: I learnt Emacs Lisp through trial and error by
playing around with the editor. My nominal goal was to improve certain
micro-motions I was repeating over and over. I sought efficiency only
to discover something much more profound and rewarding. Learning to
extend my editor has been a fulfilling experience and I am more
productive as a result. Emacs does what I want it to do and I am happy
with it.

Each chapter herein is generally short and to-the-point. Some are more
friendly to beginners while others dive deeper into advanced topics.
The progression from one chapter to the other should be linear, such
that you have enough information to proceed. There are links between
the chapters, exactly how a reference manual is supposed to be done.
You may then go back and forth to find what you need.

The text you find here is a combination of prose and code. The latter
may be actual Elisp or pseudo-code which captures the underlying
pattern. I encourage you to read this book either inside of Emacs or
with Emacs readily available. This way, you can play around with the
functions I give you, to further appreciate their nuances. The code I
write here is simple, trivial even. I want you to make sense of the
given principle and to not distract you with irrelevant complexity.
The goal is to show you how the pieces are put together. It is then up
to you to write elaborate programs.

The ``big picture view'' approach I am adopting is about covering the
concepts that I encounter frequently while working with Emacs Lisp.
This book is no substitute for the Emacs Lisp Reference Manual and
should by no means be treated as the source of truth for any of the
Elisp forms I comment on.

Good luck and enjoy!

@node Basics of how Lisp works
@chapter Basics of how Lisp works

Emacs Lisp is a programming language whose basic form has a simple
syntax: there are fundamental objects and lists of them. For example,
we have numbers and strings of characters inside double quotes (also
known as ``strings''). These are some of the fundamental objects.
Symbols are another fundamental object: they are made up of
alphanumeric characters and/or symbols. They will often look like
ordinary words, though they are not inside a pair of double quotes,
otherwise they would be strings. A symbol is commonly used as the
proper name of some variable or function: they ``symbolise'' something
other than themselves. Though symbols can be self-referential, such
that they symbolise themselves. For example, the value of @code{nil} is
@code{nil}.

Every computation is expressed as a list. This is a list of
fundamental objects or, in other words, one or more fundamental
objects inside of a pair of parentheses. The first element of the list
is the symbol of the function. The remaining elements, if any, are the
arguments passed to the function. ``Arguments'' here means that they are
the exact values that correspond to the specified parameters of the
function. A function has ``parameters'', meaning that it expects certain
inputs with which to carry out its work. Functions can define zero or
more parameters and internally decide how to handle them. Some
parameters can be mandatory and others optional. The number of
arguments must match that of the mandatory parameters, otherwise we
get an error.

Let us take a look at a basic function call. For example, this is how
we print a message, which we can then find in the @samp{*Messages*} buffer:

@lisp
(message "Hello world, this is my message to you!")
;; => "Hello world, this is my message to you!"
@end lisp

@findex message
Look at the syntax we have used. Here @code{message} is a symbol. It is the
first element of the list, therefore @code{message} is interpreted as the
proper name of a function. The second element of the list is a string
which, in this case, is understood as the first argument passed to the
@code{message} function. The entire expression is a list, hence the
parentheses around it. This expression is a function call: it performs
a computation.

When we use the term ``evaluate'' and derivatives, we are effectively
describing how we ask the computer to perform some computation for us,
such as to get the value of a variable or call a function for the work
it does and get back whatever it returns. In the above example, I
wrote the list and then evaluated it with @kbd{C-x C-e}
(@code{eval-last-sexp}). The text on the second line is my way of
representing the return value of this computation (@ref{Side effect and return value}).

What you just read explains most of Emacs Lisp. Though it can still be
difficult to understand a program because of how all the parentheses
line up. It can be hard to figure out where something starts and where
it ends when you have something like this:

@lisp
(upcase (message "Hello world, the number is %s" (+ 1 1 1)))
;; => "HELLO WORLD, THE NUMBER IS 3"
@end lisp

What we have above are three function calls inside of each other. If
you look at the closing three parentheses, you may panic as they are
already more than what you are used to. Relax! Elisp is cool because
you learn it by keeping calm. Let me read it to you from left to
right. Put the previous code block on one side and the following
explanation on the other, so that you can follow along more easily.

@itemize
@item
I am asked to evaluate this piece of Emacs Lisp.

@item
I have found a parenthesis, which means that this is a list that
stands for a function call.

@item
Let me check the first element of this list.

@item
I found the symbol @code{upcase}. Fine, I will use this.

@item
I know that @code{upcase} will work on a string to make all its letters
upper case (@ref{Introspecting Emacs}).

@item
Now I will check the next element of this function call. It has to
be the argument passed to @code{upcase}.

@item
The argument I have found starts with a parenthesis. This means that
it is not a fundamental object, but a function call in its own
right.

@item
Before I do anything with @code{upcase}, I have to evaluate this function
call.

@item
I found @code{message}, so I will use that. Time to check the next
element of this list.

@item
I found the string. Good! It has a @samp{%s} placeholder, which means
that there is another argument whose value will go where @samp{%s} now
is.

@item
Here is another parenthesis. We have a third function call.

@item
The symbol I found here is @samp{+}. This is a valid name for a function.
I will check what the arguments are.

@item
I checked the arguments. They are all numbers. So I will apply @samp{+}
to them.

@item
I got the result of this function call, which is the number @samp{3}. Now
I can go back to @code{message} with @samp{3} as its second argument (the
first argument is that string I found which had the @samp{%s}
placeholder). I have all the values to make it work.

@item
Fine, I called @code{message}. It returns a string.

@item
With this string I got back, I am finally ready to run @code{upcase}.
@end itemize

What I just described is how Emacs Lisp code is expressed in its
simplest form. This is enough to write a program.

Though you will eventually want to control when something is
evaluated. To this end, Emacs Lisp has the concept of quoting, which
is done with the single quote @samp{'}. When the single quote is added as a
prefix to an object, then it means ``do not evaluate this right now and
take it as-is'' (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}). Using the
example from earlier with @code{message}:

@lisp
(message "I got this: %s" '(one two three))
;; => "I got this: (one two three)"
@end lisp

When Emacs reads this, it now finds only one function call, which
starts with the opening parenthesis for @code{message}. Then it reads one
list of data, which starts with the quoted list of symbols we have
there. By using the quote, we have successfully controlled where
evaluation should happen and where it should just take what we give it
without trying to interpret it.

Remember that when we use ``quote'' and related words in Emacs Lisp, we
are referring to this single quote, which is always a prefix. We do
not have pairs of single quotes around words or lists. No. It is only
a prefix for the object that follows.

If we did not have the single quote there, then we would effectively
be telling Emacs to evaluate @samp{(one two three)} as a function call
where @samp{one} would be the name of the function and the rest would be
its arguments. Unless you have a function whose proper name is @samp{one},
this will result in an error.

Earlier in this chapter I wrote ``every computation is expressed as a
list''. When you are writing Emacs Lisp, you may find that this does
not seem to be the case. For example, you can have a variable that you
evaluate on its own. Let us first declare a variable and give it a
string value:

@lisp
(defvar my-name "Protesilaos")
;; => my-name
@end lisp

We have now defined the symbol @code{my-name}, whose value is the string of
characters @samp{Protesilaos}. What you read here looks exactly like the
function calls we discussed in the previous examples. This is what
Lisp is all about. Now you may wonder what happens if we evaluate
@code{my-name} without doing a function call. Like this:

@lisp
my-name
;; => "Protesilaos"
@end lisp

@findex symbol-value
We get back the value. So is what I wrote earlier about everything
being a list incorrect? While you do not have any parentheses there,
it is helpful to think that Emacs makes things easier for you by
internally using the @code{symbol-value} function to interpret the symbol
@code{my-name}:

@lisp
(symbol-value 'my-name)
;; => "Protesilaos"
@end lisp

Note that the @code{symbol-value} here is important because it is the
function that takes the @code{my-name} symbol as an argument. But you
cannot evaluate a variable by writing it as a function call. This is
erroneous:

@lisp
(my-name)
;; => ERROR...
@end lisp

The error pertains to the fact that @code{my-name} is not a function: it is
a variable. Emacs has different namespaces for functions and
variables, meaning that you can have @code{my-name} as a symbol of a
function and as the symbol of a variable. Those are two separate
objects that we distinguish by how they are called. Let me show you:

@lisp
(defun my-name nil
  "I am the function that returns this string which includes Protesilaos")
;; => my-name
@end lisp

Again, you notice in the code above the idea of everything being a
list: @code{defun} is what we call to interpret all the other elements. We
now have defined @code{my-name} as a function. All this function does is
return a string, which in practice is not really useful: we could have
done this with a variable. Though what we are interested in at present
is to understand how we can have @code{my-name} be both a variable and a
function which we tell apart based on how they are used in context. It
is time to test our work:

@lisp
;; Here I am evaluating the variable.  When you evaluate a variable
;; directly, it is helpful to think that internally Emacs translates
;; your request to something like this: (symbol-value 'my-name)
my-name
;; => "Protesilaos"

;; Here I am evaluating the function.
(my-name)
;; => "I am the function that returns this string which includes Protesilaos"
@end lisp

What we have discussed thus far should help you make sense of all
these nested parentheses you will be dealing with when working with
Emacs Lisp. As you gain more experience, you will discover cases where
the syntax varies slightly (@ref{Basic control flow with @code{if} @code{cond} and others, , Basic control flow with @code{if}@comma{} @code{cond}@comma{} and others}).
This is because programmers want to economise on typing the same
things over and over, so they design ``special forms'' or ``Lisp macros''
that handle some things internally (@ref{Evaluation inside of a macro or special form}).
Specifically, you will encounter cases where quoting seems to be
different than what you have learnt here. Worry not. The principles are
the same. Those exceptions will ultimately be easy to reason about.

To avoid complex language such as ``a list of list of lists with quoted
lists and fundamental objects'' we use the term ``expression''. In
general, an expression is anything that Emacs can evaluate, be it a
list, list of lists, or symbol (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}).

@node Evaluate Emacs Lisp
@chapter Evaluate Emacs Lisp

@cindex The freedom and uniformity of Emacs
Everything you do in Emacs calls some function (@ref{Basics of how Lisp works}).
Click a button? That is a function. Write a few words? That is a
series of functions. Use the arrow keys to move around? Functions;
functions all the way down! Emacs evaluates Emacs Lisp code, reading
the return values while dealing with side effects (@ref{Side effect and return value}).

The fact that a computer program does computation is not peculiar to
Emacs. What is special is the combination of two qualities: (i) Emacs
is free software and (ii) it is extended in the same programming
language it is written in. Its inherent freedom means that every
single line of code that is evaluated is available to you for
potential inspection, modification, and redistribution (@ref{Introspecting Emacs}).

Nothing is hidden from you. While the uniform extensibility
through Emacs Lisp means that the code you are reading and the code
you are writing are treated the same way. You do not need to learn
different, typically incompatible, programming languages or
configuration formats to make Emacs perform the computations you
want. Emacs Lisp is all there is.

Freedom and uniformity of computation together give you maximum
control over your text editor (@ref{Emacs as a computing environment}). The
promise, then, is that learning to program in Elisp grants you access
to the full power of Emacs, such that you do exactly what you want
with it, given that you also understand some basic concepts such as
buffers and text manipulation (@ref{Buffers as data}).

@cindex Interactive functions are commands
You type a key on your keyboard and a character is written to the
current buffer at the point where the cursor is. This is a function
bound to a key. It actually is an interactive function, because you
are calling it via a key binding rather than through some other Emacs
Lisp program (the latter is also described as ``calling it from Lisp''
or ``Lisp call''). Interactive functions are known as ``commands''. They
are computations which we can invoke interactively on demand.

Though do not let the implementation detail of interactivity distract
you from the fact that every single action you perform in Emacs
involves the evaluation of Emacs Lisp. A command will typically rely
on the computations of other functions to do its work. For example, if
I have a function that increments a list of numbers, I am internally
calling another function for adding one number to another, and then
yet another function to apply this operation over each element of the
list (@ref{Mapping over a list of elements}).

@cindex M-x shows evaluated or autoloaded commands
@findex execute-extended-command
Apart from direct key bindings, the other pattern of interaction is
with the @kbd{M-x} (@code{execute-extended-command}) key: it produces
a minibuffer prompt that asks you to select a command by its name. You
press the @kbd{RET} key and Emacs proceeds to execute the command
you selected. What you get in this prompt is a list of all the
commands that have currently been evaluated or automatically loaded
(@ref{Autoloading symbols}).

@findex eval-last-sexp
@findex eval-buffer
@findex eval-region
Emacs can evaluate Elisp code from anywhere. Normally, you would want
to do this in a buffer whose major mode is designed for editing Emacs
Lisp (@ref{What are major and minor modes}). But Emacs will blithely
evaluate any Elisp expression from any buffer, including those whose
major mode is not designed to treat Elisp code in some special way. If
you have some Elisp in your buffer, you can place the cursor at the
end of its closing parenthesis and type @kbd{C-x C-e}
(@code{eval-last-sexp}). Similarly, you can use the commands @code{eval-buffer}
and @code{eval-region} to operate on the current buffer or highlighted
region, respectively. The @code{eval-buffer} only makes sense in a buffer
that contains only Elisp, otherwise you will probably get errors from
asking Emacs to evaluate text that does not correspond to known
functions or variables and whose syntax does not consist of lists.

To evaluate some code is to make its results available to the running
Emacs session. You are, in effect, teaching Emacs something new. It
will know about it for as long as the session is active and you have
not overwritten this knowledge, as it were, with some new definition
of it. This is how you add new functionality to Emacs, redefine
existing one, or simply get the value out of some code you are using.

@vindex buffer-file-name
The @code{eval-last-sexp} also works on symbols (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}).
For example, if you place the cursor at the end of the variable
@code{buffer-file-name} and use @kbd{C-x C-e} (@code{eval-last-sexp}), you
will get the value of that variable, which is either @code{nil} or the file
system path to the file you are editing in the current buffer.
Internally, it is like evaluating @code{(symbol-value 'buffer-file-name)},
as we covered in the chapter about the basics of Lisp (@ref{Basics of how Lisp works}).

@findex eval-expression
Sometimes the above are not appropriate for what you are trying to do.
Suppose you intend to write a command that copies the file path of the
current buffer. To do that, you need your code to test the value of
the variable @code{buffer-file-name} (@ref{Buffers as data, , Buffers as data structures}). But you
do not want to type out @code{buffer-file-name} in your actual file, then
use one of the aforementioned commands for Elisp evaluation, and then
undo your edits. Such is a cumbersome way of doing what is needed,
plus it is prone to mistakes! The best way to run Elisp in the current
buffer is to type @kbd{M-:} (@code{eval-expression}): it opens the
minibuffer and expects you to write the code you want to evaluate.
Type @kbd{RET} from there to proceed. The evaluation is done with
the last buffer as current (the buffer that was current prior to
calling @code{eval-expression}). This is especially useful if you want to
do a quick test of some part of a bigger procedure you are working on.

Here is some Emacs Lisp you may want to try in (i) a buffer that
corresponds to a file versus (ii) a buffer that is not associated with
any file on disk, such as the @samp{*scratch*} buffer.

@lisp
;; Use `eval-expression' to evaluate this code in a file-visiting
;; buffer versus a buffer that does not visit any file.
(if buffer-file-name
    (message "The path to this file is `%s'" buffer-file-name)
  (message "Sorry mate, this buffer is not visiting a file"))
@end lisp

@findex ielm
When you are experimenting with code, you want to test how it behaves
and confirm you are getting the expected results out of it. Since Lisp
consists of lists that can feed into each other, you can evaluate
smaller snippets of code while working towards the final version of
the program. Use the command @code{ielm} to open an interactive shell for
Emacs Lisp evaluation. It puts you at a prompt where you can type any
Elisp and hit @kbd{RET} to evaluate it. The return value is
printed right below.

@findex lisp-interaction-mode
@vindex initial-major-mode
@findex eval-print-last-sexp
@findex eval-last-sexp
Alternatively, switch to the @samp{*scratch*} buffer. If it is using the
major mode @code{lisp-interaction-mode}, which is the default value of the
variable @code{initial-major-mode}, then you can move around freely in that
buffer and type @kbd{C-j} (@code{eval-print-last-sexp}) at the end of
some code to evaluate it. This works almost the same way as
@code{eval-last-sexp}, with the added effect of putting the return value
right below the expression you just evaluated.

@cindex Introspect Emacs Lisp
@vindex major-mode
@findex describe-variable
@findex describe-function
@findex describe-keymap
@findex describe-key
@findex describe-symbol
In addition to these, you can rely on the self-documenting nature of
Emacs to figure out what the current state is. For example, to learn
about the buffer-local value of the variable @code{major-mode}, you can do
@kbd{C-h v} (@code{describe-variable}), and then search for that
variable. The resulting @samp{*Help*} buffer will inform you about the
current value of @code{major-mode}. This help command and many others like
@code{describe-function}, @code{describe-keymap}, @code{describe-key}, and
@code{describe-symbol}, provide insight into what Emacs knows about a given
object. The @samp{*Help*} buffer will show relevant information, such as
the path to the file that defines the given function or whether a
variable is declared as buffer-local (@ref{Introspecting Emacs}).

@node Introspecting Emacs
@chapter Introspecting Emacs

@cindex Emacs is self-documenting
@findex describe-variable
Emacs is ``self-documenting'' because it is aware of its state and can
report on it. When you define a variable, such as @code{my-name}, Emacs
retains in its running memory the symbol @code{my-name} and its
corresponding value of, say, @samp{Protesilaos}. If you invoke the command
@code{describe-variable}, it will produce a minibuffer prompt from where
you can select @code{my-name} among all other known variables. Once you
select that, a @samp{*Help*} buffer will be displayed. There you will find
information about @code{my-name}, such as its current value, any
documentation it may have and whether it has a buffer-local value
(@ref{Buffers as data, , Buffers as data structures}).

At all times, you update the state of Emacs by evaluating Elisp code
(@ref{Evaluate Emacs Lisp}). Let us consider the example of a variable that
we define for the first time:

@lisp
(defvar my-name "Protesilaos"
  "This is some documentation about my name.
A good Elisp program will document all the functions and variables it
provides.  Emacs developers have a strong documentation culture.  It
complements the software freedom we stand for, because it empowers users
to learn from the tools available to them and thus exercise their
freedom.")
@end lisp

@cindex The documentation culture of Emacs
@cindex Emacs is the epitome of the GNU project
@findex defvar
We use the special form @code{defvar} to declare @code{my-name} with an initial
value of @samp{Protesilaos} as a string (@ref{Evaluation inside of a macro or special form}).
The second line specifies the documentation of this variable.
Documentation strings, also known as ``docstrings'' are optional though
strongly recommended as a matter of convention. As you can tell from
the sample above, docstrings are how we make software freedom more
accessible to users. Like me, they can learn by reading this
information and then by trying to understand the code.

A combination of consistent reading habits and the ease of trial and
error that Emacs provides makes it possible to learn Elisp by doing
more with it, one small step at a time. This is how every Emacs user
can learn to program in Emacs Lisp or, at least, better understand
what their tool is doing. Such is the realisation of the promise of
free software: everyone, not just professional programmers, benefits
from it. And is why, in my opinion, Emacs epitomises the stated
objectives of the GNU project for software freedom: it incorporates
them and puts them to practice, all in one powerful program.

Once we evaluate the @code{defvar} for @code{my-name}, @code{describe-variable} will
produce a @samp{*Help*} buffer with the following contents about it:

@example
my-name’s value is "Protesilaos"

This is some documentation about my name.
A good Elisp program will document all the functions and variables it
provides.  Emacs developers have a strong documentation culture.  It
complements the software freedom we stand for, because it empowers users
to learn from the tools available to them and thus exercise their
freedom.
@end example

Now go to the source code of @code{my-name} and modify its value to @samp{Prot}
between double quotes. Then invoke the command @code{eval-defun} to
evaluate the definition anew. If you now call @code{describe-variable}, you
will get a @samp{*Help*} buffer with the updated value. This is how Emacs
works for all symbols it has evaluated. When the source code is in a
file, the @samp{*Help*} buffer will include a link to it. If you find such
a link, click on it to navigate to the file and at the locus where the
source code is.

@findex describe-variable
@findex describe-function
@findex describe-keymap
@findex describe-key
@findex describe-symbol
Depending on how the code is written, Emacs will have access to
metadata that can feed into those @samp{*Help*} buffers, among other uses.
For example, when a variable is defined, it can specify its original
value (@ref{Add metadata to symbols}). What matters at this point is that
Emacs will always know what the current state is. Make a habit out of
using the commands @code{describe-variable}, @code{describe-function},
@code{describe-keymap}, @code{describe-key}, and @code{describe-symbol}, among
others, whenever you have a question about what Emacs knows.

Do this before you search for further information online: it will
teach you to rely more on the primary source of Emacs and less on
secondary sources on the Internet. Plus, the resulting @samp{*Help*}
buffers will link you to the source code, from where you may learn
something more than just what you are searching for, such as how a
certain function is autoloaded (@ref{Autoloading symbols}). This is how you
build up your capacity for working with Elisp, which is how you get to
extend Emacs the way you want.

@node Side effect and return value
@chapter Side effect and return value

Emacs Lisp has functions. They take inputs and produce outputs. In its
purest form, a function is a computation that only returns a value: it
does not change anything in its environment. The return value of a
function can be used as input for another function, in what
effectively is a chain of computations. You can thus rely on a
function's return value to express something like ``if this works the
way I expect, then also do this other thing, otherwise do something
else or even nothing''.

Elisp is the language that extends and controls Emacs. This means that
it also affects the state of the editor. When you run a function, it
can make permanent changes, such as to insert some text at the point
of the cursor, delete a buffer, create a new window, permanently
change the value of some variable or function, and so on. These
changes may have an impact on future computations. For example, if the
previous function deleted a certain buffer, the next function which
was supposed to write to that same buffer can no longer do its job:
the buffer is gone! We call all these changes to the environment ``side
effects''. They are the byproducts of the computation, which itself
results in some value, i.e. the ``return value''.

When you write Elisp, you have to account for both the return value
and the side effects. If you are sloppy, you will get unintended
results caused by all those ill-considered changes to the environment.
But if you use side effects meticulously, you use Elisp to its full
potential. For instance, imagine you define a function that follows
the logic of ``create a buffer, go there, write some text, save the
buffer to a file at my preferred location, and then come back where I
was before I called this function, while leaving the created buffer
open''. All these are side effects and they are all instrumental to
your goal. Your function may have some meaningful return value as well
that you can employ as the input of another function. For example,
your function could return the buffer object it generated, so that the
next function can do something useful with it like display that buffer
in a separate frame and make its text larger.

The idea is to manipulate the state of the editor, to make Emacs do
what you envision. Sometimes this means your code has side effects. At
other times, side effects are useless or even run counter to your
intended patterns of behaviour. You will keep refining your intuition
about what needs to be done as you gain more experience and expand the
array of your skills (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}). No
problem; no stress!

@node Symbols balanced expressions and quoting
@chapter Symbols, balanced expressions, and quoting

@cindex Define a simple function
To someone not familiar with Emacs Lisp, it is a language that has so
many nested parentheses (@ref{Basics of how Lisp works})! Here is a simple
function definition:

@lisp
(defun my-greet-person (name)
  "Say hello to the person with NAME."
  (message "Hello %s" name))
@end lisp

@findex message
@findex view-echo-area-messages
I just defined the function with the name @code{my-greet-person}. It has a
list of parameters, specifically, a list of one parameter, called
@samp{name}. Then is the optional documentation string, which is for users
to make sense of the code and/or understand the intent of the function
(@ref{Introspecting Emacs}).

By convention, we write in the imperative voice (``Say hello and do
THIS'' instead of ``Says hello and does THIS'') and use upper case
letters to refer to the parameters or something that works as a
placeholder. Even in that parenthetic comment I made about the
imperative voice I followed the convention of using all capital
letters to denote a variable/placeholder with @samp{THIS}. Looks neat!

@code{my-greet-person} takes @samp{name} as input and passes it to the function
@code{message} as an argument to ultimately print a greeting. The @code{message}
function returns the string it formats and also produces the side
effect of appending it to the @samp{*Messages*} buffer. You can visit the
@samp{*Messages*} buffer directly with @kbd{C-h e} (@code{view-echo-area-messages}).

At any rate, this is how you call @code{my-greet-person} with the one
argument it expects:

@lisp
(my-greet-person "Protesilaos")
@end lisp

Now do the same with more than one parameters:

@lisp
(defun my-greet-person-from-country (name country)
  "Say hello to the person with NAME who lives in COUNTRY."
  (message "Hello %s of %s" name country))
@end lisp

And call it thus:

@lisp
(my-greet-person-from-country "Protesilaos" "Cyprus")
@end lisp

Even for the most basic tasks, you have parentheses everywhere: the
uniformity of Lisp means that we have lists all the way down! These
actually establish a clear structure, which make it easier to reason
about your program. If Lisp does not feel easy right now, it is
because you are not used to it yet. Once you do, there is no going
back.

@cindex Lisp languages are all about lists
The basic idea of any dialect of Lisp, Emacs Lisp being one of them,
is that you have parentheses which delimit lists. A list consists of
elements. Lists are either evaluated to produce the results of some
computation or returned as they are for use in some other evaluation
(@ref{Side effect and return value}):

@table @asis
@item The list as a function call
When a list is evaluated, the first
element is the name of the function and the remaining elements are
the arguments passed to it. You already saw this play out above with
how I called @code{my-greet-person} with @samp{"Protesilaos"} as its argument.
Same principle for @code{my-greet-person-from-country}, with
@samp{"Protesilaos"} and @samp{"Cyprus"} as its arguments.

@item The list as data
When a list is not evaluated, then none of its
elements has any special meaning at the outset. They are all
returned as a list of elements without further changes. When you do
not want your code to be evaluated, you prefix it with a single
quote character. For example, @samp{'("Protesilaos" "Prot" "Cyprus")} is
a list of three elements that should be returned as-is. The quote
prefix can be applied to symbols as well, such as @code{(symbol-function
  'my-greet-person)} to get the actual value out of the function
object whose symbol is @code{my-greet-person} (@ref{Basics of how Lisp works}).
@end table

@findex car
@findex cdr
Consider the latter case of lists as data, which you have not seen
yet. You have a list of elements and you want to get something out of
it. At the most basic level, the functions @code{car} and @code{cdr} return the
first element and the list of all remaining elements, respectively:

@lisp
(car '("Protesilaos" "Prot" "Cyprus"))
;; => "Protesilaos"

(cdr '("Protesilaos" "Prot" "Cyprus"))
;; => ("Prot" "Cyprus")
@end lisp

The single quote here is critical, because it instructs Emacs to not
evaluate the list. Otherwise, the evaluation of this list would treat
the first element, namely @samp{"Protesilaos"}, as the name of a function
and the remainder of the list as the arguments to that function. As
you do not have the definition of such a function, you get an error.

@findex list
@cindex Self-evaluating objects
Certain data types in Emacs Lisp are ``self-evaluating''. This means
that if you evaluate them, their return value is what you are already
working with. For example, the return value of the string of
characters @samp{"Protesilaos"} is @samp{"Protesilaos"}. This is true for
strings, numbers, keywords, symbols, and the special @code{nil} or @code{t}.
Here is a list with a sample of each of these, which you construct by
calling the function @code{list}:

@lisp
(list "Protesilaos" 1 :hello 'my-greet-person-from-country nil t)
;; => ("Protesilaos" 1 :hello my-greet-person-from-country nil t)
@end lisp

The @code{list} function evaluates the arguments passed to it, unless they
are quoted. The reason you get the return value without any apparent
changes is because of self-evaluation. Notice that @code{my-greet-person-from-country}
is quoted the same way we quote a list: we do not want to evaluate at
this moment, but only to include its symbol in the resulting list.
Without it, @code{my-greet-person-from-country} would be evaluated, which
would return an error of a void/undefined variable, unless that symbol
was also defined as a variable.

Pay close attention to the above code block and the resulting value I
included in the comment below. You will notice that @code{my-greet-person-from-country}
was quoted but is not quoted anymore. You can do this with any symbol
or list (@ref{Evaluate Emacs Lisp}). Every time you evaluate a quote
expression, you get back the expression without the quote. This means
that if you evaluate it again, you will get something different, such
as a function call, the value of a variable, or some error.

@cindex Quoting means to pass the expression to the next evaluation
@cindex Quoting means to avoid the evaluation right now
As such, it is helpful to think of the single quote prefix as an
instruction to ``do not evaluate this right now, but pass it over to
the next evaluation''. In its simplest form though, you can just say
``do not evaluate the following'', which is exactly what happens. More
specifically, it is an instruction to not perform evaluation if it
would have normally happened in that context (@ref{Evaluate some elements inside of a list}).

In other words, you do not want to quote something inside of a quoted
list, because that is the same as quoting it twice. The way the quote
prefix works is that it passes the ``do not evaluate'' instruction to
its entire form, which in the case of a list is from one parenthesis
all the way to the closing matching parenthesis, covering everything
in between.

@lisp
;; This is the correct way:
'(1 :hello my-greet-person-from-country)

;; It is wrong to quote `my-greet-person-from-country' because the
;; entire list would not have been evaluated anyway.  The mistake here
;; is that you are quoting what is already quoted, like doing
;; ''my-greet-person-from-country.
'(1 :hello 'my-greet-person-from-country)
@end lisp

@cindex Self-quoting objects
@cindex Unquoted symbols are evaluated
@findex symbol-value
Now you may be wondering why did we quote @code{my-greet-person-from-country}
but nothing else? The reason is that everything else you saw there is
effectively ``self-quoting'', i.e. the flip-side of self-evaluation.
Whereas @code{my-greet-person-from-country} is a symbol. A ``symbol'' is
usually a reference to something other than itself: it either
represents some computation---a function---or the value of a variable.
The symbols @code{nil} and @code{t} are special as they always refer to
themselves, meaning that when you evaluate them you get back exactly
what you evaluated (@ref{Add metadata to symbols}).

If you write a symbol without quoting it, you are effectively telling
Emacs ``give me the value this symbol represents''. In the case of
@code{my-greet-person-from-country}, you will get an error if you try that
because this symbol is not a variable and thus trying to get a value
out of it (the @code{symbol-value} to be precise) is not going to work.

@findex electric-pair-mode
To make it easier to describe our actions, we say that we are
evaluating ``expressions''. These are the objects that Emacs can
evaluate, such as a list, a list of lists, or fundamental objects in
their own right, like strings and symbols. These expressions need to
be balanced, meaning that either they are self-contained (e.g. a
string) or have parentheses around them and start and end where they
are supposed to be.

A common error in Elisp programs is to have unbalanced parentheses,
such as by forgetting one parenthesis at the end or mistyping an extra
one. Some programmers use packages that automatically balance Elisp
code. The built-in @code{electric-pair-mode} minor mode can help in this
regard (@ref{What are major and minor modes}). It automatically inserts
delimiters as pairs, so you will probably have the correct number of
parentheses each time. You may like to write code this way. Though it
is a matter of style. I am among those who prefer to do things
manually. I find such ``electric'' behaviour to be more trouble than it
is worth, given how I like to move around in a buffer. Perhaps, then,
the name ``electric'' draws from the ability of this mode to shock you
at times.

Keep in mind that Emacs Lisp has a concept of ``macro'', which basically
is a templating system to write code that actually expands into some
other code which is then evaluated. Macros are not some other language
with its own syntax. They are Emacs Lisp as well, only they make more
advanced use of quoting to control how evaluation is done and where.
Inside of a macro, you specify what is evaluated now as opposed to
later, meaning that the aforementioned may not apply directly to calls
that involve the macro, even if they are still used inside of the
macro's expanded form (@ref{Evaluation inside of a macro or special form}).

@findex lambda
@findex symbol-value
@findex symbol-function
As you expose yourself to more Emacs Lisp code, you will encounter
quotes that are preceded by the hash sign, like @samp{#'some-symbol}. This
``sharp quote'', as it is called, is the same as the regular quote with
the added semantics of referring to a function in particular. The
programmer can thus better articulate the intent of a given
expression, while the byte compiler may internally perform the
requisite checks and optimisations.

This is not merely a matter of semantics though. When you define a
symbol, there is a difference between storing in it a value or a
closure. A ``closure'' is an object consisting of a @code{lambda} with its
parameters and the body of form. In other words, defining a variable
and defining a value leads to a different result. Consider how the
functions @code{symbol-value} and @code{symbol-function} work: they both examine
a symbol. @code{symbol-value} treats the symbol as a variable and will
return its value, if any. @code{symbol-function} treats the symbol as a
function and returns its closure, if any.

Here is how it works:

@lisp
(defvar my-name "Protesilaos")
;; => my-name

(symbol-value 'my-name)
;; => "Protesilaos"

(symbol-function 'my-name)
;; => nil

(defun my-greet (person)
  (format "Hello %s" person))
;; => my-greet

(symbol-function 'my-greet)
;; => #[(person) ((format "Hello %s" person)) nil]

(symbol-value 'my-greet)
;; => ERROR...
@end lisp

Notice that @samp{[(person) ((format "Hello %s" person)) nil]} is the
printed representation of a closure. This is the object corresponding
to the following:

@lisp
(lambda (person)
  (format "Hello %s" person))
@end lisp

@findex pp-macroexpand-last-sexp
In fact, when you use @code{defun} it actually creates an alias for such a
lambda. Place the cursor at the closing parenthesis of the @code{defun}
expression and invoke the command @code{pp-macroexpand-last-sexp} to
confirm as much. I am printing it below for your convenience:

@lisp
(defun my-greet (person)
  (format "Hello %s" person))
;; => (defalias 'my-greet (lambda (person) (format "Hello %s" person)))
@end lisp

@findex quote
@findex function
In light of these, you can better appreciate the nuances between the
functions @code{quote} and @code{function}, as pertains to symbols. When you
write @code{(quote some-symbol)} this is the same as @code{'some-symbol}, which
is then expected to be evaluated by @code{symbol-value}. Whereas @code{(function
some-symbol)} is the way to state @code{#'some-symbol} and to suggest that
@code{symbol-function} is how to get the data out of the symbol in
question.

While these technicalities matter, you do not need to be an expert in
them to write decent code. What you need to remember when working with
Elisp is that you can tell from the context alone whether something is
treated as a function call or as a variable.

@node Buffers as data
@chapter Buffers as data

@findex point
@findex point-min
@findex point-max
@findex line-beginning-position
@findex re-search-forward
In its simplest form, a buffer holds data as a sequence of characters.
When you open a file, for example, Emacs reads the file contents from
the disk, loads them into its running memory, and displays the
contents in a buffer. This buffer now has as its data the contents of
the file and anything else that can be extracted therefrom. Each
character exists at a given position, which is a number. The function
@code{point} gives you the numeric position at the point you are on, which
typically corresponds to where the cursor is (@ref{Evaluate Emacs Lisp}).

At the beginning of a buffer, @code{point} returns the value of @samp{1} (@ref{Side effect and return value, , Side
effect and return value}). There are plenty of functions that return a
buffer position, such as @code{point-min}, @code{point-max}, @code{re-search-forward},
and @code{line-beginning-position}. Some of those will have side effects,
like @code{re-search-forward} which moves the cursor to the given match.

When you program in Emacs Lisp, you frequently rely on buffers to do
some of the following:

@findex buffer-string
@findex buffer-substring
@findex buffer-substring-no-properties
@table @asis
@item Extract file contents as a string
Think of the buffer as a large
string. You can get the entirety of its contents as one potentially
massive string by using the function @code{buffer-string}. You may also
get a substring between two buffer positions, such as with the
@code{buffer-substring} function or its @code{buffer-substring-no-properties}
counterpart (@ref{Text has its own properties}). Imagine you do this as
part of a wider operation that (i) opens a file, (ii) goes to a
certain position, (iii) copies the text between some boundaries,
(iv) switches to another buffer, and (v) writes what it found to
this new buffer.
@end table

@findex get-buffer-create
@findex get-buffer
@findex with-current-buffer
@findex erase-buffer
@findex delete-region
@findex display-buffer
@findex pop-to-buffer
@table @asis
@item Present the results of some operation
You may have a function
that shows upcoming holidays. Your code does the computations behind
the scenes and ultimately writes some text to a buffer. The end
product is on display. Depending on how you go about it, you will
want to evaluate the function @code{get-buffer-create} or its more strict
@code{get-buffer} alternative. If you need to clear the contents of an
existing buffer, you might use the @code{with-current-buffer} macro to
temporarily switch to the buffer you are targetting and then either
call the function @code{erase-buffer} to delete everything or limit the
deletion to the range between two buffer positions with
@code{delete-region}. Finally, the functions @code{display-buffer} or
@code{pop-to-buffer} will place the buffer in an Emacs window. When you
present data, you may also choose to have some specialised major
mode that sets the appropriate settings (@ref{What are major and minor modes}).
@end table

@vindex buffer-file-name
@vindex fill-column
@vindex default-directory
@vindex buffer-list
@findex setq-local
@table @asis
@item Associate variables with a given buffer
In Emacs Lisp, variables
can take a buffer-local value which differs from its global
counterpart. Some variables are even declared to always be
buffer-local, such as the @code{buffer-file-name}, @code{fill-column}, and
@code{default-directory}. Suppose you are doing something like returning
a list of buffers that visit files in a given directory. You would
iterate through the return value of the @code{buffer-list} function to
filter the results accordingly by testing for a certain value of
@code{buffer-file-name} (@ref{Basic control flow with @code{if} @code{cond} and others, , Basic control flow with @code{if}@comma{} @code{cond}@comma{} and others}).
The special form @code{setq-local} sets the buffer-local value of a
variable (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}).
@end table

@findex seq-filter
@findex buffer-list
@cindex Hidden buffers
The latter point is perhaps the most open-ended one. Buffers are like
a bundle of variables. This bundle includes their contents, any
overlays or text properties associated with the contents, the active
major mode, any active minor modes, and all the buffer-local values of
other variables (@ref{What are major and minor modes}). In the following
code block, I am using the @code{seq-filter} function to iterate through
the return value of the function @code{buffer-list} to get a list of
buffers that (i) are not hidden from the user's view and (ii) have
@code{text-mode} as their major mode or a derivative thereof (@ref{Mapping over a list of elements}).

@lisp
(seq-filter
 (lambda (buffer)
   "Return BUFFER if it is visible and its major mode derives from `text-mode'."
   (with-current-buffer buffer
     ;; The convention for buffers which are not meant to be seen by
     ;; the user is to start their name with an empty space.  We are
     ;; not interested in those right now.
     (and (not (string-prefix-p " " (buffer-name buffer)))
          (derived-mode-p 'text-mode))))
 (buffer-list))
@end lisp

This will return a list of buffer objects or @code{nil}. The above relies
on a @code{lambda} to do its work. This @code{lambda} exists only inside the
given function call. If we ever need to perform the same check, it is
better to give a name to the @code{lambda}, i.e. to define a function. As
such, we may write the following (@ref{When to use a named function or a lambda function}):

@lisp
(defun my-buffer-visible-and-text-p (buffer)
  "Return BUFFER if it is visible and its major mode derives from `text-mode'."
  (with-current-buffer buffer
    ;; The convention for buffers which are not meant to be seen by
    ;; the user is to start their name with an empty space.  We are
    ;; not interested in those right now.
    (and (not (string-prefix-p " " (buffer-name buffer)))
         (derived-mode-p 'text-mode))))

(seq-filter #'my-buffer-visible-and-text-p (buffer-list))
@end lisp

As with buffers, Emacs windows and frames have their own parameters. I
will not cover those as their utility is more specialised and the
concepts are the same. Just know that they are data objects that you
may use in your programs.

@node Text has its own properties
@chapter Text has its own properties

@cindex Propertise text
@cindex Fontify text
@cindex Faces
@findex describe-char
Just as with buffers that work like data objects (@ref{Buffers as data}),
any text may also have properties associated with it---and symbols
too, by the way (@ref{Add metadata to symbols}). This is metadata that you
inspect using Emacs Lisp functions. For example, when you have syntax
highlighting in some programming buffer, it is the effect of
underlying text properties. Some function takes care to ``propertise''
or to ``fontify'' the relevant text. It applies to it an object known as
a ``face''.

Faces are constructs of the Emacs display engine that bundle together
typography and colour attributes, such as the font family and weight,
as well as foreground and background hues. Every piece of text uses
the @code{default} face at minimum. Whenever a colour is present or some
other typographic style, then there are more faces present.

To get a @samp{*Help*} buffer with information about the text properties
where the cursor is, type @kbd{M-x} (@code{execute-extended-command})
and then invoke the command @code{describe-char}. It will tell you about
the character it identifies, what font it is rendered in, which code
point it is, and what its text properties are, if any. If there is a
face, that @samp{*Help*} buffer will link to it. Following the link shows
you what the face's effective attributes are.

Suppose you are writing your own major mode. At the early stage of
experimentation, you want to manually add text properties to all
instances of the phrase @samp{I have properties} in a buffer whose major
mode is @code{fundamental-mode}, so you produce a function that adds text
properties where relevant, like the following (@ref{The match data of the last search}):

@lisp
(defun my-add-properties ()
  "Add properties to the text \"I have properties\" across the current buffer."
  (goto-char (point-min))
  (while (re-search-forward "I have properties" nil t)
    (add-text-properties (match-beginning 0) (match-end 0) '(face error))))
@end lisp

@findex switch-to-buffer
Actually test this. Use @kbd{C-x b} (@code{switch-to-buffer}), type in
some random characters that do not match an existing buffer, and then
press @kbd{RET} to visit that new buffer. It runs @code{fundamental-mode},
meaning that no special ``fontification'' is in effect and, thus,
@code{my-add-properties} will work as intented (@ref{What are major and minor modes}).
Now paste this snippet of text:

@example
This is some sample text. Will the phrase "I have properties" use the `error' face?

What does it even mean for I have properties to be rendered as `error'?
@end example

Continue with @kbd{M-:} (@code{eval-expression}) and call the function
@code{my-add-properties}, i.e. @code{(my-add-properties)}. Did it work? The face
this function is applying is called @code{error}. Ignore the semantics of
that word: I picked @code{error} simply because it typically is styled in a
fairly intense and obvious way (though your current theme may do
things differently).

@findex shortdoc
@cindex Shortdoc for text properties
There are functions which find the properties at a given buffer
position and others which can search forward and backward for a
certain property. The specifics do not matter right now. All I want
you to remember is that the text may hold data beyond its constituent
characters. For more details, type @kbd{M-x} (@code{execute-extended-command})
to call the command @code{shortdoc}. It will ask you for a documentation
group. Pick @samp{text-properties} to learn more. Well, actually use
@code{shortdoc} for everything listed there---I do it frequently!

@cindex The font-lock mechanism
@vindex font-lock-defaults
@vindex font-lock-keywords
The example above with @code{add-text-properties} is not how major modes
typically do things (@ref{What are major and minor modes}). Emacs has a more
sophisticated mechanism, called ``font-lock''. It is responsible for
fontifying the buffer. A major mode will thus set up the
@code{font-lock-defaults} variable (minor modes will typically modify the
@code{font-lock-keywords}). How exactly this works is not important for our
purposes. The general idea is that for each style, say level 1
headings in Org, you either write a regular expression or, better, a
function that does pattern matching. You then specify which face
corresponds to the matched pattern or subgroups thereof and how should
the faces be applied in case of competing fontification rules.

What ultimately matters is that we have buffers as data objects and
text that has metadata. We use this to our advantage to parse the text
available to us.

@node Add metadata to symbols
@chapter Add metadata to symbols

@findex symbol-value
A symbol can be a reference to itself or to some value (@ref{Basics of how Lisp works}).
For variables, @code{nil} returns @code{nil}, @code{t} returns @code{t}, and @code{my-name}
will return @samp{Protesilaos} if it is defined thus. For functions, the
symbol actually is an alias for a given computation, i.e. a @code{lambda}
expression whose evaluation may produce side effects and return a
value (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}).
We can get the value of a variable either by evaluating it without a
quote or by passing its symbol as an argument to the function
@code{symbol-value} (@ref{Side effect and return value}). Consider these:

@lisp
;; Define the variable `my-name' and give it a value.
(defvar my-name "Protesilaos")
;; => my-name

;; What is the value of the symbol `my-name', where the symbol is a variable?
(symbol-value 'my-name)
;; => "Protesilaos"

;; What is the value of the variable `my-name' if I do not quote it?
my-name
;; => "Protesilaos"
@end lisp

@findex symbol-function
Similarly, we can get the function value of a symbol by calling @code{symbol-function}:

@lisp
(defun my-hello (person)
  "Say hello to PERSON."
  (message "Hello %s" person))
;; => my-hello

;; What is the symbol `my-hello' as a function?
(symbol-function 'my-hello)
;; => #[(person) ((message "Hello %s" person)) nil nil "Say hello to PERSON."]

;; What happens if I call `my-hello' without parentheses and/or a quote?
my-hello
;; => ERROR
@end lisp

@findex put
What we know up until now about symbols is that they can be associated
with a data point, be it as variables or functions. That is their
value. They may also have metadata, which in Emacs Lisp terminology is
known as a ``property'' or ``symbol properties''. In its simplest form, a
symbol @code{my-name} is associated with arbitrary metadata through the use
of the @code{put} function:

@lisp
(put 'my-name 'my-nicknames '("Prot" "The dog" "The Cypriot" "The Greek-mainlander"))
;; => ("Prot" "The dog" "The Cypriot" "The Greek-mainlander")
@end lisp

Similarly, the @code{get} function returns the value of the given symbol's
property.

@lisp
(get 'my-name 'my-nicknames)
;; => ("Prot" "The dog" "The Cypriot" "The Greek-mainlander")
@end lisp

@findex symbol-plist
In the above two examples, the symbol we are operating on is @code{my-name}
and its property is @code{my-nicknames}. The value given to the property
can be any Elisp object, such as a number, a string, or a list. In the
above examples we have a list of strings. To retrieve all the
properties of a symbol, we use the function @code{symbol-plist}, where
``plist'' stands for ``property list''.

@lisp
(symbol-plist 'my-name)
;; => (variable-documentation "This is some documentation about my name." my-nicknames ("Prot" "The dog" "The Cypriot" "The Greek-mainlander"))
@end lisp

@cindex What is a property list
@findex plist-get
What @code{symbol-plist} returns is an even-numbered list where each odd
number is the key and each even number is its corresponding value.
This is the plist. Looking at what we have above, we can use
@code{plist-get} to extract a value from the property list, thus:

@lisp
(plist-get (symbol-plist 'my-name) 'my-nicknames)
;; => ("Prot" "The dog" "The Cypriot" "The Greek-mainlander")
@end lisp

Though in this specific case we already have @code{get} do the same work,
so @code{plist-get} is superfluous---it is applicable in other contexts
where you need to work with a plist.

The @code{my-name} is the symbol of a variable, though the symbol of a
function will work the same way. Let me show you how the @code{my-hello} we
defined further above will get its @samp{cool-factor}:

@lisp
(put 'my-hello 'cool-factor t)
@end lisp

@cindex A function definition can specify metadata
@findex declare
@findex string-chop-newline
You @code{get} how this works. In working code, you will probably not need
to use properties in this way. Some macro will handle them internally.
Consider this real-world example from the Emacs source code where the
function @code{string-chop-newline} is declared with concomitant metadata
(the relevant symbols for @code{declare}, such as @code{pure} and
@code{side-effect-free}, are documented in the Emacs Lisp Reference
Manual):

@lisp
(defun string-chop-newline (string)
  "Remove the final newline (if any) from STRING."
  (declare (pure t) (side-effect-free t))
  (string-remove-suffix "\n" string))
@end lisp

@cindex A user option is defined with relevant metadata
@findex defcustom
In practice, this boils down to a @code{put} operation, as illustrated
above. You just do not need to specify it yourself. Same principle for
variables. For example, the Lisp macro @code{defcustom} defines a variable
with some special metadata which renders it as a so-called ``user
option'': it is a variable that the programmer has designed for users
to modify and, therefore, is meant to have a predictable,
well-supported behaviour. Internally, @code{defcustom} will add properties
to associate the variable with its original value and to do everything
necessary to render concrete its particularities, such as whether the
variable is safe as a buffer-local value (@ref{Buffers as data}).

Chances are that you will not need to deal with symbol properties,
especially not while you are getting started. Though know that there
are Emacs Lisp programs that make extensive use of them. If your
program needs to work with symbol properties, you have already gotten
enough exposure to them to proceed with confidence. May you make the
most out of this occasion!

@node What are major and minor modes
@chapter What are major and minor modes

@cindex Major modes work with buffer-local variables
@cindex Buffers can have a local keymap
Buffers are data objects that can be associated with more data
(@ref{Buffers as data}). A common use-case is to have buffer-local variables
that control how certain functions behave when called with the given
buffer as current. If the text is read-only, for example, this is due
to a buffer-local variable that inhibits the ordinary behaviour of
text editing commands. When a certain key binding does something
different in one buffer than in another, this too is because of
buffer-local variables. Or, to be more precise, the buffer applies its
own local keymap which overrides the global keymap.

In essence, major and minor modes are commands which activate settings
once they are invoked, such as with @kbd{M-x}
(@code{execute-extended-command}) (minor mode commands have a toggle
behaviour, but more on that below). If you look at the definition of a
major mode, for instance, you will notice that all it seems to do is
specify buffer-local values for certain variables. Those typically
pertain to standardised definitions, such as what is a paragraph, what
constitutes a comment, how should indentation be handled, whether
there is an outline or some kind or index with points of interest in
the buffer, and the fontification settings or other text properties
(@ref{Text has its own properties}). Here is a simple example from the
source code of Emacs, specifically @file{text.el}:

@lisp
(define-derived-mode text-mode nil "Text"
  "Major mode for editing text written for humans to read.
In this mode, paragraphs are delimited only by blank or white lines.
You can thus get the full benefit of adaptive filling
 (see the variable `adaptive-fill-mode').
\\@{text-mode-map@}
Turning on Text mode runs the normal hook `text-mode-hook'."
  (setq-local text-mode-variant t)
  (setq-local require-final-newline mode-require-final-newline)

  ;; Enable text conversion in this buffer.
  (setq-local text-conversion-style t)
  (add-hook 'context-menu-functions 'text-mode-context-menu 10 t)
  (when (eq text-mode-ispell-word-completion 'completion-at-point)
    (add-hook 'completion-at-point-functions #'ispell-completion-at-point 10 t)))
@end lisp

@findex setq-local
@findex add-hook
The docstring of @code{text-mode} has some markup that controls what the
@samp{*Help*} buffer will show (@ref{Introspecting Emacs}). The combination of
backtick and single quote makes @samp{*Help*} treat the given text as a
symbol that it links to. Thus, by reading about @code{text-mode}, we also
get a link to @code{adaptive-fill-mode}. Following that link yields the
relevant documentation. The braces or curly brackets, the opening of
which is escaped with backslashes, is a placeholder to get the
contents of a keymap listed there. What we will then get in the
@samp{*Help*} buffer is a listing with all the keys and the commands they
are bound to. Beside these technicalities, we have some @code{setq-local}
and @code{add-hook} calls that also have a local scope (@ref{Hooks and the advice mechanism}).

@cindex The default major mode is Fundamental mode
@findex fundamental-mode
What you learn from studying the definition of @code{text-mode} is that it
effectively is a bundle of settings. By setting a buffer to use the
major mode @code{text-mode}, we are practically opting in to those
settings. If you create a new buffer, whose major mode is
@code{fundamental-mode} by default, you can manually set all of the above
without explicitly calling @code{text-mode}. Doing so will give you
most---though not all!---of what @code{text-mode} does. Actually, do not
try this at home: nobody has time for such cumbersome labour and it
anyway is not doing what you actually need.

@cindex Major modes have a hook, keymap, syntax table, abbrev table, and parent mode
@vindex major-mode
@findex abbrev-mode
@findex define-derived-mode
If you do proceed though, know that you are not getting the full
effect of @code{text-mode}. Internally, Emacs takes care of a few more
things when you invoke the command of the major mode. Specifically, it
updates the variable @code{major-mode} to point to the symbol of the
currently active mode. It also specifies the parent major mode, if
any, from where the current major mode inherits its settings.
Furthermore, Emacs updates the local keymap and also calls the hook of
the given major mode. And if you are really curious, it even changes
the applicable syntax table and table of abbreviations. The syntax
table determines such things as what is a symbol and what is
punctuation, while the abbreviations' table, known as ``abbrev table'',
holds data that is used by the built-in minor mode called
@code{abbrev-mode}.

Where do all these come from? Well, @code{define-derived-mode} is a macro
that instantiates everything using the name of the mode as a prefix
(@ref{Evaluation inside of a macro or special form}). If, for example, there
is a major mode called @code{football-mode}, in reference to the game where
players kick a ball around the pitch instead of hugging it in
confusion, then there will be a @code{football-mode-hook},
@code{football-mode-map}, @code{football-mode-syntax-table}, and
@code{football-mode-abbrev-table}.

@cindex One major mode per buffer
Major modes are mutually exclusive. There can only be one per buffer,
though there are clever ways to have the effects of many major modes
in one buffer, like what Org mode does with source code blocks that
retain some of the qualities of the programming modes they reference.
The reason a buffer has one major mode is due to the conflicts that
would otherwise arise. For example, Emacs would have an unpredictable
behaviour if one major mode defined, say, dashes as punctuation while
another treated them as constituent characters of symbols. A
programmer could come up with increasingly complex heuristics, though
there is a certain elegance to the ``one buffer, one major mode''
approach. In some contexts, like in modern web development, the major
mode effectively is a superset of other major modes, such that it can
work with a mixture of JavaScript, HTML, and CSS@.

@findex hl-line-mode
@findex display-line-numbers-mode
@findex show-paren-mode
@findex electric-pair-mode
By contrast, there can be more than one minor mode per buffer.
Sometimes the functionality of one will directly contradict another,
though they generally combine harmoniously. For example, Emacs comes
with lots of useful minor modes out-of-the-box. One of them highlights
the current line. It is called @code{hl-line-mode}. Another displays line
numbers on the side of the window: its symbol is @code{display-line-numbers-mode}.
Those can work together in a buffer in conjunction with other minor
modes, such as @code{show-paren-mode}, that highlights matching
parentheses, and @code{electric-pair-mode} that inserts certain characters
as pairs, like double quotes and parentheses. Because minor modes
usually have complementary functionality, they are designed to work
both locally and globally. Whatever conflicts are up to the user to
resolve.

Otherwise, minor modes follow the rationale of major modes: they are
commands that typically set some variables (not to imply they are
simple though, as they can do anything they want). Since minor modes
can, in principle, coexist, calling their command with @kbd{M-x}
(@code{execute-extended-command}) toggles them on and off. Such a switch
would not be of much use for major modes: it would be the same as
activating @code{fundamental-mode}.

@findex define-minor-mode
Once you delve deeper, minor modes are also supposed to have a
different scope of application. A minor mode should not be messing
around with the syntax table, for example, as then there could be a
minor mode that breaks the current major mode. This could be done
though, but the programmer must be extra careful how they go about
dealing with the resulting complexity, given that other minor modes
may also be in effect while major modes may be doing something of
their own that has to be accounted for. The macro which defines a
minor mode, namely, @code{define-minor-mode} will also not do exactly what
@code{define-derived-mode} does for major modes. It will not specify a
parent mode as there is no such concept of inheritance for minor
modes. There will also be no abbrev table, no syntax table, and no
keymap. A keymap can be associated with a minor mode, though it must
be done explicitly with a special keyword. The documentation of
@code{define-minor-mode} covers the details (@ref{Introspecting Emacs}).

In general, you will benefit from thinking of Emacs as one big mutable
state. Within it there are compartments with their own peculiarities.
Emacs is designed to give priority to the particular over the general.
The specific/local overrides the generic/global. This is true for
variables, keymaps, abbrev tables, faces (via face remapping that we
do not need to cover), and, in an analogous way, is also true for
@code{let} bindings where the innermost overrides the outer ones
(@ref{Evaluation inside of a macro or special form}). For Emacs' modes, a
major mode will override the settings of the major mode it is derived
from, while a minor mode will take precedence over a major mode. Be
mindful of this so that you can use it to your advantage.

@node Hooks and the advice mechanism
@chapter Hooks and the advice mechanism

@findex add-hook
You know that each major and minor mode runs its own hook (@ref{What are major and minor modes}).
A hook is a variable that holds a list of functions. These are
evaluated in sequence when the hook runs. The functions are normally
called without an argument, so they must have their parameters set up
correctly to avoid the error with the mismatching number of mandatory
arguments. Some hooks are considered ``abnormal'' in that they call
their functions with one or more arguments. How many arguments is up
to each hook. I will show you in practice.

The function @code{add-hook} adds a function to a hook. It looks like the
function call in Emacs Lisp (@ref{Basics of how Lisp works}):

@lisp
(add-hook 'text-mode-hook #'visual-line-mode)
@end lisp

@vindex text-mode-hook
@findex visual-line-mode
@vindex before-save-hook
@vindex pre-command-hook
The @code{text-mode-hook} is exactly what its name suggests: the hook that
@code{text-mode} runs. It is evaluated after the @code{text-mode} is done
setting all its variables. Generally, it is common for hooks to run at
the end of the function that calls them, though it is also possible to
run a hook before or during some operation. Notable examples are
@code{before-save-hook} and @code{pre-command-hook}. The rule of thumb is this:
if the hook's symbol does not imply otherwise, the hook is run at the
end.

In the above example, you noticed how I added a quote to the variable
@code{text-mode-hook} and a sharp quote to the function @code{visual-line-mode}
(@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}). The expression would
have still worked fine with a regular quote instead of the sharp
quote. Though these added semantics can help us catch problems during
byte compilation when we are developing packages.

@vindex hl-line-mode-hook
The @code{add-hook} has a global effect by default: it updates the global
value of the variable, not its buffer-local value (@ref{Buffers as data}).
For example, if you want to do something with, say,
@code{hl-line-mode-hook} only in a specific file, then you need to arrange
for the @code{add-hook} side effect to be applied in the buffer that visits
the given file (@ref{Side effect and return value}). This is done by passing
a non-@code{nil} argument to the @samp{LOCAL} parameter of @code{add-hook}, as we
learn from its documentation (@ref{Introspecting Emacs}):

@lisp
(defun my-display-line-numbers-toggle ()
  "Enable `display-line-numbers-mode' if `hl-line-mode' is active.
Else disable `display-line-numbers-mode'."
  (if hl-line-mode
      (display-line-numbers-mode 1)
    (display-line-numbers-mode -1)))

(add-hook 'hl-line-mode-hook #'my-display-line-numbers-toggle nil t)
@end lisp

@findex hl-line-mode
@vindex hl-line-mode
The function @code{my-display-line-numbers-toggle} is now set up to run in
the current buffer whenever @code{hl-line-mode} is enabled or disabled. Try
it! Here you will also notice a technicality. Each minor mode has a
function and a variable of the same symbol. When the minor mode is
enabled, the variable is set to a non-@code{nil} value.

@findex run-hooks
Internally, a function that runs a hook does it with a call to @code{run-hooks}:

@lisp
(run-hooks 'text-mode-hook)
@end lisp

@cindex The &rest keyword in run-hooks
The @code{run-hooks} is plural because it has a @samp{&rest} keyword in its
parameters, meaning that we can give it as many arguments as we want
and it will collect them all into a single list that will then be
handled appropriately. Thus:

@lisp
;; No matter how many arguments we pass, they will be collected into a
;; single HOOKS list, owning to the &rest keyword.
(run-hooks 'text-mode-hook 'hl-line-mode-hook)
@end lisp

@findex remove-hook
To remove a function from a hook variable, we use @code{remove-hook}. It is
similar to @code{add-hook}, though check its documentation because its
parameters are not the same:

@lisp
;; Remove globally
(remove-hook 'hl-line-mode-hook #'my-display-line-numbers-toggle)

;; Remove locally
(remove-hook 'hl-line-mode-hook #'my-display-line-numbers-toggle t)
@end lisp

Thus far we have examined ``normal hooks'', i.e. hooks whose functions
are called without any arguments. By convention, a normal hook has the
@samp{-hook} suffix. ``Abnormal hooks'' are called with one or more
arguments. Each hook decides how many those are and what they are
expected to be. Abnormal hooks have the suffix @samp{-functions}. The
@code{add-hook} and @code{remove-hook} work the same way for abnormal hooks.
What is different is the functions we have to add to them, in order to
get the expected results: they must be able to handle the arguments
passed to them. Here is an example of defining and then calling a
hook. Remember that hooks are ordinary variables:

@lisp
;; Example with a normal hook:
(defvar my-normal-hook nil
  "Normal hook for `my-hello-world'.")

(defun my-hello-world ()
  "Print a hello message and run `my-normal-hook'."
  (message "Hello world")
  (run-hooks 'my-normal-hook))

;; Example with an abnormal hook:
(defvar my-normal-functions nil
  "List of functions to call after `my-say-hello'.
Each function takes two arguments, the name of the person and their
country of residence.")

(defun my-say-hello (person country)
  "Say hello to PERSON from COUNTRY."
  (message "Hello %s from %s" person country)
  (run-hook-with-args 'my-normal-functions person country))
@end lisp

@findex run-hook-with-args
The @code{run-hook-with-args} takes one hook and the arguments that are
passed to its functions. Otherwise the functionality is the same
between running a normal hook and an abnormal hook.

@cindex The advice mechanism
@findex add-function
The logic of a hook is simple ``let the user do something before or
after some event''. The only constraint is that the programmer has
provided such a point of entry. There are times though where you want
to do something, but there is no hook for it. This is where the advice
mechanism comes in. We can ``advise'' a function to run some code before
or after or even around some other function. In practice, we can
redefine the original function by wrapping it in our function. The
documentation string of @code{add-function} provides a concise overview,
but let me show you a couple of common use-cases. Before you proceed,
promise me to use the advice mechanism with care, because you can
produce unexpected results and create bugs in other packages.

@findex advice-add
Probably the simplest use of the advice mechanism is to do something
after a given function is called. Conceptually, this is like a hook in
the ordinary scenario. You do it with the function @code{advice-add}:

@lisp
(defun my-after-next-line (&rest _)
  "Message the current line number while ignoring any arguments."
  (message "Current line: %s" (line-number-at-pos)))

(advice-add #'next-line :after #'my-after-next-line)
@end lisp

Once you evaluate this, move down a line and notice how you get the
message with the current line number. Now do @code{advice-remove} to undo
the effect:

@lisp
(advice-remove #'next-line #'my-after-next-line)
@end lisp

@cindex Using &optional and &rest with the advice mechanism
Go back to the definition of @code{my-after-next-line}. It says that it
ignores any arguments. This is done by writing the @samp{&rest} keyword and
then the name of some parameter prefixed by an underscore. If we do
not care about the name either, we just write the underscore. The
underscore is how we convey the meaning of ``I shall ignore this, mate;
cheers!''. The reason I wrote it this way is because the advice is
called with the arguments of the original function. If I wanted to do
something with one or more of them, I could have written the list of
parameters in one of the following ways:

@lisp
;; Two mandatory parameters.
(defun my-demo (parameter-one parameter-two)
  ...)

;; A mandatory parameter and a list of zero or more other acceptable arguments.
(defun my-demo (parameter-one &rest all-others)
  ...)

;; As above but we declare the intention to ignore ALL-OTHERS.
(defun my-demo (parameter-one &rest _all-others)
  ...)

;; Two optional parameters, meaning that the function can be called
;; without them.  But if the function is called with arguments, those
;; must be maximum two.
(defun my-demo (&optional parameter-one parameter-two)
  ...)

;; One mandatory and one optional parameter.
(defun my-demo (parameter-one &optional parameter-two)
  ...)

;; One optional parameter and a list of zero or more acceptable arguments.
(defun my-demo (&optional parameter-one &rest all-others)
  ...)

;; As above, but ALL-OTHERS is meant to be ignored.
(defun my-demo (&optional parameter-one &rest _all-others)
  ...)

;; One mandatory, one optional parameter, and then a list of zero or
;; more acceptable arguments.
(defun my-demo (parameter-one &optional parameter-two &rest all-others)
  ...)
@end lisp

Keep the above in mind while adding an advice. If you get the
parameters wrong, then errors will ensue. The easiest is @samp{(&rest _)}
though it may not be what you need to do.

Other than the @samp{:after} advice, the @samp{:around} is common. You want to
use it to do something before and/or after the original function is
called. For example, I want the @code{fundamental-mode} to actually have a
hook, so I do this, which also happens to tie together what we have
covered in this chapter:

@lisp
(defvar my-fundamental-mode-hook nil
  "Normal hook for `fundamental-mode' (which is missing by default).")

(defun my-fundamental-mode-run-hook (&rest args)
  "Apply ARGS and then run `my-fundamental-mode-hook'."
  (apply args)
  (run-hooks 'my-fundamental-mode-hook))

(advice-add #'fundamental-mode :around #'my-fundamental-mode-run-hook)
@end lisp

After installing this advice, calling @code{fundamental-mode} will also run
the @code{my-fundamental-mode-run-hook}. Neat!

@findex apply
Check how the function @code{my-fundamental-mode-run-hook} makes use of the
@samp{args} it gets. The @code{(apply args)} effectively means ``call the
original function with its original arguments''. It works because the
function and its arguments are all part of one list, namely @samp{args},
where the symbol of the function is the first element and the
arguments to it are the remaining elements---exactly how a function is
called. Now, it so happens that @code{fundamental-mode} is called without
any arguments, but the code will still work even if @code{fundamental-mode}
is rewritten to have parameters. What matters is that the pattern of
@samp{&rest args} and then @code{(apply args)} is robust.

@cindex The apply function calls a quoted list as a function
@cindex The apply function prepends a given symbol to a list and evaluates the list
I like to think of @code{apply} as (i) ``here is a quoted list, remove the
quote and evaluate it'' or (ii) ``here is the symbol of a function and
then a quoted list of arguments, so append the symbol to the following
list, remove the quote, and evaluate it''. In other words, these two
examples will yield the same results (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}):

@lisp
(apply '(+ 1 1 1))
;; => 3

(apply #'+ '(1 1 1))
;; => 3
@end lisp

Because the function @code{my-fundamental-mode-run-hook} I was showing you
earlier has full control over when to make use of the @samp{args}, it gives
me the power to do something before I call @code{apply}. I do not need it
here, but you get the idea.

The advice mechanism is powerful, though you have to use it
judiciously. Emacs gives you the power. It is then up to you to act
responsibly. Otherwise, you will encounter nasty bugs and create
problems for others.

@node Evaluate some elements inside of a list
@chapter Evaluate some elements inside of a list

You already have an idea of how Emacs Lisp code looks like (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}).
You have a list that is either evaluated or taken as-is (@ref{Basics of how Lisp works, , Basics of how
Lisp works}). There is another case where a list should be selectively
evaluated or, more specifically, where it should be treated as data
instead of a function call with some elements inside of it still
subject to evaluation.

@cindex Declare a variable
In the following code block, I am defining a variable called
@code{my-greeting-in-greek}, which is a common phrase in Greek that
literally means ``health to you'' and is pronounced as ``yah sou''. Why
Greek? Well, you got the @code{lambda} that engendered this whole business
with Lisp, so you might as well get all the rest (@ref{When to use a named function or a lambda function})!

@lisp
(defvar my-greeting-in-greek "Γεια σου"
  "Basic greeting in Greek to wish health to somebody.")
@end lisp

@findex message
Now I want to experiment with the @code{message} function to better
understand how evaluation works. Let me start with the scenario of
quoting the list, thus taking it as-is:

@lisp
(message "%S" '(one two my-greeting-in-greek four))
;;=> "(one two my-greeting-in-greek four)"
@end lisp

The @code{message} function has the side effect of appending the message it
produces to the @samp{*Messages*} buffer (@ref{Side effect and return value}).
You can review the log this way. Now check the code we have here. You
will notice that the variable @code{my-greeting-in-greek} is not evaluated.
I get the symbol, the actual @code{my-greeting-in-greek}, but not the value
it represents. This is the expected result, because the entire list is
quoted and, ipso facto, everything inside of it is not evaluated. Now
pay attention to the next code block to understand how I can tell
Emacs that I want the entire list to still be quoted but for the
singular element @code{my-greeting-in-greek} to be evaluated. This means
that @code{my-greeting-in-greek} is replaced by its value while everything
else is taken as-is:

@lisp
(message "%S" `(one two ,my-greeting-in-greek four))
;; => "(one two \"Γεια σου\" four)"
@end lisp

@findex concat
@cindex Quasi quote an expression
@cindex Backtick for quasi quoting and the comma operator
The syntax here is special. Instead of a single quote, I am using the
backtick character or back quote or grave accent, to write an
expression that is ``quasi quoted''. The backtick behaves like the
single quote except for anything that is preceded by a comma. The
comma only has meaning inside of a quasi quoted list, otherwise you
get an error. The comma is an instruction to ``evaluate the thing that
follows''. It is written as a prefix without a space after it and
applies to the thing it is attached to. The ``thing'' that follows is
either a symbol or a list. The list can, of course, be a function call
of arbitrary complexity. Let me then use @code{concat} to greet a certain
person all while returning everything as a list:

@lisp
(message "%S" `(one two ,(concat my-greeting-in-greek " " "Πρωτεσίλαε") four))
;; => "(one two \"Γεια σου Πρωτεσίλαε\" four)"
@end lisp

Do not forget that you will get an error if you are not quoting this
list at all, because the first element @code{one} will be treated as the
symbol of a defined function, which must then be called with all other
elements as its arguments. Chances are that @code{one} is not defined as a
function in your current Emacs session or those arguments are not
meaningful to it, anyway. Plus, @code{two} and @code{four} will then have to
exist as variables, since they are not quoted either. Else more errors
ensue. By quasi quoting the list, we get the best of both worlds:
evaluate what we need and skip the evaluation of all the rest.

@cindex Splicing in general
Other than the comma operator, there is the @samp{,@@} (how is this even
pronounced? ``comma at'', perhaps?), which is notation for ``splicing''.
This is jargon in lieu of saying ``the return value is a list and I
want you to remove the outermost parentheses from it''. In effect, the
code that would normally return @samp{'(one two three)} now returns @samp{one
two three}. This difference may not make much sense in a vacuum,
though it does once you consider those elements as expressions that
should work in their own right, rather than simply be elements of a
quoted list. I will not provide an example here, as I think this is
best covered in the context of defining macros (@ref{Evaluation inside of a macro or special form}).

@findex list
Chances are you will not need to use the knowledge of selective
evaluation. It is more common in macros, though can be applied
anywhere. Be aware of it regardless, as there are scenaria where you
will, at the very least, want to understand what some code you depend
on is doing. Besides, when you write something like @samp{`(one ,two
,three)} you can alternatively call the @code{list} function like @samp{(list
'one two three)} to get the same results. Sometimes the backtick with
all its comma operators looks right while at others the @code{list} is more
appropriate. The way I approach this is in terms of style: what would
look more clean in the given context is the more appropriate option.
Mine is an aesthetic principle, if you will. In this example, I prefer
@samp{(list 'one two three)} over @samp{`(one ,two ,three)}: it has no special
syntax beside the basics of Lisp and is thus easier to reason about
(@ref{Basics of how Lisp works}).

Lastly, since I introduced you to some Greek words, I am now
considering you my potential friend. Here is a joke from when I was a
kid. I was trying to explain some event to my English instructor. As I
lacked the vocabulary to express myself, I resorted to the use of
Greek words. My instructor had a strict policy of only responding in
English, so she said ``It is all Greek to me''. Not knowing that her
answer is an idiom for ``I do not understand you'', I blithely replied,
``Yes, madame, Greek; me no speak England very best.'' I was not
actually a beginner at the time. I simply could not pass on the
opportunity to make fun of the situation. This illustrates how you
should remember to enjoy the time spent tinkering with Emacs. But
enough of that! Back to the elements of Emacs Lisp.

@node Evaluation inside of a macro or special form
@chapter Evaluation inside of a macro or special form

In the most basic case of Emacs Lisp code, you have lists (@ref{Basics of how Lisp works}).
Those are either evaluated or not (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}).
If you get a little more fancy, you have lists whose elements are
selectively evaluated (@ref{Evaluate some elements inside of a list}).
Sometimes, though, you come across a piece of code and cannot
understand why the normal rules of quoting and evaluation do not
apply. Before you see this in action, inspect a typical function call
that also involves the evaluation of a variable:

@lisp
(concat my-greeting-in-greek " " "Πρωτεσίλαε")
@end lisp

@findex concat
@cindex Evaluation inside of a function call
You encountered this code in the section about the evaluation of some
elements inside of a list. What you have here is a call to the
function @code{concat}, followed by three arguments. One of these arguments
is a variable, the @code{my-greeting-in-greek}. When this list is
evaluated, what Emacs actually does is to first evaluate the
arguments, including @code{my-greeting-in-greek}, in order to resolve their
respective values. Once it collects those it calls @code{concat} with them.
You can think of the entire operation as follows:

@itemize
@item
Here is a list.

@item
It is not quoted.

@item
So you should evaluate it.

@item
The first element is the name of the function.

@item
The remaining elements are arguments passed to that function.

@item
Check what the arguments are.

@item
Evaluate each of the arguments to get its value.

@item
Strings are self-evaluating (a string evaluates to itself), while
the @code{my-greeting-in-greek} is a variable that likely has some value
other than itself.

@item
You now have the value of each of the arguments, including the value
of the symbol @code{my-greeting-in-greek}.

@item
Call @code{concat} with all the values you got.
@end itemize

In other words, the following two yield the same results (assuming a
constant @code{my-greeting-in-greek}):

@lisp
(concat my-greeting-in-greek " " "Πρωτεσίλαε")

(concat "Γεια σου" " " "Πρωτεσίλαε")
@end lisp

@findex setq
This is predictable. It follows the basic logic of the single quote:
if a symbol is quoted, do not evaluate it and return it as-is,
otherwise evaluate it and return its value. Here
@code{my-greeting-in-greek} is not quoted, so it is evaluated. All clear!
But you will find plenty of cases where this expected pattern is
seemingly not followed. Consider this common scenario of using @code{setq}
to bind a symbol to the given value (i.e. set the value of a
variable):

@lisp
(setq my-test-symbol "Protesilaos of Cyprus")
@end lisp

@findex set
The above expression looks like a function call, meaning that (i) the
entire list is not quoted, (ii) the first element is the name of a
function, and (iii) the remaining elements are arguments passed to
that function. In a way, this is all true. Though you would then
expect the @code{my-test-symbol} to be treated as a variable, which would
be evaluated in place to return its result which would, in turn, be
the actual argument passed to the function. However, this is not how
@code{setq} works. The reason is that it is a so-called ``special form'' that
internally calls @code{set} while quoting the symbol it got, thus:

@lisp
(set 'my-test-symbol "Protesilaos of Cyprus")
@end lisp

@findex set
@findex setq
@findex defun
With @code{set} things are as expected. There is no magic happening behind
the scenes. The @code{setq}, then, is a convenience for the user to not
quote the symbol each time. Yes, this makes it a bit more difficult to
reason about it, though you get used to it and eventually it all makes
sense. Hopefully, you will have a sense of when you are dealing with
special forms. Those include @code{setq}, @code{defun}, @code{let}, and a few others.
Here is a function you have already seen in this book:

@lisp
(defun my-greet-person-from-country (name country)
  "Say hello to the person with NAME who lives in COUNTRY."
  (message "Hello %s of %s" name country))
@end lisp

If the normal rules of evaluation applied, then the list of parameters
should be quoted. Otherwise, you would expect @samp{(name country)} to be
interpreted as a function call with @code{name} as the symbol of the
function and @code{country} as its argument, which would also be a
variable. But this is not what is happening because @code{defun} will
internally treat that list of parameters as if it was quoted. Imagine
this:

@lisp
;; PSEUDO-CODE to illustrate how the `defun' special form could be
;; expressed if normal quoting was applied.
(PSEUDO-defun 'my-greet-person-from-country '(name country)
  "Say hello to the person with NAME who lives in COUNTRY."
  (message "Hello %s of %s" name country))
@end lisp

Now you can appreciate @code{defun} a little bit more.

@findex let
Another common scenario is with @code{let} (@ref{Control flow with @code{if-let*} and friends}).
Its general form is as follows:

@lisp
;; This is pseudo-code
(let LIST-OF-LISTS-AS-VARIABLE-BINDINGS
  BODY-OF-THE-FUNCTION)
@end lisp

The @samp{LIST-OF-LISTS-AS-VARIABLE-BINDINGS} is a list in which each
element is a list of the form @samp{(SYMBOL VALUE)}. Here is some actual
code:

@lisp
(let ((name "Protesilaos")
      (country "Cyprus"))
  (message "Hello %s of %s" name country))
@end lisp

Continuing with the theme of special forms, if @code{let} was a typical
function call, the @samp{LIST-OF-LISTS-AS-VARIABLE-BINDINGS} would have to
be quoted. Otherwise, it would be evaluated, in which case the first
element would be the name of the function. But that would return an
error, as the name of the function would correspond to another list,
the @samp{(name "Protesilaos")}, rather than a symbol. Things work fine
with @code{let} because it internally does the quoting of its
@samp{LIST-OF-LISTS-AS-VARIABLE-BINDINGS}. Behold the pseudo-code that
illustrates my point:

@lisp
(PSEUDO-let '((name "Protesilaos")
              (country "Cyprus"))
 (message "Hello %s of %s" name country))
@end lisp

@findex cl-loop
From a user perspective, there is no distinction between special forms
and Lisp macros. The former are implemented in C, as part of the
engine at the heart of Emacs. While Lisp macros are written in Emacs
Lisp, the same way as everything else you see in this book. In
practice, macros is how we define our own special form counterparts,
in the sense that macros can implement their own rules of evaluation.
A macro can even define its own mini-language, such that it looks
profoundly different from your average lisp expression. Depending on
how you feel about it, something like @code{cl-loop} will be a thing of
beauty or the bane of your existence (@ref{Pattern match with @code{pcase} and related}).

@findex use-package
Expect similar behaviour with many special forms as well as with
macros such as the popular @code{use-package}, which is used to configure
packages inside of your Emacs initialisation file. How each of those
macros works depends on the way it is designed. I will not delve into
the technicalities here, as I want the book to be useful long-term,
focusing on the principles rather than the implementation details that
might change over time. A cursory review of some @code{use-package}
declaration will suffice: you are not looking at your average Lisp
program and what you know may not even be valid syntax for this macro
(@ref{Basics of how Lisp works}).

@findex pp-macroexpand-last-sexp
@cindex Pretty print or expand a macro
To learn what a given macro expands to place the cursor at the end of
its closing parenthesis and call the command @code{pp-macroexpand-last-sexp}.
It will produce a new buffer showing the expanded Emacs Lisp code.
This is what is actually evaluated in the macro's stead.

@findex defmacro
@vindex default-directory
@cindex Defining macros
@cindex Splicing within a macro
With those granted, it is time to write a macro. This is like a
template, which empowers you to not repeat yourself. Syntactically, a
macro will most probably depend on the use of the backtick, the comma
operator, and the mechanics of splicing (@ref{Evaluate some elements inside of a list}).
Here is a simple scenario where we want to run some code in a
temporary buffer while setting the @code{default-directory} to the user's
home directory.

@lisp
(defmacro my-work-in-temp-buffer-from-home (&rest expressions)
  "Evaluate EXPRESSIONS in a temporary buffer with `default-directory' set to the user's home."
  `(let ((default-directory ,(expand-file-name "~/")))
     (with-temp-buffer
       (message "Running all expression from the `%s' directory" default-directory)
       ,@@expressions)))
@end lisp

@cindex The &rest keyword for function or macro parameters
In this definition, the @samp{&rest} keyword makes the following parameter
a list of arbitrary length. So you can pass any number of arguments to
it, all of which are collected into a single @samp{expressions} variable.
The judicious use of selective evaluation inside of a quasi quoted
list ensures that the macro will not be evaluated right now but only
when its expansion is called. We thus appreciate how the quote is, in
effect a ``do not evaluate now but pass it over to the next evaluation''
(@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}). The arguments given to
it will be placed where you have specified. Here is a call that uses
this macro:

@lisp
(progn
  (message "Now we are doing something unrelated to the macro")
  (my-work-in-temp-buffer-from-home
   (message "We do stuff inside the macro")
   (+ 1 1)
   (list "Protesilaos" "Cyprus")))
@end lisp

If you place the cursor at the closing parenthesis of
@code{my-work-in-temp-buffer-from-home}, you will be able to confirm what
it expands to by typing @kbd{M-x} (@code{execute-extended-command})
and then invoking the command @code{pp-macroexpand-last-sexp}. This is what
I get out of the macroexpansion:

@lisp
(let ((default-directory "/home/prot/"))
  (with-temp-buffer
    (message "Running all expression from the `%s' directory" default-directory)
    (message "We do stuff inside the macro")
    (+ 1 1)
    (list "Protesilaos" "Cyprus")))
@end lisp

Piecing it together with the rest of the code in its context, I arrive
at the following:

@lisp
(progn
  (message "Now we are doing something unrelated to the macro")
  (let ((default-directory "/home/prot/"))
    (with-temp-buffer
      (message "Running all expression from the `%s' directory" default-directory)
      (message "We do stuff inside the macro")
      (+ 1 1)
      (list "Protesilaos" "Cyprus"))))
@end lisp

With this example in mind, consider Elisp macros to be a way of saying
``this little thing here helps me express this larger procedure more
succinctly, while the actual code that runs is still that of the
latter''.

The above macro I wrote has its body start with a backtick, so you do
not get to appreciate the nuances of evaluation within it. Let me show
you this other approach, instead, where I write a macro that lets me
define several almost identical interactive functions (@ref{Make your interactive function also work from Lisp calls}).

@lisp
(defmacro my-define-command (name &rest expressions)
  "Define command with specifier NAME that evaluates EXPRESSIONS."
  (declare (indent 1))
  (unless (symbolp name)
    (error "I want NAME to be a symbol"))
  (let ((modifined-name (format "modified-version-of-%s" name)))
    `(defun ,(intern modifined-name) ()
       (interactive)
       ,(message "The difference between `%s' and `%s'" modifined-name name)
       ,@@expressions)))
@end lisp

The @code{my-define-command} can be broadly divided into two parts: (i)
what gets evaluated outright and (ii) what gets expanded for further
evaluation at a later point. The latter part starts with the backtick.
This distinction is important when we call the macro, because the
former part will be executed outright: if we hit the error, the macro
will never expand the rest of the form which includes the
@samp{EXPRESSIONS}. Try @code{pp-macroexpand-last-sexp} with the following to
see what I mean. For your convenience, I include the macro expansions
right below each case.

@lisp
(my-define-command first-demo
  (message "This is what my function does")
  (+ 1 10)
  (message "And this"))
;; =>
;;
;; (defun modified-version-of-first-demo nil
;;   (interactive)
;;   "The difference between ‘modified-version-of-first-demo’ and ‘first-demo’"
;;   (message "This is what my function does")
;;   (+ 1 10)
;;   (message "And this"))


(my-define-command second-demo
  (list "Protesilaos" "Cyprus")
  (+ 1 1)
  (message "Arbitrary expressions here"))
;; =>
;;
;; (defun modified-version-of-second-demo nil
;;   (interactive)
;;   "The difference between ‘modified-version-of-second-demo’ and ‘second-demo’"
;;   (list "Protesilaos" "Cyprus")
;;   (+ 1 1)
;;   (message "Arbitrary expressions here"))


(my-define-command "error scenario"
  (list "Will" "Not" "Reach" "This")
  (/ 2 0))
;; => ERROR...
@end lisp

Do you need macros? Not always, though there will be cases where a
well-defined macro makes your code more elegant and, indeed, more
powerful. Experience will teach you when a macro is the right tool for
the job. What matters here is that you have a sense of how evaluation
works so that you do not get confused by all those parentheses,
quotes, quasi quoting, and splicing. Otherwise, you might expect
something different to happen than what you actually get. Use
@code{pp-macroexpand-last-sexp} meticulously and try to reason about what
it shows you.

@node Mapping over a list of elements
@chapter Mapping over a list of elements

@findex while
@findex mapcar
@findex mapc
@findex dolist
@findex seq-filter
@findex seq-remove
A common routine in programming is to work through a list of items and
perform some computation on each of them. Emacs Lisp has the generic
@code{while} loop, as well as a whole range of more specialised functions
to map over a list of elements, such as @code{mapcar}, @code{mapc}, @code{dolist},
@code{seq-filter}, @code{seq-remove}, and many more. Depending on what you are
doing, you map through elements with the intent to produce some side
effect and/or to test for a return value (@ref{Side effect and return value}).
I will show you some examples and let you decide which is the most
appropriate tool for the task at hand.

@findex mapcar
@cindex Accumulating results of a map
Starting with @code{mapcar}, it applies a function to each element of a
list. It then takes the return value at each iteration and collects it
into a new list. This is the return value of @code{mapcar} as a whole. In
the following code block, I use @code{mapcar} over a list of numbers to
increment them by @samp{10} and return a new list of the incremented
numbers.

@lisp
(mapcar
 (lambda (number)
   (+ 10 number))
 '(1 2 3 4 5))
;; => (11 12 13 14 15)
@end lisp

In the code block above, I am using a @code{lambda}, else an anonymous
function (@ref{When to use a named function or a lambda function}). Here is
the same code, but with an eponymous function, i.e. a named function:

@lisp
(defun my-increment-by-ten (number)
  "Add 10 to NUMBER."
  (+ 10 number))

(mapcar #'my-increment-by-ten '(1 2 3 4 5))
;; => (11 12 13 14 15)
@end lisp

Notice that here we quote the eponymous function (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}).

@findex mapcar
@findex mapc
@cindex Mapping only for side effects
The @code{mapcar} collects the return values into a new list. Sometimes
this is useless. Suppose you want to evaluate a function that saves
all unsaved buffers which visit a file. In this scenario, you do not
care about accumulating the results: you just want the side effect of
saving the buffer outright. To this end, you may use @code{mapc}, which
always returns the list it operated on:

@lisp
(mapc
 (lambda (buffer)
   (when (and (buffer-file-name buffer)
              (buffer-modified-p buffer))
     (save-buffer)))
 (buffer-list))
@end lisp

@findex dolist
An alternative to the above is @code{dolist}, which is used for side
effects but always returns @code{nil}:

@lisp
(dolist (buffer (buffer-list))
  (when (and (buffer-file-name buffer)
             (buffer-modified-p buffer))
    (save-buffer)))
@end lisp

You will notice that the @code{dolist} is a macro, so some parts of it seem
to behave differently than with basic lists and the evaluation rules
that apply to them (@ref{Basics of how Lisp works}). This is a matter of
getting used to how the code is expressed (@ref{Evaluation inside of a macro or special form}).

@cindex When do use dolist over mapc and vice versa
@findex dolist
@findex mapc
When to use a @code{dolist} as opposed to a @code{mapc} is largely a matter of
style. If you are using a named function, a @code{mapc} looks cleaner to my
eyes. Otherwise a @code{dolist} is easier to read. Here is my approach with
some pseudo-code:

@lisp
;; I like this:
(mapc #'NAMED-FUNCTION LIST)

;; I also like a `dolist' instead of a `mapc' with a `lambda':
(dolist (element LIST)
  (OPERATE-ON element))

;; I do not like this:
(mapc
 (lambda (element)
   (OPERATE-ON element))
 LIST)
@end lisp

@cindex mapc or dolist can also be used to accumulate results
While @code{dolist} and @code{mapc} are for side effects, you can still employ
them in the service of accumulating results, with the help of @code{let}
and related forms (@ref{Control flow with @code{if-let*} and friends}). Depending
on the specifics, this approach may make more sense than relying on a
@code{mapcar}. Here is an annotated sketch:

@lisp
;; Start with an empty list of `found-strings'.
(let ((found-strings nil))
  ;; Use `dolist' to test each element of the list '("Protesilaos" 1 2 3 "Cyprus").
  (dolist (element '("Protesilaos" 1 2 3 "Cyprus"))
    ;; If the element is a string, then `push' it to the `found-strings', else skip it.
    (when (stringp element)
      (push element found-strings)))
  ;; Now that we are done with the `dolist', return the new value of `found-strings'.
  found-strings)
;; => ("Cyprus" "Protesilaos")


;; As above but reverse the return value, which makes more sense:
(let ((found-strings nil))
  (dolist (element '("Protesilaos" 1 2 3 "Cyprus"))
    (when (stringp element)
      (push element found-strings)))
  (nreverse found-strings))
;; => ("Protesilaos" "Cyprus")
@end lisp

@cindex mapcar will also accumulate nil values
For completeness, the previous example would have to be done as
follows with the use of @code{mapcar}:

@lisp
(mapcar
 (lambda (element)
   (when (stringp element)
     element))
 '("Protesilaos" 1 2 3 "Cyprus"))
;; => ("Protesilaos" nil nil nil "Cyprus")


(delq nil
      (mapcar
       (lambda (element)
         (when (stringp element)
           element))
       '("Protesilaos" 1 2 3 "Cyprus")))
;; => ("Protesilaos" "Cyprus")
@end lisp

@cindex seq-filter instead of removing nil from what mapcar returns
Because @code{mapcar} happily accumulates all the return values, it returns
a list that includes @code{nil}. If you wanted that, you would probably not
even bother with the @code{when} clause there. The @code{delq} is thus applied
to the return value of the @code{mapcar} to delete all the instances of
@code{nil}. Now compare this busy work to @code{seq-filter}:

@lisp
(seq-filter #'stringp '("Protesilaos" 1 2 3 "Cyprus"))
;; => ("Protesilaos" "Cyprus")
@end lisp

The @code{seq-filter} is the best tool when all you need is to test if the
element satisfies a predicate function and then return that element.
But you cannot return something else. Whereas @code{mapcar} will take any
return value without complaints, such as the following:

@lisp
(delq nil
      (mapcar
       (lambda (element)
         (when (stringp element)
           ;; `mapcar' accumulates any return value, so we can change
           ;; the element to generate the results we need.
           (upcase element)))
       '("Protesilaos" 1 2 3 "Cyprus")))
;; => ("PROTESILAOS" "CYPRUS")

(seq-filter
 (lambda (element)
   (when (stringp element)
     ;; `seq-filter' only returns elements that have a non-nil return
     ;; value here, but it returns the elements, not what we return
     ;; here.  In other words, this `lambda' does unnecessary work.
     (upcase element)))
 '("Protesilaos" 1 2 3 "Cyprus"))
;; => ("Protesilaos" "Cyprus")
@end lisp

@findex find-library
@findex seq-take
@findex seq-find
@findex seq-union
@findex shortdoc
@cindex Visit the source code of a file
@cindex Shortdoc for lists and sequences
How you go about mapping over a list of elements will depend on what
you are trying to do. There is no one single function that does
everything for you. Understand the nuances and you are good to go. Oh,
and do look into the built-in @code{seq} library (use @kbd{M-x}
(@code{execute-extended-command}), invoke @code{find-library}, and then search
for @code{seq}). You are now looking at the source code of
@file{seq.el}: it defines plenty of functions like @code{seq-take},
@code{seq-find}, @code{seq-union}. Another way is to invoke the command
@code{shortdoc} and read about the documentation groups @samp{list} as well as
@samp{sequence}.

@node The match data of the last search
@chapter The match data of the last search

@findex match-data
@findex match-beginning
@findex match-string
@findex re-search-forward
@findex looking-at
@findex string-match
As you work with Emacs Lisp, you will encounter the concept of ``match
data'' and the concomitant functions @code{match-data}, @code{match-beginning},
@code{match-string}, and so on. These refer to the results of the last
search, which is typically performed by the functions @code{looking-at},
@code{re-search-forward}, @code{string-match}, and related. Each time you
perform a search, the match data gets updated. Be mindful of this
common side effect (@ref{Side effect and return value}). If you forget about
it, chances are your code will not do the right thing.

@cindex Get match data without text properties
In the following code block, I define a function that performs a
search in the current buffer and returns a list of match data without
text properties, where relevant (@ref{Text has its own properties}).

@lisp
(defun my-get-match-data (regexp)
  "Search forward for REGEXP and return its match data, else nil."
  (when (re-search-forward regexp nil t)
    (list
     :beginning (match-beginning 0)
     :end (match-end 0)
     :string (match-string-no-properties 0))))
@end lisp

You may then call it with a string argument, representing an Emacs
Lisp regular expression:

@lisp
(my-get-match-data "Protesilaos.*Cyprus")
@end lisp

If the regular expression matches, then you get the match data. Here
is some sample text:

@example
Protesilaos lives in the mountains of Cyprus.
@end example

Place the cursor before that text and use @kbd{M-:}
(@code{eval-expression}) to evaluate @code{my-get-match-data} with the regexp I
show above. You will get a return value, as intended.

@cindex Preserve the last position of the cursor
@findex save-excursion
@findex point
The way @code{my-get-match-data} is written, it does two things: (i) it has
the side effect of moving the cursor to the end of the text it found
and (ii) it returns a list with the match data I specified. There are
many scenaria where you do not want the aforementioned side effect:
the cursor should stay where it is. As such, you can wrap your code in
a @code{save-excursion} (@ref{Switching to another buffer window or narrowed state, , Switching to another buffer@comma{} window@comma{} or narrowed state}):
it will do what it must and finally restore the @code{point} (@ref{Run some code or fall back to some other code}):

@lisp
(defun my-get-match-data (regexp)
  "Search forward for REGEXP and return its match data, else nil."
  (save-excursion ; we wrap our code in a `save-excursion' to inhibit the side effect
    (when (re-search-forward regexp nil t)
      (list
       :beginning (match-beginning 0)
       :end (match-end 0)
       :string (match-string-no-properties 0)))))
@end lisp

@cindex Preserve the last match data
@findex save-match-data
If you evaluate this version of @code{my-get-match-data} and then retry the
function call I had above, you will notice how you get the expected
return value without the side effect of the cursor moving to the end
of the matching text. In practice, this is a useful tool that may be
combined with @code{save-match-data}. Imagine you want to do a search
forward inside of another search you are performing, such as to merely
test if there is a match for a regular expression in the context, but
need to inhibit the modification of the match data you planned to
operate on. As such:

@lisp
(defun my-get-match-data-with-extra-check (regexp)
  "Search forward for REGEXP followed by no spaces and return its match data, else nil."
  (save-excursion
    (when (and (re-search-forward regexp nil t)
               (save-match-data (not (looking-at "[\s\t]+"))))
      ;; Return the match data of the first search.  The second one
      ;; which tests for spaces or tabs is just an extra check, but we
      ;; do not want to use its match data, hence the `save-match-data'
      ;; around it.
      (list
       :beginning (match-beginning 0)
       :end (match-end 0)
       :string (match-string-no-properties 0)))))
@end lisp

Evaluate the function @code{my-get-match-data-with-extra-check} and then
call it with @kbd{M-:} (@code{eval-expression}) to test that it
returns a non-@code{nil} value with the second example below, but not the
first one. This is the expected outcome.

@lisp
(my-get-match-data-with-extra-check "Protesilaos.*Cyprus")
;; => nil


;; Protesilaos, also known as "Prot", lives in the mountains of Cyprus   .

(my-get-match-data-with-extra-check "Protesilaos.*Cyprus")
;; => (:beginning 41988 :end 42032 :string "Protesilaos lives in the mountains of Cyprus")


;; Protesilaos lives in the mountains of Cyprus.
@end lisp

@findex string-match-p
If all you want is to check for a regular expression in the buffer,
you wrap your search in a @code{save-match-data}. If, on the other hand,
you need to test for the presence of a regular expression in a string,
without modifying---or indeed wanting to access---the match, then you
can rely on the function @code{string-match-p}. Given that much of the work
you do in Emacs involves buffers, it is important to familiarise
yourself with how match data work (@ref{Buffers as data}). Another use-case
for match data is if you are writing fontification rules for a major
or minor mode, though that is probably more of a niche requirement
(@ref{What are major and minor modes}).

@node Switching to another buffer window or narrowed state
@chapter Switching to another buffer, window, or narrowed state

As you use Emacs Lisp to do things programmatically, you encounter
cases where you need to move away from where you are in order to
perform some computation. You may have to switch to another buffer,
change to the window of a given buffer, or even modify what is visible
in the buffer you are editing. At all times, this involves one or more
side effects which, most probably, should be undone once your program
concludes its operations (@ref{Side effect and return value}).

@cindex Restore the point
@findex point
@findex save-excursion
Perhaps the most common case is to restore the @code{point}. You have some
code that moves back or forth in the buffer to perform a match for a
given piece of text. But then, you need to leave the cursor where it
originally was, otherwise the user will lose their orientation. Wrap
your code in a @code{save-excursion} and you are good to go, as I show
elsewhere (@ref{The match data of the last search}):

@lisp
(save-excursion ; restore the `point' after you are done
  MOVE-AROUND-IN-THIS-BUFFER)
@end lisp

@cindex Restore the selected window
@findex save-window-excursion
@findex select-window
Same principle for @code{save-window-excursion}, which allows you to select
another window, such as with @code{select-window}, move around in its
buffer, and then restore the windows as they were:

@lisp
(save-window-excursion
  (select-window SOME-WINDOW)
  MOVE-AROUND-IN-THIS-BUFFER)
@end lisp

@cindex Restore the narrowing state
@findex save-restriction
@findex point-min
@findex point-max
@findex widen
@findex narrow-to-region
@findex org-narrow-to-subtree
The @code{save-restriction} allows you to restore the current visibility
state of the buffer. This pertains to whether the buffer is narrowed
or not and the exact boundaries of the narrowed view. When the buffer
is narrowed, the functions @code{point-min} and @code{point-max} return the
minimum and maximum positions within those boundaries. Your program
may need to work outside of them, yet still respect them after it is
done. Same principle if you need to narrow to some portion of the
buffer to better target a piece of text. You may then choose to either
@code{widen} or @code{narrow-to-region} (and related commands like
@code{org-narrow-to-subtree}), do what you must, and then restore the
buffer to its original state.

@lisp
;; Here we assume that we start in a widened state.  Then we narrow to
;; the current Org heading to get all of its contents as one massive
;; string.  Then we widen again, courtesy of `save-restriction'.
(save-restriction
  (org-narrow-to-subtree)
  (buffer-string))
@end lisp

Depending on the specifics, you will want to combine the
aforementioned. Beware that the documentation of @code{save-restriction}
tells you to use @code{save-excursion} as the outermost call. Other than
that, you will also find cases that require a different approach to
perform some conditional behaviour (@ref{Run some code or fall back to some other code}).

At any rate, because Emacs effectively is one large mutable state, you
have to write code that does not produce permanent side effects that
are not necessary. Guard against them and you should be good to go
(@ref{Emacs as a computing environment}).

@node Basic control flow with @code{if} @code{cond} and others
@chapter Basic control flow with @code{if}, @code{cond}, and others

@findex defun
@findex forward-line
You do not need any conditional logic to perform basic operations. For
example, if you write a command that moves 15 lines down, it will
naturally stop at the end of the buffer when it cannot move past the
number you specified. Using @code{defun}, you write an interactive function
(i.e. a ``command'') to unconditionally move down 15 lines using
@code{forward-line} internally (@ref{Basics of how Lisp works}).

@lisp
(defun my-15-lines-down ()
  "Move at most 15 lines down."
  (interactive)
  ;; Give it a negative number to move in the opposite direction.
  (forward-line 15))
@end lisp

@findex if
@findex when
@findex unless
@findex cond
@findex and
@findex or
@cindex Control flow
The @code{my-15-lines-down} is about as simple as it gets: it wraps around
a basic function and passes to it a fixed argument, in this case the
number @samp{15}. Use @kbd{M-x} (@code{execute-extended-command}) and then
call this command by its name. It works! Things get more involved as
soon as you decide to perform certain actions only once a given
condition is met. This ``control flow'' between different branches of a
logical sequence is expressed with @code{if}, @code{when}, @code{unless}, and @code{cond},
among others. Depending on the specifics of the case, @code{and} as well as
@code{or} may suffice.

@findex eobp
@findex string-match-p
@findex stringp
@cindex Predicate functions
How about you make your @code{my-15-lines-down} a bit smarter? When it is
at the absolute end of the buffer, have it move 15 lines up. Why?
Because this is a demonstration, so why not? The predicate function
that tests if the point is at the end of the buffer is @code{eobp}. A
``predicate'' is a function that returns true, technically non-@code{nil},
when its condition is met, else it returns @code{nil} (@ref{Side effect and return value}).
As for the weird name, the convention in Emacs Lisp is to end
predicate functions with the @samp{p} suffix: if the name of the function
consists of multiple words, typically separated by dashes, then the
predicate function is named @samp{NAME-p}, like @code{string-match-p}, otherwise
it is @samp{NAMEp}, like @code{stringp}.

@lisp
(defun my-15-lines-down-or-up ()
  "Move at most 15 lines down or go back if `eobp' is non-nil."
  (interactive)
  (if (eobp)
      (forward-line -15)
    (forward-line 15)))
@end lisp

Evaluate this function, then type @kbd{M-x} (@code{execute-extended-command})
and invoke @code{my-15-lines-down-or-up} to get a feel for it. Below is a
similar idea, which throws and error and exits what it was doing if
@code{eobp} returns non-@code{nil}:

@lisp
(defun my-15-lines-down-or-error ()
  "Throw an error if `eobp' returns non-nil, else move 15 lines down."
  (interactive)
  (if (eobp)
      (error "Already at the end; will not move further")
    (forward-line 15)))
@end lisp

@cindex Indentation in Emacs Lisp
A peculiarity of Emacs Lisp is how indentation is done. Just mark the
code you have written and type @kbd{TAB}: Emacs will take care to
indent it the way it should be done. Do not leave parentheses on their
own line. Put them at the end of a balanced expression, as you have
seen in all my examples. In the case of the @code{if} statement, the ``then''
part is further in than the ``else'' part of the logic. There is no
special meaning to this indentation: you could write everything on a
single line like @samp{(if COND THIS ELSE)}, which looks like your typical
list, by the way (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}).

What the indentation does is help you identify imbalances in your
parentheses. If the different expressions all line up in a way that
looks odd, then you are most probably missing a parenthesis or have
too many of them. Generally, expressions at the same level of depth
will all line up the same way. Those deeper in will have more
indentation, and so on. Experience will allow you to spot mistakes
with mismatching parentheses. But even if you do not identify them,
you will get an error eventually. Rest assured!

The way @code{if} is written is like a function that takes two or more
arguments (@ref{Evaluation inside of a macro or special form}). The ``or
more'' counts as part of the ``else'' logic. As such, @samp{(if COND THIS)}
has no ``else'' consequence, while @samp{(if COND THIS ELSE1 ELSE2 ELSE3)}
will run @samp{ELSE1}, @samp{ELSE2}, and @samp{ELSE3} in order as part of the ``else''
branch. Here is how this looks once you factor in proper indentation:

@lisp
(if COND
    THIS
  ELSE1
  ELSE2
  ELSE3)
@end lisp

@findex progn
Now what if the @samp{THIS} part needs to be more than one function call?
Elisp has the @code{progn} form, which you can use to wrap function calls
and pass them as a single argument. Putting it all together, your code
will now look like this:

@lisp
(if COND
    (progn
      THIS1
      THIS2
      THIS3)
  ELSE1
  ELSE2
  ELSE3)
@end lisp

The else clause does not need a @code{progn} because internally it is
functionally equivalent to using a @samp{&rest} for the arguments. You may
remember some of the examples I demonstrated with @samp{&rest} (@ref{Hooks and the advice mechanism}).
In short, it will automatically collect all arguments into a single
list. But because we can only have one @samp{&rest} parameter, the first
argument passed to @code{if} cannot be done the same as the else. Besides,
how would we be able to disambiguate something like this?

@lisp
(if COND ONE TWO THREE)
@end lisp

Without knowing where the arguments start and end, we cannot have a
reliable way forward. Whereas this is clear:

@lisp
(if COND (progn ONE TWO) THREE)
@end lisp

This would also work, but is unnecessary:

@lisp
(if COND (progn ONE TWO) (progn THREE FOUR))

;; Same as above because of how there is a de facto &rest for the "else" consequences
(if COND (progn ONE TWO) THREE FOUR)
@end lisp

@findex when
If you do not need the ``else'' part, use @code{when} to express your
intention. Internally, this is a macro which actually stands for @samp{(if
COND (progn EXPRESSIONS))}, where @samp{EXPRESSIONS} is one or more
expressions. A @code{when} looks like this:

@lisp
(when COND
  THIS1
  THIS2
  THIS3)
@end lisp

I personally always opt for @code{when} instead of writing an @code{if} without
an ``else'' branch, because this way I am clear about what I am trying
to do. When I look back at my code, I do not need to double-check
every @code{if} statement to confirm that it is balanced the way it ought
to.

@findex unless
Similarly, the @code{unless} has the meaning of @samp{(when (not COND)
EXPRESSIONS)}. It, too, is a macro that expands to an @code{if} statement
and, again, I rely on it whenever I want to make my intent clear:

@lisp
(unless COND
  THIS1
  THIS2
  THIS3)
@end lisp

@findex and
@findex or
When the condition you are testing for has multiple parts, you can
rely on @code{and} as well as @code{or}:

@lisp
(when (or THIS THAT)
  EXPRESSIONS)

(when (and THIS THAT)
  EXPRESSIONS)

(when (or (and THIS THAT) OTHER)
  EXPRESSIONS)
@end lisp

@cindex Use the or/and without an if/when/unless around them
Depending on what you are doing, you may not even need to write
anything more than @code{and} or @code{or}. For example, suppose you want to
express the logic of "if something is true, return it, else return an
error. You may write this using an @code{if}, but an @code{or} will also do,
thus:

@lisp
;; Return THIS if it is non-nil
(if THIS
    THIS
  (error "The THIS cannot be nil"))

;; This is practically the same as above
(or THIS
    (error "The THIS cannot be nil"))
@end lisp

Like @code{or}, @code{and} can also do the same trick:

@lisp
;; These are practically the same.
(when (and THIS THAT)
  (FUNCTION-FOR THIS THAT))

(and THIS
     THAT
     (FUNCTION-FOR THIS THAT))
@end lisp

@findex if
@findex when
@findex or
@findex and
@findex cond
Depending on the specifics of the case, the combination of multiple
@code{if}, @code{when}, @code{or}, @code{and} will look awkward. You can break down the
logic into distinct conditions, which are tested in order from top to
bottom, using @code{cond}. The way @code{cond} is written is as a list of lists,
which do not need quoting because @code{cond} is a special form (@ref{Evaluation inside of a macro or special form}).
In abstract, it looks like this:

@lisp
(cond
 (CONDITION1
  CONSEQUENCES1)
 (CONDITION2
  CONSEQUENCES2)
 (CONDITION3
  CONSEQUENCES3)
 (t
  CONSEQUENCES-FALLBACK))
@end lisp

Each of the consequences can be any number of expressions, like you
saw above with @code{when} or the @code{if COND (progn EXPRESSIONS)} pattern.
This is a toy function to show how @code{cond} behaves:

@lisp
(defun my-toy-cond (argument)
  "Return a response depending on the type of ARGUMENT."
  (cond
   ((and (stringp argument)
         (string-blank-p argument))
    (message "You just gave me a blank string; try harder!"))
   ((stringp argument)
    (message "I see you can do non-blanks string; I call that progress."))
   ((null argument)
    (message "Yes, the nil is an empty list like (), but do not worry about it"))
   ((listp argument)
    (message "Oh, I see you are in the flow of using lists!"))
   ((symbolp argument)
    (message "What's up with the symbols, mate?"))
   ((natnump argument)
    (message "I fancy those natural numbers!"))
   ((numberp argument)
    (message "You might as well be a math prodigy!"))
   (t
    (message "I have no idea what type of thing your argument `%s' is" argument))))
@end lisp

I want you to evaluate it and pass it different arguments to test what
it does (@ref{Evaluate Emacs Lisp}). Here are two examples:

@lisp
(my-toy-cond "")
;; => "You just gave me a blank string; try harder!"

(my-toy-cond '(1 2 3))
;; => "Oh, I see you are in the flow of using lists!"
@end lisp

All of the above are common in Emacs Lisp. Another powerful macro is
@code{pcase}, which we will consider separately due to its particularities
(@ref{Pattern match with @code{pcase} and related}).

@node Control flow with @code{if-let*} and friends
@chapter Control flow with @code{if-let*} and friends

@cindex Let bind variables in the current scope
@cindex The lexical scope
@findex let
@findex let*
A function may need to process data that is local to it; data that is
located in the context of the function, else in its ``lexical scope''.
This means that whatever variables or values thereof should not be
exposed to the environment outside of the function. The @code{let} and
@code{let*} create and bind variables that are available only within their
scope, else the @samp{BODY} of the @code{let}. These bindings can be arbitrary
new symbols or existing symbols with a new value. Those will take
precedence over the value of the same variable outside of this lexical
scope. Again, you will notice how Emacs is consistent about the
principle of the specific/local taking precedence over the
generic/global (@ref{What are major and minor modes}). As such:

@lisp
(let BINDINGS
  BODY)

(let ((variable1 value1)
      (variable2 value2))
  BODY)
@end lisp

The @samp{BINDINGS} is a list of lists, which does not need to be quoted
(@ref{Evaluation inside of a macro or special form}). While @samp{BODY} consists
of one or more expressions, which I have also named @samp{EXPRESSIONS}
elsewhere in this book. The difference between @code{let} and @code{let*}
(pronounced ``let star'') is that the latter makes earlier bindings
available to later bindings. Like this:

@lisp
;; This works because `greeting' can access `name' and `country',
;; courtesy of `let*':
(let* ((name "Protesilaos")
       (country "Cyprus")
       (greeting (format "Hello %s of %s" name country)))
  (DO-STUFF-WITH greeting))

;; But this fails...
(let ((name "Protesilaos")
      (country "Cyprus")
      (greeting (format "Hello %s of %s" name country)))
  (DO-STUFF-WITH greeting))
@end lisp

Sometimes what you want to do is create those bindings if---and only
if---they are all non-@code{nil}. If their value is @code{nil}, then they are
useless to you, in which case you do something else (@ref{Basic control flow with @code{if} @code{cond} and others, , Basic control flow with @code{if}@comma{} @code{cond}@comma{} and others}).
Values may or may not be @code{nil} when you are creating a binding with
the return value of a function call or some other variable. You could
always write code like this:

@lisp
(let ((variable1 (SOME-FUNCTION SOME-ARGUMENT))
      (variable2 (OTHER-FUNCTION OTHER-ARGUMENT)))
  (if (and variable1 variable2) ; simply test both for non-nil
      THIS
    ELSE))
@end lisp

@findex if-let*
But you can do the same with @code{if-let*}, where the @samp{THIS} part runs
only if all the bindings are non-@code{nil}:

@lisp
(if-let* ((variable1 (SOME-FUNCTION SOME-ARGUMENT))
          (variable2 (OTHER-FUNCTION OTHER-ARGUMENT)))
    THIS
  ELSE)
@end lisp

@findex when-let*
The @code{when-let*} is the same as @code{when}, meaning that it has no ``else''
logic. If one of its bindings is @code{nil}, then the whole @code{when-let*}
returns @code{nil} immeditately.

@cindex The if-let* and when-let* bindings have an implicit AND logic
The bindings of both @code{if-let*} and @code{when-let*} have an implied @code{and}
logic to them, exactly because they do not accept a @code{nil} value: as
soon as a @code{nil} is returned, they are aborted. Concretely, if a
@code{if-let*} has three bindings and the second is @code{nil}, the third will
never be bound to what you expect. In the following example, the
@code{if-let*} has the third binding of @samp{(country "Cyprus")} which,
however, is not established because @code{if-let*} exits at the @code{nil} it
gets from its second binding. Consequently, the @samp{ELSE} branch of the
logic get @code{nil} out of @code{country} instead of what we thought we were
assigning it to.

@lisp
(if-let* ((name "Protesilaos")
          (nickname nil)
          (country "Cyprus"))
    (message "This does not run")
  (message "The country is %s" country))
;; => "The country is nil"
@end lisp

Remember this implicit @code{and} for the @code{if-let*} and @code{when-let*}
bindings, otherwise your code will not do what you expect.

As you dig deeper into the Emacs Lisp ecosystem, you will come across
uses of @code{if-let*} or @code{when-let*} that (i) create multiple bindings
like @code{let} or @code{let*} but (ii) also call a predicate function to test
if they should continue with the @samp{THIS} part of their logic. Remember
that @code{if-let*} goes straight to @samp{ELSE} if one of its bindings returns
@code{nil}, while @code{when-let*} exits immediately and returns @code{nil}. Consider
this example:

@lisp
(if-let* ((variable1 (SOME-FUNCTION SOME-ARGUMENT))
          ;; The _ signifies intent: "do not bind this; I only care
          ;; about the return value being non-nil".  What we are doing
          ;; here is test if `variable1' is a string: if it is, we
          ;; continue with the bindings, otherwise we move to the ELSE
          ;; part of the code and thus refrain from binding
          ;; `variable2' to whatever it would otherwise be bound to.
          (_ (stringp variable1))
          (variable2 (OTHER-FUNCTION OTHER-ARGUMENT)))
    THIS
  ELSE)
@end lisp

I personally enjoy using @code{if-let*} and @code{when-let*}. They have the same
syntax as @code{let*}, which means that I do not need to remember the
intricacies of yet another Lisp macro. Plus, they express intent which
is always good as a way of making the code self-evident or, at least,
easier to reason about. Ultimately though, there is no inherently
superior way of doing things. It is a matter of using the right tool
for the task at hand. Sometimes you want the bindings to be created,
even if their value is @code{nil}, in which case @code{let} or @code{let*} are what
you need. Choose what makes sense.

@node Autoloading symbols
@chapter Autoloading symbols

@vindex load-path
In general, Emacs knows the functions and variables it has evaluated
(@ref{Evaluate Emacs Lisp}). Though it is also aware of all symbols that are
marked for automatic loading inside the @code{load-path}. The @code{load-path}
is a variable whose value is a list of directories. Each of those
directories is expected to contain Elisp files. Those are specified
with the @samp{.el} file type extension, such as @file{my-hello.el}.
An Elisp file may choose to mark for automatic loading some of the
symbols it defines. When a symbol is marked for automatic loading,
also known as an ``autoload'', Emacs will do the following when that
symbol is called for evaluation:

@itemize
@item
If the file with the given symbol's source code have been loaded,
then Emacs will simply evaluate the symbol in the given call.

@item
If the file has not been loaded, Emacs will first load and evaluate
the file, and then evaluate the symbol from where it is being
called.
@end itemize

@cindex Lazy loading Emacs Lisp code
In this way, we can write programs that load their source code only
when needed. Such is a concept that is also described by members of
the community as ``lazy loading''. The idea is that we do not need to
evaluate potentially millions of lines of code as soon as we launch
Emacs. Most of that is likely not needed each time. But when we wish
to do something with one of those definitions, its code base becomes
available to us.

Programs will typically have functions that are there purely for
internal purposes and others which are meant to be called by the user.
The latter may be autoloaded. Though the programmer must take care to
autoload only what is the actual point of entry to the package and not
every single symbol that may be called at some point. For example, the
built-in @file{ielm.el} autoloads the command @code{ielm}. This makes
perfect sense. If we want to start using that package, we will do it
by invoking @code{ielm}. The program defines many other commands, such as
@code{ielm-return}. Those only work inside of the IELM shell. It thus is
wrong to autoload them and, indeed, @code{ielm-return} and all related
commands are not autoloaded. Compare the differences by doing the
following:

@findex find-library
@itemize
@item
Call the command @code{find-library}. It will ask you for a file anywhere
in the @code{load-path} that contains Emacs Lisp.

@item
Select @samp{ielm} to visit the file @file{ielm.el}.

@item
Search for @code{(defun ielm (}. Notice that the definition of this
command has a special @samp{;;;###autoload} directive right above it.

@item
Now search for @code{(defun ielm-return}. This one does not have the
@samp{;;;###autoload}.
@end itemize

In this case, @code{ielm} is declared for autoloading, while @code{ielm-return}
is not. The latter will be available only after the former has been
called (or the entire feature is explicitly loaded by the user or
another program). This is the correct way to organise the code of a
program.

From the programmer's perspective, autoloading is set up with those
special @samp{;;;###autoload} comments. For example:

@lisp
;;;###autoload
(defun my-hello-world ()
  "Greet the world."
  (message "Hello everyone! My name is Protesilaos, also known as Prot!"))
@end lisp

If the code you want to autoload is the result of a macro, then you
would need to write it this way (@ref{Evaluation inside of a macro or special form}):

@lisp
;;;###autoload (autoload 'my-hello-world "my-hello")
(my-hello-define-command ARGUMENTS-FOR-THE-MACRO-THAT-WILL-YIELD-my-hello-world-DEFINITION)
@end lisp

Here the @code{my-hello-define-command} is an Elisp macro that expands into
a function like the @code{my-hello-world} shown further above. Because it
is the latter you wish to autoload, you need to write the exact
function call that would yield the desired result, hence
@samp{;;;###autoload (autoload 'my-hello-world "my-hello")}.

When you write @samp{;;;###autoload} on its own, you are effectively asking
to operate on the following symbol being defined. Whereas an
@samp{;;;###autoload WHAT-TO-LOAD-EXACTLY} gives you complete control over
what to autoload by specifying the exact function call to be used.
Generally, @samp{;;;###autoload} is enough.

@findex loaddefs-generate
@findex package-install
The @samp{;;;###autoload} statements are read by the function
@code{loaddefs-generate}. This is typically done when you install a
package, such as with the @code{package-install} command. The relevant
machinery will read every @samp{.el} file to generate a new file that
contains all the autoloads. This file will be in the same directory as
the rest of the source code, all of which is part of a directory among
those specified in the @code{load-path}.

If you have ever installed a package, then you most likely have files
with autoloads. You can check what they look like by doing the
following:

@itemize
@item
Visit the directory where you Emacs configuration file is. It might
be at @samp{~/.emacs.d/} or @samp{~/.config/emacs/}. When in doubt, inspect
the value of the variable @code{user-emacs-directory}.

@item
If you have installed packages, you will find an @samp{elpa} directory.

@item
Therein are all the directories of the packages you have.

@item
Inside those you will find @samp{.el} files, which are the original
source code, @samp{.elc} files which are the byte compiled counterparts
of the former, and a @samp{PACKAGE-autoloads.el} file with all the
collected autoloads. Here @samp{PACKAGE} is a placeholder for the name of
the package.
@end itemize

When you start up Emacs, it reads all those @file{PACKAGE-autoloads.el}
and thus knows where the specified symbols are defined. From then on,
the lazy loading happens when it must, i.e. when the affected symbol
is called for evaluation.

@cindex Start a generic Emacs session
Every Emacs user experiences the benefits of autoloading from day one.
Consider the scenario where you launch a pristine Emacs for the first
time. This can be done at any moment by running the following on the
command-line or terminal emulator:

@example
emacs -q
@end example

This generic Emacs session should take a short amount of time to
initialise its state and be ready for further input. Do @kbd{M-x}
(@code{execute-extended-command}) and press the @kbd{TAB} key. A
@samp{*Completions*} buffer will pop up, informing you about the thousands
of commands that are available as candidates of the present
interactive function call. Emacs has not actually evaluated the code
of all those: that would take a lot more time than what you
experienced at startup. Instead, Emacs is aware of all of them via the
autoload mechanism. Once you invoke a command, Emacs will take care to
load the corresponding file and then perform whatever computation the
command specifies (@ref{Make your interactive function also work from Lisp calls}).

What is usually autoloaded are commands, though variables can be
handled the same way. It all depends on what the program is doing.

@node Pattern match with @code{pcase} and related
@chapter Pattern match with @code{pcase} and related

@findex pcase
@vindex major-mode
Once you get in the flow of expressing your thoughts with Emacs Lisp,
you will be fluent in the use of @code{if}, @code{cond}, and the like (@ref{Basic control flow with @code{if} @code{cond} and others, , Basic control flow with @code{if}@comma{} @code{cond}@comma{} and others}).
You might even get more fancy with @code{if-let*} and @code{when-let*} (@ref{Control flow with @code{if-let*} and friends}).
However you go about it, there are some cases that arguably benefit
from more succinct expressions. ``Arguably'' is the operative term,
because code that is more terse can also be harder to reason about. At
any rate, this is where the @code{pcase} Lisp macro comes in (@ref{Evaluation inside of a macro or special form}).
At its more basic formulation, it is like @code{cond}, in that it tests the
return value of a given expression against a list of conditions.
Unlike @code{cond}, it can perform pattern matching and create binding that
it can then use based on the pattern it is matching.

Let me show you how @code{pcase} works like a @code{cond}. Here is an example
that compares the buffer-local value of the variable @code{major-mode} for
equality against a couple of known major mode symbols, namely
@code{org-mode} and @code{emacs-lisp-mode} (@ref{What are major and minor modes}):

@lisp
(pcase major-mode
  ('org-mode (message "You are in Org"))
  ('emacs-lisp-mode (message "You are in Emacs Lisp"))
  (_ (message "You are somewhere else")))
@end lisp

The above is the same idea as the following @code{cond}:

@lisp
(cond
 ((eq major-mode 'org-mode)
  (message "You are in Org"))
 ((eq major-mode 'emacs-lisp-mode)
  (message "You are in Emacs Lisp"))
 (t
  (message "You are somewhere else")))
@end lisp

@findex pcase
@findex message
Some programmers may argue that @code{pcase} is already more elegant. I
think it is true in this specific example, though I remain flexible
and practical: I will use whatever makes more sense for the code I am
writing. While on the topic of elegance, I should inform you that
practically all of the conditional logic can be done in a way that may
seem unexpected. Consider how my examples in this book make repetitive
use of @code{message}, when in reality the only part that changes is the
actual string/argument passed to that function. If we care about
``elegance'', we might prefer this way of expressing ourselves:

@lisp
(message
 (pcase major-mode
   ('org-mode "You are in Org")
   ('emacs-lisp-mode "You are in Emacs Lisp")
   (_ "You are somewhere else")))
@end lisp

Same idea for @code{if}, @code{when}, and the rest. It works, but now you have
to keep in your head the @code{message} that is waiting for the @code{pcase}
that is testing for many conditions.

@cindex Domain-Specific Language (DSL)
Back to the topic of what @code{pcase} does differently. If you read its
documentation, you will realise that it has its own mini language, or
``domain-specific language'' (DSL). This is common for macros
(@ref{Evaluation inside of a macro or special form}). They define how
evaluation is done and what sort of expressions are treated specially.
Let me then gift you this toy function that illustrates some of the
main features of the DSL now under consideration:

@lisp
(defun my-toy-pcase (argument)
  "Use `pcase' to return an appropriate response for ARGUMENT."
  (pcase argument
    (`(,one ,_ ,three)
     (message "List where first element is `%s', second is ignored, third is `%s'" one three))
    (`(,one . ,two)
     (message "Cons cell where first element is `%s' and second is `%s'" one two))
    ((pred stringp)
     (message "The argument is a string of some sort"))
    ('hello
     (message "The argument is equal to the symbol `hello'"))
    (_ (message "This is the fallback"))))
@end lisp

Go ahead and evaluate that function and then try it out (@ref{Evaluate Emacs Lisp}).
What it showcases is the various ways we write the cases that @code{pcase}
checks for. You will notice the use of the backtick and the comma,
which is similar to the quasi quoting I have covered before (@ref{Evaluate some elements inside of a list}).
Those perform the pattern matching against the expression that is
given to @code{pcase}, in this case the @samp{argument}. If the pattern matches,
the elements of the list are bound to the corresponding elements
returned by @samp{argument}. Then they can be used inside of that lexical
scope (@ref{Control flow with @code{if-let*} and friends}).

Below are a couple of examples with @code{my-toy-pcase}:

@lisp
(my-toy-pcase '("Protesilaos" "of" "Cyprus"))
;; => "List where first element is ‘Protesilaos’, second is ignored, third is ‘Cyprus’"

(my-toy-pcase '("Protesilaos" . "Cyprus"))
;; => "Cons cell where first element is ‘Protesilaos’ and second is ‘Cyprus’"
@end lisp

@findex pcase-let
@findex pcase-let*
@findex pcase-lambda
@findex pcase-dolist
@findex let
@findex let*
@findex lambda
@findex dolist
@cindex Destructuring
Some of those clauses in @code{my-toy-pcase} are a different way to express
@code{cond}. Arguably better, but not a clear winner in my opinion. What is
impressive and a true paradigm shift is the concept of
``destructuring'', else the pattern matching done to the expression that
effectively @code{let} binds elements of a list or cons cell to their
corresponding index in the list. The syntax used for this
destructuring is arcane, until you relate it to the backtick and the
comma which are used for selective evaluation (@ref{Evaluate some elements inside of a list}).

With this in mind, consider @code{pcase-let}, @code{pcase-let*}, @code{pcase-lambda},
and @code{pcase-dolist}, as variations of the plain @code{let}, @code{let*},
@code{lambda}, and @code{dolist} with the added feature of supporting
destructuring. They are not doing any of the extras of @code{pcase}
though---just destructuring on top of their familiar behaviour!
Perhaps calling something @code{pcase-let} when it does not handle cases is
wrong, but you will eventually get used to the @samp{pcase-} prefix being a
reference to destructuring capabilities. Those are especially useful
when you are working with the return value of a function which comes
as a list.

Consider a @code{pcase-dolist}. It maps through a list of elements for side
effects only, just like @code{dolist}, while doing destructuring (@ref{Mapping over a list of elements, , Mapping through a list of elements}).
For example, evaluate the following @code{defvar}, then the @code{pcase-dolist},
and then check the @samp{*Messages*} buffer to confirm what it did. Once
you do that, come back and evaluate the @code{dolist} and check the
@samp{*Messages*} once more.

@lisp
(defvar my-sample-data-for-pcase-dolist
  '(("Craig Gordon" "Goalkeeper" "Hearts")
    ("Aaron Hickey" "Defender" "Brentford")
    ("Grant Hanley" "Defender" "Hibernian")
    ("Scott McKenna" "Defender" "GNK Dinamo")
    ("Andy Robertson" "Defender" "Liverpool")
    ("Lewis Ferguson" "Midfielder" "Bologna")
    ("John McGinn" "Midfielder" "Aston Villa")
    ("Scott McTominay" "Midfielder" "Napoli")
    ("Ben Gannon-Doak" "Forward" "Bournemouth")
    ("Ryan Christie" "Forward" "Bournemouth")
    ("Lyndon Dykes" "Forward" "Birmingham"))
  "The starting lineup of Scotland's final qualifier match for the World Cup 2026.")

;; Here we go through a list of elements for side effects only while
;; relying on destructuring to create the bindings.
(pcase-dolist (`(,name ,position ,club) my-sample-data-for-pcase-dolist)
  (message "%s is a %s who plays for %s" name position club))

;; And here is the equivalent with a regular `dolist' and `let'.
(dolist (element my-sample-data-for-pcase-dolist)
  (let ((name (nth 0 element))
        (position (nth 1 element))
        (club (nth 2 element)))
    (message "%s is a %s who plays for %s" name position club)))
@end lisp

Whether you use @code{pcase} and destructuring in general is up to you. You
do not require them to write high quality code. Though you might agree
with those who consider them inherently more elegant and opt to use
them for this very reason. I do rely on them on occasion, though I am
not fully convinced that destructuring is the superior paradigm. It
makes the code harder to reason about if you are not well versed in
its domain-specific language (@ref{Basics of how Lisp works}). This is
especially true once you work with real-world programs rather than the
simple snippets I am showing you here.

@node Run some code or fall back to some other code
@chapter Run some code or fall back to some other code

@findex unwind-protect
@cindex Unwinding
Your typical program will rely on @code{if}, @code{cond}, and the like for
control flow (@ref{Basic control flow with @code{if} @code{cond} and others, , Basic control flow with @code{if}@comma{} @code{cond}@comma{} and others}).
Depending on your specific needs or stylistic considerations, it may
even include @code{pcase} (@ref{Pattern match with @code{pcase} and related}) as well
as @code{if-let*} or related (@ref{Control flow with @code{if-let*} and friends}).
Whatever style you prefer there are some cases that make it imperative
you run additional code after your primary operation concludes or
exits. The idea is to clean up whatever intermediate state you created
so that any unwanted---yet temporarily necessary---side effects are
undone (@ref{Side effect and return value}). The logic is ``do some
computation with all the desired side effects, then once that
transpires do some other computation to undo the side effects of the
latter or perform whatever kind you reset you consider necessary''.
This is the concept of ``unwinding'', which is implemented via
@code{unwind-protect}.

Here is some pseudo code:

@lisp
(unwind-protect
    ;; First do this
    DOING-STUFF
  ;; Then do this
  UNDOING-STUFF)
@end lisp

@cindex Non-local exit
@findex signal
@vindex error
@vindex quit
@findex keyboard-quit
With the above example in mind, @samp{DOING-STUFF} will be evaluated first
and then @samp{UNDOING-STUFF} will follow. If @samp{DOING-STUFF} does not
encounter errors, @samp{UNDOING-STUFF} will be evaluated in sequence and
the return value of this entire expression will be what @samp{DOING-STUFF}
returns. If, by contrast, @samp{DOING-STUFF} exits without doing what it
was supposed to (a ``non-local exit''), then the @samp{UNDOING-STUFF} will
still be evaluated and there will be no return value. A non-local exit
occurs when the @code{signal} function is called to report on some error.
What @code{signal} effectively does is abort the current computation and,
depending on the type of the signal like with @code{error}, produce a
backtrace. Some signals, like @code{quit}, do not produce a backtrace: they
simply abort the current computation. You signal @code{quit} whenever you
type @kbd{C-g} (@code{keyboard-quit}).

To illustrate what I just wrote:

@lisp
;; It does not make sense to use `unwind-protect' if we are not
;; producing side effects, but focus on the return value for now.
(unwind-protect
    (+ 1 1)
  (+ 10 10))
;; => 2

(unwind-protect
    (progn
      (+ 1 1)
      (signal 'quit (list "We are aborting")))
  (+ 10 10))
;; => NO RETURN VALUE.
;; => Quit: "We are aborting"
@end lisp

In other words, the unwinding part of the logic, which is the @samp{(+ 10
10)} in this case, is for side effects only: it does not return a
value.

@findex y-or-n-p
@findex progn
@findex unhighlight-regexp
Let me now show you when @code{unwinding-protect} makes sense. We want to
produce some side effect and then undo it. In the following code
block, I define a function which creates a minibuffer prompt. It asks
you to provide a @samp{y} or @samp{n} answer, which is shorthand notation for
``yes'' or ``no''. It tests the return value of @code{y-or-n-p} to determine
what it needs to do. While the prompt is waiting for your input, the
function highlights all instances of the regular expression @samp{(message}
in the current buffer. Those highlights must go away after you are
done with the minibuffer and its consequences. What is in the @code{progn}
is the part we want to run and we guard against its side effects with
the following @code{unhighlight-regexp}.

@lisp
(defun my-prompt-with-temporary-highlight ()
  "Ask for confirmation and highlight all instances of a regexp while waiting."
  (let ((regexp "(message"))
    (unwind-protect
        (progn
          (highlight-regexp regexp)
          (if (y-or-n-p "Should we proceed or not? ")
              (message "You have decided to proceed")
            (message "You prefer not to continue")))
      (unhighlight-regexp regexp))))

;; Call the following with the above in context.  Check how the
;; regular expression is highlighted.
(my-prompt-with-temporary-highlight)
@end lisp

Try the above in your Emacs to get a feel for it. Whatever answer you
provide at the prompt, the code still exits locally, meaning that the
@code{progn} produces whatever value it is designed to return. As always,
the @code{unhighlight-regexp} is evaluated no matter what. To get a
non-local exit from the @code{my-prompt-with-temporary-highlight} wait for
the prompt and while it is open type @kbd{C-g} (@code{keyboard-quit}).
Whether you exit locally or not, the highlights will be undone, which
is the desired outcome.

@cindex Unwinding happens after the backtrace is closed
@cindex Recursive edits and the backtrace buffer
@cindex Recursive edits are shown on the mode line as square brackets
@findex error
@findex abort-recursive-edit
In practice, your code may encounter an error, which is produced by
the @code{error} function (it technically is the @code{signal} function with the
@code{error} type). When that happens, you are presented with a backtrace
and Emacs enters a ``recursive edit''. The recursive edit means that
unwinding forms are suspended until you either type @kbd{C-]}
(@code{abort-recursive-edit}) or select the window with the @samp{*Backtrace*}
buffer and do @kbd{q} (@code{debugger-quit}) from there. Emacs can
enter more than one such recursive edit. While you are inside one, no
more backtrace buffers will be shown: you must first exit the
recursive edit. With default settings, the mode line shows levels of
recursive edits by placing square brackets around the indicator with
the major and minor modes (@ref{What are major and minor modes}). Always
remember to exit the recursive edit state, otherwise the unwind forms
will not be evaluated and you may end up with an Emacs session that is
in an inconsistent state.

To help you get a feel for it, I modify the function I wrote earlier
to now produce an error before it reaches the minibuffer prompt. This
will cause a non-local exit and will create a backtrace if you are not
already in a recursive edit---so make sure you exit that one first.

@lisp
(defun my-prompt-with-temporary-highlight-try-with-error ()
  "Ask for confirmation and highlight all instances of a regexp while waiting."
  (let ((regexp "(message"))
    (unwind-protect
        (progn
          (highlight-regexp regexp)
          (error "This error makes no sense here; close the backtrace to test the unwinding")
          (if (y-or-n-p "Should we proceed or not? ")
              (message "You have decided to proceed")
            (message "You prefer not to continue")))
      (unhighlight-regexp regexp))))
@end lisp

Evaluate this in some buffer that has the @samp{(message} text and notice
how the unwinding does not happen outright. It happens after you exit
the recursive edit. Again, remember to use @code{abort-recursive-edit}.

@lisp
(my-prompt-with-temporary-highlight-try-with-error)
@end lisp

@findex unwind-protect
@findex save-excursion
@findex save-restriction
@findex save-match-data
@findex with-temp-buffer
@findex save-window-excursion
@findex error
Taking a step back, you will figure out how @code{unwind-protect} is a more
general form of specialists like @code{save-excursion} and
@code{save-restriction} (@ref{Switching to another buffer window or narrowed state, , Switching to another buffer@comma{} window@comma{} or narrowed state}),
while it underpins the @code{save-match-data} (@ref{The match data of the last search})
among many other functions/macros, such as @code{with-temp-buffer} and
@code{save-window-excursion}. What @code{unwind-protect} does not do is respond
specially to signals, such as those coming from the @code{error} function:
it will allow the error to happen, meaning that a backtrace will be
displayed and your code will exit right there (but the unwinding will
still work, as I already explained, once you dismiss the backtrace).
To make your code treat signals in a controlled fashion, such as to
handle an error specially instead of what it normally does, you must
rely on @code{condition-case}.

@cindex Catching errors and other signals
@cindex Non-local exits
@findex condition-case
@findex signal
@findex define-error
With @code{condition-case} you assume full control over the behaviour of
your code, including how it should deal with any kind of @code{signal}. Put
differently, your Elisp will express the intent of ``I want to do this,
but if I get a certain signal I want to do that instead''. There are
many signals to consider, all of which come from the @code{signal}
function. These include the symbols @code{error}, @code{user-error},
@code{args-out-of-range}, @code{wrong-type-argument}, @code{wrong-length-argument},
and @code{quit}, in addition to anything else the programmer may choose to
define via @code{define-error}. In the following code blocks, I show you
how @code{condition-case} looks like. Remember that sometimes you do not do
quoting the usual way because of how the underlying form is
implemented (@ref{Evaluation inside of a macro or special form}). The
example I am using is the same I had for @code{unwind-protect}.

@lisp
(defun my-prompt-with-temporary-highlight-and-signal-checks ()
  "Ask for confirmation and highlight all instances of a regexp while waiting."
  (let ((regexp "(defun"))
    (condition-case nil
        (progn
          (highlight-regexp regexp)
          (if (y-or-n-p "Should we proceed or not? ")
              (user-error "You have decided to proceed; but we need to return a `user-error' for demo purposes")
            (error "You prefer not to continue; but we need to return an `error' for the demo")))
      (:success
       (unhighlight-regexp regexp)
       (message "No errors, but still need to unwind what we did, plus whatever else we want here"))
      (quit
       (unhighlight-regexp regexp)
       (message "This is our response to the user aborting the prompt"))
      (user-error
       (unhighlight-regexp regexp)
       (message "This is our response to the `user-error' signal"))
      (error
       (unhighlight-regexp regexp)
       (message "This is our response to the `error' signal")))))
@end lisp

@findex condition-case
@findex let
@findex unwind-protect
@findex cond
@findex message
@findex user-error
The above function illustrates both the aforementioned concept of
unwinding and the mechanics of handling signals. The abstract
structure of @code{condition-case} looks to me like an amalgamation of
@code{let}, @code{unwind-protect}, and @code{cond}. These conditions may include the
special handler of @samp{:success}, as I show there. Granted, the code I
wrote will never lead to that specific success case, though you can
modify what happens after the prompt to, say, call @code{message} instead
of the @code{user-error} function, which will then count as a successful
conclusion, i.e. a local exit. Otherwise, I think the expressions I
wrote tell you exactly how this program responds to the signals it
receives.

What I have not covered yet, is the aspect of @code{condition-case} that is
like the @code{let}, namely, how it binds the error data to a variable
within this scope. In my implementation above, it is the @code{nil} you see
there, meaning that I choose not to perform such a binding, as I have
no use for its data. Below I decide to bind the error data to the
symbol @code{error-data-i-got}, just for the sake of demonstration.

@lisp
(defun my-prompt-with-temporary-highlight-and-signal-checks-with-error-report ()
  "Ask for confirmation and highlight all instances of a regexp while waiting."
  (let ((regexp "(defun"))
    (condition-case error-data-i-got
        (progn
          (highlight-regexp regexp)
          (if (y-or-n-p "Should we proceed or not? ")
              (user-error "You have decided to proceed; but we need to return a `user-error'")
            (error "You prefer not to continue; but we need to return an `error'")))
      (:success
       (unhighlight-regexp regexp)
       (message "No errors, but still need to unwind what we did, plus whatever else we want here")
       (message "The error is `%s' and its data is `%S'" (car error-data-i-got) (cdr error-data-i-got)))
      (quit
       (unhighlight-regexp regexp)
       (message "This is our response to the user aborting the prompt")
       (message "The error is `%s' and its data is `%S'" (car error-data-i-got) (cdr error-data-i-got)))
      (user-error
       (unhighlight-regexp regexp)
       (message "This is our response to the `user-error' signal")
       (message "The error is `%s' and its data is `%S'" (car error-data-i-got) (cdr error-data-i-got)))
      (error
       (unhighlight-regexp regexp)
       (message "This is our response to the `error' signal")
       (message "The error is `%s' and its data is `%S'" (car error-data-i-got) (cdr error-data-i-got))))))
@end lisp

There will be times when @code{unwind-protect} and @code{condition-case} are the
right tools for the job. My hope is that these examples have given you
the big picture view and you are now ready to write your own programs
in Emacs Lisp.

@node When to use a named function or a lambda function
@chapter When to use a named function or a lambda function

@cindex Anonymous and eponymous functions
@findex lambda
The @code{lambda} is an anonymous function or, if you will, the form of a
computation as such (@ref{Symbols balanced expressions and quoting, , Symbols@comma{} balanced expressions@comma{} and quoting}).
@code{defun} defines a function with a given name (``eponymous'', if I may
bring more of the Greek language into this): technically, it creates
an alias for a @code{lambda}. When to use one versus the other is often a
matter of style. Though there are some cases where a certain approach
has clear advantages.

@cindex Eponymous functions provide an indirection that makes them more flexible
The rule of thumb is this: if you need to use the function more than
once, then give it a name and call it by its name. This way, you have
a symbol which provides an indirection to the actual computation: if
you change what the function is doing, the symbol is still the same,
so your changes apply across your code base. Otherwise, you will have
to update all the @code{lambda} forms you have.

The @code{lambda} is anonymous in the sense that it has nothing else
pointing to it: there is no indirection. As such, you must modify the
@code{lambda} in place. Knowledge of this quality is of paramount
importance, especially when working with hooks and the advice
mechanism (@ref{Hooks and the advice mechanism}). Unless your code is
trivial, do not use a @code{lambda} in a hook or advice as the lack of
indirection makes it harder for you to tweak how your function works.
Rely on a @code{lambda} when what you want to do is either trivial and not
subject to further revision or you wish to perform an ad-hoc
computation that is not needed elsewhere.

In some cases, you will have a named function that employs a @code{lambda}
internally. To modify one of the examples you will find in this book
(@ref{Mapping over a list of elements}):

@lisp
(defun my-increment-numbers-by-ten (numbers)
  "Add 10 to each number in NUMBERS and return the new list."
  (mapcar
   (lambda (number)
     (+ 10 number))
   numbers))

(my-increment-numbers-by-ten '(1 2 3))
;; => (11 12 13)
@end lisp

A @code{lambda} inside of a named function may also be used to do something
over and over again, with the help of @code{let}. You may, for instance,
have a function that needs to greet a list of people as a side effect
with @code{mapc} and you do not want to define the same function more than
once:

@lisp
(defun my-greet-teams (&rest teams)
  "Say hello to each person in TEAMS and return list with all persons per team.
Each member of TEAMS is a list of strings."
  (let* ((greet-name-fn (lambda (name)
                          (message "Hello %s" name)))
         (greet-team-and-names-fn (lambda (team)
                                    (message "Greeting the team of `%s'..." team)
                                    (mapc greet-name-fn team))))
    (mapcar greet-team-and-names-fn teams)))

(my-greet-teams
 '("Pelé" "Ronaldo")
 '("Maradona" "Messi")
 '("Beckenbauer" "Neuer")
 '("Platini" "Zidane")
 '("Baresi" "Maldini")
 '("Eusebio" "Cristiano Ronaldo")
 '("Xavi" "Iniesta")
 '("Charlton" "Shearer")
 '("Cruyff" "Van Basten")
 '("Puskas" "Kubala")
 '("All of the Greece Euro 2004 squad ;)"))
;; => (("Pelé" "Ronaldo") ("Maradona" "Messi") ...)
@end lisp

@cindex View the echo area messages
The greetings are a side effect in this case and are available in the
@samp{*Messages*} buffer. You can quickly access that buffer with
@kbd{C-h e} (@code{view-echo-area-messages}). It does not really
matter what @code{my-greet-teams} is doing. Focus on the combination of a
named function and anonymous functions inside of it.

Again, there is no right or wrong. Use a @code{lambda} for ad-hoc
computations, where you do not care about the potential for future
edits. Otherwise give your functions a name and you shall benefit from
the indirection they provide.

@node Make your interactive function also work from Lisp calls
@chapter Make your interactive function also work from Lisp calls

@cindex Interactive functions are commands
Functions can be used interactively when they are declared with the
@code{interactive} specification. This turns them into ``commands''
(@ref{Autoloading symbols}). They can be called via their name by first
doing @kbd{M-x} (@code{execute-extended-command}) and then finding the
command. They may also be assigned to a key and invoked directly by
pressing that key. Unless they absolutely depend on user input, they
will continue to work just fine if called directly from Lisp (@ref{Evaluate Emacs Lisp}).

@findex interactive
@findex read-string
In its simplest form, the @code{interactive} specification is an unquoted
list like @code{(interactive)}, which looks exactly like a function call
(@ref{Basics of how Lisp works}). Here is a trivial example that calls the
function @code{read-string} to produce a minibuffer prompt which accepts
user input and returns it as a string:

@lisp
(defun my-greet-person ()
  (interactive)
  (message "Hello %s" (read-string "Whom to greet? ")))
@end lisp

The problem with the above implementation is that it is only useful in
interactive use. If you want to issue such a greeting directly through
a program, you need to write another function that does practically
the same thing except that it takes a @samp{NAME} argument. Like this:

@lisp
(defun my-greet-person-with-name (name)
  "Greet person with NAME."
  (message "Hello %s" name))
@end lisp

For trivial computations, it is inconsequential whether you have
multiple functions do the work interactively and non-interactively.
But if you are doing something more involved, you do not want to
duplicate it across different functions. It is more maintenance work
for you as the implementation details might change and the subtle
problems shall arise. Emacs gives you the tools to write one function
that can accept arguments when called from Lisp while still working
the way you want when invoked interactively. You can have one
function, with its parameters, which decides how to get the values of
the arguments passed to it depending on if it is called
programmatically or interactively. Consider this scenario:

@lisp
(defun my-greet-interactive-and-non-interactive (name)
  "Greet person with NAME.
When called interactively, produce a minibuffer prompt asking for NAME.

When called from Lisp, NAME is a string."
  (interactive (list (read-string "Whom to greet? ")))
  (message "Hello %s" name))
@end lisp

@findex defun
The documentation I wrote there tells you exactly what is happening.
Though let me explain @code{interactive} in further detail: it takes an
argument, which is a list that mirrors the argument list of the
current @code{defun}. In this case, the @code{defun} has a list of arguments
that includes a single element, the @samp{NAME}. Thus, @code{interactive} also
has a list with one element, whose value corresponds to @samp{NAME}. If the
parameters were more than one, then the @code{interactive} would have to be
written accordingly: each of its elements would correspond to the
parameter at the same index on the list.

This list of expressions you pass to @code{interactive} essentially is the
preparatory work that binds values to the parameters. When you call
the above function interactively, you practically tell Emacs that in
this case @samp{NAME} is the return value of the call to @code{read-string}. For
more parameters, you get the same principle but I write it down just
to be clear:

@lisp
(defun my-greet-with-two-parameters (name country)
  "Greet person with NAME from COUNTRY.
When called interactively, produce a minibuffer prompt asking for NAME
and then another prompt for COUNTRY.

When called from Lisp, NAME and COUNTRY are strings."
  (interactive
   (list
    (read-string "Whom to greet? ")
    (read-string "Where from? ")))
  (message "Hello %s of %s" name country))

(my-greet-with-two-parameters "Protesilaos" "Cyprus")
;; => "Hello Protesilaos of Cyprus"
@end lisp

@findex length
The code you write inside of the @code{interactive} specification does not
have some special restriction. Express yourself as you see fit with
@code{let} bindings and control flow (@ref{Basic control flow with @code{if} @code{cond} and others, , Basic control flow with @code{if}@comma{} @code{cond}@comma{} and others}).
What matters though is that you return a list whose @code{length} is equal
to that of the list of parameters specified by the @code{defun}.

@vindex current-prefix-arg
Of interest in this context is the @code{current-prefix-arg} variable: it
holds the value of the prefix argument passed to the current function
in interactive use. Users input it by typing @kbd{C-u}
(@code{universal-argument}) for a ``universal prefix'' or @kbd{C-u} and
then a number (@code{digit-argument}) for a ``numeric prefix'' (something
like @kbd{C-1} is equivalent to @kbd{C-u} followed by
@kbd{1}). There is no predefined behaviour to the prefix
argument: it will do whatever you decide within the @code{interactive} by
reading the @code{current-prefix-arg} and later in the body of the function
where you parse that value. Here is an example:

@lisp
(defun my-greet-interactive-and-non-interactive-plus-prefix-arg (name &optional be-polite)
  "Greet person with NAME.
With optional BE-POLITE as a prefix argument, use a formal greeting,
otherwise remain casual.

When called interactively, produce a minibuffer prompt asking for NAME.

When called from Lisp, NAME is a string, while BE-POLITE is a non-nil
value."
  (interactive
   (list
    (read-string "Whom to greet? ")
    current-prefix-arg))
  (if be-polite
      (message "Greetings %s" name)
    (message "Howdy %s" name)))

(my-greet-interactive-and-non-interactive-plus-prefix-arg "Prot")
;; => "Howdy Prot"

(my-greet-interactive-and-non-interactive-plus-prefix-arg "Protesilaos" t)
;; => "Greetings Protesilaos"
@end lisp

And here is how you can take it a step further:

@lisp
(defun my-greet-interactive-and-non-interactive-plus-prefix-arg (name &optional title)
  "Greet person with NAME.
With optional TITLE as a prefix argument, prompt for a formal title and
prepend it to NAME.

When called from Lisp, NAME and TITLE are strings."
  (interactive
   (list
    (read-string "Whom to greet? ")
    (when current-prefix-arg
      (read-string "Which title to use? "))))
  (if title
      (message "Greetings %s %s" title name)
    (message "Howdy %s" name)))

(my-greet-interactive-and-non-interactive-plus-prefix-arg "Prot")
;; => "Howdy Prot"

(my-greet-interactive-and-non-interactive-plus-prefix-arg "Protesilaos" "Teacher")
;; => "Greetings Teacher Protesilaos"
@end lisp

Call @code{my-greet-interactive-and-non-interactive-plus-prefix-arg} with
and without a prefix argument to get a feel for it. It should do the
same as what it does in the Lisp calls included in this code block.

The @code{interactive} specification is a powerful mechanism when used
correctly. Do it right and you will end up with a rich corpus of
functions that are equally useful to programs and to users.

@node Emacs as a computing environment
@chapter Emacs as a computing environment

When you start using Emacs, you experience a text editor. You move the
cursor around and insert text. This is basically it. At the surface
level, Emacs looks like every other generic editor you have seen
before. Other actions, such as selecting another window or switching
to a new buffer, are ancillary to text editing. Using Emacs in this
capacity is perfectly fine.

What makes Emacs something far more powerful than a text editor is its
ability to be reprogrammed, else ``extended'', live by evaluating some
Emacs Lisp (@ref{Basics of how Lisp works}). Once you install a few packages
or, better, learn to program in Emacs Lisp, your text editor will
become a text-centric interface to increasingly more parts of your
computing life. For example, if you are a programmer, you will
eventually incorporate into your Emacs-based workflow tools for
compiling your project, debugging your code, viewing changes, and
sending patches. If you only write prose, you get to streamline your
work for taking notes, maintaining an agenda, writing technical
documents, sending emails, and more. The best part is that you can
have your integrated programming setup and your plain text writing
platform plus, generally, everything you can use Emacs for, all in
one.

With Emacs as your primary interface, you benefit from the consistency
and predictability of a unified system. You have pieced it together so
you understand how it works, more or less. This means you can extend
it when needed. Since Emacs is free software, you retain the freedom
to modify it as you see fit, such as in response to evolving work
requirements. If you have something that does what you expect, you
will rely on it long-term. Emacs will grow or shrink to fit your
current needs.

The consistency is one of presentation and function. At the level of
appearances, you get to use the same font and theme settings, as well
as the standard Emacs paradigms of frames, windows, buffers, the
minibuffer, and text editing. On the functionality front, you rely on
one programming language---Emacs Lisp---for all the interfaces you
will be working with. As such, commands you have written or received
from a package will be available to you in whatever new interface you
bring into your setup. For example, if you have a minor mode that
blinks the current line after a few seconds of idleness (e.g. because
you want to be reminded where you are), this feature is already
available when you start writing emails from inside Emacs: you do not
need to port it the way you would if you were introducing an entirely
new program to your workflow.

Compare this potential for unencumbered extensibility with what you
would otherwise be doing. You would be relying on disparate
applications that (i) do not necessarily talk to each other, (ii) each
has its own concepts for the user experience, and (iii) each uses its
own programming or configuration language. You can still get something
decent if you are determined. Though you will realise that Emacs
offers a better return on investment. For instance, the programming
skills you acquire from extending your text editing apply directly to
any future project to further extend Emacs. This is the gift that
keeps giving.

As such, you will benefit from thinking of Emacs as (i) the layer of
interactivity on top of command-line tools like @code{ls} and @code{grep}, and
(ii) an interpreter of a programming language that can draw linkages
between such tools, plus everything else it can do in its own right.
In effect, Emacs is a turbocharged command-line interpreter like Bash
equipped with a fully realised model of user interaction. Your Emacs
Lisp programs are the equivalent of Bash scripts, plus all the
accoutrements of interactivity. The counterpart to @samp{#!/bin/bash}
(which tells the computer which interpreter is needed for the given
script) is the current Emacs process.

Use this concept to better understand what the value proposition of
Emacs is for you in present time and in terms of sheer potential. Have
fun!

@node Acknowledgements
@chapter Acknowledgements

Thanks to the following people for fixing typos and spotting other
such mistakes:

José David Pernía, Laurent Gatto, Nicolas Semrau, Spike-Leung,
slackline, eNotchy.

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include doclicense.texi

@node Indices
@chapter Indices

@menu
* Function index::
* Variable index::
* Concept index::
@end menu

@node Function index
@section Function index

@printindex fn

@node Variable index
@section Variable index

@printindex vr

@node Concept index
@section Concept index

@printindex cp

@bye