+++ /dev/null
-START-INFO-DIR-ENTRY
-* Emacs Lisp Intro: (eintr).
- A simple introduction to Emacs Lisp programming.
-END-INFO-DIR-ENTRY
-
-Short Contents
-**************
-
-An Introduction to Programming in Emacs Lisp
-Preface
-List Processing
-Practicing Evaluation
-How To Write Function Definitions
-A Few Buffer-Related Functions
-A Few More Complex Functions
-Narrowing and Widening
-`car', `cdr', `cons': Fundamental Functions
-Cutting and Storing Text
-How Lists are Implemented
-Yanking Text Back
-Loops and Recursion
-Regular Expression Searches
-Counting: Repetition and Regexps
-Counting Words in a `defun'
-Readying a Graph
-Your `.emacs' File
-Debugging
-Conclusion
-The `the-the' Function
-Handling the Kill Ring
-A Graph with Labelled Axes
-GNU Free Documentation License
-Index
-About the Author
-
-
-Table of Contents
-*****************
-
-
-An Introduction to Programming in Emacs Lisp
-
-Preface
- Why Study Emacs Lisp?
- On Reading this Text
- For Whom This is Written
- Lisp History
- A Note for Novices
- Thank You
-
-List Processing
- Lisp Lists
- Numbers, Lists inside of Lists
- Lisp Atoms
- Whitespace in Lists
- GNU Emacs Helps You Type Lists
- Run a Program
- Generate an Error Message
- Symbol Names and Function Definitions
- The Lisp Interpreter
- Complications
- Byte Compiling
- Evaluation
- Evaluating Inner Lists
- Variables
- `fill-column', an Example Variable
- Error Message for a Symbol Without a Function
- Error Message for a Symbol Without a Value
- Arguments
- Arguments' Data Types
- An Argument as the Value of a Variable or List
- Variable Number of Arguments
- Using the Wrong Type Object as an Argument
- The `message' Function
- Setting the Value of a Variable
- Using `set'
- Using `setq'
- Counting
- Summary
- Exercises
-
-Practicing Evaluation
- How to Evaluate
- Buffer Names
- Getting Buffers
- Switching Buffers
- Buffer Size and the Location of Point
- Exercise
-
-How To Write Function Definitions
- An Aside about Primitive Functions
- The `defun' Special Form
- Install a Function Definition
- The effect of installation
- Change a Function Definition
- Make a Function Interactive
- An Interactive `multiply-by-seven', An Overview
- An Interactive `multiply-by-seven'
- Different Options for `interactive'
- Install Code Permanently
- `let'
- `let' Prevents Confusion
- The Parts of a `let' Expression
- Sample `let' Expression
- Uninitialized Variables in a `let' Statement
- The `if' Special Form
- `if' in more detail
- The `type-of-animal' Function in Detail
- If-then-else Expressions
- Truth and Falsehood in Emacs Lisp
- An explanation of `nil'
- `save-excursion'
- Point and Mark
- Template for a `save-excursion' Expression
- Review
- Exercises
-
-A Few Buffer-Related Functions
- Finding More Information
- A Simplified `beginning-of-buffer' Definition
- The Definition of `mark-whole-buffer'
- An overview of `mark-whole-buffer'
- Body of `mark-whole-buffer'
- The Definition of `append-to-buffer'
- An Overview of `append-to-buffer'
- The `append-to-buffer' Interactive Expression
- The Body of `append-to-buffer'
- `save-excursion' in `append-to-buffer'
- Review
- Exercises
-
-A Few More Complex Functions
- The Definition of `copy-to-buffer'
- The Definition of `insert-buffer'
- The Code for `insert-buffer'
- The Interactive Expression in `insert-buffer'
- A Read-only Buffer
- `b' in an Interactive Expression
- The Body of the `insert-buffer' Function
- `insert-buffer' With an `if' Instead of an `or'
- The `or' in the Body
- The `let' Expression in `insert-buffer'
- Complete Definition of `beginning-of-buffer'
- Optional Arguments
- `beginning-of-buffer' with an Argument
- Disentangle `beginning-of-buffer'
- What happens in a large buffer
- What happens in a small buffer
- The Complete `beginning-of-buffer'
- Review
- `optional' Argument Exercise
-
-Narrowing and Widening
- The Advantages of Narrowing
- The `save-restriction' Special Form
- `what-line'
- Exercise with Narrowing
-
-`car', `cdr', `cons': Fundamental Functions
- Strange Names
- `car' and `cdr'
- `cons'
- Build a list
- Find the Length of a List: `length'
- `nthcdr'
- `nth'
- `setcar'
- `setcdr'
- Exercise
-
-Cutting and Storing Text
- Storing Text in a List
- `zap-to-char'
- The Complete `zap-to-char' Implementation
- The `interactive' Expression
- The Body of `zap-to-char'
- The `search-forward' Function
- The `progn' Special Form
- Summing up `zap-to-char'
- `kill-region'
- The Complete `kill-region' Definition
- `condition-case'
- `delete-and-extract-region'
- Digression into C
- Initializing a Variable with `defvar'
- Seeing the Current Value of a Variable
- `defvar' and an asterisk
- `copy-region-as-kill'
- The complete `copy-region-as-kill' function definition
- The Body of `copy-region-as-kill'
- `last-command' and `this-command'
- The `kill-append' function
- The `kill-new' function
- Review
- Searching Exercises
-
-How Lists are Implemented
- Lists diagrammed
- Symbols as a Chest of Drawers
- Exercise
-
-Yanking Text Back
- Kill Ring Overview
- The `kill-ring-yank-pointer' Variable
- Exercises with `yank' and `nthcdr'
-
-Loops and Recursion
- `while'
- Looping with `while'
- A `while' Loop and a List
- An Example: `print-elements-of-list'
- A Loop with an Incrementing Counter
- Example with incrementing counter
- The parts of the function definition
- Putting the function definition together
- Loop with a Decrementing Counter
- Example with decrementing counter
- The parts of the function definition
- Putting the function definition together
- Save your time: `dolist' and `dotimes'
- The `dolist' Macro
- The `dotimes' Macro
- Recursion
- Building Robots: Extending the Metaphor
- The Parts of a Recursive Definition
- Recursion with a List
- Recursion in Place of a Counter
- An argument of 1 or 2
- An argument of 3 or 4
- Recursion Example Using `cond'
- Recursive Patterns
- Recursive Pattern: _every_
- Recursive Pattern: _accumulate_
- Recursive Pattern: _keep_
- Recursion without Deferments
- No Deferment Solution
- Looping Exercise
-
-Regular Expression Searches
- The Regular Expression for `sentence-end'
- The `re-search-forward' Function
- `forward-sentence'
- Complete `forward-sentence' function definition
- The `while' loops
- The regular expression search
- `forward-paragraph': a Goldmine of Functions
- Shortened `forward-paragraph' function definition
- The `let*' expression
- The forward motion `while' loop
- Between paragraphs
- Within paragraphs
- No fill prefix
- With a fill prefix
- Summary
- Create Your Own `TAGS' File
- Review
- Exercises with `re-search-forward'
-
-Counting: Repetition and Regexps
- Counting words
- The `count-words-region' Function
- Designing `count-words-region'
- The Whitespace Bug in `count-words-region'
- Count Words Recursively
- Exercise: Counting Punctuation
-
-Counting Words in a `defun'
- Divide and Conquer
- What to Count?
- What Constitutes a Word or Symbol?
- The `count-words-in-defun' Function
- Count Several `defuns' Within a File
- Find a File
- `lengths-list-file' in Detail
- Count Words in `defuns' in Different Files
- Determine the lengths of `defuns'
- The `append' Function
- Recursively Count Words in Different Files
- Prepare the Data for Display in a Graph
- Sorting Lists
- Making a List of Files
- Counting function definitions
-
-Readying a Graph
- Printing the Columns of a Graph
- The `graph-body-print' Function
- The `recursive-graph-body-print' Function
- Need for Printed Axes
- Exercise
-
-Your `.emacs' File
- Emacs' Default Configuration
- Site-wide Initialization Files
- Specifying Variables using `defcustom'
- Beginning a `.emacs' File
- Text and Auto Fill Mode
- Mail Aliases
- Indent Tabs Mode
- Some Keybindings
- Keymaps
- Loading Files
- Autoloading
- A Simple Extension: `line-to-top-of-window'
- X11 Colors
- Miscellaneous Settings for a `.emacs' File
- A Modified Mode Line
-
-Debugging
- `debug'
- `debug-on-entry'
- `debug-on-quit' and `(debug)'
- The `edebug' Source Level Debugger
- Debugging Exercises
-
-Conclusion
-
-The `the-the' Function
-
-Handling the Kill Ring
- The `rotate-yank-pointer' Function
- `rotate-yank-pointer' in Outline
- The Body of `rotate-yank-pointer'
- Digression about the word `error'
- The else-part of the `if' expression
- The `%' remainder function
- Using `%' in `rotate-yank-pointer'
- Pointing to the last element
- `yank'
- Passing the argument
- Passing a negative argument
- `yank-pop'
-
-A Graph with Labelled Axes
- Labelled Example Graph
- The `print-graph' Varlist
- The `print-Y-axis' Function
- What height should the label be?
- Side Trip: Compute a Remainder
- Construct a Y Axis Element
- Create a Y Axis Column
- The Not Quite Final Version of `print-Y-axis'
- The `print-X-axis' Function
- Similarities and differences
- X Axis Tic Marks
- Printing the Whole Graph
- Changes for the Final Version
- Testing `print-graph'
- Graphing Numbers of Words and Symbols
- A `lambda' Expression: Useful Anonymity
- The `mapcar' Function
- Another Bug ... Most Insidious
- The Printed Graph
-
-GNU Free Documentation License
-
-Index
-
-About the Author
-
-
-An Introduction to Programming in Emacs Lisp
-********************************************
-
-This is an introduction to `Programming in Emacs Lisp', for people
-who are not programmers.
-
-Edition 2.07, 2002 Aug 23
-
-Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2002
-Free Software Foundation, Inc.
-
-
-Published by the Free Software Foundation, Inc.
-59 Temple Place, Suite 330
-Boston, MA 02111-1307 USA
-Edition 2.07, 2002 Aug 23
-
-ISBN 1-882114-43-4
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; there
-being no Invariant Section, with the Front-Cover Texts being "A GNU
-Manual", and with the Back-Cover Texts as in (a) below. A copy of
-the license is included in the section entitled "GNU Free
-Documentation License".
-
-(a) The FSF's Back-Cover Text is: "You have freedom to copy and
-modify this GNU Manual, like GNU software. Copies published by the
-Free Software Foundation raise funds for GNU development."
-This master menu first lists each chapter and index; then it lists
-every node in every chapter.
-
-Preface
-*******
-
-Most of the GNU Emacs integrated environment is written in the
-programming language called Emacs Lisp. The code written in this
-programming language is the software--the sets of instructions--that
-tell the computer what to do when you give it commands. Emacs is
-designed so that you can write new code in Emacs Lisp and easily
-install it as an extension to the editor.
-
-(GNU Emacs is sometimes called an "extensible editor", but it does
-much more than provide editing capabilities. It is better to refer to
-Emacs as an "extensible computing environment". However, that phrase
-is quite a mouthful. It is easier to refer to Emacs simply as an
-editor. Moreover, everything you do in Emacs--find the Mayan date
-and phases of the moon, simplify polynomials, debug code, manage
-files, read letters, write books--all these activities are kinds of
-editing in the most general sense of the word.)
-
-Why Study Emacs Lisp?
-=====================
-
-Although Emacs Lisp is usually thought of in association only with
-Emacs, it is a full computer programming language. You can use Emacs
-Lisp as you would any other programming language.
-
-Perhaps you want to understand programming; perhaps you want to extend
-Emacs; or perhaps you want to become a programmer. This introduction
-to Emacs Lisp is designed to get you started: to guide you in
-learning the fundamentals of programming, and more importantly, to
-show you how you can teach yourself to go further.
-
-On Reading this Text
-====================
-
-All through this document, you will see little sample programs you can
-run inside of Emacs. If you read this document in Info inside of GNU
-Emacs, you can run the programs as they appear. (This is easy to do
-and is explained when the examples are presented.) Alternatively,
-you can read this introduction as a printed book while sitting beside
-a computer running Emacs. (This is what I like to do; I like printed
-books.) If you don't have a running Emacs beside you, you can still
-read this book, but in this case, it is best to treat it as a novel
-or as a travel guide to a country not yet visited: interesting, but
-not the same as being there.
-
-Much of this introduction is dedicated to walk-throughs or guided
-tours of code used in GNU Emacs. These tours are designed for two
-purposes: first, to give you familiarity with real, working code
-(code you use every day); and, second, to give you familiarity with
-the way Emacs works. It is interesting to see how a working
-environment is implemented. Also, I hope that you will pick up the
-habit of browsing through source code. You can learn from it and
-mine it for ideas. Having GNU Emacs is like having a dragon's cave
-of treasures.
-
-In addition to learning about Emacs as an editor and Emacs Lisp as a
-programming language, the examples and guided tours will give you an
-opportunity to get acquainted with Emacs as a Lisp programming
-environment. GNU Emacs supports programming and provides tools that
-you will want to become comfortable using, such as `M-.' (the key
-which invokes the `find-tag' command). You will also learn about
-buffers and other objects that are part of the environment. Learning
-about these features of Emacs is like learning new routes around your
-home town.
-
-Finally, I hope to convey some of the skills for using Emacs to learn
-aspects of programming that you don't know. You can often use Emacs
-to help you understand what puzzles you or to find out how to do
-something new. This self-reliance is not only a pleasure, but an
-advantage.
-
-For Whom This is Written
-========================
-
-This text is written as an elementary introduction for people who are
-not programmers. If you are a programmer, you may not be satisfied
-with this primer. The reason is that you may have become expert at
-reading reference manuals and be put off by the way this text is
-organized.
-
-An expert programmer who reviewed this text said to me:
-
- I prefer to learn from reference manuals. I "dive into" each
- paragraph, and "come up for air" between paragraphs.
-
- When I get to the end of a paragraph, I assume that that subject
- is done, finished, that I know everything I need (with the
- possible exception of the case when the next paragraph starts
- talking about it in more detail). I expect that a well written
- reference manual will not have a lot of redundancy, and that it
- will have excellent pointers to the (one) place where the
- information I want is.
-
-This introduction is not written for this person!
-
-Firstly, I try to say everything at least three times: first, to
-introduce it; second, to show it in context; and third, to show it in
-a different context, or to review it.
-
-Secondly, I hardly ever put all the information about a subject in one
-place, much less in one paragraph. To my way of thinking, that
-imposes too heavy a burden on the reader. Instead I try to explain
-only what you need to know at the time. (Sometimes I include a
-little extra information so you won't be surprised later when the
-additional information is formally introduced.)
-
-When you read this text, you are not expected to learn everything the
-first time. Frequently, you need only make, as it were, a `nodding
-acquaintance' with some of the items mentioned. My hope is that I
-have structured the text and given you enough hints that you will be
-alert to what is important, and concentrate on it.
-
-You will need to "dive into" some paragraphs; there is no other way
-to read them. But I have tried to keep down the number of such
-paragraphs. This book is intended as an approachable hill, rather
-than as a daunting mountain.
-
-This introduction to `Programming in Emacs Lisp' has a companion
-document, *Note The GNU Emacs Lisp Reference Manual: (elisp)Top. The
-reference manual has more detail than this introduction. In the
-reference manual, all the information about one topic is concentrated
-in one place. You should turn to it if you are like the programmer
-quoted above. And, of course, after you have read this
-`Introduction', you will find the `Reference Manual' useful when you
-are writing your own programs.
-
-Lisp History
-============
-
-Lisp was first developed in the late 1950s at the Massachusetts
-Institute of Technology for research in artificial intelligence. The
-great power of the Lisp language makes it superior for other purposes
-as well, such as writing editor commands and integrated environments.
-
-GNU Emacs Lisp is largely inspired by Maclisp, which was written at
-MIT in the 1960s. It is somewhat inspired by Common Lisp, which
-became a standard in the 1980s. However, Emacs Lisp is much simpler
-than Common Lisp. (The standard Emacs distribution contains an
-optional extensions file, `cl.el', that adds many Common Lisp
-features to Emacs Lisp.)
-
-A Note for Novices
-==================
-
-If you don't know GNU Emacs, you can still read this document
-profitably. However, I recommend you learn Emacs, if only to learn to
-move around your computer screen. You can teach yourself how to use
-Emacs with the on-line tutorial. To use it, type `C-h t'. (This
-means you press and release the <CTRL> key and the `h' at the same
-time, and then press and release `t'.)
-
-Also, I often refer to one of Emacs' standard commands by listing the
-keys which you press to invoke the command and then giving the name of
-the command in parentheses, like this: `M-C-\' (`indent-region').
-What this means is that the `indent-region' command is customarily
-invoked by typing `M-C-\'. (You can, if you wish, change the keys
-that are typed to invoke the command; this is called "rebinding".
-*Note Keymaps: Keymaps.) The abbreviation `M-C-\' means that you
-type your <META> key, <CTRL> key and <\> key all at the same time.
-(On many modern keyboards the <META> key is labelled <ALT>.)
-Sometimes a combination like this is called a keychord, since it is
-similar to the way you play a chord on a piano. If your keyboard does
-not have a <META> key, the <ESC> key prefix is used in place of it.
-In this case, `M-C-\' means that you press and release your <ESC> key
-and then type the <CTRL> key and the <\> key at the same time. But
-usually `M-C-\' means press the <CTRL> key along with the key that is
-labelled <ALT> and, at the same time, press the <\> key.
-
-In addition to typing a lone keychord, you can prefix what you type
-with `C-u', which is called the `universal argument'. The `C-u'
-keychord passes an argument to the subsequent command. Thus, to
-indent a region of plain text by 6 spaces, mark the region, and then
-type `C-u 6 M-C-\'. (If you do not specify a number, Emacs either
-passes the number 4 to the command or otherwise runs the command
-differently than it would otherwise.) *Note Numeric Arguments:
-(emacs)Arguments.
-
-If you are reading this in Info using GNU Emacs, you can read through
-this whole document just by pressing the space bar, <SPC>. (To learn
-about Info, type `C-h i' and then select Info.)
-
-A note on terminology: when I use the word Lisp alone, I often am
-referring to the various dialects of Lisp in general, but when I speak
-of Emacs Lisp, I am referring to GNU Emacs Lisp in particular.
-
-Thank You
-=========
-
-My thanks to all who helped me with this book. My especial thanks to
-Jim Blandy, Noah Friedman, Jim Kingdon, Roland McGrath, Frank Ritter,
-Randy Smith, Richard M. Stallman, and Melissa Weisshaus. My thanks
-also go to both Philip Johnson and David Stampe for their patient
-encouragement. My mistakes are my own.
-
- Robert J. Chassell
-
-List Processing
-***************
-
-To the untutored eye, Lisp is a strange programming language. In Lisp
-code there are parentheses everywhere. Some people even claim that
-the name stands for `Lots of Isolated Silly Parentheses'. But the
-claim is unwarranted. Lisp stands for LISt Processing, and the
-programming language handles _lists_ (and lists of lists) by putting
-them between parentheses. The parentheses mark the boundaries of the
-list. Sometimes a list is preceded by a single apostrophe or
-quotation mark, `''. Lists are the basis of Lisp.
-
-Lisp Lists
-==========
-
-In Lisp, a list looks like this: `'(rose violet daisy buttercup)'.
-This list is preceded by a single apostrophe. It could just as well
-be written as follows, which looks more like the kind of list you are
-likely to be familiar with:
-
- '(rose
- violet
- daisy
- buttercup)
-
-The elements of this list are the names of the four different flowers,
-separated from each other by whitespace and surrounded by parentheses,
-like flowers in a field with a stone wall around them.
-
-Numbers, Lists inside of Lists
-------------------------------
-
-Lists can also have numbers in them, as in this list: `(+ 2 2)'.
-This list has a plus-sign, `+', followed by two `2's, each separated
-by whitespace.
-
-In Lisp, both data and programs are represented the same way; that is,
-they are both lists of words, numbers, or other lists, separated by
-whitespace and surrounded by parentheses. (Since a program looks like
-data, one program may easily serve as data for another; this is a very
-powerful feature of Lisp.) (Incidentally, these two parenthetical
-remarks are _not_ Lisp lists, because they contain `;' and `.' as
-punctuation marks.)
-
-Here is another list, this time with a list inside of it:
-
- '(this list has (a list inside of it))
-
-The components of this list are the words `this', `list', `has', and
-the list `(a list inside of it)'. The interior list is made up of
-the words `a', `list', `inside', `of', `it'.
-
-Lisp Atoms
-----------
-
-In Lisp, what we have been calling words are called "atoms". This
-term comes from the historical meaning of the word atom, which means
-`indivisible'. As far as Lisp is concerned, the words we have been
-using in the lists cannot be divided into any smaller parts and still
-mean the same thing as part of a program; likewise with numbers and
-single character symbols like `+'. On the other hand, unlike an
-atom, a list can be split into parts. (*Note `car' `cdr' & `cons'
-Fundamental Functions: car cdr & cons.)
-
-In a list, atoms are separated from each other by whitespace. They
-can be right next to a parenthesis.
-
-Technically speaking, a list in Lisp consists of parentheses
-surrounding atoms separated by whitespace or surrounding other lists
-or surrounding both atoms and other lists. A list can have just one
-atom in it or have nothing in it at all. A list with nothing in it
-looks like this: `()', and is called the "empty list". Unlike
-anything else, an empty list is considered both an atom and a list at
-the same time.
-
-The printed representation of both atoms and lists are called
-"symbolic expressions" or, more concisely, "s-expressions". The word
-"expression" by itself can refer to either the printed
-representation, or to the atom or list as it is held internally in the
-computer. Often, people use the term "expression" indiscriminately.
-(Also, in many texts, the word "form" is used as a synonym for
-expression.)
-
-Incidentally, the atoms that make up our universe were named such when
-they were thought to be indivisible; but it has been found that
-physical atoms are not indivisible. Parts can split off an atom or
-it can fission into two parts of roughly equal size. Physical atoms
-were named prematurely, before their truer nature was found. In
-Lisp, certain kinds of atom, such as an array, can be separated into
-parts; but the mechanism for doing this is different from the
-mechanism for splitting a list. As far as list operations are
-concerned, the atoms of a list are unsplittable.
-
-As in English, the meanings of the component letters of a Lisp atom
-are different from the meaning the letters make as a word. For
-example, the word for the South American sloth, the `ai', is
-completely different from the two words, `a', and `i'.
-
-There are many kinds of atom in nature but only a few in Lisp: for
-example, "numbers", such as 37, 511, or 1729, and "symbols", such as
-`+', `foo', or `forward-line'. The words we have listed in the
-examples above are all symbols. In everyday Lisp conversation, the
-word "atom" is not often used, because programmers usually try to be
-more specific about what kind of atom they are dealing with. Lisp
-programming is mostly about symbols (and sometimes numbers) within
-lists. (Incidentally, the preceding three word parenthetical remark
-is a proper list in Lisp, since it consists of atoms, which in this
-case are symbols, separated by whitespace and enclosed by
-parentheses, without any non-Lisp punctuation.)
-
-In addition, text between double quotation marks--even sentences or
-paragraphs--is an atom. Here is an example:
-
- '(this list includes "text between quotation marks.")
-
-In Lisp, all of the quoted text including the punctuation mark and the
-blank spaces is a single atom. This kind of atom is called a
-"string" (for `string of characters') and is the sort of thing that
-is used for messages that a computer can print for a human to read.
-Strings are a different kind of atom than numbers or symbols and are
-used differently.
-
-Whitespace in Lists
--------------------
-
-The amount of whitespace in a list does not matter. From the point
-of view of the Lisp language,
-
- '(this list
- looks like this)
-
-is exactly the same as this:
-
- '(this list looks like this)
-
-Both examples show what to Lisp is the same list, the list made up of
-the symbols `this', `list', `looks', `like', and `this' in that order.
-
-Extra whitespace and newlines are designed to make a list more
-readable by humans. When Lisp reads the expression, it gets rid of
-all the extra whitespace (but it needs to have at least one space
-between atoms in order to tell them apart.)
-
-Odd as it seems, the examples we have seen cover almost all of what
-Lisp lists look like! Every other list in Lisp looks more or less
-like one of these examples, except that the list may be longer and
-more complex. In brief, a list is between parentheses, a string is
-between quotation marks, a symbol looks like a word, and a number
-looks like a number. (For certain situations, square brackets, dots
-and a few other special characters may be used; however, we will go
-quite far without them.)
-
-GNU Emacs Helps You Type Lists
-------------------------------
-
-When you type a Lisp expression in GNU Emacs using either Lisp
-Interaction mode or Emacs Lisp mode, you have available to you several
-commands to format the Lisp expression so it is easy to read. For
-example, pressing the <TAB> key automatically indents the line the
-cursor is on by the right amount. A command to properly indent the
-code in a region is customarily bound to `M-C-\'. Indentation is
-designed so that you can see which elements of a list belong to which
-list--elements of a sub-list are indented more than the elements of
-the enclosing list.
-
-In addition, when you type a closing parenthesis, Emacs momentarily
-jumps the cursor back to the matching opening parenthesis, so you can
-see which one it is. This is very useful, since every list you type
-in Lisp must have its closing parenthesis match its opening
-parenthesis. (*Note Major Modes: (emacs)Major Modes, for more
-information about Emacs' modes.)
-
-Run a Program
-=============
-
-A list in Lisp--any list--is a program ready to run. If you run it
-(for which the Lisp jargon is "evaluate"), the computer will do one
-of three things: do nothing except return to you the list itself; send
-you an error message; or, treat the first symbol in the list as a
-command to do something. (Usually, of course, it is the last of these
-three things that you really want!)
-
-The single apostrophe, `'', that I put in front of some of the
-example lists in preceding sections is called a "quote"; when it
-precedes a list, it tells Lisp to do nothing with the list, other than
-take it as it is written. But if there is no quote preceding a list,
-the first item of the list is special: it is a command for the
-computer to obey. (In Lisp, these commands are called _functions_.)
-The list `(+ 2 2)' shown above did not have a quote in front of it,
-so Lisp understands that the `+' is an instruction to do something
-with the rest of the list: add the numbers that follow.
-
-If you are reading this inside of GNU Emacs in Info, here is how you
-can evaluate such a list: place your cursor immediately after the
-right hand parenthesis of the following list and then type `C-x C-e':
-
- (+ 2 2)
-
-You will see the number `4' appear in the echo area. (In the jargon,
-what you have just done is "evaluate the list." The echo area is the
-line at the bottom of the screen that displays or "echoes" text.)
-Now try the same thing with a quoted list: place the cursor right
-after the following list and type `C-x C-e':
-
- '(this is a quoted list)
-
-You will see `(this is a quoted list)' appear in the echo area.
-
-In both cases, what you are doing is giving a command to the program
-inside of GNU Emacs called the "Lisp interpreter"--giving the
-interpreter a command to evaluate the expression. The name of the
-Lisp interpreter comes from the word for the task done by a human who
-comes up with the meaning of an expression--who "interprets" it.
-
-You can also evaluate an atom that is not part of a list--one that is
-not surrounded by parentheses; again, the Lisp interpreter translates
-from the humanly readable expression to the language of the computer.
-But before discussing this (*note Variables::), we will discuss what
-the Lisp interpreter does when you make an error.
-
-Generate an Error Message
-=========================
-
-Partly so you won't worry if you do it accidentally, we will now give
-a command to the Lisp interpreter that generates an error message.
-This is a harmless activity; and indeed, we will often try to generate
-error messages intentionally. Once you understand the jargon, error
-messages can be informative. Instead of being called "error"
-messages, they should be called "help" messages. They are like
-signposts to a traveller in a strange country; deciphering them can be
-hard, but once understood, they can point the way.
-
-The error message is generated by a built-in GNU Emacs debugger. We
-will `enter the debugger'. You get out of the debugger by typing `q'.
-
-What we will do is evaluate a list that is not quoted and does not
-have a meaningful command as its first element. Here is a list almost
-exactly the same as the one we just used, but without the single-quote
-in front of it. Position the cursor right after it and type `C-x
-C-e':
-
- (this is an unquoted list)
-
-What you see depends on which version of Emacs you are running. GNU
-Emacs version 21 provides more information than version 20 and before.
-First, the more recent result of generating an error; then the
-earlier, version 20 result.
-
-In GNU Emacs version 21, a `*Backtrace*' window will open up and you
-will see the following in it:
-
- ---------- Buffer: *Backtrace* ----------
- Debugger entered--Lisp error: (void-function this)
- (this is an unquoted list)
- eval((this is an unquoted list))
- eval-last-sexp-1(nil)
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
- ---------- Buffer: *Backtrace* ----------
-
-Your cursor will be in this window (you may have to wait a few seconds
-before it becomes visible). To quit the debugger and make the
-debugger window go away, type:
-
- q
-
-Please type `q' right now, so you become confident that you can get
-out of the debugger. Then, type `C-x C-e' again to re-enter it.
-
-Based on what we already know, we can almost read this error message.
-
-You read the `*Backtrace*' buffer from the bottom up; it tells you
-what Emacs did. When you typed `C-x C-e', you made an interactive
-call to the command `eval-last-sexp'. `eval' is an abbreviation for
-`evaluate' and `sexp' is an abbreviation for `symbolic expression'.
-The command means `evaluate last symbolic expression', which is the
-expression just before your cursor.
-
-Each line above tells you what the Lisp interpreter evaluated next.
-The most recent action is at the top. The buffer is called the
-`*Backtrace*' buffer because it enables you to track Emacs backwards.
-
-At the top of the `*Backtrace*' buffer, you see the line:
-
- Debugger entered--Lisp error: (void-function this)
-
-The Lisp interpreter tried to evaluate the first atom of the list, the
-word `this'. It is this action that generated the error message
-`void-function this'.
-
-The message contains the words `void-function' and `this'.
-
-The word `function' was mentioned once before. It is a very
-important word. For our purposes, we can define it by saying that a
-"function" is a set of instructions to the computer that tell the
-computer to do something.
-
-Now we can begin to understand the error message: `void-function
-this'. The function (that is, the word `this') does not have a
-definition of any set of instructions for the computer to carry out.
-
-The slightly odd word, `void-function', is designed to cover the way
-Emacs Lisp is implemented, which is that when a symbol does not have
-a function definition attached to it, the place that should contain
-the instructions is `void'.
-
-On the other hand, since we were able to add 2 plus 2 successfully, by
-evaluating `(+ 2 2)', we can infer that the symbol `+' must have a
-set of instructions for the computer to obey and those instructions
-must be to add the numbers that follow the `+'.
-
-In GNU Emacs version 20, and in earlier versions, you will see only
-one line of error message; it will appear in the echo area and look
-like this:
-
- Symbol's function definition is void: this
-
-(Also, your terminal may beep at you--some do, some don't; and others
-blink. This is just a device to get your attention.) The message
-goes away as soon as you type another key, even just to move the
-cursor.
-
-We know the meaning of the word `Symbol'. It refers to the first
-atom of the list, the word `this'. The word `function' refers to the
-instructions that tell the computer what to do. (Technically, the
-symbol tells the computer where to find the instructions, but this is
-a complication we can ignore for the moment.)
-
-The error message can be understood: `Symbol's function definition is
-void: this'. The symbol (that is, the word `this') lacks
-instructions for the computer to carry out.
-
-Symbol Names and Function Definitions
-=====================================
-
-We can articulate another characteristic of Lisp based on what we have
-discussed so far--an important characteristic: a symbol, like `+', is
-not itself the set of instructions for the computer to carry out.
-Instead, the symbol is used, perhaps temporarily, as a way of
-locating the definition or set of instructions. What we see is the
-name through which the instructions can be found. Names of people
-work the same way. I can be referred to as `Bob'; however, I am not
-the letters `B', `o', `b' but am the consciousness consistently
-associated with a particular life-form. The name is not me, but it
-can be used to refer to me.
-
-In Lisp, one set of instructions can be attached to several names.
-For example, the computer instructions for adding numbers can be
-linked to the symbol `plus' as well as to the symbol `+' (and are in
-some dialects of Lisp). Among humans, I can be referred to as
-`Robert' as well as `Bob' and by other words as well.
-
-On the other hand, a symbol can have only one function definition
-attached to it at a time. Otherwise, the computer would be confused
-as to which definition to use. If this were the case among people,
-only one person in the world could be named `Bob'. However, the
-function definition to which the name refers can be changed readily.
-(*Note Install a Function Definition: Install.)
-
-Since Emacs Lisp is large, it is customary to name symbols in a way
-that identifies the part of Emacs to which the function belongs.
-Thus, all the names for functions that deal with Texinfo start with
-`texinfo-' and those for functions that deal with reading mail start
-with `rmail-'.
-
-The Lisp Interpreter
-====================
-
-Based on what we have seen, we can now start to figure out what the
-Lisp interpreter does when we command it to evaluate a list. First,
-it looks to see whether there is a quote before the list; if there
-is, the interpreter just gives us the list. On the other hand, if
-there is no quote, the interpreter looks at the first element in the
-list and sees whether it has a function definition. If it does, the
-interpreter carries out the instructions in the function definition.
-Otherwise, the interpreter prints an error message.
-
-This is how Lisp works. Simple. There are added complications which
-we will get to in a minute, but these are the fundamentals. Of
-course, to write Lisp programs, you need to know how to write
-function definitions and attach them to names, and how to do this
-without confusing either yourself or the computer.
-
-Complications
--------------
-
-Now, for the first complication. In addition to lists, the Lisp
-interpreter can evaluate a symbol that is not quoted and does not have
-parentheses around it. The Lisp interpreter will attempt to determine
-the symbol's value as a "variable". This situation is described in
-the section on variables. (*Note Variables::.)
-
-The second complication occurs because some functions are unusual and
-do not work in the usual manner. Those that don't are called "special
-forms". They are used for special jobs, like defining a function, and
-there are not many of them. In the next few chapters, you will be
-introduced to several of the more important special forms.
-
-The third and final complication is this: if the function that the
-Lisp interpreter is looking at is not a special form, and if it is
-part of a list, the Lisp interpreter looks to see whether the list
-has a list inside of it. If there is an inner list, the Lisp
-interpreter first figures out what it should do with the inside list,
-and then it works on the outside list. If there is yet another list
-embedded inside the inner list, it works on that one first, and so
-on. It always works on the innermost list first. The interpreter
-works on the innermost list first, to evaluate the result of that
-list. The result may be used by the enclosing expression.
-
-Otherwise, the interpreter works left to right, from one expression to
-the next.
-
-Byte Compiling
---------------
-
-One other aspect of interpreting: the Lisp interpreter is able to
-interpret two kinds of entity: humanly readable code, on which we will
-focus exclusively, and specially processed code, called "byte
-compiled" code, which is not humanly readable. Byte compiled code
-runs faster than humanly readable code.
-
-You can transform humanly readable code into byte compiled code by
-running one of the compile commands such as `byte-compile-file'.
-Byte compiled code is usually stored in a file that ends with a
-`.elc' extension rather than a `.el' extension. You will see both
-kinds of file in the `emacs/lisp' directory; the files to read are
-those with `.el' extensions.
-
-As a practical matter, for most things you might do to customize or
-extend Emacs, you do not need to byte compile; and I will not discuss
-the topic here. *Note Byte Compilation: (elisp)Byte Compilation, for
-a full description of byte compilation.
-
-Evaluation
-==========
-
-When the Lisp interpreter works on an expression, the term for the
-activity is called "evaluation". We say that the interpreter
-`evaluates the expression'. I've used this term several times before.
-The word comes from its use in everyday language, `to ascertain the
-value or amount of; to appraise', according to `Webster's New
-Collegiate Dictionary'.
-
-After evaluating an expression, the Lisp interpreter will most likely
-"return" the value that the computer produces by carrying out the
-instructions it found in the function definition, or perhaps it will
-give up on that function and produce an error message. (The
-interpreter may also find itself tossed, so to speak, to a different
-function or it may attempt to repeat continually what it is doing for
-ever and ever in what is called an `infinite loop'. These actions
-are less common; and we can ignore them.) Most frequently, the
-interpreter returns a value.
-
-At the same time the interpreter returns a value, it may do something
-else as well, such as move a cursor or copy a file; this other kind of
-action is called a "side effect". Actions that we humans think are
-important, such as printing results, are often "side effects" to the
-Lisp interpreter. The jargon can sound peculiar, but it turns out
-that it is fairly easy to learn to use side effects.
-
-In summary, evaluating a symbolic expression most commonly causes the
-Lisp interpreter to return a value and perhaps carry out a side
-effect; or else produce an error.
-
-Evaluating Inner Lists
-----------------------
-
-If evaluation applies to a list that is inside another list, the outer
-list may use the value returned by the first evaluation as information
-when the outer list is evaluated. This explains why inner expressions
-are evaluated first: the values they return are used by the outer
-expressions.
-
-We can investigate this process by evaluating another addition
-example. Place your cursor after the following expression and type
-`C-x C-e':
-
- (+ 2 (+ 3 3))
-
-The number 8 will appear in the echo area.
-
-What happens is that the Lisp interpreter first evaluates the inner
-expression, `(+ 3 3)', for which the value 6 is returned; then it
-evaluates the outer expression as if it were written `(+ 2 6)', which
-returns the value 8. Since there are no more enclosing expressions to
-evaluate, the interpreter prints that value in the echo area.
-
-Now it is easy to understand the name of the command invoked by the
-keystrokes `C-x C-e': the name is `eval-last-sexp'. The letters
-`sexp' are an abbreviation for `symbolic expression', and `eval' is
-an abbreviation for `evaluate'. The command means `evaluate last
-symbolic expression'.
-
-As an experiment, you can try evaluating the expression by putting the
-cursor at the beginning of the next line immediately following the
-expression, or inside the expression.
-
-Here is another copy of the expression:
-
- (+ 2 (+ 3 3))
-
-If you place the cursor at the beginning of the blank line that
-immediately follows the expression and type `C-x C-e', you will still
-get the value 8 printed in the echo area. Now try putting the cursor
-inside the expression. If you put it right after the next to last
-parenthesis (so it appears to sit on top of the last parenthesis),
-you will get a 6 printed in the echo area! This is because the
-command evaluates the expression `(+ 3 3)'.
-
-Now put the cursor immediately after a number. Type `C-x C-e' and
-you will get the number itself. In Lisp, if you evaluate a number,
-you get the number itself--this is how numbers differ from symbols.
-If you evaluate a list starting with a symbol like `+', you will get a
-value returned that is the result of the computer carrying out the
-instructions in the function definition attached to that name. If a
-symbol by itself is evaluated, something different happens, as we will
-see in the next section.
-
-Variables
-=========
-
-In Emacs Lisp, a symbol can have a value attached to it just as it can
-have a function definition attached to it. The two are different.
-The function definition is a set of instructions that a computer will
-obey. A value, on the other hand, is something, such as number or a
-name, that can vary (which is why such a symbol is called a variable).
-The value of a symbol can be any expression in Lisp, such as a symbol,
-number, list, or string. A symbol that has a value is often called a
-"variable".
-
-A symbol can have both a function definition and a value attached to
-it at the same time. Or it can have just one or the other. The two
-are separate. This is somewhat similar to the way the name Cambridge
-can refer to the city in Massachusetts and have some information
-attached to the name as well, such as "great programming center".
-
-Another way to think about this is to imagine a symbol as being a
-chest of drawers. The function definition is put in one drawer, the
-value in another, and so on. What is put in the drawer holding the
-value can be changed without affecting the contents of the drawer
-holding the function definition, and vice-versa.
-
-`fill-column', an Example Variable
-----------------------------------
-
-The variable `fill-column' illustrates a symbol with a value attached
-to it: in every GNU Emacs buffer, this symbol is set to some value,
-usually 72 or 70, but sometimes to some other value. To find the
-value of this symbol, evaluate it by itself. If you are reading this
-in Info inside of GNU Emacs, you can do this by putting the cursor
-after the symbol and typing `C-x C-e':
-
- fill-column
-
-After I typed `C-x C-e', Emacs printed the number 72 in my echo area.
-This is the value for which `fill-column' is set for me as I write
-this. It may be different for you in your Info buffer. Notice that
-the value returned as a variable is printed in exactly the same way
-as the value returned by a function carrying out its instructions.
-From the point of view of the Lisp interpreter, a value returned is a
-value returned. What kind of expression it came from ceases to
-matter once the value is known.
-
-A symbol can have any value attached to it or, to use the jargon, we
-can "bind" the variable to a value: to a number, such as 72; to a
-string, `"such as this"'; to a list, such as `(spruce pine oak)'; we
-can even bind a variable to a function definition.
-
-A symbol can be bound to a value in several ways. *Note Setting the
-Value of a Variable: set & setq, for information about one way to do
-this.
-
-Error Message for a Symbol Without a Function
----------------------------------------------
-
-When we evaluated `fill-column' to find its value as a variable, we
-did not place parentheses around the word. This is because we did
-not intend to use it as a function name.
-
-If `fill-column' were the first or only element of a list, the Lisp
-interpreter would attempt to find the function definition attached to
-it. But `fill-column' has no function definition. Try evaluating
-this:
-
- (fill-column)
-
-In GNU Emacs version 21, you will create a `*Backtrace*' buffer that
-says:
-
- ---------- Buffer: *Backtrace* ----------
- Debugger entered--Lisp error: (void-function fill-column)
- (fill-column)
- eval((fill-column))
- eval-last-sexp-1(nil)
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
- ---------- Buffer: *Backtrace* ----------
-
-(Remember, to quit the debugger and make the debugger window go away,
-type `q' in the `*Backtrace*' buffer.)
-
-In GNU Emacs 20 and before, you will produce an error message that
-says:
-
- Symbol's function definition is void: fill-column
-
-(The message will go away away as soon as you move the cursor or type
-another key.)
-
-Error Message for a Symbol Without a Value
-------------------------------------------
-
-If you attempt to evaluate a symbol that does not have a value bound
-to it, you will receive an error message. You can see this by
-experimenting with our 2 plus 2 addition. In the following
-expression, put your cursor right after the `+', before the first
-number 2, type `C-x C-e':
-
- (+ 2 2)
-
-In GNU Emacs 21, you will create a `*Backtrace*' buffer that says:
-
- ---------- Buffer: *Backtrace* ----------
- Debugger entered--Lisp error: (void-variable +)
- eval(+)
- eval-last-sexp-1(nil)
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
- ---------- Buffer: *Backtrace* ----------
-
-(As with the other times we entered the debugger, you can quit by
-typing `q' in the `*Backtrace*' buffer.)
-
-This backtrace is different from the very first error message we saw,
-which said, `Debugger entered--Lisp error: (void-function this)'. In
-this case, the function does not have a value as a variable; while in
-the other error message, the function (the word `this') did not have
-a definition.
-
-In this experiment with the `+', what we did was cause the Lisp
-interpreter to evaluate the `+' and look for the value of the
-variable instead of the function definition. We did this by placing
-the cursor right after the symbol rather than after the parenthesis
-of the enclosing list as we did before. As a consequence, the Lisp
-interpreter evaluated the preceding s-expression, which in this case
-was the `+' by itself.
-
-Since `+' does not have a value bound to it, just the function
-definition, the error message reported that the symbol's value as a
-variable was void.
-
-In GNU Emacs version 20 and before, your error message will say:
-
- Symbol's value as variable is void: +
-
-The meaning is the same as in GNU Emacs 21.
-
-Arguments
-=========
-
-To see how information is passed to functions, let's look again at
-our old standby, the addition of two plus two. In Lisp, this is
-written as follows:
-
- (+ 2 2)
-
-If you evaluate this expression, the number 4 will appear in your echo
-area. What the Lisp interpreter does is add the numbers that follow
-the `+'.
-
-The numbers added by `+' are called the "arguments" of the function
-`+'. These numbers are the information that is given to or "passed"
-to the function.
-
-The word `argument' comes from the way it is used in mathematics and
-does not refer to a disputation between two people; instead it refers
-to the information presented to the function, in this case, to the
-`+'. In Lisp, the arguments to a function are the atoms or lists
-that follow the function. The values returned by the evaluation of
-these atoms or lists are passed to the function. Different functions
-require different numbers of arguments; some functions require none at
-all.(1)
-
----------- Footnotes ----------
-
-(1) It is curious to track the path by which the word `argument' came
-to have two different meanings, one in mathematics and the other in
-everyday English. According to the `Oxford English Dictionary', the
-word derives from the Latin for `to make clear, prove'; thus it came
-to mean, by one thread of derivation, `the evidence offered as
-proof', which is to say, `the information offered', which led to its
-meaning in Lisp. But in the other thread of derivation, it came to
-mean `to assert in a manner against which others may make counter
-assertions', which led to the meaning of the word as a disputation.
-(Note here that the English word has two different definitions
-attached to it at the same time. By contrast, in Emacs Lisp, a
-symbol cannot have two different function definitions at the same
-time.)
-
-Arguments' Data Types
----------------------
-
-The type of data that should be passed to a function depends on what
-kind of information it uses. The arguments to a function such as `+'
-must have values that are numbers, since `+' adds numbers. Other
-functions use different kinds of data for their arguments.
-
-For example, the `concat' function links together or unites two or
-more strings of text to produce a string. The arguments are strings.
-Concatenating the two character strings `abc', `def' produces the
-single string `abcdef'. This can be seen by evaluating the following:
-
- (concat "abc" "def")
-
-The value produced by evaluating this expression is `"abcdef"'.
-
-A function such as `substring' uses both a string and numbers as
-arguments. The function returns a part of the string, a substring of
-the first argument. This function takes three arguments. Its first
-argument is the string of characters, the second and third arguments
-are numbers that indicate the beginning and end of the substring. The
-numbers are a count of the number of characters (including spaces and
-punctuations) from the beginning of the string.
-
-For example, if you evaluate the following:
-
- (substring "The quick brown fox jumped." 16 19)
-
-you will see `"fox"' appear in the echo area. The arguments are the
-string and the two numbers.
-
-Note that the string passed to `substring' is a single atom even
-though it is made up of several words separated by spaces. Lisp
-counts everything between the two quotation marks as part of the
-string, including the spaces. You can think of the `substring'
-function as a kind of `atom smasher' since it takes an otherwise
-indivisible atom and extracts a part. However, `substring' is only
-able to extract a substring from an argument that is a string, not
-from another type of atom such as a number or symbol.
-
-An Argument as the Value of a Variable or List
-----------------------------------------------
-
-An argument can be a symbol that returns a value when it is evaluated.
-For example, when the symbol `fill-column' by itself is evaluated, it
-returns a number. This number can be used in an addition.
-
-Position the cursor after the following expression and type `C-x C-e':
-
- (+ 2 fill-column)
-
-The value will be a number two more than what you get by evaluating
-`fill-column' alone. For me, this is 74, because the value of
-`fill-column' is 72.
-
-As we have just seen, an argument can be a symbol that returns a value
-when evaluated. In addition, an argument can be a list that returns a
-value when it is evaluated. For example, in the following expression,
-the arguments to the function `concat' are the strings `"The "' and
-`" red foxes."' and the list `(number-to-string (+ 2 fill-column))'.
-
- (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
-
-If you evaluate this expression--and if, as with my Emacs,
-`fill-column' evaluates to 72--`"The 74 red foxes."' will appear in
-the echo area. (Note that you must put spaces after the word `The'
-and before the word `red' so they will appear in the final string.
-The function `number-to-string' converts the integer that the
-addition function returns to a string. `number-to-string' is also
-known as `int-to-string'.)
-
-Variable Number of Arguments
-----------------------------
-
-Some functions, such as `concat', `+' or `*', take any number of
-arguments. (The `*' is the symbol for multiplication.) This can be
-seen by evaluating each of the following expressions in the usual
-way. What you will see in the echo area is printed in this text
-after `=>', which you may read as `evaluates to'.
-
-In the first set, the functions have no arguments:
-
- (+) => 0
-
- (*) => 1
-
-In this set, the functions have one argument each:
-
- (+ 3) => 3
-
- (* 3) => 3
-
-In this set, the functions have three arguments each:
-
- (+ 3 4 5) => 12
-
- (* 3 4 5) => 60
-
-Using the Wrong Type Object as an Argument
-------------------------------------------
-
-When a function is passed an argument of the wrong type, the Lisp
-interpreter produces an error message. For example, the `+' function
-expects the values of its arguments to be numbers. As an experiment
-we can pass it the quoted symbol `hello' instead of a number.
-Position the cursor after the following expression and type `C-x C-e':
-
- (+ 2 'hello)
-
-When you do this you will generate an error message. What has
-happened is that `+' has tried to add the 2 to the value returned by
-`'hello', but the value returned by `'hello' is the symbol `hello',
-not a number. Only numbers can be added. So `+' could not carry out
-its addition.
-
-In GNU Emacs version 21, you will create and enter a `*Backtrace*'
-buffer that says:
-
- ---------- Buffer: *Backtrace* ----------
- Debugger entered--Lisp error:
- (wrong-type-argument number-or-marker-p hello)
- +(2 hello)
- eval((+ 2 (quote hello)))
- eval-last-sexp-1(nil)
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
- ---------- Buffer: *Backtrace* ----------
-
-As usual, the error message tries to be helpful and makes sense after
-you learn how to read it.
-
-The first part of the error message is straightforward; it says
-`wrong type argument'. Next comes the mysterious jargon word
-`number-or-marker-p'. This word is trying to tell you what kind of
-argument the `+' expected.
-
-The symbol `number-or-marker-p' says that the Lisp interpreter is
-trying to determine whether the information presented it (the value of
-the argument) is a number or a marker (a special object representing a
-buffer position). What it does is test to see whether the `+' is
-being given numbers to add. It also tests to see whether the
-argument is something called a marker, which is a specific feature of
-Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers.
-When the mark is set with the `C-@' or `C-<SPC>' command, its
-position is kept as a marker. The mark can be considered a
-number--the number of characters the location is from the beginning
-of the buffer.) In Emacs Lisp, `+' can be used to add the numeric
-value of marker positions as numbers.
-
-The `p' of `number-or-marker-p' is the embodiment of a practice
-started in the early days of Lisp programming. The `p' stands for
-`predicate'. In the jargon used by the early Lisp researchers, a
-predicate refers to a function to determine whether some property is
-true or false. So the `p' tells us that `number-or-marker-p' is the
-name of a function that determines whether it is true or false that
-the argument supplied is a number or a marker. Other Lisp symbols
-that end in `p' include `zerop', a function that tests whether its
-argument has the value of zero, and `listp', a function that tests
-whether its argument is a list.
-
-Finally, the last part of the error message is the symbol `hello'.
-This is the value of the argument that was passed to `+'. If the
-addition had been passed the correct type of object, the value passed
-would have been a number, such as 37, rather than a symbol like
-`hello'. But then you would not have got the error message.
-
-In GNU Emacs version 20 and before, the echo area displays an error
-message that says:
-
- Wrong type argument: number-or-marker-p, hello
-
-This says, in different words, the same as the top line of the
-`*Backtrace*' buffer.
-
-The `message' Function
-----------------------
-
-Like `+', the `message' function takes a variable number of
-arguments. It is used to send messages to the user and is so useful
-that we will describe it here.
-
-A message is printed in the echo area. For example, you can print a
-message in your echo area by evaluating the following list:
-
- (message "This message appears in the echo area!")
-
-The whole string between double quotation marks is a single argument
-and is printed in toto. (Note that in this example, the message
-itself will appear in the echo area within double quotes; that is
-because you see the value returned by the `message' function. In
-most uses of `message' in programs that you write, the text will be
-printed in the echo area as a side-effect, without the quotes. *Note
-`multiply-by-seven' in detail: multiply-by-seven in detail, for an
-example of this.)
-
-However, if there is a `%s' in the quoted string of characters, the
-`message' function does not print the `%s' as such, but looks to the
-argument that follows the string. It evaluates the second argument
-and prints the value at the location in the string where the `%s' is.
-
-You can see this by positioning the cursor after the following
-expression and typing `C-x C-e':
-
- (message "The name of this buffer is: %s." (buffer-name))
-
-In Info, `"The name of this buffer is: *info*."' will appear in the
-echo area. The function `buffer-name' returns the name of the buffer
-as a string, which the `message' function inserts in place of `%s'.
-
-To print a value as an integer, use `%d' in the same way as `%s'.
-For example, to print a message in the echo area that states the
-value of the `fill-column', evaluate the following:
-
- (message "The value of fill-column is %d." fill-column)
-
-On my system, when I evaluate this list, `"The value of fill-column
-is 72."' appears in my echo area(1).
-
-If there is more than one `%s' in the quoted string, the value of the
-first argument following the quoted string is printed at the location
-of the first `%s' and the value of the second argument is printed at
-the location of the second `%s', and so on.
-
-For example, if you evaluate the following,
-
- (message "There are %d %s in the office!"
- (- fill-column 14) "pink elephants")
-
-a rather whimsical message will appear in your echo area. On my
-system it says, `"There are 58 pink elephants in the office!"'.
-
-The expression `(- fill-column 14)' is evaluated and the resulting
-number is inserted in place of the `%d'; and the string in double
-quotes, `"pink elephants"', is treated as a single argument and
-inserted in place of the `%s'. (That is to say, a string between
-double quotes evaluates to itself, like a number.)
-
-Finally, here is a somewhat complex example that not only illustrates
-the computation of a number, but also shows how you can use an
-expression within an expression to generate the text that is
-substituted for `%s':
-
- (message "He saw %d %s"
- (- fill-column 34)
- (concat "red "
- (substring
- "The quick brown foxes jumped." 16 21)
- " leaping."))
-
-In this example, `message' has three arguments: the string, `"He saw
-%d %s"', the expression, `(- fill-column 32)', and the expression
-beginning with the function `concat'. The value resulting from the
-evaluation of `(- fill-column 32)' is inserted in place of the `%d';
-and the value returned by the expression beginning with `concat' is
-inserted in place of the `%s'.
-
-When I evaluate the expression, the message `"He saw 38 red foxes
-leaping."' appears in my echo area.
-
----------- Footnotes ----------
-
-(1) Actually, you can use `%s' to print a number. It is
-non-specific. `%d' prints only the part of a number left of a
-decimal point, and not anything that is not a number.
-
-Setting the Value of a Variable
-===============================
-
-There are several ways by which a variable can be given a value. One
-of the ways is to use either the function `set' or the function
-`setq'. Another way is to use `let' (*note let::). (The jargon for
-this process is to "bind" a variable to a value.)
-
-The following sections not only describe how `set' and `setq' work
-but also illustrate how arguments are passed.
-
-Using `set'
------------
-
-To set the value of the symbol `flowers' to the list `'(rose violet
-daisy buttercup)', evaluate the following expression by positioning
-the cursor after the expression and typing `C-x C-e'.
-
- (set 'flowers '(rose violet daisy buttercup))
-
-The list `(rose violet daisy buttercup)' will appear in the echo
-area. This is what is _returned_ by the `set' function. As a side
-effect, the symbol `flowers' is bound to the list ; that is, the
-symbol `flowers', which can be viewed as a variable, is given the
-list as its value. (This process, by the way, illustrates how a side
-effect to the Lisp interpreter, setting the value, can be the primary
-effect that we humans are interested in. This is because every Lisp
-function must return a value if it does not get an error, but it will
-only have a side effect if it is designed to have one.)
-
-After evaluating the `set' expression, you can evaluate the symbol
-`flowers' and it will return the value you just set. Here is the
-symbol. Place your cursor after it and type `C-x C-e'.
-
- flowers
-
-When you evaluate `flowers', the list `(rose violet daisy buttercup)'
-appears in the echo area.
-
-Incidentally, if you evaluate `'flowers', the variable with a quote
-in front of it, what you will see in the echo area is the symbol
-itself, `flowers'. Here is the quoted symbol, so you can try this:
-
- 'flowers
-
-Note also, that when you use `set', you need to quote both arguments
-to `set', unless you want them evaluated. Since we do not want
-either argument evaluated, neither the variable `flowers' nor the
-list `(rose violet daisy buttercup)', both are quoted. (When you use
-`set' without quoting its first argument, the first argument is
-evaluated before anything else is done. If you did this and
-`flowers' did not have a value already, you would get an error
-message that the `Symbol's value as variable is void'; on the other
-hand, if `flowers' did return a value after it was evaluated, the
-`set' would attempt to set the value that was returned. There are
-situations where this is the right thing for the function to do; but
-such situations are rare.)
-
-Using `setq'
-------------
-
-As a practical matter, you almost always quote the first argument to
-`set'. The combination of `set' and a quoted first argument is so
-common that it has its own name: the special form `setq'. This
-special form is just like `set' except that the first argument is
-quoted automatically, so you don't need to type the quote mark
-yourself. Also, as an added convenience, `setq' permits you to set
-several different variables to different values, all in one
-expression.
-
-To set the value of the variable `carnivores' to the list `'(lion
-tiger leopard)' using `setq', the following expression is used:
-
- (setq carnivores '(lion tiger leopard))
-
-This is exactly the same as using `set' except the first argument is
-automatically quoted by `setq'. (The `q' in `setq' means `quote'.)
-
-With `set', the expression would look like this:
-
- (set 'carnivores '(lion tiger leopard))
-
-Also, `setq' can be used to assign different values to different
-variables. The first argument is bound to the value of the second
-argument, the third argument is bound to the value of the fourth
-argument, and so on. For example, you could use the following to
-assign a list of trees to the symbol `trees' and a list of herbivores
-to the symbol `herbivores':
-
- (setq trees '(pine fir oak maple)
- herbivores '(gazelle antelope zebra))
-
-(The expression could just as well have been on one line, but it might
-not have fit on a page; and humans find it easier to read nicely
-formatted lists.)
-
-Although I have been using the term `assign', there is another way of
-thinking about the workings of `set' and `setq'; and that is to say
-that `set' and `setq' make the symbol _point_ to the list. This
-latter way of thinking is very common and in forthcoming chapters we
-shall come upon at least one symbol that has `pointer' as part of its
-name. The name is chosen because the symbol has a value,
-specifically a list, attached to it; or, expressed another way, the
-symbol is set to "point" to the list.
-
-Counting
---------
-
-Here is an example that shows how to use `setq' in a counter. You
-might use this to count how many times a part of your program repeats
-itself. First set a variable to zero; then add one to the number each
-time the program repeats itself. To do this, you need a variable that
-serves as a counter, and two expressions: an initial `setq'
-expression that sets the counter variable to zero; and a second
-`setq' expression that increments the counter each time it is
-evaluated.
-
- (setq counter 0) ; Let's call this the initializer.
-
- (setq counter (+ counter 1)) ; This is the incrementer.
-
- counter ; This is the counter.
-
-(The text following the `;' are comments. *Note Change a Function
-Definition: Change a defun.)
-
-If you evaluate the first of these expressions, the initializer,
-`(setq counter 0)', and then evaluate the third expression,
-`counter', the number `0' will appear in the echo area. If you then
-evaluate the second expression, the incrementer, `(setq counter (+
-counter 1))', the counter will get the value 1. So if you again
-evaluate `counter', the number `1' will appear in the echo area.
-Each time you evaluate the second expression, the value of the
-counter will be incremented.
-
-When you evaluate the incrementer, `(setq counter (+ counter 1))',
-the Lisp interpreter first evaluates the innermost list; this is the
-addition. In order to evaluate this list, it must evaluate the
-variable `counter' and the number `1'. When it evaluates the variable
-`counter', it receives its current value. It passes this value and
-the number `1' to the `+' which adds them together. The sum is then
-returned as the value of the inner list and passed to the `setq'
-which sets the variable `counter' to this new value. Thus, the value
-of the variable, `counter', is changed.
-
-Summary
-=======
-
-Learning Lisp is like climbing a hill in which the first part is the
-steepest. You have now climbed the most difficult part; what remains
-becomes easier as you progress onwards.
-
-In summary,
-
- * Lisp programs are made up of expressions, which are lists or
- single atoms.
-
- * Lists are made up of zero or more atoms or inner lists,
- separated by whitespace and surrounded by parentheses. A list
- can be empty.
-
- * Atoms are multi-character symbols, like `forward-paragraph',
- single character symbols like `+', strings of characters between
- double quotation marks, or numbers.
-
- * A number evaluates to itself.
-
- * A string between double quotes also evaluates to itself.
-
- * When you evaluate a symbol by itself, its value is returned.
-
- * When you evaluate a list, the Lisp interpreter looks at the
- first symbol in the list and then at the function definition
- bound to that symbol. Then the instructions in the function
- definition are carried out.
-
- * A single-quote, `'', tells the Lisp interpreter that it should
- return the following expression as written, and not evaluate it
- as it would if the quote were not there.
-
- * Arguments are the information passed to a function. The
- arguments to a function are computed by evaluating the rest of
- the elements of the list of which the function is the first
- element.
-
- * A function always returns a value when it is evaluated (unless
- it gets an error); in addition, it may also carry out some
- action called a "side effect". In many cases, a function's
- primary purpose is to create a side effect.
-
-Exercises
-=========
-
-A few simple exercises:
-
- * Generate an error message by evaluating an appropriate symbol
- that is not within parentheses.
-
- * Generate an error message by evaluating an appropriate symbol
- that is between parentheses.
-
- * Create a counter that increments by two rather than one.
-
- * Write an expression that prints a message in the echo area when
- evaluated.
-
-Practicing Evaluation
-*********************
-
-Before learning how to write a function definition in Emacs Lisp, it
-is useful to spend a little time evaluating various expressions that
-have already been written. These expressions will be lists with the
-functions as their first (and often only) element. Since some of the
-functions associated with buffers are both simple and interesting, we
-will start with those. In this section, we will evaluate a few of
-these. In another section, we will study the code of several other
-buffer-related functions, to see how they were written.
-
-How to Evaluate
-===============
-
-Whenever you give an editing command to Emacs Lisp, such as the
-command to move the cursor or to scroll the screen, you are evaluating
-an expression, the first element of which is a function. This is how
-Emacs works.
-
-When you type keys, you cause the Lisp interpreter to evaluate an
-expression and that is how you get your results. Even typing plain
-text involves evaluating an Emacs Lisp function, in this case, one
-that uses `self-insert-command', which simply inserts the character
-you typed. The functions you evaluate by typing keystrokes are called
-"interactive" functions, or "commands"; how you make a function
-interactive will be illustrated in the chapter on how to write
-function definitions. *Note Making a Function Interactive:
-Interactive.
-
-In addition to typing keyboard commands, we have seen a second way to
-evaluate an expression: by positioning the cursor after a list and
-typing `C-x C-e'. This is what we will do in the rest of this
-section. There are other ways to evaluate an expression as well;
-these will be described as we come to them.
-
-Besides being used for practicing evaluation, the functions shown in
-the next few sections are important in their own right. A study of
-these functions makes clear the distinction between buffers and
-files, how to switch to a buffer, and how to determine a location
-within it.
-
-Buffer Names
-============
-
-The two functions, `buffer-name' and `buffer-file-name', show the
-difference between a file and a buffer. When you evaluate the
-following expression, `(buffer-name)', the name of the buffer appears
-in the echo area. When you evaluate `(buffer-file-name)', the name
-of the file to which the buffer refers appears in the echo area.
-Usually, the name returned by `(buffer-name)' is the same as the name
-of the file to which it refers, and the name returned by
-`(buffer-file-name)' is the full path-name of the file.
-
-A file and a buffer are two different entities. A file is information
-recorded permanently in the computer (unless you delete it). A
-buffer, on the other hand, is information inside of Emacs that will
-vanish at the end of the editing session (or when you kill the
-buffer). Usually, a buffer contains information that you have copied
-from a file; we say the buffer is "visiting" that file. This copy is
-what you work on and modify. Changes to the buffer do not change the
-file, until you save the buffer. When you save the buffer, the
-buffer is copied to the file and is thus saved permanently.
-
-If you are reading this in Info inside of GNU Emacs, you can evaluate
-each of the following expressions by positioning the cursor after it
-and typing `C-x C-e'.
-
- (buffer-name)
-
- (buffer-file-name)
-
-When I do this, `"introduction.texinfo"' is the value returned by
-evaluating `(buffer-name)', and
-`"/gnu/work/intro/introduction.texinfo"' is the value returned by
-evaluating `(buffer-file-name)'. The former is the name of the
-buffer and the latter is the name of the file. (In the expressions,
-the parentheses tell the Lisp interpreter to treat `buffer-name' and
-`buffer-file-name' as functions; without the parentheses, the
-interpreter would attempt to evaluate the symbols as variables.
-*Note Variables::.)
-
-In spite of the distinction between files and buffers, you will often
-find that people refer to a file when they mean a buffer and
-vice-versa. Indeed, most people say, "I am editing a file," rather
-than saying, "I am editing a buffer which I will soon save to a
-file." It is almost always clear from context what people mean.
-When dealing with computer programs, however, it is important to keep
-the distinction in mind, since the computer is not as smart as a
-person.
-
-The word `buffer', by the way, comes from the meaning of the word as a
-cushion that deadens the force of a collision. In early computers, a
-buffer cushioned the interaction between files and the computer's
-central processing unit. The drums or tapes that held a file and the
-central processing unit were pieces of equipment that were very
-different from each other, working at their own speeds, in spurts.
-The buffer made it possible for them to work together effectively.
-Eventually, the buffer grew from being an intermediary, a temporary
-holding place, to being the place where work is done. This
-transformation is rather like that of a small seaport that grew into a
-great city: once it was merely the place where cargo was warehoused
-temporarily before being loaded onto ships; then it became a business
-and cultural center in its own right.
-
-Not all buffers are associated with files. For example, when you
-start an Emacs session by typing the command `emacs' alone, without
-naming any files, Emacs will start with the `*scratch*' buffer on the
-screen. This buffer is not visiting any file. Similarly, a `*Help*'
-buffer is not associated with any file.
-
-If you switch to the `*scratch*' buffer, type `(buffer-name)',
-position the cursor after it, and type `C-x C-e' to evaluate the
-expression, the name `"*scratch*"' is returned and will appear in the
-echo area. `"*scratch*"' is the name of the buffer. However, if you
-type `(buffer-file-name)' in the `*scratch*' buffer and evaluate
-that, `nil' will appear in the echo area. `nil' is from the Latin
-word for `nothing'; in this case, it means that the `*scratch*'
-buffer is not associated with any file. (In Lisp, `nil' is also used
-to mean `false' and is a synonym for the empty list, `()'.)
-
-Incidentally, if you are in the `*scratch*' buffer and want the value
-returned by an expression to appear in the `*scratch*' buffer itself
-rather than in the echo area, type `C-u C-x C-e' instead of `C-x
-C-e'. This causes the value returned to appear after the expression.
-The buffer will look like this:
-
- (buffer-name)"*scratch*"
-
-You cannot do this in Info since Info is read-only and it will not
-allow you to change the contents of the buffer. But you can do this
-in any buffer you can edit; and when you write code or documentation
-(such as this book), this feature is very useful.
-
-Getting Buffers
-===============
-
-The `buffer-name' function returns the _name_ of the buffer; to get
-the buffer _itself_, a different function is needed: the
-`current-buffer' function. If you use this function in code, what
-you get is the buffer itself.
-
-A name and the object or entity to which the name refers are different
-from each other. You are not your name. You are a person to whom
-others refer by name. If you ask to speak to George and someone
-hands you a card with the letters `G', `e', `o', `r', `g', and `e'
-written on it, you might be amused, but you would not be satisfied.
-You do not want to speak to the name, but to the person to whom the
-name refers. A buffer is similar: the name of the scratch buffer is
-`*scratch*', but the name is not the buffer. To get a buffer itself,
-you need to use a function such as `current-buffer'.
-
-However, there is a slight complication: if you evaluate
-`current-buffer' in an expression on its own, as we will do here,
-what you see is a printed representation of the name of the buffer
-without the contents of the buffer. Emacs works this way for two
-reasons: the buffer may be thousands of lines long--too long to be
-conveniently displayed; and, another buffer may have the same contents
-but a different name, and it is important to distinguish between them.
-
-Here is an expression containing the function:
-
- (current-buffer)
-
-If you evaluate the expression in the usual way, `#<buffer *info*>'
-appears in the echo area. The special format indicates that the
-buffer itself is being returned, rather than just its name.
-
-Incidentally, while you can type a number or symbol into a program,
-you cannot do that with the printed representation of a buffer: the
-only way to get a buffer itself is with a function such as
-`current-buffer'.
-
-A related function is `other-buffer'. This returns the most recently
-selected buffer other than the one you are in currently. If you have
-recently switched back and forth from the `*scratch*' buffer,
-`other-buffer' will return that buffer.
-
-You can see this by evaluating the expression:
-
- (other-buffer)
-
-You should see `#<buffer *scratch*>' appear in the echo area, or the
-name of whatever other buffer you switched back from most recently(1).
-
----------- Footnotes ----------
-
-(1) Actually, by default, if the buffer from which you just switched
-is visible to you in another window, `other-buffer' will choose the
-most recent buffer that you cannot see; this is a subtlety that I
-often forget.
-
-Switching Buffers
-=================
-
-The `other-buffer' function actually provides a buffer when it is
-used as an argument to a function that requires one. We can see this
-by using `other-buffer' and `switch-to-buffer' to switch to a
-different buffer.
-
-But first, a brief introduction to the `switch-to-buffer' function.
-When you switched back and forth from Info to the `*scratch*' buffer
-to evaluate `(buffer-name)', you most likely typed `C-x b' and then
-typed `*scratch*'(1) when prompted in the minibuffer for the name of
-the buffer to which you wanted to switch. The keystrokes, `C-x b',
-cause the Lisp interpreter to evaluate the interactive function
-`switch-to-buffer'. As we said before, this is how Emacs works:
-different keystrokes call or run different functions. For example,
-`C-f' calls `forward-char', `M-e' calls `forward-sentence', and so on.
-
-By writing `switch-to-buffer' in an expression, and giving it a
-buffer to switch to, we can switch buffers just the way `C-x b' does.
-
-Here is the Lisp expression:
-
- (switch-to-buffer (other-buffer))
-
-The symbol `switch-to-buffer' is the first element of the list, so
-the Lisp interpreter will treat it as a function and carry out the
-instructions that are attached to it. But before doing that, the
-interpreter will note that `other-buffer' is inside parentheses and
-work on that symbol first. `other-buffer' is the first (and in this
-case, the only) element of this list, so the Lisp interpreter calls
-or runs the function. It returns another buffer. Next, the
-interpreter runs `switch-to-buffer', passing to it, as an argument,
-the other buffer, which is what Emacs will switch to. If you are
-reading this in Info, try this now. Evaluate the expression. (To
-get back, type `C-x b <RET>'.)(2)
-
-In the programming examples in later sections of this document, you
-will see the function `set-buffer' more often than
-`switch-to-buffer'. This is because of a difference between computer
-programs and humans: humans have eyes and expect to see the buffer on
-which they are working on their computer terminals. This is so
-obvious, it almost goes without saying. However, programs do not
-have eyes. When a computer program works on a buffer, that buffer
-does not need to be visible on the screen.
-
-`switch-to-buffer' is designed for humans and does two different
-things: it switches the buffer to which Emacs' attention is directed;
-and it switches the buffer displayed in the window to the new buffer.
-`set-buffer', on the other hand, does only one thing: it switches the
-attention of the computer program to a different buffer. The buffer
-on the screen remains unchanged (of course, normally nothing happens
-there until the command finishes running).
-
-Also, we have just introduced another jargon term, the word "call".
-When you evaluate a list in which the first symbol is a function, you
-are calling that function. The use of the term comes from the notion
-of the function as an entity that can do something for you if you
-`call' it--just as a plumber is an entity who can fix a leak if you
-call him or her.
-
----------- Footnotes ----------
-
-(1) Or rather, to save typing, you probably typed just part of the
-name, such as `*sc', and then pressed your `TAB' key to cause it to
-expand to the full name; and then typed your `RET' key.
-
-(2) Remember, this expression will move you to your most recent other
-buffer that you cannot see. If you really want to go to your most
-recently selected buffer, even if you can still see it, you need to
-evaluate the following more complex expression:
-
- (switch-to-buffer (other-buffer (current-buffer) t))
-
-In this case, the first argument to `other-buffer' tells it which
-buffer to skip--the current one--and the second argument tells
-`other-buffer' it is OK to switch to a visible buffer. In regular
-use, `switch-to-buffer' takes you to an invisible window since you
-would most likely use `C-x o' (`other-window') to go to another
-visible buffer.
-
-Buffer Size and the Location of Point
-=====================================
-
-Finally, let's look at several rather simple functions,
-`buffer-size', `point', `point-min', and `point-max'. These give
-information about the size of a buffer and the location of point
-within it.
-
-The function `buffer-size' tells you the size of the current buffer;
-that is, the function returns a count of the number of characters in
-the buffer.
-
- (buffer-size)
-
-You can evaluate this in the usual way, by positioning the cursor
-after the expression and typing `C-x C-e'.
-
-In Emacs, the current position of the cursor is called "point". The
-expression `(point)' returns a number that tells you where the cursor
-is located as a count of the number of characters from the beginning
-of the buffer up to point.
-
-You can see the character count for point in this buffer by evaluating
-the following expression in the usual way:
-
- (point)
-
-As I write this, the value of `point' is 65724. The `point' function
-is frequently used in some of the examples later in this book.
-
-The value of point depends, of course, on its location within the
-buffer. If you evaluate point in this spot, the number will be
-larger:
-
- (point)
-
-For me, the value of point in this location is 66043, which means that
-there are 319 characters (including spaces) between the two
-expressions.
-
-The function `point-min' is somewhat similar to `point', but it
-returns the value of the minimum permissible value of point in the
-current buffer. This is the number 1 unless "narrowing" is in
-effect. (Narrowing is a mechanism whereby you can restrict yourself,
-or a program, to operations on just a part of a buffer. *Note
-Narrowing and Widening: Narrowing & Widening.) Likewise, the
-function `point-max' returns the value of the maximum permissible
-value of point in the current buffer.
-
-Exercise
-========
-
-Find a file with which you are working and move towards its middle.
-Find its buffer name, file name, length, and your position in the
-file.
-
-How To Write Function Definitions
-*********************************
-
-When the Lisp interpreter evaluates a list, it looks to see whether
-the first symbol on the list has a function definition attached to
-it; or, put another way, whether the symbol points to a function
-definition. If it does, the computer carries out the instructions in
-the definition. A symbol that has a function definition is called,
-simply, a function (although, properly speaking, the definition is
-the function and the symbol refers to it.)
-
-An Aside about Primitive Functions
-==================================
-
-All functions are defined in terms of other functions, except for a
-few "primitive" functions that are written in the C programming
-language. When you write functions' definitions, you will write them
-in Emacs Lisp and use other functions as your building blocks. Some
-of the functions you will use will themselves be written in Emacs
-Lisp (perhaps by you) and some will be primitives written in C. The
-primitive functions are used exactly like those written in Emacs Lisp
-and behave like them. They are written in C so we can easily run GNU
-Emacs on any computer that has sufficient power and can run C.
-
-Let me re-emphasize this: when you write code in Emacs Lisp, you do
-not distinguish between the use of functions written in C and the use
-of functions written in Emacs Lisp. The difference is irrelevant. I
-mention the distinction only because it is interesting to know.
-Indeed, unless you investigate, you won't know whether an
-already-written function is written in Emacs Lisp or C.
-
-The `defun' Special Form
-========================
-
-In Lisp, a symbol such as `mark-whole-buffer' has code attached to it
-that tells the computer what to do when the function is called. This
-code is called the "function definition" and is created by evaluating
-a Lisp expression that starts with the symbol `defun' (which is an
-abbreviation for _define function_). Because `defun' does not
-evaluate its arguments in the usual way, it is called a "special
-form".
-
-In subsequent sections, we will look at function definitions from the
-Emacs source code, such as `mark-whole-buffer'. In this section, we
-will describe a simple function definition so you can see how it
-looks. This function definition uses arithmetic because it makes for
-a simple example. Some people dislike examples using arithmetic;
-however, if you are such a person, do not despair. Hardly any of the
-code we will study in the remainder of this introduction involves
-arithmetic or mathematics. The examples mostly involve text in one
-way or another.
-
-A function definition has up to five parts following the word `defun':
-
- 1. The name of the symbol to which the function definition should be
- attached.
-
- 2. A list of the arguments that will be passed to the function. If
- no arguments will be passed to the function, this is an empty
- list, `()'.
-
- 3. Documentation describing the function. (Technically optional,
- but strongly recommended.)
-
- 4. Optionally, an expression to make the function interactive so
- you can use it by typing `M-x' and then the name of the
- function; or by typing an appropriate key or keychord.
-
- 5. The code that instructs the computer what to do: the "body" of
- the function definition.
-
-It is helpful to think of the five parts of a function definition as
-being organized in a template, with slots for each part:
-
- (defun FUNCTION-NAME (ARGUMENTS...)
- "OPTIONAL-DOCUMENTATION..."
- (interactive ARGUMENT-PASSING-INFO) ; optional
- BODY...)
-
-As an example, here is the code for a function that multiplies its
-argument by 7. (This example is not interactive. *Note Making a
-Function Interactive: Interactive, for that information.)
-
- (defun multiply-by-seven (number)
- "Multiply NUMBER by seven."
- (* 7 number))
-
-This definition begins with a parenthesis and the symbol `defun',
-followed by the name of the function.
-
-The name of the function is followed by a list that contains the
-arguments that will be passed to the function. This list is called
-the "argument list". In this example, the list has only one element,
-the symbol, `number'. When the function is used, the symbol will be
-bound to the value that is used as the argument to the function.
-
-Instead of choosing the word `number' for the name of the argument, I
-could have picked any other name. For example, I could have chosen
-the word `multiplicand'. I picked the word `number' because it tells
-what kind of value is intended for this slot; but I could just as
-well have chosen the word `multiplicand' to indicate the role that the
-value placed in this slot will play in the workings of the function.
-I could have called it `foogle', but that would have been a bad
-choice because it would not tell humans what it means. The choice of
-name is up to the programmer and should be chosen to make the meaning
-of the function clear.
-
-Indeed, you can choose any name you wish for a symbol in an argument
-list, even the name of a symbol used in some other function: the name
-you use in an argument list is private to that particular definition.
-In that definition, the name refers to a different entity than any use
-of the same name outside the function definition. Suppose you have a
-nick-name `Shorty' in your family; when your family members refer to
-`Shorty', they mean you. But outside your family, in a movie, for
-example, the name `Shorty' refers to someone else. Because a name in
-an argument list is private to the function definition, you can
-change the value of such a symbol inside the body of a function
-without changing its value outside the function. The effect is
-similar to that produced by a `let' expression. (*Note `let': let.)
-
-The argument list is followed by the documentation string that
-describes the function. This is what you see when you type `C-h f'
-and the name of a function. Incidentally, when you write a
-documentation string like this, you should make the first line a
-complete sentence since some commands, such as `apropos', print only
-the first line of a multi-line documentation string. Also, you
-should not indent the second line of a documentation string, if you
-have one, because that looks odd when you use `C-h f'
-(`describe-function'). The documentation string is optional, but it
-is so useful, it should be included in almost every function you
-write.
-
-The third line of the example consists of the body of the function
-definition. (Most functions' definitions, of course, are longer than
-this.) In this function, the body is the list, `(* 7 number)', which
-says to multiply the value of NUMBER by 7. (In Emacs Lisp, `*' is
-the function for multiplication, just as `+' is the function for
-addition.)
-
-When you use the `multiply-by-seven' function, the argument `number'
-evaluates to the actual number you want used. Here is an example
-that shows how `multiply-by-seven' is used; but don't try to evaluate
-this yet!
-
- (multiply-by-seven 3)
-
-The symbol `number', specified in the function definition in the next
-section, is given or "bound to" the value 3 in the actual use of the
-function. Note that although `number' was inside parentheses in the
-function definition, the argument passed to the `multiply-by-seven'
-function is not in parentheses. The parentheses are written in the
-function definition so the computer can figure out where the argument
-list ends and the rest of the function definition begins.
-
-If you evaluate this example, you are likely to get an error message.
-(Go ahead, try it!) This is because we have written the function
-definition, but not yet told the computer about the definition--we
-have not yet installed (or `loaded') the function definition in Emacs.
-Installing a function is the process that tells the Lisp interpreter
-the definition of the function. Installation is described in the next
-section.
-
-Install a Function Definition
-=============================
-
-If you are reading this inside of Info in Emacs, you can try out the
-`multiply-by-seven' function by first evaluating the function
-definition and then evaluating `(multiply-by-seven 3)'. A copy of
-the function definition follows. Place the cursor after the last
-parenthesis of the function definition and type `C-x C-e'. When you
-do this, `multiply-by-seven' will appear in the echo area. (What
-this means is that when a function definition is evaluated, the value
-it returns is the name of the defined function.) At the same time,
-this action installs the function definition.
-
- (defun multiply-by-seven (number)
- "Multiply NUMBER by seven."
- (* 7 number))
-
-By evaluating this `defun', you have just installed
-`multiply-by-seven' in Emacs. The function is now just as much a
-part of Emacs as `forward-word' or any other editing function you
-use. (`multiply-by-seven' will stay installed until you quit Emacs.
-To reload code automatically whenever you start Emacs, see *Note
-Installing Code Permanently: Permanent Installation.)
-
-The effect of installation
---------------------------
-
-You can see the effect of installing `multiply-by-seven' by
-evaluating the following sample. Place the cursor after the following
-expression and type `C-x C-e'. The number 21 will appear in the echo
-area.
-
- (multiply-by-seven 3)
-
-If you wish, you can read the documentation for the function by typing
-`C-h f' (`describe-function') and then the name of the function,
-`multiply-by-seven'. When you do this, a `*Help*' window will appear
-on your screen that says:
-
- multiply-by-seven:
- Multiply NUMBER by seven.
-
-(To return to a single window on your screen, type `C-x 1'.)
-
-Change a Function Definition
-----------------------------
-
-If you want to change the code in `multiply-by-seven', just rewrite
-it. To install the new version in place of the old one, evaluate the
-function definition again. This is how you modify code in Emacs. It
-is very simple.
-
-As an example, you can change the `multiply-by-seven' function to add
-the number to itself seven times instead of multiplying the number by
-seven. It produces the same answer, but by a different path. At the
-same time, we will add a comment to the code; a comment is text that
-the Lisp interpreter ignores, but that a human reader may find useful
-or enlightening. The comment is that this is the "second version".
-
- (defun multiply-by-seven (number) ; Second version.
- "Multiply NUMBER by seven."
- (+ number number number number number number number))
-
-The comment follows a semicolon, `;'. In Lisp, everything on a line
-that follows a semicolon is a comment. The end of the line is the
-end of the comment. To stretch a comment over two or more lines,
-begin each line with a semicolon.
-
-*Note Beginning a `.emacs' File: Beginning a .emacs File, and *Note
-Comments: (elisp)Comments, for more about comments.
-
-You can install this version of the `multiply-by-seven' function by
-evaluating it in the same way you evaluated the first function: place
-the cursor after the last parenthesis and type `C-x C-e'.
-
-In summary, this is how you write code in Emacs Lisp: you write a
-function; install it; test it; and then make fixes or enhancements and
-install it again.
-
-Make a Function Interactive
-===========================
-
-You make a function interactive by placing a list that begins with
-the special form `interactive' immediately after the documentation.
-A user can invoke an interactive function by typing `M-x' and then
-the name of the function; or by typing the keys to which it is bound,
-for example, by typing `C-n' for `next-line' or `C-x h' for
-`mark-whole-buffer'.
-
-Interestingly, when you call an interactive function interactively,
-the value returned is not automatically displayed in the echo area.
-This is because you often call an interactive function for its side
-effects, such as moving forward by a word or line, and not for the
-value returned. If the returned value were displayed in the echo area
-each time you typed a key, it would be very distracting.
-
-An Interactive `multiply-by-seven', An Overview
------------------------------------------------
-
-Both the use of the special form `interactive' and one way to display
-a value in the echo area can be illustrated by creating an
-interactive version of `multiply-by-seven'.
-
-Here is the code:
-
- (defun multiply-by-seven (number) ; Interactive version.
- "Multiply NUMBER by seven."
- (interactive "p")
- (message "The result is %d" (* 7 number)))
-
-You can install this code by placing your cursor after it and typing
-`C-x C-e'. The name of the function will appear in your echo area.
-Then, you can use this code by typing `C-u' and a number and then
-typing `M-x multiply-by-seven' and pressing <RET>. The phrase `The
-result is ...' followed by the product will appear in the echo area.
-
-Speaking more generally, you invoke a function like this in either of
-two ways:
-
- 1. By typing a prefix argument that contains the number to be
- passed, and then typing `M-x' and the name of the function, as
- with `C-u 3 M-x forward-sentence'; or,
-
- 2. By typing whatever key or keychord the function is bound to, as
- with `C-u 3 M-e'.
-
-Both the examples just mentioned work identically to move point
-forward three sentences. (Since `multiply-by-seven' is not bound to
-a key, it could not be used as an example of key binding.)
-
-(*Note Some Keybindings: Keybindings, to learn how to bind a command
-to a key.)
-
-A prefix argument is passed to an interactive function by typing the
-<META> key followed by a number, for example, `M-3 M-e', or by typing
-`C-u' and then a number, for example, `C-u 3 M-e' (if you type `C-u'
-without a number, it defaults to 4).
-
-An Interactive `multiply-by-seven'
-----------------------------------
-
-Let's look at the use of the special form `interactive' and then at
-the function `message' in the interactive version of
-`multiply-by-seven'. You will recall that the function definition
-looks like this:
-
- (defun multiply-by-seven (number) ; Interactive version.
- "Multiply NUMBER by seven."
- (interactive "p")
- (message "The result is %d" (* 7 number)))
-
-In this function, the expression, `(interactive "p")', is a list of
-two elements. The `"p"' tells Emacs to pass the prefix argument to
-the function and use its value for the argument of the function.
-
-The argument will be a number. This means that the symbol `number'
-will be bound to a number in the line:
-
- (message "The result is %d" (* 7 number))
-
-For example, if your prefix argument is 5, the Lisp interpreter will
-evaluate the line as if it were:
-
- (message "The result is %d" (* 7 5))
-
-(If you are reading this in GNU Emacs, you can evaluate this
-expression yourself.) First, the interpreter will evaluate the inner
-list, which is `(* 7 5)'. This returns a value of 35. Next, it will
-evaluate the outer list, passing the values of the second and
-subsequent elements of the list to the function `message'.
-
-As we have seen, `message' is an Emacs Lisp function especially
-designed for sending a one line message to a user. (*Note The
-`message' function: message.) In summary, the `message' function
-prints its first argument in the echo area as is, except for
-occurrences of `%d', `%s', or `%c'. When it sees one of these
-control sequences, the function looks to the second and subsequent
-arguments and prints the value of the argument in the location in the
-string where the control sequence is located.
-
-In the interactive `multiply-by-seven' function, the control string
-is `%d', which requires a number, and the value returned by
-evaluating `(* 7 5)' is the number 35. Consequently, the number 35
-is printed in place of the `%d' and the message is `The result is 35'.
-
-(Note that when you call the function `multiply-by-seven', the
-message is printed without quotes, but when you call `message', the
-text is printed in double quotes. This is because the value returned
-by `message' is what appears in the echo area when you evaluate an
-expression whose first element is `message'; but when embedded in a
-function, `message' prints the text as a side effect without quotes.)
-
-Different Options for `interactive'
-===================================
-
-In the example, `multiply-by-seven' used `"p"' as the argument to
-`interactive'. This argument told Emacs to interpret your typing
-either `C-u' followed by a number or <META> followed by a number as a
-command to pass that number to the function as its argument. Emacs
-has more than twenty characters predefined for use with
-`interactive'. In almost every case, one of these options will
-enable you to pass the right information interactively to a function.
-(*Note Code Characters for `interactive': (elisp)Interactive Codes.)
-
-For example, the character `r' causes Emacs to pass the beginning and
-end of the region (the current values of point and mark) to the
-function as two separate arguments. It is used as follows:
-
- (interactive "r")
-
-On the other hand, a `B' tells Emacs to ask for the name of a buffer
-that will be passed to the function. When it sees a `B', Emacs will
-ask for the name by prompting the user in the minibuffer, using a
-string that follows the `B', as in `"BAppend to buffer: "'. Not only
-will Emacs prompt for the name, but Emacs will complete the name if
-you type enough of it and press <TAB>.
-
-A function with two or more arguments can have information passed to
-each argument by adding parts to the string that follows
-`interactive'. When you do this, the information is passed to each
-argument in the same order it is specified in the `interactive' list.
-In the string, each part is separated from the next part by a `\n',
-which is a newline. For example, you could follow `"BAppend to
-buffer: "' with a `\n') and an `r'. This would cause Emacs to pass
-the values of point and mark to the function as well as prompt you
-for the buffer--three arguments in all.
-
-In this case, the function definition would look like the following,
-where `buffer', `start', and `end' are the symbols to which
-`interactive' binds the buffer and the current values of the
-beginning and ending of the region:
-
- (defun NAME-OF-FUNCTION (buffer start end)
- "DOCUMENTATION..."
- (interactive "BAppend to buffer: \nr")
- BODY-OF-FUNCTION...)
-
-(The space after the colon in the prompt makes it look better when you
-are prompted. The `append-to-buffer' function looks exactly like
-this. *Note The Definition of `append-to-buffer': append-to-buffer.)
-
-If a function does not have arguments, then `interactive' does not
-require any. Such a function contains the simple expression
-`(interactive)'. The `mark-whole-buffer' function is like this.
-
-Alternatively, if the special letter-codes are not right for your
-application, you can pass your own arguments to `interactive' as a
-list. *Note Using `Interactive': (elisp)interactive, for more
-information about this advanced technique.
-
-Install Code Permanently
-========================
-
-When you install a function definition by evaluating it, it will stay
-installed until you quit Emacs. The next time you start a new session
-of Emacs, the function will not be installed unless you evaluate the
-function definition again.
-
-At some point, you may want to have code installed automatically
-whenever you start a new session of Emacs. There are several ways of
-doing this:
-
- * If you have code that is just for yourself, you can put the code
- for the function definition in your `.emacs' initialization
- file. When you start Emacs, your `.emacs' file is automatically
- evaluated and all the function definitions within it are
- installed. *Note Your `.emacs' File: Emacs Initialization.
-
- * Alternatively, you can put the function definitions that you want
- installed in one or more files of their own and use the `load'
- function to cause Emacs to evaluate and thereby install each of
- the functions in the files. *Note Loading Files: Loading Files.
-
- * On the other hand, if you have code that your whole site will
- use, it is usual to put it in a file called `site-init.el' that
- is loaded when Emacs is built. This makes the code available to
- everyone who uses your machine. (See the `INSTALL' file that is
- part of the Emacs distribution.)
-
-Finally, if you have code that everyone who uses Emacs may want, you
-can post it on a computer network or send a copy to the Free Software
-Foundation. (When you do this, please license the code and its
-documentation under a license that permits other people to run, copy,
-study, modify, and redistribute the code and which protects you from
-having your work taken from you.) If you send a copy of your code to
-the Free Software Foundation, and properly protect yourself and
-others, it may be included in the next release of Emacs. In large
-part, this is how Emacs has grown over the past years, by donations.
-
-`let'
-=====
-
-The `let' expression is a special form in Lisp that you will need to
-use in most function definitions.
-
-`let' is used to attach or bind a symbol to a value in such a way
-that the Lisp interpreter will not confuse the variable with a
-variable of the same name that is not part of the function.
-
-To understand why the `let' special form is necessary, consider the
-situation in which you own a home that you generally refer to as `the
-house', as in the sentence, "The house needs painting." If you are
-visiting a friend and your host refers to `the house', he is likely
-to be referring to _his_ house, not yours, that is, to a different
-house.
-
-If your friend is referring to his house and you think he is referring
-to your house, you may be in for some confusion. The same thing could
-happen in Lisp if a variable that is used inside of one function has
-the same name as a variable that is used inside of another function,
-and the two are not intended to refer to the same value. The `let'
-special form prevents this kind of confusion.
-
-`let' Prevents Confusion
-------------------------
-
-The `let' special form prevents confusion. `let' creates a name for
-a "local variable" that overshadows any use of the same name outside
-the `let' expression. This is like understanding that whenever your
-host refers to `the house', he means his house, not yours. (Symbols
-used in argument lists work the same way. *Note The `defun' Special
-Form: defun.)
-
-Local variables created by a `let' expression retain their value
-_only_ within the `let' expression itself (and within expressions
-called within the `let' expression); the local variables have no
-effect outside the `let' expression.
-
-Another way to think about `let' is that it is like a `setq' that is
-temporary and local. The values set by `let' are automatically
-undone when the `let' is finished. The setting only affects
-expressions that are inside the bounds of the `let' expression. In
-computer science jargon, we would say "the binding of a symbol is
-visible only in functions called in the `let' form; in Emacs Lisp,
-scoping is dynamic, not lexical."
-
-`let' can create more than one variable at once. Also, `let' gives
-each variable it creates an initial value, either a value specified
-by you, or `nil'. (In the jargon, this is called `binding the
-variable to the value'.) After `let' has created and bound the
-variables, it executes the code in the body of the `let', and returns
-the value of the last expression in the body, as the value of the
-whole `let' expression. (`Execute' is a jargon term that means to
-evaluate a list; it comes from the use of the word meaning `to give
-practical effect to' (`Oxford English Dictionary'). Since you
-evaluate an expression to perform an action, `execute' has evolved as
-a synonym to `evaluate'.)
-
-The Parts of a `let' Expression
--------------------------------
-
-A `let' expression is a list of three parts. The first part is the
-symbol `let'. The second part is a list, called a "varlist", each
-element of which is either a symbol by itself or a two-element list,
-the first element of which is a symbol. The third part of the `let'
-expression is the body of the `let'. The body usually consists of
-one or more lists.
-
-A template for a `let' expression looks like this:
-
- (let VARLIST BODY...)
-
-The symbols in the varlist are the variables that are given initial
-values by the `let' special form. Symbols by themselves are given
-the initial value of `nil'; and each symbol that is the first element
-of a two-element list is bound to the value that is returned when the
-Lisp interpreter evaluates the second element.
-
-Thus, a varlist might look like this: `(thread (needles 3))'. In
-this case, in a `let' expression, Emacs binds the symbol `thread' to
-an initial value of `nil', and binds the symbol `needles' to an
-initial value of 3.
-
-When you write a `let' expression, what you do is put the appropriate
-expressions in the slots of the `let' expression template.
-
-If the varlist is composed of two-element lists, as is often the case,
-the template for the `let' expression looks like this:
-
- (let ((VARIABLE VALUE)
- (VARIABLE VALUE)
- ...)
- BODY...)
-
-Sample `let' Expression
------------------------
-
-The following expression creates and gives initial values to the two
-variables `zebra' and `tiger'. The body of the `let' expression is a
-list which calls the `message' function.
-
- (let ((zebra 'stripes)
- (tiger 'fierce))
- (message "One kind of animal has %s and another is %s."
- zebra tiger))
-
-Here, the varlist is `((zebra 'stripes) (tiger 'fierce))'.
-
-The two variables are `zebra' and `tiger'. Each variable is the
-first element of a two-element list and each value is the second
-element of its two-element list. In the varlist, Emacs binds the
-variable `zebra' to the value `stripes', and binds the variable
-`tiger' to the value `fierce'. In this example, both values are
-symbols preceded by a quote. The values could just as well have been
-another list or a string. The body of the `let' follows after the
-list holding the variables. In this example, the body is a list that
-uses the `message' function to print a string in the echo area.
-
-You may evaluate the example in the usual fashion, by placing the
-cursor after the last parenthesis and typing `C-x C-e'. When you do
-this, the following will appear in the echo area:
-
- "One kind of animal has stripes and another is fierce."
-
-As we have seen before, the `message' function prints its first
-argument, except for `%s'. In this example, the value of the variable
-`zebra' is printed at the location of the first `%s' and the value of
-the variable `tiger' is printed at the location of the second `%s'.
-
-Uninitialized Variables in a `let' Statement
---------------------------------------------
-
-If you do not bind the variables in a `let' statement to specific
-initial values, they will automatically be bound to an initial value
-of `nil', as in the following expression:
-
- (let ((birch 3)
- pine
- fir
- (oak 'some))
- (message
- "Here are %d variables with %s, %s, and %s value."
- birch pine fir oak))
-
-Here, the varlist is `((birch 3) pine fir (oak 'some))'.
-
-If you evaluate this expression in the usual way, the following will
-appear in your echo area:
-
- "Here are 3 variables with nil, nil, and some value."
-
-In this example, Emacs binds the symbol `birch' to the number 3,
-binds the symbols `pine' and `fir' to `nil', and binds the symbol
-`oak' to the value `some'.
-
-Note that in the first part of the `let', the variables `pine' and
-`fir' stand alone as atoms that are not surrounded by parentheses;
-this is because they are being bound to `nil', the empty list. But
-`oak' is bound to `some' and so is a part of the list `(oak 'some)'.
-Similarly, `birch' is bound to the number 3 and so is in a list with
-that number. (Since a number evaluates to itself, the number does
-not need to be quoted. Also, the number is printed in the message
-using a `%d' rather than a `%s'.) The four variables as a group are
-put into a list to delimit them from the body of the `let'.
-
-The `if' Special Form
-=====================
-
-A third special form, in addition to `defun' and `let', is the
-conditional `if'. This form is used to instruct the computer to make
-decisions. You can write function definitions without using `if',
-but it is used often enough, and is important enough, to be included
-here. It is used, for example, in the code for the function
-`beginning-of-buffer'.
-
-The basic idea behind an `if', is that "_if_ a test is true, _then_
-an expression is evaluated." If the test is not true, the expression
-is not evaluated. For example, you might make a decision such as,
-"if it is warm and sunny, then go to the beach!"
-
-`if' in more detail
--------------------
-
-An `if' expression written in Lisp does not use the word `then'; the
-test and the action are the second and third elements of the list
-whose first element is `if'. Nonetheless, the test part of an `if'
-expression is often called the "if-part" and the second argument is
-often called the "then-part".
-
-Also, when an `if' expression is written, the true-or-false-test is
-usually written on the same line as the symbol `if', but the action
-to carry out if the test is true, the "then-part", is written on the
-second and subsequent lines. This makes the `if' expression easier
-to read.
-
- (if TRUE-OR-FALSE-TEST
- ACTION-TO-CARRY-OUT-IF-TEST-IS-TRUE)
-
-The true-or-false-test will be an expression that is evaluated by the
-Lisp interpreter.
-
-Here is an example that you can evaluate in the usual manner. The
-test is whether the number 5 is greater than the number 4. Since it
-is, the message `5 is greater than 4!' will be printed.
-
- (if (> 5 4) ; if-part
- (message "5 is greater than 4!")) ; then-part
-
-(The function `>' tests whether its first argument is greater than
-its second argument and returns true if it is.)
-
-Of course, in actual use, the test in an `if' expression will not be
-fixed for all time as it is by the expression `(> 5 4)'. Instead, at
-least one of the variables used in the test will be bound to a value
-that is not known ahead of time. (If the value were known ahead of
-time, we would not need to run the test!)
-
-For example, the value may be bound to an argument of a function
-definition. In the following function definition, the character of
-the animal is a value that is passed to the function. If the value
-bound to `characteristic' is `fierce', then the message, `It's a
-tiger!' will be printed; otherwise, `nil' will be returned.
-
- (defun type-of-animal (characteristic)
- "Print message in echo area depending on CHARACTERISTIC.
- If the CHARACTERISTIC is the symbol `fierce',
- then warn of a tiger."
- (if (equal characteristic 'fierce)
- (message "It's a tiger!")))
-
-If you are reading this inside of GNU Emacs, you can evaluate the
-function definition in the usual way to install it in Emacs, and then
-you can evaluate the following two expressions to see the results:
-
- (type-of-animal 'fierce)
-
- (type-of-animal 'zebra)
-
-When you evaluate `(type-of-animal 'fierce)', you will see the
-following message printed in the echo area: `"It's a tiger!"'; and
-when you evaluate `(type-of-animal 'zebra)' you will see `nil'
-printed in the echo area.
-
-The `type-of-animal' Function in Detail
----------------------------------------
-
-Let's look at the `type-of-animal' function in detail.
-
-The function definition for `type-of-animal' was written by filling
-the slots of two templates, one for a function definition as a whole,
-and a second for an `if' expression.
-
-The template for every function that is not interactive is:
-
- (defun NAME-OF-FUNCTION (ARGUMENT-LIST)
- "DOCUMENTATION..."
- BODY...)
-
-The parts of the function that match this template look like this:
-
- (defun type-of-animal (characteristic)
- "Print message in echo area depending on CHARACTERISTIC.
- If the CHARACTERISTIC is the symbol `fierce',
- then warn of a tiger."
- BODY: THE `if' EXPRESSION)
-
-The name of function is `type-of-animal'; it is passed the value of
-one argument. The argument list is followed by a multi-line
-documentation string. The documentation string is included in the
-example because it is a good habit to write documentation string for
-every function definition. The body of the function definition
-consists of the `if' expression.
-
-The template for an `if' expression looks like this:
-
- (if TRUE-OR-FALSE-TEST
- ACTION-TO-CARRY-OUT-IF-THE-TEST-RETURNS-TRUE)
-
-In the `type-of-animal' function, the code for the `if' looks like
-this:
-
- (if (equal characteristic 'fierce)
- (message "It's a tiger!")))
-
-Here, the true-or-false-test is the expression:
-
- (equal characteristic 'fierce)
-
-In Lisp, `equal' is a function that determines whether its first
-argument is equal to its second argument. The second argument is the
-quoted symbol `'fierce' and the first argument is the value of the
-symbol `characteristic'--in other words, the argument passed to this
-function.
-
-In the first exercise of `type-of-animal', the argument `fierce' is
-passed to `type-of-animal'. Since `fierce' is equal to `fierce', the
-expression, `(equal characteristic 'fierce)', returns a value of
-true. When this happens, the `if' evaluates the second argument or
-then-part of the `if': `(message "It's tiger!")'.
-
-On the other hand, in the second exercise of `type-of-animal', the
-argument `zebra' is passed to `type-of-animal'. `zebra' is not equal
-to `fierce', so the then-part is not evaluated and `nil' is returned
-by the `if' expression.
-
-If-then-else Expressions
-========================
-
-An `if' expression may have an optional third argument, called the
-"else-part", for the case when the true-or-false-test returns false.
-When this happens, the second argument or then-part of the overall
-`if' expression is _not_ evaluated, but the third or else-part _is_
-evaluated. You might think of this as the cloudy day alternative for
-the decision `if it is warm and sunny, then go to the beach, else
-read a book!".
-
-The word "else" is not written in the Lisp code; the else-part of an
-`if' expression comes after the then-part. In the written Lisp, the
-else-part is usually written to start on a line of its own and is
-indented less than the then-part:
-
- (if TRUE-OR-FALSE-TEST
- ACTION-TO-CARRY-OUT-IF-THE-TEST-RETURNS-TRUE
- ACTION-TO-CARRY-OUT-IF-THE-TEST-RETURNS-FALSE)
-
-For example, the following `if' expression prints the message `4 is
-not greater than 5!' when you evaluate it in the usual way:
-
- (if (> 4 5) ; if-part
- (message "5 is greater than 4!") ; then-part
- (message "4 is not greater than 5!")) ; else-part
-
-Note that the different levels of indentation make it easy to
-distinguish the then-part from the else-part. (GNU Emacs has several
-commands that automatically indent `if' expressions correctly. *Note
-GNU Emacs Helps You Type Lists: Typing Lists.)
-
-We can extend the `type-of-animal' function to include an else-part
-by simply incorporating an additional part to the `if' expression.
-
-You can see the consequences of doing this if you evaluate the
-following version of the `type-of-animal' function definition to
-install it and then evaluate the two subsequent expressions to pass
-different arguments to the function.
-
- (defun type-of-animal (characteristic) ; Second version.
- "Print message in echo area depending on CHARACTERISTIC.
- If the CHARACTERISTIC is the symbol `fierce',
- then warn of a tiger;
- else say it's not fierce."
- (if (equal characteristic 'fierce)
- (message "It's a tiger!")
- (message "It's not fierce!")))
-
-
- (type-of-animal 'fierce)
-
- (type-of-animal 'zebra)
-
-When you evaluate `(type-of-animal 'fierce)', you will see the
-following message printed in the echo area: `"It's a tiger!"'; but
-when you evaluate `(type-of-animal 'zebra)', you will see `"It's not
-fierce!"'.
-
-(Of course, if the CHARACTERISTIC were `ferocious', the message
-`"It's not fierce!"' would be printed; and it would be misleading!
-When you write code, you need to take into account the possibility
-that some such argument will be tested by the `if' and write your
-program accordingly.)
-
-Truth and Falsehood in Emacs Lisp
-=================================
-
-There is an important aspect to the truth test in an `if' expression.
-So far, we have spoken of `true' and `false' as values of predicates
-as if they were new kinds of Emacs Lisp objects. In fact, `false' is
-just our old friend `nil'. Anything else--anything at all--is `true'.
-
-The expression that tests for truth is interpreted as "true" if the
-result of evaluating it is a value that is not `nil'. In other
-words, the result of the test is considered true if the value
-returned is a number such as 47, a string such as `"hello"', or a
-symbol (other than `nil') such as `flowers', or a list, or even a
-buffer!
-
-An explanation of `nil'
------------------------
-
-Before illustrating a test for truth, we need an explanation of `nil'.
-
-In Emacs Lisp, the symbol `nil' has two meanings. First, it means the
-empty list. Second, it means false and is the value returned when a
-true-or-false-test tests false. `nil' can be written as an empty
-list, `()', or as `nil'. As far as the Lisp interpreter is
-concerned, `()' and `nil' are the same. Humans, however, tend to use
-`nil' for false and `()' for the empty list.
-
-In Emacs Lisp, any value that is not `nil'--is not the empty list--is
-considered true. This means that if an evaluation returns something
-that is not an empty list, an `if' expression will test true. For
-example, if a number is put in the slot for the test, it will be
-evaluated and will return itself, since that is what numbers do when
-evaluated. In this conditional, the `if' expression will test true.
-The expression tests false only when `nil', an empty list, is
-returned by evaluating the expression.
-
-You can see this by evaluating the two expressions in the following
-examples.
-
-In the first example, the number 4 is evaluated as the test in the
-`if' expression and returns itself; consequently, the then-part of
-the expression is evaluated and returned: `true' appears in the echo
-area. In the second example, the `nil' indicates false;
-consequently, the else-part of the expression is evaluated and
-returned: `false' appears in the echo area.
-
- (if 4
- 'true
- 'false)
-
- (if nil
- 'true
- 'false)
-
-Incidentally, if some other useful value is not available for a test
-that returns true, then the Lisp interpreter will return the symbol
-`t' for true. For example, the expression `(> 5 4)' returns `t' when
-evaluated, as you can see by evaluating it in the usual way:
-
- (> 5 4)
-
-On the other hand, this function returns `nil' if the test is false.
-
- (> 4 5)
-
-`save-excursion'
-================
-
-The `save-excursion' function is the fourth and final special form
-that we will discuss in this chapter.
-
-In Emacs Lisp programs used for editing, the `save-excursion'
-function is very common. It saves the location of point and mark,
-executes the body of the function, and then restores point and mark to
-their previous positions if their locations were changed. Its primary
-purpose is to keep the user from being surprised and disturbed by
-unexpected movement of point or mark.
-
-Point and Mark
---------------
-
-Before discussing `save-excursion', however, it may be useful first
-to review what point and mark are in GNU Emacs. "Point" is the
-current location of the cursor. Wherever the cursor is, that is
-point. More precisely, on terminals where the cursor appears to be
-on top of a character, point is immediately before the character. In
-Emacs Lisp, point is an integer. The first character in a buffer is
-number one, the second is number two, and so on. The function
-`point' returns the current position of the cursor as a number. Each
-buffer has its own value for point.
-
-The "mark" is another position in the buffer; its value can be set
-with a command such as `C-<SPC>' (`set-mark-command'). If a mark has
-been set, you can use the command `C-x C-x'
-(`exchange-point-and-mark') to cause the cursor to jump to the mark
-and set the mark to be the previous position of point. In addition,
-if you set another mark, the position of the previous mark is saved
-in the mark ring. Many mark positions can be saved this way. You
-can jump the cursor to a saved mark by typing `C-u C-<SPC>' one or
-more times.
-
-The part of the buffer between point and mark is called "the region".
-Numerous commands work on the region, including `center-region',
-`count-lines-region', `kill-region', and `print-region'.
-
-The `save-excursion' special form saves the locations of point and
-mark and restores those positions after the code within the body of
-the special form is evaluated by the Lisp interpreter. Thus, if
-point were in the beginning of a piece of text and some code moved
-point to the end of the buffer, the `save-excursion' would put point
-back to where it was before, after the expressions in the body of the
-function were evaluated.
-
-In Emacs, a function frequently moves point as part of its internal
-workings even though a user would not expect this. For example,
-`count-lines-region' moves point. To prevent the user from being
-bothered by jumps that are both unexpected and (from the user's point
-of view) unnecessary, `save-excursion' is often used to keep point and
-mark in the location expected by the user. The use of
-`save-excursion' is good housekeeping.
-
-To make sure the house stays clean, `save-excursion' restores the
-values of point and mark even if something goes wrong in the code
-inside of it (or, to be more precise and to use the proper jargon,
-"in case of abnormal exit"). This feature is very helpful.
-
-In addition to recording the values of point and mark,
-`save-excursion' keeps track of the current buffer, and restores it,
-too. This means you can write code that will change the buffer and
-have `save-excursion' switch you back to the original buffer. This
-is how `save-excursion' is used in `append-to-buffer'. (*Note The
-Definition of `append-to-buffer': append-to-buffer.)
-
-Template for a `save-excursion' Expression
-------------------------------------------
-
-The template for code using `save-excursion' is simple:
-
- (save-excursion
- BODY...)
-
-The body of the function is one or more expressions that will be
-evaluated in sequence by the Lisp interpreter. If there is more than
-one expression in the body, the value of the last one will be returned
-as the value of the `save-excursion' function. The other expressions
-in the body are evaluated only for their side effects; and
-`save-excursion' itself is used only for its side effect (which is
-restoring the positions of point and mark).
-
-In more detail, the template for a `save-excursion' expression looks
-like this:
-
- (save-excursion
- FIRST-EXPRESSION-IN-BODY
- SECOND-EXPRESSION-IN-BODY
- THIRD-EXPRESSION-IN-BODY
- ...
- LAST-EXPRESSION-IN-BODY)
-
-An expression, of course, may be a symbol on its own or a list.
-
-In Emacs Lisp code, a `save-excursion' expression often occurs within
-the body of a `let' expression. It looks like this:
-
- (let VARLIST
- (save-excursion
- BODY...))
-
-Review
-======
-
-In the last few chapters we have introduced a fair number of functions
-and special forms. Here they are described in brief, along with a few
-similar functions that have not been mentioned yet.
-
-`eval-last-sexp'
- Evaluate the last symbolic expression before the current
- location of point. The value is printed in the echo area unless
- the function is invoked with an argument; in that case, the
- output is printed in the current buffer. This command is
- normally bound to `C-x C-e'.
-
-`defun'
- Define function. This special form has up to five parts: the
- name, a template for the arguments that will be passed to the
- function, documentation, an optional interactive declaration,
- and the body of the definition.
-
- For example:
-
- (defun back-to-indentation ()
- "Move point to first visible character on line."
- (interactive)
- (beginning-of-line 1)
- (skip-chars-forward " \t"))
-
-`interactive'
- Declare to the interpreter that the function can be used
- interactively. This special form may be followed by a string
- with one or more parts that pass the information to the
- arguments of the function, in sequence. These parts may also
- tell the interpreter to prompt for information. Parts of the
- string are separated by newlines, `\n'.
-
- Common code characters are:
-
- `b'
- The name of an existing buffer.
-
- `f'
- The name of an existing file.
-
- `p'
- The numeric prefix argument. (Note that this `p' is lower
- case.)
-
- `r'
- Point and the mark, as two numeric arguments, smallest
- first. This is the only code letter that specifies two
- successive arguments rather than one.
-
- *Note Code Characters for `interactive': (elisp)Interactive
- Codes, for a complete list of code characters.
-
-`let'
- Declare that a list of variables is for use within the body of
- the `let' and give them an initial value, either `nil' or a
- specified value; then evaluate the rest of the expressions in
- the body of the `let' and return the value of the last one.
- Inside the body of the `let', the Lisp interpreter does not see
- the values of the variables of the same names that are bound
- outside of the `let'.
-
- For example,
-
- (let ((foo (buffer-name))
- (bar (buffer-size)))
- (message
- "This buffer is %s and has %d characters."
- foo bar))
-
-`save-excursion'
- Record the values of point and mark and the current buffer before
- evaluating the body of this special form. Restore the values of
- point and mark and buffer afterward.
-
- For example,
-
- (message "We are %d characters into this buffer."
- (- (point)
- (save-excursion
- (goto-char (point-min)) (point))))
-
-`if'
- Evaluate the first argument to the function; if it is true,
- evaluate the second argument; else evaluate the third argument,
- if there is one.
-
- The `if' special form is called a "conditional". There are
- other conditionals in Emacs Lisp, but `if' is perhaps the most
- commonly used.
-
- For example,
-
- (if (string-equal
- (number-to-string 21)
- (substring (emacs-version) 10 12))
- (message "This is version 21 Emacs")
- (message "This is not version 21 Emacs"))
-
-`equal'
-`eq'
- Test whether two objects are the same. `equal' uses one meaning
- of the word `same' and `eq' uses another: `equal' returns true
- if the two objects have a similar structure and contents, such as
- two copies of the same book. On the other hand, `eq', returns
- true if both arguments are actually the same object.
-
-`<'
-`>'
-`<='
-`>='
- The `<' function tests whether its first argument is smaller than
- its second argument. A corresponding function, `>', tests
- whether the first argument is greater than the second.
- Likewise, `<=' tests whether the first argument is less than or
- equal to the second and `>=' tests whether the first argument is
- greater than or equal to the second. In all cases, both
- arguments must be numbers or markers (markers indicate positions
- in buffers).
-
-`string<'
-`string-lessp'
-`string='
-`string-equal'
- The `string-lessp' function tests whether its first argument is
- smaller than the second argument. A shorter, alternative name
- for the same function (a `defalias') is `string<'.
-
- The arguments to `string-lessp' must be strings or symbols; the
- ordering is lexicographic, so case is significant. The print
- names of symbols are used instead of the symbols themselves.
-
- An empty string, `""', a string with no characters in it, is
- smaller than any string of characters.
-
- `string-equal' provides the corresponding test for equality. Its
- shorter, alternative name is `string='. There are no string test
- functions that correspond to >, `>=', or `<='.
-
-`message'
- Print a message in the echo area. The first argument is a string
- that can contain `%s', `%d', or `%c' to print the value of
- arguments that follow the string. The argument used by `%s' must
- be a string or a symbol; the argument used by `%d' must be a
- number. The argument used by `%c' must be an ascii code number;
- it will be printed as the character with that ASCII code.
-
-`setq'
-`set'
- The `setq' function sets the value of its first argument to the
- value of the second argument. The first argument is
- automatically quoted by `setq'. It does the same for succeeding
- pairs of arguments. Another function, `set', takes only two
- arguments and evaluates both of them before setting the value
- returned by its first argument to the value returned by its
- second argument.
-
-`buffer-name'
- Without an argument, return the name of the buffer, as a string.
-
-`buffer-file-name'
- Without an argument, return the name of the file the buffer is
- visiting.
-
-`current-buffer'
- Return the buffer in which Emacs is active; it may not be the
- buffer that is visible on the screen.
-
-`other-buffer'
- Return the most recently selected buffer (other than the buffer
- passed to `other-buffer' as an argument and other than the
- current buffer).
-
-`switch-to-buffer'
- Select a buffer for Emacs to be active in and display it in the
- current window so users can look at it. Usually bound to `C-x
- b'.
-
-`set-buffer'
- Switch Emacs' attention to a buffer on which programs will run.
- Don't alter what the window is showing.
-
-`buffer-size'
- Return the number of characters in the current buffer.
-
-`point'
- Return the value of the current position of the cursor, as an
- integer counting the number of characters from the beginning of
- the buffer.
-
-`point-min'
- Return the minimum permissible value of point in the current
- buffer. This is 1, unless narrowing is in effect.
-
-`point-max'
- Return the value of the maximum permissible value of point in the
- current buffer. This is the end of the buffer, unless narrowing
- is in effect.
-
-Exercises
-=========
-
- * Write a non-interactive function that doubles the value of its
- argument, a number. Make that function interactive.
-
- * Write a function that tests whether the current value of
- `fill-column' is greater than the argument passed to the
- function, and if so, prints an appropriate message.
-
-A Few Buffer-Related Functions
-******************************
-
-In this chapter we study in detail several of the functions used in
-GNU Emacs. This is called a "walk-through". These functions are
-used as examples of Lisp code, but are not imaginary examples; with
-the exception of the first, simplified function definition, these
-functions show the actual code used in GNU Emacs. You can learn a
-great deal from these definitions. The functions described here are
-all related to buffers. Later, we will study other functions.
-
-Finding More Information
-========================
-
-In this walk-through, I will describe each new function as we come to
-it, sometimes in detail and sometimes briefly. If you are interested,
-you can get the full documentation of any Emacs Lisp function at any
-time by typing `C-h f' and then the name of the function (and then
-<RET>). Similarly, you can get the full documentation for a variable
-by typing `C-h v' and then the name of the variable (and then <RET>).
-
-In versions 20 and higher, when a function is written in Emacs Lisp,
-`describe-function' will also tell you the location of the function
-definition. If you move point over the file name and press the <RET>
-key, which is this case means `help-follow' rather than `return' or
-`enter', Emacs will take you directly to the function definition.
-
-More generally, if you want to see a function in its original source
-file, you can use the `find-tags' function to jump to it.
-`find-tags' works with a wide variety of languages, not just Lisp,
-and C, and it works with non-programming text as well. For example,
-`find-tags' will jump to the various nodes in the Texinfo source file
-of this document.
-
-The `find-tags' function depends on `tags tables' that record the
-locations of the functions, variables, and other items to which
-`find-tags' jumps.
-
-To use the `find-tags' command, type `M-.' (i.e., type the <META>
-key and the period key at the same time, or else type the <ESC> key
-and then type the period key), and then, at the prompt, type in the
-name of the function whose source code you want to see, such as
-`mark-whole-buffer', and then type <RET>. Emacs will switch buffers
-and display the source code for the function on your screen. To
-switch back to your current buffer, type `C-x b <RET>'. (On some
-keyboards, the <META> key is labelled <ALT>.)
-
-Depending on how the initial default values of your copy of Emacs are
-set, you may also need to specify the location of your `tags table',
-which is a file called `TAGS'. For example, if you are interested in
-Emacs sources, the tags table you will most likely want, if it has
-already been created for you, will be in a subdirectory of the
-`/usr/local/share/emacs/' directory; thus you would use the `M-x
-visit-tags-table' command and specify a pathname such as
-`/usr/local/share/emacs/21.0.100/lisp/TAGS' or
-`/usr/local/src/emacs/lisp/TAGS'. If the tags table has not already
-been created, you will have to create it yourself.
-
-To create a `TAGS' file in a specific directory, switch to that
-directory in Emacs using `M-x cd' command, or list the directory with
-`C-x d' (`dired'). Then run the compile command, with `etags *.el'
-as the command to execute
-
- M-x compile RET etags *.el RET
-
-For more information, see *Note Create Your Own `TAGS' File: etags.
-
-After you become more familiar with Emacs Lisp, you will find that
-you will frequently use `find-tags' to navigate your way around
-source code; and you will create your own `TAGS' tables.
-
-Incidentally, the files that contain Lisp code are conventionally
-called "libraries". The metaphor is derived from that of a
-specialized library, such as a law library or an engineering library,
-rather than a general library. Each library, or file, contains
-functions that relate to a particular topic or activity, such as
-`abbrev.el' for handling abbreviations and other typing shortcuts,
-and `help.el' for on-line help. (Sometimes several libraries provide
-code for a single activity, as the various `rmail...' files provide
-code for reading electronic mail.) In `The GNU Emacs Manual', you
-will see sentences such as "The `C-h p' command lets you search the
-standard Emacs Lisp libraries by topic keywords."
-
-A Simplified `beginning-of-buffer' Definition
-=============================================
-
-The `beginning-of-buffer' command is a good function to start with
-since you are likely to be familiar with it and it is easy to
-understand. Used as an interactive command, `beginning-of-buffer'
-moves the cursor to the beginning of the buffer, leaving the mark at
-the previous position. It is generally bound to `M-<'.
-
-In this section, we will discuss a shortened version of the function
-that shows how it is most frequently used. This shortened function
-works as written, but it does not contain the code for a complex
-option. In another section, we will describe the entire function.
-(*Note Complete Definition of `beginning-of-buffer':
-beginning-of-buffer.)
-
-Before looking at the code, let's consider what the function
-definition has to contain: it must include an expression that makes
-the function interactive so it can be called by typing `M-x
-beginning-of-buffer' or by typing a keychord such as `M-<'; it must
-include code to leave a mark at the original position in the buffer;
-and it must include code to move the cursor to the beginning of the
-buffer.
-
-Here is the complete text of the shortened version of the function:
-
- (defun simplified-beginning-of-buffer ()
- "Move point to the beginning of the buffer;
- leave mark at previous position."
- (interactive)
- (push-mark)
- (goto-char (point-min)))
-
-Like all function definitions, this definition has five parts
-following the special form `defun':
-
- 1. The name: in this example, `simplified-beginning-of-buffer'.
-
- 2. A list of the arguments: in this example, an empty list, `()',
-
- 3. The documentation string.
-
- 4. The interactive expression.
-
- 5. The body.
-
-In this function definition, the argument list is empty; this means
-that this function does not require any arguments. (When we look at
-the definition for the complete function, we will see that it may be
-passed an optional argument.)
-
-The interactive expression tells Emacs that the function is intended
-to be used interactively. In this example, `interactive' does not
-have an argument because `simplified-beginning-of-buffer' does not
-require one.
-
-The body of the function consists of the two lines:
-
- (push-mark)
- (goto-char (point-min))
-
-The first of these lines is the expression, `(push-mark)'. When this
-expression is evaluated by the Lisp interpreter, it sets a mark at
-the current position of the cursor, wherever that may be. The
-position of this mark is saved in the mark ring.
-
-The next line is `(goto-char (point-min))'. This expression jumps
-the cursor to the minimum point in the buffer, that is, to the
-beginning of the buffer (or to the beginning of the accessible portion
-of the buffer if it is narrowed. *Note Narrowing and Widening:
-Narrowing & Widening.)
-
-The `push-mark' command sets a mark at the place where the cursor was
-located before it was moved to the beginning of the buffer by the
-`(goto-char (point-min))' expression. Consequently, you can, if you
-wish, go back to where you were originally by typing `C-x C-x'.
-
-That is all there is to the function definition!
-
-When you are reading code such as this and come upon an unfamiliar
-function, such as `goto-char', you can find out what it does by using
-the `describe-function' command. To use this command, type `C-h f'
-and then type in the name of the function and press <RET>. The
-`describe-function' command will print the function's documentation
-string in a `*Help*' window. For example, the documentation for
-`goto-char' is:
-
- One arg, a number. Set point to that number.
- Beginning of buffer is position (point-min),
- end is (point-max).
-
-(The prompt for `describe-function' will offer you the symbol under
-or preceding the cursor, so you can save typing by positioning the
-cursor right over or after the function and then typing `C-h f
-<RET>'.)
-
-The `end-of-buffer' function definition is written in the same way as
-the `beginning-of-buffer' definition except that the body of the
-function contains the expression `(goto-char (point-max))' in place
-of `(goto-char (point-min))'.
-
-The Definition of `mark-whole-buffer'
-=====================================
-
-The `mark-whole-buffer' function is no harder to understand than the
-`simplified-beginning-of-buffer' function. In this case, however, we
-will look at the complete function, not a shortened version.
-
-The `mark-whole-buffer' function is not as commonly used as the
-`beginning-of-buffer' function, but is useful nonetheless: it marks a
-whole buffer as a region by putting point at the beginning and a mark
-at the end of the buffer. It is generally bound to `C-x h'.
-
-An overview of `mark-whole-buffer'
-----------------------------------
-
-In GNU Emacs 20, the code for the complete function looks like this:
-
- (defun mark-whole-buffer ()
- "Put point at beginning and mark at end of buffer."
- (interactive)
- (push-mark (point))
- (push-mark (point-max))
- (goto-char (point-min)))
-
-Like all other functions, the `mark-whole-buffer' function fits into
-the template for a function definition. The template looks like this:
-
- (defun NAME-OF-FUNCTION (ARGUMENT-LIST)
- "DOCUMENTATION..."
- (INTERACTIVE-EXPRESSION...)
- BODY...)
-
-Here is how the function works: the name of the function is
-`mark-whole-buffer'; it is followed by an empty argument list, `()',
-which means that the function does not require arguments. The
-documentation comes next.
-
-The next line is an `(interactive)' expression that tells Emacs that
-the function will be used interactively. These details are similar
-to the `simplified-beginning-of-buffer' function described in the
-previous section.
-
-Body of `mark-whole-buffer'
----------------------------
-
-The body of the `mark-whole-buffer' function consists of three lines
-of code:
-
- (push-mark (point))
- (push-mark (point-max))
- (goto-char (point-min))
-
-The first of these lines is the expression, `(push-mark (point))'.
-
-This line does exactly the same job as the first line of the body of
-the `simplified-beginning-of-buffer' function, which is written
-`(push-mark)'. In both cases, the Lisp interpreter sets a mark at
-the current position of the cursor.
-
-I don't know why the expression in `mark-whole-buffer' is written
-`(push-mark (point))' and the expression in `beginning-of-buffer' is
-written `(push-mark)'. Perhaps whoever wrote the code did not know
-that the arguments for `push-mark' are optional and that if
-`push-mark' is not passed an argument, the function automatically
-sets mark at the location of point by default. Or perhaps the
-expression was written so as to parallel the structure of the next
-line. In any case, the line causes Emacs to determine the position
-of point and set a mark there.
-
-The next line of `mark-whole-buffer' is `(push-mark (point-max)'.
-This expression sets a mark at the point in the buffer that has the
-highest number. This will be the end of the buffer (or, if the
-buffer is narrowed, the end of the accessible portion of the buffer.
-*Note Narrowing and Widening: Narrowing & Widening, for more about
-narrowing.) After this mark has been set, the previous mark, the one
-set at point, is no longer set, but Emacs remembers its position,
-just as all other recent marks are always remembered. This means
-that you can, if you wish, go back to that position by typing `C-u
-C-<SPC>' twice.
-
-(In GNU Emacs 21, the `(push-mark (point-max)' is slightly more
-complicated than shown here. The line reads
-
- (push-mark (point-max) nil t)
-
-(The expression works nearly the same as before. It sets a mark at
-the highest numbered place in the buffer that it can. However, in
-this version, `push-mark' has two additional arguments. The second
-argument to `push-mark' is `nil'. This tells the function it
-_should_ display a message that says `Mark set' when it pushes the
-mark. The third argument is `t'. This tells `push-mark' to activate
-the mark when Transient Mark mode is turned on. Transient Mark mode
-highlights the currently active region. It is usually turned off.)
-
-Finally, the last line of the function is `(goto-char (point-min)))'.
-This is written exactly the same way as it is written in
-`beginning-of-buffer'. The expression moves the cursor to the
-minimum point in the buffer, that is, to the beginning of the buffer
-(or to the beginning of the accessible portion of the buffer). As a
-result of this, point is placed at the beginning of the buffer and
-mark is set at the end of the buffer. The whole buffer is,
-therefore, the region.
-
-The Definition of `append-to-buffer'
-====================================
-
-The `append-to-buffer' command is very nearly as simple as the
-`mark-whole-buffer' command. What it does is copy the region (that
-is, the part of the buffer between point and mark) from the current
-buffer to a specified buffer.
-
-An Overview of `append-to-buffer'
----------------------------------
-
-The `append-to-buffer' command uses the `insert-buffer-substring'
-function to copy the region. `insert-buffer-substring' is described
-by its name: it takes a string of characters from part of a buffer, a
-"substring", and inserts them into another buffer. Most of
-`append-to-buffer' is concerned with setting up the conditions for
-`insert-buffer-substring' to work: the code must specify both the
-buffer to which the text will go and the region that will be copied.
-Here is the complete text of the function:
-
- (defun append-to-buffer (buffer start end)
- "Append to specified buffer the text of the region.
- It is inserted into that buffer before its point.
-
- When calling from a program, give three arguments:
- a buffer or the name of one, and two character numbers
- specifying the portion of the current buffer to be copied."
- (interactive "BAppend to buffer: \nr")
- (let ((oldbuf (current-buffer)))
- (save-excursion
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
-
-The function can be understood by looking at it as a series of
-filled-in templates.
-
-The outermost template is for the function definition. In this
-function, it looks like this (with several slots filled in):
-
- (defun append-to-buffer (buffer start end)
- "DOCUMENTATION..."
- (interactive "BAppend to buffer: \nr")
- BODY...)
-
-The first line of the function includes its name and three arguments.
-The arguments are the `buffer' to which the text will be copied, and
-the `start' and `end' of the region in the current buffer that will
-be copied.
-
-The next part of the function is the documentation, which is clear and
-complete.
-
-The `append-to-buffer' Interactive Expression
----------------------------------------------
-
-Since the `append-to-buffer' function will be used interactively, the
-function must have an `interactive' expression. (For a review of
-`interactive', see *Note Making a Function Interactive: Interactive.)
-The expression reads as follows:
-
- (interactive "BAppend to buffer: \nr")
-
-This expression has an argument inside of quotation marks and that
-argument has two parts, separated by `\n'.
-
-The first part is `BAppend to buffer: '. Here, the `B' tells Emacs
-to ask for the name of the buffer that will be passed to the
-function. Emacs will ask for the name by prompting the user in the
-minibuffer, using the string following the `B', which is the string
-`Append to buffer: '. Emacs then binds the variable `buffer' in the
-function's argument list to the specified buffer.
-
-The newline, `\n', separates the first part of the argument from the
-second part. It is followed by an `r' that tells Emacs to bind the
-two arguments that follow the symbol `buffer' in the function's
-argument list (that is, `start' and `end') to the values of point and
-mark.
-
-The Body of `append-to-buffer'
-------------------------------
-
-The body of the `append-to-buffer' function begins with `let'.
-
-As we have seen before (*note `let': let.), the purpose of a `let'
-expression is to create and give initial values to one or more
-variables that will only be used within the body of the `let'. This
-means that such a variable will not be confused with any variable of
-the same name outside the `let' expression.
-
-We can see how the `let' expression fits into the function as a whole
-by showing a template for `append-to-buffer' with the `let'
-expression in outline:
-
- (defun append-to-buffer (buffer start end)
- "DOCUMENTATION..."
- (interactive "BAppend to buffer: \nr")
- (let ((VARIABLE VALUE))
- BODY...)
-
-The `let' expression has three elements:
-
- 1. The symbol `let';
-
- 2. A varlist containing, in this case, a single two-element list,
- `(VARIABLE VALUE)';
-
- 3. The body of the `let' expression.
-
-In the `append-to-buffer' function, the varlist looks like this:
-
- (oldbuf (current-buffer))
-
-In this part of the `let' expression, the one variable, `oldbuf', is
-bound to the value returned by the `(current-buffer)' expression.
-The variable, `oldbuf', is used to keep track of the buffer in which
-you are working and from which you will copy.
-
-The element or elements of a varlist are surrounded by a set of
-parentheses so the Lisp interpreter can distinguish the varlist from
-the body of the `let'. As a consequence, the two-element list within
-the varlist is surrounded by a circumscribing set of parentheses.
-The line looks like this:
-
- (let ((oldbuf (current-buffer)))
- ... )
-
-The two parentheses before `oldbuf' might surprise you if you did not
-realize that the first parenthesis before `oldbuf' marks the boundary
-of the varlist and the second parenthesis marks the beginning of the
-two-element list, `(oldbuf (current-buffer))'.
-
-`save-excursion' in `append-to-buffer'
---------------------------------------
-
-The body of the `let' expression in `append-to-buffer' consists of a
-`save-excursion' expression.
-
-The `save-excursion' function saves the locations of point and mark,
-and restores them to those positions after the expressions in the
-body of the `save-excursion' complete execution. In addition,
-`save-excursion' keeps track of the original buffer, and restores it.
-This is how `save-excursion' is used in `append-to-buffer'.
-
-Incidentally, it is worth noting here that a Lisp function is normally
-formatted so that everything that is enclosed in a multi-line spread
-is indented more to the right than the first symbol. In this function
-definition, the `let' is indented more than the `defun', and the
-`save-excursion' is indented more than the `let', like this:
-
- (defun ...
- ...
- ...
- (let...
- (save-excursion
- ...
-
-This formatting convention makes it easy to see that the two lines in
-the body of the `save-excursion' are enclosed by the parentheses
-associated with `save-excursion', just as the `save-excursion' itself
-is enclosed by the parentheses associated with the `let':
-
- (let ((oldbuf (current-buffer)))
- (save-excursion
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
-
-The use of the `save-excursion' function can be viewed as a process
-of filling in the slots of a template:
-
- (save-excursion
- FIRST-EXPRESSION-IN-BODY
- SECOND-EXPRESSION-IN-BODY
- ...
- LAST-EXPRESSION-IN-BODY)
-
-In this function, the body of the `save-excursion' contains only two
-expressions. The body looks like this:
-
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end)
-
-When the `append-to-buffer' function is evaluated, the two
-expressions in the body of the `save-excursion' are evaluated in
-sequence. The value of the last expression is returned as the value
-of the `save-excursion' function; the other expression is evaluated
-only for its side effects.
-
-The first line in the body of the `save-excursion' uses the
-`set-buffer' function to change the current buffer to the one
-specified in the first argument to `append-to-buffer'. (Changing the
-buffer is the side effect; as we have said before, in Lisp, a side
-effect is often the primary thing we want.) The second line does the
-primary work of the function.
-
-The `set-buffer' function changes Emacs' attention to the buffer to
-which the text will be copied and from which `save-excursion' will
-return.
-
-The line looks like this:
-
- (set-buffer (get-buffer-create buffer))
-
-The innermost expression of this list is `(get-buffer-create
-buffer)'. This expression uses the `get-buffer-create' function,
-which either gets the named buffer, or if it does not exist, creates
-one with the given name. This means you can use `append-to-buffer' to
-put text into a buffer that did not previously exist.
-
-`get-buffer-create' also keeps `set-buffer' from getting an
-unnecessary error: `set-buffer' needs a buffer to go to; if you were
-to specify a buffer that does not exist, Emacs would baulk. Since
-`get-buffer-create' will create a buffer if none exists, `set-buffer'
-is always provided with a buffer.
-
-The last line of `append-to-buffer' does the work of appending the
-text:
-
- (insert-buffer-substring oldbuf start end)
-
-The `insert-buffer-substring' function copies a string _from_ the
-buffer specified as its first argument and inserts the string into
-the present buffer. In this case, the argument to
-`insert-buffer-substring' is the value of the variable created and
-bound by the `let', namely the value of `oldbuf', which was the
-current buffer when you gave the `append-to-buffer' command.
-
-After `insert-buffer-substring' has done its work, `save-excursion'
-will restore the action to the original buffer and `append-to-buffer'
-will have done its job.
-
-Written in skeletal form, the workings of the body look like this:
-
- (let (BIND-`oldbuf'-TO-VALUE-OF-`current-buffer')
- (save-excursion ; Keep track of buffer.
- CHANGE-BUFFER
- INSERT-SUBSTRING-FROM-`oldbuf'-INTO-BUFFER)
-
- CHANGE-BACK-TO-ORIGINAL-BUFFER-WHEN-FINISHED
- LET-THE-LOCAL-MEANING-OF-`oldbuf'-DISAPPEAR-WHEN-FINISHED
-
-In summary, `append-to-buffer' works as follows: it saves the value
-of the current buffer in the variable called `oldbuf'. It gets the
-new buffer, creating one if need be, and switches Emacs to it. Using
-the value of `oldbuf', it inserts the region of text from the old
-buffer into the new buffer; and then using `save-excursion', it
-brings you back to your original buffer.
-
-In looking at `append-to-buffer', you have explored a fairly complex
-function. It shows how to use `let' and `save-excursion', and how to
-change to and come back from another buffer. Many function
-definitions use `let', `save-excursion', and `set-buffer' this way.
-
-Review
-======
-
-Here is a brief summary of the various functions discussed in this
-chapter.
-
-`describe-function'
-`describe-variable'
- Print the documentation for a function or variable.
- Conventionally bound to `C-h f' and `C-h v'.
-
-`find-tag'
- Find the file containing the source for a function or variable
- and switch buffers to it, positioning point at the beginning of
- the item. Conventionally bound to `M-.' (that's a period
- following the <META> key).
-
-`save-excursion'
- Save the location of point and mark and restore their values
- after the arguments to `save-excursion' have been evaluated.
- Also, remember the current buffer and return to it.
-
-`push-mark'
- Set mark at a location and record the value of the previous mark
- on the mark ring. The mark is a location in the buffer that
- will keep its relative position even if text is added to or
- removed from the buffer.
-
-`goto-char'
- Set point to the location specified by the value of the
- argument, which can be a number, a marker, or an expression
- that returns the number of a position, such as `(point-min)'.
-
-`insert-buffer-substring'
- Copy a region of text from a buffer that is passed to the
- function as an argument and insert the region into the current
- buffer.
-
-`mark-whole-buffer'
- Mark the whole buffer as a region. Normally bound to `C-x h'.
-
-`set-buffer'
- Switch the attention of Emacs to another buffer, but do not
- change the window being displayed. Used when the program rather
- than a human is to work on a different buffer.
-
-`get-buffer-create'
-`get-buffer'
- Find a named buffer or create one if a buffer of that name does
- not exist. The `get-buffer' function returns `nil' if the named
- buffer does not exist.
-
-Exercises
-=========
-
- * Write your own `simplified-end-of-buffer' function definition;
- then test it to see whether it works.
-
- * Use `if' and `get-buffer' to write a function that prints a
- message telling you whether a buffer exists.
-
- * Using `find-tag', find the source for the `copy-to-buffer'
- function.
-
-A Few More Complex Functions
-****************************
-
-In this chapter, we build on what we have learned in previous chapters
-by looking at more complex functions. The `copy-to-buffer' function
-illustrates use of two `save-excursion' expressions in one
-definition, while the `insert-buffer' function illustrates use of an
-asterisk in an `interactive' expression, use of `or', and the
-important distinction between a name and the object to which the name
-refers.
-
-The Definition of `copy-to-buffer'
-==================================
-
-After understanding how `append-to-buffer' works, it is easy to
-understand `copy-to-buffer'. This function copies text into a
-buffer, but instead of adding to the second buffer, it replaces the
-previous text in the second buffer. The code for the
-`copy-to-buffer' function is almost the same as the code for
-`append-to-buffer', except that `erase-buffer' and a second
-`save-excursion' are used. (*Note The Definition of
-`append-to-buffer': append-to-buffer, for the description of
-`append-to-buffer'.)
-
-The body of `copy-to-buffer' looks like this
-
- ...
- (interactive "BCopy to buffer: \nr")
- (let ((oldbuf (current-buffer)))
- (save-excursion
- (set-buffer (get-buffer-create buffer))
- (erase-buffer)
- (save-excursion
- (insert-buffer-substring oldbuf start end)))))
-
-This code is similar to the code in `append-to-buffer': it is only
-after changing to the buffer to which the text will be copied that
-the definition for this function diverges from the definition for
-`append-to-buffer': the `copy-to-buffer' function erases the buffer's
-former contents. (This is what is meant by `replacement'; to replace
-text, Emacs erases the previous text and then inserts new text.)
-After erasing the previous contents of the buffer, `save-excursion'
-is used for a second time and the new text is inserted.
-
-Why is `save-excursion' used twice? Consider again what the function
-does.
-
-In outline, the body of `copy-to-buffer' looks like this:
-
- (let (BIND-`oldbuf'-TO-VALUE-OF-`current-buffer')
- (save-excursion ; First use of `save-excursion'.
- CHANGE-BUFFER
- (erase-buffer)
- (save-excursion ; Second use of `save-excursion'.
- INSERT-SUBSTRING-FROM-`oldbuf'-INTO-BUFFER)))
-
-The first use of `save-excursion' returns Emacs to the buffer from
-which the text is being copied. That is clear, and is just like its
-use in `append-to-buffer'. Why the second use? The reason is that
-`insert-buffer-substring' always leaves point at the _end_ of the
-region being inserted. The second `save-excursion' causes Emacs to
-leave point at the beginning of the text being inserted. In most
-circumstances, users prefer to find point at the beginning of
-inserted text. (Of course, the `copy-to-buffer' function returns the
-user to the original buffer when done--but if the user _then_
-switches to the copied-to buffer, point will go to the beginning of
-the text. Thus, this use of a second `save-excursion' is a little
-nicety.)
-
-The Definition of `insert-buffer'
-=================================
-
-`insert-buffer' is yet another buffer-related function. This command
-copies another buffer _into_ the current buffer. It is the reverse
-of `append-to-buffer' or `copy-to-buffer', since they copy a region
-of text _from_ the current buffer to another buffer.
-
-In addition, this code illustrates the use of `interactive' with a
-buffer that might be "read-only" and the important distinction
-between the name of an object and the object actually referred to.
-
-The Code for `insert-buffer'
-----------------------------
-
-Here is the code:
-
- (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: ")
- (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)))
- (insert-buffer-substring buffer start end)
- (setq newmark (point)))
- (push-mark newmark)))
-
-As with other function definitions, you can use a template to see an
-outline of the function:
-
- (defun insert-buffer (buffer)
- "DOCUMENTATION..."
- (interactive "*bInsert buffer: ")
- BODY...)
-
-The Interactive Expression in `insert-buffer'
----------------------------------------------
-
-In `insert-buffer', the argument to the `interactive' declaration has
-two parts, an asterisk, `*', and `bInsert buffer: '.
-
-A Read-only Buffer
-..................
-
-The asterisk is for the situation when the current buffer is a
-read-only buffer--a buffer that cannot be modified. If
-`insert-buffer' is called when the current buffer is read-only, a
-message to this effect is printed in the echo area and the terminal
-may beep or blink at you; you will not be permitted to insert anything
-into current buffer. The asterisk does not need to be followed by a
-newline to separate it from the next argument.
-
-`b' in an Interactive Expression
-................................
-
-The next argument in the interactive expression starts with a lower
-case `b'. (This is different from the code for `append-to-buffer',
-which uses an upper-case `B'. *Note The Definition of
-`append-to-buffer': append-to-buffer.) The lower-case `b' tells the
-Lisp interpreter that the argument for `insert-buffer' should be an
-existing buffer or else its name. (The upper-case `B' option
-provides for the possibility that the buffer does not exist.) Emacs
-will prompt you for the name of the buffer, offering you a default
-buffer, with name completion enabled. If the buffer does not exist,
-you receive a message that says "No match"; your terminal may beep at
-you as well.
-
-The Body of the `insert-buffer' Function
-----------------------------------------
-
-The body of the `insert-buffer' function has two major parts: an `or'
-expression and a `let' expression. The purpose of the `or'
-expression is to ensure that the argument `buffer' is bound to a
-buffer and not just the name of a buffer. The body of the `let'
-expression contains the code which copies the other buffer into the
-current buffer.
-
-In outline, the two expressions fit into the `insert-buffer' function
-like this:
-
- (defun insert-buffer (buffer)
- "DOCUMENTATION..."
- (interactive "*bInsert buffer: ")
- (or ...
- ...
- (let (VARLIST)
- BODY-OF-`let'... )
-
-To understand how the `or' expression ensures that the argument
-`buffer' is bound to a buffer and not to the name of a buffer, it is
-first necessary to understand the `or' function.
-
-Before doing this, let me rewrite this part of the function using
-`if' so that you can see what is done in a manner that will be
-familiar.
-
-`insert-buffer' With an `if' Instead of an `or'
------------------------------------------------
-
-The job to be done is to make sure the value of `buffer' is a buffer
-itself and not the name of a buffer. If the value is the name, then
-the buffer itself must be got.
-
-You can imagine yourself at a conference where an usher is wandering
-around holding a list with your name on it and looking for you: the
-usher is "bound" to your name, not to you; but when the usher finds
-you and takes your arm, the usher becomes "bound" to you.
-
-In Lisp, you might describe this situation like this:
-
- (if (not (holding-on-to-guest))
- (find-and-take-arm-of-guest))
-
-We want to do the same thing with a buffer--if we do not have the
-buffer itself, we want to get it.
-
-Using a predicate called `bufferp' that tells us whether we have a
-buffer (rather than its name), we can write the code like this:
-
- (if (not (bufferp buffer)) ; if-part
- (setq buffer (get-buffer buffer))) ; then-part
-
-Here, the true-or-false-test of the `if' expression is
-`(not (bufferp buffer))'; and the then-part is the expression
-`(setq buffer (get-buffer buffer))'.
-
-In the test, the function `bufferp' returns true if its argument is a
-buffer--but false if its argument is the name of the buffer. (The
-last character of the function name `bufferp' is the character `p';
-as we saw earlier, such use of `p' is a convention that indicates
-that the function is a predicate, which is a term that means that the
-function will determine whether some property is true or false.
-*Note Using the Wrong Type Object as an Argument: Wrong Type of
-Argument.)
-
-The function `not' precedes the expression `(bufferp buffer)', so the
-true-or-false-test looks like this:
-
- (not (bufferp buffer))
-
-`not' is a function that returns true if its argument is false and
-false if its argument is true. So if `(bufferp buffer)' returns
-true, the `not' expression returns false and vice-versa: what is "not
-true" is false and what is "not false" is true.
-
-Using this test, the `if' expression works as follows: when the value
-of the variable `buffer' is actually a buffer rather then its name,
-the true-or-false-test returns false and the `if' expression does not
-evaluate the then-part. This is fine, since we do not need to do
-anything to the variable `buffer' if it really is a buffer.
-
-On the other hand, when the value of `buffer' is not a buffer itself,
-but the name of a buffer, the true-or-false-test returns true and the
-then-part of the expression is evaluated. In this case, the
-then-part is `(setq buffer (get-buffer buffer))'. This expression
-uses the `get-buffer' function to return an actual buffer itself,
-given its name. The `setq' then sets the variable `buffer' to the
-value of the buffer itself, replacing its previous value (which was
-the name of the buffer).
-
-The `or' in the Body
---------------------
-
-The purpose of the `or' expression in the `insert-buffer' function is
-to ensure that the argument `buffer' is bound to a buffer and not
-just to the name of a buffer. The previous section shows how the job
-could have been done using an `if' expression. However, the
-`insert-buffer' function actually uses `or'. To understand this, it
-is necessary to understand how `or' works.
-
-An `or' function can have any number of arguments. It evaluates each
-argument in turn and returns the value of the first of its arguments
-that is not `nil'. Also, and this is a crucial feature of `or', it
-does not evaluate any subsequent arguments after returning the first
-non-`nil' value.
-
-The `or' expression looks like this:
-
- (or (bufferp buffer)
- (setq buffer (get-buffer buffer)))
-
-The first argument to `or' is the expression `(bufferp buffer)'.
-This expression returns true (a non-`nil' value) if the buffer is
-actually a buffer, and not just the name of a buffer. In the `or'
-expression, if this is the case, the `or' expression returns this
-true value and does not evaluate the next expression--and this is fine
-with us, since we do not want to do anything to the value of `buffer'
-if it really is a buffer.
-
-On the other hand, if the value of `(bufferp buffer)' is `nil', which
-it will be if the value of `buffer' is the name of a buffer, the Lisp
-interpreter evaluates the next element of the `or' expression. This
-is the expression `(setq buffer (get-buffer buffer))'. This
-expression returns a non-`nil' value, which is the value to which it
-sets the variable `buffer'--and this value is a buffer itself, not
-the name of a buffer.
-
-The result of all this is that the symbol `buffer' is always bound to
-a buffer itself rather than to the name of a buffer. All this is
-necessary because the `set-buffer' function in a following line only
-works with a buffer itself, not with the name to a buffer.
-
-Incidentally, using `or', the situation with the usher would be
-written like this:
-
- (or (holding-on-to-guest) (find-and-take-arm-of-guest))
-
-The `let' Expression in `insert-buffer'
----------------------------------------
-
-After ensuring that the variable `buffer' refers to a buffer itself
-and not just to the name of a buffer, the `insert-buffer function'
-continues with a `let' expression. This specifies three local
-variables, `start', `end', and `newmark' and binds them to the
-initial value `nil'. These variables are used inside the remainder
-of the `let' and temporarily hide any other occurrence of variables
-of the same name in Emacs until the end of the `let'.
-
-The body of the `let' contains two `save-excursion' expressions.
-First, we will look at the inner `save-excursion' expression in
-detail. The expression looks like this:
-
- (save-excursion
- (set-buffer buffer)
- (setq start (point-min) end (point-max)))
-
-The expression `(set-buffer buffer)' changes Emacs' attention from
-the current buffer to the one from which the text will copied. In
-that buffer, the variables `start' and `end' are set to the beginning
-and end of the buffer, using the commands `point-min' and
-`point-max'. Note that we have here an illustration of how `setq' is
-able to set two variables in the same expression. The first argument
-of `setq' is set to the value of its second, and its third argument
-is set to the value of its fourth.
-
-After the body of the inner `save-excursion' is evaluated, the
-`save-excursion' restores the original buffer, but `start' and `end'
-remain set to the values of the beginning and end of the buffer from
-which the text will be copied.
-
-The outer `save-excursion' expression looks like this:
-
- (save-excursion
- (INNER-`save-excursion'-EXPRESSION
- (GO-TO-NEW-BUFFER-AND-SET-`start'-AND-`end')
- (insert-buffer-substring buffer start end)
- (setq newmark (point)))
-
-The `insert-buffer-substring' function copies the text _into_ the
-current buffer _from_ the region indicated by `start' and `end' in
-`buffer'. Since the whole of the second buffer lies between `start'
-and `end', the whole of the second buffer is copied into the buffer
-you are editing. Next, the value of point, which will be at the end
-of the inserted text, is recorded in the variable `newmark'.
-
-After the body of the outer `save-excursion' is evaluated, point and
-mark are relocated to their original places.
-
-However, it is convenient to locate a mark at the end of the newly
-inserted text and locate point at its beginning. The `newmark'
-variable records the end of the inserted text. In the last line of
-the `let' expression, the `(push-mark newmark)' expression function
-sets a mark to this location. (The previous location of the mark is
-still accessible; it is recorded on the mark ring and you can go back
-to it with `C-u C-<SPC>'.) Meanwhile, point is located at the
-beginning of the inserted text, which is where it was before you
-called the insert function.
-
-The whole `let' expression looks like this:
-
- (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))
-
-Like the `append-to-buffer' function, the `insert-buffer' function
-uses `let', `save-excursion', and `set-buffer'. In addition, the
-function illustrates one way to use `or'. All these functions are
-building blocks that we will find and use again and again.
-
-Complete Definition of `beginning-of-buffer'
-============================================
-
-The basic structure of the `beginning-of-buffer' function has already
-been discussed. (*Note A Simplified `beginning-of-buffer'
-Definition: simplified-beginning-of-buffer.) This section describes
-the complex part of the definition.
-
-As previously described, when invoked without an argument,
-`beginning-of-buffer' moves the cursor to the beginning of the
-buffer, leaving the mark at the previous position. However, when the
-command is invoked with a number between one and ten, the function
-considers that number to be a fraction of the length of the buffer,
-measured in tenths, and Emacs moves the cursor that fraction of the
-way from the beginning of the buffer. Thus, you can either call this
-function with the key command `M-<', which will move the cursor to
-the beginning of the buffer, or with a key command such as `C-u 7
-M-<' which will move the cursor to a point 70% of the way through the
-buffer. If a number bigger than ten is used for the argument, it
-moves to the end of the buffer.
-
-The `beginning-of-buffer' function can be called with or without an
-argument. The use of the argument is optional.
-
-Optional Arguments
-------------------
-
-Unless told otherwise, Lisp expects that a function with an argument
-in its function definition will be called with a value for that
-argument. If that does not happen, you get an error and a message
-that says `Wrong number of arguments'.
-
-However, optional arguments are a feature of Lisp: a "keyword" may be
-used to tell the Lisp interpreter that an argument is optional. The
-keyword is `&optional'. (The `&' in front of `optional' is part of
-the keyword.) In a function definition, if an argument follows the
-keyword `&optional', a value does not need to be passed to that
-argument when the function is called.
-
-The first line of the function definition of `beginning-of-buffer'
-therefore looks like this:
-
- (defun beginning-of-buffer (&optional arg)
-
-In outline, the whole function looks like this:
-
- (defun beginning-of-buffer (&optional arg)
- "DOCUMENTATION..."
- (interactive "P")
- (push-mark)
- (goto-char
- (IF-THERE-IS-AN-ARGUMENT
- FIGURE-OUT-WHERE-TO-GO
- ELSE-GO-TO
- (point-min))))
-
-The function is similar to the `simplified-beginning-of-buffer'
-function except that the `interactive' expression has `"P"' as an
-argument and the `goto-char' function is followed by an if-then-else
-expression that figures out where to put the cursor if there is an
-argument.
-
-The `"P"' in the `interactive' expression tells Emacs to pass a
-prefix argument, if there is one, to the function. A prefix argument
-is made by typing the <META> key followed by a number, or by typing
-`C-u' and then a number (if you don't type a number, `C-u' defaults
-to 4).
-
-The true-or-false-test of the `if' expression is simple: it is simply
-the argument `arg'. If `arg' has a value that is not `nil', which
-will be the case if `beginning-of-buffer' is called with an argument,
-then this true-or-false-test will return true and the then-part of
-the `if' expression will be evaluated. On the other hand, if
-`beginning-of-buffer' is not called with an argument, the value of
-`arg' will be `nil' and the else-part of the `if' expression will be
-evaluated. The else-part is simply `point-min', and when this is the
-outcome, the whole `goto-char' expression is `(goto-char
-(point-min))', which is how we saw the `beginning-of-buffer' function
-in its simplified form.
-
-`beginning-of-buffer' with an Argument
---------------------------------------
-
-When `beginning-of-buffer' is called with an argument, an expression
-is evaluated which calculates what value to pass to `goto-char'.
-This expression is rather complicated at first sight. It includes an
-inner `if' expression and much arithmetic. It looks like this:
-
- (if (> (buffer-size) 10000)
- ;; Avoid overflow for large buffer sizes!
- (* (prefix-numeric-value arg) (/ (buffer-size) 10))
- (/
- (+ 10
- (*
- (buffer-size) (prefix-numeric-value arg))) 10))
-
-Disentangle `beginning-of-buffer'
-.................................
-
-Like other complex-looking expressions, the conditional expression
-within `beginning-of-buffer' can be disentangled by looking at it as
-parts of a template, in this case, the template for an if-then-else
-expression. In skeletal form, the expression looks like this:
-
- (if (BUFFER-IS-LARGE
- DIVIDE-BUFFER-SIZE-BY-10-AND-MULTIPLY-BY-ARG
- ELSE-USE-ALTERNATE-CALCULATION
-
-The true-or-false-test of this inner `if' expression checks the size
-of the buffer. The reason for this is that the old Version 18 Emacs
-used numbers that are no bigger than eight million or so and in the
-computation that followed, the programmer feared that Emacs might try
-to use over-large numbers if the buffer were large. The term
-`overflow', mentioned in the comment, means numbers that are over
-large. Version 21 Emacs uses larger numbers, but this code has not
-been touched, if only because people now look at buffers that are far,
-far larger than ever before.
-
-There are two cases: if the buffer is large and if it is not.
-
-What happens in a large buffer
-..............................
-
-In `beginning-of-buffer', the inner `if' expression tests whether the
-size of the buffer is greater than 10,000 characters. To do this, it
-uses the `>' function and the `buffer-size' function.
-
-The line looks like this:
-
- (if (> (buffer-size) 10000)
-
-When the buffer is large, the then-part of the `if' expression is
-evaluated. It reads like this (after formatting for easy reading):
-
- (*
- (prefix-numeric-value arg)
- (/ (buffer-size) 10))
-
-This expression is a multiplication, with two arguments to the
-function `*'.
-
-The first argument is `(prefix-numeric-value arg)'. When `"P"' is
-used as the argument for `interactive', the value passed to the
-function as its argument is passed a "raw prefix argument", and not a
-number. (It is a number in a list.) To perform the arithmetic, a
-conversion is necessary, and `prefix-numeric-value' does the job.
-
-The second argument is `(/ (buffer-size) 10)'. This expression
-divides the numeric value of the buffer by ten. This produces a
-number that tells how many characters make up one tenth of the buffer
-size. (In Lisp, `/' is used for division, just as `*' is used for
-multiplication.)
-
-In the multiplication expression as a whole, this amount is multiplied
-by the value of the prefix argument--the multiplication looks like
-this:
-
- (* NUMERIC-VALUE-OF-PREFIX-ARG
- NUMBER-OF-CHARACTERS-IN-ONE-TENTH-OF-THE-BUFFER)
-
-If, for example, the prefix argument is `7', the one-tenth value will
-be multiplied by 7 to give a position 70% of the way through the
-buffer.
-
-The result of all this is that if the buffer is large, the
-`goto-char' expression reads like this:
-
- (goto-char (* (prefix-numeric-value arg)
- (/ (buffer-size) 10)))
-
-This puts the cursor where we want it.
-
-What happens in a small buffer
-..............................
-
-If the buffer contains fewer than 10,000 characters, a slightly
-different computation is performed. You might think this is not
-necessary, since the first computation could do the job. However, in
-a small buffer, the first method may not put the cursor on exactly the
-desired line; the second method does a better job.
-
-The code looks like this:
-
- (/ (+ 10 (* (buffer-size) (prefix-numeric-value arg))) 10))
-
-This is code in which you figure out what happens by discovering how
-the functions are embedded in parentheses. It is easier to read if
-you reformat it with each expression indented more deeply than its
-enclosing expression:
-
- (/
- (+ 10
- (*
- (buffer-size)
- (prefix-numeric-value arg)))
- 10))
-
-Looking at parentheses, we see that the innermost operation is
-`(prefix-numeric-value arg)', which converts the raw argument to a
-number. This number is multiplied by the buffer size in the following
-expression:
-
- (* (buffer-size) (prefix-numeric-value arg)
-
-This multiplication creates a number that may be larger than the size
-of the buffer--seven times larger if the argument is 7, for example.
-Ten is then added to this number and finally the large number is
-divided by ten to provide a value that is one character larger than
-the percentage position in the buffer.
-
-The number that results from all this is passed to `goto-char' and
-the cursor is moved to that point.
-
-The Complete `beginning-of-buffer'
-----------------------------------
-
-Here is the complete text of the `beginning-of-buffer' function:
-
- (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.
- Don't use this in Lisp programs!
- \(goto-char (point-min)) is faster
- and does not set the mark."
- (interactive "P")
- (push-mark)
- (goto-char
- (if arg
- (if (> (buffer-size) 10000)
- ;; Avoid overflow for large buffer sizes!
- (* (prefix-numeric-value arg)
- (/ (buffer-size) 10))
- (/ (+ 10 (* (buffer-size)
- (prefix-numeric-value arg)))
- 10))
- (point-min)))
- (if arg (forward-line 1)))
-
-Except for two small points, the previous discussion shows how this
-function works. The first point deals with a detail in the
-documentation string, and the second point concerns the last line of
-the function.
-
-In the documentation string, there is reference to an expression:
-
- \(goto-char (point-min))
-
-A `\' is used before the first parenthesis of this expression. This
-`\' tells the Lisp interpreter that the expression should be printed
-as shown in the documentation rather than evaluated as a symbolic
-expression, which is what it looks like.
-
-Finally, the last line of the `beginning-of-buffer' command says to
-move point to the beginning of the next line if the command is
-invoked with an argument:
-
- (if arg (forward-line 1)))
-
-This puts the cursor at the beginning of the first line after the
-appropriate tenths position in the buffer. This is a flourish that
-means that the cursor is always located _at least_ the requested
-tenths of the way through the buffer, which is a nicety that is,
-perhaps, not necessary, but which, if it did not occur, would be sure
-to draw complaints.
-
-Review
-======
-
-Here is a brief summary of some of the topics covered in this chapter.
-
-`or'
- Evaluate each argument in sequence, and return the value of the
- first argument that is not `nil'; if none return a value that is
- not `nil', return `nil'. In brief, return the first true value
- of the arguments; return a true value if one _or_ any of the
- other are true.
-
-`and'
- Evaluate each argument in sequence, and if any are `nil', return
- `nil'; if none are `nil', return the value of the last argument.
- In brief, return a true value only if all the arguments are
- true; return a true value if one _and_ each of the others is
- true.
-
-`&optional'
- A keyword used to indicate that an argument to a function
- definition is optional; this means that the function can be
- evaluated without the argument, if desired.
-
-`prefix-numeric-value'
- Convert the `raw prefix argument' produced by `(interactive
- "P")' to a numeric value.
-
-`forward-line'
- Move point forward to the beginning of the next line, or if the
- argument is greater than one, forward that many lines. If it
- can't move as far forward as it is supposed to, `forward-line'
- goes forward as far as it can and then returns a count of the
- number of additional lines it was supposed to move but couldn't.
-
-`erase-buffer'
- Delete the entire contents of the current buffer.
-
-`bufferp'
- Return `t' if its argument is a buffer; otherwise return `nil'.
-
-`optional' Argument Exercise
-============================
-
-Write an interactive function with an optional argument that tests
-whether its argument, a number, is greater or less than the value of
-`fill-column', and tells you which, in a message. However, if you do
-not pass an argument to the function, use 56 as a default value.
-
-Narrowing and Widening
-**********************
-
-Narrowing is a feature of Emacs that makes it possible for you to
-focus on a specific part of a buffer, and work without accidentally
-changing other parts. Narrowing is normally disabled since it can
-confuse novices.
-
-The Advantages of Narrowing
-===========================
-
-With narrowing, the rest of a buffer is made invisible, as if it
-weren't there. This is an advantage if, for example, you want to
-replace a word in one part of a buffer but not in another: you narrow
-to the part you want and the replacement is carried out only in that
-section, not in the rest of the buffer. Searches will only work
-within a narrowed region, not outside of one, so if you are fixing a
-part of a document, you can keep yourself from accidentally finding
-parts you do not need to fix by narrowing just to the region you want.
-(The key binding for `narrow-to-region' is `C-x n n'.)
-
-However, narrowing does make the rest of the buffer invisible, which
-can scare people who inadvertently invoke narrowing and think they
-have deleted a part of their file. Moreover, the `undo' command
-(which is usually bound to `C-x u') does not turn off narrowing (nor
-should it), so people can become quite desperate if they do not know
-that they can return the rest of a buffer to visibility with the
-`widen' command. (The key binding for `widen' is `C-x n w'.)
-
-Narrowing is just as useful to the Lisp interpreter as to a human.
-Often, an Emacs Lisp function is designed to work on just part of a
-buffer; or conversely, an Emacs Lisp function needs to work on all of
-a buffer that has been narrowed. The `what-line' function, for
-example, removes the narrowing from a buffer, if it has any narrowing
-and when it has finished its job, restores the narrowing to what it
-was. On the other hand, the `count-lines' function, which is called
-by `what-line', uses narrowing to restrict itself to just that portion
-of the buffer in which it is interested and then restores the previous
-situation.
-
-The `save-restriction' Special Form
-===================================
-
-In Emacs Lisp, you can use the `save-restriction' special form to
-keep track of whatever narrowing is in effect, if any. When the Lisp
-interpreter meets with `save-restriction', it executes the code in
-the body of the `save-restriction' expression, and then undoes any
-changes to narrowing that the code caused. If, for example, the
-buffer is narrowed and the code that follows `save-restriction' gets
-rid of the narrowing, `save-restriction' returns the buffer to its
-narrowed region afterwards. In the `what-line' command, any
-narrowing the buffer may have is undone by the `widen' command that
-immediately follows the `save-restriction' command. Any original
-narrowing is restored just before the completion of the function.
-
-The template for a `save-restriction' expression is simple:
-
- (save-restriction
- BODY... )
-
-The body of the `save-restriction' is one or more expressions that
-will be evaluated in sequence by the Lisp interpreter.
-
-Finally, a point to note: when you use both `save-excursion' and
-`save-restriction', one right after the other, you should use
-`save-excursion' outermost. If you write them in reverse order, you
-may fail to record narrowing in the buffer to which Emacs switches
-after calling `save-excursion'. Thus, when written together,
-`save-excursion' and `save-restriction' should be written like this:
-
- (save-excursion
- (save-restriction
- BODY...))
-
-In other circumstances, when not written together, the
-`save-excursion' and `save-restriction' special forms must be written
-in the order appropriate to the function.
-
-For example,
-
- (save-restriction
- (widen)
- (save-excursion
- BODY...))
-
-`what-line'
-===========
-
-The `what-line' command tells you the number of the line in which the
-cursor is located. The function illustrates the use of the
-`save-restriction' and `save-excursion' commands. Here is the text
-of the function in full:
-
- (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)))))))
-
-The function has a documentation line and is interactive, as you would
-expect. The next two lines use the functions `save-restriction' and
-`widen'.
-
-The `save-restriction' special form notes whatever narrowing is in
-effect, if any, in the current buffer and restores that narrowing
-after the code in the body of the `save-restriction' has been
-evaluated.
-
-The `save-restriction' special form is followed by `widen'. This
-function undoes any narrowing the current buffer may have had when
-`what-line' was called. (The narrowing that was there is the
-narrowing that `save-restriction' remembers.) This widening makes it
-possible for the line counting commands to count from the beginning
-of the buffer. Otherwise, they would have been limited to counting
-within the accessible region. Any original narrowing is restored
-just before the completion of the function by the `save-restriction'
-special form.
-
-The call to `widen' is followed by `save-excursion', which saves the
-location of the cursor (i.e., of point) and of the mark, and restores
-them after the code in the body of the `save-excursion' uses the
-`beginning-of-line' function to move point.
-
-(Note that the `(widen)' expression comes between the
-`save-restriction' and `save-excursion' special forms. When you
-write the two `save- ...' expressions in sequence, write
-`save-excursion' outermost.)
-
-The last two lines of the `what-line' function are functions to count
-the number of lines in the buffer and then print the number in the
-echo area.
-
- (message "Line %d"
- (1+ (count-lines 1 (point)))))))
-
-The `message' function prints a one-line message at the bottom of the
-Emacs screen. The first argument is inside of quotation marks and is
-printed as a string of characters. However, it may contain `%d',
-`%s', or `%c' to print arguments that follow the string. `%d' prints
-the argument as a decimal, so the message will say something such as
-`Line 243'.
-
-The number that is printed in place of the `%d' is computed by the
-last line of the function:
-
- (1+ (count-lines 1 (point)))
-
-What this does is count the lines from the first position of the
-buffer, indicated by the `1', up to `(point)', and then add one to
-that number. (The `1+' function adds one to its argument.) We add
-one to it because line 2 has only one line before it, and
-`count-lines' counts only the lines _before_ the current line.
-
-After `count-lines' has done its job, and the message has been
-printed in the echo area, the `save-excursion' restores point and
-mark to their original positions; and `save-restriction' restores the
-original narrowing, if any.
-
-Exercise with Narrowing
-=======================
-
-Write a function that will display the first 60 characters of the
-current buffer, even if you have narrowed the buffer to its latter
-half so that the first line is inaccessible. Restore point, mark,
-and narrowing. For this exercise, you need to use
-`save-restriction', `widen', `goto-char', `point-min',
-`buffer-substring', `message', and other functions, a whole potpourri.
-
-`car', `cdr', `cons': Fundamental Functions
-*******************************************
-
-In Lisp, `car', `cdr', and `cons' are fundamental functions. The
-`cons' function is used to construct lists, and the `car' and `cdr'
-functions are used to take them apart.
-
-In the walk through of the `copy-region-as-kill' function, we will
-see `cons' as well as two variants on `cdr', namely, `setcdr' and
-`nthcdr'. (*Note copy-region-as-kill::.)
-
-Strange Names
-=============
-
-The name of the `cons' function is not unreasonable: it is an
-abbreviation of the word `construct'. The origins of the names for
-`car' and `cdr', on the other hand, are esoteric: `car' is an acronym
-from the phrase `Contents of the Address part of the Register'; and
-`cdr' (pronounced `could-er') is an acronym from the phrase `Contents
-of the Decrement part of the Register'. These phrases refer to
-specific pieces of hardware on the very early computer on which the
-original Lisp was developed. Besides being obsolete, the phrases
-have been completely irrelevant for more than 25 years to anyone
-thinking about Lisp. Nonetheless, although a few brave scholars have
-begun to use more reasonable names for these functions, the old terms
-are still in use. In particular, since the terms are used in the
-Emacs Lisp source code, we will use them in this introduction.
-
-`car' and `cdr'
-===============
-
-The CAR of a list is, quite simply, the first item in the list. Thus
-the CAR of the list `(rose violet daisy buttercup)' is `rose'.
-
-If you are reading this in Info in GNU Emacs, you can see this by
-evaluating the following:
-
- (car '(rose violet daisy buttercup))
-
-After evaluating the expression, `rose' will appear in the echo area.
-
-Clearly, a more reasonable name for the `car' function would be
-`first' and this is often suggested.
-
-`car' does not remove the first item from the list; it only reports
-what it is. After `car' has been applied to a list, the list is
-still the same as it was. In the jargon, `car' is `non-destructive'.
-This feature turns out to be important.
-
-The CDR of a list is the rest of the list, that is, the `cdr'
-function returns the part of the list that follows the first item.
-Thus, while the CAR of the list `'(rose violet daisy buttercup)' is
-`rose', the rest of the list, the value returned by the `cdr'
-function, is `(violet daisy buttercup)'.
-
-You can see this by evaluating the following in the usual way:
-
- (cdr '(rose violet daisy buttercup))
-
-When you evaluate this, `(violet daisy buttercup)' will appear in the
-echo area.
-
-Like `car', `cdr' does not remove any elements from the list--it just
-returns a report of what the second and subsequent elements are.
-
-Incidentally, in the example, the list of flowers is quoted. If it
-were not, the Lisp interpreter would try to evaluate the list by
-calling `rose' as a function. In this example, we do not want to do
-that.
-
-Clearly, a more reasonable name for `cdr' would be `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.)
-
-When `car' and `cdr' are applied to a list made up of symbols, such
-as the list `(pine fir oak maple)', the element of the list returned
-by the function `car' is the symbol `pine' without any parentheses
-around it. `pine' is the first element in the list. However, the
-CDR of the list is a list itself, `(fir oak maple)', as you can see
-by evaluating the following expressions in the usual way:
-
- (car '(pine fir oak maple))
-
- (cdr '(pine fir oak maple))
-
-On the other hand, in a list of lists, the first element is itself a
-list. `car' returns this first element as a list. For example, the
-following list contains three sub-lists, a list of carnivores, a list
-of herbivores and a list of sea mammals:
-
- (car '((lion tiger cheetah)
- (gazelle antelope zebra)
- (whale dolphin seal)))
-
-In this example, the first element or CAR of the list is the list of
-carnivores, `(lion tiger cheetah)', and the rest of the list is
-`((gazelle antelope zebra) (whale dolphin seal))'.
-
- (cdr '((lion tiger cheetah)
- (gazelle antelope zebra)
- (whale dolphin seal)))
-
-It is worth saying again that `car' and `cdr' are
-non-destructive--that is, they do not modify or change lists to which
-they are applied. This is very important for how they are used.
-
-Also, in the first chapter, in the discussion about atoms, I said that
-in Lisp, "certain kinds of atom, such as an array, can be separated
-into parts; but the mechanism for doing this is different from the
-mechanism for splitting a list. As far as Lisp is concerned, the
-atoms of a list are unsplittable." (*Note Lisp Atoms::.) The `car'
-and `cdr' functions are used for splitting lists and are considered
-fundamental to Lisp. Since they cannot split or gain access to the
-parts of an array, an array is considered an atom. Conversely, the
-other fundamental function, `cons', can put together or construct a
-list, but not an array. (Arrays are handled by array-specific
-functions. *Note Arrays: (elisp)Arrays.)
-
-`cons'
-======
-
-The `cons' function constructs lists; it is the inverse of `car' and
-`cdr'. For example, `cons' can be used to make a four element list
-from the three element list, `(fir oak maple)':
-
- (cons 'pine '(fir oak maple))
-
-After evaluating this list, you will see
-
- (pine fir oak maple)
-
-appear in the echo area. `cons' causes the creation of a new list in
-which the element is followed by the elements of the original list.
-
-We often say that ``cons' puts a new element at the beginning of a
-list; it attaches or pushes elements onto the list', but this
-phrasing can be misleading, since `cons' does not change an existing
-list, but creates a new one.
-
-Like `car' and `cdr', `cons' is non-destructive.
-
-Build a list
-------------
-
-`cons' must have a list to attach to.(1) You cannot start from
-absolutely nothing. If you are building a list, you need to provide
-at least an empty list at the beginning. Here is a series of `cons'
-expressions that build up a list of flowers. If you are reading this
-in Info in GNU Emacs, you can evaluate each of the expressions in the
-usual way; the value is printed in this text after `=>', which you
-may read as `evaluates to'.
-
- (cons 'buttercup ())
- => (buttercup)
-
- (cons 'daisy '(buttercup))
- => (daisy buttercup)
-
- (cons 'violet '(daisy buttercup))
- => (violet daisy buttercup)
-
- (cons 'rose '(violet daisy buttercup))
- => (rose violet daisy buttercup)
-
-In the first example, the empty list is shown as `()' and a list made
-up of `buttercup' followed by the empty list is constructed. As you
-can see, the empty list is not shown in the list that was
-constructed. All that you see is `(buttercup)'. The empty list is
-not counted as an element of a list because there is nothing in an
-empty list. Generally speaking, an empty list is invisible.
-
-The second example, `(cons 'daisy '(buttercup))' constructs a new,
-two element list by putting `daisy' in front of `buttercup'; and the
-third example constructs a three element list by putting `violet' in
-front of `daisy' and `buttercup'.
-
----------- Footnotes ----------
-
-(1) Actually, you can `cons' an element to an atom to produce a
-dotted pair. Dotted pairs are not discussed here; see *Note Dotted
-Pair Notation: (elisp)Dotted Pair Notation.
-
-Find the Length of a List: `length'
------------------------------------
-
-You can find out how many elements there are in a list by using the
-Lisp function `length', as in the following examples:
-
- (length '(buttercup))
- => 1
-
- (length '(daisy buttercup))
- => 2
-
- (length (cons 'violet '(daisy buttercup)))
- => 3
-
-In the third example, the `cons' function is used to construct a
-three element list which is then passed to the `length' function as
-its argument.
-
-We can also use `length' to count the number of elements in an empty
-list:
-
- (length ())
- => 0
-
-As you would expect, the number of elements in an empty list is zero.
-
-An interesting experiment is to find out what happens if you try to
-find the length of no list at all; that is, if you try to call
-`length' without giving it an argument, not even an empty list:
-
- (length )
-
-What you see, if you evaluate this, is the error message
-
- Wrong number of arguments: #<subr length>, 0
-
-This means that the function receives the wrong number of arguments,
-zero, when it expects some other number of arguments. In this case,
-one argument is expected, the argument being a list whose length the
-function is measuring. (Note that _one_ list is _one_ argument, even
-if the list has many elements inside it.)
-
-The part of the error message that says `#<subr length>' is the name
-of the function. This is written with a special notation, `#<subr',
-that indicates that the function `length' is one of the primitive
-functions written in C rather than in Emacs Lisp. (`subr' is an
-abbreviation for `subroutine'.) *Note What Is a Function?:
-(elisp)What Is a Function, for more about subroutines.
-
-`nthcdr'
-========
-
-The `nthcdr' function is associated with the `cdr' function. What it
-does is take the CDR of a list repeatedly.
-
-If you take the CDR of the list `(pine fir oak maple)', you will be
-returned the list `(fir oak maple)'. If you repeat this on what was
-returned, you will be returned the list `(oak maple)'. (Of course,
-repeated CDRing on the original list will just give you the original
-CDR since the function does not change the list. You need to
-evaluate the CDR of the CDR and so on.) If you continue this,
-eventually you will be returned an empty list, which in this case,
-instead of being shown as `()' is shown as `nil'.
-
-For review, here is a series of repeated CDRs, the text following the
-`=>' shows what is returned.
-
- (cdr '(pine fir oak maple))
- =>(fir oak maple)
-
- (cdr '(fir oak maple))
- => (oak maple)
-
- (cdr '(oak maple))
- =>(maple)
-
- (cdr '(maple))
- => nil
-
- (cdr 'nil)
- => nil
-
- (cdr ())
- => nil
-
-You can also do several CDRs without printing the values in between,
-like this:
-
- (cdr (cdr '(pine fir oak maple)))
- => (oak maple)
-
-In this example, the Lisp interpreter evaluates the innermost list
-first. The innermost list is quoted, so it just passes the list as
-it is to the innermost `cdr'. This `cdr' passes a list made up of the
-second and subsequent elements of the list to the outermost `cdr',
-which produces a list composed of the third and subsequent elements of
-the original list. In this example, the `cdr' function is repeated
-and returns a list that consists of the original list without its
-first two elements.
-
-The `nthcdr' function does the same as repeating the call to `cdr'.
-In the following example, the argument 2 is passed to the function
-`nthcdr', along with the list, and the value returned is the list
-without its first two items, which is exactly the same as repeating
-`cdr' twice on the list:
-
- (nthcdr 2 '(pine fir oak maple))
- => (oak maple)
-
-Using the original four element list, we can see what happens when
-various numeric arguments are passed to `nthcdr', including 0, 1, and
-5:
-
- ;; Leave the list as it was.
- (nthcdr 0 '(pine fir oak maple))
- => (pine fir oak maple)
-
- ;; Return a copy without the first element.
- (nthcdr 1 '(pine fir oak maple))
- => (fir oak maple)
-
- ;; Return a copy of the list without three elements.
- (nthcdr 3 '(pine fir oak maple))
- => (maple)
-
- ;; Return a copy lacking all four elements.
- (nthcdr 4 '(pine fir oak maple))
- => nil
-
- ;; Return a copy lacking all elements.
- (nthcdr 5 '(pine fir oak maple))
- => nil
-
-`nth'
-=====
-
-The `nthcdr' function takes the CDR of a list repeatedly. The `nth'
-function takes the CAR of the result returned by `nthcdr'. It
-returns the Nth element of the list.
-
-Thus, if it were not defined in C for speed, the definition of `nth'
-would be:
-
- (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)))
-
-(Originally, `nth' was defined in Emacs Lisp in `subr.el', but its
-definition was redone in C in the 1980s.)
-
-The `nth' function returns a single element of a list. This can be
-very convenient.
-
-Note that the elements are numbered from zero, not one. That is to
-say, the first element of a list, its CAR is the zeroth element.
-This is called `zero-based' counting and often bothers people who are
-accustomed to the first element in a list being number one, which is
-`one-based'.
-
-For example:
-
- (nth 0 '("one" "two" "three"))
- => "one"
-
- (nth 1 '("one" "two" "three"))
- => "two"
-
-It is worth mentioning that `nth', like `nthcdr' and `cdr', does not
-change the original list--the function is non-destructive. This is
-in sharp contrast to the `setcar' and `setcdr' functions.
-
-`setcar'
-========
-
-As you might guess from their names, the `setcar' and `setcdr'
-functions set the CAR or the CDR of a list to a new value. They
-actually change the original list, unlike `car' and `cdr' which leave
-the original list as it was. One way to find out how this works is
-to experiment. We will start with the `setcar' function.
-
-First, we can make a list and then set the value of a variable to the
-list, using the `setq' function. Here is a list of animals:
-
- (setq animals '(antelope giraffe lion tiger))
-
-If you are reading this in Info inside of GNU Emacs, you can evaluate
-this expression in the usual fashion, by positioning the cursor after
-the expression and typing `C-x C-e'. (I'm doing this right here as I
-write this. This is one of the advantages of having the interpreter
-built into the computing environment.)
-
-When we evaluate the variable `animals', we see that it is bound to
-the list `(antelope giraffe lion tiger)':
-
- animals
- => (antelope giraffe lion tiger)
-
-Put another way, the variable `animals' points to the list `(antelope
-giraffe lion tiger)'.
-
-Next, evaluate the function `setcar' while passing it two arguments,
-the variable `animals' and the quoted symbol `hippopotamus'; this is
-done by writing the three element list `(setcar animals
-'hippopotamus)' and then evaluating it in the usual fashion:
-
- (setcar animals 'hippopotamus)
-
-After evaluating this expression, evaluate the variable `animals'
-again. You will see that the list of animals has changed:
-
- animals
- => (hippopotamus giraffe lion tiger)
-
-The first element on the list, `antelope' is replaced by
-`hippopotamus'.
-
-So we can see that `setcar' did not add a new element to the list as
-`cons' would have; it replaced `giraffe' with `hippopotamus'; it
-_changed_ the list.
-
-`setcdr'
-========
-
-The `setcdr' function is similar to the `setcar' function, except
-that the function replaces the second and subsequent elements of a
-list rather than the first element.
-
-To see how this works, set the value of the variable to a list of
-domesticated animals by evaluating the following expression:
-
- (setq domesticated-animals '(horse cow sheep goat))
-
-If you now evaluate the list, you will be returned the list `(horse
-cow sheep goat)':
-
- domesticated-animals
- => (horse cow sheep goat)
-
-Next, evaluate `setcdr' with two arguments, the name of the variable
-which has a list as its value, and the list to which the CDR of the
-first list will be set;
-
- (setcdr domesticated-animals '(cat dog))
-
-If you evaluate this expression, the list `(cat dog)' will appear in
-the echo area. This is the value returned by the function. The
-result we are interested in is the "side effect", which we can see by
-evaluating the variable `domesticated-animals':
-
- domesticated-animals
- => (horse cat dog)
-
-Indeed, the list is changed from `(horse cow sheep goat)' to `(horse
-cat dog)'. The CDR of the list is changed from `(cow sheep goat)' to
-`(cat dog)'.
-
-Exercise
-========
-
-Construct a list of four birds by evaluating several expressions with
-`cons'. Find out what happens when you `cons' a list onto itself.
-Replace the first element of the list of four birds with a fish.
-Replace the rest of that list with a list of other fish.
-
-Cutting and Storing Text
-************************
-
-Whenever you cut or clip text out of a buffer with a `kill' command in
-GNU Emacs, it is stored in a list and you can bring it back with a
-`yank' command.
-
-(The use of the word `kill' in Emacs for processes which specifically
-_do not_ destroy the values of the entities is an unfortunate
-historical accident. A much more appropriate word would be `clip'
-since that is what the kill commands do; they clip text out of a
-buffer and put it into storage from which it can be brought back. I
-have often been tempted to replace globally all occurrences of `kill'
-in the Emacs sources with `clip' and all occurrences of `killed' with
-`clipped'.)
-
-Storing Text in a List
-======================
-
-When text is cut out of a buffer, it is stored on a list. Successive
-pieces of text are stored on the list successively, so the list might
-look like this:
-
- ("a piece of text" "previous piece")
-
-The function `cons' can be used to to create a new list from a piece
-of text (an `atom', to use the jargon) and an existing list, like
-this:
-
- (cons "another piece"
- '("a piece of text" "previous piece"))
-
-If you evaluate this expression, a list of three elements will appear
-in the echo area:
-
- ("another piece" "a piece of text" "previous piece")
-
-With the `car' and `nthcdr' functions, you can retrieve whichever
-piece of text you want. For example, in the following code, `nthcdr
-1 ...' returns the list with the first item removed; and the `car'
-returns the first element of that remainder--the second element of
-the original list:
-
- (car (nthcdr 1 '("another piece"
- "a piece of text"
- "previous piece")))
- => "a piece of text"
-
-The actual functions in Emacs are more complex than this, of course.
-The code for cutting and retrieving text has to be written so that
-Emacs can figure out which element in the list you want--the first,
-second, third, or whatever. In addition, when you get to the end of
-the list, Emacs should give you the first element of the list, rather
-than nothing at all.
-
-The list that holds the pieces of text is called the "kill ring".
-This chapter leads up to a description of the kill ring and how it is
-used by first tracing how the `zap-to-char' function works. This
-function uses (or `calls') a function that invokes a function that
-manipulates the kill ring. Thus, before reaching the mountains, we
-climb the foothills.
-
-A subsequent chapter describes how text that is cut from the buffer is
-retrieved. *Note Yanking Text Back: Yanking.
-
-`zap-to-char'
-=============
-
-The `zap-to-char' function barely changed between GNU Emacs version
-19 and GNU Emacs version 21. However, `zap-to-char' calls another
-function, `kill-region', which enjoyed a major rewrite on the way to
-version 21.
-
-The `kill-region' function in Emacs 19 is complex, but does not use
-code that is important at this time. We will skip it.
-
-The `kill-region' function in Emacs 21 is easier to read than the
-same function in Emacs 19 and introduces a very important concept,
-that of error handling. We will walk through the function.
-
-But first, let us look at the interactive `zap-to-char' function.
-
-The Complete `zap-to-char' Implementation
------------------------------------------
-
-The GNU Emacs version 19 and version 21 implementations of the
-`zap-to-char' function are nearly identical in form, and they work
-alike. The function removes the text in the region between the
-location of the cursor (i.e., of point) up to and including the next
-occurrence of a specified character. The text that `zap-to-char'
-removes is put in the kill ring; and it can be retrieved from the kill
-ring by typing `C-y' (`yank'). If the command is given an argument,
-it removes text through that number of occurrences. Thus, if the
-cursor were at the beginning of this sentence and the character were
-`s', `Thus' would be removed. If the argument were two, `Thus, if
-the curs' would be removed, up to and including the `s' in `cursor'.
-
-If the specified character is not found, `zap-to-char' will say
-"Search failed", tell you the character you typed, and not remove any
-text.
-
-In order to determine how much text to remove, `zap-to-char' uses a
-search function. Searches are used extensively in code that
-manipulates text, and we will focus attention on them as well as on
-the deletion command.
-
-Here is the complete text of the version 19 implementation of the
-function:
-
- (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))))
-
-The `interactive' Expression
-----------------------------
-
-The interactive expression in the `zap-to-char' command looks like
-this:
-
- (interactive "*p\ncZap to char: ")
-
-The part within quotation marks, `"*p\ncZap to char: "', specifies
-three different things. First, and most simply, the asterisk, `*',
-causes an error to be signalled if the buffer is read-only. This
-means that if you try `zap-to-char' in a read-only buffer you will
-not be able to remove text, and you will receive a message that says
-"Buffer is read-only"; your terminal may beep at you as well.
-
-The version 21 implementation does not have the asterisk, `*'. The
-function works the same as in version 19: in both cases, it cannot
-remove text from a read-only buffer but the function does copy the
-text that would have been removed to the kill ring. Also, in both
-cases, you see an error message.
-
-However, the version 19 implementation copies text from a read-only
-buffer only because of a mistake in the implementation of
-`interactive'. According to the documentation for `interactive', the
-asterisk, `*', should prevent the `zap-to-char' function from doing
-anything at all when the buffer is read only. The function should
-not copy the text to the kill ring. It is a bug that it does.
-
-In version 21, `interactive' is implemented correctly. So the
-asterisk, `*', had to be removed from the interactive specification.
-If you insert an `*' and evaluate the function definition, then the
-next time you run the `zap-to-char' function on a read-only buffer,
-you will not copy any text.
-
-That change aside, and a change to the documentation, the two versions
-of the `zap-to-char' function are identical.
-
-Let us continue with the interactive specification.
-
-The second part of `"*p\ncZap to char: "' is the `p'. This part is
-separated from the next part by a newline, `\n'. The `p' means that
-the first argument to the function will be passed the value of a
-`processed prefix'. The prefix argument is passed by typing `C-u'
-and a number, or `M-' and a number. If the function is called
-interactively without a prefix, 1 is passed to this argument.
-
-The third part of `"*p\ncZap to char: "' is `cZap to char: '. In
-this part, the lower case `c' indicates that `interactive' expects a
-prompt and that the argument will be a character. The prompt follows
-the `c' and is the string `Zap to char: ' (with a space after the
-colon to make it look good).
-
-What all this does is prepare the arguments to `zap-to-char' so they
-are of the right type, and give the user a prompt.
-
-The Body of `zap-to-char'
--------------------------
-
-The body of the `zap-to-char' function contains the code that kills
-(that is, removes) the text in the region from the current position
-of the cursor up to and including the specified character. The first
-part of the code looks like this:
-
- (kill-region (point) ...
-
-`(point)' is the current position of the cursor.
-
-The next part of the code is an expression using `progn'. The body
-of the `progn' consists of calls to `search-forward' and `point'.
-
-It is easier to understand how `progn' works after learning about
-`search-forward', so we will look at `search-forward' and then at
-`progn'.
-
-The `search-forward' Function
------------------------------
-
-The `search-forward' function is used to locate the
-zapped-for-character in `zap-to-char'. If the search is successful,
-`search-forward' leaves point immediately after the last character in
-the target string. (In `zap-to-char', the target string is just one
-character long.) If the search is backwards, `search-forward' leaves
-point just before the first character in the target. Also,
-`search-forward' returns `t' for true. (Moving point is therefore a
-`side effect'.)
-
-In `zap-to-char', the `search-forward' function looks like this:
-
- (search-forward (char-to-string char) nil nil arg)
-
-The `search-forward' function takes four arguments:
-
- 1. The first argument is the target, what is searched for. This
- must be a string, such as `"z"'.
-
- As it happens, the argument passed to `zap-to-char' is a single
- character. Because of the way computers are built, the Lisp
- interpreter may treat a single character as being different from
- a string of characters. Inside the computer, a single character
- has a different electronic format than a string of one
- character. (A single character can often be recorded in the
- computer using exactly one byte; but a string may be longer, and
- the computer needs to be ready for this.) Since the
- `search-forward' function searches for a string, the character
- that the `zap-to-char' function receives as its argument must be
- converted inside the computer from one format to the other;
- otherwise the `search-forward' function will fail. The
- `char-to-string' function is used to make this conversion.
-
- 2. The second argument bounds the search; it is specified as a
- position in the buffer. In this case, the search can go to the
- end of the buffer, so no bound is set and the second argument is
- `nil'.
-
- 3. The third argument tells the function what it should do if the
- search fails--it can signal an error (and print a message) or it
- can return `nil'. A `nil' as the third argument causes the
- function to signal an error when the search fails.
-
- 4. The fourth argument to `search-forward' is the repeat count--how
- many occurrences of the string to look for. This argument is
- optional and if the function is called without a repeat count,
- this argument is passed the value 1. If this argument is
- negative, the search goes backwards.
-
-In template form, a `search-forward' expression looks like this:
-
- (search-forward "TARGET-STRING"
- LIMIT-OF-SEARCH
- WHAT-TO-DO-IF-SEARCH-FAILS
- REPEAT-COUNT)
-
-We will look at `progn' next.
-
-The `progn' Special Form
-------------------------
-
-`progn' is a special form that causes each of its arguments to be
-evaluated in sequence and then returns the value of the last one. The
-preceding expressions are evaluated only for the side effects they
-perform. The values produced by them are discarded.
-
-The template for a `progn' expression is very simple:
-
- (progn
- BODY...)
-
-In `zap-to-char', the `progn' expression has to do two things: put
-point in exactly the right position; and return the location of point
-so that `kill-region' will know how far to kill to.
-
-The first argument to the `progn' is `search-forward'. When
-`search-forward' finds the string, the function leaves point
-immediately after the last character in the target string. (In this
-case the target string is just one character long.) If the search is
-backwards, `search-forward' leaves point just before the first
-character in the target. The movement of point is a side effect.
-
-The second and last argument to `progn' is the expression `(point)'.
-This expression returns the value of point, which in this case will
-be the location to which it has been moved by `search-forward'. This
-value is returned by the `progn' expression and is passed to
-`kill-region' as `kill-region''s second argument.
-
-Summing up `zap-to-char'
-------------------------
-
-Now that we have seen how `search-forward' and `progn' work, we can
-see how the `zap-to-char' function works as a whole.
-
-The first argument to `kill-region' is the position of the cursor
-when the `zap-to-char' command is given--the value of point at that
-time. Within the `progn', the search function then moves point to
-just after the zapped-to-character and `point' returns the value of
-this location. The `kill-region' function puts together these two
-values of point, the first one as the beginning of the region and the
-second one as the end of the region, and removes the region.
-
-The `progn' special form is necessary because the `kill-region'
-command takes two arguments; and it would fail if `search-forward'
-and `point' expressions were written in sequence as two additional
-arguments. The `progn' expression is a single argument to
-`kill-region' and returns the one value that `kill-region' needs for
-its second argument.
-
-`kill-region'
-=============
-
-The `zap-to-char' function uses the `kill-region' function. This
-function clips text from a region and copies that text to the kill
-ring, from which it may be retrieved.
-
-The Emacs 21 version of that function uses `condition-case' and
-`copy-region-as-kill', both of which we will explain.
-`condition-case' is an important special form.
-
-In essence, the `kill-region' function calls `condition-case', which
-takes three arguments. In this function, the first argument does
-nothing. The second argument contains the code that does the work
-when all goes well. The third argument contains the code that is
-called in the event of an error.
-
-The Complete `kill-region' Definition
--------------------------------------
-
-We will go through the `condition-case' code in a moment. First, let
-us look at the complete definition of `kill-region', with comments
-added:
-
- (defun kill-region (beg end)
- "Kill between point and mark.
- The text is deleted but saved in the kill ring."
- (interactive "r")
-
- ;; 1. `condition-case' takes three arguments.
- ;; If the first argument is nil, as it is here,
- ;; information about the error signal is not
- ;; stored for use by another function.
- (condition-case nil
-
- ;; 2. The second argument to `condition-case'
- ;; tells the Lisp interpreter what to do when all goes well.
-
- ;; The `delete-and-extract-region' function usually does the
- ;; work. If the beginning and ending of the region are both
- ;; the same, then the variable `string' will be empty, or nil
- (let ((string (delete-and-extract-region beg end)))
-
- ;; `when' is an `if' clause that cannot take an `else-part'.
- ;; Emacs normally sets the value of `last-command' to the
- ;; previous command.
- ;; `kill-append' concatenates the new string and the old.
- ;; `kill-new' inserts text into a new item in the kill ring.
- (when string
- (if (eq last-command 'kill-region)
- ;; if true, prepend string
- (kill-append string (< end beg))
- (kill-new string)))
- (setq this-command 'kill-region))
-
- ;; 3. The third argument to `condition-case' tells the interpreter
- ;; what to do with an error.
- ;; The third argument has a conditions part and a body part.
- ;; If the conditions are met (in this case,
- ;; if text or buffer is read-only)
- ;; then the body is executed.
- ((buffer-read-only text-read-only) ;; this is the if-part
- ;; then...
- (copy-region-as-kill beg end)
- (if kill-read-only-ok ;; usually this variable is nil
- (message "Read only text copied to kill ring")
- ;; or else, signal an error if the buffer is read-only;
- (barf-if-buffer-read-only)
- ;; and, in any case, signal that the text is read-only.
- (signal 'text-read-only (list (current-buffer)))))))
-
-`condition-case'
-----------------
-
-As we have seen earlier (*note Generate an Error Message: Making
-Errors.), when the Emacs Lisp interpreter has trouble evaluating an
-expression, it provides you with help; in the jargon, this is called
-"signaling an error". Usually, the computer stops the program and
-shows you a message.
-
-However, some programs undertake complicated actions. They should not
-simply stop on an error. In the `kill-region' function, the most
-likely error is that you will try to kill text that is read-only and
-cannot be removed. So the `kill-region' function contains code to
-handle this circumstance. This code, which makes up the body of the
-`kill-region' function, is inside of a `condition-case' special form.
-
-The template for `condition-case' looks like this:
-
- (condition-case
- VAR
- BODYFORM
- ERROR-HANDLER...)
-
-The second argument, BODYFORM, is straightforward. The
-`condition-case' special form causes the Lisp interpreter to evaluate
-the code in BODYFORM. If no error occurs, the special form returns
-the code's value and produces the side-effects, if any.
-
-In short, the BODYFORM part of a `condition-case' expression
-determines what should happen when everything works correctly.
-
-However, if an error occurs, among its other actions, the function
-generating the error signal will define one or more error condition
-names.
-
-An error handler is the third argument to `condition case'. An error
-handler has two parts, a CONDITION-NAME and a BODY. If the
-CONDITION-NAME part of an error handler matches a condition name
-generated by an error, then the BODY part of the error handler is run.
-
-As you will expect, the CONDITION-NAME part of an error handler may
-be either a single condition name or a list of condition names.
-
-Also, a complete `condition-case' expression may contain more than
-one error handler. When an error occurs, the first applicable
-handler is run.
-
-Lastly, the first argument to the `condition-case' expression, the
-VAR argument, is sometimes bound to a variable that contains
-information about the error. However, if that argument is nil, as is
-the case in `kill-region', that information is discarded.
-
-In brief, in the `kill-region' function, the code `condition-case'
-works like this:
-
- IF NO ERRORS, RUN ONLY THIS CODE
- BUT, IF ERRORS, RUN THIS OTHER CODE.
-
-`delete-and-extract-region'
----------------------------
-
-A `condition-case' expression has two parts, a part that is evaluated
-in the expectation that all will go well, but which may generate an
-error; and a part that is evaluated when there is an error.
-
-First, let us look at the code in `kill-region' that is run in the
-expectation that all goes well. This is the core of the function.
-The code looks like this:
-
- (let ((string (delete-and-extract-region beg end)))
- (when string
- (if (eq last-command 'kill-region)
- (kill-append string (< end beg))
- (kill-new string)))
- (setq this-command 'kill-region))
-
-It looks complicated because we have the new functions
-`delete-and-extract-region', `kill-append', and `kill-new' as well as
-the new variables, `last-command' and `this-command'.
-
-The `delete-and-extract-region' function is straightforward. It is a
-built-in function that deletes the text in a region (a side effect)
-and also returns that text. This is the function that actually
-removes the text. (And if it cannot do that, it signals the error.)
-
-In this `let' expression, the text that `delete-and-extract-region'
-returns is placed in the local variable called `string'. This is the
-text that is removed from the buffer. (To be more precise, the
-variable is set to point to the address of the extracted text; to say
-it is `placed in' the variable is simply a shorthand.)
-
-If the variable `string' does point to text, that text is added to
-the kill ring. The variable will have a `nil' value if no text was
-removed.
-
-The code uses `when' to determine whether the variable `string'
-points to text. A `when' statement is simply a programmers'
-convenience. A `when' statement is an `if' statement without the
-possibility of an else clause. In your mind, you can replace `when'
-with `if' and understand what goes on. That is what the Lisp
-interpreter does.
-
-Technically speaking, `when' is a Lisp macro. A Lisp "macro" enables
-you to define new control constructs and other language features. It
-tells the interpreter how to compute another Lisp expression which
-will in turn compute the value. In this case, the `other expression'
-is an `if' expression. For more about Lisp macros, see *Note Macros:
-(elisp)Macros. The C programming language also provides macros.
-These are different, but also useful. We will briefly look at C
-macros in *Note Digression into C::.
-
-If the string has content, then another conditional expression is
-executed. This is an `if' with both a then-part and an else-part.
-
- (if (eq last-command 'kill-region)
- (kill-append string (< end beg))
- (kill-new string)))
-
-The then-part is evaluated if the previous command was another call to
-`kill-region'; if not, the else-part is evaluated.
-
-`last-command' is a variable that comes with Emacs that we have not
-seen before. Normally, whenever a function is executed, Emacs sets
-the value of `last-command' to the previous command.
-
-In this segment of the definition, the `if' expression checks whether
-the previous command was `kill-region'. If it was,
-
- (kill-append string (< end beg))
-
-concatenates a copy of the newly clipped text to the just previously
-clipped text in the kill ring. (If the `(< end beg))' expression is
-true, `kill-append' prepends the string to the just previously
-clipped text. For a detailed discussion, see *Note The `kill-append'
-function: 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 `(< end beg))' expression makes sure the order is
-correct.)
-
-On the other hand, if the previous command is not `kill-region', then
-the `kill-new' function is called, which adds the text to the kill
-ring as the latest item, and sets the `kill-ring-yank-pointer'
-variable to point to it.
-
-Digression into C
-=================
-
-The `zap-to-char' command uses the `delete-and-extract-region'
-function, which in turn uses two other functions,
-`copy-region-as-kill' and `del_range_1'. The `copy-region-as-kill'
-function will be described in a following section; it puts a copy of
-the region in the kill ring so it can be yanked back. (*Note
-`copy-region-as-kill': copy-region-as-kill.)
-
-The `delete-and-extract-region' function removes the contents of a
-region and you cannot get them back.
-
-Unlike the other code discussed here, `delete-and-extract-region' is
-not written in Emacs Lisp; it is written in C and is one of the
-primitives of the GNU Emacs system. Since it is very simple, I will
-digress briefly from Lisp and describe it here.
-
-Like many of the other Emacs primitives, `delete-and-extract-region'
-is written as an instance of a C macro, a macro being a template for
-code. The complete macro looks like this:
-
- DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
- Sdelete_and_extract_region, 2, 2, 0,
- "Delete the text between START and END and return it.")
- (start, end)
- Lisp_Object start, end;
- {
- validate_region (&start, &end);
- return del_range_1 (XINT (start), XINT (end), 1, 1);
- }
-
-Without going into the details of the macro writing process, let me
-point out that this macro starts with the word `DEFUN'. The word
-`DEFUN' was chosen since the code serves the same purpose as `defun'
-does in Lisp. The word `DEFUN' is followed by seven parts inside of
-parentheses:
-
- * The first part is the name given to the function in Lisp,
- `delete-and-extract-region'.
-
- * The second part is the name of the function in C,
- `Fdelete_and_extract_region'. By convention, it starts with
- `F'. Since C does not use hyphens in names, underscores are used
- instead.
-
- * The third part is the name for the C constant structure that
- records information on this function for internal use. It is
- the name of the function in C but begins with an `S' instead of
- an `F'.
-
- * The fourth and fifth parts specify the minimum and maximum
- number of arguments the function can have. This function
- demands exactly 2 arguments.
-
- * The sixth part is nearly like the argument that follows the
- `interactive' declaration in a function written in Lisp: a letter
- followed, perhaps, by a prompt. The only difference from the
- Lisp is when the macro is called with no arguments. Then you
- write a `0' (which is a `null string'), as in this macro.
-
- If you were to specify arguments, you would place them between
- quotation marks. The C macro for `goto-char' includes `"NGoto
- char: "' in this position to indicate that the function expects
- a raw prefix, in this case, a numerical location in a buffer,
- and provides a prompt.
-
- * The seventh part is a documentation string, just like the one
- for a function written in Emacs Lisp, except that every newline
- must be written explicitly as `\n' followed by a backslash and
- carriage return.
-
- Thus, the first two lines of documentation for `goto-char' are
- written like this:
-
- "Set point to POSITION, a number or marker.\n\
- Beginning of buffer is position (point-min), end is (point-max).
-
-In a C macro, the formal parameters come next, with a statement of
-what kind of object they are, followed by what might be called the
-`body' of the macro. For `delete-and-extract-region' the `body'
-consists of the following two lines:
-
- validate_region (&start, &end);
- return del_range_1 (XINT (start), XINT (end), 1, 1);
-
-The first function, `validate_region' checks whether the values
-passed as the beginning and end of the region are the proper type and
-are within range. The second function, `del_range_1', actually
-deletes the text.
-
-`del_range_1' is a complex function we will not look into. It
-updates the buffer and does other things.
-
-However, it is worth looking at the two arguments passed to
-`del_range'. These are `XINT (start)' and `XINT (end)'.
-
-As far as the C language is concerned, `start' and `end' are two
-integers that mark the beginning and end of the region to be
-deleted(1).
-
-In early versions of Emacs, these two numbers were thirty-two bits
-long, but the code is slowly being generalized to handle other
-lengths. Three of the available bits are used to specify the type of
-information and a fourth bit is used for handling the computer's
-memory; the remaining bits are used as `content'.
-
-`XINT' is a C macro that extracts the relevant number from the longer
-collection of bits; the four other bits are discarded.
-
-The command in `delete-and-extract-region' looks like this:
-
- del_range_1 (XINT (start), XINT (end), 1, 1);
-
-It deletes the region between the beginning position, `start', and
-the ending position, `end'.
-
-From the point of view of the person writing Lisp, Emacs is all very
-simple; but hidden underneath is a great deal of complexity to make it
-all work.
-
----------- Footnotes ----------
-
-(1) More precisely, and requiring more expert knowledge to
-understand, the two integers are of type `Lisp_Object', which can
-also be a C union instead of an integer type.
-
-Initializing a Variable with `defvar'
-=====================================
-
-Unlike the `delete-and-extract-region' function, the
-`copy-region-as-kill' function is written in Emacs Lisp. Two
-functions within it, `kill-append' and `kill-new', copy a region in a
-buffer and save it in a variable called the `kill-ring'. This
-section describes how the `kill-ring' variable is created and
-initialized using the `defvar' special form.
-
-(Again we note that the term `kill-ring' is a misnomer. The text
-that is clipped out of the buffer can be brought back; it is not a
-ring of corpses, but a ring of resurrectable text.)
-
-In Emacs Lisp, a variable such as the `kill-ring' is created and
-given an initial value by using the `defvar' special form. The name
-comes from "define variable".
-
-The `defvar' special form is similar to `setq' in that it sets the
-value of a variable. It is unlike `setq' in two ways: first, it only
-sets the value of the variable if the variable does not already have
-a value. If the variable already has a value, `defvar' does not
-override the existing value. Second, `defvar' has a documentation
-string.
-
-(Another special form, `defcustom', is designed for variables that
-people customize. It has more features than `defvar'. (*Note
-Setting Variables with `defcustom': defcustom.)
-
-Seeing the Current Value of a Variable
---------------------------------------
-
-You can see the current value of a variable, any variable, by using
-the `describe-variable' function, which is usually invoked by typing
-`C-h v'. If you type `C-h v' and then `kill-ring' (followed by
-<RET>) when prompted, you will see what is in your current kill
-ring--this may be quite a lot! Conversely, if you have been doing
-nothing this Emacs session except read this document, you may have
-nothing in it. Also, you will see the documentation for `kill-ring':
-
- 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
- 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.
-
-The kill ring is defined by a `defvar' in the following way:
-
- (defvar kill-ring nil
- "List of killed text sequences.
- ...")
-
-In this variable definition, the variable is given an initial value of
-`nil', which makes sense, since if you have saved nothing, you want
-nothing back if you give a `yank' command. The documentation string
-is written just like the documentation string of a `defun'. As with
-the documentation string of the `defun', the first line of the
-documentation should be a complete sentence, since some commands,
-like `apropos', print only the first line of documentation.
-Succeeding lines should not be indented; otherwise they look odd when
-you use `C-h v' (`describe-variable').
-
-`defvar' and an asterisk
-------------------------
-
-In the past, Emacs used the `defvar' special form both for internal
-variables that you would not expect a user to change and for
-variables that you do expect a user to change. Although you can still
-use `defvar' for user customizable variables, please use `defcustom'
-instead, since that special form provides a path into the
-Customization commands. (*Note Setting Variables with `defcustom':
-defcustom.)
-
-When you specified a variable using the `defvar' special form, you
-could distinguish a readily settable variable from others by typing
-an asterisk, `*', in the first column of its documentation string.
-For example:
-
- (defvar shell-command-default-error-buffer nil
- "*Buffer name for `shell-command' ... error output.
- ... ")
-
-This means that you could (and still can) use the `edit-options'
-command to change the value of `shell-command-default-error-buffer'
-temporarily.
-
-However, options set using `edit-options' are set only for the
-duration of your editing session. The new values are not saved
-between sessions. Each time Emacs starts, it reads the original
-value, unless you change the value within your `.emacs' file, either
-by setting it manually or by using `customize'. *Note Your `.emacs'
-File: Emacs Initialization.
-
-For me, the major use of the `edit-options' command is to suggest
-variables that I might want to set in my `.emacs' file. I urge you
-to look through the list. (*Note Editing Variable Values:
-(emacs)Edit Options.)
-
-`copy-region-as-kill'
-=====================
-
-The `copy-region-as-kill' function copies a region of text from a
-buffer and (via either `kill-append' or `kill-new') saves it in the
-`kill-ring'.
-
-If you call `copy-region-as-kill' immediately after a `kill-region'
-command, Emacs appends the newly copied text to the previously copied
-text. This means that if you yank back the text, you get it all,
-from both this and the previous operation. On the other hand, if
-some other command precedes the `copy-region-as-kill', the function
-copies the text into a separate entry in the kill ring.
-
-The complete `copy-region-as-kill' function definition
-------------------------------------------------------
-
-Here is the complete text of the version 21 `copy-region-as-kill'
-function:
-
- (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")
- (if (eq last-command 'kill-region)
- (kill-append (buffer-substring beg end) (< end beg))
- (kill-new (buffer-substring beg end)))
- (if transient-mark-mode
- (setq deactivate-mark t))
- nil)
-
-As usual, this function can be divided into its component parts:
-
- (defun copy-region-as-kill (ARGUMENT-LIST)
- "DOCUMENTATION..."
- (interactive "r")
- BODY...)
-
-The arguments are `beg' and `end' and the function is interactive
-with `"r"', so the two arguments must refer to the beginning and end
-of the region. If you have been reading though this document from
-the beginning, understanding these parts of a function is almost
-becoming routine.
-
-The documentation is somewhat confusing unless you remember that the
-word `kill' has a meaning different from its usual meaning. The
-`Transient Mark' and `interprogram-cut-function' comments explain
-certain side-effects.
-
-After you once set a mark, a buffer always contains a region. If you
-wish, you can use Transient Mark mode to highlight the region
-temporarily. (No one wants to highlight the region all the time, so
-Transient Mark mode highlights it only at appropriate times. Many
-people turn off Transient Mark mode, so the region is never
-highlighted.)
-
-Also, a windowing system allows you to copy, cut, and paste among
-different programs. In the X windowing system, for example, the
-`interprogram-cut-function' function is `x-select-text', which works
-with the windowing system's equivalent of the Emacs kill ring.
-
-The body of the `copy-region-as-kill' function starts with an `if'
-clause. What this clause does is distinguish between two different
-situations: whether or not this command is executed immediately after
-a previous `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.
-
-The last two lines of the function prevent the region from lighting up
-if Transient Mark mode is turned on.
-
-The body of `copy-region-as-kill' merits discussion in detail.
-
-The Body of `copy-region-as-kill'
----------------------------------
-
-The `copy-region-as-kill' function works in much the same way as the
-`kill-region' function (*note `kill-region': kill-region.). Both are
-written so that two or more kills in a row combine their text into a
-single entry. If you yank back the text from the kill ring, you get
-it all in one piece. Moreover, kills that kill forward from the
-current position of the cursor are added to the end of the previously
-copied text and commands that copy text backwards add it to the
-beginning of the previously copied text. This way, the words in the
-text stay in the proper order.
-
-Like `kill-region', the `copy-region-as-kill' function makes use of
-the `last-command' variable that keeps track of the previous Emacs
-command.
-
-`last-command' and `this-command'
-.................................
-
-Normally, whenever a function is executed, Emacs sets the value of
-`this-command' to the function being executed (which in this case
-would be `copy-region-as-kill'). At the same time, Emacs sets the
-value of `last-command' to the previous value of `this-command'.
-
-In the first part of the body of the `copy-region-as-kill' function,
-an `if' expression determines whether the value of `last-command' is
-`kill-region'. If so, the then-part of the `if' expression is
-evaluated; it uses the `kill-append' function to concatenate the text
-copied at this call to the function with the text already in the
-first element (the CAR) of the kill ring. On the other hand, if the
-value of `last-command' is not `kill-region', then the
-`copy-region-as-kill' function attaches a new element to the kill
-ring using the `kill-new' function.
-
-The `if' expression reads as follows; it uses `eq', which is a
-function we have not yet seen:
-
- (if (eq last-command 'kill-region)
- ;; then-part
- (kill-append (buffer-substring beg end) (< end beg))
- ;; else-part
- (kill-new (buffer-substring beg end)))
-
-The `eq' function tests whether its first argument is the same Lisp
-object as its second argument. The `eq' function is similar to the
-`equal' function in that it is used to test for equality, but differs
-in that it determines whether two representations are actually the
-same object inside the computer, but with different names. `equal'
-determines whether the structure and contents of two expressions are
-the same.
-
-If the previous command was `kill-region', then the Emacs Lisp
-interpreter calls the `kill-append' function
-
-The `kill-append' function
-..........................
-
-The `kill-append' function looks like this:
-
- (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))
-
-The `kill-append' function is fairly straightforward. It uses the
-`kill-new' function, which we will discuss in more detail in a moment.
-
-First, let us look at the conditional that is one of the two arguments
-to `kill-new'. It uses `concat' to concatenate the new text to the
-CAR of the kill ring. Whether it prepends or appends the text
-depends on the results of an `if' expression:
-
- (if before-p ; if-part
- (concat string (car kill-ring)) ; then-part
- (concat (car kill-ring) string)) ; else-part
-
-If the region being killed is before the region that was killed in the
-last command, then it should be prepended before the material that was
-saved in the previous kill; and conversely, if the killed text follows
-what was just killed, it should be appended after the previous text.
-The `if' expression depends on the predicate `before-p' to decide
-whether the newly saved text should be put before or after the
-previously saved text.
-
-The symbol `before-p' is the name of one of the arguments to
-`kill-append'. When the `kill-append' function is evaluated, it is
-bound to the value returned by evaluating the actual argument. In
-this case, this is the expression `(< end beg)'. This expression
-does not directly determine whether the killed text in this command
-is located before or after the kill text of the last command; what is
-does is determine whether the value of the variable `end' is less
-than the value of the variable `beg'. If it is, it means that the
-user is most likely heading towards the beginning of the buffer.
-Also, the result of evaluating the predicate expression, `(< end
-beg)', will be true and the text will be prepended before the
-previous text. On the other hand, if the value of the variable `end'
-is greater than the value of the variable `beg', the text will be
-appended after the previous text.
-
-When the newly saved text will be prepended, then the string with the
-new text will be concatenated before the old text:
-
- (concat string (car kill-ring))
-
-But if the text will be appended, it will be concatenated after the
-old text:
-
- (concat (car kill-ring) string))
-
-To understand how this works, we first need to review the `concat'
-function. The `concat' function links together or unites two strings
-of text. The result is a string. For example:
-
- (concat "abc" "def")
- => "abcdef"
-
- (concat "new "
- (car '("first element" "second element")))
- => "new first element"
-
- (concat (car
- '("first element" "second element")) " modified")
- => "first element modified"
-
-We can now make sense of `kill-append': it modifies the contents of
-the kill ring. The kill ring is a list, each element of which is
-saved text. The `kill-append' function uses the `kill-new' function
-which in turn uses the `setcar' function.
-
-The `kill-new' function
-.......................
-
-The `kill-new' function looks like this:
-
- (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))))
-
-As usual, we can look at this function in parts.
-
-The first line of the documentation makes sense:
-
- Make STRING the latest kill in the kill ring.
-
-Let's skip over the rest of the documentation for the moment.
-
-Also, let's skip over the first two lines of code, those involving
-`menu-bar-update-yank-menu'. We will explain them below.
-
-The critical lines are these:
-
- (if (and replace kill-ring)
- ;; then
- (setcar kill-ring string)
- ;; else
- (setq kill-ring (cons string kill-ring))
- (if (> (length kill-ring) kill-ring-max)
- ;; avoid overly long kill ring
- (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))))
-
-The conditional test is `(and replace kill-ring)'. This will be true
-when two conditions are met: the kill ring has something in it, and
-the `replace' variable is true.
-
-The `kill-append' function sets `replace' to be true; then, when the
-kill ring has at least one item in it, the `setcar' expression is
-executed:
-
- (setcar kill-ring string)
-
-The `setcar' function actually changes the first element of the
-`kill-ring' list to the value of `string'. It replaces the first
-element.
-
-On the other hand, if the kill ring is empty, or replace is false, the
-else-part of the condition is executed:
-
- (setq kill-ring (cons string kill-ring))
- (if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
-
-This expression first constructs a new version of the kill ring by
-prepending `string' to the existing kill ring as a new element. Then
-it executes a second `if' clause. This second `if' clause keeps the
-kill ring from growing too long.
-
-Let's look at these two expressions in order.
-
-The `setq' line of the else-part sets the new value of the kill ring
-to what results from adding the string being killed to the old kill
-ring.
-
-We can see how this works with an example:
-
- (setq example-list '("here is a clause" "another clause"))
-
-After evaluating this expression with `C-x C-e', you can evaluate
-`example-list' and see what it returns:
-
- example-list
- => ("here is a clause" "another clause")
-
-Now, we can add a new element on to this list by evaluating the
-following expression:
-
- (setq example-list (cons "a third clause" example-list))
-
-When we evaluate `example-list', we find its value is:
-
- example-list
- => ("a third clause" "here is a clause" "another clause")
-
-Thus, the third clause was added to the list by `cons'.
-
-This is exactly similar to what the `setq' and `cons' do in the
-function. Here is the line again:
-
- (setq kill-ring (cons string kill-ring))
-
-Now for the second part of the `if' clause. This expression keeps
-the kill ring from growing too long. It looks like this:
-
- (if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
-
-The code checks whether the length of the kill ring is greater than
-the maximum permitted length. This is the value of `kill-ring-max'
-(which is 60, by default). If the length of the kill ring is too
-long, then this code sets the last element of the kill ring to `nil'.
-It does this by using two functions, `nthcdr' and `setcdr'.
-
-We looked at `setcdr' earlier (*note `setcdr': setcdr.). It sets the
-CDR of a list, just as `setcar' sets the CAR of a list. In this
-case, however, `setcdr' will not be setting the CDR of the whole kill
-ring; the `nthcdr' function is used to cause it to set the CDR of the
-next to last element of the kill ring--this means that since the CDR
-of the next to last element is the last element of the kill ring, it
-will set the last element of the kill ring.
-
-The `nthcdr' function works by repeatedly taking the CDR of a
-list--it takes the CDR of the CDR of the CDR ... It does this N
-times and returns the results.
-
-Thus, if we had a four element list that was supposed to be three
-elements long, we could set the CDR of the next to last element to
-`nil', and thereby shorten the list.
-
-You can see this by evaluating the following three expressions in
-turn. First set the value of `trees' to `(maple oak pine birch)',
-then set the CDR of its second CDR to `nil' and then find the value
-of `trees':
-
- (setq trees '(maple oak pine birch))
- => (maple oak pine birch)
-
- (setcdr (nthcdr 2 trees) nil)
- => nil
-
- trees
- => (maple oak pine)
-
-(The value returned by the `setcdr' expression is `nil' since that is
-what the CDR is set to.)
-
-To repeat, in `kill-new', the `nthcdr' function takes the CDR a
-number of times that is one less than the maximum permitted size of
-the kill ring and sets the CDR of that element (which will be the
-rest of the elements in the kill ring) to `nil'. This prevents the
-kill ring from growing too long.
-
-The next to last expression in the `kill-new' function is
-
- (setq kill-ring-yank-pointer kill-ring)
-
-The `kill-ring-yank-pointer' is a global variable that is set to be
-the `kill-ring'.
-
-Even though the `kill-ring-yank-pointer' is called a `pointer', it is
-a variable just like the kill ring. However, the name has been
-chosen to help humans understand how the variable is used. The
-variable is used in functions such as `yank' and `yank-pop' (*note
-Yanking Text Back: Yanking.).
-
-Now, to return to the first two lines in the body of the function:
-
- (and (fboundp 'menu-bar-update-yank-menu)
- (menu-bar-update-yank-menu string (and replace (car kill-ring))))
-
-This is an expression whose first element is the function `and'.
-
-The `and' special form evaluates each of its arguments until one of
-the arguments returns a value of `nil', in which case the `and'
-expression returns `nil'; however, if none of the arguments returns a
-value of `nil', the value resulting from evaluating the last argument
-is returned. (Since such a value is not `nil', it is considered true
-in Emacs Lisp.) In other words, an `and' expression returns a true
-value only if all its arguments are true.
-
-In this case, the expression tests first to see whether
-`menu-bar-update-yank-menu' exists as a function, and if so, calls
-it. The `fboundp' function returns true if the symbol it is testing
-has a function definition that `is not void'. If the symbol's
-function definition were void, we would receive an error message, as
-we did when we created errors intentionally (*note Generate an Error
-Message: Making Errors.).
-
-Essentially, the `and' is an `if' expression that reads like this:
-
- if THE-MENU-BAR-FUNCTION-EXISTS
- then EXECUTE-IT
-
-`menu-bar-update-yank-menu' is one of the functions that make it
-possible to use the `Select and Paste' menu in the Edit item of a menu
-bar; using a mouse, you can look at the various pieces of text you
-have saved and select one piece to paste.
-
-Finally, the last expression in the `kill-new' function adds the
-newly copied string to whatever facility exists for copying and
-pasting among different programs running in a windowing system. In
-the X Windowing system, for example, the `x-select-text' function
-takes the string and stores it in memory operated by X. You can paste
-the string in another program, such as an Xterm.
-
-The expression looks like this:
-
- (if interprogram-cut-function
- (funcall interprogram-cut-function string (not replace))))
-
-If an `interprogram-cut-function' exists, then Emacs executes
-`funcall', which in turn calls its first argument as a function and
-passes the remaining arguments to it. (Incidentally, as far as I can
-see, this `if' expression could be replaced by an `and' expression
-similar to the one in the first part of the function.)
-
-We are not going to discuss windowing systems and other programs
-further, but merely note that this is a mechanism that enables GNU
-Emacs to work easily and well with other programs.
-
-This code for placing text in the kill ring, either concatenated with
-an existing element or as a new element, leads us to the code for
-bringing back text that has been cut out of the buffer--the yank
-commands. However, before discussing the yank commands, it is better
-to learn how lists are implemented in a computer. This will make
-clear such mysteries as the use of the term `pointer'.
-
-Review
-======
-
-Here is a brief summary of some recently introduced functions.
-
-`car'
-`cdr'
- `car' returns the first element of a list; `cdr' returns the
- second and subsequent elements of a list.
-
- For example:
-
- (car '(1 2 3 4 5 6 7))
- => 1
- (cdr '(1 2 3 4 5 6 7))
- => (2 3 4 5 6 7)
-
-`cons'
- `cons' constructs a list by prepending its first argument to its
- second argument.
-
- For example:
-
- (cons 1 '(2 3 4))
- => (1 2 3 4)
-
-`nthcdr'
- Return the result of taking CDR `n' times on a list. The `rest
- of the rest', as it were.
-
- For example:
-
- (nthcdr 3 '(1 2 3 4 5 6 7))
- => (4 5 6 7)
-
-`setcar'
-`setcdr'
- `setcar' changes the first element of a list; `setcdr' changes
- the second and subsequent elements of a list.
-
- For example:
-
- (setq triple '(1 2 3))
-
- (setcar triple '37)
-
- triple
- => (37 2 3)
-
- (setcdr triple '("foo" "bar"))
-
- triple
- => (37 "foo" "bar")
-
-`progn'
- Evaluate each argument in sequence and then return the value of
- the last.
-
- For example:
-
- (progn 1 2 3 4)
- => 4
-
-`save-restriction'
- Record whatever narrowing is in effect in the current buffer, if
- any, and restore that narrowing after evaluating the arguments.
-
-`search-forward'
- Search for a string, and if the string is found, move point.
-
- Takes four arguments:
-
- 1. The string to search for.
-
- 2. Optionally, the limit of the search.
-
- 3. Optionally, what to do if the search fails, return `nil' or
- an error message.
-
- 4. Optionally, how many times to repeat the search; if
- negative, the search goes backwards.
-
-`kill-region'
-`delete-region'
-`copy-region-as-kill'
- `kill-region' cuts the text between point and mark from the
- buffer and stores that text in the kill ring, so you can get it
- back by yanking.
-
- `delete-and-extract-region' removes the text between point and
- mark from the buffer and throws it away. You cannot get it back.
-
- `copy-region-as-kill' copies the text between point and mark into
- the kill ring, from which you can get it by yanking. The
- function does not cut or remove the text from the buffer.
-
-Searching Exercises
-===================
-
- * Write an interactive function that searches for a string. If the
- search finds the string, leave point after it and display a
- message that says "Found!". (Do not use `search-forward' for
- the name of this function; if you do, you will overwrite the
- existing version of `search-forward' that comes with Emacs. Use
- a name such as `test-search' instead.)
-
- * Write a function that prints the third element of the kill ring
- in the echo area, if any; if the kill ring does not contain a
- third element, print an appropriate message.
-
-How Lists are Implemented
-*************************
-
-In Lisp, atoms are recorded in a straightforward fashion; if the
-implementation is not straightforward in practice, it is, nonetheless,
-straightforward in theory. The atom `rose', for example, is recorded
-as the four contiguous letters `r', `o', `s', `e'. A list, on the
-other hand, is kept differently. The mechanism is equally simple,
-but it takes a moment to get used to the idea. A list is kept using
-a series of pairs of pointers. In the series, the first pointer in
-each pair points to an atom or to another list, and the second
-pointer in each pair points to the next pair, or to the symbol `nil',
-which marks the end of the list.
-
-A pointer itself is quite simply the electronic address of what is
-pointed to. Hence, a list is kept as a series of electronic
-addresses.
-
-Lists diagrammed
-================
-
-For example, the list `(rose violet buttercup)' has three elements,
-`rose', `violet', and `buttercup'. In the computer, the electronic
-address of `rose' is recorded in a segment of computer memory along
-with the address that gives the electronic address of where the atom
-`violet' is located; and that address (the one that tells where
-`violet' is located) is kept along with an address that tells where
-the address for the atom `buttercup' is located.
-
-This sounds more complicated than it is and is easier seen in a
-diagram:
-
- ___ ___ ___ ___ ___ ___
- |___|___|--> |___|___|--> |___|___|--> nil
- | | |
- | | |
- --> rose --> violet --> buttercup
-
-
-
-In the diagram, each box represents a word of computer memory that
-holds a Lisp object, usually in the form of a memory address. The
-boxes, i.e. the addresses, are in pairs. Each arrow points to what
-the address is the address of, either an atom or another pair of
-addresses. The first box is the electronic address of `rose' and the
-arrow points to `rose'; the second box is the address of the next
-pair of boxes, the first part of which is the address of `violet' and
-the second part of which is the address of the next pair. The very
-last box points to the symbol `nil', which marks the end of the list.
-
-When a variable is set to a list with a function such as `setq', it
-stores the address of the first box in the variable. Thus,
-evaluation of the expression
-
- (setq bouquet '(rose violet buttercup))
-
-creates a situation like this:
-
- bouquet
- |
- | ___ ___ ___ ___ ___ ___
- --> |___|___|--> |___|___|--> |___|___|--> nil
- | | |
- | | |
- --> rose --> violet --> buttercup
-
-
-
-In this example, the symbol `bouquet' holds the address of the first
-pair of boxes.
-
-This same list can be illustrated in a different sort of box notation
-like this:
-
- bouquet
- |
- | -------------- --------------- ----------------
- | | car | cdr | | car | cdr | | car | cdr |
- -->| rose | o------->| violet | o------->| butter- | nil |
- | | | | | | | cup | |
- -------------- --------------- ----------------
-
-
-
-(Symbols consist of more than pairs of addresses, but the structure of
-a symbol is made up of addresses. Indeed, the symbol `bouquet'
-consists of a group of address-boxes, one of which is the address of
-the printed word `bouquet', a second of which is the address of a
-function definition attached to the symbol, if any, a third of which
-is the address of the first pair of address-boxes for the list `(rose
-violet buttercup)', and so on. Here we are showing that the symbol's
-third address-box points to the first pair of address-boxes for the
-list.)
-
-If a symbol is set to the CDR of a list, the list itself is not
-changed; the symbol simply has an address further down the list. (In
-the jargon, CAR and CDR are `non-destructive'.) Thus, evaluation of
-the following expression
-
- (setq flowers (cdr bouquet))
-
-produces this:
-
-
- bouquet flowers
- | |
- | ___ ___ | ___ ___ ___ ___
- --> | | | --> | | | | | |
- |___|___|----> |___|___|--> |___|___|--> nil
- | | |
- | | |
- --> rose --> violet --> buttercup
-
-
-
-
-The value of `flowers' is `(violet buttercup)', which is to say, the
-symbol `flowers' holds the address of the pair of address-boxes, the
-first of which holds the address of `violet', and the second of which
-holds the address of `buttercup'.
-
-A pair of address-boxes is called a "cons cell" or "dotted pair".
-*Note List Type: (elisp)List Type, and *Note Dotted Pair Notation:
-(elisp)Dotted Pair Notation, for more information about cons cells
-and dotted pairs.
-
-The function `cons' adds a new pair of addresses to the front of a
-series of addresses like that shown above. For example, evaluating
-the expression
-
- (setq bouquet (cons 'lily bouquet))
-
-produces:
-
-
- bouquet flowers
- | |
- | ___ ___ ___ ___ | ___ ___ ___ ___
- --> | | | | | | --> | | | | | |
- |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil
- | | | |
- | | | |
- --> lily --> rose --> violet --> buttercup
-
-
-
-
-However, this does not change the value of the symbol `flowers', as
-you can see by evaluating the following,
-
- (eq (cdr (cdr bouquet)) flowers)
-
-which returns `t' for true.
-
-Until it is reset, `flowers' still has the value `(violet
-buttercup)'; that is, it has the address of the cons cell whose first
-address is of `violet'. Also, this does not alter any of the
-pre-existing cons cells; they are all still there.
-
-Thus, in Lisp, to get the CDR of a list, you just get the address of
-the next cons cell in the series; to get the CAR of a list, you get
-the address of the first element of the list; to `cons' a new element
-on a list, you add a new cons cell to the front of the list. That is
-all there is to it! The underlying structure of Lisp is brilliantly
-simple!
-
-And what does the last address in a series of cons cells refer to? It
-is the address of the empty list, of `nil'.
-
-In summary, when a Lisp variable is set to a value, it is provided
-with the address of the list to which the variable refers.
-
-Symbols as a Chest of Drawers
-=============================
-
-In an earlier section, I suggested that you might imagine a symbol as
-being a chest of drawers. The function definition is put in one
-drawer, the value in another, and so on. What is put in the drawer
-holding the value can be changed without affecting the contents of the
-drawer holding the function definition, and vice-versa.
-
-Actually, what is put in each drawer is the address of the value or
-function definition. It is as if you found an old chest in the attic,
-and in one of its drawers you found a map giving you directions to
-where the buried treasure lies.
-
-(In addition to its name, symbol definition, and variable value, a
-symbol has a `drawer' for a "property list" which can be used to
-record other information. Property lists are not discussed here; see
-*Note Property Lists: (elisp)Property Lists.)
-
-Here is a fanciful representation:
-
-
- Chest of Drawers Contents of Drawers
-
- __ o0O0o __
- / \
- ---------------------
- | directions to | [map to]
- | symbol name | bouquet
- | |
- +---------------------+
- | directions to |
- | symbol definition | [none]
- | |
- +---------------------+
- | directions to | [map to]
- | variable value | (rose violet buttercup)
- | |
- +---------------------+
- | directions to |
- | property list | [not described here]
- | |
- +---------------------+
- |/ \|
-
-
-
-
-Exercise
-========
-
-Set `flowers' to `violet' and `buttercup'. Cons two more flowers on
-to this list and set this new list to `more-flowers'. Set the CAR of
-`flowers' to a fish. What does the `more-flowers' list now contain?
-
-Yanking Text Back
-*****************
-
-Whenever you cut text out of a buffer with a `kill' command in GNU
-Emacs, you can bring it back with a `yank' command. The text that is
-cut out of the buffer is put in the kill ring and the yank commands
-insert the appropriate contents of the kill ring back into a buffer
-(not necessarily the original buffer).
-
-A simple `C-y' (`yank') command inserts the first item from the kill
-ring into the current buffer. If the `C-y' command is followed
-immediately by `M-y', the first element is replaced by the second
-element. Successive `M-y' commands replace the second element with
-the third, fourth, or fifth element, and so on. When the last
-element in the kill ring is reached, it is replaced by the first
-element and the cycle is repeated. (Thus the kill ring is called a
-`ring' rather than just a `list'. However, the actual data structure
-that holds the text is a list. *Note Handling the Kill Ring: Kill
-Ring, for the details of how the list is handled as a ring.)
-
-Kill Ring Overview
-==================
-
-The kill ring is a list of textual strings. This is what it looks
-like:
-
- ("some text" "a different piece of text" "yet more text")
-
-If this were the contents of my kill ring and I pressed `C-y', the
-string of characters saying `some text' would be inserted in this
-buffer where my cursor is located.
-
-The `yank' command is also used for duplicating text by copying it.
-The copied text is not cut from the buffer, but a copy of it is put
-on the kill ring and is inserted by yanking it back.
-
-Three functions are used for bringing text back from the kill ring:
-`yank', which is usually bound to `C-y'; `yank-pop', which is usually
-bound to `M-y'; and `rotate-yank-pointer', which is used by the two
-other functions.
-
-These functions refer to the kill ring through a variable called the
-`kill-ring-yank-pointer'. Indeed, the insertion code for both the
-`yank' and `yank-pop' functions is:
-
- (insert (car kill-ring-yank-pointer))
-
-To begin to understand how `yank' and `yank-pop' work, it is first
-necessary to look at the `kill-ring-yank-pointer' variable and the
-`rotate-yank-pointer' function.
-
-The `kill-ring-yank-pointer' Variable
-=====================================
-
-`kill-ring-yank-pointer' is a variable, just as `kill-ring' is a
-variable. It points to something by being bound to the value of what
-it points to, like any other Lisp variable.
-
-Thus, if the value of the kill ring is:
-
- ("some text" "a different piece of text" "yet more text")
-
-and the `kill-ring-yank-pointer' points to the second clause, the
-value of `kill-ring-yank-pointer' is:
-
- ("a different piece of text" "yet more text")
-
-As explained in the previous chapter (*note List Implementation::),
-the computer does not keep two different copies of the text being
-pointed to by both the `kill-ring' and the `kill-ring-yank-pointer'.
-The words "a different piece of text" and "yet more text" are not
-duplicated. Instead, the two Lisp variables point to the same pieces
-of text. Here is a diagram:
-
- kill-ring kill-ring-yank-pointer
- | |
- | ___ ___ | ___ ___ ___ ___
- ---> | | | --> | | | | | |
- |___|___|----> |___|___|--> |___|___|--> nil
- | | |
- | | |
- | | --> "yet more text"
- | |
- | --> "a different piece of text
- |
- --> "some text"
-
-
-
-
-Both the variable `kill-ring' and the variable
-`kill-ring-yank-pointer' are pointers. But the kill ring itself is
-usually described as if it were actually what it is composed of. The
-`kill-ring' is spoken of as if it were the list rather than that it
-points to the list. Conversely, the `kill-ring-yank-pointer' is
-spoken of as pointing to a list.
-
-These two ways of talking about the same thing sound confusing at
-first but make sense on reflection. The kill ring is generally
-thought of as the complete structure of data that holds the
-information of what has recently been cut out of the Emacs buffers.
-The `kill-ring-yank-pointer' on the other hand, serves to
-indicate--that is, to `point to'--that part of the kill ring of which
-the first element (the CAR) will be inserted.
-
-The `rotate-yank-pointer' function changes the element in the kill
-ring to which the `kill-ring-yank-pointer' points; when the pointer
-is set to point to the next element beyond the end of the kill ring,
-it automatically sets it to point to the first element of the kill
-ring. This is how the list is transformed into a ring. The
-`rotate-yank-pointer' function itself is not difficult, but contains
-many details. It and the much simpler `yank' and `yank-pop'
-functions are described in an appendix. *Note Handling the Kill
-Ring: Kill Ring.
-
-Exercises with `yank' and `nthcdr'
-==================================
-
- * Using `C-h v' (`describe-variable'), look at the value of your
- kill ring. Add several items to your kill ring; look at its
- value again. Using `M-y' (`yank-pop)', move all the way around
- the kill ring. How many items were in your kill ring? Find the
- value of `kill-ring-max'. Was your kill ring full, or could you
- have kept more blocks of text within it?
-
- * Using `nthcdr' and `car', construct a series of expressions to
- return the first, second, third, and fourth elements of a list.
-
-Loops and Recursion
-*******************
-
-Emacs Lisp has two primary ways to cause an expression, or a series of
-expressions, to be evaluated repeatedly: one uses a `while' loop, and
-the other uses "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 `while' loops and
-their kin; but you can use recursion, which provides a very powerful
-way to think about and then to solve problems(1).
-
----------- Footnotes ----------
-
-(1) 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 values of
-`max-specpdl-size' and `max-lisp-eval-depth'. In my `.emacs' file, I
-set them to 15 and 30 times their default value.
-
-`while'
-=======
-
-The `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 `if'; what the interpreter does
-next, however, is different.
-
-In a `while' expression, if the value returned by evaluating the
-first argument is false, the Lisp interpreter skips the rest of the
-expression (the "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
-`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.
-
-The template for a `while' expression looks like this:
-
- (while TRUE-OR-FALSE-TEST
- BODY...)
-
-Looping with `while'
---------------------
-
-So long as the true-or-false-test of the `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 `while' expression and
-`exits the loop'.
-
-Clearly, if the value returned by evaluating the first argument to
-`while' is always true, the body following will be evaluated again
-and again ... and again ... forever. Conversely, if the value
-returned is never true, the expressions in the body will never be
-evaluated. The craft of writing a `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 `while' is the value of the
-true-or-false-test. An interesting consequence of this is that a
-`while' loop that evaluates without error will return `nil' or false
-regardless of whether it has looped 1 or 100 times or none at all. A
-`while' expression that evaluates successfully never returns a true
-value! What this means is that `while' is always evaluated for its
-side effects, which is to say, the consequences of evaluating the
-expressions within the body of the `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.
-
-A `while' Loop and a List
--------------------------
-
-A common way to control a `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, `()', which is a synonym for `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 `nil', a list that returns elements will test true in a `while'
-loop.
-
-For example, you can set the variable `empty-list' to `nil' by
-evaluating the following `setq' expression:
-
- (setq empty-list ())
-
-After evaluating the `setq' expression, you can evaluate the variable
-`empty-list' in the usual way, by placing the cursor after the symbol
-and typing `C-x C-e'; `nil' will appear in your echo area:
-
- empty-list
-
-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:
-
- (setq animals '(gazelle giraffe lion tiger))
-
- animals
-
-Thus, to create a `while' loop that tests whether there are any items
-in the list `animals', the first part of the loop will be written
-like this:
-
- (while animals
- ...
-
-When the `while' tests its first argument, the variable `animals' is
-evaluated. It returns a list. So long as the list has elements, the
-`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 `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 `while'
-expression set the value of the list to be the CDR of the list. Each
-time the `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 `while' loop will return false, and the arguments to
-the `while' will no longer be evaluated.
-
-For example, the list of animals bound to the variable `animals' can
-be set to be the CDR of the original list with the following
-expression:
-
- (setq animals (cdr animals))
-
-If you have evaluated the previous expressions and then evaluate this
-expression, you will see `(giraffe lion tiger)' appear in the echo
-area. If you evaluate the expression again, `(lion tiger)' will
-appear in the echo area. If you evaluate it again and yet again,
-`(tiger)' appears and then the empty list, shown by `nil'.
-
-A template for a `while' loop that uses the `cdr' function repeatedly
-to cause the true-or-false-test eventually to test false looks like
-this:
-
- (while TEST-WHETHER-LIST-IS-EMPTY
- BODY...
- SET-LIST-TO-CDR-OF-LIST)
-
-This test and use of `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.
-
-An Example: `print-elements-of-list'
-------------------------------------
-
-The `print-elements-of-list' function illustrates a `while' loop with
-a list.
-
-The function requires several lines for its output. If you are
-reading this in Emacs 21 or a later version, 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 `*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 `C-<SPC>' (`set-mark-command'), moving the cursor to the end of
-the region and then copying the region using `M-w'
-(`copy-region-as-kill'). In the `*scratch*' buffer, you can yank the
-expressions back by typing `C-y' (`yank').
-
-After you have copied the expressions to the `*scratch*' buffer,
-evaluate each expression in turn. Be sure to evaluate the last
-expression, `(print-elements-of-list animals)', by typing `C-u C-x
-C-e', that is, by giving an argument to `eval-last-sexp'. This will
-cause the result of the evaluation to be printed in the `*scratch*'
-buffer instead of being printed in the echo area. (Otherwise you
-will see something like this in your echo area:
-`^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil', in which each `^J'
-stands for a `newline'.)
-
-If you are using Emacs 21 or later, you can evaluate these expressions
-directly in the Info buffer, and the echo area will grow to show the
-results.
-
- (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)
-
-When you evaluate the three expressions in sequence, you will see
-this:
-
- gazelle
-
- giraffe
-
- lion
-
- tiger
- nil
-
-Each element of the list is printed on a line of its own (that is what
-the function `print' does) and then the value returned by the
-function is printed. Since the last expression in the function is the
-`while' loop, and since `while' loops always return `nil', a `nil' is
-printed after the last element of the list.
-
-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.
-
-The test can be an expression such as `(< count desired-number)'
-which returns `t' for true if the value of `count' is less than the
-`desired-number' of repetitions and `nil' for false if the value of
-`count' is equal to or is greater than the `desired-number'. The
-expression that increments the count can be a simple `setq' such as
-`(setq count (1+ count))', where `1+' is a built-in function in Emacs
-Lisp that adds 1 to its argument. (The expression `(1+ count)' has
-the same result as `(+ count 1)', but is easier for a human to read.)
-
-The template for a `while' loop controlled by an incrementing counter
-looks like this:
-
- SET-COUNT-TO-INITIAL-VALUE
- (while (< count desired-number) ; true-or-false-test
- BODY...
- (setq count (1+ count))) ; incrementer
-
-Note that you need to set the initial value of `count'; usually it is
-set to 1.
-
-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:
-
-
- *
- * *
- * * *
- * * * *
-
-
-(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 `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.
-
-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 `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 `number-of-rows'.
-
-Finally, we need a variable to use as a counter. We could call this
-variable `counter', but a better name is `row-number'. That is
-because what the counter does 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 `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 `total' and `row-number' are used only inside the function, so
-they can be declared as local variables with `let' and given initial
-values. Clearly, the initial value for `total' should be 0. The
-initial value of `row-number' should be 1, since we start with the
-first row. This means that the `let' statement will look like this:
-
- (let ((total 0)
- (row-number 1))
- BODY...)
-
-After the internal variables are declared and bound to their initial
-values, we can begin the `while' loop. The expression that serves as
-the test should return a value of `t' for true so long as the
-`row-number' is less than or equal to the `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.)
-
-Lisp provides the `<=' 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 `while'
-will evaluate as its test should look like this:
-
- (<= row-number number-of-rows)
-
-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.)
-
- (setq total (+ total row-number))
-
-What this does is set the new value of `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 `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 `row-number' variable,
-which serves as a counter. After the `row-number' variable has been
-incremented, the true-or-false-test at the beginning of the `while'
-loop tests whether its value is still less than or equal to the value
-of the `number-of-rows' and if it is, adds the new value of the
-`row-number' variable to the `total' of the previous repetition of
-the loop.
-
-The built-in Emacs Lisp function `1+' adds 1 to a number, so the
-`row-number' variable can be incremented with this expression:
-
- (setq row-number (1+ row-number))
-
-Putting the function definition together
-........................................
-
-We have created the parts for the function definition; now we need to
-put them together.
-
-First, the contents of the `while' expression:
-
- (while (<= row-number number-of-rows) ; true-or-false-test
- (setq total (+ total row-number))
- (setq row-number (1+ row-number))) ; incrementer
-
-Along with the `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 `total' on a line by itself
-after the `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 `let', and this is the value returned by the
-`while', which is always `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 `while'; it is the
-last element of the list that starts with the symbol `while'.
-Moreover, the whole of the `while' loop is a list within the body of
-the `let'.
-
-In outline, the function will look like this:
-
- (defun NAME-OF-FUNCTION (ARGUMENT-LIST)
- "DOCUMENTATION..."
- (let (VARLIST)
- (while (TRUE-OR-FALSE-TEST)
- BODY-OF-WHILE... )
- ... ) ; Need final expression here.
-
-The result of evaluating the `let' is what is going to be returned by
-the `defun' since the `let' is not embedded within any containing
-list, except for the `defun' as a whole. However, if the `while' is
-the last element of the `let' expression, the function will always
-return `nil'. This is not what we want! Instead, what we want is
-the value of the variable `total'. This is returned by simply
-placing the symbol as the last element of the list starting with
-`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 `let'
-all on one line. This format makes it evident that the VARLIST and
-`while' expressions are the second and third elements of the list
-starting with `let', and the `total' is the last element:
-
- (let (VARLIST) (while (TRUE-OR-FALSE-TEST) BODY-OF-WHILE... ) total)
-
-Putting everything together, the `triangle' function definition looks
-like this:
-
- (defun triangle (number-of-rows) ; Version with
- ; 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."
- (let ((total 0)
- (row-number 1))
- (while (<= row-number number-of-rows)
- (setq total (+ total row-number))
- (setq row-number (1+ row-number)))
- total))
-
-After you have installed `triangle' by evaluating the function, you
-can try it out. Here are two examples:
-
- (triangle 4)
-
- (triangle 7)
-
-The sum of the first four numbers is 10 and the sum of the first seven
-numbers is 28.
-
-Loop with a Decrementing Counter
---------------------------------
-
-Another common way to write a `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 `(> counter 0)' which returns
-`t' for true if the value of `counter' is greater than zero, and
-`nil' for false if the value of `counter' is equal to or less than
-zero. The expression that makes the number smaller and smaller can
-be a simple `setq' such as `(setq counter (1- counter))', where `1-'
-is a built-in function in Emacs Lisp that subtracts 1 from its
-argument.
-
-The template for a decrementing `while' loop looks like this:
-
- (while (> counter 0) ; true-or-false-test
- BODY...
- (setq counter (1- counter))) ; decrementer
-
-Example with decrementing counter
-.................................
-
-To illustrate a loop with a decrementing counter, we will rewrite the
-`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.
-
-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 `number-of-rows', `number-of-pebbles-in-row', and `total',
-respectively.
-
-Both `total' and `number-of-pebbles-in-row' are used only inside the
-function and are declared with `let'. The initial value of `total'
-should, of course, be zero. However, the initial value of
-`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.
-
-This means that the beginning of the `let' expression will look like
-this:
-
- (let ((total 0)
- (number-of-pebbles-in-row number-of-rows))
- BODY...)
-
-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:
-
- (setq total (+ total number-of-pebbles-in-row))
-
-After the `number-of-pebbles-in-row' is added to the `total', the
-`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 `1-' can be
-used to compute the number of pebbles in the preceding row. This can
-be done with the following expression:
-
- (setq number-of-pebbles-in-row
- (1- number-of-pebbles-in-row))
-
-Finally, we know that the `while' loop should stop making repeated
-additions when there are no pebbles in a row. So the test for the
-`while' loop is simply:
-
- (while (> number-of-pebbles-in-row 0)
-
-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!
-
-The function definition looks like this:
-
- ;;; 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))
-
-As written, this function works.
-
-However, we do not need `number-of-pebbles-in-row'.
-
-When the `triangle' function is evaluated, the symbol
-`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
-`number-of-rows' can be used anywhere in the function where
-`number-of-pebbles-in-row' is used.
-
-Here is a second version of the function written a bit more cleanly:
-
- (defun triangle (number) ; 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))
-
-In brief, a properly written `while' loop will consist of three parts:
-
- 1. A test that will return false after the loop has repeated itself
- the correct number of times.
-
- 2. An expression the evaluation of which will return the value
- desired after being repeatedly evaluated.
-
- 3. 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.
-
-Save your time: `dolist' and `dotimes'
-======================================
-
-In addition to `while', both `dolist' and `dotimes' provide for
-looping. Sometimes these are quicker to write than the equivalent
-`while' loop. Both are Lisp macros. (*Note Macros: (elisp)Macros. )
-
-`dolist' works like a `while' loop that `CDRs down a list': `dolist'
-automatically shortens the list each time it loops--takes the CDR of
-the list--and binds the CAR of each shorter version of the list to
-the first of its arguments.
-
-`dotimes' loops a specific number of times: you specify the number.
-
-The `dolist' Macro
-..................
-
-Suppose, for example, you want to reverse a list, so that "first"
-"second" "third" becomes "third" "second" "first".
-
-In practice, you would use the `reverse' function, like this:
-
- (setq animals '(gazelle giraffe lion tiger))
-
- (reverse animals)
-
-Here is how you could reverse the list using a `while' loop:
-
- (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)
-
-And here is how you could use the `dolist' macro:
-
- (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)
-
-In Info, you can place your cursor after the closing parenthesis of
-each expression and type `C-x C-e'; in each case, you should see
-
- (tiger lion giraffe gazelle)
-
-in the echo area.
-
-For this example, the existing `reverse' function is obviously best.
-The `while' loop is just like our first example (*note A `while' Loop
-and a List: Loop Example.). The `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 `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 `while' loop, the `(setq list (cdr list))'
-expression shortens the list, so the `while' loop eventually stops.
-In addition, it provides the `cons' expression with a new first
-element by creating a new and shorter list at each repetition of the
-loop.
-
-The `dolist' expression does very much the same as the `while'
-expression, except that the `dolist' macro does some of the work you
-have to do when writing a `while' expression.
-
-Like a `while' loop, a `dolist' loops. What is different is that it
-automatically shortens the list each time it loops -- it `CDRs down
-the list' on its own -- and it automatically binds the CAR of each
-shorter version of the list to the first of its arguments.
-
-In the example, the CAR of each shorter version of the list is
-referred to using the symbol `element', the list itself is called
-`list', and the value returned is called `value'. The remainder of
-the `dolist' expression is the body.
-
-The `dolist' expression binds the CAR of each shorter version of the
-list to `element' and then evaluates the body of the expression; and
-repeats the loop. The result is returned in `value'.
-
-The `dotimes' Macro
-...................
-
-The `dotimes' macro is similar to `dolist', except that it loops a
-specific number of times.
-
-The first argument to `dotimes' is assigned the numbers 0, 1, 2 and
-so forth each time around the loop, and the value of the third
-argument is returned. You need to provide the value of the second
-argument, which is how many times the macro loops.
-
-For example, the following binds the numbers from 0 up to, but not
-including, the number 3 to the first argument, 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.)
-
- (let (value) ; otherwise a value is a void variable
- (dotimes (number 3 value)
- (setq value (cons number value))))
-
- => (2 1 0)
-
-`dotimes' returns `value', so the way to use `dotimes' is to operate
-on some expression NUMBER number of times and then return the result,
-either as a list or an atom.
-
-Here is an example of a `defun' that uses `dotimes' to add up the
-number of pebbles in a triangle.
-
- (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 total)
- (setq total (+ total (1+ number))))))
-
- (triangle-using-dotimes 4)
-
-Recursion
-=========
-
-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.
-
-Building Robots: Extending the Metaphor
----------------------------------------
-
-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 `defun'
-special form, 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, as it were, 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.
-
-The Parts of a Recursive Definition
------------------------------------
-
-A recursive function typically contains a conditional expression which
-has three parts:
-
- 1. A true-or-false-test that determines whether the function is
- called again, here called the "do-again-test".
-
- 2. 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.
-
- 3. An expression that returns a different value each time the
- function is called, here called the "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 "do-again-test", to test false after the correct number of
- repetitions.
-
-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.
-
-There are several different common recursive patterns. A very simple
-pattern looks like this:
-
- (defun NAME-OF-RECURSIVE-FUNCTION (ARGUMENT-LIST)
- "DOCUMENTATION..."
- (if DO-AGAIN-TEST
- BODY...
- (NAME-OF-RECURSIVE-FUNCTION
- NEXT-STEP-EXPRESSION)))
-
-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 "stop condition", since it
-stops the repetitions when it tests false.
-
-Recursion with a List
----------------------
-
-The example of a `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 `animals' to a list.
-
-If you are using Emacs 20 or before, this example must be copied to
-the `*scratch*' buffer and each expression must be evaluated there.
-Use `C-u C-x C-e' to evaluate the `(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 `print-elements-recursively' function, before the comment.
-Otherwise, the Lisp interpreter will try to evaluate the comment.
-
-If you are using Emacs 21 or later, you can evaluate this expression
-directly in Info.
-
- (setq animals '(gazelle giraffe lion tiger))
-
- (defun print-elements-recursively (list)
- "Print each element of LIST on a line of its own.
- Uses recursion."
- (if list ; do-again-test
- (progn
- (print (car list)) ; body
- (print-elements-recursively ; recursive call
- (cdr list))))) ; next-step-expression
-
- (print-elements-recursively animals)
-
-The `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 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 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
-assemblies 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 `if' 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 CDR of the list it is invoked
-with, which (the second time around) is the CDR of the 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 invokes itself 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 `nil'. The conditional expression
-tests the value of `list'. Since the value of `list' is `nil', the
-`if' expression tests false so the then-part is not evaluated. The
-function as a whole then returns `nil'.
-
-When you evaluate `(print-elements-recursively animals)' in the
-`*scratch*' buffer, you see this result:
-
- gazelle
-
- giraffe
-
- lion
-
- tiger
- nil
-
-Recursion in Place of a Counter
--------------------------------
-
-The `triangle' function described in a previous section can also be
-written recursively. It looks like this:
-
- (defun triangle-recursively (number)
- "Return the sum of the numbers 1 through NUMBER inclusive.
- Uses recursion."
- (if (= number 1) ; do-again-test
- 1 ; then-part
- (+ number ; else-part
- (triangle-recursively ; recursive call
- (1- number))))) ; next-step-expression
-
- (triangle-recursively 7)
-
-You can install this function by evaluating it and then try it by
-evaluating `(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.
-
-An argument of 1 or 2
-.....................
-
-First, what happens if the value of the argument is 1?
-
-The function has an `if' expression after the documentation string.
-It tests whether the value of `number' is equal to 1; if so, Emacs
-evaluates the then-part of the `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 `if' expression.
-
-The else-part consists of an addition, the recursive call to
-`triangle-recursively' and a decrementing action; and it looks like
-this:
-
- (+ number (triangle-recursively (1- number)))
-
-When Emacs evaluates this expression, the innermost expression is
-evaluated first; then the other parts in sequence. Here are the steps
-in detail:
-
-Step 1 Evaluate the innermost expression.
- The innermost expression is `(1- number)' so Emacs decrements the
- value of `number' from 2 to 1.
-
-Step 2 Evaluate the `triangle-recursively' function.
- The Lisp interpreter creates an individual instance of
- `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 `triangle-recursively'
- function
-
- In this case, Emacs evaluates `triangle-recursively' with an
- argument of 1. This means that this evaluation of
- `triangle-recursively' returns 1.
-
-Step 3 Evaluate the value of `number'.
- The variable `number' is the second element of the list that
- starts with `+'; its value is 2.
-
-Step 4 Evaluate the `+' expression.
- The `+' expression receives two arguments, the first from the
- evaluation of `number' (Step 3) and the second from the
- evaluation of `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.
-
-An argument of 3 or 4
-.....................
-
-Suppose that `triangle-recursively' is called with an argument of 3.
-
-Step 1 Evaluate the do-again-test.
- The `if' expression is evaluated first. This is the do-again
- test and returns false, so the else-part of the `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.)
-
-Step 2 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.
-
-Step 3 Evaluate the `triangle-recursively' function.
- The number 2 is passed to the `triangle-recursively' function.
-
- We know what happens when Emacs evaluates `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.
-
-Step 4 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.
-
-The value returned by the function as a whole will be 6.
-
-Now that we know what will happen when `triangle-recursively' is
-called with an argument of 3, it is evident what will happen if it is
-called with an argument of 4:
-
- In the recursive call, the evaluation of
-
- (triangle-recursively (1- 4))
-
- will return the value of evaluating
-
- (triangle-recursively 3)
-
- which is 6 and this value will be added to 4 by the addition in
- the third line.
-
-The value returned by the function as a whole will be 10.
-
-Each time `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 `(triangle-recursively 7)' can calculate its answer, it must
-call `(triangle-recursively 6)'; and before `(triangle-recursively
-6)' can calculate its answer, it must call `(triangle-recursively
-5)'; and so on. That is to say, the calculation that
-`(triangle-recursively 7)' makes must be deferred until
-`(triangle-recursively 6)' makes its calculation; and
-`(triangle-recursively 6)' must defer until `(triangle-recursively
-5)' completes; and so on.
-
-If each of these instances of `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
-*Note Recursion without Deferments: No Deferment.
-
-Recursion Example Using `cond'
-------------------------------
-
-The version of `triangle-recursively' described earlier is written
-with the `if' special form. It can also be written using another
-special form called `cond'. The name of the special form `cond' is
-an abbreviation of the word `conditional'.
-
-Although the `cond' special form is not used as often in the Emacs
-Lisp sources as `if', it is used often enough to justify explaining
-it.
-
-The template for a `cond' expression looks like this:
-
- (cond
- BODY...)
-
-where the BODY is a series of lists.
-
-Written out more fully, the template looks like this:
-
- (cond
- (FIRST-TRUE-OR-FALSE-TEST FIRST-CONSEQUENT)
- (SECOND-TRUE-OR-FALSE-TEST SECOND-CONSEQUENT)
- (THIRD-TRUE-OR-FALSE-TEST THIRD-CONSEQUENT)
- ...)
-
-When the Lisp interpreter evaluates the `cond' expression, it
-evaluates the first element (the CAR or true-or-false-test) of the
-first expression in a series of expressions within the body of the
-`cond'.
-
-If the true-or-false-test returns `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 `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 `cond' expression
-returns `nil'.
-
-Written using `cond', the `triangle' function looks like this:
-
- (defun triangle-using-cond (number)
- (cond ((<= number 0) 0)
- ((= number 1) 1)
- ((> number 1)
- (+ number (triangle-using-cond (1- number))))))
-
-In this example, the `cond' returns 0 if the number is less than or
-equal to 0, it returns 1 if the number is 1 and it evaluates `(+
-number (triangle-using-cond (1- number)))' if the number is greater
-than 1.
-
-Recursive Patterns
-------------------
-
-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.
-
-Recursive Pattern: _every_
-..........................
-
-In the `every' recursive pattern, an action is performed on every
-element of a list.
-
-The basic pattern is:
-
- * If a list be empty, return `nil'.
-
- * Else, act on the beginning of the list (the CAR of the list)
- - through a recursive call by the function on the rest
- (the CDR) of the list,
-
- - and, optionally, combine the acted-on element, using
- `cons', with the results of acting on the rest.
-
-Here is example:
-
- (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
-
- (square-each '(1 2 3))
- => (1 4 9)
-
-If `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: `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 `print-elements-recursively' function (*note Recursion with a
-List: Recursion with list.) is another example of an `every' pattern,
-except in this case, rather than bring the results together using
-`cons', we print each element of output.
-
-The `print-elements-recursively' function looks like this:
-
- (setq animals '(gazelle giraffe lion tiger))
-
- (defun print-elements-recursively (list)
- "Print each element of LIST on a line of its own.
- Uses recursion."
- (if list ; do-again-test
- (progn
- (print (car list)) ; body
- (print-elements-recursively ; recursive call
- (cdr list))))) ; next-step-expression
-
- (print-elements-recursively animals)
-
-The pattern for `print-elements-recursively' is:
-
- * If the list be empty, do nothing.
-
- * But if the list has at least one element,
- - act on the beginning of the list (the CAR of the list),
-
- - and make a recursive call on the rest (the CDR) of the
- list.
-
-Recursive Pattern: _accumulate_
-...............................
-
-Another recursive pattern is called the `accumulate' pattern. In the
-`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 `every' pattern using `cons', except that
-`cons' is not used, but some other combiner.
-
-The pattern is:
-
- * If a list be empty, return zero or some other constant.
-
- * Else, act on the beginning of the list (the CAR of the list),
- - and combine that acted-on element, using `+' or
- some other combining function, with
-
- - a recursive call by the function on the rest (the CDR)
- of the list.
-
-Here is an example:
-
- (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)))))
-
- (add-elements '(1 2 3 4))
- => 10
-
-*Note Making a List of Files: Files List, for an example of the
-accumulate pattern.
-
-Recursive Pattern: _keep_
-.........................
-
-A third recursive pattern is called the `keep' pattern. In the
-`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 `every' pattern, except the element is
-skipped unless it meets a criterion.
-
-The pattern has three parts:
-
- * If a list be empty, return `nil'.
-
- * Else, if the beginning of the list (the CAR of the list) passes
- a test
- - act on that element and combine it, using `cons' with
-
- - a recursive call by the function on the rest (the CDR)
- of the list.
-
- * Otherwise, if the beginning of the list (the CAR of the list)
- fails the test
- - skip on that element,
-
- - and, recursively call the function on the rest (the
- CDR) of the list.
-
-Here is an example that uses `cond':
-
- (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)))))
-
- (keep-three-letter-words '(one two three four five six))
- => (one two six)
-
-It goes without saying that you need not use `nil' as the test for
-when to stop; and you can, of course, combine these patterns.
-
-Recursion without Deferments
-----------------------------
-
-Let's consider again what happens with the `triangle-recursively'
-function. We will find that the intermediate calculations are
-deferred until all can be done.
-
-Here is the function definition:
-
- (defun triangle-recursively (number)
- "Return the sum of the numbers 1 through NUMBER inclusive.
- Uses recursion."
- (if (= number 1) ; do-again-test
- 1 ; then-part
- (+ number ; else-part
- (triangle-recursively ; recursive call
- (1- number))))) ; next-step-expression
-
-What happens when we call this function with a argument of 7?
-
-The first instance of the `triangle-recursively' function adds the
-number 7 to the value returned by a second instance of
-`triangle-recursively', an instance that has been passed an argument
-of 6. That is to say, the first calculation is:
-
- (+ 7 (triangle-recursively 6))
-
-The first instance of `triangle-recursively'--you may want to think
-of it as a little robot--cannot complete its job. It must hand off
-the calculation for `(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 `(triangle-recursively 6)' return? It returns the
-number 6 added to the value returned by evaluating
-`triangle-recursively' with an argument of 5. Using the robot
-metaphor, it asks yet another robot to help it.
-
-Now the total is:
-
- (+ 7 6 (triangle-recursively 5))
-
-And what happens next?
-
- (+ 7 6 5 (triangle-recursively 4))
-
-Each time `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.
-
-Eventually, the full addition is set up and performed:
-
- (+ 7 6 5 4 3 2 1)
-
-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.
-
-No Deferment Solution
----------------------
-
-The solution to the problem of deferred operations is to write in a
-manner that does not defer operations(1). 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.
-
-Here are the two function definitions for adding up numbers. They are
-so simple, I find them hard to understand.
-
- (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))
-
- (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) ; sum
- (1+ counter) ; counter
- number))) ; number
-
-Install both function definitions by evaluating them, then call
-`triangle-initialization' with 2 rows:
-
- (triangle-initialization 2)
- => 3
-
-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
-`triangle-recursive-helper' invokes new instances.(2)
-
-Let's see what happens when we have a triangle that has one row.
-(This triangle will have one pebble in it!)
-
-`triangle-initialization' will call its helper with the arguments
-`0 0 1'. That function will run the conditional test whether `(>
-counter number)':
-
- (> 0 1)
-
-and find that the result is false, so it will invoke the then-part of
-the `if' clause:
-
- (triangle-recursive-helper
- (+ sum counter) ; sum plus counter => sum
- (1+ counter) ; increment counter => counter
- number) ; number stays the same
-
-which will first compute:
-
- (triangle-recursive-helper (+ 0 0) ; sum
- (1+ 0) ; counter
- 1) ; number
-which is:
-
- (triangle-recursive-helper 0 1 1)
-
-Again, `(> counter number)' will be false, so again, the Lisp
-interpreter will evaluate `triangle-recursive-helper', creating a new
-instance with new arguments.
-
-This new instance will be;
-
- (triangle-recursive-helper
- (+ sum counter) ; sum plus counter => sum
- (1+ counter) ; increment counter => counter
- number) ; number stays the same
-
-which is:
-
- (triangle-recursive-helper 1 2 1)
-
-In this case, the `(> 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 `triangle-initialization' an argument of 2, to find
-out how many pebbles there are in a triangle with two rows.
-
-That function calls `(triangle-recursive-helper 0 0 2)'.
-
-In stages, the instances called will be:
-
- sum counter number
- (triangle-recursive-helper 0 1 2)
-
- (triangle-recursive-helper 1 2 2)
-
- (triangle-recursive-helper 3 3 2)
-
-When the last instance is called, the `(> counter number)' test will
-be true, so the instance will return the value of `sum', which will
-be 3.
-
-This kind of pattern helps when you are writing functions that can use
-many resources in a computer.
-
----------- Footnotes ----------
-
-(1) The phrase "tail recursive" is used to describe such a process,
-one that uses `constant space'.
-
-(2) The jargon is mildly confusing: `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, `sum', `counter', and `number'; the procedure is
-recursive because the function `calls itself'. On the other hand,
-both the process and the procedure used by `triangle-recursively' are
-called recursive. The word `recursive' has different meanings in the
-two contexts.
-
-Looping Exercise
-================
-
- * Write a function similar to `triangle' in which each row has a
- value which is the square of the row number. Use a `while' loop.
-
- * Write a function similar to `triangle' that multiplies instead of
- adds the values.
-
- * Rewrite these two functions recursively. Rewrite these functions
- using `cond'.
-
- * Write a function for Texinfo mode that creates an index entry at
- the beginning of a paragraph for every `@dfn' within the
- paragraph. (In a Texinfo file, `@dfn' marks a definition. For
- more information, see *Note Indicating Definitions:
- (texinfo)Indicating.)
-
-Regular Expression Searches
-***************************
-
-Regular expression searches are used extensively in GNU Emacs. The
-two functions, `forward-sentence' and `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'.
-
-Regular expression searches are described in *Note Regular Expression
-Search: (emacs)Regexp Search, as well as in *Note Regular
-Expressions: (elisp)Regular Expressions. In writing this chapter, I
-am presuming that you have at least a mild acquaintance with them.
-The major point to remember is that regular expressions permit you to
-search for patterns as well as for literal strings of characters.
-For example, the code in `forward-sentence' searches for the pattern
-of possible characters that could mark the end of a sentence, and
-moves point to that spot.
-
-Before looking at the code for the `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,
-`re-search-forward'. The `forward-sentence' function is described in
-the section following. Finally, the `forward-paragraph' function is
-described in the last section of this chapter. `forward-paragraph'
-is a complex function that introduces several new features.
-
-The Regular Expression for `sentence-end'
-=========================================
-
-The symbol `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, 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:
-
- [.?!]
-
-However, we do not want `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.
-
-This group of alternatives will look like this:
-
- \\($\\| \\| \\)
- ^ ^^
- TAB SPC
-
-Here, `$' 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, `\\', 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.
-
-Also, a sentence may be followed by one or more carriage returns, like
-this:
-
- [
- ]*
-
-Like tabs and spaces, a carriage return is inserted into a regular
-expression by inserting it literally. The asterisk indicates that the
-<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:
-
- []\"')}]*
-
-In this expression, the first `]' is the first character in the
-expression; the second character is `"', which is preceded by a `\'
-to tell Emacs the `"' is _not_ special. The last three characters
-are `'', `)', and `}'.
-
-All this suggests what the regular expression pattern for matching the
-end of a sentence should be; and, indeed, if we evaluate
-`sentence-end' we find that it returns the following value:
-
- sentence-end
- => "[.?!][]\"')}]*\\($\\| \\| \\)[
- ]*"
-
-The `re-search-forward' Function
-================================
-
-The `re-search-forward' function is very like the `search-forward'
-function. (*Note The `search-forward' Function: search-forward.)
-
-`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
-`re-search-forward' to return `t' for true. (Moving point is
-therefore a `side effect'.)
-
-Like `search-forward', the `re-search-forward' function takes four
-arguments:
-
- 1. The first argument is the regular expression that the function
- searches for. The regular expression will be a string between
- quotations marks.
-
- 2. The optional second argument limits how far the function will
- search; it is a bound, which is specified as a position in the
- buffer.
-
- 3. The optional third argument specifies how the function responds
- to failure: `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 `nil' if the search fails and `t'
- if the search succeeds.
-
- 4. The optional fourth argument is the repeat count. A negative
- repeat count causes `re-search-forward' to search backwards.
-
-The template for `re-search-forward' looks like this:
-
- (re-search-forward "REGULAR-EXPRESSION"
- LIMIT-OF-SEARCH
- WHAT-TO-DO-IF-SEARCH-FAILS
- REPEAT-COUNT)
-
-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.
-
-In the `forward-sentence' function, the regular expression will be
-the value of the variable `sentence-end', namely:
-
- "[.?!][]\"')}]*\\($\\| \\| \\)[
- ]*"
-
-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 `nil'; and the repeat count will be provided by
-the argument to the `forward-sentence' function.
-
-`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 `M-e'.
-
-Complete `forward-sentence' function definition
------------------------------------------------
-
-Here is the code for `forward-sentence':
-
- (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."
- (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))))
-
-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:
-
- (defun forward-sentence (&optional arg)
- "DOCUMENTATION..."
- (interactive "p")
- (or arg (setq arg 1))
- (while (< arg 0)
- BODY-OF-WHILE-LOOP
- (while (> arg 0)
- BODY-OF-WHILE-LOOP
-
-This looks much simpler! The function definition consists of
-documentation, an `interactive' expression, an `or' expression, and
-`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 `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 `arg' will be
-bound to 1. When `forward-sentence' is called non-interactively
-without an argument, `arg' is bound to `nil'.
-
-The `or' expression handles the prefix argument. What it does is
-either leave the value of `arg' as it is, but only if `arg' is bound
-to a value; or it sets the value of `arg' to 1, in the case when
-`arg' is bound to `nil'.
-
-The `while' loops
------------------
-
-Two `while' loops follow the `or' expression. The first `while' has
-a true-or-false-test that tests true if the prefix argument for
-`forward-sentence' is a negative number. This is for going
-backwards. The body of this loop is similar to the body of the
-second `while' clause, but it is not exactly the same. We will skip
-this `while' loop and concentrate on the second `while' loop.
-
-The second `while' loop is for moving point forward. Its skeleton
-looks like this:
-
- (while (> arg 0) ; true-or-false-test
- (let VARLIST
- (if (TRUE-OR-FALSE-TEST)
- THEN-PART
- ELSE-PART
- (setq arg (1- arg)))) ; `while' loop decrementer
-
-The `while' loop is of the decrementing kind. (*Note A Loop with a
-Decrementing Counter: Decrementing Loop.) It has a
-true-or-false-test that tests true so long as the counter (in this
-case, the variable `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 `forward-sentence', which is the
-most common way the command is used, this `while' loop will run once,
-since the value of `arg' will be 1.
-
-The body of the `while' loop consists of a `let' expression, which
-creates and binds a local variable, and has, as its body, an `if'
-expression.
-
-The body of the `while' loop looks like this:
-
- (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)))
-
-The `let' expression creates and binds the local variable `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 `par-end' is bound to the value of the
-end of the paragraph. What happens is that the `let' sets the value
-of `par-end' to the value returned when the Lisp interpreter
-evaluates the expression
-
- (save-excursion (end-of-paragraph-text) (point))
-
-In this expression, `(end-of-paragraph-text)' moves point to the end
-of the paragraph, `(point)' returns the value of point, and then
-`save-excursion' restores point to its original position. Thus, the
-`let' binds `par-end' to the value returned by the `save-excursion'
-expression, which is the position of the end of the paragraph. (The
-`(end-of-paragraph-text)' function uses `forward-paragraph', which we
-will discuss shortly.)
-
-Emacs next evaluates the body of the `let', which is an `if'
-expression that looks like this:
-
- (if (re-search-forward sentence-end par-end t) ; if-part
- (skip-chars-backward " \t\n") ; then-part
- (goto-char par-end))) ; else-part
-
-The `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 `if'
-expression is the regular expression search.
-
-It may seem odd to have what looks like the `real work' of the
-`forward-sentence' function buried here, but this is a common way
-this kind of operation is carried out in Lisp.
-
-The regular expression search
------------------------------
-
-The `re-search-forward' function searches for the end of the
-sentence, that is, for the pattern defined by the `sentence-end'
-regular expression. If the pattern is found--if the end of the
-sentence is found--then the `re-search-forward' function does two
-things:
-
- 1. The `re-search-forward' function carries out a side effect, which
- is to move point to the end of the occurrence found.
-
- 2. The `re-search-forward' function returns a value of true. This
- is the value received by the `if', and means that the search was
- successful.
-
-The side effect, the movement of point, is completed before the `if'
-function is handed the value returned by the successful conclusion of
-the search.
-
-When the `if' function receives the value of true from a successful
-call to `re-search-forward', the `if' evaluates the then-part, which
-is the expression `(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 `re-search-forward' function fails to find
-a pattern marking the end of the sentence, the function returns
-false. The false then causes the `if' to evaluate its third
-argument, which is `(goto-char par-end)': it moves point to the end
-of the paragraph.
-
-Regular expression searches are exceptionally useful and the pattern
-illustrated by `re-search-forward', in which the search is the test
-of an `if' expression, is handy. You will see or write code
-incorporating this pattern often.
-
-`forward-paragraph': a Goldmine of Functions
-============================================
-
-The `forward-paragraph' function moves point forward to the end of
-the paragraph. It is usually bound to `M-}' and makes use of a
-number of functions that are important in themselves, including
-`let*', `match-beginning', and `looking-at'.
-
-The function definition for `forward-paragraph' is considerably
-longer than the function definition for `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 `;;;
-'. In Text mode, four blank spaces make up another common fill
-prefix, creating an indented paragraph. (*Note Fill Prefix:
-(emacs)Fill Prefix, 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 `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.
-
-Shortened `forward-paragraph' function definition
--------------------------------------------------
-
-Rather than print all of the `forward-paragraph' function, we will
-only print parts of it. Read without preparation, the function can
-be daunting!
-
-In outline, the function looks like this:
-
- (defun forward-paragraph (&optional arg)
- "DOCUMENTATION..."
- (interactive "p")
- (or arg (setq arg 1))
- (let*
- VARLIST
- (while (< arg 0) ; backward-moving-code
- ...
- (setq arg (1+ arg)))
- (while (> arg 0) ; forward-moving-code
- ...
- (setq arg (1- arg)))))
-
-The first parts of the function are routine: the function's argument
-list consists of one optional argument. Documentation follows.
-
-The lower case `p' in the `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 `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. (*Note The `forward-sentence'
-function: forward-sentence.) Now we reach the end of the familiar
-part of this function.
-
-The `let*' expression
----------------------
-
-The next line of the `forward-paragraph' function begins a `let*'
-expression. This is a different kind of expression than we have seen
-so far. The symbol is `let*' not `let'.
-
-The `let*' special form is like `let' except that Emacs sets each
-variable in sequence, one after another, and variables in the latter
-part of the varlist can make use of the values to which Emacs set
-variables in the earlier part of the varlist.
-
-In the `let*' expression in this function, Emacs binds two variables:
-`fill-prefix-regexp' and `paragraph-separate'. The value to which
-`paragraph-separate' is bound depends on the value of
-`fill-prefix-regexp'.
-
-Let's look at each in turn. The symbol `fill-prefix-regexp' is set
-to the value returned by evaluating the following list:
-
- (and fill-prefix
- (not (equal fill-prefix ""))
- (not paragraph-ignore-fill-prefix)
- (regexp-quote fill-prefix))
-
-This is an expression whose first element is the `and' special form.
-
-As we learned earlier (*note The `kill-new' function: kill-new
-function.), the `and' special form evaluates each of its arguments
-until one of the arguments returns a value of `nil', in which case
-the `and' expression returns `nil'; however, if none of the arguments
-returns a value of `nil', the value resulting from evaluating the
-last argument is returned. (Since such a value is not `nil', it is
-considered true in Lisp.) In other words, an `and' expression
-returns a true value only if all its arguments are true.
-
-In this case, the variable `fill-prefix-regexp' is bound to a
-non-`nil' value only if the following four expressions produce a true
-(i.e., a non-`nil') value when they are evaluated; otherwise,
-`fill-prefix-regexp' is bound to `nil'.
-
-`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 `nil'.
-
-`(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.
-
-`(not paragraph-ignore-fill-prefix)'
- This expression returns `nil' if the variable
- `paragraph-ignore-fill-prefix' has been turned on by being set
- to a true value such as `t'.
-
-`(regexp-quote fill-prefix)'
- This is the last argument to the `and' special form. If all the
- arguments to the `and' are true, the value resulting from
- evaluating this expression will be returned by the `and'
- expression and bound to the variable `fill-prefix-regexp',
-
-The result of evaluating this `and' expression successfully is that
-`fill-prefix-regexp' will be bound to the value of `fill-prefix' as
-modified by the `regexp-quote' function. What `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
-`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 `nil'.
-
-The second local variable in the `let*' expression is
-`paragraph-separate'. It is bound to the value returned by
-evaluating the expression:
-
- (if fill-prefix-regexp
- (concat paragraph-separate
- "\\|^" fill-prefix-regexp "[ \t]*$")
- paragraph-separate)))
-
-This expression shows why `let*' rather than `let' was used. The
-true-or-false-test for the `if' depends on whether the variable
-`fill-prefix-regexp' evaluates to `nil' or some other value.
-
-If `fill-prefix-regexp' does not have a value, Emacs evaluates the
-else-part of the `if' expression and binds `paragraph-separate' to
-its local value. (`paragraph-separate' is a regular expression that
-matches what separates paragraphs.)
-
-But if `fill-prefix-regexp' does have a value, Emacs evaluates the
-then-part of the `if' expression and binds `paragraph-separate' to a
-regular expression that includes the `fill-prefix-regexp' as part of
-the pattern.
-
-Specifically, `paragraph-separate' is set to the original value of
-the paragraph separate regular expression concatenated with an
-alternative expression that consists of the `fill-prefix-regexp'
-followed by a blank line. The `^' indicates that the
-`fill-prefix-regexp' must begin a line, and the optional whitespace
-to the end of the line is defined by `"[ \t]*$"'.) The `\\|' defines
-this portion of the regexp as an alternative to `paragraph-separate'.
-
-Now we get into the body of the `let*'. The first part of the body
-of the `let*' deals with the case when the function is given a
-negative argument and is therefore moving backwards. We will skip
-this section.
-
-The forward motion `while' loop
--------------------------------
-
-The second part of the body of the `let*' deals with forward motion.
-It is a `while' loop that repeats itself so long as the value of
-`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 `while' loop is
-evaluated exactly once, and the cursor moves forward one paragraph.
-
-This part handles three situations: when point is between paragraphs,
-when point is within a paragraph and there is a fill prefix, and when
-point is within a paragraph and there is no fill prefix.
-
-The `while' loop looks like this:
-
- (while (> arg 0)
- (beginning-of-line)
-
- ;; between paragraphs
- (while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
-
- ;; within paragraphs, with a fill prefix
- (if fill-prefix-regexp
- ;; There is a fill prefix; it overrides paragraph-start.
- (while (and (not (eobp))
- (not (looking-at paragraph-separate))
- (looking-at fill-prefix-regexp))
- (forward-line 1))
-
- ;; within paragraphs, no fill prefix
- (if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max))))
-
- (setq arg (1- arg)))
-
-We can see immediately that this is a decrementing counter `while'
-loop, using the expression `(setq arg (1- arg))' as the decrementer.
-
-The body of the loop consists of three expressions:
-
- ;; between paragraphs
- (beginning-of-line)
- (while
- BODY-OF-WHILE)
-
- ;; within paragraphs, with fill prefix
- (if TRUE-OR-FALSE-TEST
- THEN-PART
-
- ;; within paragraphs, no fill prefix
- ELSE-PART
-
-When the Emacs Lisp interpreter evaluates the body of the `while'
-loop, the first thing it does is evaluate the `(beginning-of-line)'
-expression and move point to the beginning of the line. Then there
-is an inner `while' loop. This `while' loop is designed to move the
-cursor out of the blank space between paragraphs, if it should happen
-to be there. Finally, there is an `if' expression that actually
-moves point to the end of the paragraph.
-
-Between paragraphs
-------------------
-
-First, let us look at the inner `while' loop. This loop handles the
-case when point is between paragraphs; it uses three functions that
-are new to us: `prog1', `eobp' and `looking-at'.
-
- * `prog1' is similar to the `progn' special form, except that
- `prog1' evaluates its arguments in sequence and then returns the
- value of its first argument as the value of the whole
- expression. (`progn' returns the value of its last argument as
- the value of the expression.) The second and subsequent
- arguments to `prog1' are evaluated only for their side effects.
-
- * `eobp' is an abbreviation of `End Of Buffer P' and is a function
- that returns true if point is at the end of the buffer.
-
- * `looking-at' is a function that returns true if the text
- following point matches the regular expression passed
- `looking-at' as its argument.
-
-The `while' loop we are studying looks like this:
-
- (while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
-
-This is a `while' loop with no body! The true-or-false-test of the
-loop is the expression:
-
- (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1))
-
-The first argument to the `prog1' is the `and' expression. It has
-within in it a test of whether point is at the end of the buffer and
-also a test of whether the pattern following point matches the regular
-expression for separating paragraphs.
-
-If the cursor is not at the end of the buffer and if the characters
-following the cursor mark the separation between two paragraphs, then
-the `and' expression is true. After evaluating the `and' expression,
-the Lisp interpreter evaluates the second argument to `prog1', which
-is `forward-line'. This moves point forward one line. The value
-returned by the `prog1' however, is the value of its first argument,
-so the `while' loop continues so long as point is not at the end of
-the buffer and is between paragraphs. When, finally, point is moved
-to a paragraph, the `and' expression tests false. Note however, that
-the `forward-line' command is carried out anyhow. This means that
-when point is moved from between paragraphs to a paragraph, it is left
-at the beginning of the second line of the paragraph.
-
-Within paragraphs
------------------
-
-The next expression in the outer `while' loop is an `if' expression.
-The Lisp interpreter evaluates the then-part of the `if' when the
-`fill-prefix-regexp' variable has a value other than `nil', and it
-evaluates the else-part when the value of `if fill-prefix-regexp' is
-`nil', that is, when there is no fill prefix.
-
-No fill prefix
---------------
-
-It is simplest to look at the code for the case when there is no fill
-prefix first. This code consists of yet another inner `if'
-expression, and reads as follows:
-
- (if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max)))
-
-This expression actually does the work that most people think of as
-the primary purpose of the `forward-paragraph' command: it causes a
-regular expression search to occur that searches forward to the start
-of the next paragraph and if it is found, moves point there; but if
-the start of another paragraph if not found, it moves point to the
-end of the accessible region of the buffer.
-
-The only unfamiliar part of this is the use of `match-beginning'.
-This is another function that is new to us. The `match-beginning'
-function returns a number specifying the location of the start of the
-text that was matched by the last regular expression search.
-
-The `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, will move point to the end of the text that is found. In this
-case, a successful search will move point to the end of the pattern
-for `paragraph-start', which will be the beginning of the next
-paragraph rather than the end of the current one.
-
-However, we want to put point at the end of the current paragraph,
-not at the beginning of the next one. The two positions may be
-different, because there may be several blank lines between
-paragraphs.
-
-When given an argument of 0, `match-beginning' returns the position
-that is the start of the text that the most recent regular expression
-search matched. In this case, the most recent regular expression
-search is the one looking for `paragraph-start', so `match-beginning'
-returns the beginning position of the pattern, rather than the end of
-the pattern. The beginning position is the end of the paragraph.
-
-(Incidentally, when passed a positive number as an argument, the
-`match-beginning' function will place point at that parenthesized
-expression in the last regular expression. It is a useful function.)
-
-With a fill prefix
-------------------
-
-The inner `if' expression just discussed is the else-part of an
-enclosing `if' expression which tests whether there is a fill prefix.
-If there is a fill prefix, the then-part of this `if' is evaluated.
-It looks like this:
-
- (while (and (not (eobp))
- (not (looking-at paragraph-separate))
- (looking-at fill-prefix-regexp))
- (forward-line 1))
-
-What this expression does is move point forward line by line so long
-as three conditions are true:
-
- 1. Point is not at the end of the buffer.
-
- 2. The text following point does not separate paragraphs.
-
- 3. The pattern following point is the fill prefix regular
- expression.
-
-The last condition may be puzzling, until you remember that point was
-moved to the beginning of the line early in the `forward-paragraph'
-function. This means that if the text has a fill prefix, the
-`looking-at' function will see it.
-
-Summary
--------
-
-In summary, when moving forward, the `forward-paragraph' function
-does the following:
-
- * Move point to the beginning of the line.
-
- * Skip over lines between paragraphs.
-
- * Check whether there is a fill prefix, and if there is:
-
- -- Go forward line by line so long as the line is not a
- paragraph separating line.
-
- * But if there is no fill prefix,
-
- -- Search for the next paragraph start pattern.
-
- -- Go to the beginning of the paragraph start pattern, which
- will be the end of the previous paragraph.
-
- -- Or else go to the end of the accessible portion of the
- buffer.
-
-For review, here is the code we have just been discussing, formatted
-for clarity:
-
- (interactive "p")
- (or arg (setq arg 1))
- (let* (
- (fill-prefix-regexp
- (and fill-prefix (not (equal fill-prefix ""))
- (not paragraph-ignore-fill-prefix)
- (regexp-quote fill-prefix)))
-
- (paragraph-separate
- (if fill-prefix-regexp
- (concat paragraph-separate
- "\\|^"
- fill-prefix-regexp
- "[ \t]*$")
- paragraph-separate)))
-
- OMITTED-BACKWARD-MOVING-CODE ...
-
- (while (> arg 0) ; forward-moving-code
- (beginning-of-line)
-
- (while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
-
- (if fill-prefix-regexp
- (while (and (not (eobp)) ; then-part
- (not (looking-at paragraph-separate))
- (looking-at fill-prefix-regexp))
- (forward-line 1))
- ; else-part: the inner-if
- (if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max))))
-
- (setq arg (1- arg))))) ; decrementer
-
-The full definition for the `forward-paragraph' function not only
-includes this 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 `C-h f' (`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 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!)
-
-Or - a good habit to get into - you can type `M-.' (`find-tag') and
-the name of the function when prompted for it. This will take you
-directly to the source. If the `find-tag' function first asks you
-for the name of a `TAGS' table, give it the name of the `TAGS' file
-such as `/usr/local/share/emacs/21.0.100/lisp/TAGS'. (The exact path
-to your `TAGS' file depends on how your copy of Emacs was installed.)
-
-You can also create your own `TAGS' file for directories that lack
-one. *Note Create Your Own `TAGS' File: etags.
-
-Create Your Own `TAGS' File
-===========================
-
-The `M-.' (`find-tag') command takes you directly to the source for a
-function, variable, node, or other source. The function depends on
-tags tables to tell it where to go.
-
-You often need to build and install tags tables yourself. They are
-not built automatically. A tags table is called a `TAGS' file; the
-name is in upper case letters.
-
-You can create a `TAGS' file by calling the `etags' program that
-comes as a part of the Emacs distribution. Usually, `etags' is
-compiled and installed when Emacs is built. (`etags' is not an Emacs
-Lisp function or a part of Emacs; it is a C program.)
-
-To create a `TAGS' file, first switch to the directory in which you
-want to create the file. In Emacs you can do this with the `M-x cd'
-command, or by visiting a file in the directory, or by listing the
-directory with `C-x d' (`dired'). Then run the compile command, with
-`etags *.el' as the command to execute
-
- M-x compile RET etags *.el RET
-
-to create a `TAGS' file.
-
-For example, if you have a large number of files in your `~/emacs'
-directory, as I do--I have 137 `.el' files in it, of which I load
-12--you can create a `TAGS' file for the Emacs Lisp files in that
-directory.
-
-The `etags' program takes all the usual shell `wildcards'. For
-example, if you have two directories for which you want a single
-`TAGS file', type `etags *.el ../elisp/*.el', where `../elisp/' is
-the second directory:
-
- M-x compile RET etags *.el ../elisp/*.el RET
-
-Type
-
- M-x compile RET etags --help RET
-
-to see a list of the options accepted by `etags' as well as a list of
-supported languages.
-
-The `etags' program handles more than 20 languages, including Emacs
-Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, Java, LaTeX, Pascal,
-Perl, Python, Texinfo, makefiles, and most assemblers. The program
-has no switches for specifying the language; it recognizes the
-language in an input file according to its file name and contents.
-
-`etags' is very helpful when you are writing code yourself and want
-to refer back to functions you have already written. Just run
-`etags' again at intervals as you write new functions, so they become
-part of the `TAGS' file.
-
-If you think an appropriate `TAGS' file already exists for what you
-want, but do not know where it is, you can use the `locate' program
-to attempt to find it.
-
-Type `M-x locate RET TAGS RET' and Emacs will list for you the full
-path names of all your `TAGS' files. On my system, this command
-lists 34 `TAGS' files. On the other hand, a `plain vanilla' system I
-recently installed did not contain any `TAGS' files.
-
-If the tags table you want has been created, you can use the `M-x
-visit-tags-table' command to specify it. Otherwise, you will need to
-create the tag table yourself and then use `M-x visit-tags-table'.
-
-Building Tags in the Emacs sources
-..................................
-
-The GNU Emacs sources come with a `Makefile' that contains a
-sophisticated `etags' command that creates, collects, and merges tags
-tables from all over the Emacs sources and puts the information into
-one `TAGS' file in the `src/' directory below the top level of your
-Emacs source directory.
-
-To build this `TAGS' file, go to the top level of your Emacs source
-directory and run the compile command `make tags':
-
- M-x compile RET make tags RET
-
-(The `make tags' command works well with the GNU Emacs sources, as
-well as with some other source packages.)
-
-For more information, see *Note Tag Tables: (emacs)Tags.
-
-Review
-======
-
-Here is a brief summary of some recently introduced functions.
-
-`while'
- Repeatedly evaluate the body of the expression so long as the
- first element of the body tests true. Then return `nil'. (The
- expression is evaluated only for its side effects.)
-
- For example:
-
- (let ((foo 2))
- (while (> foo 0)
- (insert (format "foo is %d.\n" foo))
- (setq foo (1- foo))))
-
- => foo is 2.
- foo is 1.
- nil
-
- (The `insert' function inserts its arguments at point; the
- `format' function returns a string formatted from its arguments
- the way `message' formats its arguments; `\n' produces a new
- line.)
-
-`re-search-forward'
- Search for a pattern, and if the pattern is found, move point to
- rest just after it.
-
- Takes four arguments, like `search-forward':
-
- 1. A regular expression that specifies the pattern to search
- for.
-
- 2. Optionally, the limit of the search.
-
- 3. Optionally, what to do if the search fails, return `nil' or
- an error message.
-
- 4. Optionally, how many times to repeat the search; if
- negative, the search goes backwards.
-
-`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.
-
- For example:
-
- (let* ((foo 7)
- (bar (* 3 foo)))
- (message "`bar' is %d." bar))
- => `bar' is 21.
-
-`match-beginning'
- Return the position of the start of the text found by the last
- regular expression search.
-
-`looking-at'
- Return `t' for true if the text after point matches the argument,
- which should be a regular expression.
-
-`eobp'
- Return `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.
-
-`prog1'
- Evaluate each argument in sequence and then return the value of
- the _first_.
-
- For example:
-
- (prog1 1 2 3 4)
- => 1
-
-Exercises with `re-search-forward'
-==================================
-
- * Write a function to search for a regular expression that matches
- two or more blank lines in sequence.
-
- * Write a function to search for duplicated words, such as `the
- the'. *Note Syntax of Regular Expressions: (emacs)Regexps, 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. *Note `the-the' Duplicated Words Function: the-the.
-
-Counting: Repetition and Regexps
-********************************
-
-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 `while' loops and recursion.
-
-Counting words
-==============
-
-The standard Emacs distribution contains a function for counting the
-number of lines within a region. However, there is no corresponding
-function for counting words.
-
-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 to me
-that Emacs lacks a word count command. Perhaps people use Emacs
-mostly for code or types of documentation that do not require word
-counts; or perhaps they restrict themselves to the operating system
-word count command, `wc'. Alternatively, people may follow the
-publishers' convention and compute a word count by dividing the
-number of characters in a document by five. In any event, here are
-commands to count words.
-
-The `count-words-region' Function
-=================================
-
-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 `count-words-region' command, you can, if
-you wish, count words in a whole buffer by marking it with `C-x h'
-(`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 `while' loop.
-
-Designing `count-words-region'
-------------------------------
-
-First, we will implement the word count command with a `while' loop,
-then with recursion. The command will, of course, be interactive.
-
-The template for an interactive function definition is, as always:
-
- (defun NAME-OF-FUNCTION (ARGUMENT-LIST)
- "DOCUMENTATION..."
- (INTERACTIVE-EXPRESSION...)
- BODY...)
-
-What we need to do is fill in the slots.
-
-The name of the function should be self-explanatory and similar to the
-existing `count-lines-region' name. This makes the name easier to
-remember. `count-words-region' is a good choice.
-
-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 `beginning' and `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 `apropos'. The
-interactive expression will be of the form `(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 `while' loop can count
-words, second, to run the `while' loop, and third, to send a message
-to the user.
-
-When a user calls `count-words-region', 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 `(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 `save-excursion' expression.
-
-The central part of the body of the function consists of a `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
-`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 `(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:
-
- \w+\W*
-
-The buffer's syntax table determines which characters are and are not
-word constituents. (*Note What Constitutes a Word or Symbol?:
-Syntax, for more about syntax. Also, see *Note Syntax:
-(emacs)Syntax, and *Note Syntax Tables: (elisp)Syntax Tables.)
-
-The search expression looks like this:
-
- (re-search-forward "\\w+\\W*")
-
-(Note that paired backslashes precede the `w' and `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, `\n', stand for `newline',
-rather than for a backslash followed by `n'. Two backslashes in a
-row stand for an ordinary, `unspecial' backslash.)
-
-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 `while' loop. The incrementing expression is simply:
-
- (setq count (1+ count))
-
-Finally, we want to tell the user how many words there are in the
-region. The `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 `cond' special
-form is appropriate.
-
-All this leads to the following function definition:
-
- ;;; First version; has bugs!
- (defun count-words-region (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 ... ")
-
- ;;; 1. Set up appropriate conditions.
- (save-excursion
- (goto-char beginning)
- (let ((count 0))
-
- ;;; 2. Run the while loop.
- (while (< (point) end)
- (re-search-forward "\\w+\\W*")
- (setq count (1+ count)))
-
- ;;; 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))))))
-
-As written, the function works, but not in all circumstances.
-
-The Whitespace Bug in `count-words-region'
-------------------------------------------
-
-The `count-words-region' 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 `count-words-region' 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:
-
- Search failed: "\\w+\\W*"
-
-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. Here
-is a copy of the definition. Place your cursor after the closing
-parenthesis and type `C-x C-e' to install it.
-
- ;; First version; has bugs!
- (defun count-words-region (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 ... ")
-
- ;;; 1. Set up appropriate conditions.
- (save-excursion
- (goto-char beginning)
- (let ((count 0))
-
- ;;; 2. Run the while loop.
- (while (< (point) end)
- (re-search-forward "\\w+\\W*")
- (setq count (1+ count)))
-
- ;;; 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))))))
-
-If you wish, you can also install this keybinding by evaluating it:
-
- (global-set-key "\C-c=" 'count-words-region)
-
-To conduct the first test, set mark and point to the beginning and end
-of the following line and then type `C-c =' (or `M-x
-count-words-region' if you have not bound `C-c ='):
-
- one two three
-
-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 _before_ the word `one'. Again type the command `C-c ='
-(or `M-x count-words-region'). 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
-`*scratch*' buffer and then type several spaces at the end of the
-line. Place mark right after the word `three' and point at the end
-of line. (The end of the line will be the end of the buffer.) Type
-`C-c =' (or `M-x count-words-region') 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 `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 `M-x count-words-region' command
-moves point to the beginning of the region. The `while' tests
-whether the value of point is smaller than the value of `end', which
-it is. Consequently, the regular expression search looks for and
-finds the first word. It leaves point after the word. `count' is
-set to one. The `while' loop repeats; but this time the value of
-point is larger than the value of `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 `Search failed'. What happens is
-that the true-or-false-test in the `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 `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
-`t', causes the function to return `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 `C-h f',
-the name of the function, and then <RET>.)
-
-In the `count-words-region' definition, the value of the end of the
-region is held by the variable `end' which is passed as an argument
-to the function. Thus, we can add `end' as an argument to the
-regular expression search expression:
-
- (re-search-forward "\\w+\\W*" end)
-
-However, if you make only this change to the `count-words-region'
-definition and then test the new version of the definition on a
-stretch of whitespace, you will receive an error message saying
-`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 that "The region does NOT have any words."
-
-The solution to this problem is to provide `re-search-forward' with a
-third argument of `t', which causes the function to return `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 ... you will keep on seeing that
-message ..., until you type `C-g' (`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 `re-search-forward'
-expression returns `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 `re-search-forward' expression returns
-`nil', the next expression in the `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 `re-search-forward' expression did
-not move point. ... and the cycle repeats ...
-
-The `count-words-region' definition requires yet another
-modification, to cause the true-or-false-test of the `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 `and' special form and embedded in
-the `while' loop as the true-or-false-test, like this:
-
- (and (< (point) end) (re-search-forward "\\w+\\W*" end t))
-
-(*Note forward-paragraph::, for information about `and'.)
-
-The `re-search-forward' expression returns `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 `while' loop exists, and the
-`count-words-region' function displays one or other of its messages.
-
-After incorporating these final changes, the `count-words-region'
-works without bugs (or at least, without bugs that I have found!).
-Here is what it looks like:
-
- ;;; Final version: `while'
- (defun count-words-region (beginning end)
- "Print number of words in the region."
- (interactive "r")
- (message "Counting words in region ... ")
-
- ;;; 1. Set up appropriate conditions.
- (save-excursion
- (let ((count 0))
- (goto-char beginning)
-
- ;;; 2. Run the while loop.
- (while (and (< (point) end)
- (re-search-forward "\\w+\\W*" end t))
- (setq count (1+ count)))
-
- ;;; 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))))))
-
-Count Words Recursively
-=======================
-
-You can write the function for counting words recursively as well as
-with a `while' loop. Let's see how this is done.
-
-First, we need to recognize that the `count-words-region' 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 `count-words-region'.
-
-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 `recursive-count-words' to determine how
-many words are in the region.
-
-We can readily construct a template for this function, based on our
-previous versions:
-
- ;; Recursive version; uses regular expression search
- (defun count-words-region (beginning end)
- "DOCUMENTATION..."
- (INTERACTIVE-EXPRESSION...)
-
- ;;; 1. Set up appropriate conditions.
- (EXPLANATORY MESSAGE)
- (SET-UP FUNCTIONS...
-
- ;;; 2. Count the words.
- RECURSIVE CALL
-
- ;;; 3. Send a message to the user.
- MESSAGE PROVIDING WORD COUNT))
-
-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 `let' expression: we can bind a variable in
-the varlist of a `let' expression to the number of words in the
-region, as returned by the recursive call; and then the `cond'
-expression, using binding, can display the value to the user.
-
-Often, one thinks of the binding within a `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 `let' expression.
-
-Using `let', the function definition looks like this:
-
- (defun count-words-region (beginning end)
- "Print number of words in the region."
- (interactive "r")
-
- ;;; 1. Set up appropriate conditions.
- (message "Counting words in region ... ")
- (save-excursion
- (goto-char beginning)
-
- ;;; 2. Count the words.
- (let ((count (recursive-count-words end)))
-
- ;;; 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))))))
-
-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
-`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, also, we also need a part that does the `work' of the
-function, a part that does the counting. A vital part!
-
-But already, we have an outline of the recursive counting function:
-
- (defun recursive-count-words (region-end)
- "DOCUMENTATION..."
- DO-AGAIN-TEST
- NEXT-STEP-EXPRESSION
- RECURSIVE CALL)
-
-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.
-
-Thus, the do-again-test should look like this:
-
- (and (< (point) region-end)
- (re-search-forward "\\w+\\W*" region-end t))
-
-Note that the search expression is part of the do-again-test--the
-function returns `t' if its search succeeds and `nil' if it fails.
-(*Note The Whitespace Bug in `count-words-region': Whitespace Bug,
-for an explanation of how `re-search-forward' works.)
-
-The do-again-test is the true-or-false test of an `if' clause.
-Clearly, if the do-again-test succeeds, the then-part of the `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 `t' or `nil' for the do-again-test,
-`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
-`re-search-forward' expression is the next-step-expression.
-
-In outline, then, the body of the `recursive-count-words' function
-looks like this:
-
- (if DO-AGAIN-TEST-AND-NEXT-STEP-COMBINED
- ;; then
- RECURSIVE-CALL-RETURNING-COUNT
- ;; else
- RETURN-ZERO)
-
-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 `recursive-count-words'.
-
-Consider several cases:
-
- * 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.
-
- * 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.
-
- * If there are no words in the region, the function should return
- zero.
-
-From the sketch we can see that the else-part of the `if' returns
-zero for the case of no words. This means that the then-part of the
-`if' must return a value resulting from adding one to the value
-returned from a count of the remaining words.
-
-The expression will look like this, where `1+' is a function that
-adds one to its argument.
-
- (1+ (recursive-count-words region-end))
-
-The whole `recursive-count-words' function will then look like this:
-
- (defun recursive-count-words (region-end)
- "DOCUMENTATION..."
-
- ;;; 1. do-again-test
- (if (and (< (point) region-end)
- (re-search-forward "\\w+\\W*" region-end t))
-
- ;;; 2. then-part: the recursive call
- (1+ (recursive-count-words region-end))
-
- ;;; 3. else-part
- 0))
-
-Let's examine how this works:
-
-If there are no words in the region, the else part of the `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 `region-end' and the search succeeds. In this case, the
-true-or-false-test of the `if' expression tests true, and the
-then-part of the `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 `(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,
-`recursive-count-words' will return zero. The zero will be added to
-one, and the original evaluation of `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
-`recursive-count-words' returns one added to the value returned by
-calling `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
-`recursive-count-words' returns one added to the value returned by
-calling `recursive-count-words' on a region containing the remaining
-two words--and so on and so on.
-
-With full documentation the two functions look like this:
-
-The recursive function:
-
- (defun recursive-count-words (region-end)
- "Number of words between point and REGION-END."
-
- ;;; 1. do-again-test
- (if (and (< (point) region-end)
- (re-search-forward "\\w+\\W*" region-end t))
-
- ;;; 2. then-part: the recursive call
- (1+ (recursive-count-words region-end))
-
- ;;; 3. else-part
- 0))
-
-The wrapper:
-
- ;;; Recursive version
- (defun count-words-region (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 ... ")
- (save-excursion
- (goto-char beginning)
- (let ((count (recursive-count-words end)))
- (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))))))
-
-Exercise: Counting Punctuation
-==============================
-
-Using a `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.
-
-Counting Words in a `defun'
-***************************
-
-Our next project is to count the number of words in a function
-definition. Clearly, this can be done using some variant of
-`count-word-region'. *Note Counting Words: Repetition and Regexps:
-Counting Words. If we are just going to count the words in one
-definition, it is easy enough to mark the definition with the `C-M-h'
-(`mark-defun') command, and then call `count-word-region'.
-
-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.
-
-Divide and Conquer
-==================
-
-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:
-
- * First, write a function to count the words in one definition.
- This includes the problem of handling symbols as well as words.
-
- * Second, write a function to list the numbers of words in each
- function in a file. This function can use the
- `count-words-in-defun' function.
-
- * Third, write a function to list the numbers 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.
-
- * 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.
-
- * Fifth, write a function to print the results as a graph.
-
-This is quite a project! But if we take each step slowly, it will not
-be difficult.
-
-What to Count?
-==============
-
-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 `multiply-by-seven' function
-contains the five symbols `defun', `multiply-by-seven', `number',
-`*', and `7'. In addition, in the documentation string, it contains
-the four words `Multiply', `NUMBER', `by', and `seven'. The symbol
-`number' is repeated, so the definition contains a total of ten words
-and symbols.
-
- (defun multiply-by-seven (number)
- "Multiply NUMBER by seven."
- (* 7 number))
-
-However, if we mark the `multiply-by-seven' definition with `C-M-h'
-(`mark-defun'), and then call `count-words-region' on it, we will
-find that `count-words-region' claims the definition has eleven
-words, not ten! Something is wrong!
-
-The problem is twofold: `count-words-region' does not count the `*'
-as a word, and it counts the single symbol, `multiply-by-seven', as
-containing three words. The hyphens are treated as if they were
-interword spaces rather than intraword connectors:
-`multiply-by-seven' is counted as if it were written `multiply by
-seven'.
-
-The cause of this confusion is the regular expression search within
-the `count-words-region' definition that moves point forward word by
-word. In the canonical version of `count-words-region', the regexp
-is:
-
- "\\w+\\W*"
-
-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.
-
-What Constitutes a Word or Symbol?
-==================================
-
-Emacs treats different characters as belonging to different "syntax
-categories". For example, the regular expression, `\\w+', is a
-pattern specifying one or more _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, see *Note Syntax: (emacs)Syntax, and *Note Syntax
-Tables: (elisp)Syntax Tables.)
-
-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
-`count-words-region' function treats it in the same way it treats an
-interword white space, which is why `count-words-region' counts
-`multiply-by-seven' as three words.
-
-There are two ways to cause Emacs to count `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 regular expression used in the
-`count-words' definition so as to include symbols. This procedure
-has the merit of clarity, but the task is a little tricky.
-
-The first part is simple enough: the pattern must match "at least one
-character that is a word or symbol constituent". Thus:
-
- "\\(\\w\\|\\s_\\)+"
-
-The `\\(' is the first part of the grouping construct that includes
-the `\\w' and the `\\s_' as alternatives, separated by the `\\|'.
-The `\\w' matches any word-constituent character and the `\\s_'
-matches any character that is part of a symbol name but not a
-word-constituent character. The `+' 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:
-
- "\\(\\W\\|\\S_\\)*"
-
-The upper case `W' and `S' match characters that are _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.
-
-Here is the full regular expression:
-
- "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
-
-The `count-words-in-defun' Function
-===================================
-
-We have seen that there are several ways to write a
-`count-word-region' function. To write a `count-words-in-defun', we
-need merely adapt one of these versions.
-
-The version that uses a `while' loop is easy to understand, so I am
-going to adapt that. Because `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, `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.
-
-These considerations lead us to prepare the following template:
-
- (defun count-words-in-defun ()
- "DOCUMENTATION..."
- (SET UP...
- (WHILE LOOP...)
- RETURN COUNT)
-
-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 `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 `beginning-of-defun' function searches backwards for an opening
-delimiter such as a `(' 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 `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 `beginning-of-defun' to place
-point where we wish to start.
-
-The `while' loop requires a counter to keep track of the words or
-symbols being counted. A `let' expression can be used to create a
-local variable for this purpose, and bind it to an initial value of
-zero.
-
-The `end-of-defun' function works like `beginning-of-defun' except
-that it moves point to the end of the definition. `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 `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 `while' loop will know when to stop
-looping.
-
-The code looks like this:
-
- (beginning-of-defun)
- (let ((count 0)
- (end (save-excursion (end-of-defun) (point))))
-
-The code is simple. The only slight complication is likely to concern
-`end': it is bound to the position of the end of the definition by a
-`save-excursion' expression that returns the value of point after
-`end-of-defun' temporarily moves it to the end of the definition.
-
-The second part of the `count-words-in-defun', after the set up, is
-the `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 `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 (*note Syntax::), so the loop is straightforward:
-
- (while (and (< (point) end)
- (re-search-forward
- "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t)
- (setq count (1+ count)))
-
-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
-`let' expression, and can be, very simply, the local variable
-`count', which when evaluated returns the count.
-
-Put together, the `count-words-in-defun' definition looks like this:
-
- (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))))
- (while
- (and (< (point) end)
- (re-search-forward
- "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*"
- end t))
- (setq count (1+ count)))
- count))
-
-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
-`count-words-region':
-
- ;;; Interactive version.
- (defun count-words-defun ()
- "Number of words and symbols in a function definition."
- (interactive)
- (message
- "Counting words and symbols in function definition ... ")
- (let ((count (count-words-in-defun)))
- (cond
- ((zerop count)
- (message
- "The definition does NOT have any words or symbols."))
- ((= 1 count)
- (message
- "The definition has 1 word or symbol."))
- (t
- (message
- "The definition has %d words or symbols." count)))))
-
-Let's re-use `C-c =' as a convenient keybinding:
-
- (global-set-key "\C-c=" 'count-words-defun)
-
-Now we can try out `count-words-defun': install both
-`count-words-in-defun' and `count-words-defun', and set the
-keybinding, and then place the cursor within the following definition:
-
- (defun multiply-by-seven (number)
- "Multiply NUMBER by seven."
- (* 7 number))
- => 10
-
-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.
-
-Count Several `defuns' Within a File
-====================================
-
-A file such as `simple.el' may have 80 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 `(goto-char
-(point-min))'. Next, we start the `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. `cons', the
-list construction command, can be used to create the list. That is
-almost all there is to it.
-
-Here is what this fragment of code looks like:
-
- (goto-char (point-min))
- (while (re-search-forward "^(defun" nil t)
- (setq lengths-list
- (cons (count-words-in-defun) lengths-list)))
-
-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 `*scratch*'
-buffer.
-
-Finding a file is a new process that we have not yet discussed.
-
-Find a File
-===========
-
-To find a file in Emacs, you use the `C-x C-f' (`find-file') command.
-This command is almost, but not quite right for the lengths problem.
-
-Let's look at the source for `find-file' (you can use the `find-tag'
-command or `C-h f' (`describe-function') to find the source of a
-function):
-
- (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)))
-
-The definition 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, `find-file-noselect' and `switch-to-buffer'.
-
-According to its documentation as shown by `C-h f' (the
-`describe-function' command), the `find-file-noselect' function reads
-the named file into a buffer and returns the buffer. However, the
-buffer is not selected. Emacs does not switch its attention (or
-yours if you are using `find-file-noselect') to the named buffer.
-That is what `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. (*Note 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 `switch-to-buffer', we can work with
-`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 `find-file' to do the job, we must write our
-own expression.
-
-The task is easy: use `find-file-noselect' and `set-buffer'.
-
-`lengths-list-file' in Detail
-=============================
-
-The core of the `lengths-list-file' function is a `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:
-
- (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."
- (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)))
-
-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 `save-excursion' that returns Emacs'
-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 `let' expression, Emacs finds the file and
-binds the local variable `buffer' to the buffer containing the file.
-At the same time, Emacs creates `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 very 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 ...
-
-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 `(goto-char (point-min))' expression moves point to the beginning
-of the buffer.
-
-Then comes a `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 Emacs 19 contained over 300
-source files of interest; Emacs 21 contains over 800 source files.
-Another function will apply `lengths-list-file' to each of the files.
-
-Finally, the last expression within the `let' expression is the
-`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 `C-x C-e'
-(`eval-last-sexp').
-
- (lengths-list-file
- "/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el")
-
-(You may need to change the pathname of the file; the one here worked
-with GNU Emacs version 21.0.100. To change the expression, copy it to
-the `*scratch*' buffer and edit it.
-
-(Also, to see the full length of the list, rather than a truncated
-version, you may have to evaluate the following:
-
- (custom-set-variables '(eval-expression-print-length nil))
-
-(*Note Setting Variables with `defcustom': defcustom. Then evaluate
-the `lengths-list-file' expression.)
-
-The lengths' list for `debug.el' takes less than a second to produce
-and looks like this:
-
- (77 95 85 87 131 89 50 25 44 44 68 35 64 45 17 34 167 457)
-
-(Using my old machine, the version 19 lengths' list for `debug.el'
-took seven seconds to produce and looked like this:
-
- (75 41 80 62 20 45 44 68 45 12 34 235)
-
-(The newer version of `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.
-
-Count Words in `defuns' in Different Files
-==========================================
-
-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 `while' loop or recursion.
-
-Determine the lengths of `defuns'
----------------------------------
-
-The design using a `while' loop is routine. The argument passed the
-function is a list of files. As we saw earlier (*note Loop
-Example::), you can write a `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 CDR of
-the list each time the body is evaluated.
-
-The template looks like this:
-
- (while TEST-WHETHER-LIST-IS-EMPTY
- BODY...
- SET-LIST-TO-CDR-OF-LIST)
-
-Also, we remember that a `while' loop returns `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
-`while' loop within a `let' expression, and arrange that the last
-element of the `let' expression contains the value of the lengths'
-list. (*Note Loop Example with an Incrementing Counter: Incrementing
-Example.)
-
-These considerations lead us directly to the function itself:
-
- ;;; Use `while' loop.
- (defun lengths-list-many-files (list-of-files)
- "Return list of lengths of defuns in LIST-OF-FILES."
- (let (lengths-list)
-
- ;;; true-or-false-test
- (while list-of-files
- (setq lengths-list
- (append
- lengths-list
-
- ;;; Generate a lengths' list.
- (lengths-list-file
- (expand-file-name (car list-of-files)))))
-
- ;;; Make files' list shorter.
- (setq list-of-files (cdr list-of-files)))
-
- ;;; Return final value of lengths' list.
- lengths-list))
-
-`expand-file-name' is a built-in function that converts a file name
-to the absolute, long, path name form of the directory in which the
-function is called.
-
-Thus, if `expand-file-name' is called on `debug.el' when Emacs is
-visiting the `/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/'
-directory,
-
- debug.el
-
-becomes
-
- /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
-
-The only other new element of this function definition is the as yet
-unstudied function `append', which merits a short section for itself.
-
-The `append' Function
----------------------
-
-The `append' function attaches one list to another. Thus,
-
- (append '(1 2 3 4) '(5 6 7 8))
-
-produces the list
-
- (1 2 3 4 5 6 7 8)
-
-This is exactly how we want to attach two lengths' lists produced by
-`lengths-list-file' to each other. The results contrast with `cons',
-
- (cons '(1 2 3 4) '(5 6 7 8))
-
-which constructs a new list in which the first argument to `cons'
-becomes the first element of the new list:
-
- ((1 2 3 4) 5 6 7 8)
-
-Recursively Count Words in Different Files
-==========================================
-
-Besides a `while' loop, you can work on each of a list of files with
-recursion. A recursive version of `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 `list-of-files' contains any remaining elements; the
-`next-step-expression' resets the `list-of-files' to the 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!
-
- (defun recursive-lengths-list-many-files (list-of-files)
- "Return list of lengths of each defun in LIST-OF-FILES."
- (if list-of-files ; do-again-test
- (append
- (lengths-list-file
- (expand-file-name (car list-of-files)))
- (recursive-lengths-list-many-files
- (cdr list-of-files)))))
-
-In a sentence, the function returns the lengths' list for the first of
-the `list-of-files' appended to the result of calling itself on the
-rest of the `list-of-files'.
-
-Here is a test of `recursive-lengths-list-many-files', along with the
-results of running `lengths-list-file' on each of the files
-individually.
-
-Install `recursive-lengths-list-many-files' and `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 `*scratch*' buffer, edit
-them, and then evaluate them.
-
-The results are shown after the `=>'. (These results are for files
-from Emacs Version 21.0.100; files from other versions of Emacs may
-produce different results.)
-
- (cd "/usr/local/share/emacs/21.0.100/")
-
- (lengths-list-file "./lisp/macros.el")
- => (273 263 456 90)
-
- (lengths-list-file "./lisp/mail/mailalias.el")
- => (38 32 26 77 174 180 321 198 324)
-
- (lengths-list-file "./lisp/makesum.el")
- => (85 181)
-
- (recursive-lengths-list-many-files
- '("./lisp/macros.el"
- "./lisp/mail/mailalias.el"
- "./lisp/makesum.el"))
- => (273 263 456 90 38 32 26 77 174 180 321 198 324 85 181)
-
-The `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.
-
-Prepare the Data for Display in a Graph
-=======================================
-
-The `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
-`recursive-lengths-list-many-files' function and count the number of
-defuns within each range of lengths, and produce a list of those
-numbers.
-
-Based on what we have done before, we can readily foresee that it
-should not be too hard to write a function that `CDRs' 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.
-
-Sorting Lists
--------------
-
-Emacs contains a function to sort lists, called (as you might guess)
-`sort'. The `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 (*note Using the Wrong Type Object as an Argument:
-Wrong Type of Argument.), a predicate is a function that determines
-whether some property is true or false. The `sort' function will
-reorder a list according to whatever property the predicate uses;
-this means that `sort' can be used to sort non-numeric lists by
-non-numeric criteria--it can, for example, alphabetize a list.
-
-The `<' function is used when sorting a numeric list. For example,
-
- (sort '(4 8 21 17 33 7 21 7) '<)
-
-produces this:
-
- (4 7 7 8 17 21 21 33)
-
-(Note that in this example, both the arguments are quoted so that the
-symbols are not evaluated before being passed to `sort' as arguments.)
-
-Sorting the list returned by the `recursive-lengths-list-many-files'
-function is straightforward; it uses the `<' function:
-
- (sort
- (recursive-lengths-list-many-files
- '("../lisp/macros.el"
- "../lisp/mailalias.el"
- "../lisp/makesum.el"))
- '<
-
-which produces:
-
- (85 86 116 122 154 176 179 265)
-
-(Note that in this example, the first argument to `sort' is not
-quoted, since the expression must be evaluated so as to produce the
-list that is passed to `sort'.)
-
-Making a List of Files
-----------------------
-
-The `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 `while' loop and a
-recursive call.
-
-We did not have to write a function like this for older versions of
-GNU Emacs, since they placed all the `.el' files in one directory.
-Instead, we were able to use the `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 `lisp' directory. This
-re-arrangement eases navigation. For example, all the mail related
-files are in a `lisp' sub-directory called `mail'. But at the same
-time, this arrangement forces us to create a file listing function
-that descends into the sub-directories.
-
-We can create this function, called `files-in-below-directory', using
-familiar functions such as `car', `nthcdr', and `substring' in
-conjunction with an existing function called
-`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 `recursive-lengths-list-many-files' as a list that looks
-like this (but with more elements):
-
- ("../lisp/macros.el"
- "../lisp/mail/rmail.el"
- "../lisp/makesum.el")
-
-The `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 `directory file', that is to
-say, a file with the special attributes of a directory. The second
-element of the list is `t' for a directory, a string for symbolic
-link (the string is the name linked to), or `nil'.
-
-For example, the first `.el' file in the `lisp/' directory is
-`abbrev.el'. Its name is
-`/usr/local/share/emacs/21.0.100/lisp/abbrev.el' and it is not a
-directory or a symbolic link.
-
-This is how `directory-files-and-attributes' lists that file and its
-attributes:
-
- ("/usr/local/share/emacs/21.0.100/lisp/abbrev.el"
- nil
- 1
- 1000
- 100
- (15019 32380)
- (14883 48041)
- (15214 49336)
- 11583
- "-rw-rw-r--"
- t
- 341385
- 776)
-
-On the other hand, `mail/' is a directory within the `lisp/'
-directory. The beginning of its listing looks like this:
-
- ("/usr/local/share/emacs/21.0.100/lisp/mail"
- t
- ...
- )
-
-(Look at the documentation of `file-attributes' to learn about the
-different attributes. Bear in mind that the `file-attributes'
-function does not list the filename, so its first element is
-`directory-files-and-attributes''s second element.)
-
-We will want our new function, `files-in-below-directory', to list
-the `.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 `files-in-below-directory':
-within a directory, the function should add `.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 `.', ("dot") and a name that refers to its
-parent directory, called `..' ("double dot"). (In `/', the root
-directory, `..' refers to itself, since `/' has no parent.) Clearly,
-we do not want our `files-in-below-directory' function to enter those
-directories, since they always lead us, directly or indirectly, to
-the current directory.
-
-Consequently, our `files-in-below-directory' function must do several
-tasks:
-
- * Check to see whether it is looking at a filename that ends in
- `.el'; and if so, add its name to a list.
-
- * Check to see whether it is looking at a filename that is the
- name of a directory; and if so,
-
- - Check to see whether it is looking at `.' or `..'; and if
- so skip it.
-
- - Or else, go into that directory and repeat the process.
-
-Let's write a function definition to do these tasks. We will use a
-`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' (*note Recursive Pattern: _accumulate_: Accumulate.),
-using `append' as the combiner.
-
-Here is the function:
-
- (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/21.0.100/lisp/"
- (interactive "DDirectory name: ")
- (let (el-files-list
- (current-directory-list
- (directory-files-and-attributes directory t)))
- ;; while we are in the current directory
- (while current-directory-list
- (cond
- ;; check to see whether filename ends in `.el'
- ;; and if so, append 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)))
- ;; check whether filename is that of a directory
- ((eq t (car (cdr (car current-directory-list))))
- ;; decide whether to skip or recurse
- (if
- (equal (or "." "..")
- (substring (car (car current-directory-list)) -1))
- ;; then do nothing if filename is that of
- ;; current directory or parent
- ()
- ;; 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))
-
-The `files-in-below-directory' `directory-files' function takes one
-argument, the name of a directory.
-
-Thus, on my system,
-
- (length
- (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/"))
-
-tells me that my version 21.0.100 Lisp sources directory contains 754
-`.el' files.
-
-`files-in-below-directory' returns a list in reverse alphabetical
-order. An expression to sort the list in alphabetical order looks
-like this:
-
- (sort
- (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
- 'string-lessp)
-
-Counting function definitions
------------------------------
-
-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 `top-of-ranges' list.
-
-If we wished, we could generate this list automatically, but it is
-simpler to write a list manually. Here it is:
-
- (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'.")
-
-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 `sorted-lengths' and the `top-of-ranges' lists as arguments.
-
-The `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 `top-of-ranges' list after counting the number of
-definitions in the current range. Since each of these actions is
-repetitive, we can use `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 `sorted-lengths' list are counted for each
-range; this means that the loop for the `sorted-lengths' list will be
-inside the loop for the `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. (*Note A
-loop with an incrementing counter: Incrementing Loop.) The
-true-or-false test of the loop tests whether the value from the
-`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 `sorted-lengths' list.
-
-The inner loop looks like this:
-
- (while LENGTH-ELEMENT-SMALLER-THAN-TOP-OF-RANGE
- (setq number-within-range (1+ number-within-range))
- (setq sorted-lengths (cdr sorted-lengths)))
-
-The outer loop must start with the lowest value of the
-`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:
-
- (while top-of-ranges
- BODY-OF-LOOP...
- (setq top-of-ranges (cdr top-of-ranges)))
-
-Put together, the two loops look like this:
-
- (while top-of-ranges
-
- ;; Count the number of elements within the current range.
- (while LENGTH-ELEMENT-SMALLER-THAN-TOP-OF-RANGE
- (setq number-within-range (1+ number-within-range))
- (setq sorted-lengths (cdr sorted-lengths)))
-
- ;; Move to next range.
- (setq top-of-ranges (cdr top-of-ranges)))
-
-In addition, in each circuit of the outer loop, Emacs should record
-the number of definitions within that range (the value of
-`number-within-range') in a list. We can use `cons' for this
-purpose. (*Note `cons': cons.)
-
-The `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 `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
-`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
-`defuns-per-range-list'. We can do this using the `nreverse'
-function, which reverses the order of a list.
-
-For example,
-
- (nreverse '(1 2 3 4))
-
-produces:
-
- (4 3 2 1)
-
-Note that the `nreverse' function is "destructive"--that is, it
-changes the list to which it is applied; this contrasts with the
-`car' and `cdr' functions, which are non-destructive. In this case,
-we do not want the original `defuns-per-range-list', so it does not
-matter that it is destroyed. (The `reverse' function provides a
-reversed copy of a list, leaving the original list as is.)
-
-Put all together, the `defuns-per-range' looks like this:
-
- (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)
-
- ;; Outer loop.
- (while top-of-ranges
-
- ;; Inner loop.
- (while (and
- ;; Need number for numeric test.
- (car sorted-lengths)
- (< (car sorted-lengths) top-of-range))
-
- ;; Count number of definitions within current range.
- (setq number-within-range (1+ number-within-range))
- (setq sorted-lengths (cdr sorted-lengths)))
-
- ;; 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) ; Reset count to zero.
-
- ;; Move to next range.
- (setq top-of-ranges (cdr top-of-ranges))
- ;; Specify next top of range value.
- (setq top-of-range (car top-of-ranges)))
-
- ;; Exit outer loop and count the number of defuns larger than
- ;; the largest top-of-range value.
- (setq defuns-per-range-list
- (cons
- (length sorted-lengths)
- defuns-per-range-list))
-
- ;; Return a list of the number of definitions within each range,
- ;; smallest to largest.
- (nreverse defuns-per-range-list)))
-
-The function is straightforward except for one subtle feature. The
-true-or-false test of the inner loop looks like this:
-
- (and (car sorted-lengths)
- (< (car sorted-lengths) top-of-range))
-
-instead of like this:
-
- (< (car sorted-lengths) top-of-range)
-
-The purpose of the test is to determine whether the first item in the
-`sorted-lengths' list is less than the value of the top of the range.
-
-The simple version of the test works fine unless the `sorted-lengths'
-list has a `nil' value. In that case, the `(car sorted-lengths)'
-expression function returns `nil'. The `<' function cannot compare a
-number to `nil', which is an empty list, so Emacs signals an error and
-stops the function from attempting to continue to execute.
-
-The `sorted-lengths' list always becomes `nil' when the counter
-reaches the end of the list. This means that any attempt to use the
-`defuns-per-range' function with the simple version of the test will
-fail.
-
-We solve the problem by using the `(car sorted-lengths)' expression
-in conjunction with the `and' expression. The `(car sorted-lengths)'
-expression returns a non-`nil' value so long as the list has at least
-one number within it, but returns `nil' if the list is empty. The
-`and' expression first evaluates the `(car sorted-lengths)'
-expression, and if it is `nil', returns false _without_ evaluating the
-`<' expression. But if the `(car sorted-lengths)' expression returns
-a non-`nil' value, the `and' expression evaluates the `<' expression,
-and returns that value as the value of the `and' expression.
-
-This way, we avoid an error. *Note forward-paragraph::, for more
-information about `and'.
-
-Here is a short test of the `defuns-per-range' function. First,
-evaluate the expression that binds (a shortened) `top-of-ranges' list
-to the list of values, then evaluate the expression for binding the
-`sorted-lengths' list, and then evaluate the `defuns-per-range'
-function.
-
- ;; (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)
-
-The list returned looks like this:
-
- (2 2 2 0 0 1 0 2 0 0 4)
-
-Indeed, there are two elements of the `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.
-
-Readying a 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 `gnuplot' to do the job. (`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 "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.
-
-Printing the Columns of a Graph
-===============================
-
-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 `graph-body-print'; it will take a
-`numbers-list' as its only argument. At this stage, we will not
-label the graph, but only print its body.
-
-The `graph-body-print' function inserts a vertical column of
-asterisks for each element in the `numbers-list'. The height of each
-line is determined by the value of that element of the `numbers-list'.
-
-Inserting columns is a repetitive act; that means that this function
-can be written either with a `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 `M-x apropos'
-command. This command is like the `C-h a' (command-apropos) command,
-except that the latter finds only those functions that are commands.
-The `M-x apropos' command lists all symbols that match a regular
-expression, including functions that are not interactive.
-
-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 `M-x apropos RET print\|insert\|column
-RET' and look at the result. On my system, this command takes quite
-some time, and then produces a list of 79 functions and variables.
-Scanning down the list, the only function that looks as if it might
-do the job is `insert-rectangle'.
-
-Indeed, this is the function we want; its documentation says:
-
- 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.
-
-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 `insert-rectangle'
-expression and typing `C-u C-x C-e' (`eval-last-sexp'). The function
-inserts the strings `"first"', `"second"', and `"third"' at and below
-point. Also the function returns `nil'.
-
- (insert-rectangle '("first" "second" "third"))first
- second
- third
- nil
-
-Of course, we won't be inserting the text of the `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
-`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 `*scratch*' buffer, placing
-point somewhere in the buffer, typing `M-:', typing the
-`insert-rectangle' expression into the minibuffer at the prompt, and
-then typing <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 `*scratch*' buffer. (`M-:' is the keybinding for
-`eval-expression'.)
-
-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 `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...
-
-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 `numbers-list'. We need to construct a list
-of asterisks of the right length for each call to `insert-rectangle'.
-If this list consists solely of the requisite number of asterisks,
-then we will have 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
-`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 `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
-`insert-rectangle' requires an argument that looks like this:
-
- (" " " " "*" "*" "*")
-
-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 `max' and it returns the largest of
-all its arguments, which must be numbers. Thus, for example,
-
- (max 3 4 6 5 7 3)
-
-returns 7. (A corresponding function called `min' returns the
-smallest of all its arguments.)
-
-However, we cannot simply call `max' on the `numbers-list'; the `max'
-function expects numbers as its argument, not a list of numbers.
-Thus, the following expression,
-
- (max '(3 4 6 5 7 3))
-
-produces the following error message;
-
- Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3)
-
-We need a function that passes a list of arguments to a function.
-This function is `apply'. This function `applies' its first argument
-(a function) to its remaining arguments, the last of which may be a
-list.
-
-For example,
-
- (apply 'max 3 4 7 3 '(4 8 5))
-
-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 `search-forward' or `insert-rectangle', by guessing
-at a part of their names and then using `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
-`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 `apply' are optional, so we
-can use `apply' to call a function and pass the elements of a list to
-it, like this, which also returns 8:
-
- (apply 'max '(4 8 5))
-
-This latter way is how we will use `apply'. The
-`recursive-lengths-list-many-files' function returns a numbers' list
-to which we can apply `max' (we could also apply `max' to the sorted
-numbers' list; it does not matter whether the list is sorted or not.)
-
-Hence, the operation for finding the maximum height of the graph is
-this:
-
- (setq max-graph-height (apply 'max numbers-list))
-
-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 `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 `while'
-loops can be used to construct the list:
-
- ;;; 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)))
-
- ;; Fill in asterisks.
- (while (> actual-height 0)
- (setq insert-list (cons "*" insert-list))
- (setq actual-height (1- actual-height)))
-
- ;; 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)))
-
- ;; Return whole list.
- insert-list))
-
-If you install this function and then evaluate the following
-expression you will see that it returns the list as desired:
-
- (column-of-graph 5 3)
-
-returns
-
- (" " " " "*" "*" "*")
-
-As written, `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 many want to use a period in place
-of the space, to make sure the point is being repositioned properly
-each time the `insert-rectangle' function is called; or you might
-want to substitute a `+' 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 `graph-blank' and `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:
-
- (defvar graph-symbol "*"
- "String used as symbol in graph, usually an asterisk.")
-
- (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.")
-
-(For an explanation of `defvar', see *Note Initializing a Variable
-with `defvar': defvar.)
-
- ;;; Second version.
- (defun column-of-graph (max-graph-height actual-height)
- "Return 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."
-
- (let ((insert-list nil)
- (number-of-top-blanks
- (- max-graph-height actual-height)))
-
- ;; Fill in `graph-symbols'.
- (while (> actual-height 0)
- (setq insert-list (cons graph-symbol insert-list))
- (setq actual-height (1- actual-height)))
-
- ;; Fill in `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)))
-
- ;; Return whole list.
- insert-list))
-
-If we wished, we could rewrite `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 `cons' to attach a graph symbol to the list;
-then it uses `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 `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 `graph-body-print'.
-
-The `graph-body-print' Function
-===============================
-
-After our preparation in the preceding section, the
-`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
-`while' loop or recursive function for the job. In this section, we
-will write the definition using a `while' loop.
-
-The `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 `while' loop version
-of this function:
-
- (defun graph-body-print (numbers-list)
- "DOCUMENTATION..."
- (let ((height ...
- ...))
-
- (while numbers-list
- INSERT-COLUMNS-AND-REPOSITION-POINT
- (setq numbers-list (cdr numbers-list)))))
-
-We need to fill in the slots of the template.
-
-Clearly, we can use the `(apply 'max numbers-list)' expression to
-determine the height of the graph.
-
-The `while' loop will cycle through the `numbers-list' one element at
-a time. As it is shortened by the `(setq numbers-list (cdr
-numbers-list))' expression, the CAR of each instance of the list is
-the value of the argument for `column-of-graph'.
-
-At each cycle of the `while' loop, the `insert-rectangle' function
-inserts the list returned by `column-of-graph'. Since the
-`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 `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 `(forward-char 1)'; however, the width of a column may be
-greater than one. This means that the repositioning command should be
-written `(forward-char symbol-width)'. The `symbol-width' itself is
-the length of a `graph-blank' and can be found using the expression
-`(length graph-blank)'. The best place to bind the `symbol-width'
-variable to the value of the width of graph column is in the varlist
-of the `let' expression.
-
-These considerations lead to the following function definition:
-
- (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)
-
- (while numbers-list
- (setq from-position (point))
- (insert-rectangle
- (column-of-graph height (car numbers-list)))
- (goto-char from-position)
- (forward-char symbol-width)
- ;; Draw graph column by column.
- (sit-for 0)
- (setq numbers-list (cdr numbers-list)))
- ;; Place point for X axis labels.
- (forward-line height)
- (insert "\n")
- ))
-
-The one unexpected expression in this function is the `(sit-for 0)'
-expression in the `while' loop. This expression makes the graph
-printing operation more interesting to watch than it would be
-otherwise. The expression causes Emacs to `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 `graph-body-print' with a short list of numbers.
-
- 1. Install `graph-symbol', `graph-blank', `column-of-graph', which
- are in *Note Columns of a graph::, and `graph-body-print'.
-
- 2. Copy the following expression:
-
- (graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3))
-
- 3. Switch to the `*scratch*' buffer and place the cursor where you
- want the graph to start.
-
- 4. Type `M-:' (`eval-expression').
-
- 5. Yank the `graph-body-print' expression into the minibuffer with
- `C-y' (`yank)'.
-
- 6. Press <RET> to evaluate the `graph-body-print' expression.
-
-Emacs will print a graph like this:
-
- *
- * **
- * ****
- *** ****
- ********* *
- ************
- *************
-
-The `recursive-graph-body-print' Function
-=========================================
-
-The `graph-body-print' function may also be written recursively. The
-recursive solution is divided into two parts: an outside `wrapper'
-that uses a `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.
-
-The `wrapper' is uncomplicated:
-
- (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)))
-
-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 an `if' expression
-that determines whether the `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 `numbers-list'.
-
- (defun recursive-graph-body-print-internal
- (numbers-list height symbol-width)
- "Print a bar graph.
- Used within recursive-graph-body-print function."
-
- (if numbers-list
- (progn
- (setq from-position (point))
- (insert-rectangle
- (column-of-graph height (car numbers-list)))
- (goto-char from-position)
- (forward-char symbol-width)
- (sit-for 0) ; Draw graph column by column.
- (recursive-graph-body-print-internal
- (cdr numbers-list) height symbol-width))))
-
-After installation, this expression can be tested; here is a sample:
-
- (recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1))
-
-Here is what `recursive-graph-body-print' produces:
-
- *
- ** *
- **** *
- **** ***
- * *********
- ************
- *************
-
-Either of these two functions, `graph-body-print' or
-`recursive-graph-body-print', create the body of a graph.
-
-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'
-Picture mode; but a graph drawing function may be used more than once.
-
-For this reason, I have written enhancements to the basic
-`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. *Note A Graph with Labelled Axes: Full Graph.
-
-Exercise
-========
-
-Write a line graph version of the graph printing functions.
-
-Your `.emacs' 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.
-
-Emacs' Default Configuration
-============================
-
-There are those who appreciate Emacs' 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. 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
-`~/.emacs' file. This is your personal initialization file; its
-contents, written in Emacs Lisp, tell Emacs what to do.(1)
-
-A `~/.emacs' file contains Emacs Lisp code. You can write this code
-yourself; or you can use Emacs' `customize' feature to write the code
-for you. You can combine your own expressions and auto-written
-Customize expressions in your `.emacs' file.
-
-(I myself prefer to write my own expressions, except for those,
-particularly fonts, that I find easier to manipulate using the
-`customize' command. I combine the two methods.)
-
-Most of this chapter is about writing expressions yourself. It
-describes a simple `.emacs' file; for more information, see *Note The
-Init File: (emacs)Init File, and *Note The Init File: (elisp)Init
-File.
-
----------- Footnotes ----------
-
-(1) You may also add `.el' to `~/.emacs' and call it a `~/.emacs.el'
-file. In the past, you were forbidden to type the extra keystrokes
-that the name `~/.emacs.el' requires, but now you may. The new
-format is consistent with the Emacs Lisp file naming conventions; the
-old format saves typing.
-
-Site-wide Initialization Files
-==============================
-
-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 `.emacs' file, but are loaded by everyone.
-
-Two site-wide initialization files, `site-load.el' and
-`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. *Note Building Emacs: (elisp)Building
-Emacs, and the `INSTALL' file.)
-
-Three other site-wide initialization files are loaded automatically
-each time you start Emacs, if they exist. These are `site-start.el',
-which is loaded _before_ your `.emacs' file, and `default.el', and
-the terminal type file, which are both loaded _after_ your `.emacs'
-file.
-
-Settings and definitions in your `.emacs' file will overwrite
-conflicting settings and definitions in a `site-start.el' file, if it
-exists; but the settings and definitions in a `default.el' or
-terminal type file will overwrite those in your `.emacs' file. (You
-can prevent interference from a terminal type file by setting
-`term-file-prefix' to `nil'. *Note A Simple Extension: Simple
-Extension.)
-
-The `INSTALL' file that comes in the distribution contains
-descriptions of the `site-init.el' and `site-load.el' files.
-
-The `loadup.el', `startup.el', and `loaddefs.el' files control
-loading. These files are in the `lisp' directory of the Emacs
-distribution and are worth perusing.
-
-The `loaddefs.el' file contains a good many suggestions as to what to
-put into your own `.emacs' file, or into a site-wide initialization
-file.
-
-Specifying Variables using `defcustom'
-======================================
-
-You can specify variables using `defcustom' so that you and others
-can then use Emacs' `customize' feature to set their values. (You
-cannot use `customize' to write function definitions; but you can
-write `defuns' in your `.emacs' file. Indeed, you can write any Lisp
-expression in your `.emacs' file.)
-
-The `customize' feature depends on the `defcustom' special form.
-Although you can use `defvar' or `setq' for variables that users set,
-the `defcustom' special form is designed for the job.
-
-You can use your knowledge of `defvar' for writing the first three
-arguments for `defcustom'. The first argument to `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 `defcustom' specify types and
-options; these are not featured in `defvar'. (These arguments are
-optional.)
-
-Each of these arguments consists of a keyword followed by a value.
-Each keyword starts with the character `:'.
-
-For example, the customizable user option variable `text-mode-hook'
-looks like this:
-
- (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 'data)
-
-The name of the variable is `text-mode-hook'; it has no default
-value; and its documentation string tells you what it does.
-
-The `:type' keyword tells Emacs what kind of data `text-mode-hook'
-should be set to and how to display the value in a Customization
-buffer.
-
-The `:options' keyword specifies a suggested list of values for the
-variable. Currently, you can use `:options' only for 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
-`:options' keyword is intended to offer convenient choices to a user.
-
-Finally, the `:group' keyword tells the Emacs Customization command
-in which group the variable is located. This tells where to find it.
-
-For more information, see *Note Writing Customization Definitions:
-(elisp)Customization.
-
-Consider `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.
-
-Using the customization command, you can type:
-
- M-x customize
-
-and find that the group for editing files of data is called `data'.
-Enter that group. Text Mode Hook is the first member. You can click
-on its various options to set the values. After you click on the
-button to
-
- Save for Future Sessions
-
-Emacs will write an expression into your `.emacs' file. It will look
-like this:
-
- (custom-set-variables
- ;; custom-set-variables was added by Custom --
- ;; don't edit or cut/paste it!
- ;; Your init file should contain only one such instance.
- '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
-
-(The `text-mode-hook-identify' function tells
-`toggle-text-mode-auto-fill' which buffers are in Text mode.)
-
-In spite of the warning, you certainly may edit, cut, and paste the
-expression! I do all time. The purpose of the warning is to scare
-those who do not know what they are doing, so they do not
-inadvertently generate an error.
-
-The `custom-set-variables' works somewhat differently than a `setq'.
-While I have never learned the differences, I do modify the
-`custom-set-variables' expressions in my `.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 `custom-set-...' function is `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
-`customize'; other times, I simply edit the `custom-set-faces'
-expression in my `.emacs' file itself.
-
-The second way to customize your `text-mode-hook' is to set it
-yourself in your `.emacs' file using code that has nothing to do with
-the `custom-set-...' functions.
-
-When you do this, and later use `customize', you will see a message
-that says
-
- this option has been changed outside the customize buffer.
-
-This message is only a warning. If you click on the button to
-
- Save for Future Sessions
-
-Emacs will write a `custom-set-...' expression near the end of your
-`.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 `.emacs'.
-
-I myself use `customize' for hardly anything. Mostly, I write
-expressions myself.
-
-Beginning a `.emacs' File
-=========================
-
-When you start Emacs, it loads your `.emacs' file unless you tell it
-not to by specifying `-q' on the command line. (The `emacs -q'
-command gives you a plain, out-of-the-box Emacs.)
-
-A `.emacs' file contains Lisp expressions. Often, these are no more
-than expressions to set values; sometimes they are function
-definitions.
-
-*Note The Init File `~/.emacs': (emacs)Init File, 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 `.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.
-
- ;;;; Bob's .emacs file
- ; Robert J. Chassell
- ; 26 September 1985
-
-Look at that date! I started this file a long time ago. I have been
-adding to it ever since.
-
- ; 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.
-
-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 section and subsection
-markers. (*Note Comments: (elisp)Comments, for more about comments.)
-
- ;;;; 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.
-
-Just remember: type `C-h' two times for help.
-
- ; 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.
-
-`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
-`.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.
-
-Text and Auto Fill Mode
-=======================
-
-Now we come to the part that `turns on' Text mode and Auto Fill mode.
-
- ;;; Text mode and Auto Fill mode
- ; The next three 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 'text-mode-hook-identify)
- (add-hook 'text-mode-hook 'turn-on-auto-fill)
-
-Here is the first part of this `.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, _unless_ that file should go into some
-other mode, such as C mode.
-
-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 `.'.) If the
-file ends with a `.c' or `.h' extension then Emacs turns on C mode.
-Also, Emacs looks at first nonblank line of the file; if the line
-says `-*- 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.
-
-*Note How Major Modes are Chosen: (emacs)Choosing Modes.
-
-*Note Local Variables in Files: (emacs)File Variables.
-
-Now, back to the `.emacs' file.
-
-Here is the line again; how does it work?
-
- (setq default-major-mode 'text-mode)
-
-This line is a short, but complete Emacs Lisp expression.
-
-We are already familiar with `setq'. It sets the following variable,
-`default-major-mode', to the subsequent value, which is `text-mode'.
-The single quote mark before `text-mode' tells Emacs to deal directly
-with the `text-mode' variable, not with whatever it might stand for.
-*Note Setting the Value of a Variable: set & setq, for a reminder of
-how `setq' works. The main point is that there is no difference
-between the procedure you use to set a value in your `.emacs' file
-and the procedure you use anywhere else in Emacs.
-
-Here are the next two lines:
-
- (add-hook 'text-mode-hook 'text-mode-hook-identify)
- (add-hook 'text-mode-hook 'turn-on-auto-fill)
-
-In these two lines, the `add-hook' command first adds
-`text-mode-hook-identify' to the variable called `text-mode-hook' and
-then adds `turn-on-auto-fill' to the variable.
-
-`turn-on-auto-fill' is the name of a program, that, you guessed it!,
-turns on Auto Fill mode. `text-mode-hook-identify' is a function
-that tells `toggle-text-mode-auto-fill' which buffers are in Text
-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, first non-blank line, or local
-variables 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, `M-f' moves you over `it's'. On
-the other hand, in C mode, `M-f' stops just after the `t' of `it's'.
-
-The second and third lines 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 `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.
-
-In addition, in this part of my `.emacs' file, I tell the Emacs fill
-commands to insert two spaces after a colon:
-
- (setq colon-double-space t)
-
-Mail Aliases
-============
-
-Here is a `setq' that `turns on' mail aliases, along with more
-reminders.
-
- ;;; Mail mode
- ; To enter mail mode, type `C-x m'
- ; To enter RMAIL (for reading mail),
- ; type `M-x rmail'
-
- (setq mail-aliases t)
-
-This `setq' command sets the value of the variable `mail-aliases' to
-`t'. Since `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 `~/.mailrc'. You write an alias like this:
-
- alias geo george@foobar.wiz.edu
-
-When you write a message to George, address it to `geo'; the mailer
-will automatically expand `geo' to the full address.
-
-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 `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.
-
-The following turns off Indent Tabs mode:
-
- ;;; Prevent Extraneous Tabs
- (setq-default indent-tabs-mode nil)
-
-Note that this line uses `setq-default' rather than the `setq'
-command that we have seen before. The `setq-default' command sets
-values only in buffers that do not have their own local values for
-the variable.
-
-*Note Tabs vs. Spaces: (emacs)Just Spaces.
-
-*Note Local Variables in Files: (emacs)File Variables.
-
-Some Keybindings
-================
-
-Now for some personal keybindings:
-
- ;;; Compare windows
- (global-set-key "\C-cw" 'compare-windows)
-
-`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.
-
-The command is `global-set-key'. It is followed by the keybinding.
-In a `.emacs' file, the keybinding is written as shown: `\C-c' stands
-for `control-c', which means `press the control key and the `c' key
-at the same time'. The `w' means `press the `w' key'. The
-keybinding is surrounded by double quotation marks. In
-documentation, you would write this as `C-c w'. (If you were binding
-a <META> key, such as `M-c', rather than a <CTL> key, you would write
-`\M-c'. *Note Rebinding Keys in Your Init File: (emacs)Init
-Rebinding, for details.)
-
-The command invoked by the keys is `compare-windows'. Note that
-`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 `C', and the single quote mark are necessary parts of keybinding
-that I tend to forget. Fortunately, I have come to remember that I
-should look at my existing `.emacs' file, and adapt what is there.
-
-As for the keybinding itself: `C-c w'. This combines the prefix key,
-`C-c', with a single character, in this case, `w'. This set of keys,
-`C-c' followed by a single character, is strictly reserved for
-individuals' own use. (I call these `own' keys, since these are for
-my own use.) You should always be able to create such a keybinding
-for your own use without stomping on someone else's keybinding. If
-you ever write an extension to Emacs, please avoid taking any of
-these keys for public use. Create a key like `C-c C-w' instead.
-Otherwise, we will run out of `own' keys.
-
-Here is another keybinding, with a comment:
-
- ;;; Keybinding for `occur'
- ; I use occur a lot, so let's bind it to a key:
- (global-set-key "\C-co" 'occur)
-
-The `occur' command shows all the lines in the current buffer that
-contain a match for a regular expression. Matching lines are shown
-in a buffer called `*Occur*'. That buffer serves as a menu to jump
-to occurrences.
-
-Here is how to unbind a key, so it does not work:
-
- ;;; Unbind `C-x f'
- (global-unset-key "\C-xf")
-
-There is a reason for this unbinding: I found I inadvertently typed
-`C-x f' when I meant to type `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.
-
-The following rebinds an existing key:
-
- ;;; Rebind `C-x C-b' for `buffer-menu'
- (global-set-key "\C-x\C-b" 'buffer-menu)
-
-By default, `C-x C-b' runs the `list-buffers' command. This command
-lists your buffers in _another_ window. Since I almost always want
-to do something in that window, I prefer the `buffer-menu' command,
-which not only lists the buffers, but moves point into that window.
-
-Keymaps
-=======
-
-Emacs uses "keymaps" to record which keys call which commands. When
-you use `global-set-key' to set the keybinding for a single command
-in all parts of Emacs, you are specifying the keybinding in
-`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 `global-set-key' function binds, or rebinds, the global keymap.
-For example, the following binds the key `C-x C-b' to the function
-`buffer-menu':
-
- (global-set-key "\C-x\C-b" 'buffer-menu)
-
-Mode-specific keymaps are bound using the `define-key' function,
-which takes a specific keymap as an argument, as well as the key and
-the command. For example, my `.emacs' file contains the following
-expression to bind the `texinfo-insert-@group' command to `C-c C-c g':
-
- (define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@group)
-
-The `texinfo-insert-@group' function itself is a little extension to
-Texinfo mode that inserts `@group' into a Texinfo file. I use this
-command all the time and prefer to type the three strokes `C-c C-c g'
-rather than the six strokes `@ g r o u p'. (`@group' and its
-matching `@end group' are commands that keep all enclosed text
-together on one page; many multi-line examples in this book are
-surrounded by `@group ... @end group'.)
-
-Here is the `texinfo-insert-@group' function definition:
-
- (defun texinfo-insert-@group ()
- "Insert the string @group in a Texinfo buffer."
- (interactive)
- (beginning-of-line)
- (insert "@group\n"))
-
-(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 `define-key' expressions in `loaddefs.el' as
-well as in the various mode libraries, such as `cc-mode.el' and
-`lisp-mode.el'.
-
-*Note Customizing Key Bindings: (emacs)Key Bindings, and *Note
-Keymaps: (elisp)Keymaps, for more information about keymaps.
-
-Loading Files
-=============
-
-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.
-
-(Calc, which I consider a vital part of Emacs, would be part of the
-standard distribution except that it was so large it was packaged
-separately and no one has changed that.)
-
-You can use a `load' command to evaluate a complete file and thereby
-install all the functions and variables in the file into Emacs. For
-example:
-
- (load "~/emacs/slowsplit")
-
-This evaluates, i.e. loads, the `slowsplit.el' file or if it exists,
-the faster, byte compiled `slowsplit.elc' file from the `emacs'
-sub-directory of your home directory. The file contains the function
-`split-window-quietly', which John Robinson wrote in 1989.
-
-The `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.
-
-To replace the key binding for the default `split-window-vertically',
-you must also unset that key and bind the keys to
-`split-window-quietly', like this:
-
- (global-unset-key "\C-x2")
- (global-set-key "\C-x2" 'split-window-quietly)
-
-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' `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 `paths.h' when Emacs
-is built.)
-
-The following command adds your `~/emacs' directory to the existing
-load path:
-
- ;;; Emacs Load Path
- (setq load-path (cons "~/emacs" load-path))
-
-Incidentally, `load-library' is an interactive interface to the
-`load' function. The complete function looks like this:
-
- (defun load-library (library)
- "Load the library named LIBRARY.
- This is an interface to the function `load'."
- (interactive "sLoad library: ")
- (load library))
-
-The name of the function, `load-library', comes from the use of
-`library' as a conventional synonym for `file'. The source for the
-`load-library' command is in the `files.el' library.
-
-Another interactive command that does a slightly different job is
-`load-file'. *Note Libraries of Lisp Code for Emacs: (emacs)Lisp
-Libraries, for information on the distinction between `load-library'
-and this command.
-
-Autoloading
-===========
-
-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 "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 `loaddefs.el'
-library contains hundreds of autoloaded functions, from
-`bookmark-set' to `wordstar-mode'. Of course, you may come to use a
-`rare' function frequently. When you do, you should load that
-function's file with a `load' expression in your `.emacs' file.
-
-In my `.emacs' file for Emacs version 21, I load 12 libraries that
-contain functions that would otherwise be autoloaded. (Actually, it
-would have been better to include these files in my `dumped' Emacs
-when I built it, but I forgot. *Note Building Emacs: (elisp)Building
-Emacs, and the `INSTALL' file for more about dumping.)
-
-You may also want to include autoloaded expressions in your `.emacs'
-file. `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--`autoload' can handle a keymap or macro as well as a function
-(the default is a function).
-
-Here is a typical example:
-
- (autoload 'html-helper-mode
- "html-helper-mode" "Edit HTML documents" t)
-
-(`html-helper-mode' is an alternative to `html-mode', which is a
-standard part of the distribution).
-
-This expression autoloads the `html-helper-mode' function. It takes
-it from the `html-helper-mode.el' file (or from the byte compiled
-file `html-helper-mode.elc', if it exists.) The file must be located
-in a directory specified by `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 `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.)
-
-*Note Autoload: (elisp)Autoload, for more information.
-
-A Simple Extension: `line-to-top-of-window'
-===========================================
-
-Here is a simple extension to Emacs that moves the line 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 `.emacs' file, or you can include it within your `.emacs'
-file.
-
-Here is the definition:
-
- ;;; Line to top of window;
- ;;; replace three keystroke sequence C-u 0 C-l
- (defun line-to-top-of-window ()
- "Move the line point is on to top of window."
- (interactive)
- (recenter 0))
-
-Now for the keybinding.
-
-Nowadays, function keys as well as mouse button events and non-ASCII
-characters are written within square brackets, without quotation
-marks. (In Emacs version 18 and before, you had to write different
-function key bindings for each different make of terminal.)
-
-I bind `line-to-top-of-window' to my <F6> function key like this:
-
- (global-set-key [f6] 'line-to-top-of-window)
-
-For more information, see *Note Rebinding Keys in Your Init File:
-(emacs)Init Rebinding.
-
-If you run two versions of GNU Emacs, such as versions 20 and 21, and
-use one `.emacs' file, you can select which code to evaluate with the
-following conditional:
-
- (cond
- ((string-equal (number-to-string 20) (substring (emacs-version) 10 12))
- ;; evaluate version 20 code
- ( ... ))
- ((string-equal (number-to-string 21) (substring (emacs-version) 10 12))
- ;; evaluate version 21 code
- ( ... )))
-
-For example, in contrast to version 20, version 21 blinks its cursor
-by default. I hate such blinking, as well as some other features in
-version 21, so I placed the following in my `.emacs' file(1):
-
- (if (string-equal "21" (substring (emacs-version) 10 12))
- (progn
- (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)
- ;; Turn on image viewing
- (auto-image-file-mode t)
- ;; Turn on menu bar (this bar has text)
- ;; (Use numeric argument to turn on)
- (menu-bar-mode 1)
- ;; Turn off tool bar (this bar has icons)
- ;; (Use numeric argument to turn on)
- (tool-bar-mode nil)
- ;; 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 one second
- ))
-
-(You will note that instead of typing `(number-to-string 21)', I
-decided to save typing and wrote `21' as a string, `"21"', rather
-than convert it from an integer to a string. In this instance, this
-expression is better than the longer, but more general
-`(number-to-string 21)'. However, if you do not know ahead of time
-what type of information will be returned, then the
-`number-to-string' function will be needed.)
-
----------- Footnotes ----------
-
-(1) When I start instances of Emacs that do not load my `.emacs' file
-or any site file, I also turn off blinking:
-
- emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
-
-X11 Colors
-==========
-
-You can specify colors when you use Emacs with the MIT X Windowing
-system.
-
-I dislike the default colors and specify my own.
-
-Here are the expressions in my `.emacs' file that set values:
-
- ;; 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")
-
- ;;; Set highlighting colors for isearch and drag
- (set-face-foreground 'highlight "white")
- (set-face-background 'highlight "blue")
-
- (set-face-foreground 'region "cyan")
- (set-face-background 'region "blue")
-
- (set-face-foreground 'secondary-selection "skyblue")
- (set-face-background 'secondary-selection "darkblue")
-
- ;; Set calendar highlighting colors
- (setq calendar-load-hook
- '(lambda ()
- (set-face-foreground 'diary-face "skyblue")
- (set-face-background 'holiday-face "slate blue")
- (set-face-foreground 'holiday-face "white")))
-
-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
-`~/.Xresources' file like this:
-
- Emacs*foreground: white
- Emacs*background: darkblue
- Emacs*cursorColor: white
- Emacs*pointerColor: white
-
-In any event, since it is not part of Emacs, I set the root color of
-my X window in my `~/.xinitrc' file, like this(1):
-
- # I use TWM for window manager.
- xsetroot -solid Navy -fg white &
-
----------- Footnotes ----------
-
-(1) I occasionally run more modern window managers, such as Sawfish
-with GNOME, Enlightenment, SCWM, or KDE; in those cases, I often
-specify an image rather than a plain color.
-
-Miscellaneous Settings for a `.emacs' File
-==========================================
-
-Here are a few miscellaneous settings:
-
- - Set the shape and color of the mouse cursor:
- ; 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.
-
- (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
- (setq x-pointer-shape (string-to-int mpointer))
- (set-mouse-color "white"))
-
-A Modified Mode Line
-====================
-
-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 I lose track of where I am, and which line point is on.
-
-So I reset my mode line to look like this:
-
- -:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top
-
-I am visiting a file called `foo.texi', on my machine `rattlesnake'
-in my `/home/bob' buffer. I am on line 1, in Texinfo mode, and am at
-the top of the buffer.
-
-My `.emacs' file has a section that looks like this:
-
- ;; 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
- " "
- 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
- #(" %[(" 0 6
- (help-echo
- "mouse-1: select window, mouse-2: delete others ..."))
- (:eval (mode-line-mode-name))
- mode-line-process
- minor-mode-alist
- #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...)))
- ")%] "
- (-3 . "%P")
- ;; "-%-"
- )))
-
-Here, I redefine the default mode line. Most of the parts are from
-the original; but I make a few changes. I set the _default_ mode
-line format so as to permit various modes, such as Info, to override
-it.
-
-Many elements in the list are self-explanatory: `mode-line-modified'
-is a variable that tells whether the buffer has been modified,
-`mode-name' tells the name of the mode, and so on. However, the
-format looks complicated because of two features we have not
-discussed.
-
-The first string in the mode line is a dash or hyphen, `-'. In the
-old days, it would have been specified simply as `"-"'. 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 one second before the information appears. You can change that
-timing by changing the value of `tooltip-delay'.)
-
-The new string format has a special syntax:
-
- #("-" 0 1 (help-echo "mouse-1: select window, ..."))
-
-The `#(' begins a list. The first element of the list is the string
-itself, just one `-'. The second and third elements specify the
-range over which the fourth element applies. A range starts _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,
-`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.
-
-*Note Text Properties in String: (elisp)Text Props and Strings, and
-see *Note Mode Line Format: (elisp)Mode Line Format, for more
-information.
-
-`mode-line-buffer-identification' displays the current buffer name.
-It is a list beginning `(#("%12b" 0 4 ...'. The `#(' begins the list.
-
-The `"%12b"' displays the current buffer name, using the
-`buffer-name' function with which we are familiar; the `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.)
-
-`:eval' is a new feature in GNU Emacs version 21. It 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 `.' (`period'), so
-I use the `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.
-
-This is the expression:
-
- (:eval (substring
- (system-name) 0 (string-match "\\..+" (system-name))))
-
-`%[' and `%]' cause a pair of square brackets to appear for each
-recursive editing level. `%n' says `Narrow' when narrowing is in
-effect. `%P' tells you the percentage of the buffer that is above
-the bottom of the window, or `Top', `Bottom', or `All'. (A lower
-case `p' tell you the percentage above the _top_ of the window.)
-`%-' 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:
-
- emacs -q
-
-This will start an Emacs that does _not_ load your `~/.emacs'
-initialization file. A plain, default Emacs. Nothing more.
-
-Debugging
-*********
-
-GNU Emacs has two debuggers, `debug' and `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 *Note Debugging Lisp
-Programs: (elisp)Debugging. In this chapter, I will walk through a
-short example of each.
-
-`debug'
-=======
-
-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
-`triangle' function discussed earlier. *Note Example with
-Decrementing Counter: Decrementing Example, for a discussion.)
-
-However, your function definition has a bug. You have mistyped `1='
-for `1-'. Here is the broken definition:
-
- (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))) ; Error here.
- total))
-
-If you are reading this in Info, you can evaluate this definition in
-the normal fashion. You will see `triangle-bugged' appear in the
-echo area.
-
-Now evaluate the `triangle-bugged' function with an argument of 4:
-
- (triangle-bugged 4)
-
-In GNU Emacs version 21, you will create and enter a `*Backtrace*'
-buffer that says:
-
- ---------- 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)
- eval((triangle-bugged 4))
- eval-last-sexp-1(nil)
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
- ---------- Buffer: *Backtrace* ----------
-
-(I have reformatted this example slightly; the debugger does not fold
-long lines. As usual, you can quit the debugger by typing `q' in the
-`*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 `1=' is `void'.
-
-In GNU Emacs 20 and before, you will see:
-
- Symbol's function definition is void: 1=
-
-which has the same meaning as the `*Backtrace*' buffer line in
-version 21.
-
-However, suppose you are not quite certain what is going on? You can
-read the complete backtrace.
-
-In this case, you need to run GNU Emacs 21, which automatically starts
-the debugger that puts you in the `*Backtrace*' buffer; or else, you
-need to start the debugger manually as described below.
-
-Read the `*Backtrace*' buffer from the bottom up; it tells you what
-Emacs did that led to the error. Emacs made an interactive call to
-`C-x C-e' (`eval-last-sexp'), which led to the evaluation of the
-`triangle-bugged' expression. Each line above tells you what the
-Lisp interpreter evaluated next.
-
-The third line from the top of the buffer is
-
- (setq number (1= number))
-
-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:
-
- (1= number)
-
-This is where the error occurred; as the top line says:
-
- Debugger entered--Lisp error: (void-function 1=)
-
-You can correct the mistake, re-evaluate the function definition, and
-then run your test again.
-
-`debug-on-entry'
-================
-
-GNU Emacs 21 starts the debugger automatically when your function has
-an error. GNU Emacs version 20 and before did not; it simply
-presented you with an error message. You had to start the debugger
-manually.
-
-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
-`debug-on-entry'.
-
-Type:
-
- M-x debug-on-entry RET triangle-bugged RET
-
-Now, evaluate the following:
-
- (triangle-bugged 5)
-
-All versions of Emacs will create a `*Backtrace*' buffer and tell you
-that it is beginning to evaluate the `triangle-bugged' function:
-
- ---------- Buffer: *Backtrace* ----------
- Debugger entered--entering a function:
- * triangle-bugged(5)
- eval((triangle-bugged 5))
- eval-last-sexp-1(nil)
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
- ---------- Buffer: *Backtrace* ----------
-
-In the `*Backtrace*' buffer, type `d'. Emacs will evaluate the first
-expression in `triangle-bugged'; the buffer will look like this:
-
- ---------- 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))
- eval-last-sexp-1(nil)
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
- ---------- Buffer: *Backtrace* ----------
-
-Now, type `d' again, eight times, slowly. Each time you type `d',
-Emacs will evaluate another expression in the function definition.
-
-Eventually, the buffer will look like this:
-
- ---------- 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)))
- * (let ((total 0)) (while (> number 0) (setq total ...)
- (setq number ...)) total)
- * triangle-bugged(5)
- eval((triangle-bugged 5))
- eval-last-sexp-1(nil)
- eval-last-sexp(nil)
- call-interactively(eval-last-sexp)
- ---------- Buffer: *Backtrace* ----------
-
-Finally, after you type `d' two more times, Emacs will reach the
-error, and the top two lines of the `*Backtrace*' buffer will look
-like this:
-
- ---------- Buffer: *Backtrace* ----------
- Debugger entered--Lisp error: (void-function 1=)
- * (1= number)
- ...
- ---------- Buffer: *Backtrace* ----------
-
-By typing `d', you were able to step through the function.
-
-You can quit a `*Backtrace*' buffer by typing `q' in it; this quits
-the trace, but does not cancel `debug-on-entry'.
-
-To cancel the effect of `debug-on-entry', call
-`cancel-debug-on-entry' and the name of the function, like this:
-
- M-x cancel-debug-on-entry RET triangle-bugged RET
-
-(If you are reading this in Info, cancel `debug-on-entry' now.)
-
-`debug-on-quit' and `(debug)'
-=============================
-
-In addition to setting `debug-on-error' or calling `debug-on-entry',
-there are two other ways to start `debug'.
-
-You can start `debug' whenever you type `C-g' (`keyboard-quit') by
-setting the variable `debug-on-quit' to `t'. This is useful for
-debugging infinite loops.
-
-Or, you can insert a line that says `(debug)' into your code where
-you want the debugger to start, like this:
-
- (defun triangle-bugged (number)
- "Return sum of numbers 1 through NUMBER inclusive."
- (let ((total 0))
- (while (> number 0)
- (setq total (+ total number))
- (debug) ; Start debugger.
- (setq number (1= number))) ; Error here.
- total))
-
-The `debug' function is described in detail in *Note The Lisp
-Debugger: (elisp)Debugger.
-
-The `edebug' Source Level Debugger
-==================================
-
-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 "breakpoint" where execution stops.
-
-Edebug is described in *Note Edebug: (elisp)edebug.
-
-Here is a bugged function definition for `triangle-recursively'.
-*Note Recursion in place of a counter: Recursive triangle function,
-for a review of it.
-
- (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))))) ; Error here.
-
-Normally, you would install this definition by positioning your cursor
-after the function's closing parenthesis and typing `C-x C-e'
-(`eval-last-sexp') or else by positioning your cursor within the
-definition and typing `C-M-x' (`eval-defun'). (By default, the
-`eval-defun' command works only in Emacs Lisp mode or in Lisp
-Interactive mode.)
-
-However, to prepare this function definition for Edebug, you must
-first "instrument" the code using a different command. You can do
-this by positioning your cursor within the definition and typing
-
- M-x edebug-defun RET
-
-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 `C-x C-e' (`eval-last-sexp'):
-
- (triangle-recursively-bugged 3)
-
-You will be jumped back to the source for
-`triangle-recursively-bugged' and the cursor positioned at the
-beginning of the `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 `=>'; in a windowing system, you may see
-the arrowhead as a solid triangle in the window `fringe'.)
-
- =>-!-(if (= number 1)
-
-In the example, the location of point is displayed as `-!-' (in a
-printed book, it is displayed with a five pointed star).
-
-If you now press <SPC>, point will move to the next expression to be
-executed; the line will look like this:
-
- =>(if -!-(= number 1)
-
-As you continue to press <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 `number', you will see the following:
-
- Result: 3 = C-c
-
-This means the value of `number' is 3, which is ASCII `control-c'
-(the third letter of the alphabet).
-
-You can continue moving through the code until you reach the line with
-the error. Before evaluation, that line looks like this:
-
- => -!-(1= number))))) ; Error here.
-
-When you press <SPC> once again, you will produce an error message
-that says:
-
- Symbol's function definition is void: 1=
-
-This is the bug.
-
-Press `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 `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 *Note Edebug: (elisp)edebug.
-
-Debugging Exercises
-===================
-
- * Install the `count-words-region' 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 `d' a
- remarkable number of times. On your system, is a `hook' called
- after the command finishes? (For information on hooks, see
- *Note Command Loop Overview: (elisp)Command Overview.)
-
- * Copy `count-words-region' into the `*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.
-
- * While running Edebug, type `?' to see a list of all the Edebug
- commands. (The `global-edebug-prefix' is usually `C-x X', i.e.
- `<CTL>-x' followed by an upper case `X'; use this prefix for
- commands made outside of the Edebug debugging buffer.)
-
- * In the Edebug debugging buffer, use the `p'
- (`edebug-bounce-point') command to see where in the region the
- `count-words-region' is working.
-
- * Move point to some spot further down function and then type the
- `h' (`edebug-goto-here') command to jump to that location.
-
- * Use the `t' (`edebug-trace-mode') command to cause Edebug to
- walk through the function on its own; use an upper case `T' for
- `edebug-Trace-fast-mode'.
-
- * Set a breakpoint, then run Edebug in Trace mode until it reaches
- the stopping point.
-
-Conclusion
-**********
-
-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 `.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 *Note The GNU Emacs Lisp Reference Manual: (elisp)Top.
-
-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 `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-line and as a typeset, printed book.)
-
-Go to the other on-line help that is part of GNU Emacs: the on-line
-documentation for all functions, and `find-tags', the program that
-takes you to sources.
-
-Here is an example of how I explore the sources. Because of its name,
-`simple.el' is the file I looked at first, a long time ago. As it
-happens some of the functions in `simple.el' are complicated, or at
-least look complicated at first sight. The `open-line' function, for
-example, looks complicated.
-
-You may want to walk through this function slowly, as we did with the
-`forward-sentence' function. (*Note forward-sentence::.) Or you may
-want to skip that function and look at another, such as `split-line'.
-You don't need to read all the functions. According to
-`count-words-in-defun', the `split-line' function contains 27 words
-and symbols.
-
-Even though it is short, `split-line' contains four expressions we
-have not studied: `skip-chars-forward', `indent-to', `current-column'
-and `?\n'.
-
-Consider the `skip-chars-forward' function. (It is part of the
-function definition for `back-to-indentation', which is shown in
-*Note Review: Review.)
-
-In GNU Emacs, you can find out more about `skip-chars-forward' by
-typing `C-h f' (`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
-`indent-to'; or you can look it up, too. Incidentally, the
-`describe-function' function itself is in `help.el'; it is one of
-those long, but decipherable functions. You can look up
-`describe-function' using the `C-h f' command!
-
-In this instance, since the code is Lisp, the `*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 RET key,
-which in this situation is bound to `help-follow', and be taken
-directly to the source, in the same way as `M-.' (`find-tag').
-
-The definition for `describe-function' illustrates how to customize
-the `interactive' expression without using the standard character
-codes; and it shows how to create a temporary buffer.
-
-(The `indent-to' function is written in C rather than Emacs Lisp; it
-is a `built-in' function. `help-follow' only provides you with the
-documentation of a built-in function; it does not take you to the
-source. But `find-tag' will take you to the source, if properly set
-up.)
-
-You can look at a function's source using `find-tag', which is bound
-to `M-.' Finally, you can find out what the Reference Manual has to
-say by visiting the manual in Info, and typing `i' (`Info-index') and
-the name of the function, or by looking up `skip-chars-forward' in
-the index to a printed copy of the manual.
-
-Similarly, you can find out what is meant by `?\n'. You can try
-using `Info-index' with `?\n'. It turns out that this action won't
-help; but don't give up. If you search the index for `\n' without
-the `?', you will be taken directly to the relevant section of the
-manual. (*Note Character Type: (elisp)Character Type. `?\n' stands
-for the newline character.)
-
-Other interesting source files include `paragraphs.el',
-`loaddefs.el', and `loadup.el'. The `paragraphs.el' file includes
-short, easily understood functions as well as longer ones. The
-`loaddefs.el' file contains the many standard autoloads and many
-keymaps. I have never looked at it all; only at parts. `loadup.el'
-is the file that loads the standard parts of Emacs; it tells you a
-great deal about how Emacs is built. (*Note Building Emacs:
-(elisp)Building Emacs, 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 `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.
-
-The `the-the' Function
-**********************
-
-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, `the-the'.
-
-As a first step, you could use the following regular expression to
-search for duplicates:
-
- \\(\\w+[ \t\n]+\\)\\1
-
-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
-*Note Regular Expression Searches: Regexp Search, as well as *Note
-Syntax of Regular Expressions: (emacs)Regexps, and *Note Regular
-Expressions: (elisp)Regular Expressions.)
-
-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+' matches one or more word-constituent characters and `\\W*'
-matches zero or more non-word-constituent characters.
-
- \\(\\(\\w+\\)\\W*\\)\\1
-
-Again, not useful.
-
-Here is the pattern that I use. It is not perfect, but good enough.
-`\\b' matches the empty string, provided it is at the beginning or
-end of a word; `[^@ \n\t]+' matches one or more occurrences of any
-characters that are _not_ an @-sign, space, newline, or tab.
-
- \\b\\([^@ \n\t]+\\)[ \n\t]+\\1\\b
-
-One can write more complicated expressions, but I found that this
-expression is good enough, so I use it.
-
-Here is the `the-the' function, as I include it in my `.emacs' file,
-along with a handy global key binding:
-
- (defun the-the ()
- "Search forward for for a duplicated word."
- (interactive)
- (message "Searching for for duplicated words ...")
- (push-mark)
- ;; 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")))
-
- ;; Bind `the-the' to C-c \
- (global-set-key "\C-c\\" 'the-the)
-
-
-Here is test text:
-
- one two two three four five
- five six seven
-
-You can substitute the other regular expressions shown above in the
-function definition and try each of them on this list.
-
-Handling the Kill Ring
-**********************
-
-The kill ring is a list that is transformed into a ring by the
-workings of the `rotate-yank-pointer' function. The `yank' and
-`yank-pop' commands use the `rotate-yank-pointer' function. This
-appendix describes the `rotate-yank-pointer' function as well as both
-the `yank' and the `yank-pop' commands.
-
-The `rotate-yank-pointer' Function
-==================================
-
-The `rotate-yank-pointer' function changes the element in the kill
-ring to which `kill-ring-yank-pointer' points. For example, it can
-change `kill-ring-yank-pointer' from pointing to the second element
-to point to the third element.
-
-Here is the code for `rotate-yank-pointer':
-
- (defun rotate-yank-pointer (arg)
- "Rotate the yanking point in the kill ring."
- (interactive "p")
- (let ((length (length kill-ring)))
- (if (zerop length)
- ;; then-part
- (error "Kill ring is empty")
- ;; else-part
- (setq kill-ring-yank-pointer
- (nthcdr (% (+ arg
- (- length
- (length
- kill-ring-yank-pointer)))
- length)
- kill-ring)))))
-
-`rotate-yank-pointer' in Outline
---------------------------------
-
-The `rotate-yank-pointer' function looks complex, but as usual, it
-can be understood by taking it apart piece by piece. First look at
-it in skeletal form:
-
- (defun rotate-yank-pointer (arg)
- "Rotate the yanking point in the kill ring."
- (interactive "p")
- (let VARLIST
- BODY...)
-
-This function takes one argument, called `arg'. It has a brief
-documentation string; and it is interactive with a small `p', which
-means that the argument must be a processed prefix passed to the
-function as a number.
-
-The body of the function definition is a `let' expression, which
-itself has a body as well as a VARLIST.
-
-The `let' expression declares a variable that will be only usable
-within the bounds of this function. This variable is called `length'
-and is bound to a value that is equal to the number of items in the
-kill ring. This is done by using the function called `length'.
-(Note that this function has the same name as the variable called
-`length'; but one use of the word is to name the function and the
-other is to name the variable. The two are quite distinct.
-Similarly, an English speaker will distinguish between the meanings
-of the word `ship' when he says: "I must ship this package
-immediately." and "I must get aboard the ship immediately.")
-
-The function `length' tells the number of items there are in a list,
-so `(length kill-ring)' returns the number of items there are in the
-kill ring.
-
-The Body of `rotate-yank-pointer'
----------------------------------
-
-The body of `rotate-yank-pointer' is a `let' expression and the body
-of the `let' expression is an `if' expression.
-
-The purpose of the `if' expression is to find out whether there is
-anything in the kill ring. If the kill ring is empty, the `error'
-function stops evaluation of the function and prints a message in the
-echo area. On the other hand, if the kill ring has something in it,
-the work of the function is done.
-
-Here is the if-part and then-part of the `if' expression:
-
- (if (zerop length) ; if-part
- (error "Kill ring is empty") ; then-part
- ...
-
-If there is not anything in the kill ring, its length must be zero and
-an error message sent to the user: `Kill ring is empty'. The `if'
-expression uses the function `zerop' which returns true if the value
-it is testing is zero. When `zerop' tests true, the then-part of the
-`if' is evaluated. The then-part is a list starting with the
-function `error', which is a function that is similar to the
-`message' function (*note message::), in that it prints a one-line
-message in the echo area. However, in addition to printing a
-message, `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.
-
-Digression about the word `error'
-.................................
-
-(In my opinion, it is slightly misleading, at least to humans, to use
-the term `error' as the name of the `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 labelled 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.)
-
-The else-part of the `if' expression
-....................................
-
-The else-part of the `if' expression is dedicated to setting the
-value of `kill-ring-yank-pointer' when the kill ring has something in
-it. The code looks like this:
-
- (setq kill-ring-yank-pointer
- (nthcdr (% (+ arg
- (- length
- (length kill-ring-yank-pointer)))
- length)
- kill-ring)))))
-
-This needs some examination. Clearly, `kill-ring-yank-pointer' is
-being set to be equal to some CDR of the kill ring, using the
-`nthcdr' function that is described in an earlier section. (*Note
-copy-region-as-kill::.) But exactly how does it do this?
-
-Before looking at the details of the code let's first consider the
-purpose of the `rotate-yank-pointer' function.
-
-The `rotate-yank-pointer' function changes what
-`kill-ring-yank-pointer' points to. If `kill-ring-yank-pointer'
-starts by pointing to the first element of a list, a call to
-`rotate-yank-pointer' causes it to point to the second element; and
-if `kill-ring-yank-pointer' points to the second element, a call to
-`rotate-yank-pointer' causes it to point to the third element. (And
-if `rotate-yank-pointer' is given an argument greater than 1, it
-jumps the pointer that many elements.)
-
-The `rotate-yank-pointer' function uses `setq' to reset what the
-`kill-ring-yank-pointer' points to. If `kill-ring-yank-pointer'
-points to the first element of the kill ring, then, in the simplest
-case, the `rotate-yank-pointer' function must cause it to point to
-the second element. Put another way, `kill-ring-yank-pointer' must
-be reset to have a value equal to the CDR of the kill ring.
-
-That is, under these circumstances,
-
- (setq kill-ring-yank-pointer
- ("some text" "a different piece of text" "yet more text"))
-
- (setq kill-ring
- ("some text" "a different piece of text" "yet more text"))
-
-the code should do this:
-
- (setq kill-ring-yank-pointer (cdr kill-ring))
-
-As a result, the `kill-ring-yank-pointer' will look like this:
-
- kill-ring-yank-pointer
- => ("a different piece of text" "yet more text"))
-
-The actual `setq' expression uses the `nthcdr' function to do the job.
-
-As we have seen before (*note nthcdr::), the `nthcdr' function works
-by repeatedly taking the CDR of a list--it takes the CDR of the CDR
-of the CDR ...
-
-The two following expressions produce the same result:
-
- (setq kill-ring-yank-pointer (cdr kill-ring))
-
- (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
-
-In the `rotate-yank-pointer' function, however, the first argument to
-`nthcdr' is a rather complex looking expression with lots of
-arithmetic inside of it:
-
- (% (+ arg
- (- length
- (length kill-ring-yank-pointer)))
- length)
-
-As usual, we need to look at the most deeply embedded expression first
-and then work our way towards the light.
-
-The most deeply embedded expression is `(length
-kill-ring-yank-pointer)'. This finds the length of the current value
-of the `kill-ring-yank-pointer'. (Remember that the
-`kill-ring-yank-pointer' is the name of a variable whose value is a
-list.)
-
-The measurement of the length is inside the expression:
-
- (- length (length kill-ring-yank-pointer))
-
-In this expression, the first `length' is the variable that was
-assigned the length of the kill ring in the `let' statement at the
-beginning of the function. (One might think this function would be
-clearer if the variable `length' were named `length-of-kill-ring'
-instead; but if you look at the text of the whole function, you will
-see that it is so short that naming this variable `length' is not a
-bother, unless you are pulling the function apart into very tiny
-pieces as we are doing here.)
-
-So the line `(- length (length kill-ring-yank-pointer))' tells the
-difference between the length of the kill ring and the length of the
-list whose name is `kill-ring-yank-pointer'.
-
-To see how all this fits into the `rotate-yank-pointer' function,
-let's begin by analyzing the case where `kill-ring-yank-pointer'
-points to the first element of the kill ring, just as `kill-ring'
-does, and see what happens when `rotate-yank-pointer' is called with
-an argument of 1.
-
-The variable `length' and the value of the expression `(length
-kill-ring-yank-pointer)' will be the same since the variable `length'
-is the length of the kill ring and the `kill-ring-yank-pointer' is
-pointing to the whole kill ring. Consequently, the value of
-
- (- length (length kill-ring-yank-pointer))
-
-will be zero. Since the value of `arg' will be 1, this will mean
-that the value of the whole expression
-
- (+ arg (- length (length kill-ring-yank-pointer)))
-
-will be 1.
-
-Consequently, the argument to `nthcdr' will be found as the result of
-the expression
-
- (% 1 length)
-
-The `%' remainder function
-..........................
-
-To understand `(% 1 length)', we need to understand `%'. According
-to its documentation (which I just found by typing `C-h f % <RET>'),
-the `%' function returns the remainder of its first argument divided
-by its second argument. For example, the remainder of 5 divided by 2
-is 1. (2 goes into 5 twice with a remainder of 1.)
-
-What surprises people who don't often do arithmetic is that a smaller
-number can be divided by a larger number and have a remainder. In the
-example we just used, 5 was divided by 2. We can reverse that and
-ask, what is the result of dividing 2 by 5? If you can use
-fractions, the answer is obviously 2/5 or .4; but if, as here, you
-can only use whole numbers, the result has to be something different.
-Clearly, 5 can go into 2 zero times, but what of the remainder? To
-see what the answer is, consider a case that has to be familiar from
-childhood:
-
- * 5 divided by 5 is 1 with a remainder of 0;
-
- * 6 divided by 5 is 1 with a remainder of 1;
-
- * 7 divided by 5 is 1 with a remainder of 2.
-
- * Similarly, 10 divided by 5 is 2 with a remainder of 0;
-
- * 11 divided by 5 is 2 with a remainder of 1;
-
- * 12 divided by 5 is 1 with a remainder of 2.
-
-By considering the cases as parallel, we can see that
-
- * zero divided by 5 must be zero with a remainder of zero;
-
- * 1 divided by 5 must be zero with a remainder of 1;
-
- * 2 divided by 5 must be zero with a remainder of 2;
-
-and so on.
-
-So, in this code, if the value of `length' is 5, then the result of
-evaluating
-
- (% 1 5)
-
-is 1. (I just checked this by placing the cursor after the expression
-and typing `C-x C-e'. Indeed, 1 is printed in the echo area.)
-
-Using `%' in `rotate-yank-pointer'
-..................................
-
-When the `kill-ring-yank-pointer' points to the beginning of the kill
-ring, and the argument passed to `rotate-yank-pointer' is 1, the `%'
-expression returns 1:
-
- (- length (length kill-ring-yank-pointer))
- => 0
-
-therefore,
-
- (+ arg (- length (length kill-ring-yank-pointer)))
- => 1
-
-and consequently:
-
- (% (+ arg (- length (length kill-ring-yank-pointer)))
- length)
- => 1
-
-regardless of the value of `length'.
-
-As a result of this, the `setq kill-ring-yank-pointer' expression
-simplifies to:
-
- (setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
-
-What it does is now easy to understand. Instead of pointing as it did
-to the first element of the kill ring, the `kill-ring-yank-pointer'
-is set to point to the second element.
-
-Clearly, if the argument passed to `rotate-yank-pointer' is two, then
-the `kill-ring-yank-pointer' is set to `(nthcdr 2 kill-ring)'; and so
-on for different values of the argument.
-
-Similarly, if the `kill-ring-yank-pointer' starts out pointing to the
-second element of the kill ring, its length is shorter than the
-length of the kill ring by 1, so the computation of the remainder is
-based on the expression `(% (+ arg 1) length)'. This means that the
-`kill-ring-yank-pointer' is moved from the second element of the kill
-ring to the third element if the argument passed to
-`rotate-yank-pointer' is 1.
-
-Pointing to the last element
-............................
-
-The final question is, what happens if the `kill-ring-yank-pointer'
-is set to the _last_ element of the kill ring? Will a call to
-`rotate-yank-pointer' mean that nothing more can be taken from the
-kill ring? The answer is no. What happens is different and useful.
-The `kill-ring-yank-pointer' is set to point to the beginning of the
-kill ring instead.
-
-Let's see how this works by looking at the code, assuming the length
-of the kill ring is 5 and the argument passed to
-`rotate-yank-pointer' is 1. When the `kill-ring-yank-pointer' points
-to the last element of the kill ring, its length is 1. The code
-looks like this:
-
- (% (+ arg (- length (length kill-ring-yank-pointer))) length)
-
-When the variables are replaced by their numeric values, the
-expression looks like this:
-
- (% (+ 1 (- 5 1)) 5)
-
-This expression can be evaluated by looking at the most embedded inner
-expression first and working outwards: The value of `(- 5 1)' is 4;
-the sum of `(+ 1 4)' is 5; and the remainder of dividing 5 by 5 is
-zero. So what `rotate-yank-pointer' will do is
-
- (setq kill-ring-yank-pointer (nthcdr 0 kill-ring))
-
-which will set the `kill-ring-yank-pointer' to point to the beginning
-of the kill ring.
-
-So what happens with successive calls to `rotate-yank-pointer' is that
-it moves the `kill-ring-yank-pointer' from element to element in the
-kill ring until it reaches the end; then it jumps back to the
-beginning. And this is why the kill ring is called a ring, since by
-jumping back to the beginning, it is as if the list has no end! (And
-what is a ring, but an entity with no end?)
-
-`yank'
-======
-
-After learning about `rotate-yank-pointer', the code for the `yank'
-function is almost easy. It has only one tricky part, which is the
-computation of the argument to be passed to `rotate-yank-pointer'.
-
-The code looks like this:
-
- (defun yank (&optional arg)
- "Reinsert the last stretch of killed text.
- More precisely, reinsert the stretch of killed text most
- recently killed OR yanked.
- With just C-U as argument, same but put point in front
- (and mark at end). With argument n, reinsert the nth
- most recently killed stretch of killed text.
- See also the command \\[yank-pop]."
-
- (interactive "*P")
- (rotate-yank-pointer (if (listp arg) 0
- (if (eq arg '-) -1
- (1- arg))))
- (push-mark (point))
- (insert (car kill-ring-yank-pointer))
- (if (consp arg)
- (exchange-point-and-mark)))
-
-Glancing over this code, we can understand the last few lines readily
-enough. The mark is pushed, that is, remembered; then the first
-element (the CAR) of what the `kill-ring-yank-pointer' points to is
-inserted; and then, if the argument passed the function is a `cons',
-point and mark are exchanged so the point is put in the front of the
-inserted text rather than at the end. This option is explained in
-the documentation. The function itself is interactive with `"*P"'.
-This means it will not work on a read-only buffer, and that the
-unprocessed prefix argument is passed to the function.
-
-Passing the argument
-....................
-
-The hard part of `yank' is understanding the computation that
-determines the value of the argument passed to `rotate-yank-pointer'.
-Fortunately, it is not so difficult as it looks at first sight.
-
-What happens is that the result of evaluating one or both of the `if'
-expressions will be a number and that number will be the argument
-passed to `rotate-yank-pointer'.
-
-Laid out with comments, the code looks like this:
-
- (if (listp arg) ; if-part
- 0 ; then-part
- (if (eq arg '-) ; else-part, inner if
- -1 ; inner if's then-part
- (1- arg)))) ; inner if's else-part
-
-This code consists of two `if' expression, one the else-part of the
-other.
-
-The first or outer `if' expression tests whether the argument passed
-to `yank' is a list. Oddly enough, this will be true if `yank' is
-called without an argument--because then it will be passed the value
-of `nil' for the optional argument and an evaluation of `(listp nil)'
-returns true! So, if no argument is passed to `yank', the argument
-passed to `rotate-yank-pointer' inside of `yank' is zero. This means
-the pointer is not moved and the first element to which
-`kill-ring-yank-pointer' points is inserted, as we expect.
-Similarly, if the argument for `yank' is `C-u', this will be read as
-a list, so again, a zero will be passed to `rotate-yank-pointer'.
-(`C-u' produces an unprocessed prefix argument of `(4)', which is a
-list of one element.) At the same time, later in the function, this
-argument will be read as a `cons' so point will be put in the front
-and mark at the end of the insertion. (The `P' argument to
-`interactive' is designed to provide these values for the case when
-an optional argument is not provided or when it is `C-u'.)
-
-The then-part of the outer `if' expression handles the case when
-there is no argument or when it is `C-u'. The else-part handles the
-other situations. The else-part is itself another `if' expression.
-
-The inner `if' expression tests whether the argument is a minus sign.
-(This is done by pressing the <META> and `-' keys at the same time,
-or the <ESC> key and then the `-' key). In this case, the
-`rotate-yank-pointer' function is passed `-1' as an argument. This
-moves the `kill-ring-yank-pointer' backwards, which is what is
-desired.
-
-If the true-or-false-test of the inner `if' expression is false (that
-is, if the argument is not a minus sign), the else-part of the
-expression is evaluated. This is the expression `(1- arg)'. Because
-of the two `if' expressions, it will only occur when the argument is
-a positive number or when it is a negative number (not just a minus
-sign on its own). What `(1- arg)' does is decrement the number and
-return it. (The `1-' function subtracts one from its argument.)
-This means that if the argument to `rotate-yank-pointer' is 1, it is
-reduced to zero, which means the first element to which
-`kill-ring-yank-pointer' points is yanked back, as you would expect.
-
-Passing a negative argument
-...........................
-
-Finally, the question arises, what happens if either the remainder
-function, `%', or the `nthcdr' function is passed a negative
-argument, as they quite well may?
-
-The answers can be found by a quick test. When `(% -1 5)' is
-evaluated, a negative number is returned; and if `nthcdr' is called
-with a negative number, it returns the same value as if it were
-called with a first argument of zero. This can be seen by evaluating
-the following code.
-
-Here the `=>' points to the result of evaluating the code preceding
-it. This was done by positioning the cursor after the code and
-typing `C-x C-e' (`eval-last-sexp') in the usual fashion. You can do
-this if you are reading this in Info inside of GNU Emacs.
-
- (% -1 5)
- => -1
-
- (setq animals '(cats dogs elephants))
- => (cats dogs elephants)
-
- (nthcdr 1 animals)
- => (dogs elephants)
-
- (nthcdr 0 animals)
- => (cats dogs elephants)
-
- (nthcdr -1 animals)
- => (cats dogs elephants)
-
-So, if a minus sign or a negative number is passed to `yank', the
-`kill-ring-yank-point' is rotated backwards until it reaches the
-beginning of the list. Then it stays there. Unlike the other case,
-when it jumps from the end of the list to the beginning of the list,
-making a ring, it stops. This makes sense. You often want to get
-back to the most recently clipped out piece of text, but you don't
-usually want to insert text from as many as thirty kill commands ago.
-So you need to work through the ring to get to the end, but won't
-cycle around it inadvertently if you are trying to come back to the
-beginning.
-
-Incidentally, any number passed to `yank' with a minus sign preceding
-it will be treated as -1. This is evidently a simplification for
-writing the program. You don't need to jump back towards the
-beginning of the kill ring more than one place at a time and doing
-this is easier than writing a function to determine the magnitude of
-the number that follows the minus sign.
-
-`yank-pop'
-==========
-
-After understanding `yank', the `yank-pop' function is easy. Leaving
-out the documentation to save space, it looks like this:
-
- (defun yank-pop (arg)
- (interactive "*p")
- (if (not (eq last-command 'yank))
- (error "Previous command was not a yank"))
- (setq this-command 'yank)
- (let ((before (< (point) (mark))))
- (delete-region (point) (mark))
- (rotate-yank-pointer arg)
- (set-mark (point))
- (insert (car kill-ring-yank-pointer))
- (if before (exchange-point-and-mark))))
-
-The function is interactive with a small `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 `last-command' which is discussed elsewhere.
-(*Note copy-region-as-kill::.)
-
-The `let' clause sets the variable `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. Next the `kill-ring-yank-pointer' is rotated so that the
-previously inserted text is not reinserted yet again. Mark is set at
-the beginning of the place the new text will be inserted and then the
-first element to which `kill-ring-yank-pointer' points is inserted.
-This leaves point after the new text. If in the previous yank, point
-was left before the inserted text, point and mark are now exchanged
-so point is again left in front of the newly inserted text. That is
-all there is to it!
-
-A Graph with Labelled Axes
-**************************
-
-Printed axes help you understand a graph. They convey scale. In an
-earlier chapter (*note 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 labelling vertical and horizontal axes, along with the
-body itself.
-
-Labelled Example Graph
-======================
-
-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:
-
- 1. Set up code.
-
- 2. Print Y axis.
-
- 3. Print body of graph.
-
- 4. Print X axis.
-
-Here is an example of how a finished graph should look:
-
- 10 -
- *
- * *
- * **
- * ***
- 5 - * *******
- * *** *******
- *************
- ***************
- 1 - ****************
- | | | |
- 1 5 10 15
-
-In this graph, both the vertical and the horizontal axes are labelled
-with numbers. However, in some graphs, the horizontal axis is time
-and would be better labelled with months, like this:
-
- 5 - *
- * ** *
- *******
- ********** **
- 1 - **************
- | ^ |
- Jan June Jan
-
-Indeed, with a little thought, we can easily come up with a variety of
-vertical and horizontal labelling schemes. Our task could become
-complicated. But complications breed confusion. Rather than permit
-this, it is better choose a simple labelling scheme for our first
-effort, and to modify or replace it later.
-
-These considerations suggest the following outline for the
-`print-graph' function:
-
- (defun print-graph (numbers-list)
- "DOCUMENTATION..."
- (let ((height ...
- ...))
- (print-Y-axis height ... )
- (graph-body-print numbers-list)
- (print-X-axis ... )))
-
-We can work on each part of the `print-graph' function definition in
-turn.
-
-The `print-graph' Varlist
-=========================
-
-In writing the `print-graph' function, the first task is to write the
-varlist in the `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
-`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 `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
-`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 `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 `let' for `print-graph':
-
- (let ((height (apply 'max numbers-list)) ; First version.
- (symbol-width (length graph-blank)))
-
-As we shall see, this expression is not quite right.
-
-The `print-Y-axis' Function
-===========================
-
-The job of the `print-Y-axis' function is to print a label for the
-vertical axis that looks like this:
-
- 10 -
-
-
-
-
- 5 -
-
-
-
- 1 -
-
-The function should be passed the height of the graph, and then should
-construct and insert the appropriate numbers and marks.
-
-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 `1' and the `5' (lines 2, 3, and 4), but four
-lines between the `5' and the `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.
-
-What height should the label be?
---------------------------------
-
-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 `5 -', and should the graph stick up
-above the label? Or should the highest label be `7 -', and mark the
-peak of the graph? Or should the highest label be `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 `(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.
-
-Side Trip: Compute a Remainder
-------------------------------
-
-In Lisp, the function for computing a remainder is `%'. The function
-returns the remainder of its first argument divided by its second
-argument. As it happens, `%' is a function in Emacs Lisp that you
-cannot discover using `apropos': you find nothing if you type `M-x
-apropos <RET> remainder <RET>'. The only way to learn of the
-existence of `%' is to read about it in a book such as this or in the
-Emacs Lisp sources. The `%' function is used in the code for
-`rotate-yank-pointer', which is described in an appendix. (*Note The
-Body of `rotate-yank-pointer': rotate-yk-ptr body.)
-
-You can try the `%' function by evaluating the following two
-expressions:
-
- (% 7 5)
-
- (% 10 5)
-
-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 `zerop' function. This function returns `t' if its
-argument, which must be a number, is zero.
-
- (zerop (% 7 5))
- => nil
-
- (zerop (% 10 5))
- => t
-
-Thus, the following expression will return `t' if the height of the
-graph is evenly divisible by five:
-
- (zerop (% height 5))
-
-(The value of `height', of course, can be found from `(apply 'max
-numbers-list)'.)
-
-On the other hand, if the value of `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 `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:
-
- (* (1+ (/ height 5)) 5)
-
-For example, if you evaluate the following, the result is 15:
-
- (* (1+ (/ 12 5)) 5)
-
-All through this discussion, we have been using `five' as the value
-for spacing labels on the Y axis; but we may want to use some other
-value. For generality, we should replace `five' with a variable to
-which we can assign a value. The best name I can think of for this
-variable is `Y-axis-label-spacing'.
-
-Using this term, and an `if' expression, we produce the following:
-
- (if (zerop (% height Y-axis-label-spacing))
- height
- ;; else
- (* (1+ (/ height Y-axis-label-spacing))
- Y-axis-label-spacing))
-
-This expression returns the value of `height' itself if the height is
-an even multiple of the value of the `Y-axis-label-spacing' or else
-it computes and returns a value of `height' that is equal to the next
-higher multiple of the value of the `Y-axis-label-spacing'.
-
-We can now include this expression in the `let' expression of the
-`print-graph' function (after first setting the value of
-`Y-axis-label-spacing'):
-
- (defvar Y-axis-label-spacing 5
- "Number of lines from one Y axis label to next.")
-
- ...
- (let* ((height (apply 'max numbers-list))
- (height-of-top-line
- (if (zerop (% height Y-axis-label-spacing))
- height
- ;; else
- (* (1+ (/ height Y-axis-label-spacing))
- Y-axis-label-spacing)))
- (symbol-width (length graph-blank))))
- ...
-
-(Note use of the `let*' function: the initial value of height is
-computed once by the `(apply 'max numbers-list)' expression and then
-the resulting value of `height' is used to compute its final value.
-*Note The `let*' expression: fwd-para let, for more about `let*'.)
-
-Construct a Y Axis Element
---------------------------
-
-When we print the vertical axis, we want to insert strings such as
-`5 -' and `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.
-
-To figure out the length of the number, the `length' function is
-used. But the `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 `number-to-string' function.
-For example,
-
- (length (number-to-string 35))
- => 2
-
- (length (number-to-string 100))
- => 3
-
-(`number-to-string' is also called `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 ` - ', which we will call the `Y-axis-tic' marker. This variable
-is defined with `defvar':
-
- (defvar Y-axis-tic " - "
- "String that follows number in a Y axis label.")
-
-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.
-
- (length (concat (number-to-string height) Y-axis-tic)))
-
-This value will be calculated by the `print-graph' function in its
-varlist as `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 `print-graph'.
-
- (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."
- (let* ((leading-spaces
- (- full-Y-label-width
- (length
- (concat (number-to-string number)
- Y-axis-tic)))))
- (concat
- (make-string leading-spaces ? )
- (number-to-string number)
- Y-axis-tic)))
-
-The `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.
-
-Blank spaces are inserted using the `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, `? '. *Note Character Type: (elisp)Character Type,
-for a description of the syntax for characters.
-
-The `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.
-
-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:
-
- (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)
- (while (> height 1)
- (if (zerop (% height Y-axis-label-spacing))
- ;; Insert label.
- (setq Y-axis
- (cons
- (Y-axis-element height width-of-label)
- Y-axis))
- ;; Else, insert blanks.
- (setq Y-axis
- (cons
- (make-string width-of-label ? )
- Y-axis)))
- (setq height (1- height)))
- ;; Insert base line.
- (setq Y-axis
- (cons (Y-axis-element 1 width-of-label) Y-axis))
- (nreverse Y-axis)))
-
-In this function, we start with the value of `height' and
-repetitively subtract one from its value. After each subtraction, we
-test to see whether the value is an integral multiple of the
-`Y-axis-label-spacing'. If it is, we construct a numbered label
-using the `Y-axis-element' function; if not, we construct a blank
-label using the `make-string' function. The base line consists of
-the number one followed by a tic mark.
-
-The Not Quite Final Version of `print-Y-axis'
----------------------------------------------
-
-The list constructed by the `Y-axis-column' function is passed to the
-`print-Y-axis' function, which inserts the list as a column.
-
- (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'.
- (let ((start (point)))
- (insert-rectangle
- (Y-axis-column height full-Y-label-width))
- ;; Place point ready for inserting graph.
- (goto-char start)
- ;; Move point forward by value of full-Y-label-width
- (forward-char full-Y-label-width)))
-
-The `print-Y-axis' uses the `insert-rectangle' function to insert the
-Y axis labels created by the `Y-axis-column' function. In addition,
-it places point at the correct position for printing the body of the
-graph.
-
-You can test `print-Y-axis':
-
- 1. Install
-
- Y-axis-label-spacing
- Y-axis-tic
- Y-axis-element
- Y-axis-column
- print-Y-axis
-
- 2. Copy the following expression:
-
- (print-Y-axis 12 5)
-
- 3. Switch to the `*scratch*' buffer and place the cursor where you
- want the axis labels to start.
-
- 4. Type `M-:' (`eval-expression').
-
- 5. Yank the `graph-body-print' expression into the minibuffer with
- `C-y' (`yank)'.
-
- 6. Press <RET> to evaluate the expression.
-
-Emacs will print labels vertically, the top one being `10 - '. (The
-`print-graph' function will pass the value of `height-of-top-line',
-which in this case would end up as 15.)
-
-The `print-X-axis' Function
-===========================
-
-X axis labels are much like Y axis labels, except that the tics are
-on a line above the numbers. Labels should look like this:
-
- | | | |
- 1 5 10 15
-
-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 tics
-are all spaced equally, according to the value of
-`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
-`X-axis-label-spacing'.
-
-The value of the variable `X-axis-label-spacing' should itself be
-measured in units of `symbol-width', since you may want to change the
-width of the symbols that you are using to print the body of the
-graph without changing the ways the graph is labelled.
-
-Similarities and differences
-----------------------------
-
-The `print-X-axis' function is constructed in more or less the same
-fashion as the `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
-`print-X-axis' function.
-
-This is a three step process:
-
- 1. Write a function to print the X axis tic marks,
- `print-X-axis-tic-line'.
-
- 2. Write a function to print the X numbers,
- `print-X-axis-numbered-line'.
-
- 3. Write a function to print both lines, the `print-X-axis'
- function, using `print-X-axis-tic-line' and
- `print-X-axis-numbered-line'.
-
-X Axis Tic Marks
-----------------
-
-The first function should print the X axis tic marks. We must specify
-the tic marks themselves and their spacing:
-
- (defvar X-axis-label-spacing
- (if (boundp 'graph-blank)
- (* 5 (length graph-blank)) 5)
- "Number of units from one X axis label to next.")
-
-(Note that the value of `graph-blank' is set by another `defvar'.
-The `boundp' predicate checks whether it has already been set;
-`boundp' returns `nil' if it has not. If `graph-blank' were unbound
-and we did not use this conditional construction, in GNU Emacs 21, we
-would enter the debugger and see an error message saying
-`Debugger entered--Lisp error: (void-variable graph-blank)'.)
-
-Here is the `defvar' for `X-axis-tic-symbol':
-
- (defvar X-axis-tic-symbol "|"
- "String to insert to point to a column in X axis.")
-
-The goal is to make a line that looks like this:
-
- | | | |
-
-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 `X-axis-label-spacing'.
-
-The code looks like this:
-
- ;;; X-axis-tic-element
- ...
- (concat
- (make-string
- ;; Make a string of blanks.
- (- (* symbol-width X-axis-label-spacing)
- (length X-axis-tic-symbol))
- ? )
- ;; Concatenate blanks with tic symbol.
- X-axis-tic-symbol)
- ...
-
-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
-`full-Y-label-width' passed it by the `print-graph' function.
-
-The code to make `X-axis-leading-spaces' looks like this:
-
- ;; X-axis-leading-spaces
- ...
- (make-string full-Y-label-width ? )
- ...
-
-We also need to determine the length of the horizontal axis, which is
-the length of the numbers list, and the number of tics in the
-horizontal axis:
-
- ;; X-length
- ...
- (length numbers-list)
-
- ;; tic-width
- ...
- (* symbol-width X-axis-label-spacing)
-
- ;; number-of-X-tics
- (if (zerop (% (X-length tic-width)))
- (/ (X-length tic-width))
- (1+ (/ (X-length tic-width))))
-
-All this leads us directly to the function for printing the X axis
-tic line:
-
- (defun print-X-axis-tic-line
- (number-of-X-tics X-axis-leading-spaces X-axis-tic-element)
- "Print tics for X axis."
- (insert X-axis-leading-spaces)
- (insert X-axis-tic-symbol) ; Under first column.
- ;; Insert second tic in the right spot.
- (insert (concat
- (make-string
- (- (* symbol-width X-axis-label-spacing)
- ;; Insert white space up to second tic symbol.
- (* 2 (length X-axis-tic-symbol)))
- ? )
- X-axis-tic-symbol))
- ;; Insert remaining tics.
- (while (> number-of-X-tics 1)
- (insert X-axis-tic-element)
- (setq number-of-X-tics (1- number-of-X-tics))))
-
-The line of numbers is equally straightforward:
-
-First, we create a numbered element with blank spaces before each
-number:
-
- (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))))
-
-Next, we create the function to print the numbered line, starting with
-the number "1" under the first column:
-
- (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")
- (insert (concat
- (make-string
- ;; Insert white space up to next number.
- (- (* symbol-width X-axis-label-spacing) 2)
- ? )
- (number-to-string number)))
- ;; 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)))))
-
-Finally, we need to write the `print-X-axis' that uses
-`print-X-axis-tic-line' and `print-X-axis-numbered-line'.
-
-The function must determine the local values of the variables used by
-both `print-X-axis-tic-line' and `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:
-
- (defun print-X-axis (numbers-list)
- "Print X axis labels to length of NUMBERS-LIST."
- (let* ((leading-spaces
- (make-string full-Y-label-width ? ))
- ;; symbol-width is provided by graph-body-print
- (tic-width (* symbol-width X-axis-label-spacing))
- (X-length (length numbers-list))
- (X-tic
- (concat
- (make-string
- ;; Make a string of blanks.
- (- (* symbol-width X-axis-label-spacing)
- (length X-axis-tic-symbol))
- ? )
- ;; 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)))))
- (print-X-axis-tic-line tic-number leading-spaces X-tic)
- (insert "\n")
- (print-X-axis-numbered-line tic-number leading-spaces)))
-
-You can test `print-X-axis':
-
- 1. Install `X-axis-tic-symbol', `X-axis-label-spacing',
- `print-X-axis-tic-line', as well as `X-axis-element',
- `print-X-axis-numbered-line', and `print-X-axis'.
-
- 2. Copy the following expression:
-
- (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))))
-
- 3. Switch to the `*scratch*' buffer and place the cursor where you
- want the axis labels to start.
-
- 4. Type `M-:' (`eval-expression').
-
- 5. Yank the test expression into the minibuffer with `C-y' (`yank)'.
-
- 6. Press <RET> to evaluate the expression.
-
-Emacs will print the horizontal axis like this:
-
- | | | | |
- 1 5 10 15 20
-
-Printing the Whole Graph
-========================
-
-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 (*note A Graph with Labelled Axes: Full
-Graph.), but with additions.
-
-Here is the outline:
-
- (defun print-graph (numbers-list)
- "DOCUMENTATION..."
- (let ((height ...
- ...))
- (print-Y-axis height ... )
- (graph-body-print numbers-list)
- (print-X-axis ... )))
-
-Changes for the Final Version
------------------------------
-
-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.
-
-This new feature requires a change to the `Y-axis-column' function,
-to add `vertical-step' to it. The function looks like this:
-
- ;;; 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."
- (let (Y-axis
- (number-per-line (or vertical-step 1)))
- (while (> height 1)
- (if (zerop (% height Y-axis-label-spacing))
- ;; Insert label.
- (setq Y-axis
- (cons
- (Y-axis-element
- (* height number-per-line)
- width-of-label)
- Y-axis))
- ;; Else, insert blanks.
- (setq Y-axis
- (cons
- (make-string width-of-label ? )
- Y-axis)))
- (setq height (1- height)))
- ;; Insert base line.
- (setq Y-axis (cons (Y-axis-element
- (or vertical-step 1)
- width-of-label)
- Y-axis))
- (nreverse Y-axis)))
-
-The values for the maximum height of graph and the width of a symbol
-are computed by `print-graph' in its `let' expression; so
-`graph-body-print' must be changed to accept them.
-
- ;;; 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."
- (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)
- ;; Draw graph column by column.
- (sit-for 0)
- (setq numbers-list (cdr numbers-list)))
- ;; Place point for X axis labels.
- (forward-line height)
- (insert "\n")))
-
-Finally, the code for the `print-graph' function:
-
- ;;; Final version.
- (defun print-graph
- (numbers-list &optional vertical-step)
- "Print labelled bar graph of the NUMBERS-LIST.
- The numbers-list consists of the Y-axis values.
-
- 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."
- (let* ((symbol-width (length graph-blank))
- ;; `height' is both the largest number
- ;; and the number with the most digits.
- (height (apply 'max numbers-list))
- (height-of-top-line
- (if (zerop (% height Y-axis-label-spacing))
- height
- ;; else
- (* (1+ (/ height Y-axis-label-spacing))
- Y-axis-label-spacing)))
- (vertical-step (or vertical-step 1))
- (full-Y-label-width
- (length
- (concat
- (number-to-string
- (* height-of-top-line vertical-step))
- Y-axis-tic))))
-
- (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)))
-
-Testing `print-graph'
----------------------
-
-We can test the `print-graph' function with a short list of numbers:
-
- 1. Install the final versions of `Y-axis-column',
- `graph-body-print', and `print-graph' (in addition to the rest
- of the code.)
-
- 2. Copy the following expression:
-
- (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1))
-
- 3. Switch to the `*scratch*' buffer and place the cursor where you
- want the axis labels to start.
-
- 4. Type `M-:' (`eval-expression').
-
- 5. Yank the test expression into the minibuffer with `C-y' (`yank)'.
-
- 6. Press <RET> to evaluate the expression.
-
-Emacs will print a graph that looks like this:
-
- 10 -
-
-
- *
- ** *
- 5 - **** *
- **** ***
- * *********
- ************
- 1 - *************
-
- | | | |
- 1 5 10 15
-
-On the other hand, if you pass `print-graph' a `vertical-step' value
-of 2, by evaluating this expression:
-
- (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2)
-
-The graph looks like this:
-
- 20 -
-
-
- *
- ** *
- 10 - **** *
- **** ***
- * *********
- ************
- 2 - *************
-
- | | | |
- 1 5 10 15
-
-(A question: is the `2' on the bottom of the vertical axis a bug or a
-feature? If you think it is a bug, and should be a `1' instead, (or
-even a `0'), you can modify the sources.)
-
-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.
-
-It is a good idea to reset the value of `top-of-ranges' in case you
-have set it to some different value. You can evaluate the following:
-
- (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)
-
-Next create a list of the number of words and symbols in each range.
-
-Evaluate the following:
-
- (setq list-for-graph
- (defuns-per-range
- (sort
- (recursive-lengths-list-many-files
- (directory-files "/usr/local/emacs/lisp"
- t ".+el$"))
- '<)
- top-of-ranges))
-
-On my machine, this takes about an hour. It looks though 303 Lisp
-files in my copy of Emacs version 19.23. After all that computing,
-the `list-for-graph' has this value:
-
- (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)
-
-This means that my copy of Emacs has 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 _not_ want to print a graph that is 1,030
-lines high ... 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 `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, `mapcar' and `lambda'.
-
- (defun one-fiftieth (full-range)
- "Return list, each number one-fiftieth of previous."
- (mapcar '(lambda (arg) (/ arg 50)) full-range))
-
-A `lambda' Expression: Useful Anonymity
----------------------------------------
-
-`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.
-
-Thus,
-
- (lambda (arg) (/ arg 50))
-
-is a function definition that says `return the value resulting from
-dividing whatever is passed to me as `arg' by 50'.
-
-Earlier, for example, we had a function `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 `multiply-by-seven' is:
-
- (lambda (number) (* 7 number))
-
-(*Note The `defun' Special Form: defun.)
-
-If we want to multiply 3 by 7, we can write:
-
- (multiply-by-seven 3)
- \_______________/ ^
- | |
- function argument
-
-
-
-This expression returns 21.
-
-Similarly, we can write:
-
- ((lambda (number) (* 7 number)) 3)
- \____________________________/ ^
- | |
- anonymous function argument
-
-
-
-If we want to divide 100 by 50, we can write:
-
- ((lambda (arg) (/ arg 50)) 100)
- \______________________/ \_/
- | |
- anonymous function argument
-
-
-
-This expression returns 2. The 100 is passed to the function, which
-divides that number by 50.
-
-*Note Lambda Expressions: (elisp)Lambda Expressions, for more about
-`lambda'. Lisp and lambda expressions derive from the Lambda
-Calculus.
-
-The `mapcar' Function
----------------------
-
-`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 `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 `car', of course, comes from the Lisp notion of the
-first of a list.
-
-For example,
-
- (mapcar '1+ '(2 4 6))
- => (3 5 7)
-
-The function `1+' which adds one to its argument, is executed on
-_each_ element of the list, and a new list is returned.
-
-Contrast this with `apply', which applies its first argument to all
-the remaining. (*Note Readying a Graph: Readying a Graph, for a
-explanation of `apply'.)
-
-In the definition of `one-fiftieth', the first argument is the
-anonymous function:
-
- (lambda (arg) (/ arg 50))
-
-and the second argument is `full-range', which will be bound to
-`list-for-graph'.
-
-The whole expression looks like this:
-
- (mapcar '(lambda (arg) (/ arg 50)) full-range))
-
-*Note Mapping Functions: (elisp)Mapping Functions, for more about
-`mapcar'.
-
-Using the `one-fiftieth' function, we can generate a list in which
-each element is one-fiftieth the size of the corresponding element in
-`list-for-graph'.
-
- (setq fiftieth-list-for-graph
- (one-fiftieth list-for-graph))
-
-The resulting list looks like this:
-
- (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)
-
-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.)
-
-Another Bug ... Most Insidious
-------------------------------
-
-I said `almost ready to print'! Of course, there is a bug in the
-`print-graph' function ... It has a `vertical-step' option, but not
-a `horizontal-step' option. The `top-of-range' scale goes from 10 to
-300 by tens. But the `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, _will_ be rewritten, if not soon,
-eventually. A hard maxim to follow.
-
-It is the `print-X-axis-numbered-line' function that needs the work;
-and then the `print-X-axis' and the `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.
-
-Here is the corrected `print-X-axis-numbered-line':
-
- (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)))
- (insert X-axis-leading-spaces)
- ;; Delete extra leading spaces.
- (delete-char
- (- (1-
- (length (number-to-string horizontal-step)))))
- (insert (concat
- (make-string
- ;; Insert white space.
- (- (* symbol-width
- X-axis-label-spacing)
- (1-
- (length
- (number-to-string horizontal-step)))
- 2)
- ? )
- (number-to-string
- (* number horizontal-step))))
- ;; 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)))))
-
-If you are reading this in Info, you can see the new versions of
-`print-X-axis' `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).
-
- (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."
- ;; 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 is provided by graph-body-print
- (tic-width (* symbol-width X-axis-label-spacing))
- (X-length (length numbers-list))
- (X-tic
- (concat
- (make-string
- ;; Make a string of blanks.
- (- (* symbol-width X-axis-label-spacing)
- (length X-axis-tic-symbol))
- ? )
- ;; 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)))))
-
- (print-X-axis-tic-line
- tic-number leading-spaces X-tic)
- (insert "\n")
- (print-X-axis-numbered-line
- tic-number leading-spaces horizontal-step)))
-
- (defun print-graph
- (numbers-list &optional vertical-step horizontal-step)
- "Print labelled bar graph of the NUMBERS-LIST.
- The numbers-list consists of the Y-axis values.
-
- 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.
-
- Optionally, HORIZONTAL-STEP, a positive integer,
- specifies how much an X axis label increments for
- each column."
- (let* ((symbol-width (length graph-blank))
- ;; `height' is both the largest number
- ;; and the number with the most digits.
- (height (apply 'max numbers-list))
- (height-of-top-line
- (if (zerop (% height Y-axis-label-spacing))
- height
- ;; else
- (* (1+ (/ height Y-axis-label-spacing))
- Y-axis-label-spacing)))
- (vertical-step (or vertical-step 1))
- (full-Y-label-width
- (length
- (concat
- (number-to-string
- (* height-of-top-line vertical-step))
- Y-axis-tic))))
- (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)))
-
-The Printed Graph
------------------
-
-When made and installed, you can call the `print-graph' command like
-this:
-
- (print-graph fiftieth-list-for-graph 50 10)
-
-Here is the graph:
-
-
-
- 1000 - *
- **
- **
- **
- **
- 750 - ***
- ***
- ***
- ***
- ****
- 500 - *****
- ******
- ******
- ******
- *******
- 250 - ********
- ********* *
- *********** *
- ************* *
- 50 - ***************** * *
- | | | | | | | |
- 10 50 100 150 200 250 300 350
-
-
-
-The largest group of functions contain 10 - 19 words and symbols each.
-
-GNU Free Documentation License
-******************************
-
- Version 1.1, March 2000
- Copyright (C) 2000 Free Software Foundation, Inc.
- 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
-
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
- 0. PREAMBLE
-
- The purpose of this License is to make a manual, textbook, or
- other written document "free" in the sense of freedom: to assure
- everyone the effective freedom to copy and redistribute it, with
- or without modifying it, either commercially or noncommercially.
- Secondarily, this License preserves for the author and
- publisher a way to get credit for their work, while not being
- considered responsible for modifications made by others.
-
- This License is a kind of "copyleft", which means that derivative
- works of the document must themselves be free in the same sense.
- It complements the GNU General Public License, which is a
- copyleft license designed for free software.
-
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same
- freedoms that the software does. But this License is not
- limited to software manuals; it can be used for any textual
- work, regardless of subject matter or whether it is published as
- a printed book. We recommend this License principally for works
- whose purpose is instruction or reference.
-
- 1. APPLICABILITY AND DEFINITIONS
-
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be
- distributed under the terms of this License. The "Document",
- below, refers to any such manual or work. Any member of the
- public is a licensee, and is addressed as "you".
-
- A "Modified Version" of the Document means any work containing
- the Document or a portion of it, either copied verbatim, or with
- modifications and/or translated into another language.
-
- A "Secondary Section" is a named appendix or a front-matter
- section of the Document that deals exclusively with the
- relationship of the publishers or authors of the Document to the
- Document's overall subject (or to related matters) and contains
- nothing that could fall directly within that overall subject.
- (For example, if the Document is in part a textbook of
- mathematics, a Secondary Section may not explain any
- mathematics.) The relationship could be a matter of historical
- connection with the subject or with related matters, or of legal,
- commercial, philosophical, ethical or political position
- regarding them.
-
- The "Invariant Sections" are certain Secondary Sections whose
- titles are designated, as being those of Invariant Sections, in
- the notice that says that the Document is released under this
- License.
-
- The "Cover Texts" are certain short passages of text that are
- listed, as Front-Cover Texts or Back-Cover Texts, in the notice
- that says that the Document is released under this License.
-
- A "Transparent" copy of the Document means a machine-readable
- copy, represented in a format whose specification is available
- to the general public, whose contents can be viewed and edited
- directly and straightforwardly with generic text editors or (for
- images composed of pixels) generic paint programs or (for
- drawings) some widely available drawing editor, and that is
- suitable for input to text formatters or for automatic
- translation to a variety of formats suitable for input to text
- formatters. A copy made in an otherwise Transparent file format
- whose markup has been designed to thwart or discourage
- subsequent modification by readers is not Transparent. A copy
- that is not "Transparent" is called "Opaque".
-
- Examples of suitable formats for Transparent copies include plain
- ASCII without markup, Texinfo input format, LaTeX input format,
- SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human modification.
- Opaque formats include PostScript, PDF, proprietary formats
- that can be read and edited only by proprietary word processors,
- SGML or XML for which the DTD and/or processing tools are not
- generally available, and the machine-generated HTML produced by
- some word processors for output purposes only.
-
- The "Title Page" means, for a printed book, the title page
- itself, plus such following pages as are needed to hold,
- legibly, the material this License requires to appear in the
- title page. For works in formats which do not have any title
- page as such, "Title Page" means the text near the most
- prominent appearance of the work's title, preceding the
- beginning of the body of the text.
-
- 2. VERBATIM COPYING
-
- You may copy and distribute the Document in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that
- you add no other conditions whatsoever to those of this License.
- You may not use technical measures to obstruct or control the
- reading or further copying of the copies you make or distribute.
- However, you may accept compensation in exchange for copies.
- If you distribute a large enough number of copies you must also
- follow the conditions in section 3.
-
- You may also lend copies, under the same conditions stated
- above, and you may publicly display copies.
-
- 3. COPYING IN QUANTITY
-
- If you publish printed copies of the Document numbering more
- than 100, and the Document's license notice requires Cover
- Texts, you must enclose the copies in covers that carry, clearly
- and legibly, all these Cover Texts: Front-Cover Texts on the
- front cover, and Back-Cover Texts on the back cover. Both
- covers must also clearly and legibly identify you as the
- publisher of these copies. The front cover must present the
- full title with all words of the title equally prominent and
- visible. You may add other material on the covers in addition.
- Copying with changes limited to the covers, as long as they
- preserve the title of the Document and satisfy these conditions,
- can be treated as verbatim copying in other respects.
-
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
-
- If you publish or distribute Opaque copies of the Document
- numbering more than 100, you must either include a
- machine-readable Transparent copy along with each Opaque copy,
- or state in or with each Opaque copy a publicly-accessible
- computer-network location containing a complete Transparent copy
- of the Document, free of added material, which the general
- network-using public has access to download anonymously at no
- charge using public-standard network protocols. If you use the
- latter option, you must take reasonably prudent steps, when you
- begin distribution of Opaque copies in quantity, to ensure that
- this Transparent copy will remain thus accessible at the stated
- location until at least one year after the last time you
- distribute an Opaque copy (directly or through your agents or
- retailers) of that edition to the public.
-
- It is requested, but not required, that you contact the authors
- of the Document well before redistributing any large number of
- copies, to give them a chance to provide you with an updated
- version of the Document.
-
- 4. MODIFICATIONS
-
- You may copy and distribute a Modified Version of the Document
- under the conditions of sections 2 and 3 above, provided that
- you release the Modified Version under precisely this License,
- with the Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version
- to whoever possesses a copy of it. In addition, you must do
- these things in the Modified Version:
-
- A. Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of
- previous versions (which should, if there were any, be
- listed in the History section of the Document). You may
- use the same title as a previous version if the original
- publisher of that version gives permission.
-
- B. List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in
- the Modified Version, together with at least five of the
- principal authors of the Document (all of its principal
- authors, if it has less than five).
-
- C. State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
-
- D. Preserve all the copyright notices of the Document.
-
- E. Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
-
- F. Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified
- Version under the terms of this License, in the form shown
- in the Addendum below.
-
- G. Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's
- license notice.
-
- H. Include an unaltered copy of this License.
-
- I. Preserve the section entitled "History", and its title, and
- add to it an item stating at least the title, year, new
- authors, and publisher of the Modified Version as given on
- the Title Page. If there is no section entitled "History"
- in the Document, create one stating the title, year,
- authors, and publisher of the Document as given on its
- Title Page, then add an item describing the Modified
- Version as stated in the previous sentence.
-
- J. Preserve the network location, if any, given in the
- Document for public access to a Transparent copy of the
- Document, and likewise the network locations given in the
- Document for previous versions it was based on. These may
- be placed in the "History" section. You may omit a network
- location for a work that was published at least four years
- before the Document itself, or if the original publisher of
- the version it refers to gives permission.
-
- K. In any section entitled "Acknowledgments" or "Dedications",
- preserve the section's title, and preserve in the section
- all the substance and tone of each of the contributor
- acknowledgments and/or dedications given therein.
-
- L. Preserve all the Invariant Sections of the Document,
- unaltered in their text and in their titles. Section
- numbers or the equivalent are not considered part of the
- section titles.
-
- M. Delete any section entitled "Endorsements". Such a section
- may not be included in the Modified Version.
-
- N. Do not retitle any existing section as "Endorsements" or to
- conflict in title with any Invariant Section.
-
- If the Modified Version includes new front-matter sections or
- appendices that qualify as Secondary Sections and contain no
- material copied from the Document, you may at your option
- designate some or all of these sections as invariant. To do
- this, add their titles to the list of Invariant Sections in the
- Modified Version's license notice. These titles must be
- distinct from any other section titles.
-
- You may add a section entitled "Endorsements", provided it
- contains nothing but endorsements of your Modified Version by
- various parties--for example, statements of peer review or that
- the text has been approved by an organization as the
- authoritative definition of a standard.
-
- You may add a passage of up to five words as a Front-Cover Text,
- and a passage of up to 25 words as a Back-Cover Text, to the end
- of the list of Cover Texts in the Modified Version. Only one
- passage of Front-Cover Text and one of Back-Cover Text may be
- added by (or through arrangements made by) any one entity. If
- the Document already includes a cover text for the same cover,
- previously added by you or by arrangement made by the same
- entity you are acting on behalf of, you may not add another; but
- you may replace the old one, on explicit permission from the
- previous publisher that added the old one.
-
- The author(s) and publisher(s) of the Document do not by this
- License give permission to use their names for publicity for or
- to assert or imply endorsement of any Modified Version.
-
- 5. COMBINING DOCUMENTS
-
- You may combine the Document with other documents released under
- this License, under the terms defined in section 4 above for
- modified versions, provided that you include in the combination
- all of the Invariant Sections of all of the original documents,
- unmodified, and list them all as Invariant Sections of your
- combined work in its license notice.
-
- The combined work need only contain one copy of this License, and
- multiple identical Invariant Sections may be replaced with a
- single copy. If there are multiple Invariant Sections with the
- same name but different contents, make the title of each such
- section unique by adding at the end of it, in parentheses, the
- name of the original author or publisher of that section if
- known, or else a unique number. Make the same adjustment to the
- section titles in the list of Invariant Sections in the license
- notice of the combined work.
-
- In the combination, you must combine any sections entitled
- "History" in the various original documents, forming one section
- entitled "History"; likewise combine any sections entitled
- "Acknowledgments", and any sections entitled "Dedications". You
- must delete all sections entitled "Endorsements."
-
- 6. COLLECTIONS OF DOCUMENTS
-
- You may make a collection consisting of the Document and other
- documents released under this License, and replace the
- individual copies of this License in the various documents with
- a single copy that is included in the collection, provided that
- you follow the rules of this License for verbatim copying of
- each of the documents in all other respects.
-
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you
- insert a copy of this License into the extracted document, and
- follow this License in all other respects regarding verbatim
- copying of that document.
-
- 7. AGGREGATION WITH INDEPENDENT WORKS
-
- A compilation of the Document or its derivatives with other
- separate and independent documents or works, in or on a volume
- of a storage or distribution medium, does not as a whole count
- as a Modified Version of the Document, provided no compilation
- copyright is claimed for the compilation. Such a compilation is
- called an "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document, on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document.
-
- If the Cover Text requirement of section 3 is applicable to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may
- be placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the
- whole aggregate.
-
- 8. TRANSLATION
-
- Translation is considered a kind of modification, so you may
- distribute translations of the Document under the terms of
- section 4. Replacing Invariant Sections with translations
- requires special permission from their copyright holders, but
- you may include translations of some or all Invariant Sections
- in addition to the original versions of these Invariant
- Sections. You may include a translation of this License
- provided that you also include the original English version of
- this License. In case of a disagreement between the translation
- and the original English version of this License, the original
- English version will prevail.
-
- 9. TERMINATION
-
- You may not copy, modify, sublicense, or distribute the Document
- except as expressly provided for under this License. Any other
- attempt to copy, modify, sublicense or distribute the Document
- is void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights,
- from you under this License will not have their licenses
- terminated so long as such parties remain in full compliance.
-
- 10. FUTURE REVISIONS OF THIS LICENSE
-
- The Free Software Foundation may publish new, revised versions
- of the GNU Free Documentation License from time to time. Such
- new versions will be similar in spirit to the present version,
- but may differ in detail to address new problems or concerns.
- See `http://www.gnu.org/copyleft/'.
-
- Each version of the License is given a distinguishing version
- number. If the Document specifies that a particular numbered
- version of this License "or any later version" applies to it,
- you have the option of following the terms and conditions either
- of that specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by
- the Free Software Foundation.
-
-Index
-*****
-
-% (remainder function):
- See ``Side Trip: Compute a Remainder''.
-(debug) in code:
- See ```debug-on-quit' and `(debug)'''.
-* (multiplication):
- See ``The `defun' Special Form''.
-* for read-only buffer:
- See ``A Read-only Buffer''.
-*scratch* buffer:
- See ``An Example: `print-elements-of-list'''.
-.emacs file:
- See ``Your `.emacs' File''.
-.emacs file, beginning of:
- See ``Beginning a `.emacs' File''.
-/ (division):
- See ``What happens in a large buffer''.
-<= (less than or equal):
- See ``The parts of the function definition''.
-> (greater than):
- See ```if' in more detail''.
-Accumulate, type of recursive pattern:
- See ``Recursive Pattern: _accumulate_''.
-add-hook:
- See ``Text and Auto Fill Mode''.
-and <1>:
- See ``The `let*' expression''.
-and:
- See ``The `kill-new' function''.
-and, introduced:
- See ``The `kill-new' function''.
-Anonymous function:
- See ``A `lambda' Expression: Useful Anonymity''.
-append-to-buffer:
- See ``The Definition of `append-to-buffer'''.
-apply:
- See ``Printing the Columns of a Graph''.
-apropos:
- See ``Printing the Columns of a Graph''.
-Argument as local variable:
- See ``Putting the function definition together''.
-argument defined:
- See ``Arguments''.
-argument list defined:
- See ``The `defun' Special Form''.
-Argument, wrong type of:
- See ``Using the Wrong Type Object as an Argument''.
-Arguments:
- See ``Arguments''.
-Arguments' data types:
- See ``Arguments' Data Types''.
-Arguments, variable number of:
- See ``Variable Number of Arguments''.
-Asterisk for read-only buffer:
- See ``A Read-only Buffer''.
-Auto Fill mode turned on:
- See ``Text and Auto Fill Mode''.
-autoload:
- See ``Autoloading''.
-Automatic mode selection:
- See ``Text and Auto Fill Mode''.
-Axis, print horizontal:
- See ``The `print-X-axis' Function''.
-Axis, print vertical:
- See ``The `print-Y-axis' Function''.
-beginning-of-buffer:
- See ``Complete Definition of `beginning-of-buffer'''.
-bind defined:
- See ``Setting the Value of a Variable''.
-body defined:
- See ``The `defun' Special Form''.
-Body of graph:
- See ``Readying a Graph''.
-Buffer size:
- See ``Buffer Size and the Location of Point''.
-Buffer, history of word:
- See ``Buffer Names''.
-buffer-file-name:
- See ``Buffer Names''.
-buffer-menu, bound to key:
- See ``Some Keybindings''.
-buffer-name:
- See ``Buffer Names''.
-Bug, most insidious type:
- See ``Another Bug ... Most Insidious''.
-Building robots:
- See ``Building Robots: Extending the Metaphor''.
-Building Tags in the Emacs sources:
- See ``Create Your Own `TAGS' File''.
-Byte compiling:
- See ``Byte Compiling''.
-C language primitives:
- See ``An Aside about Primitive Functions''.
-C, a digression into:
- See ``Digression into C''.
-call defined:
- See ``Switching Buffers''.
-cancel-debug-on-entry:
- See ```debug-on-entry'''.
-car, introduced:
- See ```car', `cdr', `cons': Fundamental Functions''.
-cdr, introduced:
- See ```car', `cdr', `cons': Fundamental Functions''.
-Changing a function definition:
- See ``Change a Function Definition''.
-Chest of Drawers, metaphor for a symbol:
- See ``Symbols as a Chest of Drawers''.
-Clipping text:
- See ``Cutting and Storing Text''.
-Code installation:
- See ``Install Code Permanently''.
-command defined:
- See ``How to Evaluate''.
-Comments in Lisp code:
- See ``Change a Function Definition''.
-Common Lisp:
- See ``Lisp History''.
-compare-windows:
- See ``Some Keybindings''.
-concat:
- See ``Arguments' Data Types''.
-cond:
- See ``Recursion Example Using `cond'''.
-condition-case:
- See ```condition-case'''.
-Conditional 'twixt two versions of Emacs:
- See ``A Simple Extension: `line-to-top-of-window'''.
-Conditional with if:
- See ``The `if' Special Form''.
-cons, example:
- See ``The `kill-new' function''.
-cons, introduced:
- See ```cons'''.
-copy-region-as-kill:
- See ```copy-region-as-kill'''.
-copy-to-buffer:
- See ``The Definition of `copy-to-buffer'''.
-Count words recursively:
- See ``Count Words Recursively''.
-count-words-in-defun:
- See ``The `count-words-in-defun' Function''.
-count-words-region:
- See ``The `count-words-region' Function''.
-Counting:
- See ``Counting''.
-Counting words in a defun <1>:
- See ``The `count-words-in-defun' Function''.
-Counting words in a defun:
- See ``Counting Words in a `defun'''.
-current-buffer:
- See ``Getting Buffers''.
-Customizing your .emacs file:
- See ``Your `.emacs' File''.
-Cutting and storing text:
- See ``Cutting and Storing Text''.
-Data types:
- See ``Arguments' Data Types''.
-debug:
- See ```debug'''.
-debug-on-entry:
- See ```debug-on-entry'''.
-debug-on-quit:
- See ```debug-on-quit' and `(debug)'''.
-debugging:
- See ``Debugging''.
-default-mode-line-format:
- See ``A Modified Mode Line''.
-default.el init file:
- See ``Site-wide Initialization Files''.
-defcustom:
- See ``Specifying Variables using `defcustom'''.
-Deferment in recursion:
- See ``Recursion without Deferments''.
-Defermentless solution:
- See ``No Deferment Solution''.
-Definition installation:
- See ``Install a Function Definition''.
-Definition writing:
- See ``How To Write Function Definitions''.
-Definition, how to change:
- See ``Change a Function Definition''.
-defun:
- See ``The `defun' Special Form''.
-defvar:
- See ``Initializing a Variable with `defvar'''.
-defvar for a user customizable variable:
- See ```defvar' and an asterisk''.
-defvar with an asterisk:
- See ```defvar' and an asterisk''.
-delete-and-extract-region <1>:
- See ``Digression into C''.
-delete-and-extract-region:
- See ```delete-and-extract-region'''.
-Deleting text:
- See ``Cutting and Storing Text''.
-describe-function:
- See ``A Simplified `beginning-of-buffer' Definition''.
-describe-function, introduced:
- See ``Finding More Information''.
-Digression into C:
- See ``Digression into C''.
-directory-files:
- See ``Making a List of Files''.
-Division:
- See ``What happens in a large buffer''.
-dolist:
- See ``The `dolist' Macro''.
-dotimes:
- See ``The `dotimes' Macro''.
-Drawers, Chest of, metaphor for a symbol:
- See ``Symbols as a Chest of Drawers''.
-Duplicated words function:
- See ``The `the-the' Function''.
-edebug:
- See ``The `edebug' Source Level Debugger''.
-edit-options:
- See ```defvar' and an asterisk''.
-Else:
- See ``If-then-else Expressions''.
-Emacs version, choosing:
- See ``A Simple Extension: `line-to-top-of-window'''.
-empty list defined:
- See ``Lisp Atoms''.
-empty string defined:
- See ``Review''.
-eobp:
- See ``Between paragraphs''.
-eq:
- See ``Review''.
-eq (example of use):
- See ```last-command' and `this-command'''.
-equal:
- See ``Review''.
-Erasing text:
- See ``Cutting and Storing Text''.
-error:
- See ``The Body of `rotate-yank-pointer'''.
-Error for symbol without function:
- See ``Error Message for a Symbol Without a Function''.
-Error for symbol without value:
- See ``Error Message for a Symbol Without a Value''.
-Error message generation:
- See ``Generate an Error Message''.
-etags:
- See ``Create Your Own `TAGS' File''.
-evaluate defined:
- See ``Run a Program''.
-Evaluating inner lists:
- See ``Evaluating Inner Lists''.
-Evaluation:
- See ``Evaluation''.
-Evaluation practice:
- See ``Practicing Evaluation''.
-Every, type of recursive pattern:
- See ``Recursive Pattern: _every_''.
-Example variable, fill-column:
- See ```fill-column', an Example Variable''.
-expression defined:
- See ``Lisp Atoms''.
-Falsehood and truth in Emacs Lisp:
- See ``Truth and Falsehood in Emacs Lisp''.
-FDL, GNU Free Documentation License:
- See ``GNU Free Documentation License''.
-files-in-below-directory:
- See ``Making a List of Files''.
-fill-column, an example variable:
- See ```fill-column', an Example Variable''.
-Find a File:
- See ``Find a File''.
-Find function documentation:
- See ``Finding More Information''.
-Find source of function:
- See ``Finding More Information''.
-find-tags:
- See ``Finding More Information''.
-Flowers in a field:
- See ``Lisp Lists''.
-Focusing attention (narrowing):
- See ``Narrowing and Widening''.
-form defined:
- See ``Lisp Atoms''.
-Formatting convention:
- See ```save-excursion' in `append-to-buffer'''.
-Formatting help:
- See ``GNU Emacs Helps You Type Lists''.
-forward-paragraph:
- See ```forward-paragraph': a Goldmine of Functions''.
-forward-sentence:
- See ```forward-sentence'''.
-function defined:
- See ``Generate an Error Message''.
-function definition defined:
- See ``The `defun' Special Form''.
-Function definition installation:
- See ``Install a Function Definition''.
-Function definition writing:
- See ``How To Write Function Definitions''.
-Function definition, how to change:
- See ``Change a Function Definition''.
-Functions, primitive:
- See ``An Aside about Primitive Functions''.
-Generate an error message:
- See ``Generate an Error Message''.
-Getting a buffer:
- See ``Getting Buffers''.
-Global set key:
- See ``Some Keybindings''.
-global-set-key:
- See ``Some Keybindings''.
-global-unset-key:
- See ``Some Keybindings''.
-Graph prototype:
- See ``Readying a Graph''.
-Graph, printing all:
- See ``Printing the Whole Graph''.
-graph-body-print:
- See ``The `graph-body-print' Function''.
-graph-body-print Final version.:
- See ``Changes for the Final Version''.
-Handling the kill ring:
- See ``Handling the Kill Ring''.
-Help typing lists:
- See ``GNU Emacs Helps You Type Lists''.
-Horizontal axis printing:
- See ``The `print-X-axis' Function''.
-if:
- See ``The `if' Special Form''.
-if-part defined:
- See ```if' in more detail''.
-indent-tabs-mode:
- See ``Indent Tabs Mode''.
-Indentation for formatting:
- See ```save-excursion' in `append-to-buffer'''.
-Initialization file:
- See ``Your `.emacs' File''.
-Initializing a variable:
- See ``Initializing a Variable with `defvar'''.
-Inner list evaluation:
- See ``Evaluating Inner Lists''.
-insert-buffer:
- See ``The Definition of `insert-buffer'''.
-insert-buffer-substring:
- See ``An Overview of `append-to-buffer'''.
-Insidious type of bug:
- See ``Another Bug ... Most Insidious''.
-Install a Function Definition:
- See ``Install a Function Definition''.
-Install code permanently:
- See ``Install Code Permanently''.
-interactive:
- See ``Make a Function Interactive''.
-interactive function defined:
- See ``How to Evaluate''.
-Interactive functions:
- See ``Make a Function Interactive''.
-Interactive options:
- See ``Different Options for `interactive'''.
-interactive, example use of:
- See ``The Interactive Expression in `insert-buffer'''.
-Interpreter, Lisp, explained:
- See ``Run a Program''.
-Interpreter, what it does:
- See ``The Lisp Interpreter''.
-Keep, type of recursive pattern:
- See ``Recursive Pattern: _keep_''.
-Key setting globally:
- See ``Some Keybindings''.
-Key unbinding:
- See ``Some Keybindings''.
-Keymaps:
- See ``Keymaps''.
-Keyword:
- See ``Optional Arguments''.
-Kill ring handling:
- See ``Handling the Kill Ring''.
-Kill ring overview:
- See ``Kill Ring Overview''.
-kill-append:
- See ``The `kill-append' function''.
-kill-new:
- See ``The `kill-new' function''.
-kill-region:
- See ```kill-region'''.
-Killing text:
- See ``Cutting and Storing Text''.
-lambda:
- See ``A `lambda' Expression: Useful Anonymity''.
-length:
- See ``Find the Length of a List: `length'''.
-lengths-list-file:
- See ```lengths-list-file' in Detail''.
-lengths-list-many-files:
- See ``Determine the lengths of `defuns'''.
-let:
- See ```let'''.
-let expression sample:
- See ``Sample `let' Expression''.
-let expression, parts of:
- See ``The Parts of a `let' Expression''.
-let variables uninitialized:
- See ``Uninitialized Variables in a `let' Statement''.
-Library, as term for `file':
- See ``Finding More Information''.
-line-to-top-of-window:
- See ``A Simple Extension: `line-to-top-of-window'''.
-Lisp Atoms:
- See ``Lisp Atoms''.
-Lisp history:
- See ``Lisp History''.
-Lisp interpreter, explained:
- See ``Run a Program''.
-Lisp interpreter, what it does:
- See ``The Lisp Interpreter''.
-Lisp Lists:
- See ``Lisp Lists''.
-Lisp macro:
- See ```delete-and-extract-region'''.
-list-buffers, rebound:
- See ``Some Keybindings''.
-Lists in a computer:
- See ``How Lists are Implemented''.
-load-library:
- See ``Loading Files''.
-load-path:
- See ``Loading Files''.
-Loading files:
- See ``Loading Files''.
-local variable defined:
- See ```let' Prevents Confusion''.
-Local variables list, per-buffer,:
- See ``Text and Auto Fill Mode''.
-Location of point:
- See ``Buffer Size and the Location of Point''.
-looking-at:
- See ``Between paragraphs''.
-Loops:
- See ```while'''.
-Loops and recursion:
- See ``Loops and Recursion''.
-Maclisp:
- See ``Lisp History''.
-Macro, lisp:
- See ```delete-and-extract-region'''.
-Mail aliases:
- See ``Mail Aliases''.
-make tags:
- See ``Create Your Own `TAGS' File''.
-make-string:
- See ``Construct a Y Axis Element''.
-mapcar:
- See ``The `mapcar' Function''.
-mark:
- See ```save-excursion'''.
-mark-whole-buffer:
- See ``The Definition of `mark-whole-buffer'''.
-match-beginning:
- See ``No fill prefix''.
-max:
- See ``Printing the Columns of a Graph''.
-message:
- See ``The `message' Function''.
-min:
- See ``Printing the Columns of a Graph''.
-Mode line format:
- See ``A Modified Mode Line''.
-Mode selection, automatic:
- See ``Text and Auto Fill Mode''.
-Motion by sentence and paragraph:
- See ``Regular Expression Searches''.
-Narrowing:
- See ``Narrowing and Widening''.
-narrowing defined:
- See ``Buffer Size and the Location of Point''.
-nil:
- See ``Truth and Falsehood in Emacs Lisp''.
-nil, history of word:
- See ``Buffer Names''.
-No deferment solution:
- See ``No Deferment Solution''.
-nreverse:
- See ``Counting function definitions''.
-nth:
- See ```nth'''.
-nthcdr <1>:
- See ```copy-region-as-kill'''.
-nthcdr:
- See ```nthcdr'''.
-nthcdr, example:
- See ``The `kill-new' function''.
-number-to-string:
- See ``Construct a Y Axis Element''.
-occur:
- See ``Some Keybindings''.
-optional:
- See ``Optional Arguments''.
-Optional arguments:
- See ``Optional Arguments''.
-Options for interactive:
- See ``Different Options for `interactive'''.
-or:
- See ``The `or' in the Body''.
-other-buffer:
- See ``Getting Buffers''.
-Paragraphs, movement by:
- See ``Regular Expression Searches''.
-Parts of a Recursive Definition:
- See ``The Parts of a Recursive Definition''.
-Parts of let expression:
- See ``The Parts of a `let' Expression''.
-Passing information to functions:
- See ``Arguments''.
-Pasting text:
- See ``Yanking Text Back''.
-Patterns, searching for:
- See ``Regular Expression Searches''.
-Per-buffer, local variables list:
- See ``Text and Auto Fill Mode''.
-Permanent code installation:
- See ``Install Code Permanently''.
-point:
- See ```save-excursion'''.
-point defined:
- See ``Buffer Size and the Location of Point''.
-Point location:
- See ``Buffer Size and the Location of Point''.
-Point, mark, buffer preservation:
- See ```save-excursion'''.
-Practicing evaluation:
- See ``Practicing Evaluation''.
-Preserving point, mark, and buffer:
- See ```save-excursion'''.
-Primitive functions:
- See ``An Aside about Primitive Functions''.
-Primitives written in C:
- See ``An Aside about Primitive Functions''.
-Print horizontal axis:
- See ``The `print-X-axis' Function''.
-Print vertical axis:
- See ``The `print-Y-axis' Function''.
-print-elements-of-list:
- See ``An Example: `print-elements-of-list'''.
-print-elements-recursively:
- See ``Recursion with a List''.
-print-graph Final version.:
- See ``Changes for the Final Version''.
-print-graph varlist:
- See ``The `print-graph' Varlist''.
-print-X-axis:
- See ``X Axis Tic Marks''.
-print-X-axis-numbered-line:
- See ``X Axis Tic Marks''.
-print-X-axis-tic-line:
- See ``X Axis Tic Marks''.
-print-Y-axis:
- See ``The Not Quite Final Version of `print-Y-axis'''.
-Printing the whole graph:
- See ``Printing the Whole Graph''.
-prog1:
- See ``Between paragraphs''.
-progn:
- See ``The `progn' Special Form''.
-Program, running one:
- See ``Run a Program''.
-Prototype graph:
- See ``Readying a Graph''.
-re-search-forward:
- See ``The `re-search-forward' Function''.
-Read-only buffer:
- See ``A Read-only Buffer''.
-Readying a graph:
- See ``Readying a Graph''.
-Rebinding keys:
- See ``Keymaps''.
-Recursion:
- See ``Recursion''.
-Recursion and loops:
- See ``Loops and Recursion''.
-Recursion without Deferments:
- See ``Recursion without Deferments''.
-Recursive Definition Parts:
- See ``The Parts of a Recursive Definition''.
-Recursive pattern: accumulate:
- See ``Recursive Pattern: _accumulate_''.
-Recursive pattern: every:
- See ``Recursive Pattern: _every_''.
-Recursive pattern: keep:
- See ``Recursive Pattern: _keep_''.
-Recursive Patterns:
- See ``Recursive Patterns''.
-recursive-count-words:
- See ``Count Words Recursively''.
-recursive-graph-body-print:
- See ``The `recursive-graph-body-print' Function''.
-recursive-lengths-list-many-files:
- See ``Recursively Count Words in Different Files''.
-Recursively counting words:
- See ``Count Words Recursively''.
-regexp-quote:
- See ``The `let*' expression''.
-Region, what it is:
- See ```save-excursion'''.
-Regular expression searches:
- See ``Regular Expression Searches''.
-Regular expressions for word counting:
- See ``Counting: Repetition and Regexps''.
-Remainder function, %:
- See ``Side Trip: Compute a Remainder''.
-Repetition (loops):
- See ``Loops and Recursion''.
-Repetition for word counting:
- See ``Counting: Repetition and Regexps''.
-Retrieving text:
- See ``Yanking Text Back''.
-reverse:
- See ``Counting function definitions''.
-Ring, making a list like a:
- See ``Handling the Kill Ring''.
-Robots, building:
- See ``Building Robots: Extending the Metaphor''.
-rotate-yank-pointer <1>:
- See ``The `rotate-yank-pointer' Function''.
-rotate-yank-pointer:
- See ``Yanking Text Back''.
-Run a program:
- See ``Run a Program''.
-Sample let expression:
- See ``Sample `let' Expression''.
-save-excursion:
- See ```save-excursion'''.
-save-restriction:
- See ``The `save-restriction' Special Form''.
-search-forward:
- See ``The `search-forward' Function''.
-Searches, illustrating:
- See ``Regular Expression Searches''.
-sentence-end:
- See ``The Regular Expression for `sentence-end'''.
-Sentences, movement by:
- See ``Regular Expression Searches''.
-set:
- See ``Using `set'''.
-set-buffer:
- See ``Switching Buffers''.
-setcar:
- See ```setcar'''.
-setcdr:
- See ```setcdr'''.
-setcdr, example:
- See ``The `kill-new' function''.
-setq:
- See ``Using `setq'''.
-Setting a key globally:
- See ``Some Keybindings''.
-Setting value of variable:
- See ``Setting the Value of a Variable''.
-side effect defined:
- See ``Evaluation''.
-Simple extension in .emacs file:
- See ``A Simple Extension: `line-to-top-of-window'''.
-simplified-beginning-of-buffer:
- See ``A Simplified `beginning-of-buffer' Definition''.
-site-init.el init file:
- See ``Site-wide Initialization Files''.
-site-load.el init file:
- See ``Site-wide Initialization Files''.
-Size of buffer:
- See ``Buffer Size and the Location of Point''.
-Solution without deferment:
- See ``No Deferment Solution''.
-sort:
- See ``Sorting Lists''.
-Source level debugger:
- See ``The `edebug' Source Level Debugger''.
-Special form:
- See ``Complications''.
-Special form of defun:
- See ``The `defun' Special Form''.
-Storing and cutting text:
- See ``Cutting and Storing Text''.
-string defined:
- See ``Lisp Atoms''.
-switch-to-buffer:
- See ``Switching Buffers''.
-Switching to a buffer:
- See ``Switching Buffers''.
-Symbol names:
- See ``Symbol Names and Function Definitions''.
-Symbol without function error:
- See ``Error Message for a Symbol Without a Function''.
-Symbol without value error:
- See ``Error Message for a Symbol Without a Value''.
-Symbolic expressions, introduced:
- See ``Lisp Atoms''.
-Symbols as a Chest of Drawers:
- See ``Symbols as a Chest of Drawers''.
-Syntax categories and tables:
- See ``What Constitutes a Word or Symbol?''.
-Tabs, preventing:
- See ``Indent Tabs Mode''.
-TAGS file, create own:
- See ``Create Your Own `TAGS' File''.
-Tags in the Emacs sources:
- See ``Create Your Own `TAGS' File''.
-TAGS table, specifying:
- See ``Finding More Information''.
-Text between double quotation marks:
- See ``Lisp Atoms''.
-Text Mode turned on:
- See ``Text and Auto Fill Mode''.
-Text retrieval:
- See ``Yanking Text Back''.
-the-the:
- See ``The `the-the' Function''.
-then-part defined:
- See ```if' in more detail''.
-top-of-ranges:
- See ``Counting function definitions''.
-triangle-bugged:
- See ```debug'''.
-triangle-recursively:
- See ``Recursion in Place of a Counter''.
-Truth and falsehood in Emacs Lisp:
- See ``Truth and Falsehood in Emacs Lisp''.
-Types of data:
- See ``Arguments' Data Types''.
-Unbinding key:
- See ``Some Keybindings''.
-Uninitialized let variables:
- See ``Uninitialized Variables in a `let' Statement''.
-Variable initialization:
- See ``Initializing a Variable with `defvar'''.
-Variable number of arguments:
- See ``Variable Number of Arguments''.
-Variable, example of, fill-column:
- See ```fill-column', an Example Variable''.
-Variable, setting value:
- See ``Setting the Value of a Variable''.
-Variables:
- See ``Variables''.
-varlist defined:
- See ``The Parts of a `let' Expression''.
-Version of Emacs, choosing:
- See ``A Simple Extension: `line-to-top-of-window'''.
-Vertical axis printing:
- See ``The `print-Y-axis' Function''.
-what-line:
- See ```what-line'''.
-while:
- See ```while'''.
-Whitespace in lists:
- See ``Whitespace in Lists''.
-Whole graph printing:
- See ``Printing the Whole Graph''.
-Widening:
- See ``Narrowing and Widening''.
-Widening, example of:
- See ```what-line'''.
-Word counting in a defun:
- See ``Counting Words in a `defun'''.
-Words and symbols in defun:
- See ``What to Count?''.
-Words, counted recursively:
- See ``Count Words Recursively''.
-Words, duplicated:
- See ``The `the-the' Function''.
-Writing a function definition:
- See ``How To Write Function Definitions''.
-Wrong type of argument:
- See ``Using the Wrong Type Object as an Argument''.
-X axis printing:
- See ``The `print-X-axis' Function''.
-X-axis-element:
- See ``X Axis Tic Marks''.
-Y axis printing:
- See ``The `print-Y-axis' Function''.
-Y-axis-column:
- See ``Create a Y Axis Column''.
-Y-axis-column Final version.:
- See ``Changes for the Final Version''.
-Y-axis-label-spacing:
- See ``Side Trip: Compute a Remainder''.
-Y-axis-tic:
- See ``Construct a Y Axis Element''.
-yank <1>:
- See ```yank'''.
-yank:
- See ``Yanking Text Back''.
-yank-pop:
- See ```yank-pop'''.
-zap-to-char:
- See ```zap-to-char'''.
-zerop:
- See ``The Body of `rotate-yank-pointer'''.
-About the Author
-****************
-
- Robert J. Chassell has worked with GNU Emacs since 1985. He
- writes and edits, teaches Emacs and Emacs Lisp, and speaks
- throughout the world on software freedom. Chassell was a
- founding Director and Treasurer of the Free Software Foundation,
- Inc. He is co-author of the `Texinfo' manual, and has edited
- more than a dozen other books. He graduated from Cambridge
- University, in England. He has an abiding interest in social
- and economic history and flies his own airplane.
-
-