\input ../man/texinfo @c -*-texinfo-*-
-@c change above to \input texinfo if building on own.
+@c \input texinfo @c -*-texinfo-*-
+@c change to \input texinfo if building on own.
@comment %**start of header
@setfilename ../info/eintr
@c setfilename emacs-lisp-intro.info
@comment %**end of header
-@set edition-number 2.14
-@set update-date 2004 Oct 12
+@set edition-number 2.15
+@set update-date 2006 Oct 30
@ignore
## Summary of shell commands to create various output formats:
pushd /usr/local/src/emacs/lispintro/
+ ## pushd /u/intro/
## Info output
makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi
+ ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/u/intro/emacs-lisp-intro.info"))
+
## DVI output
- texi2dvi emacs-lisp-intro.texi
+ texi2dvi /u/intro/emacs-lisp-intro.texi
+
+ ## View DVI output; see below also
+ # xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 /u/intro/emacs-lisp-intro.dvi &
## HTML output
makeinfo --html --no-split --verbose emacs-lisp-intro.texi
makeinfo --xml --no-split --paragraph-indent=0 \
--verbose emacs-lisp-intro.texi
+ popd
+
#### (You must be in the same directory as the viewed file.)
## View DVI output
## View Info output with standalone reader
info emacs-lisp-intro.info
- ## popd
+ ## popd
+
+Need to explain defcustom see (elisp)Customization (elisp)Variable Definitions
+ defsubst
+ defconst
+
+
+
+# as user `root'
+# insert thumbdrive
+ mtusb # mount -v -t ext3 /dev/sda /mnt
+ cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi
+ umtusb # umount -v /mnt
+# remove thumbdrive
@end ignore
@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution.
@tex
-\global\def\xrefprintnodename#1{``#1''}
+\global\def\xrefprintnodename#1{\unskip, ``#1''}
+% \global\def\xrefprintnodename#1{, ``#1''}
@end tex
@c ----------------------------------------------------
every node in every chapter.
@end ifnottex
+@c >>>> Set pageno appropriately <<<<
+
+@c The first page of the Preface is a roman numeral; it is the first
+@c right handed page after the Table of Contents; hence the following
+@c setting must be for an odd negative number.
+
+@iftex
+@global@pageno = -11
+@end iftex
+
@menu
* Preface:: What to look for.
* List Processing:: What is Lisp?
Setting the Value of a Variable
-* Using set:: Setting values.
-* Using setq:: Setting a quoted value.
-* Counting:: Using @code{setq} to count.
+* Using set:: Setting values.
+* Using setq:: Setting a quoted value.
+* Counting:: Using @code{setq} to count.
Practicing Evaluation
-* How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
- causes evaluation.
-* Buffer Names:: Buffers and files are different.
-* Getting Buffers:: Getting a buffer itself, not merely its name.
-* Switching Buffers:: How to change to another buffer.
-* Buffer Size & Locations:: Where point is located and the size of
- the buffer.
+* How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
+ causes evaluation.
+* Buffer Names:: Buffers and files are different.
+* Getting Buffers:: Getting a buffer itself, not merely its name.
+* Switching Buffers:: How to change to another buffer.
+* Buffer Size & Locations:: Where point is located and the size of
+ the buffer.
* Evaluation Exercise::
How To Write Function Definitions
* Primitive Functions::
-* defun:: The @code{defun} special form.
-* Install:: Install a function definition.
-* Interactive:: Making a function interactive.
-* Interactive Options:: Different options for @code{interactive}.
-* Permanent Installation:: Installing code permanently.
-* let:: Creating and initializing local variables.
-* if:: What if?
-* else:: If--then--else expressions.
-* Truth & Falsehood:: What Lisp considers false and true.
-* save-excursion:: Keeping track of point, mark, and buffer.
+* defun:: The @code{defun} special form.
+* Install:: Install a function definition.
+* Interactive:: Making a function interactive.
+* Interactive Options:: Different options for @code{interactive}.
+* Permanent Installation:: Installing code permanently.
+* let:: Creating and initializing local variables.
+* if:: What if?
+* else:: If--then--else expressions.
+* Truth & Falsehood:: What Lisp considers false and true.
+* save-excursion:: Keeping track of point, mark, and buffer.
* Review::
* defun Exercises::
* if & or:: Using an @code{if} instead of an @code{or}.
* Insert or:: How the @code{or} expression works.
* Insert let:: Two @code{save-excursion} expressions.
+* New insert-buffer::
The Interactive Expression in @code{insert-buffer}
* Storing Text:: Text is stored in a list.
* zap-to-char:: Cutting out text up to a character.
* kill-region:: Cutting text out of a region.
+* copy-region-as-kill:: A definition for copying text.
* Digression into C:: Minor note on C programming language macros.
* defvar:: How to give a variable an initial value.
-* copy-region-as-kill:: A definition for copying text.
* cons & search-fwd Review::
* search Exercises::
* Complete kill-region:: The function definition.
* condition-case:: Dealing with a problem.
-* delete-and-extract-region:: Doing the work.
-
-Initializing a Variable with @code{defvar}
-
-* See variable current value::
-* defvar and asterisk:: An old-time convention.
+* Lisp macro::
@code{copy-region-as-kill}
* kill-append function::
* kill-new function::
+Initializing a Variable with @code{defvar}
+
+* See variable current value::
+* defvar and asterisk::
+
How Lists are Implemented
* Lists diagrammed::
Yanking Text Back
-* Kill Ring Overview:: The kill ring is a list.
-* kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable.
-* yank nthcdr Exercises::
+* Kill Ring Overview::
+* kill-ring-yank-pointer:: The kill ring is a list.
+* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable.
Loops and Recursion
* forward-paragraph in brief:: Key parts of the function definition.
* fwd-para let:: The @code{let*} expression.
* fwd-para while:: The forward motion @code{while} loop.
-* fwd-para between paragraphs:: Movement between paragraphs.
-* fwd-para within paragraph:: Movement within paragraphs.
-* fwd-para no fill prefix:: When there is no fill prefix.
-* fwd-para with fill prefix:: When there is a fill prefix.
-* fwd-para summary:: Summary of @code{forward-paragraph} code.
Counting: Repetition and Regexps
Handling the Kill Ring
-* rotate-yank-pointer:: Move a pointer along a list and around.
+* current-kill::
* yank:: Paste a copy of a clipped element.
-* yank-pop:: Insert first element pointed to.
+* yank-pop:: Insert element pointed to.
* ring file::
-The @code{rotate-yank-pointer} Function
+The @code{current-kill} Function
-* Understanding rotate-yk-ptr::
-* rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}.
+* Understanding current-kill::
-The Body of @code{rotate-yank-pointer}
+@code{current-kill} in Outline
* Digression concerning error:: How to mislead humans, but not computers.
-* rotate-yk-ptr else-part:: The else-part of the @code{if} expression.
-* Remainder Function:: The remainder, @code{%}, function.
-* rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}.
-* kill-rng-yk-ptr last elt:: Pointing to the last element.
-
-@code{yank}
-
-* rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}.
-* rotate-yk-ptr negative arg:: Pass a negative argument.
+* Determining the Element::
A Graph with Labelled Axes
@end detailmenu
@end menu
-@c >>>> Set pageno appropriately <<<<
-
-@c The first page of the Preface is a roman numeral; it is the first
-@c right handed page after the Table of Contents; hence the following
-@c setting must be for an odd negative number.
-
-@iftex
-@global@pageno = -11
-@end iftex
-
@node Preface, List Processing, Top, Top
@comment node-name, next, previous, up
@unnumbered Preface
editing in the most general sense of the word.)
@menu
-* Why:: Why learn Emacs Lisp?
-* On Reading this Text:: Read, gain familiarity, pick up habits....
-* Who You Are:: For whom this is written.
+* Why::
+* On Reading this Text::
+* Who You Are::
* Lisp History::
-* Note for Novices:: You can read this as a novice.
+* Note for Novices::
* Thank You::
@end menu
Errors, , Generate an Error Message}.} Lists are the basis of Lisp.
@menu
-* Lisp Lists:: What are lists?
-* Run a Program:: Any list in Lisp is a program ready to run.
-* Making Errors:: Generating an error message.
-* Names & Definitions:: Names of symbols and function definitions.
-* Lisp Interpreter:: What the Lisp interpreter does.
-* Evaluation:: Running a program.
-* Variables:: Returning a value from a variable.
-* Arguments:: Passing information to a function.
-* set & setq:: Setting the value of a variable.
-* Summary:: The major points.
+* Lisp Lists::
+* Run a Program::
+* Making Errors::
+* Names & Definitions::
+* Lisp Interpreter::
+* Evaluation::
+* Variables::
+* Arguments::
+* set & setq::
+* Summary::
* Error Message Exercises::
@end menu
@cindex Flowers in a field
@menu
-* Numbers Lists:: List have numbers, other lists, in them.
-* Lisp Atoms:: Elemental entities.
-* Whitespace in Lists:: Formating lists to be readable.
-* Typing Lists:: How GNU Emacs helps you type lists.
+* Numbers Lists::
+* Lisp Atoms::
+* Whitespace in Lists::
+* Typing Lists::
@end menu
@node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists
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 @samp{+}. On the other hand, unlike an
-atom, a list can be split into parts. (@xref{car cdr & cons, ,
-@code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
+ancient atom, a list can be split into parts. (@xref{car cdr & cons,
+, @code{car} @code{cdr} & @code{cons} Fundamental Functions}.)
In a list, atoms are separated from each other by whitespace. They can be
right next to a parenthesis.
@noindent
What you see depends on which version of Emacs you are running. GNU
-Emacs version 21 provides more information than version 20 and before.
+Emacs version 22 provides more information than version 20 and before.
First, the more recent result of generating an error; then the
earlier, version 20 result.
@need 1250
@noindent
-In GNU Emacs version 21, a @file{*Backtrace*} window will open up and
+In GNU Emacs version 22, a @file{*Backtrace*} window will open up and
you will see the following in it:
@smallexample
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 @samp{Bob}; however, I am
-not the letters @samp{B}, @samp{o}, @samp{b} but am, or were, the
+not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the
consciousness consistently associated with a particular life-form.
The name is not me, but it can be used to refer to me.
yourself or the computer.
@menu
-* Complications:: Variables, Special forms, Lists within.
-* Byte Compiling:: Specially processing code for speed.
+* Complications::
+* Byte Compiling::
@end menu
@node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter
or else produce an error.
@menu
-* Evaluating Inner Lists:: Lists within lists...
+* Evaluating Inner Lists::
@end menu
@node Evaluating Inner Lists, , Evaluation, Evaluation
@menu
* fill-column Example::
-* Void Function:: The error message for a symbol
- without a function.
-* Void Variable:: The error message for a symbol without a value.
+* Void Function::
+* Void Variable::
@end menu
@node fill-column Example, Void Function, Variables, Variables
@need 1250
@noindent
-In GNU Emacs version 21, you will create a @file{*Backtrace*} buffer
+In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer
that says:
@smallexample
(Remember, to quit the debugger and make the debugger window go away,
type @kbd{q} in the @file{*Backtrace*} buffer.)
+@ignore
@need 800
In GNU Emacs 20 and before, you will produce an error message that says:
@end smallexample
@noindent
-(The message will go away away as soon as you move the cursor or type
+(The message will go away as soon as you move the cursor or type
another key.)
+@end ignore
@node Void Variable, , Void Function, Variables
@comment node-name, next, previous, up
@need 1500
@noindent
-In GNU Emacs 21, you will create a @file{*Backtrace*} buffer that
+In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that
says:
@smallexample
definition, the error message reported that the symbol's value as a
variable was void.
+@ignore
@need 800
In GNU Emacs version 20 and before, your error message will say:
@end example
@noindent
-The meaning is the same as in GNU Emacs 21.
+The meaning is the same as in GNU Emacs 22.
+@end ignore
@node Arguments, set & setq, Variables, List Processing
@comment node-name, next, previous, up
have two different function definitions at the same time.)}
@menu
-* Data types:: Types of data passed to a function.
-* Args as Variable or List:: An argument can be the value
- of a variable or list.
-* Variable Number of Arguments:: Some functions may take a
- variable number of arguments.
-* Wrong Type of Argument:: Passing an argument of the wrong type
- to a function.
-* message:: A useful function for sending messages.
+* Data types::
+* Args as Variable or List::
+* Variable Number of Arguments::
+* Wrong Type of Argument::
+* message::
@end menu
@node Data types, Args as Variable or List, Arguments, Arguments
@noindent
The value will be a number two more than what you get by evaluating
-@code{fill-column} alone. For me, this is 74, because the value of
+@code{fill-column} alone. For me, this is 74, because my value of
@code{fill-column} is 72.
As we have just seen, an argument can be a symbol that returns a value
@w{@code{"The "}} and @w{@code{" red foxes."}} and the list
@code{(number-to-string (+ 2 fill-column))}.
-@c For Emacs 21, need number-to-string
+@c For GNU Emacs 22, need number-to-string
@smallexample
(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
@end smallexample
could not carry out its addition.
@need 1250
-In GNU Emacs version 21, you will create and enter a
+In GNU Emacs version 22, you will create and enter a
@file{*Backtrace*} buffer that says:
@noindent
would have been a number, such as 37, rather than a symbol like
@code{hello}. But then you would not have got the error message.
+@ignore
@need 1250
In GNU Emacs version 20 and before, the echo area displays an error
message that says:
This says, in different words, the same as the top line of the
@file{*Backtrace*} buffer.
+@end ignore
@node message, , Wrong Type of Argument, Arguments
@comment node-name, next, previous, up
in place of the @samp{%d}; and the value returned by the expression
beginning with @code{concat} is inserted in place of the @samp{%s}.
-When I evaluate the expression, the message @code{"He saw 38 red
-foxes leaping."} appears in my echo area.
+When your fill column is 70 and you evaluate the expression, the
+message @code{"He saw 38 red foxes leaping."} appears in your echo
+area.
@node set & setq, Summary, Arguments, List Processing
@comment node-name, next, previous, up
work but also illustrate how arguments are passed.
@menu
-* Using set:: Setting values.
-* Using setq:: Setting a quoted value.
-* Counting:: Using @code{setq} to count.
+* Using set::
+* Using setq::
+* Counting::
@end menu
@node Using set, Using setq, set & setq, set & setq
@noindent
The list @code{(rose violet daisy buttercup)} will appear in the echo
area. This is what is @emph{returned} by the @code{set} function. As a
-side effect, the symbol @code{flowers} is bound to the list ; that is,
+side effect, the symbol @code{flowers} is bound to the list; that is,
the symbol @code{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
Then the instructions in the function definition are carried out.
@item
-A single-quote, @code{'}, tells the Lisp interpreter that it should
+A single quotation mark,
+@ifinfo
+'
+@end ifinfo
+@ifnotinfo
+@code{'}
+@end ifnotinfo
+, 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.
buffer-related functions, to see how they were written.
@menu
-* How to Evaluate:: Typing editing commands or @kbd{C-x C-e}
- causes evaluation.
-* Buffer Names:: Buffers and files are different.
-* Getting Buffers:: Getting a buffer itself, not merely its name.
-* Switching Buffers:: How to change to another buffer.
-* Buffer Size & Locations:: Where point is located and the size of
- the buffer.
+* How to Evaluate::
+* Buffer Names::
+* Getting Buffers::
+* Switching Buffers::
+* Buffer Size & Locations::
* Evaluation Exercise::
@end menu
each of the following expressions by positioning the cursor after it and
typing @kbd{C-x C-e}.
-@smallexample
+@example
@group
(buffer-name)
(buffer-file-name)
@end group
-@end smallexample
+@end example
@noindent
-When I do this, @file{"introduction.texinfo"} is the value returned by
-evaluating @code{(buffer-name)}, and
-@file{"/gnu/work/intro/introduction.texinfo"} is the value returned by
-evaluating @code{(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 @code{buffer-name} and
-@code{buffer-file-name} as functions; without the parentheses, the
-interpreter would attempt to evaluate the symbols as variables.
-@xref{Variables}.)
+When I do this in Info, the value returned by evaluating
+@code{(buffer-name)} is @file{"*info*"}, and the value returned by
+evaluating @code{(buffer-file-name)} is @file{nil}.
+
+On the other hand, while I am writing this Introduction, the value
+returned by evaluating @code{(buffer-name)} is
+@file{"introduction.texinfo"}, and the value returned by evaluating
+@code{(buffer-file-name)} is
+@file{"/gnu/work/intro/introduction.texinfo"}.
+
+@cindex @code{nil}, history of word
+The former is the name of the buffer and the latter is the name of the
+file. In Info, the buffer name is @file{"*info*"}. Info does not
+point to any file, so the result of evaluating
+@code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is
+from the Latin word for `nothing'; in this case, it means that the
+buffer is not associated with any file. (In Lisp, @code{nil} is also
+used to mean `false' and is a synonym for the empty list, @code{()}.)
+
+When I am writing, the name of my buffer is
+@file{"introduction.texinfo"}. The name of the file to which it
+points is @file{"/gnu/work/intro/introduction.texinfo"}.
+
+(In the expressions, the parentheses tell the Lisp interpreter to
+treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as
+functions; without the parentheses, the interpreter would attempt to
+evaluate the symbols as variables. @xref{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.
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 @code{emacs} alone, without
-naming any files, Emacs will start with the @file{*scratch*} buffer on
-the screen. This buffer is not visiting any file. Similarly, a
+Not all buffers are associated with files. For example, a
+@file{*scratch*} buffer does not visit any file. Similarly, a
@file{*Help*} buffer is not associated with any file.
-@cindex @code{nil}, history of word
-If you switch to the @file{*scratch*} buffer, type @code{(buffer-name)},
-position the cursor after it, and type @kbd{C-x C-e} to evaluate the
-expression, the name @code{"*scratch*"} is returned and will appear in
-the echo area. @code{"*scratch*"} is the name of the buffer. However,
-if you type @code{(buffer-file-name)} in the @file{*scratch*} buffer and
-evaluate that, @code{nil} will appear in the echo area. @code{nil} is
-from the Latin word for `nothing'; in this case, it means that the
-@file{*scratch*} buffer is not associated with any file. (In Lisp,
-@code{nil} is also used to mean `false' and is a synonym for the empty
-list, @code{()}.)
+In the old days, when you lacked a @file{~/.emacs} file and started an
+Emacs session by typing the command @code{emacs} alone, without naming
+any files, Emacs started with the @file{*scratch*} buffer visible.
+Nowadays, you will see a splash screen. You can follow one of the
+commands suggested on the splash screen, visit a file, or press the
+spacebar to reach the @file{*scratch*} buffer.
+
+If you switch to the @file{*scratch*} buffer, type
+@code{(buffer-name)}, position the cursor after it, and then type
+@kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"}
+will be returned and will appear in the echo area. @code{"*scratch*"}
+is the name of the buffer. When you type @code{(buffer-file-name)} in
+the @file{*scratch*} buffer and evaluate that, @code{nil} will appear
+in the echo area, just as it does when you evaluate
+@code{(buffer-file-name)} in Info.
Incidentally, if you are in the @file{*scratch*} buffer and want the
value returned by an expression to appear in the @file{*scratch*}
@end smallexample
@noindent
-If you evaluate the expression in the usual way, @file{#<buffer *info*>}
-appears in the echo area. The special format indicates that the
-buffer itself is being returned, rather than just its name.
+If you evaluate this expression in Info in Emacs in the usual way,
+@file{#<buffer *info*>} will appear 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 @code{current-buffer}.
A related function is @code{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 @file{*scratch*}
-buffer, @code{other-buffer} will return that buffer.
+recently selected buffer other than the one you are in currently, not
+a printed representation of its name. If you have recently switched
+back and forth from the @file{*scratch*} buffer, @code{other-buffer}
+will return that buffer.
@need 800
You can see this by evaluating the expression:
function. When you switched back and forth from Info to the
@file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most
likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or
-rather, to save typing, you probably typed just part of the name, such
-as @code{*sc}, and then pressed your @kbd{TAB} key to cause it to
-expand to the full name; and then typed your @kbd{RET} key.} when
-prompted in the minibuffer for the name of the buffer to which you
-wanted to switch. The keystrokes, @kbd{C-x b}, cause the Lisp
-interpreter to evaluate the interactive function
+rather, to save typing, you probably only typed @kbd{RET} if the
+default buffer was @file{*scratch*}, or if it was different, then you
+typed just part of the name, such as @code{*sc}, pressed your
+@kbd{TAB} key to cause it to expand to the full name, and then typed
+your @kbd{RET} key.} when prompted in the minibuffer for the name of
+the buffer to which you wanted to switch. The keystrokes, @kbd{C-x
+b}, cause the Lisp interpreter to evaluate the interactive function
@code{switch-to-buffer}. As we said before, this is how Emacs works:
different keystrokes call or run different functions. For example,
@kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls
@menu
* Primitive Functions::
-* defun:: The @code{defun} special form.
-* Install:: Install a function definition.
-* Interactive:: Making a function interactive.
-* Interactive Options:: Different options for @code{interactive}.
-* Permanent Installation:: Installing code permanently.
-* let:: Creating and initializing local variables.
-* if:: What if?
-* else:: If--then--else expressions.
-* Truth & Falsehood:: What Lisp considers false and true.
-* save-excursion:: Keeping track of point, mark, and buffer.
+* defun::
+* Install::
+* Interactive::
+* Interactive Options::
+* Permanent Installation::
+* let::
+* if::
+* else::
+* Truth & Falsehood::
+* save-excursion::
* Review::
* defun Exercises::
@end menu
Emacs. To reload code automatically whenever you start Emacs, see
@ref{Permanent Installation, , Installing Code Permanently}.)
-
@menu
* Effect of installation::
-* Change a defun:: How to change a function definition.
+* Change a defun::
@end menu
@node Effect of installation, Change a defun, Install, Install
@smallexample
@group
-multiply-by-seven:
+multiply-by-seven is a Lisp function.
+(multiply-by-seven NUMBER)
+
Multiply NUMBER by seven.
@end group
@end smallexample
each time you typed a key, it would be very distracting.
@menu
-* Interactive multiply-by-seven:: An overview.
-* multiply-by-seven in detail:: The interactive version.
+* Interactive multiply-by-seven::
+* multiply-by-seven in detail::
@end menu
@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive
subsequent elements of the list to the function @code{message}.
As we have seen, @code{message} is an Emacs Lisp function especially
-designed for sending a one line message to a user. (@xref{message, , The
-@code{message} function}.)
-In summary, the @code{message} function prints its first argument in the
-echo area as is, except for occurrences of @samp{%d}, @samp{%s}, or
-@samp{%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.
+designed for sending a one line message to a user. (@xref{message, ,
+The @code{message} function}.) In summary, the @code{message}
+function prints its first argument in the echo area as is, except for
+occurrences of @samp{%d} or @samp{%s} (and various other %-sequences
+which we have not mentioned). When it sees a control sequence, the
+function looks to the second or subsequent arguments and prints the
+value of the argument in the location in the string where the control
+sequence is located.
In the interactive @code{multiply-by-seven} function, the control string
is @samp{%d}, which requires a number, and the value returned by
@code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.)
@need 1250
-For example, the character @samp{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:
+Consider the function @code{zap-to-char}. Its interactive expression
+is
@smallexample
-(interactive "r")
+(interactive "p\ncZap to char: ")
@end smallexample
-On the other hand, a @samp{B} tells Emacs to ask for the name of a
-buffer that will be passed to the function. When it sees a @samp{B},
-Emacs will ask for the name by prompting the user in the minibuffer,
-using a string that follows the @samp{B}, as in @code{"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 @key{TAB}.
+The first part of the argument to @code{interactive} is @samp{p}, with
+which you are already familiar. This argument tells Emacs to
+interpret a `prefix', as a number to be passed to the function. You
+can specify a prefix either by typing @kbd{C-u} followed by a number
+or by typing @key{META} followed by a number. The prefix is the
+number of specified characters. Thus, if your prefix is three and the
+specified character is @samp{x}, then you will delete all the text up
+to and including the third next @samp{x}. If you do not set a prefix,
+then you delete all the text up to and including the specified
+character, but no more.
+
+The @samp{c} tells the function the name of the character to which to delete.
-A function with two or more arguments can have information passed to
-each argument by adding parts to the string that follows
-@code{interactive}. When you do this, the information is passed to
-each argument in the same order it is specified in the
+More formally, a function with two or more arguments can have
+information passed to each argument by adding parts to the string that
+follows @code{interactive}. When you do this, the information is
+passed to each argument in the same order it is specified in the
@code{interactive} list. In the string, each part is separated from
the next part by a @samp{\n}, which is a newline. For example, you
-could follow @code{"BAppend to buffer:@: "} with a @samp{\n} and an
-@samp{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.
+can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }.
+This causes Emacs to pass the value of the prefix argument (if there
+is one) and the character.
-In this case, the function definition would look like the following,
-where @code{buffer}, @code{start}, and @code{end} are the symbols to
-which @code{interactive} binds the buffer and the current values of the
-beginning and ending of the region:
+In this case, the function definition looks like the following, where
+@code{arg} and @code{char} are the symbols to which @code{interactive}
+binds the prefix argument and the specified character:
@smallexample
@group
-(defun @var{name-of-function} (buffer start end)
+(defun @var{name-of-function} (arg char)
"@var{documentation}@dots{}"
- (interactive "BAppend to buffer:@: \nr")
+ (interactive "p\ncZap to char: ")
@var{body-of-function}@dots{})
@end group
@end smallexample
@noindent
(The space after the colon in the prompt makes it look better when you
-are prompted. The @code{append-to-buffer} function looks exactly like
-this. @xref{append-to-buffer, , The Definition of
-@code{append-to-buffer}}.)
+are prompted. @xref{copy-to-buffer, , The Definition of
+@code{copy-to-buffer}}, for an example.)
-If a function does not have arguments, then @code{interactive} does not
+When a function does not take arguments, @code{interactive} does not
require any. Such a function contains the simple expression
@code{(interactive)}. The @code{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 @code{interactive} as
-a list. @xref{Using Interactive, , Using @code{Interactive}, elisp, The
-GNU Emacs Lisp Reference Manual}, for more information about this advanced
-technique.
+a list.
+
+@xref{append-to-buffer, , The Definition of @code{append-to-buffer}},
+for an example. @xref{Using Interactive, , Using @code{Interactive},
+elisp, The GNU Emacs Lisp Reference Manual}, for a more complete
+explanation about this technique.
@node Permanent Installation, let, Interactive Options, Writing Defuns
@comment node-name, next, previous, up
@xref{Loading Files, , Loading Files}.
@item
-On the other hand, if you have code that your whole site will use, it
-is usual to put it in a file called @file{site-init.el} that is loaded
-when Emacs is built. This makes the code available to everyone who
-uses your machine. (See the @file{INSTALL} file that is part of the
-Emacs distribution.)
+Thirdly, if you have code that your whole site will use, it is usual
+to put it in a file called @file{site-init.el} that is loaded when
+Emacs is built. This makes the code available to everyone who uses
+your machine. (See the @file{INSTALL} file that is part of the Emacs
+distribution.)
@end itemize
Finally, if you have code that everyone who uses Emacs may want, you
@end ifnottex
@cindex @samp{local variable} defined
+@cindex @samp{variable, local}, defined
The @code{let} special form prevents confusion. @code{let} creates a
name for a @dfn{local variable} that overshadows any use of the same
name outside the @code{let} expression. This is like understanding
The two variables are @code{zebra} and @code{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 @code{zebra} to the value @code{stripes}, and binds the
+variable @code{zebra} to the value @code{stripes}@footnote{According
+to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras
+become impossibly dangerous as they grow older'' but the claim here is
+that they do not become fierce like a tiger. (1997, W. W. Norton and
+Co., ISBN 0-393-03894-2, page 171)}, and binds the
variable @code{tiger} to the value @code{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 @code{let}
-follows after the list holding the variables. In this example, the body
-is a list that uses the @code{message} function to print a string in
-the echo area.
+follows after the list holding the variables. In this example, the
+body is a list that uses the @code{message} function to print a string
+in the echo area.
@need 1500
You may evaluate the example in the usual fashion, by placing the
@menu
* if in more detail::
-* type-of-animal in detail:: An example of an @code{if} expression.
+* type-of-animal in detail::
@end menu
@node if in more detail, type-of-animal in detail, if, if
(Of course, if the @var{characteristic} were @code{ferocious}, the
message @code{"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 @code{if} and
-write your program accordingly.)
+possibility that some such argument will be tested by the @code{if}
+and write your program accordingly.)
@node Truth & Falsehood, save-excursion, else, Writing Defuns
@comment node-name, next, previous, up
if the result of evaluating it is a value that is not @code{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 @code{"hello"}, or a
-symbol (other than @code{nil}) such as @code{flowers}, or a list, or
-even a buffer!
+symbol (other than @code{nil}) such as @code{flowers}, or a list (so
+long as it is not empty), or even a buffer!
@menu
-* nil explained:: @code{nil} has two meanings.
+* nil explained::
@end menu
@node nil explained, , Truth & Falsehood, Truth & Falsehood
unexpected movement of point or mark.
@menu
-* Point and mark:: A review of various locations.
+* Point and mark::
* Template for save-excursion::
@end menu
In addition to recording the values of point and mark,
@code{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 @code{save-excursion} switch you back to the original buffer. This
-is how @code{save-excursion} is used in @code{append-to-buffer}.
+have @code{save-excursion} switch you back to the original buffer.
+This is how @code{save-excursion} is used in @code{append-to-buffer}.
(@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.)
@node Template for save-excursion, , Point and mark, save-excursion
definition.
@need 1250
-For example:
+For example, in an early version of Emacs, the function definition was
+as follows. (It is slightly more complex now that it seeks the first
+non-whitespace character rather than the first visible character.)
@smallexample
@group
@end group
@end smallexample
+@ignore
+In GNU Emacs 22,
+
+(defun backward-to-indentation (&optional arg)
+ "Move backward ARG lines and position at first nonblank character."
+ (interactive "p")
+ (forward-line (- (or arg 1)))
+ (skip-chars-forward " \t"))
+
+(defun back-to-indentation ()
+ "Move point to the first non-whitespace character on this line."
+ (interactive)
+ (beginning-of-line 1)
+ (skip-syntax-forward " " (line-end-position))
+ ;; Move back over chars that have whitespace syntax but have the p flag.
+ (backward-prefix-chars))
+@end ignore
+
@item interactive
Declare to the interpreter that the function can be used
interactively. This special form may be followed by a string with one
@smallexample
@group
(if (string-equal
- (number-to-string 21)
+ (number-to-string 22)
(substring (emacs-version) 10 12))
- (message "This is version 21 Emacs")
- (message "This is not version 21 Emacs"))
+ (message "This is version 22 Emacs")
+ (message "This is not version 22 Emacs"))
@end group
@end smallexample
be a string or a symbol; the argument used by @samp{%d} must be a
number. The argument used by @samp{%c} must be an @sc{ascii} code
number; it will be printed as the character with that @sc{ascii} code.
+(Various other %-sequences have not been mentioned.)
@item setq
@itemx set
buffers. Later, we will study other functions.
@menu
-* Finding More:: How to find more information.
-* simplified-beginning-of-buffer:: Shows @code{goto-char},
- @code{point-min}, and @code{push-mark}.
-* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}.
-* append-to-buffer:: Uses @code{save-excursion} and
- @code{insert-buffer-substring}.
-* Buffer Related Review:: Review.
+* Finding More::
+* simplified-beginning-of-buffer::
+* mark-whole-buffer::
+* append-to-buffer::
+* Buffer Related Review::
* Buffer Exercises::
@end menu
then @key{RET}).
@cindex Find source of function
-In versions 20 and higher, when a function is written in Emacs Lisp,
-@code{describe-function} will also tell you the location of the
-function definition. If you move point over the file name and press
+@c In version 22
+When a function is written in Emacs Lisp, @code{describe-function}
+will also tell you the location of the function definition.
+
+Put point into the name of the file that contains the function and
+press the @key{RET} key. In this case, @key{RET} means
+@code{push-button} rather than `return' or `enter'. Emacs will take
+you directly to the function definition.
+
+@ignore
+Not In version 22
+
+If you move point over the file name and press
the @key{RET} key, which in this case means @code{help-follow} rather
than `return' or `enter', Emacs will take you directly to the function
definition.
+@end ignore
More generally, if you want to see a function in its original source
file, you can use the @code{find-tags} function to jump to it.
@key{RET}}. (On some keyboards, the @key{META} key is labelled
@key{ALT}.)
-@c !!! 21.0.100 tags table location in this paragraph
+@c !!! 22.0.100 tags table location in this paragraph
@cindex TAGS table, specifying
@findex find-tags
Depending on how the initial default values of your copy of Emacs are
if it has already been created for you, will be in a subdirectory of
the @file{/usr/local/share/emacs/} directory; thus you would use the
@code{M-x visit-tags-table} command and specify a pathname such as
-@file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or
-@file{/usr/local/src/emacs/src/TAGS}. If the tags table has
-not already been created, you will have to create it yourself.
+@file{/usr/local/share/emacs/22.0.100/lisp/TAGS}. If the tags table
+has not already been created, you will have to create it yourself. It
+will in a file such as @file{/usr/local/src/emacs/src/TAGS}.
@need 1250
To create a @file{TAGS} file in a specific directory, switch to that
directory in Emacs using @kbd{M-x cd} command, or list the directory
with @kbd{C-x d} (@code{dired}). Then run the compile command, with
-@w{@code{etags *.el}} as the command to execute
+@w{@code{etags *.el}} as the command to execute:
@smallexample
M-x compile RET etags *.el RET
@smallexample
@group
-One arg, a number. Set point to that number.
-Beginning of buffer is position (point-min),
-end is (point-max).
+Set point to POSITION, a number or marker.
+Beginning of buffer is position (point-min), end is (point-max).
@end group
@end smallexample
+@noindent
+The function's one argument is the desired position.
+
@noindent
(The prompt for @code{describe-function} will offer you the symbol
under or preceding the cursor, so you can save typing by positioning
a mark at the end of the buffer. It is generally bound to @kbd{C-x
h}.
-
@menu
* mark-whole-buffer overview::
-* Body of mark-whole-buffer:: Only three lines of code.
+* Body of mark-whole-buffer::
@end menu
-
@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer
@ifnottex
@unnumberedsubsec An overview of @code{mark-whole-buffer}
@end ifnottex
@need 1250
-In GNU Emacs 20, the code for the complete function looks like this:
+In GNU Emacs 22, the code for the complete function looks like this:
@smallexample
@group
(defun mark-whole-buffer ()
- "Put point at beginning and mark at end of buffer."
+ "Put point at beginning and mark at end of buffer.
+You probably should not use this function in Lisp programs;
+it is usually a mistake for a Lisp function to use any subroutine
+that uses or sets the mark."
(interactive)
(push-mark (point))
- (push-mark (point-max))
+ (push-mark (point-max) nil t)
(goto-char (point-min)))
@end group
@end smallexample
The body of the @code{mark-whole-buffer} function consists of three
lines of code:
+@c GNU Emacs 22
@smallexample
@group
(push-mark (point))
-(push-mark (point-max))
+(push-mark (point-max) nil t)
(goto-char (point-min))
@end group
@end smallexample
line causes Emacs to determine the position of point and set a mark
there.
-The next line of @code{mark-whole-buffer} is @code{(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. @xref{Narrowing & Widening, , Narrowing and 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
-@kbd{C-u C-@key{SPC}} twice.
+In earlier versions of GNU Emacs, the next line of
+@code{mark-whole-buffer} was @code{(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.
+@xref{Narrowing & Widening, , Narrowing and 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 @kbd{C-u
+C-@key{SPC}} twice.
-(In GNU Emacs 21, the @code{(push-mark (point-max)} is slightly more
-complicated than shown here. The line reads
+@need 1250
+In GNU Emacs 22, the @code{(point-max)} is slightly more complicated.
+The line reads
@smallexample
(push-mark (point-max) nil t)
@end smallexample
@noindent
-(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, @code{push-mark} has two additional arguments. The
-second argument to @code{push-mark} is @code{nil}. This tells the
-function it @emph{should} display a message that says `Mark set' when
-it pushes the mark. The third argument is @code{t}. This tells
+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, @code{push-mark} has two additional arguments. The second
+argument to @code{push-mark} is @code{nil}. This tells the function
+it @emph{should} display a message that says `Mark set' when it pushes
+the mark. The third argument is @code{t}. This tells
@code{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.)
+region. It is often turned off.
Finally, the last line of the function is @code{(goto-char
(point-min)))}. This is written exactly the same way as it is written
@section The Definition of @code{append-to-buffer}
@findex append-to-buffer
-The @code{append-to-buffer} command is very nearly as simple as the
-@code{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.
+The @code{append-to-buffer} command is more complex than the
+@code{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.
@menu
* append-to-buffer overview::
-* append interactive:: A two part interactive expression.
-* append-to-buffer body:: Incorporates a @code{let} expression.
-* append save-excursion:: How the @code{save-excursion} works.
+* append interactive::
+* append-to-buffer body::
+* append save-excursion::
@end menu
@node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer
@code{insert-buffer-substring} function to copy the region.
@code{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 @code{append-to-buffer} is
+inserts them into another buffer.
+
+Most of @code{append-to-buffer} is
concerned with setting up the conditions for
@code{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.
+buffer to which the text will go, the window it comes from and goes
+to, and the region that will be copied.
+
+@need 1250
Here is the complete text of the function:
@smallexample
@group
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")
+BUFFER (or buffer name), START and END.
+START and END specify the portion of the current buffer to be copied."
+ (interactive
+ (list (read-buffer "Append to buffer: " (other-buffer
+ (current-buffer) t))
+ (region-beginning) (region-end)))
+@end group
+@group
(let ((oldbuf (current-buffer)))
(save-excursion
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
+ (let* ((append-to (get-buffer-create buffer))
+ (windows (get-buffer-window-list append-to t t))
+ point)
+ (set-buffer append-to)
+ (setq point (point))
+ (barf-if-buffer-read-only)
+ (insert-buffer-substring oldbuf start end)
+ (dolist (window windows)
+ (when (= (window-point window) point)
+ (set-window-point window (point))))))))
@end group
@end smallexample
@group
(defun append-to-buffer (buffer start end)
"@var{documentation}@dots{}"
- (interactive "BAppend to buffer:@: \nr")
+ (interactive @dots{})
@var{body}@dots{})
@end group
@end smallexample
will be copied.
The next part of the function is the documentation, which is clear and
-complete.
+complete. As is conventional, the three arguments are written in
+upper case so you will notice them easily. Even better, they are
+described in the same order as in the argument list.
+
+Note that the documentation distinguishes between a buffer and its
+name. (The function can handle either.)
@node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer
@comment node-name, next, previous, up
Function Interactive}.) The expression reads as follows:
@smallexample
-(interactive "BAppend to buffer:@: \nr")
+(interactive
+ (list (read-buffer
+ "Append to buffer: "
+ (other-buffer (current-buffer) t))
+ (region-beginning)
+ (region-end)))
@end smallexample
@noindent
-This expression has an argument inside of quotation marks and that
-argument has two parts, separated by @samp{\n}.
+This expression is not one with letters standing for parts, as
+described earlier. Instead, it starts a list with thee parts.
+
+The first part of the list is an expression to read the name of a
+buffer and return it as a string. That is @code{read-buffer}. The
+function requires a prompt as its first argument, @samp{"Append to
+buffer: "}. Its second argument tells the command what value to
+provide if you don't specify anything.
+
+In this case that second argument is an expression containing the
+function @code{other-buffer}, an exception, and a @samp{t}, standing
+for true.
+
+The first argument to @code{other-buffer}, the exception, is yet
+another function, @code{current-buffer}. That is not going to be
+returned. The second argument is the symbol for true, @code{t}. that
+tells @code{other-buffer} that it may show visible buffers (except in
+this case, it will not show the current buffer, which makes sense).
+
+@need 1250
+The expression looks like this:
+
+@smallexample
+(other-buffer (current-buffer) t)
+@end smallexample
+
+The second and third arguments to the @code{list} expression are
+@code{(region-beginning)} and @code{(region-end)}. These two
+functions specify the beginning and end of the text to be appended.
+
+@need 1250
+Originally, the command used the letters @samp{B} and @samp{r}.
+The whole @code{interactive} expression looked like this:
+
+@smallexample
+(interactive "BAppend to buffer:@: \nr")
+@end smallexample
-The first part is @samp{BAppend to buffer:@: }. Here, the @samp{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 @samp{B}, which is the string
-@samp{Append to buffer:@: }. Emacs then binds the variable @code{buffer}
-in the function's argument list to the specified buffer.
+@noindent
+But when that was done, the default value of the buffer switched to
+was invisible. That was not wanted.
-The newline, @samp{\n}, separates the first part of the argument from
-the second part. It is followed by an @samp{r} that tells Emacs to bind
-the two arguments that follow the symbol @code{buffer} in the function's
+(The prompt was separated from the second argument with a newline,
+@samp{\n}. It was followed by an @samp{r} that told Emacs to bind the
+two arguments that follow the symbol @code{buffer} in the function's
argument list (that is, @code{start} and @code{end}) to the values of
-point and mark.
+point and mark. That argument worked fine.)
@node append-to-buffer body, append save-excursion, append interactive, append-to-buffer
@comment node-name, next, previous, up
@subsection The Body of @code{append-to-buffer}
+@ignore
+in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el
+
+(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:
+BUFFER (or buffer name), START and END.
+START and END specify the portion of the current buffer to be copied."
+ (interactive
+ (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t))
+ (region-beginning) (region-end)))
+ (let ((oldbuf (current-buffer)))
+ (save-excursion
+ (let* ((append-to (get-buffer-create buffer))
+ (windows (get-buffer-window-list append-to t t))
+ point)
+ (set-buffer append-to)
+ (setq point (point))
+ (barf-if-buffer-read-only)
+ (insert-buffer-substring oldbuf start end)
+ (dolist (window windows)
+ (when (= (window-point window) point)
+ (set-window-point window (point))))))))
+@end ignore
+
The body of the @code{append-to-buffer} function begins with @code{let}.
As we have seen before (@pxref{let, , @code{let}}), the purpose of a
@group
(defun append-to-buffer (buffer start end)
"@var{documentation}@dots{}"
- (interactive "BAppend to buffer:@: \nr")
+ (interactive @dots{})
(let ((@var{variable} @var{value}))
@var{body}@dots{})
@end group
@need 1500
@noindent
-This formatting convention makes it easy to see that the two lines in
+This formatting convention makes it easy to see that the lines in
the body of the @code{save-excursion} are enclosed by the parentheses
associated with @code{save-excursion}, just as the
@code{save-excursion} itself is enclosed by the parentheses associated
@group
(let ((oldbuf (current-buffer)))
(save-excursion
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
+ @dots{}
+ (set-buffer @dots{})
+ (insert-buffer-substring oldbuf start end)
+ @dots{}))
@end group
@end smallexample
@need 1200
@noindent
In this function, the body of the @code{save-excursion} contains only
-two expressions. The body looks like this:
+one expression, the @code{let*} expression. You know about a
+@code{let} function. The @code{let*} function is different. It has a
+@samp{*} in its name. It enables Emacs to set each variable in its
+varlist in sequence, one after another.
-@smallexample
-@group
-(set-buffer (get-buffer-create buffer))
-(insert-buffer-substring oldbuf start end)
-@end group
-@end smallexample
+Its critical feature is that variables later in the varlist can make
+use of the values to which Emacs set variables earlier in the varlist.
+@xref{fwd-para let, , The @code{let*} expression}.
-When the @code{append-to-buffer} function is evaluated, the two
-expressions in the body of the @code{save-excursion} are evaluated in
-sequence. The value of the last expression is returned as the value of
-the @code{save-excursion} function; the other expression is evaluated
-only for its side effects.
+We will skip functions like @code{let*} and focus on two: the
+@code{set-buffer} function and the @code{insert-buffer-substring}
+function.
-The first line in the body of the @code{save-excursion} uses the
-@code{set-buffer} function to change the current buffer to the one
-specified in the first argument to @code{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.
+@need 1250
+In the old days, the @code{set-buffer} expression was simply
-The @code{set-buffer} function changes Emacs' attention to the buffer to
-which the text will be copied and from which @code{save-excursion} will
-return.
+@smallexample
+(set-buffer (get-buffer-create buffer))
+@end smallexample
-@need 800
-The line looks like this:
+@need 1250
+@noindent
+but now it is
@smallexample
-(set-buffer (get-buffer-create buffer))
+(set-buffer append-to)
@end smallexample
-The innermost expression of this list is @code{(get-buffer-create
-buffer)}. This expression uses the @code{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 @code{append-to-buffer} to
-put text into a buffer that did not previously exist.
+@noindent
+@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier
+on in the @code{let*} expression. That extra binding would not be
+necessary except for that @code{append-to} is used later in the
+varlist as an argument to @code{get-buffer-window-list}.
+
+@ignore
+in GNU Emacs 22
+
+ (let ((oldbuf (current-buffer)))
+ (save-excursion
+ (let* ((append-to (get-buffer-create buffer))
+ (windows (get-buffer-window-list append-to t t))
+ point)
+ (set-buffer append-to)
+ (setq point (point))
+ (barf-if-buffer-read-only)
+ (insert-buffer-substring oldbuf start end)
+ (dolist (window windows)
+ (when (= (window-point window) point)
+ (set-window-point window (point))))))))
+@end ignore
-@code{get-buffer-create} also keeps @code{set-buffer} from getting an
-unnecessary error: @code{set-buffer} needs a buffer to go to; if you
-were to specify a buffer that does not exist, Emacs would baulk.
-Since @code{get-buffer-create} will create a buffer if none exists,
-@code{set-buffer} is always provided with a buffer.
+The @code{append-to-buffer} function definition inserts text from the
+buffer in which you are currently to a named buffer. It happens that
+@code{insert-buffer-substring} copies text from another buffer to the
+current buffer, just the reverse---that is why the
+@code{append-to-buffer} definition starts out with a @code{let} that
+binds the local symbol @code{oldbuf} to the value returned by
+@code{current-buffer}.
@need 1250
-The last line of @code{append-to-buffer} does the work of appending
-the text:
+The @code{insert-buffer-substring} expression looks like this:
@smallexample
(insert-buffer-substring oldbuf start end)
@end smallexample
@noindent
-The @code{insert-buffer-substring} function copies a string @emph{from}
-the buffer specified as its first argument and inserts the string into
-the present buffer. In this case, the argument to
-@code{insert-buffer-substring} is the value of the variable created and
-bound by the @code{let}, namely the value of @code{oldbuf}, which was
-the current buffer when you gave the @code{append-to-buffer} command.
+The @code{insert-buffer-substring} function copies a string
+@emph{from} the buffer specified as its first argument and inserts the
+string into the present buffer. In this case, the argument to
+@code{insert-buffer-substring} is the value of the variable created
+and bound by the @code{let}, namely the value of @code{oldbuf}, which
+was the current buffer when you gave the @code{append-to-buffer}
+command.
After @code{insert-buffer-substring} has done its work,
-@code{save-excursion} will restore the action to the original buffer and
-@code{append-to-buffer} will have done its job.
+@code{save-excursion} will restore the action to the original buffer
+and @code{append-to-buffer} will have done its job.
@need 800
Written in skeletal form, the workings of the body look like this:
@var{change-back-to-original-buffer-when-finished}
@var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished}
-
@end group
@end smallexample
-In summary, @code{append-to-buffer} works as follows: it saves the value
-of the current buffer in the variable called @code{oldbuf}. It gets the
-new buffer, creating one if need be, and switches Emacs to it. Using
-the value of @code{oldbuf}, it inserts the region of text from the old
-buffer into the new buffer; and then using @code{save-excursion}, it
-brings you back to your original buffer.
+In summary, @code{append-to-buffer} works as follows: it saves the
+value of the current buffer in the variable called @code{oldbuf}. It
+gets the new buffer (creating one if need be) and switches Emacs'
+attention to it. Using the value of @code{oldbuf}, it inserts the
+region of text from the old buffer into the new buffer; and then using
+@code{save-excursion}, it brings you back to your original buffer.
In looking at @code{append-to-buffer}, you have explored a fairly
complex function. It shows how to use @code{let} and
to which the name refers.
@menu
-* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}.
-* insert-buffer:: Read-only, and with @code{or}.
-* beginning-of-buffer:: Shows @code{goto-char},
- @code{point-min}, and @code{push-mark}.
+* copy-to-buffer::
+* insert-buffer::
+* beginning-of-buffer::
* Second Buffer Related Review::
* optional Exercise::
@end menu
After understanding how @code{append-to-buffer} works, it is easy to
understand @code{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
-@code{copy-to-buffer} function is almost the same as the code for
-@code{append-to-buffer}, except that @code{erase-buffer} and a second
-@code{save-excursion} are used. (@xref{append-to-buffer, , The
-Definition of @code{append-to-buffer}}, for the description of
-@code{append-to-buffer}.)
+buffer, but instead of adding to the second buffer, it replaces all the
+previous text in the second buffer.
@need 800
-The body of @code{copy-to-buffer} looks like this
+The body of @code{copy-to-buffer} looks like this,
@smallexample
@group
@dots{}
-(interactive "BCopy to buffer:@: \nr")
- (let ((oldbuf (current-buffer)))
+(interactive "BCopy to buffer: \nr")
+(let ((oldbuf (current-buffer)))
+ (with-current-buffer (get-buffer-create buffer)
+ (barf-if-buffer-read-only)
+ (erase-buffer)
(save-excursion
- (set-buffer (get-buffer-create buffer))
- (erase-buffer)
- (save-excursion
- (insert-buffer-substring oldbuf start end)))))
+ (insert-buffer-substring oldbuf start end)))))
@end group
@end smallexample
-This code is similar to the code in @code{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
-@code{append-to-buffer}: the @code{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,
-@code{save-excursion} is used for a second time and the new text is
-inserted.
+The @code{copy-to-buffer} function has a simpler @code{interactive}
+expression than @code{append-to-buffer}.
+
+@need 800
+The definition then says
+
+@smallexample
+(with-current-buffer (get-buffer-create buffer) @dots{}
+@end smallexample
+
+First, look at the earliest inner expression; that is evaluated first.
+That expression starts with @code{get-buffer-create buffer}. The
+function tells the computer to use the buffer with the name specified
+as the one to which you are copying, or if such a buffer does not
+exist, to create it. Then, the @code{with-current-buffer} function
+evaluates its body with that buffer temporarily current.
+
+(This demonstrates another way to shift the computer's attention but
+not the user's. The @code{append-to-buffer} function showed how to do
+the same with @code{save-excursion} and @code{set-buffer}.
+@code{with-current-buffer} is a newer, and arguably easier,
+mechanism.)
+
+The @code{barf-if-buffer-read-only} function sends you an error
+message saying the buffer is read-only if you cannot modify it.
-Why is @code{save-excursion} used twice? Consider again what the
-function does.
+The next line has the @code{erase-buffer} function as its sole
+contents. That function erases the buffer.
+
+Finally, the last two lines contain the @code{save-excursion}
+expression with @code{insert-buffer-substring} as its body.
+The @code{insert-buffer-substring} expression copies the text from
+the buffer you are in (and you have not seen the computer shift its
+attention, so you don't know that that buffer is now called
+@code{oldbuf}).
+
+Incidently, this is what is meant by `replacement'. To replace text,
+Emacs erases the previous text and then inserts new text.
@need 1250
In outline, the body of @code{copy-to-buffer} looks like this:
@smallexample
@group
(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer})
- (save-excursion ; @r{First use of @code{save-excursion}.}
- @var{change-buffer}
+ (@var{with-the-buffer-you-are-copying-to}
+ (@var{but-do-not-erase-or-copy-to-a-read-only-buffer})
(erase-buffer)
- (save-excursion ; @r{Second use of @code{save-excursion}.}
+ (save-excursion
@var{insert-substring-from-}@code{oldbuf}@var{-into-buffer})))
@end group
@end smallexample
-The first use of @code{save-excursion} returns Emacs to the buffer from
-which the text is being copied. That is clear, and is just like its use
-in @code{append-to-buffer}. Why the second use? The reason is that
-@code{insert-buffer-substring} always leaves point at the @emph{end} of
-the region being inserted. The second @code{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 @code{copy-to-buffer} function returns
-the user to the original buffer when done---but if the user @emph{then}
-switches to the copied-to buffer, point will go to the beginning of the
-text. Thus, this use of a second @code{save-excursion} is a little
-nicety.)
-
@node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex
@comment node-name, next, previous, up
@section The Definition of @code{insert-buffer}
Here is a discussion based on the original code. The code was
simplified in 2003 and is harder to understand.
+@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see
+a discussion of the new body.)
+
In addition, this code illustrates the use of @code{interactive} with a
buffer that might be @dfn{read-only} and the important distinction
between the name of an object and the object actually referred to.
@menu
* insert-buffer code::
-* insert-buffer interactive:: When you can read, but not write.
-* insert-buffer body:: The body has an @code{or} and a @code{let}.
-* if & or:: Using an @code{if} instead of an @code{or}.
-* Insert or:: How the @code{or} expression works.
-* Insert let:: Two @code{save-excursion} expressions.
+* insert-buffer interactive::
+* insert-buffer body::
+* if & or::
+* Insert or::
+* Insert let::
+* New insert-buffer ::
@end menu
@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer
@end ifnottex
@need 800
-Here is the code:
+Here is the earlier code:
@smallexample
@group
buffer:@: }.
@menu
-* Read-only buffer:: When a buffer cannot be modified.
-* b for interactive:: An existing buffer or else its name.
+* Read-only buffer::
+* b for interactive::
@end menu
@node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive
enabled. If the buffer does not exist, you receive a message that
says ``No match''; your terminal may beep at you as well.
+The new and simplified code generates a list for @code{interactive}.
+It uses the @code{barf-if-buffer-read-only} and @code{read-buffer}
+functions with which we are already familiar and the @code{progn}
+special form with which we are not. (It will be described later.)
+
@node insert-buffer body, if & or, insert-buffer interactive, insert-buffer
@comment node-name, next, previous, up
@subsection The Body of the @code{insert-buffer} Function
(or (holding-on-to-guest) (find-and-take-arm-of-guest))
@end smallexample
-@node Insert let, , Insert or, insert-buffer
+@node Insert let, New insert-buffer , Insert or, insert-buffer
@comment node-name, next, previous, up
@subsection The @code{let} Expression in @code{insert-buffer}
use @code{or}. All these functions are building blocks that we will
find and use again and again.
+@node New insert-buffer , , Insert let, insert-buffer
+@comment node-name, next, previous, up
+@subsection New Body for @code{insert-buffer}
+@findex insert-buffer, new version body
+@findex new version body for insert-buffer
+
+The body in the GNU Emacs 22 version is more confusing than the original.
+
+@need 1250
+It consists of two expressions,
+
+@smallexample
+@group
+ (push-mark
+ (save-excursion
+ (insert-buffer-substring (get-buffer buffer))
+ (point)))
+
+ nil
+@end group
+@end smallexample
+
+@noindent
+except, and this is what confuses novices, very important work is done
+inside the @code{push-mark} expression.
+
+The @code{get-buffer} function returns a buffer with the name
+provided. You will note that the function is @emph{not} called
+@code{get-buffer-create}; it does not create a buffer if one does not
+already exist. The buffer returned by @code{get-buffer}, an existing
+buffer, is passed to @code{insert-buffer-substring}, which inserts the
+whole of the buffer (since you did not specify anything else).
+
+The location into which the buffer is inserted is recorded by
+@code{push-mark}. Then the function returns @code{nil}, the value of
+its last command. Put another way, the @code{insert-buffer} function
+exists only to produce a side effect, inserting another buffer, not to
+return any value.
+
@node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex
@comment node-name, next, previous, up
@section Complete Definition of @code{beginning-of-buffer}
As previously described, when invoked without an argument,
@code{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 @kbd{M-<}, which will move the cursor to
-the beginning of the buffer, or with a key command such as @kbd{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.
+buffer (in truth, the accessible portion 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 @kbd{M-<}, which will move the cursor to the beginning of the
+buffer, or with a key command such as @kbd{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 @code{beginning-of-buffer} function can be called with or without an
argument. The use of the argument is optional.
@menu
* Optional Arguments::
-* beginning-of-buffer opt arg:: Example with optional argument.
+* beginning-of-buffer opt arg::
* beginning-of-buffer complete::
@end menu
@cindex Optional arguments
@cindex Keyword
@findex optional
-However, optional arguments are a feature of Lisp: a @dfn{keyword} may
-be used to tell the Lisp interpreter that an argument is optional.
-The keyword is @code{&optional}. (The @samp{&} in front of
+However, optional arguments are a feature of Lisp: a particular
+@dfn{keyword} is used to tell the Lisp interpreter that an argument is
+optional. The keyword is @code{&optional}. (The @samp{&} in front of
@samp{optional} is part of the keyword.) In a function definition, if
-an argument follows the keyword @code{&optional}, a value does not
-need to be passed to that argument when the function is called.
+an argument follows the keyword @code{&optional}, no value need be
+passed to that argument when the function is called.
@need 1200
The first line of the function definition of @code{beginning-of-buffer}
(defun beginning-of-buffer (&optional arg)
"@var{documentation}@dots{}"
(interactive "P")
- (push-mark)
+ (or (@var{is-the-argument-a-cons-cell} arg)
+ (and @var{are-both-transient-mark-mode-and-mark-active-true})
+ (push-mark))
+ (let (@var{determine-size-and-set-it})
(goto-char
(@var{if-there-is-an-argument}
@var{figure-out-where-to-go}
@var{else-go-to}
(point-min))))
+ @var{do-nicety}
@end group
@end smallexample
function except that the @code{interactive} expression has @code{"P"}
as an argument and the @code{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 @code{"P"} in the @code{interactive} expression tells Emacs to pass
-a prefix argument, if there is one, to the function. A prefix argument
-is made by typing the @key{META} key followed by a number, or by typing
-@kbd{C-u} and then a number (if you don't type a number, @kbd{C-u}
-defaults to 4).
-
-The true-or-false-test of the @code{if} expression is simple: it is
-simply the argument @code{arg}. If @code{arg} has a value that is not
-@code{nil}, which will be the case if @code{beginning-of-buffer} is
-called with an argument, then this true-or-false-test will return true
-and the then-part of the @code{if} expression will be evaluated. On the
+there is an argument that is not a cons cell.
+
+(Since I do not explain a cons cell for many more chapters, please
+consider ignoring the function @code{consp}. @xref{List
+Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type,
+, Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference
+Manual}.)
+
+The @code{"P"} in the @code{interactive} expression tells Emacs to
+pass a prefix argument, if there is one, to the function in raw form.
+A prefix argument is made by typing the @key{META} key followed by a
+number, or by typing @kbd{C-u} and then a number. (If you don't type
+a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase
+@code{"p"} in the @code{interactive} expression causes the function to
+convert a prefix arg to a number.)
+
+The true-or-false-test of the @code{if} expression looks complex, but
+it is not: it checks whether @code{arg} has a value that is not
+@code{nil} and whether it is a cons cell. (That is what @code{consp}
+does; it checks whether its argument is a cons cell.) If @code{arg}
+has a value that is not @code{nil} (and is not a cons cell), which
+will be the case if @code{beginning-of-buffer} is called with a
+numeric argument, then this true-or-false-test will return true and
+the then-part of the @code{if} expression will be evaluated. On the
other hand, if @code{beginning-of-buffer} is not called with an
argument, the value of @code{arg} will be @code{nil} and the else-part
-of the @code{if} expression will be evaluated. The else-part is simply
-@code{point-min}, and when this is the outcome, the whole
-@code{goto-char} expression is @code{(goto-char (point-min))}, which is
-how we saw the @code{beginning-of-buffer} function in its simplified
-form.
+of the @code{if} expression will be evaluated. The else-part is
+simply @code{point-min}, and when this is the outcome, the whole
+@code{goto-char} expression is @code{(goto-char (point-min))}, which
+is how we saw the @code{beginning-of-buffer} function in its
+simplified form.
@node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer
@subsection @code{beginning-of-buffer} with an Argument
@group
(if (> (buffer-size) 10000)
;; @r{Avoid overflow for large buffer sizes!}
- (* (prefix-numeric-value arg) (/ (buffer-size) 10))
+ (* (prefix-numeric-value arg)
+ (/ size 10))
(/
(+ 10
(*
- (buffer-size) (prefix-numeric-value arg))) 10))
+ size (prefix-numeric-value arg))) 10)))
@end group
@end smallexample
In @code{beginning-of-buffer}, the inner @code{if} expression tests
whether the size of the buffer is greater than 10,000 characters. To do
-this, it uses the @code{>} function and the @code{buffer-size} function.
+this, it uses the @code{>} function and the computation of @code{size}
+that comes from the let expression.
+
+In the old days, the function @code{buffer-size} was used. Not only
+was that function called several times, it gave the size of the whole
+buffer, not the accessible part. The computation makes much more
+sense when it handles just the accessible part. (@xref{Narrowing &
+Widening, , Narrowing and Widening}, for more information on focusing
+attention to an `accessible' part.)
@need 800
The line looks like this:
@smallexample
-(if (> (buffer-size) 10000)
+(if (> size 10000)
@end smallexample
@need 1200
@group
(*
(prefix-numeric-value arg)
- (/ (buffer-size) 10))
+ (/ size 10))
@end group
@end smallexample
@findex / @r{(division)}
@cindex Division
-The second argument is @code{(/ (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, @code{/} is used for division, just as @code{*} is
-used for multiplication.)
+The second argument is @code{(/ size 10)}. This expression divides
+the numeric value by ten --- the numeric value of the size of the
+accessible portion of the buffer. This produces a number that tells
+how many characters make up one tenth of the buffer size. (In Lisp,
+@code{/} is used for division, just as @code{*} is used for
+multiplication.)
@need 1200
In the multiplication expression as a whole, this amount is multiplied
@smallexample
@group
(* @var{numeric-value-of-prefix-arg}
- @var{number-of-characters-in-one-tenth-of-the-buffer})
+ @var{number-of-characters-in-one-tenth-of-the-accessible-buffer})
@end group
@end smallexample
@noindent
If, for example, the prefix argument is @samp{7}, the one-tenth value
-will be multiplied by 7 to give a position 70% of the way through the
-buffer.
+will be multiplied by 7 to give a position 70% of the way through.
@need 1200
-The result of all this is that if the buffer is large, the
-@code{goto-char} expression reads like this:
+The result of all this is that if the accessible portion of the buffer
+is large, the @code{goto-char} expression reads like this:
@smallexample
@group
(goto-char (* (prefix-numeric-value arg)
- (/ (buffer-size) 10)))
+ (/ size 10)))
@end group
@end smallexample
@c Keep this on one line.
@smallexample
-(/ (+ 10 (* (buffer-size) (prefix-numeric-value arg))) 10))
+(/ (+ 10 (* size (prefix-numeric-value arg))) 10))
@end smallexample
@need 1200
(/
(+ 10
(*
- (buffer-size)
+ size
(prefix-numeric-value arg)))
10))
@end group
@need 1200
@noindent
Looking at parentheses, we see that the innermost operation is
-@code{(prefix-numeric-value arg)}, which converts the raw argument to a
-number. This number is multiplied by the buffer size in the following
-expression:
+@code{(prefix-numeric-value arg)}, which converts the raw argument to
+a number. In the following expression, this number is multiplied by
+the size of the accessible portion of the buffer:
@smallexample
-(* (buffer-size) (prefix-numeric-value arg))
+(* size (prefix-numeric-value arg))
@end smallexample
@noindent
Here is the complete text of the @code{beginning-of-buffer} function:
@sp 1
+@c In GNU Emacs 22
+@smallexample
+@group
+(defun beginning-of-buffer (&optional arg)
+ "Move point to the beginning of the buffer;
+leave mark at previous position.
+With \\[universal-argument] prefix,
+do not set mark at previous position.
+With numeric arg N,
+put point N/10 of the way from the beginning.
+
+If the buffer is narrowed,
+this command uses the beginning and size
+of the accessible part of the buffer.
+@end group
+
+@group
+Don't use this command in Lisp programs!
+\(goto-char (point-min)) is faster
+and avoids clobbering the mark."
+ (interactive "P")
+ (or (consp arg)
+ (and transient-mark-mode mark-active)
+ (push-mark))
+@end group
+@group
+ (let ((size (- (point-max) (point-min))))
+ (goto-char (if (and arg (not (consp arg)))
+ (+ (point-min)
+ (if (> size 10000)
+ ;; Avoid overflow for large buffer sizes!
+ (* (prefix-numeric-value arg)
+ (/ size 10))
+ (/ (+ 10 (* size (prefix-numeric-value arg))) 10)))
+ (point-min))))
+ (if arg (forward-line 1)))
+@end group
+@end smallexample
+
+@ignore
+From before GNU Emacs 22
@smallexample
@group
(defun beginning-of-buffer (&optional arg)
(if arg (forward-line 1)))
@end group
@end smallexample
+@end ignore
@noindent
Except for two small points, the previous discussion shows how this
In the documentation string, there is reference to an expression:
@smallexample
-\(goto-char (point-min))
+\\[universal-argument]
@end smallexample
@noindent
-A @samp{\} is used before the first parenthesis of this expression.
-This @samp{\} 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.
+A @samp{\\} is used before the first square bracket of this
+expression. This @samp{\\} tells the Lisp interpreter to substitute
+whatever key is currently bound to the @samp{[@dots{}]}. In the case
+of @code{universal-argument}, that is usually @kbd{C-u}, but it might
+be different. (@xref{Documentation Tips, , Tips for Documentation
+Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more
+information.)
@need 1200
-Finally, the last line of the @code{beginning-of-buffer} command says to
-move point to the beginning of the next line if the command is
+Finally, the last line of the @code{beginning-of-buffer} command says
+to move point to the beginning of the next line if the command is
invoked with an argument:
@smallexample
appropriate tenths position in the buffer. This is a flourish that
means that the cursor is always located @emph{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.
+perhaps, not necessary, but which, if it did not occur, would be sure
+to draw complaints.
+
+On the other hand, it also means that if you specify the command with
+a @kbd{C-u}, but without a number, that is to say, if the `raw prefix
+argument' is simply a cons cell, then the command puts you at the
+beginning of the second line @dots{} I don't know whether this is
+intended or whether no one has dealt with the code to avoid this
+happening.
@node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex
@comment node-name, next, previous, up
argument that is not @code{nil}; if none return a value that is not
@code{nil}, return @code{nil}. In brief, return the first true value
of the arguments; return a true value if one @emph{or} any of the
-other are true.
+others are true.
@item and
Evaluate each argument in sequence, and if any are @code{nil}, return
novices.
@menu
-* Narrowing advantages:: The advantages of narrowing
-* save-restriction:: The @code{save-restriction} special form.
-* what-line:: The number of the line that point is on.
+* Narrowing advantages::
+* save-restriction::
+* what-line::
* narrow Exercise::
@end menu
@end group
@end smallexample
+@ignore
+Emacs 22
+/usr/local/src/emacs/lisp/simple.el
+
+(defun what-line ()
+ "Print the current buffer line number and narrowed line number of point."
+ (interactive)
+ (let ((start (point-min))
+ (n (line-number-at-pos)))
+ (if (= start 1)
+ (message "Line %d" n)
+ (save-excursion
+ (save-restriction
+ (widen)
+ (message "line %d (narrowed line %d)"
+ (+ n (line-number-at-pos start) -1) n))))))
+
+(defun line-number-at-pos (&optional pos)
+ "Return (narrowed) buffer line number at position POS.
+If POS is nil, use current buffer location.
+Counting starts at (point-min), so the value refers
+to the contents of the accessible portion of the buffer."
+ (let ((opoint (or pos (point))) start)
+ (save-excursion
+ (goto-char (point-min))
+ (setq start (point))
+ (goto-char opoint)
+ (forward-line 0)
+ (1+ (count-lines start (point))))))
+
+(defun count-lines (start end)
+ "Return number of lines between START and END.
+This is usually the number of newlines between them,
+but can be one more if START is not equal to END
+and the greater of them is not at the start of a line."
+ (save-excursion
+ (save-restriction
+ (narrow-to-region start end)
+ (goto-char (point-min))
+ (if (eq selective-display t)
+ (save-match-data
+ (let ((done 0))
+ (while (re-search-forward "[\n\C-m]" nil t 40)
+ (setq done (+ 40 done)))
+ (while (re-search-forward "[\n\C-m]" nil t 1)
+ (setq done (+ 1 done)))
+ (goto-char (point-max))
+ (if (and (/= start end)
+ (not (bolp)))
+ (1+ done)
+ done)))
+ (- (buffer-size) (forward-line (buffer-size)))))))
+@end ignore
+
@node what-line, narrow Exercise, save-restriction, Narrowing & Widening
@comment node-name, next, previous, up
@section @code{what-line}
well as your line number in a widened buffer. The recent version is
more complex than the version shown here. If you feel adventurous,
you might want to look at it after figuring out how this version
-works. The newer version uses a conditional to determine whether the
-buffer has been narrowed, and rather than use @code{beginning-of-line}
-to move point to the beginning of the current line, if need be, the
-function uses @code{(forward-line 0)}.)
+works. You will probably need to use @kbd{C-h f}
+(@code{describe-function}). The newer version uses a conditional to
+determine whether the buffer has been narrowed.
-The function as shown here has a documentation line and is
-interactive, as you would expect. The next two lines use the
+(Also, it uses @code{line-number-at-pos}, which among other simple
+expressions, such as @code{(goto-char (point-min))}, moves point to
+the beginning of the current line with @code{(forward-line 0)} rather
+than @code{beginning-of-line}.)
+
+The @code{what-line} function as shown here has a documentation line
+and is interactive, as you would expect. The next two lines use the
functions @code{save-restriction} and @code{widen}.
The @code{save-restriction} special form notes whatever narrowing is in
@end group
@end smallexample
-The @code{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 @samp{%d},
-@samp{%s}, or @samp{%c} to print arguments that follow the string.
-@samp{%d} prints the argument as a decimal, so the message will say
-something such as @samp{Line 243}.
+The @code{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 a
+@samp{%d} expression to print a following argument. @samp{%d} prints
+the argument as a decimal, so the message will say something such as
+@samp{Line 243}.
@need 1200
-
The number that is printed in place of the @samp{%d} is computed by the
last line of the function:
(1+ (count-lines 1 (point)))
@end smallexample
+@ignore
+GNU Emacs 22
+
+(defun count-lines (start end)
+ "Return number of lines between START and END.
+This is usually the number of newlines between them,
+but can be one more if START is not equal to END
+and the greater of them is not at the start of a line."
+ (save-excursion
+ (save-restriction
+ (narrow-to-region start end)
+ (goto-char (point-min))
+ (if (eq selective-display t)
+ (save-match-data
+ (let ((done 0))
+ (while (re-search-forward "[\n\C-m]" nil t 40)
+ (setq done (+ 40 done)))
+ (while (re-search-forward "[\n\C-m]" nil t 1)
+ (setq done (+ 1 done)))
+ (goto-char (point-max))
+ (if (and (/= start end)
+ (not (bolp)))
+ (1+ done)
+ done)))
+ (- (buffer-size) (forward-line (buffer-size)))))))
+@end ignore
+
@noindent
What this does is count the lines from the first position of the
buffer, indicated by the @code{1}, up to @code{(point)}, and then add
@cindex Properties, mention of @code{buffer-substring-no-properties}
(@code{buffer-substring} is a previously unmentioned function you will
have to investigate yourself; or perhaps you will have to use
-@code{buffer-substring-no-properties} @dots{}, yet another function
-and one that introduces text properties, a feature otherwise not
-discussed here. @xref{Text Properties, , Text Properties, elisp, The
-GNU Emacs Lisp Reference Manual}. Additionally, do you really need
-@code{goto-char} or @code{point-min}? Or can you write the function
-without them?)
+@code{buffer-substring-no-properties} or
+@code{filter-buffer-substring} @dots{}, yet other functions. Text
+properties are a feature otherwise not discussed here. @xref{Text
+Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference
+Manual}.
+
+Additionally, do you really need @code{goto-char} or @code{point-min}?
+Or can you write the function without them?)
@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top
@comment node-name, next, previous, up
namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.)
@menu
-* Strange Names:: An historical aside: why the strange names?
-* car & cdr:: Functions for extracting part of a list.
-* cons:: Constructing a list.
-* nthcdr:: Calling @code{cdr} repeatedly.
+* Strange Names::
+* car & cdr::
+* cons::
+* nthcdr::
* nth::
-* setcar:: Changing the first element of a list.
-* setcdr:: Changing the rest of a list.
+* setcar::
+* setcdr::
* cons Exercise::
@end menu
@menu
* Build a list::
-* length:: How to find the length of a list.
+* length::
@end menu
@node Build a list, length, cons, cons
What you see, if you evaluate this, is the error message
@smallexample
-Wrong number of arguments: #<subr length>, 0
+Lisp error: (wrong-number-of-arguments length 0)
@end smallexample
@noindent
length the function is measuring. (Note that @emph{one} list is
@emph{one} argument, even if the list has many elements inside it.)
-The part of the error message that says @samp{#<subr length>} is the
-name of the function. This is written with a special notation,
-@samp{#<subr}, that indicates that the function @code{length} is one
-of the primitive functions written in C rather than in Emacs Lisp.
-(@samp{subr} is an abbreviation for `subroutine'.) @xref{What Is a
-Function, , What Is a Function?, elisp , The GNU Emacs Lisp Reference
-Manual}, for more about subroutines.
+The part of the error message that says @samp{length} is the name of
+the function.
+
+@ignore
+@code{length} is still a subroutine, but you need C-h f to discover that.
+
+In an earlier version:
+ This is written with a special notation, @samp{#<subr},
+ that indicates that the function @code{length} is one of the primitive
+ functions written in C rather than in Emacs Lisp. (@samp{subr} is an
+ abbreviation for `subroutine'.) @xref{What Is a Function, , What Is a
+ Function?, elisp , The GNU Emacs Lisp Reference Manual}, for more
+ about subroutines.
+@end ignore
@node nthcdr, nth, cons, car cdr & cons
@comment node-name, next, previous, up
@noindent
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 @kbd{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.)
+the expression and typing @kbd{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. Incidently, when
+there is nothing on the line after the final parentheses, such as a
+comment, point can be on the next line. Thus, if your cursor is in
+the first column of the next line, you do not need to move it.
+Indeed, Emacs permits any amount of white space after the final
+parenthesis.)
@need 1200
When we evaluate the variable @code{animals}, we see that it is bound to
sources with `clip' and all occurrences of `killed' with `clipped'.)
@menu
-* Storing Text:: Text is stored in a list.
-* zap-to-char:: Cutting out text up to a character.
-* kill-region:: Cutting text out of a region.
-* Digression into C:: Minor note on C programming language macros.
-* defvar:: How to give a variable an initial value.
-* copy-region-as-kill:: A definition for copying text.
+* Storing Text::
+* zap-to-char::
+* kill-region::
+* copy-region-as-kill::
+* Digression into C::
+* defvar::
* cons & search-fwd Review::
* search Exercises::
@end menu
@need 1200
@noindent
-The function @code{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:
+The function @code{cons} can be used to create a new list from a piece
+of text (an `atom', to use the jargon) and an existing list, like
+this:
@smallexample
@group
@section @code{zap-to-char}
@findex zap-to-char
-The @code{zap-to-char} function barely changed between GNU Emacs
-version 19 and GNU Emacs version 21. However, @code{zap-to-char}
-calls another function, @code{kill-region}, which enjoyed a major rewrite
-on the way to version 21.
+The @code{zap-to-char} function changed a little between GNU Emacs
+version 19 and GNU Emacs version 22. However, @code{zap-to-char}
+calls another function, @code{kill-region}, which enjoyed a major
+rewrite.
The @code{kill-region} function in Emacs 19 is complex, but does not
use code that is important at this time. We will skip it.
-The @code{kill-region} function in Emacs 21 is easier to read than the
+The @code{kill-region} function in Emacs 22 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 @code{zap-to-char} function.
@menu
-* Complete zap-to-char:: The complete implementation.
-* zap-to-char interactive:: A three part interactive expression.
-* zap-to-char body:: A short overview.
-* search-forward:: How to search for a string.
-* progn:: The @code{progn} special form.
-* Summing up zap-to-char:: Using @code{point} and @code{search-forward}.
+* Complete zap-to-char::
+* zap-to-char interactive::
+* zap-to-char body::
+* search-forward::
+* progn::
+* Summing up zap-to-char::
@end menu
@node Complete zap-to-char, zap-to-char interactive, zap-to-char, zap-to-char
manipulates text, and we will focus attention on them as well as on the
deletion command.
-@need 800
-Here is the complete text of the version 19 implementation of the function:
-
-@c v 19
-@smallexample
-@group
+@ignore
+@c GNU Emacs version 19
(defun zap-to-char (arg char) ; version 19 implementation
"Kill up to and including ARG'th occurrence of CHAR.
Goes backward if ARG is negative; error if CHAR not found."
(search-forward
(char-to-string char) nil nil arg)
(point))))
+@end ignore
+
+@need 1250
+Here is the complete text of the version 22 implementation of the function:
+
+@c GNU Emacs 22
+@smallexample
+@group
+(defun zap-to-char (arg char)
+ "Kill up to and including ARG'th occurrence of CHAR.
+Case is ignored if `case-fold-search' is non-nil in the current buffer.
+Goes backward if ARG is negative; error if CHAR not found."
+ (interactive "p\ncZap to char: ")
+ (if (char-table-p translation-table-for-input)
+ (setq char (or (aref translation-table-for-input char) char)))
+ (kill-region (point) (progn
+ (search-forward (char-to-string char) nil nil arg)
+ (point))))
@end group
@end smallexample
this:
@smallexample
-(interactive "*p\ncZap to char: ")
-@end smallexample
-
-The part within quotation marks, @code{"*p\ncZap to char:@: "}, specifies
-three different things. First, and most simply, the asterisk, @samp{*},
-causes an error to be signaled if the buffer is read-only. This means that
-if you try @code{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, @samp{*}. 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
-@code{interactive}. According to the documentation for
-@code{interactive}, the asterisk, @samp{*}, should prevent the
-@code{zap-to-char} function from doing anything at all when the buffer
-is read only. In version 19, the function should not copy the text to
-the kill ring. It is a bug that it does.
-
-In version 21, the function is designed to copy the text to the kill
-ring; moreover, @code{interactive} is implemented correctly. So the
-asterisk, @samp{*}, had to be removed from the interactive
-specification. However, if you insert an @samp{*} yourself and
-evaluate the function definition, then the next time you run the
-@code{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 @code{zap-to-char} function are identical.
-
-Let us continue with the interactive specification.
+(interactive "p\ncZap to char: ")
+@end smallexample
-The second part of @code{"*p\ncZap to char:@: "} is the @samp{p}.
+The part within quotation marks, @code{"p\ncZap to char:@: "}, specifies
+two different things. First, and most simply, is the @samp{p}.
This part is separated from the next part by a newline, @samp{\n}.
The @samp{p} means that the first argument to the function will be
passed the value of a `processed prefix'. The prefix argument is
the function is called interactively without a prefix, 1 is passed to
this argument.
-The third part of @code{"*p\ncZap to char:@: "} is @samp{cZap to char:@:
-}. In this part, the lower case @samp{c} indicates that
-@code{interactive} expects a prompt and that the argument will be a
-character. The prompt follows the @samp{c} and is the string @samp{Zap
-to char:@: } (with a space after the colon to make it look good).
+The second part of @code{"p\ncZap to char:@: "} is
+@samp{cZap to char:@: }. In this part, the lower case @samp{c}
+indicates that @code{interactive} expects a prompt and that the
+argument will be a character. The prompt follows the @samp{c} and is
+the string @samp{Zap to char:@: } (with a space after the colon to
+make it look good).
What all this does is prepare the arguments to @code{zap-to-char} so they
are of the right type, and give the user a prompt.
+In a read-only buffer, the @code{zap-to-char} function copies the text
+to the kill ring, but does not remove it. The echo area displays a
+message saying that the buffer is read-ly. Also, the terminal may
+beep or blink at you.
+
+Let us continue with the interactive specification.
+
@node zap-to-char body, search-forward, zap-to-char interactive, zap-to-char
@comment node-name, next, previous, up
@subsection The Body of @code{zap-to-char}
The body of the @code{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 documentation is thorough. You do need to know the jargon meaning
+of the word `kill'.
+
The first part of the code looks like this:
@smallexample
-(kill-region (point) @dots{}
+(if (char-table-p translation-table-for-input)
+ (setq char (or (aref translation-table-for-input char) char)))
+(kill-region (point) (progn
+ (search-forward (char-to-string char) nil nil arg)
+ (point)))
@end smallexample
+@noindent
+@code{char-table-p} is an hitherto unseen function. It determines
+whether its argument is a character table. When it is, it sets the
+character passed to @code{zap-to-char} to one of them, if that
+character exists, or to the character itself. (This becomes important
+for certain characters in non-European languages. The @code{aref}
+function extracts an element from an array. It is an array-specific
+function that is not described in this document. @xref{Arrays, ,
+Arrays, elisp, The GNU Emacs Lisp Reference Manual}.)
+
@noindent
@code{(point)} is the current position of the cursor.
zapped-for-character in @code{zap-to-char}. If the search is
successful, @code{search-forward} leaves point immediately after the
last character in the target string. (In @code{zap-to-char}, the
-target string is just one character long.) If the search is
-backwards, @code{search-forward} leaves point just before the first
-character in the target. Also, @code{search-forward} returns @code{t}
-for true. (Moving point is therefore a `side effect'.)
+target string is just one character long. @code{zap-to-char} uses the
+function @code{char-to-string} to ensure that the computer treats that
+character as a string.) If the search is backwards,
+@code{search-forward} leaves point just before the first character in
+the target. Also, @code{search-forward} returns @code{t} for true.
+(Moving point is therefore a `side effect'.)
+
@need 1250
In @code{zap-to-char}, the @code{search-forward} function looks like this:
The second and last argument to @code{progn} is the expression
@code{(point)}. This expression returns the value of point, which in
this case will be the location to which it has been moved by
-@code{search-forward}. This value is returned by the @code{progn}
-expression and is passed to @code{kill-region} as @code{kill-region}'s
-second argument.
+@code{search-forward}. (In the source, a line that tells the function
+to go to the previous character, if it is going forward, was commented
+out in 1999; I don't remember whether that feature or mis-feature was
+ever a part of the distributed source.) The value of @code{point} is
+returned by the @code{progn} expression and is passed to
+@code{kill-region} as @code{kill-region}'s second argument.
@node Summing up zap-to-char, , progn, zap-to-char
@comment node-name, next, previous, up
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 @code{progn} special form is necessary because the @code{kill-region}
-command takes two arguments; and it would fail if @code{search-forward}
-and @code{point} expressions were written in sequence as two
-additional arguments. The @code{progn} expression is a single argument
-to @code{kill-region} and returns the one value that @code{kill-region}
-needs for its second argument.
+The @code{progn} special form is necessary because the
+@code{kill-region} command takes two arguments; and it would fail if
+@code{search-forward} and @code{point} expressions were written in
+sequence as two additional arguments. The @code{progn} expression is
+a single argument to @code{kill-region} and returns the one value that
+@code{kill-region} needs for its second argument.
-@node kill-region, Digression into C, zap-to-char, Cutting & Storing Text
+@node kill-region, copy-region-as-kill, zap-to-char, Cutting & Storing Text
@comment node-name, next, previous, up
@section @code{kill-region}
@findex kill-region
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 @code{condition-case} and
+@ignore
+GNU Emacs 22:
+
+(defun kill-region (beg end &optional yank-handler)
+ "Kill (\"cut\") text between point and mark.
+This deletes the text from the buffer and saves it in the kill ring.
+The command \\[yank] can retrieve it from there.
+\(If you want to kill and then yank immediately, use \\[kill-ring-save].)
+
+If you want to append the killed region to the last killed text,
+use \\[append-next-kill] before \\[kill-region].
+
+If the buffer is read-only, Emacs will beep and refrain from deleting
+the text, but put the text in the kill ring anyway. This means that
+you can use the killing commands to copy text from a read-only buffer.
+
+This is the primitive for programs to kill text (as opposed to deleting it).
+Supply two arguments, character positions indicating the stretch of text
+ to be killed.
+Any command that calls this function is a \"kill command\".
+If the previous command was also a kill command,
+the text killed this time appends to the text killed last time
+to make one entry in the kill ring.
+
+In Lisp code, optional third arg YANK-HANDLER, if non-nil,
+specifies the yank-handler text property to be set on the killed
+text. See `insert-for-yank'."
+ ;; Pass point first, then mark, because the order matters
+ ;; when calling kill-append.
+ (interactive (list (point) (mark)))
+ (unless (and beg end)
+ (error "The mark is not set now, so there is no region"))
+ (condition-case nil
+ (let ((string (filter-buffer-substring beg end t)))
+ (when string ;STRING is nil if BEG = END
+ ;; Add that string to the kill ring, one way or another.
+ (if (eq last-command 'kill-region)
+ (kill-append string (< end beg) yank-handler)
+ (kill-new string nil yank-handler)))
+ (when (or string (eq last-command 'kill-region))
+ (setq this-command 'kill-region))
+ nil)
+ ((buffer-read-only text-read-only)
+ ;; The code above failed because the buffer, or some of the characters
+ ;; in the region, are read-only.
+ ;; We should beep, in case the user just isn't aware of this.
+ ;; However, there's no harm in putting
+ ;; the region's text in the kill ring, anyway.
+ (copy-region-as-kill beg end)
+ ;; Set this-command now, so it will be set even if we get an error.
+ (setq this-command 'kill-region)
+ ;; This should barf, if appropriate, and give us the correct error.
+ (if kill-read-only-ok
+ (progn (message "Read only text copied to kill ring") nil)
+ ;; Signal an error if the buffer is read-only.
+ (barf-if-buffer-read-only)
+ ;; If the buffer isn't read-only, the text is.
+ (signal 'text-read-only (list (current-buffer)))))))
+
+
+kfstorm 18-Jan-03): (defun kill-region (beg end &optional yank-handler)
+rms 11-Mar-06): "Kill (\"cut\") text between point and mark.
+rms 11-Mar-06): This deletes the text from the buffer and saves it in the kill ring.
+jimb 21-Dec-91): The command \\[yank] can retrieve it from there.
+eliz 16-Feb-01): \(If you want to kill and then yank immediately, use \\[kill-ring-save].)
+eliz 16-Feb-01):
+eliz 16-Feb-01): If you want to append the killed region to the last killed text,
+eliz 16-Feb-01): use \\[append-next-kill] before \\[kill-region].
+eliz 16-Feb-01):
+jimb 01-Feb-93): If the buffer is read-only, Emacs will beep and refrain from deleting
+jimb 01-Feb-93): the text, but put the text in the kill ring anyway. This means that
+jimb 01-Feb-93): you can use the killing commands to copy text from a read-only buffer.
+jimb 21-Dec-91):
+jimb 21-Dec-91): This is the primitive for programs to kill text (as opposed to deleting it).
+lektu 07-Jun-04): Supply two arguments, character positions indicating the stretch of text
+jimb 21-Dec-91): to be killed.
+jimb 21-Dec-91): Any command that calls this function is a \"kill command\".
+jimb 21-Dec-91): If the previous command was also a kill command,
+jimb 21-Dec-91): the text killed this time appends to the text killed last time
+kfstorm 18-Jan-03): to make one entry in the kill ring.
+kfstorm 18-Jan-03):
+uid68472 18-Feb-04): In Lisp code, optional third arg YANK-HANDLER, if non-nil,
+uid68472 18-Feb-04): specifies the yank-handler text property to be set on the killed
+uid68472 18-Feb-04): text. See `insert-for-yank'."
+rms 21-May-06): ;; Pass point first, then mark, because the order matters
+rms 21-May-06): ;; when calling kill-append.
+rms 21-May-06): (interactive (list (point) (mark)))
+rms 04-Sep-06): (unless (and beg end)
+rms 04-Sep-06): (error "The mark is not set now, so there is no region"))
+kwzh 19-Nov-97): (condition-case nil
+rms 29-Mar-05): (let ((string (filter-buffer-substring beg end t)))
+monnier 07-Dec-99): (when string ;STRING is nil if BEG = END
+monnier 07-Dec-99): ;; Add that string to the kill ring, one way or another.
+monnier 07-Dec-99): (if (eq last-command 'kill-region)
+kfstorm 18-Jan-03): (kill-append string (< end beg) yank-handler)
+kfstorm 18-Jan-03): (kill-new string nil yank-handler)))
+kai 28-May-03): (when (or string (eq last-command 'kill-region))
+uid68472 18-Feb-04): (setq this-command 'kill-region))
+uid68472 18-Feb-04): nil)
+kwzh 19-Nov-97): ((buffer-read-only text-read-only)
+kwzh 19-Nov-97): ;; The code above failed because the buffer, or some of the characters
+kwzh 19-Nov-97): ;; in the region, are read-only.
+kwzh 19-Nov-97): ;; We should beep, in case the user just isn't aware of this.
+kwzh 19-Nov-97): ;; However, there's no harm in putting
+kwzh 19-Nov-97): ;; the region's text in the kill ring, anyway.
+kwzh 19-Nov-97): (copy-region-as-kill beg end)
+rms 19-May-98): ;; Set this-command now, so it will be set even if we get an error.
+rms 19-May-98): (setq this-command 'kill-region)
+rms 19-May-98): ;; This should barf, if appropriate, and give us the correct error.
+kwzh 19-Nov-97): (if kill-read-only-ok
+uid68472 18-Feb-04): (progn (message "Read only text copied to kill ring") nil)
+kwzh 19-Nov-97): ;; Signal an error if the buffer is read-only.
+kwzh 19-Nov-97): (barf-if-buffer-read-only)
+kwzh 19-Nov-97): ;; If the buffer isn't read-only, the text is.
+kwzh 19-Nov-97): (signal 'text-read-only (list (current-buffer)))))))
+
+@end ignore
+
+The Emacs 22 version of that function uses @code{condition-case} and
@code{copy-region-as-kill}, both of which we will explain.
@code{condition-case} is an important special form.
contains the code that is called in the event of an error.
@menu
-* Complete kill-region:: The function definition.
-* condition-case:: Dealing with a problem.
-* delete-and-extract-region:: Doing the work.
+* Complete kill-region::
+* condition-case::
+* Lisp macro::
@end menu
@node Complete kill-region, condition-case, kill-region, kill-region
@need 1200
We will go through the @code{condition-case} code in a moment. First,
-let us look at the original definition of @code{kill-region}, with
-comments added (the newer definition has an optional third argument
-and is more complex):
+let us look at the definition of @code{kill-region}, with comments
+added:
+
+@c GNU Emacs 22:
+@smallexample
+@group
+(defun kill-region (beg end)
+ "Kill (\"cut\") text between point and mark.
+This deletes the text from the buffer and saves it in the kill ring.
+The command \\[yank] can retrieve it from there. @dots{} "
+@end group
+
+@group
+ ;; @bullet{} Since order matters, pass point first.
+ (interactive (list (point) (mark)))
+ ;; @bullet{} And tell us if we cannot cut the text.
+ (unless (and beg end)
+ (error "The mark is not set now, so there is no region"))
+@end group
+
+@group
+ ;; @bullet{} `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
+@end group
+
+@group
+ ;; @bullet{} The second argument to `condition-case' tells the
+ ;; Lisp interpreter what to do when all goes well.
+@end group
+
+@group
+ ;; It starts with a `let' function that extracts the string
+ ;; and tests whether it exists. If so (that is what the
+ ;; `when' checks), it calls an `if' function that determines
+ ;; whether the previous command was another call to
+ ;; `kill-region'; if it was, then the new text is appended to
+ ;; the previous text; if not, then a different function,
+ ;; `kill-new', is called.
+@end group
+
+@group
+ ;; The `kill-append' function concatenates the new string and
+ ;; the old. The `kill-new' function inserts text into a new
+ ;; item in the kill ring.
+@end group
+
+@group
+ ;; `when' is an `if' without an else-part. The second `when'
+ ;; again checks whether the current string exists; in
+ ;; addition, it checks whether the previous command was
+ ;; another call to `kill-region'. If one or the other
+ ;; condition is true, then it sets the current command to
+ ;; be `kill-region'.
+@end group
+@group
+ (let ((string (filter-buffer-substring beg end t)))
+ (when string ;STRING is nil if BEG = END
+ ;; Add that string to the kill ring, one way or another.
+ (if (eq last-command 'kill-region)
+@end group
+@group
+ ;; @minus{} `yank-handler' is an optional argument to
+ ;; `kill-region' that tells the `kill-append' and
+ ;; `kill-new' functions how deal with properties
+ ;; added to the text, such as `bold' or `italics'.
+ (kill-append string (< end beg) yank-handler)
+ (kill-new string nil yank-handler)))
+ (when (or string (eq last-command 'kill-region))
+ (setq this-command 'kill-region))
+ nil)
+@end group
+
+@group
+ ;; @bullet{} The third argument to `condition-case' tells the interpreter
+ ;; what to do with an error.
+@end group
+@group
+ ;; The third argument has a conditions part and a body part.
+ ;; If the conditions are met (in this case,
+ ;; if text or buffer are read-only)
+ ;; then the body is executed.
+@end group
+@group
+ ;; The first part of the third argument is the following:
+ ((buffer-read-only text-read-only) ;; the if-part
+ ;; then @dots{}
+ (copy-region-as-kill beg end)
+@end group
+@group
+ ;; Next, also as part of the then-part, set this-command, so
+ ;; it will be set in an error
+ (setq this-command 'kill-region)
+ ;; Finally, in the then-part, send a message if you may copy
+ ;; the text to the kill ring without signally an error, but
+ ;; don't if you may not.
+@end group
+@group
+ (if kill-read-only-ok
+ (progn (message "Read only text copied to kill ring") nil)
+ (barf-if-buffer-read-only)
+ ;; If the buffer isn't read-only, the text is.
+ (signal 'text-read-only (list (current-buffer)))))
+@end group
+@end smallexample
+@ignore
@c v 21
@smallexample
@group
@group
;; 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)
+ ;; if text or buffer are read-only)
;; then the body is executed.
@end group
@group
(signal 'text-read-only (list (current-buffer)))))))
@end group
@end smallexample
+@end ignore
-@node condition-case, delete-and-extract-region, Complete kill-region, kill-region
+@node condition-case, Lisp macro, Complete kill-region, kill-region
@comment node-name, next, previous, up
@subsection @code{condition-case}
@findex condition-case
@end group
@end smallexample
-@node delete-and-extract-region, , condition-case, kill-region
-@comment node-name, next, previous, up
-@subsection @code{delete-and-extract-region}
-@findex delete-and-extract-region
-
-A @code{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 @code{kill-region} that is run in
-the expectation that all goes well. This is the core of the function.
-The code looks like this:
-
-@smallexample
-@group
-(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))
-@end group
-@end smallexample
-
-It looks complicated because we have the new functions
-@code{delete-and-extract-region}, @code{kill-append}, and
-@code{kill-new} as well as the new variables,
-@code{last-command} and @code{this-command}.
-The @code{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.)
+@ignore
+2006 Oct 24
+In Emacs 22,
+copy-region-as-kill is short, 12 lines, and uses
+filter-buffer-substring, which is longer, 39 lines
+and has delete-and-extract-region in it.
+delete-and-extract-region is written in C.
+
+see Initializing a Variable with @code{defvar}
+this is line 8054
+Initializing a Variable with @code{defvar} includes line 8350
+@end ignore
-In this @code{let} expression, the text that
-@code{delete-and-extract-region} returns is placed in the local
-variable called @samp{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.)
+@node Lisp macro, , condition-case, kill-region
+@comment node-name, next, previous, up
+@subsection Lisp macro
+@cindex Macro, lisp
+@cindex Lisp macro
-If the variable @samp{string} does point to text, that text is added
-to the kill ring. The variable will have a @code{nil} value if no
-text was removed.
+The part of the @code{condition-case} expression that is evaluated in
+the expectation that all goes well has a @code{when}. The code uses
+@code{when} to determine whether the @code{string} variable points to
+text that exists.
-The code uses @code{when} to determine whether the variable
-@samp{string} points to text. A @code{when} statement is simply a
-programmers' convenience. A @code{when} statement is an @code{if}
-statement without the possibility of an else clause. In your mind, you
-can replace @code{when} with @code{if} and understand what goes on.
-That is what the Lisp interpreter does.
+A @code{when} expression is simply a programmers' convenience. It is
+an @code{if} without the possibility of an else clause. In your mind,
+you can replace @code{when} with @code{if} and understand what goes
+on. That is what the Lisp interpreter does.
-@cindex Macro, lisp
-@cindex Lisp macro
Technically speaking, @code{when} is a Lisp macro. A Lisp @dfn{macro}
enables you to define new control constructs and other language
features. It tells the interpreter how to compute another Lisp
`other expression' is an @code{if} expression. For more about Lisp
macros, see @ref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference
Manual}. The C programming language also provides macros. These are
-different, but also useful. We will briefly look at C macros in
+different, but also useful.
+
+@ignore
+We will briefly look at C macros in
@ref{Digression into C}.
+@end ignore
@need 1200
If the string has content, then another conditional expression is
@smallexample
@group
(if (eq last-command 'kill-region)
- (kill-append string (< end beg))
- (kill-new string)))
+ (kill-append string (< end beg) yank-handler)
+ (kill-new string nil yank-handler))
@end group
@end smallexample
The then-part is evaluated if the previous command was another call to
@code{kill-region}; if not, the else-part is evaluated.
+@code{yank-handler} is an optional argument to @code{kill-region} that
+tells the @code{kill-append} and @code{kill-new} functions how deal
+with properties added to the text, such as `bold' or `italics'.
+
@code{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 @code{last-command} to the previous command.
whether the previous command was @code{kill-region}. If it was,
@smallexample
-(kill-append string (< end beg))
+(kill-append string (< end beg) yank-handler)
@end smallexample
@noindent
concatenates a copy of the newly clipped text to the just previously
-clipped text in the kill ring. (If the @w{@code{(< end beg))}}
-expression is true, @code{kill-append} prepends the string to the just
-previously clipped text. For a detailed discussion, see
-@ref{kill-append function, , The @code{kill-append} function}.)
-
-If you then yank back the text, i.e., `paste' it, you get both
-pieces of text at once. That way, if you delete two words in a row,
-and then yank them back, you get both words, in their proper order,
-with one yank. (The @w{@code{(< end beg))}} expression makes sure the
-order is correct.)
-
-On the other hand, if the previous command is not @code{kill-region},
-then the @code{kill-new} function is called, which adds the text to
-the kill ring as the latest item, and sets the
-@code{kill-ring-yank-pointer} variable to point to it.
+clipped text in the kill ring.
-@node Digression into C, defvar, kill-region, Cutting & Storing Text
+@node copy-region-as-kill, Digression into C, kill-region, Cutting & Storing Text
@comment node-name, next, previous, up
-@section Digression into C
-@findex delete-and-extract-region
-@cindex C, a digression into
-@cindex Digression into C
+@section @code{copy-region-as-kill}
+@findex copy-region-as-kill
+@findex nthcdr
-The @code{zap-to-char} command uses the
-@code{delete-and-extract-region} function, which in turn uses two
-other functions, @code{copy-region-as-kill} and
-@code{del_range_1}. The @code{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. (@xref{copy-region-as-kill, ,
-@code{copy-region-as-kill}}.)
+The @code{copy-region-as-kill} function copies a region of text from a
+buffer and (via either @code{kill-append} or @code{kill-new}) saves it
+in the @code{kill-ring}.
-The @code{delete-and-extract-region} function removes the contents of
-a region and you cannot get them back.
+If you call @code{copy-region-as-kill} immediately after a
+@code{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 @code{copy-region-as-kill},
+the function copies the text into a separate entry in the kill ring.
-Unlike the other code discussed here, @code{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.
+@menu
+* Complete copy-region-as-kill::
+* copy-region-as-kill body::
+@end menu
-@need 1500
-Like many of the other Emacs primitives,
-@code{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:
+@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
+@ifnottex
+@unnumberedsubsec The complete @code{copy-region-as-kill} function definition
+@end ifnottex
+
+@need 1200
+Here is the complete text of the version 22 @code{copy-region-as-kill}
+function:
-@c /usr/local/src/emacs/src/editfns.c
@smallexample
@group
-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);
-@}
+(defun copy-region-as-kill (beg end)
+ "Save the region as if killed, but don't kill it.
+In Transient Mark mode, deactivate the mark.
+If `interprogram-cut-function' is non-nil, also save the text for a window
+system cut and paste."
+ (interactive "r")
+@end group
+@group
+ (if (eq last-command 'kill-region)
+ (kill-append (filter-buffer-substring beg end) (< end beg))
+ (kill-new (filter-buffer-substring beg end)))
+@end group
+@group
+ (if transient-mark-mode
+ (setq deactivate-mark t))
+ nil)
@end group
@end smallexample
-Without going into the details of the macro writing process, let me
-point out that this macro starts with the word @code{DEFUN}. The word
-@code{DEFUN} was chosen since the code serves the same purpose as
-@code{defun} does in Lisp. The word @code{DEFUN} is followed by seven
-parts inside of parentheses:
-
-@itemize @bullet
-@item
-The first part is the name given to the function in Lisp,
-@code{delete-and-extract-region}.
+@need 800
+As usual, this function can be divided into its component parts:
-@item
-The second part is the name of the function in C,
-@code{Fdelete_and_extract_region}. By convention, it starts with
-@samp{F}. Since C does not use hyphens in names, underscores are used
-instead.
+@smallexample
+@group
+(defun copy-region-as-kill (@var{argument-list})
+ "@var{documentation}@dots{}"
+ (interactive "r")
+ @var{body}@dots{})
+@end group
+@end smallexample
-@item
-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 @samp{S} instead of an @samp{F}.
+The arguments are @code{beg} and @code{end} and the function is
+interactive with @code{"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.
-@item
-The fourth and fifth parts specify the minimum and maximum number of
-arguments the function can have. This function demands exactly 2
-arguments.
+The documentation is somewhat confusing unless you remember that the
+word `kill' has a meaning different from usual. The `Transient Mark'
+and @code{interprogram-cut-function} comments explain certain
+side-effects.
-@item
-The sixth part is nearly like the argument that follows the
-@code{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 @code{0}
-(which is a `null string'), as in this macro.
+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.)
-If you were to specify arguments, you would place them between
-quotation marks. The C macro for @code{goto-char} includes
-@code{"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.
+Also, a windowing system allows you to copy, cut, and paste among
+different programs. In the X windowing system, for example, the
+@code{interprogram-cut-function} function is @code{x-select-text},
+which works with the windowing system's equivalent of the Emacs kill
+ring.
-@item
-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 @samp{\n} followed by a backslash and carriage
-return.
+The body of the @code{copy-region-as-kill} function starts with an
+@code{if} clause. What this clause does is distinguish between two
+different situations: whether or not this command is executed
+immediately after a previous @code{kill-region} command. In the first
+case, the new region is appended to the previously copied text.
+Otherwise, it is inserted into the beginning of the kill ring as a
+separate piece of text from the previous piece.
-@need 1000
-Thus, the first two lines of documentation for @code{goto-char} are
-written like this:
+The last two lines of the function prevent the region from lighting up
+if Transient Mark mode is turned on.
-@smallexample
-@group
- "Set point to POSITION, a number or marker.\n\
-Beginning of buffer is position (point-min), end is (point-max).
-@end group
-@end smallexample
-@end itemize
+The body of @code{copy-region-as-kill} merits discussion in detail.
-@need 1200
-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 @code{delete-and-extract-region} the `body'
-consists of the following two lines:
+@node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
+@comment node-name, next, previous, up
+@subsection The Body of @code{copy-region-as-kill}
+
+The @code{copy-region-as-kill} function works in much the same way as
+the @code{kill-region} function. 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 @code{kill-region}, the @code{copy-region-as-kill} function makes
+use of the @code{last-command} variable that keeps track of the
+previous Emacs command.
+
+@menu
+* last-command & this-command::
+* kill-append function::
+* kill-new function::
+@end menu
+
+@node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
+@ifnottex
+@unnumberedsubsubsec @code{last-command} and @code{this-command}
+@end ifnottex
+
+Normally, whenever a function is executed, Emacs sets the value of
+@code{this-command} to the function being executed (which in this case
+would be @code{copy-region-as-kill}). At the same time, Emacs sets
+the value of @code{last-command} to the previous value of
+@code{this-command}.
+
+In the first part of the body of the @code{copy-region-as-kill}
+function, an @code{if} expression determines whether the value of
+@code{last-command} is @code{kill-region}. If so, the then-part of
+the @code{if} expression is evaluated; it uses the @code{kill-append}
+function to concatenate the text copied at this call to the function
+with the text already in the first element (the @sc{car}) of the kill
+ring. On the other hand, if the value of @code{last-command} is not
+@code{kill-region}, then the @code{copy-region-as-kill} function
+attaches a new element to the kill ring using the @code{kill-new}
+function.
+
+@need 1250
+The @code{if} expression reads as follows; it uses @code{eq}, which is
+a function we have not yet seen:
@smallexample
@group
-validate_region (&start, &end);
-return del_range_1 (XINT (start), XINT (end), 1, 1);
+ (if (eq last-command 'kill-region)
+ ;; @r{then-part}
+ (kill-append (filter-buffer-substring beg end) (< end beg))
+ ;; @r{else-part}
+ (kill-new (filter-buffer-substring beg end)))
@end group
@end smallexample
-The first function, @code{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, @code{del_range_1}, actually
-deletes the text.
-
-@code{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
-@code{del_range}. These are @w{@code{XINT (start)}} and @w{@code{XINT
-(end)}}.
+@findex filter-buffer-substring
+(The @code{filter-buffer-substring} function returns a filtered
+substring of the buffer, if any. Optionally---the arguments are not
+here, so neither is done---the function may delete the initial text or
+return the text without its properties; this function is a replacement
+for the older @code{buffer-substring} function, which came before text
+properties were implemented.)
-As far as the C language is concerned, @code{start} and @code{end} are
-two integers that mark the beginning and end of the region to be
-deleted@footnote{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.}.
+@findex eq @r{(example of use)}
+@noindent
+The @code{eq} function tests whether its first argument is the same Lisp
+object as its second argument. The @code{eq} function is similar to the
+@code{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.
+@code{equal} determines whether the structure and contents of two
+expressions are the same.
-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'.
+If the previous command was @code{kill-region}, then the Emacs Lisp
+interpreter calls the @code{kill-append} function
-@samp{XINT} is a C macro that extracts the relevant number from the
-longer collection of bits; the four other bits are discarded.
+@node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
+@unnumberedsubsubsec The @code{kill-append} function
+@findex kill-append
@need 800
-The command in @code{delete-and-extract-region} looks like this:
+The @code{kill-append} function looks like this:
+@c in GNU Emacs 22
@smallexample
-del_range_1 (XINT (start), XINT (end), 1, 1);
+@group
+(defun kill-append (string before-p &optional yank-handler)
+ "Append STRING to the end of the latest kill in the kill ring.
+If BEFORE-P is non-nil, prepend STRING to the kill.
+@dots{} "
+ (let* ((cur (car kill-ring)))
+ (kill-new (if before-p (concat string cur) (concat cur string))
+ (or (= (length cur) 0)
+ (equal yank-handler (get-text-property 0 'yank-handler cur)))
+ yank-handler)))
+@end group
@end smallexample
-@noindent
-It deletes the region between the beginning position, @code{start},
-and the ending position, @code{end}.
+@ignore
+was:
+(defun kill-append (string before-p)
+ "Append STRING to the end of the latest kill in the kill ring.
+If BEFORE-P is non-nil, prepend STRING to the kill.
+If `interprogram-cut-function' is set, pass the resulting kill to
+it."
+ (kill-new (if before-p
+ (concat string (car kill-ring))
+ (concat (car kill-ring) string))
+ t))
+@end ignore
-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.
+@noindent
+The @code{kill-append} function is fairly straightforward. It uses
+the @code{kill-new} function, which we will discuss in more detail in
+a moment.
-@node defvar, copy-region-as-kill, Digression into C, Cutting & Storing Text
-@comment node-name, next, previous, up
-@section Initializing a Variable with @code{defvar}
-@findex defvar
-@cindex Initializing a variable
-@cindex Variable initialization
+(Also, the function provides an optional argument called
+@code{yank-handler}; when invoked, this argument tells the function
+how to deal with properties added to the text, such as `bold' or
+`italics'.)
-Unlike the @code{delete-and-extract-region} function, the
-@code{copy-region-as-kill} function is written in Emacs Lisp. Two
-functions within it, @code{kill-append} and @code{kill-new}, copy a
-region in a buffer and save it in a variable called the
-@code{kill-ring}. This section describes how the @code{kill-ring}
-variable is created and initialized using the @code{defvar} special
-form.
+@c !!! bug in GNU Emacs 22 version of kill-append ?
+It has a @code{let*} function to set the value of the first element of
+the kill ring to @code{cur}. (I do not know why the function does not
+use @code{let} instead; only one value is set in the expression.
+Perhaps this is a bug that produces no problems?)
-(Again we note that the term @code{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.)
+Consider the conditional that is one of the two arguments to
+@code{kill-new}. It uses @code{concat} to concatenate the new text to
+the @sc{car} of the kill ring. Whether it prepends or appends the
+text depends on the results of an @code{if} expression:
-In Emacs Lisp, a variable such as the @code{kill-ring} is created and
-given an initial value by using the @code{defvar} special form. The
-name comes from ``define variable''.
+@smallexample
+@group
+(if before-p ; @r{if-part}
+ (concat string cur) ; @r{then-part}
+ (concat cur string)) ; @r{else-part}
+@end group
+@end smallexample
-The @code{defvar} special form is similar to @code{setq} in that it sets
-the value of a variable. It is unlike @code{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, @code{defvar} does
-not override the existing value. Second, @code{defvar} has a
-documentation string.
+@noindent
+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 @code{if} expression depends on the predicate @code{before-p} to
+decide whether the newly saved text should be put before or after the
+previously saved text.
-(Another special form, @code{defcustom}, is designed for variables
-that people customize. It has more features than @code{defvar}.
-(@xref{defcustom, , Setting Variables with @code{defcustom}}.)
+The symbol @code{before-p} is the name of one of the arguments to
+@code{kill-append}. When the @code{kill-append} function is
+evaluated, it is bound to the value returned by evaluating the actual
+argument. In this case, this is the expression @code{(< 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 it does is determine whether the value of the variable
+@code{end} is less than the value of the variable @code{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, @code{(< 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 @code{end} is greater than the value of the variable
+@code{beg}, the text will be appended after the previous text.
-@menu
-* See variable current value::
-* defvar and asterisk:: An old-time convention.
-@end menu
+@need 800
+When the newly saved text will be prepended, then the string with the new
+text will be concatenated before the old text:
-@node See variable current value, defvar and asterisk, defvar, defvar
-@ifnottex
-@unnumberedsubsec Seeing the Current Value of a Variable
-@end ifnottex
+@smallexample
+(concat string cur)
+@end smallexample
-You can see the current value of a variable, any variable, by using
-the @code{describe-variable} function, which is usually invoked by
-typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
-(followed by @key{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
-@code{kill-ring}:
+@need 1200
+@noindent
+But if the text will be appended, it will be concatenated
+after the old text:
@smallexample
-@group
-Documentation:
-List of killed text sequences.
-Since the kill ring is supposed to interact nicely with cut-and-paste
-facilities offered by window systems, use of this variable should
-@end group
-@group
-interact nicely with `interprogram-cut-function' and
-`interprogram-paste-function'. The functions `kill-new',
-`kill-append', and `current-kill' are supposed to implement this
-interaction; you may want to use them instead of manipulating the kill
-ring directly.
-@end group
+(concat cur string))
@end smallexample
-@need 800
-The kill ring is defined by a @code{defvar} in the following way:
+To understand how this works, we first need to review the
+@code{concat} function. The @code{concat} function links together or
+unites two strings of text. The result is a string. For example:
@smallexample
@group
-(defvar kill-ring nil
- "List of killed text sequences.
-@dots{}")
+(concat "abc" "def")
+ @result{} "abcdef"
@end group
-@end smallexample
-@noindent
-In this variable definition, the variable is given an initial value of
-@code{nil}, which makes sense, since if you have saved nothing, you want
-nothing back if you give a @code{yank} command. The documentation
-string is written just like the documentation string of a @code{defun}.
-As with the documentation string of the @code{defun}, the first line of
-the documentation should be a complete sentence, since some commands,
-like @code{apropos}, print only the first line of documentation.
-Succeeding lines should not be indented; otherwise they look odd when
-you use @kbd{C-h v} (@code{describe-variable}).
+@group
+(concat "new "
+ (car '("first element" "second element")))
+ @result{} "new first element"
-@node defvar and asterisk, , See variable current value, defvar
-@subsection @code{defvar} and an asterisk
-@findex defvar @r{for a user customizable variable}
-@findex defvar @r{with an asterisk}
+(concat (car
+ '("first element" "second element")) " modified")
+ @result{} "first element modified"
+@end group
+@end smallexample
-In the past, Emacs used the @code{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 @code{defvar} for user customizable variables, please use
-@code{defcustom} instead, since that special form provides a path into
-the Customization commands. (@xref{defcustom, , Specifying Variables
-using @code{defcustom}}.)
+We can now make sense of @code{kill-append}: it modifies the contents
+of the kill ring. The kill ring is a list, each element of which is
+saved text. The @code{kill-append} function uses the @code{kill-new}
+function which in turn uses the @code{setcar} function.
-When you specified a variable using the @code{defvar} special form,
-you could distinguish a readily settable variable from others by
-typing an asterisk, @samp{*}, in the first column of its documentation
-string. For example:
+@node kill-new function, , kill-append function, copy-region-as-kill body
+@unnumberedsubsubsec The @code{kill-new} function
+@findex kill-new
+
+@c in GNU Emacs 22, additional documentation to kill-new:
+@ignore
+Optional third arguments YANK-HANDLER controls how the STRING is later
+inserted into a buffer; see `insert-for-yank' for details.
+When a yank handler is specified, STRING must be non-empty (the yank
+handler, if non-nil, is stored as a `yank-handler' text property on STRING).
+
+When the yank handler has a non-nil PARAM element, the original STRING
+argument is not used by `insert-for-yank'. However, since Lisp code
+may access and use elements from the kill ring directly, the STRING
+argument should still be a \"useful\" string for such uses."
+@end ignore
+@need 1200
+The @code{kill-new} function looks like this:
@smallexample
@group
-(defvar shell-command-default-error-buffer nil
- "*Buffer name for `shell-command' @dots{} error output.
-@dots{} ")
+(defun kill-new (string &optional replace yank-handler)
+ "Make STRING the latest kill in the kill ring.
+Set `kill-ring-yank-pointer' to point to it.
+
+If `interprogram-cut-function' is non-nil, apply it to STRING.
+Optional second argument REPLACE non-nil means that STRING will replace
+the front of the kill ring, rather than being added to the list.
+@dots{}"
+@end group
+@group
+ (if (> (length string) 0)
+ (if yank-handler
+ (put-text-property 0 (length string)
+ 'yank-handler yank-handler string))
+ (if yank-handler
+ (signal 'args-out-of-range
+ (list string "yank-handler specified for empty string"))))
+@end group
+@group
+ (if (fboundp 'menu-bar-update-yank-menu)
+ (menu-bar-update-yank-menu string (and replace (car kill-ring))))
+@end group
+@group
+ (if (and replace kill-ring)
+ (setcar kill-ring string)
+ (push string kill-ring)
+ (if (> (length kill-ring) kill-ring-max)
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
+@end group
+@group
+ (setq kill-ring-yank-pointer kill-ring)
+ (if interprogram-cut-function
+ (funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample
+@ignore
+was:
+(defun kill-new (string &optional replace)
+ "Make STRING the latest kill in the kill ring.
+Set the kill-ring-yank pointer to point to it.
+If `interprogram-cut-function' is non-nil, apply it to STRING.
+Optional second argument REPLACE non-nil means that STRING will replace
+the front of the kill ring, rather than being added to the list."
+ (and (fboundp 'menu-bar-update-yank-menu)
+ (menu-bar-update-yank-menu string (and replace (car kill-ring))))
+ (if (and replace kill-ring)
+ (setcar kill-ring string)
+ (setq kill-ring (cons string kill-ring))
+ (if (> (length kill-ring) kill-ring-max)
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
+ (setq kill-ring-yank-pointer kill-ring)
+ (if interprogram-cut-function
+ (funcall interprogram-cut-function string (not replace))))
+@end ignore
-@findex set-variable
@noindent
-You could (and still can) use the @code{set-variable} command to
-change the value of @code{shell-command-default-error-buffer}
-temporarily. However, options set using @code{set-variable} 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 @file{.emacs} file,
-either by setting it manually or by using @code{customize}.
-@xref{Emacs Initialization, , Your @file{.emacs} File}.
+(Notice that the function is not interactive.)
-For me, the major use of the @code{set-variable} command is to suggest
-variables that I might want to set in my @file{.emacs} file. There
-are now more than 700 such variables --- far too many to remember
-readily. Fortunately, you can press @key{TAB} after calling the
-@code{M-x set-variable} command to see the list of variables.
-(@xref{Examining, , Examining and Setting Variables, emacs,
-The GNU Emacs Manual}.)
+As usual, we can look at this function in parts.
-@node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text
-@comment node-name, next, previous, up
-@section @code{copy-region-as-kill}
-@findex copy-region-as-kill
-@findex nthcdr
+The function definition has an optional @code{yank-handler} argument,
+which when invoked tells the function how to deal with properties
+added to the text, such as `bold' or `italics'. We will skip that.
-The @code{copy-region-as-kill} function copies a region of text from a
-buffer and (via either @code{kill-append} or @code{kill-new}) saves it
-in the @code{kill-ring}.
+@need 1200
+The first line of the documentation makes sense:
-If you call @code{copy-region-as-kill} immediately after a
-@code{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 @code{copy-region-as-kill},
-the function copies the text into a separate entry in the kill ring.
+@smallexample
+Make STRING the latest kill in the kill ring.
+@end smallexample
-@menu
-* Complete copy-region-as-kill:: The complete function definition.
-* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
-@end menu
+@noindent
+Let's skip over the rest of the documentation for the moment.
-@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
-@ifnottex
-@unnumberedsubsec The complete @code{copy-region-as-kill} function definition
-@end ifnottex
+Also, let's skip over the initial @code{if} expression and those lines
+of code involving @code{menu-bar-update-yank-menu}. We will explain
+them below.
@need 1200
-Here is the complete text of the version 21 @code{copy-region-as-kill}
-function:
-
-@c !!! for no text properties, use buffer-substring-no-properties
+The critical lines are these:
@smallexample
@group
-(defun copy-region-as-kill (beg end)
- "Save the region as if killed, but don't kill it.
-In Transient Mark mode, deactivate the mark.
-If `interprogram-cut-function' is non-nil, also save
-the text for a window system cut and paste."
- (interactive "r")
+ (if (and replace kill-ring)
+ ;; @r{then}
+ (setcar kill-ring string)
@end group
@group
- (if (eq last-command 'kill-region)
- (kill-append (buffer-substring beg end) (< end beg))
- (kill-new (buffer-substring beg end)))
+ ;; @r{else}
+ (push string kill-ring)
@end group
@group
- (if transient-mark-mode
- (setq deactivate-mark t))
- nil)
+ (setq kill-ring (cons string kill-ring))
+ (if (> (length kill-ring) kill-ring-max)
+ ;; @r{avoid overly long kill ring}
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
+@end group
+@group
+ (setq kill-ring-yank-pointer kill-ring)
+ (if interprogram-cut-function
+ (funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample
-@need 800
-As usual, this function can be divided into its component parts:
+The conditional test is @w{@code{(and replace kill-ring)}}.
+This will be true when two conditions are met: the kill ring has
+something in it, and the @code{replace} variable is true.
+
+@need 1250
+When the @code{kill-append} function sets @code{replace} to be true
+and when the kill ring has at least one item in it, the @code{setcar}
+expression is executed:
@smallexample
-@group
-(defun copy-region-as-kill (@var{argument-list})
- "@var{documentation}@dots{}"
- (interactive "r")
- @var{body}@dots{})
-@end group
+(setcar kill-ring string)
@end smallexample
-The arguments are @code{beg} and @code{end} and the function is
-interactive with @code{"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 @code{setcar} function actually changes the first element of the
+@code{kill-ring} list to the value of @code{string}. It replaces the
+first element.
-The documentation is somewhat confusing unless you remember that the
-word `kill' has a meaning different from its usual meaning. The
-`Transient Mark' and @code{interprogram-cut-function} comments explain
-certain side-effects.
+@need 1250
+On the other hand, if the kill ring is empty, or replace is false, the
+else-part of the condition is executed:
-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.)
+@smallexample
+(push string kill-ring)
+@end smallexample
-Also, a windowing system allows you to copy, cut, and paste among
-different programs. In the X windowing system, for example, the
-@code{interprogram-cut-function} function is @code{x-select-text},
-which works with the windowing system's equivalent of the Emacs kill
-ring.
+@noindent
+@need 1250
+@code{push} puts its first argument onto the second. It is the same
+as the older
-The body of the @code{copy-region-as-kill} function starts with an
-@code{if} clause. What this clause does is distinguish between two
-different situations: whether or not this command is executed
-immediately after a previous @code{kill-region} command. In the first
-case, the new region is appended to the previously copied text.
-Otherwise, it is inserted into the beginning of the kill ring as a
-separate piece of text from the previous piece.
+@smallexample
+(setq kill-ring (cons string kill-ring))
+@end smallexample
-The last two lines of the function prevent the region from lighting up
-if Transient Mark mode is turned on.
+@noindent
+@need 1250
+or the newer
-The body of @code{copy-region-as-kill} merits discussion in detail.
+@smallexample
+(add-to-list kill-ring string)
+@end smallexample
-@node copy-region-as-kill body, , Complete copy-region-as-kill, copy-region-as-kill
-@comment node-name, next, previous, up
-@subsection The Body of @code{copy-region-as-kill}
+@noindent
+When it is false, the expression first constructs a new version of the
+kill ring by prepending @code{string} to the existing kill ring as a
+new element (that is what the @code{push} does). Then it executes a
+second @code{if} clause. This second @code{if} clause keeps the kill
+ring from growing too long.
-The @code{copy-region-as-kill} function works in much the same way as
-the @code{kill-region} function (@pxref{kill-region,
-,@code{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.
+Let's look at these two expressions in order.
-Like @code{kill-region}, the @code{copy-region-as-kill} function makes
-use of the @code{last-command} variable that keeps track of the
-previous Emacs command.
+The @code{push} 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.
-@menu
-* last-command & this-command::
-* kill-append function::
-* kill-new function::
-@end menu
-@node last-command & this-command, kill-append function, copy-region-as-kill body, copy-region-as-kill body
-@ifnottex
-@unnumberedsubsubsec @code{last-command} and @code{this-command}
-@end ifnottex
+We can see how this works with an example.
-Normally, whenever a function is executed, Emacs sets the value of
-@code{this-command} to the function being executed (which in this case
-would be @code{copy-region-as-kill}). At the same time, Emacs sets
-the value of @code{last-command} to the previous value of
-@code{this-command}.
+@need 800
+First,
-In the first part of the body of the @code{copy-region-as-kill}
-function, an @code{if} expression determines whether the value of
-@code{last-command} is @code{kill-region}. If so, the then-part of
-the @code{if} expression is evaluated; it uses the @code{kill-append}
-function to concatenate the text copied at this call to the function
-with the text already in the first element (the @sc{car}) of the kill
-ring. On the other hand, if the value of @code{last-command} is not
-@code{kill-region}, then the @code{copy-region-as-kill} function
-attaches a new element to the kill ring using the @code{kill-new}
-function.
+@smallexample
+(setq example-list '("here is a clause" "another clause"))
+@end smallexample
-@need 1250
-The @code{if} expression reads as follows; it uses @code{eq}, which is
-a function we have not yet seen:
+@need 1200
+@noindent
+After evaluating this expression with @kbd{C-x C-e}, you can evaluate
+@code{example-list} and see what it returns:
@smallexample
@group
- (if (eq last-command 'kill-region)
- ;; @r{then-part}
- (kill-append (buffer-substring beg end) (< end beg))
- ;; @r{else-part}
- (kill-new (buffer-substring beg end)))
+example-list
+ @result{} ("here is a clause" "another clause")
@end group
@end smallexample
-@findex eq @r{(example of use)}
+@need 1200
@noindent
-The @code{eq} function tests whether its first argument is the same Lisp
-object as its second argument. The @code{eq} function is similar to the
-@code{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.
-@code{equal} determines whether the structure and contents of two
-expressions are the same.
-
-If the previous command was @code{kill-region}, then the Emacs Lisp
-interpreter calls the @code{kill-append} function
+Now, we can add a new element on to this list by evaluating the
+following expression:
+@findex push, @r{example}
-@node kill-append function, kill-new function, last-command & this-command, copy-region-as-kill body
-@unnumberedsubsubsec The @code{kill-append} function
-@findex kill-append
+@smallexample
+(push "a third clause" example-list)
+@end smallexample
@need 800
-The @code{kill-append} function looks like this:
+@noindent
+When we evaluate @code{example-list}, we find its value is:
@smallexample
@group
-(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))
+example-list
+ @result{} ("a third clause" "here is a clause" "another clause")
@end group
@end smallexample
@noindent
-The @code{kill-append} function is fairly straightforward. It uses
-the @code{kill-new} function, which we will discuss in more detail in
-a moment.
+Thus, the third clause is added to the list by @code{push}.
+
+@need 1200
+Now for the second part of the @code{if} clause. This expression
+keeps the kill ring from growing too long. It looks like this:
+
+@smallexample
+@group
+(if (> (length kill-ring) kill-ring-max)
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
+@end group
+@end smallexample
+
+The code checks whether the length of the kill ring is greater than
+the maximum permitted length. This is the value of
+@code{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 @code{nil}. It does this by using two functions,
+@code{nthcdr} and @code{setcdr}.
+
+We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
+It sets the @sc{cdr} of a list, just as @code{setcar} sets the
+@sc{car} of a list. In this case, however, @code{setcdr} will not be
+setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
+function is used to cause it to set the @sc{cdr} of the next to last
+element of the kill ring---this means that since the @sc{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.
+
+@findex nthcdr, @r{example}
+The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
+list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
+@dots{} It does this @var{N} times and returns the results.
+(@xref{nthcdr, , @code{nthcdr}}.)
+
+@findex setcdr, @r{example}
+Thus, if we had a four element list that was supposed to be three
+elements long, we could set the @sc{cdr} of the next to last element
+to @code{nil}, and thereby shorten the list. (If you sent the last
+element to some other value than @code{nil}, which you could do, then
+you would not have shortened the list. @xref{setcdr, ,
+@code{setcdr}}.)
-First, let us look at the conditional that is one of the two arguments
-to @code{kill-new}. It uses @code{concat} to concatenate the new text
-to the @sc{car} of the kill ring. Whether it prepends or appends the
-text depends on the results of an @code{if} expression:
+You can see shortening by evaluating the following three expressions
+in turn. First set the value of @code{trees} to @code{(maple oak pine
+birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
+and then find the value of @code{trees}:
@smallexample
@group
-(if before-p ; @r{if-part}
- (concat string (car kill-ring)) ; @r{then-part}
- (concat (car kill-ring) string)) ; @r{else-part}
+(setq trees '(maple oak pine birch))
+ @result{} (maple oak pine birch)
+@end group
+
+@group
+(setcdr (nthcdr 2 trees) nil)
+ @result{} nil
+
+trees
+ @result{} (maple oak pine)
@end group
@end smallexample
@noindent
-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 @code{if} expression depends on the predicate @code{before-p} to
-decide whether the newly saved text should be put before or after the
-previously saved text.
+(The value returned by the @code{setcdr} expression is @code{nil} since
+that is what the @sc{cdr} is set to.)
-The symbol @code{before-p} is the name of one of the arguments to
-@code{kill-append}. When the @code{kill-append} function is
-evaluated, it is bound to the value returned by evaluating the actual
-argument. In this case, this is the expression @code{(< 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 it does is determine whether the value of the variable
-@code{end} is less than the value of the variable @code{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, @code{(< 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 @code{end} is greater than the value of the variable
-@code{beg}, the text will be appended after the previous text.
+To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
+@sc{cdr} a number of times that is one less than the maximum permitted
+size of the kill ring and @code{setcdr} sets the @sc{cdr} of that
+element (which will be the rest of the elements in the kill ring) to
+@code{nil}. This prevents the kill ring from growing too long.
@need 800
-When the newly saved text will be prepended, then the string with the new
-text will be concatenated before the old text:
+The next to last expression in the @code{kill-new} function is
@smallexample
-(concat string (car kill-ring))
+(setq kill-ring-yank-pointer kill-ring)
@end smallexample
-@need 1200
-@noindent
-But if the text will be appended, it will be concatenated
-after the old text:
+The @code{kill-ring-yank-pointer} is a global variable that is set to be
+the @code{kill-ring}.
-@smallexample
-(concat (car kill-ring) string))
-@end smallexample
+Even though the @code{kill-ring-yank-pointer} is called a
+@samp{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 @code{yank} and
+@code{yank-pop} (@pxref{Yanking, , Yanking Text Back}).
-To understand how this works, we first need to review the
-@code{concat} function. The @code{concat} function links together or
-unites two strings of text. The result is a string. For example:
+@need 1200
+Now, to return to an early expression in the body of the function:
@smallexample
@group
-(concat "abc" "def")
- @result{} "abcdef"
+ (if (fboundp 'menu-bar-update-yank-menu)
+ (menu-bar-update-yank-menu string (and replace (car kill-ring))))
@end group
+@end smallexample
-@group
-(concat "new "
- (car '("first element" "second element")))
- @result{} "new first element"
+@noindent
+It starts with an @code{if} expression
-(concat (car
- '("first element" "second element")) " modified")
- @result{} "first element modified"
-@end group
-@end smallexample
+In this case, the expression tests first to see whether
+@code{menu-bar-update-yank-menu} exists as a function, and if so,
+calls it. The @code{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 (@pxref{Making
+Errors, , Generate an Error Message}).
-We can now make sense of @code{kill-append}: it modifies the contents
-of the kill ring. The kill ring is a list, each element of which is
-saved text. The @code{kill-append} function uses the @code{kill-new}
-function which in turn uses the @code{setcar} function.
+@noindent
+The then-part contains an expression whose first element is the
+function @code{and}.
-@node kill-new function, , kill-append function, copy-region-as-kill body
-@unnumberedsubsubsec The @code{kill-new} function
-@findex kill-new
+@findex and
+The @code{and} special form evaluates each of its arguments until one
+of the arguments returns a value of @code{nil}, in which case the
+@code{and} expression returns @code{nil}; however, if none of the
+arguments returns a value of @code{nil}, the value resulting from
+evaluating the last argument is returned. (Since such a value is not
+@code{nil}, it is considered true in Emacs Lisp.) In other words, an
+@code{and} expression returns a true value only if all its arguments
+are true. (@xref{Second Buffer Related Review}.)
+
+The expression determines whether the second argument to
+@code{menu-bar-update-yank-menu} is true or not.
+@ignore
+ ;; If we're supposed to be extending an existing string, and that
+ ;; string really is at the front of the menu, then update it in place.
+@end ignore
+
+@code{menu-bar-update-yank-menu} is 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.
+
+The last expression in the @code{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 @code{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.
@need 1200
-The @code{kill-new} function looks like this:
+The expression looks like this:
@smallexample
@group
-(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."
-@end group
-@group
- (and (fboundp 'menu-bar-update-yank-menu)
- (menu-bar-update-yank-menu string (and replace (car kill-ring))))
-@end group
-@group
- (if (and replace kill-ring)
- (setcar kill-ring string)
- (setq kill-ring (cons string kill-ring))
- (if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
-@end group
-@group
- (setq kill-ring-yank-pointer kill-ring)
(if interprogram-cut-function
(funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample
-As usual, we can look at this function in parts.
+If an @code{interprogram-cut-function} exists, then Emacs executes
+@code{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 @code{if} expression could be replaced by an @code{and}
+expression similar to the one in the first part of the function.)
-@need 1200
-The first line of the documentation makes sense:
+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.
-@smallexample
-Make STRING the latest kill in the kill ring.
-@end smallexample
+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'.
-@noindent
-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
-@code{menu-bar-update-yank-menu}. We will explain them below.
+@ignore
+@c is this true in Emacs 22? Does not seems to be
-@need 1200
-The critical lines are these:
+ (If the @w{@code{(< end beg))}}
+expression is true, @code{kill-append} prepends the string to the just
+previously clipped text. For a detailed discussion, see
+@ref{kill-append function, , The @code{kill-append} function}.)
+
+If you then yank back the text, i.e., `paste' it, you get both
+pieces of text at once. That way, if you delete two words in a row,
+and then yank them back, you get both words, in their proper order,
+with one yank. (The @w{@code{(< end beg))}} expression makes sure the
+order is correct.)
+
+On the other hand, if the previous command is not @code{kill-region},
+then the @code{kill-new} function is called, which adds the text to
+the kill ring as the latest item, and sets the
+@code{kill-ring-yank-pointer} variable to point to it.
+@end ignore
+@ignore
+
+@c Evidently, changed for Emacs 22. The zap-to-char command does not
+@c use the delete-and-extract-region function
+
+2006 Oct 26, the Digression into C is now OK but should come after
+copy-region-as-kill and filter-buffer-substring
+
+2006 Oct 24
+In Emacs 22,
+copy-region-as-kill is short, 12 lines, and uses
+filter-buffer-substring, which is longer, 39 lines
+and has delete-and-extract-region in it.
+delete-and-extract-region is written in C.
+
+see Initializing a Variable with @code{defvar}
+@end ignore
+
+@node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text
+@comment node-name, next, previous, up
+@section Digression into C
+@findex delete-and-extract-region
+@cindex C, a digression into
+@cindex Digression into C
+
+The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
+@code{copy-region-as-kill}}) uses the @code{filter-buffer-substring}
+function, which in turn uses the @code{delete-and-extract-region}
+function. It removes the contents of a region and you cannot get them
+back.
+
+Unlike the other code discussed here, the
+@code{delete-and-extract-region} function 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.
+
+@c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c
+@c the DEFUN for buffer-substring-no-properties
+
+@need 1500
+Like many of the other Emacs primitives,
+@code{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:
@smallexample
@group
- (if (and replace kill-ring)
- ;; @r{then}
- (setcar kill-ring string)
-@end group
-@group
- ;; @r{else}
- (setq kill-ring (cons string kill-ring))
- (if (> (length kill-ring) kill-ring-max)
- ;; @r{avoid overly long kill ring}
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))
-@end group
-@group
- (setq kill-ring-yank-pointer kill-ring)
- (if interprogram-cut-function
- (funcall interprogram-cut-function string (not replace))))
+DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties,
+ Sbuffer_substring_no_properties, 2, 2, 0,
+ doc: /* Return the characters of part of the buffer,
+without the text properties.
+The two arguments START and END are character positions;
+they can be in either order. */)
+ (start, end)
+ Lisp_Object start, end;
+@{
+ register int b, e;
+
+ validate_region (&start, &end);
+ b = XINT (start);
+ e = XINT (end);
+
+ return make_buffer_string (b, e, 0);
+@}
@end group
@end smallexample
-The conditional test is @w{@code{(and replace kill-ring)}}.
-This will be true when two conditions are met: the kill ring has
-something in it, and the @code{replace} variable is true.
+Without going into the details of the macro writing process, let me
+point out that this macro starts with the word @code{DEFUN}. The word
+@code{DEFUN} was chosen since the code serves the same purpose as
+@code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in
+@file{emacs/src/lisp.h}.)
+
+The word @code{DEFUN} is followed by seven parts inside of
+parentheses:
+
+@itemize @bullet
+@item
+The first part is the name given to the function in Lisp,
+@code{delete-and-extract-region}.
+
+@item
+The second part is the name of the function in C,
+@code{Fdelete_and_extract_region}. By convention, it starts with
+@samp{F}. Since C does not use hyphens in names, underscores are used
+instead.
+
+@item
+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 @samp{S} instead of an @samp{F}.
+
+@item
+The fourth and fifth parts specify the minimum and maximum number of
+arguments the function can have. This function demands exactly 2
+arguments.
+
+@item
+The sixth part is nearly like the argument that follows the
+@code{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 @code{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 @code{goto-char} includes
+@code{"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.
+
+@item
+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 @samp{\n} followed by a backslash and carriage
+return.
-@need 1250
-The @code{kill-append} function sets @code{replace} to be true; then,
-when the kill ring has at least one item in it, the @code{setcar}
-expression is executed:
+@need 1000
+Thus, the first two lines of documentation for @code{goto-char} are
+written like this:
@smallexample
-(setcar kill-ring string)
+@group
+ "Set point to POSITION, a number or marker.\n\
+Beginning of buffer is position (point-min), end is (point-max).
+@end group
@end smallexample
+@end itemize
-The @code{setcar} function actually changes the first element of the
-@code{kill-ring} list to the value of @code{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:
+@need 1200
+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 @code{delete-and-extract-region} the `body'
+consists of the following four lines:
@smallexample
@group
-(setq kill-ring (cons string kill-ring))
-(if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
+validate_region (&start, &end);
+if (XINT (start) == XINT (end))
+ return build_string ("");
+return del_range_1 (XINT (start), XINT (end), 1, 1);
@end group
@end smallexample
-@noindent
-This expression first constructs a new version of the kill ring by
-prepending @code{string} to the existing kill ring as a new element.
-Then it executes a second @code{if} clause. This second @code{if}
-clause keeps the kill ring from growing too long.
+The @code{validate_region} function checks whether the values
+passed as the beginning and end of the region are the proper type and
+are within range. If the beginning and end positions are the same,
+then return and empty string.
-Let's look at these two expressions in order.
+The @code{del_range_1} function actually deletes the text. It 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 @code{del_range}. These are @w{@code{XINT (start)}} and
+@w{@code{XINT (end)}}.
-The @code{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.
+As far as the C language is concerned, @code{start} and @code{end} are
+two integers that mark the beginning and end of the region to be
+deleted@footnote{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.}.
-@need 800
-We can see how this works with an example:
+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; the remaining bits are used as `content'.
-@smallexample
-(setq example-list '("here is a clause" "another clause"))
-@end smallexample
+@samp{XINT} is a C macro that extracts the relevant number from the
+longer collection of bits; the three other bits are discarded.
-@need 1200
-@noindent
-After evaluating this expression with @kbd{C-x C-e}, you can evaluate
-@code{example-list} and see what it returns:
+@need 800
+The command in @code{delete-and-extract-region} looks like this:
@smallexample
-@group
-example-list
- @result{} ("here is a clause" "another clause")
-@end group
+del_range_1 (XINT (start), XINT (end), 1, 1);
@end smallexample
-@need 1200
@noindent
-Now, we can add a new element on to this list by evaluating the
-following expression:
-@findex cons, @r{example}
+It deletes the region between the beginning position, @code{start},
+and the ending position, @code{end}.
-@smallexample
-(setq example-list (cons "a third clause" example-list))
-@end smallexample
+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.
-@need 800
-@noindent
-When we evaluate @code{example-list}, we find its value is:
+@node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text
+@comment node-name, next, previous, up
+@section Initializing a Variable with @code{defvar}
+@findex defvar
+@cindex Initializing a variable
+@cindex Variable initialization
-@smallexample
-@group
-example-list
- @result{} ("a third clause" "here is a clause" "another clause")
-@end group
-@end smallexample
+@ignore
+2006 Oct 24
+In Emacs 22,
+copy-region-as-kill is short, 12 lines, and uses
+filter-buffer-substring, which is longer, 39 lines
+and has delete-and-extract-region in it.
+delete-and-extract-region is written in C.
-@noindent
-Thus, the third clause was added to the list by @code{cons}.
+see Initializing a Variable with @code{defvar}
-@need 1200
-This is exactly similar to what the @code{setq} and @code{cons} do in
-the function. Here is the line again:
+@end ignore
-@smallexample
-(setq kill-ring (cons string kill-ring))
-@end smallexample
+The @code{copy-region-as-kill} function is written in Emacs Lisp. Two
+functions within it, @code{kill-append} and @code{kill-new}, copy a
+region in a buffer and save it in a variable called the
+@code{kill-ring}. This section describes how the @code{kill-ring}
+variable is created and initialized using the @code{defvar} special
+form.
-@need 1200
-Now for the second part of the @code{if} clause. This expression
-keeps the kill ring from growing too long. It looks like this:
+(Again we note that the term @code{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.)
-@smallexample
-@group
-(if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
-@end group
-@end smallexample
+In Emacs Lisp, a variable such as the @code{kill-ring} is created and
+given an initial value by using the @code{defvar} special form. The
+name comes from ``define variable''.
-The code checks whether the length of the kill ring is greater than
-the maximum permitted length. This is the value of
-@code{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 @code{nil}. It does this by using two functions,
-@code{nthcdr} and @code{setcdr}.
+The @code{defvar} special form is similar to @code{setq} in that it sets
+the value of a variable. It is unlike @code{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, @code{defvar} does
+not override the existing value. Second, @code{defvar} has a
+documentation string.
-We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}).
-It sets the @sc{cdr} of a list, just as @code{setcar} sets the
-@sc{car} of a list. In this case, however, @code{setcdr} will not be
-setting the @sc{cdr} of the whole kill ring; the @code{nthcdr}
-function is used to cause it to set the @sc{cdr} of the next to last
-element of the kill ring---this means that since the @sc{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.
+(Another special form, @code{defcustom}, is designed for variables
+that people customize. It has more features than @code{defvar}.
+(@xref{defcustom, , Setting Variables with @code{defcustom}}.)
-@findex nthcdr, @r{example}
-The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a
-list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr}
-@dots{} It does this @var{N} times and returns the results.
+@menu
+* See variable current value::
+* defvar and asterisk::
+@end menu
-@findex setcdr, @r{example}
-Thus, if we had a four element list that was supposed to be three
-elements long, we could set the @sc{cdr} of the next to last element
-to @code{nil}, and thereby shorten the list. (If you sent the last
-element to some other value than @code{nil}, which you could do, then
-you would not have shortened the list.)
+@node See variable current value, defvar and asterisk, defvar, defvar
+@ifnottex
+@unnumberedsubsec Seeing the Current Value of a Variable
+@end ifnottex
-You can see shortening by evaluating the following three expressions
-in turn. First set the value of @code{trees} to @code{(maple oak pine
-birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil}
-and then find the value of @code{trees}:
+You can see the current value of a variable, any variable, by using
+the @code{describe-variable} function, which is usually invoked by
+typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
+(followed by @key{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
+@code{kill-ring}:
@smallexample
@group
-(setq trees '(maple oak pine birch))
- @result{} (maple oak pine birch)
+Documentation:
+List of killed text sequences.
+Since the kill ring is supposed to interact nicely with cut-and-paste
+facilities offered by window systems, use of this variable should
@end group
-
@group
-(setcdr (nthcdr 2 trees) nil)
- @result{} nil
-
-trees
- @result{} (maple oak pine)
+interact nicely with `interprogram-cut-function' and
+`interprogram-paste-function'. The functions `kill-new',
+`kill-append', and `current-kill' are supposed to implement this
+interaction; you may want to use them instead of manipulating the kill
+ring directly.
@end group
@end smallexample
-@noindent
-(The value returned by the @code{setcdr} expression is @code{nil} since
-that is what the @sc{cdr} is set to.)
-
-To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
-@sc{cdr} a number of times that is one less than the maximum permitted
-size of the kill ring and sets the @sc{cdr} of that element (which
-will be the rest of the elements in the kill ring) to @code{nil}.
-This prevents the kill ring from growing too long.
-
@need 800
-The next to last expression in the @code{kill-new} function is
-
-@smallexample
-(setq kill-ring-yank-pointer kill-ring)
-@end smallexample
-
-The @code{kill-ring-yank-pointer} is a global variable that is set to be
-the @code{kill-ring}.
-
-Even though the @code{kill-ring-yank-pointer} is called a
-@samp{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 @code{yank} and
-@code{yank-pop} (@pxref{Yanking, , Yanking Text Back}).
-
-@need 1200
-Now, to return to the first two lines in the body of the function:
+The kill ring is defined by a @code{defvar} in the following way:
@smallexample
@group
- (and (fboundp 'menu-bar-update-yank-menu)
- (menu-bar-update-yank-menu string (and replace (car kill-ring))))
+(defvar kill-ring nil
+ "List of killed text sequences.
+@dots{}")
@end group
@end smallexample
@noindent
-This is an expression whose first element is the function @code{and}.
-
-@findex and, @r{introduced}
-The @code{and} special form evaluates each of its arguments until one of
-the arguments returns a value of @code{nil}, in which case the
-@code{and} expression returns @code{nil}; however, if none of the
-arguments returns a value of @code{nil}, the value resulting from
-evaluating the last argument is returned. (Since such a value is not
-@code{nil}, it is considered true in Emacs Lisp.) In other words, an
-@code{and} expression returns a true value only if all its arguments
-are true.
-@findex and
-
-In this case, the expression tests first to see whether
-@code{menu-bar-update-yank-menu} exists as a function, and if so,
-calls it. The @code{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 (@pxref{Making
-Errors, , Generate an Error Message}).
-
-@need 1200
-Essentially, the @code{and} is an @code{if} expression that reads like
-this:
-
-@smallexample
-@group
-if @var{the-menu-bar-function-exists}
- then @var{execute-it}
-@end group
-@end smallexample
+In this variable definition, the variable is given an initial value of
+@code{nil}, which makes sense, since if you have saved nothing, you want
+nothing back if you give a @code{yank} command. The documentation
+string is written just like the documentation string of a @code{defun}.
+As with the documentation string of the @code{defun}, the first line of
+the documentation should be a complete sentence, since some commands,
+like @code{apropos}, print only the first line of documentation.
+Succeeding lines should not be indented; otherwise they look odd when
+you use @kbd{C-h v} (@code{describe-variable}).
-@code{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.
+@node defvar and asterisk, , See variable current value, defvar
+@subsection @code{defvar} and an asterisk
+@findex defvar @r{for a user customizable variable}
+@findex defvar @r{with an asterisk}
-Finally, the last expression in the @code{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 @code{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.
+In the past, Emacs used the @code{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 @code{defvar} for user customizable variables, please use
+@code{defcustom} instead, since that special form provides a path into
+the Customization commands. (@xref{defcustom, , Specifying Variables
+using @code{defcustom}}.)
-@need 1200
-The expression looks like this:
+When you specified a variable using the @code{defvar} special form,
+you could distinguish a readily settable variable from others by
+typing an asterisk, @samp{*}, in the first column of its documentation
+string. For example:
@smallexample
@group
- (if interprogram-cut-function
- (funcall interprogram-cut-function string (not replace))))
+(defvar shell-command-default-error-buffer nil
+ "*Buffer name for `shell-command' @dots{} error output.
+@dots{} ")
@end group
@end smallexample
-If an @code{interprogram-cut-function} exists, then Emacs executes
-@code{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 @code{if} expression could be replaced by an @code{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.
+@findex set-variable
+@noindent
+You could (and still can) use the @code{set-variable} command to
+change the value of @code{shell-command-default-error-buffer}
+temporarily. However, options set using @code{set-variable} 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 @file{.emacs} file,
+either by setting it manually or by using @code{customize}.
+@xref{Emacs Initialization, , Your @file{.emacs} File}.
-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'.
+For me, the major use of the @code{set-variable} command is to suggest
+variables that I might want to set in my @file{.emacs} file. There
+are now more than 700 such variables --- far too many to remember
+readily. Fortunately, you can press @key{TAB} after calling the
+@code{M-x set-variable} command to see the list of variables.
+(@xref{Examining, , Examining and Setting Variables, emacs,
+The GNU Emacs Manual}.)
@need 1250
-@node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text
+@node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text
@comment node-name, next, previous, up
@section Review
buffer and stores that text in the kill ring, so you can get it back
by yanking.
-@code{delete-and-extract-region} removes the text between point and
-mark from the buffer and throws it away. You cannot get it back.
-
@code{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.
@end table
+@code{delete-and-extract-region} removes the text between point and
+mark from the buffer and throws it away. You cannot get it back.
+(This is not an interactive command.)
+
@need 1500
@node search Exercises, , cons & search-fwd Review, Cutting & Storing Text
@section Searching Exercises
@menu
* Lists diagrammed::
-* Symbols as Chest:: Exploring a powerful metaphor.
+* Symbols as Chest::
* List Exercise::
@end menu
list is handled as a ring.)
@menu
-* Kill Ring Overview:: The kill ring is a list.
-* kill-ring-yank-pointer:: The @code{kill-ring-yank-pointer} variable.
+* Kill Ring Overview::
+* kill-ring-yank-pointer::
* yank nthcdr Exercises::
@end menu
(insert (car kill-ring-yank-pointer))
@end smallexample
+@noindent
+(Well, no more. In GNU Emacs 22, the function has been replaced by
+@code{insert-for-yank} which calls @code{insert-for-yank-1}
+repetitively for each @code{yank-handler} segment. In turn,
+@code{insert-for-yank-1} strips text properties from the inserted text
+according to @code{yank-excluded-properties}. Otherwise, it is just
+like @code{insert}. We will stick with plain @code{insert} since it
+is easier to understand.)
+
To begin to understand how @code{yank} and @code{yank-pop} work, it is
first necessary to look at the @code{kill-ring-yank-pointer} variable
and the @code{rotate-yank-pointer} function.
of the kill ring of which the first element (the @sc{car}) will be
inserted.
-The @code{rotate-yank-pointer} function changes the element in the
-kill ring to which the @code{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
-@code{rotate-yank-pointer} function itself is not difficult, but
-contains many details. It and the much simpler @code{yank} and
-@code{yank-pop} functions are described in an appendix.
-@xref{Kill Ring, , Handling the Kill Ring}.
+
+@ignore
+In GNU Emacs 22, the @code{kill-new} function calls
+
+@code{(setq kill-ring-yank-pointer kill-ring)}
+
+(defun rotate-yank-pointer (arg)
+ "Rotate the yanking point in the kill ring.
+With argument, rotate that many kills forward (or backward, if negative)."
+ (interactive "p")
+ (current-kill arg))
+
+(defun current-kill (n &optional do-not-move)
+ "Rotate the yanking point by N places, and then return that kill.
+If N is zero, `interprogram-paste-function' is set, and calling it
+returns a string, then that string is added to the front of the
+kill ring and returned as the latest kill.
+If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
+yanking point; just return the Nth kill forward."
+ (let ((interprogram-paste (and (= n 0)
+ interprogram-paste-function
+ (funcall interprogram-paste-function))))
+ (if interprogram-paste
+ (progn
+ ;; Disable the interprogram cut function when we add the new
+ ;; text to the kill ring, so Emacs doesn't try to own the
+ ;; selection, with identical text.
+ (let ((interprogram-cut-function nil))
+ (kill-new interprogram-paste))
+ interprogram-paste)
+ (or kill-ring (error "Kill ring is empty"))
+ (let ((ARGth-kill-element
+ (nthcdr (mod (- n (length kill-ring-yank-pointer))
+ (length kill-ring))
+ kill-ring)))
+ (or do-not-move
+ (setq kill-ring-yank-pointer ARGth-kill-element))
+ (car ARGth-kill-element)))))
+
+@end ignore
@need 1500
@node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking
15 and 30 times their default value.}.
@menu
-* while:: Causing a stretch of code to repeat.
+* while::
* dolist dotimes::
-* Recursion:: Causing a function to call itself.
+* Recursion::
* Looping exercise::
@end menu
@end smallexample
@menu
-* Looping with while:: Repeat so long as test returns true.
-* Loop Example:: A @code{while} loop that uses a list.
-* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}.
-* Incrementing Loop:: A loop with an incrementing counter.
-* Decrementing Loop:: A loop with a decrementing counter.
+* Looping with while::
+* Loop Example::
+* print-elements-of-list::
+* Incrementing Loop::
+* Decrementing Loop::
@end menu
@node Looping with while, Loop Example, while, while
@cindex @file{*scratch*} buffer
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.
+reading this in a recent instance of GNU Emacs,
+@c GNU Emacs 21, GNU Emacs 22, 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 @file{*scratch*} buffer and evaluate
You can copy the expressions by marking the beginning of the region
with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to
the end of the region and then copying the region using @kbd{M-w}
-(@code{copy-region-as-kill}). In the @file{*scratch*} buffer, you can
-yank the expressions back by typing @kbd{C-y} (@code{yank}).
+(@code{kill-ring-save}, which calls @code{copy-region-as-kill} and
+then provides visual feedback). In the @file{*scratch*}
+buffer, you can yank the expressions back by typing @kbd{C-y}
+(@code{yank}).
After you have copied the expressions to the @file{*scratch*} buffer,
evaluate each expression in turn. Be sure to evaluate the last
each @samp{^J} stands for a `newline'.)
@need 1500
-If you are using Emacs 21 or later, you can evaluate these expressions
+In a recent instance of GNU Emacs, you can evaluate these expressions
directly in the Info buffer, and the echo area will grow to show the
results.
is set to 1.
@menu
-* Incrementing Example:: Counting pebbles in a triangle.
-* Inc Example parts:: The parts of the function definition.
-* Inc Example altogether:: Putting the function definition together.
+* Incrementing Example::
+* Inc Example parts::
+* Inc Example altogether::
@end menu
@node Incrementing Example, Inc Example parts, Incrementing Loop, Incrementing Loop
called @code{number-of-rows}.
Finally, we need a variable to use as a counter. We could call this
-variable @code{counter}, but a better name is @code{row-number}.
-That is because what the counter does is count rows, and a program
-should be written to be as understandable as possible.
+variable @code{counter}, but a better name is @code{row-number}. That
+is because what the counter does in this function is count rows, and a
+program should be written to be as understandable as possible.
When the Lisp interpreter first starts evaluating the expressions in the
function, the value of @code{total} should be set to zero, since we have
(let (@var{varlist})
(while (@var{true-or-false-test})
@var{body-of-while}@dots{} )
- @dots{} ) ; @r{Need final expression here.}
+ @dots{} )) ; @r{Need final expression here.}
@end group
@end smallexample
@end smallexample
@menu
-* Decrementing Example:: More pebbles on the beach.
-* Dec Example parts:: The parts of the function definition.
-* Dec Example altogether:: Putting the function definition together.
+* Decrementing Example::
+* Dec Example parts::
+* Dec Example altogether::
@end menu
@node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop
arguments that the final instance will stop.
@menu
-* Building Robots:: Same model, different serial number ...
-* Recursive Definition Parts:: Walk until you stop ...
-* Recursion with list:: Using a list as the test whether to recurse.
+* Building Robots::
+* Recursive Definition Parts::
+* Recursion with list::
* Recursive triangle function::
* Recursion with cond::
-* Recursive Patterns:: Often used templates.
-* No Deferment:: Don't store up work ...
+* Recursive Patterns::
+* No Deferment::
* No deferment solution::
@end menu
of numbers can be written recursively. Here is the code, including
an expression to set the value of the variable @code{animals} to a list.
-If you are using Emacs 20 or before, this example must be copied to
-the @file{*scratch*} buffer and each expression must be evaluated
+If you are using GNU Emacs 20 or before, this example must be copied
+to the @file{*scratch*} buffer and each expression must be evaluated
there. Use @kbd{C-u C-x C-e} to evaluate the
@code{(print-elements-recursively animals)} expression so that the
results are printed in the buffer; otherwise the Lisp interpreter will
of the @code{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.
+If you are using a more recent version, you can evaluate this
+expression directly in Info.
@findex print-elements-recursively
@smallexample
@need 1200
@noindent
and find that the result is false, so it will invoke
-the then-part of the @code{if} clause:
+the else-part of the @code{if} clause:
@smallexample
@group
@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
a Texinfo manual in the current directory. Or, if you are on the
Internet, see
-@uref{http://www.gnu.org/manual/texinfo-4.6/html_node/Indicating.html}
+@uref{http://www.gnu.org/software/texinfo/manual/texinfo/}
@end ifhtml
@iftex
``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
introduces several new features.
@menu
-* sentence-end:: The regular expression for @code{sentence-end}.
-* re-search-forward:: Very similar to @code{search-forward}.
-* forward-sentence:: A straightforward example of regexp search.
-* forward-paragraph:: A somewhat complex example.
-* etags:: How to create your own @file{TAGS} table.
+* sentence-end::
+* re-search-forward::
+* forward-sentence::
+* forward-paragraph::
+* etags::
* Regexp Review::
* re-search Exercises::
@end menu
@end group
@end smallexample
-@ignore
+@noindent
+(Well, not in GNU Emacs 22; that is because of an effort to make the
+process simpler. When its value is @code{nil}, then use the value
+defined by the function @code{sentence-end}, and that returns a value
+constructed from the variables @code{sentence-end-base},
+@code{sentence-end-double-space}, @code{sentence-end-without-period},
+and @code{sentence-end-without-space}. The critical variable is
+@code{sentence-end-base}; its global value is similar to the one
+described above but it also contains two additional quotation marks.
+These have differing degrees of curliness. The
+@code{sentence-end-without-period} variable, when true, tells Emacs
+that a sentence may end without a period, such as text in Thai.)
+@ignore
@noindent
(Note that here the @key{TAB}, two spaces, and @key{RET} are shown
literally in the pattern.)
the pattern, the carriage return is inserted as an actual carriage
return between square brackets but here it is shown as @key{RET}.
@end table
-
@end ignore
@node re-search-forward, forward-sentence, sentence-end, Regexp Search
@need 1200
In the @code{forward-sentence} function, the regular expression will be
-the value of the variable @code{sentence-end}, namely:
+the value of the variable @code{sentence-end}. In simple form, that is:
@smallexample
@group
@menu
* Complete forward-sentence::
-* fwd-sentence while loops:: Two @code{while} loops.
-* fwd-sentence re-search:: A regular expression search.
+* fwd-sentence while loops::
+* fwd-sentence re-search::
@end menu
@node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence
@need 1250
Here is the code for @code{forward-sentence}:
+@c in GNU Emacs 22
+@smallexample
+@group
+(defun forward-sentence (&optional arg)
+ "Move forward to next `sentence-end'. With argument, repeat.
+With negative argument, move backward repeatedly to `sentence-beginning'.
+
+The variable `sentence-end' is a regular expression that matches ends of
+sentences. Also, every paragraph boundary terminates sentences as well."
+@end group
+@group
+ (interactive "p")
+ (or arg (setq arg 1))
+ (let ((opoint (point))
+ (sentence-end (sentence-end)))
+ (while (< arg 0)
+ (let ((pos (point))
+ (par-beg (save-excursion (start-of-paragraph-text) (point))))
+ (if (and (re-search-backward sentence-end par-beg t)
+ (or (< (match-end 0) pos)
+ (re-search-backward sentence-end par-beg t)))
+ (goto-char (match-end 0))
+ (goto-char par-beg)))
+ (setq arg (1+ arg)))
+@end group
+@group
+ (while (> arg 0)
+ (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
+ (if (re-search-forward sentence-end par-end t)
+ (skip-chars-backward " \t\n")
+ (goto-char par-end)))
+ (setq arg (1- arg)))
+ (constrain-to-field nil opoint t)))
+@end group
+@end smallexample
+
+@ignore
+GNU Emacs 21
@smallexample
@group
(defun forward-sentence (&optional arg)
(setq arg (1- arg))))
@end group
@end smallexample
+@end ignore
The function looks long at first sight and it is best to look at its
skeleton first, and then its muscle. The way to see the skeleton is to
"@var{documentation}@dots{}"
(interactive "p")
(or arg (setq arg 1))
- (while (< arg 0)
- @var{body-of-while-loop}
- (while (> arg 0)
- @var{body-of-while-loop}
+ (let ((opoint (point)) (sentence-end (sentence-end)))
+ (while (< arg 0)
+ (let ((pos (point))
+ (par-beg (save-excursion (start-of-paragraph-text) (point))))
+ @var{rest-of-body-of-while-loop-when-going-backwards}
+ (while (> arg 0)
+ (let ((par-end (save-excursion (end-of-paragraph-text) (point))))
+ @var{rest-of-body-of-while-loop-when-going-forwards}
+ @var{handle-forms-and-equivalent}
@end group
@end smallexample
This looks much simpler! The function definition consists of
documentation, an @code{interactive} expression, an @code{or}
-expression, and @code{while} loops.
+expression, a @code{let} expression, and @code{while} loops.
Let's look at each of these parts in turn.
that the processed prefix argument, if any, is passed to the
function as its argument. (This will be a number.) If the function
is not passed an argument (it is optional) then the argument
-@code{arg} will be bound to 1. When @code{forward-sentence} is called
-non-interactively without an argument, @code{arg} is bound to
+@code{arg} will be bound to 1.
+
+When @code{forward-sentence} is called non-interactively without an
+argument, @code{arg} is bound to @code{nil}. The @code{or} expression
+handles this. What it does is either leave the value of @code{arg} as
+it is, but only if @code{arg} is bound to a value; or it sets the
+value of @code{arg} to 1, in the case when @code{arg} is bound to
@code{nil}.
-The @code{or} expression handles the prefix argument. What it does is
-either leave the value of @code{arg} as it is, but only if @code{arg}
-is bound to a value; or it sets the value of @code{arg} to 1, in the
-case when @code{arg} is bound to @code{nil}.
+Next is a @code{let}. That specifies the values of two local
+variables, @code{point} and @code{sentence-end}. The local value of
+point, from before the search, is used in the
+@code{constrain-to-field} function which handles forms and
+equivalents. The @code{sentence-end} variable is set by the
+@code{sentence-end} function.
@node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence
@unnumberedsubsec The @code{while} loops
-Two @code{while} loops follow the @code{or} expression. The first
-@code{while} has a true-or-false-test that tests true if the prefix
-argument for @code{forward-sentence} is a negative number. This is for
-going backwards. The body of this loop is similar to the body of the
-second @code{while} clause, but it is not exactly the same. We will
-skip this @code{while} loop and concentrate on the second @code{while}
+Two @code{while} loops follow. The first @code{while} has a
+true-or-false-test that tests true if the prefix argument for
+@code{forward-sentence} is a negative number. This is for going
+backwards. The body of this loop is similar to the body of the second
+@code{while} clause, but it is not exactly the same. We will skip
+this @code{while} loop and concentrate on the second @code{while}
loop.
@need 1500
argument, which is @code{(goto-char par-end)}: it moves point to the
end of the paragraph.
+(And if the text is in a form or equivalent, and point may not move
+fully, then the @code{constrain-to-field} function comes into play.)
+
Regular expression searches are exceptionally useful and the pattern
illustrated by @code{re-search-forward}, in which the search is the
test of an @code{if} expression, is handy. You will see or write code
@section @code{forward-paragraph}: a Goldmine of Functions
@findex forward-paragraph
+@ignore
+@c in GNU Emacs 22
+(defun forward-paragraph (&optional arg)
+ "Move forward to end of paragraph.
+With argument ARG, do it ARG times;
+a negative argument ARG = -N means move backward N paragraphs.
+
+A line which `paragraph-start' matches either separates paragraphs
+\(if `paragraph-separate' matches it also) or is the first line of a paragraph.
+A paragraph end is the beginning of a line which is not part of the paragraph
+to which the end of the previous line belongs, or the end of the buffer.
+Returns the count of paragraphs left to move."
+ (interactive "p")
+ (or arg (setq arg 1))
+ (let* ((opoint (point))
+ (fill-prefix-regexp
+ (and fill-prefix (not (equal fill-prefix ""))
+ (not paragraph-ignore-fill-prefix)
+ (regexp-quote fill-prefix)))
+ ;; Remove ^ from paragraph-start and paragraph-sep if they are there.
+ ;; These regexps shouldn't be anchored, because we look for them
+ ;; starting at the left-margin. This allows paragraph commands to
+ ;; work normally with indented text.
+ ;; This hack will not find problem cases like "whatever\\|^something".
+ (parstart (if (and (not (equal "" paragraph-start))
+ (equal ?^ (aref paragraph-start 0)))
+ (substring paragraph-start 1)
+ paragraph-start))
+ (parsep (if (and (not (equal "" paragraph-separate))
+ (equal ?^ (aref paragraph-separate 0)))
+ (substring paragraph-separate 1)
+ paragraph-separate))
+ (parsep
+ (if fill-prefix-regexp
+ (concat parsep "\\|"
+ fill-prefix-regexp "[ \t]*$")
+ parsep))
+ ;; This is used for searching.
+ (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)"))
+ start found-start)
+ (while (and (< arg 0) (not (bobp)))
+ (if (and (not (looking-at parsep))
+ (re-search-backward "^\n" (max (1- (point)) (point-min)) t)
+ (looking-at parsep))
+ (setq arg (1+ arg))
+ (setq start (point))
+ ;; Move back over paragraph-separating lines.
+ (forward-char -1) (beginning-of-line)
+ (while (and (not (bobp))
+ (progn (move-to-left-margin)
+ (looking-at parsep)))
+ (forward-line -1))
+ (if (bobp)
+ nil
+ (setq arg (1+ arg))
+ ;; Go to end of the previous (non-separating) line.
+ (end-of-line)
+ ;; Search back for line that starts or separates paragraphs.
+ (if (if fill-prefix-regexp
+ ;; There is a fill prefix; it overrides parstart.
+ (let (multiple-lines)
+ (while (and (progn (beginning-of-line) (not (bobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (looking-at fill-prefix-regexp))
+ (unless (= (point) start)
+ (setq multiple-lines t))
+ (forward-line -1))
+ (move-to-left-margin)
+ ;; This deleted code caused a long hanging-indent line
+ ;; not to be filled together with the following lines.
+ ;; ;; Don't move back over a line before the paragraph
+ ;; ;; which doesn't start with fill-prefix
+ ;; ;; unless that is the only line we've moved over.
+ ;; (and (not (looking-at fill-prefix-regexp))
+ ;; multiple-lines
+ ;; (forward-line 1))
+ (not (bobp)))
+ (while (and (re-search-backward sp-parstart nil 1)
+ (setq found-start t)
+ ;; Found a candidate, but need to check if it is a
+ ;; REAL parstart.
+ (progn (setq start (point))
+ (move-to-left-margin)
+ (not (looking-at parsep)))
+ (not (and (looking-at parstart)
+ (or (not use-hard-newlines)
+ (bobp)
+ (get-text-property
+ (1- start) 'hard)))))
+ (setq found-start nil)
+ (goto-char start))
+ found-start)
+ ;; Found one.
+ (progn
+ ;; Move forward over paragraph separators.
+ ;; We know this cannot reach the place we started
+ ;; because we know we moved back over a non-separator.
+ (while (and (not (eobp))
+ (progn (move-to-left-margin)
+ (looking-at parsep)))
+ (forward-line 1))
+ ;; If line before paragraph is just margin, back up to there.
+ (end-of-line 0)
+ (if (> (current-column) (current-left-margin))
+ (forward-char 1)
+ (skip-chars-backward " \t")
+ (if (not (bolp))
+ (forward-line 1))))
+ ;; No starter or separator line => use buffer beg.
+ (goto-char (point-min))))))
+
+ (while (and (> arg 0) (not (eobp)))
+ ;; Move forward over separator lines...
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (looking-at parsep))
+ (forward-line 1))
+ (unless (eobp) (setq arg (1- arg)))
+ ;; ... and one more line.
+ (forward-line 1)
+ (if fill-prefix-regexp
+ ;; There is a fill prefix; it overrides parstart.
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (not (looking-at parsep))
+ (looking-at fill-prefix-regexp))
+ (forward-line 1))
+ (while (and (re-search-forward sp-parstart nil 1)
+ (progn (setq start (match-beginning 0))
+ (goto-char start)
+ (not (eobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (or (not (looking-at parstart))
+ (and use-hard-newlines
+ (not (get-text-property (1- start) 'hard)))))
+ (forward-char 1))
+ (if (< (point) (point-max))
+ (goto-char start))))
+ (constrain-to-field nil opoint t)
+ ;; Return the number of steps that could not be done.
+ arg))
+@end ignore
+
The @code{forward-paragraph} function moves point forward to the end
of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a
number of functions that are important in themselves, including
This is an added complication.
@menu
-* forward-paragraph in brief:: Key parts of the function definition.
-* fwd-para let:: The @code{let*} expression.
-* fwd-para while:: The forward motion @code{while} loop.
-* fwd-para between paragraphs:: Movement between paragraphs.
-* fwd-para within paragraph:: Movement within paragraphs.
-* fwd-para no fill prefix:: When there is no fill prefix.
-* fwd-para with fill prefix:: When there is a fill prefix.
-* fwd-para summary:: Summary of @code{forward-paragraph} code.
+* forward-paragraph in brief::
+* fwd-para let::
+* fwd-para while::
@end menu
@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph
(or arg (setq arg 1))
(let*
@var{varlist}
- (while (< arg 0) ; @r{backward-moving-code}
+ (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code}
@dots{}
- (setq arg (1+ arg)))
- (while (> arg 0) ; @r{forward-moving-code}
+ (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code}
@dots{}
- (setq arg (1- arg)))))
@end group
@end smallexample
@unnumberedsubsec The @code{let*} expression
The next line of the @code{forward-paragraph} function begins a
-@code{let*} expression. This is a different kind of expression than
-we have seen so far. The symbol is @code{let*} not @code{let}.
+@code{let*} expression. This is a different than @code{let}. The
+symbol is @code{let*} not @code{let}.
The @code{let*} special form is like @code{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 @code{let*} expression in this function, Emacs binds two
-variables: @code{fill-prefix-regexp} and @code{paragraph-separate}.
-The value to which @code{paragraph-separate} is bound depends on the
-value of @code{fill-prefix-regexp}.
+@ignore
+( refappend save-excursion, , code save-excursion in code append-to-buffer .)
+@end ignore
-@need 1200
-Let's look at each in turn. The symbol @code{fill-prefix-regexp} is
-set to the value returned by evaluating the following list:
+(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.)
+
+In the @code{let*} expression in this function, Emacs binds a total of
+seven variables: @code{opoint}, @code{fill-prefix-regexp},
+@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and
+@code{found-start}.
+
+The variable @code{parsep} appears twice, first, to remove instances
+of @samp{^}, and second, to handle fill prefixes.
+
+The variable @code{opoint} is just the value of @code{point}. As you
+can guess, it is used in a @code{constrain-to-field} expression, just
+as in @code{forward-sentence}.
+
+The variable @code{fill-prefix-regexp} is set to the value returned by
+evaluating the following list:
@smallexample
@group
will exactly match the fill prefix if the fill prefix exists.
Otherwise, the variable will be set to @code{nil}.
-The second local variable in the @code{let*} expression is
-@code{paragraph-separate}. It is bound to the value returned by
-evaluating the expression:
-
-@smallexample
-@group
-(if fill-prefix-regexp
- (concat paragraph-separate
- "\\|^" fill-prefix-regexp "[ \t]*$")
- paragraph-separate)))
-@end group
-@end smallexample
+The next two local variables in the @code{let*} expression are
+designed to remove instances of @samp{^} from @code{parstart} and
+@code{parsep}, the local variables indicate the paragraph start and
+the paragraph separator. The next expression sets @code{parsep}
+again. That is to handle fill prefixes.
-This expression shows why @code{let*} rather than @code{let} was used.
-The true-or-false-test for the @code{if} depends on whether the variable
-@code{fill-prefix-regexp} evaluates to @code{nil} or some other value.
+This is the setting that requires the definition call @code{let*}
+rather than @code{let}. The true-or-false-test for the @code{if}
+depends on whether the variable @code{fill-prefix-regexp} evaluates to
+@code{nil} or some other value.
If @code{fill-prefix-regexp} does not have a value, Emacs evaluates
-the else-part of the @code{if} expression and binds
-@code{paragraph-separate} to its local value.
-(@code{paragraph-separate} is a regular expression that matches what
-separates paragraphs.)
+the else-part of the @code{if} expression and binds @code{parsep} to
+its local value. (@code{parsep} is a regular expression that matches
+what separates paragraphs.)
But if @code{fill-prefix-regexp} does have a value, Emacs evaluates
-the then-part of the @code{if} expression and binds
-@code{paragraph-separate} to a regular expression that includes the
-@code{fill-prefix-regexp} as part of the pattern.
-
-Specifically, @code{paragraph-separate} is set to the original value
-of the paragraph separate regular expression concatenated with an
-alternative expression that consists of the @code{fill-prefix-regexp}
-followed by a blank line. The @samp{^} indicates that the
-@code{fill-prefix-regexp} must begin a line, and the optional
-whitespace to the end of the line is defined by @w{@code{"[ \t]*$"}}.)
-The @samp{\\|} defines this portion of the regexp as an alternative to
-@code{paragraph-separate}.
+the then-part of the @code{if} expression and binds @code{parsep} to a
+regular expression that includes the @code{fill-prefix-regexp} as part
+of the pattern.
+
+Specifically, @code{parsep} is set to the original value of the
+paragraph separate regular expression concatenated with an alternative
+expression that consists of the @code{fill-prefix-regexp} followed by
+optional whitespace to the end of the line. The whitespace is defined
+by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the
+regexp as an alternative to @code{parsep}.
+
+According to a comment in the code, the next local variable,
+@code{sp-parstart}, is used for searching, and then the final two,
+@code{start} and @code{found-start}, are set to @code{nil}.
Now we get into the body of the @code{let*}. The first part of the body
of the @code{let*} deals with the case when the function is given a
negative argument and is therefore moving backwards. We will skip this
section.
-@node fwd-para while, fwd-para between paragraphs, fwd-para let, forward-paragraph
+@node fwd-para while, , fwd-para let, forward-paragraph
@unnumberedsubsec The forward motion @code{while} loop
The second part of the body of the @code{let*} deals with forward
@code{while} loop is evaluated exactly once, and the cursor moves
forward one paragraph.
+@ignore
+(while (and (> arg 0) (not (eobp)))
+
+ ;; Move forward over separator lines...
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (looking-at parsep))
+ (forward-line 1))
+ (unless (eobp) (setq arg (1- arg)))
+ ;; ... and one more line.
+ (forward-line 1)
+
+ (if fill-prefix-regexp
+ ;; There is a fill prefix; it overrides parstart.
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (not (looking-at parsep))
+ (looking-at fill-prefix-regexp))
+ (forward-line 1))
+
+
+ (while (and (re-search-forward sp-parstart nil 1)
+ (progn (setq start (match-beginning 0))
+ (goto-char start)
+ (not (eobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (or (not (looking-at parstart))
+ (and use-hard-newlines
+ (not (get-text-property (1- start) 'hard)))))
+ (forward-char 1))
+
+ (if (< (point) (point-max))
+ (goto-char start))))
+@end ignore
+
This part handles three situations: when point is between paragraphs,
-when point is within a paragraph and there is a fill prefix, and
-when point is within a paragraph and there is no fill prefix.
+when there is a fill prefix and when there is no fill prefix.
@need 800
The @code{while} loop looks like this:
@smallexample
@group
-(while (> arg 0)
- (beginning-of-line)
+;; @r{going forwards and not at the end of the buffer}
+(while (and (> arg 0) (not (eobp)))
;; @r{between paragraphs}
- (while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
+ ;; Move forward over separator lines...
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (looking-at parsep))
+ (forward-line 1))
+ ;; @r{This decrements the loop}
+ (unless (eobp) (setq arg (1- arg)))
+ ;; ... and one more line.
+ (forward-line 1)
@end group
@group
- ;; @r{within paragraphs, with a fill prefix}
(if fill-prefix-regexp
- ;; @r{There is a fill prefix; it overrides paragraph-start.}
+ ;; There is a fill prefix; it overrides parstart;
+ ;; we go forward line by line
(while (and (not (eobp))
- (not (looking-at paragraph-separate))
+ (progn (move-to-left-margin) (not (eobp)))
+ (not (looking-at parsep))
(looking-at fill-prefix-regexp))
(forward-line 1))
@end group
@group
- ;; @r{within paragraphs, no fill prefix}
- (if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max))))
+ ;; There is no fill prefix;
+ ;; we go forward character by character
+ (while (and (re-search-forward sp-parstart nil 1)
+ (progn (setq start (match-beginning 0))
+ (goto-char start)
+ (not (eobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (or (not (looking-at parstart))
+ (and use-hard-newlines
+ (not (get-text-property (1- start) 'hard)))))
+ (forward-char 1))
+@end group
- (setq arg (1- arg)))
+@group
+ ;; and if there is no fill prefix and if we are not at the end,
+ ;; go to whatever was found in the regular expression search
+ ;; for sp-parstart
+ (if (< (point) (point-max))
+ (goto-char start))))
@end group
@end smallexample
-We can see immediately that this is a decrementing counter @code{while}
-loop, using the expression @code{(setq arg (1- arg))} as the decrementer.
+@findex eobp
+We can see that this is a decrementing counter @code{while} loop,
+using the expression @code{(setq arg (1- arg))} as the decrementer.
+That expression is not far from the @code{while}, but is hidden in
+another Lisp macro, an @code{unless} macro. Unless we are at the end
+of the buffer --- that is what the @code{eobp} function determines; it
+is an abbreviation of @samp{End Of Buffer P} --- we decrease the value
+of @code{arg} by one.
+
+(If we are at the end of the buffer, we cannot go forward any more and
+the next loop of the @code{while} expression will test false since the
+test is an @code{and} with @code{(not (eobp))}. The @code{not}
+function means exactly as you expect; it is another name for
+@code{null}, a function that returns true when its argument is false.)
+
+Interestingly, the loop count is not decremented until we leave the
+space between paragraphs, unless we come to the end of buffer or stop
+seeing the local value of the paragraph separator.
+
+That second @code{while} also has a @code{(move-to-left-margin)}
+expression. The function is self-explanatory. It is inside a
+@code{progn} expression and not the last element of its body, so it is
+only invoked for its side effect, which is to move point to the left
+margin of the current line.
-@need 800
-The body of the loop consists of three expressions:
+@findex looking-at
+The @code{looking-at} function is also self-explanatory; it returns
+true if the text after point matches the regular expression given as
+its argument.
-@smallexample
-@group
-;; @r{between paragraphs}
-(beginning-of-line)
-(while
- @var{body-of-while})
-@end group
+The rest of the body of the loop looks difficult at first, but makes
+sense as you come to understand it.
-@group
-;; @r{within paragraphs, with fill prefix}
-(if @var{true-or-false-test}
- @var{then-part}
-@end group
+@need 800
+First consider what happens if there is a fill prefix:
+@smallexample
@group
-;; @r{within paragraphs, no fill prefix}
- @var{else-part}
+ (if fill-prefix-regexp
+ ;; There is a fill prefix; it overrides parstart;
+ ;; we go forward line by line
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (not (looking-at parsep))
+ (looking-at fill-prefix-regexp))
+ (forward-line 1))
@end group
@end smallexample
@noindent
-When the Emacs Lisp interpreter evaluates the body of the
-@code{while} loop, the first thing it does is evaluate the
-@code{(beginning-of-line)} expression and move point to the beginning
-of the line. Then there is an inner @code{while} loop. This
-@code{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 @code{if} expression that actually moves point to the end
-of the paragraph.
-
-@node fwd-para between paragraphs, fwd-para within paragraph, fwd-para while, forward-paragraph
-@unnumberedsubsec Between paragraphs
-
-First, let us look at the inner @code{while} loop. This loop handles
-the case when point is between paragraphs; it uses three functions
-that are new to us: @code{prog1}, @code{eobp} and @code{looking-at}.
-@findex prog1
-@findex eobp
-@findex looking-at
+This expression moves point forward line by line so long
+as four conditions are true:
-@itemize @bullet
+@enumerate
@item
-@code{prog1} is similar to the @code{progn} special form,
-except that @code{prog1} evaluates its arguments in sequence and then
-returns the value of its first argument as the value of the whole
-expression. (@code{progn} returns the value of its last argument as the
-value of the expression.) The second and subsequent arguments to
-@code{prog1} are evaluated only for their side effects.
+Point is not at the end of the buffer.
@item
-@code{eobp} is an abbreviation of @samp{End Of Buffer P} and is a
-function that returns true if point is at the end of the buffer.
+We can move to the left margin of the text and are
+not at the end of the buffer.
@item
-@code{looking-at} is a function that returns true if the text following
-point matches the regular expression passed @code{looking-at} as its
-argument.
-@end itemize
+The text following point does not separate paragraphs.
-@need 800
-The @code{while} loop we are studying looks like this:
+@item
+The pattern following point is the fill prefix regular expression.
+@end enumerate
-@smallexample
-@group
-(while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
-@end group
-@end smallexample
+The last condition may be puzzling, until you remember that point was
+moved to the beginning of the line early in the @code{forward-paragraph}
+function. This means that if the text has a fill prefix, the
+@code{looking-at} function will see it.
-@need 1200
-@noindent
-This is a @code{while} loop with no body! The true-or-false-test of the
-loop is the expression:
+@need 1250
+Consider what happens when there is no fill prefix.
@smallexample
@group
-(prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1))
+ (while (and (re-search-forward sp-parstart nil 1)
+ (progn (setq start (match-beginning 0))
+ (goto-char start)
+ (not (eobp)))
+ (progn (move-to-left-margin)
+ (not (looking-at parsep)))
+ (or (not (looking-at parstart))
+ (and use-hard-newlines
+ (not (get-text-property (1- start) 'hard)))))
+ (forward-char 1))
@end group
@end smallexample
@noindent
-The first argument to the @code{prog1} is the @code{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 @code{and} expression is true. After evaluating the @code{and}
-expression, the Lisp interpreter evaluates the second argument to
-@code{prog1}, which is @code{forward-line}. This moves point forward
-one line. The value returned by the @code{prog1} however, is the
-value of its first argument, so the @code{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
-@code{and} expression tests false. Note however, that the
-@code{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.
-
-@node fwd-para within paragraph, fwd-para no fill prefix, fwd-para between paragraphs, forward-paragraph
-@unnumberedsubsec Within paragraphs
-
-The next expression in the outer @code{while} loop is an @code{if}
-expression. The Lisp interpreter evaluates the then-part of the
-@code{if} when the @code{fill-prefix-regexp} variable has a value other
-than @code{nil}, and it evaluates the else-part when the value of
-@code{if fill-prefix-regexp} is @code{nil}, that is, when there is no
-fill prefix.
-
-@node fwd-para no fill prefix, fwd-para with fill prefix, fwd-para within paragraph, forward-paragraph
-@unnumberedsubsec No fill prefix
+This @code{while} loop has us searching forward for
+@code{sp-parstart}, which is the combination of possible whitespace
+with a the local value of the start of a paragraph or of a paragraph
+separator. (The latter two are within an expression starting
+@code{\(?:} so that they are not referenced by the
+@code{match-beginning} function.)
-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 @code{if}
-expression, and reads as follows:
+@need 800
+The two expressions,
@smallexample
@group
-(if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max)))
+(setq start (match-beginning 0))
+(goto-char start)
@end group
@end smallexample
@noindent
-This expression actually does the work that most people think of as
-the primary purpose of the @code{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.
+mean go to the start of the text matched by the regular expression
+search.
-The only unfamiliar part of this is the use of @code{match-beginning}.
-This is another function that is new to us. The
-@code{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 @code{(match-beginning 0)} expression is new. It returns a number
+specifying the location of the start of the text that was matched by
+the last search.
The @code{match-beginning} function is used here because of a
characteristic of a forward search: a successful forward search,
regardless of whether it is a plain search or a regular expression
-search, 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
-@code{paragraph-start}, which will be the beginning of the next
-paragraph rather than the end of the current one.
+search, moves point to the end of the text that is found. In this
+case, a successful search moves point to the end of the pattern for
+@code{sp-parstart}.
-However, we want to put point at the end of the current paragraph, not at
-the beginning of the next one. The two positions may be different,
-because there may be several blank lines between paragraphs.
+However, we want to put point at the end of the current paragraph, not
+somewhere else. Indeed, since the search possibly includes the
+paragraph separator, point may end up at the beginning of the next one
+unless we use an expression that includes @code{match-beginning}.
@findex match-beginning
-When given an argument of 0, @code{match-beginning} returns the position
-that is the start of the text that the most recent regular
-expression search matched. In this case, the most recent regular
-expression search is the one looking for @code{paragraph-start}, so
-@code{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.
+When given an argument of 0, @code{match-beginning} returns the
+position that is the start of the text matched by the most recent
+search. In this case, the most recent search looks for
+@code{sp-parstart}. The @code{(match-beginning 0)} expression returns
+the beginning position of that pattern, rather than the end position
+of that pattern.
(Incidentally, when passed a positive number as an argument, the
-@code{match-beginning} function will place point at that parenthesized
-expression in the last regular expression. It is a useful function.)
-
-@node fwd-para with fill prefix, fwd-para summary, fwd-para no fill prefix, forward-paragraph
-@unnumberedsubsec With a fill prefix
-
-The inner @code{if} expression just discussed is the else-part of an enclosing
-@code{if} expression which tests whether there is a fill prefix. If
-there is a fill prefix, the then-part of this @code{if} is evaluated.
-It looks like this:
-
-@smallexample
-@group
-(while (and (not (eobp))
- (not (looking-at paragraph-separate))
- (looking-at fill-prefix-regexp))
- (forward-line 1))
-@end group
-@end smallexample
-
-@noindent
-What this expression does is move point forward line by line so long
-as three conditions are true:
-
-@enumerate
-@item
-Point is not at the end of the buffer.
-
-@item
-The text following point does not separate paragraphs.
-
-@item
-The pattern following point is the fill prefix regular expression.
-@end enumerate
-
-The last condition may be puzzling, until you remember that point was
-moved to the beginning of the line early in the @code{forward-paragraph}
-function. This means that if the text has a fill prefix, the
-@code{looking-at} function will see it.
-
-@node fwd-para summary, , fwd-para with fill prefix, forward-paragraph
-@unnumberedsubsec Summary
-
-In summary, when moving forward, the @code{forward-paragraph} function
-does the following:
-
-@itemize @bullet
-@item
-Move point to the beginning of the line.
+@code{match-beginning} function returns the location of point at that
+parenthesized expression in the last search unless that parenthesized
+expression begins with @code{\(?:}. I don't know why @code{\(?:}
+appears here since the argument is 0.)
-@item
-Skip over lines between paragraphs.
-
-@item
-Check whether there is a fill prefix, and if there is:
-
-@itemize ---
-
-@item
-Go forward line by line so long as the line is not a paragraph
-separating line.
-@end itemize
-
-@item
-But if there is no fill prefix,
-
-@itemize ---
-
-@item
-Search for the next paragraph start pattern.
-
-@item
-Go to the beginning of the paragraph start pattern, which will be the
-end of the previous paragraph.
-
-@item
-Or else go to the end of the accessible portion of the buffer.
-@end itemize
-@end itemize
-
-@need 1200
-For review, here is the code we have just been discussing, formatted
-for clarity:
-
-@smallexample
-@group
-(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)))
-@end group
-
-@group
- (paragraph-separate
- (if fill-prefix-regexp
- (concat paragraph-separate
- "\\|^"
- fill-prefix-regexp
- "[ \t]*$")
- paragraph-separate)))
-
- @var{omitted-backward-moving-code} @dots{}
-@end group
-
-@group
- (while (> arg 0) ; @r{forward-moving-code}
- (beginning-of-line)
-
- (while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
-@end group
+@need 1250
+The last expression when there is no fill prefix is
+@smallexample
@group
- (if fill-prefix-regexp
- (while (and (not (eobp)) ; @r{then-part}
- (not (looking-at paragraph-separate))
- (looking-at fill-prefix-regexp))
- (forward-line 1))
-@end group
-@group
- ; @r{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))))) ; @r{decrementer}
+(if (< (point) (point-max))
+ (goto-char start))))
@end group
@end smallexample
+@noindent
+This says that if there is no fill prefix and if we are not at the
+end, point should move to the beginning of whatever was found by the
+regular expression search for @code{sp-parstart}.
+
The full definition for the @code{forward-paragraph} function not only
-includes this code for going forwards, but also code for going backwards.
+includes code for going forwards, but also code for going backwards.
If you are reading this inside of GNU Emacs and you want to see the
whole function, you can type @kbd{C-h f} (@code{describe-function})
your sources! Without them, you are like a person who tries to drive
a car with his eyes shut!)
-@c !!! again, 21.0.100 tags table location in this paragraph
-Or -- a good habit to get into -- you can type @kbd{M-.}
-(@code{find-tag}) and the name of the function when prompted for it.
-This will take you directly to the source. If the @code{find-tag}
-function first asks you for the name of a @file{TAGS} table, give it
-the name of the @file{TAGS} file such as
-@file{/usr/local/share/emacs/21.0.100/lisp/TAGS}. (The exact path to your
-@file{TAGS} file depends on how your copy of Emacs was installed.)
-
-You can also create your own @file{TAGS} file for directories that
-lack one.
-@ifnottex
-@xref{etags, , Create Your Own @file{TAGS} File}.
-@end ifnottex
-
@node etags, Regexp Review, forward-paragraph, Regexp Search
@section Create Your Own @file{TAGS} File
@findex etags
@cindex @file{TAGS} file, create own
+Besides @kbd{C-h f} (@code{describe-function}), another way to see the
+source of a function is to type @kbd{M-.} (@code{find-tag}) and the
+name of the function when prompted for it. This is a good habit to
+get into. This will take you directly to the source. If the
+@code{find-tag} function first asks you for the name of a @file{TAGS}
+table, give it the name of a @file{TAGS} file such as
+@file{/usr/local/src/emacs/src/TAGS}. (The exact path to your
+@file{TAGS} file depends on how your copy of Emacs was installed. I
+just told you the location that provides both my C and my Emacs Lisp
+sources.)
+
+You can also create your own @file{TAGS} file for directories that
+lack one.
+
The @kbd{M-.} (@code{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 want, but do not know where it is, you can use the @code{locate}
program to attempt to find it.
-Type @w{@kbd{M-x locate RET TAGS RET}} and Emacs will list for you the
-full path names of all your @file{TAGS} files. On my system, this
-command lists 34 @file{TAGS} files. On the other hand, a `plain
-vanilla' system I recently installed did not contain any @file{TAGS}
-files.
+Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list
+for you the full path names of all your @file{TAGS} files. On my
+system, this command lists 34 @file{TAGS} files. On the other hand, a
+`plain vanilla' system I recently installed did not contain any
+@file{TAGS} files.
If the tags table you want has been created, you can use the @code{M-x
visit-tags-table} command to specify it. Otherwise, you will need to
nil
@end group
@end smallexample
+
@noindent
(The @code{insert} function inserts its arguments at point; the
@code{format} function returns a string formatted from its arguments
@enumerate
@item
A regular expression that specifies the pattern to search for.
+(Remember to put quotation marks around this argument!)
@item
Optionally, the limit of the search.
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.
-
-@item prog1
-Evaluate each argument in sequence and then return the value of the
-@emph{first}.
-
-@need 1250
-For example:
-
-@smallexample
-@group
-(prog1 1 2 3 4)
- @result{} 1
-@end group
-@end smallexample
@end table
@need 1500
@menu
* Why Count Words::
-* count-words-region:: Use a regexp, but find a problem.
-* recursive-count-words:: Start with case of no words in region.
+* count-words-region::
+* recursive-count-words::
* Counting Exercise::
@end menu
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 @code{count-words-region} command, you can,
-if you wish, count words in a whole buffer by marking it with @kbd{C-x
-h} (@code{mark-whole-buffer}).
+if you wish, count words in a whole buffer by marking it with
+@w{@kbd{C-x h}} (@code{mark-whole-buffer}).
Clearly, counting words is a repetitive act: starting from the
beginning of the region, you count the first word, then the second
or to a @code{while} loop.
@menu
-* Design count-words-region:: The definition using a @code{while} loop.
-* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}.
+* Design count-words-region::
+* Whitespace Bug::
@end menu
@node Design count-words-region, Whitespace Bug, count-words-region, count-words-region
@noindent
(Note that paired backslashes precede the @samp{w} and @samp{W}. A
-single backslash has special meaning to the Emacs Lisp interpreter. It
-indicates that the following character is interpreted differently than
-usual. For example, the two characters, @samp{\n}, stand for
+single backslash has special meaning to the Emacs Lisp interpreter.
+It indicates that the following character is interpreted differently
+than usual. For example, the two characters, @samp{\n}, stand for
@samp{newline}, rather than for a backslash followed by @samp{n}. Two
-backslashes in a row stand for an ordinary, `unspecial' backslash.)
+backslashes in a row stand for an ordinary, `unspecial' backslash,
+which in this case is followed by a letter, the combination of which
+is important to @code{re-search-forward}.)
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
@iftex
@noindent
(For information about @code{and}, see
-@ref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
-Functions}.)
+@ref{kill-new function, , The @code{kill-new} function}.)
@end iftex
@ifinfo
@noindent
-(@xref{forward-paragraph}, for information about @code{and}.)
+(@xref{kill-new function, , The @code{kill-new} function}, for
+information about @code{and}.)
@end ifinfo
The @code{re-search-forward} expression returns @code{t} if the search
succeeds and as a side effect moves point. Consequently, as words are
-found, point is moved through the region. When the search
-expression fails to find another word, or when point reaches the end
-of the region, the true-or-false-test tests false, the @code{while}
-loop exists, and the @code{count-words-region} function displays one
-or other of its messages.
+found, point is moved through the region. When the search expression
+fails to find another word, or when point reaches the end of the
+region, the true-or-false-test tests false, the @code{while} loop
+exits, and the @code{count-words-region} function displays one or
+other of its messages.
After incorporating these final changes, the @code{count-words-region}
works without bugs (or at least, without bugs that I have found!).
each word, the counting mechanism must be an expression that adds one
to the value returned by a call to @code{recursive-count-words}.
+@need 800
Consider several cases:
@itemize @bullet
@menu
* Divide and Conquer::
-* Words and Symbols:: What to count?
-* Syntax:: What constitutes a word or symbol?
-* count-words-in-defun:: Very like @code{count-words}.
-* Several defuns:: Counting several defuns in a file.
-* Find a File:: Do you want to look at a file?
-* lengths-list-file:: A list of the lengths of many definitions.
-* Several files:: Counting in definitions in different files.
-* Several files recursively:: Recursively counting in different files.
-* Prepare the data:: Prepare the data for display in a graph.
+* Words and Symbols::
+* Syntax::
+* count-words-in-defun::
+* Several defuns::
+* Find a File::
+* lengths-list-file::
+* Several files::
+* Several files recursively::
+* Prepare the data::
@end menu
@node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun
@node Several defuns, Find a File, count-words-in-defun, Words in a defun
@section Count Several @code{defuns} Within a File
-A file such as @file{simple.el} may have 80 or more function
+A file such as @file{simple.el} may have a hundred or more function
definitions within it. Our long term goal is to collect statistics on
many files, but as a first step, our immediate goal is to collect
statistics on one file.
problem.
@need 1200
-Let's look at the source for @code{find-file} (you can use the
-@code{find-tag} command or @kbd{C-h f} (@code{describe-function}) to
-find the source of a function):
+Let's look at the source for @code{find-file}:
@smallexample
@group
@end group
@end smallexample
-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, @code{find-file-noselect} and @code{switch-to-buffer}.
+@noindent
+(The most recent version of the @code{find-file} function definition
+permits you to specify optional wildcards visit multiple files; that
+makes the definition more complex and we will not discuss it here,
+since it is not relevant. You can see its source using either
+@kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
+
+@ignore
+In Emacs 22
+(defun find-file (filename &optional wildcards)
+ "Edit file FILENAME.
+Switch to a buffer visiting file FILENAME,
+creating one if none already exists.
+Interactively, the default if you just type RET is the current directory,
+but the visited file name is available through the minibuffer history:
+type M-n to pull it into the minibuffer.
+
+Interactively, or if WILDCARDS is non-nil in a call from Lisp,
+expand wildcards (if any) and visit multiple files. You can
+suppress wildcard expansion by setting `find-file-wildcards' to nil.
+
+To visit a file without any kind of conversion and without
+automatically choosing a major mode, use \\[find-file-literally]."
+ (interactive (find-file-read-args "Find file: " nil))
+ (let ((value (find-file-noselect filename nil nil wildcards)))
+ (if (listp value)
+ (mapcar 'switch-to-buffer (nreverse value))
+ (switch-to-buffer value))))
+@end ignore
+
+The definition I am showing possesses short but complete documentation
+and an interactive specification that prompts you for a file name when
+you use the command interactively. The body of the definition
+contains two functions, @code{find-file-noselect} and
+@code{switch-to-buffer}.
According to its documentation as shown by @kbd{C-h f} (the
@code{describe-function} command), the @code{find-file-noselect}
function reads the named file into a buffer and returns the buffer.
-However, the buffer is not selected. Emacs does not switch its
-attention (or yours if you are using @code{find-file-noselect}) to the
-named buffer. That is what @code{switch-to-buffer} does: it switches
-the buffer to which Emacs attention is directed; and it switches the
+(Its most recent version includes an optional wildcards argument,
+too, as well as another to read a file literally and an other you
+suppress warning messages. These optional arguments are irrelevant.)
+
+However, the @code{find-file-noselect} function does not select the
+buffer in which it puts the file. Emacs does not switch its attention
+(or yours if you are using @code{find-file-noselect}) to the named
+buffer. That is what @code{switch-to-buffer} does: it switches the
+buffer to which Emacs attention is directed; and it switches the
buffer displayed in the window to the new buffer. We have discussed
buffer switching elsewhere. (@xref{Switching Buffers}.)
So instead of calling on @code{find-file} to do the job, we must write
our own expression.
-The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
+The task is easy: use @code{find-file-noselect} and @code{set-buffer}.
@node lengths-list-file, Several files, Find a File, Words in a defun
@section @code{lengths-list-file} in Detail
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 @code{lengths-list-file} to each of the
-files.
+space inside of Emacs. My version of GNU Emacs 19 contained over 300
+source files of interest; GNU Emacs 22 contains over a thousand source
+files. Another function will apply @code{lengths-list-file} to each
+of the files.
Finally, the last expression within the @code{let} expression is the
@code{lengths-list} variable; its value is returned as the value of
place your cursor after the following expression and type @kbd{C-x
C-e} (@code{eval-last-sexp}).
-@c !!! 21.0.100 lisp sources location here
+@c !!! 22.0.100 lisp sources location here
@smallexample
(lengths-list-file
- "/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el")
+ "/usr/local/share/emacs/22.0.100/lisp/emacs-lisp/debug.el")
@end smallexample
@c was: (lengths-list-file "../lisp/debug.el")
-@c !!! as of 21, Info file is in
-@c /usr/share/info/emacs-lisp-intro.info.gz
-@c but debug.el is in /usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
+@ignore
+2006 Oct 29
+For Bob, as root,
+ gunzip /usr/local/share/emacs/22.0.50/lisp/emacs-lisp/debug.el.gz
+In GNU Emacs 22, in *info* eval
+ count-words-in-defun
+in The `count-words-in-defun' Function
+ count-words-in-defun
+in `lengths-list-file' in Detail
+then eval
+ (lengths-list-file "/usr/local/share/emacs/22.0.50/lisp/emacs-lisp/debug.el")
+@end ignore
@noindent
-(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
+(You may need to change the pathname of the file; the one here is for
+GNU Emacs version 22.0.100. To change the expression, copy it to
the @file{*scratch*} buffer and edit it.
@need 1200
@need 1200
The lengths' list for @file{debug.el} takes less than a second to
-produce and looks like this:
+produce and looks like this in GNY Emacs 22:
@smallexample
-(77 95 85 87 131 89 50 25 44 44 68 35 64 45 17 34 167 457)
+(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
@end smallexample
@need 1500
(75 41 80 62 20 45 44 68 45 12 34 235)
@end smallexample
-(The newer version of @file{debug.el} contains more defuns than the
+(The newer version of @file{debug.el} contains more defuns than the
earlier one; and my new machine is much faster than the old one.)
Note that the length of the last definition in the file is first in
either a @code{while} loop or recursion.
@menu
-* lengths-list-many-files:: Return a list of the lengths of defuns.
-* append:: Attach one list to another.
+* lengths-list-many-files::
+* append::
@end menu
@node lengths-list-many-files, append, Several files, Several files
name to the absolute, long, path name form of the directory in which
the function is called.
-@c !!! 21.0.100 lisp sources location here
+@ignore
+2006 Oct 29
+For Bob, as root,
+ gunzip /usr/local/share/emacs/22.0.50/lisp/emacs-lisp/debug.el.gz
+In GNU Emacs 22, eval
+(expand-file-name "/usr/local/share/emacs/22.0.50/lisp/emacs-lisp/debug.el")
+@end ignore
+
+@c !!! 22.0.100 lisp sources location here
@need 1500
Thus, if @code{expand-file-name} is called on @code{debug.el} when
Emacs is visiting the
-@file{/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/} directory,
+@file{/usr/local/share/emacs/22.0.100/lisp/emacs-lisp/} directory,
@smallexample
debug.el
@noindent
becomes
-@c !!! 21.0.100 lisp sources location here
+@c !!! 22.0.100 lisp sources location here
@smallexample
-/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
+/usr/local/share/emacs/22.0.100/lisp/emacs-lisp/debug.el
@end smallexample
The only other new element of this function definition is the as yet
the @file{*scratch*} buffer, edit them, and then evaluate them.
The results are shown after the @samp{@result{}}. (These results are
-for files from Emacs Version 21.0.100; files from other versions of
+for files from Emacs Version 22.0.100; files from other versions of
Emacs may produce different results.)
-@c !!! 21.0.100 lisp sources location here
+@ignore
+2006 Oct 29
+For Bob, as root,
+ gunzip /usr/local/share/emacs/22.0.50/lisp/macros.el.gz
+In GNU Emacs 22, eval
+ (lengths-list-file "/usr/local/share/emacs/22.0.50/lisp/macros.el")
+@end ignore
+
+@c !!! 22.0.100 lisp sources location here
@smallexample
@group
-(cd "/usr/local/share/emacs/21.0.100/")
+(cd "/usr/local/share/emacs/22.0.100/")
(lengths-list-file "./lisp/macros.el")
- @result{} (273 263 456 90)
+ @result{} (283 263 480 90)
@end group
+@ignore
+2006 Oct 29
+For Bob, as root,
+ gunzip /usr/local/share/emacs/22.0.50/lisp/mail/mailalias.el.gz
+In GNU Emacs 22, eval
+ (lengths-list-file "/usr/local/share/emacs/22.0.50/lisp/mail/mailalias.el")
+@end ignore
+
@group
(lengths-list-file "./lisp/mail/mailalias.el")
- @result{} (38 32 26 77 174 180 321 198 324)
+ @result{} (38 32 29 95 178 180 321 218 324)
@end group
+@ignore
+2006 Oct 29
+For Bob, as root,
+ gunzip /usr/local/share/emacs/22.0.50/lisp/makesum.el
+In GNU Emacs 22, eval
+ (lengths-list-file "/usr/local/share/emacs/22.0.50/lisp/makesum.el")
+@end ignore
+
@group
(lengths-list-file "./lisp/makesum.el")
@result{} (85 181)
@end group
+@ignore
+2006 Oct 29
+In GNU Emacs 22, eval
+(progn
+ (cd "/usr/local/share/emacs/22.0.50/")
+ (recursive-lengths-list-many-files
+ '("./lisp/macros.el"
+ "./lisp/mail/mailalias.el"
+ "./lisp/makesum.el")))
+@end ignore
+
@group
-(recursive-lengths-list-many-files
- '("./lisp/macros.el"
- "./lisp/mail/mailalias.el"
- "./lisp/makesum.el"))
- @result{} (273 263 456 90 38 32 26 77 174 180 321 198 324 85 181)
+ (recursive-lengths-list-many-files
+ '("./lisp/macros.el"
+ "./lisp/mail/mailalias.el"
+ "./lisp/makesum.el"))
+ @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
@end group
@end smallexample
that we will need.
@menu
-* Sorting:: Sorting lists.
-* Files List:: Making a list of files.
+* Sorting::
+* Files List::
* Counting function definitions::
@end menu
@code{recursive-lengths-list-many-files} function is straightforward;
it uses the @code{<} function:
+@ignore
+2006 Oct 29
+In GNU Emacs 22, eval
+(progn
+ (cd "/usr/local/share/emacs/22.0.50/")
+ (sort
+ (recursive-lengths-list-many-files
+ '("./lisp/macros.el"
+ "./lisp/mail/mailalias.el"
+ "./lisp/makesum.el"))
+ '<))
+
+@end ignore
+
@smallexample
@group
(sort
(recursive-lengths-list-many-files
- '("../lisp/macros.el"
- "../lisp/mailalias.el"
- "../lisp/makesum.el"))
+ '("./lisp/macros.el"
+ "./lisp/mailalias.el"
+ "./lisp/makesum.el"))
'<)
@end group
@end smallexample
which produces:
@smallexample
-(85 86 116 122 154 176 179 265)
+(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480)
@end smallexample
@noindent
@smallexample
@group
-("../lisp/macros.el"
- "../lisp/mail/rmail.el"
- "../lisp/makesum.el")
+("./lisp/macros.el"
+ "./lisp/mail/rmail.el"
+ "./lisp/makesum.el")
@end group
@end smallexample
element of the list is @code{t} for a directory, a string
for symbolic link (the string is the name linked to), or @code{nil}.
+@ignore
+(directory-files-and-attributes "/usr/local/src/emacs") -->
+(... ("lisp" t 21 1000 100 (17733 259) (17732 36064) (17732 36064) 12288
+"drwxr-xr-x" nil 2971606 773))
+@end ignore
+
+
For example, the first @samp{.el} file in the @file{lisp/} directory
is @file{abbrev.el}. Its name is
-@file{/usr/local/share/emacs/21.0.100/lisp/abbrev.el} and it is not a
+@file{/usr/local/share/emacs/22.0.100/lisp/abbrev.el} and it is not a
directory or a symbolic link.
@need 1000
This is how @code{directory-files-and-attributes} lists that file and
its attributes:
+@ignore
+(directory-files-and-attributes "/usr/local/src/emacs/lisp") -->
+(... ("abbrev.el" nil 1 1000 100 (17733 259) (17491 28834) (17596 62124)
+13157 "-rw-r--r--" nil 2971624 773) ...)
+@end ignore
+
@smallexample
@group
-("/usr/local/share/emacs/21.0.100/lisp/abbrev.el"
+("abbrev.el"
nil
1
1000
100
@end group
@group
-(15019 32380)
-(14883 48041)
-(15214 49336)
-11583
+(17733 259)
+(17491 28834)
+(17596 62124)
+13157
"-rw-rw-r--"
@end group
@group
-t
-341385
-776)
+nil
+2971624
+773)
@end group
@end smallexample
+@ignore
+(directory-files-and-attributes "/usr/local/src/emacs/lisp/mail/") -->
+(("." t 3 1000 100 (17733 1296) (17718 8756) (17718 8756) 4096 "drwxr-xr-x" nil 1273504 773))
+
+(directory-files-and-attributes "/usr/local/src/emacs/lisp/") -->
+(... ("mail" t 3 1000 100 (17733 1296) (17718 8756) (17718 8756) 4096
+"drwxr-xr-x" nil 1273504 773) ...)
+@end ignore
+
@need 1200
On the other hand, @file{mail/} is a directory within the @file{lisp/}
directory. The beginning of its listing looks like this:
@smallexample
@group
-("/usr/local/share/emacs/21.0.100/lisp/mail"
+("mail"
t
@dots{}
)
@end group
@end smallexample
-(Look at the documentation of @code{file-attributes} to learn about
-the different attributes. Bear in mind that the
-@code{file-attributes} function does not list the filename, so its
-first element is @code{directory-files-and-attributes}'s second
-element.)
+(To learn about the different attributes, look at the documentation of
+@code{file-attributes}. Bear in mind that the @code{file-attributes}
+function does not list the filename, so its first element is
+@code{directory-files-and-attributes}'s second element.)
We will want our new function, @code{files-in-below-directory}, to
list the @samp{.el} files in the directory it is told to check, and in
using @code{append} as the combiner.
@ignore
-(directory-files "/usr/local/share/emacs/21.0.100/lisp/" t "\\.el$")
-(shell-command "find /usr/local/share/emacs/21.0.100/lisp/ -name '*.el'")
+(directory-files "/usr/local/src/emacs/lisp/" t "\\.el$")
+(shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'")
+
+(directory-files "/usr/local/share/emacs/22.0.100/lisp/" t "\\.el$")
+(shell-command "find /usr/local/share/emacs/22.0.100/lisp/ -name '*.el'")
@end ignore
-@c /usr/local/share/emacs/21.0.100/lisp/
+@c /usr/local/share/emacs/22.0.100/lisp/
@need 800
Here is the function:
;; 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/"
+ ;; "/usr/local/share/emacs/22.0.100/lisp/"
(interactive "DDirectory name: ")
@end group
@group
@end group
@end smallexample
-@c (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
+@c (files-in-below-directory "/usr/local/src/emacs/lisp/")
+@c (files-in-below-directory "/usr/local/share/emacs/22.0.100/lisp/")
The @code{files-in-below-directory} @code{directory-files} function
takes one argument, the name of a directory.
@need 1250
Thus, on my system,
-@c !!! 21.0.100 lisp sources location here
+@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
+
+@c !!! 22.0.100 lisp sources location here
@smallexample
@group
(length
- (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/"))
+ (files-in-below-directory "/usr/local/share/emacs/22.0.100/lisp/"))
@end group
@end smallexample
@noindent
-tells me that my version 21.0.100 Lisp sources directory contains 754
-@samp{.el} files.
+tells me that my Lisp sources directory contains 1031 @samp{.el}
+files.
@code{files-in-below-directory} returns a list in reverse alphabetical
order. An expression to sort the list in alphabetical order looks
@smallexample
@group
(sort
- (files-in-below-directory "/usr/local/share/emacs/21.0.100/lisp/")
+ (files-in-below-directory "/usr/local/share/emacs/22.0.100/lisp/")
'string-lessp)
@end group
@end smallexample
@ignore
(defun test ()
- "Test how long it takes to find lengths of all elisp defuns."
+ "Test how long it takes to find lengths of all sorted elisp defuns."
(insert "\n" (current-time-string) "\n")
(sit-for 0)
(sort
(recursive-lengths-list-many-files
- '("../lisp/macros.el"
- "../lisp/mailalias.el"
- "../lisp/makesum.el"))
+ (files-in-below-directory "/usr/local/src/emacs/lisp/"))
'<)
(insert (format "%s" (current-time-string))))
-
@end ignore
@node Counting function definitions, , Files List, Prepare the data
@c colon in printed section title causes problem in Info cross reference
This way, we avoid an error.
@iftex
-@xref{forward-paragraph, , @code{forward-paragraph}: a Goldmine of
-Functions}, for more information about @code{and}.
+@noindent
+(For information about @code{and}, see
+@ref{kill-new function, , The @code{kill-new} function}.)
@end iftex
@ifinfo
-@xref{forward-paragraph}, for more information about @code{and}.
+@noindent
+(@xref{kill-new function, , The @code{kill-new} function}, for
+information about @code{and}.)
@end ifinfo
Here is a short test of the @code{defuns-per-range} function. First,
of 200 or larger.
@c The next step is to turn this numbers' list into a graph.
-
@node Readying a Graph, Emacs Initialization, Words in a defun, Top
@chapter Readying a Graph
@cindex Readying a graph
@menu
* Columns of a graph::
-* graph-body-print:: How to print the body of a graph.
+* graph-body-print::
* recursive-graph-body-print::
* Printed Axes::
* Line Graph Exercise::
own column-insertion function or discover whether one exists in Emacs.
To see whether there is one in Emacs, we can use the @kbd{M-x apropos}
-command. This command is like the @kbd{C-h a} (command-apropos)
+command. This command is like the @kbd{C-h a} (@code{command-apropos})
command, except that the latter finds only those functions that are
commands. The @kbd{M-x apropos} command lists all symbols that match
a regular expression, including functions that are not interactive.
the word `print' or the word `insert' or the word `column'.
Therefore, we can simply type @kbd{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 @code{insert-rectangle}.
+command once too takes quite some time, and then produced a list of 79
+functions and variables. Now it does not take much time at all and
+produces a list of 211 functions and variables. Scanning down the
+list, the only function that looks as if it might do the job is
+@code{insert-rectangle}.
@need 1200
Indeed, this is the function we want; its documentation says:
RECTANGLE's first line is inserted at point,
its second line is inserted at a point vertically under point, etc.
RECTANGLE should be a list of strings.
+After this command, the mark is at the upper left corner
+and point is at the lower right corner.
@end group
@end smallexample
@group
(insert-rectangle '("first" "second" "third"))first
second
- third
-nil
+ thirdnil
@end group
@end smallexample
If you are reading this in Info, you can see how this works by
switching to another buffer, such as the @file{*scratch*} buffer,
-placing point somewhere in the buffer, typing @kbd{M-:},
-typing the @code{insert-rectangle} expression into the minibuffer at
-the prompt, and then typing @key{RET}. This causes Emacs to evaluate
-the expression in the minibuffer, but to use as the value of point the
-position of point in the @file{*scratch*} buffer. (@kbd{M-:}
-is the keybinding for @code{eval-expression}.)
+placing point somewhere in the buffer, typing @kbd{M-:}, typing the
+@code{insert-rectangle} expression into the minibuffer at the prompt,
+and then typing @key{RET}. This causes Emacs to evaluate the
+expression in the minibuffer, but to use as the value of point the
+position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the
+keybinding for @code{eval-expression}. Also, @code{nil} does not
+appear in the @file{*scratch*} buffer since the expression is
+evaluated in the minibuffer.)
We find when we do this that point ends up at the end of the last
inserted line---that is to say, this function moves point as a
@menu
* Default Configuration::
-* Site-wide Init:: You can write site-wide init files.
-* defcustom:: Emacs will write code for you.
-* Beginning a .emacs File:: How to write a @code{.emacs file}.
-* Text and Auto-fill:: Automatically wrap lines.
-* Mail Aliases:: Use abbreviations for email addresses.
-* Indent Tabs Mode:: Don't use tabs with @TeX{}
-* Keybindings:: Create some personal keybindings.
-* Keymaps:: More about key binding.
-* Loading Files:: Load (i.e., evaluate) files automatically.
-* Autoload:: Make functions available.
-* Simple Extension:: Define a function; bind it to a key.
-* X11 Colors:: Colors in version 19 in X.
+* Site-wide Init::
+* defcustom::
+* Beginning a .emacs File::
+* Text and Auto-fill::
+* Mail Aliases::
+* Indent Tabs Mode::
+* Keybindings::
+* Keymaps::
+* Loading Files::
+* Autoload::
+* Simple Extension::
+* X11 Colors::
* Miscellaneous::
-* Mode Line:: How to customize your mode line.
+* Mode Line::
@end menu
@node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization
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,
+editing C code. (Enough programming languages have syntaxes
+that enable them to share or nearly share features, so C mode is
+now provided by by CC mode, the `C Collection'.)
+
+But when you do know who is going to use Emacs---you,
yourself---then it makes sense to customize Emacs.
For example, I seldom want Fundamental mode when I edit an
@noindent
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
+on its various options, such as @code{turn-on-auto-fill}, to set the
+values. After you click on the button to
@smallexample
Save for Future Sessions
@smallexample
@group
(custom-set-variables
- ;; custom-set-variables was added by Custom --
- ;; don't edit or cut/paste it!
+ ;; custom-set-variables was added by Custom.
+ ;; If you edit it by hand, you could mess it up, so be careful.
;; Your init file should contain only one such instance.
+ ;; If there is more than one, they won't work right.
'(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify))))
@end group
@end smallexample
@noindent
(The @code{text-mode-hook-identify} function tells
-@code{toggle-text-mode-auto-fill} which buffers are in Text mode.)
-
-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.
+@code{toggle-text-mode-auto-fill} which buffers are in Text mode.
+It comes on automatically.
+)
The @code{custom-set-variables} function works somewhat differently
-than a @code{setq}. While I have never learned the differences, I do
+than a @code{setq}. While I have never learned the differences, I
modify the @code{custom-set-variables} expressions in my @file{.emacs}
file by hand: I make the changes in what appears to me to be a
reasonable manner and have not had any problems. Others prefer to use
message that says
@smallexample
-this option has been changed outside the customize buffer.
+CHANGED outside Customize; operating on it here may be unreliable.
@end smallexample
@need 800
@smallexample
@group
;;; Text mode and Auto Fill mode
-; The next three lines put Emacs into Text mode
+; The next two lines put Emacs into Text mode
; and Auto Fill mode, and are for writers who
; want to start writing prose rather than code.
(setq default-major-mode 'text-mode)
-(add-hook 'text-mode-hook 'text-mode-hook-identify)
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end group
@end smallexample
else in Emacs.
@need 800
-Here are the next two lines:
+Here is the next line:
@cindex Auto Fill mode turned on
@findex add-hook
@smallexample
-(add-hook 'text-mode-hook 'text-mode-hook-identify)
(add-hook 'text-mode-hook 'turn-on-auto-fill)
@end smallexample
@noindent
-In these two lines, the @code{add-hook} command first adds
-@code{text-mode-hook-identify} to the variable called
-@code{text-mode-hook} and then adds @code{turn-on-auto-fill} to the
-variable.
+In this line, the @code{add-hook} command adds
+@code{turn-on-auto-fill} to the variable.
@code{turn-on-auto-fill} is the name of a program, that, you guessed
-it!, turns on Auto Fill mode. @code{text-mode-hook-identify} is a
-function that tells @code{toggle-text-mode-auto-fill} which buffers
-are in Text mode.
+it!, turns on Auto Fill mode.
Every time Emacs turns on Text mode, Emacs runs the commands `hooked'
onto Text mode. So every time Emacs turns on Text mode, Emacs also
turns on Auto Fill mode.
-In brief, the first line causes Emacs to enter Text mode when you edit
-a file, unless the file name extension, first non-blank line, or local
-variables tell Emacs otherwise.
+In brief, the first line causes Emacs to enter Text mode when you edit a
+file, unless the file name extension, a first non-blank line, or local
+variables to tell Emacs otherwise.
Text mode among other actions, sets the syntax table to work
conveniently for writers. In Text mode, Emacs considers an apostrophe
@samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after
the @samp{t} of @samp{it's}.
-The second 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.
+The second line causes Emacs to turn on Auto Fill mode when it turns
+on Text mode. In Auto Fill mode, Emacs automatically breaks a line
+that is too wide and brings the excessively wide part of the line down
+to the next line. Emacs breaks lines between words, not within them.
When Auto Fill mode is turned off, lines continue to the right as you
type them. Depending on how you set the value of
(defun load-library (library)
"Load the library named LIBRARY.
This is an interface to the function `load'."
- (interactive "sLoad library: ")
+ (interactive
+ (list (completing-read "Load library: "
+ 'locate-file-completion
+ (cons load-path (get-load-suffixes)))))
(load library))
@end group
@end smallexample
load that function's file with a @code{load} expression in your
@file{.emacs} file.
-In my @file{.emacs} file for Emacs version 21, I load 12 libraries
+In my @file{.emacs} file for Emacs version 22, I load 14 libraries
that contain functions that would otherwise be autoloaded. (Actually,
-it would have been better to include these files in my `dumped' Emacs
-when I built it, but I forgot. @xref{Building Emacs, , Building
-Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the @file{INSTALL}
-file for more about dumping.)
+it would have been better to include these files in my `dumped' Emacs,
+but I forgot. @xref{Building Emacs, , Building Emacs, elisp, The GNU
+Emacs Lisp Reference Manual}, and the @file{INSTALL} file for more
+about dumping.)
You may also want to include autoloaded expressions in your @file{.emacs}
file. @code{autoload} is a built-in function that takes up to five
@cindex Conditional 'twixt two versions of Emacs
@cindex Version of Emacs, choosing
@cindex Emacs version, choosing
-If you run two versions of GNU Emacs, such as versions 20 and 21, and
+If you run two versions of GNU Emacs, such as versions 21 and 22, and
use one @file{.emacs} file, you can select which code to evaluate with
the following conditional:
@smallexample
@group
(cond
- ((string-equal (number-to-string 20) (substring (emacs-version) 10 12))
- ;; evaluate version 20 code
- ( @dots{} ))
((string-equal (number-to-string 21) (substring (emacs-version) 10 12))
;; evaluate version 21 code
+ ( @dots{} ))
+ ((string-equal (number-to-string 22) (substring (emacs-version) 10 12))
+ ;; evaluate version 22 code
( @dots{} )))
@end group
@end smallexample
@smallexample
emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
+
+@exdent Or nowadays, using an even more sophisticated set of options,
+
+emacs -Q - D
@end smallexample
}:
@end smallexample
In any event, since it is not part of Emacs, I set the root color of
-my X window in my @file{~/.xinitrc} file, like this@footnote{I
-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.}:
+my X window in my @file{~/.xinitrc} file, like this@footnote{I also
+run more modern window managers, such as Enlightenment, Gnome, or KDE;
+in those cases, I often specify an image rather than a plain color.}:
@smallexample
-@group
-# I use TWM for window manager.
xsetroot -solid Navy -fg white &
-@end group
@end smallexample
@node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
@itemize @minus
@item
Set the shape and color of the mouse cursor:
+
@smallexample
@group
; Cursor shapes are defined in
@end group
@end smallexample
+@item
+Or you can set the values of a variety of features in an alist, like
+this:
+
+@smallexample
+@group
+(setq-default
+ default-frame-alist
+ '((cursor-color . "white")
+ (mouse-color . "white")
+ (foreground-color . "white")
+ (background-color . "DodgerBlue4")
+ ;; (cursor-type . bar)
+ (cursor-type . box)
+@end group
+@group
+ (tool-bar-lines . 0)
+ (menu-bar-lines . 1)
+ (width . 80)
+ (height . 58)
+ (font .
+ "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1")
+ ))
+@end group
+@end smallexample
+
@item
Convert @kbd{@key{CTL}-h} into @key{DEL} and @key{DEL}
into @kbd{@key{CTL}-h}.@*
@end group
@end smallexample
+@noindent
+or start GNU Emacs with the command @code{emacs -nbc}.
+
@item Ignore case when using `grep'@*
@samp{-n}@w{ } Prefix each line of output with line number@*
@samp{-i}@w{ } Ignore case distinctions@*
(setq grep-command "grep -n -i -e ")
@end smallexample
-@item Automatically uncompress compressed files when visiting them
+@ignore
+@c Evidently, no longer needed in GNU Emacs 22
-@smallexample
+item Automatically uncompress compressed files when visiting them
+
+smallexample
(load "uncompress")
-@end smallexample
+end smallexample
+
+@end ignore
@item Find an existing buffer, even if it has a different name@*
This avoids problems with symbolic links.
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 @code{tooltip-delay}.)
+wait seven-tenths of a second before the information appears. You can
+change that timing by changing the value of @code{tooltip-delay}.)
@need 1000
The new string format has a special syntax:
characters; this length works well in a typical 80 column wide
window.)
-@code{:eval} is a new feature in GNU Emacs version 21. It says to
+@code{:eval} was 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 @samp{.} (`period'),
In this chapter, I will walk through a short example of each.
@menu
-* debug:: How to use the built-in debugger.
-* debug-on-entry:: Start debugging when you call a function.
-* debug-on-quit:: Start debugging when you quit with @kbd{C-g}.
-* edebug:: How to use Edebug, a source level debugger.
+* debug::
+* debug-on-entry::
+* debug-on-quit::
+* edebug::
* Debugging Exercises::
@end menu
tell you what you need to know to correct the definition. The
function @code{1=} is `void'.
+@ignore
@need 800
In GNU Emacs 20 and before, you will see:
@noindent
which has the same meaning as the @file{*Backtrace*} buffer line in
version 21.
+@end ignore
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
+In this case, you need to run GNU Emacs 22, which automatically starts
the debugger that puts you in the @file{*Backtrace*} buffer; or else,
you need to start the debugger manually as described below.
@section @code{debug-on-entry}
@findex 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
+GNU Emacs 22 starts the debugger automatically when your function has
+an error.
+
+@ignore
+GNU Emacs version 20 and before did not; it simply
presented you with an error message. You had to start the debugger
manually.
+@end ignore
-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!
+Incidently, you can start the debugger manually for all versions of
+Emacs; the advantage is that the debugger runs even if you do not have
+a bug in your code. Sometimes your code will be free of bugs!
You can enter the debugger when you call the function by calling
@code{debug-on-entry}.
move point past @code{number}, you will see the following:
@smallexample
-Result: 3 = C-c
+Result: 3 (#o3, #x3, ?\C-c)
@end smallexample
@noindent
-This means the value of @code{number} is 3, which is @sc{ascii}
-`control-c' (the third letter of the alphabet, in case you need to
-know this information).
+This means the value of @code{number} is 3, which is octal three,
+hexadecimal three, and @sc{ascii} `control-c' (the third letter of the
+alphabet, in case you need to know this information).
You can continue moving through the code until you reach the line with
the error. Before evaluation, that line looks like this:
@code{count-words-region} is working.
@item
-Move point to some spot further down function and then type the
+Move point to some spot further down the function and then type the
@kbd{h} (@code{edebug-goto-here}) command to jump to that location.
@item
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 @code{find-tags}, the program
-that takes you to sources.
+documentation for all functions and variables, and @code{find-tags},
+the program that takes you to sources.
Here is an example of how I explore the sources. Because of its name,
@file{simple.el} is the file I looked at first, a long time ago. As
function, for example, looks complicated.
You may want to walk through this function slowly, as we did with the
-@code{forward-sentence} function.
-@ifnottex
-(@xref{forward-sentence}.)
-@end ifnottex
-@iftex
-(@xref{forward-sentence, , @code{forward-sentence}}.)
-@end iftex
-Or you may want to skip that function and look at another, such as
-@code{split-line}. You don't need to read all the functions.
-According to @code{count-words-in-defun}, the @code{split-line}
-function contains 27 words and symbols.
-
-Even though it is short, @code{split-line} contains four expressions
+@code{forward-sentence} function. (@xref{forward-sentence, The
+@code{forward-sentence} function}.) Or you may want to skip that
+function and look at another, such as @code{split-line}. You don't
+need to read all the functions. According to
+@code{count-words-in-defun}, the @code{split-line} function contains
+102 words and symbols.
+
+Even though it is short, @code{split-line} contains expressions
we have not studied: @code{skip-chars-forward}, @code{indent-to},
-@code{current-column} and @samp{?\n}.
+@code{current-column} and @code{insert-and-inherit}.
Consider the @code{skip-chars-forward} function. (It is part of the
function definition for @code{back-to-indentation}, which is shown in
character codes; and it shows how to create a temporary buffer.
(The @code{indent-to} function is written in C rather than Emacs Lisp;
-it is a `built-in' function. @code{help-follow} only provides you
-with the documentation of a built-in function; it does not take you to
-the source. But @code{find-tag} will take you to the source, if
-properly set up.)
+it is a `built-in' function. @code{help-follow} takes you to its
+source as does @code{find-tag}, when properly set up.)
You can look at a function's source using @code{find-tag}, which is
bound to @kbd{M-.} Finally, you can find out what the Reference
Manual has to say by visiting the manual in Info, and typing @kbd{i}
-(@code{Info-index}) and the name of the function, or by looking up
-@code{skip-chars-forward} in the index to a printed copy of the
-manual.
-
-Similarly, you can find out what is meant by @samp{?\n}. You can try
-using @code{Info-index} with @samp{?\n}. It turns out that this
-action won't help; but don't give up. If you search the index for
-@samp{\n} without the @samp{?}, you will be taken directly to the
-relevant section of the manual. (@xref{Character Type, , Character
-Type, elisp, The GNU Emacs Lisp Reference Manual}. @samp{?\n} stands
-for the newline character.)
+(@code{Info-index}) and the name of the function, or by looking up the
+function in the index to a printed copy of the manual.
+
+Similarly, you can find out what is meant by
+@code{insert-and-inherit}.
Other interesting source files include @file{paragraphs.el},
@file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
@end group
@end smallexample
-@sp 1
-Here is test text:
+@sp 1
+Here is test text:
+
+@smallexample
+@group
+one two two three four five
+five six seven
+@end group
+@end smallexample
+
+You can substitute the other regular expressions shown above in the
+function definition and try each of them on this list.
+
+@c done til here 2006 Oct 29
+
+@ignore
+
+
+
+@end ignore
+
+
+@ignore
+as of GNU Emacs 22, this no longer seems to be the case
+with yank yank-pop
+
+guts of rotate-yank-pointer moved to current-kill
+in simple.el
+
+(defun current-kill (n &optional do-not-move)
+ "Rotate the yanking point by N places, and then return that kill.
+
+critical part is:
+
+ (let ((ARGth-kill-element
+ (nthcdr (mod (- n (length kill-ring-yank-pointer))
+ (length kill-ring))
+ kill-ring)))
+ (or do-not-move
+ (setq kill-ring-yank-pointer ARGth-kill-element))
+ (car ARGth-kill-element))
+
+
+
+ (mod X Y)
+ Return X modulo Y.
+
+ (% X Y)
+ Return remainder of X divided by Y.
+
+ (mod 12 3) 0 (#o0, #x0, ?\C-@)
+ (mod 4 3) 1
+ (mod 13 3) 1
+
+ (% 12 3) 0
+ (% 4 3) 1
+ (% 13 3) 1
+
+ mod returns the value of DIVIDEND modulo DIVISOR; in
+ other words, the remainder after division of DIVIDEND by DIVISOR,
+ but with the same sign as DIVISOR. The arguments must be numbers
+ or markers.
+
+ Unlike `%', `mod' returns a well-defined result for negative
+ arguments. It also permits floating point arguments; it rounds the
+ quotient downward (towards minus infinity) to an integer, and uses
+ that quotient to compute the remainder.
+
+ % returns the integer remainder after division of
+ DIVIDEND by DIVISOR. The arguments must be integers or markers.
+
+ For negative arguments, the remainder is in principle
+ machine-dependent since the quotient is; but in practice, all
+ known machines behave alike.
+
+
+
+rotate-yank-pointer has
+
+reformatted:
+ (let ((length (length kill-ring)))
+ ...
+ (setq kill-ring-yank-pointer
+ (nthcdr (% (+ arg
+ (- length (length kill-ring-yank-pointer)))
+ length)
+ kill-ring)))))
+
+originally
+ (setq kill-ring-yank-pointer
+ (nthcdr (% (+ arg
+ (- length
+ (length
+ kill-ring-yank-pointer)))
+ length)
+ kill-ring)))))
+
+
+
+
+
+
+/usr/local/src/emacs/lisp/ChangeLog.3
+1992-05-21 Jim Blandy (jimb@pogo.cs.oberlin.edu)
+simple.el
+ (yank-pop): Use current-kill, rather than assuming that
+ kill-ring-yank-pointer points to the text you should use.
+ (yank): Use current-kill, instead of calling rotate-yank-pointer
+ and then fetching through the kill-ring-yank-pointer.
+
+@end ignore
+
+@node Kill Ring, Full Graph, the-the, Top
+@appendix Handling the Kill Ring
+@cindex Kill ring handling
+@cindex Handling the kill ring
+@cindex Ring, making a list like a
+
+The kill ring is a list that is transformed into a ring by the
+workings of the @code{current-kill} function. The @code{yank} and
+@code{yank-pop} commands use the @code{current-kill} function.
+
+This appendix describes the @code{current-kill} function as well as
+both the @code{yank} and the @code{yank-pop} commands, but first,
+consider the workings of the kill ring.
+
+@need 1250
+The kill ring has a default maximum length of sixty items; this number
+is too large for an explanation. Instead, set it to four. Please
+evaluate the following:
+
+@smallexample
+@group
+(setq old-kill-ring-max kill-ring-max)
+(setq kill-ring-max 4)
+@end group
+@end smallexample
+
+@noindent
+Then, please copy each line of the following indented example into the
+kill ring. You may kill each line with @kbd{C-k} or mark it and copy
+it with @kbd{M-w}.
+
+@noindent
+(In a read-only buffer, such as the @file{*info*} buffer, the kill
+command, @kbd{C-k} (@code{kill-line}), will not remove the text,
+merely copy it to the kill ring. However, your machine may beep at
+you. Alternatively, for silence, you may copy the region of each line
+with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark
+each line for this command to succeed, but it does not matter at which
+end you put point or mark.)
+
+@need 1250
+@noindent
+Please invoke the calls in order, so that five elements attempt to
+fill the kill ring:
+
+@smallexample
+@group
+first some text
+second piece of text
+third line
+fourth line of text
+fifth bit of text
+@end group
+@end smallexample
+
+@need 1250
+@noindent
+Then find the value of @code{kill-ring} by evaluating
+
+@smallexample
+kill-ring
+@end smallexample
+
+@need 800
+@noindent
+It is:
@smallexample
@group
-one two two three four five
-five six seven
+("fifth bit of text" "fourth line of text"
+"third line" "second piece of text")
@end group
@end smallexample
-You can substitute the other regular expressions shown above in the
-function definition and try each of them on this list.
+@noindent
+The first element, @samp{first some text}, was dropped.
-@node Kill Ring, Full Graph, the-the, Top
-@appendix Handling the Kill Ring
-@cindex Kill ring handling
-@cindex Handling the kill ring
-@cindex Ring, making a list like a
+@need 1250
+To return to the old value for the length of the kill ring, evaluate:
-The kill ring is a list that is transformed into a ring by the
-workings of the @code{rotate-yank-pointer} function. The @code{yank}
-and @code{yank-pop} commands use the @code{rotate-yank-pointer}
-function. This appendix describes the @code{rotate-yank-pointer}
-function as well as both the @code{yank} and the @code{yank-pop}
-commands.
+@smallexample
+(setq kill-ring-max old-kill-ring-max)
+@end smallexample
@menu
-* rotate-yank-pointer:: Move a pointer along a list and around.
-* yank:: Paste a copy of a clipped element.
-* yank-pop:: Insert first element pointed to.
+* current-kill::
+* yank::
+* yank-pop::
* ring file::
@end menu
-@node rotate-yank-pointer, yank, Kill Ring, Kill Ring
+@node current-kill, yank, Kill Ring, Kill Ring
@comment node-name, next, previous, up
-@appendixsec The @code{rotate-yank-pointer} Function
-@findex rotate-yank-pointer
+@appendixsec The @code{current-kill} Function
+@findex current-kill
-The @code{rotate-yank-pointer} function changes the element in the kill
-ring to which @code{kill-ring-yank-pointer} points. For example, it can
-change @code{kill-ring-yank-pointer} from pointing to the second
-element to point to the third element.
+The @code{current-kill} function changes the element in the kill ring
+to which @code{kill-ring-yank-pointer} points. (Also, the
+@code{kill-new} function sets @code{kill-ring-yank-pointer} to point
+to the latest element of the the kill ring.)
-@need 800
-Here is the code for @code{rotate-yank-pointer}:
+@need 1500
+The @code{current-kill} function is used by @code{yank} and by
+@code{yank-pop}. Here is the code for @code{current-kill}:
@smallexample
@group
-(defun rotate-yank-pointer (arg)
- "Rotate the yanking point in the kill ring."
- (interactive "p")
- (let ((length (length kill-ring)))
+(defun current-kill (n &optional do-not-move)
+ "Rotate the yanking point by N places, and then return that kill.
+If N is zero, `interprogram-paste-function' is set, and calling it
+returns a string, then that string is added to the front of the
+kill ring and returned as the latest kill.
@end group
@group
- (if (zerop length)
- ;; @r{then-part}
- (error "Kill ring is empty")
+If optional arg DO-NOT-MOVE is non-nil, then don't actually move the
+yanking point; just return the Nth kill forward."
+ (let ((interprogram-paste (and (= n 0)
+ interprogram-paste-function
+ (funcall interprogram-paste-function))))
@end group
@group
- ;; @r{else-part}
- (setq kill-ring-yank-pointer
- (nthcdr (% (+ arg
- (- length
- (length
- kill-ring-yank-pointer)))
- length)
- kill-ring)))))
+ (if interprogram-paste
+ (progn
+ ;; Disable the interprogram cut function when we add the new
+ ;; text to the kill ring, so Emacs doesn't try to own the
+ ;; selection, with identical text.
+ (let ((interprogram-cut-function nil))
+ (kill-new interprogram-paste))
+ interprogram-paste)
+@end group
+@group
+ (or kill-ring (error "Kill ring is empty"))
+ (let ((ARGth-kill-element
+ (nthcdr (mod (- n (length kill-ring-yank-pointer))
+ (length kill-ring))
+ kill-ring)))
+ (or do-not-move
+ (setq kill-ring-yank-pointer ARGth-kill-element))
+ (car ARGth-kill-element)))))
@end group
@end smallexample
+In addition, the @code{kill-new} function sets
+@code{kill-ring-yank-pointer} to the latest element of the the kill
+ring. And indirectly so does @code{kill-append}, since it calls
+@code{kill-new}. In addition, @code{kill-region} and @code{kill-line}
+call the @code{kill-new} function.
+
+@need 1500
+Here is the line in @code{kill-new}, which is explained in
+@ref{kill-new function, , The @code{kill-new} function}.
+
+@smallexample
+(setq kill-ring-yank-pointer kill-ring)
+@end smallexample
+
@menu
-* Understanding rotate-yk-ptr::
-* rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}.
+* Understanding current-kill::
@end menu
-@node Understanding rotate-yk-ptr, rotate-yk-ptr body, rotate-yank-pointer, rotate-yank-pointer
+@node Understanding current-kill, , current-kill, current-kill
@ifnottex
-@unnumberedsubsec @code{rotate-yank-pointer} in Outline
+@unnumberedsubsec @code{current-kill} in Outline
@end ifnottex
-The @code{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:
+The @code{current-kill} function looks complex, but as usual, it can
+be understood by taking it apart piece by piece. First look at it in
+skeletal form:
@smallexample
@group
-(defun rotate-yank-pointer (arg)
- "Rotate the yanking point in the kill ring."
- (interactive "p")
+(defun current-kill (n &optional do-not-move)
+ "Rotate the yanking point by N places, and then return that kill.
(let @var{varlist}
@var{body}@dots{})
@end group
@end smallexample
-This function takes one argument, called @code{arg}. It has a brief
-documentation string; and it is interactive with a small @samp{p}, which
-means that the argument must be a processed prefix passed to the
-function as a number.
+This function takes two arguments, one of which is optional. It has a
+documentation string. It is @emph{not} interactive.
The body of the function definition is a @code{let} expression, which
itself has a body as well as a @var{varlist}.
The @code{let} expression declares a variable that will be only usable
within the bounds of this function. This variable is called
-@code{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
-@code{length}. (Note that this function has the same name as the
-variable called @code{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 @samp{ship} when he says: "I must ship this package
-immediately." and "I must get aboard the ship immediately.")
-
-The function @code{length} tells the number of items there are in a list,
-so @code{(length kill-ring)} returns the number of items there are in the
-kill ring.
+@code{interprogram-paste} and is for copying to another program. It
+is not for copying within this instance of GNU Emacs. Most window
+systems provide a facility for interprogram pasting. Sadly, that
+facility usually provides only for the lasted element. Most windowing
+systems have not adopted a ring of many possiblities, even though
+Emacs has provided it for decades.
-@node rotate-yk-ptr body, , Understanding rotate-yk-ptr, rotate-yank-pointer
-@comment node-name, next, previous, up
-@appendixsubsec The Body of @code{rotate-yank-pointer}
+The @code{if} expression has two parts, one if there exists
+@code{interprogram-paste} and one if not.
-The body of @code{rotate-yank-pointer} is a @code{let} expression and
-the body of the @code{let} expression is an @code{if} expression.
+@need 2000
+Let us consider the `if not' or else-part of the @code{current-kill}
+function. (The then-part uses the the @code{kill-new} function, which
+we have already described. (@xref{kill-new function, , The
+@code{kill-new} function}.)
+
+@smallexample
+@group
+(or kill-ring (error "Kill ring is empty"))
+(let ((ARGth-kill-element
+ (nthcdr (mod (- n (length kill-ring-yank-pointer))
+ (length kill-ring))
+ kill-ring)))
+ (or do-not-move
+ (setq kill-ring-yank-pointer ARGth-kill-element))
+ (car ARGth-kill-element))
+@end group
+@end smallexample
-The purpose of the @code{if} expression is to find out whether there is
-anything in the kill ring. If the kill ring is empty, the @code{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.
+@noindent
+The code first checks whether the kill ring has content; otherwise it
+signals an error.
-Here is the if-part and then-part of the @code{if} expression:
+@need 1000
+Note that the @code{or} expression is very similar to writing
@findex zerop
@findex error
@smallexample
@group
-(if (zerop length) ; @r{if-part}
- (error "Kill ring is empty") ; @r{then-part}
- @dots{}
+(if (zerop (length kill-ring)) ; @r{if-part}
+ (error "Kill ring is empty")) ; @r{then-part}
+ ;; No else-part
@end group
@end smallexample
@noindent
If there is not anything in the kill ring, its length must be zero and
an error message sent to the user: @samp{Kill ring is empty}. The
-@code{if} expression uses the function @code{zerop} which returns true
-if the value it is testing is zero. When @code{zerop} tests true, the
-then-part of the @code{if} is evaluated. The then-part is a list
-starting with the function @code{error}, which is a function that is
-similar to the @code{message} function (@pxref{message}), in that it
-prints a one-line message in the echo area. However, in addition to
-printing a message, @code{error} also stops evaluation of the function
-within which it is embedded. This means that the rest of the function
-will not be evaluated if the length of the kill ring is zero.
+@code{current-kill} function uses an @code{or} expression which is
+simpler. But an @code{if} expression reminds us what goes on.
+
+This @code{if} expression uses the function @code{zerop} which returns
+true if the value it is testing is zero. When @code{zerop} tests
+true, the then-part of the @code{if} is evaluated. The then-part is a
+list starting with the function @code{error}, which is a function that
+is similar to the @code{message} function
+(@pxref{message, , The @code{message} Function}), in that
+it prints a one-line message in the echo area. However, in addition
+to printing a message, @code{error} also stops evaluation of the
+function within which it is embedded. This means that the rest of the
+function will not be evaluated if the length of the kill ring is zero.
+
+Then the @code{current-kill} function selects the element to return.
+The selection depends on the number of places that @code{current-kill}
+rotates and on where @code{kill-ring-yank-pointer} points.
+
+Next, either the optional @code{do-not-move} argument is true or the
+current value of @code{kill-ring-yank-pointer} is set to point to the
+list, the first element of which is returned even if the
+@code{do-not-move} argument is true.
+
@menu
-* Digression concerning error:: How to mislead humans, but not computers.
-* rotate-yk-ptr else-part:: The else-part of the @code{if} expression.
-* Remainder Function:: The remainder, @code{%}, function.
-* rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}.
-* kill-rng-yk-ptr last elt:: Pointing to the last element.
+* Digression concerning error::
+* Determining the Element ::
@end menu
-@node Digression concerning error, rotate-yk-ptr else-part, rotate-yk-ptr body, rotate-yk-ptr body
+@node Digression concerning error, Determining the Element , Understanding current-kill, Understanding current-kill
@ifnottex
@unnumberedsubsubsec Digression about the word `error'
@end ifnottex
-(In my opinion, it is slightly misleading, at least to humans, to use
+In my opinion, it is slightly misleading, at least to humans, to use
the term `error' as the name of the @code{error} function. A better
term would be `cancel'. Strictly speaking, of course, you cannot
point to, much less rotate a pointer to a list that has no length, so
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.)
-
-@node rotate-yk-ptr else-part, Remainder Function, Digression concerning error, rotate-yk-ptr body
-@unnumberedsubsubsec The else-part of the @code{if} expression
-
-The else-part of the @code{if} expression is dedicated to setting the
-value of @code{kill-ring-yank-pointer} when the kill ring has something
-in it. The code looks like this:
-
-@smallexample
-@group
-(setq kill-ring-yank-pointer
- (nthcdr (% (+ arg
- (- length
- (length kill-ring-yank-pointer)))
- length)
- kill-ring)))))
-@end group
-@end smallexample
-
-This needs some examination. Clearly, @code{kill-ring-yank-pointer}
-is being set to be equal to some @sc{cdr} of the kill ring, using the
-@code{nthcdr} function that is described in an earlier section.
-(@xref{copy-region-as-kill}.) But exactly how does it do this?
-
-Before looking at the details of the code let's first consider the
-purpose of the @code{rotate-yank-pointer} function.
-
-The @code{rotate-yank-pointer} function changes what
-@code{kill-ring-yank-pointer} points to. If
-@code{kill-ring-yank-pointer} starts by pointing to the first element
-of a list, a call to @code{rotate-yank-pointer} causes it to point to
-the second element; and if @code{kill-ring-yank-pointer} points to the
-second element, a call to @code{rotate-yank-pointer} causes it to
-point to the third element. (And if @code{rotate-yank-pointer} is
-given an argument greater than 1, it jumps the pointer that many
-elements.)
-
-The @code{rotate-yank-pointer} function uses @code{setq} to reset what
-the @code{kill-ring-yank-pointer} points to. If
-@code{kill-ring-yank-pointer} points to the first element of the kill
-ring, then, in the simplest case, the @code{rotate-yank-pointer}
-function must cause it to point to the second element. Put another
-way, @code{kill-ring-yank-pointer} must be reset to have a value equal
-to the @sc{cdr} of the kill ring.
+`cancel' would have a clearer connotation.
-@need 1250
-That is, under these circumstances,
-
-@smallexample
-@group
-(setq kill-ring-yank-pointer
- ("some text" "a different piece of text" "yet more text"))
+@node Determining the Element , , Digression concerning error, Understanding current-kill
+@ifnottex
+@unnumberedsubsubsec Determining the Element
+@end ifnottex
-(setq kill-ring
- ("some text" "a different piece of text" "yet more text"))
-@end group
-@end smallexample
+Among other actions, the else-part of the @code{if} expression sets
+the value of @code{kill-ring-yank-pointer} to
+@code{ARGth-kill-element} when the kill ring has something in it and
+the value of @code{do-not-move} is @code{nil}.
@need 800
-@noindent
-the code should do this:
-
-@smallexample
-(setq kill-ring-yank-pointer (cdr kill-ring))
-@end smallexample
-
-@need 1000
-@noindent
-As a result, the @code{kill-ring-yank-pointer} will look like this:
+The code looks like this:
@smallexample
@group
-kill-ring-yank-pointer
- @result{} ("a different piece of text" "yet more text"))
+(nthcdr (mod (- n (length kill-ring-yank-pointer))
+ (length kill-ring))
+ kill-ring)))
@end group
@end smallexample
-The actual @code{setq} expression uses the @code{nthcdr} function to do
-the job.
+This needs some examination. Unless it is not supposed to move the
+pointer, the @code{current-kill} function changes where
+@code{kill-ring-yank-pointer} points.
+That is what the
+@w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}}
+expression does. Also, clearly, @code{ARGth-kill-element} is being
+set to be equal to some @sc{cdr} of the kill ring, using the
+@code{nthcdr} function that is described in an earlier section.
+(@xref{copy-region-as-kill}.) How does it do this?
As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function
works by repeatedly taking the @sc{cdr} of a list---it takes the
@end group
@end smallexample
-In the @code{rotate-yank-pointer} function, however, the first
-argument to @code{nthcdr} is a rather complex looking expression with
-lots of arithmetic inside of it:
-
-@smallexample
-@group
-(% (+ arg
- (- length
- (length kill-ring-yank-pointer)))
- length)
-@end group
-@end smallexample
+However, the @code{nthcdr} expression is more complicated. It uses
+the @code{mod} function to determine which @sc{cdr} to select.
-As usual, we need to look at the most deeply embedded expression first
-and then work our way towards the light.
+(You will remember to look at inner functions first; indeed, we will
+have to go inside the @code{mod}.)
-The most deeply embedded expression is @code{(length
-kill-ring-yank-pointer)}. This finds the length of the current value of
-the @code{kill-ring-yank-pointer}. (Remember that the
-@code{kill-ring-yank-pointer} is the name of a variable whose value is a
-list.)
+The @code{mod} function returns the value of its first argument modulo
+the second; that is to say, it returns the remainder after dividing
+the first argument by the second. The value returned has the same
+sign as the second argument.
@need 800
-The measurement of the length is inside the expression:
-
-@smallexample
-(- length (length kill-ring-yank-pointer))
-@end smallexample
-
-@noindent
-In this expression, the first @code{length} is the variable that was
-assigned the length of the kill ring in the @code{let} statement at the
-beginning of the function. (One might think this function would be
-clearer if the variable @code{length} were named
-@code{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 @code{length} is not a bother, unless you are pulling the
-function apart into very tiny pieces as we are doing here.)
-
-So the line @code{(- 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 @code{kill-ring-yank-pointer}.
-
-To see how all this fits into the @code{rotate-yank-pointer}
-function, let's begin by analyzing the case where
-@code{kill-ring-yank-pointer} points to the first element of the kill
-ring, just as @code{kill-ring} does, and see what happens when
-@code{rotate-yank-pointer} is called with an argument of 1.
-
-The variable @code{length} and the value of the expression
-@code{(length kill-ring-yank-pointer)} will be the same since the
-variable @code{length} is the length of the kill ring and the
-@code{kill-ring-yank-pointer} is pointing to the whole kill ring.
-Consequently, the value of
-
-@smallexample
-(- length (length kill-ring-yank-pointer))
-@end smallexample
-
-@noindent
-will be zero. Since the value of @code{arg} will be 1, this will mean
-that the value of the whole expression
-
-@smallexample
-(+ arg (- length (length kill-ring-yank-pointer)))
-@end smallexample
-
-@noindent
-will be 1.
-
-@need 1200
-Consequently, the argument to @code{nthcdr} will be found as the result of
-the expression
-
-@smallexample
-(% 1 length)
-@end smallexample
-
-@node Remainder Function, rotate-yk-ptr remainder, rotate-yk-ptr else-part, rotate-yk-ptr body
-@unnumberedsubsubsec The @code{%} remainder function
-
-To understand @code{(% 1 length)}, we need to understand @code{%}.
-According to its documentation (which I just found by typing @kbd{C-h
-f @kbd{%} @key{RET}}), the @code{%} 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:
-
-@itemize @bullet
-@item
-5 divided by 5 is 1 with a remainder of 0;
-
-@item
-6 divided by 5 is 1 with a remainder of 1;
-
-@item
-7 divided by 5 is 1 with a remainder of 2.
-
-@item
-Similarly, 10 divided by 5 is 2 with a remainder of 0;
-
-@item
-11 divided by 5 is 2 with a remainder of 1;
-
-@item
-12 divided by 5 is 1 with a remainder of 2.
-@end itemize
-
-@need 1250
-@noindent
-By considering the cases as parallel, we can see that
-
-@itemize @bullet
-@item
-zero divided by 5 must be zero with a remainder of zero;
-
-@item
-1 divided by 5 must be zero with a remainder of 1;
-
-@item
-2 divided by 5 must be zero with a remainder of 2;
-@end itemize
-
-@noindent
-and so on.
-
-@need 1250
-So, in this code, if the value of @code{length} is 5, then the result of
-evaluating
-
-@smallexample
-(% 1 5)
-@end smallexample
-
-@noindent
-is 1. (I just checked this by placing the cursor after the expression
-and typing @kbd{C-x C-e}. Indeed, 1 is printed in the echo area.)
-
-@need 2000
-@node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body
-@unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer}
-
-When the @code{kill-ring-yank-pointer} points to the
-beginning of the kill ring, and the argument passed to
-@code{rotate-yank-pointer} is 1, the @code{%} expression returns 1:
+Thus,
@smallexample
@group
-(- length (length kill-ring-yank-pointer))
- @result{} 0
+(mod 12 4)
+ @result{} 0 ;; @r{because there is no remainder}
+(mod 13 4)
+ @result{} 1
@end group
@end smallexample
@need 1250
-@noindent
-therefore,
+In this case, the first argument is often smaller than the second.
+That is fine.
@smallexample
@group
-(+ arg (- length (length kill-ring-yank-pointer)))
- @result{} 1
+(mod 0 4)
+ @result{} 0
+(mod 1 4)
+ @result{} 1
@end group
@end smallexample
-@need 1250
-@noindent
-and consequently:
-
-@smallexample
-@group
-(% (+ arg (- length (length kill-ring-yank-pointer)))
- length)
- @result{} 1
-@end group
-@end smallexample
+We can guess what the @code{-} function does. It is like @code{+} but
+substracts instead of adds; the @code{-} function subtracts its second
+argument from its first. Also, we already know what the @code{length}
+function does (@pxref{length}). It returns the length of a list.
-@noindent
-regardless of the value of @code{length}.
+And @code{n} is the name of the required argument to the
+@code{current-kill} function.
@need 1250
-@noindent
-As a result of this, the @code{setq kill-ring-yank-pointer} expression
-simplifies to:
-
-@smallexample
-(setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
-@end smallexample
-
-@noindent
-What it does is now easy to understand. Instead of pointing as it did
-to the first element of the kill ring, the
-@code{kill-ring-yank-pointer} is set to point to the second element.
-
-Clearly, if the argument passed to @code{rotate-yank-pointer} is two, then
-the @code{kill-ring-yank-pointer} is set to @code{(nthcdr 2 kill-ring)};
-and so on for different values of the argument.
-
-Similarly, if the @code{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 @code{(% (+ arg 1) length)}. This means that
-the @code{kill-ring-yank-pointer} is moved from the second element of
-the kill ring to the third element if the argument passed to
-@code{rotate-yank-pointer} is 1.
-
-@node kill-rng-yk-ptr last elt, , rotate-yk-ptr remainder, rotate-yk-ptr body
-@unnumberedsubsubsec Pointing to the last element
-
-The final question is, what happens if the @code{kill-ring-yank-pointer}
-is set to the @emph{last} element of the kill ring? Will a call to
-@code{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 @code{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 @code{rotate-yank-pointer} is 1.
-When the @code{kill-ring-yank-pointer} points to the last element of
-the kill ring, its length is 1. The code looks like this:
+So when the first argument to @code{nthcdr} is zero, the @code{nthcdr}
+expression returns the whole list, as you can see by evaluating the
+following:
@smallexample
-(% (+ arg (- length (length kill-ring-yank-pointer))) length)
+@group
+;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four}
+(nthcdr (mod (- 0 4) 4) ; (mod -4 4) @result{} 0
+ '("fourth line of text"
+ "third line"
+ "second piece of text"
+ "first some text"))
+@end group
@end smallexample
@need 1250
-When the variables are replaced by their numeric values, the expression
-looks like this:
-
-@smallexample
-(% (+ 1 (- 5 1)) 5)
-@end smallexample
-
-@noindent
-This expression can be evaluated by looking at the most embedded inner
-expression first and working outwards: The value of @code{(- 5 1)} is 4;
-the sum of @code{(+ 1 4)} is 5; and the remainder of dividing 5 by 5 is
-zero. So what @code{rotate-yank-pointer} will do is
+When the first argument to the @code{current-kill} function is one,
+the @code{nthcdr} expression returns the list without its first
+element.
@smallexample
-(setq kill-ring-yank-pointer (nthcdr 0 kill-ring))
+@group
+(nthcdr (mod (- 1 4) 4)
+ '("fourth line of text"
+ "third line"
+ "second piece of text"
+ "first some text"))
+@end group
@end smallexample
-@noindent
-which will set the @code{kill-ring-yank-pointer} to point to the beginning
-of the kill ring.
-
-So what happens with successive calls to @code{rotate-yank-pointer} is that
-it moves the @code{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?)
+@cindex @samp{global variable} defined
+@cindex @samp{variable, global}, defined
+Incidently, both @code{kill-ring} and @code{kill-ring-yank-pointer}
+are @dfn{global variables}. That means that any expression in Emacs
+Lisp can access them. They are not like the local variables set by
+@code{let} (@pxref{Prevent confusion}) or like the symbols in an
+argument list (@pxref{defun, , The @code{defun} Special Form}). Local
+variables can only be accessed within the @code{let} that defines them
+or the function that specifies them in an argument list (and within
+expressions called by them).
-@node yank, yank-pop, rotate-yank-pointer, Kill Ring
+@node yank, yank-pop, current-kill, Kill Ring
@comment node-name, next, previous, up
@appendixsec @code{yank}
@findex yank
-After learning about @code{rotate-yank-pointer}, the code for the
+After learning about @code{current-kill}, the code for the
@code{yank} function is almost easy. It has only one tricky part, which is
the computation of the argument to be passed to @code{rotate-yank-pointer}.
@need 1250
The code looks like this:
+@c in GNU Emacs 22
@smallexample
@group
(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.
+ "Reinsert (\"paste\") the last stretch of killed text.
+More precisely, reinsert the stretch of killed text most recently
+killed OR yanked. Put point at end, and set mark at beginning.
+With just \\[universal-argument] as argument, same but put point at
+beginning (and mark at end). With argument N, reinsert the Nth most
+recently killed stretch of killed text.
+
+When this command inserts killed text into the buffer, it honors
+`yank-excluded-properties' and `yank-handler' as described in the
+doc string for `insert-for-yank-1', which see.
+
See also the command \\[yank-pop]."
@end group
@group
-
(interactive "*P")
- (rotate-yank-pointer (if (listp arg) 0
- (if (eq arg '-) -1
- (1- arg))))
+ (setq yank-window-start (window-start))
+ ;; If we don't get all the way thru, make last-command indicate that
+ ;; for the following command.
+ (setq this-command t)
(push-mark (point))
- (insert (car kill-ring-yank-pointer))
- (if (consp arg)
- (exchange-point-and-mark)))
@end group
-@end smallexample
-
-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 @sc{car}) of what the @code{kill-ring-yank-pointer} points to is
-inserted; and then, if the argument passed the function is a
-@code{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
-@code{"*P"}. This means it will not work on a read-only buffer, and that
-the unprocessed prefix argument is passed to the function.
-
-@menu
-* rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}.
-* rotate-yk-ptr negative arg:: Pass a negative argument.
-@end menu
-
-@node rotate-yk-ptr arg, rotate-yk-ptr negative arg, yank, yank
-@unnumberedsubsubsec Passing the argument
-
-The hard part of @code{yank} is understanding the computation that
-determines the value of the argument passed to
-@code{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
-@code{if} expressions will be a number and that number will be the
-argument passed to @code{rotate-yank-pointer}.
-
-@need 1250
-Laid out with comments, the code looks like this:
-
-@smallexample
@group
-(if (listp arg) ; @r{if-part}
- 0 ; @r{then-part}
- (if (eq arg '-) ; @r{else-part, inner if}
- -1 ; @r{inner if's then-part}
- (1- arg)))) ; @r{inner if's else-part}
+ (insert-for-yank (current-kill (cond
+ ((listp arg) 0)
+ ((eq arg '-) -2)
+ (t (1- arg)))))
+ (if (consp arg)
+ ;; This is like exchange-point-and-mark,
+ ;; but doesn't activate the mark.
+ ;; It is cleaner to avoid activation, even though the command
+ ;; loop would deactivate the mark because we inserted text.
+ (goto-char (prog1 (mark t)
+ (set-marker (mark-marker) (point) (current-buffer)))))
@end group
-@end smallexample
-
-@noindent
-This code consists of two @code{if} expression, one the else-part of
-the other.
-
-The first or outer @code{if} expression tests whether the argument
-passed to @code{yank} is a list. Oddly enough, this will be true if
-@code{yank} is called without an argument---because then it will be
-passed the value of @code{nil} for the optional argument and an
-evaluation of @code{(listp nil)} returns true! So, if no argument is
-passed to @code{yank}, the argument passed to
-@code{rotate-yank-pointer} inside of @code{yank} is zero. This means
-the pointer is not moved and the first element to which
-@code{kill-ring-yank-pointer} points is inserted, as we expect.
-Similarly, if the argument for @code{yank} is @kbd{C-u}, this will be
-read as a list, so again, a zero will be passed to
-@code{rotate-yank-pointer}. (@kbd{C-u} produces an unprocessed prefix
-argument of @code{(4)}, which is a list of one element.) At the same
-time, later in the function, this argument will be read as a
-@code{cons} so point will be put in the front and mark at the end of
-the insertion. (The @code{P} argument to @code{interactive} is
-designed to provide these values for the case when an optional
-argument is not provided or when it is @kbd{C-u}.)
-
-The then-part of the outer @code{if} expression handles the case when
-there is no argument or when it is @kbd{C-u}. The else-part handles the
-other situations. The else-part is itself another @code{if} expression.
-
-The inner @code{if} expression tests whether the argument is a minus
-sign. (This is done by pressing the @key{META} and @kbd{-} keys at the
-same time, or the @key{ESC} key and then the @kbd{-} key). In this
-case, the @code{rotate-yank-pointer} function is passed @kbd{-1} as an
-argument. This moves the @code{kill-ring-yank-pointer} backwards, which
-is what is desired.
-
-If the true-or-false-test of the inner @code{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 @code{(1- arg)}.
-Because of the two @code{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 @code{(1- arg)} does is decrement
-the number and return it. (The @code{1-} function subtracts one from
-its argument.) This means that if the argument to
-@code{rotate-yank-pointer} is 1, it is reduced to zero, which means
-the first element to which @code{kill-ring-yank-pointer} points is
-yanked back, as you would expect.
-
-@node rotate-yk-ptr negative arg, , rotate-yk-ptr arg, yank
-@unnumberedsubsubsec Passing a negative argument
-
-Finally, the question arises, what happens if either the remainder
-function, @code{%}, or the @code{nthcdr} function is passed a negative
-argument, as they quite well may?
-
-The answers can be found by a quick test. When @code{(% -1 5)} is
-evaluated, a negative number is returned; and if @code{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 @samp{@result{}} points to the result of evaluating the code
-preceding it. This was done by positioning the cursor after the code
-and typing @kbd{C-x C-e} (@code{eval-last-sexp}) in the usual fashion.
-You can do this if you are reading this in Info inside of GNU Emacs.
-
-@smallexample
@group
-(% -1 5)
- @result{} -1
+ ;; If we do get all the way thru, make this-command indicate that.
+ (if (eq this-command t)
+ (setq this-command 'yank))
+ nil)
@end group
+@end smallexample
-@group
-(setq animals '(cats dogs elephants))
- @result{} (cats dogs elephants)
-@end group
+The key expression is @code{insert-for-yank}, which inserts the string
+returned by @code{current-kill}, but removes some text properties from
+it.
-@group
-(nthcdr 1 animals)
- @result{} (dogs elephants)
-@end group
+However, before getting to that expression, the function set the value
+of @code{yank-window-start} to the position returned by the
+@code{(window-start)} expression, the position at which the display
+currently starts. It also set @code{this-command} and pushed the
+mark.
-@group
-(nthcdr 0 animals)
- @result{} (cats dogs elephants)
-@end group
+After it yanks the appropriate element, if the optional argument is a
+@sc{cons} rather than a number or nothing, put point at beginning of
+the yanked text and mark at its end. (The @code{prog1} function is
+like @code{progn} but returns the value of its first argument rather
+than the value of its last argument. Its first argument is forced to
+return the buffer's mark as an integer. You can see the documentation
+for these functions by placing point over them in this buffer and then
+typing @kbd{C-h f} (@code{describe-function}) followed by a @kbd{RET};
+the default is the function.)
-@group
-(nthcdr -1 animals)
- @result{} (cats dogs elephants)
-@end group
-@end smallexample
+The last part of the function tells what to do when it succeeds.
-So, if a minus sign or a negative number is passed to @code{yank}, the
-@code{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 @code{yank} with a minus sign
-preceding it will be treated as @minus{}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.
@node yank-pop, ring file, yank, Kill Ring
@comment node-name, next, previous, up
@appendixsec @code{yank-pop}
@findex yank-pop
-After understanding @code{yank}, the @code{yank-pop} function is easy.
-Leaving out the documentation to save space, it looks like this:
+After understanding @code{yank} and @code{current-kill}, you know how
+to approach the @code{yank-pop} function Leaving out the documentation
+to save space, it looks like this:
+@c GNU Emacs 22
@smallexample
@group
-(defun yank-pop (arg)
+(defun yank-pop (&optional arg)
+ "@dots{}"
(interactive "*p")
(if (not (eq last-command 'yank))
(error "Previous command was not a yank"))
@end group
@group
(setq this-command 'yank)
- (let ((before (< (point) (mark))))
- (delete-region (point) (mark))
- (rotate-yank-pointer arg)
+ (unless arg (setq arg 1))
+ (let ((inhibit-read-only t)
+ (before (< (point) (mark t))))
+@end group
+@group
+ (if before
+ (funcall (or yank-undo-function 'delete-region) (point) (mark t))
+ (funcall (or yank-undo-function 'delete-region) (mark t) (point)))
+ (setq yank-undo-function nil)
+@end group
+@group
+ (set-marker (mark-marker) (point) (current-buffer))
+ (insert-for-yank (current-kill arg))
+ ;; Set the window start back where it was in the yank command,
+ ;; if possible.
+ (set-window-start (selected-window) yank-window-start t)
@end group
@group
- (set-mark (point))
- (insert (car kill-ring-yank-pointer))
- (if before (exchange-point-and-mark))))
+ (if before
+ ;; This is like exchange-point-and-mark,
+ ;; but doesn't activate the mark.
+ ;; It is cleaner to avoid activation, even though the command
+ ;; loop would deactivate the mark because we inserted text.
+ (goto-char (prog1 (mark t)
+ (set-marker (mark-marker)
+ (point)
+ (current-buffer))))))
+ nil)
@end group
@end smallexample
argument is processed and passed to the function. The command can
only be used after a previous yank; otherwise an error message is
sent. This check uses the variable @code{last-command} which is
-discussed elsewhere. (@xref{copy-region-as-kill}.)
+set by @code{yank} and is discussed elsewhere. (@xref{copy-region-as-kill}.)
The @code{let} clause sets the variable @code{before} to true or false
depending whether point is before or after mark and then the region
between point and mark is deleted. This is the region that was just
inserted by the previous yank and it is this text that will be
-replaced. Next the @code{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 @code{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!
+replaced.
+
+@code{funcall} calls its first argument as a function, passing
+remaining arguments to it. The first argument is whatever the
+@code{or} expression returns. The two remaining arguments are the
+positions of point and mark set by the preceding @code{yank} command.
+
+There is more, but that is the hardest part.
@node ring file, , yank-pop, Kill Ring
@comment node-name, next, previous, up
@menu
* Labelled Example::
-* print-graph Varlist:: @code{let} expression in @code{print-graph}.
-* print-Y-axis:: Print a label for the vertical axis.
-* print-X-axis:: Print a horizontal label.
-* Print Whole Graph:: The function to print a complete graph.
+* print-graph Varlist::
+* print-Y-axis::
+* print-X-axis::
+* Print Whole Graph::
@end menu
@node Labelled Example, print-graph Varlist, Full Graph, Full Graph
five.
@menu
-* Height of label:: What height for the Y axis?
-* Compute a Remainder:: How to compute the remainder of a division.
-* Y Axis Element:: Construct a line for the Y axis.
-* Y-axis-column:: Generate a list of Y axis labels.
-* print-Y-axis Penultimate:: A not quite final version.
+* Height of label::
+* Compute a Remainder::
+* Y Axis Element::
+* Y-axis-column::
+* print-Y-axis Penultimate::
@end menu
@node Height of label, Compute a Remainder, print-Y-axis, print-Y-axis
that you cannot discover using @code{apropos}: you find nothing if you
type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to
learn of the existence of @code{%} is to read about it in a book such
-as this or in the Emacs Lisp sources. The @code{%} function is used
-in the code for @code{rotate-yank-pointer}, which is described in an
-appendix. (@xref{rotate-yk-ptr body, , The Body of
-@code{rotate-yank-pointer}}.)
+as this or in the Emacs Lisp sources.
You can try the @code{%} function by evaluating the following two
expressions:
graph without changing the ways the graph is labelled.
@menu
-* Similarities differences:: Much like @code{print-Y-axis}, but not exactly.
-* X Axis Tic Marks:: Create tic marks for the horizontal axis.
+* Similarities differences::
+* X Axis Tic Marks::
@end menu
@node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis
@end smallexample
@menu
-* The final version:: A few changes.
-* Test print-graph:: Run a short test.
-* Graphing words in defuns:: Executing the final code.
-* lambda:: How to write an anonymous function.
-* mapcar:: Apply a function to elements of a list.
-* Another Bug:: Yet another bug @dots{} most insidious.
-* Final printed graph:: The graph itself!
+* The final version::
+* Test print-graph::
+* Graphing words in defuns::
+* lambda::
+* mapcar::
+* Another Bug::
+* Final printed graph::
@end menu
@node The final version, Test print-graph, Print Whole Graph, Print Whole Graph