\input texinfo                       @c -*- mode: texinfo; coding: utf-8 -*-
@c ===========================================================================
@c
@c This file was generated with po4a. Translate the source file.
@c
@c ===========================================================================

@comment %**start of header
@setfilename ../../info/eintr.info
@settitle programmeren in Emacs Lisp
@documentlanguage en
@include docstyle.texi
@syncodeindex vr cp
@syncodeindex fn cp
@documentencoding UTF-8
@documentlanguage nl
@finalout

@include /dev/null

@c ================ How to Print a Book in Various Sizes ================

@c This book can be printed in any of three different sizes.
@c Set the following @-commands appropriately.

@c     7 by 9.25 inches:
@c              @smallbook
@c              @clear largebook

@c     8.5 by 11 inches:
@c              @c smallbook
@c              @set largebook

@c     European A4 size paper:
@c              @c smallbook
@c              @afourpaper
@c              @set largebook

@c (Note: if you edit the book so as to change the length of the
@c table of contents, you may have to change the value of 'pageno' below.)

@c <<<< For hard copy printing, this file is now
@c      set for smallbook, which works for all sizes
@c      of paper, and with PostScript figures >>>>

@set smallbook
@ifset smallbook
@smallbook
@clear largebook
@end ifset

@c ================ Included Figures ================

@c If you clear this, the figures will be printed as ASCII diagrams
@c rather than PostScript/PDF.
@c (This is not relevant to Info, since Info only handles ASCII.)
@iftex
@set print-postscript-figures
@end iftex
@c clear print-postscript-figures

@comment %**end of header

@c per rms and peterb, use 10pt fonts for the main text, mostly to
@c save on paper cost.
@c Do this inside @tex for now, so current makeinfo does not complain.
@tex
@ifset smallbook
@fonttextsize 10

@end ifset
\global\hbadness=6666 % don't worry about not-too-underfull boxes
@end tex

@c For next or subsequent edition:
@c   create function using with-output-to-temp-buffer
@c   create a major mode, with keymaps
@c   run an asynchronous process, like grep or diff

@c For 8.5 by 11 inch format: do not use such a small amount of
@c whitespace between paragraphs as smallbook format
@ifset largebook
@tex
\global\parskip 6pt plus 1pt
@end tex
@end ifset

@c For all sized formats:  print within-book cross
@c reference with ``...''  rather than [...]

@c This works with the texinfo.tex file, version 2003-05-04.08,
@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.

@tex
\if \xrefprintnodename
 \global\def\xrefprintnodename#1{\unskip, ``#1''}
 \else
 \global\def\xrefprintnodename#1{ ``#1''}
\fi
% \global\def\xrefprintnodename#1{, ``#1''}
@end tex

@c ----------------------------------------------------

@dircategory Emacs lisp
@direntry
* Emacs Lisp Intro: (eintr).  Eenvoudige introductie in Emacs Lisp 
                                programmeren.
@end direntry

@c When printing, define edition-number to be the printed edition
@c number, titlepage-edition-number to be the spelled out edition
@c number suitable for the title page, and update-date to be the date,
@c in the preferred style for these.  E.g., run the shell command:
@c   texi2any -D 'edition-number 3.11' \
@c            -D 'titlepage-edition-number Revised Third Edition' \
@c            -D 'update-date 31 March 2020'
@c This relates mainly to the published book sold by the FSF.

@copying
Dit is @cite{Een introductie in Programmeren in Emacs Lisp}, voor mensen die
geen programmeur zijn.
@sp 1
@ifset edition-number
Edition @value{edition-number}, @value{update-date}
@end ifset
@sp 1
Gedistribueerd met Emacs versie @value{EMACSVER}.
@sp 1
Copyright @copyright{} 1990--1995, 1997, 2001--2026 Free Software
Foundation, Inc.
@sp 1

@iftex
Gepubliceerd door de:@*

GNU Press, @hfill @uref{https://www.fsf.org/licensing/gnu-press/}@* a
division of the @hfill email: @email{sales@@fsf.org}@* Free Software
Foundation, Inc.  @hfill Tel: +1 (617) 542-5942@* 31 Milk Street, # 960789
@hfill Fax: +1 (617) 542-2652@* Boston, MA 02196 USA
@end iftex

@ifnottex
Gedrukte exemplaren verkrijgbaar bij
@uref{https://shop.fsf.org/}. Gepubliceerd door:

@example
GNU Press,                        https://www.fsf.org/licensing/gnu-press/
a division of the                 email: sales@@fsf.org
Free Software Foundation, Inc.    Tel: +1 (617) 542-5942
31 Milk Street, # 960789          Fax: +1 (617) 542-2652
Boston, MA 02196 USA
@end example
@end ifnottex

@sp 1
ISBN 1-882114-43-4

@quotation
Het is toegestaan dit document te kopiëren, distribueren en/of te wijzigen
onder de termen van de GNU Free Documentation License, Version 1.3 of een
latere versie gepubliceerd door de Free Software Foundation; er is geen
andere sectie met de voorpagina tekst ``A GNU Manual'', en met de
achterpagina tekst als in (a) hieronder. Een exemplaar van de licentie is
opgenomen in de sectie met de titel ``GNU Free Documentation License''.

De FSF's achterkant tekst is: ``Je hebt de vrijheid deze GNU handleiding te
kopiëren en te wijzigen. Met het kopen van exemplaren ondersteun je de FSF
in het ontwikkelen van GNU en het promoten van software vrijheid.''
@end quotation
@end copying

@c half title; two lines here, so do not use 'shorttitlepage'
@tex
{\begingroup%
    \hbox{}\vskip 1.5in \chaprm \centerline{Een introductie in}%
        \endgroup}%
{\begingroup\hbox{}\vskip 0.25in \chaprm%
        \centerline{programmeren in Emacs Lisp}%
        \endgroup\page\hbox{}\page}
@end tex

@titlepage
@sp 6
@center @titlefont{Een introductie in}
@sp 2
@center @titlefont{programmeren in Emacs Lisp}
@sp 2
@ifset titlepage-edition-number
@center @value{titlepage-edition-number}
@end ifset
@sp 4
@center door by Robert J. Chassell

@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@iftex
@headings off
@evenheading @thispage @| @| @thischapter
@oddheading @thissection @| @| @thispage
@end iftex

@ifnothtml
@c     Keep T.O.C. short by tightening up for largebook
@ifset largebook
@tex
\global\parskip 2pt plus 1pt
\global\advance\baselineskip by -1pt
@end tex
@end ifset
@end ifnothtml

@c If you think this manual is too large for an introduction, please
@c consider this email exchange:
@c
@c       >> The intro is almost 300 pages in full.  I had expected 60 pages.
@c       >
@c       > This is an important point in its own right.  Could you
@c       > write a simplified introduction that is only 50 pages or so?
@c       > That would be helpful to many potential users, I'd think.
@c
@c   > The problem with the introduction is that it was written when
@c   > programming was only starting to be a skill "normal" people could
@c   > have access to.  So the text is extremely verbose and is
@c   > sometimes hard to follow because of that.  The gist of the
@c   > document could be summarized in 50 pages.
@c
@c This book is intentionally addressed to people who don't know how to
@c program.  That is its purpose.  We recommend people start learning to
@c program using this book.
@c
@c If you DO know how to program in some other language, you can probably
@c learn Emacs Lisp starting with the Emacs Lisp Reference Manual.
@c
@c        Richard Stallman <rms@gnu.org>,
@c        https://lists.gnu.org/r/emacs-devel/2018-05/msg00374.html

@shortcontents
@contents

@ifnottex
@node Top
@top Een introductie in programmeren in Emacs Lisp

@ifset WWW_GNU_ORG
@html
<p>De GNU Emacs website
is<href="/software/emacs/">https://www.gnu.org/software/emacs/</a>.<br> Om
deze handleiding in andere formaten te zien, klikt <a
href="/software/emacs/manual/eintr.html">hier</a>.
@end html
@end ifset

@insertcopying

Dit hoofdmenu toont eerst elk hoofdstuk en een index, daarna elk onderdeel
van elk hoofdstuk.
@end ifnottex

@c Uncomment the 3 lines below, starting with @iftex, if you want the
@c pages of Preface to be numbered in roman numerals.  Use -9 instead
@c of -11 for smallbook format.

@c >>>> Set pageno appropriately <<<<

@c The first page of the Preface is a roman numeral; it is the first
@c right handed page after the Table of Contents; hence the following
@c setting must be for an odd negative number.

@c iftex
@c global@pageno = -11
@c end iftex

@set COUNT-WORDS count-words-example
@c Length of variable name chosen so that things still line up when expanded.

@menu
* Voorwoord::                Wat je hier vindt.
* Lijsten verwerken::        Wat is Lisp?
* Oefenen van evaluatie::    Verschillende programma's draaien
* Defuns schrijven::         Hoe functiedefinities te schrijven
* Buffer rondleiding::       Ontdek een paar buffer gerelateerde functies.
* Meer complex::             Enkele nog complexere functies.
* Versmallen en verbreden::  Beperk jouw en Emacs aandacht tot een region.
* car cdr en cons::          Fundamentele functies in Lisp.
* Knippen en opslaan van tekst::  Tekst verwijderen en bewaren
* Implementatie van lijsten::  Hoe lijsten zijn geïmplementeerd in de 
                                 computer
* Yanking::                  Opgeslagen tekst plakken
* Loops en recursie::        Hoe een proces te herhalen
* Regexp zoeken::            Reguliere expressie zoekopdrachten
* Woorden tellen::           Een terugblik op herhaling en regexps.
* Woorden in een defun::     Woorden tellen in een @code{defun}.
* Een grafiek klaarmaken::   Een prototype grafiek print functie.
* Initialisatie van Emacs::  Hoe een @file{.emacs} bestand te schrijven.
* Debuggen.::                Hoe Emacs Lisp debuggers te draaien.
* Conclusie::                Nu heb je de basis.
* de-de::                    Een appendix: hoe vind je gerepliceerde 
                               woorden.
* Killring::                 Een appendix: hoe de killring werkt.
* Volledige grafiek::        Hoe een grafiek met labels op de assen te 
                               maken.
* Vrije software en vrije handleidingen::  Vrije software en vrije 
                                             handleidingen
* GNU Free Documentation License::  GNU Free Documentation License
* Index::                    Index
* Over de auteur::           Over de auteur

@detailmenu
 --- De gedetaileerde onderdelen lijst ---



Voorwoord



* Waarom::                   Waarom Emacs Lisp leren?
* Over het lezen van deze tekst::  Lees, raak vertrouwd en ontwikkel 
                                     gewoontes ...
* Doelgroep::                Voor wie dit is geschreven
* Geschiedenis van Lisp::    Geschiedenis van Lisp
* Opmerking voor beginners::  Je kunt dit lezen als beginner
* Dank::                     Dank

Lijsten verwerken



* Lisp lijsten::             Wat zijn lijsten
* Draai een programma::      Elke lijst in Lisp is een programma gereed om 
                               te draaien.
* Fouten maken::             Een foutboodschap genereren
* Namen en definities::      Namen van symbolen en functie-definities.
* Lisp interpreter::         Wat de Lisp interpreter doet.
* Evaluatie::                Een programma draaien
* Variabelen::               Een waarde van een variabele teruggeven
* Argumenten::               Informatie doorgeven aan een functie
* setq::                     De waarde van een variabele zetten.
* Samenvatting::             De belangrijkste punten
* Foutmelding oefeningen::   Foutmelding oefeningen

Lisp lijsten



* Genummerde lijsten::       Lijsten bevatten getallen en andere lijsten
* Lisp atomen::              Elementaire entiteiten
* Whitespace in lijsten::    Lijsten leesbaar formatteren
* Typen van lijsten::        Hoe GNU Emacs helpt bij het typen van lijsten

De Lisp interpreter



* Complicaties::             Variabelen, speciale vormen, lijsten daarbinnen
* Byte compiling::           Speciale verwerkingscode voor snelheid.

Evaluatie



* Hoe de interpreter werkt::  Returns en zij-effecten...
* Geneste lijsten evalueren::  Lijsten binnen lijsten...

Variabelen



* fill-column voorbeeld::    fill-column voorbeeld
* Void functie::             De foutmelding voor een symbool zonder functie.
* Void variabele::           De foutmelding voor een symbool zonder waarde.

Argumenten



* Data typen::               Typen van data doorgegeven naar een functie.
* Argumenten als variabele of als lijst::  Een argument kan de waarde van 
                                             een variabele of lijst zijn
* Variabel aantal argumenten::  Sommige functies accepteren een variable 
                                  aantal argumenten.
* Verkeerde type argument::  Een argument van het verkeerde type aan een 
                               functie doorgeven
* message::                  Een nuttige functie om boodschappen te zenden.

De waarde van een variabele zetten



* Setq gebruiken::           Een gequote waarde instellen.
* Tellen::                   @code{setq} gebruiken om te tellen.

Oefenen van evaluatie



* Hoe te evalueren::         Het typen van commando's of @kbd{C-x C-e} 
                               veroorzaakt evalatie.
* Buffer namen::             Buffers en bestanden zijn verschillend.
* Buffers pakken::           Pak een buffer zelf, niet slechts zijn naam.
* Van buffer verwisselen::   Hoe je naar een andere buffer overschakelt
* Buffer grootte en locatie::  De locatie van point en de grootte van het 
                                 buffer.
* Evaluatie oefening::       Evaluatie oefening

Hoe functiedefinities te schrijven



* Primitieve functies::      Primitieve functies
* defun::                    De @code{defun} macro.
* Installeer::               Installeer een functiedefinitie
* Interactief::              Een functie interactief maken.
* Interactieve opties::      Verschillende opties voor @code{interactive}.
* Permanent installeren::    Installeer code permanent
* let::                      Locale variabelen maken en initialiseren
* if::                       Wat als?
* else::                     If--then--else expressies.
* Waar en onwaarheid::       Wat Lisp als waar en onwaar beschouwt.
* save-excursion::           Point en buffer volgen
* Terugblik::                Terugblik
* defun oefeningen::         defun oefeningen

Installeer een functiedefinitie



* Effect van installatie::   Effect van installatie
* Een defun wijzigen::       Hoe een functiedefinitie te wijzigen.

Een functie interactief maken



* Interactieve vermenigvuldig-met-zeven::  Een overzicht
* vermenigvuldig-met-zeven in detail::  De interactieve versie

@code{let}



* Voorkom verwarring::       Voorkom verwarring
* Delen van een let expressie::  Delen van een let expressie
* Voorbeeld let expressie::  Voorbeeld let expressie
* Niet-geïnitialiseerde let variabelen::  Niet-geïnitialiseerde let 
                                            variabelen

De @code{if} speciale vorm



* if in meer detail::        if in meer detail
* type-dier in detail::      Voorbeeld van een @code{if} expressie.

Waar en onwaarheid in Emacs Lisp



* nil uitgelegd::            @code{nil} heeft twee betekenissen.

@code{save-excursion}



* Point en mark::            Een overzicht van verschillende locaties.
* Template voor save-excursion::  Template voor save-excursion

Enkele buffer gerelateerde functies



* Meer vinden::              Hoe meer informatie te vinden
* versimpelde-beginning-of-buffer::  Toon @code{goto-char}, @code{point-min} 
                                       en @code{push-mark}.
* mark-whole-buffer::        Bijna hetzelde als @code{beginning-of-buffer}.
* append-to-buffer::         Gebruikt @code{save-excursion} en 
                               @code{insert-buffer-substring}.
* Buffer gerelateerde terugblik::  Terugblik.
* Buffer oefeningen::        Buffer oefeningen

De definitie van @code{mark-whole-buffer}



* mark-whole-buffer overzicht::  mark-whole-buffer overzicht
* Body van mark-whole-buffer::  Slechts drie regels met code

De definitie van @code{append-to-buffer}



* append-to-buffer overzicht::  append-to-buffer overzicht
* append interactief::       Een tweedelige interactieve expressie.
* append-to-buffer body::    Bevat een @code{let} expressie.
* append save-excursion::    Hoe de @code{save-excursion} werkt.

Enkele meer complexe functies



* copy-to-buffer::           Met @code{set-buffer} en 
                               @code{get-buffer-create}.
* insert-buffer::            Read-only en met @code{or}
* beginning-of-buffer::      Toon @code{goto-char}, @code{point-min} en 
                               @code{push-mark}.
* Tweede buffer gerelateerde terugblik::  Tweede buffer gerelateerde 
                                            terugblik
* optionele oefening::       optionele oefening

De definitie van @code{insert-buffer}



* insert-buffer code::       insert-buffer code
* insert-buffer interactief::  Wanneer je kan lezen maar niet schrijven.
* insert-buffer body::       The body heeft een @code{or} en een @code{let}.
* if en or::                 Gebruik een @code{if} in plaats van een 
                               @code{or}.
* Voeg or in::               Hoe de @code{or} expressie werkt.
* Voeg let in::              Twee @code{save-excursion} expressies.
* Nieuwe insert-buffer::     Nieuwe insert-buffer

De interactieve expressie in @code{insert-buffer}



* Read-only buffer::         Wanneer een buffer niet gewijzigd kan worden.
* b for interactief::        Een bestaand buffer of anders zijn naam.

Complete definitie van @code{beginning-of-buffer}



* Optionele argumenten::     Optionele argumenten
* beginning-of-buffer opt arg::  Voorbeeld met optioneel argument.
* beginning-of-buffer compleet::  beginning-of-buffer compleet

@code{beginning-of-buffer} met een argument



* Ontrafelen beginning-of-buffer::  Ontrafelen beginning-of-buffer
* In geval van een groot buffer::  In geval van een groot buffer
* In geval van een klein buffer::  In geval van een klein buffer

Versmallen en verbreden



* Voordelen van versmallen::  De voordelen van versmallen
* save-restriction::         De @code{save-restriction} speciale vorm.
* what-line::                Het regelnummer waarop de point is.
* versmal oefening::         versmal oefening

@code{car}, @code{cdr}, @code{cons}: Fundamentele functies



* Vreemde namen::            Een historische terzijde: waarom de vreemde 
                               namen?
* car en cdr::               Functies om een deel van een lijst te 
                               extraheren.
* cons::                     Een lijst construeren.
* nthcdr::                   @code{cdr} herhaaldelijk aanroepen.
* nth::                      nth
* setcar::                   Het eerste element van een lijst veranderen.
* setcdr::                   De rest van de lijst veranderen.
* cons oefening::            cons oefening

@code{cons}



* Bouw een lijst::           Bouw een lijst
* length::                   Hoe de lengte van een lijst te vinden.

Tekst knippen en opslaan



* Tekst opslaan::            Tekst wordt opgeslagen in een lijst.
* zap-to-char::              Tekst tot aan een karakter knippen.
* kill-region::              Tekst uit een gebied knippen.
* copy-region-as-kill::      Een definitie van tekst kopiëren.
* Uitwijding naar C::        Kleine opmerking over C programmeertaal macros.
* defvar::                   Hoe een variabele een initiële waarde te geven.
* cons en search-fwd terugblik::  cons en search-fwd terugblik
* zoek oefening::            zoek oefening

@code{zap-to-char}



* Complete zap-to-char::     De complete implementatie.
* zap-to-char interactief::  Een driedelige iteractive expressie.
* zap-to-char body::         Een kort overzicht.
* search-forward::           Hoe naar een string te zoeken.
* progn::                    De @code{progn} speciale vorm.
* Samenvatting zap-to-char::  Gebruik @code{point} en @code{search-forward}.

@code{kill-region}



* Complete kill-region::     De functiedefinitie.
* condition-case::           Met een probleem omgaan
* Lisp macro::               Lisp macro

@code{copy-region-as-kill}



* Complete copy-region-as-kill::  De complete functiedefinitie.
* copy-region-as-kill body::  De body van @code{copy-region-as-kill}.

De body van @code{copy-region-as-kill}



* last-command en this-command::  last-command en this-command
* kill-append functie::      kill-append functie
* kill-new functie::         kill-new functie

Initialiseer een variabele met @code{defvar}



* Inzien huidige variabele waarde::  Inzien huidige variabele waarde
* defvar en asterisk::       defvar en asterisk

Hoe lijsten zijn geïmplementeerd



* Lijsten uitgetekend::      Lijsten uitgetekend
* Symbolen als ladekast::    Een krachtige metafoor verkennen.
* Lijst oefening::           Lijst oefening

Tekst terug yanken



* Killring overzicht::       Killring overzicht
* kill-ring-yank-pointer::   De killring is een lijst.
* yank nthcdr oefeningen::   De @code{kill-ring-yank-pointer} variabele.

Loops en recursie



* while::                    Een stuk code zich laten herhalen.
* dolist dotimes::           dolist dotimes
* Recursie::                 Een functie zichzelf laten aanroepen.
* Looping oefening::         Looping oefening

@code{while}



* Looping met while::        Herhaal zolang de test waar teruggeeft.
* Loop voorbeeld::           Een @code{while} loop die een lijst gebruikt.
* print-elements-of-list::   Gebruik @code{while}, @code{car}, @code{cdr}.
* Incrementele loop::        Een loop met een incrementele teller.
* Incrementele loop details::  Incrementele loop details
* Decrementele loop::        Een loop met een aflopende teller.

Details van een incrementele loop



* Incrementeel voorbeeld::   Steentjes in een driehoek tellen.
* Inc voorbeeld onderdelen::  De onderdelen van een functiedefinitie.
* inc voorbeeld samengesteld::  De functiedefinitie samenstellen.

Loop met een decrementele teller



* Decerementeel voorbeeld::  Meer steentjes op het strand.
* Dec voorbeeld onderdelen::  De onderdelen van een functiedefinitie.
* Dec voorbeeld samengesteld::  De functiedefinitie samenstellen.

Bespaar je tijd: @code{dolist} en @code{dotimes}



* dolist::                   dolist
* dotimes::                  dotimes

Recursie



* Robots bouwen::            Zelfde model, verschillend serienummer ...
* Recursive definitie onderdelen::  Loop totdat je stopt ...
* Recursie met lijst::       Een lijst gebruiken als test of je moet 
                               recursen.
* Recursieve driehoek functie::  Recursieve driehoek functie
* Recursie met cond::        Recursie met cond
* Recursieve patronen::      Veelgebruikte templates.
* Geen uitstel::             Sla geen werk op ...
* Geen uitstel oplossing::   Geen uitstel oplossing

Recursie in plaats van een teller



* Recursief voorbeeld arg van 1 of 2::  Recursief voorbeeld arg van 1 of 2
* Recursief voorbeeld arg van 3 of 4::  Recursief voorbeeld arg van 3 of 4

Recursieve patronen



* Every::                    Every
* Accumulate::               Accumulate
* Bewaar::                   Bewaar

Reguliere expressie zoekopdrachten



* sentence-end::             De reguliere expressie van @code{sentence-end}.
* re-search-forward::        Erg vergelijkbaar met @code{search-forward}.
* forward-sentence::         Een eenvoudig voorbeeld van regexp 
                               zoekopdracht.
* forward-paragraph::        Een iets complexer voorbeeld.
* Regexp terugblik::         Regexp terugblik
* re-search oefeningen::     re-search oefeningen

@code{forward-sentence}



* Complete forward-sentence::  Complete forward-sentence
* fwd-sentence while loops::  Twee @code{while} loops.
* fwd-sentence re-search::   Een reguliere expressie zoekopdracht.

@code{forward-paragraph}: een goudmijn van functies



* forward-paragraph in het kort::  Belangrijke onderdelen van de 
                                     functiedefinitie.
* fwd-para let::             De @code{let*} expressie
* fwd-para while::           De voorwaartse beweging @code{while} loop.

Tellen: repetitie en regexps



* Waarom woorden tellen::    Waarom woorden tellen
* @value{COUNT-WORDS}::      Gebruik een regexp, maar vindt een probleem.
* recursive-count-words::    Start met het geval van geen woorden in de 
                               region.
* Tellen voorbeeld::         Tellen voorbeeld

De @code{@value{COUNT-WORDS}} functie



* Ontwerp @value{COUNT-WORDS}::  De definitie met @code{while} loop.
* Wiite ruimte bug::         De witte ruimte bug in 
                               @code{@value{COUNT-WORDS}}

Woorden tellen in een @code{defun}



* Verdeel en heers::         Verdeel en heers
* Woorden en symbolen::      Wat te tellen?
* Syntax::                   Wat vormt een woord of een symbool?
* count-words-in-defun::     Erg vergelijkbaar met 
                               @code{@value{COUNT-WORDS}}
* Enkele defuns::            Enkele defuns in een bestand tellen.
* Een bestand vinden::       Wil je naar een bestand kijken?
* lengths-list-file::        Een lijst met de lengtes van veel definities.
* Enkele bestanden::         Tellen in definities in verschillende 
                               bestanden.
* Enkele bestanden recursief::  Recursief tellen in verschillende bestanden.
* De data voorbereiden::     De data voorbereiden om in een grafiek te 
                               tonen.

Woorden tellen in  @code{defuns} in verschillende bestanden



* lengths-list-many-files::  Een lijst met de lengte van defuns teruggeven.
* append::                   Een lijst aan een andere koppelen.

De data voorbereiden om in een grafiek te tonen



* Data in detail te tonen::  Data in detail te tonen
* Sorteren::                 Lijsten sorteren
* Bestanden lijst::          Een lijst van bestanden maken.
* Functiedefinities tellen::  Functiedefinities tellen

Een grafiek klaarmaken



* Kolommen van een grafiek::  Kolommen van een grafiek
* graph-body-print::         Hoe de body van een grafiek af te drukken.
* recursive-graph-body-print::  recursive-graph-body-print
* Afgedrukte assen::         Afgedrukte assen
* Lijngrafiek oefening::     Lijngrafiek oefening

Jouw @file{.emacs} bestand



* Default configuratie::     Default configuratie
* Site-wide init::           Je kunt systeem-brede init bestanden schrijven.
* defcustom::                Emacs schrijft de code voor je.
* Een init bestand beginnen::  Hoe een @file{.emacs} init bestand te 
                                 schrijven.
* Tekst en auto-fill::       Automatisch regels afbreken.
* Mail aliasen::             Gebruik afkortingen voor e-mailadressen.
* Indent Tabs Mode::         Gebruik geen tabs met @TeX{}
* Key bindings::             Enkele persoonlijke key bindings maken.
* Keymaps::                  Meer over key binding.
* Bestanden laden::          Automatisch bestanden laden (en dus evalueren).
* Autoload::                 Functies beschikbaar maken.
* Eenvoudige uitbreiding::   Definieer een functie, bind het aan een toets.
* X11 kleuren::              Kleuren in X.
* Diverse::                  Diverse
* Mode line::                Hoe je mode line aan te passen

Debuggen.



* debug::                    Hoe de ingebouwde debugger te gebruiken.
* debug-on-entry::           Start debugen wanneer je een functie aanroept.
* debug-on-quit::            Start debuggen wanneer je quit met @kbd{C-g}.
* edebug::                   Hoe je Edebug gebruikt, een source level 
                               debugger.
* Debuggen oefeningen::      Debuggen oefeningen

De killring hanteren



* Wat de killring doet::     Wat de killring doet
* current-kill::             current-kill
* yank::                     Plak een kopie van een afgeknipt element
* yank-pop::                 Element waar naar verwezen wordt invoegen.
* ring bestand::             ring bestand

De @code{current-kill} functie



* Code voor current-kill::   Code voor current-kill
* current-kill begrijpen::   current-kill begrijpen

Overzicht @code{current-kill}



* Body van current-kill::    Body van current-kill
* Uitwijding over fout::     Hoe mensen te misleiden, maar niet computers.
* Het element vaststellen::  Het element vaststellen

Een grafiek met labels op de assen



* Gelabeld voorbeeld::       Gelabeld voorbeeld
* print-graph varlist::      @code{let} expressie in @code{print-graph}
* print-Y-axis::             Print een label voor de verticale as
* print-X-axis::             Print een horizontaal label
* De gehele grafiek afdrukken::  De functie om een hele grafiek te printen.

De @code{print-Y-axis} functie



* print-Y-axis in detail::   print-Y-axis in detail
* Hoogte van label::         Welke hoogte voor de Y-as?
* Bereken het restant::      Hoe het restant van een deling te berekenen.
* Y-as element::             Een lijn voor de y-as construeren.
* Y-axis-column::            Een lijst van y-as labels genereren.
* print-Y-axis enalaatste::  Nog niet finale versie

De @code{print-X-axis} functie



* Overeenkomsten verschillen::  Grotendeels als @code{print-Y-axis}, maar 
                                  niet helemaal gelijk.
* X-as tic marks::           Maak tic marks voor de horizontale as.

De hele grafiek afdrukken



* De finale versie::         Enkele veranderingen.
* Test print-graph::         Een korte test draaien.
* Woorden in defuns grafisch weergeven::  De finale code uitvoeren.
* lambda::                   Hoe een anonyme functie te schrijven
* mapcar::                   Een functie toepassen op de elementen van een 
                               lijst.
* Een andere bug::           Weer een andere bug @dots{} erg verraderlijk.
* Finale afgedrukte grafiek::  De grafiek zelf

@end detailmenu
@end menu

@node Voorwoord
@unnumbered Voorwoord

Het grootste deel van de GNU Emacs geïntegreerde omgeving is geschreven in
de programmeertaal met de naam Emacs Lisp. De code in deze taal is de
software, de verzameling instructies, die de computer vertellen wat te doen
wanneer je die commando's geeft. Emacs is zo ontworpen dat je nieuwe code in
Emacs Lisp kunt schrijven en die makkelijk als uitbreiding op de editor
installeert.

(GNU Emacs wordt soms een `uitbreidbare editor'' genoemd, maar biedt veel
meer dan mogelijkheden voor tekstbewerking. Het is beter om Emacs als een
``uitbreidbare computer omgeving'' te beschrijven. Dat is echter nogal een
mond vol. Het is eenvoudiger om Emacs een editor te noemen. Bovendien is
alles wat je in Emacs doet, zoals het vinden van de Maya-datum, fasen van de
maan, het vereenvoudigen van polynomen, code debuggen, bestanden beheren,
brieven lezen, boeken schrijven, al deze activiteiten komen neer op tekst
bewerken in de breedste zin van het woord.)

@menu
* Waarom::                   Waarom Emacs Lisp leren?
* Over het lezen van deze tekst::  Lees, raak vertrouwd en ontwikkel 
                                     gewoontes ...
* Doelgroep::                Voor wie dit is geschreven
* Geschiedenis van Lisp::    Geschiedenis van Lisp
* Opmerking voor beginners::  Je kunt dit lezen als beginner
* Dank::                     Dank
@end menu

@ifnottex
@node Waarom
@unnumberedsec Why Study Emacs Lisp?
@end ifnottex

Alhoewel men Emacs Lisp meestal alleen in samenhang met Emacs ziet, is het
een volwaardige computer programmeertaal. Je kunt Emacs Lisp net als elke
andere programmeertaal gebruiken.

Misschien wil je programmeren begrijpen, misschien wil je Emacs uitbreiden,
of misschien wil je een programmeur worden. Deze introductie in Emacs Lisp
is bedoeld om je op weg te helpen, je te begeleiden bij het leren van de
beginselen van programmeren en, belangrijker, te laten zien hoe je jezelf
kunt leren verder te gaan.

@node Over het lezen van deze tekst
@unnumberedsec Over het lezen van deze tekst

Verspreid over dit document kom je kleine voorbeeldprogramma's tegen die je
in Emacs kunt draaien. Wanneer je dit document in Info binnen GNU Emacs
leest, dan draai je de programma's zoals ze verschijnen. (Dit is eenvoudig
te doen en wordt uitgelegd bij de presentatie van de voorbeelden.) Daarnaast
kan je deze introductie lezen in een gedrukt boek zittend bij een computer
waarop Emacs draait. (Dit is wat ik graag doe, ik hou van gedrukte boeken.)
Wanneer je geen draaiende Emacs bij de hand hebt dan kan je nog steeds dit
boek lezen. Beschouw het in dat geval als een roman of een reisgids naar een
land waar je niet geweest bent, interessant, maar niet hetzelfde als er
daadwerkelijk zijn.

Een groot deel van deze introductie leidt je rond door de code van GNU
Emacs. Deze rondleidingen dienen twee doeleinden. Ten eerste om je vertrouwd
te maken met de echte, werkende code (code die je dagelijks gebruikt) en ten
tweede om je vertrouwd te maken met de manier waarop Emacs werkt. Het is
interessant te zien hoe een werkomgeving is geïmplementeerd. Ook hoop ik dat
je de gewoonte overneemt om de source code door te bladeren. Je kan er van
leren en je kunt er ideeën uit halen. GNU Emacs hebben is zoals een
drakengrot vol schatten hebben.

Naast het leren van Emacs als editor en Emacs Lisp als programmeertaal geven
de voorbeelden en de rondleiding je de gelegenheid vertrouwd te raken met
Emacs als een Lisp programmeeromgeving. GNU Emacs ondersteunt het
programmeren en verschaft gereedschappen waar je comfortabel gebruik van
wilt maken, zoals @kbd{M-.} (de toetsaanslag waarmee je het
@code{xref-find-definitions} commando start). Je leert ook over buffers en
andere objecten die onderdeel van de omgeving uitmaken. Deze
functionaliteiten van Emacs ontdekken is als nieuwe routes door je
geboorteplaats ontdekken.

@ignore
In addition, I have written several programs as extended examples.
Although these are examples, the programs are real.  I use them.
Other people use them.  You may use them.  Beyond the fragments of
programs used for illustrations, there is very little in here that is
just for teaching purposes; what you see is used.  This is a great
advantage of Emacs Lisp: it is easy to learn to use it for work.
@end ignore

Tenslotte hoop ik hiermee vaardigheden over te brengen over het gebruik van
Emacs om aspecten van het programmeren te leren die je nog niet weet. Vaak
kan Emacs je helpen om dingen te begrijpen of te ontdekken hoe je iets
nieuws doet. Deze zelfredzaamheid is niet alleen prettig, maar ook een
voordeel.

@node Doelgroep
@unnumberedsec Voor wie dit is geschreven

De tekst is bedoeld als een elementaire introductie voor mensen die geen
programmeur zijn. Wanneer je een programmeur bent, zal je niet tevreden zijn
met deze introductie. De reden daarvoor is dat je waarschijnlijk een expert
bent geworden in het lezen van referentiehandleidingen en niet blij wordt
van de manier waarop deze tekst is opgezet.

Een expert-programmeur die deze tekst heeft gereviewed zei me:

@quotation
@i{Ik geeft de voorkeur aan het bestuderen van referentiehandleidingen. Ik
``duik'' in elke paragraaf en ``kom boven voor lucht'' tussen de
paragrafen. }

@i{Wanneer ik aan het einde van een paragraaf ben verwacht ik dat het onderwerp
klaar is, dat ik alles weet wat ik moet weten (met als mogelijke
uitzondering het geval de volgende paragraaf dieper op de inhoud ingaat). Ik
verwacht dat een goed geschreven referentiehandleiding weinig herhaling
bevat en dat het uitstekende verwijzingen heeft naar de (enige) plek waar de
informatie is die ik zoek.}
@end quotation

Deze introductie in niet voor die persoon geschreven!

Ten eerste probeer ik alles tenminste drie keer te behandelen: eerst om het
te introduceren, dan om het in context te laten zien, en vervolgens in een
andere context, of om het te herhalen.

Ten tweede stop ik vrijwel nooit alle informatie over een onderwerp op een
enkele plek, laat staat in een paragraaf. In mijn manier van denken legt dit
een te zware last op de lezer. In plaats daarvan probeer ik alleen uit te
leggen wat de lezer op dat moment moet weten. (Soms voeg ik wat extra
informatie toe zodat je later niet verrast wordt wanneer de aanvullende
informatie formeel wordt geïntroduceerd.)

Wanneer je deze test leest wordt niet van je verwacht dat je alles meteen de
eerste keer leert. Je hoeft slechts vluchtig kennis te maken met enkele van
de genoemde onderdelen. Ik hoop dat ik de tekst zo gestructureerd heb en je
genoeg hints gegeven heb dat je bewust bent van wat belangrijk is en je
daarop concentreert.

Je zult in sommige paragrafen moeten duiken, er is geen andere manier om die
te lezen. Maar ik heb geprobeerd hun aantal zo klein mogelijk te houden. Dit
boek is bedoeld als een toegankelijke heuvel in plaats van een ontmoedigende
berg.

Dit boek, @cite{Een introductie in programmeren in Emacs Lisp}, heeft een
bijpassend document,
@iftex
@cite{The GNU Emacs Lisp Reference Manual}.
@end iftex
@ifnottex
@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU Emacs Lisp
Reference Manual}.
@end ifnottex
Deze referentiehandleiding bevat meer details dan deze introductie. In de
referentiehandleiding is alle informatie met betrekking tot een onderwerp op
een plek geconcentreerd. Je zou die moeten gebruiken wanneer je bent zoals
de hierboven genoemde programmeur. En nadat je deze @cite{Introductie}
gelezen hebt is de @cite{Reference Manual} natuurlijk  bruikbaar tijdens het
schrijven van je eigen programma's.

@node Geschiedenis van Lisp
@unnumberedsec Geschiedenis van Lisp
@cindex Lisp geschiedenis

Lisp is oorspronkelijk eind jaren '50 ontwikkeld in het Massachusetts
Institute of Technology voor onderzoek op het gebied van kunstmatige
intelligentie. De grote kracht van de Lisp taal maakt het ook voor andere
toepassingen superieur, zoals het schrijven van editor-commando's en
geïntegreerde omgevingen. 

@cindex Maclisp
@cindex Common Lisp
GNU Emacs Lisp is grotendeels geïnspireerd door Maclisp, dat in de jaren '60
in het MIT is geschreven. Het is ook enigszins geïnspireerd door Common
Lisp, dat in de jaren '80 een standaard werd. Emacs Lisp is echter een stuk
eenvoudiger dan Common Lisp. (De standaard Emacs distributie bevat een
optioneel uitbreidingsbestand @file{cl-lib.el}, dat veel Common Lisp
functionaliteiten aan Emacs Lisp toevoegt.)

@node Opmerking voor beginners
@unnumberedsec Een opmerking voor beginners

Ook als je GNU Emacs niet kent heeft het lezen van dit document  veel
nut. Ik raad je echter aan om Emacs te leren, al is het alleen  maar te
leren hoe je over het scherm beweegt. Je kunt zelf  het gebruik van Emacs
leren met de ingebouwde tutorial. Om die  te gebruiken, type je @kbd{C-h
t}. (Dit betekent dat je  de toetsen @key{CTRL} @kbd{h} tegelijk indrukt en
loslaat, en daarna  de toets @kbd{t} indrukt en loslaat.) 

Ook verwijs ik vaak naar Emacs's standaard commando's door de
toetscombinaties te noemen die je gebruikt om het commando aan te roepen  en
vervolgens de naam van het commando tussen haakjes, zoals dit:  @kbd{C-M-\}
(@code{indent-region}). Wat dit betekent is dat  het @code{indent-region}
commando gebruikelijk wordt aangeroepen door  @kbd{C-M-\} te typen. (Je
kunt, als je dat wilt, de toetscombinaties  om commando's aan te roepen
wijzigen, dit heet @dfn{rebinding}.  @xref{Keymaps, , Keymaps}.)  De
afkorting @kbd{C-M-\} betekent dat je  de @key{CTRL}-toets, de
@key{META}-toets en de @kbd{\}-toets  allemaal tegelijk indrukt. Soms wordt
een toetscombinatie als dit  een keychord genoemd, omdat het vergelijkbaar
is met de manier waarop je  een akkoord op een piano speelt. Wanneer je
toetsenbord geen @key{META}-toets  heeft, dan gebruik je de @key{ESC}-toets
als prefix. In dat geval  betekent @kbd{C-M-\} dat je eerst de  @key{ESC}
indrukt en loslaat  en daarna tegelijkertijd de  @key{CTRL}-toets en de
@kbd{\}-toets indrukt.  Maar meestal betekent @kbd{C-M-\} dat je de
@key{CTRL}-toets samen met  de toets die als @key{ALT} is gelabeld indrukt
en tegelijkertijd de  @kbd{\}-toets indrukt.

In aanvulling op het typen van een toetscombinatie, kan je wat je typt
uitbreiden met de prefix @kbd{C-u}, wat het @dfn{universal argument}
heet. De  @kbd{C-u}-toetscombinatie geeft een argument door aan het
eerstvolgende commando. Dus, om een gebied met gewone tekst 6 spaties te
indenten, markeer je het gebied en vervolgens type je  @w{@kbd{C-u 6
C-M-\}}. (Wanneer je geen getal opgeeft, dan geeft Emacs hetzij het getal 4
door aan het commando, of voert het commando anders uit). @xref{Arguments, ,
Numeric Arguments, emacs, The GNU Emacs Manual}.

Wanneer je dit in Info met GNU Emacs leest, dan kun je het hele document
lezen slechts door het indrukken van de spatiebalk, @key{SPC}. (Om meer over
Info te leren, type @kbd{C-h i} en selecteer daarna Info.)

Een opmerking over terminologie: wanneer ik het woord Lisp alleen gebruik,
dan refereer ik meestal naar de verschillende dialecten van Lisp in het
algemeen, maar wanneer ik het over Emacs Lisp heb, dan refereer ik naar GNU
Emacs Lisp in het bijzonder.

@node Dank
@unnumberedsec Dank

Mijn dank aan iedereen die met met dit boek hielpen. Mijn speciale dank gaat
uit naar @r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland
McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M. Stallman} en
@w{Melissa Weisshaus}. Mijn dank gaat ook uit naar @w{Philip Johnson} en
@w{David Stampe} voor hun geduldige aanmoediging. Mijn vergissingen zijn van
mij zelf. 

@flushright
Robert J. Chassell
@ifnothtml
@email{bob@@gnu.org}
@end ifnothtml
@ifhtml
bob@@gnu.org
@end ifhtml
@end flushright

@c ================ Beginning of main text ================

@c Start main text on right-hand (verso) page

@tex
\par\vfill\supereject
\headings off
\ifodd\pageno
    \par\vfill\supereject
\else
    \par\vfill\supereject
    \page\hbox{}\page
    \par\vfill\supereject
\fi
@end tex

@c Note: this resetting of the page number back to 1 causes TeX to gripe
@c about already having seen page numbers 1-4 before (in the preface):
@c   pdfTeX warning (ext4): destination with the same identifier (name{1})
@c   has been already used, duplicate ignored
@c I guess that is harmless (what happens if a later part of the text
@c makes a link to something in the first 4 pages though?).
@c E.g., note that the Emacs manual has a preface, but does not bother
@c resetting the page numbers back to 1 after that.
@c Alternatively, uncomment the 3 lines above (search for ``pageno'')
@c to have the preface numbered in roman numerals.
@iftex
@headings off
@evenheading @thispage @| @| @thischapter
@oddheading @thissection @| @| @thispage
@global@pageno = 1
@end iftex

@node Lijsten verwerken
@chapter Lijsten verwerken

Voor het ongetrainde oog is Lisp een vreemde programmeertaal. In Lisp code
staan overal haakjes. Sommige mensen stellen zelfs dat de naam voor ``Lots
of Isolated Silly Parentheses'' staat. Maar die stelling is ongegrond. Lisp
staat voor  LISt Processing en de programmeertaal behandelt @emph{lijsten}
(en lijsten van lijsten) door ze tussen haakjes te zetten. De haakjes
markeren de grenzen van de lijst. Soms wordt een lijst voorafgegaan door een
apostrof @samp{'}, in Lips heet dat een @dfn{single-quote}. @footnote{Een
single-quote is een afkorting voor de speciale vorm @code{quote}. Je hoeft
nu nog niet over speciale vormen na te denken.
@ifnottex
@xref{Complicaties}.
@end ifnottex
@iftex
@xref{Lisp interpreter}.
@end iftex
} Lijsten zijn de basis van Lisp.

@menu
* Lisp lijsten::             Wat zijn lijsten
* Draai een programma::      Elke lijst in Lisp is een programma gereed om 
                               te draaien.
* Fouten maken::             Een foutboodschap genereren
* Namen en definities::      Namen van symbolen en functie-definities.
* Lisp interpreter::         Wat de Lisp interpreter doet.
* Evaluatie::                Een programma draaien
* Variabelen::               Een waarde van een variabele teruggeven
* Argumenten::               Informatie doorgeven aan een functie
* setq::                     De waarde van een variabele zetten.
* Samenvatting::             De belangrijkste punten
* Foutmelding oefeningen::   Foutmelding oefeningen
@end menu

@node Lisp lijsten
@section Lisp lijsten
@cindex Lisp lijsten

In Lisp ziet een lijst er zo uit: @code{'(roos viool madelief
boterbloem)}. Deze lijst wordt voorafgegaan door een enkele apostrof. Het
kon net zo goed als volgt geschreven worden, wat meer lijkt op de soort van
lijsten waar je waarschijnlijk bekend mee bent:

@smallexample
@group
'(roos
  viool
  madelief
  boterbloem)
@end group
@end smallexample

@noindent
De elementen van deze lijst zijn de namen van vier verschillende bloemen,
onderling gescheiden door witte ruimte en omgeven door haakjes, net als
bloemen in een veld met een stenen muur er omheen.
@cindex Bloemen in een veld

@menu
* Genummerde lijsten::       Lijsten bevatten getallen en andere lijsten
* Lisp atomen::              Elementaire entiteiten
* Whitespace in lijsten::    Lijsten leesbaar formatteren
* Typen van lijsten::        Hoe GNU Emacs helpt bij het typen van lijsten
@end menu

@ifnottex
@node Genummerde lijsten
@unnumberedsubsec Getallen, lijsten binnen lijsten
@end ifnottex

Lijsten kunnen ook getallen bevatten, zoals deze lijst: @code{(+ 2 2)}. Deze
lijst heeft een plusteken, @samp{+}, gevolgd door twee @samp{2}-en,
onderling gescheiden met witte ruimte.

In Lisp worden zowel data als programma's op dezelfde manier
gerepresenteerd. Het zijn beiden lijsten van woorden, getallen, andere
lijsten, gescheiden door witte ruimte en omgeven door haakjes. (Omdat een
programma er uit ziet als data, kan het ene programma makkelijk dienen als
data voor een ander; dit is een erg krachtige eigenschap van Lisp.)
(Overigens, deze twee opmerkingen tussen haakjes zijn @emph{geen} Lisp
lijsten, omdat zij @samp{;} en @samp{.} als leesteken bevatten.) 

@need 1200
Hier is een andere lijst, deze keer met daarin een lijst.

@smallexample
'(deze lijst heeft (van binnen een lijst))
@end smallexample

De componenten van deze lijst zijn de woorden @samp{deze}, @samp{lijst},
@samp{heeft} en de lijst @samp{(van binnen een lijst)}. De binnenste lijst
bestaat uit de woorden @samp{van}, @samp{binnen}, @samp{een} en
@samp{lijst}. 

@node Lisp atomen
@subsection Lisp atomen
@cindex Lisp atomen

Wat we woorden genoemd hebben, heten in Lisp @dfn{atomen}. Deze term komt
van de historische betekenis van het woord atoom, wat ``onscheidbaar''
betekent. Wat Lisp betreft kunnen de woorden die we in de lijst gebruikt
hebben niet in kleinere delen opgedeeld worden en nog steeds dezelfde
betekenis als onderdeel van een programma hebben, net als getallen en
enkele-karakter symbolen zoals @samp{+}. Aan de andere kant, in
tegenstelling tot het oude atoom, kan een lijst in delen worden
opgesplitst. (@xref{car cdr en cons, , @code{car} @code{cdr} en @code{cons}
Fundamentele functies}.) 

In een lijst worden atomen onderling gescheiden door witte ruimte. Zij
kunnen meteen naast een haakje staan.

@cindex @samp{empty list} gedefinieerd
Technisch gesproken bestaat een lijst in Lisp uit haakjes rondom atomen
gescheiden door witte ruimte of rondom andere lijsten of rondom zowel atomen
als andere lijsten. Een list kan slechts een atoom bevatten, of helemaal
niets bevatten. Een lijst met niets er in ziet er zo uit: @code{()}, en heet
een @dfn{lege lijst}. In tegenstelling tot alles anders wordt een lege lijst
tegelijk zowel als een atoom als een lijst beschouwd. 

@cindex Symbolische expressies, geïntroduceerd
@cindex @samp{expressie} gedefinieerd
@cindex @samp{vorm} gedefinieerd
De afgedrukte representatie van zowel atomen als lijsten heten
@dfn{symbolische expressies} of, korter, @dfn{s-expressies}. Het woord
@dfn{expressie} op zichzelf kan hetzij naar de afgedrukte representatie
hetzij naar het atoom of lijst zoals die intern in de computer staat
verwijzen. Vaak gebruiken mensen de term @dfn{expressie} willekeurig. (Ook
wordt in veel teksten het woord @dfn{vorm} gebruikt als synoniem voor
expressie.)

@c This and the next paragraph say ``kinds of atom'', but that is not
@c a typo, just slightly ``old-fashioned wording which adds a fillip
@c of interest to it'', and ``is more elegant writing'', according to
@c RMS.
Toevallig werden de atomen waaruit ons universum bestaat zo genoemd omdat
men dacht dat ze ondeelbaar zijn, maar er is vastgesteld dat fysieke atomen
niet ondeelbaar zijn. Deeltjes kunnen van een atoom afsplitsen of het kan
zich in twee ongeveer even grote delen opsplitsen. Fysieke atomen werden
voortijdig zo genoemd, voordat hun ware aard was ontdekt. In Lisp kunnen
sommige soorten atomen, zoals een array, in delen worden gescheiden, maar
het mechanisme om dit te doen wijkt af van het mechanisme om een lijst op te
splitsen. Voor zover het lijst-operaties betreft, zijn de atomen van een
lijst ondeelbaar.

Net als in het Engels, is de betekenis van de samenstellende letters van een
Lisp atoom verschillend van de betekenis die de letters als woord
maken. Bijvoorbeeld het Engelse woord voor de Zuid-Amerikaanse luiaard,
@samp{ai}, is volledig anders dan de twee Engelse woorden @samp{a} en
@samp{i}. 

In de natuur bestaan veel verschillende soorten atomen, maar slechts een
paar in Lisp: bijvoorbeeld @dfn{getallen}, zoals 37, 511 of 1729, en
@dfn{symbolen}, zoals @samp{+}, @samp{foo}, of @samp{forward-line}. In het
dagelijks Lisp taalgebruik wordt het woord ``atoom'' maar weinig gebruikt,
omdat programmeurs meestal specifieker zijn over het soort atoom waar ze mee
te maken hebben. Lisp programmeren betreft hoofdzakelijk symbolen (en soms
getallen) binnen lijsten. (Overigens, de voorgaande opmerking met drie
woorden tussen haakjes is een geldige lijst in Lisp, omdat het uit atomen
bestaat, welke in dit geval symbolen zijn, gescheiden door witte ruimte en
omgeven door haakjes, zonder enige non-Lisp leestekens.)

@need 1250
Tekst tussen dubbele aanhalingstekens ---zelfs zinnen en paragrafen--- is
ook een atoom.  Hier is een voorbeeld:
@cindex Tekst tussen dubbele aanhalingstekens

@smallexample
'(deze lijst bevat "tekst tussen aanhalingstekens.")
@end smallexample

@cindex @samp{string} gedefinieerd
@noindent
In Lisp is alle gequote tekst inclusief leestekens en witte ruimte een
enkele atoom. Deze atoom-soort heet een @dfn{string} (wegens ``string of
characters'') en is het soort dingen dat gebruikt wordt voor boodschappen
die de computer toont om door mensen gelezen te worden. Strings zijn een
andere atoom-soort dan getallen of symbolen en worden anders gebruikt.

@node Whitespace in lijsten
@subsection Whitespace in lijsten
@cindex Witte ruimte in lijsten

@need 1200
De hoeveelheid witte ruimte in een lijst maakt niet uit. Vanuit het
gezichtspunt van de Lisp taal, is

@smallexample
@group
'(deze lijst
    lijkt op dit)
@end group
@end smallexample

@need 800
@noindent
exact hetzelfde als dit:

@smallexample
'(deze lijst lijkt op dit)
@end smallexample

Beide voorbeelden tonen wat Lisp als dezelfde lijst ziet, de lijst
samengesteld uit de symbolen @samp{deze}, @samp{lijst}, @samp{lijkt},
@samp{op} en @samp{dit} in die volgorde.

Extra witte ruimte en regels zijn bedoeld om de lijst meer voor mensen
leesbaar te maken. Wanneer Lisp de expressie leest, verwijdert het alle
extra witte ruimte (maar heeft tenminste een spatie tussen de atomen nodig
om ze uit elkaar te houden).

Hoe vreemd het ook lijkt, de voorbeelden die we gezien hebben dekken alles
hoe lijsten er uit zien! Elke andere lijst in Lisp ziet er min of meer
hetzelfde uit als een van deze voorbeelden, behalve dat de lijst langer of
meer complex kan zijn. In het kort, een lijst is tussen haakjes, een string
tussen aanhalingstekens, een symbool ziet er uit als een woord en een getal
als een getal. (Voor bepaalde situaties worden vierkante haken, punten en
enkele andere speciale karakters gebruikt, maar we gaan vrij ver zonder
hen.)

@node Typen van lijsten
@subsection GNU Emacs helpt je om lijsten te typen
@cindex Hulp bij lijsten typen
@cindex Hulp bij formatteren

Wanneer je een Lisp expressie in GNU Emacs typt, met hetzij Lisp Interaction
mode of Emacs Lisp mode, dan zijn verschillende commando's beschikbaar om de
Lisp expressie zo te formatteren dat deze makkelijk te lezen
is. Bijvoorbeeld het indrukken van de @key{TAB}-toets laat de regel waar de
cursor is automatisch met de juiste hoeveelheid inspringen. Het commando om
de code in een region juist te laten inspringen is normaal gesproken
gebonden aan @kbd{C-M-\}. De inspringingen zijn ontworpen om te laten zien
welke elementen van een lijst bij welke lijst horen---elementen van een
sub-lijst springen meer in dan elementen van de insluitende lijst.

Bovendien, wanneer je een haakje sluiten typt, dan laat Emacs tijdelijk de
cursor terugspringen naar het bijbehorende haakje openen, zodat je kunt zien
welke dat is. Dit is erg zinvol, omdat elke lijst die je typt in Lisp een
haakje sluiten horend bij zijn haakje openen moet hebben. (@xref{Major
Modes, , Major Modes, emacs, The GNU Emacs Manual}, voor meer informatie
over Emacs's modes.)

@node Draai een programma
@section Draai een programma
@cindex Een programma draaien
@cindex Draai een programma

@cindex @samp{evaluate} gedefinieerd
Een lijst in Lisp---elke lijst---is een programma om te draaien. Wanneer je
het draait (wat in Lisp-jargon @dfn{evalueren} is), doet de computer een van
deze drie dingen: doe niets behalve de lijst zelf teruggeven; een
foutmelding geven; of het eerste symbool in de lijst behandelen als commando
om iets te doen. (Meestal is dat laatste natuurlijk wat je echt wilt!)

@c use code for the single apostrophe, not samp.
@findex quote
@cindex @code{'} om te quoten
@cindex quoten met de apostrof
@cindex apostrof om te quoten
De enkele apostrof, @code{'}, die ik aan de voorkant van enkele voorbeeld
lijsten in de voorgaande hoofdstukken gebruikte, heten een
@dfn{quote}. Wanneer die aan een lijst voorafgaan, dan vertelt dat Lisp om
niets met de lijst te doen, anders dan te accepteren precies zoals die is
geschreven. Maar wanneer er geen quote aan de lijst voorafgaat, dan is het
eerste element in de lijst speciaal: het is een commando voor de computer om
te gehoorzamen. (In Lisp, heten deze commando's @emph{functies}.) De eerder
genoemde lijst @code{(+ 2 2)} is een instructie om iets met de rest van de
lijst te doen: tel de getallen die volgen op.

@need 1250
Wanneer je dit binnen GNU Emacs in Info leest, dan kun je de lijst als volgt
evalueren: ga met de cursor direct achter het rechtse haakje sluiten staan
van de volgende lijst en typ vervolgens @kbd{C-x C-e}:

@smallexample
(+ 2 2)
@end smallexample

@c use code for the number four, not samp.
@noindent
Je ziet het getal @code{4} verschijnen in het echogebied @footnote{  Emacs
toont integer waardes in decimaal, in octaal en in hex en ook  als een
karakter, maar laten we deze gemaksfunctie nu even negeren.}. (Wat je
zojuist gedaan hebt is het evalueren van de lijst. Het  echogebied is de
regel aan de onderkant van het scherm dat de  echotekst toont.) Probeer nu
hetzelfde met een gequote lijst: plaats  de cursor meteen achter de volgende
lijst en type @kbd{C-x C-e}:

@smallexample
'(dit is een gequote lijst)
@end smallexample

@noindent
Je ziet @code{(dit is een gequote lijst)} in het echogebied verschijnen.

@cindex Lisp interpreter, uitgelegd
@cindex Interpreter, Lisp, uitgelegd
Wat je in beide gevallen deed is het geven van een commando aan een
programma in GNU Emacs met de naam @dfn{Lisp interpreter}---de interpreter
een commando geven om de expressie te evalueren. De naam van de Lisp
interpreter komt van het woord voor de taak die een mens uitvoert die de
betekenis van de expressie bedenkt---die het interpreteert.

Je kunt ook een atoom evalueren dat geen deel van een lijst is---een die
niet door haakjes ingesloten is. Weer vertaalt de Lisp interpreter van de
voor mensen leesbare expressie naar de taal van de computer. Maar voor we
dit bespreken (@pxref{Variabelen}), bespreken we eerste wat de Lisp
interpreter doet wanneer je een fout maakt. 

@node Fouten maken
@section Een foutmelding genereren
@cindex Genereer een foutmelding
@cindex Foutmelding generatie

Deels zodat je je geen zorgen hoeft te maken wanneer je het per ongeluk
doet, geven we nu een commando aan de Lisp interpreter dat een foutmelding
genereert. Dit is een onschuldige activiteit, en wij zullen inderdaad vaker
proberen expres een foutmelding te genereren. Wanneer je eenmaal het jargon
begrijpt, kunnen foutmeldingen informatief zijn. In plaats van
``fout''-meldingen zouden ze ``hulp''-meldingen moeten heten. Zij zijn als
wegwijzers voor een reiziger in een vreemd land. Ze ontcijferen kan moeilijk
zijn, maar wanneer je ze begrijpt wijzen ze je de weg.

De foutmelding wordt gegenereerd door een ingebouwde GNU Emacs debugger. Wij
gaan de debugger binnen. Je verlaat de debugger met het typen van @code{q}.

Wat we gaan doen is het evalueren van een lijst die niet gequote is en niet
een betekenisvol commando als eerste element heeft. Hier is een lijst die
bijna gelijk is aan die we niet gebruikt hebben, maar zonder de voorafgaande
enkele quote. Positioneer de cursor direct er achter en type @kbd{C-x C-e}:

@smallexample
(dit is een ongequote lijst)
@end smallexample

Een @file{*Backtrace*} window opent waarin je het volgende zou moeten zien:

@smallexample
@group
---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-function dit)
  (dit is een ongequote lijst)
  eval((dit is een ongequote lijst) nil)
  elisp--eval-last-sexp(nil)
  eval-last-sexp(nil)
  funcall-interactively(eval-last-sexp nil)
  call-interactively(eval-last-sexp nil nil)
  command-execute(eval-last-sexp)
---------- Buffer: *Backtrace* ----------
@end group
@end smallexample

@need 1200
@noindent
Je cursor staat in dit venster (mogelijk moet je een paar seconden wachten
voordat het zichtbaar wordt). Om de debugger af te sluiten en het venster te
laten verdwijnen, typ je:

@smallexample
q
@end smallexample

@noindent
Gelieve @kbd{q} nu te typen, zodat je zelfverzekerd de debugger weet te
verlaten. Type vervolgens weer @kbd{C-x C-e} om er opnieuw in te gaan.

@cindex @samp{functie} gedefinieerd
Gebaseerd op wat we al weten, kunnen we bijna deze foutmelding lezen.

Je leest de @file{*Backtrace*} buffer van beneden naar boven; het vertelt je
wat Emacs deed. Toen je @kbd{C-x C-e} typte, maakte je een interactieve
aanroep naar het commando @code{eval-last-sexp}. @code{eval} is een
afkorting van ``evalueer'' en @code{sexp} is een afkorting voor
``symbolische expressie'', de expressie vlak voor de cursor.

Elke regel er boven vertelt je wat de Lisp interpreter er na evalueerde. De
meest recente actie staat bovenaan. Het buffer heet het @file{*Backtrace*}
buffer omdat het je in staat stelt Emacs achterwaarts te volgen.

@need 800
Bovenaan het  @file{*Backtrace*} buffer zie je de regel:

@smallexample
Debugger entered--Lisp error: (void-function dit)
@end smallexample

@noindent
De Lisp interpreter probeerde het eerste atoom van de lijst te evalueren,
het woord @samp{dit}. Het is deze actie die de foutmelding
@samp{(void-function dit)} genereerde.

De melding bevat de woorden @samp{void-function} en @samp{dit}.

@cindex @samp{functie} gedefinieerd
Het woord @samp{functie} is een keer eerder genoemd. Het is een erg
belangrijk woord. Voor onze doeleinden kunnen we definiëren door te zeggen
dat een @samp{functie} een verzameling instructies is die de computer
vertellen iets te doen.

Nu beginnen we de foutmelding te begrijpen: @samp{void-function dit}. De
functie (het woord @samp{dit}) heeft geen definitie van enige verzameling
instructies voor de computer om uit te voeren.

Het ietwat vreemde woord @samp{void-function} is ontworpen voor de manier
waarop Emacs Lisp is geïmplementeerd, dat is wat het doet wanneer een
symbool geen functiedefinitie heeft waaraan het gekoppeld is, de plaats die
de instructies zou moeten bevatten is leeg.

Aan de andere kant, omdat we in staat waren 2 plus 2 succesvol op te tellen
door @code{(+ 2 2)} te evalueren, kunnen we afleiden dat het symbool
@code{+} een verzameling instructies moet hebben voor de computer om te
gehoorzamen en dat deze instructies het optellen van de getallen achter de
@code{+} moeten zijn.

Het is mogelijk te voorkomen dat Emacs de debugger in gaat in situaties
zoals deze. Hier leggen we niet uit hoe je dat doet, maar we vertellen hoe
het resultaat er uit ziet, omdat je een vergelijkbare situatie kunt
tegenkomen wanneer er een bug zit in de Emacs code die je gebruikt. In zulke
gevallen zie je een foutmelding met maar een regel, het verschijnt in het
echogebied en ziet er als volgt uit:

@smallexample
Symbol's function definition is void:@: dit
@end smallexample

@noindent
@ignore
(Also, your terminal may beep at you---some do, some don't; and others
blink.  This is just a device to get your attention.)
@end ignore
De melding gaat weg zodra je een toets aanslaat of zelfs de cursor
verplaatst.

We kennen de betekenis van het woord @samp{Symbool}. Het refereert naar de
eerste atoom van de lijst, het woord @samp{dit}. Het woord @samp{functie}
refereert naar de instructies die de computer vertellen wat te
doen. (Technisch gezien, vertelt het symbool de computer waar de instructies
zijn te vinden, maar dit is een complicatie dit we op dit moment kunnen
negeren.)

De foutmelding kan begrepen worden: @samp{Symbol's function definition is
void:@: dit}. Het symbool (het woord @samp{dit}) mist instructies die de
computer kan uitvoeren.

@node Namen en definities
@section Symboolnamen en functiedefinities
@cindex Symboolnamen

We kunnen een ander kenmerk van Lisp verwoorden op basis van wat we tot nu
toe besproken hebben---en belangrijk kenmerk: een symbool, zoals @code{+},
is zelf geen verzameling van instructies die de computer kan uitvoeren. In
plaats daarvan wordt het symbool gebruikt, misschien tijdelijk, als een
manier om de instructies te lokaliseren. Namen van mensen werken op de
zelfde manier. Ik kan worden gerefereerd als @samp{Bob}. Ik ben echter niet
de letters @samp{B}, @samp{o} en @samp{b} maar ik ben of was het bewustzijn
dat consequent met een bepaalde levensvorm wordt geassocieerd. De naam is
niet mij, maar het kan worden gebruikt om naar mij te refereren. 

In Lisp kan een enkele verzameling instructies meerdere namen hebben. De
computer instructies om getallen op te tellen kan bijvoorbeeld zijn
gekoppeld aan zowel het symbool @code{plus} als het symbool @code{+} (en
zijn dat in sommige Lisp-dialecten). Onder mensen kan ik gerefereerd met
zowel @samp{Robert} als met  @samp{Bob} en ook nog andere woorden.

Aan de andere kant kan maar aan een functiedefinitie tegelijk zijn
gekoppeld. Anders zou de computer in verwarring raken over welke definitie
te gebruiken. Wanneer dit onder mensen het geval zou zijn, dan kan er in de
hele wereld maar een persoon de naam @samp{Bob} hebben. Echter de
functiedefinitie naar de naam naar refereert kan makkelijk worden
aangepast. (@xref{Installeer, , Installeer een functiedefinitie}.)

Omdat Emacs erg groot is, is het gebruikelijk om de symbolen zo te benoemen
dat zij het deel van Emacs waar zij thuishoren identificeren. Alle namen
voor functies die met Texinfo te maken hebben beginnen met @samp{texinfo-}
en die voor de functies die met e-mail lezen te maken hebben beginnen met
@samp{rmail-}.

@node Lisp interpreter
@section De Lisp interpreter
@cindex Lisp interpreter, wat die doet
@cindex Lisp interpreter, wat die doet

Op basis van wat we nu gezien hebben kunnen we beginnen te achterhalen wat
de Lisp interpreter doet wanneer we de opdracht geven een lijst te
evalueren. Eerst kijkt die of er een quote voor de lijst staat. Als die er
is, dan geeft de interpreter ons slechts de lijst. Aan de andere kant, als
er geen quote is, dan kijkt de interpreter naar het eerste element van de
lijst om te zien of die een functiedefinitie heeft. Wanneer dat het geval
is, dan voert de interpreter de instructies in de functiedefinitie uit. Zo
niet, dan drukt de interpreter een foutmelding af. 

Dit is hoe Lisp werkt. Simpel. Er zijn aanvullende complicaties waar we zo
aan toe komen, maar dit zijn de basisprincipes. Om Lisp-programma's te
schrijven moet je natuurlijk weten hoe je functiedefinities schrijft en aan
een naam koppelt, en hoe je dit doet zonder zelf of de computer in
verwarring te brengen.

@menu
* Complicaties::             Variabelen, speciale vormen, lijsten daarbinnen
* Byte compiling::           Speciale verwerkingscode voor snelheid.
@end menu

@ifnottex
@node Complicaties
@unnumberedsubsec Complicaties
@end ifnottex

Nu komt de eerste complicatie. Naast lijsten kan de Lisp interpreter een
symbool evalueren dat niet is gequote en niet tussen haakjes staat. De Lisp
interpreter zal proberen de waarde van het symbool als een @dfn{variabele}
te bepalen. Deze situatie wordt besproken in het hoofdstuk over
variabelen. (@xref{Variabelen}.)

@cindex Speciale vorm
De tweede complicatie ontstaat doordat sommige functies ongebruikelijk zijn
en niet op de normale manier werken. Zij die dat niet doen worden
@dfn{speciale vormen} genoemd. Zij worden voor speciale taken gebruikt,
zoals het definieren van een functie, er er zijn er niet veel van. In enkele
van de volgende hoofdstukken maak je kennis met verschillende belangrijkere
speciale vormen.

Naast speciale vormen zijn er ook @dfn{macros}. Een macro is een in Lisp
gedefineerde constructie die afwijkt van een functie omdat het een Lisp
expressie vertaalt in een andere expressie, die in plaats van de orginele
expressie geëvalueerd gaat worden. 

Voor deze introductie hoef je je niet al te veel zorgen te maken of iets een
speciale vorm, een macro of een gewone functie is. @code{if} bijvoorbeeld is
een speciale vorm (@pxref{if}), maar @code{when} is een macro. In eerdere
versies van Emacs was @code{defun} een speciale vorm, maar nu is het een
macro (@pxref{defun}). Het gedraagt zich nog steeds op dezelfde manier. 

De laatste complicatie is het volgende: wanneer een functie waar de Lisp
interpreter naar kijkt geen speciale vorm is, en deel van een lijst
uitmaakt, dan kijkt de interpreter of de lijst een lijst in zich
bevat. Wanneer er een binnenliggende lijst is, dan zoekt de interpreter
eerst uit wat het moet doen met die binnenliggende lijst en daarna gaat die
met de buitenste lijst aan de slag. Als er weer een lijst opgenomen is in de
binnenliggende lijst, dan werkt die eerst aan die lijst, enzovoorts. Het
begint steeds met de meest binnenliggende lijst, om het resultaat van die
lijst te evalueren. Het resultaat kan gebruikt worden door de omsluitende
expressie. 

Zo niet, dan werkt de interpreter van links naar rechts, van de ene
expressie naar de ander.

@node Byte compiling
@subsection Byte compiling
@cindex Byte compiling

Een ander aspect van interpreteren: de Lisp interpreter is in staat om twee
soorten entiteiten te interpreteren: voor mensen leesbare code, op welke wij
ons exclusief richten, en speciaal geproduceerde code, @dfn{byte compiled}
code genoemd, die niet door mensen te lezen is. Byte compiled code draait
sneller dan voor mensen leesbare code.

Je transformeert voor mensen leesbare code in byte compiled code met een van
de compile commando's zoals @code{byte-compile-file}. Byte compiled code is
meestal opgeslagen in een bestand dat eindigt met de extensie
@file{.elc}. Je ziet beide soorten bestanden in de @file{emacs/lisp}
directory. De bestanden om te lezen zijn die met de extensie @file{.el}.

Praktisch gesproken, voor de meeste dingen die je doet om Emacs aan te
passen of uit te breiden is er geen noodzaak voor byte compile, en ik
bespreek dit onderwerp hier niet. @xref{Byte Compilation, , Byte
Compilation, elisp, The GNU Emacs Lisp  Reference Manual}, voor een
volledige beschrijving van byte compilation.

@node Evaluatie
@section Evaluatie
@cindex Evaluatie

Wanneer de Lisp interpreter een expressie verwerkt, dan is de term voor die
activiteit @dfn{evaluatie}. We zeggen dat de interpreter ``de expressie
evalueert''. Ik heb deze term verschillende keren eerder gebruikt. Het woord
komt van het gebruik in alledaagse taal, ``de waarde vaststellen'',
``taxeren'', volgens de @cite{Webster's New Collegiate Dictionary}.

@menu
* Hoe de interpreter werkt::  Returns en zij-effecten...
* Geneste lijsten evalueren::  Lijsten binnen lijsten...
@end menu

@ifnottex
@node Hoe de interpreter werkt
@unnumberedsubsec Hoe de Lisp interpreter acteert
@end ifnottex

@cindex @samp{teruggegeven waarde} uitgelegd
Na het evalueren van een expressie zal de Lisp interpreter
hoogstwaarschijnlijk de waarde @dfn{teruggeven} die de computer produceert
bij het uitvoeren van de instructies die die in de functiedefinitie vondt,
of misschien geeft die de functie op en produceert een foutmelding. (De
interpreter kan bij wijze van spreken ook naar een andere functie geworpen
worden, of het kan proberen continue wat het doet voor altijd en eeuwig te
herhalen in een oneindige loop. Deze activiteiten zijn minder gebruikelijk
en wij kunnen ze negeren.) Meestal geeft de interpreter een waarde terug.

@cindex @samp{zij-effect} gedefinieerd
Op hetzelfde moment dat de interpreter een waarde terug geeft kan het ook
iets anders doen, zoals de cursor verplaatsen of een bestand kopiëren. Deze
andere soort activiteit heet een @dfn{zij-effect}. Acties die wij belangrijk
vinden, zoals het tonen van resultaten, zijn vaak zij-effecten voor de Lisp
interpreter. Het is vrij eenvoudig te leren hoe deze zij-effecten te
gebruiken.

Samenvattend, het meest gebruikelijk is dat het evalueren van een
symbolische expressie zorgt dat de Lisp interpreter een waarde teruggeeft en
misschien ook een zij-effect uitvoert, of anders een fout produceert.

@node Geneste lijsten evalueren
@subsection Geneste lijsten evalueren
@cindex Binnenste lijst evaluatie
@cindex Het evalueren van een binnenste lijst

Wanneer de evaluatie van toepassing is op een lijst die binnen een andere
lijst zit, kan de omsluitende lijst de waarde gebruiken van de eerste
evaluatie als informatie bij het evalueren van de omsluitende lijst. Dit
verklaart waarom de binnenste expressies het eerst worden geëvalueerd: de
waarden die zij teruggeven worden gebruikt door de buitenliggende
expressies. 

@need 1250
Wij kunnen dit proces onderzoeken door het evalueren van een ander
optelvoorbeeld. Plaats je cursor achter de volgende expressie en type
@kbd{C-x C-e}: 

@smallexample
(+ 2 (+ 3 3))
@end smallexample

@noindent
Het getal 8 zal in het echogebied verschijnen.

Wat er gebeurt is dat de Lisp interpreter eerst de waarde van de binnenste
expressie, @code{(+ 3 3)} evalueert, wat de waarde 6 teruggeeft. Vervolgens
evalueert het de buitenste expressie alsof die als @code{(+ 2 6)} geschreven
was, wat de waarde 8 teruggeeft. Omdat er geen omsluitende expressies meer
te evalueren zijn, toont de interpreter de waarde in het echogebied.

Nu is de naam van het commando aangeroepen met de toetsaanslagen @kbd{C-x
C-e} te begrijpen: de naam is @code{eval-last-sexp}. De letters @code{sexp}
zijn een afkorting van ``symbolische expressie'', en @code{eval} is een
afkorting van ``evalueer''. Het commando evalueert de laatste symbolische
expressie.

Als een experiment kan je proberen de expressie te evalueren door de cursor
aan het begin van de regel direct onder de expressie te plaatsen, of binnen
de expressie.

@need 800
Hier is een andere kopie van de expressie:

@smallexample
(+ 2 (+ 3 3))
@end smallexample

@noindent
Als je de cursor aan het begin van de lege regel die onmiddellijk op de
expressie volgt plaatst en je @kbd{C-x C-e} typt, krijg je nog steeds de
waarde 8 getoond in het echogebied. Probeer nu de cursor binnen de expressie
te plaatsen. Als je die rechts achter het een-na-laatste haakje plaatst
(zodat het lijkt of die bovenop het laatste haakje zit), dan krijg je een 6
getoond het echogebied! Dit is omdat het commando de expressie @code{(+ 3
3)} evalueert.

Plaats nu de cursor direct achter een getal. Typ @kbd{C-x C-e} en je krijgt
het getal zelf. Wanneer je in Lisp een getal evalueert, dan krijg je het
getal zelf---dit is hoe getallen verschillen van symbolen. Wanneer je een
lijst evalueert die begint met een symbool zoals @code{+}, dan krijg je de
waarde terug die het resultaat is van de computer die de instructies
uitvoert die zijn gekoppeld aan die naam. Wanneer je het symbool op zichzelf
evalueert, dan gebeurt er iets anders, zoals we in het volgende hoofdstuk
zien. 

@node Variabelen
@section Variabelen
@cindex Variabelen

In Emacs Lisp kan een symbool een waarde aan zich gekoppeld hebben, net
zoals het een functiedefinitie aan zich gekoppeld kan hebben. Die twee zijn
verschillend. De functiedefinitie is een verzameling instructies die de
computer zal gehoorzamen. Daartegenover is een waarde iets, zoals een getal
of een naam die kan variëren (daarom wordt zo'n symbool een variabele
genoemd). De waarde van een symbool kan elke expressie in Lisp zijn, zoals
een symbool, getal, lijst of string. Een symbool die een waarde heeft wordt
vaak een @dfn{variabele} genoemd.

Een symbool kan zowel een functiedefinitie als een waarde tegelijkertijd aan
zich gekoppeld hebben. Of het kan slechts een van die tee hebben. De twee
staan los van elkaar. Dit is ongeveer vergelijkbaar me de manier waarop
Cambridge kan refereren naar een stad in Massachusetts en informatie aan de
naam gekoppeld kan hebben, zoals ``geweldig programmeercentrum''.

@ignore
(Incidentally, in Emacs Lisp, a symbol can have two
other things attached to it, too: a property list and a documentation
string; these are discussed later.)
@end ignore

Een andere manier om hierover te denken is een symbool voor te stellen als
een ladekast. De functiedefinitie wordt in de ene lade gestopt, de waarde in
een andere, enzovoorts. Wat in de lade die de waarde bevat gestopt is kan
worden veranderd zonder effect te hebben op de lade die de functiedefinitie
bevat, en omgekeerd. 

@menu
* fill-column voorbeeld::    fill-column voorbeeld
* Void functie::             De foutmelding voor een symbool zonder functie.
* Void variabele::           De foutmelding voor een symbool zonder waarde.
@end menu

@ifnottex
@node fill-column voorbeeld
@unnumberedsubsec @code{fill-column}, een voorbeeldvariabele
@end ifnottex

@findex fill-column@r{, een voorbeeldvariabele}
@cindex Voorbeeldvariabele, @code{fill-column}
@cindex Variabele, voorbeeld van, @code{fill-column}
De variabele @code{fill-column} illustreert een symbool waar een waarde aan
gekoppeld is. In elk GNU Emacs buffer is dit symbool op een bepaalde waarde
ingesteld, meetal 72 of 70, maar soms een andere waarde. Om de waarde van
dit symbool te vinden evalueer je het op zichzelf. Wanneer je dit in Info
binnen GNU Emacs leest, dan doe je dit door de cursor achter het symbool te
zetten en vervolgens @kbd{C-x C-e} te typen:

@smallexample
fill-column
@end smallexample

@noindent
Nadat ik @kbd{C-x C-e} typte, toonde Emacs het getal 72 in mijn
echogebied. Dit is waarde waar voor mij @code{fill-column} op is ingesteld
terwijl ik dit schrijf. Het kan verschillend zijn in jouw Infobuffer. Merk
op dat de waarde die de variabele teruggeeft op precies dezelfde manier
wordt getoond als de waarde die teruggeven wordt door een functie die zijn
instructies uitvoert. Vanuit het gezichtspunt van de Lisp interpreter is een
teruggeven waarde een teruggegeven waarde. Van wat voor soort expresse het
vandaan kwam doet er niet meer toe zodra de waarde bekend is.

Een symbool kan elke waarde aan zich gekoppeld hebben, of om het jargon te
gebruiken, we kunnen de variabele aan een waarde @dfn{binden}: aan een
getal, zoals 72, aan een string @code{"zoals deze"}, aan een lijst, zoals
@code{(spar den eik)}; we kunnen zelfs een variabele aan een
functiedefinitie binden.

Een symbool kan op verschillende manieren aan een waarde worden
gebonden. @xref{setq, , De waarde van een variabele zetten}, voor informatie
over een manier om dit te doen.

@node Void functie
@subsection Foutmelding voor een symbool zonder functie
@cindex Symbool zonder functie foutmelding
@cindex Fout van symbool zonder functie

Bij het evalueren van @code{fill-column} om de waarde daarvan als een
variabele te ontdekken, plaatsten we geen haakjes rondom het woord. Dit is
omdat we het niet als functienaam wilden gebruiken.

Wanneer @code{fill-column} het eerste of enige element van een lijst was,
zou de Lisp interpreter proberen de er aangekoppelde functiedefinitie te
vinden. Maar @code{fill-column} heeft geen functiedefinitie. Probeer dit te
evalueren:

@smallexample
(fill-column)
@end smallexample

@need 1250
@noindent
Je maakt een @file{*Backtrace*} buffer dat het volgende toont:

@smallexample
@group
---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-function fill-column)
  (fill-column)
  eval((fill-column) nil)
  elisp--eval-last-sexp(nil)
  eval-last-sexp(nil)
  funcall-interactively(eval-last-sexp nil)
  call-interactively(eval-last-sexp nil nil)
  command-execute(eval-last-sexp)
---------- Buffer: *Backtrace* ----------
@end group
@end smallexample

@noindent
(Onthoud, om de debugger te sluiten en het debugger window te laten
verdwijnen typ je @kbd{q} in het @file{*Backtrace*} buffer.)

@node Void variabele
@subsection Foutmelding voor een symbool zonder waarde
@cindex Symbool zonder waarde fout
@cindex Fout voor symbool zonder waarde

Wanneer je een symbool dat geen waarde aan zich gekoppeld heeft probeert te
evalueren, dan krijg je een foutmelding. Dit kan je zien door te
experimenteren met onze 2 plus 2 optelling. Zet de cursor meteen achter de
@code{+}, voor het eerste getal 2 in de volgende expressie, en typ @kbd{C-x
C-e}:

@smallexample
(+ 2 2)
@end smallexample

@need 1500
@noindent
In GNU Emacs 22 maak je een @file{*Backtrace*} buffer dat het volgende
toont:

@smallexample
@group
---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-variable +)
  eval(+)
  elisp--eval-last-sexp(nil)
  eval-last-sexp(nil)
  funcall-interactively(eval-last-sexp nil)
  call-interactively(eval-last-sexp nil nil)
  command-execute(eval-last-sexp)
---------- Buffer: *Backtrace* ----------
@end group
@end smallexample

@noindent
(Je sluit de debugger opnieuw door @kbd{q} in het @file{*Backtrace*} buffer
te typen.)

Deze backtrace verschilt van de allereerste foutmelding die we zagen, die
toonde @samp{Debugger entered--Lisp error: (void-function dit)}. In dit
geval heeft de functie geen waarde als variabele, terwijl in de andere
foutmelding, de functie (het woord @samp{dit}) geen definitie had.

Wat we in het experiment met de @code{+} deden liet de Lisp interpreter de
@code{+} evaluaren en zoeken naar de waarde van de variabele in plaats van
de functiedefinitie. We deden dit door de cursor meteen achter het symbool
te plaatsen in plaats van achter het haakje van de omsluitende lijst, zoals
we eerder deden. Als gevolg hiervan evalueerde de Lisp interpreter de
voorafgaande s-expressie, in dit geval @code{+} op zichzelf.

Omdat @code{+} geen waarde aan zich gekoppeld heeft en alleen een
functiedefinitie, rapporteerde de foutmelding dat de waarde van het symbool
als variabele leeg was.

@node Argumenten
@section Argumenten
@cindex Argumenten
@cindex Informatie naar functies doorgeven

Laten we nog eens naar ons oude voorbeeld kijken om te zien hoe informatie
tussen functies doorgegeven wordt, de optelling van twee plus twee. In Lisp
schrijven we dit als volgt:

@smallexample
(+ 2 2)
@end smallexample

Wanneer je deze expressie evalueert verschijnt het getal in je
echogebied. Wat de Lisp interpreter doet is het optellen van de getallen die
volgen na de @code{+}.

@cindex @samp{argument} gedefinieerd
De getallen toegevoegd aan @code{+} heten de @dfn{argumenten} van de functie
@code{+}. Deze getallen vormen de informatie die @dfn{doorgegeven} wordt aan
de de functie.

Het woord ``argument'' komt van de manier waarop het gebruikt wordt in
wiskunde en refereert niet naar een dispuut tussen twee mensen. In plaats
daarvan refereert het naar de informatie gegeven aan een functie, in dit
geval aan de @code{+}. In Lisp zijn de argumenten van een functie de atomen
of lijsten die volgen op de functie. De waarde die de evaluatie van deze
atomen of lijsten teruggeeft worden doorgegeven aan de
functie. Verschillende functies vereisen een verschillend aantal argumenten,
sommige functies vereisen er geen.@footnote{Het is interessant om het pad te
volgen dat voor het woord ``argument'' tot twee verschillende betekenissen
leidde, eentje in wiskunde en eentje in dagelijks Engels. Volgens de
@cite{Oxford English Dictionary} is het woord afgeleid van het Latijn voor
@samp{duidelijk maken, bewijzen}. Via één tak van de afleiding kreeg het de
betekenis ``het bewijsmateriaal aangereikt als bewijs'', met andere woorden
``de aangeboden informatie'', wat tot de betekenis van het woord in Lisp
leidde. In de andere tak van de afleiding kreeg het de betekenis ``iets
beweren op een manier waarop anderen een tegenbewering maken'', wat leidde
tot de betekenis van het woord als dispuut. (Merk op dat het Engelse woord
hier tegelijk aan twee betekenissen zich gekoppeld heeft. In tegenstelling
kan in Emacs Lisp een symbool geen twee verschillende functiedefinities
tegelijk kan hebben.)}

@menu
* Data typen::               Typen van data doorgegeven naar een functie.
* Argumenten als variabele of als lijst::  Een argument kan de waarde van 
                                             een variabele of lijst zijn
* Variabel aantal argumenten::  Sommige functies accepteren een variable 
                                  aantal argumenten.
* Verkeerde type argument::  Een argument van het verkeerde type aan een 
                               functie doorgeven
* message::                  Een nuttige functie om boodschappen te zenden.
@end menu

@node Data typen
@subsection Data typen van argumenten
@cindex Data typen
@cindex Typen van data
@cindex Data typen van argumenten

Het type data dat aan een functie moet worden doorgegeven hangt af van het
soort informatie dat die gebruikt. De argumenten voor een functie zoals
@code{+} moeten waarden hebben die getallen zijn, omdat @code{+} getallen
optelt. Andere functies gebruiken andere vormen van data voor hun
argumenten.

@need 1250
@findex concat
De functie @code{concat} bijvoorbeeld koppelt of verbindt twee of meer
tekstreeksen om een string te produceren. De argumenten zijn strings. Het
concatenaten van de twee tekenreeksen @code{abc} en @code{def} produceert de
enkele string @code{abcdef}. Dit is te zien door het volgende te evalueren:

@smallexample
(concat "abc" "def")
@end smallexample

@noindent
De waarde die het evalueren van deze expressie produceert is
@code{"abcdef"}.

@cindex substring
Een functie zoals @code{substring} gebruikt zowel een string en getallen als
argumenten. De functie geeft een van de string terug, een @dfn{substring}
van zijn eerste argument. Deze functie accepteert drie argumenten. Het
eerste argument is de tekenreeks, het tweede en derde argument zijn de
getallen die het begin (inclusief) en het einde (exclusief) van de substring
aanduiden. De getallen zijn een telling van het aantal karakters (inclusief
spaties en leestekens) vanaf het begin van de string. Merk op dat de
karakters vanaf nul zijn genummerd, niet vanaf één.

@need 800
Bijvoorbeeld, als je het volgende evalueert:

@smallexample
(substring "The quick brown fox jumped." 16 19)
@end smallexample

@noindent
dan zie je @code{"fox"} in het echogebied verschijnen. De argumenten zijn de
string en twee getallen.

Merk op dat de aan @code{substring} doorgegeven string een enkelvoudig atoom
is, alhoewel het is opgebouwd uit meerdere woorden gescheiden door
spaties. Lisp rekent alles tussen de twee aanhalingstekens als onderdeel van
de string, inclusief de spaties. Je kunt de @code{substring} functie als een
soort van atoombreker zien, omdat het een anders ondeelbaar atoom neemt en
daar een onderdeel uit haalt. @code{substring} is echter alleen in staat een
substring uit een argument te halen dat een string is, niet van ander soort
atoom zoals een getal of een symbool.

@node Argumenten als variabele of als lijst
@subsection Een argument als de waarde van een variabele of lijst

Een argument kan een symbool zijn die een waarde teruggeeft wanneer het
wordt geëvalueerd. Wanneer bijvoorbeeld het symbool @code{fill-column} op
zichzelf wordt geëvalueerd, geeft het een getal terug. Dit getal kan in een
optelling worden gebruikt.

@need 1250
Plaats de cursor achter de volgende expressie en typ @kbd{C-x C-e}:

@smallexample
(+ 2 fill-column)
@end smallexample

@noindent
De waarde is een getal, twee groter dan wat je krijgt door het evalueren van
alleen @code{fill-column}. Voor mij is dit 74, omdat mijn waarde van
@code{fill-column} 72 is.

Zoals we zojuist zagen kan een argument een symbool zijn dat een waarde
teruggeeft wanneer het geëvalueerd wordt. Daarnaast kan een argument een
lijst zijn die een waarde teruggeeft wanneer die geëvalueerd
wordt. Bijvoorbeeld in de volgende expressie zijn de argumenten voor de
functie @code{concat} de strings @w{@code{"De "}} en @w{@code{" rode
vossen."}} en de lijst @code{(number-to-string (+ 2 fill-column))}.

@smallexample
(concat "De " (number-to-string (+ 2 fill-column)) " rode vossen.")
@end smallexample

@noindent
Wanneer je deze expressie evalueert---en als, zoals met mijn Emacs,
@code{fill-column} naar 72 evalueert---verschijnt @code{"De 74 rode
vossen."} in het echogebied. (Merk op dat je spaties achter het woord
@samp{De} en voor het voord @samp{rode} zet zodat deze in de uiteindelijke
string verschijnen. De functie @code{number-to-string} converteert de
integer die de optelling teruggeeft naar een string. @code{number-to-string}
is ook bekend als @code{int-to-string}.)

@node Variabel aantal argumenten
@subsection Variabel aantal argumenten
@cindex Variabel aantal argumenten
@cindex Argumenten, variabel aantal

Sommige functies, zoals  @code{concat}, @code{+} of @code{*} accepteren elk
aantal argumenten. (De @code{*} is het symbool voor vermenigvuldiging.) Dit
is te zien door het op de gebruikelijke manier evalueren van elk van de
volgende expressies. Wat je in het echogebied ziet verschijnen is deze tekst
achter @samp{@result{}} wat je kunt lezen als ``evalueert naar''. 

@need 1250
In de eerste groep hebben de functies geen argumenten:

@smallexample
@group
(+)       @result{} 0

(*)       @result{} 1
@end group
@end smallexample

@need 1250
In deze groep hebben de functies elk één argument:

@smallexample
@group
(+ 3)     @result{} 3

(* 3)     @result{} 3
@end group
@end smallexample

@need 1250
In deze groep hebben de functies elk drie argumenten:

@smallexample
@group
(+ 3 4 5) @result{} 12

(* 3 4 5) @result{} 60
@end group
@end smallexample

@node Verkeerde type argument
@subsection Het verkeerde object type als argument gebruiken
@cindex Verkeerde type argument
@cindex Argument, verkeerde type

Wanneer aan een functie een argument van een verkeerde type wordt
doorgegeven, produceert de Lisp interpreter een foutmelding. Bijvoorbeeld
verwacht de @code{+} functie dat de waarden van zijn argumenten getallen
zijn. Als experiment kunnen we het gequote symbool @code{hello} in plaats
van een getal doorgeven. Plaats de cursor achter de volgende expressie en
typ @kbd{C-x C-e}:

@smallexample
(+ 2 'hello)
@end smallexample

@noindent
Wanneer je dit doet dan genereer je een foutmelding. Wat gebeurde is dat
@code{+} geprobeerd het 2 op te tellen bij de waarde teruggegeven door
@code{'hello}, maar de waarde teruggegeven door @code{'hello} is het symbool
@code{hello}, geen getal. Alleen getallen kunnen worden opgeteld. Daardoor
kon @code{+} zijn optelling niet uitvoeren.

@need 1250
Je maakt en betreedt een @file{*Backtrace*} buffer die toont:

@noindent
@smallexample
@group
---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error:
         (wrong-type-argument number-or-marker-p hello)
  +(2 hello)
  eval((+ 2 'hello) nil)
  elisp--eval-last-sexp(t)
  eval-last-sexp(nil)
  funcall-interactively(eval-print-last-sexp nil)
  call-interactively(eval-print-last-sexp nil nil)
  command-execute(eval-print-last-sexp)
---------- Buffer: *Backtrace* ----------
@end group
@end smallexample

@need 1250
Zoals gebruikelijk probeert de foutmelding behulpzaam te zijn en klinkt
logisch nadat je geleerd hebt hoe die te lezen.@footnote{@code{(quote
hello)} is een expansie van de afkorting @code{'hello}.}

Het eerste deel van de foutmelding is eenvoudig, het toont @samp{wrong type
argument}. Daarna komt in mysterieus jargon het woord
@w{@samp{number-or-marker-p}}. Dit woord probeert je aan te geven welk type
argument de @code{+} verwachtte.

Het symbool @code{number-or-marker-p} geeft aan dat de Lisp interpreter
probeert vast te stellen of de informatie die het kreeg een getal is of een
marker (een speciaal object dat een bufferpositie vertegenwoordigt). Wat het
doet is testen of de @code{+} getallen kreeg om op te tellen. Ook test of
het argument iets is dat een marker genoemd wordt, wat een specifieke
eigenschap van Emacs Lisp is. (In Emacs worden locaties in een buffer
geregistreerd als markers. Wanneer de mark is gezet met het @kbd{C-@@} of
@kbd{C-@key{SPC}} commando, wordt zijn positie bewaard als een marker. De
mark kan worden beschouwd als een getal--het aantal karakters van de lokatie
ten opzichte van het begin van de buffer.) In Emacs Lisp kan @code{+}
gebruikt worden om de numerieke waarde van de marker-posities als getallen
op te tellen.

@cindex @samp{predicate} gedefinieerd
De @samp{p} in @code{number-or-marker-p} is de belichaming van een praktijk
die startte in de beginjaren van Lisp programmeren. De @samp{p} staat voor
@dfn{predicate}. In het jargon dat de eerste Lisp onderzoekers gebruikten,
refereert een predicate aan een functie die bepaalt of een bepaalde
eigenschap waar of onwaar is. De @samp{p} vertelt ons dus dat
@code{number-or-marker-p} de naam van een functie is die bepaalt of het waar
of onwaar is dat het doorgegeven argument een getal of een marker is. Andere
Lisp symbolen die eindigen in @samp{p} zijn onder andere @code{zerop}, een
functie die test of zijn argument de waarde nul heeft, en @code{listp}, een
functie die test of zijn argument een lijst is.

Het laatste deel van de foutmelding tenslotte is het symbool
@code{hello}. Dit is de waarde van het argument dat was doorgegeven aan
@code{+}. Wanneer het juiste type object aan de optelling was doorgegeven,
dan was de waarde die was doorgegeven een getal, zoals 37, in plaats van een
symbool zoals @code{hello}. Maar dan had je geen foutmelding gekregen.

@node message
@subsection De @code{message} functie
@findex message

Net als @code{+} accepteert de @code{message} functie een variabel aantal
argumenten. Het wordt gebruikt om berichten naar de gebruiker te sturen en
is zo nuttig dat we het hier beschrijven. 

@need 1250
Een bericht wordt getoond in het echogebied. Je kunt bijvoorbeeld een
bericht in je echogebied tonen door het evalueren van de volgende lijst:

@smallexample
(message "Dit bericht verschijnt in het echogebied!")
@end smallexample

De hele string tussen de dubbele aanhalingstekens in een enkelvoudig
argument en wordt volledig getoond. (Merk op dat in dit voorbeeld het
bericht zelf in het echogebied wordt getoond tussen dubbele
aanhalingstekens. Dat is omdat je de waarde ziet die de @code{message}
functie teruggeeft. In de meeste toepassingen van @code{message} in
programma's die je schrijft wordt de tekst getoond in het echogebied als
zij-effect, zonder aanhalingstekens.
@xref{vermenigvuldig-met-zeven in detail, , @code{vermenigvuldig-met-zeven}
in detail},
voor een voorbeeld hiervan).

Wanneer er echter een @samp{%s} in de string tussen aanhalingstekens staat,
toont de @code{message}-functie de @samp{%s} niet als zodanig, maar kijkt
naar het argument dat op de string volgt. Het evalueert het tweede argument
en toont de waarde op de locatie in de string waar de @samp{%s} staat.

@need 1250
De kun je zien door de cursor achter de volgende expressie te plaatsen en
@kbd{C-x C-e} te typen:

@smallexample
(message "De naam van dit buffer is: %s." (buffer-name))
@end smallexample

@noindent
In Info zal @code{"De naam van dit buffer is: *info*."} in het echogebied
verschijnen. De functie @code{buffer-name} geeft de naam van het buffer
terug als string, die de @code{message} functie invoegt op de plek van de
@code{%s}.

Om de waarde als een integer te tonen gebruik je @samp{%d} op dezelfde
manier als @samp{%s}. Bijvoorbeeld om een bericht in het echogebied te tonen
dat de waarde van @code{fill-column} opgeeft, evalueer je het volgende:

@smallexample
(message "De waarde van fill-column is %d." fill-column)
@end smallexample

@noindent
Wanneer ik op mijn systeem de lijst evalueer, verschijnt @code{"De waarde
van fill-column is 72."} in mijn echogebied @footnote{Je kunt trouwens
@code{%s} gebruiken om een getal te tonen. Het is niet-specifiek. @code{%d}
toont alleen het deel van het getal dat links van het decimale teken staan,
en niets dat geen getal is.}

Wanneer er meer dan een @samp{%s} in de string tussen aanhalingstekens
staat, wordt de waarde van het eerste argument dat volgt op de string tussen
aanhalingstekens op de plaats van de eerste @samp{%s} getoond, de waarde van
het tweede argument op de plaats van de tweede @samp{%s}, enzovoorts.

@need 1250
Wanneer je bijvoorbeeld het volgende evalueert,

@smallexample
@group
(message "Er zijn %d %s in het kantoor!"
         (- fill-column 14) "paarse olifanten")
@end group
@end smallexample

@noindent
zal een nogal eigenaardig bericht in je echogebied verschijnen. Op mijn
systeem zegt het @code{"Er zijn 58 paarse olifanten in het kantoor!"}.

De expressie @code{(- fill-column 14)} wordt geëvalueerd and het
resulterende getal wordt ingevoegd op de plaats van @samp{%d} en de string
in dubbele aanhalingstekens @code{"paarse olifanten"} wordt behandeld als
een enkelvoudig argument ingevoegd o de plaats van @samp{%s}. (Dat wil
zeggen dat een string tussen dubbele aanhalingstekens naar zichzelf
evalueert, net als een getal.

Tenslotte is hier een enigszins complex voorbeeld dat niet alleen de
berekening van een getal illustreert, maar ook hoe je een expressie binnen
een expressie gebruikt om een tekst te genereren die @samp{%s} vervangt:

@smallexample
@group
(message "He saw %d %s"
         (- fill-column 32)
         (concat "red "
                 (substring
                  "The quick brown foxes jumped." 16 21)
                 " leaping."))
@end group
@end smallexample

In dit voorbeeld heeft @code{message} drie argumenten: de string @code{"He
saw %d %s"}, de expressie @code{(- fill-column 32)} en de expressie
beginnend met de functie @code{concat}. De waarde resulterend van de
evaluatie van @code{(- fill-column 32)} wordt ingevoegd op de plaats van de
@samp{%d} en de waarde teruggeven door de expressie beginnend met
@code{concat} wordt ingevoegd op de plaats van de @samp{%s}.

Wanneer jouw fill column 70 is en je de expressie evalueert, verschijnt
@code{"He saw 38 red foxes leaping."} in je echogebied.

@node setq
@section De waarde van een variabele zetten
@cindex Variabele, waarde zetten
@cindex De waarde van een variabele zetten

@cindex @samp{bind} gedefinieerd
Er zijn verschillende manieren waarop een variabele een waarde kan
krijgen. Een van de manieren is het gebruik van de speciale vorm
@code{setq}. Een andere manier is het gebruik van @code{let}
(@pxref{let}). (Het jargon voor dit proces is @dfn{bind} een variabele aan
een waarde.)

De volgende paragrafen beschrijven niet alleen hoe @code{setq} werkt maar
illustreren tevens hoe argumenten worden doorgegeven.

@menu
* Setq gebruiken::           Variabelen zetten
* Tellen::                   @code{setq} gebruiken om te tellen.
@end menu

@node Setq gebruiken
@subsection Gebruik van @code{setq}
@findex set

Om de waarde van het symbool @code{bloemen} op de lijst @code{roos viool
madelief boterbloem} te zetten evalueer je de volgende expressie door de
cursor achter de expressie te zetten en @kbd{C-x C-e} te typen:

@smallexample
(setq bloemen '(roos viool madelief boterbloem))
@end smallexample

@noindent
De lijst @code{(roos viool madelief boterbloem)} verschijnt in het
echogebied. Dat is wat is @emph{teruggegeven} door de speciale vorm
@code{setq}. Als zij-effect is het symbool @code{bloemen} aan de lijst
gebonden. Dat wil zeggen dat het symbool @code{bloemen}, welke als een
variabel gezien kan worden, de lijst als waarde krijgt. (Overigens
illustreert dit proces hoe een zij-effect voor de Lisp interpreter, de
waarde zetten, het primaire effect kan zijn waar wij mensen in
geïnteresseerd zijn.. Dit is omdat elke Lisp functie een waarde moet
teruggeven wanneer het geen fout krijgt, maar alleen een zij-effect heeft
wanneer die is ontworpen om er een te hebben.

Nadat je de @code{setq} expressie hebt geëvalueerd, kun je het symbool
@code{bloemen} evalueren, dit geeft je de waarde terug die je zojuist gezet
hebt. Hier is het symbool. Plaats je cursor er achter en typ @kbd{C-x C-e}.

@smallexample
bloemen
@end smallexample

@noindent
Wanneer je @code{bloemen} evalueert, verschijnt de lijst @code{(roos viool
madelief boterbloem)} in het echogebied.

Overigens, wanneer je @code{'bloemen} evalueert, de variabele met een enkele
quote er voor, dat zie je in het echogebied het symbool zelf,
@code{bloemen}. Hier is het gequote symbool, zodat je het kunt proberen:

@smallexample
'bloemen
@end smallexample

Als extra gemak staat @code{setq} je toe verschillende variablen naar
verschillende waarden te zetten, in een enkele expressie.

Om de waarde van de variabele @code{carnivoren} met @code{setq} naar de
lijst @code{'(leeuw tijger luipaard)} te zetten is de volgende expressie
gebruikt:

@smallexample
(setq carnivoren '(leeuw tijger luipaard)
@end smallexample

@code{setq} kan ook gebruikt worden om verschillende waarden naar
verschillende variabelen toe te kennen. Het eerste argument wordt gebonden
aan de waarde van het tweede argument, het derde argument aan de waarde van
het vierde argument, enzovoorts. Bijvoorbeeld kan je het volgende gebruiken
om een lijst van bomen aan het symbool @code{bomen} en een lijst van
herbivoren aan het symbool @code{herbivoren} toe te kennen:

@smallexample
@group
(setq bomen '(den spar eik esdoorn)
      herbivoren '(gazelle antiloop zebra)
@end group
@end smallexample

@noindent
(De expressie had net zo goed op een enkele regel gekund, maar het zou
misschien niet op een bladzijde passen, en mensen vinden het makkelijker om
mooi opemaakte lijsten te lezen).

Alhoewel ik de term ``toekennen'' heb gebruikt, is er een andere manier over
de werking van @code{setq} te denken, en dat zo te zeggen dat @code{setq}
het symbool laat @emph{wijzen} naar de lijst. Deze laatste manier van denken
is erg gebruikelijk en in de volgende hoofdstukken zullen we een symbool
tegenkomen dat ``pointer'' als onderdeel van zijn naam heeft. De naam is
gekozen omdat het symbool een waarde, in het bijzonder een lijst aan zich
gebonden heeft, of, op een andere manier uitgedrukt, het symbool is
ingesteld om naar de lijst te wijzen.

@node Tellen
@subsection Tellen
@cindex Tellen

Hier volgt een voorbeeld dat laat zien hoe je @code{setq} in een teller
gebruikt. Je kunt dit gebruiken om te tellen hoe vaak een deel van je
programma zichzelf herhaalt. Stel eerst een variabele op nul. Vervolgens tel
je iedere keer dat het programma zich herhaalt een bij het getal op. Om dit
te doen heb je een variabele nodig die dienst doet als teller, en twee
expressies: een initiële @code{setq} expressie die de variabele instelt op
nul, en een tweede @code{setq} expressie die elke keer dat die wordt
geëvalueerd de teller verhoogt.

@smallexample
@group
(setq counter 0)                ; @r{Laten wij dit de initialisator noemen.}

(setq counter (+ counter 1))    ; @r{Dit is de incrementer.}

counter                         ; @r{Dit is de teller.}
@end group
@end smallexample

@noindent
(De tekst die volgt na de @samp{;} zijn comments.  @xref{Een defun wijzigen,
, Wijzig een functiedefinitie}.)

Wanneer je de eerste van deze drie expressies evalueert, de initialisator,
@code{(setq counter 0)}, en daarna evalueer je de derde expressie,
@code{counter}. dan verschijnt het getal @code{0} in het echogebied. Wanneer
je de tweede expressie, de incrementer, @code{(setq counter (+ counter 1))},
evalueert, dan verschijnt het getal @code{1} in het echogebied. Elke keer
dat je de tweede expressie evalueert, wordt de waarde van de counter
verhoogd.

Wanneer je de incrementer, @code{(setq counter (+ counter 1))} evalueert,
evalueert de Lisp interpreter eerst de meest binnenste lijst, dit is de
optelling. Om deze lijst te evalueren, moet het de variabele @code{counter}
en het getal @code{1} evalueren. Wanneer het de variabele @code{counter}
evalueert, krijgt het diens huidige waarde. Het geeft deze waarde en het
getal @code{1} door aan de @code{+}, die ze bij elkaar optelt. De som wordt
teruggegeven als de waarde van de binnenste lijst en doorgegeven aan de
@code{setq}, die de variabele @code{counter} op deze nieuwe waarde
instelt. Zo is de waarde van de variabele @code{counter} gewijzigd.

@node Samenvatting
@section Samenvatting

Lisp leren is net zo iets als een heuvel beklimmen, waar het eerste deel het
steilste is. Je hebt inmiddels het moeilijkste deel beklommen, wat
overblijft wordt makkelijker naarmate je verder komt.

@need 1000
Samenvattend,

@itemize @bullet

@item
Lisp programma's zijn gemaakt van expressies, elke lijsten of enkelvoudige
atomen zijn.

@item
Lijsten zijn gemaakt van nul of meer atomen of binnenliggende lijsten,
gescheiden door witte ruimte en omgeven door haakjes. Een lijst kan leeg
zijn.

@item
Atomen zijn multi-karakter symbolen, zoals @code{forward-paragraph},
enkele-karakter symboleen zoals @code{+}, strings of karakters tussen
dubbele aanhalingstekens, of getallen.

@item
Een getal evalueert naar zichzelf.

@item
Een string tussen dubbele aanhalingstekens evalueert ook naar zichzelf.

@item
Wanneer je een symbool op zichzelf evalueert, wordt zijn waarde
teruggegeven.

@item
Wanneer je een lijst evalueert, kijkt de Lisp interpreter naar het eerste
symbool in de lijst en vervolgens naar de functiedefinitie die aan dat
symbool gebonden is. Daarvan worden de instructies in de functiedefinitie
uitgevoerd. 

@item
Een enkele quote @samp{'} vertelt de Lisp interpreter dat het de
daaropvolgende expressie moet teruggeven zoals die is geschreven, en niet
evalueren alsof de quote er niet was. 

@item
Argumenten vormen de informatie die aan een functie wordt doorgegeven. De
argumenten voor een functie worden berekend door de rest van de elementen
van de lijst te evalueren, waarvan de functie het eerste element is.

@item
Een functie geeft altijd een waarde terug wanneer die wordt geëvalueerd
(tenzij het een fout krijgt). Ook kan die een actie uitvoeren dat een
zij-effect is. In veel gevallen is het creëren van zij-effecten het primaire
doel.
@end itemize

@node Foutmelding oefeningen
@section Oefeningen

Enkele simpele oefeningen:

@itemize @bullet
@item
Genereer een foutmelding door een geschikt symbool te evalueren dat niet
tussen haakjes staat.

@item
Genereer een foutmelding door een geschikt symbool te evalueren dat tussen
haakjes staat.

@item
Maak een teller die met twee verhoogt in plaats van een.

@item
Schrijf een expressie die een boodschap in het echogebied toont wanneer die
wordt geëvalueerd.
@end itemize

@node Oefenen van evaluatie
@chapter Oefenen van evaluatie
@cindex Evaluatie oefenen
@cindex Evaluatiepraktijk

Voordat je leert hoe je een functiedefinitie in Emacs Lisp schrijft, is het
zinnig om wat tijd te besteden aan het evalueren van diverse expressies die
al zijn geschreven. Deze expressies zijn lijsten met de functies als hun
eerste (en vaak enige) element. Omdat sommige buffer-geassocieerde functies
zowel eenvoudig als interessant zijn, beginnen we met die. In deze sectie
evalueren we enkele daarvan. In een andere sectie bestuderen we de code van
verscheidene andere buffer-gerelateerde functies om te zien hoe die zijn
geschreven. 

@menu
* Hoe te evalueren::         Het typen van commando's of @kbd{C-x C-e} 
                               veroorzaakt evalatie.
* Buffer namen::             Buffers en bestanden zijn verschillend.
* Buffers pakken::           Pak een buffer zelf, niet slechts zijn naam.
* Van buffer verwisselen::   Hoe je naar een andere buffer overschakelt
* Buffer grootte en locatie::  De locatie van point en de grootte van het 
                                 buffer.
* Evaluatie oefening::       Evaluatie oefening
@end menu

@ifnottex
@node Hoe te evalueren
@unnumberedsec Hoe te evalueren
@end ifnottex

@i{Telkens wanneer je een edit-commando} aan Emacs Lisp geeft, zoals het
commando om de cursor te verplaatsen of het scherm te scrollen, @i{evalueer
je een expressie}, waarvan het eerste element een functie is. @i{Dit is hoe
Emacs werkt.}

@cindex @samp{interactive function} gedefinieerd
@cindex @samp{command} gedefinieerd
Wanneer je toetsen aanslaat laat je de Lisp interpreter een expressie
evalueren en zo krijg je je resultaten. Zelfs het typen van platte tekst
houdt het evalueren van een Emacs Lisp functie in, in dit geval eentje dat
het @code{self-insert-command} gebruikt, die eenvoudig het karakter dat je
typte invoegt. De functies die je evalueert met het typen van toetsaanslagen
worden @dfn{interactief} genoemd, of @dfn{commando's}. Hoe je een functie
interactief maakt wordt in het volgende hoofdstuk
geïllustreerd. @xref{Interactief, , Een functie interactief maken}.

Naast het typen van toetsenbord commando's, hebben we een tweede manier
gezien om een expressie te evalueren: door de cursor achter de lijst te
plaatsen en @kbd{C-x C-e} te typen. Dit is wat we in rest van deze sectie
zullen doen. Er zijn nog meer manieren om een expressie te evalueren, deze
zullen we beschrijven wanneer die aan de orde komen.

Naast dat we ze voor evaluatie-oefeningen gebruiken, zijn de functies die in
volgende secties behandeld worden op zichzelf belangrijk. Het bestuderen van
deze functies verheldert het verschil tussen buffers en bestanden, hoe
tussen buffer te schakelen, en hoe een locatie er binnen vast te stellen.

@node Buffer namen
@section Buffer namen
@findex buffer-name
@findex buffer-file-name

De twee functies @code{buffer-name} en @code{buffer-file-name} tonen het
verschil tussen een buffer en een bestand. Wanneer je volgende expressie
evalueert, @code{(buffer-name)}, verschijnt de naam van het buffer in het
echogebied. Wanneer je @code{(buffer-file-name)} evalueert, verschijnt de
naam van het bestand waar het buffer naar refereert in het
echogebied. Meestal is de naam die @code{(buffer-name)} teruggeeft hetzelfde
als de naam van het bestand waarnaar het refereert, en is de naam die
@code{(buffer-file-name)} teruggeeft de volledige padnaam van het bestand.

Een bestand en een buffer zijn twee verschillende entiteiten. Een bestand is
informatie permanent opgeslagen op de computer (tenzij je het
verwijdert). Een buffer daarentegen is informatie binnen Emacs, die
verdwijnt aan het einde van de editing sessie (of wanneer je het buffer
killt). Meestal bevat een buffer informatie die je van een bestand
gekopieerd hebt, we zeggen dat het buffer het bestand @dfn{bezoekt}. Deze
kopie is waar je op werkt en wijzigt. Veranderingen in het buffer wijzigen
het bestand niet, totdat je het buffer opslaat. Wanneer je het buffer
opslaat, wordt het buffer gekopieerd naar het bestand en zo permanent
opgeslagen.

@need 1250
Wanneer je dit in Info leest binnen Emacs, kan je elk van de volgende
expressies evalueren door de cursor er achter te zetten en @kbd{C-x C-e} te
typen. 

@example
@group
(buffer-name)

(buffer-file-name)
@end group
@end example

@noindent
Wanneer ik dit in Info doe, geeft evaluatie van @code{(buffer-name)} de
waarde @file{"*info*"} terug, en is de waarde die de evaluatie van
@code{(buffer-file-name)} teruggeeft @file{nil}.

Anderzijds, terwijl ik dit document schrijf is de waarde die het evalueren
van @code{(buffer-name)} teruggeeft, @file{"introduction.texinfo"} en de
waarde die de evaluatie van @code{(buffer-file-name)} teruggeeft
@file{"/gnu/work/intro/introduction.texinfo"}.

@cindex @code{nil}, geschiedenis van woord
De eerste is de naam van het buffer en het tweede is de naam van het
bestand. In Info is de naam van het buffer @file{"*info*"}. Info wijst niet
naar een bestand, waardoor @file{nil} het resultaat van de evaluatie
@code{(buffer-file-name)} is. Het symbool @file{nil} is van het Latijnse
woord voor ``niets'', in dit geval betekent het dat het buffer met geen
enkel bestand geassocieerd is. (In Lisp betekent @code{nil} ook ``onwaar''
en is synoniem voor de lege lijst, @code{()}.)

Wanneer ik schrijf is de naam van mijn buffer
@file{"introduction.texinfo"}. De naam van het bestand waar het naar wijst
is @file{"/gnu/work/intro/introduction.texinfo"}.

(In de expressies vertellen de haakjes aan de Lisp interpreter om
@w{@code{buffer-name}} en @w{@code{buffer-file-name}} als functies te
behandelen. Zonder de haakjes zou de interpreter proberen de symbolen als
variabelen te behandelen. @xref{Variabelen}.)

Ondanks het onderscheid tussen bestanden en buffers zie je vaak dat mensen
aan een bestand refereren wanneer ze een buffer bedoelen en
andersom. Inderdaad zeggen de meeste mensen ``ik edit een bestand'' in
plaats van ``ik edit een buffer dat ik binnenkort naar een bestand ga
saven''. Het is vrijwel altijd duidelijk van de context wat mensen
bedoelen. Wanneer we met computerprogramma's werken is het belangrijk het
onderscheid in gedachten te houden, want computers zijn niet zo slim als
mensen.

@cindex Buffer, geschiedenis van woord
Overigens komt het woord ``buffer'' van de betekenis van het woord als een
``kussen dat de kracht van een botsing opvangt''. In de eerste computers
verzachtte een buffer de interactie tussen bestanden en de centrale
verwerkingseenheid. De drums of tapes die het bestand bevatten en de
centrale verwerkingseenheid waren onderdelen van de apparatuur die zeer
verschillend van elkaar waren en op hun eigen snelheid werkten, in
stoten. Uiteindelijk groeide het buffer van een intermediair, een tijdelijke
opslagplaats uit naar de plaats waar het werk wordt gedaan. Deze
transformatie is ongeveer zoals een kleine zeehaven uitgroeide naar een
grote stad. Eens was het slechts de plaats waar lading tijdelijk in
magazijnen werd opgeslagen voordat het op schepen werd verladen en daarna
een zakelijk en cultureel centrum op zichzelf werd.

Niet alle buffers zijn geassocieerd met bestanden. Bijvoorbeeld een
@file{*scratch*}-buffer bezoekt geen enkel bestand. Op dezelfde manier is
het @file{*Help*}-buffer met geen enkel bestand geassocieerd.

Wanneer je vroeger geen @file{~/.emacs} bestand had en een Emacs sessie
startte door het typen van alleen het commando @code{emacs}, zonder enig
bestand te noemen, startte Emacs met het @file{*scratch*} buffer
zichtbaar. Tegenwoordig zie je een startscherm. Je kunt een van de
commando's volgen die op het startscherm gesuggereerd worden, een bestand
bezoeken of op @kbd{q} drukken om het startscherm te sluiten en het
@file{*scratch*}-buffer te bereiken.

Schakel over naar het @file{*scratch*}-buffer en typ @code{(buffer-name)},
plaats de cursor direct er achter, en typ vervolgens @kbd{C-x C-e} om de
expressie te evalueren. De naam @code{"*scratch*"} wordt teruggegeven en
verschijnt in het echogebied. @code{"*scratch*"} is de naam van het
buffer. Wanneer je @code{(buffer-file-name)} in het @file{*scratch*} buffer
typt en dat evalueert, verschijnt @code{nil} in het echogebied, net zoals
dat gebeurt wanneer je @code{(buffer-file-name)} in Info evalueert.

Overigens, als je in het @file{*scratch*} buffer bent en door een expressie
teruggeven waarde in het @file{*scratch*} wilt laten verschijnen in plaats
van het echogebied, typ je @kbd{C-u C-x C-e} in plaats van @kbd{C-x
C-e}. Dit zorgt dat de teruggegeven waarde achter de expressie
verschijnt. Het buffer ziet er zo uit:

@smallexample
(buffer-name)"*scratch*"
@end smallexample

@noindent
Je kunt dit niet in Info doen, omdat Info read-only is en je niet toestaat
de inhoud van het buffer te wijzigen. Maar je kunt dit in elk buffer doen
dat je kunt editen. Wanneer je code schrijft of documentatie (zoals dit
boek), is deze eigenschap erg nuttig.

@node Buffers pakken
@section Buffers pakken
@findex current-buffer
@findex other-buffer
@cindex Een buffer krijgen

De @code{buffer-name}-functie geeft de @emph{naam} van het buffer. Om het
buffer @emph{zelf} te krijgen is een andere functie benodigd, de  functie
@code{current-buffer}. Wanneer je deze functie in code gebruikt krijg je het
buffer zelf.

Een naam en het object of entiteit waar de naam aan refereert zijn van
elkaar verschillend. Jij bent niet je naam. Je bent een persoon die anderen
bij naam noemen. Wanneer je vraagt om met George te spreken en iemand geeft
je een kaart met de letters @samp{G}, @samp{e}, @samp{o}, @samp{r}, @samp{g}
en @samp{e}, dan kan dat je amuseren, maar je zal er niet tevreden mee
zijn. Je wilt niet met de naam spreken, maar met de persoon die met die naam
genoemd is. Een buffer is vergelijkbaar: de naam van het scratch-buffer is
@file{*scratch*}, maar de naam is niet het buffer. Om het buffer zelf te
krijgen, heb je een functie nodig zoals @code{current-buffer}. 

Er is echter een kleine complicatie: wanneer je @code{current-buffer} zelf
evalueert in een expressie, zoals we hier gaan doen, dan wordt de de
representatie van de naam van het buffer getoond zonder de inhoud van het
buffer. Emacs werkt op deze manier wegens twee redenen: het buffer kan
duizenden regels lang zijn---te lang om handig weer te geven, en een ander
buffer kan dezelfde inhoud maar een andere naam hebben en het is belangrijk
om onderscheid tussen hen te maken.

@need 800
Hier is een expressie die de functie bevat:

@smallexample
(current-buffer)
@end smallexample

@noindent
Wanneer je deze expressie in Info in Emacs op de gebruikelijke manier
evalueert, verschijnt @file{#<buffer *info*>} in het echogebied. Het
speciale formaat geeft aan dat het buffer zelf is teruggegeven in plaats van
slechts de naam.

Overigens, hoewel je een getal of symbool in een programma kunt typen, kan
je dit niet doen met de getoonde representatie van een buffer: de enige
manier om een buffer zelf te krijgen is met een functie zoals
@code{current-buffer}.

Een gerelateerde functie is @code{other-buffer}. Deze geeft de meest recent
geselecteerde buffer terug, anders dan degene waar je nu in bent, en niet de
getoonde representatie van de naam. Wanneer je recentelijk heen en weer
tussen het @file{*scratch*} buffer geschakeld hebt, dan zal
@code{other-buffer} dat buffer teruggeven.

@need 800
Dit zie je door de volgende expressie te evalueren:

@smallexample
(other-buffer)
@end smallexample

@noindent
Je zou @file{#<buffer *scratch*>} moeten zien verschijnen in het echogebied,
of de naam van welk ander buffer je het meest recent van teruggeschakeld
hebt. @footnote{Eigenlijk wanneer het buffer waar je laatst vandaan
schakelde voor je zichtbaar is in een ander venster. zal standaard
@code{other-buffer} het meest recente buffer kiezen dat je niet kunt
zien. Dit is een subtiliteit die ik meestal vergeet.}

@node Van buffer verwisselen
@section Van buffer verwisselen
@findex switch-to-buffer
@findex set-buffer
@cindex Switching to a buffer

De @code{other-buffer}-functie biedt eigenlijk een buffer wanneer het
gebruikt wordt als een argument voor een functie die er een vereist. We zien
dit door @code{other-buffer} en @code{switch-to-buffer} te gebruiken om naar
een ander buffer te schakelen.

Maar eerst een korte introductie van de @code{switch-to-buffer}
functie. Toen je heen en weer schakelde tussen Info en het
@file{*scratch*}-buffer om @code{(buffer-name)} te evalueren, heb je
hoogstwaarschijnlijk @kbd{C-x b} en daarna @file{*scratch*}
getypt@footnote{Of beter gezegd, om toetsaanslagen te besparen, heb je
waarschijnlijk alleen @kbd{RET} getypt indien het default buffer
@file{*scratch*} was, of wanneer het niet zo was, je slechts een gedeelte
van de naam typte, zoals @code{*sc}, en de @kbd{TAB}-toets gebruikte zodat
het expandeerde naar de volledige naam, en daarna @kbd{RET} typte.} toen je
in het minibuffer gevraagd werd naar de naam van het buffer waar naar toe te
schakelen. De toetsaanslagen @kbd{C-x b} laten de Lisp interpreter de
interactieve @code{switch-to-buffer}-functie evalueren. Zoals we eerder
gezegd hebben, dit is hoe Emacs werkt: verschillende toetsaanslagen roepen
verschillende functies aan of draaien die. Bijvoorbeeld @kbd{C-f} roept
@code{forward-char} aan, @kbd{M-e} roept @code{forward-sentence} aan,
enzovoorts.

Door @code{switch-to-buffer} in een expressie te schrijven en het een
buffernaam te geven om naar te schakelen, kunnen we buffers schakelen op
dezelfde manier zoals @kbd{C-x b} doet:

@smallexample
(switch-to-buffer (other-buffer))
@end smallexample

@noindent
@c noindent
Het symbool @code{switch-to-buffer} is het eerste element in de lijst, dus
zal de Lisp interpreter het als een functie behandelen en de instructies
uitvoeren die daaraan gekoppeld zijn. Maar voordat die dat doet, merkt de
interpreter op dat @code{other-buffer} tussen haakjes staat en eerst dat
symbool verwerkt. @code{other-buffer} is het eerste (en in dit geval enige)
element in deze lijst, dus de Lisp interpreter roept of runt deze
functie. Het geeft een ander buffer terug. Vervolgens runt de interpreter
@code{switch-to-buffer} en geeft het andere buffer als argument door, waar
Emacs naar zal omschakelen. Wanneer je dit in Info leest, probeer het dan nu
direct. Evalueer de expressie. (Typ @kbd{C-x b @key{RET}} om terug te gaan.)
@footnote{Onthoudt, deze expressie zal je naar het meest recent
geselecteerde buffer brengen, die je niet kunt zien. Wanneer je werkelijk
naar je meest recent geselecteerde buffer wilt gaan, zelfs wanneer je die
kunt zien, evalueer dan de volgende expressie:
@smallexample
(switch-to-buffer (other-buffer (current-buffer) t))
@end smallexample
In dit geval vertelt het eerste argument van  @code{other-buffer} welk
buffer het moet overslaan---het huidige---en het tweede argument vertelt
@code{other-buffer} dat het OK is om naar een zichtbaar buffer te
schakelen. Bij normaal gebruik neemt @code{switch-to-buffer} je naar een
buffer dat niet in vensters zichtbaar is omdat je hoogst waarschijnlijk
@kbd{C-x o} (@code{other-window}) gebruikt om naar een ander zichtbaar
buffer te gaan.}

In de programmeervoorbeelden in volgende secties van dit document zie je de
functie @code{set-buffer} vaker dan @code{switch-to-buffer}. Dit is wegens
een verschil tussen computerprogramma's en mensen: mensen hebben ogen en
verwachten het buffer te zien waarop ze werken op hun computerterminals. Dit
is zo voor de hand liggend, het spreekt bijna voor zich. Echter, programma's
hebben geen ogen. Wanneer een computerprogramma op een buffer werkt, dan
hoeft dat buffer niet op het scherm zichtbaar te zijn.

@code{switch-to-buffer} is ontworpen voor mensen en doet twee verschillende
dingen: het schakelt het buffer waar de aandacht van Emacs op is gevestigd
en het schakelt het buffer dat getoond wordt in het venster naar een nieuw
buffer. @code{set-buffer} anderzijds doet meer een enkel ding: het schakelt
de aandacht van het computerprogramma naar een ander buffer. Het buffer op
het scherm blijft onveranderd (uiteraard gebeurt er niets totdat het
commando klaar is met lopen).

@cindex @samp{aanroepen} gedefinieerd
Ook hebben we net een ander jargon term geïntroduceerd, het woord
@dfn{aanroepen}. Wanneer je een lijst evalueert waar het eerste symbool een
functie is, dan roep je die functie aan. Het gebruik van deze term komt
voort uit het begrip van de functie als entiteit dan iets voor je kan doen
wanneer je het aanroept---net als een loodgieter een entiteit is die een lek
kan repareren wanneer je hem of haar roept.

@node Buffer grootte en locatie
@section Buffergrootte en de locatie van point
@cindex Buffergrootte
@cindex Buffergrootte
@cindex Locatie van point
@cindex Locatie van point

Laten wij tenslotte naar enkele nogal eenvoudige functies kijken,
@code{buffer-size}, @code{point}, @code{point-min} en @code{point-max}. Deze
geven informatie over de grootte van een buffer en de locatie van point
daarin.

De functie @code{buffer-size} vertelt je hoe groot het huidige buffer
is. Dit houdt in dat de functie de som van het aantal karakters in het
buffer teruggeeft.

@smallexample
(buffer-size)
@end smallexample

@noindent
Je kunt dit op de gebruikelijke manier evalueren door de cursor achter de
expressie te plaatsen en @kbd{C-x C-e} te typen.

@cindex @samp{point} gedefinieerd
In Emacs wordt de huidige positie van de cursor @dfn{point} genoemd. De
expressie @code{(point)} geeft een getal terug dat je vertelt waar de cursor
is gepositioneerd als een telling van het aantal karakters vanaf het begin
van het buffer tot point.

@need 1250
Je kunt de karaktertelling voor point in dit buffer zien door het op de
gebruikelijke manier evalueren van de volgende expressie:

@smallexample
(point)
@end smallexample

@noindent
Terwijl ik dit schrijf is de waarde van point 65724. De @code{point} functie
wordt vaak gebruikt in sommige voorbeelden later in dit boek.

@need 1250
De waarde van point hangt natuurlijk af van zijn locatie in het
buffer. Wanneer je point op deze plek evalueert, is het getal groter:

@smallexample
(point)
@end smallexample

@noindent
Voor mij is de waarde van point op deze plek 66043, wat betekent dat er 319
karakters (inclusief spaties) tussen de twee expressies zijn. (Ongetwijfeld
zie je verschillende getallen, omdat ik dit heb geschreven heb na de eerste
evaluatie van point.)

@cindex @samp{narrowing} defined
De functie @code{point-min} lijkt enigszins op @code{point}, maar het geeft
de waarde van de minimum toegestane waarde van point in het huidige
buffer. Dit is het getal 1 tenzij @dfn{versmallen} van toepassing
is. (Versmallen is het mechanisme waarmee je jezelf of een programma beperkt
tot operaties op slechts een deel van een buffer. @xref{Versmallen en
verbreden, , Versmallen en verbreden}.) Evenzo geeft de functie
@code{point-max} de maximum toegestane waarde van point in het huidige
buffer.

@node Evaluatie oefening
@section Oefening

Vindt een bestand waarmee je werkt en ga naar het midden. Vindt zijn
buffernaam, bestandsnaam, lengte en je positie in het bestand.

@node Defuns schrijven
@chapter Hoe functiedefinities te schrijven
@cindex Definitie schrijven
@cindex Functiedefinitie schrijven
@cindex Schrijven van een functiedefinitie

Wanneer de Lisp interpreter een lijst evalueert, kijkt het of het eerste
symbool in de lijst een functiedefinitie aan zich gekoppeld heeft, met
andere woorden, of het symbool naar een functiedefinitie wijst. Een symbool
met een functiedefinitie wordt eenvoudig een functie genoemd (alhoewel,
eigenlijk is de definitie de functie en verwijst het symbool er naar).

@menu
* Primitieve functies::      Primitieve functies
* defun::                    De @code{defun} macro.
* Installeer::               Installeer een functiedefinitie
* Interactief::              Een functie interactief maken.
* Interactieve opties::      Verschillende opties voor @code{interactive}.
* Permanent installeren::    Installeer code permanent
* let::                      Locale variabelen maken en initialiseren
* if::                       Wat als?
* else::                     If--then--else expressies.
* Waar en onwaarheid::       Wat Lisp als waar en onwaar beschouwt.
* save-excursion::           Point en buffer volgen
* Terugblik::                Terugblik
* defun oefeningen::         defun oefeningen
@end menu

@ifnottex
@node Primitieve functies
@unnumberedsec Een terzijde over primitieve functies
@end ifnottex
@cindex Primitieve functies
@cindex Functies, primitief

@cindex C-taal primitieven
@cindex Primitieven geschreven in C
Alle functies zijn beschreven in termen van andere functies, behalve enkele
@dfn{primitieve} functies die in de C programmeertaal geschreven
zijn. Wanneer je functiedefinities schrijft, schrijf je ze in Emacs Lisp en
je gebruikt andere functies als bouwstenen. Sommige functies die je gebruikt
zijn zelf geschreven in Emacs Lisp (misschien door jezelf) en sommige zijn
primitieven geschreven in C@. De primitieve functies worden precies zo
gebruikt als de in Emacs Lisp geschreven functies en gedragen zich net
zo. Zij zijn in C geschreven zodat we GNU Emacs makkelijk op elke computer
kunnen draaien die voldoende krachtig is en C kan draaien.

Laat me dit nogmaals benadrukken: wanneer je code in Emacs Lisp schrijft,
maak je geen onderscheid tussen het gebruik van functies geschreven in C en
functies geschreven in Emacs Lisp. Het verschil is irrelevant. Ik noem het
onderscheid alleen omdat is interessant is het te weten. Inderdaad, tenzij
je het onderzoekt, zou je niet weten of een reeds geschreven functie is
geschreven in Emacs Lisp of C.

@node defun
@section De @code{defun} macro
@findex defun

@cindex @samp{functiedefinitie} gedefinieerd
In Lisp heeft een symbool zoals @code{mark-whole-buffer} code aan zich
gekoppeld die de computer vertelt wat te doen wanneer die functie wordt
aangeroepen. Deze code heet de @dfn{functiedefinitie} en is gecreëerd door
het evalueren van een Lisp expressie die start met het symbool @code{defun}
(wat een afkorting is van @emph{definieer functie}).

In volgende secties kijken we naar functiedefinities van de Emacs broncode,
zoals @code{mark-whole-buffer}. In deze sectie beschrijven we een eenvoudige
functiedefinitie zodat je kunt zien hoe die eruitzien. Dat voorbeeld
gebruikt rekenkunde omdat het tot een eenvoudig voorbeeld leidt. Sommige
mensen houden niet van voorbeelden met rekenkunde, echter wanneer je zo'n
persoon bent, wanhoop niet. Nauwelijks enige code die we in de rest van deze
introductie behandelen heeft met rekenkunde of wiskunde te maken. De
voorbeelden hebben hoofdzakelijk op de een of andere manier met tekst te
maken.

Een functiedefinitie bestaat uit maximaal vijf onderdelen volgend op het
woord @code{defun}: 

@enumerate
@item
De naam van het symbool waaraan de functiedefinitie gekoppeld moet worden.

@item
Een lijst met de argumenten die aan de functie zullen worden
doorgegeven. Wanneer geen argumenten aan de functie zullen worden
doorgegeven is dit een lege lijst, @code{()}.

@item
Documentatie die de functie beschrijft. (Technisch optioneel, maar sterk
aanbevolen.)

@item
Optioneel een expressie die de functie interactief maakt zodat je die kunt
gebruiken door @kbd{M-x} gevolgd door de naam van de functie te typen, of
door het typen van een passende toets of toetscombinatie.

@cindex @samp{body} gedefinieerd
@item
De code die de computer instrueert wat de doen de @dfn{body} van de
functiedefinitie.
@end enumerate

Het is nuttig om de vijf delen van een functiedefinitie te beschouwen als
een sjabloon met vijf slots voor elk onderdeel: 

@smallexample
@group
(defun @var{functienaam} (@var{argumenten}@dots{})
  "@var{optionele-documentatie}@dots{}"
  (interactive @var{argument-doorgevende-info})     ; @r{optioneel}
  @var{body}@dots{})
@end group
@end smallexample

Als een voorbeeld is hier de code voor een functie die zijn argument met 7
vermenigvuldigt. (Het voorbeeld is niet interactief. @xref{Interactief, ,
Een functie interactief maken}, voor die informatie.)

@smallexample
@group
(defun vermenigvuldig-met-zeven (getal)
  "Vermenigvuldig GETAL met zeven."
  (* 7 getal))
@end group
@end smallexample

Deze definitie begint met een haakje en het symbool @code{defun}, gevolgd
door de naam van de functie.

@cindex @samp{argumentlijst} gedefinieerd
De naam van de functie wordt gevolgd door een lijst die de argumenten bevat
die aan de functie zullen worden doorgegeven. Deze lijst heet de
@dfn{argumentlijst}. In dit voorbeeld heeft de lijst maar één element, het
symbool @code{getal}. Wanneer de functie wordt gebruikt wordt het symbool
gebonden aan de waarde die als argument van de functie is gebruikt.

In plaats van te kiezen voor het woord @code{getal} als naam van het
argument had ik elke andere naam kunnen pakken. Bijvoorbeeld had ik kunnen
kiezen voor het woord @code{multiplicant}. Ik pakte het woord ``getal''
omdat het vertelt wat voor soort waarde bedoeld is voor het slot, maar ik
net zo goed het woord ``multiplicant'' kunnen kiezen om de rol aan te geven
die de in dit slot geplaatste waarde speelt in de werking van de functie. Ik
had het ook @code{foogle} kunnen noemen, maar dat zou een slechte keuze zijn
omdat het niet aan mensen vertelt wat het betekent. De keuze van de naam is
aan de programmeur en moet zo gekozen worden dat het de betekenis van de
functie duidelijk maakt.

Je kunt inderdaad elke naam die je maar wilt kiezen voor een symbool in de
argumentlijst, zelfs de naam van een symbool die in een andere functie
gebruikt wordt: de naam die je gebruikt in de argumentlijst is privé voor
die specifieke definitie. In die definitie refereert de naam naar een andere
entiteit dan elk gebruik van de zelfde naam buiten de functiedefinitie. Stel
je hebt de bijnaam ``Kleintje'' in je familie, dan refereren familieleden
met ``Kleintje'' naar jou. Maar buiten jouw familie, bijvoorbeeld in een
speelfilm, refereert  de naam ``Kleintje'' naar iemand anders. Omdat de naam
in de argumentlijst privé is voor de functiedefinitie kan je de waarde van
zo'n symbool binnen de body van de functie wijzigen zonder de waarde buiten
de functie te wijzigen. Het effect is vergelijkbaar met dat geproduceerd
door de @code{let}-expressie. (@xref{let, , @code{let}}.)

@ignore
Note also that we discuss the word ``number'' in two different ways: as a
symbol that appears in the code, and as the name of something that will
be replaced by a something else during the evaluation of the function.
In the first case, @code{number} is a symbol, not a number; it happens
that within the function, it is a variable who value is the number in
question, but our primary interest in it is as a symbol.  On the other
hand, when we are talking about the function, our interest is that we
will substitute a number for the word @var{number}.  To keep this
distinction clear, we use different typography for the two
circumstances.  When we talk about this function, or about how it works,
we refer to this number by writing @var{number}.  In the function
itself, we refer to it by writing @code{number}.
@end ignore

De argumentlijst wordt gevolgd door de documentatiestring die de functie
beschrijft. Dat is wat je ziet als je @w{@kbd{C-h f}} en de naam van de
functie typt. Overigens, wanneer je een documentatiestring als deze schrijft
moet je van de eerste regel een complete zin maken, omdat sommige
commando's, zoals @code{apropos}, alleen de eerste regel tonen van een
meerregelige documentatiestring. Ook moet je de tweede regel van een
documentatiestring, wanneer die er is, niet laten inspringen, omdat dit er
raar uitziet wanner je @kbd{C-h f} (@code{describe-function}) gebruikt. De
documentatiestring is optioneel, maar is zo nuttig, dat die deel van vrijwel
elke functie die je schrijft zou moeten zijn.

@findex * @r{(vermenigvuldiging)}
De derde regel van ons voorbeeld bestaat uit de body van de
functiedefinitie. (De meeste functiedefinities zijn natuurlijk langer dan
deze.) In dit voorbeeld is de body de lijst @code{(* 7 getal)}, die zegt
vermenigvuldig de waarde van @var{getal} met 7. (In Emacs Lisp, is @code{*}
de functie voor vermenigvuldiging, net zoals @code{+} de functie voor
optellen is.)

Wanneer je de functie @code{vermenigvuldig-met-zeven} gebruikt evalueert
@code{getal} naar het daadwerkelijk getal dat je wilt gebruiken. Hier is een
voorbeeld dat toont hoe je @code{vermenigvuldig-met-zeven} gebruikt, maar
probeer het nu nog niet te evalueren!

@smallexample
(vermenigvuldig-met-zeven 3)
@end smallexample

@noindent
Het symbool @code{getal}, gespecificeerd in de functiedefinitie in de
volgende sectie, is gebonden aan de waarde 3 in het daadwerkelijk gebruik
van de functie. Merk op dat hoewel @code{getal} tussen haakjes in de
functiedefinitie stond, het argument dat aan de functie
@code{vermenigvuldig-met-zeven} wordt doorgegeven niet tussen haakjes
staat. De haakjes worden in de functiedefinitie geschreven zodat de computer
uit kan zoeken waar de argumentlijst eindigt en de rest van de functie
begint.

Wanneer je dit voorbeeld evalueert, krijgt je waarschijnlijk een
foutmelding. (Ga je gang, probeer het!) Dit is omdat we de functiedefinitie
hebben geschreven maar de computer nog niet op de hoogte gebracht hebben van
de definitie---wij hebben de functiedefinitie nog niet in Emacs geladen. Het
installeren van een functie is het proces dat de Lisp interpreter op de
hoogte brengt van de functie. Het installeren wordt in de volgende sectie
beschreven.

@node Installeer
@section Installeer een functiedefinitie
@cindex Installeer een functiedefinitie
@cindex Definitie installatie
@cindex functiedefinitie installatie

Wanneer je dit binnen Info in Emacs leest, kan je de functie
@code{vermenigvuldig-met-zeven} proberen door eerst de functiedefinitie te
evalueren en daarna @code{(vermenigvuldig-met-zeven 3)} te evalueren. Een
exemplaar van de functiedefinitie volgt. Plaats de cursor achter het laatste
haakje van de functiedefinitie en typ @kbd{C-x C-e}. Wanneer je dit doet,
verschijnt @code{vermenigvuldig-met-zeven} in het echogebied. (Wat dit
betekent is dat wanneer een functiedefinitie wordt geëvalueerd, de waarde
die het teruggeeft de naam van de gedefinieerde functie is.) Tegelijkertijd
installeert deze actie de functiedefinitie.

@smallexample
@group
(defun vermenigvuldig-met-zeven (getal)
  "Vermenigvuldig GETAL met zeven."
  (* 7 getal))
@end group
@end smallexample

@noindent
Met het evalueren van deze @code{defun} heb je zojuist
@code{vermenigvuldig-met-zeven} in Emacs geïnstalleerd. De functie is nu net
zo goed onderdeel van Emacs als
@code{forward-word}.(@code{vermenigvuldig-met-zeven} blijft geïnstalleerd
totdat je Emacs afsluit. Om de code automatisch opnieuw te laden wanneer je
Emacs start, zie @ref{Permanent installeren, , Installeer code permanent}.)

@menu
* Effect van installatie::   Effect van installatie
* Een defun wijzigen::       Hoe een functiedefinitie te wijzigen.
@end menu

@ifnottex
@node Effect van installatie
@unnumberedsubsec Het effect van de installatie
@end ifnottex

Je kunt het effect van het installeren van @code{vermenigvuldig-met-zeven}
zien dor het volgende voorbeeld te evalueren. Plaats de cursor achter de
volgende expressie en typ @kbd{C-x C-e}. Het getal 21 verschijnt in het
echogebied.

@smallexample
(vermenigvuldig-met-zeven 3)
@end smallexample

Als je dat wilt kun je de documentatie van de functie lezen door het typen
van @kbd{C-h f} (@code{describe-function}) en dan de naam van de functie
@code{vermenigvuldig-met-zeven}. Wanneer je dat doet dan verschijnt een
@file{*Help*}-venster op het scherm, dat zegt:

@smallexample
@group
vermenigvuldig-met-zeven is an interpreted-function.

(vermenigvuldig-met-zeven GETAL)
Vermenigvuldig-met-zeven GETAL met zeven.
@end group
@end smallexample

@noindent
(Om terug te gaan naan een enkel venster op je scherm, typ @kbd{C-x 1}.)

@node Een defun wijzigen
@subsection Wijzig een functiedefinitie
@cindex Een functiedefinitie wijzigen
@cindex Functiedefinitie, hoe te wijzigen
@cindex Definitie, hoe te wijzigen

Wanneer je de code in @code{vermenigvuldig-met-zeven} wilt wijzigen,
herschrijf je die. Om een nieuwe versie in plaats van de oude te installeren
evalueer je de functiedefinitie opnieuw. Dit is hoe je code in Emacs
aanpast. Dat is erg eenvoudig.

Als een voorbeeld kan je de @code{vermenigvuldig-met-zeven}-functie wijzigen
zodat die het getal zeven keer met zichzelf optelt, in plaats van het
vermenigvuldigen van het getal met zeven. Het produceert hetzelfde antwoord,
maar via een andere route. Tegelijkertijd voegen we commentaar toe aan de
code. Commentaar is tekst die de Lisp interpreter negeert, maar die de
menselijke lezer nuttig of verhelderend kan vinden. Het commentaar is dat
dit de tweede versie is.

@smallexample
@group
(defun vermenigvuldig-met-zeven (getal)       ; @r{Tweede versie.}
  "Multiply GETAL by seven."
  (+ getal getal getal getal getal getal getal))
@end group
@end smallexample

@cindex Commentaar in Lisp code
Het commentaar volgt op een puntkomma, @samp{;}. In Lisp is alles op een
regel dat volgt achter een puntkomma commentaar. Het einde van de regel is
het einde van het commentaar. Om het commentaar over twee of meer regels te
spreiden, begin je elke regel met een puntkomma.

@xref{Een init bestand beginnen, , Starten met een @file{.emacs} bestand},
en @ref{Comments, , Comments, elisp, The GNU Emacs Lisp Reference Manual},
voor meer over commentaar.

Je kunt deze versie van @code{vermenigvuldig-met-zeven} installeren door het
op dezelfde manier te evalueren als je de eerste functie geëvalueerd hebt:
plaats de cursor achter het laatste haakje en typ @kbd{C-x C-e}.

Samengevat, dit is hoe je code in Emacs Lisp schrijft: je schrijft een
functie, installeert die, test die en dan maak je verbeteringen of
uitbreidingen en installeert die opnieuw.

@node Interactief
@section Een functie interactief maken
@cindex Interactieve functies
@findex interactive

Je maakt een functie interactief door een lijst die begint met de speciale
vorm @code{interactive} direct achter de documentatie. Een gebruiker kan een
interactieve functie starten door het typen van @kbd{M-x} en daarna de naam
van de functie, of door het typen van de toetscombinatie waaraan die is
gebonden, bijvoorbeeld door het typen van @kbd{C-n} voor @code{next-line} of
@kbd{C-x h} voor @code{mark-whole-buffer}.

Het is interessant dat wanneer je een interactieve functie interactief
aanroept, de teruggegeven waarde niet automatisch in het echogebied wordt
getoond. Dit is omdat je vaak een interactieve functie aanroept wegens de
zij-effecten, zoals een woord of regel verder gaan, en niet voor de
teruggegeven waarde. Wanneer de teruggegeven waarde elke keer dat je een
toets aanslaat in het echogebied getoond zou worden, zou dat erg afleiden.

@menu
* Interactieve vermenigvuldig-met-zeven::  Een overzicht
* vermenigvuldig-met-zeven in detail::  De interactieve versie
@end menu

@ifnottex
@node Interactieve vermenigvuldig-met-zeven
@unnumberedsubsec Een interactieve @code{vermenigvuldig-met-zeven}, een overzicht
@end ifnottex

Zowel het gebruik van de speciale vorm @code{interactive} en een manier om
de waarde in het echogebied te tonen kan door het maken van een interactieve
versie van @code{vermenigvuldig-met-zeven} worden geïllustreerd.

@need 1250
Hier is de code:

@smallexample
@group
(defun vermenigvuldig-met-zeven (getal)       ; @r{Interactieve versie.}
  "Vermenigvuldig GETAL met zeven."
  (interactive "p")
  (message "Het resultaat is %d" (* 7 getal)))
@end group
@end smallexample

@noindent
Je installeert deze code door de cursor er achter te plaatsen en @kbd{C-x
C-e} te typen. De naam van de functie verschijnt in je
echogebied. Vervolgens kan je deze code gebruiken door het typen van
@kbd{C-u} en een getal, en daarna @kbd{M-x vermenigvuldig-met-zeven} te
typen en op @key{RET} te drukken. De zin @samp{Het resultaat is @dots{}}
gevolgd door het product verschijnt in het echogebied.

Meer algemeen gesproken roep je een functie zoals deze aan op een van de
twee manieren: 

@enumerate
@item
Door het typen van een prefix-argument dat het door te geven getal bevat en
daarna @kbd{M-x} en de naam van de functie te typen, zoals met @kbd{C-u 3
M-x forward-sentence}; of,

@item
Door welke toets of toetscombinatie dan ook de functie aan gebonden is,
zoals met @kbd{C-u 3 M-e}.
@end enumerate

@noindent
Beide zojuist genoemde voorbeelden werken identiek om point drie zinnen
verder te plaatsen. (Omdat @code{vermenigvuldig-met-zeven} niet aan een
toets gebonden is, kan dit niet gebruikt worden als voorbeeld van een key
binding.) 

(@xref{Key bindings, , Sommige key bindings}, om te leren hoe je een
commando aan een key bindt.) 

Een @dfn{prefix-argument} wordt aan een interactieve functie gegeven door
het aanslaan van de @key{META} toets gevolg door een cijfer, bijvoorbeeld
@kbd{M-3 M-e}, of door het aanslaan van @kbd{C-u} en daarna een getal,
bijvoorbeeld @kbd{C-u 3 M-e} (wanneer je @kbd{C-u} zonder getal aanslaat, is
de standaard waarde 4).

@node vermenigvuldig-met-zeven in detail
@subsection Een interactieve @code{vermenigvuldig-met-zeven}

Laten we naar het gebruik van de speciale vorm @code{intertive} kijken en
daarna naar de functie @code{message} in de interactieve versie van
@code{vermenigvuldig-met-zeven}. Je herinnert dat de functiedefinitie er zo
uitziet:

@smallexample
@group
(defun vermenigvuldig-met-zeven (getal)       ; @r{Interactieve versie.}
  "Vermenigvuldig GETAL met zeven."
  (interactive "p")
  (message "Het resultaat is %d" (* 7 getal)))
@end group
@end smallexample

In deze functie is de expressie  @code{(interactive "p")} een lijst met twee
elementen. De  @code{"p"} vertelt Emacs om het prefix-argument door te geven
aan de functie en zijn waarde te gebruiken voor het argument van de functie.

@need 1000
Het argument is een getal. Dit betekent dat het symbool @code{getal} wordt
gebonden aan een getal in de regel:

@smallexample
(message "Het resultaat is %d" (* 7 getal))
@end smallexample

@need 1250
@noindent
Bijvoorbeeld wanneer je prefix-argument 5 is, zal de Lisp interpreter de
regel evalueren alsof het was:

@smallexample
(message "Het resultaat is %d" (* 7 5))
@end smallexample

@noindent
(Wanneer je dit in GNU Emacs leest, kan je zelf deze expressie evalueren.)
Eerst zal de interpreter de binnenste lijst evalueren, dus @code{(* 7
5)}. Dit geeft een waarde van 35 terug. Daarna zal het de buitenste lijst
evalueren, en daarbij de waardes van tweede en volgende elementen van de
lijst doorgeven aan de functie @code{message}.

Zoals we hebben gezien is @code{message} een Emacs Lisp functie specifiek
ontworpen om een eenregelige boodschap naar de gebruiker te
sturen. (@xref{message, , De @code{message} functie}.) Samengevat, de
@code{message} functie toont zijn argumenten in het gebied zoals ze zijn,
met uitzondering van gevallen zoals @samp{%d} of @samp{%s} (en diverse
andere %-reeksen die we nog niet genoemd hebben). Wanneer het een
control-reeks ziet, kijkt de functie naar het tweede en volgende argumenten
en toont de waarde van de argumenten in de string op de plek waar de
control-reeks staat.

In de interactieve @code{vermenigvuldig-met-zeven}-functie is de
control-reeks @samp{%d}, die een getal vereist, en de waarde die de
evaluatie van @code{(* 7 5)} teruggeeft is het getal 35. Daarom wordt het
getal 35 getoond op de plaats van @samp{%d} en is de boodschap @samp{Het
resultaat is 35}.

(Merk op dat wanneer je de functie @code{vermenigvuldig-met-zeven} aanroept,
de boodschap zonder aanhalingstekens getoond wordt. Dit komt omdat de waarde
die door @code{message} wordt teruggeven in het echogebied verschijnt
wanneer je een expressie evalueert wiens eerste element @code{message} is,
maar wanneer het in een functie is ingebed, toont @code{message} de tekst
als een zij-effect zonder de aanhalingstekens.)

@node Interactieve opties
@section Verschillende opties voor @code{interactive}
@cindex Opties voor @code{interactive}
@cindex Interactieve opties

In het voorbeeld gebruikte @code{vermenigvuldig-met-zeven} @code{"p"} als
argument voor @code{interactive}. Dit argument vertelde Emacs om door wat je
typte, hetzij @kbd{C-u} gevolgd door een getal of @key{META} gevold door een
cijfer, te interpreteren als een commando om dat getal door te geven aan de
functie als zijn argument. Emacs heeft meer dan twintig karakters
voorgedefinieerd om met @code{interactive} te gebruiken. In vrijwel alle
gevallen maakt een van deze opties het je mogelijk de juiste informatie
interactief aan een functie door te geven. (@xref{Interactive Codes, , Code
Characters for @code{interactive}, elisp, The GNU Emacs Lisp Reference
Manual}.)

@need 1250
Beschouw de functie @code{zap-to-char}. De interactieve expressie daarvan is

@c FIXME: the interactive expression of zap-to-char has been changed
@c (in 2012-04-10).

@smallexample
(interactive "p\ncZap to char: ")
@end smallexample

Het eerste deel van het argument van @code{interactive} is @samp{p}, waarmee
je al vertrouwd bent. Dit argument vertelt Emacs een prefix als getal te
interpreteren om aan de functie door te geven. Je geeft het prefix op hetzij
door @kbd{C-u} gevolgd door een getal te typen, of door het typen van
@key{META} gevolgd door een cijfer. Het prefix is het aantal van het
opgegeven karakter. Dus als je prefix drie is en het opgegeven karakter
@samp{x}, dan verwijder je alle tekst tot en met de derde volgende
@samp{x}. Wanneer je geen prefix gebruikt dan verwijder je alle tekst tot en
met het gespecificeerde karakter, maar niet meer.

De @samp{c} vertelt de functie de naam van het karakter tot waar te
verwijderen.

Meer formeel, een functie met twee of meer argumenten kan voor elk argument
informatie doorgegeven krijgen door delen toe te voegen aan de string die
volgt op @code{interactive}. Wanneer je dit doet is de informatie die
doorgegeven wordt in dezelfde volgorde als gespecificeerd is de
@code{interactive} lijst. In de string is elk deel gescheiden van het
volgende deel door een @samp{\n}, wat een nieuwe regel is. Bijvoorbeeld, je
kunt @samp{p} opvolgen met een @samp{\n} en een @samp{cZap to char:@: }. Dit
laat Emacs de waarde doorgeven van het prefix-argument (als er een is) en
het karakter.

In dit geval ziet de functiedefinitie er als volgt uit, waarbij @code{arg}
en @code{char} de symbolen zijn waaraan @code{interactive} het
prefix-argument en het gespecificeerde karakter bindt:

@smallexample
@group
(defun @var{name-of-function} (arg char)
  "@var{documentation}@dots{}"
  (interactive "p\ncZap to char: ")
  @var{body-of-function}@dots{})
@end group
@end smallexample

@noindent
(De spatie achter de dubbele punt in de prompt maakt dat het er beter
uitziet wanneer je wordt geprompt. @xref{copy-to-buffer, , De definitie van
@code{copy-to-buffer}}, bijvoorbeeld.)

Wanneer een functie geen argumenten heeft, hoeft @code{interactive} er geen
te hebben. Zo'n functie bevat de eenvoudige expressie
@code{(interactive)}. De functie @code{mark-whole-buffer} is er zo een.

Daarnaast kun je, wanneer de speciale letter-codes niet geschikt zijn voor
jouw applicatie, je eigen argumenten als lijst doorgeven aan
@code{interactive}.

@xref{append-to-buffer, , De definitie van @code{append-to-buffer}}, voor
een voorbeeld. @xref{Using Interactive, , Using @code{Interactive}, elisp,
The GNU Emacs Lisp Reference Manual}, voor een meer complete uitleg over
deze techniek.

@node Permanent installeren
@section Code permanent installeren
@cindex Code permanent installeren
@cindex Permanente code installatie
@cindex Code installtie

Wanneer je een functiedefinitie installeert door het te evalueren, blijft
het geïnstalleerd totdat je Emacs sluit. De volgende keer dat je een nieuwe
sessie van Emacs start, is de functie niet geïnstalleerd tenzij je de
functiedefinitie opnieuw evalueert.

Op een gegeven moment wil je de code automatisch geïnstalleerd hebben
wanneer je een nieuwe Emacs sessie start. Er zijn verschillende manieren om
dit te doen:

@itemize @bullet
@item
Wanneer je code hebt die uitsluitend voor jezelf is, kan je de code voor de
functiedefinitie opnemen in je @file{.emacs} initialisatiebestand.

@item
Een andere manier is de functiedefinities die je geïnstalleerd wilt hebben
zelf in een of meer bestanden opnemen en de functie @code{load} gebruiken om
Emacs ze te laten evalueren en daarmee elk van de functies in de bestanden
installeren. @xref{Bestanden laden, , Bestanden laden}.

@item
Ten derde, wanneer je code hebt die je systeem-breed wilt gebruiken, is het
gebruikelijk die in een bestand op te nemen met de naam @file{site-init.el},
die wordt geladen wanneer Emacs wordt gebouwd. Dit maakt de code beschikbaar
voor iedereen die jouw machine gebruikt. (Zie het bestand @file{INSTALL} dat
onderdeel is van je Emacs distributie.)
@end itemize

Tenslotte, wanneer je code hebt die iedereen die Emacs gebruikt zou willen
hebben, dan kun je het op een computernetwerk posten of een exemplaar naar
de Free Software Foundation sturen. (Wanneer je dit doet, breng dan
alsjeblieft de code en de bijbehorende documentatie onder een licentie die
andere mensen toestaat het te draaien, kopiëren, bestuderen, aan te passen
en verder te distribueren en die je beschermt tegen dat je werk van je
afgenomen wordt.) Wanneer je een exemplaar van jouw code naar de Free
Software Foundation stuurt, en jezelf en anderen juist beschermt, dan zou
het in een volgende release van Emacs kunnen worden opgenomen. Dit is
grotendeels hoe Emacs over de jaren gegroeid is, door donaties.

@xref{Contributing, Contributing to Emacs Development,, emacs, The GNU Emacs
Manual}, over hoe bij te dragen met opname van je code in Emacs.

@node let
@section @code{let}
@findex let

De @code{let} expressie is een speciale vorm in Lisp die je in de meeste
functiedefinities nodig hebt.

@code{let} wordt gebruikt om een symbool aan een variabele te koppelen of te
binden op zo'n manier dat de Lisp interpreter het niet verwart met een
variabele met dezelfde naam die geen onderdeel van de functie is.

Om te begrijpen waarom de speciale vorm @code{let} nodig is, beschouw de
situatie waarin je in het algemeen aan jouw huis refereert als ``het huis'',
zoals in de zin ``Het huis moet geverfd worden''. Wanneer je een vriend
bezoekt en de gastheer refereert aan ``het huis'', refereert hij
waarschijnlijk aan @emph{zijn} huis, niet het jouwe, dus aan een ander huis.

Wanneer je vriend naar zijn huis refereert en jij denkt dat hij naar jouw
huis refereert, dan kan dat verwarrend zijn. Hetzelfde kan in Lisp gebeuren
wanneer een variabele die binnen de ene functie gebruikt wordt dezelfde naam
heeft als een variabele die binnen een andere functie gebruikt wordt, en de
twee zijn niet bedoeld om naar dezelfde waarde te refereren. De speciale
vorm @code{let} voorkomt dit soort verwarring.

@menu
* Voorkom verwarring::       Voorkom verwarring
* Delen van een let expressie::  Delen van een let expressie
* Voorbeeld let expressie::  Voorbeeld let expressie
* Niet-geïnitialiseerde let variabelen::  Niet-geïnitialiseerde let 
                                            variabelen
* Hoe let variabelen bindt::  Hoe let variabelen bindt
@end menu

@ifnottex
@node Voorkom verwarring
@unnumberedsubsec @code{let} voorkomt verwarring
@end ifnottex

@c FIXME!! lexbind!!

@cindex @samp{lokale variabele} gedefinieerd
@cindex @samp{variabele, lokaal}, gedefinieerd
De speciale vorm @code{let} voorkomt verwarring. @code{let} creëert een naam
voor een @dfn{lokale variabele} die elk gebruik van dezelfde naam buiten de
@code{let}-expressie overschaduwt (in computerwetenschappelijk jargon noemen
we dit het @dfn{binden} van de variabele). Dit is vergelijkbaar met
begrijpen dat in het huis van je gastheer, wanneer hij refereert aan ``het
huis'', hij zijn huis bedoelt en niet het jouwe. (De symbolen die gebruikt
worden om functieargumenten te benoemen worden op precies dezelfde manier
als lokale variabelen gebonden. @xref{defun, , De @code{defun} macro}.)

Een andere manier om over @code{let} te denken is dat het een speciaal
gebied in je code definieert: binnen de body van de @code{let}-expressie,
hebben de variabelen die je benoemd hebt hun eigen lokale betekenis. Buiten
de @code{let} body hebben zij een andere betekenis (of ze zijn helemaal niet
gedefinieerd). Dit betekent dat binnen de @code{let} body het aanroepen van
@code{setq} voor een variabele benoemd door de @code{let}-expressie de
waarde instelt voor de @emph{lokale} variabele met die naam. Echter buiten
de @code{let} body (zoals bij het aanroepen van een functie die ergens
anders is gedefinieerd), @code{setq} aanroepen voor een variabele benoemd
door de @code{let}-expressie heeft @emph{geen} effect voor die lokale
variabele.@footnote{Dit beschrijft het gedrag van @code{let} bij het gebruik
van een stijl met de naam ``lexical binding'' (@pxref{Hoe let variabelen
bindt}).} 

@code{let} kan meer dan een variabele tegelijk creëren. Dus @code{let} geeft
iedere variabele die het creëert een initiële waarde, of een door jou
gespecificeerde waarde, of @code{nil}. (In het jargon is dit het binden van
de variabele aan de waarde.) Nadat @code{let} de variabelen heeft gecreëerd
en gebonden voert het de code in de body van de @code{let} uit, als de
waarde van de gehele @code{let}-expressie. (``Uitvoeren'' is een jargon term
die het evalueren van de lijst betekent, het komt van het gebruik van het
woord met de betekenis ``een praktisch effect hebben op'' (@cite{Oxford
English Dictionary}) Wanneer je een expressie evalueert om een actie uit te
voeren, is ``uitvoeren'' geëvolueerd tot synoniem voor ``evalueren''.)

@node Delen van een let expressie
@subsection De delen van een @code{let} expressie
@cindex @code{let} expressie, delen van
@cindex Delen van een let expressie

@cindex @samp{varlist} gedefinieerd
De lijst van een @code{let}-expressie bestaat uit drie delen. Het eerste
deel is het symbool @code{let}. Het tweede deel is een lijst, genaamd
@dfn{varlist}, van wie elk element hetzij een symbool op zichzelf is, of een
lijst met twee elementen, waarvan het eerste element een symbool is. Het
derde deel van de @code{let}-expressie is de body van de @code{let}. De body
bestaat gebruikelijk uit een of meer lijsten.

@need 800
Het sjabloon voor een @code{let}-expressie ziet er zo uit:

@smallexample
(let @var{varlist} @var{body}@dots{})
@end smallexample

@noindent
De symbolen in de varlist zijn de variabelen die een initiële waarde krijgen
door de speciale vorm @code{let}. De symbolen zelf krijgen een initiële
waarde van @code{nil} en elk symbool dat het eerste is van een lijst met
twee elementen is gebonden aan de waarde dat de Lisp interpreter teruggeeft
bij het evalueren van het tweede element.

Een varlist kan er dus als volgt uitzien: @code{(draad (naalden 3))}. In dit
geval, in een @code{let}-expressie, bindt Emacs het symbool @code{draad} aan
een initiële waarde van @code{nil}, en bindt het symbool @code{naalden} aan
een initiële waarde van 3.

Wanneer je een @code{let}-expressie schrijft, dan plaats je de passende
expressies in de slots van het sjabloon voor @code{let}-expressies.

Wanneer de varlist is samengesteld uit lijsten met twee elementen, wat vaak
het geval is, dan ziet het sjabloon voor de @code{let}-expressie er zo uit:

@smallexample
@group
(let ((@var{variable} @var{value})
      (@var{variable} @var{value})
      @dots{})
  @var{body}@dots{})
@end group
@end smallexample

@node Voorbeeld let expressie
@subsection Voorbeeld @code{let} expressie
@cindex Voorbeeld @code{let} expressie
@cindex @code{let} expressie voorbeeld

De volgende expressie creëert en geeft initiele waarden aan de twee
variabelen @code{zebra} en @code{tijger}. De body van de
@code{let}-expressie is een lijst die de @code{message}-functie aanroept.

@smallexample
@group
(let ((zebra "strepen")
      (tijger "woest"))
  (message "Eén soort dieren heeft %s en de ander is %s."
           zebra tijger))
@end group
@end smallexample

Hier is de varlist @code{((zebra "strepen") (tijger "woest"))} 

De twee variabelen zijn @code{zebra} en @code{tijger}. Elke variabele is het
eerste element van een lijst met twee elementen en elke waarde is het tweede
element van die lijst. In de varlist bindt Emacs de variabele @code{zebra}
aan de waarde @code{"strepen"}@footnote{volgens Jared Diamond in @cite{Guns,
Germs, and Steel}, ``@dots{} worden zebras onvoorstelbaar gevaarlijk als ze
ouder worden'' maar de claim hier is dat ze niet zo woest worden als een
tijger. (1997, W. W. Norton and Co., ISBN 0-393-03894-2, page 171)}, en bind
de variabele @code{tijger} aan de waarde @code{"woest"}. In dit voorbeeld
zijn beide waarden strings. De waarde had net zo goed een andere lijst of
een symbool kunnen zijn. De body van de @code{let} is een lijst die de
@code{message}-functie gebruikt om een string in het echogebied te tonen.

@need 1500
Je kunt het voorbeeld op de gebruikelijke manier evalueren door de cursor
achter het laatste haakje te zetten en @kbd{C-x C-e} te typen. Wanneer je
dit doet, verschijnt het volgende in het echogebied:

@smallexample
"Eén soort dieren heeft strepen en de ander is woest."
@end smallexample

Zoals we eerder gezien hebben toont de @code{message}-functie zijn argument,
met uitzondering van @samp{%s}. In dit voorbeeld wordt de waarde van de
variabele @code{zebra} getoond op de plek van de eerste @samp{%s} en wordt
de waarde van de variabele @code{tijger} op de plek van de tweede @samp{%s}
getoond.

@node Niet-geïnitialiseerde let variabelen
@subsection Ongeïnitialiseerde variabelen in een @code{let} statement
@cindex Ongeïnitialiseerde @code{let}  variabelen
@cindex @code{let} variabelen ongeïnitialiseerd

Wanneer je variabelen niet aan een specifieke initiële waarde bindt in een
@code{let} statement, dan worden die automatisch gebonden aan de initiële
waarde @code{nil}, zoals in de volgende expressie:

@smallexample
@group
(let ((berk 3)
      spar
      den
      (eik 'enige))
  (message
   "Hier zijn %d variabelen met %s, %s, en %s waarde."
   berk spar den eik))
@end group
@end smallexample

@noindent
Hier is de varlist @code{((berk 3) spar den (eik 'enige))}

@need 1250
Wanneer je deze expressie op de gebruikelijke manier evalueert, verschijnt
het volgende in je echogebied:

@smallexample
"Hier zijn 3 variabelen met nil, nil, en enige waarde."
@end smallexample

@noindent
In dit voorbeeld bindt Emacs het symbool @code{berk} aan het getal 3, bindt
het symbool @code{spar} en @code{den} aan @code{nil}, en bindt het symbool
@code{eik} aan de waarde @code{enige}.

Merk op dat in het eerste deel van de @code{let}-expressie de variabelen
@code{spar} en @code{den} op zichzelf staan als atomen en niet omgeven zijn
met haakjes. Dit is omdat ze aan @code{nil} gebonden worden, de lege
lijst. Maar @code{eik} is gebonden aan @code{enige} en daarom is een deel
van de lijst @code{(eik 'enige)}. @code{berk} is op dezelfde manier gebonden
aan het getal 3 en staat daarom in een lijst met dat getal. (Omdat een getal
naar zichzelf evalueert hoeft een getal niet gequote te worden. Ook wordt
het getal in de boodschap getoond met @samp{%d} in plaats van @samp{%s}.) De
vier variabelen zijn als groep in de lijst geplaatst om ze te scheiden van
de body van de @code{let}. 

@node Hoe let variabelen bindt
@subsection Hoe @code{let} variabelen bindt

Emacs Lisp ondersteunt twee manieren om een variabele namen aan hun waarde
te binden. Deze manieren raken de delen van je programma waar een bepaalde
binding geldig is. Wegens historische redenen gebruikt Emacs Lisp standaard
een vorm van variabele binding met de naam @dfn{dynamic binding}. Echter in
deze handleiding behandelen we de voorkeursvorm voor binding, met de naam
@dfn{lexical binding}, tenzij anders vermeld (de Emacs-beheerders zijn van
plan in de toekomst de standaard te wijzigen naar lexical binding). Wanneer
je eerder in andere talen geprogrammeerd hebt, ben je waarschijnlijk
vertrouwd met hoe lexical binding zich gedraagt.

Om lexical binding in een programma te gebruiken zet je dit in de eerste
regel van je Emacs Lisp bestand:

@example
;;; -*- lexical-binding: t -*-
@end example

Voor meer informatie hierover @pxref{Variable Scoping, , , elisp, The Emacs
Lisp Reference Manual}.

@menu
* Lexical en dynamische binding verschillen::  Lexical en dynamische binding 
                                                 verschillen
* Lexical vs dynamische binding voorbeeld::  Lexical vs dynamische binding 
                                               voorbeeld
@end menu

@node Lexical en dynamische binding verschillen
@unnumberedsubsubsec Verschillen tussen lexical en dynamische binding

@cindex Lexical binding
@cindex Binding, lexical
Zoals eerder besproken
@iftex
(@pxref{Permanent installeren}),
@end iftex
@ifnottex
(@pxref{Voorkom verwarring}),
@end ifnottex
wanneer je lokale variabelen met @code{let} onder lexical binding creëert,
zijn die variabelen alleen geldig in de body van de @code{let}-expressie. In
andere delen van je code hebben ze geen betekenis, dus wanneer je een elders
gedefinieerde functie aanroept vanuit de @code{let} body, kan die functie de
lokale variabelen die je gemaakt hebt niet ``zien''. (Anderzijds, wanneer je
een functie aanroept die was gedefinieerd in een @code{let} body. @emph{zou}
die functie de lokale variabelen van die @code{let}-expressie moeten kunnen
zien en wijzigen.

@cindex Dynamische binding
@cindex Binding, dynamisch
Onder dynamische binding zijn de regels verschillend: wanneer je @code{let}
gebruikt. zijn de lokale variabelen geldig gedurende de uitvoering van de
@code{let}-expressie. Dit betekent dat wanneer je @code{let}-expressie een
functie aanroept, die functie deze lokale variabelen kan zien, ongeacht waar
de functie is gedefinieerd (inclusief wanneer dit zelfs in een heel ander
bestand staat).

Een andere manier om over @code{let} bij het gebruik van dynamische binding
te denken is dat elke variabele naam een globale ``stapel'' van bindings
heeft, en wanneer je de naam van de variabele gebruikt, dat refereert aan de
bovenkant van de stapel. (Je kan je dit voorstellen als een stapel papieren
op je bureau waarop de waarden zijn geschreven.) Wanneer je een variabele
dynamisch bindt met @code{let}, plaatst het de nieuw gespecificeerde binding
bovenop de stapel en voert vervolgens de @code{let} body uit. Nadat de
@code{let} body eindigt, neemt het die binding van de stapel, en toont
diegene die er voor de @code{let}-expressie was (als er een was).

@node Lexical vs dynamische binding voorbeeld
@unnumberedsubsubsec Voorbeeld van lexical vs.@: dynamische binding
In sommige gevallen gedragen lexical en dynamische bindingen zich
gelijk. Echter in sommige gevallen kunnen zij de betekenis van je programma
wijzigen. Kijk bijvoorbeeld naar wat gebeurt in deze code onder lexical
binding: 

@example
;;; -*- lexical-binding: t -*-

(setq x 0)

(defun getx ()
  x)

(setq x 1)

(let ((x 2))
  (getx))
     @result{} 1
@end example

@noindent
Het resultaat van @code{(getx)} is hier @code{1}. Onder lexical binding ziet
@code{getx} de waarde van onze @code{let}-expressie niet. Dit is omdat de
body van @code{(getx)} buiten de body van onze @code{let}-expressie
is. Omdat @code{getx} bovenaan, op het globale niveau van code gedefinieerd
is (dus niet binnen de body van enige @code{let}-expressie), zoekt het en
vindt @code{x} eveneens op het globale niveau. De huidige globale waarde van
@code{x} is @code{1} bij de uitvoering van @code{getx}, en dus is dat wat
@code{getx} teruggeeft.

Wanneer we in plaats daarvan dynamisch binding gebruiken, is het gedrag
anders:

@example
;;; -*- lexical-binding: t -*-

(defvar x) ;; Gebruik dynamic binding voor 'x'.

(setq x 0)

(defun getx ()
  x)

(setq x 1)

(let ((x 2))
  (getx))
     @result{} 2
@end example

@noindent
Het resultaat van @code{(getx)} is nu @code{2}. Dat is omdat onder
dynamische binding bij het uitvoeren van @code{getx} de huidige binding voor
@code{x} op de bovenkant van onze stapel die is van onze @code{let}
binding. Deze keer ziet @code{getx} de globale waarde van @code{x} niet,
omdat deze binding onder degene van onze @code{let}-expressie in de stapel
van bindings ligt.

(De @code{defvar} declaratie hierboven maakt zogezegd de variabele
``speciaal'', wat zorgt dat het de dynamische binding regels volgt in plaats
van de standaard binding regels. @xref{defvar, , Initialiseer een variabele
met @code{defvar}}.)

@node if
@section De @code{if} speciale vorm
@findex if
@cindex Conditioneel met @code{if}

Een andere speciale vorm is de conditionele @code{if}. Deze vorm wordt
gebruikt om de computer te instrueren om beslissingen te nemen. Je kunt
functiedefinities schrijven zonder @code{if} te gebruiken, maar het wordt
vaak genoeg gebruikt en is belangrijk genoeg om het hier te behandelen. Het
wordt bijvoorbeeld gebruikt in de code van de functie
@code{beginning-of-buffer}.

Het basisidee achter @code{if} is, dat @emph{wanneer} een test waar is,
@emph{dan} een expressie wordt geëvalueerd. Wanneer de test niet waar is,
dan wordt de expressie niet geëvalueerd. Bijvoorbeeld zou je een
beslissingen kunnen maken zoals ``als het warm en zonnig is, dan ga ik naar
het strand!''. 

@menu
* if in meer detail::        if in meer detail
* type-dier in detail::      Voorbeeld van een @code{if} expressie.
@end menu

@ifnottex
@node if in meer detail
@unnumberedsubsec @code{if} in meer detail
@end ifnottex

@cindex @samp{wanneer-deel} gedefinieerd
@cindex @samp{dan-deel} gedefinieerd
Een @code{if}-expressie geschreven in Lisp gebruikt het woord ``then'' niet,
de test en de actie zijn de tweede en derde elementen van de lijst wiens
eerste element @code{if} is. Echter, het test-gedeelte van de lijst wordt
vaak het @code{wanneer}-gedeelte en het tweede argument het
@code{dan}-gedeelte genoemd.

Bij het schrijven van een @code{if}-expressie is het gebruikelijk de
waar-of-onwaar-test op dezelfde regel te zetten als het symbool @code{if},
maar de uit te voeren actie wanneer de test waar is, het dan-deel, op de
tweede en verdere regels. Dit maakt de @code{if}-expressie makkelijker te
lezen.

@smallexample
@group
(if @var{waar-of-onwaar-test}
    @var{actie-uit-te-voeren-als-de-test-waar-is})
@end group
@end smallexample

@noindent
De waar-of-onwaar-test is een expressie die door de Lisp interpreter wordt
geëvalueerd.

Hier is een voorbeeld dat je op de gebruikelijke manier kunt evalueren. De
test is of het getal 5 groter is dan het getal 4. Omdat dit zo is, wordt de
boodschap @samp{5 is groter dan 4!} getoond.

@smallexample
@group
(if (> 5 4)                             ; @r{wanneer-deel}
    (message "5 is groter dan 4!"))     ; @r{dan-deel}
@end group
@end smallexample

@noindent
(De functie @code{>} test of zijn eerste argument groter is dan zijn tweede
argument en geeft waar terug indien dat zo is.)
@findex > @r{(greater than)}

In werkelijk gebruik is de test natuurlijk niet voor altijd vastgelegd zoals
dat het geval is bij de expressie @code{(> 5 4)}. In plaats daarvan is
tenminste een van de variabelen die in de test gebruikt worden gebonden aan
een waarde die vooraf niet bekend is. (Als de waarde vooraf bekend zou zijn,
hoeven we de test niet doen!)

De waarde kan bijvoorbeeld gebonden zijn aan het argument van een
functiedefinitie. In de volgende functiedefinitie is het karakter van een
dier een waarde die wordt doorgegeven aan de functie. Wanneer de waarde
gebonden aan @code{karakteristiek} @code{woest} is, dan wordt de boodschap
@samp{Het is een tijger!} getoond. Zo niet, dan wordt @code{nil} teruggeven.

@smallexample
@group
(defun type-dier (karakteristiek)
  "Toon boodschap in echogebied afhankelijk van KARAKTERISTIEK.
Wanneer de KARAKTERISTIEK de string \"woest\" is,
dan waarschuw voor een tijger."
  (if (equal karakteristiek "woest")
      (message "Het is een tijger!")))
@end group
@end smallexample

@need 1500
@noindent
Wanneer je dit in GNU Emacs leest, dan kun je de functiedefinitie op de
gebruikelijke manier evalueren, en daarna kan je de volgende twee expressies
evalueren om de resultaten te zien:

@smallexample
@group
(type-dier "woest")

(type-dier "gestreept")

@end group
@end smallexample

@c Following sentences rewritten to prevent overfull hbox.
@noindent
Wanneer je @code{(type-dier "woest")} evalueert, zie je de volgende
boodschap in het echogebied: @code{"Het is een tijger!"} en wanneer je
@code{(type-dier "gestreept")} evalueert dan zie je @code{nil} in het
echogebied.

@node type-dier in detail
@subsection De @code{type-dier}-functie in detail

Laten we kijken naar de @code{type-dier}-functie in detail

De functiedefinitie van @code{type-dier} is geschreven door de slots van
twee sjablonen in te vullen, een voor de functiedefinitie in zijn geheel, en
een tweede voor een @code{if}-expressie.

@need 1250
Het sjabloon voor elke functie die niet interactief is, is:

@smallexample
@group
(defun @var{naam-van-de-functie} (@var{argument-list})
  "@var{documentatie}@dots{}"
  @var{body}@dots{})
@end group
@end smallexample

@need 800
De delen van de functie die overeenkomen met het sjabloon zien er zo uit:

@smallexample
@group
(defun type-dier  (karakteristiek)
  "Toon boodschap in echogebied afhankelijk van KARAKTERISTIEK.
Wanneer de KARAKTERISTIEK de string \"woest\" is,
dan waarschuw voor een tijger."
  @var{body: de} @code{if} @var{expressie})
@end group
@end smallexample

De naam van de functie is @code{type-dier}, het krijgt de waarde van één
argument doorgegeven. De argumentlijst wordt gevolgd door een meerregelige
documentatiestring. De documentatiestring is in dit voorbeeld opgenomen
omdat het een goede gewoonte is voor elke functiedefinitie een
documentatiestring te schrijven. De body van de functiedefinitie bestaat uit
de @code{if}-expressie.

@need 800
Het sjabloon voor een @code{if}-expressie ziet er zo uit: 

@smallexample
@group
(if @var{waar-of-onwaar-test}
    @var{uit-te-voeren-actie-wanneer-de-waar-of-onwaar-test-waar-teruggeeft})
@end group
@end smallexample

@need 1250
In de @code{type-dier}-functie, ziet de code voor de @code{if} er zo uit:

@smallexample
@group
  (if (equal karakteristiek "woest")
      (message "Het is een tijger!"))
@end group
@end smallexample

@need 800
Hier is de waar-of-onwaar-test de expressie:

@smallexample
(equal karakteristiek "woest")
@end smallexample

@noindent
In Lisp is @code{equal} een functie die vaststelt of zijn eerste argument
gelijk is aan zijn tweede argument. Het tweede argument is de string
@code{"woest"} en het eerste argument is de waarde van het symbool
@code{karakteristiek}---met andere woorden, het argument doorgegeven aan
deze functie.

In de eerste oefening van @code{type-dier} is het argument @code{"woest"}
doorgegeven naar @code{type-dier}. Omdat @code{"woest"} gelijk is aan
@code{"woest"} geeft de expressie @code{(equal karakteristiek "woest")} de
waarde waar terug. Wanneer dit gebeurt, evalueert de @code{if} het tweede
argument oftewel het dan-deel van de @code{if}: @code{(message "Het is een
tijger!")}.

Daarnaast is in de tweede oefening van @code{type-dier} het argument
@code{"gestreept"} doorgegeven naar @code{type-dier}. @code{"gestreept"} is
niet gelijk aan @code{"woest"} en daarom is het dan-deel niet geëvalueerd en
is @code{nil} teruggeven door de @code{if}-expressie.

@node else
@section If--then--else expressies
@cindex Else

Een @code{if}-expressie kan optioneel een derde argument hebben, het
@dfn{anders-deel}. voor het geval de waar-of-onwaar-test onwaar
teruggeeft. Wanneer dit gebeurt wordt het tweede argument, het dan-deel van
de @code{if}-expressie @emph{niet} geëvalueerd, maar wordt het derde deel,
het anders-deel, @emph{wel} geëvalueerd. Je kunt dit zien als het bewolkte
dag alternatief voor de beslissing ``als het warm en zonnig is, ga dan naar
het strand, anders lees een boek!''.

In de Lisp-code wordt het woord ``else'' niet geschreven, het anders-deel
van een @code{if}-expressie komt na het dan-gedeelte. In Lisp staat het
anders-deel gebruikelijk op zichzelf op een nieuwe regel en minder
ingesprongen dan het dan-deel:

@smallexample
@group
(if @var{waar-of-onwaar-test}
    @var{uit-te-voeren-actie-wanneer-de-waar-of-onwaar-test-waar-teruggeeft}
  @var{uit-te-voeren-actie-wanneer-de-waar-of-onwaar-test-onwaar-teruggeeft}))
@end group
@end smallexample

De volgende @code{if}-expressie bijvoorbeeld toont de boodschap @samp{4 is
niet groter dan 5!} wanneer je het op de gebruikelijke manier evalueert:

@smallexample
@group
(if (> 4 5)                               ; @r{if-deel}
    (message "4 valselijk groter dan 5!") ; @r{dan-deel}
  (message "4 is niet groter dan 5!"))    ; @r{anders-deel}
@end group
@end smallexample

@noindent
Merk op dat de verschillende niveaus van inspringen het makkelijk maken het
dan-deel te onderscheiden van het anders-deel. (GNU Emacs heeft
verschillende commando's die automatisch @code{if}-expressies correct laat
inspringen. @xref{Typen van lijsten, , GNU Emacs helpt je om lijsten te
typen}.) 

We kunnen de @code{type-dier}-functie uitbreiden met een anders-deel door
eenvoudig een aanvullend deel in de @code{if}-expressie in te voegen.

@need 1500
Je kunt de consequenties hiervan zien wanneer je de volgende versie van de
@code{type-dier} functiedefinitie installeert en daarna de twee volgende
expressies evalueert om de verschillende argumenten aan de functie door te
geven.

@smallexample
@group
(defun type-dier (karakteristiek)
  "Toon boodschap in echogebied afhankelijk van KARAKTERISTIEK.
Wanneer de KARAKTERISTIEK de string \"woest\" is,
dan waarschuw voor een tijger."
  (if (equal karakteristiek "woest")
      (message "Het is een tijger!")
    (message "Het is niet woest!")))
@end group
@end smallexample
@sp 1

@smallexample
@group
(type-dier "woest")

(type-dier "gestreept")

@end group
@end smallexample

@c Following sentence rewritten to prevent overfull hbox.
@noindent
Wanneer je @code{(type-dier "woest")} evalueert, zie je de volgende
boodschap in het echogebied: @code{"Het is een tijger!"}, maar wanneer je
@code{(type-dier "gestreept")} evalueert zie je @code{"Het is niet woest!"}.

(Wanneer de @var{karakteristiek} @code{"zeer woest"} is, dan wordt de
boodschap @code{"Het is niet woest!"} getoond, en dat is
misleidend!. Wanneer je code schrijft, moet je rekening houden met de
mogelijkheid dat een dergelijk argument wordt getest door de code en je
programma overeenkomstig schrijven.)

@node Waar en onwaarheid
@section Waar en onwaarheid in Emacs Lisp
@cindex Waar en onwaarheid in Emacs Lisp
@cindex Onwaarheid en waar in Emacs Lisp
@findex nil

Er is een belangrijk aspect aan de waarheidstest in een
@code{if}-expressie. Tot nu toe hebben we gesproken over ``waar'' en
``onwaar'' als waarden van predicaten alsof het nieuwe soorten van Emacs
Lisp objecten zijn. Feitelijk is ``onwaar'' onze oude vriend
@code{nil}. Alles wat anders is---wat dan ook--- is ``waar''.

De expressie die de test op waar wordt geïnterpreteerd als @dfn{waar}
wanneer het resultaat van de evaluatie een waarde ongelijk aan @code{nil}
is. Met andere woorden, het resultaat van de test wordt geacht waar te zijn
wanneer de teruggegeven waarde een getal is zoals 47, een string zoals
@code{"hallo"} of een symbool (anders dan @code{nil}), zoals @code{bloemen},
of een lijst (zolang die niet leeg is) of zelfs een buffer!

@menu
* nil uitgelegd::            @code{nil} heeft twee betekenissen.
@end menu

@ifnottex
@node nil uitgelegd
@unnumberedsubsec Een uitleg van @code{nil}
@end ifnottex

Voordat we de test op waar illustreren, hebben we eerst een uitleg van
@code{nil} nodig.

In Emacs Lisp heeft het symbool @code{nil} twee betekenissen. De eerste
betekenis is de lege lijst. De tweede betekenis is onwaar en is de waarde
wordt teruggegeven wanneer de waar-of-onwaar-test onwaar test. @code{nil}
kan worden geschreven als de lege lijst, @code{()}, of als @code{nil}. Voor
wat de Lisp interpreter betreft zijn @code{()} en @code{nil} gelijk. Mensen
echter gebruiken meestal @code{nil} voor onwaar en @code{()} voor de lege
lijst,

In Emacs Lisp wordt elke waarde die niet @code{nil} is---niet de lege lijst
is--- beschouwd als waar. Dit betekent dat wanneer een evaluatie iets
teruggeeft dat geen lege lijst is, een @code{if}-expressie het als waar
test. Wanneer bijvoorbeeld een getal in het slot voor de test gestopt
wordt. wordt het geëvalueerd en zal het zichzelf teruggeven, omdat dat is
wat getallen doen wanneer ze worden geëvalueerd. De expressie test als
onwaar uitsluitend wanneer @code{nil}, een lege lijst, wordt teruggegeven
door de expressie te evalueren.

Je kunt dit zien door het evalueren van de twee expressies in de volgende
voorbeelden.

In het eerste voorbeeld wordt het getal 4 geëvalueerd als de test in de
@code{if}-expressie en geeft zichzelf terug. Als gevolg wordt het dan-deel
van de expressie geëvalueerd en teruggegeven: @samp{waar} verschijnt in het
echogebied. In het tweede voorbeeld, de @code{nil} geeft onwaar aan, als
gevold wordt het anders-deel van de expressie geëvalueerd en teruggegeven:
@samp{onwaar} verschijnt in het echogebied.

@smallexample
@group
(if 4
    'waar
  'onwaar)
@end group

@group
(if nil
    'waar
  'onwaar)
@end group
@end smallexample

@need 1250
Overigens wanneer een zinnige waarde niet beschikbaar is voor een test die
waar teruggeeft, dan geeft de Lisp interpreter het symbool @code{t} voor
waar. Bijvoorbeeld evaluatie van de expressie @code{(> 5 4)} geeft @code{t}
terug, zoals je op de gebruikelijke manier kunt zien.

@smallexample
(> 5 4)
@end smallexample

@need 1250
@noindent
Anderzijds, deze functie geeft @code{nil} terug, wanneer het als onwaar
test.

@smallexample
(> 4 5)
@end smallexample

@node save-excursion
@section @code{save-excursion}
@findex save-excursion
@cindex Region, wat is het
@cindex Point en buffer behouden
@cindex Point en buffer behouden
@findex point
@findex mark

De functie @code{save-excursion} is de laatste speciale vorm die we in dit
hoofdstuk bespreken.

In Emacs Lisp programma's voor editing is de functie @code{save-excursion}
heel gebruikelijk. Het bewaart de locatie van point, voert de body van de
functie uit en herstelt point naar zijn vorige positie indien zijn lokatie
is gewijzigd. Het primaire doel is te voorkomen dat de gebruiker verrast en
verstoord wordt door onverwachte verplaatsing van point.

@menu
* Point en mark::            Een overzicht van verschillende locaties.
* Template voor save-excursion::  Template voor save-excursion
@end menu

@ifnottex
@node Point en mark
@unnumberedsubsec Point and Mark
@end ifnottex

Voordat we @code{save-excursion} bespreken is het echter zinvol eerst te
bekijken wat in GNU Emacs point en mark zijn. @dfn{Point} is de huidige
lokatie van de cursor. Waar de cursor ook is, dat is point. Preciezer
gezegd, in terminals waar de cursor bovenop een karakter verschijnt, is
point direct voor dat karakter. In Emacs Lisp is point een integer (geheel
getal). Het eerste karakter in een buffer is nummer één, het tweede is
nummer twee, enzovoorts. De functie @code{point} geeft de huidige positie
van de cursor als getal terug. Elk buffer heeft zijn eigen waarde voor
point.

De @dfn{mark} is een andere positie in het buffer. De waarde kan ingesteld
worden met een commando zoals @kbd{C-@key{SPC}}
(@code{set-mark-command}). Wanneer een mark is ingesteld, laat je met het
commando @kbd{C-x C-x} (@code{exchange-point-and-mark}) de cursor naar mark
springen en de mark instellen op de vorige positie van point. Verder, als je
een andere mark instelt wordt de positie van de vorige mark bewaard in de
mark-ring. Veel mark-posities kunnen zo bewaard worden. Je laat de cursor
naar een bewaarde mark springen door een of meer keer @kbd{C-u C-@key{SPC}}
te typen.

De deel van het buffer tussen point en mark heet de @dfn{region}. Talrijke
commando's werken op de region, inclusief @code{center-region},
@code{count-words-region}, @code{kill-region} en @code{print-region}.

De speciale vorm @code{save-excursion} bewaart de lokatie van point en
herstelt de positie nadat de code in de body van de speciale vorm is
geëvalueerd door de Lisp interpreter. Als point dus aan het begin van een
stuk tekst staat en bepaalde code heeft point naar het eind van het buffer
verplaatst, plaatst @code{save-excursion} point terug naar de locatie waar
het eerder was, nadat de expressies in de body van de functie zijn
geëvalueerd.

In Emacs verplaatsen functies regelmatig point als onderdeel van de interne
werking daarvan, alhoewel de gebruiker dat niet zou verwachten. Om te
voorkomen dat de gebruiker lastig gevallen wordt door springen die zowel
onverwacht als (vanuit het gezichtspunt van de gebruiker) onnodig zijn,
wordt @code{save-excursion} vaak gebruikt om point op de plek te houden waar
de gebruiker die verwacht. Het gebruik van @code{save-excursion} vormt een
goede huishouding.

Om zeker te stellen dat het huis schoon blijft, herstelt
@code{save-excursion} de waarde van point zelfs wanneer iets fout gaat in de
code (of, meer preciezer en in het juiste jargon, ``in geval van een
abnormale exit''). Deze eigenschap is erg behulpzaam.

Naast het registreren van de waarde van point houdt @code{save-excursion}
bij wat de huidige buffer is en herstelt die ook. Dit betekent dat je code
kunt schrijven die van buffer wisselt en je @code{save-excursion} laat
terugschakelen naar de originele buffer. Dit is hoe @code{save-excursion}
gebruikt wordt in @code{append-to-buffer}. (@xref{append-to-buffer, , De
definitie van @code{append-to-buffer}}.)

@node Template voor save-excursion
@subsection Sjabloon voor een @code{save-excursion} expressie

@need 800
Het sjabloon voor code die @code{save-excursion} gebruikt is simpel:

@smallexample
@group
(save-excursion
  @var{body}@dots{})
@end group
@end smallexample

@noindent
De body van de functie bestaat uit een of meer expressies die de Lisp
interpreter opeenvolgend evalueert. Wanneer de body meer dan een expressie
bevat, wordt de waarde van de laatste teruggegeven als waarde van de
@code{save-excursion}-functie. De andere expressies in de body worden
uitsluitend geëvalueerd voor hun zij-effecten en @code{save-excursion} zelf
wordt alleen gebruikt voor zijn zij-effect (het herstellen van de positie
van point).

@need 1250
Meer gedetailleerd ziet het sjabloon voor een
@code{save-excursion}-expressie er zo uit: 

@smallexample
@group
(save-excursion
  @var{eerste-expressie-in-body}
  @var{tweede-expressie-in-body}
  @var{derde-expressie-in-body}
   @dots{}
  @var{laatste-expressie-in-body})
@end group
@end smallexample

@noindent
Een expressie kan uiteraard zelf een symbool zijn, of een lijst.

In Emacs Lisp code komt een @code{save-excursion} vaak voor binnen de body
van een @code{let}-expressie. Dit ziet er zo uit:

@smallexample
@group
(let @var{varlist}
  (save-excursion
    @var{body}@dots{}))
@end group
@end smallexample

@node Terugblik
@section Terugblik

In de laatste hoofdstukken introduceerden we een macro en een flink aantal
functies en speciale vormen. Deze bespreken we hier in het kort, samen met
enkele vergelijkbare functies die we nog niet behandeld hebben.

@table @code
@item eval-last-sexp
Evalueer de laatste symbolische expressie voor de huidige lokatie van
point. De waarde wordt getoond in het echogebied tenzij de functie met een
argument is aangeroepen. In dat geval wordt de output in het huidige buffer
getoond. Dit commando is gewoonlijk gebonden aan @kbd{C-x C-e}.

@item defun
Definieer functie. Deze macro heeft maximaal vijf onderdelen: de naam, een
sjabloon voor de argumenten die aan de functie doorgegeven worden,
documentatie, een optionele interactieve declaratie en de body van de
definitie.

@need 1250
In Emacs is de functiedefinitie van bijvoorbeeld
@code{dired-unmark-all-marks} als volgt:

@smallexample
@group
(defun dired-unmark-all-marks ()
  "Remove all marks from all files in the Dired buffer."
  (interactive)
  (dired-unmark-all-files ?\r))
@end group
@end smallexample

@item interactive
Verklaar de interpreter dat de functie interactief gebruikt kan worden. Deze
speciale vorm kan worden gevolgd door een string met een of meer delen die
op volgorde informatie aan de argumenten van de functie doorgeven. Deze
delen kunnen de interactief ook om informatie vragen. Delen van de string
zijn gescheiden door nieuwe regels, @samp{\n}.

@need 1000
Gebruikelijke code karakters zijn:

@table @code
@item b
De naam van een bestaand buffer

@item f
De naam van een bestaand bestand

@item p
Het numerieke prefix-argument. (Merk op dat dit de kleine letter @code{p}
is)

@item r
Point en mark als twee numerieke argumenten, de kleinste eerst. Dit is de
enige letter die twee opvolgende argumenten specificeert, in plaats van een.
@end table

@xref{Interactive Codes, , Code Characters for @samp{interactive}, elisp,
The GNU Emacs Lisp Reference Manual}, voor een complete lijst van code
karakters.

@item let
Verklaar dat een lijst van variabelen wordt gebruikt binnen de body van de
@code{let} en geef ze een initiële waarde, hetzij @code{nil} of een
gespecificeerde waarde. Evalueer daarna de rest van de expressies in de body
van de @code{let} en geef de waarde van de laatste terug. Binnen de body van
de @code{let} ziet de Lisp interpreter de waarden niet van variabelen met
dezelfde naam die gebonden zijn buiten de @code{let}.

@need 1250
Bijvoorbeeld,

@smallexample
@group
(let ((foo (buffer-name))
      (bar (buffer-size)))
  (message
   "Dit buffer is %s en heeft %d karakters."
   foo bar))
@end group
@end smallexample

@item save-excursion
Registreer de waarde van point en het huidige buffer voor het evalueren van
de body van deze speciale vorm. Herstel achteraf de waarde van point en
buffer.

@need 1250
Bijvoorbeeld,

@smallexample
@group
(message "We zijn %d karakters in dit buffer."
         (- (point)
            (save-excursion
              (goto-char (point-min)) (point))))
@end group
@end smallexample

@item if
Evalueer het eerste argument van de functie. Wanneer het waar is, evalueer
het tweede argument, anders evalueer het derde argument, mits die er is.

De speciale vorm @code{if} heet een @dfn{conditional}. Er zijn andere
conditionals in Emacs Lisp, maar @code{if} is waarschijnlijk de meest
gebruikte.

@need 1250
Bijvoorbeeld,

@smallexample
@group
(if (= 22 emacs-major-version)
    (message "Dit is versie 22 Emacs")
  (message "Dit is niet versie 22 Emacs"))
@end group
@end smallexample

@need 1250
@item <
@itemx >
@itemx <=
@itemx >=
De functie @code{<} test of het eerste argument kleiner is dan het tweede
argument. Een corresponderende functie, @code{>} test of het eerste argument
groter is dan het tweede. Vergelijkbaar test @code{<=} of het eerste
argument kleiner of gelijk is aan het tweede en @code{>=} test of het eerste
argument groter of gelijk is aan het tweede. In alle gevallen moeten beide
argumenten getallen zijn of markers (markers geven de positie in buffers
aan).

@need 800
@item =
De functie @code{=} test of twee argumenten, beide nummers of markers,
gelijk zijn.

@need 1250
@item equal
@itemx eq
Test of twee objecten hetzelfde zijn. @code{equal} gebruikt een betekenis
van ``hetzelfde'' en @code{eq} gebruikt een andere. @code{equal} geeft waar
terug wanneer de twee objecten dezelfde structuur en inhoud hebben, zoals
twee exemplaren van hetzelfde boek. Daarnaast geeft @code{eq} waar terug
indien beide argumenten daadwerkelijk hetzelfde object zijn.
@findex equal
@findex eq

@need 1250
@item string<
@itemx string-lessp
@itemx string=
@itemx string-equal
De functie @code{string-lessp} test of het eerste argument kleiner is dan
het tweede. Een kortere alternatieve naam voor dezelfde functie (een
@code{defalias}) is @code{string<}.

De argumenten van @code{string-lessp} moeten strings of symbolen zijn, de
volgorde is lexicografish, dus hoofd- of kleine letters is van belang. Het
toont de namen van symbolen die worden gebruikt in plaats van de symbolen
zelf.

@cindex @samp{lege string} gedefinieerd
Een lege string, @samp{""}, is een string zonder karakters er in, en is
kleiner dan elke andere string van karakters.

@code{string-equal} verschaft de corresponderende test voor gelijkheid. De
kortere alternatieve naam is @code{string=}. Recente versies van Emacs
bevatten @code{string-greaterp}, met @code{string>} als korter
alternatief. Er zijn geen string test- functies die corresponderen met
@code{>=} of @code{<=}.

@item message
Toon een boodschap in het echogebied. Het eerste argument is een string die
@samp{%s}, @samp{%d} of @samp{%c} kan bevatten om de waarde van argumenten
te tonen die volgen op de string. Het voor @samp{%s} gebruikte argument moet
een string of een symbool zijn, het voor @samp{%d} gebruikte argument moet
een getal zijn. Het voor @samp{%c} gebruikte argument moet een @sc{ascii}
codenummer zijn, het wordt getoond als het karakter met die
@sc{ascii}-code. (Verschillende andere %-sequences zijn niet genoemd.) 

@item setq
@itemx set
De speciale vorm @code{setq} stelt de waarde van zijn eerste argument in op
de waarde van het tweede argument. Het eerste argument wordt automatisch
gequote door @code{setq}. Het doet hetzelfde voor opvolgende argumentparen.

@item buffer-name
Zonder een argument, geeft de waarde van het buffer terug als een string.

@item buffer-file-name
Zonder een argument, geeft de naam van het bestand terug dat het buffer
bezoekt.

@item current-buffer
Geeft het buffer waar Emacs actief is terug. Het is misschien niet het
buffer dat zichtbaar op het scherm is.

@item other-buffer
Geeft het meest recent geselecteerde buffer (anders dan het buffer
doorgegeven aan @code{other-buffer} als een argument en anders dan het
huidige buffer).

@item switch-to-buffer
Selecteert een buffer voor Emacs om actief in te zijn en toon het in het
huidige venster zodat de gebruiker het kan zien. Gebruikelijk gebonden aan
@kbd{C-x b}.

@item set-buffer
Schakelt de aandacht van Emacs naar een buffer waarop programma's gaan
draaien. Verandert niet wat het venster toont.

@item buffer-size
Geeft het aantal karakters in het huidige buffer.

@item point
Geeft de waarde van de huidige positie van de cursor, als een integer, telt
het aantal karakters vanaf het begin van het buffer.

@item point-min
Geeft de minimaal toegestane waarde van point in het huidige buffer. Dit is
1, behalve wanneer narrowing van toepassing is.

@item point-max
Geef de maximaal toegestane waarde van point in het huidige buffer. Dit is
het einde van het buffer, tenzij narrowing van toepassing is.
@end table

@need 1500
@node defun oefeningen
@section Oefeningen

@itemize @bullet
@item
Schrijf een niet-interactieve functie die de waarde van zijn argument, een
getal, verdubbelt. Maak die functie interactief.

@item
Schrijf een functie die test of de huidige waarde van  @code{fill-column}
groter is dan het argument dat wordt doorgegeven aan de functie, en zo ja,
toon het als een passende boodschap.
@end itemize

@node Buffer rondleiding
@chapter Enkele buffer gerelateerde functies

In dit hoofdstuk bestuderen we in detail verschillende in GNU Emacs
gebruikte functies. We noemen dit een ``rondleiding''. Deze functies worden
gebruikt als voorbeelden van Lisp code maar zijn geen denkbeeldige
voorbeelden. Met de uitzondering van de eerste versimpelde functiedefinitie
tonen deze functies de werkelijke code van GNU Emacs. Je kunt veel van deze
definities leren. De hier beschreven functies zijn alle gerelateerd aan
bufers. Later kijken we naar andere functies.

@menu
* Meer vinden::              Hoe meer informatie te vinden
* versimpelde-beginning-of-buffer::  Toon @code{goto-char}, @code{point-min} 
                                       en @code{push-mark}.
* mark-whole-buffer::        Bijna hetzelde als @code{beginning-of-buffer}.
* append-to-buffer::         Gebruikt @code{save-excursion} en 
                               @code{insert-buffer-substring}.
* Buffer gerelateerde terugblik::  Terugblik.
* Buffer oefeningen::        Buffer oefeningen
@end menu

@node Meer vinden
@section Meer informatie vinden

@findex describe-function@r{, geïntroduceerd}
@cindex Vind functiedocumentatie
In deze rondleiding beschrijf elke nieuwe functie die we behandelen. soms in
detail en soms kort. Wanneer je geïnteresseerd bent vraag je op elk moment
de volledige documentatie op van elke Emacs Lisp functie door @kbd{C-h f} te
typen, en daarna de naam van de functie (gevolg met @key{RET}). Je kunt op
ook de volledige documentatie van een variabele opvragen met het typen van
@kbd{C-h v}, en daarna de naam van de variabele (gevolg met @key{RET}).

@cindex De source van een functie vinden
@c In version 22, tells location both of C and of Emacs Lisp
@code{describe-function} vertelt je ook de locatie van de functie.

Plaats point in de naam van het bestand dat de functie bevat en druk op de
@key{RET}-toets. In dit geval @key{RET} betekent @code{push-button} in
plaats van ``return'' of ``enter''. Emacs neemt je meteen naar de
functiedefinitie.

@ignore
Not In version 22

If you move point over the file name and press
the @key{RET} key, which in this case means @code{help-follow} rather
than ``return'' or ``enter'', Emacs will take you directly to the function
definition.
@end ignore

Meer in het algemeen, wanneer je de functie in het originele bronbestand
wilt zien, spring je met de functie @code{xref-find-definitions} er
heen. @code{xref-find-definitions} werkt met een brede variëteit van talen,
niet alleen Lisp en C, en het werkt ook met non-programming
tekst. @code{xref-find-definitions} springt bijvoorbeeld naar de
verschillende nodes in de Texinfo broncode van dit document (onder
voorwaarde dat je het @command{etags}-hulpprogramma alle nodes van alle
handleidingen de met Emacs komen hebt laten registeren @pxref{Create Tags
Table,,, emacs, The GNU Emacs Manual}).

Type @kbd{M-.} (dus druk op de punt-toet terwijl je de @key{META}-toets
ingedrukt houdt, of type anders de @key{ESC} gevold door de punt-toets) om
het commando @code{xref-find-definitions} te gebruiken, en vervolgens, na de
prompt, de naam van de functie wiens broncode je wilt zien, zoals
@code{mark-whole-buffer} en type daarna @key{RET}. (Wanneer het commando
geen prompt geeft, roep het dan met een argument: @kbd{C-u
M-.}). @pxref{Interactieve opties}.) Emacs schakelt buffers en toont de
broncode van de functie op je scherm@footnote{Wanneer Emacs, in plaats van
het tonen van de broncode voor een Lisp functie, je vraagt welke tags tabel
te openen, roep dan @kbd{M-.} aan vanuit een buffer wiens major mode Emacs
Lisp of Lisp Interaction is. } Om naar je buffer terug te keren type je type
@kbd{M-,} of @kbd{C-x b @key{RET}}. (Op sommige toetsenborden, heeft de
@key{META}-toets het label @key{ALT}.)

@cindex Bibliotheek als term voor ``bestand''
Overigens worden de bestanden die Lisp code bevatten gewoonlijk
@dfn{bibliotheken} genoemd. De metafoor is afgeleid van een gespecialiseerde
bibliotheek, zoals een juridische bibliotheek of een technische bibliotheek,
in plaats van een algemene bibliotheek. Elke bibliotheek, of bestand, bevat
functies die aan bepaald onderwerp of activiteit gerelatieerd zijn, zoals
@file{abbrev.el} voor het afhandelen van afkortingen en andere
snelkoppelingen voor het typen, en @file{help.el} for hulp. (Soms
verschaffen verschillende bestanden code voor een enkele activiteit, zoals
de diverse @file{rmail@dots{}} bestanden code voor het lezen van e-mail
verschaffen.) In @cite{The GNU Emacs Manual} zie je zinnen zoals ``het
@kbd{C-h p} commando laat je de standaard Emacs lisp bibliotheken doorzoeken
op onderwerp sleutelwoorden.''

@node versimpelde-beginning-of-buffer
@section Een versimpelde @code{beginning-of-buffer} definitie
@findex versimpelde-beginning-of-buffer

De @code{beginning-of-buffer} is een goede functie om mee te starten omdat
je er waarschijnlijk al bekend mee bent en makkelijk te begrijpen
is. Gebruikt als een interactief commando verplaatst
@code{beginning-of-buffer} de cursor naar het begin van het buffer, en zet
de mark op de vorige positie. Het is gewoonlijk gebonden aan @kbd{M-<}.

In deze sectie bespreken we een verkorte versie van de functie die laat zien
hoe het meestal gebruikt wordt. De verkorte functie werkt, maar heeft geen
code voor een complexe optie. In een andere sectie zullen we de volledige
code bespreken. (@xref{beginning-of-buffer, , Complete definitie van
@code{beginning-of-buffer}}.) 

Voordat we naar de code kijken staan we stil bij de functiedefinitie moet
bevatten: het moet een expressie bevatten die de functie interactief maakt
zodat het kan worden afgeroepen met typen van @kbd{M-x beginning-of-buffer}
of door het typen van een toetscombinatie zoals @kbd{M-<}. Het moet code
bevatten om de mark op de originele positie te plaatsen en het moet code
bevatten om de cursor naar het begin van het buffer te verplaatsen. 

@need 1250
Hier is de complete text van de verkorte versie van de functie:

@smallexample
@group
(defun versimpelde-beginning-of-buffer ()
  "Verplaats point naar begin van het buffer;
plaats mark op de vorige positie."
  (interactive)
  (push-mark)
  (goto-char (point-min)))
@end group
@end smallexample

Zoals alle functiedefinitie heeft deze definitie de vijf delen volgens de
macro @code{defun}: 

@enumerate
@item
De naam: in dit voorbeeld @code{versimpelde-beginning-of-buffer}.

@item
Een lijst met argumenten, in dit voorbeeld een lege lijst, @code{()}.

@item
De documentatiestring

@item
De interactive expressie

@item
De body
@end enumerate

@noindent
In deze functiedefinitie is de argumentlijst leeg, dit betekent dat de
functie geen argumenten vereist. (Wanneer we naar de definitie van de
complete functie kijken zien we dat deze een optioneel argument kan
krijgen.)

De interactive expressie vertelt Emacs dat de functie bedoeld is voor
interactief gebruik. In dit voorbeeld heeft @code{interactive} geen
argumenten omdat @code{versimpelde-beginning-of-buffer} die niet nodig
heeft.

@need 800
De body van de functie bestaat uit twee regels:

@smallexample
@group
(push-mark)
(goto-char (point-min))
@end group
@end smallexample

De eerste van de twee regels is de expressie @code{(push-mark)}. Wanneer de
Lisp interpreter deze expressie evalueert stel het de mark op de huidige
positie van de cursor in, wat die ook is. De positie van deze mark wordt
bewaard in de mark-ring.

De volgende regel is @code{(goto-char (point-min))}. Deze expressie springt
de cursor naar het minimum punt in het buffer, dat is het begin van de
buffer (of het begin van het bereikbare deel van de buffer wanneer is het
versmald. @xref{Versmallen en verbreden, , Versmallen en verbreden}.)

Het @code{push-mark} commando zet de mark op de plaats waar de cursor was
voordat het door de @code{(goto-char (point-min))} expressie naar het begin
van de buffer werd verplaatst. Daardoor kan je, als je dat wilt, terug gaan
naar de plek waar je oorspronkelijk was door @kbd{C-x C-x} te typen.

Dat is alles wat er is voor deze functiedefinitie!

@findex describe-function
Wanneer je code zoals deze leest en een onbekende functie tegenkomt zoals
@code{goto-char}, kan je met het @code{describe-function} commando ontdekken
wat die doet. Typ @kbd{C-h f} gevold door de naam van de functie en toets
daarna @key{RET} om dit commando te gebruiken. Het @code{describe-function}
commando toont de documentatiestring van de functie in een
@file{*Help*}-venster. Bijvoorbeeld de documentatie voor @code{goto-char}
is: 

@smallexample
@group
Set point to POSITION, a number or marker.
Beginning of buffer is position (point-min), end is (point-max).
@end group
@end smallexample

@noindent
Het enige argument van de functie is de gewenste positie.

@noindent
De prompt voor @code{describe-function} stelt je het symbool onder of
voorafgaand aan de cursor voor, zodat je minder hoeft te typen door de
cursor boven of meteen achter de functie te plaatsen en dan @kbd{C-h f
@key{RET}} te typen.)

De functiedefinitie van @code{end-of-buffer} is op dezelfde manier
geschreven als de @code{beginning-of-buffer}-definitie, belalve dat de body
van de functie de expressie @code{(goto-char (point-max))} bevat in plaats
van @code{(goto-char (point-min))}.

@node mark-whole-buffer
@section De definitie van @code{mark-whole-buffer}
@findex mark-whole-buffer

De functie @code{mark-whole-buffer} is niet lastiger te begrijpen dan de
@code{versimpelde-beginning-of-buffer}-functie. In dit geval kijken we
echter naar de complete functie en niet naar een verkorte versie.

De functie @code{mark-whole-buffer} wordt minder vaak gebruikt dan de
functie @code{beginning-of-buffer}, maar is toch zinvol: het markeert de
hele buffer als region door de point aan het begin en de mark aan het einde
van de buffer te plaatsen. Het is gebruikelijk gebonden aan @kbd{C-x h}.

@menu
* mark-whole-buffer overzicht::  mark-whole-buffer overzicht
* Body van mark-whole-buffer::  Slechts drie regels met code
@end menu

@ifnottex
@node mark-whole-buffer overzicht
@unnumberedsubsec Een overzicht van @code{mark-whole-buffer}
@end ifnottex

@need 1250
In GNU Emacs 22 ziet de code voor de gehele functie er zo uit:

@smallexample
@group
(defun mark-whole-buffer ()
  "Put point at beginning and mark at end of buffer.
You probably should not use this function in Lisp programs;
it is usually a mistake for a Lisp function to use any subroutine
that uses or sets the mark."
  (interactive)
  (push-mark (point))
  (push-mark (point-max) nil t)
  (goto-char (point-min)))
@end group
@end smallexample

@need 1250
Zoals alle andere functie past de functie @code{mark-whole-buffer} in het
sjabloon voor de functiedefinitie. Het sjabloon is als volgt: 

@smallexample
@group
(defun @var{naam-van-de-functie} (@var{argument-list})
  "@var{documentatie}@dots{}"
  (@var{interactive-expression}@dots{})
  @var{body}@dots{})
@end group
@end smallexample

Dit is hoe de functie werkt: de naam van de functie is
@code{mark-whole-buffer}, gevold door een lege argumentlijst @samp{()}, wat
inhoudt dat de functie geen argumenten vereist. De documentatie komt daarna.

De volgende regel is de @code{(interactive)}-expressie die Emacs vertelt dat
de functie interactief gebruikt gaat worden. Deze details zijn vergelijkbaar
met de in de vorige sectie beschreven functie
@code{versimpelde-beginning-of-buffer}.

@need 1250
@node Body van mark-whole-buffer
@subsection Body van @code{mark-whole-buffer}

De body van de functie @code{mark-whole-buffer} bestaat uit drie regels
code:

@c GNU Emacs 22
@smallexample
@group
(push-mark (point))
(push-mark (point-max) nil t)
(goto-char (point-min))
@end group
@end smallexample

De eerste van deze regels is de expressie @code{(push-mark (point))}.

Deze regel doet precies hetzelfde als de eerste regel in de body van de
functie @code{versimpelde-beginning-of-buffer}, waar @code{(push-mark)}
staat. In beide gevallen zet de Lisp interpreter de mark op de huidige
positie van de cursor.

Ik weet niet waarom @code{(push-mark (point))} in @code{mark-whole-buffer}
staat en @code{(push-mark)} in de expressie @code{beginning-of-buffer}
. Misschien wist wie de code schreef niet dat de argumenten van
@code{push-mark} optioneel zijn en dat wanneer geen argument aan
@code{push-mark} wordt doorgegeven, de functie automatisch standaard de
locatie van de cursor gebruikt. Of misschien was de expressie zo geschreven
dat die parallel aan de structuur van de volgende regel is. In elk geval
zorgt de regel dat Emacs de positie van point vaststelt en de mark daar zet.

De volgende regel van @code{mark-whole-buffer} was in een eerdere versie van
GNU Emacs @code{(push-mark (point-max))}. Deze expressie zet de mark op het
punt met het hoogste getal in het buffer. Deze is aan het eind van het
buffer (of, wanneer het buffer versmald is, aan het eind van het bereikbare
deel van de buffer, @xref{Versmallen en verbreden, , Versmallen en
verbreden}.) Nadat de mark is ingesteld, is de vorige mark, die op point was
gezet, niet meer ingesteld, maar Emacs herinnert zijn positie, net als het
alle recente marks altijd herinnert. Dit betekent dat, als je het wilt, je
naar de positie terugkeert met het twee keer typen van @kbd{C-u
C-@key{SPC}}.

@need 1250
In GNU Emacs 22 is @code{(point-max)} iets meer gecompliceerd. De regel is:

@smallexample
(push-mark (point-max) nil t)
@end smallexample

@noindent
De expressie werkt bijna hetzelfde als hiervoor. Het stelt de mark in op de
hoogst mogelijk  genummerde plaats in het buffer. Echter in deze versie
heeft @code{push-mark} twee aanvullende argumenten. Het tweede argument voor
@code{push-mark} is @code{nil}. Dit vertelt de functie dat het de boodschap
``Mark set'' @emph{moet} tonen wanneer het de mark pusht. Het derde argument
is  @code{t}. Dit vertelt @code{push-mark} om de mark te activeren wanneer
Transient Mark mode aan staat. Transient Mark mode highlight de huidige
actieve region. Het staat vaak uit.

De laatste regel van de functie is tenslotte @code{(goto-char
(point-min)))}. Dit is op precies dezelfde manier geschreven als in
@code{beginning-of-buffer}. De expressie verplaatst de cursor naar het
minimale punt in het buffer, dat is het begin van het buffer (of het begin
van het bereikbare deel van het buffer). Het resultaat is dat point aan het
begin van het buffer en de mark aan het eind van het buffer staan. Het hele
buffer is daardoor de region.

@node append-to-buffer
@section De definitie van @code{append-to-buffer}
@findex append-to-buffer

Het @code{append-to-buffer} commando is complexer dan het
@code{mark-whole-buffer} commando. Wat het doet is de region (dat is het
deel van het buffer tussen point en mark) van het huidige buffer kopiëren
naar een specifiek buffer.

@menu
* append-to-buffer overzicht::  append-to-buffer overzicht
* append interactief::       Een tweedelige interactieve expressie.
* append-to-buffer body::    Bevat een @code{let} expressie.
* append save-excursion::    Hoe de @code{save-excursion} werkt.
@end menu

@ifnottex
@node append-to-buffer overzicht
@unnumberedsubsec Een overzicht van @code{append-to-buffer}
@end ifnottex

@findex insert-buffer-substring
Het @code{append-to-buffer} commando gebruikt de functie
@code{insert-buffer-substring} om de region te
kopiëren. @code{insert-buffer-substring} doet wat de naam zegt: het neemt
een substring van een buffer en voegt die in een andere buffer in.

Het grootste deel van @code{append-to-buffer} houdt zich bezig met het
voorbereiden van de condities voor het werk van
@code{insert-buffer-substring}: de code specificeert het buffer waar de
tekst heen gaat, het venster waar het vandaan komt en naar toe gaat en de
region die gekopieerd wordt.

@need 1250
Hier is een mogelijke implementatie van de functie:

@c GNU Emacs 22
@smallexample
@group
(defun append-to-buffer (buffer start end)
  "Voeg tekst van de region toe aan het gespecificeerde buffer.
Het wordt voor de point in dat buffer ingevoegd.
@end group

@group
Geef bij het aanroepen vanuit een programma drie argumenten:
BUFFER (of buffernaam), START en END.
START en END specificeren het te kopiëren deel van het huidige buffer."
  (interactive
   (list (read-buffer "Append to buffer: " (other-buffer
                                            (current-buffer) t))
         (region-beginning) (region-end)))
@end group
@group
  (let ((oldbuf (current-buffer)))
    (save-excursion
      (let* ((append-to (get-buffer-create buffer))
             (windows (get-buffer-window-list append-to t t))
             point)
        (set-buffer append-to)
        (setq point (point))
        (barf-if-buffer-read-only)
        (insert-buffer-substring oldbuf start end)
        (dolist (window windows)
          (when (= (window-point window) point)
            (set-window-point window (point))))))))
@end group
@end smallexample

De functie kan begrepen worden door het bekijken als een serie ingevulde
sjablonen.

Het buitenste sjabloon is voor de functiedefinitie. In deze functie ziet het
er zo uit (met verschillende ingevulde slots):

@smallexample
@group
(defun append-to-buffer (buffer start end)
  "@var{documentatie}@dots{}"
  (interactive @dots{})
  @var{body}@dots{})
@end group
@end smallexample

De eerste regel van de functie bevat de naam en drie argumenten. De
argumenten zijn de @code{buffer} waar het de tekst naar toe kopieert, en de
@code{start} en @code{end} van de te kopiëren region in het huidige buffer.

Het volgende deel is de documentatie die helder en compleet is. De drie
argumenten zijn, volgens de conventie, in hoofdletters geschreven, zodat je
ze makkelijk kunt opmerken. Nog beter is dat ze in dezelfde volgorde staan
als in de argumentlijst.

Merk op de dat de documentatie de buffer en zijn naam onderscheidt. (De
functie kan met beide overweg.)

@node append interactief
@subsection De @code{append-to-buffer} interactieve expressie

Omdat de @code{append-to-buffer} functie interactief gebruikt gaat worden,
moet de functie een @code{interactive} expressie hebben. (Voor een terugblik
op d@code{interactive}, zie @ref{Interactief, , Een functie interactief
maken}. 

De exressie is als volgt:

@smallexample
@group
 (list (read-buffer
        "Append to buffer: "
        (other-buffer (current-buffer) t))
       (region-beginning)
       (region-end)))
@end group
@end smallexample

@noindent
Deze expressie is er niet een met letters die voor de delen staan, zoals
eerder beschreven. In plaats daarvan begint het met een lijst met deze
delen:

Het eerste deel van de lijst is een expressie die de naam van het buffer
leest en als een string teruggeeft. Dat is @code{read-buffer}. De functie
vereist een prompt as het eerste argument, @samp{"Append to buffer: "}. Het
tweede argument vertelt het commando welke waarde te verschaffen wanneer je
er geen specificeert.

In dit geval is het tweede argument een expressie bestaand uit de functie
@code{other-buffer}, een utizondering en een @samp{t}, dat voor waar staat.

Het eerste argument voor @code{other-buffer}, de uitzondering, is opnieuw
een functie, @code{current-buffer}. Die wordt niet teruggegeven. Het tweede
argument is het symbool voor waar, @code{t}. Deze vertelt
@code{other-buffer} dat het zichtbare buffers mag tonen (behalve dat het in
dit geval niet het huidige buffer toont, wat logisch is).

@need 1250
De expressie ziet er zo uit:

@smallexample
(other-buffer (current-buffer) t)
@end smallexample

Het tweede en derde argument in de @code{lijst} expressies zijn
@code{(region-beginning)} en @code{(region-end)}. Deze twee functies
specificeren het begin en einde van de toe te voegen tekst.

@need 1250
Oorspronkelijk gebruikte het commando de letters @samp{B} en @samp{r}. De
gehele @code{interactive} expressie zag er zo uit:

@smallexample
(interactive "BAppend to buffer:@: \nr")
@end smallexample

@noindent
Maar toen dat gereed was, bleek de standaard waarde van het buffer waar naar
toe geschakeld was onzichtbaar. Dat was niet gewenst.

(De prompt werd gescheiden van het tweede argument met een nieuwe regel,
@samp{\n}. Het werd gevolgd door een @samp{r} die Emacs vertelde om de twee
argumenten die volgen op het symbool @code{buffer} in de argumentlijst van
de functie (te weten, @code{start} en @code{end}) aan de waarden van point
en mark te binden. Dat argument werkte prima.)

@node append-to-buffer body
@subsection De body van @code{append-to-buffer}

De body van de functie @code{append-to-buffer} begint met @code{let}.

Zoals we eerder zagen (@pxref{let, , @code{let}}), is het doel van een
@code{let} expressie om een of meer variabelen te creëerden en een initiële
waarde te geven die uitsluitend worden gebruikt binnen de body van de
@code{let}. Dit betekent dat zo'n variabele niet verward wordt met een
variabele met dezelfde naam buiten de @code{let} expressie.

We kunnen zien hoe de @code{let}-expressie past in de functie als geheel,
door een overzicht van het sjabloon te tonen voor de @code{append-to-buffer}
met de @code{let}-expressie.

@smallexample
@group
(defun append-to-buffer (buffer start end)
  "@var{documentatie}@dots{}"
  (interactive @dots{})
  (let ((@var{variable} @var{value}))
        @var{body}@dots{}))
@end group
@end smallexample

De @code{let}-expressie heeft drie elementen:

@enumerate
@item
Het symbool @code{let};

@item
Een varlist die, in dit geval, een enkele lijst met twee elementen bevat,
@code{(@var{variable} @var{value})};

@item
De body van de @code{let}-expressie.
@end enumerate

@need 800
In de functie @code{append-to-buffer} ziet de varlist er zo uit:

@smallexample
(oldbuf (current-buffer))
@end smallexample

@noindent
In dit deel van de @code{let} de ene variabele, @code{oldbuf}, is gebonden
aan de waarde die de @code{(current-buffer)} expressie teruggeeft. De
variabele, @code{oldbuf} wordt gebruikt om het buffer bij te houden in welk
je werkt en vanwaar je kopieert.

Het element of de elementen van een varlist zijn omgeven door een paar
haakjes, zodat de Lisp interpreter de varlist kan onderscheiden van de body
van de @code{let}. Als gevolg hiervan is de lijst met twee elementen binnen
de varlist omgeven door een omtrekkende paar haakjes. De regel ziet er zo
uit:

@smallexample
@group
(let ((oldbuf (current-buffer)))
  @dots{} )
@end group
@end smallexample

@noindent
De twee haakjes voor @code{oldbuf} kunnen je verrassen wanneer je je niet
realseerde dat het eerste haakje voorafgaand aan @code{oldbuf} de grens van
de varlist markeert en het tweede haakje het begin van de lijst met twee
elementen, @code{(oldbuf (current-buffer))}.markeert. 

@node append save-excursion
@subsection @code{save-excursion} in @code{append-to-buffer}

De body van de @code{let} expressie in @code{append-to-buffer} bestaat uit
een @code{save-excursion} expressie.

De functie @code{save-excursion} bewaart de lokatie van point en herstelt
point naar die positie na afloop van de uitvoering van de expressies in de
body van @code{save-excursion}. Verder houdt @code{save-excursion} bij wat
het oorspronkelijke buffer en herstelt die. Dit is hoe @code{save-excursion}
wordt gebruikt in @code{append-to-buffer}.

@need 1500
@cindex Indentie voor formatteren
@cindex Formattering conventie
Overigens is het waardevol hier op te merken dat een Lisp functie normaal zo
geformatteerd is dat alles wat over meerdere regels verspreid is, meer
inspringt dan het eerste symbool. In deze functiedefinitie springt de
@code{let} meer in dan de @code{defun} en de @code{save-excursion} springt
meer in dan de @code{let}, zoals dit:

@smallexample
@group
(defun @dots{}
  @dots{}
  @dots{}
  (let@dots{}
    (save-excursion
      @dots{}
@end group
@end smallexample

@need 1500
@noindent
De formattering-conventie maakt het makkelijk te zien dat de regels in de
body van @code{save-excursion} zijn ingesloten in de haakjes geassocieerd
met @code{save-excursion}, net zoals de @code{save-excursion} ingesloten is
in de haakjes geassocieerd met de @code{let}:

@smallexample
@group
(let ((oldbuf (current-buffer)))
  (save-excursion
    @dots{}
    (set-buffer @dots{})
    (insert-buffer-substring oldbuf start end)
    @dots{}))
@end group
@end smallexample

@need 1200
Het gebruik van de functie @code{save-excursion} kan beschouwd worden als
een proces om de slots in het sjabloon in te vullen:

@smallexample
@group
(save-excursion
  @var{eerste-expressie-in-body}
  @var{tweede-expressie-in-body}
   @dots{}
  @var{laatste-expressie-in-body})
@end group
@end smallexample

@need 1200
@noindent
@anchor{let* geïntroduceerd}
@findex let*
In deze functie bevat de body van @code{save-excursion} slechts één
expressie, de @code{let*} expressie. Je kent de @code{let}-functie. de
functie @code{let*} is anders. Het maakt Emacs mogelijk om elke variabele in
de varlist op volgorde in te stellen, de een na de ander. zo dat de
variabelen in een later gedeelte van de varlist gebruik kunnen maken van
waarden die Emacs eerder in de varlist instelde.

Kijkend naar de @code{let*} expressie in @code{append-to-buffer}:

@smallexample
@group
(let* ((append-to (get-buffer-create buffer))
       (windows (get-buffer-window-list append-to t t))
       point)
  BODY...)
@end group
@end smallexample

@noindent
zien we dat @code{append-to} gebonden is aan de waarde teruggegeven door
@w{@code{(get-buffer-create buffer)}}. Op de volgende regel is
@code{append-to} gebruikt als argument voor
@code{get-buffer-window-list}. Dit zou niet mogelijk geweest zijn met de
@code{let}-expressie. Merk op dat @code{point} automatisch is gebonden aan
@code{nil}, net zo als dat zou zijn gebeurd in de @code{let}-statement.

Laten we ons nu focussen op de functies @code{set-buffer} en
@code{insert-buffer-substring} in de body van de @code{let*} expressie.

@need 1250
In het verleden was de @code{set-buffer}-expressie eenvoudigweg:

@smallexample
(set-buffer (get-buffer-create buffer))
@end smallexample

@need 1250
@noindent
maar nu is het

@smallexample
(set-buffer append-to)
@end smallexample

@noindent
Dit is omdat @code{append-to} gebonden was aan @code{(get-buffer-create
buffer)} eerder in de @code{let*}-expressie.

De @code{append-to-buffer} functiedefinitie voegt tekst in van het buffer
waar je nu in bent naar een genoemd buffer. Toevallig doet
@code{insert-buffer-substring} precies het omgekeerde---het kopieert tekst
van een ander buffer naar het huidige buffer---en dat is waarom de
@code{append-to-buffer} definitie begint met de @code{let} dat het lokale
symbool @code{oldbuf} bindt aan de door @code{current-buffer} teruggegeven
waarde.

@need 1250
De @code{insert-buffer-substring} expressie ziet er zo uit:

@smallexample
(insert-buffer-substring oldbuf start end)
@end smallexample

@noindent
The @code{insert-buffer-substring} function copies a string @emph{from} the
buffer specified as its first argument and inserts the string into the
present buffer.  In this case, the argument to
@code{insert-buffer-substring} is the value of the variable created and
bound by the @code{let}, namely the value of @code{oldbuf}, which was the
current buffer when you gave the @code{append-to-buffer} command.

Nadat @code{insert-buffer-substring} zijn werk gedaan heeft, herstelt
@code{save-excursion} de actie naar het originele buffer en heeft
@code{append-to-buffer} zijn werk gedaan.

@need 800
Hoog over bekeken ziet de werking van de body er zo uit:

@smallexample
@group
(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
  (save-excursion                       ; @r{Bijhouden van het buffer.}
    @var{change-buffer}
    @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})

  @var{schakel-terug-naar-oorspronkelijke-buffer-indien-gereed}
@var{laat-de-lokale-betekenis-van-}@code{oldbuf}@var{-verdwijnen-indien-gereed}
@end group
@end smallexample

Samengevat werkt @code{append-to-buffer} als volgt: het bewaart de waarde
van het huidige buffer in de variabele met de naam @code{oldbuf}. Het krijgt
de nieuwe buffer (en maakt er zo nodig een aan) en schakelt de aandacht van
Emacs daar naar toe. Met de waarde van @code{oldbuf} voegt het de tekst van
de region van het oude buffer in het nieuwe in. Daarna brengt het je met
@code{save-excursion} terug naar je oorspronkelijke buffer.

Met het kijken naar @code{append-to-buffer}, heb je een behoorlijk complexe
functie verkend. Het toont het gebruik van @code{let} en
@code{save-excursion} en hoe naar een ander buffer te schakelen en terug te
komen. Veel functiedefinities gebruiken @code{let}, @code{save-excursion} en
@code{set-buffer} op deze manier.

@node Buffer gerelateerde terugblik
@section Terugblik

Hier is een korte samenvatting van de verschillende in dit hoofdstuk
besproken functies.

@table @code
@item describe-function
@itemx describe-variable
Toon de documentatie voor een functie of variabele. Gewoonlijk gebonden
aan@kbd{C-h f} en @kbd{C-h v}.

@item xref-find-definitions
Vindt het bestand dat de broncode voor een functie of variabele bevat en
schakel buffers daar naar toe en plaats point aan het begin van dat
item. Gewoonlijk gebonden aan @kbd{M-.} (dat is een punt volgend op de
@key{META} toets).

@item save-excursion
Bewaar de lokatie van point en herstel zijn waarde nadat de argumenten van
@code{save-excursion} zijn geëvalueerd. Onthoud ook het huidige buffer en
keer daar naar terug.

@item push-mark
Stel mark in op een lokatie en bewaarde waarde van voorgaande mark op de
mark-ring. De mark is een lokatie in het buffer dat zijn relatieve positie
behoudt, zelfs wanneer in het buffer tekst is toegevoegd of verwijderd.

@item goto-char
Zet point op de lokatie gespecificeerd door de waarde van het argument, dat
een getal kan zijn, een marker, of een expressie die ene getal of een
positie teruggeeft, zoals @code{(point-min)}.

@item insert-buffer-substring
Kopieer een region met tekst van een buffer dat als argument is doorgegeven
aan de functie en voeg de region in het huidige buffer in.

@item mark-whole-buffer
Markeer het gehele buffer als region. Normaal gebonden aan  @kbd{C-x h}.

@item let*
Declareer een lijst met variabelen en geef die een initiële waarde. Evalueer
de rest van de expressies in de body van @code{let*}. De waarden van de
variabelen kunnen gebruikt worden om daaropvolgende variabelen in de lijst
te binden.

@item set-buffer
Richt de aandacht van Emacs op een ander buffer, maar wijzig het getoonde
venster niet. Wordt gebruikt wanneer een programma in plaats van een mens op
een ander buffer werkt.

@item get-buffer-create
@itemx get-buffer
Vindt een genoemd buffer of maak er een wanneer een buffer met die naam nog
niet bestaat. De functie @code{get-buffer} geeft @code{nil} terug wanneer
het genoemde buffer niet bestaat.
@end table

@need 1500
@node Buffer oefeningen
@section Oefeningen

@itemize @bullet
@item
Schrijf je eigen @code{versimpelde-beginning-of-buffer}
functiedefinitie. Test daarna om te kijken of het werkt.

@item
Gebruik @code{if} en @code{get-buffer} om een functie te schrijven die een
boodschap toon die aangeeft of een buffer wel of niet bestaat.

@item
Zoek met @code{xref-find-definitions} de bron voor de functie
@code{copy-to-buffer}.
@end itemize

@node Meer complex
@chapter Enkele meer complexe functies

In dit hoofdstuk bouwen we voort op wat in de vorige hoofdstukken hebben
geleerd door naar meer complexe functies te kijken. De functie
@code{copy-to-buffer} illustreert het gebruik van twee @code{save-excursion}
expressies in één definitie, terwijl de @code{insert-buffer} het gebruik van
een ster in een @code{interactive} expressie, het gebruik van @code{or}, en
het belangrijke onderscheid tussen een naam en het object waar die aan
refereert.

@menu
* copy-to-buffer::           Met @code{set-buffer} en 
                               @code{get-buffer-create}.
* insert-buffer::            Read-only en met @code{or}
* beginning-of-buffer::      Toon @code{goto-char}, @code{point-min} en 
                               @code{push-mark}.
* Tweede buffer gerelateerde terugblik::  Tweede buffer gerelateerde 
                                            terugblik
* optionele oefening::       optionele oefening
@end menu

@node copy-to-buffer
@section De definitie van @code{copy-to-buffer}
@findex copy-to-buffer

Wanneer je begrijpt hoe @code{append-to-buffer} werkt, is het eenvoudig
@code{copy-to-buffer} te begrijpen. Deze functie kopieert tekst naar een
buffer, maar in plaats van het aan het tweede buffer toe te voegen vervangt
het alle voorgaande tekst in het tweede buffer.

@need 800
De body van @code{copy-to-buffer} ziet er zo uit.

@smallexample
@group
@dots{}
(interactive "BCopy to buffer: \nr")
(let ((oldbuf (current-buffer)))
  (with-current-buffer (get-buffer-create buffer)
    (barf-if-buffer-read-only)
    (erase-buffer)
    (save-excursion
      (insert-buffer-substring oldbuf start end)))))
@end group
@end smallexample

De functie @code{copy-to-buffer} heeft een simpeler @code{interactive}
expressie dan @code{append-to-buffer}.

@need 800
De definitie zegt daarna:

@smallexample
(with-current-buffer (get-buffer-create buffer) @dots{}
@end smallexample

Kijk ten eerste naar de vroegste binnen liggende expressie, die wordt het
eerste geëvalueerd. De functie vertelt de computer het buffer te gebruiken
met de naam gespecificeerd als diegene waarna je wilt kopiëren, of aan te
maken als die niet bestaat. Daarna evalueert de functie
@code{with-current-buffer} met dat als tijdelijk huidige buffer, waarna het
terugschakelt naar de buffer waar wij nu zijn@footnote{Dit is vergelijkbaar
met @w{@code{(save-excursion (set-buffer @dots{}) @dots{})}} in één keer
aanroepen, maar het is een beetje anders gedefinieerd, wat de
geïnteresseerde lezer met @code{describe-function} kan ontdekken.}.

(Dit demonstreert een andere manier om de aandacht van de computer maar niet
die van de gebruiker te schakelen). De functie @code{append-to-buffer}
toonde dit te doen met @code{save-excursion} and
@code{set-buffer}. @code{with-current-buffer} is een nieuwer en misschien
zelfs makkelijker mechanisme.)

De functie @code{barf-if-buffer-read-only} zend je een foutmelding die zegt
dat het buffer read-only is wanneer je het niet mag wijzigen.

De volgende regel heeft de functie @code{erase-buffer} als enige inhoud. Het
wist het buffer.

De laatste twee regels tenslotte bevatten de @code{save-excursion} expressie
met @code{insert-buffer-substring} als body. De
@code{insert-buffer-substring} expressie kopieert de tekst van het buffer
waar je nu in bent (en je hebt niet gezien dat de computer zijn aandacht
verplaatst heeft, waardoor je niet weet dat dit buffer nu @code{oldbuf}
heet.)

Overigens is dit wat bedoeld wordt met ``vervanging''. Om tekst te vervangen
wist Emacs de vorige tekst en voegt daarna de nieuwe tekst in.

@need 1250
Globaal ziet de body van @code{copy-to-buffer} er zo uit:

@smallexample
@group
(let (@var{bind-}@code{oldbuf}@var{-aan-de-waarde-van-}@code{current-buffer})
    (@var{met-het-buffer-waarheen-je-kopieert}
      (@var{maar-wis-of-kopieer-niet-naar-een-read-only-buffer})
      (erase-buffer)
      (save-excursion
        @var{insert-substring-van-}@code{oldbuf}@var{-in-buffer})))
@end group
@end smallexample

@node insert-buffer
@section De definitie van @code{insert-buffer}
@findex insert-buffer

@code{insert-buffer} is weer een andere buffer-gerelateerde functie. Het
commando kopieert een ander buffer @emph{naar} het huidige buffer. Het is
het omgekeerde van @code{append-to-buffer} of @code{copy-to-buffer}, deze
kopiëren immers tekst @emph{van} het huidige buffer naar een ander buffer.

Hier is een bespreking gebaseerd op de originele code. De code is
vereenvoudigd in 2003 en is moeilijker te begrijpen.

(@xref{Nieuwe insert-buffer, , Nieuwe body voor @code{insert-buffer}}, voor
een bespreking van de nieuwe body.

Daarnaast illustreert deze code het gebruik van @code{interactive} met een
buffer dat @dfn{read-only} zou kunnen zijn en het belangrijke onderscheid
tussen de naam van een object en het object waar daadwerkelijk aan
gerefereerd wordt. 

@menu
* insert-buffer code::       insert-buffer code
* insert-buffer interactief::  Wanneer je kan lezen maar niet schrijven.
* insert-buffer body::       The body heeft een @code{or} en een @code{let}.
* if en or::                 Gebruik een @code{if} in plaats van een 
                               @code{or}.
* Voeg or in::               Hoe de @code{or} expressie werkt.
* Voeg let in::              Twee @code{save-excursion} expressies.
* Nieuwe insert-buffer::     Nieuwe insert-buffer
@end menu

@ifnottex
@node insert-buffer code
@unnumberedsubsec De code voor @code{insert-buffer}
@end ifnottex

@need 800
Hier is de eerdere code:

@smallexample
@group
(defun insert-buffer (buffer)
  "Insert after point the contents of BUFFER.
Puts mark after the inserted text.
BUFFER may be a buffer or a buffer name."
  (interactive "*bInsert buffer:@: ")
@end group
@group
  (or (bufferp buffer)
      (setq buffer (get-buffer buffer)))
  (let (start end newmark)
    (save-excursion
      (save-excursion
        (set-buffer buffer)
        (setq start (point-min) end (point-max)))
@end group
@group
      (insert-buffer-substring buffer start end)
      (setq newmark (point)))
    (push-mark newmark)))
@end group
@end smallexample

@need 1200
Net als met andere functiedefinities kun je een sjabloon gebruiken voor een
overzicht van de functie.

@smallexample
@group
(defun insert-buffer (buffer)
  "@var{documentatie}@dots{}"
  (interactive "*bInsert buffer:@: ")
  @var{body}@dots{})
@end group
@end smallexample

@node insert-buffer interactief
@subsection De interactieve expressie in @code{insert-buffer}
@findex interactive@r{, voorbeeld gebruik van}

In @code{insert-buffer} heeft het argument van de @code{interactive}
declaratie twee onderdelen, een sterretje, @samp{*} en @samp{bInsert
buffer:@: }.

@menu
* Read-only buffer::         Wanneer een buffer niet gewijzigd kan worden.
* b for interactief::        Een bestaand buffer of anders zijn naam.
@end menu

@node Read-only buffer
@unnumberedsubsubsec Een read-only buffer
@cindex Read-only buffer
@cindex Sterretje voor een read-only buffer
@findex * @r{voor read-only buffer}

Het sterretje is voor de situatie dat het huidige buffer een read-only
buffer is---een buffer dat niet kan worden gewijzigd. Wanneer
@code{insert-buffer} wordt aangeroepen terwijl het huidige buffer read-only
is, wordt een boodschap hiervan in het echogebied getoond en de terminal can
piepen of knipperen, het is niet toegestaan iets in het huidige buffer in te
voegen. Het sterretje hoeft niet opgevolgd te worden met een nieuwe regel om
het van het volgende argument te scheiden.

@node b for interactief
@unnumberedsubsubsec @samp{b} in een interactive expressie

Het volgende argument in de interactive-expressie begint met een kleine
letter @samp{b}. (Dit is verschillend met de code voor
@code{append-to-buffer}, die gebruikt een hoofdletter @samp{B}.) De kleine
letter @samp{b} vertelt de Lisp interpreter dat het argument voor
@code{insert-buffer} een bestaand buffer moet zijn, of de naam daarvan. (De
optie hoofdletter @samp{B} is voor de mogelijkheid dat het buffer nog niet
bestaat.) Emacs vraagt je naar de naam van het buffer en biedt een standaard
buffer aan met completie voor de naam ingeschakeld. Wanneer het buffer niet
bestaat, krijg je een boodschap ``No match'', en de terminal kan daarbij ook
piepen.

De nieuwe en vereenvoudigde code genereert een lijst voor
@code{interactive}. Het gebruikt de functies @code{barf-if-buffer-read-only}
en @code{read-buffer}, waar we al vertrouwd mee zijn en de speciale vorm
@code{progn} waarmee we dat nog niet zijn. (Die wordt later beschreven.)

@node insert-buffer body
@subsection De body van de @code{insert-buffer} functie

De body van de functie @code{insert-buffer} heeft twee belangrijke delen:
een @code{or} expressie en een @code{let} expressie. Het doel van de
@code{or} is zeker te stellen dat het argument van @code{buffer} gebonden is
aan een buffer niet slechts aan de naam van een buffer. De body van de
@code{let} expressie bevat de code die het andere buffer in het huidige
kopieert.

@need 1250
Globaal passen de twee expressies als volgt in de functie
@code{insert-buffer}: 

@smallexample
@group
(defun insert-buffer (buffer)
  "@var{documentatie}@dots{}"
  (interactive "*bInsert buffer:@: ")
  (or @dots{}
      @dots{}
@end group
@group
  (let (@var{varlist})
      @var{body-of-}@code{let}@dots{} )
@end group
@end smallexample

Om te begrijpen hoe de @code{or} zeker stelt dat het argument van
@code{buffer} gebonden is aan een buffer en niet aan de naam van een buffer,
is het eerst nodig de functie @code{or} te begrijpen.

Laat mij eerst, voor dat we dat doen, dit deel van de functie met @code{if}
herschrijven, zodat je kunt zien wat er gebeurt op een manier die vertrouwd
is.

@node if en or
@subsection @code{insert-buffer} met een @code{if} in plaats van een @code{or}

De taak die gedaan moet worden is zorgen dat de waarde van @code{buffer}
echt een buffer en niet de naam van een buffer. Wanneer de waarde de naam
is, dan moet het buffer zelf worden verkregen.

Stel je voor dat je op een conferentie bent en de ceremoniemeester loopt
rond met een lijst waar je naam op staat en je zoekt: de ceremoniemeester is
gebonden aan je naam, niet aan jou, maar wanneer die je vindt en je bij je
arm neemt, raakt de ceremoniemeester gebonden aan jou.

@need 800
In Lisp kan je deze situatie als volgt beschrijven:

@smallexample
@group
(if (not (gast-vasthouden))
    (vind-en-neem-gast-bij-de arm))
@end group
@end smallexample

Wij willen hetzelfde doen met een buffer---wanneer we niet het buffer zelf
hebben, willen we het krijgen.

@need 1200
Met een predicate met de naam @code{bufferp} die ons vertelt of we een
buffer (in plaats van een naam hebben) schrijven we de code als volgt:

@smallexample
@group
(if (not (bufferp buffer))              ; @r{if-deel}
    (setq buffer (get-buffer buffer)))  ; @r{dan-deel}
@end group
@end smallexample

@noindent
De waar-of-onwaar-test van de @code{if} expresse is hier @w{@code{(not
(bufferp buffer))}} en het dan-deel is de expressie @w{@code{(setq buffer
(get-buffer buffer))}}.

In de test geeft de functie @code{bufferp} waar terug wanneer het argument
een buffer is---maar onwaar wanneer het argument de naam van een buffer
is. (Het laatste karakter van de functienaam @code{bufferp} is het karakter
@samp{p}, zoals we eerder zagen is het gebruik van @samp{p} een conventie
die aangeeft dat de functie een predicate is, wat een term is die betekent
dat de vaststelt of een bepaalde eigenschap waar of onwaar
is. @xref{Verkeerde type argument, , Het verkeerde object type als argument
gebruiken}.)

@need 1200
De functie @code{not} gaat vooraf aan de expressie @code{(bufferp buffer)},
waardoor de waar-of-onwaar-test er zo uitziet:

@smallexample
(not (bufferp buffer))
@end smallexample

@noindent
@code{not} is een functie die waar teruggeeft wanneer zijn argument onwaar
is en onwaar als zijn argument waar is. Dus wanneer @code{(bufferp buffer)}
waar teruggeeft, geeft de @code{not} onwaar terug, en omgekeerd.

Met deze test werkt de @code{if} expressie als volgt: wanneer de waarde van
de variabele @code{buffer} inderdaad een buffer is in plaats van zijn naam,
geeft de waar-of-onwaar-test onwaar terug en evalueert de @code{if}
expressie het dan-deel niet. Dat is prima, omdat we niets hoeven te doen met
de variabele @code{buffer} wanneer die werkelijk een buffer is.

Aan de andere kant, wanneer de waarde van @code{buffer} geen buffer is, maar
de naam van een buffer, geeft de waar-of-onwaar-test waar terug en wordt het
dan-deel geëvalueerd. In dit geval is het dan-deel @code{(setq buffer
(get-buffer buffer))}. Deze expressie gebruikt de functie @code{get-buffer}
om op basis van de naam het buffer zelf terug te geven. De @code{setq} stelt
vervolgens de variabele @code{buffer} in op de waarde van het buffer zelf en
vervangt zo de waarde (die de naam van het buffer was).

@node Voeg or in
@subsection De @code{or} in de body

Het doel van de e @code{or} expressie in de functie @code{insert-buffer} is
zeker te stellen dat het argument van @code{buffer} gebonden is aan een
buffer niet slechts de naam van een buffer. De vorige sectie liet zien hoe
deze taak met een @code{if} expressie gedaan kan worden. Echter, de functie
@code{insert-buffer} gebruikt @code{or}. Om dit te begrijpen, is het nodig
te begrijpen hoe @code{or} werkt.

@findex or
Een @code{or} functie kan allerlei argumenten hebben. Het evalueert elk
argument op zijn beurt en geeft de waarde van het eerste van de argumenten
dat niet @code{nil} is. Dus, en dit is een cruciale eigenschap van
@code{or}, evalueert het geen verdere argumenten na het teruggeven van de
eerste non-@code{nil} waarde.

@need 800
De @code{or} expressie ziet er zo uit:

@smallexample
@group
(or (bufferp buffer)
    (setq buffer (get-buffer buffer)))
@end group
@end smallexample

@noindent
Het eerste argument voor @code{or} is de expressie @code{(bufferp
buffer)}. Deze expressie geeft waar terug (een non-@code{nil} waarde)
wanneer het buffer inderdaad een buffer is en niet slechts de naam van een
buffer. De @code{or} expressie, wanneer dit het geval is, geeft deze waar
waarde terug en evalueert de volgende expressie niet---en dat is prima voor
on, omdat we niets anders willen dan de waarde van @code{buffer} wanneer die
echt een buffer is.

Anderzijds, als de waarde van @code{(bufferp buffer)} @code{nil} is, wat het
is wanneer de waarde van @code{buffer} de naam van buffer is, evalueert de
Lisp interpreter het volgende element van de @code{or} expressie. Dit is de
expressie @code{(setq buffer (get-buffer buffer))}. Deze expressie geeft een
non-@code{nil} waarde terug, wat de waarde is waarop het de variabele
@code{buffer} instelt---en deze waarde is het buffer zelf, niet de naam.

Het resultaat van dit alles is dat het symbool @code{buffer} altijd gebonden
is aan een buffer in plaats van aan de naam van een buffer. Dit is allemaal
noodzakelijk omdat de functie @code{set-buffer} op een volgende regel alleen
werkt met een buffer, niet met de naam van een buffer.

@need 1250
Overigens, met @code{or} is de situatie met de ceremoniemeester als volgt:

@smallexample
(or (heeft-arm-van-gast) (vind-en-neem-de-arm-van-de-gast))
@end smallexample

@node Voeg let in
@subsection De @code{let} expresse in @code{insert-buffer}

Na zeker stelling dat de variabele @code{buffer} naar een buffer en niet
slechts naar de naam van een buffer refereert, gaat de functie
@code{insert-buffer} verder met de @code{let} expressie. Deze specificeert
drie lokale variabelen, @code{start}, @code{end} en @code{newmark} en bindt
ze aan de initiele waarde @code{nil}. Deze variabelen worden binnen de rest
van de @code{let} gebruikt en verbergen tijdelijk elke andere variabele met
eenzelfde naam in Emacs tot het einde van de @code{let}. 

@need 1200
De body van de @code{let} bevat twee @code{save-excursion} expressies. Eerst
kijken we in detail naar de binnenste @code{save-excursion} expressie. De
expressie ziet er zo uit:

@smallexample
@group
(save-excursion
  (set-buffer buffer)
  (setq start (point-min) end (point-max)))
@end group
@end smallexample

@noindent
De expressie @code{(set-buffer buffer)} schakelt de aandacht van Emacs van
het huidige buffer naar een waarvan de tekst gekopieerd zal worden. In dat
buffer zijn met het gebruik van de commando's @code{point-min} en
@code{point-max} de variabelen @code{start} en @code{end} ingesteld op het
begin en het eind van het buffer. Merk op dat hier zien hoe @code{setq} twee
variabelen in een enkele expressie kan instellen. Het eerste argument van
@code{setq} is ingesteld op de waarde van de tweede, en het derde argument
op de waarde van de vierde.

Nadat de body van de binnenste @code{save-excursion} is geëvalueerd herstelt
@code{save-excursion} het oorspronkelijke buffer, maar @code{start} en
@code{eind} blijven ingesteld op de waarden van het begin en eind van het
buffer van waar de tekst gekopieerd wordt.

@need 1250
De buitenste @code{save-excursion} expressie ziet er zo uit:

@smallexample
@group
(save-excursion
  (@var{binnenste-}@code{save-excursion}@var{-expressie}
     (@var{ga-naar-nieuw-buffer-en-zet-}@code{start}@var{-en-}@code{end})
  (insert-buffer-substring buffer start end)
  (setq newmark (point)))
@end group
@end smallexample

@noindent
De functie @code{insert-buffer-substring} kopieert de tekst @emph{in} het
huidige buffer @emph{van} de region aangeduid met @code{start} en
@code{eind} in @code{buffer}. Omdat het geheel van het tweede buffer tussen
@code{start} en @code{eind} ligt, wordt het geheel van het tweede buffer
gekopieerd naar het buffer dat je aan het editen bent. Vervolgens wordt de
waarde van point, die aan het eind van de ingevoegde tekst is, vastgelegd in
de variabele @code{newmark}.

Nadat de body van de buitenste @code{save-excursion} is geëvalueerd, wordt
point naar zijn oorspronkelijke plek teruggeplaatst.

Het is echter handig om de mark aan het eind van de nieuw ingevoegde tekst
te plaatsen en point aan het begin. De variabele @code{newmark} registreert
het eind van de ingevoegde tekst. In de laatste regel van de @code{let}
expressie zet de @code{(push-mark newmark)} expressie op deze lokatie. (De
vorige plek van de mark is nog steeds bereikbaar: het is opgeslagen in de
mark-ring en je kunt teruggaan met @kbd{C-u C-@key{SPC}}.) Ondertussen staat
point aan het begin van de ingevoegde tekst, waar deze was voordat je de
insert-functie aanriep, die plek was bewaarde met de eerste
@code{save-excursion}.

@need 1250
De hele @code{let} ziet er zo uit:

@smallexample
@group
(let (start end newmark)
  (save-excursion
    (save-excursion
      (set-buffer buffer)
      (setq start (point-min) end (point-max)))
    (insert-buffer-substring buffer start end)
    (setq newmark (point)))
  (push-mark newmark))
@end group
@end smallexample

De functie @code{insert-buffer} gebruikt, net als de functie
@code{append-to-buffer}, @code{let}, @code{save-excursion} en
@code{set-buffer}. Daarnaast illustreert de functie een manier om @code{or}
te gebruiken. Al deze functies zijn bouwblokken die we keer op keer zullen
gebruiken.

@node Nieuwe insert-buffer
@subsection Nieuwe body voor @code{insert-buffer}
@findex insert-buffer@r{, nieuwe versie body}
@cindex nieuwe versie body voor @code{insert-buffer}

De body in de GNU Emacs 22 versie is meer verwarrend dan het orgineel.

@need 1250
Het bestaat uit twee expressies

@smallexample
@group
  (push-mark
   (save-excursion
     (insert-buffer-substring (get-buffer buffer))
     (point)))

   nil
@end group
@end smallexample

@noindent
behalve, en dit is wat veel beginners in de war brengt, wordt veel werk
verricht in de @code{push-mark} expressie.

De functie @code{get-buffer} geeft een buffer met de opgegeven naam
terug. Merk op dat de functie @emph{niet} @code{get-buffer-create} heet, het
maakt geen buffer wanneer er geen bestaat. De buffer die @code{get-buffer}
teruggeeft, een bestaand buffer, wordt doorgegeven aan
@code{insert-buffer-substring}, de het gehele buffer invoegt (omdat je niets
anders opgaf).

De plek waar het buffer is ingevoegd is vastgelegd door
@code{push-mark}. Daarna geeft de functie @code{nil} terug, de waarde van
het laatste commando. Anders gezegd, de functie @code{insert-buffer} bestaat
alleen om een zij-effect te produceren, invoegen in een ander buffer en niet
om enige waarde terug te geven.

@node beginning-of-buffer
@section Complete definitie van @code{beginning-of-buffer}
@findex beginning-of-buffer

De basisstructuur van de functie @code{beginning-of-buffer} hebben we eerder
besproken. (@xref{versimpelde-beginning-of-buffer, , Een versimpelde
@code{beginning-of-buffer} definitie}.) Deze sectie beschrijft het complexe
deel van de definitie.

Wanneer @code{beginning-of-buffer} zonder argument wordt aangeroepen plaatst
het, zoals eerder beschreven, de cursor naar het begin van het buffer
(eerlijk gezegd, het begin van het bereikbare deel van het buffer), en laat
de mark op de voorgaande positie. Echter, wanneer het commando wordt
aangeroepen met een getal tussen één en tien, dan beschouwt de functie dat
getal als een fractie van de lengte van het buffer, gemeten in tienden, en
verplaatst Emacs de cursor die fractie vanaf het begin van het buffer. Dus
je kunt de functie aanroepen met het commando @kbd{M-<}, wat de cursor naar
het begin van het buffer verplaatst, of met een toets commando zoals
@kbd{C-u 7 M-<} wat de cursor op een punt 70% in het buffer plaatst. Bij
gebruik van een getal groter dan tien als argument gaat het naar het einde
van het buffer.

De functie @code{beginning-of-buffer} kan met of zonder argument worden
aangeroepen. Het gebruik van een argument is optioneel.

@menu
* Optionele argumenten::     Optionele argumenten
* beginning-of-buffer opt arg::  Voorbeeld met optioneel argument.
* beginning-of-buffer compleet::  beginning-of-buffer compleet
@end menu

@node Optionele argumenten
@subsection Optionele argumenten

Tenzij anders verteld verwacht Lisp dat een functie met een argument in zijn
functiedefinitie wordt aangeroepen met een waarde voor dat argument. Wanneer
dat niet gebeurt, dan krijg je een fout en de boodschap @samp{Wrong number
of arguments}.

@cindex Optionele argumenten
@cindex Sleutelwoord
@findex optionall
Optionele argumenten zijn echter een eigenschap van Lisp: een specifiek
@dfn{sleutelwoord} wordt gebruikt om aan de Lisp interpreter te vertellen
dat een argument optioneel is. Het sleutelwoord is @code{&optional}. (De
@samp{&} aan de voorkant van @samp{optional} is onderdeel van het
sleutelwoord.) Wanneer een argument in een functiedefinitie volgt op het
sleutelwoord @code{&optional} dan behoeft geen waarde aan het argument te
worden doorgegeven bij het aanroepen van de functie.

@need 1200
De eerste regel van de functiedefinitie van @code{beginning-of-buffer} ziet
er daardoor als volgt uit:

@smallexample
(defun beginning-of-buffer (&optional arg)
@end smallexample

@need 1250
Globaal ziet de hele functie er zo uit:

@smallexample
@group
(defun beginning-of-buffer (&optional arg)
  "@var{documentatie}@dots{}"
  (interactive "P")
  (or (@var{is-het-argument-een-cons-cel} arg)
      (and @var{zijn-zowel-transient-mark-mode-als-mark-active-waar})
      (push-mark))
  (let (@var{stel-grootte-vast-en-stel-in})
    (goto-char
      (@var{als-er-een-argument-is}
          @var{zoek-uit-waar-heen-te-gaan}
        @var{anders-ga-naar}
        (point-min))))
  @var{wees-beleefd}
@end group
@end smallexample

De functie is vergelijkbaar met de @code{versimpelde-beginning-of-buffer}
functie, behalve dat de @code{interactive} expressie als argument @code{"P"}
heeft en de functie @code{goto-char} gevolgd wordt door een if-then-else
expressie die uitzoekt waar de cursor geplaatst moet worden wanneer er een
argument is dat geen cons-cel is.

(Omdat ik een cons-cel pas een aantal hoofdstukken verderop uitleg, negeer
alsjeblieft de functie @code{consp}. @xref{Implementatie van lijsten, , Hoe
lijsten zijn geïmplementeerd} en @ref{Cons Cell Type, , Cons Cell and List
Types, elisp, The GNU Emacs Lisp Reference Manual}.)

De @code{"P"} in de @code{interactive} expressie vertelt Emacs om een
prefix-argument, wanneer die er is, ongewijzigd aan de functie door te
geven. Een prefix-argument maak je het typen van de @key{META}-toets,
gevolgd door een getal, of door @kbd{C-u} te typen en dan een getal. (Als je
geen getal typt, dan leidt @kbd{C-u} standaard naar een cons-cel met een
4). De kleine letter @code{"p"} in de @code{interactive} expressie laat de
functie de prefix naar een getal converteren.

De waar-of-onwaar-test in de @code{if}-expressie ziet er gecompliceerd uit,
maar is het niet: het controleert of @code{arg} een waarde heeft doe niet
@code{nil} is en of het wel of niet een cons-cel is. (Dat is wat
@code{consp} doet, het controleert of zijn argument een cons-cel is.)
Wanneer @code{arg} een waarde heeft die ongelijk aan @code{nil} is (en ook
geen cons-cel is), wat het geval is wanneer @code{beginning-of-buffer} wordt
aangeroepen met een numeriek argument, dan geeft deze waar-of-onwaar-test
waar terug en wordt het dan-deel van de @code{if}-expressie
geëvalueerd. Anderzijds, wanneer @code{beginning-of-buffer} niet met een
argument is aangeroepen, heeft @code{arg} de waarde @code{nil} en wordt het
anders-deel van de @code{if}-expressie geëvalueerd. Dit anders-deel is
eenvoudigweg @code{point-min}, en wanneer dit de uitkomst is, dan is de
gehele @code{goto-char}-expressie @code{(goto-char (point-min))}, wat
overeenkomt met hoe we de functie @code{beginning-of-buffer} zagen in de
vereenvoudigde vorm.

@node beginning-of-buffer opt arg
@subsection @code{beginning-of-buffer} met een argument

Wanneer @code{beginning-of-buffer} wordt aangeroepen met een argument, dan
wordt een expressie geëvalueerd die de waarde berekent om aan
@code{goto-char} door te geven. Deze expressie is op het eerste gezicht
nogal complex. Het bevat een binnenliggende @code{if} en flink wat
rekenkunde. Het ziet er zo uit:

@smallexample
@group
(if (> (buffer-size) 10000)
    ;; @r{Avoid overflow for large buffer sizes!}
    (* (prefix-numeric-value arg)
       (/ size 10))
  (/
   (+ 10
      (* size
         (prefix-numeric-value arg)))
   10))
@end group
@end smallexample

@menu
* Ontrafelen beginning-of-buffer::  Ontrafelen beginning-of-buffer
* In geval van een groot buffer::  In geval van een groot buffer
* In geval van een klein buffer::  In geval van een klein buffer
@end menu

@ifnottex
@node Ontrafelen beginning-of-buffer
@unnumberedsubsubsec Ontrafelen @code{beginning-of-buffer}
@end ifnottex

Net als andere expressies die er complex uitzien, kan de conditionele
expressie in @code{beginning-of-buffer} worden ontrafeld door het te
bekijken als delen van een sjabloon, in dit geval het sjabloon voor een
if-then-else-expressie. Globaal ziet de expressie er zo uit:

@smallexample
@group
(if (@var{buffer-is-groot}
    @var{deel-buffer-grootte-door-10-en-vermenigvuldig-met-arg}
  @var{anders-gebruik-alternatieve-berekening}
@end group
@end smallexample

De waar-of-onwaar-test van de binnenliggende @code{if}-expressie controleert
de grootte van het buffer. De reden hiervoor is, is dat de oude versie 18
van Emacs met getallen werkte die niet hoger kunnen zijn dan ongeveer acht
miljoen en in de berekening die volgt, de programmeur bang was dat Emacs zou
proberen te grootte getallen te gebruiken wanneer de buffers groot zijn. De
term ``overflow'' die in het commentaar genoemd wordt betekent dat getallen
te groot zijn. Meer recente versies van Emacs gebruiken grotere getallen,
maar de code is niet gewijzigd, al is het alleen maar omdat mensen nu met
buffers werken die vele malen groter zijn dan ooit.

Er zijn twee gevallen: wanneer de buffer groot is, en wanneer niet.

@node In geval van een groot buffer
@unnumberedsubsubsec Wat in een groot buffer gebeurt

In In @code{beginning-of-buffer} test de binnenliggende @code{if}-expressie
of de grootte van het buffer groter is dan 10.000 karakters. Om dit te doen
gebruikt het de functie @code{>} en de berekening van @code{size} die van de
let-expressie komt.

Oorspronkelijk werd de functie @code{buffer-size} gebruikt. Niet alleen werd
die functie meerdere keren aangeroepen, het gaf de grootte van het gehele
buffer, niet het bereikbare deel. De berekening is veel logischer wanneer
het alleen het bereikbare deel gebruikt. (@xref{Versmallen en verbreden, ,
Versmallen en verbreden}, voor meer informatie over het richten van de
aandacht op een bereikbaar deel.)

@need 800
De regel ziet er zo uit:

@smallexample
(if (> size 10000)
@end smallexample

@need 1200
@noindent
Wanneer het buffer groot is, dan wordt het dan-deel van de
@code{if}-expressie geëvalueerd. Dit staat er (na het formatteren voor
makkelijk lezen):

@smallexample
@group
(*
  (prefix-numeric-value arg)
  (/ size 10))
@end group
@end smallexample

@noindent
Deze expressie is een vermenigvuldiging met twee argumenten voor de functie
@code{*}.

Het eerste argument is @code{(prefix-numeric-value arg)}. Wanneer @code{"P"}
wordt gebruik als argument voor @code{interactive}, is de waarde die als
argument wordt doorgegeven een @dfn{ongewijzigd prefix-argument}, en niet
een getal. (Het is een getal in een list.) Om de berekening uit te voeren is
een conversie nodig, en @code{prefix-numeric-value} doet dat.

@findex / @r{(deling)}
@cindex Deling
Het tweede argument is @code{(/ size 10)}. Deze expressie deelt het getal
door tien---de numerieke waarde van de grootte van het bereikbare deel van
de buffer. Dit produceert een getal dat vertelt hoeveel karakters een tiende
van de buffergrootte vormen. (In Lisp wordt @code{/} gebruikt voor deling,
net als @code{*} wordt gebruikt voor vermenigvuldiging.)

@need 1200
In de complete vermenigvuldiging expressie wordt dit getal vermenigvuldigd
met de waarde van het prefix-argument---de vermenigvuldiging ziet er zo uit:

@smallexample
@group
(* @var{numerieke-waarde-van-het-prefix-arg}
   @var{aantal karakters-in-een-tiende-van-het-bereikbare-buffer})
@end group
@end smallexample

@noindent
Als bijvoorbeeld het prefix-argument @samp{7} is, wordt de een-tiende waarde
vermenigvuldigd met 7, om op een positie van 70% uit te komen.

@need 1200
Het resultaat van dit alles is dat wanneer het bereikbare deel van het
buffer groot is, de @code{goto-char} als volgt is:

@smallexample
@group
(goto-char (* (prefix-numeric-value arg)
              (/ size 10)))
@end group
@end smallexample

Dit plaatst de cursor waar wij die willen hebben.

@node In geval van een klein buffer
@unnumberedsubsubsec Wat in een klein buffer gebeurt

Wanneer het buffer minder dan 10.000 karakters bevat wordt een iets andere
berekening uitgevoerd. Je zou kunnen denken dat dit niet nodig is, omdat de
eerste berekening dat zou kunnen doen. Maar in een klein buffer zou de
eerste methode de cursor niet precies op de gewenste regel kunnen
plaatsen. De tweede methode doet dat beter.

@need 800
De code ziet er zo uit:

@c Keep this on one line.
@smallexample
(/ (+ 10 (* size (prefix-numeric-value arg))) 10)
@end smallexample

@need 1200
@noindent
Dit is de code waarin je uitzoekt wat er gebeurt door te ontdekken hoe de
functies tussen de haakjes zijn ingebed. Het wordt makkelijker te lezen
wanneer je het zo formatteert dat elke expressie dieper inspringt dan zijn
omsluitende expressie:

@smallexample
@group
  (/
   (+ 10
      (*
       size
       (prefix-numeric-value arg)))
   10)
@end group
@end smallexample

@need 1200
@noindent
Naar de haakjes kijkend zien we dat de meest binnenste bewerking
@code{(prefix-numeric-value arg)} is, die het ongewijzigde argument naar een
getal converteert. In de volgende expressie wordt dit getal vermenigvuldigd
met de grootte van het bereikbare deel van het buffer:

@smallexample
(* size (prefix-numeric-value arg))
@end smallexample

@noindent
Deze vermenigvuldiging creëert een getal dat groter zou kunnen zijn dan de
grootte van het buffer---zeven keer groter als het argument 7 is,
bijvoorbeeld. Hierna wordt tien bij dit getal opgeteld en uiteindelijk wordt
het grote getal gedeeld door tien om een waarde te geven die één karakter
groter is dan de procentuele positie in het buffer.

Het getal dat de uitkomst is van dit alles wordt doorgegeven aan
@code{goto-char} en de cursor wordt naar dat punt verplaatst.

@need 1500
@node beginning-of-buffer compleet
@subsection De complete @code{beginning-of-buffer}

@need 1000
Hiet is de complete tekst van de functie @code{beginning-of-buffer}:
@sp 1

@c In GNU Emacs 22
@smallexample
@group
(defun beginning-of-buffer (&optional arg)
  "Move point to the beginning of the buffer;
leave mark at previous position.
With \\[universal-argument] prefix,
do not set mark at previous position.
With numeric arg N,
put point N/10 of the way from the beginning.

If the buffer is narrowed,
this command uses the beginning and size
of the accessible part of the buffer.
@end group

@group
Don't use this command in Lisp programs!
\(goto-char (point-min)) is faster
and avoids clobbering the mark."
  (interactive "P")
  (or (consp arg)
      (and transient-mark-mode mark-active)
      (push-mark))
@end group
@group
  (let ((size (- (point-max) (point-min))))
    (goto-char (if (and arg (not (consp arg)))
                   (+ (point-min)
                      (if (> size 10000)
                          ;; Avoid overflow for large buffer sizes!
                          (* (prefix-numeric-value arg)
                             (/ size 10))
                        (/ (+ 10 (* size (prefix-numeric-value arg)))
                           10)))
                 (point-min))))
  (if (and arg (not (consp arg))) (forward-line 1)))
@end group
@end smallexample

@ignore
From before GNU Emacs 22
@smallexample
@group
(defun beginning-of-buffer (&optional arg)
  "Move point to the beginning of the buffer;
leave mark at previous position.
With arg N, put point N/10 of the way
from the true beginning.
@end group
@group
Don't use this in Lisp programs!
\(goto-char (point-min)) is faster
and does not set the mark."
  (interactive "P")
  (push-mark)
@end group
@group
  (goto-char
   (if arg
       (if (> (buffer-size) 10000)
           ;; @r{Avoid overflow for large buffer sizes!}
           (* (prefix-numeric-value arg)
              (/ (buffer-size) 10))
@end group
@group
         (/ (+ 10 (* (buffer-size)
                     (prefix-numeric-value arg)))
            10))
     (point-min)))
  (if arg (forward-line 1)))
@end group
@end smallexample
@end ignore

@noindent
Afgezien van twee kleine punten toont de voorgaande bespreking hoe deze
functie werkt. Het eerste punt betreft een detail in de documentatiestring
en het tweede punt betreft de laatste regel van de functie.

@need 800
In de documentatiestring is een referencie naar een expressie:

@smallexample
\\[universal-argument]
@end smallexample

@noindent
Een @samp{\\} wordt gebruikt voor de eerste vierkante haak in deze
expressie. Deze @samp{\\} vertelt de Lisp interpreter de toets te vervangen
door wat dan ook thans gebonden is aan de @samp{[@dots{}]}. In het geval van
het universele argument, die meestal gebonden is aan @kbd{C-u}, maar dit kan
anders zijn (@xref{Documentation Tips, , Tips for Documentation Strings,
elisp, The GNU Emacs Lisp Reference Manual}, for more information.)

@need 1200
Tenslotte zegt de laatste regel van het @code{beginning-of-buffer} commando
de point te verplaatsten naar het begin van de volgende regel wanneer het
commando met een argument is aangeroepen:

@smallexample
(if (and arg (not (consp arg))) (forward-line 1))
@end smallexample

@noindent
Dit plaatst de cursor aan het begin van de eerste regel na de juiste tiende
deel positie in het buffer. Deze elegantie zorgt dat de cursor altijd
@emph{tenminste} het aantal gewenste tienden in het buffer is geplaatst, wat
een misschien onnodige verfraaiing is, die, als dat niet zou gebeuren
ongetwijfeld tot klachten zou leiden. (Het @code{(not (consp arg))} deel is
zo dat wanneer je het commando met @kbd{C-u} maar zonder getal aanroept, wat
inhoudt dat het prefix-argument eenvoudig een cons-cel is, het commando je
niet aan het begin van de tweede regel plaatst.)

@node Tweede buffer gerelateerde terugblik
@section Terugblik

Hier is een korte samenvatting van enkele van de onderwerpen in dit
hoofdstuk.

@table @code
@item or
Evalueer elk argument op volgorde, en geef de waarde van het eerste argument
dat niet @code{nil} is. Wanneer niet een van hen een waarde ongelijk aan
@code{nil} teruggeeft, geef dan @code{nil} terug. In het kort, geef de
eerste waarde van de argumenten die waar is terug, geef een waarde waar
terug wanneer een @emph{of} meer van de andere waar zijn.

@item and
Evalueer elk argument op volgorde, en als er een @code{nil} is, geef dan
@code{nil} terug. Als niet een van hen @code{nil} is, geef dan de waarde van
het laatste argument terug. In het kort, geef een waarde waar terug
uitsluitend wanneer alle argumenten waar zijn, geef een waarde waar terug
wanneer een @emph{en} alle andere waar zijn.

@item &optional
Een sleutelwoord dat aangeeft dat een argument van een functiedefinitie
optioneel is, dit betekent dat de functie desgewenst zonder dit argument kan
worden geëvalueerd,

@item prefix-numeric-value
Converteer het ongewijzigde prefix-numeric-value geproduceerd door
@code{(interactive "P")} naar een numerieke waarde.

@item forward-line
Verplaats point voorwaarts naar het begin van de volgende regel, of wanneer
het argument groter is dan één, dat aantal regels voorwaarts. Wanneer het
niet zo ver voorwaarts kan als het bedoeld is, gaat @code{forward-line} zo
ver mogelijk voorwaarts en geeft vervolgens het aantal terug van de extra
regels die het bedoeld was te verplaatsen maar dat niet kon.

@item erase-buffer
Verwijder de gehele inhoud van het huidige buffer.

@item bufferp
Geef @code{t} terug wanneer het argument een buffer is, zo niet geef
@code{nil} terug.
@end table

@node optionele oefening
@section @code{optioneel} argument oefening

Schrijf een interactieve functie met een optioneel argument dat test of het
argument, een getal, groter of gelijk is aan, dan wel kleiner is dan de
waarde van @code{fill-column}, en je in een boodschap vertelt welke het
geval is. Wanneer je echter geen argument aan de functie doorgeeft, gebruik
dan 56 als standaard waarde.

@node Versmallen en verbreden
@chapter Versmallen en verbreden
@cindex Aandacht richten (versmallen)
@cindex Versmallen
@cindex Verbreden

Versmallen is een eigenschap van Emacs die het mogelijk maakt je aandacht te
richten op een specifiek deel van een buffer, en te werken zonder dat je per
ongeluk iets in de andere delen wijzigt. Versmallen is normaal gesproken
uitgeschakeld omdat het verwarrend is voor beginners.

@menu
* Voordelen van versmallen::  De voordelen van versmallen
* save-restriction::         De @code{save-restriction} speciale vorm.
* what-line::                Het regelnummer waarop de point is.
* versmal oefening::         versmal oefening
@end menu

@ifnottex
@node Voordelen van versmallen
@unnumberedsec De voordelen van versmallen
@end ifnottex

Met versmallen is de rest van het buffer onzichtbaar, alsof het er niet
is. Dit is een voordeel wanneer je bijvoorbeeld een woord in een deel van
het buffer wilt vervangen, maar niet in een ander deel: je versmalt naar het
deel dat je wilt en de vervanging wordt alleen in dat deel uitgevoerd en
niet in de rest van het buffer. Zoeken werkt ook binnen een versmald gebied,
niet daarbuiten, zodat als je een deel van een document aan het verbeteren
bent, je jezelf beschermt tegen per ongeluk vinden van delen die je niet
wilt verbeteren door te versmallen naar precies dat gebied dat je wilt. (De
toetscombinatie voor @code{narrow-to-region} is @kbd{C-x n n}.)

Versmallen maakt echter de rest van het buffer onzichtbaar, wat mensen bang
kan maken die onbedoeld versmalling aanroepen en denken dat ze een deel van
het buffer verwijderd hebben. Verder zet het @code{undo} commando (wat
normaal gebonden is aan @kbd{C-x u}) het versmallen niet uit (en moet dat
ook niet doen), wat mensen wanhopig kan maken wanneer zij niet weten dat ze
de zichtbaarheid van de rest van het buffer kunnen herstellen met het
@code{widen} commando. (De toetscombinatie voor @code{widen} is @kbd{C-x n
w}.)

Versmallen is net zo zinvol voor de Lisp interpreter als voor mensen. Vaak
is een Emacs Lisp functie ontworpen om op slechts een deel van een buffer te
werken, of omgekeerd, een Emacs Lisp functie moet werken op het gehele
buffer dat is versmald. De functie @code{what-line} bijvoorbeeld, haalt de
versmalling van een buffer als die versmald is en wanneer het zijn taak
gedaan heeft, herstelt de versmalling naar wat het was. Anderzijds gebruikt
de functie @code{count-lines} versmalling om zichzelf te beperken tot dat
deel van het buffer waarin het geïnteresseerd is en herstelt daarna de
vorige situatie.

@node save-restriction
@section De speciale vorm @code{save-restriction}
@findex save-restriction

In Emacs Lisp gebruik je de speciale vorm @code{save-restriction} om bij te
houden welke versmalling van toepassing is. Wanneer de Lisp interpreter
@code{save-restriction} tegenkomt, voert het de code in de body van de
@code{save-restriction} expressie uit en maakt de eventuele wijzigingen die
het in de versmalling heeft aangebracht ongedaan. Wanneer bijvoorbeeld het
buffer versmald is en de code die volgt op @code{save-restriction} de
versmalling weghaalt, herstelt @code{save-restriction} na afloop het buffer
naar zijn versmalde region. In het @code{what-line} commando wordt de
versmalling die het buffer mogelijk heeft ongedaan gemaakt met het
@code{widen} commando, dat onmiddellijk volgt op het
@code{save-restriction}. De eventuele oorspronkelijke versmalling wordt
hersteld vlak voor het beëindigen van de functie.

@need 1250
Het sjabloon voor een @code{save-restriction} expressie is eenvoudig:

@smallexample
@group
(save-restriction
  @var{body}@dots{} )
@end group
@end smallexample

@noindent
De body van de @code{save-restriction} bestaat uit een of meer expressies
die de Lisp interpreter  op volgorde evalueert.

Tenslotte, een punt om op te merken: wanneer je zowel @code{save-excursion}
en @code{save-restriction} gebruikt, de een na de ander, dan moet je
@code{save-excursion} als de buitenste gebruiken. Wanneer je ze in
omgekeerde volgorde schrijft, kan het bijhouden van de versmalling in het
buffer waar Emacs naar toe schakelt na het aanroepen van
@code{save-excursion} fout gaan. Wanneer je daarom samen gebruikt, schrijf
je  @code{save-excursion} en @code{save-restriction} als volgt:

@smallexample
@group
(save-excursion
  (save-restriction
    @var{body}@dots{}))
@end group
@end smallexample

In andere omstandigheden, waar ze niet samen gebruikt worden, schrijf je de
speciale vormen @code{save-excursion} en @code{save-restriction} in de
volgorde die past bij de functie.

@need 1250
Bijvoorbeeld,

@smallexample
@group
  (save-restriction
    (widen)
    (save-excursion
    @var{body}@dots{}))
@end group
@end smallexample

@ignore
Emacs 22
/usr/local/src/emacs/lisp/simple.el

(defun what-line ()
  "Print the current buffer line number and narrowed line number of point."
  (interactive)
  (let ((start (point-min))
        (n (line-number-at-pos)))
    (if (= start 1)
        (message "Line %d" n)
      (save-excursion
        (save-restriction
          (widen)
          (message "line %d (narrowed line %d)"
                   (+ n (line-number-at-pos start) -1) n))))))

(defun line-number-at-pos (&optional pos)
  "Return (narrowed) buffer line number at position POS.
If POS is nil, use current buffer location.
Counting starts at (point-min), so the value refers
to the contents of the accessible portion of the buffer."
  (let ((opoint (or pos (point))) start)
    (save-excursion
      (goto-char (point-min))
      (setq start (point))
      (goto-char opoint)
      (forward-line 0)
      (1+ (count-lines start (point))))))

(defun count-lines (start end)
  "Return number of lines between START and END.
This is usually the number of newlines between them,
but can be one more if START is not equal to END
and the greater of them is not at the start of a line."
  (save-excursion
    (save-restriction
      (narrow-to-region start end)
      (goto-char (point-min))
      (if (eq selective-display t)
          (save-match-data
            (let ((done 0))
              (while (re-search-forward "[\n\C-m]" nil t 40)
                (setq done (+ 40 done)))
              (while (re-search-forward "[\n\C-m]" nil t 1)
                (setq done (+ 1 done)))
              (goto-char (point-max))
              (if (and (/= start end)
                       (not (bolp)))
                  (1+ done)
                done)))
        (- (buffer-size) (forward-line (buffer-size)))))))
@end ignore

@node what-line
@section @code{what-line}
@findex what-line
@cindex Verbreden, voorbeeld van

Het @code{what-line} commando vertelt het je het regelnummer waarop de
cursor staat. De functie illustreert het gebruik van de
@code{save-excursion} en @code{save-restriction} commando's. Hier is de
oorspronkelijke tekst van de functie.

@smallexample
@group
(defun what-line ()
  "Print the current line number (in the buffer) of point."
  (interactive)
  (save-restriction
    (widen)
    (save-excursion
      (beginning-of-line)
      (message "Line %d"
               (1+ (count-lines 1 (point)))))))
@end group
@end smallexample

(In moderne versies van GNU Emacs is de functie @code{what-line} uitgebreid
zodat het zowel het regelnummer in het versmalde buffer als het regelnummer
in het verbrede buffer vertelt. De moderne versie is complexer dan de versie
die we hier laten zien. Wanneer je een avontuurlijke bui hebt, kan je er
naar kijken nadat je uitgezocht hebt hoe deze versie werkt. Je hebt daar
waarschijnlijk @kbd{C-h f} (@code{describe-function}) bij nodig.) De
nieuwere versie gebruikt een conditional om vast te stellen of het buffer is
versmald.

Verder maakt de moderne versie van @code{what-line} gebruik van
@code{line-number-at-pos}, die net als andere eenvoudige expressies, zoals
@code{(goto-char (point-min))}, @code{(forward-line 0)} in plaats van
@code{beginning-of-line} gebruikt om point naar het begin van de huidige
regel te verplaatsen.

De functie @code{what-line} zoals hier getoond heeft zoals je zou verwachten
een documentatieregel en is interactief. De volgende twee regels gebruiken
de functies @code{save-restriction} en @code{widen}.

De speciale vorm @code{save-restriction} noteert eventuele versmalling die
van kracht is in het huidige buffer en herstelt de versmalling nadat de code
in de body van @code{save-restriction} is geëvalueerd.

De speciale vorm @code{save-restriction} wordt gevolgd door
@code{widen}. Deze functie maakt eventuele versmalling in het huidige buffer
ongedaan voor zover die er was toen @code{what-line} werd aangeroepen. (De
versmalling die daar was is de versmalling die @code{save-restriction}
onthoudt.) Deze verbreding maakt het voor de commando's die de regels tellen
mogelijk om vanaf het begin van het buffer te tellen. Anders zouden ze
beperkt zijn tot het tellen binnen het bereikbare gebied. Eventuele
oorspronkelijke versmalling wordt hersteld vlak voor de voltooiing van de
functie door de speciale vorm @code{save-restriction}.

De aanroep van @code{widen} wordt gevolgd door @code{save-excursion} die de
locatie van de cursor (dus van point) bewaart, en herstelt die nadat de code
in de body van de @code{save-excursion} de functie @code{beginning-of-line}
gebruikt om point te verplaatsen.

(Merk op dat de @code{(widen)} expressie tussen de speciale vormen
@code{save-restriction} en de @code{save-excursion} staat. Wanneer je de
twee @code{save- @dots{}} expressies opeenvolgend schrijft, zet je
@code{save-excursion} als buitenste.)

@need 1200
De laatste twee regels van de functie @code{what-line} zijn functies die het
aantal regels in het buffer tellen en daarna dat aantal in het echogebied
tonen.

@smallexample
@group
(message "Line %d"
         (1+ (count-lines 1 (point)))))))
@end group
@end smallexample

De functie @code{message} toont een eenregelige boodschap onderaan het Emacs
scherm. Het eerste argument staat tussen aanhalingstekens en wordt getoond
als een string karakters. Het mag echter een  @samp{%d} expressie bevatten
om het volgende argument te tonen. @samp{%d} toont het argument als een
decimaal getal, zodat de boodschap iets als @samp{Line 243} zegt.

@need 1200
Het getal dat getoond wordt op de plek van de @samp{%d} wordt berekend door
de laatste regel van de functie:

@smallexample
(1+ (count-lines 1 (point)))
@end smallexample

@ignore
GNU Emacs 22

(defun count-lines (start end)
  "Return number of lines between START and END.
This is usually the number of newlines between them,
but can be one more if START is not equal to END
and the greater of them is not at the start of a line."
  (save-excursion
    (save-restriction
      (narrow-to-region start end)
      (goto-char (point-min))
      (if (eq selective-display t)
          (save-match-data
            (let ((done 0))
              (while (re-search-forward "[\n\C-m]" nil t 40)
                (setq done (+ 40 done)))
              (while (re-search-forward "[\n\C-m]" nil t 1)
                (setq done (+ 1 done)))
              (goto-char (point-max))
              (if (and (/= start end)
                       (not (bolp)))
                  (1+ done)
                done)))
        (- (buffer-size) (forward-line (buffer-size)))))))
@end ignore

@noindent
Wat dit doet is het tellen van de regels vanaf de eerste positie van het
buffer, aangegeven door de @code{1}, tot de @code{(point)} en telt daar
vervolgens één bij op. (De functie @code{1+} telt één bij zijn argument op.)
We tellen één er bij op omdat regel 2 maar één regel voor zich heeft, en
@code{count-lines} alleen de regels @emph{voor} de huidige regel telt.

Nadat @code{count-lines} zijn werk heeft gedaan en de boodschap in het
echogebied is getoond, herstelt @code{save-excursion} point naar zijn
oorspronkelijke positie en herstelt @code{save-restriction} de eventuele
oorspronkelijke versmalling.

@node versmal oefening
@section Oefening met versmalling

Schrijf een functie dat de eerste 60 karakters van het huidige buffer toont,
zelfs wanneer je het buffer hebt versmald naar zijn tweede helft zodat de
eerste regel onbereikbaar is. Herstel point, mark en de versmalling. Gebruik
voor deze oefening de gehele potpourri van functies, inclusief
@code{save-restriction}, @code{widen}, @code{goto-char}, @code{point-min},
@code{message} en @code{buffer-substring}.

@cindex Eigenschappen, vermelding van @code{buffer-substring-no-properties}
(@code{buffer-substring} is een eerder ongenoemde functie die je zelf moet
onderzoeken, of misschien moet je gebruik maken van
. @code{buffer-substring-no-properties} of @code{filter-buffer-substring}
@dots{}, nog meer andere functies. Teksteigenschappen zijn een eigenschap
die overigens hier niet besproken wordt. @xref{Text Properties, , Text
Properties, elisp, The GNU Emacs Lisp Reference Manual}.)

Daarnaast, heb je @code{goto-char} of @code{point-min} echt nodig? Of kan je
de functie zonder hen schrijven?

@node car cdr en cons
@chapter @code{car}, @code{cdr}, @code{cons}: Fundamentele functies
@findex car@r{, introduced}
@findex cdr@r{, introduced}

@code{car}, @code{cdr} en @code{cons} zijn fundamentele functies in Lisp. De
functie @code{cons} wordt gebruikt om lijsten te construeren, en de functies
@code{car} en @code{cdr} worden gebruikt om ze uit elkaar te halen.

In de rondleiding door de functie @code{copy-region-as-kill} kijken we naar
@code{cons} en naar twee varianten van @code{cdr}, namelijk @code{setcdr} en
@code{nthcdr}.

@menu
* Vreemde namen::            Een historische terzijde: waarom de vreemde 
                               namen?
* car en cdr::               Functies om een deel van een lijst te 
                               extraheren.
* cons::                     Een lijst construeren.
* nthcdr::                   @code{cdr} herhaaldelijk aanroepen.
* nth::                      nth
* setcar::                   Het eerste element van een lijst veranderen.
* setcdr::                   De rest van de lijst veranderen.
* cons oefening::            cons oefening
@end menu

@ifnottex
@node Vreemde namen
@unnumberedsec Vreemde namen
@end ifnottex

De naam van de functie @code{cons} is niet onredelijk, het is een afkorting
van het woord ``construct''. De herkomst van de name voor @code{car} en
@code{cdr} aan de andere kant zijn esoterisch: @code{car} is een acroniem
van de zin ``Contents of the Address part of the Register'', en @code{cdr}
(uitgesproken als ``coeld-er'') is een acroniem van de zin ``Contents of the
Decrement part of the Register''. Deze zinnen refereren aan de IBM 704
computer waarop de oorspronkelijke Lisp werd ontwikkeld.

De IBM 704 is een voetnoot in de geschiedenis, maar deze namen zijn nu
geliefde tradities van Lisp.

@node car en cdr
@section @code{car} en @code{cdr}

De @sc{car} van een lijst is, vrij eenvoudig, het eerste item in de
lijst. Dus de @sc{car} van de lijst @code{(roos viool madelief boterbloem)}
is @code{roos}.

@need 1200
Wanneer je dit in Info in GNU Emacs leest kan je dit door het volgende te
evalueren:

@smallexample
(car '(roos viool madelief boterbloem))
@end smallexample

@noindent
Na het evalueren van de expressie verschijnt @code{roos} in het echogebied.

@code{car} verwijdert het eerste element van de lijst niet, het vertelt
alleen wat het is. Nadat @code{car} op een lijst is toegepast is de lijst
nog steeds hetzelfde. @code{car} is ``niet-destructief'', in het
jargon. Deze eigenschap blijkt belangrijk te zijn.

De @sc{cdr} van een lijst is de rest van de lijst, dat wil zeggen dat de
@sc{cdr} het deel van de lijst dat volgt op het eerste item. Dus terwijl de
@sc{car} van de lijst @code{'(roos viool madelief boterbloem)} @code{roos}
is, is de rest van de, de waarde die de functie @code{cdr} teruggeeft, is
@code{(viool madelief boterbloem)}.

@need 800
Je ziet door het volgende op de gebruikelijke manier te evalueren:

@smallexample
(cdr '(roos viool madelief boterbloem))
@end smallexample

@noindent
Wanneer je dit evalueert, verschijnt @code{(viool madelief boterbloem)} in
het echogebied.

Net als @code{car} verwijdert @code{cdr} geen elementen uit de lijst---het
vertelt aleen wat het de tweede en volgende elementen zijn.

Overigens in het voorbeeld is de lijst met bloemen gequote. Wanneer dat niet
zo was zou de Lisp interpreter de lijst proberen te evalueren door
@code{roos} als een functie aan te roepen. In dit voorbeeld willen we dat
niet.

Voor het werken met lijsten zouden de namen @code{first} en @code{rest}
logischer zijn dan de namen @code{car} en @code{cdr}. Sommige programmers
definieren inderdaad @code{first} en @code{rest} als aliassen voor
@code{car} en @code{cdr} en gebruiken daarna @code{first} en @code{rest} in
de rest van hun code.

Lijsten in Lisp worden echter gebouwd met een onderliggende structuur bekend
als ``cons cells'' (@pxref{Implementatie van lijsten}), waarin niet zo iets
als ``eerste'' of ``rest'' bestaat, en de @sc{car} en de @sc{cdr}
symmetrisch zijn. Lisp probeert niet het bestaan van cons cellen te
verstoppen en programma's gebruiken ze ook voor andere dingen dan
lijsten. Om deze reden helpen de namen de programmers te herinneren dat
@code{car} en @code{cdr} symmetrisch zijn, ondanks de asymmetrische manier
waarop ze in lijsten gebruikt worden.

@ignore
Clearly, a more reasonable name for @code{cdr} would be @code{rest}.

(There is a lesson here: when you name new functions, consider very
carefully what you are doing, since you may be stuck with the names
for far longer than you expect.  The reason this document perpetuates
these names is that the Emacs Lisp source code uses them, and if I did
not use them, you would have a hard time reading the code; but do,
please, try to avoid using these terms yourself.  The people who come
after you will be grateful to you.)
@end ignore

Wanneer @code{car} en @code{cdr} worden toegepast op lijsten van symbolen,
zoals de lijst @code{(den spar eik esdoorn)}, is het element van de lijst
dat de functie @code{car} teruggeeft het symbool @code{den}, zonder haakjes
er omheen. @code{den} is het eerste symbool in de lijst. De @sc{cdr} van de
lijst is echter een list op zichzelf, @code{(spar eik esdoorn)}, zoals je
ziet door de volgende expressie op de gebruikelijke manier te evalueren:

@smallexample
@group
(car '(den spar eik esdoorn))

(cdr '(den spar eik esdoorn))
@end group
@end smallexample

Anderzijds is in een lijst van lijsten het eerste element op zichzelf een
lijst. @code{car} geeft het eerste element als lijst terug. De volgende
lijst bijvoorbeeld bevat drie sublijsten, een lijst van carnivoren, een
lijst van herbivoren en een lijst van zeezoogdieren:

@smallexample
@group
(car '((leeuw tijger cheeta)
       (gazelle antiloop zebra)
       (walvis dolfijn zeehond)))
@end group
@end smallexample

@noindent
In dit voorbeeld is het eerste element of de @sc{car} van de lijst de lijst
met carnivoren, @code{(leeuw tijger cheeta)} en is de rest van de lijst
@code{(gazelle antiloop zebra) (walvis dolfijn zeehond)}.

@smallexample
@group
(cdr '((leeuw tijger cheeta)
       (gazelle antiloop zebra)
       (walvis dolfijn zeehond)))
@end group
@end smallexample

Het is het waard nog een keer te zeggen dat @code{car} en @code{cdr}
niet-destructief zijn, zij wijzigen de lijsten waarop worden toegepast
niet. Dit is erg belangrijk voor hoe ze worden gebruikt.

Daarnaast zei ik bij de bespreking van atomen in het eerste hoofdstuk dat in
Lisp sommige soorten atomen, zoals een array, in delen gescheiden kunnen
worden maar dat het mechanisme om dit te doen afwijkt van het mechanisme om
een lijst te splijten. Voor zover het Lisp aangaat, zijn de atomen van
lijsten onsplijtbaar. (@xref{Lisp atomen}.) De functies @code{car} en
@code{cdr} worden gebruikt om lijsten te splijten en worden als fundamenteel
voor Lisp beschouwd. Aangezien zij een array niet kunnen splijten of toegang
krijgen tot de delen van een array, wordt een array beschouwd als een
atoom. Omgekeerd kan de andere fundamentele functie @code{cons} gebruikt
worden om een lijst samen te stellen, maar niet een array. (Arrays worden
behandeld met array-specifieke functies  @xref{Arrays, , Arrays, elisp, The
GNU Emacs Lisp Reference Manual}.)

@node cons
@section @code{cons}
@findex cons@r{, geïntroduceerd}

De @code{cons} functie construeert lijsten. Het is de inverse van @code{car}
en @code{cdr}. @code{cons} kan bijvoorbeeld gebruikt worden om de lijst van
vier elementen te maken van een lijst met drie elementen, bijvoorbeeld
@code{(spar eik esdoorn)}:

@smallexample
(cons 'den '(spar eik esdoorn))
@end smallexample

@need 800
@noindent
Na evaluatie van de lijst zie je

@smallexample
(den spar eik esdoorn)
@end smallexample

@noindent
in het echogebied verschijnen. @code{cons} veroorzaakt de creatie van een
nieuwe lijst waarin het element wordt gevolgd door de elementen van de
oorspronkelijke lijst.

We zeggen vaak dat @code{cons} een nieuw element aan het begin van de lijst
plaatst, of dat het een element aan de lijst vastmaakt of pusht, maar deze
formulering is misleidend, omdat @code{cons} geen bestaande lijst verandert,
maar een nieuwe maakt.

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

@menu
* Bouw een lijst::           Bouw een lijst
* length::                   Hoe de lengte van een lijst te vinden.
@end menu

@ifnottex
@node Bouw een lijst
@unnumberedsubsec Bouw een lijst
@end ifnottex

@code{cons} moet een lijst hebben om aan vast te maken@footnote{Eigenlijk
kan je met @code{cons} een element aan een atoom consen om een dotted pair
te maken. Dotted pairs worden hier niet behandeld. Zie @ref{Dotted Pair
Notation, , Dotted Pair Notation, elisp, The GNU Emacs Lisp Reference
Manual}.} Je kunt niet van absoluut niets beginnen. Wanneer je een lijst
bouwt, dan moet je tenminste een lege lijst als begin geven. Hier is een
serie van @code{cons} expressies die een lijst van bloemen opbouwen. Wanneer
je dit in Info in GNU Emacs leest, kan je elk van expressies op de
gebruikelijke manier evalueren. De waarde wordt in deze tekst getoond na
@samp{@result{}}, wat je kunt zien als ``evalueert naar''.

@smallexample
@group
(cons 'boterbloem ())
     @result{} (boterbloem)
@end group

@group
(cons 'madelief '(boterbloem))
     @result{} (madelief boterbloem)
@end group

@group
(cons 'viool '(madelief boterbloem))
     @result{} (violet madelief boterbloem)
@end group

@group
(cons 'roos '(viool madelief boterbloem))
     @result{} (roos viool madelief boterbloem)
@end group
@end smallexample

@noindent
In het eerste voorbeeld wordt de lege lijst getoond als @code{()} en wordt
lijst geconstrueerd van @code{boterbloem} gevold door de lege lijst. Zoals
je ziet wordt de lege lijst niet getoond in de geconstrueerde lijst. Het
enige wat je ziet is @code{(boterbloem)}. De lege lijst telt niet als een
element van de lijst omdat er niets is in een lege lijst. Over het algemeen
is een lege lijst onzichtbaar.

Het tweede voorbeeld, @code{(cons 'madelief '(boterbloem))} construeert een
nieuwe lijst met twee elementen door @code{madelief} voor @code{boterbloem}
te plaatsen, en het derde voorbeeld construeert een lijst met drie elementen
door @code{viool} voor @code{madelief} en @code{boterbloem} te plaatsen.

@node length
@subsection Achterhaal de lengte van een lijst: @code{length}
@findex length

Je achterhaalt hoeveel elementen in een lijst zijn met de Lisp functie
@code{length}, zoals in de volgende voorbeelden:

@smallexample
@group
(length '(boterbloem))
     @result{} 1
@end group

@group
(length '(madelief boterbloem))
     @result{} 2
@end group

@group
(length (cons 'viool '(madelief boterbloem)))
     @result{} 3
@end group
@end smallexample

@noindent
In het derde voorbeeld is de functie @code{cons} gebruikt om een lijst met
drie elementen te construeren die daarna als argument wordt doorgegeven aan
de functie @code{length}.

@need 1200
We kunnen @code{length} ook gebruiken om het aantal elementen in een lege
lijst te tellen:

@smallexample
@group
(length ())
     @result{} 0
@end group
@end smallexample

@noindent
Zoals je zou verwachten is het aantal elementen van een lege lijst nul.

Een interessant experiment is te ontdekken wat gebeurt wanneer je probeert
de lengte van totaal geen lijst te achterhalen, dus als je probeert
@code{length} zonder enig argument aan te roepen, zelfs geen lege lijst.

@smallexample
(length )
@end smallexample

@need 800
@noindent
Wat je ziet als je dit evalueert is de foutmelding

@smallexample
Lisp error: (wrong-number-of-arguments length 0)
@end smallexample

@noindent
Dit betekent dat de functie een verkeerd aantal argumenten krijgt, nul,
terwijl het een ander aantal argumenten verwacht. In dit geval wordt één
argument verwacht, een argument dat een lijst is wiens lengte de functie
moet meten. (Merk op dat @emph{één} lijst @emph{één} argument is, zelfs als
de lijst veel elementen in zich heeft.)

Het deel van de foutmelding dat @samp{length} zegt, is de naam van de
functie.

@ignore
@code{length} is still a subroutine, but you need C-h f to discover that.

In an earlier version:
    This is written with a special notation, @samp{#<subr},
    that indicates that the function @code{length} is one of the primitive
    functions written in C rather than in Emacs Lisp.  (@samp{subr} is an
    abbreviation for ``subroutine''.)  @xref{What Is a Function, , What Is a
    Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
    about subroutines.
@end ignore

@node nthcdr
@section @code{nthcdr}
@findex nthcdr

De functie @code{nthcdr} is geassocieerd met de functie @code{cdr}. Wat het
doet is dat het herhaaldelijk de @sc{cdr} van een lijst neemt.

Wanneer je de @sc{cdr} van de lijst @code{(den spar eik esdoorn)} neemt,
krijg je de lijst @code{(spar eik esdoorn)}. Wanneer je dit herhaalt op wat
je terugkreeg, krijg je de lijst @code{(eik esdoorn)} terug. (Als je
herhaaldelijk de @sc{cdr} van de originele lijst neemt, dan krijg je
natuurlijk de originele @sc{cdr} terug, omdat deze functie de lijst niet
verandert. Je moet de @sc{cdr} van de @sc{cdr} nemen, enzovoort.) Wanneer je
hiermee doorgaat, dan krijg je uiteindelijk de lege lijst terug, welke in
dit geval in plaats van @code{()} getoond wordt als @code{nil}.

@need 1200
Ter beoordeling is hier een lijst van herhaaldelijke @sc{cdr}'s, de tekst
volgend op @samp{@result{}} toont wat wordt teruggegeven.

@smallexample
@group
(cdr '(den spar eik esdoorn))
     @result{} (spar eik esdoorn)
@end group

@group
(cdr '(spar eik esdoorn))
     @result{} (eik esdoorn)
@end group

@group
(cdr '(eik esdoorn))
     @result{} (esdoorn)
@end group

@group
(cdr '(esdoorn))
     @result{} nil
@end group

@group
(cdr 'nil)
     @result{} nil
@end group

@group
(cdr ())
     @result{} nil
@end group
@end smallexample

@need 1200
Het is ook mogelijk meerdere @sc{cdr}'s te doen zonder de waarden er tussen
te tonen.

@smallexample
@group
(cdr (cdr '(den spar eik esdoorn)))
     @result{} (eik esdoorn)
@end group
@end smallexample

@noindent
in dit voorbeeld evalueert de Lisp interpreter eerst de binnenste lijst. De
binnenste lijst is gequote, en geeft dus de lijst zoals die is door aan de
binnenste @code{cdr}. Deze @code{cdr} geeft de lijst, bestaande uit het
tweede en volgende elementen van de lijst door aan de buitenste @code{cdr},
die de lijst produceert die bestaat uit het derde en volgende elementen van
de oorspronkelijke lijst. In dit voorbeeld wordt de @code{cdr} herhaald en
geeft een lijst terug die bestaat uit de oorspronkelijke lijst zonder de
eerste twee elementen.

De functie @code{nthcdr} doet hetzelfde als een herhaalde aanroep van
@code{cdr}. In het volgende voorbeeld wordt het argument 2 doorgegeven aan
de functie @code{nthcdr}, samen met de lijst, en de teruggegeven waarde is
de lijst zonder de eerste twee elementen, wat exact hetzelfde is als twee
keer @code{cdr} herhalen op de lijst.

@smallexample
@group
(nthcdr 2 '(den spar eik esdoorn))
     @result{} (eik esdoorn)
@end group
@end smallexample

@need 1200
Je kunt met de oorspronkelijke lijst van vier elementen zien wat gebeurt
wanneer je verschillende numerieke argumenten doorgeeft aan @code{nthcdr},
waaronder 0, 1 en 5:

@smallexample
@group
;; @r{Houd de lijst zoals die was.}
(nthcdr 0 '(den spar eik esdoorn))
     @result{} (den spar eik esdoorn)
@end group

@group
;; @r{Geef een exemplaar terug zonder eerste element.}
(nthcdr 1 '(den spar eik esdoorn))
     @result{} (spar eik esdoorn)
@end group

@group
;; @r{Geef een exemplaar terug zonder drie elementen.}
(nthcdr 3 '(den spar eik esdoorn))
     @result{} (esdoorn)
@end group

@group
;; @r{Geef een exemplaar terug waar alle vier elementen ontbreken.}
(nthcdr 4 '(den spar eik esdoorn))
     @result{} nil
@end group

@group
;; @r{Geef een exemplaar terug zonder alle elementen.}
(nthcdr 5 '(den spar eik esdoorn))
     @result{} nil
@end group
@end smallexample

@node nth
@section @code{nth}
@findex nth

De functie @code{nthcdr} neemt herhaaldelijk de @sc{cdr} van een lijst. De
functie @code{nth} neemt de @sc{car} van het resultaat dat door
@code{nthcdr} wordt teruggegeven. Het geeft het N-de element van de lijst
terug.

@need 1500
Dus, als het, in verband met de snelheid, niet in C zou zijn gedefinieerd
zou dit de definitie van @code{nth} zijn:

@smallexample
@group
(defun nth (n list)
  "Returns the Nth element of LIST.
N counts from zero.  If LIST is not that long, nil is returned."
  (car (nthcdr n list)))
@end group
@end smallexample

@noindent
(Oorspronkelijk was @code{nth} gedefinieerd in Emacs Lisp in @file{subr.el},
maar de definitie was in de jaren tachtig opnieuw gedaan in C.)

De functie @code{nth} geeft een enkel element van een lijst terug. Dit kan
erg handig zijn.

Merk op de de elementen vanaf nul zijn genummerd, niet een. Dat wil zeggen
dat het eerste element van een lijst, zijn @sc{car}, is het nulde
element. Deze nul-gebaseerde telling is lastig voor mensen die gewend zijn
die gewend zijn dat het eerste element in een lijst nummer een is, wat
een-gebaseerd is.

@need 1250
Bijvoorbeeld:

@smallexample
@group
(nth 0 '("een" "twee" "drie"))
    @result{} "een"

(nth 1 '("een" "twee" "drie"))
    @result{} "twee"
@end group
@end smallexample

Het is waardevol op te merken dat @code{nth}, net als @code{nthcdr} en
@code{cdr}, de oorspronkelijke lijst niet verandert---de functie is
niet-destructief. Dit is in scherp contrast met de functies @code{setcar} en
@code{setcdr}.

@node setcar
@section @code{setcar}
@findex setcar

Zoals je wellicht door hun namen vermoedt, stellen de functies @code{setcar}
en @code{setcdr} de @sc{car} of de @sc{cdr} van een lijst in op een nieuwe
waarde. Zij wijzigen echt de oorspronkelijke lijst, in tegenstelling tot
@code{car} en @code{cdr} die de oorspronkelijke lijst laten zoals die
was. Een manier om te ontdekken hoe dit werkt is door te proberen. Wij
beginnen met de functie @code{setcar}.

@need 1200
Eerst maken we een lijst en stellen die met de speciale vorm @code{setq} als
de waarde in van een variabele. Omdat we van plan zijn @code{setcar} te
gebruiken om de lijst te wijzigen, moet deze @code{setq} geen gebruik van de
gequote vorm @code{'(antiloop giraf leeuw tijger)} maken, omdat dit een
lijst oplevert die onderdeel van het programma is en slechte dingen zouden
kunnen gebeuren wanneer we proberen een deel van het programma te wijzigen
terwijl dat loopt. In het algemeen moeten de componenten van een Emacs Lisp
programma constant zijn (of ongewijzigd) terwijl het programma loopt. In
plaats daarvan construeren we daarom als volgt een lijst met de functie
@code{list}:

@smallexample
(setq dieren (list 'antiloop 'giraf 'leeuw 'tijger))
@end smallexample

@noindent
Wanneer je dit in Info binnen GNU Emacs leest kan je deze expressie op de
gebruikelijke manier evalueren, door de cursor achter de expressie te
plaatsen en @kbd{C-x C-e} te typen. (Ik doe dat meteen hier terwijl ik dit
schrijft. Dat is een van de voordelen van een in je computer omgeving
ingebouwde interpreter Overigen, wanneer is niets op de regel na het laatste
haakje staat, zoals commentaar, kan point ook de volgende regel staan. Dus
als point op de eerste kolom van de regel staat, hoef je die niet te
verplaatsten. Emacs staat zelfs een willekeurige hoeveelheid witte ruimte
achter het laaste haakje toe.)

@need 1200
Wanneer we de variabele @code{dieren} evalueren dan zien we dat die gebonden
is aan de lijst @code{(antiloop giraf leeuw tijger)}:

@smallexample
@group
dieren
     @result{} (antiloop giraf leeuw tijger)
@end group
@end smallexample

@noindent
Anders gezegd, de variabele @code{dieren} wijst naar de lijst
@code{(antiloop giraf leeuw tijger)}.

Vervolgens evalueren we de functie @code{setcar} terwijl we daar twee
argumenten aan doorgeven, de variabele @code{dieren} en het geqoute symbool
@code{nijlpaard}. Dit doen we door de lijst van drie elementen @code{(setcar
dieren 'nijlpaard)} te schrijven en die dan op de gebruikelijke manier te
evalueren.

@smallexample
(setcar dieren 'nijlpaard)
@end smallexample

@need 1200
@noindent
Na het evalueren van deze expressie, evalueer je de variabele @code{dieren}
nogmaals. Je zult zien dat de lijst gewijzigd is:

@smallexample
@group
dieren
     @result{} (nijlpaard giraf leeuw tijger)
@end group
@end smallexample

@noindent
Het eerste element van de lijst, @code{antiloop} is vervangen met
@code{nijlpaard}.

We zien dus dat @code{setcar} geen nieuw element aan de lijst heeft
toegevoegd, wat @code{cons} gedaan zou hebben, maar het verving
@code{antiloop} met @code{nijlpaard}. Het @emph{wijzigde} de lijst.

@node setcdr
@section @code{setcdr}
@findex setcdr

De functie @code{setcdr} is vergelijkbaar met de functie @code{setcar},
behalve dat de functie de tweede en volgende elementen van een lijst
vervangt in plaats van het eerste element.

(Kijk vooruit naar @ref{kill-new functie, , De @code{kill-new} functie} om
te zien hoe het laatste element van een list te wijzigen. De @code{kill-new}
functie gebruikt de @code{nthcdr} en de @code{setcdr} functies.)

@need 1200
Om de zien hoe dit werkt stel je waarde van de variabele in op een lijst van
gedomesticeerde dieren door de volgende expressie te evalueren:

@smallexample
(setq gedomesticeerde-dieren (list 'paard 'koe 'schaap 'gijt))
@end smallexample

@need 1200
@noindent
Wanneer je nu de lijst evalueert, krijg je de lijst @code{(paard koe schaap
gijt)} terug.

@smallexample
@group
gedomesticeerde-dieren
     @result{} (paard koe schaap gijt)
@end group
@end smallexample

@need 1200
Evalueer vervolgens @code{setcdr} met twee argumenten, de naam van de
variabele die een lijst als waarde heeft, en de lijst waarop we de @sc{cdr}
van de eerste lijst willen instellen:

@smallexample
(setcdr gedomesticeerde-dieren '(kat hond))
@end smallexample

@noindent
Wanneer je deze expressie evalueert verschijnt de lijst @code{(kat hond)} in
het echogebied. Dit is de waarde die de functie teruggaf. Het resultaat waar
wij in geïnteresseerd zijn is in het zij-effect, wat we kunnen zien wanneer
we de variabele @code{gedomesticeerde-dieren} evalueren:

@smallexample
@group
gedomesticeerde-dieren
     @result{} (paard kat hond)
@end group
@end smallexample

@noindent
Inderdaad is de lijst gewijzigd van @code{(paard koe schaap gijt)} naar
@code{(paard kat hond)}. De @sc{cdr} van de lijst is gewijzigd van
@code{(koe schaap gijt)} naar @code{(kat hond)}.

@node cons oefening
@section Oefening

Construeer een lijst met vier vogels door verschillende expressies met
@code{cons} te evalueren. Ontdek wat gebeurt wanneer je een lijst met
zichzelf @code{const}-t. Vervang het eerste element van de lijst met vier
vogels met een vis. Vervang de rest van de lijst met een lijst van andere
vissen.

@node Knippen en opslaan van tekst
@chapter Tekst knippen en opslaan
@cindex Tekst knippen en opslaan
@cindex Tekst opslaan en knippen
@cindex Tekst killen
@cindex Text clippen
@cindex Tekst wissen
@cindex Tekst deleten

Steeds als je in GNU Emacs tekst uit een buffer snijdt op clipt met een
@dfn{kill} commando, wordt het bewaard in een lijst en kan je het terughalen
met een @dfn{yank} commando.

(Het gebruik van het woord ``kill'' in Emacs voor processen die @emph{niet}
specifiek de waarden van de entiteiten vernietigen), is een ongelukkig
historisch ongeluk. Een veel beter word zou ``clip'' zijn, omdat dat is wat
kill commando's doen. Zij clippen tekst uit het buffer en bergen dat in een
opslagplaats op van waar het teruggebracht kan worden. Ik ben vaak in de
verleiding gekomen om overal waar ``kill'' voorkomt in de Emacs broncode dat
met ``clip'' te vervangen en overal waar ``killed'' voorkomt met
``clipped''.)

@menu
* Tekst opslaan::            Tekst wordt opgeslagen in een lijst.
* zap-to-char::              Tekst tot aan een karakter knippen.
* kill-region::              Tekst uit een gebied knippen.
* copy-region-as-kill::      Een definitie van tekst kopiëren.
* Uitwijding naar C::        Kleine opmerking over C programmeertaal macros.
* defvar::                   Hoe een variabele een initiële waarde te geven.
* cons en search-fwd terugblik::  cons en search-fwd terugblik
* zoek oefening::            zoek oefening
@end menu

@ifnottex
@node Tekst opslaan
@unnumberedsec Tekst in een lijst opslaan
@end ifnottex

Wanneer tekst uit een buffer wordt gesneden, wordt het in een lijst
opgeslagen. Opvolgende stukken tekst worden in de lijst opeenvolgend
opgeslagen, zodat de lijst er zo uit kan zien:

@smallexample
("een stuk tekst" "vorig stuk")
@end smallexample

@need 1200
@noindent
De functie @code{cons} kan gebruikt worden om een nieuwe lijst te maken van
een stuk tekst (een ``atoom'', om het jargon te gebruiken) en een bestaande
lijst, zoals hier:

@smallexample
@group
(cons "nog een stuk"
      '("een stuk tekst" "vorig stuk"))
@end group
@end smallexample

@need 1200
@noindent
Wanneer je deze expressie evalueert, verschijnt een lijst met drie elementen
in het echogebied:

@smallexample
("nog een stuk" "een stuk tekst" "vorig stuk")
@end smallexample

Met de functies @code{car} en @code{nthcdr} haal je een willekeurig stuk
tekst naar keuze op. Bijvoorbeeld, in de volgende code geeft @code{nthcdr 1
@dots{}} de lijst met eerste element verwijderd terug, en de @code{car}
geeft het eerst element van de rest terug---het tweede element van de
oorspronkelijke lijst:

@smallexample
@group
(car (nthcdr 1 '("nog een stuk"
                  "een stuk tekst"
                  "vorig stuk")))
      @result{} "een stuk tekst"
@end group
@end smallexample

De echte functies in Emacs zijn natuurlijk meer complex dan dit. De code
voor het snijden en terughalen van tekst moet zo zijn geschreven dat Emacs
kan uitzoeken welk element in de lijst je wilt---eerste, tweede, derde, of
welke dan ook. Verder, wanneer je aan het einde van lijst komt, moet Emacs
je het eerste element van de lijst geven, in plaats van helemaal niets.

De lijst die de stukken tekst bevat het de @dfn{killring}. Dit hoofdstuk
werkt naar een beschijving van de killring toe en hoe die gebruikt wordt
door eerst te volgen hoe de functie @code{zap-to-char} werkt. Deze functie
roept een functie aan die een functie start die de killring
manipuleert. Dus, voordat we de bergen bereiken, beklimmen we eerst de
voetheuvels.

Een volgend hoofdstuk beschrijft hoe tekst dat uit het buffer is gesneden
wordt teruggehaald. @xref{Yanking, , Tekst terug yanken}.

@node zap-to-char
@section @code{zap-to-char}
@findex zap-to-char

Laten we naar de interactieve functie @code{zap-to-char} kijken.

@menu
* Complete zap-to-char::     De complete implementatie.
* zap-to-char interactief::  Een driedelige iteractive expressie.
* zap-to-char body::         Een kort overzicht.
* search-forward::           Hoe naar een string te zoeken.
* progn::                    De @code{progn} speciale vorm.
* Samenvatting zap-to-char::  Gebruik @code{point} en @code{search-forward}.
@end menu

@ifnottex
@node Complete zap-to-char
@unnumberedsubsec De complete @code{zap-to-char} implementatie
@end ifnottex

De functie @code{zap-to-char} verwijdert de tekst in de region tussen de
lokatie van de cursor (dus van point) tot en met waar het gespecificeerde
karakter verschijnt. De tekst die @code{zap-to-char} verwijdert wordt in de
killring gestopt en het kan uit de killring worden opgehaald door @kbd{C-y}
(@code{yank}) te typen.

Wanneer het gespecificeerde karakter niet gevonden is, zegt
@code{zap-to-char} ``Search failed'', en welk karakter je typte, en
verwijdert geen tekst.

Om vast te stellen hoeveel tekst te verwijderen, gebruikt @code{zap-to-char}
een zoekfunctie. Zoeken wordt extensief gebruikt in code die tekst
manipuleert, en wij zullen aandacht aan ze besteden, net als aan de delete
commando's.

@ignore
@c GNU Emacs version 19
(defun zap-to-char (arg char)  ; version 19 implementation
  "Kill up to and including ARG'th occurrence of CHAR.
Goes backward if ARG is negative; error if CHAR not found."
  (interactive "*p\ncZap to char: ")
  (kill-region (point)
               (progn
                 (search-forward
                  (char-to-string char) nil nil arg)
                 (point))))
@end ignore

@need 1250
Hier is de complete tekst van de vesie 22 implementatie van de functie:

@c GNU Emacs 22
@smallexample
@group
(defun zap-to-char (arg char)
  "Kill up to and including ARG'th occurrence of CHAR.
Case is ignored if `case-fold-search' is non-nil in the current buffer.
Goes backward if ARG is negative; error if CHAR not found."
  (interactive "p\ncZap to char: ")
  (if (char-table-p translation-table-for-input)
      (setq char (or (aref translation-table-for-input char) char)))
  (kill-region (point) (progn
                         (search-forward (char-to-string char)
                                         nil nil arg)
                         (point))))
@end group
@end smallexample

De documentatie is grondig. Je moet weten wat in het jargon het woord
``kill'' betekent.

@cindex gebogen aanhalingstekens
@cindex gebogen aanhalingstekens
The version 22 documentation string for @code{zap-to-char} uses ASCII grave
accent and apostrophe to quote a symbol, so it appears as
@t{`case-fold-search'}.  This quoting style was inspired by 1970s-era
displays in which grave accent and apostrophe were often mirror images
suitable for use as quotes.  On most modern displays this is no longer true,
and when these two ASCII characters appear in documentation strings or
diagnostic message formats, Emacs typically transliterates them to
@dfn{curved quotes} (left and right single quotation marks), so that the
abovequoted symbol appears as @t{‘case-fold-search’}.  Source-code strings
can also simply use curved quotes directly.

@node zap-to-char interactief
@subsection De @code{interactive} expressie

@need 800
De interactive expressie in het @code{zap-to-char} commando ziet er zo uit:

@smallexample
(interactive "p\ncZap to char: ")
@end smallexample

Het gedeelte tussen de aanhalingstekens, @code{"p\ncZap to char:@: "},
specificeert twee verschillende dingen. Het eerste en meest eenvoudige is de
@samp{p}. Dit deel is met een nieuwe regelteken @samp{\n} gescheiden van het
volgende deel. Het @samp{p} betekent dat het eerste argument van de functie
de waarde van een @dfn{processed prefix} doorgeeft. Het prefix-argument
wordt doorgegeven door @kbd{C-u} en een getal te typen, of @kbd{M-} en een
cijfer. Wanneer een functie interactief wordt aangeroepen zonder een prefix,
dan wordt 1 als argument doorgegeven.

Het tweede deel van @code{"p\ncZap to char:@: "} is @samp{cZap to char:@:
}. In dit deel geeft de kleine letter @samp{c} aan dat @code{interactive}
een prompt verwacht en dat het argument een karakter is. De prompt volgt op
de @samp{c} en is de string @samp{Zap to char:@: } (met een spatie achter de
dubbele punt zodat het er goed uitziet.)

Dit alles bereidt de argumenten van @code{zap-to-char} voor, zodat die van
het juiste type zijn en de gebruiker een prompt geven.

In een read-only buffer kopieert de functie @code{zap-to-char} de tekst naar
de killring, maar verwijdert die niet. Het echogebied toont een boodschap
dat het buffer read-only is. Ook kan de terminal piepen of knipperen.

@node zap-to-char body
@subsection De body van @code{zap-to-char}

De body van de functie @code{zap-to-char} bevat code die de tekst in de
region van de huidige cursorpositie tot en met het gespecificeerde karakter
killt (dat wil zeggen, verwijdert).

Het eerste deel van de code ziet er zo uit:

@smallexample
(if (char-table-p translation-table-for-input)
    (setq char (or (aref translation-table-for-input char) char)))
(kill-region (point) (progn
                       (search-forward (char-to-string char) nil nil arg)
                       (point)))
@end smallexample

@noindent
@code{char-table-p} functie zien we voor het eerst. Het stelt vast of het
argument een karakter-tabel is. Wanneer dat het geval is, dan stelt die het
karakter was aan @code{zap-to-char} wordt doorgegeven aan een van hen
in. (Dit is belangrijk voor bepaalde karakters in niet-Europese talen. De
functie @code{aref} extraheert een element uit een array. Het is een
array-specifieke functie die we in dit document niet
bespreken. @xref{Arrays, , Arrays, elisp, The GNU Emacs Lisp Reference
Manual}.)

@noindent
@code{(point)} is de huidige cursorpositie.

Het volgende deel van de code is een expressie met @code{progn}. De body van
de @code{progn} bestaat uit aanroepen van @code{search-forward} en
@code{point}.

Het is eenvoudiger te begrijpen hoe @code{progn} werkt nadat we
@code{search-forward} bestudeerd hebben, dus we kijken eerst naar
@code{search-forward} en dan naar @code{progn}.

@node search-forward
@subsection De functie @code{search-forward}
@findex search-forward

De functie @code{search-forward} wordt @code{zap-to-char} gebruikt het
zapped-for-karakter te vinden. Wanneer het zoeken succesvol is, zet
@code{search-forward} point onmiddellijk achter het laatste karakter in de
doelstring. (In @code{zap-to-char} is de doelstring slechts één karakter
lang. @code{zap-to-char} gebruikt de functie @code{char-to-string} om zeker
te stellen dat de computer het karakter als string behandelt.) Wanneer het
zoeken achterwaarts is dan zet @code{search-forward} point onmiddellijk voor
het eerste karakter in het doel. Ook geeft @code{search-forward} @code{t}
terug, voor waar. (Het verplaatsen van point is daarom een zij-effect.)

@need 1250
In @code{zap-to-char} ziet de functie @code{search-forward} er zo uit:

@smallexample
(search-forward (char-to-string char) nil nil arg)
@end smallexample

De functie @code{search-forward} heeft vier argumenten:

@enumerate
@item
Het eerste argument is het doel, waar naar gezocht wordt. Dit moet een
string zijn, zoals @samp{"z"}.

Het argument dat aan @code{zap-to-char} wordt doorgegeven is een enkel
karakter. Door de manier waarop computers zijn gebouwd kan de Lisp
interpreter een enkel karakter anders behandelen dan een string met
karakters. Binnen de computer heeft een enkel karakter een ander
elektronisch formaat dan een string van één karakter. (Een enkel karakter
kan vaak worden opgeslagen als precies één byte, maar een string kan langer
zijn en de computer moet daarop voorbereid zijn.) Omdat de functie
@code{search-forward} naar een string zoekt, moet het karakter dat de
functie @code{zap-to-char} ontvangt in de computer worden geconverteerd van
het ene formaat in het andere, anders faalt de functie
@code{search-forward}. Deze conversie wordt met de functie
@code{char-to-string} gemaakt.

@item
Het tweede argument begrenst het zoeken, het is gespecificeerd als een
positie in het buffer. In dit geval kan het zoeken tot het einde van het
buffer doorgaan, daarom is geen grens bepaald en is het tweede argument
@code{nil}.

@item
Het derde argument vertelt de functie wat het moet doen indien het zoeken
faailt---het kan een fout signaleren (en een boodschap tonen) of het kan
@code{nil} teruggeven. Een @code{nil} als derde argument zorgt dat de
functie een fout signaleert wanneer het zoeken faalt.

@item
Het vierde argument van @code{search-forward} is het aantal te
herhalen---naar hoe veel herhalingen van de string te zoeken. Dit argument
is optioneel en wanneer de functie is aangeroepen zonder dit aantal, wordt
een argument met de waarde 1 doorgegeven. Wanneer dit argument negatief is,
vindt het zoeken achterwaarts plaats.
@end enumerate

@need 800
In slaboonvorm ziet een @code{search-forward} expressie er zo uit:

@smallexample
@group
(search-forward "@var{doel-string}"
                @var{zoeklimiet}
                @var{wat-te-doen-als-zoeken-faalt}
                @var{aantal-herhalingen})
@end group
@end smallexample

We kijken nu naar @code{progn}.

@node progn
@subsection De speciale vorm @code{progn}
@findex progn

De speciale vorm @code{progn} laat elk van zijn argumenten achtereenvolgens
evalueren en geeft daarna de waarde van de laatste terug. De voorgaande
expressies worden uitsluitend geëvalueerd voor de zij-effecten die zij
uitvoeren. De waarden die zij produceren worden weggegooid.

@need 800
Het sjabloon voor een @code{progn} expressie is erg eenvoudig:

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

In @code{zap-to-char} moet de @code{progn} expressie twee dingen doen: zet
point exact op de juiste positie en geef de locatie van point zodat
@code{kill-region} weet hoe ver het moet killen.

Het eerste argument van de @code{progn} is @code{search-forward}. Wanneer
@code{search-forward} de string vindt, zet het point onmiddellijk achter het
laatste karakter in de doelstring. (In dit geval is de doelstring slechts
één karakter lang.) Wanneer het achterwaarts zoekt zet @code{search-forward}
point onmiddellijk voor het eerste karakter van het doel. Het verplaatsen
van point is een zij-effect.

Het tweede en laatste argument van @code{progn} is de expressie
@code{(point)}. Deze expressie geeft de waarde van point, wat in dit geval
de lokatie is waar het naar verplaatst is door @code{search-forward}. (In de
broncode is een regel die de functie vertelt om naar het voorgaande karakter
te gaan wanneer het voorwaarts gaat, die in 1999 uitgecomment is. Ik kan me
niet herinneren of die eigenschap of onjuiste eigenschap ooit een deel van
de gedistribueerde broncode was.) De waarde van @code{point} wordt
teruggeven door de @code{progn} expressie en wordt doorgegeven aan
@code{kill-region} als het tweede argument van @code{kill-region}.

@node Samenvatting zap-to-char
@subsection @code{zap-to-char} samengevat

Nu dat we hebben gezien hoe @code{search-forward} en @code{progn} werken,
kunnen we zien hoe de functie @code{zap-to-char} als geheel werkt.

Het eerste argument voor @code{kill-region} is de cursorpositie op het
moment dat het @code{zap-to-char} commando werd gegeven. Binnen @code{progn}
verplaatst de zoekfunctie vervolgens point naar onmiddellijk achter het
zapped-to-character en @code{point} geeft de waarde van deze lokatie
terug. De @code{kill-region} voegt deze twee waarden van point, het eerste
als het begin van de region en en de tweede als einde van de region, en
verwijdert de region.

De speciale vorm @code{progn} is noodzakelijk omdat het @code{kill-region}
twee argumenten verwacht, en het zou falen wanneer de @code{search-forward}
en @code{point} expressies als twee opeenvolgende argumenten geschreven
zouden worden. De @code{progn} expressie is een enkel argument voor
@code{kill-region} en geeft de ene waarde terug die @code{kill-region} nodig
heeft als tweede argument.

@node kill-region
@section @code{kill-region}
@findex kill-region

De functie @code{zap-to-char} gebruikt de @code{kill-region}. Deze functie
clipt de tekst van een region en kopieert die tekst naar de killring, van
waar het kan worden opgehaald.

@ignore
GNU Emacs 22:

(defun kill-region (beg end &optional yank-handler)
  "Kill (\"cut\") text between point and mark.
This deletes the text from the buffer and saves it in the kill ring.
The command \\[yank] can retrieve it from there.
\(If you want to kill and then yank immediately, use \\[kill-ring-save].)

If you want to append the killed region to the last killed text,
use \\[append-next-kill] before \\[kill-region].

If the buffer is read-only, Emacs will beep and refrain from deleting
the text, but put the text in the kill ring anyway.  This means that
you can use the killing commands to copy text from a read-only buffer.

This is the primitive for programs to kill text (as opposed to deleting it).
Supply two arguments, character positions indicating the stretch of text
 to be killed.
Any command that calls this function is a \"kill command\".
If the previous command was also a kill command,
the text killed this time appends to the text killed last time
to make one entry in the kill ring.

In Lisp code, optional third arg YANK-HANDLER, if non-nil,
specifies the yank-handler text property to be set on the killed
text.  See `insert-for-yank'."
  ;; Pass point first, then mark, because the order matters
  ;; when calling kill-append.
  (interactive (list (point) (mark)))
  (unless (and beg end)
    (error "The mark is not set now, so there is no region"))
  (condition-case nil
      (let ((string (filter-buffer-substring beg end t)))
        (when string                        ;STRING is nil if BEG = END
          ;; Add that string to the kill ring, one way or another.
          (if (eq last-command 'kill-region)
              (kill-append string (< end beg) yank-handler)
            (kill-new string nil yank-handler)))
        (when (or string (eq last-command 'kill-region))
          (setq this-command 'kill-region))
        nil)
    ((buffer-read-only text-read-only)
     ;; The code above failed because the buffer, or some of the characters
     ;; in the region, are read-only.
     ;; We should beep, in case the user just isn't aware of this.
     ;; However, there's no harm in putting
     ;; the region's text in the kill ring, anyway.
     (copy-region-as-kill beg end)
     ;; Set this-command now, so it will be set even if we get an error.
     (setq this-command 'kill-region)
     ;; This should barf, if appropriate, and give us the correct error.
     (if kill-read-only-ok
         (progn (message "Read only text copied to kill ring") nil)
       ;; Signal an error if the buffer is read-only.
       (barf-if-buffer-read-only)
       ;; If the buffer isn't read-only, the text is.
       (signal 'text-read-only (list (current-buffer)))))))
@end ignore

De Emacs 22 versie van die functie gebruikt @code{condition-case} en
@code{copy-region-as-kill} die wij beide uitleggen. @code{condition-case} is
een belangrijke speciale vorm.

De functie @code{kill-region} in essentie roept @code{condition-case} aan,
die drie argumenten verwacht. Het eerste argument deze functie doet
niets. Het tweede argument bevat de code die het werk doet als alles goed
gaat. Het derde argument bevat de code die aangeroepen wordt in het geval
van een fout.

@menu
* Complete kill-region::     De functiedefinitie.
* condition-case::           Met een probleem omgaan
* Lisp macro::               Lisp macro
@end menu

@ifnottex
@node Complete kill-region
@unnumberedsubsec De complete @code{kill-region} definitie
@end ifnottex

@need 1200
We gaan zo meteen door de code van @code{condition-case}. Laten we eerst
naar de definitie van @code{kill-region} kijken, met toegevoegd commentaar:

@c GNU Emacs 22:
@smallexample
@group
(defun kill-region (beg end)
  "Kill (\"cut\") text between point and mark.
This deletes the text from the buffer and saves it in the kill ring.
The command \\[yank] can retrieve it from there. @dots{} "
@end group

@group
  ;; @bullet{} Omdat volgorde belangrijk is, geeft eerst point door.
  (interactive (list (point) (mark)))
  ;; @bullet{} En vertel ons wanneer we geen tekst kunnen snijden.
  ;; 'unless' is een 'if' zonder een dan-deel.
  (unless (and beg end)
    (error "The mark is not set now, so there is no region"))
@end group

@group
  ;; @bullet{} 'condition-case' verwacht drie argumenten.
  ;;    Wanneer het eerste argument nil is, zoals hier,
  ;;    wordt information over het fout signaal niet
  ;;    bewaard voor gebruik in een andere functie.
  (condition-case nil
@end group

@group
      ;; @bullet{} Het tweede argument van 'condition-case' vertelt de
      ;;    Lisp interpreter wat te doen als alles goed gaat.
@end group

@group
      ;;    Het start met een 'let' functie die de string extraheert
      ;;    en test of die bestaat. Zo ja (dat is wat de
      ;;    'when' checkt), roept het een 'if' functie aan die vaststelt
      ;;    of het vorige commando een andere aanroep was van
      ;;    'kill-region'; zo ja, wordt de nieuwe tekst achter de
      ;;    vorige tekst geplakt; zo niet dan wordt een andere functie,
      ;;    'kill-new', aangeroepen.
@end group

@group
      ;;    De 'kill-append' functie plakken de nieuwe string en
      ;;    de oude aan elkaar. De 'kill-new' functie voegt tekst in als een
      ;;    nieuw item in de killring.
@end group

@group
      ;;    'when' is een 'if' zonder een dan-deel.  De tweede 'when'
      ;;    controleert opnieuw of de bestaande string bestaat;
      ;;    daarnaast, controleert het of het vorige commando een
      ;;    andere aanroep van 'kill-region' was.  Wanneer een van beide
      ;;    condities waar zijn, dan stelt het het huidige commando in
      ;;    op 'kill-region'.
@end group
@group
      (let ((string (filter-buffer-substring beg end t)))
        (when string                    ;STRING is nil if BEG = END
          ;; Voeg die string op of andere manier aan de killring toe.
          (if (eq last-command 'kill-region)
@end group
@group
              ;;    @minus{} 'yank-handler' is een optional argument van
              ;;    'kill-region' dat aan de functies 'kill-append' en
              ;;    'kill-new' hoe om te gaan met eigenschappen toegevoegd
              ;;    aan de tekst, zoals 'bold' of 'italics'.
              (kill-append string (< end beg) yank-handler)
            (kill-new string nil yank-handler)))
        (when (or string (eq last-command 'kill-region))
          (setq this-command 'kill-region))
        nil)
@end group

@group
    ;;  @bullet{} Het derde argument van 'condition-case' vertelt de interpreter
    ;;    hoe om te gaan met een fout.
@end group
@group
    ;;    Het derde argument heeft een condities deel en een body deel.
    ;;    Wanneer aan de condities is voldaan (in dit geval,
    ;;             wanneer tekst of buffer read-only zijn)
    ;;    dan wordt de body uitgevoerd.
@end group
@group
    ;;    The first part of the third argument is the following:
    ((buffer-read-only text-read-only) ;; the if-part
     ;; @dots{}  the then-part
     (copy-region-as-kill beg end)
@end group
@group
     ;;    Vervolgens, dus als deel van het dan-deel, zet this-command, zodat
     ;;    het wordt gebruikt in geval van een fout
     (setq this-command 'kill-region)
     ;;    Tenslotte, in het dan-deel, stuur een boodschap wanneer je de
     ;;    tekst niet naar de the killring kan kopiëren zonder een fout te signaleren
     ;;    maar doe dat niet als je het niet mag.
@end group
@group
     (if kill-read-only-ok
         (progn (message "Read only text copied to kill ring") nil)
       (barf-if-buffer-read-only)
       ;; Als het buffer niet read-only is, is de tekst.
       (signal 'text-read-only (list (current-buffer)))))))
@end group
@end smallexample

@ignore
@c v 21
@smallexample
@group
(defun kill-region (beg end)
  "Kill between point and mark.
The text is deleted but saved in the kill ring."
  (interactive "r")
@end group

@group
  ;; 1. 'condition-case' verwacht drie argumenten.
  ;;    Als het eerste argument nil is, zoals hier,
  ;;    wordt informatie over het foutsignaal niet
  ;;    opgeslagen ter gebruik door een andere functie.
  (condition-case nil
@end group

@group
      ;; 2. The tweede argument voor 'condition-case'
      ;;    vertelt de Lisp interpreter wat te doen als alles goed gaat.
@end group

@group
      ;;    De functie 'delete-and-extract-region' doet meestal het werk.      ;;    Wanneer het begin en eind van de region hetzelfde zijn,      ;;    dan is de variable 'string' leeg of nil
      (let ((string (delete-and-extract-region beg end)))
@end group

@group
        ;; 'when' is an 'if' clause that cannot take an 'else-part'.
        ;; Emacs normally sets the value of 'last-command' to the
        ;; previous command.
@end group
@group
        ;; 'kill-append' plakt de nieuwe en de oude string aan elkaar.
        ;; 'kill-new' voegt tekst in in een item in de killring.
        (when string
          (if (eq last-command 'kill-region)
              ;; wanneer waar, append string
              (kill-append string (< end beg))
            (kill-new string)))
        (setq this-command 'kill-region))
@end group

@group
    ;; 3. Het derde argument van 'condition-case' vertelt de interpreter
    ;;    hoe met een fout om te gaan.
@end group
@group
    ;;    Het derde argument heeft een condities deel en een body deel.
    ;;    Wanneer aan de condities is voldaan (in dit geval,
    ;;             wanneer tekst of buffer read-only zijn)
    ;;    dan wordt de body uitgevoerd.
@end group
@group
    ((buffer-read-only text-read-only) ;; dit is het if-deel
     ;; then...
     (copy-region-as-kill beg end)
@end group
@group
     (if kill-read-only-ok            ;; deze variabele is meestal nil
         (message "Read only text copied to kill ring")
       ;; anders, signaleer een fout als het buffer read-only is;
       (barf-if-buffer-read-only)
       ;; en, in ieder geval, signaleer dat de text read-only is.
       (signal 'text-read-only (list (current-buffer)))))))
@end group
@end smallexample
@end ignore

@node condition-case
@subsection @code{condition-case}
@findex condition-case

Wanneer de Emacs Lisp interpreter problemen heeft met het evalueren van een
expressie dat geeft het je hulp, zoals we eerder gezien hebben
(@pxref{Fouten maken, , Een foutboodschap genereren}). In het jargon heet
dit ``een fout signaleren''. Meestal stopt de computer het programma en
toont je een boodschap.

Sommige programma's voeren echter gecompliceerde acties uit. Zij moeten bij
een fout niet stoppen. In de functie @code{kill-region} is de meest voor de
hand liggende fout dat je probeert tekst te killen die read-only is en niet
kan worden verwijderd. De functie @code{kill-region} bevat daarom code om
met deze situatie om te gaan. Deze code in de body van de functie
@code{kill-region} bevindt zich in een speciale vorm @code{condition-case}.

@need 800
Het sjabloon voor @code{condition-case} ziet er zo uit:

@smallexample
@group
(condition-case
  @var{var}
  @var{bodyform}
  @var{error-handler}@dots{})
@end group
@end smallexample

Het tweede argument, @var{bodyform} is eenvoudig. De speciale vorm
@code{condition-case} laat de Lisp interpreter de code in @var{bodyform}
evalueren.

Kort gezegd, het @var{bodyform}-deel van een @code{condition-case} expressie
bepaalt wat moet gebeuren wanneer alles correct werkt.

Echter, wanneer een fout optreedt, definieert de functie, die naast zijn
andere activiteiten het foutsignaal genereert, een of meer conditienamen.

Een error-handler is het derde argument van @code{condition-case}. Een
error-handler heeft twee delen, een @var{conditienaam} en een
@var{body}. Wanneer het @var{conditienaam}-deel van de error-handler
overeenkomt met de conditienaam gegeneerd door een fout, dan wordt het
@var{body}-deel van de error-handler uitgevoerd.

Zoals je zou verwachten kan het @var{conditienaam}-deel van de error-handler
een enkele conditienaam zijn of een lijst met conditienamen.

Een complete @code{condition-case} expressie kan dus meer dan één
error-handler bevatten. Wanneer een fout optreedt, wordt de eerst toepasbare
handler uitgevoerd.

Tenslotte, het eerste argument van de @code{condition-case} expressie, het
@var{var} argument is soms gebonden aan een variabele die informatie over de
fout bevat. Wanneer dat argument echter @code{nil} is, zoals dat bij
@code{kill-region} het geval is, wordt die informatie genegeerd.

@need 1200
In het kort, in de functie @code{kill-region} werkt de code
@code{condition-case} als volgt:

@smallexample
@group
@var{If geen errors}, @var{voer alleen deze code uit}
    @var{maar}, @var{if errors}, @var{voer deze andere code uit}.
@end group
@end smallexample

@ignore
2006 Oct 24
In Emacs 22,
copy-region-as-kill is short, 12 lines, and uses
filter-buffer-substring, which is longer, 39 lines
and has delete-and-extract-region in it.
delete-and-extract-region is written in C.

see Initializing a Variable with @code{defvar}
this is line 8054
Initializing a Variable with @code{defvar} includes line 8350
@end ignore

@node Lisp macro
@subsection Lisp macro
@cindex Macro, lisp
@cindex Lisp macro

Het deel van de @code{condition-case} expressie die wordt geëvalueerd in de
verwachting dat alles goed gaat heeft een @code{when}. De code stelt met
@code{when} of de variabele @code{string} naar bestaande tekst wijst.

Een @code{when}-expressie maakt het de programmeur makkelijker. Het is als
een @code{if}, zonder de mogelijkheid van een anders-clausule. In je
gedachten kun je @code{when} met @code{if} vervangen om te begrijpen wat er
gebeurt. Dat is wat de Lisp interpreter doet.

Technisch gesproken is @code{when} een Lisp macro. Een Lisp macro stelt je
in staat nieuwe control-constructies en andere taaleigenschappen te
definieren. Het vertelt de interpreter hoe het een andere Lisp expressie te
berekenen die op zijn beurt de waarde berekend. In dit geval is de andere
expressie een @code{if} expressie.

De @code{kill-region} functiedefinitie heeft ook een @code{unless}
macro. Dit is het tegenovergestelde van @code{when}. De @code{unless} macro
is net als @code{if}, behalve dat het geen dan-clausule heeft, en het
verstrekt daarvoor een impliciete @code{nil}.

Voor meer over Lisp macro's, zie @ref{Macros, , Macros, elisp, The GNU Emacs
Lisp Reference Manual}. De programmeertaal C vertrekt ook macro's. Deze zijn
anders, maar ook nuttig.

@ignore
We will briefly look at C macros in
@ref{Digression into C}.
@end ignore

@need 1200
Ten aanzien van de @code{when} macro, wanneer de string in de
@code{condition-case} expressie een inhoud heeft, dat wordt een andere
conditionele expressie uitgevoerd. Dit is een @code{if} met zowel een
dan-deel en een anders-deel. 

@smallexample
@group
(if (eq last-command 'kill-region)
    (kill-append string (< end beg) yank-handler)
  (kill-new string nil yank-handler))
@end group
@end smallexample

Het dan-deel wordt geëvalueerd wanneer het voorgaande commando een andere
aanroep van @code{kill-region} was. Zo niet, dan wordt het anders-deel
geëvalueerd.

@code{yank-handler} is een optioneel argument voor @code{kill-region} dat
aan de functies @code{kill-append} en @code{kill-new} vertelt hoe het met de
eigenschappen moet omgaan die aan de tekst zijn gekoppeld, zoals bold of
italics.

@code{last-command} is een variabele in Emacs die we nog niet eerder gezien
hebben. Steeds wanneer een functie wordt uitgevoerd, stelt Emacs Normaal
gesproken de waarde van @code{last-command} in op het voorgaande commando.

@need 1200
In dit segment van de definitie controleert de @code{if} expressie of het
voorgaande commando @code{kill-region} was. Zo ja, plakt

@smallexample
(kill-append string (< end beg) yank-handler)
@end smallexample

@noindent
een kopie van de nieuw geclipte tekst aan de voorgaande zojuist geclipte
tekst in de killring.

@node copy-region-as-kill
@section @code{copy-region-as-kill}
@findex copy-region-as-kill
@findex nthcdr

De functie @code{copy-region-as-kill} kopieert een region met tekst van een
buffer en (via hetzij @code{kill-append} of @code{kill-new}) bewaart het in
de @code{kill-ring}.

Wanneer je @code{copy-region-as-kill} meteen na een @code{kill-region}
commando aanroept, plakt Emacs de nieuw gekopieerde tekst aan de voorgaande
gekopieerde tekst. Dit betekent dat als je de tekst terug-yankt, je alles
krijgt, van zowel deze als de voorgaande operatie. Anderzijds, wanneer een
ander commando aan de @code{copy-region-as-kill} voorafging, dan kopieert de
functie de tekst in een separaat item in de killring.

@menu
* Complete copy-region-as-kill::  De complete functiedefinitie.
* copy-region-as-kill body::  De body van @code{copy-region-as-kill}.
@end menu

@ifnottex
@node Complete copy-region-as-kill
@unnumberedsubsec De complete @code{copy-region-as-kill} functiedefinitie
@end ifnottex

@need 1200
Hier is de complete tekst van de versie 22 @code{copy-region-as-kill}
functie.

@smallexample
@group
(defun copy-region-as-kill (beg end)
  "Save the region as if killed, but don't kill it.
In Transient Mark mode, deactivate the mark.
If `interprogram-cut-function' is non-nil, also save the text for a window
system cut and paste."
  (interactive "r")
@end group
@group
  (if (eq last-command 'kill-region)
      (kill-append (filter-buffer-substring beg end) (< end beg))
    (kill-new (filter-buffer-substring beg end)))
@end group
@group
  (if transient-mark-mode
      (setq deactivate-mark t))
  nil)
@end group
@end smallexample

@need 800
Zoals gebruikelijk kan deze functie worden gedeeld in componenten:

@smallexample
@group
(defun copy-region-as-kill (@var{argument-list})
  "@var{documentatie}@dots{}"
  (interactive "r")
  @var{body}@dots{})
@end group
@end smallexample

De argumenten zijn @code{beg} en @code{end} en de functie is interactief met
@code{"r"}, dus de twee argumenten moeten refereren aan het begin en eind
van de region. Wanneer je dit document van het begin hebt gelezen, dan is
het begrijpen van deze delen van een functie al bijna routine.

De documentatie is ietwat verwarrend tenzij je herinnert dat het woord
``kill'' een andere betekenis dan gebruikelijk heeft. De Transient Mark en
@code{interprogram-cut-function} commentaren verhelderen bepaalde
zij-effecten.

Nadat je ooit een mark hebt gezet, bevat een buffer altijd een
region. Wanneer je dat wilt, kan je met Transient Mark de region tijdelijk
highlighten. (Niemand wil de region voortdurend gehighlight hebben, dus
Transient Mark mode highlight het alleen op passende momenten. Veel mensen
zetten Transient Mark mode uit, waardoor de region nooit wordt gehighlight.)

Ook kun je in windowing systemen tussen verschillende programma's kopiëren,
snijden en plakken. In het X windowing system bijvoorbeeld is de functie
@code{interprogram-cut-function} @code{x-select-text}, die met het
equivalent voor de Emacs killring van het windowing systeem werkt.

The body of the @code{copy-region-as-kill} function starts with an @code{if}
clause.  What this clause does is distinguish between two different
situations: whether or not this command is executed immediately after a
previous @code{kill-region} command.  In the first case, the new region is
appended to the previously copied text.  Otherwise, it is inserted into the
beginning of the kill ring as a separate piece of text from the previous
piece.

De laatste twee regels van de functie voorkomen highighting van de region
wanneer Transient Mark mode aan staat.

De body van @code{copy-region-as-kill} is bespreking in detail waard.

@node copy-region-as-kill body
@subsection De body van @code{copy-region-as-kill}

De functie @code{copy-region-as-kill} werkt op een vergelijkbare manier als
de functie @code{kill-region}. Beide zijn zo geschreven dat twee of meer
kills op een rij de tekst in een enkele entry combineren. Wanneer je de
tekst van de killring terugyankt, dan krijg alles in een stuk. Bovendien,
kills die voorwaarts vanaf de huidige cursorpositie bewegen worden
toegevoegd aan het einde van de vorige gekopieerde tekst, en commando's die
tekst achterwaarts kopiëren worden aan het begin van de vorige gekopieerde
tekst toegevoegd. Op deze manier blijven de woorden in tekst op de juiste
volgorde.

Net als @code{kill-region}, maakt de functie @code{copy-region-as-kill}
gebruik van de variabele @code{last-command} die het vorige Emacs commando
bijhoudt.

@menu
* last-command en this-command::  last-command en this-command
* kill-append functie::      kill-append functie
* kill-new functie::         kill-new functie
@end menu

@ifnottex
@node last-command en this-command
@unnumberedsubsubsec @code{last-command} en @code{this-command}
@end ifnottex

Wanneer een functie wordt uitgevoerd, stelt Emacs normaalgesproken de waarde
van @code{this-command} in op de functie die wordt uitgevoerd (wat in dit
geval @code{copy-region-as-kill} zou zijn). Tegelijkertijd stelt Emacs de
waarde van @code{last-command} in op de vorige waarde van
@code{this-command}.

In het eerste deel van de body van de functie @code{copy-region-as-kill}
stelt een @code{if} expressie vast of @code{kill-region} de waarde van
@code{last-command} is. Zo ja, dan wordt het dan-deel van de @code{if}
expressie geëvalueerd. Het gebruikt de functie @code{kill-append} om de
tekst die bij deze aanroep gekopieerd is te plakken aan de tekst die al in
het eerste element (the @sc{car}) van de killring staat. Anders, wanneer de
waarde van de @code{last-command} niet @code{kill-region} is, dan voegt de
functie @code{copy-region-as-kill} met functie @code{kill-new} een nieuw
element aan de killring toe.

@need 1250
De @code{if} expressie is als volgt, met @code{eq}:

@smallexample
@group
  (if (eq last-command 'kill-region)
      ;; @r{dan-deel}
      (kill-append  (filter-buffer-substring beg end) (< end beg))
    ;; @r{anders-deel}
    (kill-new  (filter-buffer-substring beg end)))
@end group
@end smallexample

@findex filter-buffer-substring
(De functie @code{filter-buffer-substring} geeft een gefilterde substring
van het buffer, wanneer die er is. Optioneel---de argumenten zijn hier niet,
dus geen enkele wordt uitgevoerd---kan de functie de initiële tekst deleten
of de tekst zonder eigenschappen teruggeven. Deze functie is een vervanging
voor de oudere functie @code{buffer-substring} die al bestond voordat
tekst-eigenschappen werden geïmplementeerd.)

@findex eq @r{(voorbeeld van gebruik)}
@noindent
De functie @code{eq} test of het eerste argument hetzelfde Lisp object is
als het tweede argument. De functie @code{eq} test net als de functie
@code{equal} voor gelijkheid, met het verschil dat deze vaststelt of twee
representaties daadwerkelijk hetzelfde object in de computer zijn, maar met
verschillende namen. @code{equal} stelt vast of de structuur en inhoud van
twee expressies hetzelfde zijn.

Wanneer @code{kill-region} het voorgaande commando was, dan roept de Emacs
Lisp interpreter de functie @code{kill-append} aan.

@node kill-append functie
@unnumberedsubsubsec De functie @code{kill-append}
@findex kill-append

@need 800
De functie @code{kill-append} ziet er zo uit:

@c in GNU Emacs 22
@smallexample
@group
(defun kill-append (string before-p &optional yank-handler)
  "Append STRING to the end of the latest kill in the kill ring.
If BEFORE-P is non-nil, prepend STRING to the kill.
@dots{} "
  (let* ((cur (car kill-ring)))
    (kill-new (if before-p (concat string cur) (concat cur string))
              (or (= (length cur) 0)
                  (equal yank-handler
                         (get-text-property 0 'yank-handler cur)))
              yank-handler)))
@end group
@end smallexample

@ignore
was:
(defun kill-append (string before-p)
  "Append STRING to the end of the latest kill in the kill ring.
If BEFORE-P is non-nil, prepend STRING to the kill.
If `interprogram-cut-function' is set, pass the resulting kill to
it."
  (kill-new (if before-p
                (concat string (car kill-ring))
              (concat (car kill-ring) string))
            t))
@end ignore

@noindent
De functie @code{kill-append} is redelijk eenvoudig. Het gebruikt de functie
@code{kill-new}, zie we straks in meer detail bespreken.

(De functie verschaft ook een optioneel argument die @code{yank-handler}
heet. wanneer aangeroepen vertelt dit argument de functie hoe het met
eigenschappen van de tekst moet omgaan, zoals bold of italics.)

@c !!! bug in GNU Emacs 22 version of  kill-append ?
Het heeft een functie @code{let*} om de waarde van het eerste element van de
killring in te stellen op @code{cur}. (Ik weet niet waarom de functie in
plaats hiervan geen @code{let} gebruikt, slechts één waarde wordt in de
expressie ingesteld. Misschien dat dit een bug is die geen problemen
veroorzaakt?)

Bekijk de conditional die een van de twee argumenten van @code{kill-new}
is. Het gebruikt @code{concat} om de nieuwe tekst aan de @sc{car} van de
kill ring te plakken. Of het vooraan of achteraan de tekst plakt hangt af
van het resultaat van een @code{if} expressie:

@smallexample
@group
(if before-p                            ; @r{if-deel}
    (concat string cur)                 ; @r{dan-deel}
  (concat cur string))                  ; @r{anders-deel}
@end group
@end smallexample

@noindent
Wanneer de region die gekilled wordt vooraf gaat aan de region die in het
vorige commando was gekilled, dan moet het vooraan het materiaal dat in de
vorige kill was bewaard komen en, omgekeerd, wanneer de gekillde tekst volgt
op wat zojuist was gekilled, dan moet het achter die voorgaande tekst
komen. De @code{if} expressie is afhankelijk van het predikaat
@code{before-p} om te bepalen of het de nieuwe bewaarde tekst voor of achter
de voorgaande bewaarde tekst moet plaatsen.

Het symbool @code{before-p} is de naam van een van de argumenten van
@code{kill-append}. Het evalueren van de functie @code{kill-append} bindt
die aan de waarde teruggegeven door de evaluatie van het argument. In dit
geval de expressie @code{(< end beg)}. Deze expressie stelt niet direct vast
of de gekillde tekst voor of na de kill-tekst van het vorige commando
staat. Het stelt vast of de waarde van de variabele @code{end} kleiner is
dan de waarde van de variabele @code{beg}. Wanneer dat zo is, betekent dit
dat de gebruiker hoogstwaarschijnlijk richting het begin van het buffer
beweegt. Het resultaat van het evalueren van de predikaat-expressie,
@code{(< end beg)}, is daardoor waar, en de tekst wordt voor de voorgaande
tekst geplakt. Wanneer anderzijds de waarde van de variabele @code{end}
groter is dan de waarde van de variabele @code{beg}, wordt de tekst aan het
eind van de voorgaande tekst geplakt.

@need 800
Wanneer de nieuw opgeslagen tekst aan de voorzijde komt, wordt de string met
de nieuwe tekst voor de oude tekst geplakt.

@smallexample
(concat string cur)
@end smallexample

@need 1200
@noindent
Maar als de tekst aan de achterzijde komt, wordt de string achter de oude
tekst geplakt.

@smallexample
(concat cur string))
@end smallexample

Om te begrijpen hoe dit werkt, moeten we eerst de functie @code{concat}
bekijken. De functie @code{concat} knoopt twee strings aan elkaar of
verenigt die. Het resultaat is een string. Bijvoorbeeld:

@smallexample
@group
(concat "abc" "def")
     @result{} "abcdef"
@end group

@group
(concat "nieuw "
        (car '("eerste element" "tweede element")))
     @result{} "nieuw eerste element"

(concat (car
        '("eerste element" "tweede element")) " aangepast")
     @result{} "eerste element aangepast"
@end group
@end smallexample

We begrijpen nu @code{kill-append}: het past de inhoud van de killring
aan. De killring is een lijst, elk element daarvan is opgeslagen tekst. De
functie @code{kill-append} gebruikt de functie @code{kill-new} die op zijn
beurt de functie @code{setcar} gebruikt.

@node kill-new functie
@unnumberedsubsubsec De functie @code{kill-new}
@findex kill-new

@need 1200
In versie 22 ziet de functie @code{kill-new} er zo uit:

@smallexample
@group
(defun kill-new (string &optional replace yank-handler)
  "Make STRING the latest kill in the kill ring.
Set `kill-ring-yank-pointer' to point to it.
If `interprogram-cut-function' is non-nil, apply it to STRING.
Optional second argument REPLACE non-nil means that STRING will replace
the front of the kill ring, rather than being added to the list.
@dots{}"
@end group
@group
  (if (> (length string) 0)
      (if yank-handler
          (put-text-property 0 (length string)
                             'yank-handler yank-handler string))
    (if yank-handler
        (signal 'args-out-of-range
                (list string "yank-handler specified for empty string"))))
@end group
@group
  (if (fboundp 'menu-bar-update-yank-menu)
      (menu-bar-update-yank-menu string (and replace (car kill-ring))))
@end group
@group
  (if (and replace kill-ring)
      (setcar kill-ring string)
    (push string kill-ring)
    (if (> (length kill-ring) kill-ring-max)
        (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
@end group
@group
  (setq kill-ring-yank-pointer kill-ring)
  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample
@ignore
was:
(defun kill-new (string &optional replace)
  "Make STRING the latest kill in the kill ring.
Set the kill-ring-yank pointer to point to it.
If `interprogram-cut-function' is non-nil, apply it to STRING.
Optional second argument REPLACE non-nil means that STRING will replace
the front of the kill ring, rather than being added to the list."
  (and (fboundp 'menu-bar-update-yank-menu)
       (menu-bar-update-yank-menu string (and replace (car kill-ring))))
  (if (and replace kill-ring)
      (setcar kill-ring string)
    (setq kill-ring (cons string kill-ring))
    (if (> (length kill-ring) kill-ring-max)
        (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
  (setq kill-ring-yank-pointer kill-ring)
  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))
@end ignore

(Merk op dat de functie niet interactief is.)

Zoals gebruikelijk kijken we naar de functie in delen.

De functiedefinitie heeft een optioneel argument @code{yank-handler}, dat
wanneer het aangeroepen wordt vertelt hoe het met de eigenschappen van de
tekst moet omgaan, zoals bold of italics. Dit slaan we over.

@need 1200
De eerste regel van de documentatie is logisch:

@smallexample
Make STRING the latest kill in the kill ring.
@end smallexample

@noindent
Laten voor dit moment de rest van de documentatie overslaan.

@noindent
Laten we ook de initiële @code{if} expressie overslaan en die regels code
met betrekking tot @code{menu-bar-update-yank-menu}. Die leggen we hieronder
uit.

@need 1200
De kritische regels zijn deze:

@smallexample
@group
  (if (and replace kill-ring)
      ;; @r{dan}
      (setcar kill-ring string)
@end group
@group
    ;; @r{anders}
    (push string kill-ring)
@end group
@group
    (if (> (length kill-ring) kill-ring-max)
        ;; @r{voorkom een te lange kill ring}
        (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
@end group
@group
  (setq kill-ring-yank-pointer kill-ring)
  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample

De conditionele test is @w{@code{(and replace kill-ring)}}. Deze is waar
wanneer twee condities voldoen: de killring bevast iets en de variabele
@code{replace} variable is waar.

@need 1250
Wanneer de functie @code{kill-append} @code{kill-append} op waar instelt en
wanneer de killring tenminste een element bevat, wordt de @code{setcar}
expressie uitgevoerd:

@smallexample
(setcar kill-ring string)
@end smallexample

De functie @code{setcar} wijzigt daadwerkelijk het eerste element van de
@code{kill-ring} lijst in de waarde van @code{string}. Het vervangt het
eerste element.

@need 1250
Aan de andere kant, wanneer de killring leeg, of replace onwaar is, wordt
het anders-deel van de conditie uitgevoerd:

@smallexample
(push string kill-ring)
@end smallexample

@noindent
@need 1250
@code{push} plaatst het eerste argument op het tweede. Het is vergelijkbaar
met het oudere

@smallexample
(setq kill-ring (cons string kill-ring))
@end smallexample

@noindent
@need 1250
of het nieuwere

@smallexample
(add-to-list kill-ring string)
@end smallexample

@noindent
Wanneer het onwaar is, construeert de expressie eerst een nieuwe versie van
de killring door @code{string} vooraan als nieuw element aan de bestaande
killring te plaatsen (dat is wat de @code{push} doet.) Daarna voert het een
tweede @code{if}-clausule uit. Deze tweede @code{if}-clausule voorkomt dat
de killring te groot groeit.

Laten we  in volgorde naar deze twee expressies kijken.

De @code{push} regel in het anders-deel stelt de nieuwe waarde van de kill
ring in op wat het resultaat is van het aan de oude killring toevoegen van
de gekillde string.

We zijn hoe dit werkt aan de hand van een voorbeeld.

@need 800
Eerst

@smallexample
(setq voorbeeldlijst '("hier is een clausule" "andere clausule"))
@end smallexample

@need 1200
@noindent
Na het evalueren van deze expressie met @kbd{C-x C-e}, evalueer je
@code{voorbeeldlijst} en kijk naar wat die teruggeeft.

@smallexample
@group
voorbeeldlijst
     @result{} ("hier is een clausule" "andere clausule")
@end group
@end smallexample

@need 1200
@noindent
We voegen nu een nieuw element toe aan deze lijst door de volgende expressie
te evalueren:
@findex push@r{, voorbeeld}

@smallexample
(push "een derde clausule" voorbeeldlijst)
@end smallexample

@need 800
@noindent
Wanneer we @code{voorbeeldlijst} evalueren, ontdekken we dat zijn waarde is:

@smallexample
@group
voorbeeldlijst
     @result{} ("een derde clausule" "hier is een clausule" "andere clausule")
@end group
@end smallexample

@noindent
De derde clausule is dus door @code{push} toegevoegd aan de lijst.

@need 1200
Nu het tweede deel van de @code{if} clausule. Deze expressie voorkomt dat de
killring te groot groeit. Het ziet er zo uit:

@smallexample
@group
(if (> (length kill-ring) kill-ring-max)
    (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
@end group
@end smallexample

De code controleert of de lengte va de killring groter is dan de maximum
toegestane lengte. Dit is de waarde van @code{kill-ring-max} (die standaard
120 is). Wanneer de lengte van de kill ring te groot is, dan stelt deze code
het laatste element van de killring in op @code{nil}. Het doet dit met twee
functies, @code{nthcdr} and @code{setcdr}.

We keken eerder naar @code{setcdr}, (@pxref{setcdr, , @code{setcdr}}). Het
zet de @sc{cdr} van een lijst, net als @code{setcar} de @sc{car} van de
lijst zet. In dit geval echter zet @code{setcdr} niet de de @sc{cdr} van de
gehele killring, de functie @code{nthcdr} zorgt dat het de @sc{cdr} van het
een-na-laatste element van de killring zet---dit betekent dat omdat de
@sc{cdr} van het een-na-laatste element het laatste element van de killring
is, het het laatste element van de killring zal zetten.

@findex nthcdr@r{, voorbeeld}
De functie @code{nthcdr} werkt door herhaaldelijk de @sc{cdr} van een lijst
te nemen---het neemt de @sc{cdr} van de @sc{cdr} van de @sc{cdr} @dots{} Het
doet dit @var{N} keer en geeft dan het resultaat terug. (@xref{nthcdr, ,
@code{nthcdr}}.)

@findex setcdr@r{, voorbeeld}
Dus als we een lijst met vier elementen hebben die drie elementen lang
behoort te zijn, kunnen we de @sc{cdr} van het een-na-laatste element op
@code{nil} zetten en daardoor de lijst korter maken. (Wanneer je het laatste
element op iets anders dan @code{nil} zet, wat je kunt doen, dan zou je
lijst niet korter gemaakt hebben. @xref{setcdr, , @code{setcdr}}.)

Je kan dit inkorten zien door de volgende drie expressies beurtelings te
evalueren. Eerst zet je de waarde van @code{bomen} op @code{esdoorn eik spar
berk}, daarna zet je de @sc{cdr} van zijn tweede @sc{cdr} op @code{nil} en
vindt de waarde van @code{bomen}.

@smallexample
@group
(setq bomen (list 'esdoorn 'eik 'spar 'berk))
      @result{} (esdoorn eik spar berk)
@end group

@group
(setcdr (nthcdr 2 bomen) nil)
     @result{} nil

bomen
      @result{} (esdoorn eik spar)
@end group
@end smallexample

@noindent
(De waarde teruggeven door de @code{setcdr} expressie is @code{nil} omdat
dat is waarop de @sc{cdr} is gezet.)

Nogmaals, in @code{kill-new}, neemt de functie @code{nthcdr} een aantal keer
de @sc{cdr}, één minder dan de maximaal toegestane grootte van de killring
en de @code{setcdr} zet de @sc{cdr} van dat element (wat de rest van de
elementen in de killring is) op @code{nil}. Dit voorkomt dat de killring te
groot groeit.

@need 800
De een-na-laatste expressie in de kill ring is

@smallexample
(setq kill-ring-yank-pointer kill-ring)
@end smallexample

De @code{kill-ring-yank-pointer} is een globale variabele die is ingesteld
om de @code{kill-ring} te zijn.

Ondanks dat de @code{kill-ring-yank-pointer} een @code{pointer} heet, is het
een variabele net als de killring. De naam is echter gekozen om mensen te
helpen begrijpen hoe de variabele wordt gebruikt.

@need 1200
Nu gaan we terug naar een expressie in het begin van de body van de functie:

@smallexample
@group
  (if (fboundp 'menu-bar-update-yank-menu)
       (menu-bar-update-yank-menu string (and replace (car kill-ring))))
@end group
@end smallexample

@noindent
Het begint met een @code{if} expressie

In dit geval test de expressie eerst of de functie
@code{menu-bar-update-yank-menu} bestaat en zo ja, roept die aan. De functie
@code{fboundp} geeft waar terug wanneer het symbool dat het test een
functiedefinitie heeft die niet leeg is. Wanneer de functiedefinitie van het
symbool leeg is, krijgen we een foutmelding, zoals we die kregen toen we
expres fouten maakten (@pxref{Fouten maken, , Een foutboodschap genereren}).

@noindent
Het dan-deel bevat een expressie wiens eerste argument de functie @code{and}
is.

@findex and
De speciale vorm @code{and} evalueert elk van zijn argumenten totdat een van
de argumenten de waarde @code{nil} teruggeeft, in welk geval de @code{and}
expressie @code{nil} teruggeeft. Wanneer echter geen van de argumenten een
waarde @code{nil} teruggeven, dan wordt de waarde afkomstig van de evaluatie
van het laatste argument teruggegeven. (Omdat zo'n waarde niet @code{nil}
is, wordt het in Emacs Lisp beschouwd als waar.) Met andere woorden, een
@code{and} expressie geeft alleen waar terug als al zijn argumenten waar
zijn. (@xref{Tweede buffer gerelateerde terugblik}.)

De expressie stelt vast of het tweede argument van
@code{'menu-bar-update-yank-menu} waar is of niet.
@ignore
    ;; If we're supposed to be extending an existing string, and that
    ;; string really is at the front of the menu, then update it in place.
@end ignore

@code{menu-bar-update-yank-menu} is een van de functies die het mogelijk
maken om het ``Select and Paste'' menu in het Edit-item in de menubar te
gebruiken. Met de muis kan je zien elke verschillende stukken tekst je hebt
opgeslagen en een stuk selecteren om te pasten.

De laatste expressie in de functie @code{kill-new} voegt de nieuw
gekopieerde string toe aan wat voor faciliteit dan ook bestaat voor het
kopiëren en plakken tussen de verschillende programma's die in het windowing
systeem draaien. In het X windowing systeem bijvoorbeeld, pakt de functie
@code{x-select-text} de string op en bewaart die in het geheugen dat X@
bewerkt. Je kan de string in een andere programma pasten, zoals een Xterm.

@need 1200
De expressie ziet er zo uit:

@smallexample
@group
  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample

Wanneer een @code{interprogram-cut-function} bestaat, dan voert Emacs
@code{funcall} uit, die op zijn beurt het eerste argument als een functie
aanroept en de resterende argumenten daar aan doorgeeft. (Overigens, voor
zover ik het kan zien, kan de @code{if}-expressie vervangen worden door een
@code{and} expressie vergelijkbaar met die in het eerste deel van de
functie.)

We bepreken verder geen windowing systems en andere programma's, maar merken
slechts op dat dit een mechanisme is dat het GNU Emacs mogelijk maakt om
makkelijk en goed met andere programma's samen te werken.

De code voor het plaatsen van de tekst in de killring, hetzij geplakt aan
een bestaand element hetzij als een nieuw element, leidt ons naar de code om
de verwijderde tekst terug te halen---het yank commando. Voordat we het yank
commando gaan bespreken, is het echter beter te ontdekken hoe lijsten in de
computer zijn geïmplementeerd. Dit verheldert mysteries zoals het gebruik
van de term ``pointer''. Maar voor we dat doen, weiden we uit naar C.

@ignore
@c is this true in Emacs 22?   Does not seems to be

  (If the @w{@code{(< end beg))}}
expression is true, @code{kill-append} prepends the string to the just
previously clipped text.  For a detailed discussion, see
@ref{kill-append function, , The @code{kill-append} function}.)

If you then yank back the text, i.e., paste it, you get both
pieces of text at once.  That way, if you delete two words in a row,
and then yank them back, you get both words, in their proper order,
with one yank.  (The @w{@code{(< end beg))}} expression makes sure the
order is correct.)

On the other hand, if the previous command is not @code{kill-region},
then the @code{kill-new} function is called, which adds the text to
the kill ring as the latest item, and sets the
@code{kill-ring-yank-pointer} variable to point to it.
@end ignore
@ignore

@c Evidently, changed for Emacs 22. The zap-to-char command does not
@c use the delete-and-extract-region function

2006 Oct 26, the Digression into C is now OK but should come after
copy-region-as-kill and filter-buffer-substring

2006 Oct 24
In Emacs 22,
copy-region-as-kill is short, 12 lines, and uses
filter-buffer-substring, which is longer, 39 lines
and has delete-and-extract-region in it.
delete-and-extract-region is written in C.

see Initializing a Variable with @code{defvar}
@end ignore

@node Uitwijding naar C
@section Uitwijding naar C
@findex delete-and-extract-region
@cindex C, een uitweiding naar
@cindex Uitwijding naar C

De functie @code{copy-region-as-kill} function (@pxref{copy-region-as-kill,
, @code{copy-region-as-kill}}) gebruikt de functie
@code{filter-buffer-substring}, die op zijn beurt de functie
@code{delete-and-extract-region} gebruikt. Het verwijdert de inhoud van een
region en die kun je niet terugkrijgen.

In tegenstelling tot andere code die we hier besproken hebben, is de functie
@code{delete-and-extract-region} niet in Emacs Lisp geschreven, het is
geschreven in C en is een van de primitieven van het GNU Emacs
systeem. Omdat het erg eenvoudig is, dwaal ik even af van Lisp en beschrijf
het hier.

@need 1500
Net als veel van de andere Emacs primitieven, is
@code{delete-and-extract-region} geschreven als een C macro, een macro die
een sjabloon voor code is. De complete macro ziet er zo uit:

@c This is a copy of editfns.c's DEFUN for delete-and-extract-region.
@smallexample
@group
DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
       Sdelete_and_extract_region, 2, 2, 0,
       doc: /* Delete the text between START and END and return it.  */)
  (Lisp_Object start, Lisp_Object end)
@{
  validate_region (&start, &end);
  if (XFIXNUM (start) == XFIXNUM (end))
    return empty_unibyte_string;
  return del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1);
@}
@end group
@end smallexample

Zonder verder op de details van het schrijven van macro's in te gaan, wil ik
er op wijzen dat de macro start met het woord @code{DEFUN}. Het woord
@code{DEFUN} was gekozen omdat de code hetzelfde doel dient als @code{defun}
in Lisp. (De C macro @code{DEFUN} is gedefinieerd in
@file{emacs/src/lisp.h}.)

Het woord @code{DEFUN} wordt gevolgd door zeven delen binnen haakjes:

@itemize @bullet
@item
Het eerste deel is de naam die de functie in Lisp krijgt,
@code{delete-and-extract-region}.

@item
Het tweede deel is de naam van de functie in C,
@code{Fdelete_and_extract_region}. Volgens de conventie begint die met een
@samp{F}. Omdat C geen streepjes in namen gebruikt, zijn in plaats daarvan
underscores gebruikt.

@item
Het derde deel is de naam van de C constant structure die informatie over de
deze functie opslaat voor intern gebruik. Het is de naam van de functie in C
maar begint met een @samp{S} in plaats van een @samp{F}.

@item
Het vierde en vijfde deel specificeren het minimum en maximum aantal
argumenten dat de functie kan krijgen. Deze functie vereist precies 2
argumenten.

@item
Het zesde deel is bijna hetzelfde als het argument dat volgt op de
@code{interactive} declaratie in een functie geschreven in Lisp: een letter,
misschien gevold door een prompt. Het enige verschil met Lisp is wanneer de
macro zonder argumenten wordt aangeroepen. Dan schrijf je een @code{0} (wat
een null-string is) zoals in deze macro.

Wanneer je argumenten specificeert, dan zet je die tussen
aanhalingstekens. De C macro voor @code{goto-char} bevat @code{"NGoto char:
"} op deze plek om aan te gevne dat de functie een raw prefix verwacht, in
dit geval een numerieke lokatie in het buffer, en een prompt verschaft.

@item
Het zevende deel is een documentatiestring, net zoals voor een functie
geschreven in Emacs Lisp. Dit is geschreven als C commentaar. (Wanneer je
Emacs bouwt extraheert het programma @command{lib-src/make-docfile} deze
commentaren en gebruikt die om de documentatie te maken.)
@end itemize

@need 1200
In een C macro komen de formele parameters daarna, met een statement over
het soort object dat ze zijn, gevolgd door de body van de macro. Voor
@code{delete-and-extract-region} bestaat de body uit de volgende vier
regels:

@smallexample
@group
validate_region (&start, &end);
if (XFIXNUM (start) == XFIXNUM (end))
  return empty_unibyte_string;
return del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1);
@end group
@end smallexample

De functie @code{validate_region} controleert of de waarden die als begin en
eind zijn doorgegeven, van het juiste type en binnen de range zijn.

De functie @code{del_range_1} verwijdert daadwerkelijk de tekst. Het is een
complexe functie waar we niet naar kijken. Het update het buffer en doet
andere dingen. Echter het is het waard te kijken naar de twee argumenten die
doorgeven worden aan @code{del_range_1}. Dit zijn @w{@code{XFIXNUM (start)}}
en @w{@code{XFIXNUM (end)}}.

Wat de C-taal betreft, zijn @code{start} en @code{end} twee vage waarden die
het begin en eind van de te verwijderen region markeren. Meer precies, en
met meer expertise genodigd om te begrijpen, zijn de twee waarden van het
type @code{Lisp_Object}, wat een C-pointer kan zijn, of een C-integer, of
een C-@code{struct}. Het kan de C code normaalgesproken niet schelen hoe
@code{Lisp_Object} is geïmplementeerd.

De breedte van @code{Lisp_Object} hangt af van de machine, en is typisch 32
of 64 bits. Enkele van de bits worden gebruikt om het type informatie te
specificeren, de resterende bits voor de inhoud.

@samp{XFIXNUM} is een C macro die de relevante integer uit de langere
collectie bits extraheert. De type-bits worden genegeerd.

@need 800
Het commando in @code{delete-and-extract-region} ziet het zo uit:

@smallexample
del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1);
@end smallexample

@noindent
Het verwijdert de region tussen de beginpostitie, @code{start}, en de
eindpositie, @code{end}.

Vanuit het gezichtspunt van de persoon die Lisp schrijft, is Emacs heel
eenvoudig, maar eronder is een grote hoeveelheid compliciteit verborgen die
het allemaal laat werken.

@node defvar
@section Initialiseer een variabele met @code{defvar}
@findex defvar
@cindex Een variabele initialiseren
@cindex Variabele initialisatie

@ignore
2006 Oct 24
In Emacs 22,
copy-region-as-kill is short, 12 lines, and uses
filter-buffer-substring, which is longer, 39 lines
and has delete-and-extract-region in it.
delete-and-extract-region is written in C.

see Initializing a Variable with @code{defvar}

@end ignore

De functie @code{copy-region-as-kill} is in Emacs Lisp geschreven. Twee
functies in het, @code{kill-append} en @code{kill-new}, kopiëren een region
in een buffer en bewaren het in een variabele met de naam
@code{kill-ring}. Deze sectie beschijft hoe de @code{kill-ring} met de
speciale vorm @code{defvar} is gecreëerd en geïnitialiseerd.

(Opnieuw merken we op dat de term @code{kill-ring} een misleidende naam
is. De tekst die uit het buffer is geknipt kan teruggehaald worden. Het is
niet een ring van lijken, maar een ring van herleefbare tekst.)

In Emacs Lisp wordt een variabele zoals @code{kill-ring} met de speciale
vorm gecreëerd en van een initiële waarde voorzien. De naam komt van
``define variable''.

De speciale vorm @code{defvar} stelt de waarde van een variabele in, net als
@code{setq}. Het verschilt van @code{setq} op drie manieren: ten eerste
markeert het de variabele als ``speciaal'' zodat het altijd dynamisch
gebonden is, zelfs wanneer @code{lexcial-binding} @code{t} is (@pxref{Hoe
let variabelen bindt, , Variabelen}). Ten tweede, het stelt alleen de waarde
van de variabele in wanneer de variabele nog geen waarde heeft. Wanneer de
variabele al een waarde heeft, overschrijft @code{defvar} de bestaande
waarde niet. Ten derde, @code{defvar} heeft een documentatiestring. 

(Er is een gerelateerde macro, @code{defcustom}, gemaakt voor variabelen die
mensen customizen. Het heeft meer eigenschappen dan
@code{defvar}. (@xref{defcustom, , Variabelen specificeren met
@code{defcustom}}.)

@menu
* Inzien huidige variabele waarde::  Inzien huidige variabele waarde
* defvar en asterisk::       defvar en asterisk
@end menu

@ifnottex
@node Inzien huidige variabele waarde
@unnumberedsubsec De huidige waarde van een variabele zien
@end ifnottex

Je kunt de huidige waarde van een variabele, elke variabele, zien met de
functie @code{describe-variable}, die meestal wordt aangeroepen met @kbd{C-h
v}. Wanneer je @kbd{C-h v} typt, en na de prompt @code{kill-ring} (gevolgd
door @key{RET}), krijg je de huidige inhoud van je killring te zien---dit
kan best veel zijn! Omgekeerd, wanneer je in deze Emacs sessie niets anders
gedaan hebt dan dit document lezen, kan er helemaal niets in zijn. Ook krijg
je de documentatie voor @code{kill-ring} te zien.

@smallexample
@group
Documentation:
List of killed text sequences.
Since the kill ring is supposed to interact nicely with cut-and-paste
facilities offered by window systems, use of this variable should
@end group
@group
interact nicely with `interprogram-cut-function' and
`interprogram-paste-function'.  The functions `kill-new',
`kill-append', and `current-kill' are supposed to implement this
interaction; you may want to use them instead of manipulating the kill
ring directly.
@end group
@end smallexample

@need 800
De killring is gedefinieerd door een @code{defvar} op de volgende manier: 

@smallexample
@group
(defvar kill-ring nil
  "List of killed text sequences.
@dots{}")
@end group
@end smallexample

@noindent
In deze variabele definitie krijgt de variabele de initiële waarde
@code{nil}, wat logisch is, omdat je nog niets hebt bewaard, wil je niets
terughalen met een @code{yank} commando. De documentatiestring schrijf je op
dezelfde manier als de documentatiestring van een @code{defun}. Net als bij
de documentatiestring van de @code{defun}, moet de eerste regel van de
documentatie ene volledige zin zijn omdat sommige commando's, zoals
@code{apropos} alleen de eerste documentatieregel tonen. Opvolgende regels
moeten niet ingesprongen worden, anders zien ze er raar uit als je @kbd{C-h
v} (@code{describe-variable}) gebruikt.

@node defvar en asterisk
@subsection @code{defvar} en een sterretje
@findex defvar @r{voor een user-customizable variabele}
@findex defvar @r{met een sterretje}

In het verleden gebruikte Emacs de speciale vorm @code{defvar} voor zowel
interne variabelen waarvan je niet verwacht dat een gebruiker die aanpast,
als voor variabelen waarvan je wel verwacht dat een gebruiker die
aanpast. Hoewel je nog steeds @code{defvar} voor door de gebruiker aan te
passen variabelen kunt gebruiken, gebruik je alsjeblieft @code{defcustom}
omdat dit een pad biedt naar de Customization commando's. (@xref{defcustom,
, Variabelen specificeren met @code{defcustom}}.)

Wanneer je een variabele met de speciale vorm @code{defvar} gespecificeerd
hebt, kon je onderscheid maken tussen een variabele die de gebruiker mag
veranderen en de andere, door het typen van een sterretje, @samp{*}, in de
eerste kolom van de documentatiestring. Bijvoorbeeld: 

@smallexample
@group
(defvar shell-command-default-error-buffer nil
  "*Buffer name for `shell-command' @dots{} error output.
@dots{} ")
@end group
@end smallexample

@findex set-variable
@noindent
Je kon (en kan nog steeds) het commando @code{set-variable} gebruiken om de
waarde van @code{shell-command-default-error-buffer} tijdelijk te
wijzigen. Echter, opties gezet met @code{set-variable} zijn alleen voor de
duur van je editing-sessie gezet. De nieuwe waarden worden tussen sessies
niet bewaard. Steeds wanneer Emacs start, leest het de oorspronkelijke
waarde, tenzij je de waarde in je @file{.emacs} bestand aanpast, door het
handmatig te zetten of met gebruik van @code{customize}. @xref{Initialisatie
van Emacs, , Jouw @file{.emacs} bestand}.

Het belangrijkste gebruik van het commando @code{set-variable} voor mij is
om variabelen voor te stellen die ik in mijn @file{.emacs} bestand zou
willen zetten. Er zijn nu meer dan 700 van dat soort variabelen, veel te
veel om makkelijk te herinneren. Gelukkig kan je de @key{TAB} toets
gebruiken na het commando @code{M-x set-variable} om een lijst met
variabelen te zien. (@xref{Examining, , Examining and Setting Variables,
emacs, The GNU Emacs Manual}.)

@need 1250
@node cons en search-fwd terugblik
@section Terugblik

Hier is een korte samenvatting van sommige recent geïntroduceerde functies.

@table @code
@item car
@itemx cdr
@code{car} geeft het eerste element van een lijst terug. @code{cdr} geeft
het tweede en volgende elementen van de lijst terug.

@need 1250
Bijvoorbeeld:

@smallexample
@group
(car '(1 2 3 4 5 6 7))
     @result{} 1
(cdr '(1 2 3 4 5 6 7))
     @result{} (2 3 4 5 6 7)
@end group
@end smallexample

@item cons
@code{cons} construeer een lijst door het eerste element voor het tweede te
zetten.

@need 1250
Bijvoorbeeld:

@smallexample
@group
(cons 1 '(2 3 4))
     @result{} (1 2 3 4)
@end group
@end smallexample

@item funcall
@code{funcall} evalueert het eerste argument als functie. Het geeft de
resterende argumenten door aan het eerste argument.

@item nthcdr
Geeft het resultaat van @var{n} keer @sc{cdr} nemen van een lijst.
@iftex
De
@tex
$n^{th}$
@end tex
@code{cdr} 
@end iftex
De ``rest van de rest'' als het ware.

@need 1250
Bijvoorbeeld:

@smallexample
@group
(nthcdr 3 '(1 2 3 4 5 6 7))
     @result{} (4 5 6 7)
@end group
@end smallexample

@item setcar
@itemx setcdr
@code{setcar} wijzigt het eerste element van een lijst, @code{setcdr}
wijzigt het tweede en volgende elementen van een lijst.

@need 1250
Bijvoorbeeld:

@smallexample
@group
(setq triple (list 1 2 3))

(setcar triple '37)

triple
     @result{} (37 2 3)
(setcdr triple '("foo" "bar"))

triple
     @result{} (37 "foo" "bar")
@end group
@end smallexample

@item progn
Evalueer achtereenvolgens elk argument en geef de waarde van de laatste
terug.

@need 1250
Bijvoorbeeld:

@smallexample
@group
(progn 1 2 3 4)
     @result{} 4
@end group
@end smallexample

@item save-restriction
Bewaar de versmalling die eventueel actief is in het huidige buffer en
herstel die versmalling na het evalueren van de argumenten.

@item search-forward
Zoek voor een string, en wanneer die string gevonden is, verplaats
point. Met een reguliere expressie gebruik de vergelijkbare
@code{re-search-forward}. (@xref{Regexp zoeken, , Reguliere expressie
zoekopdrachten}, voor een uitleg van reguliere expressies patronen en
zoekopdrachten.)

@need 1250
@noindent
@code{search-forward} en @code{re-search-forward} hebben vier argumenten:

@enumerate
@item
De string of reguliere expressie om naar te zoeken.

@item
Optioneel, de limiet van de zoekopdracht.

@item
Optioneel, wat te doen als de zoekopdracht mislukt, geef @code{nil} terug of
een fout.

@item
Optioneel, hoeveel keer de zoekopdracht te herhalen. Wanneer negatief, zoek
achterwaarts.
@end enumerate

@item kill-region
@itemx delete-and-extract-region
@itemx copy-region-as-kill

@code{kill-region} verwijdert de tekst tussen point en mark uit het buffer
en bewaart die tekst in de killring, zodat je die met yanken terug kunt
krijgen.

@code{copy-region-as-kill} kopieert de tekst tussen point en mark naar de
killring, van waar je het met yanken terug kunt krijgen. De functie
verwijdert de tekst niet uit het buffer.
@end table

@code{delete-and-extract-region} verwijdert de tekst tussen point en mark
uit het buffer en gooit het weg. Je kunt het niet terug krijgen. (Dit is
geen interactief commando).

@need 1500
@node zoek oefening
@section Zoek-oefeningen

@itemize @bullet
@item
Schrijf een interactieve functie die naar een string zoekt. Wanneer de
string gevonden is, plaats point er achter en toon een boodschap die zegt
``Gevonden!''. (Maak geen gebruik van @code{search-forward} als naam van
deze functie, wanneer je dat doet overschrijf je de bestaande versie van
@code{search-forward} die bij Emacs hoort. Gebruik in plaats daarvan een
naam zoals @code{test-zoeken}.)

@item
Schrijf een functie die het derde element van de killring toont in het
echogebied als dat element er is. Wanneer de killring geen derde element
heeft, toon dat een passende boodschap.
@end itemize

@node Implementatie van lijsten
@chapter Hoe lijsten zijn geïmplementeerd
@cindex Lijsten in een computer

In Lisp worden atomen op een eenvoudige manier vastgelegd. Zelfs als de
implementatie niet eenvoudig is, dan is de theorie toch eenvoudig. Het atoom
@samp{roos} bijvoorbeeld is vastgelegd als vier aaneengesloten letters,
@samp{r}, @samp{o}, @samp{o} en @samp{s}. Een lijst, anderzijds, wordt
anders bewaard. Het mechanisme is net zo eenvoudig, maar het kost even tijd
om aan het idee gewend te raken. Een lijst wordt bewaard met een reeks paren
van pointers. In de reeks wijst de eerste pointer van elk paar pointers naar
een atoom of naar een andere lijst, en de tweede pointer in elk paar
pointers wijst naar het volgende paar, of naar het symbool @code{nil}, wat
het eind van de lijst markeert.

Een pointer zelf is heel eenvoudig het elektronische adres van datgene, waar
het naar toe wijst. Een lijst wordt dus bewaard als een reeks elektronische
adressen.

@menu
* Lijsten uitgetekend::      Lijsten uitgetekend
* Symbolen als ladekast::    Een krachtige metafoor verkennen.
* Lijst oefening::           Lijst oefening
@end menu

@ifnottex
@node Lijsten uitgetekend
@unnumberedsec Lijsten uitgetekend
@end ifnottex

Bijvoorbeeld de lijst @code{(roos, viool, boterbloem)} heeft drie elementen,
@samp{roos}, @samp{viool} en @samp{boterbloem}. In de computer wordt het
elektronische adres van @samp{roos} bewaard in een segment van het
computergeheugen dat een @samp{cons-cel} heet (omdat dat is wat de functie
@code{cons} werkelijk creëert). Deze cons-cel bevat ook het adres van een
tweede cons-cel, wiens @sc{car} het atoom @samp{viool} is, en dat adres
(degene die vertelt waar @samp{viool} is bewaard) samen met het adres van
een derde cons-cel, die het adres voor het atoom @samp{boterbloem} bevat.

@need 1200
Dit klinkt gecompliceerder dan het is en is makkelijker te zien in een
diagram:

@c clear print-postscript-figures
@c !!! cons-cell-diagram #1
@ifset print-postscript-figures
@sp 1
@center @image{cons-1-nl}
@sp 1
@end ifset
@ifclear print-postscript-figures
@smallexample
@group
    ___ ___      ___ ___      ___ ___
   |___|___|--> |___|___|--> |___|___|--> nil
     |            |            |
     |            |            |
      --> roos     --> viool    --> boterbloem
@end group
@end smallexample
@end ifclear

@noindent
Elk vakje in het diagram representeert een computergeheugen woord dat een
Lisp object bevat, meestal in de vorm van een geheugenadres. De vakjes,
oftewel de adressen, zijn paren. Elke pijl wijst naar wat het adres een
adres van is, hetzij een atoom of een ander paar adressen. Het eerste vakje
is het elektronische adres van @samp{roos} en de pijl wijst naar
@samp{roos}. Het tweede vakje is het adres van het volgende paar vakjes,
waarvan het eerste deel het adres van @samp{viool} is en waarvan het tweede
deel het adres van het volgende paar is. Het allerlaatste vakje wijst naar
het symbool @code{nil}, dat het einde van de lijst markeert.

@need 1200
Wanneer een variabele met een operatie zoals @code{setq} wordt ingesteld op
een lijst, dan slaat dat het adres op van het eerste vakje. Dus, evaluatie
van de expressie

@smallexample
(setq boeket '(roos viool boterbloem))
@end smallexample

@need 1250
@noindent
creëert een situatie zoals dit:

@c cons-cell-diagram #2
@ifset print-postscript-figures
@sp 1
@center @image{cons-2-nl}
@sp 1
@end ifset
@ifclear print-postscript-figures
@smallexample
@group
boeket
     |
     |     ___ ___      ___ ___      ___ ___
      --> |___|___|--> |___|___|--> |___|___|--> nil
            |            |            |
            |            |            |
             --> roos     --> viool    --> boterbloem
@end group
@end smallexample
@end ifclear

@noindent
In dit voorbeeld bevat het symbool @code{boeket} het adres van het eerste
paar vakjes.

@need 1200
Dezelfde lijst kan met een ander soort vakjes-notatie worden geïllustreerd,
zoals dit:

@c cons-cell-diagram #2a
@ifset print-postscript-figures
@sp 1
@center @image{cons-2a-nl}
@sp 1
@end ifset
@ifclear print-postscript-figures
@smallexample
@group
bouquet
 |
 |    --------------       ---------------       ----------------
 |   | car   | cdr  |     | car    | cdr  |     | car     | cdr  |
  -->| roos  |   o------->| viool  |   o------->| boter-  |  nil |
     |       |      |     |        |      |     | bloem   |      |
      --------------       ---------------       ----------------
@end group
@end smallexample
@end ifclear

(Symbolen bestaan uit meer dan paren van adressen, maar de structuur van een
symbool is gemaakt van adressen. Het symbool @code{boeket} bestaat inderdaad
uit een groep van adresvakjes, waarvan een het adres van het getoonde woord
@samp{boeket} is, een tweede daarvan het adres van de aan het symbool
gekoppelde functiedefinitie is, als die er is, en een derde daarvan dat het
adres van het eerste paar adresvakjes voor de lijst @code{roos viool
boterbloem} is, enzovoorts. Hier tonen we dat het derde adresvakje van het
symbool naar het eerste paar van de adresvakjes van de lijst wijst.)

Wanneer een symbool naar de @sc{cdr} van de lijst wordt gezet, verandert de
lijst zelf niet. Het symbool heeft eenvoudig een adres verderop in de
lijst. (In het jargon: @sc{car} en @sc{cdr} zijn niet-destructief). Dus de
evaluatie van de volgende expressie

@smallexample
(setq bloemen (cdr boeket))
@end smallexample

@need 800
@noindent
produceert dit:

@c cons-cell-diagram #3
@ifset print-postscript-figures
@sp 1
@center @image{cons-3-nl}
@sp 1
@end ifset
@ifclear print-postscript-figures
@sp 1
@smallexample
@group
boeket         bloemen
  |              |
  |     ___ ___  |     ___ ___      ___ ___
   --> |   |   |  --> |   |   |    |   |   |
       |___|___|----> |___|___|--> |___|___|--> nil
         |              |            |
         |              |            |
          --> roos       --> viool    --> boterbloem
@end group
@end smallexample
@sp 1
@end ifclear

@noindent
De waarde van @code{bloemen} is @code{(viool boterbloem)}, dat wil zeggen,
het symbool @code{bloemen} bevat het adres van het paar adresvakjes, waarvan
de eerste het adres van @code{viool} bevat en de tweede het adres van
@code{boterbloem} bevat.

@cindex dotted pair
@cindex cons-cel
Een paar adresvakjes heet een @dfn{cons-cel} of @dfn{dotted
pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU
Emacs Lisp Reference Manual}, en @ref{Dotted Pair Notation, , Dotted Pair
Notation, elisp, The GNU Emacs Lisp Reference Manual}, voor meer informatie
over cons-cellen en dotted pairs.

@need 1200
De functie @code{cons} voegt een nieuw paar adressen aan de voorkant van de
reeks van adressen zoals hierboven getoond. Bijvoorbeeld, het evalueren van
de expressie

@smallexample
(setq boeket (cons 'lelie boeket))
@end smallexample

@need 1500
@noindent
produceert:

@c cons-cell-diagram #4
@ifset print-postscript-figures
@sp 1
@center @image{cons-4-nl}
@sp 1
@end ifset
@ifclear print-postscript-figures
@sp 1
@smallexample
@group
boeket                        bloemen
  |                             |
  |     ___ ___        ___ ___  |     ___ ___       ___ ___
   --> |   |   |      |   |   |  --> |   |   |     |   |   |
       |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
         |              |              |             |
         |              |              |             |
          --> lelie     --> roos       --> viool      --> boterbloem
@end group
@end smallexample
@sp 1
@end ifclear

@need 1200
@noindent
Dit verandert echter niet de waarde van het symbool @code{bloemen}, zoals je
kunt zien door het volgende te evalueren:

@smallexample
(eq (cdr (cdr boeket)) bloemen)
@end smallexample

@noindent
wat @code{t} voor waar teruggeeft.

Totdat het wordt gereset, heeft @code{bloemen} nog steeds de waarde
@code{(viool boterbloem)}, dat wil zeggen, het heeft het adres van de
cons-cel wiens eerste adres dat van @code{viool} is. Ook verandert dit geen
van de reeds bestaande cons-cellen, die zijn er nog steeds.

Dus om in Lisp de @sc{cdr} van een lijst te krijgen, krijg je alleen het
adres van de volgende cons-cel in de reeks. Om de @sc{car} van een lijst te
krijgen, krijg je het adres van het eerste element van de lijst. Om een
nieuw element aan een lijst te @code{cons}-en, voeg je een nieuwe cons-cel
aan de voorkant van de lijst toe. Dat is alles! De onderliggende structuur
van Lisp is briljant eenvoudig!

En waar refereert het laatste adres in een reeks van cons-cellen naar toe?
Het is het adres van de lege lijst, van @code{nil}.

Samengevat, wanneer een Lisp variabele op een waarde wordt ingesteld, dan
krijgt die het adres van de lijst waar de variabele naar refereert.

@node Symbolen als ladekast
@section Symbolen als een ladekast
@cindex Symbolen als een ladekast
@cindex Ladekast, metafoor voor een symbool
@cindex Ladekast, metafoor voor een symbool

In een eerdere sectie suggereerde ik dat je een symbool kunt voorstellen als
een ladekast. De functiedefinitie wordt in een lade gestopt, de waarde in
een andere, enzovoorts. Wat in de lade die de waarde bevat gestopt is, kan
worden gewijzigd zonder de inhoud van de waarde die de functiedefinitie
bevat te wijzigen, en andersom.

Wat eigenlijk in elke lade gestopt wordt, is het adres van de waarde of de
functiedefinitie. Het is alsof je een oude kast op de zolder gevonden hebt,
en in een van de lades een kaart vond die de route beschrijft naar waar de
begraven schat ligt.

Naast zijn naam, symbooldefinitie en variabele naam, heeft een symbool een
lade voor een @dfn{property list} die kan worden gebruikt om andere
informatie op te slaan. Property lists bespreken we hier niet, zie
@ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp Reference
Manual}.)

@need 1500
Hier is een fantasierijke weergave:

@c chest-of-drawers diagram
@ifset print-postscript-figures
@sp 1
@center @image{drawers-nl}
@sp 1
@end ifset
@ifclear print-postscript-figures
@sp 1
@smallexample
@group
              Ladekast                   Inhoud van de lade
            __   o0O0o   __
          /                 \
         ---------------------
        |  routebeschrijving  |            [wijst naar]
        |     symbool naam    |             boeket
        |                     |
        +---------------------+
        |  routebeschrijving  |
        |  symbool definitie  |             [geen]
        |                     |
        +---------------------+
        |  routebeschrijving  |            [wijst naar]
        |   variabele waarde  |             (roos viool boterbloem)
        |                     |
        +---------------------+
        |  routebeschrijving  |
        |    property list    |             [hier niet beschreven]
        |                     |
        +---------------------+
        |/                   \|
@end group
@end smallexample
@sp 1
@end ifclear

@node Lijst oefening
@section Oefening

Stel @code{bloemen} in op @code{viool} en @code{boterbloem}. Cons twee
andere bloemen aan deze lijst en zet deze lijst op @code{meer-bloemen}. Zet
de @sc{car} van bloemen op een vis. Wat bevat de lijst @code{meer-bloemen}
nu?

@node Yanking
@chapter Tekst terug yanken
@findex yank
@cindex Tekst terughalen
@cindex Tekst terughalen
@cindex Tekst plakken

Wanneer je in GNU Emacs met een kill commando tekst uit een buffer
verwijdert dan kun je die terughalen met een yank commando. De tekst die uit
het buffer verwijderd is, wordt in de killring gestopt en het yank commando
voegt de juiste inhoud van de killring terug in een buffer (niet
noodzakelijkerwijs het oorspronkelijke buffer).

Een eenvoudig @kbd{C-y} (@code{yank}) commando voegt het eerste element van
de killring in het huidige buffer. Wanneer het @kbd{C-y} commando direct
gevolg wordt door @kbd{M-y}, wordt het eerste element vervangen door het
tweede element. Herhaaldelijke @kbd{M-y} commando's vervangen het teede
element met het derde, vierde of vijfde element, enzovoorts. Wanneer het
laatste element in de killring is bereikt, wordt het vervangen door het
eerste en wordt de cyclus herhaald. (Daarom heet de killring een ``ring'' in
plaats van een ``lijst''. De werkelijke datastructuur die de tekst bevat is
echter een lijst. @xref{Killring, , De killring hanteren}, voor de details
hoe de lijst wordt gehanteerd als ring.)

@menu
* Killring overzicht::       Killring overzicht
* kill-ring-yank-pointer::   De killring is een lijst.
* yank nthcdr oefeningen::   De @code{kill-ring-yank-pointer} variabele.
@end menu

@node Killring overzicht
@section Killring overzicht
@cindex Killring overzicht

De killring is een lijst van tekstuele strings. Dit is hoe die er uit ziet:

@smallexample
("wat tekst" "een ander stuk tekst" "nog meer tekst")
@end smallexample

Wanneer dit de inhoud van mijn killring is en ik sla @kbd{C-y} aan, dan
wordt de karakterstring @samp{wat tekst} in dit buffer op de cursorlokatie
ingevoegd.

Het @code{yank} commando wordt ook gebruikt om tekst te dupliceren door het
te kopiëren. De gekopieerde tekst wordt niet uit het buffer verwijderd, maar
een kopie er van is in de killring geplaatst en onmiddellijk ingevoegd door
het terug te yanken.

Drie functies worden gebruikt om de tekst uit de killring terug te halen:
@code{yank}, dat normaalgesproken gebonden is aan
@kbd{C-y}. @code{yank-pop}, dat normaalgesproken gebonden is aan @kbd{M-y},
en @code{rotate-yank-pointer} dat door de twee andere functies gebruikt
wordt.

Deze functies refereren aan de killring via de variabele met de naam
@code{kill-ring-yank-pointer}. Inderdaad, de invoegcode van zowel de functie
@code{yank} als @code{yank-pop} is:

@smallexample
(insert (car kill-ring-yank-pointer))
@end smallexample

@noindent
(Nou, niet meer. In GNU Emacs 22 is de functie vervangen door
@code{insert-for-yank}, die herhaaldelijk @code{insert-for-yank-1} aanroept
voor elk @code{yank-handler} segment. @code{insert-for-yank-1}, op zijn
beurt, stript de tekst eigenschappen van de ingevoegde tekst in
overeenstemming met @code{yank-excluded-properties}. Anders dat dat, is het
gewoon als @code{insert}. Wij houden het bij de @code{insert}, dit is
makkelijker te begrijpen.)

Om te beginnen te begrijpen hoe @code{yank} en @code{yank-pop} werken, is
het eerst nodig naar de variabele @code{kill-ring-yank-pointer} te kijken.

@node kill-ring-yank-pointer
@section De variabele @code{kill-ring-yank-pointer}

@code{kill-ring-yank-pointer} is een variabel, net zoals @code{kill-ring}
een variabele is. Het wijst naar iets dat is gebonden aan de waarde van waar
het naar wijst, net als elke andere Lisp variabele.

@need 1000
Dus, als de waarde van de killring is:

@smallexample
("wat tekst" "een ander stuk tekst" "nog meer tekst")
@end smallexample

@need 1250
@noindent
en de @code{kill-ring-yank-pointer} wijst naar de tweede clausule, dan is de
waarde van @code{kill-ring-yank-pointer}:

@smallexample
("een ander stuk tekst" "nog meer tekst")
@end smallexample

Zoals in het vorige hoofdstuk (@pxref{Implementatie van lijsten}) uitgelegd,
bewaart de computer geen twee verschillende exemplaren van de tekst waar
zowel de @code{kill-ring} als de @code{kill-ring-yank-pointer} naar
wijzen. De woorden ``een ander stuk tekst'' en ``nog meer tekst'' worden
niet gedupliceerd. In plaats daarvan wijzen de twee Lisp variabelen naar
hetzelfde stuk tekst. Hier is een diagram:

@c cons-cell-diagram #5
@ifset print-postscript-figures
@sp 1
@center @image{cons-5}
@sp 1
@end ifset
@ifclear print-postscript-figures
@smallexample
@group
kill-ring     kill-ring-yank-pointer
    |               |
    |      ___ ___  |     ___ ___      ___ ___
     ---> |   |   |  --> |   |   |    |   |   |
          |___|___|----> |___|___|--> |___|___|--> nil
            |              |            |
            |              |            |
            |              |             --> "nog meer tekst"
            |              |
            |               --> "een ander stuk tekst"
            |
             --> "wat tekst"
@end group
@end smallexample
@sp 1
@end ifclear

Zowel de variabele @code{kill-ring} als de variabele
@code{kill-ring-yank-pointer} zijn pointers. Maar de killring zelf wordt
meestal beschreven alsof het is wat het van gemaakt is. De killring wordt
beschreven alsof het een lijst is in plaats van dat het naar de lijst
wijst. Omgekeerd, de @code{kill-ring-yank-pointer} is beschreven alsof het
wijst naar een lijst.

Deze twee manieren om over het zelfde ding te spreken klinken op het eerste
gezicht verwarrend maar zijn bij nader inzien logisch. De killring wordt
algemeen beschouwd als de complete structuur van data die de informatie
bevat van wat recentelijk uit de buffers is geknipt. De
@code{kill-ring-yank-pointer} anderzijds dient om aan te geven---dat wil
zeggen, te wijzen naar---dat deel van de killring waarvan het eerste element
(the @sc{car}) zal worden ingevoegd.

@ignore
In GNU Emacs 22, the @code{kill-new} function calls

@code{(setq kill-ring-yank-pointer kill-ring)}

(defun rotate-yank-pointer (arg)
  "Rotate the yanking point in the kill ring.
With argument, rotate that many kills forward (or backward, if negative)."
  (interactive "p")
  (current-kill arg))

(defun current-kill (n &optional do-not-move)
  "Rotate the yanking point by N places, and then return that kill.
If N is zero, `interprogram-paste-function' is set, and calling it
returns a string, then that string is added to the front of the
kill ring and returned as the latest kill.
If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
yanking point; just return the Nth kill forward."
  (let ((interprogram-paste (and (= n 0)
                                 interprogram-paste-function
                                 (funcall interprogram-paste-function))))
    (if interprogram-paste
        (progn
          ;; Disable the interprogram cut function when we add the new
          ;; text to the kill ring, so Emacs doesn't try to own the
          ;; selection, with identical text.
          (let ((interprogram-cut-function nil))
            (kill-new interprogram-paste))
          interprogram-paste)
      (or kill-ring (error "Kill ring is empty"))
      (let ((ARGth-kill-element
             (nthcdr (mod (- n (length kill-ring-yank-pointer))
                          (length kill-ring))
                     kill-ring)))
        (or do-not-move
            (setq kill-ring-yank-pointer ARGth-kill-element))
        (car ARGth-kill-element)))))

@end ignore

@need 1500
@node yank nthcdr oefeningen
@section Oefeningen met @code{yank} en @code{nthcdr}

@itemize @bullet
@item
Kijk met @kbd{C-h v} (@code{describe-variable}) naar je killring. Voeg
verschillende items aan je killring toe en kijk opnieuw naar zijn waarde. Ga
met @kbd{M-y} (@code{yank-pop)} helemaal rond in de killring. Hoeveel items
waren in je killring? Vind de waarde van @code{kill-ring-max}. Was je
killring vol, of had je nog meer blokken tekst kunnen bewaren?

@item
Construeer met @code{nthcdr} en @code{car} een reeks expressies om het
eerste, tweede, derde en vierde element van een lijst terug te geven.
@end itemize

@node Loops en recursie
@chapter Loops en recursie
@cindex Loops en recursie
@cindex Recursie en loops
@cindex Herhaling (loops)

Emacs Lisp has two primary ways to cause an expression, or a series of
expressions, to be evaluated repeatedly: one uses a @code{while} loop, and
the other uses @dfn{recursion}.

Repetition can be very valuable.  For example, to move forward four
sentences, you need only write a program that will move forward one sentence
and then repeat the process four times.  Since a computer does not get bored
or tired, such repetitive action does not have the deleterious effects that
excessive or the wrong kinds of repetition can have on humans.

People mostly write Emacs Lisp functions using @code{while} loops and their
kin; but you can use recursion, which provides a very powerful way to think
about and then to solve problems@footnote{You can write recursive functions
to be frugal or wasteful of mental or computer resources; as it happens,
methods that people find easy---that are frugal of mental
resources---sometimes use considerable computer resources.  Emacs was
designed to run on machines that we now consider limited and its default
settings are conservative.  You may want to increase the value of
@code{max-lisp-eval-depth}.  In my @file{.emacs} file, I set it to 30 times
its default value.}.

@menu
* while::                    Een stuk code zich laten herhalen.
* dolist dotimes::           dolist dotimes
* Recursie::                 Een functie zichzelf laten aanroepen.
* Looping oefening::         Looping oefening
@end menu

@node while
@section @code{while}
@cindex Loops
@findex while

The @code{while} special form tests whether the value returned by evaluating
its first argument is true or false.  This is similar to what the Lisp
interpreter does with an @code{if}; what the interpreter does next, however,
is different.

In a @code{while} expression, if the value returned by evaluating the first
argument is false, the Lisp interpreter skips the rest of the expression
(the @dfn{body} of the expression) and does not evaluate it.  However, if
the value is true, the Lisp interpreter evaluates the body of the expression
and then again tests whether the first argument to @code{while} is true or
false.  If the value returned by evaluating the first argument is again
true, the Lisp interpreter again evaluates the body of the expression.

@need 1200
The template for a @code{while} expression looks like this:

@smallexample
@group
(while @var{true-or-false-test}
  @var{body}@dots{})
@end group
@end smallexample

@menu
* Looping met while::        Herhaal zolang de test waar teruggeeft.
* Loop voorbeeld::           Een @code{while} loop die een lijst gebruikt.
* print-elements-of-list::   Gebruik @code{while}, @code{car}, @code{cdr}.
* Incrementele loop::        Een loop met een incrementele teller.
* Incrementele loop details::  Incrementele loop details
* Decrementele loop::        Een loop met een aflopende teller.
@end menu

@ifnottex
@node Looping met while
@unnumberedsubsec Looping with @code{while}
@end ifnottex

So long as the true-or-false-test of the @code{while} expression returns a
true value when it is evaluated, the body is repeatedly evaluated.  This
process is called a loop since the Lisp interpreter repeats the same thing
again and again, like an airplane doing a loop.  When the result of
evaluating the true-or-false-test is false, the Lisp interpreter does not
evaluate the rest of the @code{while} expression and exits the loop.

Clearly, if the value returned by evaluating the first argument to
@code{while} is always true, the body following will be evaluated again and
again @dots{} and again @dots{} forever.  Conversely, if the value returned
is never true, the expressions in the body will never be evaluated.  The
craft of writing a @code{while} loop consists of choosing a mechanism such
that the true-or-false-test returns true just the number of times that you
want the subsequent expressions to be evaluated, and then have the test
return false.

The value returned by evaluating a @code{while} is the value of the
true-or-false-test.  An interesting consequence of this is that a
@code{while} loop that evaluates without error will return @code{nil} or
false regardless of whether it has looped 1 or 100 times or none at all.  A
@code{while} expression that evaluates successfully never returns a true
value! What this means is that @code{while} is always evaluated for its side
effects, which is to say, the consequences of evaluating the expressions
within the body of the @code{while} loop.  This makes sense.  It is not the
mere act of looping that is desired, but the consequences of what happens
when the expressions in the loop are repeatedly evaluated.

@node Loop voorbeeld
@subsection A @code{while} Loop and a List

A common way to control a @code{while} loop is to test whether a list has
any elements.  If it does, the loop is repeated; but if it does not, the
repetition is ended.  Since this is an important technique, we will create a
short example to illustrate it.

A simple way to test whether a list has elements is to evaluate the list: if
it has no elements, it is an empty list and will return the empty list,
@code{()}, which is a synonym for @code{nil} or false.  On the other hand, a
list with elements will return those elements when it is evaluated.  Since
Emacs Lisp considers as true any value that is not @code{nil}, a list that
returns elements will test true in a @code{while} loop.

@need 1200
For example, you can set the variable @code{empty-list} to @code{nil} by
evaluating the following @code{setq} expression:

@smallexample
(setq empty-list ())
@end smallexample

@noindent
After evaluating the @code{setq} expression, you can evaluate the variable
@code{empty-list} in the usual way, by placing the cursor after the symbol
and typing @kbd{C-x C-e}; @code{nil} will appear in your echo area:

@smallexample
empty-list
@end smallexample

On the other hand, if you set a variable to be a list with elements, the
list will appear when you evaluate the variable, as you can see by
evaluating the following two expressions:

@smallexample
@group
(setq animals '(gazelle giraffe lion tiger))

animals
@end group
@end smallexample

Thus, to create a @code{while} loop that tests whether there are any items
in the list @code{animals}, the first part of the loop will be written like
this:

@smallexample
@group
(while animals
       @dots{}
@end group
@end smallexample

@noindent
When the @code{while} tests its first argument, the variable @code{animals}
is evaluated.  It returns a list.  So long as the list has elements, the
@code{while} considers the results of the test to be true; but when the list
is empty, it considers the results of the test to be false.

To prevent the @code{while} loop from running forever, some mechanism needs
to be provided to empty the list eventually.  An oft-used technique is to
have one of the subsequent forms in the @code{while} expression set the
value of the list to be the @sc{cdr} of the list.  Each time the @code{cdr}
function is evaluated, the list will be made shorter, until eventually only
the empty list will be left.  At this point, the test of the @code{while}
loop will return false, and the arguments to the @code{while} will no longer
be evaluated.

For example, the list of animals bound to the variable @code{animals} can be
set to be the @sc{cdr} of the original list with the following expression:

@smallexample
(setq animals (cdr animals))
@end smallexample

@noindent
If you have evaluated the previous expressions and then evaluate this
expression, you will see @code{(giraffe lion tiger)} appear in the echo
area.  If you evaluate the expression again, @code{(lion tiger)} will appear
in the echo area.  If you evaluate it again and yet again, @code{(tiger)}
appears and then the empty list, shown by @code{nil}.

A template for a @code{while} loop that uses the @code{cdr} function
repeatedly to cause the true-or-false-test eventually to test false looks
like this:

@smallexample
@group
(while @var{test-whether-list-is-empty}
  @var{body}@dots{}
  @var{set-list-to-cdr-of-list})
@end group
@end smallexample

This test and use of @code{cdr} can be put together in a function that goes
through a list and prints each element of the list on a line of its own.

@node print-elements-of-list
@subsection An Example: @code{print-elements-of-list}
@findex print-elements-of-list

The @code{print-elements-of-list} function illustrates a @code{while} loop
with a list.

@cindex @file{*scratch*} buffer
The function requires several lines for its output.  If you are reading this
in a recent instance of GNU Emacs, you can evaluate the following expression
inside of Info, as usual.

If you are using an earlier version of Emacs, you need to copy the necessary
expressions to your @file{*scratch*} buffer and evaluate them there.  This
is because the echo area had only one line in the earlier versions.

You can copy the expressions by marking the beginning of the region with
@kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to the end of
the region and then copying the region using @kbd{M-w}
(@code{kill-ring-save}, which calls @code{copy-region-as-kill} and then
provides visual feedback).  In the @file{*scratch*} buffer, you can yank the
expressions back by typing @kbd{C-y} (@code{yank}).

After you have copied the expressions to the @file{*scratch*} buffer,
evaluate each expression in turn.  Be sure to evaluate the last expression,
@code{(print-elements-of-list animals)}, by typing @kbd{C-u C-x C-e}, that
is, by giving an argument to @code{eval-last-sexp}.  This will cause the
result of the evaluation to be printed in the @file{*scratch*} buffer
instead of being printed in the echo area.  (Otherwise you will see
something like this in your echo area:
@code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which each @samp{^J}
stands for a newline.)

@need 1500
You can evaluate these expressions directly in the Info buffer, and the echo
area will grow to show the results.

@smallexample
@group
(setq animals '(gazelle giraffe lion tiger))

(defun print-elements-of-list (list)
  "Print each element of LIST on a line of its own."
  (while list
    (print (car list))
    (setq list (cdr list))))

(print-elements-of-list animals)
@end group
@end smallexample

@need 1200
@noindent
When you evaluate the three expressions in sequence, you will see this:

@smallexample
@group
gazelle

giraffe

lion

tiger
nil
@end group
@end smallexample

Each element of the list is printed on a line of its own (that is what the
function @code{print} does) and then the value returned by the function is
printed.  Since the last expression in the function is the @code{while}
loop, and since @code{while} loops always return @code{nil}, a @code{nil} is
printed after the last element of the list.

@node Incrementele loop
@subsection A Loop with an Incrementing Counter

A loop is not useful unless it stops when it ought.  Besides controlling a
loop with a list, a common way of stopping a loop is to write the first
argument as a test that returns false when the correct number of repetitions
are complete.  This means that the loop must have a counter---an expression
that counts how many times the loop repeats itself.

@ifnottex
@node Incrementele loop details
@unnumberedsubsec Details van een incrementele loop
@end ifnottex

The test for a loop with an incrementing counter can be an expression such
as @code{(< count desired-number)} which returns @code{t} for true if the
value of @code{count} is less than the @code{desired-number} of repetitions
and @code{nil} for false if the value of @code{count} is equal to or is
greater than the @code{desired-number}.  The expression that increments the
count can be a simple @code{setq} such as @code{(setq count (1+ count))},
where @code{1+} is a built-in function in Emacs Lisp that adds 1 to its
argument.  (The expression @w{@code{(1+ count)}} has the same result as
@w{@code{(+ count 1)}}, but is easier for a human to read.)

@need 1250
The template for a @code{while} loop controlled by an incrementing counter
looks like this:

@smallexample
@group
@var{set-count-to-initial-value}
(while (< count desired-number)         ; @r{true-or-false-test}
  @var{body}@dots{}
  (setq count (1+ count)))              ; @r{incrementer}
@end group
@end smallexample

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

@menu
* Incrementeel voorbeeld::   Steentjes in een driehoek tellen.
* Inc voorbeeld onderdelen::  De onderdelen van een functiedefinitie.
* inc voorbeeld samengesteld::  De functiedefinitie samenstellen.
@end menu

@node Incrementeel voorbeeld
@unnumberedsubsubsec Example with incrementing counter

Suppose you are playing on the beach and decide to make a triangle of
pebbles, putting one pebble in the first row, two in the second row, three
in the third row and so on, like this:

@sp 1
@c pebble diagram
@ifnottex
@smallexample
@group
               *
              * *
             * * *
            * * * *
@end group
@end smallexample
@end ifnottex
@iftex
@smallexample
@group
               @bullet{}
              @bullet{} @bullet{}
             @bullet{} @bullet{} @bullet{}
            @bullet{} @bullet{} @bullet{} @bullet{}
@end group
@end smallexample
@end iftex
@sp 1

@noindent
(About 2500 years ago, Pythagoras and others developed the beginnings of
number theory by considering questions such as this.)

Suppose you want to know how many pebbles you will need to make a triangle
with 7 rows?

Clearly, what you need to do is add up the numbers from 1 to 7.  There are
two ways to do this; start with the smallest number, one, and add up the
list in sequence, 1, 2, 3, 4 and so on; or start with the largest number and
add the list going down: 7, 6, 5, 4 and so on.  Because both mechanisms
illustrate common ways of writing @code{while} loops, we will create two
examples, one counting up and the other counting down.  In this first
example, we will start with 1 and add 2, 3, 4 and so on.

If you are just adding up a short list of numbers, the easiest way to do it
is to add up all the numbers at once.  However, if you do not know ahead of
time how many numbers your list will have, or if you want to be prepared for
a very long list, then you need to design your addition so that what you do
is repeat a simple process many times instead of doing a more complex
process once.

For example, instead of adding up all the pebbles all at once, what you can
do is add the number of pebbles in the first row, 1, to the number in the
second row, 2, and then add the total of those two rows to the third row,
3.  Then you can add the number in the fourth row, 4, to the total of the
first three rows; and so on.

The critical characteristic of the process is that each repetitive action is
simple.  In this case, at each step we add only two numbers, the number of
pebbles in the row and the total already found.  This process of adding two
numbers is repeated again and again until the last row has been added to the
total of all the preceding rows.  In a more complex loop the repetitive
action might not be so simple, but it will be simpler than doing everything
all at once.

@node Inc voorbeeld onderdelen
@unnumberedsubsubsec The parts of the function definition

The preceding analysis gives us the bones of our function definition: first,
we will need a variable that we can call @code{total} that will be the total
number of pebbles.  This will be the value returned by the function.

Second, we know that the function will require an argument: this argument
will be the total number of rows in the triangle.  It can be called
@code{number-of-rows}.

Finally, we need a variable to use as a counter.  We could call this
variable @code{counter}, but a better name is @code{row-number}.  That is
because what the counter does in this function is count rows, and a program
should be written to be as understandable as possible.

When the Lisp interpreter first starts evaluating the expressions in the
function, the value of @code{total} should be set to zero, since we have not
added anything to it.  Then the function should add the number of pebbles in
the first row to the total, and then add the number of pebbles in the second
to the total, and then add the number of pebbles in the third row to the
total, and so on, until there are no more rows left to add.

Both @code{total} and @code{row-number} are used only inside the function,
so they can be declared as local variables with @code{let} and given initial
values.  Clearly, the initial value for @code{total} should be 0.  The
initial value of @code{row-number} should be 1, since we start with the
first row.  This means that the @code{let} statement will look like this:

@smallexample
@group
  (let ((total 0)
        (row-number 1))
    @var{body}@dots{})
@end group
@end smallexample

After the internal variables are declared and bound to their initial values,
we can begin the @code{while} loop.  The expression that serves as the test
should return a value of @code{t} for true so long as the @code{row-number}
is less than or equal to the @code{number-of-rows}.  (If the expression
tests true only so long as the row number is less than the number of rows in
the triangle, the last row will never be added to the total; hence the row
number has to be either less than or equal to the number of rows.)

@need 1500
@findex <= @r{(less than or equal)}
Lisp provides the @code{<=} function that returns true if the value of its
first argument is less than or equal to the value of its second argument and
false otherwise.  So the expression that the @code{while} will evaluate as
its test should look like this:

@smallexample
(<= row-number number-of-rows)
@end smallexample

The total number of pebbles can be found by repeatedly adding the number of
pebbles in a row to the total already found.  Since the number of pebbles in
the row is equal to the row number, the total can be found by adding the row
number to the total.  (Clearly, in a more complex situation, the number of
pebbles in the row might be related to the row number in a more complicated
way; if this were the case, the row number would be replaced by the
appropriate expression.)

@smallexample
(setq total (+ total row-number))
@end smallexample

@noindent
What this does is set the new value of @code{total} to be equal to the sum
of adding the number of pebbles in the row to the previous total.

After setting the value of @code{total}, the conditions need to be
established for the next repetition of the loop, if there is one.  This is
done by incrementing the value of the @code{row-number} variable, which
serves as a counter.  After the @code{row-number} variable has been
incremented, the true-or-false-test at the beginning of the @code{while}
loop tests whether its value is still less than or equal to the value of the
@code{number-of-rows} and if it is, adds the new value of the
@code{row-number} variable to the @code{total} of the previous repetition of
the loop.

@need 1200
The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the
@code{row-number} variable can be incremented with this expression:

@smallexample
(setq row-number (1+ row-number))
@end smallexample

@node inc voorbeeld samengesteld
@unnumberedsubsubsec Putting the function definition together

We have created the parts for the function definition; now we need to put
them together.

@need 800
First, the contents of the @code{while} expression:

@smallexample
@group
(while (<= row-number number-of-rows)   ; @r{true-or-false-test}
  (setq total (+ total row-number))
  (setq row-number (1+ row-number)))    ; @r{incrementer}
@end group
@end smallexample

Along with the @code{let} expression varlist, this very nearly completes the
body of the function definition.  However, it requires one final element,
the need for which is somewhat subtle.

The final touch is to place the variable @code{total} on a line by itself
after the @code{while} expression.  Otherwise, the value returned by the
whole function is the value of the last expression that is evaluated in the
body of the @code{let}, and this is the value returned by the @code{while},
which is always @code{nil}.

This may not be evident at first sight.  It almost looks as if the
incrementing expression is the last expression of the whole function.  But
that expression is part of the body of the @code{while}; it is the last
element of the list that starts with the symbol @code{while}.  Moreover, the
whole of the @code{while} loop is a list within the body of the @code{let}.

@need 1250
In outline, the function will look like this:

@smallexample
@group
(defun @var{name-of-function} (@var{argument-list})
  "@var{documentation}@dots{}"
  (let (@var{varlist})
    (while (@var{true-or-false-test})
      @var{body-of-while}@dots{} )
    @dots{} ))                    ; @r{Need final expression here.}
@end group
@end smallexample

The result of evaluating the @code{let} is what is going to be returned by
the @code{defun} since the @code{let} is not embedded within any containing
list, except for the @code{defun} as a whole.  However, if the @code{while}
is the last element of the @code{let} expression, the function will always
return @code{nil}.  This is not what we want! Instead, what we want is the
value of the variable @code{total}.  This is returned by simply placing the
symbol as the last element of the list starting with @code{let}.  It gets
evaluated after the preceding elements of the list are evaluated, which
means it gets evaluated after it has been assigned the correct value for the
total.

It may be easier to see this by printing the list starting with @code{let}
all on one line.  This format makes it evident that the @var{varlist} and
@code{while} expressions are the second and third elements of the list
starting with @code{let}, and the @code{total} is the last element:

@smallexample
@group
(let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total)
@end group
@end smallexample

@need 1200
Putting everything together, the @code{triangle} function definition looks
like this:

@smallexample
@group
(defun triangle (number-of-rows)    ; @r{Version with}
                                    ; @r{  incrementing counter.}
  "Add up the number of pebbles in a triangle.
The first row has one pebble, the second row two pebbles,
the third row three pebbles, and so on.
The argument is NUMBER-OF-ROWS."
@end group
@group
  (let ((total 0)
        (row-number 1))
    (while (<= row-number number-of-rows)
      (setq total (+ total row-number))
      (setq row-number (1+ row-number)))
    total))
@end group
@end smallexample

@need 1200
After you have installed @code{triangle} by evaluating the function, you can
try it out.  Here are two examples:

@smallexample
@group
(triangle 4)

(triangle 7)
@end group
@end smallexample

@noindent
The sum of the first four numbers is 10 and the sum of the first seven
numbers is 28.

@node Decrementele loop
@subsection Loop met een decrementele teller

Another common way to write a @code{while} loop is to write the test so that
it determines whether a counter is greater than zero.  So long as the
counter is greater than zero, the loop is repeated.  But when the counter is
equal to or less than zero, the loop is stopped.  For this to work, the
counter has to start out greater than zero and then be made smaller and
smaller by a form that is evaluated repeatedly.

The test will be an expression such as @code{(> counter 0)} which returns
@code{t} for true if the value of @code{counter} is greater than zero, and
@code{nil} for false if the value of @code{counter} is equal to or less than
zero.  The expression that makes the number smaller and smaller can be a
simple @code{setq} such as @code{(setq counter (1- counter))}, where
@code{1-} is a built-in function in Emacs Lisp that subtracts 1 from its
argument.

@need 1250
The template for a decrementing @code{while} loop looks like this:

@smallexample
@group
(while (> counter 0)                    ; @r{true-or-false-test}
  @var{body}@dots{}
  (setq counter (1- counter)))          ; @r{decrementer}
@end group
@end smallexample

@menu
* Decerementeel voorbeeld::  Meer steentjes op het strand.
* Dec voorbeeld onderdelen::  De onderdelen van een functiedefinitie.
* Dec voorbeeld samengesteld::  De functiedefinitie samenstellen.
@end menu

@node Decerementeel voorbeeld
@unnumberedsubsubsec Example with decrementing counter

To illustrate a loop with a decrementing counter, we will rewrite the
@code{triangle} function so the counter decreases to zero.

This is the reverse of the earlier version of the function.  In this case,
to find out how many pebbles are needed to make a triangle with 3 rows, add
the number of pebbles in the third row, 3, to the number in the preceding
row, 2, and then add the total of those two rows to the row that precedes
them, which is 1.

Likewise, to find the number of pebbles in a triangle with 7 rows, add the
number of pebbles in the seventh row, 7, to the number in the preceding row,
which is 6, and then add the total of those two rows to the row that
precedes them, which is 5, and so on.  As in the previous example, each
addition only involves adding two numbers, the total of the rows already
added up and the number of pebbles in the row that is being added to the
total.  This process of adding two numbers is repeated again and again until
there are no more pebbles to add.

We know how many pebbles to start with: the number of pebbles in the last
row is equal to the number of rows.  If the triangle has seven rows, the
number of pebbles in the last row is 7.  Likewise, we know how many pebbles
are in the preceding row: it is one less than the number in the row.

@node Dec voorbeeld onderdelen
@unnumberedsubsubsec The parts of the function definition

We start with three variables: the total number of rows in the triangle; the
number of pebbles in a row; and the total number of pebbles, which is what
we want to calculate.  These variables can be named @code{number-of-rows},
@code{number-of-pebbles-in-row}, and @code{total}, respectively.

Both @code{total} and @code{number-of-pebbles-in-row} are used only inside
the function and are declared with @code{let}.  The initial value of
@code{total} should, of course, be zero.  However, the initial value of
@code{number-of-pebbles-in-row} should be equal to the number of rows in the
triangle, since the addition will start with the longest row.

@need 1250
This means that the beginning of the @code{let} expression will look like
this:

@smallexample
@group
(let ((total 0)
      (number-of-pebbles-in-row number-of-rows))
  @var{body}@dots{})
@end group
@end smallexample

The total number of pebbles can be found by repeatedly adding the number of
pebbles in a row to the total already found, that is, by repeatedly
evaluating the following expression:

@smallexample
(setq total (+ total number-of-pebbles-in-row))
@end smallexample

@noindent
After the @code{number-of-pebbles-in-row} is added to the @code{total}, the
@code{number-of-pebbles-in-row} should be decremented by one, since the next
time the loop repeats, the preceding row will be added to the total.

The number of pebbles in a preceding row is one less than the number of
pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be used
to compute the number of pebbles in the preceding row.  This can be done
with the following expression:

@smallexample
@group
(setq number-of-pebbles-in-row
      (1- number-of-pebbles-in-row))
@end group
@end smallexample

Finally, we know that the @code{while} loop should stop making repeated
additions when there are no pebbles in a row.  So the test for the
@code{while} loop is simply:

@smallexample
(while (> number-of-pebbles-in-row 0)
@end smallexample

@node Dec voorbeeld samengesteld
@unnumberedsubsubsec Putting the function definition together

We can put these expressions together to create a function definition that
works.  However, on examination, we find that one of the local variables is
unneeded!

@need 1250
The function definition looks like this:

@smallexample
@group
;;; @r{First subtractive version.}
(defun triangle (number-of-rows)
  "Add up the number of pebbles in a triangle."
  (let ((total 0)
        (number-of-pebbles-in-row number-of-rows))
    (while (> number-of-pebbles-in-row 0)
      (setq total (+ total number-of-pebbles-in-row))
      (setq number-of-pebbles-in-row
            (1- number-of-pebbles-in-row)))
    total))
@end group
@end smallexample

As written, this function works.

However, we do not need @code{number-of-pebbles-in-row}.

@cindex Argument as local variable
When the @code{triangle} function is evaluated, the symbol
@code{number-of-rows} will be bound to a number, giving it an initial
value.  That number can be changed in the body of the function as if it were
a local variable, without any fear that such a change will effect the value
of the variable outside of the function.  This is a very useful
characteristic of Lisp; it means that the variable @code{number-of-rows} can
be used anywhere in the function where @code{number-of-pebbles-in-row} is
used.

@need 800
Here is a second version of the function written a bit more cleanly:

@smallexample
@group
(defun triangle (number)                ; @r{Second version.}
  "Return sum of numbers 1 through NUMBER inclusive."
  (let ((total 0))
    (while (> number 0)
      (setq total (+ total number))
      (setq number (1- number)))
    total))
@end group
@end smallexample

In brief, a properly written @code{while} loop will consist of three parts:

@enumerate
@item
A test that will return false after the loop has repeated itself the correct
number of times.

@item
An expression the evaluation of which will return the value desired after
being repeatedly evaluated.

@item
An expression to change the value passed to the true-or-false-test so that
the test returns false after the loop has repeated itself the right number
of times.
@end enumerate

@node dolist dotimes
@section Bespaar je tijd: @code{dolist} en @code{dotimes}

In addition to @code{while}, both @code{dolist} and @code{dotimes} provide
for looping.  Sometimes these are quicker to write than the equivalent
@code{while} loop.  Both are Lisp macros.  (@xref{Macros, , Macros, elisp,
The GNU Emacs Lisp Reference Manual}. )

@code{dolist} works like a @code{while} loop that @sc{cdr}s down a list:
@code{dolist} automatically shortens the list each time it loops---takes the
@sc{cdr} of the list---and binds the @sc{car} of each shorter version of the
list to the first of its arguments.

@code{dotimes} loops a specific number of times: you specify the number.

@menu
* dolist::                   dolist
* dotimes::                  dotimes
@end menu

@node dolist
@unnumberedsubsec The @code{dolist} Macro
@findex dolist

Suppose, for example, you want to reverse a list, so that ``first''
``second'' ``third'' becomes ``third'' ``second'' ``first''.

@need 1250
In practice, you would use the @code{reverse} function, like this:

@smallexample
@group
(setq animals '(gazelle giraffe lion tiger))

(reverse animals)
@end group
@end smallexample

@need 800
@noindent
Here is how you could reverse the list using a @code{while} loop:

@smallexample
@group
(setq animals '(gazelle giraffe lion tiger))

(defun reverse-list-with-while (list)
  "Using while, reverse the order of LIST."
  (let (value)  ; make sure list starts empty
    (while list
      (setq value (cons (car list) value))
      (setq list (cdr list)))
    value))

(reverse-list-with-while animals)
@end group
@end smallexample

@need 800
@noindent
And here is how you could use the @code{dolist} macro:

@smallexample
@group
(setq animals '(gazelle giraffe lion tiger))

(defun reverse-list-with-dolist (list)
  "Using dolist, reverse the order of LIST."
  (let (value)  ; make sure list starts empty
    (dolist (element list value)
      (setq value (cons element value)))))

(reverse-list-with-dolist animals)
@end group
@end smallexample

@need 1250
@noindent
In Info, you can place your cursor after the closing parenthesis of each
expression and type @kbd{C-x C-e}; in each case, you should see

@smallexample
(tiger lion giraffe gazelle)
@end smallexample

@noindent
in the echo area.

For this example, the existing @code{reverse} function is obviously best.
The @code{while} loop is just like our first example (@pxref{Loop Example, ,
A @code{while} Loop and a List}).  The @code{while} first checks whether the
list has elements; if so, it constructs a new list by adding the first
element of the list to the existing list (which in the first iteration of
the loop is @code{nil}).  Since the second element is prepended in front of
the first element, and the third element is prepended in front of the second
element, the list is reversed.

In the expression using a @code{while} loop, the @w{@code{(setq list (cdr
list))}} expression shortens the list, so the @code{while} loop eventually
stops.  In addition, it provides the @code{cons} expression with a new first
element by creating a new and shorter list at each repetition of the loop.

The @code{dolist} expression does very much the same as the @code{while}
expression, except that the @code{dolist} macro does some of the work you
have to do when writing a @code{while} expression.

Like a @code{while} loop, a @code{dolist} loops.  What is different is that
it automatically shortens the list each time it loops---it @sc{cdr}s down
the list on its own---and it automatically binds the @sc{car} of each
shorter version of the list to the first of its arguments.

In the example, the @sc{car} of each shorter version of the list is referred
to using the symbol @samp{element}, the list itself is called @samp{list},
and the value returned is called @samp{value}.  The remainder of the
@code{dolist} expression is the body.

The @code{dolist} expression binds the @sc{car} of each shorter version of
the list to @code{element} and then evaluates the body of the expression;
and repeats the loop.  The result is returned in @code{value}.

@node dotimes
@unnumberedsubsec The @code{dotimes} Macro
@findex dotimes

The @code{dotimes} macro is similar to @code{dolist}, except that it loops a
specific number of times.

The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 and so
forth each time around the loop.  You need to provide the value of the
second argument, which is how many times the macro loops.

@need 1250
For example, the following binds the numbers from 0 up to, but not
including, the number 3 to the first argument, @var{number}, and then
constructs a list of the three numbers.  (The first number is 0, the second
number is 1, and the third number is 2; this makes a total of three numbers
in all, starting with zero as the first number.)

@smallexample
@group
(let (value)      ; otherwise a value is a void variable
  (dotimes (number 3)
    (setq value (cons number value)))
  value)

@result{} (2 1 0)
@end group
@end smallexample

@noindent
The way to use @code{dotimes} is to operate on some expression @var{number}
number of times and then return the result, either as a list or an atom.

@need 1250
Here is an example of a @code{defun} that uses @code{dotimes} to add up the
number of pebbles in a triangle.

@smallexample
@group
(defun triangle-using-dotimes (number-of-rows)
  "Using `dotimes', add up the number of pebbles in a triangle."
(let ((total 0))  ; otherwise a total is a void variable
  (dotimes (number number-of-rows)
    (setq total (+ total (1+ number))))
  total))

(triangle-using-dotimes 4)
@end group
@end smallexample

@node Recursie
@section Recursie
@cindex Recursie

A recursive function contains code that tells the Lisp interpreter to call a
program that runs exactly like itself, but with slightly different
arguments.  The code runs exactly the same because it has the same name.
However, even though the program has the same name, it is not the same
entity.  It is different.  In the jargon, it is a different ``instance''.

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

@menu
* Robots bouwen::            Zelfde model, verschillend serienummer ...
* Recursive definitie onderdelen::  Loop totdat je stopt ...
* Recursie met lijst::       Een lijst gebruiken als test of je moet 
                               recursen.
* Recursieve driehoek functie::  Recursieve driehoek functie
* Recursie met cond::        Recursie met cond
* Recursieve patronen::      Veelgebruikte templates.
* Geen uitstel::             Sla geen werk op ...
* Geen uitstel oplossing::   Geen uitstel oplossing
@end menu

@node Robots bouwen
@subsection Building Robots: Extending the Metaphor
@cindex Building robots
@cindex Robots, building

It is sometimes helpful to think of a running program as a robot that does a
job.  In doing its job, a recursive function calls on a second robot to help
it.  The second robot is identical to the first in every way, except that
the second robot helps the first and has been passed different arguments
than the first.

In a recursive function, the second robot may call a third; and the third
may call a fourth, and so on.  Each of these is a different entity; but all
are clones.

Since each robot has slightly different instructions---the arguments will
differ from one robot to the next---the last robot should know when to stop.

Let's expand on the metaphor in which a computer program is a robot.

A function definition provides the blueprints for a robot.  When you install
a function definition, that is, when you evaluate a @code{defun} macro, you
install the necessary equipment to build robots.  It is as if you were in a
factory, setting up an assembly line.  Robots with the same name are built
according to the same blueprints.  So they have the same model number, but a
different serial number.

We often say that a recursive function ``calls itself''.  What we mean is
that the instructions in a recursive function cause the Lisp interpreter to
run a different function that has the same name and does the same job as the
first, but with different arguments.

It is important that the arguments differ from one instance to the next;
otherwise, the process will never stop.

@node Recursive definitie onderdelen
@subsection The Parts of a Recursive Definition
@cindex Parts of a Recursive Definition
@cindex Recursive definitie onderdelen

A recursive function typically contains a conditional expression which has
three parts:

@enumerate
@item
A true-or-false-test that determines whether the function is called again,
here called the @dfn{do-again-test}.

@item
The name of the function.  When this name is called, a new instance of the
function---a new robot, as it were---is created and told what to do.

@item
An expression that returns a different value each time the function is
called, here called the @dfn{next-step-expression}.  Consequently, the
argument (or arguments) passed to the new instance of the function will be
different from that passed to the previous instance.  This causes the
conditional expression, the @dfn{do-again-test}, to test false after the
correct number of repetitions.
@end enumerate

Recursive functions can be much simpler than any other kind of function.
Indeed, when people first start to use them, they often look so mysteriously
simple as to be incomprehensible.  Like riding a bicycle, reading a
recursive function definition takes a certain knack which is hard at first
but then seems simple.

@need 1200
There are several different common recursive patterns.  A very simple
pattern looks like this:

@smallexample
@group
(defun @var{name-of-recursive-function} (@var{argument-list})
  "@var{documentation}@dots{}"
  (if @var{do-again-test}
    @var{body}@dots{}
    (@var{name-of-recursive-function}
         @var{next-step-expression})))
@end group
@end smallexample

Each time a recursive function is evaluated, a new instance of it is created
and told what to do.  The arguments tell the instance what to do.

An argument is bound to the value of the next-step-expression.  Each
instance runs with a different value of the next-step-expression.

The value in the next-step-expression is used in the do-again-test.

The value returned by the next-step-expression is passed to the new instance
of the function, which evaluates it (or some transmogrification of it) to
determine whether to continue or stop.  The next-step-expression is designed
so that the do-again-test returns false when the function should no longer
be repeated.

The do-again-test is sometimes called the @dfn{stop condition}, since it
stops the repetitions when it tests false.

@node Recursie met lijst
@subsection Recursion with a List

The example of a @code{while} loop that printed the elements of a list of
numbers can be written recursively.  Here is the code, including an
expression to set the value of the variable @code{animals} to a list.

If you are reading this in Info in Emacs, you can evaluate this expression
directly in Info.  Otherwise, you must copy the example to the
@file{*scratch*} buffer and evaluate each expression there.  Use @kbd{C-u
C-x C-e} to evaluate the @code{(print-elements-recursively animals)}
expression so that the results are printed in the buffer; otherwise the Lisp
interpreter will try to squeeze the results into the one line of the echo
area.

Also, place your cursor immediately after the last closing parenthesis of
the @code{print-elements-recursively} function, before the comment.
Otherwise, the Lisp interpreter will try to evaluate the comment.

@findex print-elements-recursively
@smallexample
@group
(setq animals '(gazelle giraffe lion tiger))

(defun print-elements-recursively (list)
  "Print each element of LIST on a line of its own.
Uses recursion."
  (when list                            ; @r{do-again-test}
        (print (car list))              ; @r{body}
        (print-elements-recursively     ; @r{recursive call}
         (cdr list))))                  ; @r{next-step-expression}

(print-elements-recursively animals)
@end group
@end smallexample

The @code{print-elements-recursively} function first tests whether there is
any content in the list; if there is, the function prints the first element
of the list, the @sc{car} of the list.  Then the function invokes itself,
but gives itself as its argument, not the whole list, but the second and
subsequent elements of the list, the @sc{cdr} of the list.

Put another way, if the list is not empty, the function invokes another
instance of code that is similar to the initial code, but is a different
thread of execution, with different arguments than the first instance.

Put in yet another way, if the list is not empty, the first robot assembles
a second robot and tells it what to do; the second robot is a different
individual from the first, but is the same model.

When the second evaluation occurs, the @code{when} expression is evaluated
and if true, prints the first element of the list it receives as its
argument (which is the second element of the original list).  Then the
function calls itself with the @sc{cdr} of the list it is invoked with,
which (the second time around) is the @sc{cdr} of the @sc{cdr} of the
original list.

Note that although we say that the function ``calls itself'', what we mean
is that the Lisp interpreter assembles and instructs a new instance of the
program.  The new instance is a clone of the first, but is a separate
individual.

Each time the function invokes itself, it does so on a shorter version of
the original list.  It creates a new instance that works on a shorter list.

Eventually, the function invokes itself on an empty list.  It creates a new
instance whose argument is @code{nil}.  The conditional expression tests the
value of @code{list}.  Since the value of @code{list} is @code{nil}, the
@code{when} expression tests false so the then-part is not evaluated.  The
function as a whole then returns @code{nil}.

@need 1200
When you evaluate the expression @code{(print-elements-recursively animals)}
in the @file{*scratch*} buffer, you see this result:

@smallexample
@group
gazelle

giraffe

lion

tiger
nil
@end group
@end smallexample

@need 2000
@node Recursieve driehoek functie
@subsection Recursie in plaats van een teller
@findex triangle-recursively

@need 1200
The @code{triangle} function described in a previous section can also be
written recursively.  It looks like this:

@smallexample
@group
(defun triangle-recursively (number)
  "Return the sum of the numbers 1 through NUMBER inclusive.
Uses recursion."
  (if (= number 1)                    ; @r{do-again-test}
      1                               ; @r{then-part}
    (+ number                         ; @r{else-part}
       (triangle-recursively          ; @r{recursive call}
        (1- number)))))               ; @r{next-step-expression}

(triangle-recursively 7)
@end group
@end smallexample

@noindent
You can install this function by evaluating it and then try it by evaluating
@code{(triangle-recursively 7)}.  (Remember to put your cursor immediately
after the last parenthesis of the function definition, before the comment.)
The function evaluates to 28.

To understand how this function works, let's consider what happens in the
various cases when the function is passed 1, 2, 3, or 4 as the value of its
argument.

@menu
* Recursief voorbeeld arg van 1 of 2::  Recursief voorbeeld arg van 1 of 2
* Recursief voorbeeld arg van 3 of 4::  Recursief voorbeeld arg van 3 of 4
@end menu

@ifnottex
@node Recursief voorbeeld arg van 1 of 2
@unnumberedsubsubsec An argument of 1 or 2
@end ifnottex

First, what happens if the value of the argument is 1?

The function has an @code{if} expression after the documentation string.  It
tests whether the value of @code{number} is equal to 1; if so, Emacs
evaluates the then-part of the @code{if} expression, which returns the
number 1 as the value of the function.  (A triangle with one row has one
pebble in it.)

Suppose, however, that the value of the argument is 2.  In this case, Emacs
evaluates the else-part of the @code{if} expression.

@need 1200
The else-part consists of an addition, the recursive call to
@code{triangle-recursively} and a decrementing action; and it looks like
this:

@smallexample
(+ number (triangle-recursively (1- number)))
@end smallexample

When Emacs evaluates this expression, the innermost expression is evaluated
first; then the other parts in sequence.  Here are the steps in detail:

@table @i
@item Step 1 @w{  } Evaluate the innermost expression.

The innermost expression is @code{(1- number)} so Emacs decrements the value
of @code{number} from 2 to 1.

@item Step 2 @w{  } Evaluate the @code{triangle-recursively} function.

The Lisp interpreter creates an individual instance of
@code{triangle-recursively}.  It does not matter that this function is
contained within itself.  Emacs passes the result Step 1 as the argument
used by this instance of the @code{triangle-recursively} function

In this case, Emacs evaluates @code{triangle-recursively} with an argument
of 1.  This means that this evaluation of @code{triangle-recursively}
returns 1.

@item Step 3 @w{  } Evaluate the value of @code{number}.

The variable @code{number} is the second element of the list that starts
with @code{+}; its value is 2.

@item Step 4 @w{  } Evaluate the @code{+} expression.

The @code{+} expression receives two arguments, the first from the
evaluation of @code{number} (Step 3) and the second from the evaluation of
@code{triangle-recursively} (Step 2).

The result of the addition is the sum of 2 plus 1, and the number 3 is
returned, which is correct.  A triangle with two rows has three pebbles in
it.
@end table

@node Recursief voorbeeld arg van 3 of 4
@unnumberedsubsubsec An argument of 3 or 4

Suppose that @code{triangle-recursively} is called with an argument of 3.

@table @i
@item Step 1 @w{  } Evaluate the do-again-test.

The @code{if} expression is evaluated first.  This is the do-again test and
returns false, so the else-part of the @code{if} expression is evaluated.
(Note that in this example, the do-again-test causes the function to call
itself when it tests false, not when it tests true.)

@item Step 2 @w{  } Evaluate the innermost expression of the else-part.

The innermost expression of the else-part is evaluated, which decrements 3
to 2.  This is the next-step-expression.

@item Step 3 @w{  } Evaluate the @code{triangle-recursively} function.

The number 2 is passed to the @code{triangle-recursively} function.

We already know what happens when Emacs evaluates
@code{triangle-recursively} with an argument of 2.  After going through the
sequence of actions described earlier, it returns a value of 3.  So that is
what will happen here.

@item Step 4 @w{  } Evaluate the addition.

3 will be passed as an argument to the addition and will be added to the
number with which the function was called, which is 3.
@end table

@noindent
The value returned by the function as a whole will be 6.

Now that we know what will happen when @code{triangle-recursively} is called
with an argument of 3, it is evident what will happen if it is called with
an argument of 4:

@quotation
@need 800
In the recursive call, the evaluation of

@smallexample
(triangle-recursively (1- 4))
@end smallexample

@need 800
@noindent
will return the value of evaluating

@smallexample
(triangle-recursively 3)
@end smallexample

@noindent
which is 6 and this value will be added to 4 by the addition in the third
line.
@end quotation

@noindent
The value returned by the function as a whole will be 10.

Each time @code{triangle-recursively} is evaluated, it evaluates a version
of itself---a different instance of itself---with a smaller argument, until
the argument is small enough so that it does not evaluate itself.

Note that this particular design for a recursive function requires that
operations be deferred.

Before @code{(triangle-recursively 7)} can calculate its answer, it must
call @code{(triangle-recursively 6)}; and before @code{(triangle-recursively
6)} can calculate its answer, it must call @code{(triangle-recursively 5)};
and so on.  That is to say, the calculation that @code{(triangle-recursively
7)} makes must be deferred until @code{(triangle-recursively 6)} makes its
calculation; and @code{(triangle-recursively 6)} must defer until
@code{(triangle-recursively 5)} completes; and so on.

If each of these instances of @code{triangle-recursively} are thought of as
different robots, the first robot must wait for the second to complete its
job, which must wait until the third completes, and so on.

There is a way around this kind of waiting, which we will discuss in @ref{No
Deferment, , Recursion without Deferments}.

@node Recursie met cond
@subsection Recursion Example Using @code{cond}
@findex cond

The version of @code{triangle-recursively} described earlier is written with
the @code{if} special form.  It can also be written using another special
form called @code{cond}.  The name of the special form @code{cond} is an
abbreviation of the word @samp{conditional}.

Although the @code{cond} special form is not used as often in the Emacs Lisp
sources as @code{if}, it is used often enough to justify explaining it.

@need 800
The template for a @code{cond} expression looks like this:

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

@noindent
where the @var{body} is a series of lists.

@need 800
Written out more fully, the template looks like this:

@smallexample
@group
(cond
 (@var{first-true-or-false-test} @var{first-consequent})
 (@var{second-true-or-false-test} @var{second-consequent})
 (@var{third-true-or-false-test} @var{third-consequent})
  @dots{})
@end group
@end smallexample

When the Lisp interpreter evaluates the @code{cond} expression, it evaluates
the first element (the @sc{car} or true-or-false-test) of the first
expression in a series of expressions within the body of the @code{cond}.

If the true-or-false-test returns @code{nil} the rest of that expression,
the consequent, is skipped and the true-or-false-test of the next expression
is evaluated.  When an expression is found whose true-or-false-test returns
a value that is not @code{nil}, the consequent of that expression is
evaluated.  The consequent can be one or more expressions.  If the
consequent consists of more than one expression, the expressions are
evaluated in sequence and the value of the last one is returned.  If the
expression does not have a consequent, the value of the true-or-false-test
is returned.

If none of the true-or-false-tests test true, the @code{cond} expression
returns @code{nil}.

@need 1250
Written using @code{cond}, the @code{triangle} function looks like this:

@smallexample
@group
(defun triangle-using-cond (number)
  (cond ((<= number 0) 0)
        ((= number 1) 1)
        ((> number 1)
         (+ number (triangle-using-cond (1- number))))))
@end group
@end smallexample

@noindent
In this example, the @code{cond} returns 0 if the number is less than or
equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+ number
(triangle-using-cond (1- number)))} if the number is greater than 1.

@node Recursieve patronen
@subsection Recursieve patronen
@cindex Recursieve patronen

Here are three common recursive patterns.  Each involves a list.  Recursion
does not need to involve lists, but Lisp is designed for lists and this
provides a sense of its primal capabilities.

@menu
* Every::                    Every
* Accumulate::               Accumulate
* Bewaar::                   Bewaar
@end menu

@node Every
@unnumberedsubsubsec Recursief patroon: @emph{every}
@cindex Every, soort van recursief patroon
@cindex Recursive pattern - every

In the @code{every} recursive pattern, an action is performed on every
element of a list.

@need 1500
The basic pattern is:

@itemize @bullet
@item
If a list be empty, return @code{nil}.
@item
Else, act on the beginning of the list (the @sc{car} of the list)
    @itemize @minus
    @item
    through a recursive call by the function on the rest (the @sc{cdr}) of the
list,
    @item
    and, optionally, combine the acted-on element, using @code{cons}, with the
results of acting on the rest.
    @end itemize
@end itemize

@need 1500
Here is an example:

@smallexample
@group
(defun square-each (numbers-list)
  "Square each of a NUMBERS LIST, recursively."
  (if (not numbers-list)                ; do-again-test
      nil
    (cons
     (* (car numbers-list) (car numbers-list))
     (square-each (cdr numbers-list))))) ; next-step-expression
@end group

@group
(square-each '(1 2 3))
    @result{} (1 4 9)
@end group
@end smallexample

@need 1200
@noindent
If @code{numbers-list} is empty, do nothing.  But if it has content,
construct a list combining the square of the first number in the list with
the result of the recursive call.

(The example follows the pattern exactly: @code{nil} is returned if the
numbers' list is empty.  In practice, you would write the conditional so it
carries out the action when the numbers' list is not empty.)

The @code{print-elements-recursively} function (@pxref{Recursion with list,
, Recursion with a List}) is another example of an @code{every} pattern,
except in this case, rather than bring the results together using
@code{cons}, we print each element of output.

@need 1250
The @code{print-elements-recursively} function looks like this:

@smallexample
@group
(setq animals '(gazelle giraffe lion tiger))
@end group

@group
(defun print-elements-recursively (list)
  "Print each element of LIST on a line of its own.
Uses recursion."
  (when list                            ; @r{do-again-test}
        (print (car list))              ; @r{body}
        (print-elements-recursively     ; @r{recursive call}
         (cdr list))))                  ; @r{next-step-expression}

(print-elements-recursively animals)
@end group
@end smallexample

@need 1500
The pattern for @code{print-elements-recursively} is:

@itemize @bullet
@item
When the list is empty, do nothing.
@item
But when the list has at least one element,
    @itemize @minus
    @item
    act on the beginning of the list (the @sc{car} of the list),
    @item
    and make a recursive call on the rest (the @sc{cdr}) of the list.
    @end itemize
@end itemize

@node Accumulate
@unnumberedsubsubsec Recursive Pattern: @emph{accumulate}
@cindex Accumulate, type of recursive pattern
@cindex Recursive pattern - accumulate

Another recursive pattern is called the @code{accumulate} pattern.  In the
@code{accumulate} recursive pattern, an action is performed on every element
of a list and the result of that action is accumulated with the results of
performing the action on the other elements.

This is very like the @code{every} pattern using @code{cons}, except that
@code{cons} is not used, but some other combiner.

@need 1500
Het patroon is:

@itemize @bullet
@item
Als een lijst leeg is, geef nul terug of een andere constante.
@item
Else, act on the beginning of the list (the @sc{car} of the list),
    @itemize @minus
    @item
    and combine that acted-on element, using @code{+} or some other combining
function, with
    @item
    a recursive call by the function on the rest (the @sc{cdr}) of the list.
    @end itemize
@end itemize

@need 1500
Here is an example:

@smallexample
@group
(defun add-elements (numbers-list)
  "Add the elements of NUMBERS-LIST together."
  (if (not numbers-list)
      0
    (+ (car numbers-list) (add-elements (cdr numbers-list)))))
@end group

@group
(add-elements '(1 2 3 4))
    @result{} 10
@end group
@end smallexample

@xref{Files List, , Making a List of Files}, for an example of the
accumulate pattern.

@node Bewaar
@unnumberedsubsubsec Recursive Pattern: @emph{keep}
@cindex Keep, type of recursive pattern
@cindex Recursive pattern - keep

A third recursive pattern is called the @code{keep} pattern.  In the
@code{keep} recursive pattern, each element of a list is tested; the element
is acted on and the results are kept only if the element meets a criterion.

Again, this is very like the @code{every} pattern, except the element is
skipped unless it meets a criterion.

@need 1500
Het patroon heeft drie elementen:

@itemize @bullet
@item
If a list be empty, return @code{nil}.
@item
Else, if the beginning of the list (the @sc{car} of the list) passes a test
    @itemize @minus
    @item
    act on that element and combine it, using @code{cons} with
    @item
    a recursive call by the function on the rest (the @sc{cdr}) of the list.
    @end itemize
@item
Otherwise, if the beginning of the list (the @sc{car} of the list) fails the
test
    @itemize @minus
    @item
    skip on that element,
    @item
    and, recursively call the function on the rest (the @sc{cdr}) of the list.
    @end itemize
@end itemize

@need 1500
Here is an example that uses @code{cond}:

@smallexample
@group
(defun keep-three-letter-words (word-list)
  "Keep three letter words in WORD-LIST."
  (cond
   ;; First do-again-test: stop-condition
   ((not word-list) nil)

   ;; Second do-again-test: when to act
   ((eq 3 (length (symbol-name (car word-list))))
    ;; combine acted-on element with recursive call on shorter list
    (cons (car word-list) (keep-three-letter-words (cdr word-list))))

   ;; Third do-again-test: when to skip element;
   ;;   recursively call shorter list with next-step expression
   (t (keep-three-letter-words (cdr word-list)))))
@end group

@group
(keep-three-letter-words '(one two three four five six))
    @result{} (one two six)
@end group
@end smallexample

It goes without saying that you need not use @code{nil} as the test for when
to stop; and you can, of course, combine these patterns.

@node Geen uitstel
@subsection Recursion without Deferments
@cindex Deferment in recursion
@cindex Recursion without Deferments

Let's consider again what happens with the @code{triangle-recursively}
function.  We will find that the intermediate calculations are deferred
until all can be done.

@need 800
Here is the function definition:

@smallexample
@group
(defun triangle-recursively (number)
  "Return the sum of the numbers 1 through NUMBER inclusive.
Uses recursion."
  (if (= number 1)                    ; @r{do-again-test}
      1                               ; @r{then-part}
    (+ number                         ; @r{else-part}
       (triangle-recursively          ; @r{recursive call}
        (1- number)))))               ; @r{next-step-expression}
@end group
@end smallexample

What happens when we call this function with an argument of 7?

The first instance of the @code{triangle-recursively} function adds the
number 7 to the value returned by a second instance of
@code{triangle-recursively}, an instance that has been passed an argument of
6.  That is to say, the first calculation is:

@smallexample
(+ 7 (triangle-recursively 6))
@end smallexample

@noindent
The first instance of @code{triangle-recursively}---you may want to think of
it as a little robot---cannot complete its job.  It must hand off the
calculation for @code{(triangle-recursively 6)} to a second instance of the
program, to a second robot.  This second individual is completely different
from the first one; it is, in the jargon, a ``different instantiation''.
Or, put another way, it is a different robot.  It is the same model as the
first; it calculates triangle numbers recursively; but it has a different
serial number.

And what does @code{(triangle-recursively 6)} return? It returns the number
6 added to the value returned by evaluating @code{triangle-recursively} with
an argument of 5.  Using the robot metaphor, it asks yet another robot to
help it.

@need 800
Now the total is:

@smallexample
(+ 7 6 (triangle-recursively 5))
@end smallexample

@need 800
And what happens next?

@smallexample
(+ 7 6 5 (triangle-recursively 4))
@end smallexample

Each time @code{triangle-recursively} is called, except for the last time,
it creates another instance of the program---another robot---and asks it to
make a calculation.

@need 800
Eventually, the full addition is set up and performed:

@smallexample
(+ 7 6 5 4 3 2 1)
@end smallexample

This design for the function defers the calculation of the first step until
the second can be done, and defers that until the third can be done, and so
on.  Each deferment means the computer must remember what is being waited
on.  This is not a problem when there are only a few steps, as in this
example.  But it can be a problem when there are more steps.

@node Geen uitstel oplossing
@subsection Geen uitstel oplossing
@cindex Geen uitstel oplossing
@cindex Oplossing zonder uitstel

The solution to the problem of deferred operations is to write in a manner
that does not defer operations@footnote{The phrase @dfn{tail recursive} is
used to describe such a process, one that uses constant space.}.  This
requires writing to a different pattern, often one that involves writing two
function definitions, an initialization function and a helper function.

The initialization function sets up the job; the helper function does the
work.

@need 1200
Here are the two function definitions for adding up numbers.  They are so
simple, I find them hard to understand.

@smallexample
@group
(defun triangle-initialization (number)
  "Return the sum of the numbers 1 through NUMBER inclusive.
This is the initialization component of a two function
duo that uses recursion."
  (triangle-recursive-helper 0 0 number))
@end group
@end smallexample

@smallexample
@group
(defun triangle-recursive-helper (sum counter number)
  "Return SUM, using COUNTER, through NUMBER inclusive.
This is the helper component of a two function duo
that uses recursion."
  (if (> counter number)
      sum
    (triangle-recursive-helper (+ sum counter)  ; @r{sum}
                               (1+ counter)     ; @r{counter}
                               number)))        ; @r{number}
@end group
@end smallexample

@need 1250
Install both function definitions by evaluating them, then call
@code{triangle-initialization} with 2 rows:

@smallexample
@group
(triangle-initialization 2)
    @result{} 3
@end group
@end smallexample

The initialization function calls the first instance of the helper function
with three arguments: zero, zero, and a number which is the number of rows
in the triangle.

The first two arguments passed to the helper function are initialization
values.  These values are changed when @code{triangle-recursive-helper}
invokes new instances.@footnote{The jargon is mildly confusing:
@code{triangle-recursive-helper} uses a process that is iterative in a
procedure that is recursive.  The process is called iterative because the
computer need only record the three values, @code{sum}, @code{counter}, and
@code{number}; the procedure is recursive because the function calls
itself.  On the other hand, both the process and the procedure used by
@code{triangle-recursively} are called recursive.  The word ``recursive''
has different meanings in the two contexts.}

Let's see what happens when we have a triangle that has one row.  (This
triangle will have one pebble in it!)

@need 1200
@code{triangle-initialization} will call its helper with the arguments
@w{@code{0 0 1}}.  That function will run the conditional test whether
@code{(> counter number)}:

@smallexample
(> 0 1)
@end smallexample

@need 1200
@noindent
and find that the result is false, so it will invoke the else-part of the
@code{if} clause:

@smallexample
@group
    (triangle-recursive-helper
     (+ sum counter)  ; @r{sum plus counter} @result{} @r{sum}
     (1+ counter)     ; @r{increment counter} @result{} @r{counter}
     number)          ; @r{number stays the same}
@end group
@end smallexample

@need 800
@noindent
which will first compute:

@smallexample
@group
(triangle-recursive-helper (+ 0 0)  ; @r{sum}
                           (1+ 0)   ; @r{counter}
                           1)       ; @r{number}
@exdent which is:

(triangle-recursive-helper 0 1 1)
@end group
@end smallexample

Again, @code{(> counter number)} will be false, so again, the Lisp
interpreter will evaluate @code{triangle-recursive-helper}, creating a new
instance with new arguments.

@need 800
This new instance will be;

@smallexample
@group
    (triangle-recursive-helper
     (+ sum counter)  ; @r{sum plus counter} @result{} @r{sum}
     (1+ counter)     ; @r{increment counter} @result{} @r{counter}
     number)          ; @r{number stays the same}

@exdent which is:

(triangle-recursive-helper 1 2 1)
@end group
@end smallexample

In this case, the @code{(> counter number)} test will be true! So the
instance will return the value of the sum, which will be 1, as expected.

Now, let's pass @code{triangle-initialization} an argument of 2, to find out
how many pebbles there are in a triangle with two rows.

That function calls @code{(triangle-recursive-helper 0 0 2)}.

@need 800
In stages, the instances called will be:

@smallexample
@group
                          @r{sum counter number}
(triangle-recursive-helper 0    1       2)

(triangle-recursive-helper 1    2       2)

(triangle-recursive-helper 3    3       2)
@end group
@end smallexample

When the last instance is called, the @code{(> counter number)} test will be
true, so the instance will return the value of @code{sum}, which will be 3.

This kind of pattern helps when you are writing functions that can use many
resources in a computer.

@need 1500
@node Looping oefening
@section Looping Exercise

@itemize @bullet
@item
Write a function similar to @code{triangle} in which each row has a value
which is the square of the row number.  Use a @code{while} loop.

@item
Write a function similar to @code{triangle} that multiplies instead of adds
the values.

@item
Rewrite these two functions recursively.  Rewrite these functions using
@code{cond}.

@c comma in printed title causes problem in Info cross reference
@item
Write a function for Texinfo mode that creates an index entry at the
beginning of a paragraph for every @samp{@@dfn} within the paragraph.  (In a
Texinfo file, @samp{@@dfn} marks a definition.  This book is written in
Texinfo.)

Many of the functions you will need are described in two of the previous
chapters, @ref{Cutting & Storing Text, , Cutting and Storing Text}, and
@ref{Yanking, , Yanking Text Back}.  If you use @code{forward-paragraph} to
put the index entry at the beginning of the paragraph, you will have to use
@w{@kbd{C-h f}} (@code{describe-function}) to find out how to make the
command go backwards.

For more information, see
@ifinfo
@ref{Indicating, , Indicating Definitions, texinfo}.
@end ifinfo
@ifhtml
@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to a
Texinfo manual in the current directory.  Or, if you are on the Internet,
see @uref{https://www.gnu.org/software/texinfo/manual/texinfo/}
@end ifhtml
@iftex
``Indicating Definitions, Commands, etc.''@: in @cite{Texinfo, The GNU
Documentation Format}.
@end iftex
@end itemize

@node Regexp zoeken
@chapter Reguliere expressie zoekopdrachten
@cindex Searches, illustrating
@cindex Reguliere expressie zoekopdrachten
@cindex Patronen, zoeken naar
@cindex Motion by sentence and paragraph
@cindex Sentences, movement by
@cindex Paragraphs, movement by

Regular expression searches are used extensively in GNU Emacs.  The two
functions, @code{forward-sentence} and @code{forward-paragraph}, illustrate
these searches well.  They use regular expressions to find where to move
point.  The phrase ``regular expression'' is often written as ``regexp''.

Reguliere expressie zoekopdrachten zijn beschreven in @ref{Regexp Search, ,
Regular Expression Search, emacs, The GNU Emacs Manual}, en ook in
@ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference
Manual}. Tijdens het schrijven van dit hoofdstuk ga ik er vanuit dat je
tenminste een beetje met ze kennis gemaakt hebt. Het belangrijkste punt om
te onthouden is dat reguliere expressies je in staat stellen naar patronen
te zoeken en ook naar letterlijke karakterstrings. De code in
@code{forward-sentence} zoekt bijvoorbeeld naar patronen van mogelijke
karakters die het einde van een zin kunnen markeren, en verplaatst point
naar die plek.

Before looking at the code for the @code{forward-sentence} function, it is
worth considering what the pattern that marks the end of a sentence must
be.  The pattern is discussed in the next section; following that is a
description of the regular expression search function,
@code{re-search-forward}.  The @code{forward-sentence} function is described
in the section following.  Finally, the @code{forward-paragraph} function is
described in the last section of this chapter.  @code{forward-paragraph} is
a complex function that introduces several new features.

@menu
* sentence-end::             De reguliere expressie van @code{sentence-end}.
* re-search-forward::        Erg vergelijkbaar met @code{search-forward}.
* forward-sentence::         Een eenvoudig voorbeeld van regexp 
                               zoekopdracht.
* forward-paragraph::        Een iets complexer voorbeeld.
* Regexp terugblik::         Regexp terugblik
* re-search oefeningen::     re-search oefeningen
@end menu

@node sentence-end
@section The Regular Expression for @code{sentence-end}
@findex sentence-end

The symbol @code{sentence-end} is bound to the pattern that marks the end of
a sentence.  What should this regular expression be?

Clearly, a sentence may be ended by a period, a question mark, or an
exclamation mark.  Indeed, in English, only clauses that end with one of
those three characters should be considered the end of a sentence.  This
means that the pattern should include the character set:

@smallexample
[.?!]
@end smallexample

However, we do not want @code{forward-sentence} merely to jump to a period,
a question mark, or an exclamation mark, because such a character might be
used in the middle of a sentence.  A period, for example, is used after
abbreviations.  So other information is needed.

According to convention, you type two spaces after every sentence, but only
one space after a period, a question mark, or an exclamation mark in the
body of a sentence.  So a period, a question mark, or an exclamation mark
followed by two spaces is a good indicator of an end of sentence.  However,
in a file, the two spaces may instead be a tab or the end of a line.  This
means that the regular expression should include these three items as
alternatives.

@need 800
This group of alternatives will look like this:

@smallexample
@group
\\($\\| \\|  \\)
       ^   ^^
      TAB  SPC
@end group
@end smallexample

@noindent
Here, @samp{$} indicates the end of the line, and I have pointed out where
the tab and two spaces are inserted in the expression.  Both are inserted by
putting the actual characters into the expression.

Two backslashes, @samp{\\}, are required before the parentheses and vertical
bars: the first backslash quotes the following backslash in Emacs; and the
second indicates that the following character, the parenthesis or the
vertical bar, is special.

@need 1000
Also, a sentence may be followed by one or more carriage returns, like this:

@smallexample
@group
[
]*
@end group
@end smallexample

@noindent
Like tabs and spaces, a carriage return is inserted into a regular
expression by inserting it literally.  The asterisk indicates that the
@key{RET} is repeated zero or more times.

But a sentence end does not consist only of a period, a question mark or an
exclamation mark followed by appropriate space: a closing quotation mark or
a closing brace of some kind may precede the space.  Indeed more than one
such mark or brace may precede the space.  These require a expression that
looks like this:

@smallexample
[]\"')@}]*
@end smallexample

In this expression, the first @samp{]} is the first character in the
expression; the second character is @samp{"}, which is preceded by a
@samp{\} to tell Emacs the @samp{"} is @emph{not} special.  The last three
characters are @samp{'}, @samp{)}, and @samp{@}}.

All this suggests what the regular expression pattern for matching the end
of a sentence should be; and, indeed, if we evaluate @code{sentence-end} we
find that it returns the following value:

@smallexample
@group
sentence-end
     @result{} "[.?!][]\"')@}]*\\($\\|     \\|  \\)[
]*"
@end group
@end smallexample

@noindent
(Well, not in GNU Emacs 22; that is because of an effort to make the process
simpler and to handle more glyphs and languages.  When the value of
@code{sentence-end} is @code{nil}, then use the value defined by the
function @code{sentence-end}.  (Here is a use of the difference between a
value and a function in Emacs Lisp.)  The function returns a value
constructed from the variables @code{sentence-end-base},
@code{sentence-end-double-space}, @code{sentence-end-without-period}, and
@code{sentence-end-without-space}.  The critical variable is
@code{sentence-end-base}; its global value is similar to the one described
above but it also contains two additional quotation marks.  These have
differing degrees of curliness.  The @code{sentence-end-without-period}
variable, when true, tells Emacs that a sentence may end without a period,
such as text in Thai.)

@ignore
@noindent
(Note that here the @key{TAB}, two spaces, and  @key{RET} are shown
literally in the pattern.)

This regular expression can be deciphered as follows:

@table @code
@item [.?!]
The first part of the pattern is the three characters, a period, a question
mark and an exclamation mark, within square brackets.  The pattern must
begin with one or other of these characters.

@item []\"')@}]*
The second part of the pattern is the group of closing braces and
quotation marks, which can appear zero or more times.  These may follow
the period, question mark or exclamation mark.  In a regular expression,
the backslash, @samp{\}, followed by the double quotation mark,
@samp{"}, indicates the class of string-quote characters.  Usually, the
double quotation mark is the only character in this class.  The
asterisk, @samp{*}, indicates that the items in the previous group (the
group surrounded by square brackets, @samp{[]}) may be repeated zero or
more times.

@item \\($\\|   \\|  \\)
The third part of the pattern is one or other of: either the end of a
line, or two blank spaces, or a tab.  The double back-slashes are used
to prevent Emacs from reading the parentheses and vertical bars as part
of the search pattern; the parentheses are used to mark the group and
the vertical bars are used to indicated that the patterns to either side
of them are alternatives.  The dollar sign is used to indicate the end
of a line and both the two spaces and the tab are each inserted as is to
indicate what they are.

@item [@key{RET}]*
Finally, the last part of the pattern indicates that the end of the line
or the whitespace following the period, question mark or exclamation
mark may, but need not, be followed by one or more carriage returns.  In
the pattern, the carriage return is inserted as an actual carriage
return between square brackets but here it is shown as @key{RET}.
@end table
@end ignore

@node re-search-forward
@section The @code{re-search-forward} Function
@findex re-search-forward

The @code{re-search-forward} function is very like the @code{search-forward}
function.  (@xref{search-forward, , The @code{search-forward} Function}.)

@code{re-search-forward} searches for a regular expression.  If the search
is successful, it leaves point immediately after the last character in the
target.  If the search is backwards, it leaves point just before the first
character in the target.  You may tell @code{re-search-forward} to return
@code{t} for true.  (Moving point is therefore a side effect.)

Like @code{search-forward}, the @code{re-search-forward} function takes four
arguments:

@enumerate
@item
The first argument is the regular expression that the function searches
for.  The regular expression will be a string between quotation marks.

@item
The optional second argument limits how far the function will search; it is
a bound, which is specified as a position in the buffer.

@item
The optional third argument specifies how the function responds to failure:
@code{nil} as the third argument causes the function to signal an error (and
print a message) when the search fails; any other value causes it to return
@code{nil} if the search fails and @code{t} if the search succeeds.

@item
The optional fourth argument is the repeat count.  A negative repeat count
causes @code{re-search-forward} to search backwards.
@end enumerate

@need 800
The template for @code{re-search-forward} looks like this:

@smallexample
@group
(re-search-forward "@var{regular-expression}"
                @var{limit-of-search}
                @var{what-to-do-if-search-fails}
                @var{repeat-count})
@end group
@end smallexample

The second, third, and fourth arguments are optional.  However, if you want
to pass a value to either or both of the last two arguments, you must also
pass a value to all the preceding arguments.  Otherwise, the Lisp
interpreter will mistake which argument you are passing the value to.

@need 1200
In the @code{forward-sentence} function, the regular expression will be the
value of the variable @code{sentence-end}.  In simple form, that is:

@smallexample
@group
"[.?!][]\"')@}]*\\($\\|  \\|  \\)[
]*"
@end group
@end smallexample

@noindent
The limit of the search will be the end of the paragraph (since a sentence
cannot go beyond a paragraph).  If the search fails, the function will
return @code{nil}; and the repeat count will be provided by the argument to
the @code{forward-sentence} function.

@node forward-sentence
@section @code{forward-sentence}
@findex forward-sentence

The command to move the cursor forward a sentence is a straightforward
illustration of how to use regular expression searches in Emacs Lisp.
Indeed, the function looks longer and more complicated than it is; this is
because the function is designed to go backwards as well as forwards; and,
optionally, over more than one sentence.  The function is usually bound to
the key command @kbd{M-e}.

@menu
* Complete forward-sentence::  Complete forward-sentence
* fwd-sentence while loops::  Twee @code{while} loops.
* fwd-sentence re-search::   Een reguliere expressie zoekopdracht.
@end menu

@ifnottex
@node Complete forward-sentence
@unnumberedsubsec Complete @code{forward-sentence} function definition
@end ifnottex

@need 1250
Here is the code for @code{forward-sentence}:

@c in GNU Emacs 22
@smallexample
@group
(defun forward-sentence (&optional arg)
  "Move forward to next end of sentence.  With argument, repeat.
With negative argument, move backward repeatedly to start of sentence.

The variable `sentence-end' is a regular expression that matches ends of
sentences.  Also, every paragraph boundary terminates sentences as well."
@end group
@group
  (interactive "p")
  (or arg (setq arg 1))
  (let ((opoint (point))
        (sentence-end (sentence-end)))
    (while (< arg 0)
      (let ((pos (point))
            (par-beg (save-excursion (start-of-paragraph-text) (point))))
       (if (and (re-search-backward sentence-end par-beg t)
                (or (< (match-end 0) pos)
                    (re-search-backward sentence-end par-beg t)))
           (goto-char (match-end 0))
         (goto-char par-beg)))
      (setq arg (1+ arg)))
@end group
@group
    (while (> arg 0)
      (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
       (if (re-search-forward sentence-end par-end t)
           (skip-chars-backward " \t\n")
         (goto-char par-end)))
      (setq arg (1- arg)))
    (constrain-to-field nil opoint t)))
@end group
@end smallexample

@ignore
GNU Emacs 21
@smallexample
@group
(defun forward-sentence (&optional arg)
  "Move forward to next sentence-end.  With argument, repeat.
With negative argument, move backward repeatedly to sentence-beginning.
Sentence ends are identified by the value of sentence-end
treated as a regular expression.  Also, every paragraph boundary
terminates sentences as well."
@end group
@group
  (interactive "p")
  (or arg (setq arg 1))
  (while (< arg 0)
    (let ((par-beg
           (save-excursion (start-of-paragraph-text) (point))))
      (if (re-search-backward
           (concat sentence-end "[^ \t\n]") par-beg t)
          (goto-char (1- (match-end 0)))
        (goto-char par-beg)))
    (setq arg (1+ arg)))
  (while (> arg 0)
    (let ((par-end
           (save-excursion (end-of-paragraph-text) (point))))
      (if (re-search-forward sentence-end par-end t)
          (skip-chars-backward " \t\n")
        (goto-char par-end)))
    (setq arg (1- arg))))
@end group
@end smallexample
@end ignore

The function looks long at first sight and it is best to look at its
skeleton first, and then its muscle.  The way to see the skeleton is to look
at the expressions that start in the left-most columns:

@smallexample
@group
(defun forward-sentence (&optional arg)
  "@var{documentation}@dots{}"
  (interactive "p")
  (or arg (setq arg 1))
  (let ((opoint (point)) (sentence-end (sentence-end)))
    (while (< arg 0)
      (let ((pos (point))
            (par-beg (save-excursion (start-of-paragraph-text) (point))))
       @var{rest-of-body-of-while-loop-when-going-backwards}
    (while (> arg 0)
      (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
       @var{rest-of-body-of-while-loop-when-going-forwards}
    @var{handle-forms-and-equivalent}
@end group
@end smallexample

This looks much simpler! The function definition consists of documentation,
an @code{interactive} expression, an @code{or} expression, a @code{let}
expression, and @code{while} loops.

Let's look at each of these parts in turn.

We note that the documentation is thorough and understandable.

The function has an @code{interactive "p"} declaration.  This means that the
processed prefix argument, if any, is passed to the function as its
argument.  (This will be a number.)  If the function is not passed an
argument (it is optional) then the argument @code{arg} will be bound to 1.

When @code{forward-sentence} is called non-interactively without an
argument, @code{arg} is bound to @code{nil}.  The @code{or} expression
handles this.  What it does is either leave the value of @code{arg} as it
is, but only if @code{arg} is bound to a value; or it sets the value of
@code{arg} to 1, in the case when @code{arg} is bound to @code{nil}.

Next is a @code{let}.  That specifies the values of two local variables,
@code{opoint} and @code{sentence-end}.  The local value of point, from
before the search, is used in the @code{constrain-to-field} function which
handles forms and equivalents.  The @code{sentence-end} variable is set by
the @code{sentence-end} function.

@node fwd-sentence while loops
@unnumberedsubsec The @code{while} loops

Two @code{while} loops follow.  The first @code{while} has a
true-or-false-test that tests true if the prefix argument for
@code{forward-sentence} is a negative number.  This is for going backwards.
The body of this loop is similar to the body of the second @code{while}
clause, but it is not exactly the same.  We will skip this @code{while} loop
and concentrate on the second @code{while} loop.

@need 1500
The second @code{while} loop is for moving point forward.  Its skeleton
looks like this:

@smallexample
@group
(while (> arg 0)            ; @r{true-or-false-test}
  (let @var{varlist}
    (if (@var{true-or-false-test})
        @var{then-part}
      @var{else-part}
  (setq arg (1- arg))))     ; @code{while} @r{loop decrementer}
@end group
@end smallexample

The @code{while} loop is of the decrementing kind.  (@xref{Decrementing
Loop, , A Loop with a Decrementing Counter}.)  It has a true-or-false-test
that tests true so long as the counter (in this case, the variable
@code{arg}) is greater than zero; and it has a decrementer that subtracts 1
from the value of the counter every time the loop repeats.

If no prefix argument is given to @code{forward-sentence}, which is the most
common way the command is used, this @code{while} loop will run once, since
the value of @code{arg} will be 1.

The body of the @code{while} loop consists of a @code{let} expression, which
creates and binds a local variable, and has, as its body, an @code{if}
expression.

@need 1250
The body of the @code{while} loop looks like this:

@smallexample
@group
(let ((par-end
       (save-excursion (end-of-paragraph-text) (point))))
  (if (re-search-forward sentence-end par-end t)
      (skip-chars-backward " \t\n")
    (goto-char par-end)))
@end group
@end smallexample

The @code{let} expression creates and binds the local variable
@code{par-end}.  As we shall see, this local variable is designed to provide
a bound or limit to the regular expression search.  If the search fails to
find a proper sentence ending in the paragraph, it will stop on reaching the
end of the paragraph.

But first, let us examine how @code{par-end} is bound to the value of the
end of the paragraph.  What happens is that the @code{let} sets the value of
@code{par-end} to the value returned when the Lisp interpreter evaluates the
expression

@smallexample
@group
(save-excursion (end-of-paragraph-text) (point))
@end group
@end smallexample

@noindent
In this expression, @code{(end-of-paragraph-text)} moves point to the end of
the paragraph, @code{(point)} returns the value of point, and then
@code{save-excursion} restores point to its original position.  Thus, the
@code{let} binds @code{par-end} to the value returned by the
@code{save-excursion} expression, which is the position of the end of the
paragraph.  (The @code{end-of-paragraph-text} function uses
@code{forward-paragraph}, which we will discuss shortly.)

@need 1200
Emacs next evaluates the body of the @code{let}, which is an @code{if}
expression that looks like this:

@smallexample
@group
(if (re-search-forward sentence-end par-end t) ; @r{if-part}
    (skip-chars-backward " \t\n")              ; @r{then-part}
  (goto-char par-end)))                        ; @r{else-part}
@end group
@end smallexample

The @code{if} tests whether its first argument is true and if so, evaluates
its then-part; otherwise, the Emacs Lisp interpreter evaluates the
else-part.  The true-or-false-test of the @code{if} expression is the
regular expression search.

It may seem odd to have what looks like the real work of the
@code{forward-sentence} function buried here, but this is a common way this
kind of operation is carried out in Lisp.

@node fwd-sentence re-search
@unnumberedsubsec The regular expression search

The @code{re-search-forward} function searches for the end of the sentence,
that is, for the pattern defined by the @code{sentence-end} regular
expression.  If the pattern is found---if the end of the sentence is
found---then the @code{re-search-forward} function does two things:

@enumerate
@item
The @code{re-search-forward} function carries out a side effect, which is to
move point to the end of the occurrence found.

@item
The @code{re-search-forward} function returns a value of true.  This is the
value received by the @code{if}, and means that the search was successful.
@end enumerate

@noindent
The side effect, the movement of point, is completed before the @code{if}
function is handed the value returned by the successful conclusion of the
search.

When the @code{if} function receives the value of true from a successful
call to @code{re-search-forward}, the @code{if} evaluates the then-part,
which is the expression @code{(skip-chars-backward " \t\n")}.  This
expression moves backwards over any blank spaces, tabs or carriage returns
until a printed character is found and then leaves point after the
character.  Since point has already been moved to the end of the pattern
that marks the end of the sentence, this action leaves point right after the
closing printed character of the sentence, which is usually a period.

On the other hand, if the @code{re-search-forward} function fails to find a
pattern marking the end of the sentence, the function returns false.  The
false then causes the @code{if} to evaluate its third argument, which is
@code{(goto-char par-end)}: it moves point to the end of the paragraph.

(And if the text is in a form or equivalent, and point may not move fully,
then the @code{constrain-to-field} function comes into play.)

Regular expression searches are exceptionally useful and the pattern
illustrated by @code{re-search-forward}, in which the search is the test of
an @code{if} expression, is handy.  You will see or write code incorporating
this pattern often.

@node forward-paragraph
@section @code{forward-paragraph}: een goudmijn van functies
@findex forward-paragraph

@ignore
@c in GNU Emacs 22
(defun forward-paragraph (&optional arg)
  "Move forward to end of paragraph.
With argument ARG, do it ARG times;
a negative argument ARG = -N means move backward N paragraphs.

A line which `paragraph-start' matches either separates paragraphs
\(if `paragraph-separate' matches it also) or is the first line of a paragraph.
A paragraph end is the beginning of a line which is not part of the paragraph
to which the end of the previous line belongs, or the end of the buffer.
Returns the count of paragraphs left to move."
  (interactive "p")
  (or arg (setq arg 1))
  (let* ((opoint (point))
         (fill-prefix-regexp
          (and fill-prefix (not (equal fill-prefix ""))
               (not paragraph-ignore-fill-prefix)
               (regexp-quote fill-prefix)))
         ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
         ;; These regexps shouldn't be anchored, because we look for them
         ;; starting at the left-margin.  This allows paragraph commands to
         ;; work normally with indented text.
         ;; This hack will not find problem cases like "whatever\\|^something".
         (parstart (if (and (not (equal "" paragraph-start))
                            (equal ?^ (aref paragraph-start 0)))
                       (substring paragraph-start 1)
                     paragraph-start))
         (parsep (if (and (not (equal "" paragraph-separate))
                          (equal ?^ (aref paragraph-separate 0)))
                     (substring paragraph-separate 1)
                   paragraph-separate))
         (parsep
          (if fill-prefix-regexp
              (concat parsep "\\|"
                      fill-prefix-regexp "[ \t]*$")
            parsep))
         ;; This is used for searching.
         (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
         start found-start)
    (while (and (< arg 0) (not (bobp)))
      (if (and (not (looking-at parsep))
               (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
               (looking-at parsep))
          (setq arg (1+ arg))
        (setq start (point))
        ;; Move back over paragraph-separating lines.
        (forward-char -1) (beginning-of-line)
        (while (and (not (bobp))
                    (progn (move-to-left-margin)
                           (looking-at parsep)))
          (forward-line -1))
        (if (bobp)
            nil
          (setq arg (1+ arg))
          ;; Go to end of the previous (non-separating) line.
          (end-of-line)
          ;; Search back for line that starts or separates paragraphs.
          (if (if fill-prefix-regexp
                  ;; There is a fill prefix; it overrides parstart.
                  (let (multiple-lines)
                    (while (and (progn (beginning-of-line) (not (bobp)))
                                (progn (move-to-left-margin)
                                       (not (looking-at parsep)))
                                (looking-at fill-prefix-regexp))
                      (unless (= (point) start)
                        (setq multiple-lines t))
                      (forward-line -1))
                    (move-to-left-margin)
                    ;; This deleted code caused a long hanging-indent line
                    ;; not to be filled together with the following lines.
                    ;; ;; Don't move back over a line before the paragraph
                    ;; ;; which doesn't start with fill-prefix
                    ;; ;; unless that is the only line we've moved over.
                    ;; (and (not (looking-at fill-prefix-regexp))
                    ;;      multiple-lines
                    ;;      (forward-line 1))
                    (not (bobp)))
                (while (and (re-search-backward sp-parstart nil 1)
                            (setq found-start t)
                            ;; Found a candidate, but need to check if it is a
                            ;; REAL parstart.
                            (progn (setq start (point))
                                   (move-to-left-margin)
                                   (not (looking-at parsep)))
                            (not (and (looking-at parstart)
                                      (or (not use-hard-newlines)
                                          (bobp)
                                          (get-text-property
                                           (1- start) 'hard)))))
                  (setq found-start nil)
                  (goto-char start))
                found-start)
              ;; Found one.
              (progn
                ;; Move forward over paragraph separators.
                ;; We know this cannot reach the place we started
                ;; because we know we moved back over a non-separator.
                (while (and (not (eobp))
                            (progn (move-to-left-margin)
                                   (looking-at parsep)))
                  (forward-line 1))
                ;; If line before paragraph is just margin, back up to there.
                (end-of-line 0)
                (if (> (current-column) (current-left-margin))
                    (forward-char 1)
                  (skip-chars-backward " \t")
                  (if (not (bolp))
                      (forward-line 1))))
            ;; No starter or separator line => use buffer beg.
            (goto-char (point-min))))))

    (while (and (> arg 0) (not (eobp)))
      ;; Move forward over separator lines...
      (while (and (not (eobp))
                  (progn (move-to-left-margin) (not (eobp)))
                  (looking-at parsep))
        (forward-line 1))
      (unless (eobp) (setq arg (1- arg)))
      ;; ... and one more line.
      (forward-line 1)
      (if fill-prefix-regexp
          ;; There is a fill prefix; it overrides parstart.
          (while (and (not (eobp))
                      (progn (move-to-left-margin) (not (eobp)))
                      (not (looking-at parsep))
                      (looking-at fill-prefix-regexp))
            (forward-line 1))
        (while (and (re-search-forward sp-parstart nil 1)
                    (progn (setq start (match-beginning 0))
                           (goto-char start)
                           (not (eobp)))
                    (progn (move-to-left-margin)
                           (not (looking-at parsep)))
                    (or (not (looking-at parstart))
                        (and use-hard-newlines
                             (not (get-text-property (1- start) 'hard)))))
          (forward-char 1))
        (if (< (point) (point-max))
            (goto-char start))))
    (constrain-to-field nil opoint t)
    ;; Return the number of steps that could not be done.
    arg))
@end ignore

The @code{forward-paragraph} function moves point forward to the end of the
paragraph.  It is usually bound to @kbd{M-@}} and makes use of a number of
functions that are important in themselves, including @code{let*},
@code{match-beginning}, and @code{looking-at}.

The function definition for @code{forward-paragraph} is considerably longer
than the function definition for @code{forward-sentence} because it works
with a paragraph, each line of which may begin with a fill prefix.

A fill prefix consists of a string of characters that are repeated at the
beginning of each line.  For example, in Lisp code, it is a convention to
start each line of a paragraph-long comment with @samp{;;; }.  In Text mode,
four blank spaces make up another common fill prefix, creating an indented
paragraph.  (@xref{Fill Prefix, , , emacs, The GNU Emacs Manual}, for more
information about fill prefixes.)

The existence of a fill prefix means that in addition to being able to find
the end of a paragraph whose lines begin on the left-most column, the
@code{forward-paragraph} function must be able to find the end of a
paragraph when all or many of the lines in the buffer begin with the fill
prefix.

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

@menu
* forward-paragraph in het kort::  Belangrijke onderdelen van de 
                                     functiedefinitie.
* fwd-para let::             De @code{let*} expressie
* fwd-para while::           De voorwaartse beweging @code{while} loop.
@end menu

@ifnottex
@node forward-paragraph in het kort
@unnumberedsubsec Shortened @code{forward-paragraph} function definition
@end ifnottex

Rather than print all of the @code{forward-paragraph} function, we will only
print parts of it.  Read without preparation, the function can be daunting!

@need 800
In outline, the function looks like this:

@smallexample
@group
(defun forward-paragraph (&optional arg)
  "@var{documentation}@dots{}"
  (interactive "p")
  (or arg (setq arg 1))
  (let*
      @var{varlist}
    (while (and (< arg 0) (not (bobp)))     ; @r{backward-moving-code}
      @dots{}
    (while (and (> arg 0) (not (eobp)))     ; @r{forward-moving-code}
      @dots{}
@end group
@end smallexample

The first parts of the function are routine: the function's argument list
consists of one optional argument.  Documentation follows.

The lower case @samp{p} in the @code{interactive} declaration means that the
processed prefix argument, if any, is passed to the function.  This will be
a number, and is the repeat count of how many paragraphs point will move.
The @code{or} expression in the next line handles the common case when no
argument is passed to the function, which occurs if the function is called
from other code rather than interactively.  This case was described
earlier.  (@xref{forward-sentence, The @code{forward-sentence} function}.)
Now we reach the end of the familiar part of this function.

@node fwd-para let
@unnumberedsubsec The @code{let*} expression

@findex let*
The next line of the @code{forward-paragraph} function begins a @code{let*}
expression (@pxref{let* introduced,,@code{let*} introduced}), in which Emacs
binds a total of seven variables: @code{opoint}, @code{fill-prefix-regexp},
@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
@code{found-start}.  The first part of the @code{let*} expression looks like
below:

@smallexample
@group
(let* ((opoint (point))
       (fill-prefix-regexp
        (and fill-prefix (not (equal fill-prefix ""))
             (not paragraph-ignore-fill-prefix)
             (regexp-quote fill-prefix)))
       ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
       ;; These regexps shouldn't be anchored, because we look for them
       ;; starting at the left-margin.  This allows paragraph commands to
       ;; work normally with indented text.
       ;; This hack will not find problem cases like "whatever\\|^something".
       (parstart (if (and (not (equal "" paragraph-start))
                          (equal ?^ (aref paragraph-start 0)))
                     (substring paragraph-start 1)
                   paragraph-start))
       (parsep (if (and (not (equal "" paragraph-separate))
                        (equal ?^ (aref paragraph-separate 0)))
                   (substring paragraph-separate 1)
                 paragraph-separate))
       (parsep
        (if fill-prefix-regexp
            (concat parsep "\\|"
                    fill-prefix-regexp "[ \t]*$")
          parsep))
       ;; This is used for searching.
       (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
       start found-start)
  ...)
@end group
@end smallexample

The variable @code{parsep} appears twice, first, to remove instances of
@samp{^}, and second, to handle fill prefixes.

The variable @code{opoint} is just the value of @code{point}.  As you can
guess, it is used in a @code{constrain-to-field} expression, just as in
@code{forward-sentence}.

The variable @code{fill-prefix-regexp} is set to the value returned by
evaluating the following list:

@smallexample
@group
(and fill-prefix
     (not (equal fill-prefix ""))
     (not paragraph-ignore-fill-prefix)
     (regexp-quote fill-prefix))
@end group
@end smallexample

@noindent
This is an expression whose first element is the @code{and} special form.

Zoals we eerder (@pxref{kill-new functie, , De @code{kill-new} functie})
leerden, evalueert de speciale vorm @code{and} elk van zijn argumenten tot
dat een van de de argumenten een waarde @code{nil} teruggeeft, in dat geval
geeft de @code{and} een waarde @code{nil} terug. Echter, wnanneer geen van
de arugmenten een waarde @code{nil} teruggeeft, wordt de waarde die het
resultaaat van het evalueren van het laatste argument teruggegeven. (Omdat
zo'n waarde niet @code{nil} is, wordt het als waar beschouwt in Lisp.) Met
andere woorden, een @code{and} expressie geeft alleen een waarde waar terug
wanneer al zijn argumenten waar zijn.
@findex and

In this case, the variable @code{fill-prefix-regexp} is bound to a
non-@code{nil} value only if the following four expressions produce a true
(i.e., a non-@code{nil}) value when they are evaluated; otherwise,
@code{fill-prefix-regexp} is bound to @code{nil}.

@table @code
@item fill-prefix
When this variable is evaluated, the value of the fill prefix, if any, is
returned.  If there is no fill prefix, this variable returns @code{nil}.

@item (not (equal fill-prefix "")
This expression checks whether an existing fill prefix is an empty string,
that is, a string with no characters in it.  An empty string is not a useful
fill prefix.

@item (not paragraph-ignore-fill-prefix)
This expression returns @code{nil} if the variable
@code{paragraph-ignore-fill-prefix} has been turned on by being set to a
true value such as @code{t}.

@item (regexp-quote fill-prefix)
This is the last argument to the @code{and} special form.  If all the
arguments to the @code{and} are true, the value resulting from evaluating
this expression will be returned by the @code{and} expression and bound to
the variable @code{fill-prefix-regexp},
@end table

@findex regexp-quote
@noindent
The result of evaluating this @code{and} expression successfully is that
@code{fill-prefix-regexp} will be bound to the value of @code{fill-prefix}
as modified by the @code{regexp-quote} function.  What @code{regexp-quote}
does is read a string and return a regular expression that will exactly
match the string and match nothing else.  This means that
@code{fill-prefix-regexp} will be set to a value that will exactly match the
fill prefix if the fill prefix exists.  Otherwise, the variable will be set
to @code{nil}.

The next two local variables in the @code{let*} expression are designed to
remove instances of @samp{^} from @code{parstart} and @code{parsep}, the
local variables which indicate the paragraph start and the paragraph
separator.  The next expression sets @code{parsep} again.  That is to handle
fill prefixes.

This is the setting that requires the definition call @code{let*} rather
than @code{let}.  The true-or-false-test for the @code{if} depends on
whether the variable @code{fill-prefix-regexp} evaluates to @code{nil} or
some other value.

If @code{fill-prefix-regexp} does not have a value, Emacs evaluates the
else-part of the @code{if} expression and binds @code{parsep} to its local
value.  (@code{parsep} is a regular expression that matches what separates
paragraphs.)

But if @code{fill-prefix-regexp} does have a value, Emacs evaluates the
then-part of the @code{if} expression and binds @code{parsep} to a regular
expression that includes the @code{fill-prefix-regexp} as part of the
pattern.

Specifically, @code{parsep} is set to the original value of the paragraph
separate regular expression concatenated with an alternative expression that
consists of the @code{fill-prefix-regexp} followed by optional whitespace to
the end of the line.  The whitespace is defined by @w{@code{"[ \t]*$"}}.)
The @samp{\\|} defines this portion of the regexp as an alternative to
@code{parsep}.

According to a comment in the code, the next local variable,
@code{sp-parstart}, is used for searching, and then the final two,
@code{start} and @code{found-start}, are set to @code{nil}.

Now we get into the body of the @code{let*}.  The first part of the body of
the @code{let*} deals with the case when the function is given a negative
argument and is therefore moving backwards.  We will skip this section.

@node fwd-para while
@unnumberedsubsec The forward motion @code{while} loop

The second part of the body of the @code{let*} deals with forward motion.
It is a @code{while} loop that repeats itself so long as the value of
@code{arg} is greater than zero.  In the most common use of the function,
the value of the argument is 1, so the body of the @code{while} loop is
evaluated exactly once, and the cursor moves forward one paragraph.

@ignore
(while (and (> arg 0) (not (eobp)))

  ;; Move forward over separator lines...
  (while (and (not (eobp))
              (progn (move-to-left-margin) (not (eobp)))
              (looking-at parsep))
    (forward-line 1))
  (unless (eobp) (setq arg (1- arg)))
  ;; ... and one more line.
  (forward-line 1)

  (if fill-prefix-regexp
      ;; There is a fill prefix; it overrides parstart.
      (while (and (not (eobp))
                  (progn (move-to-left-margin) (not (eobp)))
                  (not (looking-at parsep))
                  (looking-at fill-prefix-regexp))
        (forward-line 1))

    (while (and (re-search-forward sp-parstart nil 1)
                (progn (setq start (match-beginning 0))
                       (goto-char start)
                       (not (eobp)))
                (progn (move-to-left-margin)
                       (not (looking-at parsep)))
                (or (not (looking-at parstart))
                    (and use-hard-newlines
                         (not (get-text-property (1- start) 'hard)))))
      (forward-char 1))

    (if (< (point) (point-max))
        (goto-char start))))
@end ignore

This part handles three situations: when point is between paragraphs, when
there is a fill prefix and when there is no fill prefix.

@need 800
The @code{while} loop looks like this:

@smallexample
@group
;; @r{going forwards and not at the end of the buffer}
(while (and (> arg 0) (not (eobp)))

  ;; @r{between paragraphs}
  ;; Move forward over separator lines...
  (while (and (not (eobp))
              (progn (move-to-left-margin) (not (eobp)))
              (looking-at parsep))
    (forward-line 1))
  ;;  @r{This decrements the loop}
  (unless (eobp) (setq arg (1- arg)))
  ;; ... and one more line.
  (forward-line 1)
@end group

@group
  (if fill-prefix-regexp
      ;; There is a fill prefix; it overrides parstart;
      ;; we go forward line by line
      (while (and (not (eobp))
                  (progn (move-to-left-margin) (not (eobp)))
                  (not (looking-at parsep))
                  (looking-at fill-prefix-regexp))
        (forward-line 1))
@end group

@group
    ;; There is no fill prefix;
    ;; we go forward character by character
    (while (and (re-search-forward sp-parstart nil 1)
                (progn (setq start (match-beginning 0))
                       (goto-char start)
                       (not (eobp)))
                (progn (move-to-left-margin)
                       (not (looking-at parsep)))
                (or (not (looking-at parstart))
                    (and use-hard-newlines
                         (not (get-text-property (1- start) 'hard)))))
      (forward-char 1))
@end group

@group
    ;; and if there is no fill prefix and if we are not at the end,
    ;;     go to whatever was found in the regular expression search
    ;;     for sp-parstart
    (if (< (point) (point-max))
        (goto-char start))))
@end group
@end smallexample

@findex eobp
We can see that this is a decrementing counter @code{while} loop, using the
expression @code{(setq arg (1- arg))} as the decrementer.  That expression
is not far from the @code{while}, but is hidden in another Lisp macro, an
@code{unless} macro.  Unless we are at the end of the buffer---that is what
the @code{eobp} function determines; it is an abbreviation of @samp{End Of
Buffer P}---we decrease the value of @code{arg} by one.

(If we are at the end of the buffer, we cannot go forward any more and the
next loop of the @code{while} expression will test false since the test is
an @code{and} with @code{(not (eobp))}.  The @code{not} function means
exactly as you expect; it is another name for @code{null}, a function that
returns true when its argument is false.)

Interestingly, the loop count is not decremented until we leave the space
between paragraphs, unless we come to the end of buffer or stop seeing the
local value of the paragraph separator.

That second @code{while} also has a @code{(move-to-left-margin)}
expression.  The function is self-explanatory.  It is inside a @code{progn}
expression and not the last element of its body, so it is only invoked for
its side effect, which is to move point to the left margin of the current
line.

@findex looking-at
The @code{looking-at} function is also self-explanatory; it returns true if
the text after point matches the regular expression given as its argument.

The rest of the body of the loop looks difficult at first, but makes sense
as you come to understand it.

@need 800
First consider what happens if there is a fill prefix:

@smallexample
@group
  (if fill-prefix-regexp
      ;; There is a fill prefix; it overrides parstart;
      ;; we go forward line by line
      (while (and (not (eobp))
                  (progn (move-to-left-margin) (not (eobp)))
                  (not (looking-at parsep))
                  (looking-at fill-prefix-regexp))
        (forward-line 1))
@end group
@end smallexample

@noindent
This expression moves point forward line by line so long as four conditions
are true:

@enumerate
@item
Point is not at the end of the buffer.

@item
We can move to the left margin of the text and are not at the end of the
buffer.

@item
The text following point does not separate paragraphs.

@item
The pattern following point is the fill prefix regular expression.
@end enumerate

The last condition may be puzzling, until you remember that point was moved
to the beginning of the line early in the @code{forward-paragraph}
function.  This means that if the text has a fill prefix, the
@code{looking-at} function will see it.

@need 1250
Consider what happens when there is no fill prefix.

@smallexample
@group
    (while (and (re-search-forward sp-parstart nil 1)
                (progn (setq start (match-beginning 0))
                       (goto-char start)
                       (not (eobp)))
                (progn (move-to-left-margin)
                       (not (looking-at parsep)))
                (or (not (looking-at parstart))
                    (and use-hard-newlines
                         (not (get-text-property (1- start) 'hard)))))
      (forward-char 1))
@end group
@end smallexample

@noindent
This @code{while} loop has us searching forward for @code{sp-parstart},
which is the combination of possible whitespace with the local value of the
start of a paragraph or of a paragraph separator.  (The latter two are
within an expression starting @code{\(?:} so that they are not referenced by
the @code{match-beginning} function.)

@need 800
The two expressions,

@smallexample
@group
(setq start (match-beginning 0))
(goto-char start)
@end group
@end smallexample

@noindent
mean go to the start of the text matched by the regular expression search.

The @code{(match-beginning 0)} expression is new.  It returns a number
specifying the location of the start of the text that was matched by the
last search.

The @code{match-beginning} function is used here because of a characteristic
of a forward search: a successful forward search, regardless of whether it
is a plain search or a regular expression search, moves point to the end of
the text that is found.  In this case, a successful search moves point to
the end of the pattern for @code{sp-parstart}.

However, we want to put point at the end of the current paragraph, not
somewhere else.  Indeed, since the search possibly includes the paragraph
separator, point may end up at the beginning of the next one unless we use
an expression that includes @code{match-beginning}.

@findex match-beginning
When given an argument of 0, @code{match-beginning} returns the position
that is the start of the text matched by the most recent search.  In this
case, the most recent search looks for @code{sp-parstart}.  The
@code{(match-beginning 0)} expression returns the beginning position of that
pattern, rather than the end position of that pattern.

(Incidentally, when passed a positive number as an argument, the
@code{match-beginning} function returns the location of point at that
parenthesized expression in the last search unless that parenthesized
expression begins with @code{\(?:}.  I don't know why @code{\(?:} appears
here since the argument is 0.)

@need 1250
The last expression when there is no fill prefix is

@smallexample
@group
(if (< (point) (point-max))
    (goto-char start))))
@end group
@end smallexample

@noindent
(Note that this code snippet is copied verbatim from the original code, so
the two extra ending parentheses are matching the previous @code{if} and
@code{while}.)

This says that if there is no fill prefix and if we are not at the end,
point should move to the beginning of whatever was found by the regular
expression search for @code{sp-parstart}.

The full definition for the @code{forward-paragraph} function not only
includes code for going forwards, but also code for going backwards.

If you are reading this inside of GNU Emacs and you want to see the whole
function, you can type @kbd{C-h f} (@code{describe-function})  and the name
of the function.  This gives you the function documentation and the name of
the library containing the function's source.  Place point over the name of
the library and press the @key{RET} key; you will be taken directly to the
source.  (Be sure to install your sources! Without them, you are like a
person who tries to drive a car with his eyes shut!)

@node Regexp terugblik
@section Terugblik

Hier is een korte samenvatting van sommige recent geïntroduceerde functies.

@table @code
@item while
Repeatedly evaluate the body of the expression so long as the first element
of the body tests true.  Then return @code{nil}.  (The expression is
evaluated only for its side effects.)

@need 1250
Bijvoorbeeld:

@smallexample
@group
(let ((foo 2))
  (while (> foo 0)
    (insert (format "foo is %d.\n" foo))
    (setq foo (1- foo))))

     @result{}      foo is 2.
             foo is 1.
             nil
@end group
@end smallexample

@noindent
(The @code{insert} function inserts its arguments at point; the
@code{format} function returns a string formatted from its arguments the way
@code{message} formats its arguments; @code{\n} produces a new line.)

@item re-search-forward
Search for a pattern, and if the pattern is found, move point to rest just
after it.

@noindent
Takes four arguments, like @code{search-forward}:

@enumerate
@item
A regular expression that specifies the pattern to search for.  (Remember to
put quotation marks around this argument!)

@item
Optioneel, de limiet van de zoekopdracht.

@item
Optioneel, wat te doen als de zoekopdracht mislukt, geef @code{nil} terug of
een fout.

@item
Optioneel, hoeveel keer de zoekopdracht te herhalen. Wanneer negatief, zoek
achterwaarts.
@end enumerate

@item let*
Bind some variables locally to particular values, and then evaluate the
remaining arguments, returning the value of the last one.  While binding the
local variables, use the local values of variables bound earlier, if any.

@need 1250
Bijvoorbeeld:

@smallexample
@group
(let* ((foo 7)
       (bar (* 3 foo)))
  (message "`bar' is %d." bar))
     @result{} ‘bar’ is 21.
@end group
@end smallexample

@item match-beginning
Return the position of the start of the text found by the last regular
expression search.

@item looking-at
Return @code{t} for true if the text after point matches the argument, which
should be a regular expression.

@item eobp
Return @code{t} for true if point is at the end of the accessible part of a
buffer.  The end of the accessible part is the end of the buffer if the
buffer is not narrowed; it is the end of the narrowed part if the buffer is
narrowed.
@end table

@need 1500
@node re-search oefeningen
@section Exercises with @code{re-search-forward}

@itemize @bullet
@item
Write a function to search for a regular expression that matches two or more
blank lines in sequence.

@item
Write a function to search for duplicated words, such as ``the the''.
@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
Manual}, for information on how to write a regexp (a regular expression) to
match a string that is composed of two identical halves.  You can devise
several regexps; some are better than others.  The function I use is
described in an appendix, along with several regexps.  @xref{the-the, ,
@code{the-the} Duplicated Words Function}.
@end itemize

@node Woorden tellen
@chapter Counting via Repetition and Regexps
@cindex Repetition for word counting
@cindex Regular expressions for word counting

Repetition and regular expression searches are powerful tools that you often
use when you write code in Emacs Lisp.  This chapter illustrates the use of
regular expression searches through the construction of word count commands
using @code{while} loops and recursion.

@menu
* Waarom woorden tellen::    Waarom woorden tellen
* @value{COUNT-WORDS}::      Gebruik een regexp, maar vindt een probleem.
* recursive-count-words::    Start met het geval van geen woorden in de 
                               region.
* Tellen voorbeeld::         Tellen voorbeeld
@end menu

@ifnottex
@node Waarom woorden tellen
@unnumberedsec Counting words
@end ifnottex

The standard Emacs distribution contains functions for counting the number
of lines and words within a region.

Certain types of writing ask you to count words.  Thus, if you write an
essay, you may be limited to 800 words; if you write a novel, you may
discipline yourself to write 1000 words a day.  It seems odd, but for a long
time, Emacs lacked a word count command.  Perhaps people used Emacs mostly
for code or types of documentation that did not require word counts; or
perhaps they restricted themselves to the operating system word count
command, @code{wc}.  Alternatively, people may have followed the publishers'
convention and computed a word count by dividing the number of characters in
a document by five.

There are many ways to implement a command to count words.  Here are some
examples, which you may wish to compare with the standard Emacs command,
@code{count-words-region}.

@node @value{COUNT-WORDS}
@section De @code{@value{COUNT-WORDS}} functie
@findex @value{COUNT-WORDS}

A word count command could count words in a line, paragraph, region, or
buffer.  What should the command cover? You could design the command to
count the number of words in a complete buffer.  However, the Emacs
tradition encourages flexibility---you may want to count words in just a
section, rather than all of a buffer.  So it makes more sense to design the
command to count the number of words in a region.  Once you have a command
to count words in a region, you can, if you wish, count words in a whole
buffer by marking it with @w{@kbd{C-x h}} (@code{mark-whole-buffer}).

Clearly, counting words is a repetitive act: starting from the beginning of
the region, you count the first word, then the second word, then the third
word, and so on, until you reach the end of the region.  This means that
word counting is ideally suited to recursion or to a @code{while} loop.

@menu
* Ontwerp @value{COUNT-WORDS}::  De definitie met @code{while} loop.
* Wiite ruimte bug::         De witte ruimte bug in 
                               @code{@value{COUNT-WORDS}}
@end menu

@ifnottex
@node Ontwerp @value{COUNT-WORDS}
@unnumberedsubsec Designing @code{@value{COUNT-WORDS}}
@end ifnottex

First, we will implement the word count command with a @code{while} loop,
then with recursion.  The command will, of course, be interactive.

@need 800
The template for an interactive function definition is, as always:

@smallexample
@group
(defun @var{naam-van-de-functie} (@var{argument-list})
  "@var{documentatie}@dots{}"
  (@var{interactive-expression}@dots{})
  @var{body}@dots{})
@end group
@end smallexample

What we need to do is fill in the slots.

The name of the function should be self-explanatory and easy to remember.
@code{count-words-region} is the obvious choice.  Since that name is used
for the standard Emacs command to count words, we will name our
implementation @code{@value{COUNT-WORDS}}.

The function counts words within a region.  This means that the argument
list must contain symbols that are bound to the two positions, the beginning
and end of the region.  These two positions can be called @samp{beginning}
and @samp{end} respectively.  The first line of the documentation should be
a single sentence, since that is all that is printed as documentation by a
command such as @code{apropos}.  The interactive expression will be of the
form @samp{(interactive "r")}, since that will cause Emacs to pass the
beginning and end of the region to the function's argument list.  All this
is routine.

The body of the function needs to be written to do three tasks: first, to
set up conditions under which the @code{while} loop can count words, second,
to run the @code{while} loop, and third, to send a message to the user.

When a user calls @code{@value{COUNT-WORDS}}, point may be at the beginning
or the end of the region.  However, the counting process must start at the
beginning of the region.  This means we will want to put point there if it
is not already there.  Executing @code{(goto-char beginning)} ensures this.
Of course, we will want to return point to its expected position when the
function finishes its work.  For this reason, the body must be enclosed in a
@code{save-excursion} expression.

The central part of the body of the function consists of a @code{while} loop
in which one expression jumps point forward word by word, and another
expression counts those jumps.  The true-or-false-test of the @code{while}
loop should test true so long as point should jump forward, and false when
point is at the end of the region.

We could use @code{(forward-word 1)} as the expression for moving point
forward word by word, but it is easier to see what Emacs identifies as a
``word'' if we use a regular expression search.

A regular expression search that finds the pattern for which it is searching
leaves point after the last character matched.  This means that a succession
of successful word searches will move point forward word by word.

As a practical matter, we want the regular expression search to jump over
whitespace and punctuation between words as well as over the words
themselves.  A regexp that refuses to jump over interword whitespace would
never jump more than one word! This means that the regexp should include the
whitespace and punctuation that follows a word, if any, as well as the word
itself.  (A word may end a buffer and not have any following whitespace or
punctuation, so that part of the regexp must be optional.)

Thus, what we want for the regexp is a pattern defining one or more word
constituent characters followed, optionally, by one or more characters that
are not word constituents.  The regular expression for this is:

@smallexample
\w+\W*
@end smallexample

@noindent
The buffer's syntax table determines which characters are and are not word
constituents.  For more information about syntax, @pxref{Syntax Tables, ,
Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.

@need 800
The search expression looks like this:

@smallexample
(re-search-forward "\\w+\\W*")
@end smallexample

@noindent
(Note that paired backslashes precede the @samp{w} and @samp{W}.  A single
backslash has special meaning to the Emacs Lisp interpreter.  It indicates
that the following character is interpreted differently than usual.  For
example, the two characters, @samp{\n}, stand for @samp{newline}, rather
than for a backslash followed by @samp{n}.  Two backslashes in a row stand
for an ordinary, unspecial backslash, so Emacs Lisp interpreter ends of
seeing a single backslash followed by a letter.  So it discovers the letter
is special.)

We need a counter to count how many words there are; this variable must
first be set to 0 and then incremented each time Emacs goes around the
@code{while} loop.  The incrementing expression is simply:

@smallexample
(setq count (1+ count))
@end smallexample

Finally, we want to tell the user how many words there are in the region.
The @code{message} function is intended for presenting this kind of
information to the user.  The message has to be phrased so that it reads
properly regardless of how many words there are in the region: we don't want
to say that ``there are 1 words in the region''.  The conflict between
singular and plural is ungrammatical.  We can solve this problem by using a
conditional expression that evaluates different messages depending on the
number of words in the region.  There are three possibilities: no words in
the region, one word in the region, and more than one word.  This means that
the @code{cond} special form is appropriate.

@need 1500
All this leads to the following function definition:

@smallexample
@group
;;; @r{First version; has bugs!}
(defun @value{COUNT-WORDS} (beginning end)
  "Print number of words in the region.
Words are defined as at least one word-constituent
character followed by at least one character that
is not a word-constituent.  The buffer's syntax
table determines which characters these are."
  (interactive "r")
  (message "Counting words in region ... ")
@end group

@group
;;; @r{1. Set up appropriate conditions.}
  (save-excursion
    (goto-char beginning)
    (let ((count 0))
@end group

@group
;;; @r{2. Run the} while @r{loop.}
      (while (< (point) end)
        (re-search-forward "\\w+\\W*")
        (setq count (1+ count)))
@end group

@group
;;; @r{3. Send a message to the user.}
      (cond ((zerop count)
             (message
              "The region does NOT have any words."))
            ((= 1 count)
             (message
              "The region has 1 word."))
            (t
             (message
              "The region has %d words." count))))))
@end group
@end smallexample

@noindent
As written, the function works, but not in all circumstances.

@node Wiite ruimte bug
@subsection The Whitespace Bug in @code{@value{COUNT-WORDS}}

The @code{@value{COUNT-WORDS}} command described in the preceding section
has two bugs, or rather, one bug with two manifestations.  First, if you
mark a region containing only whitespace in the middle of some text, the
@code{@value{COUNT-WORDS}} command tells you that the region contains one
word! Second, if you mark a region containing only whitespace at the end of
the buffer or the accessible portion of a narrowed buffer, the command
displays an error message that looks like this:

@smallexample
Search failed: "\\w+\\W*"
@end smallexample

If you are reading this in Info in GNU Emacs, you can test for these bugs
yourself.

First, evaluate the function in the usual manner to install it.
@ifinfo
Here is a copy of the definition.  Place your cursor after the closing
parenthesis and type @kbd{C-x C-e} to install it.

@smallexample
@group
;; @r{First version; has bugs!}
(defun @value{COUNT-WORDS} (beginning end)
  "Print number of words in the region.
Words are defined as at least one word-constituent character followed
by at least one character that is not a word-constituent.  The buffer's
syntax table determines which characters these are."
@end group
@group
  (interactive "r")
  (message "Counting words in region ... ")
@end group

@group
;;; @r{1. Set up appropriate conditions.}
  (save-excursion
    (goto-char beginning)
    (let ((count 0))
@end group

@group
;;; @r{2. Run the} while @r{loop.}
      (while (< (point) end)
        (re-search-forward "\\w+\\W*")
        (setq count (1+ count)))
@end group

@group
;;; @r{3. Send a message to the user.}
      (cond ((zerop count)
             (message "The region does NOT have any words."))
            ((= 1 count) (message "The region has 1 word."))
            (t (message "The region has %d words." count))))))
@end group
@end smallexample
@end ifinfo

@need 1000
If you wish, you can also install this key binding by evaluating it:

@smallexample
(keymap-global-set "C-c =" '@value{COUNT-WORDS})
@end smallexample

To conduct the first test, set mark and point to the beginning and end of
the following line and then type @kbd{C-c =} (or @kbd{M-x
@value{COUNT-WORDS}} if you have not bound @kbd{C-c =}):

@smallexample
    one   two  three
@end smallexample

@noindent
Emacs will tell you, correctly, that the region has three words.

Repeat the test, but place mark at the beginning of the line and place point
just @emph{before} the word @samp{one}.  Again type the command @kbd{C-c =}
(or @kbd{M-x @value{COUNT-WORDS}}).  Emacs should tell you that the region
has no words, since it is composed only of the whitespace at the beginning
of the line.  But instead Emacs tells you that the region has one word!

For the third test, copy the sample line to the end of the @file{*scratch*}
buffer and then type several spaces at the end of the line.  Place mark
right after the word @samp{three} and point at the end of line.  (The end of
the line will be the end of the buffer.)  Type @kbd{C-c =} (or @kbd{M-x
@value{COUNT-WORDS}}) as you did before.  Again, Emacs should tell you that
the region has no words, since it is composed only of the whitespace at the
end of the line.  Instead, Emacs displays an error message saying
@samp{Search failed}.

The two bugs stem from the same problem.

Consider the first manifestation of the bug, in which the command tells you
that the whitespace at the beginning of the line contains one word.  What
happens is this: The @code{M-x @value{COUNT-WORDS}} command moves point to
the beginning of the region.  The @code{while} tests whether the value of
point is smaller than the value of @code{end}, which it is.  Consequently,
the regular expression search looks for and finds the first word.  It leaves
point after the word.  @code{count} is set to one.  The @code{while} loop
repeats; but this time the value of point is larger than the value of
@code{end}, the loop is exited; and the function displays a message saying
the number of words in the region is one.  In brief, the regular expression
search looks for and finds the word even though it is outside the marked
region.

In the second manifestation of the bug, the region is whitespace at the end
of the buffer.  Emacs says @samp{Search failed}.  What happens is that the
true-or-false-test in the @code{while} loop tests true, so the search
expression is executed.  But since there are no more words in the buffer,
the search fails.

In both manifestations of the bug, the search extends or attempts to extend
outside of the region.

The solution is to limit the search to the region---this is a fairly simple
action, but as you may have come to expect, it is not quite as simple as you
might think.

As we have seen, the @code{re-search-forward} function takes a search
pattern as its first argument.  But in addition to this first, mandatory
argument, it accepts three optional arguments.  The optional second argument
bounds the search.  The optional third argument, if @code{t}, causes the
function to return @code{nil} rather than signal an error if the search
fails.  The optional fourth argument is a repeat count.  (In Emacs, you can
see a function's documentation by typing @kbd{C-h f}, the name of the
function, and then @key{RET}.)

In the @code{@value{COUNT-WORDS}} definition, the value of the end of the
region is held by the variable @code{end} which is passed as an argument to
the function.  Thus, we can add @code{end} as an argument to the regular
expression search expression:

@smallexample
(re-search-forward "\\w+\\W*" end)
@end smallexample

However, if you make only this change to the @code{@value{COUNT-WORDS}}
definition and then test the new version of the definition on a stretch of
whitespace, you will receive an error message saying @samp{Search failed}.

What happens is this: the search is limited to the region, and fails as you
expect because there are no word-constituent characters in the region.
Since it fails, we receive an error message.  But we do not want to receive
an error message in this case; we want to receive the message ``The region
does NOT have any words.''

The solution to this problem is to provide @code{re-search-forward} with a
third argument of @code{t}, which causes the function to return @code{nil}
rather than signal an error if the search fails.

However, if you make this change and try it, you will see the message
``Counting words in region ... '' and @dots{} you will keep on seeing that
message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}).

Here is what happens: the search is limited to the region, as before, and it
fails because there are no word-constituent characters in the region, as
expected.  Consequently, the @code{re-search-forward} expression returns
@code{nil}.  It does nothing else.  In particular, it does not move point,
which it does as a side effect if it finds the search target.  After the
@code{re-search-forward} expression returns @code{nil}, the next expression
in the @code{while} loop is evaluated.  This expression increments the
count.  Then the loop repeats.  The true-or-false-test tests true because
the value of point is still less than the value of end, since the
@code{re-search-forward} expression did not move point. @dots{} and the
cycle repeats @dots{}

The @code{@value{COUNT-WORDS}} definition requires yet another modification,
to cause the true-or-false-test of the @code{while} loop to test false if
the search fails.  Put another way, there are two conditions that must be
satisfied in the true-or-false-test before the word count variable is
incremented: point must still be within the region and the search expression
must have found a word to count.

Since both the first condition and the second condition must be true
together, the two expressions, the region test and the search expression,
can be joined with an @code{and} special form and embedded in the
@code{while} loop as the true-or-false-test, like this:

@smallexample
(and (< (point) end) (re-search-forward "\\w+\\W*" end t))
@end smallexample

@c colon in printed section title causes problem in Info cross reference
@c also trouble with an overfull hbox
@iftex
@noindent
(For information about @code{and}, see @ref{kill-new function, , The
@code{kill-new} function}.)
@end iftex
@ifinfo
@noindent
(@xref{kill-new function, , The @code{kill-new} function}, for information
about @code{and}.)
@end ifinfo

The @code{re-search-forward} expression returns @code{t} if the search
succeeds and as a side effect moves point.  Consequently, as words are
found, point is moved through the region.  When the search expression fails
to find another word, or when point reaches the end of the region, the
true-or-false-test tests false, the @code{while} loop exits, and the
@code{@value{COUNT-WORDS}} function displays one or other of its messages.

After incorporating these final changes, the @code{@value{COUNT-WORDS}}
works without bugs (or at least, without bugs that I have found!).  Here is
what it looks like:

@smallexample
@group
;;; @r{Final version:} @code{while}
(defun @value{COUNT-WORDS} (beginning end)
  "Print number of words in the region."
  (interactive "r")
  (message "Counting words in region ... ")
@end group

@group
;;; @r{1. Set up appropriate conditions.}
  (save-excursion
    (let ((count 0))
      (goto-char beginning)
@end group

@group
;;; @r{2. Run the} while @r{loop.}
      (while (and (< (point) end)
                  (re-search-forward "\\w+\\W*" end t))
        (setq count (1+ count)))
@end group

@group
;;; @r{3. Send a message to the user.}
      (cond ((zerop count)
             (message
              "The region does NOT have any words."))
            ((= 1 count)
             (message
              "The region has 1 word."))
            (t
             (message
              "The region has %d words." count))))))
@end group
@end smallexample

@node recursive-count-words
@section Count Words Recursively
@cindex Count words recursively
@cindex Recursively counting words
@cindex Words, counted recursively

You can write the function for counting words recursively as well as with a
@code{while} loop.  Let's see how this is done.

First, we need to recognize that the @code{@value{COUNT-WORDS}} function has
three jobs: it sets up the appropriate conditions for counting to occur; it
counts the words in the region; and it sends a message to the user telling
how many words there are.

If we write a single recursive function to do everything, we will receive a
message for every recursive call.  If the region contains 13 words, we will
receive thirteen messages, one right after the other.  We don't want this!
Instead, we must write two functions to do the job, one of which (the
recursive function) will be used inside of the other.  One function will set
up the conditions and display the message; the other will return the word
count.

Let us start with the function that causes the message to be displayed.  We
can continue to call this @code{@value{COUNT-WORDS}}.

This is the function that the user will call.  It will be interactive.
Indeed, it will be similar to our previous versions of this function, except
that it will call @code{recursive-count-words} to determine how many words
are in the region.

@need 1250
We can readily construct a template for this function, based on our previous
versions:

@smallexample
@group
;; @r{Recursive version; uses regular expression search}
(defun @value{COUNT-WORDS} (beginning end)
  "@var{documentation}@dots{}"
  (@var{interactive-expression}@dots{})
@end group
@group

;;; @r{1. Set up appropriate conditions.}
  (@var{explanatory message})
  (@var{set-up functions}@dots{}
@end group
@group

;;; @r{2. Count the words.}
    @var{recursive call}
@end group
@group

;;; @r{3. Send a message to the user.}
    @var{message providing word count}))
@end group
@end smallexample

The definition looks straightforward, except that somehow the count returned
by the recursive call must be passed to the message displaying the word
count.  A little thought suggests that this can be done by making use of a
@code{let} expression: we can bind a variable in the varlist of a @code{let}
expression to the number of words in the region, as returned by the
recursive call; and then the @code{cond} expression, using binding, can
display the value to the user.

Often, one thinks of the binding within a @code{let} expression as somehow
secondary to the primary work of a function.  But in this case, what you
might consider the primary job of the function, counting words, is done
within the @code{let} expression.

@need 1250
Using @code{let}, the function definition looks like this:

@smallexample
@group
(defun @value{COUNT-WORDS} (beginning end)
  "Print number of words in the region."
  (interactive "r")
@end group

@group
;;; @r{1. Set up appropriate conditions.}
  (message "Counting words in region ... ")
  (save-excursion
    (goto-char beginning)
@end group

@group
;;; @r{2. Count the words.}
    (let ((count (recursive-count-words end)))
@end group

@group
;;; @r{3. Send a message to the user.}
      (cond ((zerop count)
             (message
              "The region does NOT have any words."))
            ((= 1 count)
             (message
              "The region has 1 word."))
            (t
             (message
              "The region has %d words." count))))))
@end group
@end smallexample

Next, we need to write the recursive counting function.

A recursive function has at least three parts: the do-again-test, the
next-step-expression, and the recursive call.

The do-again-test determines whether the function will or will not be called
again.  Since we are counting words in a region and can use a function that
moves point forward for every word, the do-again-test can check whether
point is still within the region.  The do-again-test should find the value
of point and determine whether point is before, at, or after the value of
the end of the region.  We can use the @code{point} function to locate
point.  Clearly, we must pass the value of the end of the region to the
recursive counting function as an argument.

In addition, the do-again-test should also test whether the search finds a
word.  If it does not, the function should not call itself again.

The next-step-expression changes a value so that when the recursive function
is supposed to stop calling itself, it stops.  More precisely, the
next-step-expression changes a value so that at the right time, the
do-again-test stops the recursive function from calling itself again.  In
this case, the next-step-expression can be the expression that moves point
forward, word by word.

The third part of a recursive function is the recursive call.

Somewhere, we also need a part that does the work of the function, a part
that does the counting.  A vital part!

@need 1250
But already, we have an outline of the recursive counting function:

@smallexample
@group
(defun recursive-count-words (region-end)
  "@var{documentation}@dots{}"
   @var{do-again-test}
   @var{next-step-expression}
   @var{recursive call})
@end group
@end smallexample

Now we need to fill in the slots.  Let's start with the simplest cases
first: if point is at or beyond the end of the region, there cannot be any
words in the region, so the function should return zero.  Likewise, if the
search fails, there are no words to count, so the function should return
zero.

On the other hand, if point is within the region and the search succeeds,
the function should call itself again.

@need 800
Thus, the do-again-test should look like this:

@smallexample
@group
(and (< (point) region-end)
     (re-search-forward "\\w+\\W*" region-end t))
@end group
@end smallexample

Note that the search expression is part of the do-again-test---the function
returns @code{t} if its search succeeds and @code{nil} if it fails.
(@xref{Whitespace Bug, , The Whitespace Bug in @code{@value{COUNT-WORDS}}},
for an explanation of how @code{re-search-forward} works.)

The do-again-test is the true-or-false test of an @code{if} clause.
Clearly, if the do-again-test succeeds, the then-part of the @code{if}
clause should call the function again; but if it fails, the else-part should
return zero since either point is outside the region or the search failed
because there were no words to find.

But before considering the recursive call, we need to consider the
next-step-expression.  What is it? Interestingly, it is the search part of
the do-again-test.

In addition to returning @code{t} or @code{nil} for the do-again-test,
@code{re-search-forward} moves point forward as a side effect of a
successful search.  This is the action that changes the value of point so
that the recursive function stops calling itself when point completes its
movement through the region.  Consequently, the @code{re-search-forward}
expression is the next-step-expression.

@need 1200
In outline, then, the body of the @code{recursive-count-words} function
looks like this:

@smallexample
@group
(if @var{do-again-test-and-next-step-combined}
    ;; @r{then}
    @var{recursive-call-returning-count}
  ;; @r{else}
  @var{return-zero})
@end group
@end smallexample

How to incorporate the mechanism that counts?

If you are not used to writing recursive functions, a question like this can
be troublesome.  But it can and should be approached systematically.

We know that the counting mechanism should be associated in some way with
the recursive call.  Indeed, since the next-step-expression moves point
forward by one word, and since a recursive call is made for each word, the
counting mechanism must be an expression that adds one to the value returned
by a call to @code{recursive-count-words}.

@need 800
Consider several cases:

@itemize @bullet
@item
If there are two words in the region, the function should return a value
resulting from adding one to the value returned when it counts the first
word, plus the number returned when it counts the remaining words in the
region, which in this case is one.

@item
If there is one word in the region, the function should return a value
resulting from adding one to the value returned when it counts that word,
plus the number returned when it counts the remaining words in the region,
which in this case is zero.

@item
If there are no words in the region, the function should return zero.
@end itemize

From the sketch we can see that the else-part of the @code{if} returns zero
for the case of no words.  This means that the then-part of the @code{if}
must return a value resulting from adding one to the value returned from a
count of the remaining words.

@need 1200
The expression will look like this, where @code{1+} is a function that adds
one to its argument.

@smallexample
(1+ (recursive-count-words region-end))
@end smallexample

@need 1200
The whole @code{recursive-count-words} function will then look like this:

@smallexample
@group
(defun recursive-count-words (region-end)
  "@var{documentation}@dots{}"

;;; @r{1. do-again-test}
  (if (and (< (point) region-end)
           (re-search-forward "\\w+\\W*" region-end t))
@end group

@group
;;; @r{2. then-part: the recursive call}
      (1+ (recursive-count-words region-end))

;;; @r{3. else-part}
    0))
@end group
@end smallexample

@need 1250
Let's examine how this works:

If there are no words in the region, the else part of the @code{if}
expression is evaluated and consequently the function returns zero.

If there is one word in the region, the value of point is less than the
value of @code{region-end} and the search succeeds.  In this case, the
true-or-false-test of the @code{if} expression tests true, and the then-part
of the @code{if} expression is evaluated.  The counting expression is
evaluated.  This expression returns a value (which will be the value
returned by the whole function) that is the sum of one added to the value
returned by a recursive call.

Meanwhile, the next-step-expression has caused point to jump over the first
(and in this case only) word in the region.  This means that when
@code{(recursive-count-words region-end)} is evaluated a second time, as a
result of the recursive call, the value of point will be equal to or greater
than the value of region end.  So this time, @code{recursive-count-words}
will return zero.  The zero will be added to one, and the original
evaluation of @code{recursive-count-words} will return one plus zero, which
is one, which is the correct amount.

Clearly, if there are two words in the region, the first call to
@code{recursive-count-words} returns one added to the value returned by
calling @code{recursive-count-words} on a region containing the remaining
word---that is, it adds one to one, producing two, which is the correct
amount.

Similarly, if there are three words in the region, the first call to
@code{recursive-count-words} returns one added to the value returned by
calling @code{recursive-count-words} on a region containing the remaining
two words---and so on and so on.

@need 1250
@noindent
With full documentation the two functions look like this:

@need 1250
@noindent
The recursive function:

@findex recursive-count-words
@smallexample
@group
(defun recursive-count-words (region-end)
  "Number of words between point and REGION-END."
@end group

@group
;;; @r{1. do-again-test}
  (if (and (< (point) region-end)
           (re-search-forward "\\w+\\W*" region-end t))
@end group

@group
;;; @r{2. then-part: the recursive call}
      (1+ (recursive-count-words region-end))

;;; @r{3. else-part}
    0))
@end group
@end smallexample

@need 800
@noindent
The wrapper:

@smallexample
@group
;;; @r{Recursive version}
(defun @value{COUNT-WORDS} (beginning end)
  "Print number of words in the region.
@end group

@group
Words are defined as at least one word-constituent
character followed by at least one character that is
not a word-constituent.  The buffer's syntax table
determines which characters these are."
@end group
@group
  (interactive "r")
  (message "Counting words in region ... ")
  (save-excursion
    (goto-char beginning)
    (let ((count (recursive-count-words end)))
@end group
@group
      (cond ((zerop count)
             (message
              "The region does NOT have any words."))
@end group
@group
            ((= 1 count)
             (message "The region has 1 word."))
            (t
             (message
              "The region has %d words." count))))))
@end group
@end smallexample

@node Tellen voorbeeld
@section Exercise: Counting Punctuation

Using a @code{while} loop, write a function to count the number of
punctuation marks in a region---period, comma, semicolon, colon, exclamation
mark, and question mark.  Do the same using recursion.

@node Woorden in een defun
@chapter Woorden tellen in een @code{defun}
@cindex Counting words in a @code{defun}
@cindex Word counting in a @code{defun}

Our next project is to count the number of words in a function definition.
Clearly, this can be done using some variant of @code{@value{COUNT-WORDS}}.
@xref{Counting Words, , Counting via Repetition and Regexps}.  If we are
just going to count the words in one definition, it is easy enough to mark
the definition with the @kbd{C-M-h} (@code{mark-defun}) command, and then
call @code{@value{COUNT-WORDS}}.

However, I am more ambitious: I want to count the words and symbols in every
definition in the Emacs sources and then print a graph that shows how many
functions there are of each length: how many contain 40 to 49 words or
symbols, how many contain 50 to 59 words or symbols, and so on.  I have
often been curious how long a typical function is, and this will tell.

@menu
* Verdeel en heers::         Verdeel en heers
* Woorden en symbolen::      Wat te tellen?
* Syntax::                   Wat vormt een woord of een symbool?
* count-words-in-defun::     Erg vergelijkbaar met 
                               @code{@value{COUNT-WORDS}}
* Enkele defuns::            Enkele defuns in een bestand tellen.
* Een bestand vinden::       Wil je naar een bestand kijken?
* lengths-list-file::        Een lijst met de lengtes van veel definities.
* Enkele bestanden::         Tellen in definities in verschillende 
                               bestanden.
* Enkele bestanden recursief::  Recursief tellen in verschillende bestanden.
* De data voorbereiden::     De data voorbereiden om in een grafiek te 
                               tonen.
@end menu

@ifnottex
@node Verdeel en heers
@unnumberedsec Verdeel en heers
@end ifnottex

Described in one phrase, the histogram project is daunting; but divided into
numerous small steps, each of which we can take one at a time, the project
becomes less fearsome.  Let us consider what the steps must be:

@itemize @bullet
@item
First, write a function to count the words in one definition.  This includes
the problem of handling symbols as well as words.

@item
Second, write a function to list the number of words in each function in a
file.  This function can use the @code{count-words-in-defun} function.

@item
Third, write a function to list the number of words in each function in each
of several files.  This entails automatically finding the various files,
switching to them, and counting the words in the definitions within them.

@item
Fourth, write a function to convert the list of numbers that we created in
step three to a form that will be suitable for printing as a graph.

@item
Fifth, write a function to print the results as a graph.
@end itemize

This is quite a project! But if we take each step slowly, it will not be
difficult.

@node Woorden en symbolen
@section What to Count?
@cindex Words and symbols in defun

When we first start thinking about how to count the words in a function
definition, the first question is (or ought to be) what are we going to
count? When we speak of ``words'' with respect to a Lisp function
definition, we are actually speaking, in large part, of symbols.  For
example, the following @code{multiply-by-seven} function contains the five
symbols @code{defun}, @code{multiply-by-seven}, @code{number}, @code{*}, and
@code{7}.  In addition, in the documentation string, it contains the four
words @samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}.  The
symbol @samp{number} is repeated, so the definition contains a total of ten
words and symbols.

@smallexample
@group
(defun vermenigvuldig-met-zeven (getal)
  "Vermenigvuldig GETAL met zeven."
  (* 7 getal))
@end group
@end smallexample

@noindent
However, if we mark the @code{multiply-by-seven} definition with @kbd{C-M-h}
(@code{mark-defun}), and then call @code{@value{COUNT-WORDS}} on it, we will
find that @code{@value{COUNT-WORDS}} claims the definition has eleven words,
not ten! Something is wrong!

The problem is twofold: @code{@value{COUNT-WORDS}} does not count the
@samp{*} as a word, and it counts the single symbol,
@code{multiply-by-seven}, as containing three words.  The hyphens are
treated as if they were interword spaces rather than intraword connectors:
@samp{multiply-by-seven} is counted as if it were written @samp{multiply by
seven}.

The cause of this confusion is the regular expression search within the
@code{@value{COUNT-WORDS}} definition that moves point forward word by
word.  In the canonical version of @code{@value{COUNT-WORDS}}, the regexp
is:

@smallexample
"\\w+\\W*"
@end smallexample

@noindent
This regular expression is a pattern defining one or more word constituent
characters possibly followed by one or more characters that are not word
constituents.  What is meant by ``word constituent characters'' brings us to
the issue of syntax, which is worth a section of its own.

@node Syntax
@section What Constitutes a Word or Symbol?
@cindex Syntax categories and tables

Emacs treats different characters as belonging to different @dfn{syntax
categories}.  For example, the regular expression, @samp{\\w+}, is a pattern
specifying one or more @emph{word constituent} characters.  Word constituent
characters are members of one syntax category.  Other syntax categories
include the class of punctuation characters, such as the period and the
comma, and the class of whitespace characters, such as the blank space and
the tab character.  (For more information, @pxref{Syntax Tables, , Syntax
Tables, elisp, The GNU Emacs Lisp Reference Manual}.)

Syntax tables specify which characters belong to which categories.  Usually,
a hyphen is not specified as a word constituent character.  Instead, it is
specified as being in the class of characters that are part of symbol names
but not words.  This means that the @code{@value{COUNT-WORDS}} function
treats it in the same way it treats an interword white space, which is why
@code{@value{COUNT-WORDS}} counts @samp{multiply-by-seven} as three words.

There are two ways to cause Emacs to count @samp{multiply-by-seven} as one
symbol: modify the syntax table or modify the regular expression.

We could redefine a hyphen as a word constituent character by modifying the
syntax table that Emacs keeps for each mode.  This action would serve our
purpose, except that a hyphen is merely the most common character within
symbols that is not typically a word constituent character; there are
others, too.

Alternatively, we can redefine the regexp used in the
@code{@value{COUNT-WORDS}} definition so as to include symbols.  This
procedure has the merit of clarity, but the task is a little tricky.

@need 1200
The first part is simple enough: the pattern must match at least one
character that is a word or symbol constituent.  Thus:

@smallexample
"\\(\\w\\|\\s_\\)+"
@end smallexample

@noindent
The @samp{\\(} is the first part of the grouping construct that includes the
@samp{\\w} and the @samp{\\s_} as alternatives, separated by the
@samp{\\|}.  The @samp{\\w} matches any word-constituent character and the
@samp{\\s_} matches any character that is part of a symbol name but not a
word-constituent character.  The @samp{+} following the group indicates that
the word or symbol constituent characters must be matched at least once.

However, the second part of the regexp is more difficult to design.  What we
want is to follow the first part with optionally one or more characters that
are not constituents of a word or symbol.  At first, I thought I could
define this with the following:

@smallexample
"\\(\\W\\|\\S_\\)*"
@end smallexample

@noindent
The upper case @samp{W} and @samp{S} match characters that are @emph{not}
word or symbol constituents.  Unfortunately, this expression matches any
character that is either not a word constituent or not a symbol
constituent.  This matches any character!

I then noticed that every word or symbol in my test region was followed by
white space (blank space, tab, or newline).  So I tried placing a pattern to
match one or more blank spaces after the pattern for one or more word or
symbol constituents.  This failed, too.  Words and symbols are often
separated by whitespace, but in actual code parentheses may follow symbols
and punctuation may follow words.  So finally, I designed a pattern in which
the word or symbol constituents are followed optionally by characters that
are not white space and then followed optionally by white space.

@need 800
Here is the full regular expression:

@smallexample
"\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
@end smallexample

@node count-words-in-defun
@section The @code{count-words-in-defun} Function
@cindex Counting words in a @code{defun}

We have seen that there are several ways to write a
@code{count-words-region} function.  To write a @code{count-words-in-defun},
we need merely adapt one of these versions.

The version that uses a @code{while} loop is easy to understand, so I am
going to adapt that.  Because @code{count-words-in-defun} will be part of a
more complex program, it need not be interactive and it need not display a
message but just return the count.  These considerations simplify the
definition a little.

On the other hand, @code{count-words-in-defun} will be used within a buffer
that contains function definitions.  Consequently, it is reasonable to ask
that the function determine whether it is called when point is within a
function definition, and if it is, to return the count for that definition.
This adds complexity to the definition, but saves us from needing to pass
arguments to the function.

@need 1250
These considerations lead us to prepare the following template:

@smallexample
@group
(defun count-words-in-defun ()
  "@var{documentation}@dots{}"
  (@var{set up}@dots{}
     (@var{while loop}@dots{})
   @var{return count})
@end group
@end smallexample

@noindent
As usual, our job is to fill in the slots.

First, the set up.

We are presuming that this function will be called within a buffer
containing function definitions.  Point will either be within a function
definition or not.  For @code{count-words-in-defun} to work, point must move
to the beginning of the definition, a counter must start at zero, and the
counting loop must stop when point reaches the end of the definition.

The @code{beginning-of-defun} function searches backwards for an opening
delimiter such as a @samp{(} at the beginning of a line, and moves point to
that position, or else to the limit of the search.  In practice, this means
that @code{beginning-of-defun} moves point to the beginning of an enclosing
or preceding function definition, or else to the beginning of the buffer.
We can use @code{beginning-of-defun} to place point where we wish to start.

The @code{while} loop requires a counter to keep track of the words or
symbols being counted.  A @code{let} expression can be used to create a
local variable for this purpose, and bind it to an initial value of zero.

The @code{end-of-defun} function works like @code{beginning-of-defun} except
that it moves point to the end of the definition.  @code{end-of-defun} can
be used as part of an expression that determines the position of the end of
the definition.

The set up for @code{count-words-in-defun} takes shape rapidly: first we
move point to the beginning of the definition, then we create a local
variable to hold the count, and finally, we record the position of the end
of the definition so the @code{while} loop will know when to stop looping.

@need 1250
De code ziet er zo uit:

@smallexample
@group
(beginning-of-defun)
(let ((count 0)
      (end (save-excursion (end-of-defun) (point))))
@end group
@end smallexample

@noindent
The code is simple.  The only slight complication is likely to concern
@code{end}: it is bound to the position of the end of the definition by a
@code{save-excursion} expression that returns the value of point after
@code{end-of-defun} temporarily moves it to the end of the definition.

The second part of the @code{count-words-in-defun}, after the set up, is the
@code{while} loop.

The loop must contain an expression that jumps point forward word by word
and symbol by symbol, and another expression that counts the jumps.  The
true-or-false-test for the @code{while} loop should test true so long as
point should jump forward, and false when point is at the end of the
definition.  We have already redefined the regular expression for this, so
the loop is straightforward:

@smallexample
@group
(while (and (< (point) end)
            (re-search-forward
             "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t))
  (setq count (1+ count)))
@end group
@end smallexample

The third part of the function definition returns the count of words and
symbols.  This part is the last expression within the body of the @code{let}
expression, and can be, very simply, the local variable @code{count}, which
when evaluated returns the count.

@need 1250
Put together, the @code{count-words-in-defun} definition looks like this:

@findex count-words-in-defun
@smallexample
@group
(defun count-words-in-defun ()
  "Return the number of words and symbols in a defun."
  (beginning-of-defun)
  (let ((count 0)
        (end (save-excursion (end-of-defun) (point))))
@end group
@group
    (while
        (and (< (point) end)
             (re-search-forward
              "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
              end t))
      (setq count (1+ count)))
    count))
@end group
@end smallexample

How to test this? The function is not interactive, but it is easy to put a
wrapper around the function to make it interactive; we can use almost the
same code as for the recursive version of @code{@value{COUNT-WORDS}}:

@smallexample
@group
;;; @r{Interactive version.}
(defun count-words-defun ()
  "Number of words and symbols in a function definition."
  (interactive)
  (message
   "Counting words and symbols in function definition ... ")
@end group
@group
  (let ((count (count-words-in-defun)))
    (cond
     ((zerop count)
      (message
       "The definition does NOT have any words or symbols."))
@end group
@group
     ((= 1 count)
      (message
       "The definition has 1 word or symbol."))
     (t
      (message
       "The definition has %d words or symbols." count)))))
@end group
@end smallexample

@need 800
@noindent
Let's reuse @kbd{C-c =} as a convenient key binding:

@smallexample
(keymap-global-set "C-c =" 'count-words-defun)
@end smallexample

Now we can try out @code{count-words-defun}: install both
@code{count-words-in-defun} and @code{count-words-defun}, and set the key
binding.  Then copy the following to an Emacs Lisp buffer (like, for
instance, @file{*scratch*}), place the cursor within the definition, and use
the @kbd{C-c =} command.

@smallexample
@group
(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))
     @result{} 10
@end group
@end smallexample

@noindent
Success! The definition has 10 words and symbols.

The next problem is to count the numbers of words and symbols in several
definitions within a single file.

@node Enkele defuns
@section Count Several @code{defuns} Within a File

A file such as @file{simple.el} may have a hundred or more function
definitions within it.  Our long term goal is to collect statistics on many
files, but as a first step, our immediate goal is to collect statistics on
one file.

The information will be a series of numbers, each number being the length of
a function definition.  We can store the numbers in a list.

We know that we will want to incorporate the information regarding one file
with information about many other files; this means that the function for
counting definition lengths within one file need only return the list of
lengths.  It need not and should not display any messages.

The word count commands contain one expression to jump point forward word by
word and another expression to count the jumps.  The function to return the
lengths of definitions can be designed to work the same way, with one
expression to jump point forward definition by definition and another
expression to construct the lengths' list.

This statement of the problem makes it elementary to write the function
definition.  Clearly, we will start the count at the beginning of the file,
so the first command will be @code{(goto-char (point-min))}.  Next, we start
the @code{while} loop; and the true-or-false test of the loop can be a
regular expression search for the next function definition---so long as the
search succeeds, point is moved forward and then the body of the loop is
evaluated.  The body needs an expression that constructs the lengths' list.
@code{cons}, the list construction command, can be used to create the list.
That is almost all there is to it.

@need 800
Here is what this fragment of code looks like:

@smallexample
@group
(goto-char (point-min))
(while (re-search-forward "^(defun" nil t)
  (setq lengths-list
        (cons (count-words-in-defun) lengths-list)))
@end group
@end smallexample

What we have left out is the mechanism for finding the file that contains
the function definitions.

In previous examples, we either used this, the Info file, or we switched
back and forth to some other buffer, such as the @file{*scratch*} buffer.

Finding a file is a new process that we have not yet discussed.

@node Een bestand vinden
@section Een bestand vinden
@cindex Een bestand vinden

To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file})
command.  This command is almost, but not quite right for the lengths
problem.

@need 1200
Let's look at the source for @code{find-file}:

@smallexample
@group
(defun find-file (filename)
  "Edit file FILENAME.
Switch to a buffer visiting file FILENAME,
creating one if none already exists."
  (interactive "FFind file: ")
  (switch-to-buffer (find-file-noselect filename)))
@end group
@end smallexample

@noindent
(The most recent version of the @code{find-file} function definition permits
you to specify optional wildcards to visit multiple files; that makes the
definition more complex and we will not discuss it here, since it is not
relevant.  You can see its source using either @kbd{M-.}
(@code{xref-find-definitions}) or @kbd{C-h f} (@code{describe-function}).)

@ignore
In Emacs 22
(defun find-file (filename &optional wildcards)
  "Edit file FILENAME.
Switch to a buffer visiting file FILENAME,
creating one if none already exists.
Interactively, the default if you just type @key{RET} is the current directory,
but the visited file name is available through the minibuffer history:
type M-n to pull it into the minibuffer.

Interactively, or if WILDCARDS is non-nil in a call from Lisp,
expand wildcards (if any) and visit multiple files.  You can
suppress wildcard expansion by setting `find-file-wildcards' to nil.

To visit a file without any kind of conversion and without
automatically choosing a major mode, use \\[find-file-literally]."
  (interactive (find-file-read-args "Find file: " nil))
  (let ((value (find-file-noselect filename nil nil wildcards)))
    (if (listp value)
        (mapcar 'switch-to-buffer (nreverse value))
      (switch-to-buffer value))))
@end ignore

The definition I am showing possesses short but complete documentation and
an interactive specification that prompts you for a file name when you use
the command interactively.  The body of the definition contains two
functions, @code{find-file-noselect} and @code{switch-to-buffer}.

According to its documentation as shown by @kbd{C-h f} (the
@code{describe-function} command), the @code{find-file-noselect} function
reads the named file into a buffer and returns the buffer.  (Its most recent
version includes an optional @var{wildcards} argument, too, as well as
another to read a file literally and another to suppress warning messages.
These optional arguments are irrelevant.)

However, the @code{find-file-noselect} function does not select the buffer
in which it puts the file.  Emacs does not switch its attention (or yours if
you are using @code{find-file-noselect}) to the selected buffer.  That is
what @code{switch-to-buffer} does: it switches the buffer to which Emacs
attention is directed; and it switches the buffer displayed in the window to
the new buffer.  We have discussed buffer switching elsewhere.
(@xref{Switching Buffers}.)

In this histogram project, we do not need to display each file on the screen
as the program determines the length of each definition within it.  Instead
of employing @code{switch-to-buffer}, we can work with @code{set-buffer},
which redirects the attention of the computer program to a different buffer
but does not redisplay it on the screen.  So instead of calling on
@code{find-file} to do the job, we must write our own expression.

The task is easy: use @code{find-file-noselect} and @code{set-buffer}.

@node lengths-list-file
@section @code{lengths-list-file} in Detail

The core of the @code{lengths-list-file} function is a @code{while} loop
containing a function to move point forward defun by defun, and a function
to count the number of words and symbols in each defun.  This core must be
surrounded by functions that do various other tasks, including finding the
file, and ensuring that point starts out at the beginning of the file.  The
function definition looks like this:
@findex lengths-list-file

@smallexample
@group
(defun lengths-list-file (filename)
  "Return list of definitions' lengths within FILE.
The returned list is a list of numbers.
Each number is the number of words or
symbols in one function definition."
@end group
@group
  (message "Working on `%s' ... " filename)
  (save-excursion
    (let ((buffer (find-file-noselect filename))
          (lengths-list))
      (set-buffer buffer)
      (setq buffer-read-only t)
      (widen)
      (goto-char (point-min))
      (while (re-search-forward "^(defun" nil t)
        (setq lengths-list
              (cons (count-words-in-defun) lengths-list)))
      (kill-buffer buffer)
      lengths-list)))
@end group
@end smallexample

@noindent
The function is passed one argument, the name of the file on which it will
work.  It has four lines of documentation, but no interactive
specification.  Since people worry that a computer is broken if they don't
see anything going on, the first line of the body is a message.

The next line contains a @code{save-excursion} that returns Emacs's
attention to the current buffer when the function completes.  This is useful
in case you embed this function in another function that presumes point is
restored to the original buffer.

In the varlist of the @code{let} expression, Emacs finds the file and binds
the local variable @code{buffer} to the buffer containing the file.  At the
same time, Emacs creates @code{lengths-list} as a local variable.

Next, Emacs switches its attention to the buffer.

In the following line, Emacs makes the buffer read-only.  Ideally, this line
is not necessary.  None of the functions for counting words and symbols in a
function definition should change the buffer.  Besides, the buffer is not
going to be saved, even if it were changed.  This line is entirely the
consequence of great, perhaps excessive, caution.  The reason for the
caution is that this function and those it calls work on the sources for
Emacs and it is inconvenient if they are inadvertently modified.  It goes
without saying that I did not realize a need for this line until an
experiment went awry and started to modify my Emacs source files @dots{}

Next comes a call to widen the buffer if it is narrowed.  This function is
usually not needed---Emacs creates a fresh buffer if none already exists;
but if a buffer visiting the file already exists Emacs returns that one.  In
this case, the buffer may be narrowed and must be widened.  If we wanted to
be fully user-friendly, we would arrange to save the restriction and the
location of point, but we won't.

The @code{(goto-char (point-min))} expression moves point to the beginning
of the buffer.

Then comes a @code{while} loop in which the work of the function is carried
out.  In the loop, Emacs determines the length of each definition and
constructs a lengths' list containing the information.

Emacs kills the buffer after working through it.  This is to save space
inside of Emacs.  My version of GNU Emacs 19 contained over 300 source files
of interest; GNU Emacs 22 contains over a thousand source files.  Another
function will apply @code{lengths-list-file} to each of the files.

Finally, the last expression within the @code{let} expression is the
@code{lengths-list} variable; its value is returned as the value of the
whole function.

You can try this function by installing it in the usual fashion.  Then place
your cursor after the following expression and type @kbd{C-x C-e}
(@code{eval-last-sexp}).

@c !!! 22.1.1 lisp sources location here
@smallexample
(lengths-list-file
 "/usr/local/share/emacs/22.1/lisp/emacs-lisp/debug.el")
@end smallexample

@noindent
You may need to change the pathname of the file; the one here is for GNU
Emacs version 22.1.  To change the expression, copy it to the
@file{*scratch*} buffer and edit it.

@need 1200
@noindent
@c We do not want to insert, so do not mention the zero prefix argument.
Also, to see the full length of the list, rather than a truncated version,
you may have to evaluate the following:

@smallexample
(custom-set-variables '(eval-expression-print-length nil))
@end smallexample

@noindent
(@xref{defcustom, , Variabelen specificeren met @code{defcustom}}. Evalueer
daarna de @code{lengths-list-file} expressie.)

@need 1200
The lengths' list for @file{debug.el} takes less than a second to produce
and looks like this in GNU Emacs 22:

@smallexample
(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
@end smallexample

@need 1500
(Using my old machine, the version 19 lengths' list for @file{debug.el} took
seven seconds to produce and looked like this:

@smallexample
(75 41 80 62 20 45 44 68 45 12 34 235)
@end smallexample

@noindent
The newer version of @file{debug.el} contains more defuns than the earlier
one; and my new machine is much faster than the old one.)

Note that the length of the last definition in the file is first in the
list.

@node Enkele bestanden
@section Woorden tellen in  @code{defuns} in verschillende bestanden

In the previous section, we created a function that returns a list of the
lengths of each definition in a file.  Now, we want to define a function to
return a master list of the lengths of the definitions in a list of files.

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

@menu
* lengths-list-many-files::  Een lijst met de lengte van defuns teruggeven.
* append::                   Een lijst aan een andere koppelen.
@end menu

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

The design using a @code{while} loop is routine.  The argument passed to the
function is a list of files.  As we saw earlier (@pxref{Loop Example}), you
can write a @code{while} loop so that the body of the loop is evaluated if
such a list contains elements, but to exit the loop if the list is empty.
For this design to work, the body of the loop must contain an expression
that shortens the list each time the body is evaluated, so that eventually
the list is empty.  The usual technique is to set the value of the list to
the value of the @sc{cdr} of the list each time the body is evaluated.

@need 800
The template looks like this:

@smallexample
@group
(while @var{test-whether-list-is-empty}
  @var{body}@dots{}
  @var{set-list-to-cdr-of-list})
@end group
@end smallexample

Also, we remember that a @code{while} loop returns @code{nil} (the result of
evaluating the true-or-false-test), not the result of any evaluation within
its body.  (The evaluations within the body of the loop are done for their
side effects.)  However, the expression that sets the lengths' list is part
of the body---and that is the value that we want returned by the function as
a whole.  To do this, we enclose the @code{while} loop within a @code{let}
expression, and arrange that the last element of the @code{let} expression
contains the value of the lengths' list.  (@xref{Incrementing Example, ,
Loop Example with an Incrementing Counter}.)

@findex lengths-list-many-files
@need 1250
These considerations lead us directly to the function itself:

@smallexample
@group
;;; @r{Use @code{while} loop.}
(defun lengths-list-many-files (list-of-files)
  "Return list of lengths of defuns in LIST-OF-FILES."
@end group
@group
  (let (lengths-list)

;;; @r{true-or-false-test}
    (while list-of-files
      (setq lengths-list
            (append
             lengths-list

;;; @r{Generate a lengths' list.}
             (lengths-list-file
              (expand-file-name (car list-of-files)))))
@end group

@group
;;; @r{Make files' list shorter.}
      (setq list-of-files (cdr list-of-files)))

;;; @r{Return final value of lengths' list.}
    lengths-list))
@end group
@end smallexample

@code{expand-file-name} is a built-in function that converts a file name to
the absolute, long, path name form.  The function employs the name of the
directory in which the function is called.

@c !!! 22.1.1 lisp sources location here
@need 1500
Thus, if @code{expand-file-name} is called on @code{debug.el} when Emacs is
visiting the @file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/}
directory,

@smallexample
debug.el
@end smallexample

@need 800
@noindent
becomes

@c !!! 22.1.1 lisp sources location here
@smallexample
/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el
@end smallexample

The only other new element of this function definition is the as yet
unstudied function @code{append}, which merits a short section for itself.

@node append
@subsection The @code{append} Function

@need 800
The @code{append} function attaches one list to another.  Thus,

@smallexample
(append '(1 2 3 4) '(5 6 7 8))
@end smallexample

@need 800
@noindent
produces the list

@smallexample
(1 2 3 4 5 6 7 8)
@end smallexample

This is exactly how we want to attach two lengths' lists produced by
@code{lengths-list-file} to each other.  The results contrast with
@code{cons},

@smallexample
(cons '(1 2 3 4) '(5 6 7 8))
@end smallexample

@need 1250
@noindent
which constructs a new list in which the first argument to @code{cons}
becomes the first element of the new list:

@smallexample
((1 2 3 4) 5 6 7 8)
@end smallexample

@node Enkele bestanden recursief
@section Recursively Count Words in Different Files

Besides a @code{while} loop, you can work on each of a list of files with
recursion.  A recursive version of @code{lengths-list-many-files} is short
and simple.

The recursive function has the usual parts: the do-again-test, the
next-step-expression, and the recursive call.  The do-again-test determines
whether the function should call itself again, which it will do if the
@code{list-of-files} contains any remaining elements; the
next-step-expression resets the @code{list-of-files} to the @sc{cdr} of
itself, so eventually the list will be empty; and the recursive call calls
itself on the shorter list.  The complete function is shorter than this
description!
@findex recursive-lengths-list-many-files

@smallexample
@group
(defun recursive-lengths-list-many-files (list-of-files)
  "Return list of lengths of each defun in LIST-OF-FILES."
  (if list-of-files                     ; @r{do-again-test}
      (append
       (lengths-list-file
        (expand-file-name (car list-of-files)))
       (recursive-lengths-list-many-files
        (cdr list-of-files)))))
@end group
@end smallexample

@noindent
In a sentence, the function returns the lengths' list for the first of the
@code{list-of-files} appended to the result of calling itself on the rest of
the @code{list-of-files}.

Here is a test of @code{recursive-lengths-list-many-files}, along with the
results of running @code{lengths-list-file} on each of the files
individually.

Install @code{recursive-lengths-list-many-files} and
@code{lengths-list-file}, if necessary, and then evaluate the following
expressions.  You may need to change the files' pathnames; those here work
when this Info file and the Emacs sources are located in their customary
places.  To change the expressions, copy them to the @file{*scratch*}
buffer, edit them, and then evaluate them.

The results are shown after the @samp{@result{}}.  (These results are for
files from Emacs version 22.1.1; files from other versions of Emacs may
produce different results.)

@c !!! 22.1.1 lisp sources location here
@smallexample
@group
(cd "/usr/local/share/emacs/22.1.1/")

(lengths-list-file "./lisp/macros.el")
     @result{} (283 263 480 90)
@end group

@group
(lengths-list-file "./lisp/mail/mailalias.el")
     @result{} (38 32 29 95 178 180 321 218 324)
@end group

@group
(lengths-list-file "./lisp/hex-util.el")
     @result{} (82 71)
@end group

@group
  (recursive-lengths-list-many-files
   '("./lisp/macros.el"
     "./lisp/mail/mailalias.el"
     "./lisp/hex-util.el"))
       @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 82 71)
@end group
@end smallexample

The @code{recursive-lengths-list-many-files} function produces the output we
want.

The next step is to prepare the data in the list for display in a graph.

@node De data voorbereiden
@section De data voorbereiden om in een grafiek te tonen

The @code{recursive-lengths-list-many-files} function returns a list of
numbers.  Each number records the length of a function definition.  What we
need to do now is transform this data into a list of numbers suitable for
generating a graph.  The new list will tell how many functions definitions
contain less than 10 words and symbols, how many contain between 10 and 19
words and symbols, how many contain between 20 and 29 words and symbols, and
so on.

In brief, we need to go through the lengths' list produced by the
@code{recursive-lengths-list-many-files} function and count the number of
defuns within each range of lengths, and produce a list of those numbers.

@menu
* Data in detail te tonen::  Data in detail te tonen
* Sorteren::                 Lijsten sorteren
* Bestanden lijst::          Een lijst van bestanden maken.
* Functiedefinities tellen::  Functiedefinities tellen
@end menu

@ifnottex
@node Data in detail te tonen
@unnumberedsubsec De data om in detail te tonen
@end ifnottex

Based on what we have done before, we can readily foresee that it should not
be too hard to write a function that @sc{cdr}s down the lengths' list, looks
at each element, determines which length range it is in, and increments a
counter for that range.

However, before beginning to write such a function, we should consider the
advantages of sorting the lengths' list first, so the numbers are ordered
from smallest to largest.  First, sorting will make it easier to count the
numbers in each range, since two adjacent numbers will either be in the same
length range or in adjacent ranges.  Second, by inspecting a sorted list, we
can discover the highest and lowest number, and thereby determine the
largest and smallest length range that we will need.

@node Sorteren
@subsection Sorting Lists
@findex sort

Emacs contains a function to sort lists, called (as you might guess)
@code{sort}.  The @code{sort} function takes two arguments, the list to be
sorted, and a predicate that determines whether the first of two list
elements is less than the second.

As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong Type
Object as an Argument}), a predicate is a function that determines whether
some property is true or false.  The @code{sort} function will reorder a
list according to whatever property the predicate uses; this means that
@code{sort} can be used to sort non-numeric lists by non-numeric
criteria---it can, for example, alphabetize a list.

@need 1250
The @code{<} function is used when sorting a numeric list.  For example,

@smallexample
(sort '(4 8 21 17 33 7 21 7) '<)
@end smallexample

@need 800
@noindent
produceert dit:

@smallexample
(4 7 7 8 17 21 21 33)
@end smallexample

@noindent
(Note that in this example, both the arguments are quoted so that the
symbols are not evaluated before being passed to @code{sort} as arguments.)

Sorting the list returned by the @code{recursive-lengths-list-many-files}
function is straightforward; it uses the @code{<} function:

@smallexample
@group
(sort
 (recursive-lengths-list-many-files
  '("./lisp/macros.el"
    "./lisp/mailalias.el"
    "./lisp/hex-util.el"))
 '<)
@end group
@end smallexample

@need 800
@noindent
which produces:

@smallexample
(29 32 38 71 82 90 95 178 180 218 263 283 321 324 480)
@end smallexample

@noindent
(Note that in this example, the first argument to @code{sort} is not quoted,
since the expression must be evaluated so as to produce the list that is
passed to @code{sort}.)

@node Bestanden lijst
@subsection Making a List of Files

The @code{recursive-lengths-list-many-files} function requires a list of
files as its argument.  For our test examples, we constructed such a list by
hand; but the Emacs Lisp source directory is too large for us to do for
that.  Instead, we will write a function to do the job for us.  In this
function, we will use both a @code{while} loop and a recursive call.

@findex directory-files
We did not have to write a function like this for older versions of GNU
Emacs, since they placed all the @samp{.el} files in one directory.
Instead, we were able to use the @code{directory-files} function, which
lists the names of files that match a specified pattern within a single
directory.

However, recent versions of Emacs place Emacs Lisp files in sub-directories
of the top level @file{lisp} directory.  This re-arrangement eases
navigation.  For example, all the mail related files are in a @file{lisp}
sub-directory called @file{mail}.  But at the same time, this arrangement
forces us to create a file listing function that descends into the
sub-directories.

@findex files-in-below-directory
We can create this function, called @code{files-in-below-directory}, using
familiar functions such as @code{car}, @code{nthcdr}, and @code{substring}
in conjunction with an existing function called
@code{directory-files-and-attributes}.  This latter function not only lists
all the filenames in a directory, including the names of sub-directories,
but also their attributes.

To restate our goal: to create a function that will enable us to feed
filenames to @code{recursive-lengths-list-many-files} as a list that looks
like this (but with more elements):

@smallexample
@group
("./lisp/macros.el"
 "./lisp/mail/rmail.el"
 "./lisp/hex-util.el")
@end group
@end smallexample

The @code{directory-files-and-attributes} function returns a list of lists.
Each of the lists within the main list consists of 13 elements.  The first
element is a string that contains the name of the file---which, in
GNU/Linux, may be a @dfn{directory file}, that is to say, a file with the
special attributes of a directory.  The second element of the list is
@code{t} for a directory, a string for symbolic link (the string is the name
linked to), or @code{nil}.

For example, the first @samp{.el} file in the @file{lisp/} directory is
@file{abbrev.el}.  Its name is
@file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a
directory or a symbolic link.

@need 1000
This is how @code{directory-files-and-attributes} lists that file and its
attributes:

@smallexample
@group
("abbrev.el"
nil
1
1000
100
@end group
@group
(20615 27034 579989 697000)
(17905 55681 0 0)
(20615 26327 734791 805000)@footnote{If @code{current-time-list} is
@code{nil} the three timestamps are @code{(1351051674579989697
. 1000000000)}, @code{(1173477761000000000 . 1000000000)}, and
@code{(1351050967734791805 . 1000000000)}, respectively.}
13188
"-rw-r--r--"
@end group
@group
t
2971624
773)
@end group
@end smallexample

@need 1200
On the other hand, @file{mail/} is a directory within the @file{lisp/}
directory.  The beginning of its listing looks like this:

@smallexample
@group
("mail"
t
@dots{}
)
@end group
@end smallexample

(To learn about the different attributes, look at the documentation of
@code{file-attributes}.  Bear in mind that the @code{file-attributes}
function does not list the filename, so its first element is
@code{directory-files-and-attributes}'s second element.)

We will want our new function, @code{files-in-below-directory}, to list the
@samp{.el} files in the directory it is told to check, and in any
directories below that directory.

This gives us a hint on how to construct @code{files-in-below-directory}:
within a directory, the function should add @samp{.el} filenames to a list;
and if, within a directory, the function comes upon a sub-directory, it
should go into that sub-directory and repeat its actions.

However, we should note that every directory contains a name that refers to
itself, called @file{.} (``dot''), and a name that refers to its parent
directory, called @file{..} (``dot dot'').  (In @file{/}, the root
directory, @file{..} refers to itself, since @file{/} has no parent.)
Clearly, we do not want our @code{files-in-below-directory} function to
enter those directories, since they always lead us, directly or indirectly,
to the current directory.

Consequently, our @code{files-in-below-directory} function must do several
tasks:

@itemize @bullet
@item
Check to see whether it is looking at a filename that ends in @samp{.el};
and if so, add its name to a list.

@item
Check to see whether it is looking at a filename that is the name of a
directory; and if so,

@itemize @minus
@item
Check to see whether it is looking at @file{.} or @file{..}; and if so skip
it.

@item
Or else, go into that directory and repeat the process.
@end itemize
@end itemize

Let's write a function definition to do these tasks.  We will use a
@code{while} loop to move from one filename to another within a directory,
checking what needs to be done; and we will use a recursive call to repeat
the actions on each sub-directory.  The recursive pattern is Accumulate
(@pxref{Accumulate}), using @code{append} as the combiner.

@ignore
(directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
(shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")

(directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$")
(shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'")
@end ignore

@c  /usr/local/share/emacs/22.1.1/lisp/

@need 800
Here is the function:

@smallexample
@group
(defun files-in-below-directory (directory)
  "List the .el files in DIRECTORY and in its sub-directories."
  ;; Although the function will be used non-interactively,
  ;; it will be easier to test if we make it interactive.
  ;; The directory will have a name such as
  ;;  "/usr/local/share/emacs/22.1.1/lisp/"
  (interactive "DDirectory name: ")
@end group
@group
  (let (el-files-list
        (current-directory-list
         (directory-files-and-attributes directory t)))
    ;; while we are in the current directory
    (while current-directory-list
@end group
@group
      (cond
       ;; check to see whether filename ends in '.el'
       ;; and if so, add its name to a list.
       ((equal ".el" (substring (car (car current-directory-list)) -3))
        (setq el-files-list
              (cons (car (car current-directory-list)) el-files-list)))
@end group
@group
       ;; check whether filename is that of a directory
       ((eq t (car (cdr (car current-directory-list))))
        ;; decide whether to skip or recurse
        (if
            (equal "."
                   (substring (car (car current-directory-list)) -1))
            ;; then do nothing since filename is that of
            ;;   current directory or parent, "." or ".."
            ()
@end group
@group
          ;; else descend into the directory and repeat the process
          (setq el-files-list
                (append
                 (files-in-below-directory
                  (car (car current-directory-list)))
                 el-files-list)))))
      ;; move to the next filename in the list; this also
      ;; shortens the list so the while loop eventually comes to an end
      (setq current-directory-list (cdr current-directory-list)))
    ;; return the filenames
    el-files-list))
@end group
@end smallexample

@c (files-in-below-directory "/usr/local/src/emacs/lisp/")
@c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")

The @code{files-in-below-directory} @code{directory-files} function takes
one argument, the name of a directory.

@need 1250
Thus, on my system,

@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))

@c !!! 22.1.1 lisp sources location here
@smallexample
@group
(length
 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/"))
@end group
@end smallexample

@noindent
tells me that in and below my Lisp sources directory are 1031 @samp{.el}
files.

@code{files-in-below-directory} returns a list in reverse alphabetical
order.  An expression to sort the list in alphabetical order looks like
this:

@smallexample
@group
(sort
 (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")
 'string-lessp)
@end group
@end smallexample

@ignore
(defun test ()
  "Test how long it takes to find lengths of all sorted elisp defuns."
  (insert "\n" (current-time-string) "\n")
  (sit-for 0)
  (sort
   (recursive-lengths-list-many-files
    (files-in-below-directory "/usr/local/src/emacs/lisp/"))
   '<)
  (insert (current-time-string)))
@end ignore

@node Functiedefinities tellen
@subsection Functiedefinities tellen

Our immediate goal is to generate a list that tells us how many function
definitions contain fewer than 10 words and symbols, how many contain
between 10 and 19 words and symbols, how many contain between 20 and 29
words and symbols, and so on.

With a sorted list of numbers, this is easy: count how many elements of the
list are smaller than 10, then, after moving past the numbers just counted,
count how many are smaller than 20, then, after moving past the numbers just
counted, count how many are smaller than 30, and so on.  Each of the
numbers, 10, 20, 30, 40, and the like, is one larger than the top of that
range.  We can call the list of such numbers the @code{top-of-ranges} list.

@need 1200
If we wished, we could generate this list automatically, but it is simpler
to write a list manually.  Here it is:
@vindex top-of-ranges

@smallexample
@group
(defvar top-of-ranges
 '(10  20  30  40  50
   60  70  80  90 100
  110 120 130 140 150
  160 170 180 190 200
  210 220 230 240 250
  260 270 280 290 300)
 "List specifying ranges for `defuns-per-range'.")
@end group
@end smallexample

To change the ranges, we edit this list.

Next, we need to write the function that creates the list of the number of
definitions within each range.  Clearly, this function must take the
@code{sorted-lengths} and the @code{top-of-ranges} lists as arguments.

The @code{defuns-per-range} function must do two things again and again: it
must count the number of definitions within a range specified by the current
top-of-range value; and it must shift to the next higher value in the
@code{top-of-ranges} list after counting the number of definitions in the
current range.  Since each of these actions is repetitive, we can use
@code{while} loops for the job.  One loop counts the number of definitions
in the range defined by the current top-of-range value, and the other loop
selects each of the top-of-range values in turn.

Several entries of the @code{sorted-lengths} list are counted for each
range; this means that the loop for the @code{sorted-lengths} list will be
inside the loop for the @code{top-of-ranges} list, like a small gear inside
a big gear.

The inner loop counts the number of definitions within the range.  It is a
simple counting loop of the type we have seen before.  (@xref{Incrementing
Loop, , A loop with an incrementing counter}.)  The true-or-false test of
the loop tests whether the value from the @code{sorted-lengths} list is
smaller than the current value of the top of the range.  If it is, the
function increments the counter and tests the next value from the
@code{sorted-lengths} list.

@need 1250
The inner loop looks like this:

@smallexample
@group
(while @var{length-element-smaller-than-top-of-range}
  (setq number-within-range (1+ number-within-range))
  (setq sorted-lengths (cdr sorted-lengths)))
@end group
@end smallexample

The outer loop must start with the lowest value of the @code{top-of-ranges}
list, and then be set to each of the succeeding higher values in turn.  This
can be done with a loop like this:

@smallexample
@group
(while top-of-ranges
  @var{body-of-loop}@dots{}
  (setq top-of-ranges (cdr top-of-ranges)))
@end group
@end smallexample

@need 1200
Put together, the two loops look like this:

@smallexample
@group
(while top-of-ranges

  ;; @r{Count the number of elements within the current range.}
  (while @var{length-element-smaller-than-top-of-range}
    (setq number-within-range (1+ number-within-range))
    (setq sorted-lengths (cdr sorted-lengths)))

  ;; @r{Move to next range.}
  (setq top-of-ranges (cdr top-of-ranges)))
@end group
@end smallexample

In addition, in each circuit of the outer loop, Emacs should record the
number of definitions within that range (the value of
@code{number-within-range}) in a list.  We can use @code{cons} for this
purpose.  (@xref{cons, , @code{cons}}.)

The @code{cons} function works fine, except that the list it constructs will
contain the number of definitions for the highest range at its beginning and
the number of definitions for the lowest range at its end.  This is because
@code{cons} attaches new elements of the list to the beginning of the list,
and since the two loops are working their way through the lengths' list from
the lower end first, the @code{defuns-per-range-list} will end up largest
number first.  But we will want to print our graph with smallest values
first and the larger later.  The solution is to reverse the order of the
@code{defuns-per-range-list}.  We can do this using the @code{nreverse}
function, which reverses the order of a list.
@findex nreverse

@need 800
Bijvoorbeeld,

@smallexample
(nreverse '(1 2 3 4))
@end smallexample

@need 800
@noindent
produceert:

@smallexample
(4 3 2 1)
@end smallexample

Note that the @code{nreverse} function is destructive---that is, it changes
the list to which it is applied; this contrasts with the @code{car} and
@code{cdr} functions, which are non-destructive.  In this case, we do not
want the original @code{defuns-per-range-list}, so it does not matter that
it is destroyed.  (The @code{reverse} function provides a reversed copy of a
list, leaving the original list as is.)
@findex reverse

@need 1250
Put all together, the @code{defuns-per-range} looks like this:

@smallexample
@group
(defun defuns-per-range (sorted-lengths top-of-ranges)
  "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
  (let ((top-of-range (car top-of-ranges))
        (number-within-range 0)
        defuns-per-range-list)
@end group

@group
    ;; @r{Outer loop.}
    (while top-of-ranges
@end group

@group
      ;; @r{Inner loop.}
      (while (and
              ;; @r{Need number for numeric test.}
              (car sorted-lengths)
              (< (car sorted-lengths) top-of-range))
@end group

@group
        ;; @r{Count number of definitions within current range.}
        (setq number-within-range (1+ number-within-range))
        (setq sorted-lengths (cdr sorted-lengths)))

      ;; @r{Exit inner loop but remain within outer loop.}
@end group

@group
      (setq defuns-per-range-list
            (cons number-within-range defuns-per-range-list))
      (setq number-within-range 0)      ; @r{Reset count to zero.}
@end group

@group
      ;; @r{Move to next range.}
      (setq top-of-ranges (cdr top-of-ranges))
      ;; @r{Specify next top of range value.}
      (setq top-of-range (car top-of-ranges)))
@end group

@group
    ;; @r{Exit outer loop and count the number of defuns larger than}
    ;; @r{  the largest top-of-range value.}
    (setq defuns-per-range-list
          (cons
           (length sorted-lengths)
           defuns-per-range-list))
@end group

@group
    ;; @r{Return a list of the number of definitions within each range,}
    ;; @r{  smallest to largest.}
    (nreverse defuns-per-range-list)))
@end group
@end smallexample

@need 1200
@noindent
The function is straightforward except for one subtle feature.  The
true-or-false test of the inner loop looks like this:

@smallexample
@group
(and (car sorted-lengths)
     (< (car sorted-lengths) top-of-range))
@end group
@end smallexample

@need 800
@noindent
instead of like this:

@smallexample
(< (car sorted-lengths) top-of-range)
@end smallexample

The purpose of the test is to determine whether the first item in the
@code{sorted-lengths} list is less than the value of the top of the range.

The simple version of the test works fine unless the @code{sorted-lengths}
list has a @code{nil} value.  In that case, the @code{(car sorted-lengths)}
expression function returns @code{nil}.  The @code{<} function cannot
compare a number to @code{nil}, which is an empty list, so Emacs signals an
error and stops the function from attempting to continue to execute.

The @code{sorted-lengths} list always becomes @code{nil} when the counter
reaches the end of the list.  This means that any attempt to use the
@code{defuns-per-range} function with the simple version of the test will
fail.

We solve the problem by using the @code{(car sorted-lengths)} expression in
conjunction with the @code{and} expression.  The @code{(car sorted-lengths)}
expression returns a non-@code{nil} value so long as the list has at least
one number within it, but returns @code{nil} if the list is empty.  The
@code{and} expression first evaluates the @code{(car sorted-lengths)}
expression, and if it is @code{nil}, returns false @emph{without} evaluating
the @code{<} expression.  But if the @code{(car sorted-lengths)} expression
returns a non-@code{nil} value, the @code{and} expression evaluates the
@code{<} expression, and returns that value as the value of the @code{and}
expression.

@c colon in printed section title causes problem in Info cross reference
This way, we avoid an error.

@iftex
@noindent
(For information about @code{and}, see @ref{kill-new function, , The
@code{kill-new} function}.)
@end iftex
@ifinfo
@noindent
(@xref{kill-new function, , The @code{kill-new} function}, for information
about @code{and}.)
@end ifinfo

Here is a short test of the @code{defuns-per-range} function.  First,
evaluate the expression that binds (a shortened)  @code{top-of-ranges} list
to the list of values, then evaluate the expression for binding the
@code{sorted-lengths} list, and then evaluate the @code{defuns-per-range}
function.

@smallexample
@group
;; @r{(Shorter list than we will use later.)}
(setq top-of-ranges
 '(110 120 130 140 150
   160 170 180 190 200))

(setq sorted-lengths
      '(85 86 110 116 122 129 154 176 179 200 265 300 300))

(defuns-per-range sorted-lengths top-of-ranges)
@end group
@end smallexample

@need 800
@noindent
The list returned looks like this:

@smallexample
(2 2 2 0 0 1 0 2 0 0 4)
@end smallexample

@noindent
Indeed, there are two elements of the @code{sorted-lengths} list smaller
than 110, two elements between 110 and 119, two elements between 120 and
129, and so on.  There are four elements with a value of 200 or larger.

@c The next step is to turn this numbers' list into a graph.
@node Een grafiek klaarmaken
@chapter Een grafiek klaarmaken
@cindex Readying a graph
@cindex Graph prototype
@cindex Prototype graph
@cindex Body of graph

Our goal is to construct a graph showing the numbers of function definitions
of various lengths in the Emacs lisp sources.

As a practical matter, if you were creating a graph, you would probably use
a program such as @code{gnuplot} to do the job.  (@code{gnuplot} is nicely
integrated into GNU Emacs.)  In this case, however, we create one from
scratch, and in the process we will re-acquaint ourselves with some of what
we learned before and learn more.

In this chapter, we will first write a simple graph printing function.  This
first definition will be a @dfn{prototype}, a rapidly written function that
enables us to reconnoiter this unknown graph-making territory.  We will
discover dragons, or find that they are myth.  After scouting the terrain,
we will feel more confident and enhance the function to label the axes
automatically.

@menu
* Kolommen van een grafiek::  Kolommen van een grafiek
* graph-body-print::         Hoe de body van een grafiek af te drukken.
* recursive-graph-body-print::  recursive-graph-body-print
* Afgedrukte assen::         Afgedrukte assen
* Lijngrafiek oefening::     Lijngrafiek oefening
@end menu

@ifnottex
@node Kolommen van een grafiek
@unnumberedsec Printing the Columns of a Graph
@end ifnottex

Since Emacs is designed to be flexible and work with all kinds of terminals,
including character-only terminals, the graph will need to be made from one
of the typewriter symbols.  An asterisk will do; as we enhance the
graph-printing function, we can make the choice of symbol a user option.

We can call this function @code{graph-body-print}; it will take a
@code{numbers-list} as its only argument.  At this stage, we will not label
the graph, but only print its body.

The @code{graph-body-print} function inserts a vertical column of asterisks
for each element in the @code{numbers-list}.  The height of each line is
determined by the value of that element of the @code{numbers-list}.

Inserting columns is a repetitive act; that means that this function can be
written either with a @code{while} loop or recursively.

Our first challenge is to discover how to print a column of asterisks.
Usually, in Emacs, we print characters onto a screen horizontally, line by
line, by typing.  We have two routes we can follow: write our own
column-insertion function or discover whether one exists in Emacs.

To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
command.  This command is like the @kbd{C-h a} (@code{command-apropos})
command, except that the latter finds only those functions that are
commands.  The @kbd{M-x apropos} command lists all symbols that match a
regular expression, including functions that are not interactive.
@findex apropos

What we want to look for is some command that prints or inserts columns.
Very likely, the name of the function will contain either the word ``print''
or the word ``insert'' or the word ``column''.  Therefore, we can simply
type @kbd{M-x apropos @key{RET} print\|insert\|column @key{RET}} and look at
the result.  On my system, this command once took quite some time, and then
produced a list of 79 functions and variables.  Now it does not take much
time at all and produces a list of 211 functions and variables.  Scanning
down the list, the only function that looks as if it might do the job is
@code{insert-rectangle}.

@need 1200
Indeed, this is the function we want; its documentation says:

@smallexample
@group
insert-rectangle:
Insert text of RECTANGLE with upper left corner at point.
RECTANGLE's first line is inserted at point,
its second line is inserted at a point vertically under point, etc.
RECTANGLE should be a list of strings.
After this command, the mark is at the upper left corner
and point is at the lower right corner.
@end group
@end smallexample

We can run a quick test, to make sure it does what we expect of it.

Here is the result of placing the cursor after the @code{insert-rectangle}
expression and typing @kbd{C-u C-x C-e} (@code{eval-last-sexp}).  The
function inserts the strings @samp{"first"}, @samp{"second"}, and
@samp{"third"} at and below point.  Also the function returns @code{nil}.

@smallexample
@group
(insert-rectangle '("first" "second" "third"))first
                                              second
                                              thirdnil
@end group
@end smallexample

@noindent
Of course, we won't be inserting the text of the @code{insert-rectangle}
expression itself into the buffer in which we are making the graph, but will
call the function from our program.  We shall, however, have to make sure
that point is in the buffer at the place where the @code{insert-rectangle}
function will insert its column of strings.

If you are reading this in Info, you can see how this works by switching to
another buffer, such as the @file{*scratch*} buffer, placing point somewhere
in the buffer, typing @kbd{M-:}, typing the @code{insert-rectangle}
expression into the minibuffer at the prompt, and then typing @key{RET}.
This causes Emacs to evaluate the expression in the minibuffer, but to use
as the value of point the position of point in the @file{*scratch*} buffer.
(@kbd{M-:} is the key binding for @code{eval-expression}.  Also, @code{nil}
does not appear in the @file{*scratch*} buffer since the expression is
evaluated in the minibuffer.)

We find when we do this that point ends up at the end of the last inserted
line---that is to say, this function moves point as a side-effect.  If we
were to repeat the command, with point at this position, the next insertion
would be below and to the right of the previous insertion.  We don't want
this! If we are going to make a bar graph, the columns need to be beside
each other.

So we discover that each cycle of the column-inserting @code{while} loop
must reposition point to the place we want it, and that place will be at the
top, not the bottom, of the column.  Moreover, we remember that when we
print a graph, we do not expect all the columns to be the same height.  This
means that the top of each column may be at a different height from the
previous one.  We cannot simply reposition point to the same line each time,
but moved over to the right---or perhaps we can@dots{}

We are planning to make the columns of the bar graph out of asterisks.  The
number of asterisks in the column is the number specified by the current
element of the @code{numbers-list}.  We need to construct a list of
asterisks of the right length for each call to @code{insert-rectangle}.  If
this list consists solely of the requisite number of asterisks, then we will
have to position point the right number of lines above the base for the
graph to print correctly.  This could be difficult.

Alternatively, if we can figure out some way to pass @code{insert-rectangle}
a list of the same length each time, then we can place point on the same
line each time, but move it over one column to the right for each new
column.  If we do this, however, some of the entries in the list passed to
@code{insert-rectangle} must be blanks rather than asterisks.  For example,
if the maximum height of the graph is 5, but the height of the column is 3,
then @code{insert-rectangle} requires an argument that looks like this:

@smallexample
(" " " " "*" "*" "*")
@end smallexample

This last proposal is not so difficult, so long as we can determine the
column height.  There are two ways for us to specify the column height: we
can arbitrarily state what it will be, which would work fine for graphs of
that height; or we can search through the list of numbers and use the
maximum height of the list as the maximum height of the graph.  If the
latter operation were difficult, then the former procedure would be easiest,
but there is a function built into Emacs that determines the maximum of its
arguments.  We can use that function.  The function is called @code{max} and
it returns the largest of all its arguments, which must be numbers.  Thus,
for example,

@smallexample
(max  3 4 6 5 7 3)
@end smallexample

@noindent
returns 7.  (A corresponding function called @code{min} returns the smallest
of all its arguments.)
@findex max
@findex min

However, we cannot simply call @code{max} on the @code{numbers-list}; the
@code{max} function expects numbers as its argument, not a list of numbers.
Thus, the following expression,

@smallexample
(max  '(3 4 6 5 7 3))
@end smallexample

@need 800
@noindent
produces the following error message;

@smallexample
Wrong type of argument:  number-or-marker-p, (3 4 6 5 7 3)
@end smallexample

@findex apply
We need a function that passes a list of arguments to a function.  This
function is @code{apply}.  This function applies its first argument (a
function) to its remaining arguments, the last of which may be a list.

@need 1250
Bijvoorbeeld,

@smallexample
(apply 'max 3 4 7 3 '(4 8 5))
@end smallexample

@noindent
returns 8.

(Incidentally, I don't know how you would learn of this function without a
book such as this.  It is possible to discover other functions, like
@code{search-forward} or @code{insert-rectangle}, by guessing at a part of
their names and then using @code{apropos}.  Even though its base in metaphor
is clear---apply its first argument to the rest---I doubt a novice would
come up with that particular word when using @code{apropos} or other aid.
Of course, I could be wrong; after all, the function was first named by
someone who had to invent it.)

The second and subsequent arguments to @code{apply} are optional, so we can
use @code{apply} to call a function and pass the elements of a list to it,
like this, which also returns 8:

@smallexample
(apply 'max '(4 8 5))
@end smallexample

This latter way is how we will use @code{apply}.  The
@code{recursive-lengths-list-many-files} function returns a numbers' list to
which we can apply @code{max} (we could also apply @code{max} to the sorted
numbers' list; it does not matter whether the list is sorted or not.)

@need 800
Hence, the operation for finding the maximum height of the graph is this:

@smallexample
(setq max-graph-height (apply 'max numbers-list))
@end smallexample

Now we can return to the question of how to create a list of strings for a
column of the graph.  Told the maximum height of the graph and the number of
asterisks that should appear in the column, the function should return a
list of strings for the @code{insert-rectangle} command to insert.

Each column is made up of asterisks or blanks.  Since the function is passed
the value of the height of the column and the number of asterisks in the
column, the number of blanks can be found by subtracting the number of
asterisks from the height of the column.  Given the number of blanks and the
number of asterisks, two @code{while} loops can be used to construct the
list:

@smallexample
@group
;;; @r{First version.}
(defun column-of-graph (max-graph-height actual-height)
  "Return list of strings that is one column of a graph."
  (let ((insert-list nil)
        (number-of-top-blanks
         (- max-graph-height actual-height)))
@end group

@group
    ;; @r{Fill in asterisks.}
    (while (> actual-height 0)
      (setq insert-list (cons "*" insert-list))
      (setq actual-height (1- actual-height)))
@end group

@group
    ;; @r{Fill in blanks.}
    (while (> number-of-top-blanks 0)
      (setq insert-list (cons " " insert-list))
      (setq number-of-top-blanks
            (1- number-of-top-blanks)))
@end group

@group
    ;; @r{Return whole list.}
    insert-list))
@end group
@end smallexample

If you install this function and then evaluate the following expression you
will see that it returns the list as desired:

@smallexample
(column-of-graph 5 3)
@end smallexample

@need 800
@noindent
returns

@smallexample
(" " " " "*" "*" "*")
@end smallexample

As written, @code{column-of-graph} contains a major flaw: the symbols used
for the blank and for the marked entries in the column are hard-coded as a
space and asterisk.  This is fine for a prototype, but you, or another user,
may wish to use other symbols.  For example, in testing the graph function,
you may want to use a period in place of the space, to make sure the point
is being repositioned properly each time the @code{insert-rectangle}
function is called; or you might want to substitute a @samp{+} sign or other
symbol for the asterisk.  You might even want to make a graph-column that is
more than one display column wide.  The program should be more flexible.
The way to do that is to replace the blank and the asterisk with two
variables that we can call @code{graph-blank} and @code{graph-symbol} and
define those variables separately.

Also, the documentation is not well written.  These considerations lead us
to the second version of the function:

@smallexample
@group
(defvar graph-symbol "*"
  "String used as symbol in graph, usually an asterisk.")
@end group

@group
(defvar graph-blank " "
  "String used as blank in graph, usually a blank space.
graph-blank must be the same number of columns wide
as graph-symbol.")
@end group
@end smallexample

@noindent
(For an explanation of @code{defvar}, see @ref{defvar, , Initializing a
Variable with @code{defvar}}.)

@smallexample
@group
;;; @r{Second version.}
(defun column-of-graph (max-graph-height actual-height)
  "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols.

@end group
@group
The graph-symbols are contiguous entries at the end
of the list.
The list will be inserted as one column of a graph.
The strings are either graph-blank or graph-symbol."
@end group

@group
  (let ((insert-list nil)
        (number-of-top-blanks
         (- max-graph-height actual-height)))
@end group

@group
    ;; @r{Fill in @code{graph-symbols}.}
    (while (> actual-height 0)
      (setq insert-list (cons graph-symbol insert-list))
      (setq actual-height (1- actual-height)))
@end group

@group
    ;; @r{Fill in @code{graph-blanks}.}
    (while (> number-of-top-blanks 0)
      (setq insert-list (cons graph-blank insert-list))
      (setq number-of-top-blanks
            (1- number-of-top-blanks)))

    ;; @r{Return whole list.}
    insert-list))
@end group
@end smallexample

If we wished, we could rewrite @code{column-of-graph} a third time to
provide optionally for a line graph as well as for a bar graph.  This would
not be hard to do.  One way to think of a line graph is that it is no more
than a bar graph in which the part of each bar that is below the top is
blank.  To construct a column for a line graph, the function first
constructs a list of blanks that is one shorter than the value, then it uses
@code{cons} to attach a graph symbol to the list; then it uses @code{cons}
again to attach the top blanks to the list.

It is easy to see how to write such a function, but since we don't need it,
we will not do it.  But the job could be done, and if it were done, it would
be done with @code{column-of-graph}.  Even more important, it is worth
noting that few changes would have to be made anywhere else.  The
enhancement, if we ever wish to make it, is simple.

Now, finally, we come to our first actual graph printing function.  This
prints the body of a graph, not the labels for the vertical and horizontal
axes, so we can call this @code{graph-body-print}.

@node graph-body-print
@section The @code{graph-body-print} Function
@findex graph-body-print

After our preparation in the preceding section, the @code{graph-body-print}
function is straightforward.  The function will print column after column of
asterisks and blanks, using the elements of a numbers' list to specify the
number of asterisks in each column.  This is a repetitive act, which means
we can use a decrementing @code{while} loop or recursive function for the
job.  In this section, we will write the definition using a @code{while}
loop.

The @code{column-of-graph} function requires the height of the graph as an
argument, so we should determine and record that as a local variable.

This leads us to the following template for the @code{while} loop version of
this function:

@smallexample
@group
(defun graph-body-print (numbers-list)
  "@var{documentation}@dots{}"
  (let ((height  @dots{}
         @dots{}))
@end group

@group
    (while numbers-list
      @var{insert-columns-and-reposition-point}
      (setq numbers-list (cdr numbers-list)))))
@end group
@end smallexample

@noindent
We need to fill in the slots of the template.

Clearly, we can use the @code{(apply 'max numbers-list)} expression to
determine the height of the graph.

The @code{while} loop will cycle through the @code{numbers-list} one element
at a time.  As it is shortened by the @code{(setq numbers-list (cdr
numbers-list))} expression, the @sc{car} of each instance of the list is the
value of the argument for @code{column-of-graph}.

At each cycle of the @code{while} loop, the @code{insert-rectangle} function
inserts the list returned by @code{column-of-graph}.  Since the
@code{insert-rectangle} function moves point to the lower right of the
inserted rectangle, we need to save the location of point at the time the
rectangle is inserted, move back to that position after the rectangle is
inserted, and then move horizontally to the next place from which
@code{insert-rectangle} is called.

If the inserted columns are one character wide, as they will be if single
blanks and asterisks are used, the repositioning command is simply
@code{(forward-char 1)}; however, the width of a column may be greater than
one.  This means that the repositioning command should be written
@code{(forward-char symbol-width)}.  The @code{symbol-width} itself is the
length of a @code{graph-blank} and can be found using the expression
@code{(length graph-blank)}.  The best place to bind the @code{symbol-width}
variable to the value of the width of graph column is in the varlist of the
@code{let} expression.

@need 1250
These considerations lead to the following function definition:

@smallexample
@group
(defun graph-body-print (numbers-list)
  "Print a bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values."

  (let ((height (apply 'max numbers-list))
        (symbol-width (length graph-blank))
        from-position)
@end group

@group
    (while numbers-list
      (setq from-position (point))
      (insert-rectangle
       (column-of-graph height (car numbers-list)))
      (goto-char from-position)
      (forward-char symbol-width)
@end group
@group
      ;; @r{Draw graph column by column.}
      (sit-for 0)
      (setq numbers-list (cdr numbers-list)))
@end group
@group
    ;; @r{Place point for X axis labels.}
    (forward-line height)
    (insert "\n")
))
@end group
@end smallexample

@noindent
The one unexpected expression in this function is the @w{@code{(sit-for 0)}}
expression in the @code{while} loop.  This expression makes the graph
printing operation more interesting to watch than it would be otherwise.
The expression causes Emacs to @dfn{sit} or do nothing for a zero length of
time and then redraw the screen.  Placed here, it causes Emacs to redraw the
screen column by column.  Without it, Emacs would not redraw the screen
until the function exits.

We can test @code{graph-body-print} with a short list of numbers.

@enumerate
@item
Install @code{graph-symbol}, @code{graph-blank}, @code{column-of-graph},
which are in
@iftex
@ref{Readying a Graph, , Readying a Graph},
@end iftex
@ifnottex
@ref{Columns of a graph},
@end ifnottex
and @code{graph-body-print}.

@need 800
@item
Copy the following expression:

@smallexample
(graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
@end smallexample

@item
Switch to the @file{*scratch*} buffer and place the cursor where you want
the graph to start.

@item
Type @kbd{M-:} (@code{eval-expression}).

@item
Yank the @code{graph-body-print} expression into the minibuffer with
@kbd{C-y} (@code{yank)}.

@item
Press @key{RET} to evaluate the @code{graph-body-print} expression.
@end enumerate

@need 800
Emacs will print a graph like this:

@smallexample
@group
                    *
                *   **
                *  ****
               *** ****
              ********* *
             ************
            *************
@end group
@end smallexample

@node recursive-graph-body-print
@section The @code{recursive-graph-body-print} Function
@findex recursive-graph-body-print

The @code{graph-body-print} function may also be written recursively.  The
recursive solution is divided into two parts: an outside wrapper that uses a
@code{let} expression to determine the values of several variables that need
only be found once, such as the maximum height of the graph, and an inside
function that is called recursively to print the graph.

@need 1250
The wrapper is uncomplicated:

@smallexample
@group
(defun recursive-graph-body-print (numbers-list)
  "Print a bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values."
  (let ((height (apply 'max numbers-list))
        (symbol-width (length graph-blank))
        from-position)
    (recursive-graph-body-print-internal
     numbers-list
     height
     symbol-width)))
@end group
@end smallexample

The recursive function is a little more difficult.  It has four parts: the
do-again-test, the printing code, the recursive call, and the
next-step-expression.  The do-again-test is a @code{when} expression that
determines whether the @code{numbers-list} contains any remaining elements;
if it does, the function prints one column of the graph using the printing
code and calls itself again.  The function calls itself again according to
the value produced by the next-step-expression which causes the call to act
on a shorter version of the @code{numbers-list}.

@smallexample
@group
(defun recursive-graph-body-print-internal
  (numbers-list height symbol-width)
  "Print a bar graph.
Used within recursive-graph-body-print function."
@end group

@group
  (when numbers-list
        (setq from-position (point))
        (insert-rectangle
         (column-of-graph height (car numbers-list)))
@end group
@group
        (goto-char from-position)
        (forward-char symbol-width)
        (sit-for 0)     ; @r{Draw graph column by column.}
        (recursive-graph-body-print-internal
         (cdr numbers-list) height symbol-width)))
@end group
@end smallexample

@need 1250
After installation, this expression can be tested; here is a sample:

@smallexample
(recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
@end smallexample

@need 800
Here is what @code{recursive-graph-body-print} produces:

@smallexample
@group
                *
               **   *
              ****  *
              **** ***
            * *********
            ************
            *************
@end group
@end smallexample

Either of these two functions, @code{graph-body-print} or
@code{recursive-graph-body-print}, create the body of a graph.

@node Afgedrukte assen
@section Need for Printed Axes

A graph needs printed axes, so you can orient yourself.  For a do-once
project, it may be reasonable to draw the axes by hand using Emacs's Picture
mode; but a graph drawing function may be used more than once.

For this reason, I have written enhancements to the basic
@code{print-graph-body} function that automatically print labels for the
horizontal and vertical axes.  Since the label printing functions do not
contain much new material, I have placed their description in an appendix.
@xref{Full Graph, , A Graph with Labeled Axes}.

@node Lijngrafiek oefening
@section Oefening

Write a line graph version of the graph printing functions.

@node Initialisatie van Emacs
@chapter Jouw @file{.emacs} bestand
@cindex @file{.emacs} file
@cindex Customizing your @file{.emacs} file
@cindex Initialization file

``You don't have to like Emacs to like it''---this seemingly paradoxical
statement is the secret of GNU Emacs.  The plain, out-of-the-box Emacs is a
generic tool.  Most people who use it customize it to suit themselves.

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

@menu
* Default configuratie::     Default configuratie
* Site-wide init::           Je kunt systeem-brede init bestanden schrijven.
* defcustom::                Emacs schrijft de code voor je.
* Een init bestand beginnen::  Hoe een @file{.emacs} init bestand te 
                                 schrijven.
* Tekst en auto-fill::       Automatisch regels afbreken.
* Mail aliasen::             Gebruik afkortingen voor e-mailadressen.
* Indent Tabs Mode::         Gebruik geen tabs met @TeX{}
* Key bindings::             Enkele persoonlijke key bindings maken.
* Keymaps::                  Meer over key binding.
* Bestanden laden::          Automatisch bestanden laden (en dus evalueren).
* Autoload::                 Functies beschikbaar maken.
* Eenvoudige uitbreiding::   Definieer een functie, bind het aan een toets.
* X11 kleuren::              Kleuren in X.
* Diverse::                  Diverse
* Mode line::                Hoe je mode line aan te passen
@end menu

@ifnottex
@node Default configuratie
@unnumberedsec Emacs's Default Configuration
@end ifnottex

There are those who appreciate Emacs's default configuration.  After all,
Emacs starts you in C mode when you edit a C file, starts you in Fortran
mode when you edit a Fortran file, and starts you in Fundamental mode when
you edit an unadorned file.  This all makes sense, if you do not know who is
going to use Emacs.  Who knows what a person hopes to do with an unadorned
file? Fundamental mode is the right default for such a file, just as C mode
is the right default for editing C code.  (Enough programming languages have
syntaxes that enable them to share or nearly share features, so C mode is
now provided by CC mode, the C Collection.)

But when you do know who is going to use Emacs---you, yourself---then it
makes sense to customize Emacs.

For example, I seldom want Fundamental mode when I edit an otherwise
undistinguished file; I want Text mode.  This is why I customize Emacs: so
it suits me.

You can customize and extend Emacs by writing or adapting a @file{~/.emacs}
file.  This is your personal initialization file; its contents, written in
Emacs Lisp, tell Emacs what to do.@footnote{You may also add @file{.el} to
@file{~/.emacs} and call it a @file{~/.emacs.el} file.  In the past, you
were forbidden to type the extra keystrokes that the name @file{~/.emacs.el}
requires, but now you may.  The new format is consistent with the Emacs Lisp
file naming conventions; the old format saves typing.}

A @file{~/.emacs} file contains Emacs Lisp code.  You can write this code
yourself; or you can use Emacs's @code{customize} feature to write the code
for you.  You can combine your own expressions and auto-written Customize
expressions in your @file{.emacs} file.

(I myself prefer to write my own expressions, except for those, particularly
fonts, that I find easier to manipulate using the @code{customize} command.
I combine the two methods.)

Most of this chapter is about writing expressions yourself.  It describes a
simple @file{.emacs} file; for more information, see @ref{Init File, , The
Init File, emacs, The GNU Emacs Manual}, and @ref{Init File, , The Init
File, elisp, The GNU Emacs Lisp Reference Manual}.

@node Site-wide init
@section Site-wide Initialization Files

@cindex @file{default.el} init file
@cindex @file{site-init.el} init file
@cindex @file{site-load.el} init file
In addition to your personal initialization file, Emacs automatically loads
various site-wide initialization files, if they exist.  These have the same
form as your @file{.emacs} file, but are loaded by everyone.

Two site-wide initialization files, @file{site-load.el} and
@file{site-init.el}, are loaded into Emacs and then dumped if a dumped
version of Emacs is created, as is most common.  (Dumped copies of Emacs
load more quickly.  However, once a file is loaded and dumped, a change to
it does not lead to a change in Emacs unless you load it yourself or re-dump
Emacs.  @xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp
Reference Manual}, and the @file{INSTALL} file.)

Three other site-wide initialization files are loaded automatically each
time you start Emacs, if they exist.  These are @file{site-start.el}, which
is loaded @emph{before} your @file{.emacs} file, and @file{default.el}, and
the terminal type file, which are both loaded @emph{after} your
@file{.emacs} file.

Settings and definitions in your @file{.emacs} file will overwrite
conflicting settings and definitions in a @file{site-start.el} file, if it
exists; but the settings and definitions in a @file{default.el} or terminal
type file will overwrite those in your @file{.emacs} file.  (You can prevent
interference from a terminal type file by setting @code{term-file-prefix} to
@code{nil}.  @xref{Simple Extension, , A Simple Extension}.)

@c Rewritten to avoid overfull hbox.
The @file{INSTALL} file that comes in the distribution contains descriptions
of the @file{site-init.el} and @file{site-load.el} files.

The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files
control loading.  These files are in the @file{lisp} directory of the Emacs
distribution and are worth perusing.

The @file{loaddefs.el} file contains a good many suggestions as to what to
put into your own @file{.emacs} file, or into a site-wide initialization
file.

@node defcustom
@section Variabelen specificeren met @code{defcustom}
@findex defcustom

You can specify variables using @code{defcustom} so that you and others can
then use Emacs's @code{customize} feature to set their values.  (You cannot
use @code{customize} to write function definitions; but you can write
@code{defuns} in your @file{.emacs} file.  Indeed, you can write any Lisp
expression in your @file{.emacs} file.)

The @code{customize} feature depends on the @code{defcustom} macro.
Although you can use @code{defvar} or @code{setq} for variables that users
set, the @code{defcustom} macro is designed for the job.

You can use your knowledge of @code{defvar} for writing the first three
arguments for @code{defcustom}.  The first argument to @code{defcustom} is
the name of the variable.  The second argument is the variable's initial
value, if any; and this value is set only if the value has not already been
set.  The third argument is the documentation.

The fourth and subsequent arguments to @code{defcustom} specify types and
options; these are not featured in @code{defvar}.  (These arguments are
optional.)

Each of these arguments consists of a keyword followed by a value.  Each
keyword starts with the colon character @samp{:}.

@need 1250
For example, the customizable user option variable @code{text-mode-hook}
looks like this:

@smallexample
@group
(defcustom text-mode-hook nil
  "Normal hook run when entering Text mode and many related modes."
  :type 'hook
  :options '(turn-on-auto-fill flyspell-mode)
  :group 'wp)
@end group
@end smallexample

@noindent
The name of the variable is @code{text-mode-hook}; it has no default value;
and its documentation string tells you what it does.

The @code{:type} keyword tells Emacs the kind of data to which
@code{text-mode-hook} should be set and how to display the value in a
Customization buffer.

The @code{:options} keyword specifies a suggested list of values for the
variable.  Usually, @code{:options} applies to a hook.  The list is only a
suggestion; it is not exclusive; a person who sets the variable may set it
to other values; the list shown following the @code{:options} keyword is
intended to offer convenient choices to a user.

Finally, the @code{:group} keyword tells the Emacs Customization command in
which group the variable is located.  This tells where to find it.

The @code{defcustom} macro recognizes more than a dozen keywords.  For more
information, see @ref{Customization, , Writing Customization Definitions,
elisp, The GNU Emacs Lisp Reference Manual}.

Consider @code{text-mode-hook} as an example.

There are two ways to customize this variable.  You can use the
customization command or write the appropriate expressions yourself.

@need 800
Using the customization command, you can type:

@smallexample
M-x customize
@end smallexample

@noindent
and find that the group for editing files of text is called ``Text''.  Enter
that group.  Text Mode Hook is the first member.  You can click on its
various options, such as @code{turn-on-auto-fill}, to set the values.  After
you click on the button to

@smallexample
Save for Future Sessions
@end smallexample

@noindent
Emacs will write an expression into your @file{.emacs} file.  It will look
like this:

@smallexample
@group
(custom-set-variables
  ;; custom-set-variables was added by Custom.
  ;; If you edit it by hand, you could mess it up, so be careful.
  ;; Your init file should contain only one such instance.
  ;; If there is more than one, they won't work right.
 '(text-mode-hook '(turn-on-auto-fill text-mode-hook-identify)))
@end group
@end smallexample

@noindent
(The @code{text-mode-hook-identify} function tells
@code{toggle-text-mode-auto-fill} which buffers are in Text mode.  It comes
on automatically.)

The @code{custom-set-variables} function works somewhat differently than a
@code{setq}.  While I have never learned the differences, I modify the
@code{custom-set-variables} expressions in my @file{.emacs} file by hand: I
make the changes in what appears to me to be a reasonable manner and have
not had any problems.  Others prefer to use the Customization command and
let Emacs do the work for them.

Another @code{custom-set-@dots{}} function is @code{custom-set-faces}.  This
function sets the various font faces.  Over time, I have set a considerable
number of faces.  Some of the time, I re-set them using @code{customize};
other times, I simply edit the @code{custom-set-faces} expression in my
@file{.emacs} file itself.

The second way to customize your @code{text-mode-hook} is to set it yourself
in your @file{.emacs} file using code that has nothing to do with the
@code{custom-set-@dots{}} functions.

@need 800
When you do this, and later use @code{customize}, you will see a message
that says

@smallexample
CHANGED outside Customize; operating on it here may be unreliable.
@end smallexample

@need 800
This message is only a warning.  If you click on the button to

@smallexample
Save for Future Sessions
@end smallexample

@noindent
Emacs will write a @code{custom-set-@dots{}} expression near the end of your
@file{.emacs} file that will be evaluated after your hand-written
expression.  It will, therefore, overrule your hand-written expression.  No
harm will be done.  When you do this, however, be careful to remember which
expression is active; if you forget, you may confuse yourself.

So long as you remember where the values are set, you will have no trouble.
In any event, the values are always set in your initialization file, which
is usually called @file{.emacs}.

I myself use @code{customize} for hardly anything.  Mostly, I write
expressions myself.

@findex defsubst
@findex defconst
Incidentally, to be more complete concerning defines: @code{defsubst}
defines an inline function.  The syntax is just like that of @code{defun}.
@code{defconst} defines a symbol as a constant.  The intent is that neither
programs nor users should ever change a value set by @code{defconst}.  (You
can change it; the value set is a variable; but please do not.)

@node Een init bestand beginnen
@section Starten met een @file{.emacs} bestand
@cindex @file{.emacs} file, beginning of

When you start Emacs, it loads your @file{.emacs} file unless you tell it
not to by specifying @samp{-q} on the command line.  (The @code{emacs -q}
command gives you a plain, out-of-the-box Emacs.)

A @file{.emacs} file contains Lisp expressions.  Often, these are no more
than expressions to set values; sometimes they are function definitions.

@xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs
Manual}, for a short description of initialization files.

This chapter goes over some of the same ground, but is a walk among extracts
from a complete, long-used @file{.emacs} file---my own.

The first part of the file consists of comments: reminders to myself.  By
now, of course, I remember these things, but when I started, I did not.

@need 1200
@smallexample
@group
;;;; Bob's .emacs file
; Robert J. Chassell
; 26 September 1985
@end group
@end smallexample

@noindent
Look at that date! I started this file a long time ago.  I have been adding
to it ever since.

@smallexample
@group
; Each section in this file is introduced by a
; line beginning with four semicolons; and each
; entry is introduced by a line beginning with
; three semicolons.
@end group
@end smallexample

@noindent
This describes the usual conventions for comments in Emacs Lisp.  Everything
on a line that follows a semicolon is a comment.  Two, three, and four
semicolons are used as subsection and section markers.  (@xref{Comments, ,,
elisp, The GNU Emacs Lisp Reference Manual}, for more about comments.)

@smallexample
@group
;;;; The Help Key
; Control-h is the help key;
; after typing control-h, type a letter to
; indicate the subject about which you want help.
; For an explanation of the help facility,
; type control-h two times in a row.
@end group
@end smallexample

@noindent
Just remember: type @kbd{C-h} two times for help.

@smallexample
@group
; To find out about any mode, type control-h m
; while in that mode.  For example, to find out
; about mail mode, enter mail mode and then type
; control-h m.
@end group
@end smallexample

@noindent
``Mode help'', as I call this, is very helpful.  Usually, it tells you all
you need to know.

Of course, you don't need to include comments like these in your
@file{.emacs} file.  I included them in mine because I kept forgetting about
Mode help or the conventions for comments---but I was able to remember to
look here to remind myself.

@node Tekst en auto-fill
@section Text and Auto Fill Mode

Now we come to the part that turns on Text mode and Auto Fill mode@footnote{
This section suggests settings that are more suitable for writers.  For
programmers, the default mode will be set to the corresponding prog-mode
automatically based on the type of the file.  And it's perfectly fine if you
want to keep the fundamental mode as the default mode.  }.

@smallexample
@group
;;; Text mode and Auto Fill mode
;; The next two lines put Emacs into Text mode
;; and Auto Fill mode, and are for writers who
;; want to start writing prose rather than code.
(setq-default major-mode 'text-mode)
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end group
@end smallexample

Here is the first part of this @file{.emacs} file that does something
besides remind a forgetful human!

The first of the two lines in parentheses tells Emacs to turn on Text mode
when you find a file, @emph{unless} that file should go into some other
mode, such as C mode.

@cindex Per-buffer, local variables list
@cindex Local variables list, per-buffer,
@cindex Automatic mode selection
@cindex Mode selection, automatic
When Emacs reads a file, it looks at the extension to the file name, if
any.  (The extension is the part that comes after a @samp{.}.)  If the file
ends with a @samp{.c} or @samp{.h} extension then Emacs turns on C mode.
Also, Emacs looks at first nonblank line of the file; if the line says
@w{@samp{-*- C -*-}}, Emacs turns on C mode.  Emacs possesses a list of
extensions and specifications that it uses automatically.  In addition,
Emacs looks near the last page for a per-buffer, local variables list, if
any.

@ifinfo
@xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU Emacs
Manual}.

@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
Manual}.
@end ifinfo
@iftex
See sections ``How Major Modes are Chosen'' and ``Local Variables in Files''
in @cite{The GNU Emacs Manual}.
@end iftex

Now, back to the @file{.emacs} file.

@need 800
Here is the line again; how does it work?

@cindex Text Mode turned on
@smallexample
(setq-default major-mode 'text-mode)
@end smallexample

@noindent
This line is a short, but complete Emacs Lisp expression.

We are already familiar with @code{setq}.  We use a similar macro
@code{setq-default} to set the following variable,
@code{major-mode}@footnote{ We use @code{setq-default} here because
@code{text-mode} is buffer-local.  If we use @code{setq}, it will only apply
to the current buffer, whereas using @code{setq-default} will also apply to
newly created buffers.  This is not recommended for programmers.  }, to the
subsequent value, which is @code{text-mode}.  The single-quote before
@code{text-mode} tells Emacs to deal directly with the @code{text-mode}
symbol, not with whatever it might stand for.  @xref{setq, , Setting the
Value of a Variable}, for a reminder of how @code{setq} works.  The main
point is that there is no difference between the procedure you use to set a
value in your @file{.emacs} file and the procedure you use anywhere else in
Emacs.

@need 800
Here is the next line:

@cindex Auto Fill mode turned on
@findex add-hook
@smallexample
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end smallexample

@noindent
In this line, the @code{add-hook} command adds @code{turn-on-auto-fill} to
the variable.

@code{turn-on-auto-fill} is the name of a program, that, you guessed it!,
turns on Auto Fill mode.

Every time Emacs turns on Text mode, Emacs runs the commands hooked onto
Text mode.  So every time Emacs turns on Text mode, Emacs also turns on Auto
Fill mode.

In brief, the first line causes Emacs to enter Text mode when you edit a
file, unless the file name extension, a first non-blank line, or local
variables to tell Emacs otherwise.

Text mode among other actions, sets the syntax table to work conveniently
for writers.  In Text mode, Emacs considers an apostrophe as part of a word
like a letter; but Emacs does not consider a period or a space as part of a
word.  Thus, @kbd{M-f} moves you over @samp{it's}.  On the other hand, in C
mode, @kbd{M-f} stops just after the @samp{t} of @samp{it's}.

The second line causes Emacs to turn on Auto Fill mode when it turns on Text
mode.  In Auto Fill mode, Emacs automatically breaks a line that is too wide
and brings the excessively wide part of the line down to the next line.
Emacs breaks lines between words, not within them.

When Auto Fill mode is turned off, lines continue to the right as you type
them.  Depending on how you set the value of @code{truncate-lines}, the
words you type either disappear off the right side of the screen, or else
are shown, in a rather ugly and unreadable manner, as a continuation line on
the screen.

@need 1250
In addition, in this part of my @file{.emacs} file, I tell the Emacs fill
commands to insert two spaces after a colon:

@smallexample
(setq colon-double-space t)
@end smallexample

@node Mail aliasen
@section Mail aliasen

Here is a @code{setq} that turns on mail aliases, along with more reminders.

@smallexample
@group
;;; Message mode
; To enter message mode, type 'C-x m'
; To enter RMAIL (for reading mail),
; type 'M-x rmail'
(setq mail-aliases t)
@end group
@end smallexample

@cindex Mail aliases
@noindent
This @code{setq} sets the value of the variable @code{mail-aliases} to
@code{t}.  Since @code{t} means true, the line says, in effect, ``Yes, use
mail aliases.''

Mail aliases are convenient short names for long email addresses or for
lists of email addresses.  The file where you keep your aliases is
@file{~/.mailrc}.  You write an alias like this:

@smallexample
alias geo george@@foobar.wiz.edu
@end smallexample

@noindent
When you write a message to George, address it to @samp{geo}; the mailer
will automatically expand @samp{geo} to the full address.

@node Indent Tabs Mode
@section Indent Tabs Mode
@cindex Tabs, preventing
@findex indent-tabs-mode

By default, Emacs inserts tabs in place of multiple spaces when it formats a
region.  (For example, you might indent many lines of text all at once with
the @code{indent-region} command.)  Tabs look fine on a terminal or with
ordinary printing, but they produce badly indented output when you use
@TeX{} or Texinfo since @TeX{} ignores tabs.

@need 1250
The following turns off Indent Tabs mode:

@smallexample
@group
;;; Prevent Extraneous Tabs
(setq-default indent-tabs-mode nil)
@end group
@end smallexample

Note that this line uses @code{setq-default} rather than the @code{setq}
that we have seen before; @code{setq-default} sets values only in buffers
that do not have their own local values for the variable.

@ifinfo
@xref{Just Spaces, , Tabs vs.@: Spaces, emacs, The GNU Emacs Manual}.

@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs
Manual}.
@end ifinfo
@iftex
See sections ``Tabs vs.@: Spaces'' and ``Local Variables in Files'' in
@cite{The GNU Emacs Manual}.
@end iftex

@need 1700
@node Key bindings
@section Some Key Bindings

Now for some personal key bindings:

@smallexample
@group
;;; Compare windows
(keymap-global-set "C-c w" 'compare-windows)
@end group
@end smallexample

@findex compare-windows
@code{compare-windows} is a nifty command that compares the text in your
current window with text in the next window.  It makes the comparison by
starting at point in each window, moving over text in each window as far as
they match.  I use this command all the time.

This also shows how to set a key globally, for all modes.

@cindex Setting a key globally
@cindex Keymap global set
@cindex Key setting globally
@findex keymap-global-set
The key setting command is @code{keymap-global-set}.  It is followed by the
key binding.  In a @file{.emacs} file, the keybinding is written as shown:
@code{C-c} stands for Control-C, which means to press the control key and
the @kbd{c} key at the same time.  The @code{w} means to press the @kbd{w}
key.  The key binding is surrounded by double quotation marks.  (If you were
binding a @key{META} key, rather than a @key{CTRL} key, you would write
@w{@code{M-c}} in your @file{.emacs} file.  @xref{Init Rebinding, ,
Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for
details.)

The command invoked by the keys is @code{compare-windows}.  Note that
@code{compare-windows} is preceded by a single-quote; otherwise, Emacs would
first try to evaluate the symbol to determine its value.

These three things, the double quotation marks, the backslash before the
@samp{C}, and the single-quote are necessary parts of key binding that I
tend to forget.  Fortunately, I have come to remember that I should look at
my existing @file{.emacs} file, and adapt what is there.

As for the key binding itself: @kbd{C-c w}.  This combines the prefix key,
@kbd{C-c}, with a single character, in this case, @kbd{w}.  This set of
keys, @kbd{C-c} followed by a single character, is strictly reserved for
individuals' own use.  (I call these @dfn{own} keys, since these are for my
own use.)  You should always be able to create such a key binding for your
own use without stomping on someone else's key binding.  If you ever write
an extension to Emacs, please avoid taking any of these keys for public
use.  Create a key like @kbd{C-c C-w} instead.  Otherwise, we will run out
of own keys.

@need 1250
Here is another key binding, with a comment:

@smallexample
@group
;;; Key binding for 'occur'
; I use occur a lot, so let's bind it to a key:
(keymap-global-set "C-c o" 'occur)
@end group
@end smallexample

@findex occur
The @code{occur} command shows all the lines in the current buffer that
contain a match for a regular expression.  When the region is active,
@code{occur} restricts matches to such region.  Otherwise it uses the entire
buffer.  Matching lines are shown in a buffer called @file{*Occur*}.  That
buffer serves as a menu to jump to occurrences.

@findex keymap-global-unset
@cindex Unbinding key
@cindex Key unbinding
@need 1250
Here is how to unbind a key, so it does not work:

@smallexample
@group
;;; Unbind 'C-x f'
(keymap-global-unset "C-x f")
@end group
@end smallexample

There is a reason for this unbinding: I found I inadvertently typed
@w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}.  Rather than find a
file, as I intended, I accidentally set the width for filled text, almost
always to a width I did not want.  Since I hardly ever reset my default
width, I simply unbound the key.

@findex list-buffers@r{, rebound}
@findex buffer-menu@r{, bound to key}
@need 1250
The following rebinds an existing key:

@smallexample
@group
;;; Rebind 'C-x C-b' for 'buffer-menu'
(keymap-global-set "C-x C-b" 'buffer-menu)
@end group
@end smallexample

By default, @kbd{C-x C-b} runs the @code{list-buffers} command.  This
command lists your buffers in @emph{another} window.  Since I almost always
want to do something in that window, I prefer the @code{buffer-menu}
command, which not only lists the buffers, but moves point into that window.

@subsection Legacy Global Key Binding Commands

@findex global-set-key
@cindex Global set key
Historically, keys are bound globally using a lower-level function,
@code{global-set-key}, which is now considered legacy.  While you are
encouraged to use @code{keymap-global-set}, you likely would encounter
@code{global-set-key} in various places.  The first example in this section
can be rewritten using @code{global-set-key} as:

@smallexample
@group
(global-set-key "\C-cw" 'compare-windows)
@end group
@end smallexample

It is very similar to @code{keymap-global-set}, with the keybinding
following a slightly different format.  Control-C is represented by
@code{\C-c}, instead of @code{C-c}.  There is no space between key strokes,
like @code{\C-c} and @code{w} in this example.  Despite the difference, in
documentation, this is still written as @w{@kbd{C-c w}} for readability.

@findex global-unset-key
Historically, keys are unbound globally using a lower-function,
@code{global-unset-key}, which is now considered legacy.  Its key binding
format follows that of @code{global-set-key}.  The key unbinding example in
this section can be rewritten as:

@smallexample
@group
;;; Unbind 'C-x f'
(global-unset-key "\C-xf")
@end group
@end smallexample

@node Keymaps
@section Keymaps
@cindex Keymaps
@cindex Rebinding keys

Emacs uses @dfn{keymaps} to record which keys call which commands.  When you
use @code{keymap-global-set} to set the key binding for a single command in
all parts of Emacs, you are specifying the key binding in
@code{current-global-map}.

Specific modes, such as C mode or Text mode, have their own keymaps; the
mode-specific keymaps override the global map that is shared by all buffers.

The @code{keymap-global-set} function binds, or rebinds, the global keymap.
For example, the following binds the key @kbd{C-x C-b} to the function
@code{buffer-menu}:

@smallexample
(keymap-global-set "C-x C-b" 'buffer-menu)
@end smallexample

Mode-specific keymaps are bound using the @code{keymap-set} function, which
takes a specific keymap as an argument, as well as the key and the command.
For example, the following expression binds the
@code{texinfo-insert-@@group} command to @kbd{C-c C-c g}:

@smallexample
@group
(keymap-set texinfo-mode-map "C-c C-c g" 'texinfo-insert-@@group)
@end group
@end smallexample

Historically, keymaps are bound using a lower-level function,
@code{define-key}, which is now considered legacy.  While you are encouraged
to use @code{keymap-set}, you likely would encounter @code{define-key} in
various places.  The above key binding can be rewritten using
@code{define-key} as:

@smallexample
@group
(define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group)
@end group
@end smallexample

@noindent
The @code{texinfo-insert-@@group} function itself is a little extension to
Texinfo mode that inserts @samp{@@group} into a Texinfo file.  I use this
command all the time and prefer to type the three strokes @kbd{C-c C-c g}
rather than the six strokes @kbd{@@ g r o u p}.  (@samp{@@group} and its
matching @samp{@@end group} are commands that keep all enclosed text
together on one page; many multi-line examples in this book are surrounded
by @samp{@@group @dots{} @@end group}.)

@need 1250
Here is the @code{texinfo-insert-@@group} function definition:

@smallexample
@group
(defun texinfo-insert-@@group ()
  "Insert the string @@group in a Texinfo buffer."
  (interactive)
  (beginning-of-line)
  (insert "@@group\n"))
@end group
@end smallexample

(Of course, I could have used Abbrev mode to save typing, rather than write
a function to insert a word; but I prefer key strokes consistent with other
Texinfo mode key bindings.)

You will see numerous @code{keymap-set} and @code{define-key} expressions in
@file{loaddefs.el} as well as in the various mode libraries, such as
@file{cc-mode.el} and @file{lisp-mode.el}.

@xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs
Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp Reference
Manual}, for more information about keymaps.

@node Bestanden laden
@section Bestanden laden
@cindex Loading files
@c findex load

Many people in the GNU Emacs community have written extensions to Emacs.  As
time goes by, these extensions are often included in new releases.  For
example, the Calendar and Diary packages are now part of the standard GNU
Emacs, as is Calc.

You can use a @code{load} command to evaluate a complete file and thereby
install all the functions and variables in the file into Emacs.  For
example:

@c (auto-compression-mode t)

@smallexample
(load "~/emacs/slowsplit")
@end smallexample

This evaluates, i.e., loads, the @file{slowsplit.el} file or if it exists,
the faster, byte compiled @file{slowsplit.elc} file from the @file{emacs}
sub-directory of your home directory.  The file contains the function
@code{split-window-quietly}, which John Robinson wrote in 1989.

The @code{split-window-quietly} function splits a window with the minimum of
redisplay.  I installed it in 1989 because it worked well with the slow 1200
baud terminals I was then using.  Nowadays, I only occasionally come across
such a slow connection, but I continue to use the function because I like
the way it leaves the bottom half of a buffer in the lower of the new
windows and the top half in the upper window.

@need 1250
To replace the key binding for the default @code{split-window-vertically},
you must bind the keys to @code{split-window-quietly}, like this:

@smallexample
@group
(keymap-global-set "C-x 2" 'split-window-quietly)
@end group
@end smallexample

@vindex load-path
If you load many extensions, as I do, then instead of specifying the exact
location of the extension file, as shown above, you can specify that
directory as part of Emacs's @code{load-path}.  Then, when Emacs loads a
file, it will search that directory as well as its default list of
directories.  (The default list is specified in @file{epaths.h} when Emacs
is built.)

@need 1250
The following command adds your @file{~/emacs} directory to the existing
load path:

@smallexample
@group
;;; Emacs Load Path
(setq load-path (cons "~/emacs" load-path))
@end group
@end smallexample

Incidentally, @code{load-library} is an interactive interface to the
@code{load} function.  The complete function looks like this:

@findex load-library
@smallexample
@group
(defun load-library (library)
  "Load the Emacs Lisp library named LIBRARY.
This is an interface to the function `load'.  LIBRARY is searched
for in `load-path', both with and without `load-suffixes' (as
well as `load-file-rep-suffixes').

See Info node `(emacs)Lisp Libraries' for more details.
See `load-file' for a different interface to `load'."
  (interactive
   (list (completing-read "Load library: "
                          (apply-partially 'locate-file-completion-table
                                           load-path
                                           (get-load-suffixes)))))
  (load library))
@end group
@end smallexample

The name of the function, @code{load-library}, comes from the use of
``library'' as a conventional synonym for ``file''.  The source for the
@code{load-library} command is in the @file{files.el} library.

Another interactive command that does a slightly different job is
@code{load-file}.  @xref{Lisp Libraries, , Libraries of Lisp Code for Emacs,
emacs, The GNU Emacs Manual}, for information on the distinction between
@code{load-library} and this command.

@node Autoload
@section Autoloading
@findex autoload

Instead of installing a function by loading the file that contains it, or by
evaluating the function definition, you can make the function available but
not actually install it until it is first called.  This is called
@dfn{autoloading}.

When you execute an autoloaded function, Emacs automatically evaluates the
file that contains the definition, and then calls the function.

Emacs starts quicker with autoloaded functions, since their libraries are
not loaded right away; but you need to wait a moment when you first use such
a function, while its containing file is evaluated.

Rarely used functions are frequently autoloaded.  The @file{loaddefs.el}
library contains thousands of autoloaded functions, from @code{5x5} to
@code{zone}.  Of course, you may come to use a rare function frequently.
When you do, you should load that function's file with a @code{load}
expression in your @file{.emacs} file.

In my @file{.emacs} file, I load 14 libraries that contain functions that
would otherwise be autoloaded.  (Actually, it would have been better to
include these files in my dumped Emacs, but I forgot.  @xref{Building Emacs,
, Building Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the
@file{INSTALL} file for more about dumping.)

You may also want to include autoloaded expressions in your @file{.emacs}
file.  @code{autoload} is a built-in function that takes up to five
arguments, the final three of which are optional.  The first argument is the
name of the function to be autoloaded; the second is the name of the file to
be loaded.  The third argument is documentation for the function, and the
fourth tells whether the function can be called interactively.  The fifth
argument tells what type of object---@code{autoload} can handle a keymap or
macro as well as a function (the default is a function).

@need 800
Here is a typical example:

@smallexample
@group
(autoload 'html-helper-mode
  "html-helper-mode" "Edit HTML documents" t)
@end group
@end smallexample

@noindent
(@code{html-helper-mode} is an older alternative to @code{html-mode}, which
is a standard part of the distribution.)

@noindent
This expression autoloads the @code{html-helper-mode} function.  It takes it
from the @file{html-helper-mode.el} file (or from the byte compiled version
@file{html-helper-mode.elc}, if that exists.)  The file must be located in a
directory specified by @code{load-path}.  The documentation says that this
is a mode to help you edit documents written in the HyperText Markup
Language.  You can call this mode interactively by typing @kbd{M-x
html-helper-mode}.  (You need to duplicate the function's regular
documentation in the autoload expression because the regular function is not
yet loaded, so its documentation is not available.)

@xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference Manual}, for
more information.

@node Eenvoudige uitbreiding
@section A Simple Extension: @code{line-to-top-of-window}
@findex line-to-top-of-window
@cindex Simple extension in @file{.emacs} file

Here is a simple extension to Emacs that moves the line that point is on to
the top of the window.  I use this all the time, to make text easier to
read.

You can put the following code into a separate file and then load it from
your @file{.emacs} file, or you can include it within your @file{.emacs}
file.

@need 1250
Here is the definition:

@smallexample
@group
;;; Line to top of window;
;;; replace three keystroke sequence  C-u 0 C-l
(defun line-to-top-of-window ()
  "Move the line that point is on to top of window."
  (interactive)
  (recenter 0))
@end group
@end smallexample

@need 1250
Now for the key binding.

Function keys as well as mouse button events and non-@sc{ascii} characters
are written within square brackets, without quotation marks.

I bind @code{line-to-top-of-window} to my @key{F6} function key like this:

@smallexample
(keymap-global-set "<f6>" 'line-to-top-of-window)
@end smallexample

For more information, see @ref{Init Rebinding, , Rebinding Keys in Your Init
File, emacs, The GNU Emacs Manual}.

@cindex Conditional 'twixt two versions of Emacs
@cindex Version of Emacs, choosing
@cindex Emacs version, choosing
If you run two versions of GNU Emacs, such as versions 27 and 28, and use
one @file{.emacs} file, you can select which code to evaluate with the
following conditional:

@smallexample
@group
(cond
 ((= 27 emacs-major-version)
  ;; evaluate version 27 code
  ( @dots{} ))
 ((= 28 emacs-major-version)
  ;; evaluate version 28 code
  ( @dots{} )))
@end group
@end smallexample

Recente versies laten bijvoorbeeld de cursor standaard knipperen. Ik haat
dat knipperen net zoals sommige andere features, daarom plaats ik het
volgende in mijn @file{.emacs} bestand@footnote{Wanneer ik instanties van
Emacs start die mijn @file{.emacs} of elk ander site-bestand niet laden zet
ik ook het knipperen uit:
 @smallexample
emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
 @exdent Of tegenwoordig met gebruik van een meer gesofisticeerde
verzameling opties emacs -Q -D
@end smallexample
}: 

@smallexample
@group
(when (>= emacs-major-version 21)
  (blink-cursor-mode 0)
  ;; Insert newline when you press 'C-n' (next-line)
  ;; at the end of the buffer
  (setq next-line-add-newlines t)
@end group
@group
  ;; Turn on image viewing
  (auto-image-file-mode t)
@end group
@group
  ;; Turn on menu bar (this bar has text)
  ;; (Use numeric argument to turn on)
  (menu-bar-mode 1)
@end group
@group
  ;; Turn off tool bar (this bar has icons)
  ;; (Use numeric argument to turn on)
  (tool-bar-mode nil)
@end group
@group
  ;; Turn off tooltip mode for tool bar
  ;; (This mode causes icon explanations to pop up)
  ;; (Use numeric argument to turn on)
  (tooltip-mode nil)
  ;; If tooltips turned on, make tips appear promptly
  (setq tooltip-delay 0.1)  ; default is 0.7 second
   )
@end group
@end smallexample

@node X11 kleuren
@section X11 kleuren

You can specify colors when you use Emacs with the MIT X Windowing system.

I dislike the default colors and specify my own.

@need 1250
Here are the expressions in my @file{.emacs} file that set values:

@smallexample
@group
;; Set cursor color
(set-cursor-color "white")

;; Set mouse color
(set-mouse-color "white")

;; Set foreground and background
(set-foreground-color "white")
(set-background-color "darkblue")
@end group

@group
;;; Set highlighting colors for isearch and drag
(set-face-foreground 'highlight "white")
(set-face-background 'highlight "blue")
@end group

@group
(set-face-foreground 'region "cyan")
(set-face-background 'region "blue")
@end group

@group
(set-face-foreground 'secondary-selection "skyblue")
(set-face-background 'secondary-selection "darkblue")
@end group

@group
;; Set calendar highlighting colors
(with-eval-after-load 'calendar
  (set-face-foreground 'diary   "skyblue")
  (set-face-background 'holiday "slate blue")
  (set-face-foreground 'holiday "white"))
@end group
@end smallexample

The various shades of blue soothe my eye and prevent me from seeing the
screen flicker.

Alternatively, I could have set my specifications in various X
initialization files.  For example, I could set the foreground, background,
cursor, and pointer (i.e., mouse) colors in my @file{~/.Xresources} file
like this:

@smallexample
@group
Emacs*foreground:   white
Emacs*background:   darkblue
Emacs*cursorColor:  white
Emacs*pointerColor: white
@end group
@end smallexample

In any event, since it is not part of Emacs, I set the root color of my X
window in my @file{~/.xinitrc} file, like this@footnote{I also run more
modern window managers, such as Enlightenment, Gnome, or KDE; in those
cases, I often specify an image rather than a plain color.}:

@smallexample
xsetroot -solid Navy -fg white &
@end smallexample

@need 1700
@node Diverse
@section Miscellaneous Settings for a @file{.emacs} File

@need 1250
Here are a few miscellaneous settings:
@sp 1

@itemize @minus
@item
Set the shape and color of the mouse cursor:

@smallexample
@group
; Cursor shapes are defined in
; '/usr/include/X11/cursorfont.h';
; for example, the 'target' cursor is number 128;
; the 'top_left_arrow' cursor is number 132.
@end group

@group
(let ((mpointer (x-get-resource "*mpointer"
                                "*emacs*mpointer")))
  ;; If you have not set your mouse pointer
  ;;     then set it, otherwise leave as is:
  (if (eq mpointer nil)
      (setq mpointer "132")) ; top_left_arrow
@end group
@group
  (setq x-pointer-shape (string-to-number mpointer))
  (set-mouse-color "white"))
@end group
@end smallexample

@item
Or you can set the values of a variety of features in an alist, like this:

@smallexample
@group
(setq-default
 default-frame-alist
 '((cursor-color . "white")
   (mouse-color . "white")
   (foreground-color . "white")
   (background-color . "DodgerBlue4")
   ;; (cursor-type . bar)
   (cursor-type . box)
@end group
@group
   (tool-bar-lines . 0)
   (menu-bar-lines . 1)
   (width . 80)
   (height . 58)
   (font .
         "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
   ))
@end group
@end smallexample

@item
Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL} into
@kbd{@key{CTRL}-h}.@* (Some older keyboards needed this, although I have not
seen the problem recently.)

@smallexample
@group
;; Translate 'C-h' to <DEL>.
; (key-translate "C-h" "C-?")

;; Translate <DEL> to 'C-h'.
(key-translate "C-?" "C-h")
@end group
@end smallexample

@item Turn off a blinking cursor!

@smallexample
@group
(if (fboundp 'blink-cursor-mode)
    (blink-cursor-mode -1))
@end group
@end smallexample

@noindent
or start GNU Emacs with the command @code{emacs -nbc}.

@need 1250
@item When using @command{grep}@*
@samp{-i}@w{ } Ignore case distinctions@* @samp{-n}@w{ } Prefix each line of
output with line number@* @samp{-H}@w{ } Print the filename for each
match.@* @samp{-e}@w{ } Protect patterns beginning with a hyphen character,
@samp{-}

@smallexample
(setq grep-command "grep -i -nH -e ")
@end smallexample

@item Find an existing buffer, even if it has a different name@*
This avoids problems with symbolic links.

@smallexample
(setq find-file-existing-other-name t)
@end smallexample

@item Set your language environment and default input method

@smallexample
@group
(set-language-environment "latin-1")
;; Remember you can enable or disable multilingual text input
;; with the @code{toggle-input-method'} (@kbd{C-\}) command
(setq default-input-method "latin-1-prefix")
@end group
@end smallexample

If you want to write with Chinese GB characters, set this instead:

@smallexample
@group
(set-language-environment "Chinese-GB")
(setq default-input-method "chinese-tonepy")
@end group
@end smallexample
@end itemize

@subsubheading Fixing Unpleasant Key Bindings
@cindex Key bindings, fixing
@cindex Bindings, key, fixing unpleasant

Some systems bind keys unpleasantly.  Sometimes, for example, the @key{CTRL}
key appears in an awkward spot rather than at the far left of the home row.

Usually, when people fix these sorts of key bindings, they do not change
their @file{~/.emacs} file.  Instead, they bind the proper keys on their
consoles with the @code{loadkeys} or @code{install-keymap} commands in their
boot script and then include @code{xmodmap} commands in their
@file{.xinitrc} or @file{.Xsession} file for X Windows.

@need 1250
@noindent
For a boot script:

@smallexample
@group
loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz
@exdent or
install-keymap emacs2
@end group
@end smallexample

@need 1250
@noindent
For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps Lock} key
is at the far left of the home row:

@smallexample
@group
# Bind the key labeled 'Caps Lock' to 'Control'
# (Such a broken user interface suggests that keyboard manufacturers
# think that computers are typewriters from 1885.)

xmodmap -e "clear Lock"
xmodmap -e "add Control = Caps_Lock"
@end group
@end smallexample

@need 1250
@noindent
In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} key
to a @key{META} key:

@smallexample
@group
# Some ill designed keyboards have a key labeled ALT and no Meta
xmodmap -e "keysym Alt_L = Meta_L Alt_L"
@end group
@end smallexample

@need 1700
@node Mode line
@section A Modified Mode Line
@vindex mode-line-format
@cindex Mode line format

Finally, a feature I really like: a modified mode line.

When I work over a network, I forget which machine I am using.  Also, I tend
to lose track of where I am, and which line point is on.

So I reset my mode line to look like this:

@smallexample
-:-- foo.texi   rattlesnake:/home/bob/  Line 1  (Texinfo Fill) Top
@end smallexample

I am visiting a file called @file{foo.texi}, on my machine
@file{rattlesnake} in my @file{/home/bob} buffer.  I am on line 1, in
Texinfo mode, and am at the top of the buffer.

@need 1200
My @file{.emacs} file has a section that looks like this:

@smallexample
@group
;; Set a Mode Line that tells me which machine, which directory,
;; and which line I am on, plus the other customary information.
(setq-default mode-line-format
 (quote
  (#("-" 0 1
     (help-echo
      "mouse-1: select window, mouse-2: delete others ..."))
   mode-line-mule-info
   mode-line-modified
   mode-line-frame-identification
   "    "
@end group
@group
   mode-line-buffer-identification
   "    "
   (:eval (substring
           (system-name) 0 (string-match "\\..+" (system-name))))
   ":"
   default-directory
   #(" " 0 1
     (help-echo
      "mouse-1: select window, mouse-2: delete others ..."))
   (line-number-mode " Line %l ")
   global-mode-string
@end group
@group
   #("   %[(" 0 6
     (help-echo
      "mouse-1: select window, mouse-2: delete others ..."))
   (:eval (format-time-string "%F"))
   mode-line-process
   minor-mode-alist
   #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
   ")%] "
   (-3 . "%P")
   ;;   "-%-"
   )))
@end group
@end smallexample

@noindent
Here, I redefine the default mode line.  Most of the parts are from the
original; but I make a few changes.  I set the @emph{default} mode line
format so as to permit various modes, such as Info, to override it.

Many elements in the list are self-explanatory: @code{mode-line-modified} is
a variable that tells whether the buffer has been modified, @code{mode-name}
tells the name of the mode, and so on.  However, the format looks
complicated because of two features we have not discussed.

@cindex Properties, in mode line example
The first string in the mode line is a dash or hyphen, @samp{-}.  In the old
days, it would have been specified simply as @code{"-"}.  But nowadays,
Emacs can add properties to a string, such as highlighting or, as in this
case, a help feature.  If you place your mouse cursor over the hyphen, some
help information appears (By default, you must wait seven-tenths of a second
before the information appears.  You can change that timing by changing the
value of @code{tooltip-delay}.)

@need 1000
The new string format has a special syntax:

@smallexample
#("-" 0 1 (help-echo "mouse-1: select window, ..."))
@end smallexample

@noindent
The @code{#(} begins a list.  The first element of the list is the string
itself, just one @samp{-}.  The second and third elements specify the range
over which the fourth element applies.  A range starts @emph{after} a
character, so a zero means the range starts just before the first character;
a 1 means that the range ends just after the first character.  The third
element is the property for the range.  It consists of a property list, a
property name, in this case, @samp{help-echo}, followed by a value, in this
case, a string.  The second, third, and fourth elements of this new string
format can be repeated.

@xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp
Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, elisp,
The GNU Emacs Lisp Reference Manual}, for more information.

@code{mode-line-buffer-identification} displays the current buffer name.  It
is a list beginning @code{(#("%12b" 0 4 @dots{}}.  The @code{#(} begins the
list.

The @samp{"%12b"} displays the current buffer name, using the
@code{buffer-name} function with which we are familiar; the @samp{12}
specifies the maximum number of characters that will be displayed.  When a
name has fewer characters, whitespace is added to fill out to this number.
(Buffer names can and often should be longer than 12 characters; this length
works well in a typical 80 column wide window.)

@code{:eval} says to evaluate the following form and use the result as a
string to display.  In this case, the expression displays the first
component of the full system name.  The end of the first component is a
@samp{.} (period), so I use the @code{string-match} function to tell me the
length of the first component.  The substring from the zeroth character to
that length is the name of the machine.

@need 1250
This is the expression:

@smallexample
@group
(:eval (substring
        (system-name) 0 (string-match "\\..+" (system-name))))
@end group
@end smallexample

@samp{%[} and @samp{%]} cause a pair of square brackets to appear for each
recursive editing level.  @samp{%n} says ``Narrow'' when narrowing is in
effect.  @samp{%P} tells you the percentage of the buffer that is above the
bottom of the window, or ``Top'', ``Bottom'', or ``All''.  (A lower case
@samp{p} tell you the percentage above the @emph{top} of the window.)
@samp{%-} inserts enough dashes to fill out the line.

Remember, you don't have to like Emacs to like it---your own Emacs can have
different colors, different commands, and different keys than a default
Emacs.

On the other hand, if you want to bring up a plain out-of-the-box Emacs,
with no customization, type:

@smallexample
emacs -q
@end smallexample

@noindent
This will start an Emacs that does @emph{not} load your @file{~/.emacs}
initialization file.  A plain, default Emacs.  Nothing more.

@node Debuggen.
@chapter Debuggen.
@cindex debugging

GNU Emacs has two debuggers, @code{debug} and @code{edebug}.  The first is
built into the internals of Emacs and is always with you; the second
requires that you instrument a function before you can use it.

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

@menu
* debug::                    Hoe de ingebouwde debugger te gebruiken.
* debug-on-entry::           Start debugen wanneer je een functie aanroept.
* debug-on-quit::            Start debuggen wanneer je quit met @kbd{C-g}.
* edebug::                   Hoe je Edebug gebruikt, een source level 
                               debugger.
* Debuggen oefeningen::      Debuggen oefeningen
@end menu

@node debug
@section @code{debug}
@findex debug

@c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.)
Suppose you have written a function definition that is intended to return
the sum of the numbers 1 through a given number.  (This is the
@code{triangle} function discussed earlier.  @xref{Decrementing Example, ,
Example with Decrementing Counter}, for a discussion.)

However, your function definition has a bug.  You have mistyped @samp{1=}
for @samp{1-}.  Here is the broken definition:

@findex triangle-bugged
@smallexample
@group
(defun triangle-bugged (number)
  "Return sum of numbers 1 through NUMBER inclusive."
  (let ((total 0))
    (while (> number 0)
      (setq total (+ total number))
      (setq number (1= number)))      ; @r{Error here.}
    total))
@end group
@end smallexample

If you are reading this in Info, you can evaluate this definition in the
normal fashion.  You will see @code{triangle-bugged} appear in the echo
area.

@need 1250
Now evaluate the @code{triangle-bugged} function with an argument of 4:

@smallexample
(triangle-bugged 4)
@end smallexample

@noindent
This will create and enter a @file{*Backtrace*} buffer that says:

@noindent
@smallexample
@group
---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-function 1=)
  (1= number)
  (setq number (1= number))
  (while (> number 0) (setq total (+ total number))
        (setq number (1= number)))
  (let ((total 0)) (while (> number 0) (setq total ...)
    (setq number ...)) total)
  triangle-bugged(4)
@end group
@group
  eval((triangle-bugged 4) nil)
  eval-expression((triangle-bugged 4) nil nil 127)
  funcall-interactively(eval-expression (triangle-bugged 4) nil nil 127)
  call-interactively(eval-expression nil nil)
  command-execute(eval-expression)
---------- Buffer: *Backtrace* ----------
@end group
@end smallexample

@noindent
(I have reformatted this example slightly; the debugger does not fold long
lines.  As usual, you can quit the debugger by typing @kbd{q} in the
@file{*Backtrace*} buffer.)

In practice, for a bug as simple as this, the Lisp error line will tell you
what you need to know to correct the definition.  The function @code{1=} is
void.

However, suppose you are not quite certain what is going on? You can read
the complete backtrace.

Emacs automatically starts the debugger that puts you in the
@file{*Backtrace*} buffer.  You can also start the debugger manually as
described below.

Read the @file{*Backtrace*} buffer from the bottom up; it tells you what
Emacs did that led to the error.  Emacs made an interactive call to @kbd{C-x
C-e} (@code{eval-last-sexp}), which led to the evaluation of the
@code{triangle-bugged} expression.  Each line above tells you what the Lisp
interpreter evaluated next.

@need 1250
The third line from the top of the buffer is

@smallexample
(setq number (1= number))
@end smallexample

@noindent
Emacs tried to evaluate this expression; in order to do so, it tried to
evaluate the inner expression shown on the second line from the top:

@smallexample
(1= number)
@end smallexample

@need 1250
@noindent
This is where the error occurred; as the top line says:

@smallexample
Debugger entered--Lisp error: (void-function 1=)
@end smallexample

@noindent
You can correct the mistake, re-evaluate the function definition, and then
run your test again.

@node debug-on-entry
@section @code{debug-on-entry}
@findex debug-on-entry

Emacs starts the debugger automatically when your function has an error.

Incidentally, you can start the debugger manually for all versions of Emacs;
the advantage is that the debugger runs even if you do not have a bug in
your code.  Sometimes your code will be free of bugs!

You can enter the debugger when you call the function by calling
@code{debug-on-entry}.

@need 1250
@noindent
Type:

@smallexample
M-x debug-on-entry @key{RET} triangle-bugged @key{RET}
@end smallexample

@need 1250
@noindent
Now, evaluate the following:

@smallexample
(triangle-bugged 5)
@end smallexample

@noindent
All versions of Emacs will create a @file{*Backtrace*} buffer and tell you
that it is beginning to evaluate the @code{triangle-bugged} function:

@smallexample
@group
---------- Buffer: *Backtrace* ----------
Debugger entered--entering a function:
* triangle-bugged(5)
  eval((triangle-bugged 5) nil)
@end group
@group
  eval-expression((triangle-bugged 5) nil nil 127)
  funcall-interactively(eval-expression (triangle-bugged 5) nil nil 127)
  call-interactively(eval-expression nil nil)
  command-execute(eval-expression)
---------- Buffer: *Backtrace* ----------
@end group
@end smallexample

In the @file{*Backtrace*} buffer, type @kbd{d}.  Emacs will evaluate the
first expression in @code{triangle-bugged}; the buffer will look like this:

@smallexample
@group
---------- Buffer: *Backtrace* ----------
Debugger entered--beginning evaluation of function call form:
* (let ((total 0)) (while (> number 0) (setq total ...)
        (setq number ...)) total)
* triangle-bugged(5)
  eval((triangle-bugged 5))
@end group
@group
  eval((triangle-bugged 5) nil)
  eval-expression((triangle-bugged 5) nil nil 127)
  funcall-interactively(eval-expression (triangle-bugged 5) nil nil 127)
  call-interactively(eval-expression nil nil)
  command-execute(eval-expression)
---------- Buffer: *Backtrace* ----------
@end group
@end smallexample

@noindent
Now, type @kbd{d} again, eight times, slowly.  Each time you type @kbd{d},
Emacs will evaluate another expression in the function definition.

@need 1750
Eventually, the buffer will look like this:

@smallexample
@group
---------- Buffer: *Backtrace* ----------
Debugger entered--beginning evaluation of function call form:
* (setq number (1= number))
* (while (> number 0) (setq total (+ total number))
        (setq number (1= number)))
@group
@end group
* (let ((total 0)) (while (> number 0) (setq total ...)
        (setq number ...)) total)
* triangle-bugged(5)
  eval((triangle-bugged 5) nil)
@group
@end group
  eval-expression((triangle-bugged 5) nil nil 127)
  funcall-interactively(eval-expression (triangle-bugged 5) nil nil 127)
  call-interactively(eval-expression nil nil)
  command-execute(eval-expression)
---------- Buffer: *Backtrace* ----------
@end group
@end smallexample

@need 1500
@noindent
Finally, after you type @kbd{d} two more times, Emacs will reach the error,
and the top two lines of the @file{*Backtrace*} buffer will look like this:

@smallexample
@group
---------- Buffer: *Backtrace* ----------
Debugger entered--Lisp error: (void-function 1=)
* (1= number)
@dots{}
---------- Buffer: *Backtrace* ----------
@end group
@end smallexample

By typing @kbd{d}, you were able to step through the function.

You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this quits
the trace, but does not cancel @code{debug-on-entry}.

@findex cancel-debug-on-entry
To cancel the effect of @code{debug-on-entry}, call
@code{cancel-debug-on-entry} and the name of the function, like this:

@smallexample
M-x cancel-debug-on-entry @key{RET} triangle-bugged @key{RET}
@end smallexample

@noindent
(If you are reading this in Info, cancel @code{debug-on-entry} now.)

@node debug-on-quit
@section @code{debug-on-quit} and @code{(debug)}

In addition to setting @code{debug-on-error} or calling
@code{debug-on-entry}, there are two other ways to start @code{debug}.

@findex debug-on-quit
You can start @code{debug} whenever you type @kbd{C-g}
(@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to
@code{t}.  This is useful for debugging infinite loops.

@need 1500
@cindex @code{(debug)} in code
Or, you can insert a line that says @code{(debug)} into your code where you
want the debugger to start, like this:

@smallexample
@group
(defun triangle-bugged (number)
  "Return sum of numbers 1 through NUMBER inclusive."
  (let ((total 0))
    (while (> number 0)
      (setq total (+ total number))
      (debug)                         ; @r{Start debugger.}
      (setq number (1= number)))      ; @r{Error here.}
    total))
@end group
@end smallexample

The @code{debug} function is described in detail in @ref{Debugger, , The
Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}.

@node edebug
@section The @code{edebug} Source Level Debugger
@cindex Source level debugger
@findex edebug

Edebug is a source level debugger.  Edebug normally displays the source of
the code you are debugging, with an arrow at the left that shows which line
you are currently executing.

You can walk through the execution of a function, line by line, or run
quickly until reaching a @dfn{breakpoint} where execution stops.

Edebug is described in @ref{Edebug, , , elisp, The GNU Emacs Lisp Reference
Manual}.

@need 1250
Here is a bugged function definition for @code{triangle-recursively}.
@xref{Recursive triangle function, , Recursion in place of a counter}, for a
review of it.

@smallexample
@group
(defun triangle-recursively-bugged (number)
  "Return sum of numbers 1 through NUMBER inclusive.
Uses recursion."
  (if (= number 1)
      1
    (+ number
       (triangle-recursively-bugged
        (1= number)))))               ; @r{Error here.}
@end group
@end smallexample

@noindent
Normally, you would install this definition by positioning your cursor after
the function's closing parenthesis and typing @kbd{C-x C-e}
(@code{eval-last-sexp}) or else by positioning your cursor within the
definition and typing @kbd{C-M-x} (@code{eval-defun}).  (By default, the
@code{eval-defun} command works only in Emacs Lisp mode or in Lisp
Interaction mode.)

@need 1500
However, to prepare this function definition for Edebug, you must first
@dfn{instrument} the code using a different command.  You can do this by
positioning your cursor within or just after the definition and typing

@smallexample
M-x edebug-defun @key{RET}
@end smallexample

@noindent
This will cause Emacs to load Edebug automatically if it is not already
loaded, and properly instrument the function.

After instrumenting the function, place your cursor after the following
expression and type @kbd{C-x C-e} (@code{eval-last-sexp}):

@smallexample
(triangle-recursively-bugged 3)
@end smallexample

@noindent
You will be jumped back to the source for @code{triangle-recursively-bugged}
and the cursor positioned at the beginning of the @code{if} line of the
function.  Also, you will see an arrowhead at the left hand side of that
line.  The arrowhead marks the line where the function is executing.  (In
the following examples, we show the arrowhead with @samp{=>}; in a windowing
system, you may see the arrowhead as a solid triangle in the window fringe.)

@smallexample
=>@point{}(if (= number 1)
@end smallexample

@noindent
@iftex
In the example, the location of point is displayed with a star,
@samp{@point{}} (in Info, it is displayed as @samp{-!-}).
@end iftex
@ifnottex
In the example, the location of point is displayed as @samp{@point{}} (in a
printed book, it is displayed with a five pointed star).
@end ifnottex

If you now press @key{SPC}, point will move to the next expression to be
executed; the line will look like this:

@smallexample
=>(if @point{}(= number 1)
@end smallexample

@noindent
As you continue to press @key{SPC}, point will move from expression to
expression.  At the same time, whenever an expression returns a value, that
value will be displayed in the echo area.  For example, after you move point
past @code{number}, you will see the following:

@smallexample
Result: 3 (#o3, #x3, ?\C-c)
@end smallexample

@noindent
This means the value of @code{number} is 3, which is octal three,
hexadecimal three, and @sc{ascii} Control-C (the third letter of the
alphabet, in case you need to know this information).

You can continue moving through the code until you reach the line with the
error.  Before evaluation, that line looks like this:

@smallexample
=>        @point{}(1= number)))))               ; @r{Error here.}
@end smallexample

@need 1250
@noindent
When you press @key{SPC} once again, you will produce an error message that
says:

@smallexample
Symbol's function definition is void:@: 1=
@end smallexample

@noindent
This is the bug.

Press @kbd{q} to quit Edebug.

To remove instrumentation from a function definition, simply re-evaluate it
with a command that does not instrument it.  For example, you could place
your cursor after the definition's closing parenthesis and type @kbd{C-x
C-e}.

Edebug does a great deal more than walk with you through a function.  You
can set it so it races through on its own, stopping only at an error or at
specified stopping points; you can cause it to display the changing values
of various expressions; you can find out how many times a function is
called, and more.

Edebug is described in @ref{Edebug, , , elisp, The GNU Emacs Lisp Reference
Manual}.

@need 1500
@node Debuggen oefeningen
@section Debuggen oefeningen

@itemize @bullet
@item
Install the @code{@value{COUNT-WORDS}} function and then cause it to enter
the built-in debugger when you call it.  Run the command on a region
containing two words.  You will need to press @kbd{d} a remarkable number of
times.  On your system, is a hook called after the command finishes? (For
information on hooks, see @ref{Command Overview, , Command Loop Overview,
elisp, The GNU Emacs Lisp Reference Manual}.)

@item
Copy @code{@value{COUNT-WORDS}} into the @file{*scratch*} buffer, instrument
the function for Edebug, and walk through its execution.  The function does
not need to have a bug, although you can introduce one if you wish.  If the
function lacks a bug, the walk-through completes without problems.

@item
While running Edebug, type @kbd{?} to see a list of all the Edebug
commands.  (The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.,
@kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix for
commands made outside of the Edebug debugging buffer.)

@item
In the Edebug debugging buffer, use the @kbd{p} (@code{edebug-bounce-point})
command to see where in the region the @code{@value{COUNT-WORDS}} is
working.

@item
Move point to some spot further down the function and then type the @kbd{h}
(@code{edebug-goto-here}) command to jump to that location.

@item
Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to walk
through the function on its own; use an upper case @kbd{T} for
@code{edebug-Trace-fast-mode}.

@item
Set a breakpoint, then run Edebug in Trace mode until it reaches the
stopping point.
@end itemize

@node Conclusie
@chapter Conclusie

We have now reached the end of this Introduction.  You have now learned
enough about programming in Emacs Lisp to set values, to write simple
@file{.emacs} files for yourself and your friends, and write simple
customizations and extensions to Emacs.

This is a place to stop.  Or, if you wish, you can now go onward, and teach
yourself.

You have learned some of the basic nuts and bolts of programming.  But only
some.  There are a great many more brackets and hinges that are easy to use
that we have not touched.

A path you can follow right now lies among the sources to GNU Emacs and in
@ifnotinfo
@cite{The GNU Emacs Lisp Reference Manual}.
@end ifnotinfo
@ifinfo
@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU Emacs Lisp
Reference Manual}.
@end ifinfo

The Emacs Lisp sources are an adventure.  When you read the sources and come
across a function or expression that is unfamiliar, you need to figure out
or find out what it does.

Go to the Reference Manual.  It is a thorough, complete, and fairly
easy-to-read description of Emacs Lisp.  It is written not only for experts,
but for people who know what you know.  (The @cite{Reference Manual} comes
with the standard GNU Emacs distribution.  Like this introduction, it comes
as a Texinfo source file, so you can read it on your computer and as a
typeset, printed book.)

Go to the other built-in help that is part of GNU Emacs: the built-in
documentation for all functions and variables, and
@code{xref-find-definitions}, the program that takes you to sources.

Here is an example of how I explore the sources.  Because of its name,
@file{simple.el} is the file I looked at first, a long time ago.  As it
happens some of the functions in @file{simple.el} are complicated, or at
least look complicated at first sight.  The @code{open-line} function, for
example, looks complicated.

You may want to walk through this function slowly, as we did with the
@code{forward-sentence} function.  (@xref{forward-sentence, The
@code{forward-sentence} function}.)  Or you may want to skip that function
and look at another, such as @code{split-line}.  You don't need to read all
the functions.  According to @code{count-words-in-defun}, the
@code{split-line} function contains 102 words and symbols.

Even though it is short, @code{split-line} contains expressions we have not
studied: @code{skip-chars-forward}, @code{indent-to}, @code{current-column}
and @code{insert-and-inherit}.

Consider the @code{skip-chars-forward} function.  In GNU Emacs, you can find
out more about @code{skip-chars-forward} by typing @kbd{C-h f}
(@code{describe-function}) and the name of the function.  This gives you the
function documentation.

You may be able to guess what is done by a well named function such as
@code{indent-to}; or you can look it up, too.  Incidentally, the
@code{describe-function} function itself is in @file{help.el}; it is one of
those long, but decipherable functions.  You can look up
@code{describe-function} using the @kbd{C-h f} command!

In this instance, since the code is Lisp, the @file{*Help*} buffer contains
the name of the library containing the function's source.  You can put point
over the name of the library and press the @key{RET} key, which in this
situation is bound to @code{help-follow}, and be taken directly to the
source, in the same way as @kbd{M-.} (@code{xref-find-definitions}).

The definition for @code{describe-function} illustrates how to customize the
@code{interactive} expression without using the standard character codes;
and it shows how to create a temporary buffer.

(The @code{indent-to} function is written in C rather than Emacs Lisp; it is
a built-in function.  @code{help-follow} takes you to its source as does
@code{xref-find-definitions}, when properly set up.)

You can look at a function's source using @code{xref-find-definitions},
which is bound to @kbd{M-.} Finally, you can find out what the Reference
Manual has to say by visiting the manual in Info, and typing @kbd{i}
(@code{Info-index}) and the name of the function, or by looking up the
function in the index to a printed copy of the manual.

Similarly, you can find out what is meant by @code{insert-and-inherit}.

Other interesting source files include @file{paragraphs.el},
@file{loaddefs.el}, and @file{loadup.el}.  The @file{paragraphs.el} file
includes short, easily understood functions as well as longer ones.  The
@file{loaddefs.el} file contains the many standard autoloads and many
keymaps.  I have never looked at it all; only at parts.  @file{loadup.el} is
the file that loads the standard parts of Emacs; it tells you a great deal
about how Emacs is built.  (@xref{Building Emacs, , Building Emacs, elisp,
The GNU Emacs Lisp Reference Manual}, for more about building.)

As I said, you have learned some nuts and bolts; however, and very
importantly, we have hardly touched major aspects of programming; I have
said nothing about how to sort information, except to use the predefined
@code{sort} function; I have said nothing about how to store information,
except to use variables and lists; I have said nothing about how to write
programs that write programs.  These are topics for another, and different
kind of book, a different kind of learning.

What you have done is learn enough for much practical work with GNU Emacs.
What you have done is get started.  This is the end of a beginning.

@c ================ Appendix ================

@node de-de
@appendix The @code{the-the} Function
@findex de-de
@cindex Duplicated words function
@cindex Words, duplicated

Sometimes when you you write text, you duplicate words---as with ``you you''
near the beginning of this sentence.  I find that most frequently, I
duplicate ``the''; hence, I call the function for detecting duplicated
words, @code{the-the}.

@need 1250
As a first step, you could use the following regular expression to search
for duplicates:

@smallexample
\\(\\w+[ \t\n]+\\)\\1
@end smallexample

@noindent
This regexp matches one or more word-constituent characters followed by one
or more spaces, tabs, or newlines.  However, it does not detect duplicated
words on different lines, since the ending of the first word, the end of the
line, is different from the ending of the second word, a space.  (For more
information about regular expressions, see @ref{Regexp Search, , Regular
Expression Searches}, as well as @ref{Regexps, , Syntax of Regular
Expressions, emacs, The GNU Emacs Manual}, and @ref{Regular Expressions, ,
Regular Expressions, elisp, The GNU Emacs Lisp Reference Manual}.)

You might try searching just for duplicated word-constituent characters but
that does not work since the pattern detects doubles such as the two
occurrences of ``th'' in ``with the''.

Another possible regexp searches for word-constituent characters followed by
non-word-constituent characters, reduplicated.  Here, @w{@samp{\\w+}}
matches one or more word-constituent characters and @w{@samp{\\W*}} matches
zero or more non-word-constituent characters.

@smallexample
\\(\\(\\w+\\)\\W*\\)\\1
@end smallexample

@noindent
Again, not useful.

Here is the pattern that I use.  It is not perfect, but good enough.
@w{@samp{\\b}} matches the empty string, provided it is at the beginning or
end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of any
characters that are @emph{not} an @@-sign, space, newline, or tab.

@smallexample
\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b
@end smallexample

One can write more complicated expressions, but I found that this expression
is good enough, so I use it.

Here is the @code{the-the} function, as I include it in my @file{.emacs}
file, along with a handy global key binding:

@smallexample
@group
(defun the-the ()
  "Search forward for for a duplicated word."
  (interactive)
  (message "Searching for for duplicated words ...")
  (push-mark)
@end group
@group
  ;; This regexp is not perfect
  ;; but is fairly good over all:
  (if (re-search-forward
       "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move)
      (message "Found duplicated word.")
    (message "End of buffer")))
@end group

@group
;; Bind 'the-the' to  C-c \
(keymap-global-set "C-c \\" 'the-the)
@end group
@end smallexample

@sp 1
Here is test text:

@smallexample
@group
one two two three four five
five six seven
@end group
@end smallexample

You can substitute the other regular expressions shown above in the function
definition and try each of them on this list.

@node Killring
@appendix De killring hanteren
@cindex Kill ring handling
@cindex Handling the kill ring
@cindex Ring, making a list like a

The kill ring is a list that is transformed into a ring by the workings of
the @code{current-kill} function.  The @code{yank} and @code{yank-pop}
commands use the @code{current-kill} function.

This appendix describes the @code{current-kill} function as well as both the
@code{yank} and the @code{yank-pop} commands, but first, consider the
workings of the kill ring.

@menu
* Wat de killring doet::     Wat de killring doet
* current-kill::             current-kill
* yank::                     Plak een kopie van een afgeknipt element
* yank-pop::                 Element waar naar verwezen wordt invoegen.
* ring bestand::             ring bestand
@end menu

@ifnottex
@node Wat de killring doet
@unnumberedsec Wat de killring doet
@end ifnottex

@need 1250
The kill ring has a default maximum length of sixty items; this number is
too large for an explanation.  Instead, set it to four.  Please evaluate the
following:

@smallexample
@group
(setq old-kill-ring-max kill-ring-max)
(setq kill-ring-max 4)
@end group
@end smallexample

@noindent
Then, please copy each line of the following indented example into the kill
ring.  You may kill each line with @kbd{C-k} or mark it and copy it with
@kbd{M-w}.

@noindent
(In a read-only buffer, such as the @file{*info*} buffer, the kill command,
@kbd{C-k} (@code{kill-line}), will not remove the text, merely copy it to
the kill ring.  However, your machine may beep at you.  Alternatively, for
silence, you may copy the region of each line with the @kbd{M-w}
(@code{kill-ring-save}) command.  You must mark each line for this command
to succeed, but it does not matter at which end you put point or mark.)

@need 1250
@noindent
Please invoke the calls in order, so that five elements attempt to fill the
kill ring:

@smallexample
@group
first some text
second piece of text
third line
fourth line of text
fifth bit of text
@end group
@end smallexample

@need 1250
@noindent
Then find the value of @code{kill-ring} by evaluating

@smallexample
kill-ring
@end smallexample

@need 800
@noindent
It is:

@smallexample
@group
("fifth bit of text" "fourth line of text"
"third line" "second piece of text")
@end group
@end smallexample

@noindent
The first element, @samp{first some text}, was dropped.

@need 1250
To return to the old value for the length of the kill ring, evaluate:

@smallexample
(setq kill-ring-max old-kill-ring-max)
@end smallexample

@node current-kill
@appendixsec De @code{current-kill} functie
@findex current-kill

The @code{current-kill} function changes the element in the kill ring to
which @code{kill-ring-yank-pointer} points.  (Also, the @code{kill-new}
function sets @code{kill-ring-yank-pointer} to point to the latest element
of the kill ring.  The @code{kill-new} function is used directly or
indirectly by @code{kill-append}, @code{copy-region-as-kill},
@code{kill-ring-save}, @code{kill-line}, and @code{kill-region}.)

@menu
* Code voor current-kill::   Code voor current-kill
* current-kill begrijpen::   current-kill begrijpen
@end menu

@ifnottex
@node Code voor current-kill
@unnumberedsubsec The code for @code{current-kill}
@end ifnottex


@need 1500
The @code{current-kill} function is used by @code{yank} and by
@code{yank-pop}.  Here is the code for @code{current-kill}:

@smallexample
@group
(defun current-kill (n &optional do-not-move)
  "Rotate the yanking point by N places, and then return that kill.
If N is zero and `interprogram-paste-function' is set to a
function that returns a string or a list of strings, and if that
function doesn't return nil, then that string (or list) is added
to the front of the kill ring and the string (or first string in
the list) is returned as the latest kill.
@end group
@group
If N is not zero, and if `yank-pop-change-selection' is
non-nil, use `interprogram-cut-function' to transfer the
kill at the new yank point into the window system selection.
@end group
@group
If optional arg DO-NOT-MOVE is non-nil, then don't actually
move the yanking point; just return the Nth kill forward."

  (let ((interprogram-paste (and (= n 0)
                                 interprogram-paste-function
                                 (funcall interprogram-paste-function))))
@end group
@group
    (if interprogram-paste
        (progn
          ;; Disable the interprogram cut function when we add the new
          ;; text to the kill ring, so Emacs doesn't try to own the
          ;; selection, with identical text.
          (let ((interprogram-cut-function nil))
            (if (listp interprogram-paste)
              (mapc 'kill-new (nreverse interprogram-paste))
              (kill-new interprogram-paste)))
          (car kill-ring))
@end group
@group
      (or kill-ring (error "Kill ring is empty"))
      (let ((ARGth-kill-element
             (nthcdr (mod (- n (length kill-ring-yank-pointer))
                          (length kill-ring))
                     kill-ring)))
        (unless do-not-move
          (setq kill-ring-yank-pointer ARGth-kill-element)
          (when (and yank-pop-change-selection
                     (> n 0)
                     interprogram-cut-function)
            (funcall interprogram-cut-function (car ARGth-kill-element))))
        (car ARGth-kill-element)))))
@end group
@end smallexample

Remember also that the @code{kill-new} function sets
@code{kill-ring-yank-pointer} to the latest element of the kill ring, which
means that all the functions that call it set the value indirectly:
@code{kill-append}, @code{copy-region-as-kill}, @code{kill-ring-save},
@code{kill-line}, and @code{kill-region}.

@need 1500
Here is the line in @code{kill-new}, which is explained in @ref{kill-new
function, , The @code{kill-new} function}.

@smallexample
(setq kill-ring-yank-pointer kill-ring)
@end smallexample

@ifnottex
@node current-kill begrijpen
@unnumberedsubsec Overzicht @code{current-kill}
@end ifnottex

The @code{current-kill} function looks complex, but as usual, it can be
understood by taking it apart piece by piece.  First look at it in skeletal
form:

@smallexample
@group
(defun current-kill (n &optional do-not-move)
  "Rotate the yanking point by N places, and then return that kill."
  (let @var{varlist}
    @var{body}@dots{})
@end group
@end smallexample

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

@menu
* Body van current-kill::    Body van current-kill
* Uitwijding over fout::     Hoe mensen te misleiden, maar niet computers.
* Het element vaststellen::  Het element vaststellen
@end menu

@ifnottex
@node Body van current-kill
@unnumberedsubsubsec The Body of @code{current-kill}
@end ifnottex

The body of the function definition is a @code{let} expression, which itself
has a body as well as a @var{varlist}.

The @code{let} expression declares a variable that will be only usable
within the bounds of this function.  This variable is called
@code{interprogram-paste} and is for copying to another program.  It is not
for copying within this instance of GNU Emacs.  Most window systems provide
a facility for interprogram pasting.  Sadly, that facility usually provides
only for the last element.  Most windowing systems have not adopted a ring
of many possibilities, even though Emacs has provided it for decades.

The @code{if} expression has two parts, one if there exists
@code{interprogram-paste} and one if not.

@need 2000
Laat ons het else-gedeelte van de @code{current-kill} functie
beschouwen. (Het then-gedeelte gebruikt de @code{kill-new} functie, die we
al eerder hebben beschreven. @xref{kill-new functie, , De @code{kill-new}
functie}.)

@smallexample
@group
(or kill-ring (error "Kill ring is empty"))
(let ((ARGth-kill-element
       (nthcdr (mod (- n (length kill-ring-yank-pointer))
                    (length kill-ring))
               kill-ring)))
  (or do-not-move
      (setq kill-ring-yank-pointer ARGth-kill-element))
  (car ARGth-kill-element))
@end group
@end smallexample

@noindent
The code first checks whether the kill ring has content; otherwise it
signals an error.

@need 1000
Note that the @code{or} expression is very similar to testing length with an
@code{if}:

@findex zerop
@findex error
@smallexample
@group
(if (zerop (length kill-ring))          ; @r{if-part}
    (error "Kill ring is empty"))       ; @r{then-part}
  ;; No else-part
@end group
@end smallexample

@noindent
If there is not anything in the kill ring, its length must be zero and an
error message sent to the user: @samp{Kill ring is empty}.  The
@code{current-kill} function uses an @code{or} expression which is simpler.
But an @code{if} expression reminds us what goes on.

This @code{if} expression uses the function @code{zerop} which returns true
if the value it is testing is zero.  When @code{zerop} tests true, the
then-part of the @code{if} is evaluated.  The then-part is a list starting
with the function @code{error}, which is a function that is similar to the
@code{message} function (@pxref{message, , The @code{message} Function}) in
that it prints a one-line message in the echo area.  However, in addition to
printing a message, @code{error} also stops evaluation of the function
within which it is embedded.  This means that the rest of the function will
not be evaluated if the length of the kill ring is zero.

Then the @code{current-kill} function selects the element to return.  The
selection depends on the number of places that @code{current-kill} rotates
and on where @code{kill-ring-yank-pointer} points.

Next, either the optional @code{do-not-move} argument is true or the current
value of @code{kill-ring-yank-pointer} is set to point to the list.
Finally, another expression returns the first element of the list even if
the @code{do-not-move} argument is true.

@ifnottex
@node Uitwijding over fout
@unnumberedsubsubsec Digression about the word ``error''
@end ifnottex

In my opinion, it is slightly misleading, at least to humans, to use the
term ``error'' as the name of the @code{error} function.  A better term
would be ``cancel''.  Strictly speaking, of course, you cannot point to,
much less rotate a pointer to a list that has no length, so from the point
of view of the computer, the word ``error'' is correct.  But a human expects
to attempt this sort of thing, if only to find out whether the kill ring is
full or empty.  This is an act of exploration.

From the human point of view, the act of exploration and discovery is not
necessarily an error, and therefore should not be labeled as one, even in
the bowels of a computer.  As it is, the code in Emacs implies that a human
who is acting virtuously, by exploring his or her environment, is making an
error.  This is bad.  Even though the computer takes the same steps as it
does when there is an error, a term such as ``cancel'' would have a clearer
connotation.

@ifnottex
@node Het element vaststellen
@unnumberedsubsubsec Het element vaststellen
@end ifnottex

Among other actions, the else-part of the @code{if} expression sets the
value of @code{kill-ring-yank-pointer} to @code{ARGth-kill-element} when the
kill ring has something in it and the value of @code{do-not-move} is
@code{nil}.

@need 800
De code ziet er zo uit:

@smallexample
@group
(nthcdr (mod (- n (length kill-ring-yank-pointer))
             (length kill-ring))
        kill-ring)))
@end group
@end smallexample

This needs some examination.  Unless it is not supposed to move the pointer,
the @code{current-kill} function changes where @code{kill-ring-yank-pointer}
points.  That is what the @w{@code{(setq kill-ring-yank-pointer
ARGth-kill-element))}} expression does.  Also, clearly,
@code{ARGth-kill-element} is being set to be equal to some @sc{cdr} of the
kill ring, using the @code{nthcdr} function that is described in an earlier
section.  (@xref{copy-region-as-kill}.)  How does it do this?

As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function works by
repeatedly taking the @sc{cdr} of a list---it takes the @sc{cdr} of the
@sc{cdr} of the @sc{cdr} @dots{}

@need 800
The two following expressions produce the same result:

@smallexample
@group
(setq kill-ring-yank-pointer (cdr kill-ring))

(setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
@end group
@end smallexample

However, the @code{nthcdr} expression is more complicated.  It uses the
@code{mod} function to determine which @sc{cdr} to select.

(You will remember to look at inner functions first; indeed, we will have to
go inside the @code{mod}.)

The @code{mod} function returns the value of its first argument modulo the
second; that is to say, it returns the remainder after dividing the first
argument by the second.  The value returned has the same sign as the second
argument.

@need 800
Thus,

@smallexample
@group
(mod 12 4)
  @result{} 0  ;; @r{because there is no remainder}
(mod 13 4)
  @result{} 1
@end group
@end smallexample

@need 1250
In this case, the first argument is often smaller than the second.  That is
fine.

@smallexample
@group
(mod 0 4)
  @result{} 0
(mod 1 4)
  @result{} 1
@end group
@end smallexample

We can guess what the @code{-} function does.  It is like @code{+} but
subtracts instead of adds; the @code{-} function subtracts its second
argument from its first.  Also, we already know what the @code{length}
function does (@pxref{length}).  It returns the length of a list.

And @code{n} is the name of the required argument to the @code{current-kill}
function.

@need 1250
So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
expression returns the whole list, as you can see by evaluating the
following:

@smallexample
@group
;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
;; @r{and} (mod (- 0 4) 4) @result{} 0
(nthcdr (mod (- 0 4) 4)
        '("fourth line of text"
          "third line"
          "second piece of text"
          "first some text"))
@end group
@end smallexample

@need 1250
When the first argument to the @code{current-kill} function is one, the
@code{nthcdr} expression returns the list without its first element.

@smallexample
@group
(nthcdr (mod (- 1 4) 4)
        '("fourth line of text"
          "third line"
          "second piece of text"
          "first some text"))
@end group
@end smallexample

@cindex @samp{global variable} defined
@cindex @samp{variable, global}, defined
Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer} are
@dfn{global variables}.  That means that any expression in Emacs Lisp can
access them.  They are not like the local variables set by @code{let} or
like the symbols in an argument list.  Local variables can only be accessed
within the @code{let} that defines them or the function that specifies them
in an argument list (and within expressions called by them).

@c texi2dvi fails when the name of the section is within ifnottex ...
@ifnottex
(@xref{Prevent confusion, , @code{let} Prevents Confusion}, and
@end ifnottex
@iftex
(@xref{Permanent Installation, , @code{let} Prevents Confusion}, and
@end iftex
@ref{defun, , The @code{defun} Macro}.)

@node yank
@appendixsec @code{yank}
@findex yank

After learning about @code{current-kill}, the code for the @code{yank}
function is almost easy.

The @code{yank} function does not use the @code{kill-ring-yank-pointer}
variable directly.  It calls @code{insert-for-yank} which calls
@code{current-kill} which sets the @code{kill-ring-yank-pointer} variable.

@need 1250
De code ziet er zo uit:

@c in GNU Emacs 22
@smallexample
@group
(defun yank (&optional arg)
  "Reinsert (\"paste\") the last stretch of killed text.
More precisely, reinsert the stretch of killed text most recently
killed OR yanked.  Put point at end, and set mark at beginning.
With just \\[universal-argument] as argument, same but put point at beginning (and mark at end).
With argument N, reinsert the Nth most recently killed stretch of killed
text.

When this command inserts killed text into the buffer, it honors
`yank-excluded-properties' and `yank-handler' as described in the
doc string for `insert-for-yank-1', which see.

See also the command `yank-pop' (\\[yank-pop])."
@end group
@group
  (interactive "*P")
  (setq yank-window-start (window-start))
  ;; If we don't get all the way thru, make last-command indicate that
  ;; for the following command.
  (setq this-command t)
  (push-mark (point))
@end group
@group
  (insert-for-yank (current-kill (cond
                                  ((listp arg) 0)
                                  ((eq arg '-) -2)
                                  (t (1- arg)))))
  (if (consp arg)
      ;; This is like exchange-point-and-mark, but doesn't activate the mark.
      ;; It is cleaner to avoid activation, even though the command
      ;; loop would deactivate the mark because we inserted text.
      (goto-char (prog1 (mark t)
                   (set-marker (mark-marker) (point) (current-buffer)))))
@end group
@group
  ;; If we do get all the way thru, make this-command indicate that.
  (if (eq this-command t)
      (setq this-command 'yank))
  nil)
@end group
@end smallexample

The key expression is @code{insert-for-yank}, which inserts the string
returned by @code{current-kill}, but removes some text properties from it.

However, before getting to that expression, the function sets the value of
@code{yank-window-start} to the position returned by the
@code{(window-start)} expression, the position at which the display
currently starts.  The @code{yank} function also sets @code{this-command}
and pushes the mark.

After it yanks the appropriate element, if the optional argument is a
@sc{cons} rather than a number or nothing, it puts point at beginning of the
yanked text and mark at its end.

(The @code{prog1} function is like @code{progn} but returns the value of its
first argument rather than the value of its last argument.  Its first
argument is forced to return the buffer's mark as an integer.  You can see
the documentation for these functions by placing point over them in this
buffer and then typing @kbd{C-h f} (@code{describe-function}) followed by a
@kbd{RET}; the default is the function.)

The last part of the function tells what to do when it succeeds.

@node yank-pop
@appendixsec @code{yank-pop}
@findex yank-pop

After understanding @code{yank} and @code{current-kill}, you know how to
approach the @code{yank-pop} function.  Leaving out the documentation to
save space, it looks like this:

@c GNU Emacs 22
@smallexample
@group
(defun yank-pop (&optional arg)
  "@dots{}"
  (interactive "*p")
  (if (not (eq last-command 'yank))
      (error "Previous command was not a yank"))
@end group
@group
  (setq this-command 'yank)
  (unless arg (setq arg 1))
  (let ((inhibit-read-only t)
        (before (< (point) (mark t))))
@end group
@group
    (if before
        (funcall (or yank-undo-function 'delete-region) (point) (mark t))
      (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
    (setq yank-undo-function nil)
@end group
@group
    (set-marker (mark-marker) (point) (current-buffer))
    (insert-for-yank (current-kill arg))
    ;; Set the window start back where it was in the yank command,
    ;; if possible.
    (set-window-start (selected-window) yank-window-start t)
@end group
@group
    (if before
        ;; This is like exchange-point-and-mark,
        ;;     but doesn't activate the mark.
        ;; It is cleaner to avoid activation, even though the command
        ;; loop would deactivate the mark because we inserted text.
        (goto-char (prog1 (mark t)
                     (set-marker (mark-marker)
                                 (point)
                                 (current-buffer))))))
  nil)
@end group
@end smallexample

The function is interactive with a small @samp{p} so the prefix argument is
processed and passed to the function.  The command can only be used after a
previous yank; otherwise an error message is sent.  This check uses the
variable @code{last-command} which is set by @code{yank} and is discussed
elsewhere.  (@xref{copy-region-as-kill}.)

The @code{let} clause sets the variable @code{before} to true or false
depending whether point is before or after mark and then the region between
point and mark is deleted.  This is the region that was just inserted by the
previous yank and it is this text that will be replaced.

@code{funcall} calls its first argument as a function, passing remaining
arguments to it.  The first argument is whatever the @code{or} expression
returns.  The two remaining arguments are the positions of point and mark
set by the preceding @code{yank} command.

There is more, but that is the hardest part.

@node ring bestand
@appendixsec The @file{ring.el} File
@cindex @file{ring.el} file

Interestingly, GNU Emacs possesses a file called @file{ring.el} that
provides many of the features we just discussed.  But functions such as
@code{kill-ring-yank-pointer} do not use this library, possibly because they
were written earlier.

@node Volledige grafiek
@appendix Een grafiek met labels op de assen

Printed axes help you understand a graph.  They convey scale.  In an earlier
chapter (@pxref{Readying a Graph, , Readying a Graph}), we wrote the code to
print the body of a graph.  Here we write the code for printing and labeling
vertical and horizontal axes, along with the body itself.

@menu
* Gelabeld voorbeeld::       Gelabeld voorbeeld
* print-graph varlist::      @code{let} expressie in @code{print-graph}
* print-Y-axis::             Print een label voor de verticale as
* print-X-axis::             Print een horizontaal label
* De gehele grafiek afdrukken::  De functie om een hele grafiek te printen.
@end menu

@ifnottex
@node Gelabeld voorbeeld
@unnumberedsec Labeled Example Graph
@end ifnottex

Since insertions fill a buffer to the right and below point, the new graph
printing function should first print the Y or vertical axis, then the body
of the graph, and finally the X or horizontal axis.  This sequence lays out
for us the contents of the function:

@enumerate
@item
Set up code.

@item
Print Y axis.

@item
Print body of graph.

@item
Print X axis.
@end enumerate

@need 800
Here is an example of how a finished graph should look:

@smallexample
@group
    10 -
                  *
                  *  *
                  *  **
                  *  ***
     5 -      *   *******
            * *** *******
            *************
          ***************
     1 - ****************
         |   |    |    |
         1   5   10   15
@end group
@end smallexample

@noindent
In this graph, both the vertical and the horizontal axes are labeled with
numbers.  However, in some graphs, the horizontal axis is time and would be
better labeled with months, like this:

@smallexample
@group
     5 -      *
            * ** *
            *******
          ********** **
     1 - **************
         |    ^      |
         Jan  June   Jan
@end group
@end smallexample

Indeed, with a little thought, we can easily come up with a variety of
vertical and horizontal labeling schemes.  Our task could become
complicated.  But complications breed confusion.  Rather than permit this,
it is better choose a simple labeling scheme for our first effort, and to
modify or replace it later.

@need 1200
These considerations suggest the following outline for the
@code{print-graph} function:

@smallexample
@group
(defun print-graph (numbers-list)
  "@var{documentation}@dots{}"
  (let ((height  @dots{}
        @dots{}))
@end group
@group
    (print-Y-axis height @dots{} )
    (graph-body-print numbers-list)
    (print-X-axis @dots{} )))
@end group
@end smallexample

We can work on each part of the @code{print-graph} function definition in
turn.

@node print-graph varlist
@appendixsec The @code{print-graph} Varlist
@cindex @code{print-graph} varlist

In writing the @code{print-graph} function, the first task is to write the
varlist in the @code{let} expression.  (We will leave aside for the moment
any thoughts about making the function interactive or about the contents of
its documentation string.)

The varlist should set several values.  Clearly, the top of the label for
the vertical axis must be at least the height of the graph, which means that
we must obtain this information here.  Note that the @code{print-graph-body}
function also requires this information.  There is no reason to calculate
the height of the graph in two different places, so we should change
@code{print-graph-body} from the way we defined it earlier to take advantage
of the calculation.

Similarly, both the function for printing the X axis labels and the
@code{print-graph-body} function need to learn the value of the width of
each symbol.  We can perform the calculation here and change the definition
for @code{print-graph-body} from the way we defined it in the previous
chapter.

The length of the label for the horizontal axis must be at least as long as
the graph.  However, this information is used only in the function that
prints the horizontal axis, so it does not need to be calculated here.

These thoughts lead us directly to the following form for the varlist in the
@code{let} for @code{print-graph}:

@smallexample
@group
(let ((height (apply 'max numbers-list)) ; @r{First version.}
      (symbol-width (length graph-blank)))
@end group
@end smallexample

@noindent
As we shall see, this expression is not quite right.

@need 2000
@node print-Y-axis
@appendixsec De @code{print-Y-axis} functie
@cindex Axis, print vertical
@cindex Y axis printing
@cindex Vertical axis printing
@cindex Print vertical axis

The job of the @code{print-Y-axis} function is to print a label for the
vertical axis that looks like this:

@smallexample
@group
    10 -




     5 -



     1 -
@end group
@end smallexample

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

@menu
* print-Y-axis in detail::   print-Y-axis in detail
* Hoogte van label::         Welke hoogte voor de Y-as?
* Bereken het restant::      Hoe het restant van een deling te berekenen.
* Y-as element::             Een lijn voor de y-as construeren.
* Y-axis-column::            Een lijst van y-as labels genereren.
* print-Y-axis enalaatste::  Nog niet finale versie
@end menu

@ifnottex
@node print-Y-axis in detail
@unnumberedsubsec The @code{print-Y-axis} Function in Detail
@end ifnottex

It is easy enough to see in the figure what the Y axis label should look
like; but to say in words, and then to write a function definition to do the
job is another matter.  It is not quite true to say that we want a number
and a tic every five lines: there are only three lines between the @samp{1}
and the @samp{5} (lines 2, 3, and 4), but four lines between the @samp{5}
and the @samp{10} (lines 6, 7, 8, and 9).  It is better to say that we want
a number and a tic mark on the base line (number 1) and then that we want a
number and a tic on the fifth line from the bottom and on every line that is
a multiple of five.

@ifnottex
@node Hoogte van label
@unnumberedsubsec What height should the label be?
@end ifnottex

The next issue is what height the label should be? Suppose the maximum
height of tallest column of the graph is seven.  Should the highest label on
the Y axis be @samp{5 -}, and should the graph stick up above the label? Or
should the highest label be @samp{7 -}, and mark the peak of the graph? Or
should the highest label be @code{10 -}, which is a multiple of five, and be
higher than the topmost value of the graph?

The latter form is preferred.  Most graphs are drawn within rectangles whose
sides are an integral number of steps long---5, 10, 15, and so on for a step
distance of five.  But as soon as we decide to use a step height for the
vertical axis, we discover that the simple expression in the varlist for
computing the height is wrong.  The expression is @code{(apply 'max
numbers-list)}.  This returns the precise height, not the maximum height
plus whatever is necessary to round up to the nearest multiple of five.  A
more complex expression is required.

As usual in cases like this, a complex problem becomes simpler if it is
divided into several smaller problems.

First, consider the case when the highest value of the graph is an integral
multiple of five---when it is 5, 10, 15, or some higher multiple of five.
We can use this value as the Y axis height.

A fairly simply way to determine whether a number is a multiple of five is
to divide it by five and see if the division results in a remainder.  If
there is no remainder, the number is a multiple of five.  Thus, seven
divided by five has a remainder of two, and seven is not an integral
multiple of five.  Put in slightly different language, more reminiscent of
the classroom, five goes into seven once, with a remainder of two.  However,
five goes into ten twice, with no remainder: ten is an integral multiple of
five.

@node Bereken het restant
@appendixsubsec Side Trip: Compute a Remainder

@findex % @r{(remainder function)}
@cindex Remainder function, @code{%}
In Lisp, the function for computing a remainder is @code{%}.  The function
returns the remainder of its first argument divided by its second argument.
As it happens, @code{%} is a function in Emacs Lisp that you cannot discover
using @code{apropos}: you find nothing if you type @kbd{M-x apropos
@key{RET} remainder @key{RET}}.  The only way to learn of the existence of
@code{%} is to read about it in a book such as this or in the Emacs Lisp
sources.

You can try the @code{%} function by evaluating the following two
expressions:

@smallexample
@group
(% 7 5)

(% 10 5)
@end group
@end smallexample

@noindent
The first expression returns 2 and the second expression returns 0.

To test whether the returned value is zero or some other number, we can use
the @code{zerop} function.  This function returns @code{t} if its argument,
which must be a number, is zero.

@smallexample
@group
(zerop (% 7 5))
     @result{} nil

(zerop (% 10 5))
     @result{} t
@end group
@end smallexample

Thus, the following expression will return @code{t} if the height of the
graph is evenly divisible by five:

@smallexample
(zerop (% height 5))
@end smallexample

@noindent
(The value of @code{height}, of course, can be found from @code{(apply 'max
numbers-list)}.)

On the other hand, if the value of @code{height} is not a multiple of five,
we want to reset the value to the next higher multiple of five.  This is
straightforward arithmetic using functions with which we are already
familiar.  First, we divide the value of @code{height} by five to determine
how many times five goes into the number.  Thus, five goes into twelve
twice.  If we add one to this quotient and multiply by five, we will obtain
the value of the next multiple of five that is larger than the height.  Five
goes into twelve twice.  Add one to two, and multiply by five; the result is
fifteen, which is the next multiple of five that is higher than twelve.  The
Lisp expression for this is:

@smallexample
(* (1+ (/ height 5)) 5)
@end smallexample

@noindent
For example, if you evaluate the following, the result is 15:

@smallexample
(* (1+ (/ 12 5)) 5)
@end smallexample

All through this discussion, we have been using 5 as the value for spacing
labels on the Y axis; but we may want to use some other value.  For
generality, we should replace 5 with a variable to which we can assign a
value.  The best name I can think of for this variable is
@code{Y-axis-label-spacing}.

@need 1250
Using this term, and an @code{if} expression, we produce the following:

@smallexample
@group
(if (zerop (% height Y-axis-label-spacing))
    height
  ;; @r{else}
  (* (1+ (/ height Y-axis-label-spacing))
     Y-axis-label-spacing))
@end group
@end smallexample

@noindent
This expression returns the value of @code{height} itself if the height is
an even multiple of the value of the @code{Y-axis-label-spacing} or else it
computes and returns a value of @code{height} that is equal to the next
higher multiple of the value of the @code{Y-axis-label-spacing}.

We can now include this expression in the @code{let} expression of the
@code{print-graph} function (after first setting the value of
@code{Y-axis-label-spacing}):
@vindex Y-axis-label-spacing

@smallexample
@group
(defvar Y-axis-label-spacing 5
  "Number of lines from one Y axis label to next.")
@end group

@group
@dots{}
(let* ((height (apply 'max numbers-list))
       (height-of-top-line
        (if (zerop (% height Y-axis-label-spacing))
            height
@end group
@group
          ;; @r{else}
          (* (1+ (/ height Y-axis-label-spacing))
             Y-axis-label-spacing)))
       (symbol-width (length graph-blank))))
@dots{}
@end group
@end smallexample

@noindent
(Note use of the @code{let*} function: the initial value of height is
computed once by the @code{(apply 'max numbers-list)} expression and then
the resulting value of @code{height} is used to compute its final value.
@xref{fwd-para let, , The @code{let*} expression}, for more about
@code{let*}.)

@node Y-as element
@appendixsubsec Construct a Y Axis Element

When we print the vertical axis, we want to insert strings such as
@w{@samp{5 -}} and @w{@samp{10 - }} every five lines.  Moreover, we want the
numbers and dashes to line up, so shorter numbers must be padded with
leading spaces.  If some of the strings use two digit numbers, the strings
with single digit numbers must include a leading blank space before the
number.

@findex number-to-string
To figure out the length of the number, the @code{length} function is used.
But the @code{length} function works only with a string, not with a number.
So the number has to be converted from being a number to being a string.
This is done with the @code{number-to-string} function.  For example,

@smallexample
@group
(length (number-to-string 35))
     @result{} 2

(length (number-to-string 100))
     @result{} 3
@end group
@end smallexample

@noindent
(@code{number-to-string} is also called @code{int-to-string}; you will see
this alternative name in various sources.)

In addition, in each label, each number is followed by a string such as
@w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker.  This
variable is defined with @code{defvar}:

@vindex Y-axis-tic
@smallexample
@group
(defvar Y-axis-tic " - "
   "String that follows number in a Y axis label.")
@end group
@end smallexample

The length of the Y label is the sum of the length of the Y axis tic mark
and the length of the number of the top of the graph.

@smallexample
(length (concat (number-to-string height) Y-axis-tic)))
@end smallexample

This value will be calculated by the @code{print-graph} function in its
varlist as @code{full-Y-label-width} and passed on.  (Note that we did not
think to include this in the varlist when we first proposed it.)

To make a complete vertical axis label, a tic mark is concatenated with a
number; and the two together may be preceded by one or more spaces depending
on how long the number is.  The label consists of three parts: the
(optional) leading spaces, the number, and the tic mark.  The function is
passed the value of the number for the specific row, and the value of the
width of the top line, which is calculated (just once) by
@code{print-graph}.

@smallexample
@group
(defun Y-axis-element (number full-Y-label-width)
  "Construct a NUMBERed label element.
A numbered element looks like this `  5 - ',
and is padded as needed so all line up with
the element for the largest number."
@end group
@group
  (let* ((leading-spaces
         (- full-Y-label-width
            (length
             (concat (number-to-string number)
                     Y-axis-tic)))))
@end group
@group
    (concat
     (make-string leading-spaces ? )
     (number-to-string number)
     Y-axis-tic)))
@end group
@end smallexample

The @code{Y-axis-element} function concatenates together the leading spaces,
if any; the number, as a string; and the tic mark.

To figure out how many leading spaces the label will need, the function
subtracts the actual length of the label---the length of the number plus the
length of the tic mark---from the desired label width.

@findex make-string
Blank spaces are inserted using the @code{make-string} function.  This
function takes two arguments: the first tells it how long the string will be
and the second is a symbol for the character to insert, in a special
format.  The format is a question mark followed by a blank space, like this,
@samp{? }.  @xref{Character Type, , Character Type, elisp, The GNU Emacs
Lisp Reference Manual}, for a description of the syntax for characters.  (Of
course, you might want to replace the blank space by some other character
@dots{} You know what to do.)

The @code{number-to-string} function is used in the concatenation
expression, to convert the number to a string that is concatenated with the
leading spaces and the tic mark.

@node Y-axis-column
@appendixsubsec Create a Y Axis Column

The preceding functions provide all the tools needed to construct a function
that generates a list of numbered and blank strings to insert as the label
for the vertical axis:

@findex Y-axis-column
@smallexample
@group
(defun Y-axis-column (height width-of-label)
  "Construct list of Y axis labels and blank strings.
For HEIGHT of line above base and WIDTH-OF-LABEL."
  (let (Y-axis)
@group
@end group
    (while (> height 1)
      (if (zerop (% height Y-axis-label-spacing))
          ;; @r{Insert label.}
          (setq Y-axis
                (cons
                 (Y-axis-element height width-of-label)
                 Y-axis))
@group
@end group
        ;; @r{Else, insert blanks.}
        (setq Y-axis
              (cons
               (make-string width-of-label ? )
               Y-axis)))
      (setq height (1- height)))
    ;; @r{Insert base line.}
    (setq Y-axis
          (cons (Y-axis-element 1 width-of-label) Y-axis))
    (nreverse Y-axis)))
@end group
@end smallexample

In this function, we start with the value of @code{height} and repetitively
subtract one from its value.  After each subtraction, we test to see whether
the value is an integral multiple of the @code{Y-axis-label-spacing}.  If it
is, we construct a numbered label using the @code{Y-axis-element} function;
if not, we construct a blank label using the @code{make-string} function.
The base line consists of the number one followed by a tic mark.

@need 2000
@node print-Y-axis enalaatste
@appendixsubsec The Not Quite Final Version of @code{print-Y-axis}

The list constructed by the @code{Y-axis-column} function is passed to the
@code{print-Y-axis} function, which inserts the list as a column.

@findex print-Y-axis
@smallexample
@group
(defun print-Y-axis (height full-Y-label-width)
  "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH.
Height must be the maximum height of the graph.
Full width is the width of the highest label element."
;; Value of height and full-Y-label-width
;; are passed by print-graph.
@end group
@group
  (let ((start (point)))
    (insert-rectangle
     (Y-axis-column height full-Y-label-width))
    ;; @r{Place point ready for inserting graph.}
    (goto-char start)
    ;; @r{Move point forward by value of} full-Y-label-width
    (forward-char full-Y-label-width)))
@end group
@end smallexample

The @code{print-Y-axis} uses the @code{insert-rectangle} function to insert
the Y axis labels created by the @code{Y-axis-column} function.  In
addition, it places point at the correct position for printing the body of
the graph.

You can test @code{print-Y-axis}:

@enumerate
@item
Installeer

@smallexample
@group
Y-axis-label-spacing
Y-axis-tic
Y-axis-element
Y-axis-column
print-Y-axis
@end group
@end smallexample

@item
Copy the following expression:

@smallexample
(print-Y-axis 12 5)
@end smallexample

@item
Switch to the @file{*scratch*} buffer and place the cursor where you want
the axis labels to start.

@item
Type @kbd{M-:} (@code{eval-expression}).

@item
Yank the @code{graph-body-print} expression into the minibuffer with
@kbd{C-y} (@code{yank)}.

@item
Press @key{RET} to evaluate the expression.
@end enumerate

Emacs will print labels vertically, the top one being @w{@samp{10 -@w{ }}}.
(The @code{print-graph} function will pass the value of
@code{height-of-top-line}, which in this case will end up as 15, thereby
getting rid of what might appear as a bug.)

@need 2000
@node print-X-axis
@appendixsec De @code{print-X-axis} functie
@cindex Axis, print horizontal
@cindex X axis printing
@cindex Print horizontal axis
@cindex Horizontal axis printing

X axis labels are much like Y axis labels, except that the ticks are on a
line above the numbers.  Labels should look like this:

@smallexample
@group
    |   |    |    |
    1   5   10   15
@end group
@end smallexample

The first tic is under the first column of the graph and is preceded by
several blank spaces.  These spaces provide room in rows above for the Y
axis labels.  The second, third, fourth, and subsequent ticks are all spaced
equally, according to the value of @code{X-axis-label-spacing}.

The second row of the X axis consists of numbers, preceded by several blank
spaces and also separated according to the value of the variable
@code{X-axis-label-spacing}.

The value of the variable @code{X-axis-label-spacing} should itself be
measured in units of @code{symbol-width}, since you may want to change the
width of the symbols that you are using to print the body of the graph
without changing the ways the graph is labeled.

@menu
* Overeenkomsten verschillen::  Grotendeels als @code{print-Y-axis}, maar 
                                  niet helemaal gelijk.
* X-as tic marks::           Maak tic marks voor de horizontale as.
@end menu

@ifnottex
@node Overeenkomsten verschillen
@unnumberedsubsec Similarities and differences
@end ifnottex

The @code{print-X-axis} function is constructed in more or less the same
fashion as the @code{print-Y-axis} function except that it has two lines:
the line of tic marks and the numbers.  We will write a separate function to
print each line and then combine them within the @code{print-X-axis}
function.

This is a three step process:

@enumerate
@item
Write a function to print the X axis tic marks,
@code{print-X-axis-tic-line}.

@item
Write a function to print the X numbers, @code{print-X-axis-numbered-line}.

@item
Write a function to print both lines, the @code{print-X-axis} function,
using @code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}.
@end enumerate

@node X-as tic marks
@appendixsubsec X-as tic marks

The first function should print the X axis tic marks.  We must specify the
tic marks themselves and their spacing:

@smallexample
@group
(defvar X-axis-label-spacing
  (if (boundp 'graph-blank)
      (* 5 (length graph-blank)) 5)
  "Number of units from one X axis label to next.")
@end group
@end smallexample

@noindent
(Note that the value of @code{graph-blank} is set by another @code{defvar}.
The @code{boundp} predicate checks whether it has already been set;
@code{boundp} returns @code{nil} if it has not.  If @code{graph-blank} were
unbound and we did not use this conditional construction, we would enter the
debugger and see an error message saying @samp{@w{Debugger entered--Lisp
error:} @w{(void-variable graph-blank)}}.)

@need 1200
Here is the @code{defvar} for @code{X-axis-tic-symbol}:

@smallexample
@group
(defvar X-axis-tic-symbol "|"
  "String to insert to point to a column in X axis.")
@end group
@end smallexample

@need 1250
The goal is to make a line that looks like this:

@smallexample
       |   |    |    |
@end smallexample

The first tic is indented so that it is under the first column, which is
indented to provide space for the Y axis labels.

A tic element consists of the blank spaces that stretch from one tic to the
next plus a tic symbol.  The number of blanks is determined by the width of
the tic symbol and the @code{X-axis-label-spacing}.

@need 1250
De code ziet er zo uit:

@smallexample
@group
;;; X-axis-tic-element
@dots{}
(concat
 (make-string
  ;; @r{Make a string of blanks.}
  (-  (* symbol-width X-axis-label-spacing)
      (length X-axis-tic-symbol))
  ? )
 ;; @r{Concatenate blanks with tic symbol.}
 X-axis-tic-symbol)
@dots{}
@end group
@end smallexample

Next, we determine how many blanks are needed to indent the first tic mark
to the first column of the graph.  This uses the value of
@code{full-Y-label-width} passed it by the @code{print-graph} function.

@need 1250
The code to make @code{X-axis-leading-spaces} looks like this:

@smallexample
@group
;; X-axis-leading-spaces
@dots{}
(make-string full-Y-label-width ? )
@dots{}
@end group
@end smallexample

We also need to determine the length of the horizontal axis, which is the
length of the numbers list, and the number of ticks in the horizontal axis:

@smallexample
@group
;; X-length
@dots{}
(length numbers-list)
@end group

@group
;; tic-width
@dots{}
(* symbol-width X-axis-label-spacing)
@end group

@group
;; number-of-X-ticks
(if (zerop (% (X-length tic-width)))
    (/ (X-length tic-width))
  (1+ (/ (X-length tic-width))))
@end group
@end smallexample

@need 1250
All this leads us directly to the function for printing the X axis tic line:

@findex print-X-axis-tic-line
@smallexample
@group
(defun print-X-axis-tic-line
  (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
  "Print ticks for X axis."
    (insert X-axis-leading-spaces)
    (insert X-axis-tic-symbol)  ; @r{Under first column.}
@end group
@group
    ;; @r{Insert second tic in the right spot.}
    (insert (concat
             (make-string
              (-  (* symbol-width X-axis-label-spacing)
                  ;; @r{Insert white space up to second tic symbol.}
                  (* 2 (length X-axis-tic-symbol)))
              ? )
             X-axis-tic-symbol))
@end group
@group
    ;; @r{Insert remaining ticks.}
    (while (> number-of-X-tics 1)
      (insert X-axis-tic-element)
      (setq number-of-X-tics (1- number-of-X-tics))))
@end group
@end smallexample

The line of numbers is equally straightforward:

@need 1250
First, we create a numbered element with blank spaces before each number:

@findex X-axis-element
@smallexample
@group
(defun X-axis-element (number)
  "Construct a numbered X axis element."
  (let ((leading-spaces
         (-  (* symbol-width X-axis-label-spacing)
             (length (number-to-string number)))))
    (concat (make-string leading-spaces ? )
            (number-to-string number))))
@end group
@end smallexample

Next, we create the function to print the numbered line, starting with the
number 1 under the first column:

@findex print-X-axis-numbered-line
@smallexample
@group
(defun print-X-axis-numbered-line
  (number-of-X-tics X-axis-leading-spaces)
  "Print line of X-axis numbers"
  (let ((number X-axis-label-spacing))
    (insert X-axis-leading-spaces)
    (insert "1")
@end group
@group
    (insert (concat
             (make-string
              ;; @r{Insert white space up to next number.}
              (-  (* symbol-width X-axis-label-spacing) 2)
              ? )
             (number-to-string number)))
@end group
@group
    ;; @r{Insert remaining numbers.}
    (setq number (+ number X-axis-label-spacing))
    (while (> number-of-X-tics 1)
      (insert (X-axis-element number))
      (setq number (+ number X-axis-label-spacing))
      (setq number-of-X-tics (1- number-of-X-tics)))))
@end group
@end smallexample

Finally, we need to write the @code{print-X-axis} that uses
@code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}.

The function must determine the local values of the variables used by both
@code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and then
it must call them.  Also, it must print the carriage return that separates
the two lines.

The function consists of a varlist that specifies five local variables, and
calls to each of the two line printing functions:

@findex print-X-axis
@smallexample
@group
(defun print-X-axis (numbers-list)
  "Print X axis labels to length of NUMBERS-LIST."
  (let* ((leading-spaces
          (make-string full-Y-label-width ? ))
@end group
@group
       ;; symbol-width @r{is provided by} graph-body-print
       (tic-width (* symbol-width X-axis-label-spacing))
       (X-length (length numbers-list))
@end group
@group
       (X-tic
        (concat
         (make-string
@end group
@group
          ;; @r{Make a string of blanks.}
          (-  (* symbol-width X-axis-label-spacing)
              (length X-axis-tic-symbol))
          ? )
@end group
@group
         ;; @r{Concatenate blanks with tic symbol.}
         X-axis-tic-symbol))
@end group
@group
       (tic-number
        (if (zerop (% X-length tic-width))
            (/ X-length tic-width)
          (1+ (/ X-length tic-width)))))
@end group
@group
    (print-X-axis-tic-line tic-number leading-spaces X-tic)
    (insert "\n")
    (print-X-axis-numbered-line tic-number leading-spaces)))
@end group
@end smallexample

@need 1250
You can test @code{print-X-axis}:

@enumerate
@item
Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing},
@code{print-X-axis-tic-line}, as well as @code{X-axis-element},
@code{print-X-axis-numbered-line}, and @code{print-X-axis}.

@item
Copy the following expression:

@smallexample
@group
(progn
 (let ((full-Y-label-width 5)
       (symbol-width 1))
   (print-X-axis
    '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16))))
@end group
@end smallexample

@item
Switch to the @file{*scratch*} buffer and place the cursor where you want
the axis labels to start.

@item
Type @kbd{M-:} (@code{eval-expression}).

@item
Yank the test expression into the minibuffer with @kbd{C-y} (@code{yank)}.

@item
Press @key{RET} to evaluate the expression.
@end enumerate

@need 1250
Emacs will print the horizontal axis like this:
@sp 1

@smallexample
@group
     |   |    |    |    |
     1   5   10   15   20
@end group
@end smallexample

@node De gehele grafiek afdrukken
@appendixsec De hele grafiek afdrukken
@cindex Printing the whole graph
@cindex Whole graph printing
@cindex Graph, printing all

Now we are nearly ready to print the whole graph.

The function to print the graph with the proper labels follows the outline
we created earlier (@pxref{Full Graph, , A Graph with Labeled Axes}), but
with additions.

@need 1250
Here is the outline:

@smallexample
@group
(defun print-graph (numbers-list)
  "@var{documentation}@dots{}"
  (let ((height  @dots{}
        @dots{}))
@end group
@group
    (print-Y-axis height @dots{} )
    (graph-body-print numbers-list)
    (print-X-axis @dots{} )))
@end group
@end smallexample

@menu
* De finale versie::         Enkele veranderingen.
* Test print-graph::         Een korte test draaien.
* Woorden in defuns grafisch weergeven::  De finale code uitvoeren.
* lambda::                   Hoe een anonyme functie te schrijven
* mapcar::                   Een functie toepassen op de elementen van een 
                               lijst.
* Een andere bug::           Weer een andere bug @dots{} erg verraderlijk.
* Finale afgedrukte grafiek::  De grafiek zelf
@end menu

@ifnottex
@node De finale versie
@unnumberedsubsec Changes for the Final Version
@end ifnottex

The final version is different from what we planned in two ways: first, it
contains additional values calculated once in the varlist; second, it
carries an option to specify the labels' increment per row.  This latter
feature turns out to be essential; otherwise, a graph may have more rows
than fit on a display or on a sheet of paper.

@need 1500
This new feature requires a change to the @code{Y-axis-column} function, to
add @code{vertical-step} to it.  The function looks like this:

@findex Y-axis-column @r{Final version.}
@smallexample
@group
;;; @r{Final version.}
(defun Y-axis-column
  (height width-of-label &optional vertical-step)
  "Construct list of labels for Y axis.
HEIGHT is maximum height of graph.
WIDTH-OF-LABEL is maximum width of label.
VERTICAL-STEP, an option, is a positive integer
that specifies how much a Y axis label increments
for each line.  For example, a step of 5 means
that each line is five units of the graph."
@end group
@group
  (let (Y-axis
        (number-per-line (or vertical-step 1)))
    (while (> height 1)
      (if (zerop (% height Y-axis-label-spacing))
@end group
@group
          ;; @r{Insert label.}
          (setq Y-axis
                (cons
                 (Y-axis-element
                  (* height number-per-line)
                  width-of-label)
                 Y-axis))
@end group
@group
        ;; @r{Else, insert blanks.}
        (setq Y-axis
              (cons
               (make-string width-of-label ? )
               Y-axis)))
      (setq height (1- height)))
@end group
@group
    ;; @r{Insert base line.}
    (setq Y-axis (cons (Y-axis-element
                        (or vertical-step 1)
                        width-of-label)
                       Y-axis))
    (nreverse Y-axis)))
@end group
@end smallexample

The values for the maximum height of graph and the width of a symbol are
computed by @code{print-graph} in its @code{let} expression; so
@code{graph-body-print} must be changed to accept them.

@findex graph-body-print @r{Final version.}
@smallexample
@group
;;; @r{Final version.}
(defun graph-body-print (numbers-list height symbol-width)
  "Print a bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values.
HEIGHT is maximum height of graph.
SYMBOL-WIDTH is number of each column."
@end group
@group
  (let (from-position)
    (while numbers-list
      (setq from-position (point))
      (insert-rectangle
       (column-of-graph height (car numbers-list)))
      (goto-char from-position)
      (forward-char symbol-width)
@end group
@group
      ;; @r{Draw graph column by column.}
      (sit-for 0)
      (setq numbers-list (cdr numbers-list)))
    ;; @r{Place point for X axis labels.}
    (forward-line height)
    (insert "\n")))
@end group
@end smallexample

@need 1250
Finally, the code for the @code{print-graph} function:

@findex print-graph @r{Final version.}
@smallexample
@group
;;; @r{Final version.}
(defun print-graph
  (numbers-list &optional vertical-step)
  "Print labeled bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values.
@end group

@group
Optionally, VERTICAL-STEP, a positive integer,
specifies how much a Y axis label increments for
each line.  For example, a step of 5 means that
each row is five units."
@end group
@group
  (let* ((symbol-width (length graph-blank))
         ;; @code{height} @r{is both the largest number}
         ;; @r{and the number with the most digits.}
         (height (apply 'max numbers-list))
@end group
@group
         (height-of-top-line
          (if (zerop (% height Y-axis-label-spacing))
              height
            ;; @r{else}
            (* (1+ (/ height Y-axis-label-spacing))
               Y-axis-label-spacing)))
@end group
@group
         (vertical-step (or vertical-step 1))
         (full-Y-label-width
          (length
@end group
@group
           (concat
            (number-to-string
             (* height-of-top-line vertical-step))
            Y-axis-tic))))
@end group

@group
    (print-Y-axis
     height-of-top-line full-Y-label-width vertical-step)
@end group
@group
    (graph-body-print
     numbers-list height-of-top-line symbol-width)
    (print-X-axis numbers-list)))
@end group
@end smallexample

@node Test print-graph
@appendixsubsec Testing @code{print-graph}

@need 1250
We can test the @code{print-graph} function with a short list of numbers:

@enumerate
@item
Install the final versions of @code{Y-axis-column}, @code{graph-body-print},
and @code{print-graph} (in addition to the rest of the code.)

@item
Copy the following expression:

@smallexample
(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
@end smallexample

@item
Switch to the @file{*scratch*} buffer and place the cursor where you want
the axis labels to start.

@item
Type @kbd{M-:} (@code{eval-expression}).

@item
Yank the test expression into the minibuffer with @kbd{C-y} (@code{yank)}.

@item
Press @key{RET} to evaluate the expression.
@end enumerate

@need 1250
Emacs will print a graph that looks like this:

@smallexample
@group
10 -


         *
        **   *
 5 -   ****  *
       **** ***
     * *********
     ************
 1 - *************

     |   |    |    |
     1   5   10   15
@end group
@end smallexample

@need 1200
On the other hand, if you pass @code{print-graph} a @code{vertical-step}
value of 2, by evaluating this expression:

@smallexample
(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
@end smallexample

@need 1250
@noindent
The graph looks like this:

@smallexample
@group
20 -


         *
        **   *
10 -   ****  *
       **** ***
     * *********
     ************
 2 - *************

     |   |    |    |
     1   5   10   15
@end group
@end smallexample

@noindent
(A question: is the @samp{2} on the bottom of the vertical axis a bug or a
feature? If you think it is a bug, and should be a @samp{1} instead, (or
even a @samp{0}), you can modify the sources.)

@node Woorden in defuns grafisch weergeven
@appendixsubsec Graphing Numbers of Words and Symbols

Now for the graph for which all this code was written: a graph that shows
how many function definitions contain fewer than 10 words and symbols, how
many contain between 10 and 19 words and symbols, how many contain between
20 and 29 words and symbols, and so on.

This is a multi-step process.  First make sure you have loaded all the
requisite code.

@need 1500
It is a good idea to reset the value of @code{top-of-ranges} in case you
have set it to some different value.  You can evaluate the following:

@smallexample
@group
(setq top-of-ranges
 '(10  20  30  40  50
   60  70  80  90 100
  110 120 130 140 150
  160 170 180 190 200
  210 220 230 240 250
  260 270 280 290 300)
@end group
@end smallexample

@noindent
Next create a list of the number of words and symbols in each range.

@need 1500
@noindent
Evaluate the following:

@smallexample
@group
(setq list-for-graph
       (defuns-per-range
         (sort
          (recursive-lengths-list-many-files
           (directory-files "/usr/local/emacs/lisp"
                            t ".+el$"))
          '<)
         top-of-ranges))
@end group
@end smallexample

@noindent
On my old machine, this took about an hour.  It looked though 303 Lisp files
in my copy of Emacs version 19.23.  After all that computing, the
@code{list-for-graph} had this value:

@smallexample
@group
(537 1027 955 785 594 483 349 292 224 199 166 120 116 99
90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220)
@end group
@end smallexample

@noindent
This means that my copy of Emacs had 537 function definitions with fewer
than 10 words or symbols in them, 1,027 function definitions with 10 to 19
words or symbols in them, 955 function definitions with 20 to 29 words or
symbols in them, and so on.

Clearly, just by looking at this list we can see that most function
definitions contain ten to thirty words and symbols.

Now for printing.  We do @emph{not} want to print a graph that is 1,030
lines high @dots{} Instead, we should print a graph that is fewer than
twenty-five lines high.  A graph that height can be displayed on almost any
monitor, and easily printed on a sheet of paper.

This means that each value in @code{list-for-graph} must be reduced to
one-fiftieth its present value.

Here is a short function to do just that, using two functions we have not
yet seen, @code{mapcar} and @code{lambda}.

@smallexample
@group
(defun one-fiftieth (full-range)
  "Return list, each number one-fiftieth of previous."
 (mapcar (lambda (arg) (/ arg 50)) full-range))
@end group
@end smallexample

@node lambda
@appendixsubsec A @code{lambda} Expression: Useful Anonymity
@cindex Anonymous function
@findex lambda

@code{lambda} is the symbol for an anonymous function, a function without a
name.  Every time you use an anonymous function, you need to include its
whole body.

@need 1250
@noindent
Thus,

@smallexample
(lambda (arg) (/ arg 50))
@end smallexample

@noindent
is a function that returns the value resulting from dividing whatever is
passed to it as @code{arg} by 50.

@need 1200
Earlier, for example, we had a function @code{multiply-by-seven}; it
multiplied its argument by 7.  This function is similar, except it divides
its argument by 50; and, it has no name.  The anonymous equivalent of
@code{multiply-by-seven} is:

@smallexample
(lambda (number) (* 7 number))
@end smallexample

@noindent
(@xref{defun, , The @code{defun} Macro}.)

@need 1250
@noindent
If we want to multiply 3 by 7, we can write:

@c clear print-postscript-figures
@c lambda example diagram #1
@ifset print-postscript-figures
@sp 1
@center @image{lambda-1}
@sp 1
@end ifset
@ifclear print-postscript-figures
@smallexample
@group
(multiply-by-seven 3)
 \_______________/ ^
         |         |
      function  argument
@end group
@end smallexample
@end ifclear

@noindent
This expression returns 21.

@need 1250
@noindent
Similarly, we can write:

@c lambda example diagram #2
@ifset print-postscript-figures
@sp 1
@center @image{lambda-2}
@sp 1
@end ifset
@ifclear print-postscript-figures
@smallexample
@group
((lambda (number) (* 7 number)) 3)
 \____________________________/ ^
               |                |
      anonymous function     argument
@end group
@end smallexample
@end ifclear

@need 1250
@noindent
If we want to divide 100 by 50, we can write:

@c lambda example diagram #3
@ifset print-postscript-figures
@sp 1
@center @image{lambda-3}
@sp 1
@end ifset
@ifclear print-postscript-figures
@smallexample
@group
((lambda (arg) (/ arg 50)) 100)
 \______________________/  \_/
             |              |
    anonymous function   argument
@end group
@end smallexample
@end ifclear

@noindent
This expression returns 2.  The 100 is passed to the function, which divides
that number by 50.

@xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs Lisp
Reference Manual}, for more about @code{lambda}.  Lisp and lambda
expressions derive from the Lambda Calculus.

@node mapcar
@appendixsubsec The @code{mapcar} Function
@findex mapcar

@code{mapcar} is a function that calls its first argument with each element
of its second argument, in turn.  The second argument must be a sequence.

The @samp{map} part of the name comes from the mathematical phrase,
``mapping over a domain'', meaning to apply a function to each of the
elements in a domain.  The mathematical phrase is based on the metaphor of a
surveyor walking, one step at a time, over an area he is mapping.  And
@samp{car}, of course, comes from the Lisp notion of the first of a list.

@need 1250
@noindent
Bijvoorbeeld,

@smallexample
@group
(mapcar '1+ '(2 4 6))
     @result{} (3 5 7)
@end group
@end smallexample

@noindent
The function @code{1+} which adds one to its argument, is executed on
@emph{each} element of the list, and a new list is returned.

Contrast this with @code{apply}, which applies its first argument to all the
remaining.  (@xref{Readying a Graph, , Readying a Graph}, for an explanation
of @code{apply}.)

@need 1250
In the definition of @code{one-fiftieth}, the first argument is the
anonymous function:

@smallexample
(lambda (arg) (/ arg 50))
@end smallexample

@noindent
and the second argument is @code{full-range}, which will be bound to
@code{list-for-graph}.

@need 1250
The whole expression looks like this:

@smallexample
(mapcar (lambda (arg) (/ arg 50)) full-range))
@end smallexample

@xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs Lisp
Reference Manual}, for more about @code{mapcar}.

Using the @code{one-fiftieth} function, we can generate a list in which each
element is one-fiftieth the size of the corresponding element in
@code{list-for-graph}.

@smallexample
@group
(setq fiftieth-list-for-graph
      (one-fiftieth list-for-graph))
@end group
@end smallexample

@need 1250
The resulting list looks like this:

@smallexample
@group
(10 20 19 15 11 9 6 5 4 3 3 2 2
1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4)
@end group
@end smallexample

@noindent
This, we are almost ready to print! (We also notice the loss of information:
many of the higher ranges are 0, meaning that fewer than 50 defuns had that
many words or symbols---but not necessarily meaning that none had that many
words or symbols.)

@node Een andere bug
@appendixsubsec Another Bug @dots{} Most Insidious
@cindex Bug, most insidious type
@cindex Insidious type of bug

I said ``almost ready to print''! Of course, there is a bug in the
@code{print-graph} function @dots{} It has a @code{vertical-step} option,
but not a @code{horizontal-step} option.  The @code{top-of-range} scale goes
from 10 to 300 by tens.  But the @code{print-graph} function will print only
by ones.

This is a classic example of what some consider the most insidious type of
bug, the bug of omission.  This is not the kind of bug you can find by
studying the code, for it is not in the code; it is an omitted feature.
Your best actions are to try your program early and often; and try to
arrange, as much as you can, to write code that is easy to understand and
easy to change.  Try to be aware, whenever you can, that whatever you have
written, @emph{will} be rewritten, if not soon, eventually.  A hard maxim to
follow.

It is the @code{print-X-axis-numbered-line} function that needs the work;
and then the @code{print-X-axis} and the @code{print-graph} functions need
to be adapted.  Not much needs to be done; there is one nicety: the numbers
ought to line up under the tic marks.  This takes a little thought.

@need 1250
Here is the corrected @code{print-X-axis-numbered-line}:

@smallexample
@group
(defun print-X-axis-numbered-line
  (number-of-X-tics X-axis-leading-spaces
   &optional horizontal-step)
  "Print line of X-axis numbers"
  (let ((number X-axis-label-spacing)
        (horizontal-step (or horizontal-step 1)))
@end group
@group
    (insert X-axis-leading-spaces)
    ;; @r{Delete extra leading spaces.}
    (delete-char
     (- (1-
         (length (number-to-string horizontal-step)))))
    (insert (concat
             (make-string
@end group
@group
              ;; @r{Insert white space.}
              (-  (* symbol-width
                     X-axis-label-spacing)
                  (1-
                   (length
                    (number-to-string horizontal-step)))
                  2)
              ? )
             (number-to-string
              (* number horizontal-step))))
@end group
@group
    ;; @r{Insert remaining numbers.}
    (setq number (+ number X-axis-label-spacing))
    (while (> number-of-X-tics 1)
      (insert (X-axis-element
               (* number horizontal-step)))
      (setq number (+ number X-axis-label-spacing))
      (setq number-of-X-tics (1- number-of-X-tics)))))
@end group
@end smallexample

@need 1500
If you are reading this in Info, you can see the new versions of
@code{print-X-axis} @code{print-graph} and evaluate them.  If you are
reading this in a printed book, you can see the changed lines here (the full
text is too much to print).

@iftex
@smallexample
@group
(defun print-X-axis (numbers-list horizontal-step)
  @dots{}
    (print-X-axis-numbered-line
     tic-number leading-spaces horizontal-step))
@end group
@end smallexample

@smallexample
@group
(defun print-graph
  (numbers-list
   &optional vertical-step horizontal-step)
  @dots{}
    (print-X-axis numbers-list horizontal-step))
@end group
@end smallexample
@end iftex

@ifnottex
@smallexample
@group
(defun print-X-axis (numbers-list horizontal-step)
  "Print X axis labels to length of NUMBERS-LIST.
Optionally, HORIZONTAL-STEP, a positive integer,
specifies how much an X  axis label increments for
each column."
@end group
@group
;; Value of symbol-width and full-Y-label-width
;; are passed by print-graph.
  (let* ((leading-spaces
          (make-string full-Y-label-width ? ))
       ;; symbol-width @r{is provided by} graph-body-print
       (tic-width (* symbol-width X-axis-label-spacing))
       (X-length (length numbers-list))
@end group
@group
       (X-tic
        (concat
         (make-string
          ;; @r{Make a string of blanks.}
          (-  (* symbol-width X-axis-label-spacing)
              (length X-axis-tic-symbol))
          ? )
@end group
@group
         ;; @r{Concatenate blanks with tic symbol.}
         X-axis-tic-symbol))
       (tic-number
        (if (zerop (% X-length tic-width))
            (/ X-length tic-width)
          (1+ (/ X-length tic-width)))))
@end group

@group
    (print-X-axis-tic-line
     tic-number leading-spaces X-tic)
    (insert "\n")
    (print-X-axis-numbered-line
     tic-number leading-spaces horizontal-step)))
@end group
@end smallexample

@smallexample
@group
(defun print-graph
  (numbers-list &optional vertical-step horizontal-step)
  "Print labeled bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values.
@end group

@group
Optionally, VERTICAL-STEP, a positive integer,
specifies how much a Y axis label increments for
each line.  For example, a step of 5 means that
each row is five units.
@end group

@group
Optionally, HORIZONTAL-STEP, a positive integer,
specifies how much an X  axis label increments for
each column."
  (let* ((symbol-width (length graph-blank))
         ;; @code{height} @r{is both the largest number}
         ;; @r{and the number with the most digits.}
         (height (apply 'max numbers-list))
@end group
@group
         (height-of-top-line
          (if (zerop (% height Y-axis-label-spacing))
              height
            ;; @r{else}
            (* (1+ (/ height Y-axis-label-spacing))
               Y-axis-label-spacing)))
@end group
@group
         (vertical-step (or vertical-step 1))
         (full-Y-label-width
          (length
           (concat
            (number-to-string
             (* height-of-top-line vertical-step))
            Y-axis-tic))))
@end group
@group
    (print-Y-axis
     height-of-top-line full-Y-label-width vertical-step)
    (graph-body-print
        numbers-list height-of-top-line symbol-width)
    (print-X-axis numbers-list horizontal-step)))
@end group
@end smallexample
@end ifnottex

@c qqq
@ignore
Graphing Definitions Re-listed

@need 1250
Here are all the graphing definitions in their final form:

@smallexample
@group
(defvar top-of-ranges
 '(10  20  30  40  50
   60  70  80  90 100
  110 120 130 140 150
  160 170 180 190 200
  210 220 230 240 250)
 "List specifying ranges for `defuns-per-range'.")
@end group

@group
(defvar graph-symbol "*"
  "String used as symbol in graph, usually an asterisk.")
@end group

@group
(defvar graph-blank " "
  "String used as blank in graph, usually a blank space.
graph-blank must be the same number of columns wide
as graph-symbol.")
@end group

@group
(defvar Y-axis-tic " - "
   "String that follows number in a Y axis label.")
@end group

@group
(defvar Y-axis-label-spacing 5
  "Number of lines from one Y axis label to next.")
@end group

@group
(defvar X-axis-tic-symbol "|"
  "String to insert to point to a column in X axis.")
@end group

@group
(defvar X-axis-label-spacing
  (if (boundp 'graph-blank)
      (* 5 (length graph-blank)) 5)
  "Number of units from one X axis label to next.")
@end group
@end smallexample

@smallexample
@group
(defun count-words-in-defun ()
  "Return the number of words and symbols in a defun."
  (beginning-of-defun)
  (let ((count 0)
        (end (save-excursion (end-of-defun) (point))))
@end group

@group
    (while
        (and (< (point) end)
             (re-search-forward
              "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
              end t))
      (setq count (1+ count)))
    count))
@end group
@end smallexample

@smallexample
@group
(defun lengths-list-file (filename)
  "Return list of definitions' lengths within FILE.
The returned list is a list of numbers.
Each number is the number of words or
symbols in one function definition."
@end group

@group
  (message "Working on `%s' ... " filename)
  (save-excursion
    (let ((buffer (find-file-noselect filename))
          (lengths-list))
      (set-buffer buffer)
      (setq buffer-read-only t)
      (widen)
      (goto-char (point-min))
@end group

@group
      (while (re-search-forward "^(defun" nil t)
        (setq lengths-list
              (cons (count-words-in-defun) lengths-list)))
      (kill-buffer buffer)
      lengths-list)))
@end group
@end smallexample

@smallexample
@group
(defun lengths-list-many-files (list-of-files)
  "Return list of lengths of defuns in LIST-OF-FILES."
  (let (lengths-list)
;;; @r{true-or-false-test}
    (while list-of-files
      (setq lengths-list
            (append
             lengths-list
@end group
@group
;;; @r{Generate a lengths' list.}
             (lengths-list-file
              (expand-file-name (car list-of-files)))))
;;; @r{Make files' list shorter.}
      (setq list-of-files (cdr list-of-files)))
;;; @r{Return final value of lengths' list.}
    lengths-list))
@end group
@end smallexample

@smallexample
@group
(defun defuns-per-range (sorted-lengths top-of-ranges)
  "SORTED-LENGTHS defuns in each TOP-OF-RANGES range."
  (let ((top-of-range (car top-of-ranges))
        (number-within-range 0)
        defuns-per-range-list)
@end group

@group
    ;; @r{Outer loop.}
    (while top-of-ranges

      ;; @r{Inner loop.}
      (while (and
              ;; @r{Need number for numeric test.}
              (car sorted-lengths)
              (< (car sorted-lengths) top-of-range))

        ;; @r{Count number of definitions within current range.}
        (setq number-within-range (1+ number-within-range))
        (setq sorted-lengths (cdr sorted-lengths)))
@end group

@group
      ;; @r{Exit inner loop but remain within outer loop.}

      (setq defuns-per-range-list
            (cons number-within-range defuns-per-range-list))
      (setq number-within-range 0)      ; @r{Reset count to zero.}

      ;; @r{Move to next range.}
      (setq top-of-ranges (cdr top-of-ranges))
      ;; @r{Specify next top of range value.}
      (setq top-of-range (car top-of-ranges)))
@end group

@group
    ;; @r{Exit outer loop and count the number of defuns larger than}
    ;; @r{  the largest top-of-range value.}
    (setq defuns-per-range-list
          (cons
           (length sorted-lengths)
           defuns-per-range-list))

    ;; @r{Return a list of the number of definitions within each range,}
    ;; @r{  smallest to largest.}
    (nreverse defuns-per-range-list)))
@end group
@end smallexample

@smallexample
@group
(defun column-of-graph (max-graph-height actual-height)
  "Return list of MAX-GRAPH-HEIGHT strings;
ACTUAL-HEIGHT are graph-symbols.
The graph-symbols are contiguous entries at the end
of the list.
The list will be inserted as one column of a graph.
The strings are either graph-blank or graph-symbol."
@end group

@group
  (let ((insert-list nil)
        (number-of-top-blanks
         (- max-graph-height actual-height)))

    ;; @r{Fill in @code{graph-symbols}.}
    (while (> actual-height 0)
      (setq insert-list (cons graph-symbol insert-list))
      (setq actual-height (1- actual-height)))
@end group

@group
    ;; @r{Fill in @code{graph-blanks}.}
    (while (> number-of-top-blanks 0)
      (setq insert-list (cons graph-blank insert-list))
      (setq number-of-top-blanks
            (1- number-of-top-blanks)))

    ;; @r{Return whole list.}
    insert-list))
@end group
@end smallexample

@smallexample
@group
(defun Y-axis-element (number full-Y-label-width)
  "Construct a NUMBERed label element.
A numbered element looks like this `  5 - ',
and is padded as needed so all line up with
the element for the largest number."
@end group
@group
  (let* ((leading-spaces
         (- full-Y-label-width
            (length
             (concat (number-to-string number)
                     Y-axis-tic)))))
@end group
@group
    (concat
     (make-string leading-spaces ? )
     (number-to-string number)
     Y-axis-tic)))
@end group
@end smallexample

@smallexample
@group
(defun print-Y-axis
  (height full-Y-label-width &optional vertical-step)
  "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH.
Height must be the  maximum height of the graph.
Full width is the width of the highest label element.
Optionally, print according to VERTICAL-STEP."
@end group
@group
;; Value of height and full-Y-label-width
;; are passed by 'print-graph'.
  (let ((start (point)))
    (insert-rectangle
     (Y-axis-column height full-Y-label-width vertical-step))
@end group
@group
    ;; @r{Place point ready for inserting graph.}
    (goto-char start)
    ;; @r{Move point forward by value of} full-Y-label-width
    (forward-char full-Y-label-width)))
@end group
@end smallexample

@smallexample
@group
(defun print-X-axis-tic-line
  (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
  "Print ticks for X axis."
    (insert X-axis-leading-spaces)
    (insert X-axis-tic-symbol)  ; @r{Under first column.}
@end group
@group
    ;; @r{Insert second tic in the right spot.}
    (insert (concat
             (make-string
              (-  (* symbol-width X-axis-label-spacing)
                  ;; @r{Insert white space up to second tic symbol.}
                  (* 2 (length X-axis-tic-symbol)))
              ? )
             X-axis-tic-symbol))
@end group
@group
    ;; @r{Insert remaining ticks.}
    (while (> number-of-X-tics 1)
      (insert X-axis-tic-element)
      (setq number-of-X-tics (1- number-of-X-tics))))
@end group
@end smallexample

@smallexample
@group
(defun X-axis-element (number)
  "Construct a numbered X axis element."
  (let ((leading-spaces
         (-  (* symbol-width X-axis-label-spacing)
             (length (number-to-string number)))))
    (concat (make-string leading-spaces ? )
            (number-to-string number))))
@end group
@end smallexample

@smallexample
@group
(defun graph-body-print (numbers-list height symbol-width)
  "Print a bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values.
HEIGHT is maximum height of graph.
SYMBOL-WIDTH is number of each column."
@end group
@group
  (let (from-position)
    (while numbers-list
      (setq from-position (point))
      (insert-rectangle
       (column-of-graph height (car numbers-list)))
      (goto-char from-position)
      (forward-char symbol-width)
@end group
@group
      ;; @r{Draw graph column by column.}
      (sit-for 0)
      (setq numbers-list (cdr numbers-list)))
    ;; @r{Place point for X axis labels.}
    (forward-line height)
    (insert "\n")))
@end group
@end smallexample

@smallexample
@group
(defun Y-axis-column
  (height width-of-label &optional vertical-step)
  "Construct list of labels for Y axis.
HEIGHT is maximum height of graph.
WIDTH-OF-LABEL is maximum width of label.
@end group
@group
VERTICAL-STEP, an option, is a positive integer
that specifies how much a Y axis label increments
for each line.  For example, a step of 5 means
that each line is five units of the graph."
  (let (Y-axis
        (number-per-line (or vertical-step 1)))
@end group
@group
    (while (> height 1)
      (if (zerop (% height Y-axis-label-spacing))
          ;; @r{Insert label.}
          (setq Y-axis
                (cons
                 (Y-axis-element
                  (* height number-per-line)
                  width-of-label)
                 Y-axis))
@end group
@group
        ;; @r{Else, insert blanks.}
        (setq Y-axis
              (cons
               (make-string width-of-label ? )
               Y-axis)))
      (setq height (1- height)))
@end group
@group
    ;; @r{Insert base line.}
    (setq Y-axis (cons (Y-axis-element
                        (or vertical-step 1)
                        width-of-label)
                       Y-axis))
    (nreverse Y-axis)))
@end group
@end smallexample

@smallexample
@group
(defun print-X-axis-numbered-line
  (number-of-X-tics X-axis-leading-spaces
   &optional horizontal-step)
  "Print line of X-axis numbers"
  (let ((number X-axis-label-spacing)
        (horizontal-step (or horizontal-step 1)))
@end group
@group
    (insert X-axis-leading-spaces)
    ;; line up number
    (delete-char (- (1- (length (number-to-string horizontal-step)))))
    (insert (concat
             (make-string
              ;; @r{Insert white space up to next number.}
              (-  (* symbol-width X-axis-label-spacing)
                  (1- (length (number-to-string horizontal-step)))
                  2)
              ? )
             (number-to-string (* number horizontal-step))))
@end group
@group
    ;; @r{Insert remaining numbers.}
    (setq number (+ number X-axis-label-spacing))
    (while (> number-of-X-tics 1)
      (insert (X-axis-element (* number horizontal-step)))
      (setq number (+ number X-axis-label-spacing))
      (setq number-of-X-tics (1- number-of-X-tics)))))
@end group
@end smallexample

@smallexample
@group
(defun print-X-axis (numbers-list horizontal-step)
  "Print X axis labels to length of NUMBERS-LIST.
Optionally, HORIZONTAL-STEP, a positive integer,
specifies how much an X  axis label increments for
each column."
@end group
@group
;; Value of symbol-width and full-Y-label-width
;; are passed by 'print-graph'.
  (let* ((leading-spaces
          (make-string full-Y-label-width ? ))
       ;; symbol-width @r{is provided by} graph-body-print
       (tic-width (* symbol-width X-axis-label-spacing))
       (X-length (length numbers-list))
@end group
@group
       (X-tic
        (concat
         (make-string
          ;; @r{Make a string of blanks.}
          (-  (* symbol-width X-axis-label-spacing)
              (length X-axis-tic-symbol))
          ? )
@end group
@group
         ;; @r{Concatenate blanks with tic symbol.}
         X-axis-tic-symbol))
       (tic-number
        (if (zerop (% X-length tic-width))
            (/ X-length tic-width)
          (1+ (/ X-length tic-width)))))
@end group

@group
    (print-X-axis-tic-line
     tic-number leading-spaces X-tic)
    (insert "\n")
    (print-X-axis-numbered-line
     tic-number leading-spaces horizontal-step)))
@end group
@end smallexample

@smallexample
@group
(defun one-fiftieth (full-range)
  "Return list, each number of which is 1/50th previous."
 (mapcar (lambda (arg) (/ arg 50)) full-range))
@end group
@end smallexample

@smallexample
@group
(defun print-graph
  (numbers-list &optional vertical-step horizontal-step)
  "Print labeled bar graph of the NUMBERS-LIST.
The numbers-list consists of the Y-axis values.
@end group

@group
Optionally, VERTICAL-STEP, a positive integer,
specifies how much a Y axis label increments for
each line.  For example, a step of 5 means that
each row is five units.
@end group

@group
Optionally, HORIZONTAL-STEP, a positive integer,
specifies how much an X  axis label increments for
each column."
  (let* ((symbol-width (length graph-blank))
         ;; @code{height} @r{is both the largest number}
         ;; @r{and the number with the most digits.}
         (height (apply 'max numbers-list))
@end group
@group
         (height-of-top-line
          (if (zerop (% height Y-axis-label-spacing))
              height
            ;; @r{else}
            (* (1+ (/ height Y-axis-label-spacing))
               Y-axis-label-spacing)))
@end group
@group
         (vertical-step (or vertical-step 1))
         (full-Y-label-width
          (length
           (concat
            (number-to-string
             (* height-of-top-line vertical-step))
            Y-axis-tic))))
@end group
@group

    (print-Y-axis
     height-of-top-line full-Y-label-width vertical-step)
    (graph-body-print
        numbers-list height-of-top-line symbol-width)
    (print-X-axis numbers-list horizontal-step)))
@end group
@end smallexample
@c qqq
@end ignore

@page
@node Finale afgedrukte grafiek
@appendixsubsec The Printed Graph

When made and installed, you can call the @code{print-graph} command like
this:
@sp 1

@smallexample
@group
(print-graph fiftieth-list-for-graph 50 10)
@end group
@end smallexample
@sp 1

@noindent
Here is the graph:
@sp 2

@smallexample
@group
1000 -  *
        **
        **
        **
        **
 750 -  ***
        ***
        ***
        ***
        ****
 500 - *****
       ******
       ******
       ******
       *******
 250 - ********
       *********                     *
       ***********                   *
       *************                 *
  50 - ***************** *           *
       |   |    |    |    |    |    |    |
      10  50  100  150  200  250  300  350
@end group
@end smallexample

@sp 2

@noindent
The largest group of functions contain 10--19 words and symbols each.

@node Vrije software en vrije handleidingen
@appendix Vrije software en vrije handleidingen

@strong{by Richard M. Stallman}
@sp 1

The biggest deficiency in free operating systems is not in the software---it
is the lack of good free manuals that we can include in these systems.  Many
of our most important programs do not come with full manuals.  Documentation
is an essential part of any software package; when an important free
software package does not come with a free manual, that is a major gap.  We
have many such gaps today.

Once upon a time, many years ago, I thought I would learn Perl.  I got a
copy of a free manual, but I found it hard to read.  When I asked Perl users
about alternatives, they told me that there were better introductory
manuals---but those were not free.

Why was this? The authors of the good manuals had written them for O'Reilly
Associates, which published them with restrictive terms---no copying, no
modification, source files not available---which exclude them from the free
software community.

That wasn't the first time this sort of thing has happened, and (to our
community's great loss) it was far from the last.  Proprietary manual
publishers have enticed a great many authors to restrict their manuals since
then.  Many times I have heard a GNU user eagerly tell me about a manual
that he is writing, with which he expects to help the GNU project---and then
had my hopes dashed, as he proceeded to explain that he had signed a
contract with a publisher that would restrict it so that we cannot use it.

Given that writing good English is a rare skill among programmers, we can
ill afford to lose manuals this way.

Free documentation, like free software, is a matter of freedom, not price.
The problem with these manuals was not that O'Reilly Associates charged a
price for printed copies---that in itself is fine.  The Free Software
Foundation @uref{https://shop.fsf.org, sells printed copies} of free
@uref{https://www.gnu.org/doc/doc.html, GNU manuals}, too.  But GNU manuals
are available in source code form, while these manuals are available only on
paper.  GNU manuals come with permission to copy and modify; the Perl
manuals do not.  These restrictions are the problems.

The criterion for a free manual is pretty much the same as for free
software: it is a matter of giving all users certain freedoms.
Redistribution (including commercial redistribution) must be permitted, so
that the manual can accompany every copy of the program, on-line or on
paper.  Permission for modification is crucial too.

As a general rule, I don't believe that it is essential for people to have
permission to modify all sorts of articles and books.  The issues for
writings are not necessarily the same as those for software.  For example, I
don't think you or I are obliged to give permission to modify articles like
this one, which describe our actions and our views.

But there is a particular reason why the freedom to modify is crucial for
documentation for free software.  When people exercise their right to modify
the software, and add or change its features, if they are conscientious they
will change the manual too---so they can provide accurate and usable
documentation with the modified program.  A manual which forbids programmers
to be conscientious and finish the job, or more precisely requires them to
write a new manual from scratch if they change the program, does not fill
our community's needs.

While a blanket prohibition on modification is unacceptable, some kinds of
limits on the method of modification pose no problem.  For example,
requirements to preserve the original author's copyright notice, the
distribution terms, or the list of authors, are ok.  It is also no problem
to require modified versions to include notice that they were modified, even
to have entire sections that may not be deleted or changed, as long as these
sections deal with nontechnical topics.  (Some GNU manuals have them.)

These kinds of restrictions are not a problem because, as a practical
matter, they don't stop the conscientious programmer from adapting the
manual to fit the modified program.  In other words, they don't block the
free software community from making full use of the manual.

However, it must be possible to modify all the technical content of the
manual, and then distribute the result in all the usual media, through all
the usual channels; otherwise, the restrictions do block the community, the
manual is not free, and so we need another manual.

Unfortunately, it is often hard to find someone to write another manual when
a proprietary manual exists.  The obstacle is that many users think that a
proprietary manual is good enough---so they don't see the need to write a
free manual.  They do not see that the free operating system has a gap that
needs filling.

Why do users think that proprietary manuals are good enough? Some have not
considered the issue.  I hope this article will do something to change that.

Other users consider proprietary manuals acceptable for the same reason so
many people consider proprietary software acceptable: they judge in purely
practical terms, not using freedom as a criterion.  These people are
entitled to their opinions, but since those opinions spring from values
which do not include freedom, they are no guide for those of us who do value
freedom.

Please spread the word about this issue.  We continue to lose manuals to
proprietary publishing.  If we spread the word that proprietary manuals are
not sufficient, perhaps the next person who wants to help GNU by writing
documentation will realize, before it is too late, that he must above all
make it free.

We can also encourage commercial publishers to sell free, copylefted manuals
instead of proprietary ones.  One way you can help this is to check the
distribution terms of a manual before you buy it, and prefer copylefted
manuals to non-copylefted ones.

@sp 2
@noindent
Opmerking: De Free Software Foundation onderhoudt een pagina op hun website
met een lijst van boeken die vrij beschikbaar zijn bij andere uitgevers:@*
@uref{https://www.gnu.org/doc/other-free-books.html}

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

@cindex FDL, GNU Free Documentation License
@include doclicense.texi

@node Index
@unnumbered Index

@ignore
MENU ENTRY: NODE NAME.
@end ignore

@printindex cp

@iftex
@c Place biographical information on right-hand (verso) page

@tex
\par\vfill\supereject
\ifodd\pageno
    \global\evenheadline={\hfil} \global\evenfootline={\hfil}
    \global\oddheadline={\hfil} \global\oddfootline={\hfil}
    %\page\hbox{}\page
\else
%    \par\vfill\supereject
    \global\evenheadline={\hfil} \global\evenfootline={\hfil}
    \global\oddheadline={\hfil} \global\oddfootline={\hfil}
    %\page\hbox{}%\page
    %\page\hbox{}%\page
\fi
@end tex

@c page
@w{ }

@c ================ Biographical information ================

@w{ }
@sp 8
@center Over de auteur
@sp 1
@end iftex

@ifnottex
@node Over de auteur
@unnumbered Over de auteur
@end ifnottex

@quotation
Robert J. Chassell (1946--2017) begon te werken met GNU Emacs in 1985. Hij
schreef en bewerte tekst, gaf les in Emacs en Emacs Lisp en sprak over de
hele wereld over software vrijheid. Chassel was oprichtend directeur en
penningmeester van de Free Software Foundation, Inc. He was co-auteur van de
@cite{Texinfo} handleiding, en bewerkte meer dan een dozijn andere
boeken. Hij studeerde af aan de universiteit van Cambridge in Engeland. Hij
had een blijvende interesse in sociale en economische geshiedenis en vloog
zijn eigen vliegtuig.

@uref{https://www.fsf.org/blogs/community/goodbye-to-bob-chassell, "Goodbye
to Bob Chassell"}
@end quotation

@c @page
@c @w{ }
@c
@c @c Prevent page number on blank verso, so eject it first.
@c @tex
@c \par\vfill\supereject
@c @end tex

@c @iftex
@c @headings off
@c @evenheading @thispage @| @| @thistitle
@c @oddheading            @| @| @thispage
@c @end iftex

@bye
