[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispintro/emacs-lisp-intro.texi,v
|
From: |
Robert J. Chassell |
|
Subject: |
[Emacs-diffs] Changes to emacs/lispintro/emacs-lisp-intro.texi,v |
|
Date: |
Mon, 30 Oct 2006 22:14:06 +0000 |
CVSROOT: /cvsroot/emacs
Module name: emacs
Changes by: Robert J. Chassell <bob> 06/10/30 22:14:05
Index: emacs-lisp-intro.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispintro/emacs-lisp-intro.texi,v
retrieving revision 1.42
retrieving revision 1.43
diff -u -b -r1.42 -r1.43
--- emacs-lisp-intro.texi 21 Aug 2006 18:44:54 -0000 1.42
+++ emacs-lisp-intro.texi 30 Oct 2006 22:14:05 -0000 1.43
@@ -1,5 +1,6 @@
\input ../man/texinfo @c -*-texinfo-*-
address@hidden change above to \input texinfo if building on own.
address@hidden \input texinfo @c
-*-texinfo-*-
address@hidden change to \input texinfo if building on own.
@comment %**start of header
@setfilename ../info/eintr
@c setfilename emacs-lisp-intro.info
@@ -23,19 +24,25 @@
@comment %**end of header
address@hidden edition-number 2.14
address@hidden update-date 2004 Oct 12
address@hidden edition-number 2.15
address@hidden 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
@@ -52,6 +59,8 @@
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
@@ -65,6 +74,19 @@
## 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 ================ Included Figures ================
@@ -166,7 +188,8 @@
@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 ----------------------------------------------------
@@ -280,6 +303,16 @@
every node in every chapter.
@end ifnottex
address@hidden >>>> Set pageno appropriately <<<<
+
address@hidden The first page of the Preface is a roman numeral; it is the first
address@hidden right handed page after the Table of Contents; hence the
following
address@hidden setting must be for an odd negative number.
+
address@hidden
address@hidden@pageno = -11
address@hidden iftex
+
@menu
* Preface:: What to look for.
* List Processing:: What is Lisp?
@@ -473,6 +506,7 @@
* 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}
@@ -519,9 +553,9 @@
* 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::
@@ -538,12 +572,7 @@
* 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}
@@ -556,6 +585,11 @@
* 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::
@@ -564,9 +598,9 @@
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
@@ -643,11 +677,6 @@
* 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
@@ -721,28 +750,19 @@
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}
address@hidden 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.
-
address@hidden
-
-* 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
@@ -778,16 +798,6 @@
@end detailmenu
@end menu
address@hidden >>>> Set pageno appropriately <<<<
-
address@hidden The first page of the Preface is a roman numeral; it is the first
address@hidden right handed page after the Table of Contents; hence the
following
address@hidden setting must be for an odd negative number.
-
address@hidden
address@hidden@pageno = -11
address@hidden iftex
-
@node Preface, List Processing, Top, Top
@comment node-name, next, previous, up
@unnumbered Preface
@@ -809,11 +819,11 @@
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
@@ -1066,16 +1076,16 @@
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
@@ -1105,10 +1115,10 @@
@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
@@ -1151,8 +1161,8 @@
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, ,
address@hidden @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.
@@ -1378,13 +1388,13 @@
@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
@@ -1501,7 +1511,7 @@
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.
@@ -1546,8 +1556,8 @@
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
@@ -1639,7 +1649,7 @@
or else produce an error.
@menu
-* Evaluating Inner Lists:: Lists within lists...
+* Evaluating Inner Lists::
@end menu
@node Evaluating Inner Lists, , Evaluation, Evaluation
@@ -1741,9 +1751,8 @@
@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
@@ -1805,7 +1814,7 @@
@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
@@ -1825,6 +1834,7 @@
(Remember, to quit the debugger and make the debugger window go away,
type @kbd{q} in the @file{*Backtrace*} buffer.)
address@hidden
@need 800
In GNU Emacs 20 and before, you will produce an error message that says:
@@ -1833,8 +1843,9 @@
@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.)
address@hidden ignore
@node Void Variable, , Void Function, Variables
@comment node-name, next, previous, up
@@ -1854,7 +1865,7 @@
@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
@@ -1891,6 +1902,7 @@
definition, the error message reported that the symbol's value as a
variable was void.
address@hidden
@need 800
In GNU Emacs version 20 and before, your error message will say:
@@ -1899,7 +1911,8 @@
@end example
@noindent
-The meaning is the same as in GNU Emacs 21.
+The meaning is the same as in GNU Emacs 22.
address@hidden ignore
@node Arguments, set & setq, Variables, List Processing
@comment node-name, next, previous, up
@@ -1945,14 +1958,11 @@
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
@@ -2028,7 +2038,7 @@
@noindent
The value will be a number two more than what you get by evaluating
address@hidden alone. For me, this is 74, because the value of
address@hidden 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
@@ -2038,7 +2048,7 @@
@address@hidden"The "}} and @address@hidden" red foxes."}} and the list
@code{(number-to-string (+ 2 fill-column))}.
address@hidden For Emacs 21, need number-to-string
address@hidden For GNU Emacs 22, need number-to-string
@smallexample
(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.")
@end smallexample
@@ -2122,7 +2132,7 @@
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
@@ -2180,6 +2190,7 @@
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.
address@hidden
@need 1250
In GNU Emacs version 20 and before, the echo area displays an error
message that says:
@@ -2190,6 +2201,7 @@
This says, in different words, the same as the top line of the
@file{*Backtrace*} buffer.
address@hidden ignore
@node message, , Wrong Type of Argument, Arguments
@comment node-name, next, previous, up
@@ -2300,8 +2312,9 @@
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
@@ -2319,9 +2332,9 @@
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
@@ -2340,7 +2353,7 @@
@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
@@ -2529,7 +2542,14 @@
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,
address@hidden
+'
address@hidden ifinfo
address@hidden
address@hidden'}
address@hidden 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.
@@ -2584,13 +2604,11 @@
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
@@ -2656,24 +2674,42 @@
each of the following expressions by positioning the cursor after it and
typing @kbd{C-x C-e}.
address@hidden
address@hidden
@group
(buffer-name)
(buffer-file-name)
@end group
address@hidden smallexample
address@hidden example
@noindent
-When I do this, @file{"introduction.texinfo"} is the value returned by
-evaluating @code{(buffer-name)}, and
address@hidden"/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
address@hidden as functions; without the parentheses, the
-interpreter would attempt to evaluate the symbols as variables.
address@hidden)
+When I do this in Info, the value returned by evaluating
address@hidden(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
address@hidden"introduction.texinfo"}, and the value returned by evaluating
address@hidden(buffer-file-name)} is
address@hidden"/gnu/work/intro/introduction.texinfo"}.
+
address@hidden @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
address@hidden(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
address@hidden"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 @address@hidden and @address@hidden 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.
@@ -2698,23 +2734,25 @@
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
address@hidden buffer does not visit any file. Similarly, a
@file{*Help*} buffer is not associated with any file.
address@hidden @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
address@hidden buffer is not associated with any file. (In Lisp,
address@hidden 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
address@hidden(buffer-name)}, position the cursor after it, and then type
address@hidden 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
address@hidden(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*}
@@ -2771,18 +2809,20 @@
@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,
address@hidden<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:
@@ -2815,12 +2855,13 @@
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 @address@hidden
-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
address@hidden 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
@@ -2980,16 +3021,16 @@
@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
@@ -3226,10 +3267,9 @@
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
@@ -3254,7 +3294,9 @@
@smallexample
@group
-multiply-by-seven:
+multiply-by-seven is a Lisp function.
+(multiply-by-seven NUMBER)
+
Multiply NUMBER by seven.
@end group
@end smallexample
@@ -3329,8 +3371,8 @@
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
@@ -3436,14 +3478,14 @@
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
address@hidden 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
address@hidden 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
@@ -3476,62 +3518,67 @@
@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}.
-
-A function with two or more arguments can have information passed to
-each argument by adding parts to the string that follows
address@hidden When you do this, the information is passed to
-each argument in the same order it is specified in the
+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.
+
+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
address@hidden 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
address@hidden 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)
"@address@hidden"
- (interactive "BAppend to buffer:@: \nr")
+ (interactive "p\ncZap to char: ")
@address@hidden)
@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
address@hidden)
+are prompted. @xref{copy-to-buffer, , The Definition of
address@hidden, 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.
+
address@hidden, , 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
@@ -3565,11 +3612,11 @@
@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
@@ -3621,6 +3668,7 @@
@end ifnottex
@cindex @samp{local variable} defined
address@hidden @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
@@ -3726,13 +3774,17 @@
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 @address@hidden
+to Jared Diamond in @cite{Guns, Germs, and Steel}, address@hidden 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
@@ -3818,7 +3870,7 @@
@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
@@ -4086,8 +4138,8 @@
(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
@@ -4106,11 +4158,11 @@
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
@@ -4198,7 +4250,7 @@
unexpected movement of point or mark.
@menu
-* Point and mark:: A review of various locations.
+* Point and mark::
* Template for save-excursion::
@end menu
@@ -4256,8 +4308,8 @@
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
@@ -4334,7 +4386,9 @@
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
@@ -4346,6 +4400,24 @@
@end group
@end smallexample
address@hidden
+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))
address@hidden 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
@@ -4430,10 +4502,10 @@
@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
@@ -4487,6 +4559,7 @@
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
@@ -4567,13 +4640,11 @@
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
@@ -4591,12 +4662,23 @@
then @key{RET}).
@cindex Find source of function
-In versions 20 and higher, when a function is written in Emacs Lisp,
address@hidden will also tell you the location of the
-function definition. If you move point over the file name and press
address@hidden 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
address@hidden rather than `return' or `enter'. Emacs will take
+you directly to the function definition.
+
address@hidden
+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.
address@hidden 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.
@@ -4619,7 +4701,7 @@
@key{RET}}. (On some keyboards, the @key{META} key is labelled
@key{ALT}.)
address@hidden !!! 21.0.100 tags table location in this paragraph
address@hidden !!! 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
@@ -4629,15 +4711,15 @@
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
address@hidden/usr/local/share/emacs/21.0.100/lisp/TAGS} or
address@hidden/usr/local/src/emacs/src/TAGS}. If the tags table has
-not already been created, you will have to create it yourself.
address@hidden/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
address@hidden@code{etags *.el}} as the command to execute
address@hidden@code{etags *.el}} as the command to execute:
@smallexample
M-x compile RET etags *.el RET
@@ -4773,13 +4855,15 @@
@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.
+
address@hidden
(The prompt for @code{describe-function} will offer you the symbol
under or preceding the cursor, so you can save typing by positioning
the cursor right over or after the function and then typing @kbd{C-h f
@@ -4805,28 +4889,29 @@
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
@@ -4863,10 +4948,11 @@
The body of the @code{mark-whole-buffer} function consists of three
lines of code:
address@hidden 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
@@ -4889,34 +4975,36 @@
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
address@hidden address@hidden twice.
+In earlier versions of GNU Emacs, the next line of
address@hidden 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.
address@hidden & 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
address@hidden twice.
-(In GNU Emacs 21, the @code{(push-mark (point-max)} is slightly more
-complicated than shown here. The line reads
address@hidden 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
@@ -4932,16 +5020,16 @@
@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
address@hidden 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
address@hidden 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
@@ -4954,10 +5042,15 @@
@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.
+
address@hidden 1250
Here is the complete text of the function:
@smallexample
@@ -4969,13 +5062,26 @@
@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)))
address@hidden group
address@hidden
(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
@@ -4989,7 +5095,7 @@
@group
(defun append-to-buffer (buffer start end)
"@address@hidden"
- (interactive "BAppend to buffer:@: \nr")
+ (interactive @dots{})
@address@hidden)
@end group
@end smallexample
@@ -5000,7 +5106,12 @@
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
@@ -5012,30 +5123,94 @@
Function Interactive}.) The expression reads as follows:
@smallexample
+(interactive
+ (list (read-buffer
+ "Append to buffer: "
+ (other-buffer (current-buffer) t))
+ (region-beginning)
+ (region-end)))
address@hidden smallexample
+
address@hidden
+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).
+
address@hidden 1250
+The expression looks like this:
+
address@hidden
+(other-buffer (current-buffer) t)
address@hidden smallexample
+
+The second and third arguments to the @code{list} expression are
address@hidden(region-beginning)} and @code{(region-end)}. These two
+functions specify the beginning and end of the text to be appended.
+
address@hidden 1250
+Originally, the command used the letters @samp{B} and @samp{r}.
+The whole @code{interactive} expression looked like this:
+
address@hidden
(interactive "BAppend to buffer:@: \nr")
@end smallexample
@noindent
-This expression has an argument inside of quotation marks and that
-argument has two parts, separated by @samp{\n}.
+But when that was done, the default value of the buffer switched to
+was invisible. That was not wanted.
-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
address@hidden to buffer:@: }. Emacs then binds the variable @code{buffer}
-in the function's argument list to the specified buffer.
-
-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,
address@hidden 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}
address@hidden
+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))))))))
address@hidden 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
@@ -5052,7 +5227,7 @@
@group
(defun append-to-buffer (buffer start end)
"@address@hidden"
- (interactive "BAppend to buffer:@: \nr")
+ (interactive @dots{})
(let ((@var{variable} @var{value}))
@address@hidden)
@end group
@@ -5142,7 +5317,7 @@
@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
@@ -5152,8 +5327,10 @@
@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
@@ -5174,70 +5351,84 @@
@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
address@hidden function. The @code{let*} function is different. It has a
address@hidden in its name. It enables Emacs to set each variable in its
+varlist in sequence, one after another.
+
+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.
address@hidden let, , The @code{let*} expression}.
+
+We will skip functions like @code{let*} and focus on two: the
address@hidden function and the @code{insert-buffer-substring}
+function.
+
address@hidden 1250
+In the old days, the @code{set-buffer} expression was simply
@smallexample
address@hidden
(set-buffer (get-buffer-create buffer))
-(insert-buffer-substring oldbuf start end)
address@hidden group
@end smallexample
-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.
-
-The first line in the body of the @code{save-excursion} uses the
address@hidden 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.
-
-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.
-
address@hidden 800
-The line looks like this:
address@hidden 1250
address@hidden
+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.
-
address@hidden 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,
address@hidden is always provided with a buffer.
address@hidden
address@hidden 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}.
+
address@hidden
+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))))))))
address@hidden ignore
+
+The @code{append-to-buffer} function definition inserts text from the
+buffer in which you are currently to a named buffer. It happens that
address@hidden copies text from another buffer to the
+current buffer, just the reverse---that is why the
address@hidden definition starts out with a @code{let} that
+binds the local symbol @code{oldbuf} to the value returned by
address@hidden
@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
address@hidden 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
address@hidden the buffer specified as its first argument and inserts the
+string into the present buffer. In this case, the argument to
address@hidden 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,
address@hidden will restore the action to the original buffer and
address@hidden will have done its job.
address@hidden 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:
@@ -5251,16 +5442,15 @@
@var{change-back-to-original-buffer-when-finished}
@address@hidden@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
address@hidden, 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
@@ -5351,10 +5541,9 @@
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
@@ -5366,42 +5555,63 @@
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
address@hidden function is almost the same as the code for
address@hidden, except that @code{erase-buffer} and a second
address@hidden are used. (@xref{append-to-buffer, , The
-Definition of @code{append-to-buffer}}, for the description of
address@hidden)
+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)))
- (save-excursion
- (set-buffer (get-buffer-create 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
(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
address@hidden: 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,
address@hidden 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}.
+
address@hidden 800
+The definition then says
+
address@hidden
+(with-current-buffer (get-buffer-create buffer) @dots{}
address@hidden 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}.
address@hidden is a newer, and arguably easier,
+mechanism.)
-Why is @code{save-excursion} used twice? Consider again what the
-function does.
+The @code{barf-if-buffer-read-only} function sends you an error
+message saying the buffer is read-only if you cannot modify it.
+
+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
address@hidden).
+
+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:
@@ -5409,27 +5619,14 @@
@smallexample
@group
(let (@address@hidden@address@hidden)
- (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
@address@hidden@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
address@hidden 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}
@@ -5443,17 +5640,21 @@
Here is a discussion based on the original code. The code was
simplified in 2003 and is harder to understand.
address@hidden 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
@@ -5462,7 +5663,7 @@
@end ifnottex
@need 800
-Here is the code:
+Here is the earlier code:
@smallexample
@group
@@ -5511,8 +5712,8 @@
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
@@ -5546,6 +5747,11 @@
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
@@ -5722,7 +5928,7 @@
(or (holding-on-to-guest) (find-and-take-arm-of-guest))
@end smallexample
address@hidden Insert let, , Insert or, insert-buffer
address@hidden Insert let, New insert-buffer , Insert or, insert-buffer
@comment node-name, next, previous, up
@subsection The @code{let} Expression in @code{insert-buffer}
@@ -5821,35 +6027,75 @@
use @code{or}. All these functions are building blocks that we will
find and use again and again.
address@hidden beginning-of-buffer, Second Buffer Related Review,
insert-buffer, More Complex
address@hidden New insert-buffer , , Insert let, insert-buffer
@comment node-name, next, previous, up
address@hidden Complete Definition of @code{beginning-of-buffer}
address@hidden beginning-of-buffer
address@hidden New Body for @code{insert-buffer}
address@hidden insert-buffer, new version body
address@hidden new version body for insert-buffer
-The basic structure of the @code{beginning-of-buffer} function has
+The body in the GNU Emacs 22 version is more confusing than the original.
+
address@hidden 1250
+It consists of two expressions,
+
address@hidden
address@hidden
+ (push-mark
+ (save-excursion
+ (insert-buffer-substring (get-buffer buffer))
+ (point)))
+
+ nil
address@hidden group
address@hidden smallexample
+
address@hidden
+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
address@hidden; 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
address@hidden 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.
+
address@hidden beginning-of-buffer, Second Buffer Related Review,
insert-buffer, More Complex
address@hidden node-name, next, previous, up
address@hidden Complete Definition of @code{beginning-of-buffer}
address@hidden beginning-of-buffer
+
+The basic structure of the @code{beginning-of-buffer} function has
already been discussed. (@xref{simplified-beginning-of-buffer, , A
Simplified @code{beginning-of-buffer} Definition}.)
This section describes the complex part of the definition.
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
@@ -5864,12 +6110,12 @@
@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
address@hidden 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}
@@ -5887,12 +6133,16 @@
(defun beginning-of-buffer (&optional arg)
"@address@hidden"
(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
@@ -5900,26 +6150,37 @@
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.
+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. A prefix argument
-is made by typing the @key{META} key followed by a number, or by typing
address@hidden 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
address@hidden, 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
+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
address@hidden"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
address@hidden 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
address@hidden, and when this is the outcome, the whole
address@hidden 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
address@hidden 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
@@ -5934,11 +6195,12 @@
@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
@@ -5984,13 +6246,21 @@
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
@@ -6002,7 +6272,7 @@
@group
(*
(prefix-numeric-value arg)
- (/ (buffer-size) 10))
+ (/ size 10))
@end group
@end smallexample
@@ -6019,11 +6289,12 @@
@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,
address@hidden/} is used for division, just as @code{*} is used for
+multiplication.)
@need 1200
In the multiplication expression as a whole, this amount is multiplied
@@ -6032,23 +6303,22 @@
@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
address@hidden 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
@@ -6069,7 +6339,7 @@
@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
@@ -6084,7 +6354,7 @@
(/
(+ 10
(*
- (buffer-size)
+ size
(prefix-numeric-value arg)))
10))
@end group
@@ -6093,12 +6363,12 @@
@need 1200
@noindent
Looking at parentheses, we see that the innermost operation is
address@hidden(prefix-numeric-value arg)}, which converts the raw argument to a
-number. This number is multiplied by the buffer size in the following
-expression:
address@hidden(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
@@ -6120,6 +6390,47 @@
Here is the complete text of the @code{beginning-of-buffer} function:
@sp 1
address@hidden In GNU Emacs 22
address@hidden
address@hidden
+(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.
address@hidden group
+
address@hidden
+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))
address@hidden group
address@hidden
+ (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)))
address@hidden group
address@hidden smallexample
+
address@hidden
+From before GNU Emacs 22
@smallexample
@group
(defun beginning-of-buffer (&optional arg)
@@ -6151,6 +6462,7 @@
(if arg (forward-line 1)))
@end group
@end smallexample
address@hidden ignore
@noindent
Except for two small points, the previous discussion shows how this
@@ -6162,18 +6474,21 @@
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 @address@hidden 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
@@ -6185,8 +6500,15 @@
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
@@ -6200,7 +6522,7 @@
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
@@ -6254,9 +6576,9 @@
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
@@ -6359,6 +6681,60 @@
@end group
@end smallexample
address@hidden
+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)))))))
address@hidden ignore
+
@node what-line, narrow Exercise, save-restriction, Narrowing & Widening
@comment node-name, next, previous, up
@section @code{what-line}
@@ -6389,13 +6765,17 @@
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.
+
+(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 function as shown here has a documentation line and is
-interactive, as you would expect. The next two lines use the
+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
@@ -6434,15 +6814,14 @@
@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},
address@hidden, or @samp{%c} to print arguments that follow the string.
address@hidden 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
address@hidden expression to print a following argument. @samp{%d} prints
+the argument as a decimal, so the message will say something such as
address@hidden 243}.
@need 1200
-
The number that is printed in place of the @samp{%d} is computed by the
last line of the function:
@@ -6450,6 +6829,33 @@
(1+ (count-lines 1 (point)))
@end smallexample
address@hidden
+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)))))))
address@hidden 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
@@ -6477,12 +6883,14 @@
@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
address@hidden @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
address@hidden or @code{point-min}? Or can you write the function
-without them?)
address@hidden or
address@hidden @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
@@ -6499,13 +6907,13 @@
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
@@ -6687,7 +7095,7 @@
@menu
* Build a list::
-* length:: How to find the length of a list.
+* length::
@end menu
@node Build a list, length, cons, cons
@@ -6798,7 +7206,7 @@
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
@@ -6808,13 +7216,20 @@
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,
address@hidden<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.
+
address@hidden
address@hidden 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.
address@hidden ignore
@node nthcdr, nth, cons, car cdr & cons
@comment node-name, next, previous, up
@@ -7016,9 +7431,14 @@
@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
@@ -7156,12 +7576,12 @@
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
@@ -7181,9 +7601,9 @@
@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
@@ -7238,27 +7658,27 @@
@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
@@ -7288,12 +7708,8 @@
manipulates text, and we will focus attention on them as well as on the
deletion command.
address@hidden 800
-Here is the complete text of the version 19 implementation of the function:
-
address@hidden v 19
address@hidden
address@hidden
address@hidden
address@hidden 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."
@@ -7303,6 +7719,24 @@
(search-forward
(char-to-string char) nil nil arg)
(point))))
address@hidden ignore
+
address@hidden 1250
+Here is the complete text of the version 22 implementation of the function:
+
address@hidden GNU Emacs 22
address@hidden
address@hidden
+(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
@@ -7315,44 +7749,11 @@
this:
@smallexample
-(interactive "*p\ncZap to char: ")
+(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
address@hidden According to the documentation for
address@hidden, the asterisk, @samp{*}, should prevent the
address@hidden 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
address@hidden 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.
-
-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
@@ -7360,15 +7761,23 @@
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
address@hidden 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
address@hidden 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}
@@ -7376,13 +7785,31 @@
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
address@hidden 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}.)
+
address@hidden
@code{(point)} is the current position of the cursor.
The next part of the code is an expression using @code{progn}. The body
@@ -7402,10 +7829,13 @@
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,
address@hidden 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:
@@ -7501,9 +7931,12 @@
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
address@hidden This value is returned by the @code{progn}
-expression and is passed to @code{kill-region} as @code{kill-region}'s
-second argument.
address@hidden (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
address@hidden as @code{kill-region}'s second argument.
@node Summing up zap-to-char, , progn, zap-to-char
@comment node-name, next, previous, up
@@ -7520,14 +7953,14 @@
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
address@hidden command takes two arguments; and it would fail if
address@hidden 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
address@hidden needs for its second argument.
address@hidden kill-region, Digression into C, zap-to-char, Cutting & Storing
Text
address@hidden 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
@@ -7536,7 +7969,125 @@
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
address@hidden
+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)))))))
+
address@hidden 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.
@@ -7547,9 +8098,9 @@
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
@@ -7559,10 +8110,115 @@
@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:
+
address@hidden GNU Emacs 22:
address@hidden
address@hidden
+(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{} "
address@hidden group
+
address@hidden
+ ;; @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"))
address@hidden group
+
address@hidden
+ ;; @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
address@hidden group
+
address@hidden
+ ;; @bullet{} The second argument to `condition-case' tells the
+ ;; Lisp interpreter what to do when all goes well.
address@hidden group
+
address@hidden
+ ;; 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.
address@hidden group
+
address@hidden
+ ;; 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.
address@hidden group
+
address@hidden
+ ;; `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'.
address@hidden group
address@hidden
+ (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)
address@hidden group
address@hidden
+ ;; @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)
address@hidden group
+
address@hidden
+ ;; @bullet{} The third argument to `condition-case' tells the interpreter
+ ;; what to do with an error.
address@hidden group
address@hidden
+ ;; 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.
address@hidden group
address@hidden
+ ;; 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)
address@hidden group
address@hidden
+ ;; 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.
address@hidden group
address@hidden
+ (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)))))
address@hidden group
address@hidden smallexample
address@hidden
@c v 21
@smallexample
@group
@@ -7615,7 +8271,7 @@
@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
@@ -7632,8 +8288,9 @@
(signal 'text-read-only (list (current-buffer)))))))
@end group
@end smallexample
address@hidden ignore
address@hidden condition-case, delete-and-extract-region, Complete kill-region,
kill-region
address@hidden condition-case, Lisp macro, Complete kill-region, kill-region
@comment node-name, next, previous, up
@subsection @code{condition-case}
@findex condition-case
@@ -7707,62 +8364,36 @@
@end group
@end smallexample
address@hidden delete-and-extract-region, , condition-case, kill-region
address@hidden node-name, next, previous, up
address@hidden @code{delete-and-extract-region}
address@hidden 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:
-
address@hidden
address@hidden
-(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))
address@hidden group
address@hidden smallexample
-It looks complicated because we have the new functions
address@hidden, @code{kill-append}, and
address@hidden as well as the new variables,
address@hidden 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.)
-
-In this @code{let} expression, the text that
address@hidden 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.)
-
-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 code uses @code{when} to determine whether the variable
address@hidden 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.
address@hidden
+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
address@hidden ignore
address@hidden Lisp macro, , condition-case, kill-region
address@hidden node-name, next, previous, up
address@hidden Lisp macro
@cindex Macro, lisp
@cindex Lisp macro
+
+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
address@hidden to determine whether the @code{string} variable points to
+text that exists.
+
+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.
+
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
@@ -7770,8 +8401,12 @@
`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.
+
address@hidden
+We will briefly look at C macros in
@ref{Digression into C}.
address@hidden ignore
@need 1200
If the string has content, then another conditional expression is
@@ -7780,14 +8415,18 @@
@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.
address@hidden 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.
@@ -7797,329 +8436,22 @@
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 @address@hidden(< end beg))}}
-expression is true, @code{kill-append} prepends the string to the just
-previously clipped text. For a detailed discussion, see
address@hidden 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 @address@hidden(< 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
address@hidden variable to point to it.
+clipped text in the kill ring.
address@hidden Digression into C, defvar, kill-region, Cutting & Storing Text
address@hidden copy-region-as-kill, Digression into C, kill-region, Cutting &
Storing Text
@comment node-name, next, previous, up
address@hidden Digression into C
address@hidden delete-and-extract-region
address@hidden C, a digression into
address@hidden Digression into C
address@hidden @code{copy-region-as-kill}
address@hidden copy-region-as-kill
address@hidden nthcdr
-The @code{zap-to-char} command uses the
address@hidden function, which in turn uses two
-other functions, @code{copy-region-as-kill} and
address@hidden 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, ,
address@hidden)
-
-The @code{delete-and-extract-region} function removes the contents of
-a region and you cannot get them back.
-
-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.
-
address@hidden 1500
-Like many of the other Emacs primitives,
address@hidden is written as an instance of a C
-macro, a macro being a template for code. The complete macro looks
-like this:
-
address@hidden /usr/local/src/emacs/src/editfns.c
address@hidden
address@hidden
-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;
address@hidden
- validate_region (&start, &end);
- return del_range_1 (XINT (start), XINT (end), 1, 1);
address@hidden
address@hidden group
address@hidden 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
address@hidden was chosen since the code serves the same purpose as
address@hidden does in Lisp. The word @code{DEFUN} is followed by seven
-parts inside of parentheses:
-
address@hidden @bullet
address@hidden
-The first part is the name given to the function in Lisp,
address@hidden
-
address@hidden
-The second part is the name of the function in C,
address@hidden By convention, it starts with
address@hidden Since C does not use hyphens in names, underscores are used
-instead.
-
address@hidden
-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}.
-
address@hidden
-The fourth and fifth parts specify the minimum and maximum number of
-arguments the function can have. This function demands exactly 2
-arguments.
-
address@hidden
-The sixth part is nearly like the argument that follows the
address@hidden 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
address@hidden"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.
-
address@hidden
-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.
-
address@hidden 1000
-Thus, the first two lines of documentation for @code{goto-char} are
-written like this:
-
address@hidden
address@hidden
- "Set point to POSITION, a number or marker.\n\
-Beginning of buffer is position (point-min), end is (point-max).
address@hidden group
address@hidden smallexample
address@hidden itemize
-
address@hidden 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:
-
address@hidden
address@hidden
-validate_region (&start, &end);
-return del_range_1 (XINT (start), XINT (end), 1, 1);
address@hidden group
address@hidden 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.
-
address@hidden 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
address@hidden These are @address@hidden (start)}} and @address@hidden
-(end)}}.
-
-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
address@hidden 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.}.
-
-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'.
-
address@hidden is a C macro that extracts the relevant number from the
-longer collection of bits; the four other bits are discarded.
-
address@hidden 800
-The command in @code{delete-and-extract-region} looks like this:
-
address@hidden
-del_range_1 (XINT (start), XINT (end), 1, 1);
address@hidden smallexample
-
address@hidden
-It deletes the region between the beginning position, @code{start},
-and the ending position, @code{end}.
-
-From the point of view of the person writing Lisp, Emacs is all very
-simple; but hidden underneath is a great deal of complexity to make it
-all work.
-
address@hidden defvar, copy-region-as-kill, Digression into C, Cutting &
Storing Text
address@hidden node-name, next, previous, up
address@hidden Initializing a Variable with @code{defvar}
address@hidden defvar
address@hidden Initializing a variable
address@hidden Variable initialization
-
-Unlike the @code{delete-and-extract-region} function, the
address@hidden 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
address@hidden This section describes how the @code{kill-ring}
-variable is created and initialized using the @code{defvar} special
-form.
-
-(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.)
-
-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{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.
-
-(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}}.)
-
address@hidden
-* See variable current value::
-* defvar and asterisk:: An old-time convention.
address@hidden menu
-
address@hidden See variable current value, defvar and asterisk, defvar, defvar
address@hidden
address@hidden Seeing the Current Value of a Variable
address@hidden ifnottex
-
-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
address@hidden:
-
address@hidden
address@hidden
-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
address@hidden group
address@hidden
-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.
address@hidden group
address@hidden smallexample
-
address@hidden 800
-The kill ring is defined by a @code{defvar} in the following way:
-
address@hidden
address@hidden
-(defvar kill-ring nil
- "List of killed text sequences.
address@hidden")
address@hidden group
address@hidden smallexample
-
address@hidden
-In this variable definition, the variable is given an initial value of
address@hidden, 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}).
-
address@hidden defvar and asterisk, , See variable current value, defvar
address@hidden @code{defvar} and an asterisk
address@hidden defvar @r{for a user customizable variable}
address@hidden defvar @r{with an asterisk}
-
-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
address@hidden instead, since that special form provides a path into
-the Customization commands. (@xref{defcustom, , Specifying Variables
-using @code{defcustom}}.)
-
-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:
-
address@hidden
address@hidden
-(defvar shell-command-default-error-buffer nil
- "*Buffer name for `shell-command' @dots{} error output.
address@hidden ")
address@hidden group
address@hidden smallexample
-
address@hidden set-variable
address@hidden
-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}.
address@hidden Initialization, , Your @file{.emacs} File}.
-
-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
address@hidden set-variable} command to see the list of variables.
-(@xref{Examining, , Examining and Setting Variables, emacs,
-The GNU Emacs Manual}.)
-
address@hidden copy-region-as-kill, cons & search-fwd Review, defvar, Cutting &
Storing Text
address@hidden node-name, next, previous, up
address@hidden @code{copy-region-as-kill}
address@hidden copy-region-as-kill
address@hidden nthcdr
-
-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{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}.
If you call @code{copy-region-as-kill} immediately after a
@code{kill-region} command, Emacs appends the newly copied text to the
@@ -8129,8 +8461,8 @@
the function copies the text into a separate entry in the kill ring.
@menu
-* Complete copy-region-as-kill:: The complete function definition.
-* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
+* Complete copy-region-as-kill::
+* copy-region-as-kill body::
@end menu
@node Complete copy-region-as-kill, copy-region-as-kill body,
copy-region-as-kill, copy-region-as-kill
@@ -8139,24 +8471,22 @@
@end ifnottex
@need 1200
-Here is the complete text of the version 21 @code{copy-region-as-kill}
+Here is the complete text of the version 22 @code{copy-region-as-kill}
function:
address@hidden !!! for no text properties, use buffer-substring-no-properties
-
@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."
+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 (buffer-substring beg end) (< end beg))
- (kill-new (buffer-substring beg end)))
+ (kill-append (filter-buffer-substring beg end) (< end beg))
+ (kill-new (filter-buffer-substring beg end)))
@end group
@group
(if transient-mark-mode
@@ -8184,9 +8514,9 @@
almost becoming routine.
The documentation is somewhat confusing unless you remember that the
-word `kill' has a meaning different from its usual meaning. The
-`Transient Mark' and @code{interprogram-cut-function} comments explain
-certain side-effects.
+word `kill' has a meaning different from usual. The `Transient Mark'
+and @code{interprogram-cut-function} comments explain certain
+side-effects.
After you once set a mark, a buffer always contains a region. If you
wish, you can use Transient Mark mode to highlight the region
@@ -8219,14 +8549,14 @@
@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 (@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.
+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
@@ -8268,12 +8598,20 @@
@group
(if (eq last-command 'kill-region)
;; @r{then-part}
- (kill-append (buffer-substring beg end) (< end beg))
+ (kill-append (filter-buffer-substring beg end) (< end beg))
;; @r{else-part}
- (kill-new (buffer-substring beg end)))
+ (kill-new (filter-buffer-substring beg end)))
@end group
@end smallexample
address@hidden 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.)
+
@findex eq @r{(example of use)}
@noindent
The @code{eq} function tests whether its first argument is the same Lisp
@@ -8294,8 +8632,23 @@
@need 800
The @code{kill-append} function looks like this:
address@hidden in GNU Emacs 22
@smallexample
@group
+(defun kill-append (string before-p &optional yank-handler)
+ "Append STRING to the end of the latest kill in the kill ring.
+If BEFORE-P is non-nil, prepend STRING to the kill.
address@hidden "
+ (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)))
address@hidden group
address@hidden smallexample
+
address@hidden
+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.
@@ -8305,24 +8658,34 @@
(concat string (car kill-ring))
(concat (car kill-ring) string))
t))
address@hidden group
address@hidden smallexample
address@hidden ignore
@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.
-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
+(Also, the function provides an optional argument called
address@hidden; when invoked, this argument tells the function
+how to deal with properties added to the text, such as `bold' or
+`italics'.)
+
address@hidden !!! 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?)
+
+Consider the conditional that is one of the two arguments to
address@hidden 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:
@smallexample
@group
(if before-p ; @r{if-part}
- (concat string (car kill-ring)) ; @r{then-part}
- (concat (car kill-ring) string)) ; @r{else-part}
+ (concat string cur) ; @r{then-part}
+ (concat cur string)) ; @r{else-part}
@end group
@end smallexample
@@ -8355,7 +8718,7 @@
text will be concatenated before the old text:
@smallexample
-(concat string (car kill-ring))
+(concat string cur)
@end smallexample
@need 1200
@@ -8363,368 +8726,783 @@
But if the text will be appended, it will be concatenated
after the old text:
address@hidden
-(concat (car kill-ring) string))
address@hidden smallexample
address@hidden
+(concat cur string))
address@hidden smallexample
+
+To understand how this works, we first need to review the
address@hidden function. The @code{concat} function links together or
+unites two strings of text. The result is a string. For example:
+
address@hidden
address@hidden
+(concat "abc" "def")
+ @result{} "abcdef"
address@hidden group
+
address@hidden
+(concat "new "
+ (car '("first element" "second element")))
+ @result{} "new first element"
+
+(concat (car
+ '("first element" "second element")) " modified")
+ @result{} "first element modified"
address@hidden group
address@hidden smallexample
+
+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.
+
address@hidden kill-new function, , kill-append function, copy-region-as-kill
body
address@hidden The @code{kill-new} function
address@hidden kill-new
+
address@hidden in GNU Emacs 22, additional documentation to kill-new:
address@hidden
+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."
address@hidden ignore
address@hidden 1200
+The @code{kill-new} function looks like this:
+
address@hidden
address@hidden
+(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.
address@hidden"
address@hidden group
address@hidden
+ (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"))))
address@hidden group
address@hidden
+ (if (fboundp 'menu-bar-update-yank-menu)
+ (menu-bar-update-yank-menu string (and replace (car kill-ring))))
address@hidden group
address@hidden
+ (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)))
address@hidden group
address@hidden
+ (setq kill-ring-yank-pointer kill-ring)
+ (if interprogram-cut-function
+ (funcall interprogram-cut-function string (not replace))))
address@hidden group
address@hidden smallexample
address@hidden
+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))))
address@hidden ignore
+
address@hidden
+(Notice that the function is not interactive.)
+
+As usual, we can look at this function in parts.
+
+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.
+
address@hidden 1200
+The first line of the documentation makes sense:
+
address@hidden
+Make STRING the latest kill in the kill ring.
address@hidden smallexample
+
address@hidden
+Let's skip over the rest of the documentation for the moment.
+
+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.
+
address@hidden 1200
+The critical lines are these:
+
address@hidden
address@hidden
+ (if (and replace kill-ring)
+ ;; @r{then}
+ (setcar kill-ring string)
address@hidden group
address@hidden
+ ;; @r{else}
+ (push string kill-ring)
address@hidden group
address@hidden
+ (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)))
address@hidden group
address@hidden
+ (setq kill-ring-yank-pointer kill-ring)
+ (if interprogram-cut-function
+ (funcall interprogram-cut-function string (not replace))))
address@hidden group
address@hidden smallexample
+
+The conditional test is @address@hidden(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.
+
address@hidden 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:
+
address@hidden
+(setcar kill-ring string)
address@hidden smallexample
+
+The @code{setcar} function actually changes the first element of the
address@hidden list to the value of @code{string}. It replaces the
+first element.
+
address@hidden 1250
+On the other hand, if the kill ring is empty, or replace is false, the
+else-part of the condition is executed:
+
address@hidden
+(push string kill-ring)
address@hidden smallexample
+
address@hidden
address@hidden 1250
address@hidden puts its first argument onto the second. It is the same
+as the older
+
address@hidden
+(setq kill-ring (cons string kill-ring))
address@hidden smallexample
+
address@hidden
address@hidden 1250
+or the newer
+
address@hidden
+(add-to-list kill-ring string)
address@hidden smallexample
+
address@hidden
+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.
+
+Let's look at these two expressions in order.
+
+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.
+
+
+We can see how this works with an example.
+
address@hidden 800
+First,
+
address@hidden
+(setq example-list '("here is a clause" "another clause"))
address@hidden smallexample
+
address@hidden 1200
address@hidden
+After evaluating this expression with @kbd{C-x C-e}, you can evaluate
address@hidden and see what it returns:
+
address@hidden
address@hidden
+example-list
+ @result{} ("here is a clause" "another clause")
address@hidden group
address@hidden smallexample
+
address@hidden 1200
address@hidden
+Now, we can add a new element on to this list by evaluating the
+following expression:
address@hidden push, @r{example}
+
address@hidden
+(push "a third clause" example-list)
address@hidden smallexample
+
address@hidden 800
address@hidden
+When we evaluate @code{example-list}, we find its value is:
+
address@hidden
address@hidden
+example-list
+ @result{} ("a third clause" "here is a clause" "another clause")
address@hidden group
address@hidden smallexample
+
address@hidden
+Thus, the third clause is added to the list by @code{push}.
+
address@hidden 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:
+
address@hidden
address@hidden
+(if (> (length kill-ring) kill-ring-max)
+ (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
address@hidden group
address@hidden smallexample
+
+The code checks whether the length of the kill ring is greater than
+the maximum permitted length. This is the value of
address@hidden (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,
address@hidden 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
address@hidden 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.
+
address@hidden 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}
address@hidden It does this @var{N} times and returns the results.
+(@xref{nthcdr, , @code{nthcdr}}.)
-To understand how this works, we first need to review the
address@hidden function. The @code{concat} function links together or
-unites two strings of text. The result is a string. For example:
address@hidden 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, ,
address@hidden)
+
+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
-(concat "abc" "def")
- @result{} "abcdef"
+(setq trees '(maple oak pine birch))
+ @result{} (maple oak pine birch)
@end group
@group
-(concat "new "
- (car '("first element" "second element")))
- @result{} "new first element"
+(setcdr (nthcdr 2 trees) nil)
+ @result{} nil
-(concat (car
- '("first element" "second element")) " modified")
- @result{} "first element modified"
+trees
+ @result{} (maple oak pine)
@end group
@end smallexample
-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.
address@hidden
+(The value returned by the @code{setcdr} expression is @code{nil} since
+that is what the @sc{cdr} is set to.)
address@hidden kill-new function, , kill-append function, copy-region-as-kill
body
address@hidden The @code{kill-new} function
address@hidden kill-new
+To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
address@hidden 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
address@hidden This prevents the kill ring from growing too long.
address@hidden 1200
-The @code{kill-new} function looks like this:
address@hidden 800
+The next to last expression in the @code{kill-new} function is
@smallexample
address@hidden
-(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."
address@hidden group
address@hidden
- (and (fboundp 'menu-bar-update-yank-menu)
- (menu-bar-update-yank-menu string (and replace (car kill-ring))))
address@hidden group
address@hidden
- (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)))
address@hidden group
address@hidden
- (setq kill-ring-yank-pointer kill-ring)
- (if interprogram-cut-function
- (funcall interprogram-cut-function string (not replace))))
address@hidden group
+(setq kill-ring-yank-pointer kill-ring)
@end smallexample
-As usual, we can look at this function in parts.
+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
address@hidden, 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
address@hidden (@pxref{Yanking, , Yanking Text Back}).
@need 1200
-The first line of the documentation makes sense:
+Now, to return to an early expression in the body of the function:
@smallexample
-Make STRING the latest kill in the kill ring.
address@hidden
+ (if (fboundp 'menu-bar-update-yank-menu)
+ (menu-bar-update-yank-menu string (and replace (car kill-ring))))
address@hidden group
@end smallexample
@noindent
-Let's skip over the rest of the documentation for the moment.
+It starts with an @code{if} expression
+
+In this case, the expression tests first to see whether
address@hidden 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}).
+
address@hidden
+The then-part contains an expression whose first element is the
+function @code{and}.
+
address@hidden 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
address@hidden 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
address@hidden, it is considered true in Emacs Lisp.) In other words, an
address@hidden 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
address@hidden is true or not.
address@hidden
+ ;; 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.
address@hidden ignore
+
address@hidden 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.
-Also, let's skip over the first two lines of code, those involving
address@hidden We will explain them below.
+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 critical lines are these:
+The expression looks like this:
@smallexample
@group
- (if (and replace kill-ring)
- ;; @r{then}
- (setcar kill-ring string)
address@hidden group
address@hidden
- ;; @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)))
address@hidden group
address@hidden
- (setq kill-ring-yank-pointer kill-ring)
(if interprogram-cut-function
(funcall interprogram-cut-function string (not replace))))
@end group
@end smallexample
-The conditional test is @address@hidden(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.
+If an @code{interprogram-cut-function} exists, then Emacs executes
address@hidden, 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.)
address@hidden 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:
+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.
address@hidden
-(setcar kill-ring string)
address@hidden 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'.
-The @code{setcar} function actually changes the first element of the
address@hidden 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:
address@hidden
address@hidden is this true in Emacs 22? Does not seems to be
+
+ (If the @address@hidden(< end beg))}}
+expression is true, @code{kill-append} prepends the string to the just
+previously clipped text. For a detailed discussion, see
address@hidden 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 @address@hidden(< 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
address@hidden variable to point to it.
address@hidden ignore
address@hidden
+
address@hidden Evidently, changed for Emacs 22. The zap-to-char command does not
address@hidden 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}
address@hidden ignore
+
address@hidden Digression into C, defvar, copy-region-as-kill, Cutting &
Storing Text
address@hidden node-name, next, previous, up
address@hidden Digression into C
address@hidden delete-and-extract-region
address@hidden C, a digression into
address@hidden Digression into C
+
+The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, ,
address@hidden) 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
address@hidden 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.
+
address@hidden GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c
address@hidden the DEFUN for buffer-substring-no-properties
+
address@hidden 1500
+Like many of the other Emacs primitives,
address@hidden is written as an instance of a C
+macro, a macro being a template for code. The complete macro looks
+like this:
@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))
+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;
address@hidden
+ register int b, e;
+
+ validate_region (&start, &end);
+ b = XINT (start);
+ e = XINT (end);
+
+ return make_buffer_string (b, e, 0);
address@hidden
@end group
@end smallexample
address@hidden
-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.
+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
address@hidden was chosen since the code serves the same purpose as
address@hidden does in Lisp. (The @code{DEFUN} C macro is defined in
address@hidden/src/lisp.h}.)
-Let's look at these two expressions in order.
+The word @code{DEFUN} is followed by seven parts inside of
+parentheses:
-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.
address@hidden @bullet
address@hidden
+The first part is the name given to the function in Lisp,
address@hidden
address@hidden 800
-We can see how this works with an example:
address@hidden
+The second part is the name of the function in C,
address@hidden By convention, it starts with
address@hidden Since C does not use hyphens in names, underscores are used
+instead.
address@hidden
-(setq example-list '("here is a clause" "another clause"))
address@hidden smallexample
address@hidden
+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}.
address@hidden 1200
address@hidden
-After evaluating this expression with @kbd{C-x C-e}, you can evaluate
address@hidden and see what it returns:
address@hidden
+The fourth and fifth parts specify the minimum and maximum number of
+arguments the function can have. This function demands exactly 2
+arguments.
+
address@hidden
+The sixth part is nearly like the argument that follows the
address@hidden 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
address@hidden"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.
+
address@hidden
+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.
+
address@hidden 1000
+Thus, the first two lines of documentation for @code{goto-char} are
+written like this:
@smallexample
@group
-example-list
- @result{} ("here is a clause" "another clause")
+ "Set point to POSITION, a number or marker.\n\
+Beginning of buffer is position (point-min), end is (point-max).
@end group
@end smallexample
address@hidden itemize
@need 1200
address@hidden
-Now, we can add a new element on to this list by evaluating the
-following expression:
address@hidden cons, @r{example}
-
address@hidden
-(setq example-list (cons "a third clause" example-list))
address@hidden smallexample
-
address@hidden 800
address@hidden
-When we evaluate @code{example-list}, we find its value is:
+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
-example-list
- @result{} ("a third clause" "here is a clause" "another clause")
+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
address@hidden
-Thus, the third clause was added to the list by @code{cons}.
+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.
address@hidden 1200
-This is exactly similar to what the @code{setq} and @code{cons} do in
-the function. Here is the line again:
+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 @address@hidden (start)}} and
address@hidden@code{XINT (end)}}.
address@hidden
-(setq kill-ring (cons string kill-ring))
address@hidden smallexample
+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
address@hidden 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.}.
address@hidden 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:
+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'.
+
address@hidden is a C macro that extracts the relevant number from the
+longer collection of bits; the three other bits are discarded.
+
address@hidden 800
+The command in @code{delete-and-extract-region} looks like this:
@smallexample
address@hidden
-(if (> (length kill-ring) kill-ring-max)
- (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))
address@hidden group
+del_range_1 (XINT (start), XINT (end), 1, 1);
@end smallexample
-The code checks whether the length of the kill ring is greater than
-the maximum permitted length. This is the value of
address@hidden (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,
address@hidden 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
address@hidden 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.
address@hidden
+It deletes the region between the beginning position, @code{start},
+and the ending position, @code{end}.
address@hidden 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}
address@hidden It does this @var{N} times and returns the results.
+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.
address@hidden 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.)
address@hidden defvar, cons & search-fwd Review, Digression into C, Cutting &
Storing Text
address@hidden node-name, next, previous, up
address@hidden Initializing a Variable with @code{defvar}
address@hidden defvar
address@hidden Initializing a variable
address@hidden Variable initialization
-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}:
address@hidden
+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.
address@hidden
address@hidden
-(setq trees '(maple oak pine birch))
- @result{} (maple oak pine birch)
address@hidden group
+see Initializing a Variable with @code{defvar}
address@hidden
-(setcdr (nthcdr 2 trees) nil)
- @result{} nil
address@hidden ignore
-trees
- @result{} (maple oak pine)
address@hidden group
address@hidden 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
address@hidden This section describes how the @code{kill-ring}
+variable is created and initialized using the @code{defvar} special
+form.
address@hidden
-(The value returned by the @code{setcdr} expression is @code{nil} since
-that is what the @sc{cdr} is set to.)
+(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.)
-To repeat, in @code{kill-new}, the @code{nthcdr} function takes the
address@hidden 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.
+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''.
address@hidden 800
-The next to last expression in the @code{kill-new} function is
+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.
address@hidden
-(setq kill-ring-yank-pointer kill-ring)
address@hidden smallexample
+(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 @code{kill-ring-yank-pointer} is a global variable that is set to be
-the @code{kill-ring}.
address@hidden
+* See variable current value::
+* defvar and asterisk::
address@hidden menu
-Even though the @code{kill-ring-yank-pointer} is called a
address@hidden, 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
address@hidden (@pxref{Yanking, , Yanking Text Back}).
address@hidden See variable current value, defvar and asterisk, defvar, defvar
address@hidden
address@hidden Seeing the Current Value of a Variable
address@hidden ifnottex
address@hidden 1200
-Now, to return to the first two lines in the body of the function:
+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
address@hidden:
@smallexample
@group
- (and (fboundp 'menu-bar-update-yank-menu)
- (menu-bar-update-yank-menu string (and replace (car kill-ring))))
+Documentation:
+List of killed text sequences.
+Since the kill ring is supposed to interact nicely with cut-and-paste
+facilities offered by window systems, use of this variable should
address@hidden group
address@hidden
+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
address@hidden
-This is an expression whose first element is the function @code{and}.
-
address@hidden 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
address@hidden 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
address@hidden, it is considered true in Emacs Lisp.) In other words, an
address@hidden expression returns a true value only if all its arguments
-are true.
address@hidden and
-
-In this case, the expression tests first to see whether
address@hidden 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}).
-
address@hidden 1200
-Essentially, the @code{and} is an @code{if} expression that reads like
-this:
address@hidden 800
+The kill ring is defined by a @code{defvar} in the following way:
@smallexample
@group
-if @var{the-menu-bar-function-exists}
- then @var{execute-it}
+(defvar kill-ring nil
+ "List of killed text sequences.
address@hidden")
@end group
@end smallexample
address@hidden 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.
address@hidden
+In this variable definition, the variable is given an initial value of
address@hidden, 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}).
+
address@hidden defvar and asterisk, , See variable current value, defvar
address@hidden @code{defvar} and an asterisk
address@hidden defvar @r{for a user customizable variable}
address@hidden 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
address@hidden instead, since that special form provides a path into
+the Customization commands. (@xref{defcustom, , Specifying Variables
+using @code{defcustom}}.)
address@hidden 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.
address@hidden ")
@end group
@end smallexample
-If an @code{interprogram-cut-function} exists, then Emacs executes
address@hidden, 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.
-
-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'.
address@hidden set-variable
address@hidden
+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}.
address@hidden Initialization, , Your @file{.emacs} File}.
+
+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
address@hidden set-variable} command to see the list of variables.
+(@xref{Examining, , Examining and Setting Variables, emacs,
+The GNU Emacs Manual}.)
@need 1250
address@hidden cons & search-fwd Review, search Exercises, copy-region-as-kill,
Cutting & Storing Text
address@hidden cons & search-fwd Review, search Exercises, defvar, Cutting &
Storing Text
@comment node-name, next, previous, up
@section Review
@@ -8856,14 +9634,15 @@
buffer and stores that text in the kill ring, so you can get it back
by yanking.
address@hidden 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
address@hidden 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
@@ -8904,7 +9683,7 @@
@menu
* Lists diagrammed::
-* Symbols as Chest:: Exploring a powerful metaphor.
+* Symbols as Chest::
* List Exercise::
@end menu
@@ -9385,8 +10164,8 @@
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
@@ -9422,6 +10201,15 @@
(insert (car kill-ring-yank-pointer))
@end smallexample
address@hidden
+(Well, no more. In GNU Emacs 22, the function has been replaced by
address@hidden which calls @code{insert-for-yank-1}
+repetitively for each @code{yank-handler} segment. In turn,
address@hidden 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.
@@ -9525,15 +10313,46 @@
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
address@hidden function itself is not difficult, but
-contains many details. It and the much simpler @code{yank} and
address@hidden functions are described in an appendix.
address@hidden Ring, , Handling the Kill Ring}.
+
address@hidden
+In GNU Emacs 22, the @code{kill-new} function calls
+
address@hidden(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)))))
+
address@hidden ignore
@need 1500
@node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking
@@ -9584,9 +10403,9 @@
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
@@ -9621,11 +10440,11 @@
@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
@@ -9776,8 +10595,9 @@
@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,
address@hidden 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
@@ -9787,8 +10607,10 @@
You can copy the expressions by marking the beginning of the region
with @address@hidden (@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
@@ -9801,7 +10623,7 @@
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.
@@ -9882,9 +10704,9 @@
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
@@ -9967,9 +10789,9 @@
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
@@ -10092,7 +10914,7 @@
(let (@var{varlist})
(while (@var{true-or-false-test})
@address@hidden )
- @dots{} ) ; @r{Need final expression here.}
+ @dots{} )) ; @r{Need final expression here.}
@end group
@end smallexample
@@ -10190,9 +11012,9 @@
@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
@@ -10547,13 +11369,13 @@
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
@@ -10668,8 +11490,8 @@
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
@@ -10679,8 +11501,8 @@
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
@@ -11432,7 +12254,7 @@
@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
@@ -11548,7 +12370,7 @@
@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to
a Texinfo manual in the current directory. Or, if you are on the
Internet, see
address@hidden://www.gnu.org/manual/texinfo-4.6/html_node/Indicating.html}
address@hidden://www.gnu.org/software/texinfo/manual/texinfo/}
@end ifhtml
@iftex
``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU
@@ -11594,11 +12416,11 @@
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
@@ -11697,8 +12519,20 @@
@end group
@end smallexample
address@hidden
address@hidden
+(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},
address@hidden, @code{sentence-end-without-period},
+and @code{sentence-end-without-space}. The critical variable is
address@hidden; 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
address@hidden variable, when true, tells Emacs
+that a sentence may end without a period, such as text in Thai.)
address@hidden
@noindent
(Note that here the @key{TAB}, two spaces, and @key{RET} are shown
literally in the pattern.)
@@ -11739,7 +12573,6 @@
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
@@ -11802,7 +12635,7 @@
@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
@@ -11831,8 +12664,8 @@
@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
@@ -11843,6 +12676,44 @@
@need 1250
Here is the code for @code{forward-sentence}:
address@hidden in GNU Emacs 22
address@hidden
address@hidden
+(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."
address@hidden group
address@hidden
+ (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)))
address@hidden group
address@hidden
+ (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)))
address@hidden group
address@hidden smallexample
+
address@hidden
+GNU Emacs 21
@smallexample
@group
(defun forward-sentence (&optional arg)
@@ -11872,6 +12743,7 @@
(setq arg (1- arg))))
@end group
@end smallexample
address@hidden 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
@@ -11883,16 +12755,21 @@
"@address@hidden"
(interactive "p")
(or arg (setq arg 1))
+ (let ((opoint (point)) (sentence-end (sentence-end)))
(while (< arg 0)
- @var{body-of-while-loop}
+ (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)
- @var{body-of-while-loop}
+ (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.
@@ -11902,24 +12779,31 @@
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
address@hidden will be bound to 1. When @code{forward-sentence} is called
-non-interactively without an argument, @code{arg} is bound to
address@hidden 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
address@hidden function which handles forms and
+equivalents. The @code{sentence-end} variable is set by the
address@hidden 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
address@hidden 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
address@hidden is a negative number. This is for going
+backwards. The body of this loop is similar to the body of the second
address@hidden 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
@@ -12052,6 +12936,9 @@
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
@@ -12062,6 +12949,151 @@
@section @code{forward-paragraph}: a Goldmine of Functions
@findex forward-paragraph
address@hidden
address@hidden 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))
address@hidden ignore
+
The @code{forward-paragraph} function moves point forward to the end
of the paragraph. It is usually bound to @address@hidden and makes use of a
number of functions that are important in themselves, including
@@ -12091,14 +13123,9 @@
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
@@ -12121,12 +13148,10 @@
(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
@@ -12147,22 +13172,34 @@
@unnumberedsubsec The @code{let*} expression
The next line of the @code{forward-paragraph} function begins a
address@hidden expression. This is a different kind of expression than
-we have seen so far. The symbol is @code{let*} not @code{let}.
address@hidden 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}.
address@hidden
+( refappend save-excursion, , code save-excursion in code append-to-buffer .)
address@hidden ignore
address@hidden 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},
address@hidden, @code{parsep}, @code{sp-parstart}, @code{start}, and
address@hidden
+
+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
@@ -12226,49 +13263,44 @@
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
address@hidden It is bound to the value returned by
-evaluating the expression:
-
address@hidden
address@hidden
-(if fill-prefix-regexp
- (concat paragraph-separate
- "\\|^" fill-prefix-regexp "[ \t]*$")
- paragraph-separate)))
address@hidden group
address@hidden smallexample
-
-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
address@hidden evaluates to @code{nil} or some other value.
+The next two local variables in the @code{let*} expression are
+designed to remove instances of @samp{^} from @code{parstart} and
address@hidden, 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 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
address@hidden 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
address@hidden 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
address@hidden to a regular expression that includes the
address@hidden 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
address@hidden must begin a line, and the optional
-whitespace to the end of the line is defined by @address@hidden"[ \t]*$"}}.)
-The @samp{\\|} defines this portion of the regexp as an alternative to
address@hidden
+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 @address@hidden"[ \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,
address@hidden, is used for searching, and then the final two,
address@hidden 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.
address@hidden fwd-para while, fwd-para between paragraphs, fwd-para let,
forward-paragraph
address@hidden 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
@@ -12278,243 +13310,162 @@
@code{while} loop is evaluated exactly once, and the cursor moves
forward one paragraph.
-This part handles three situations: when point is between paragraphs,
-when point is within a paragraph and there is a fill prefix, and
-when point is within a paragraph and there is no fill prefix.
-
address@hidden 800
-The @code{while} loop looks like this:
-
address@hidden
address@hidden
-(while (> arg 0)
- (beginning-of-line)
address@hidden
+(while (and (> arg 0) (not (eobp)))
- ;; @r{between paragraphs}
- (while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
address@hidden group
+ ;; 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)
address@hidden
- ;; @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.
(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))
address@hidden group
address@hidden
- ;; @r{within paragraphs, no fill prefix}
- (if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max))))
- (setq arg (1- arg)))
address@hidden group
address@hidden smallexample
+ (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))
-We can see immediately that this is a decrementing counter @code{while}
-loop, using the expression @code{(setq arg (1- arg))} as the decrementer.
+ (if (< (point) (point-max))
+ (goto-char start))))
address@hidden ignore
+
+This part handles three situations: when point is between paragraphs,
+when there is a fill prefix and when there is no fill prefix.
@need 800
-The body of the loop consists of three expressions:
+The @code{while} loop looks like this:
@smallexample
@group
-;; @r{between paragraphs}
-(beginning-of-line)
-(while
- @var{body-of-while})
address@hidden group
-
address@hidden
-;; @r{within paragraphs, with fill prefix}
-(if @var{true-or-false-test}
- @var{then-part}
address@hidden group
+;; @r{going forwards and not at the end of the buffer}
+(while (and (> arg 0) (not (eobp)))
address@hidden
-;; @r{within paragraphs, no fill prefix}
- @var{else-part}
+ ;; @r{between paragraphs}
+ ;; Move forward over separator lines...
+ (while (and (not (eobp))
+ (progn (move-to-left-margin) (not (eobp)))
+ (looking-at parsep))
+ (forward-line 1))
+ ;; @r{This decrements the loop}
+ (unless (eobp) (setq arg (1- arg)))
+ ;; ... and one more line.
+ (forward-line 1)
@end group
address@hidden smallexample
-
address@hidden
-When the Emacs Lisp interpreter evaluates the body of the
address@hidden loop, the first thing it does is evaluate the
address@hidden(beginning-of-line)} expression and move point to the beginning
-of the line. Then there is an inner @code{while} loop. This
address@hidden 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.
-
address@hidden fwd-para between paragraphs, fwd-para within paragraph, fwd-para
while, forward-paragraph
address@hidden 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}.
address@hidden prog1
address@hidden eobp
address@hidden looking-at
address@hidden @bullet
address@hidden
address@hidden 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
address@hidden are evaluated only for their side effects.
-
address@hidden
address@hidden 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.
-
address@hidden
address@hidden is a function that returns true if the text following
-point matches the regular expression passed @code{looking-at} as its
-argument.
address@hidden itemize
-
address@hidden 800
-The @code{while} loop we are studying looks like this:
-
address@hidden
@group
-(while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
+ (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
address@hidden smallexample
-
address@hidden 1200
address@hidden
-This is a @code{while} loop with no body! The true-or-false-test of the
-loop is the expression:
address@hidden
@group
-(prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1))
+ ;; 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
address@hidden smallexample
address@hidden
-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
address@hidden, 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
address@hidden expression tests false. Note however, that the
address@hidden 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.
-
address@hidden fwd-para within paragraph, fwd-para no fill prefix, fwd-para
between paragraphs, forward-paragraph
address@hidden 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
address@hidden when the @code{fill-prefix-regexp} variable has a value other
-than @code{nil}, and it evaluates the else-part when the value of
address@hidden fill-prefix-regexp} is @code{nil}, that is, when there is no
-fill prefix.
-
address@hidden fwd-para no fill prefix, fwd-para with fill prefix, fwd-para
within paragraph, forward-paragraph
address@hidden No fill prefix
-
-It is simplest to look at the code for the case when there is no fill
-prefix first. This code consists of yet another inner @code{if}
-expression, and reads as follows:
-
address@hidden
@group
-(if (re-search-forward paragraph-start nil t)
- (goto-char (match-beginning 0))
- (goto-char (point-max)))
+ ;; 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
address@hidden
-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.
-
-The only unfamiliar part of this is the use of @code{match-beginning}.
-This is another function that is new to us. The
address@hidden 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} 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
address@hidden, which will be the beginning of the next
-paragraph rather than the end of the current one.
-
-However, we want to put point at the end of the current paragraph, not at
-the beginning of the next one. The two positions may be different,
-because there may be several blank lines between paragraphs.
-
address@hidden 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
address@hidden returns the beginning position of the pattern,
-rather than the end of the pattern. The beginning position is the end
-of the paragraph.
address@hidden 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
address@hidden, 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
address@hidden 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.
-(Incidentally, when passed a positive number as an argument, the
address@hidden function will place point at that parenthesized
-expression in the last regular expression. It is a useful function.)
address@hidden 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.
address@hidden fwd-para with fill prefix, fwd-para summary, fwd-para no fill
prefix, forward-paragraph
address@hidden With a fill prefix
+The rest of the body of the loop looks difficult at first, but makes
+sense as you come to understand it.
-The inner @code{if} expression just discussed is the else-part of an enclosing
address@hidden 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:
address@hidden 800
+First consider what happens if there is a fill prefix:
@smallexample
@group
-(while (and (not (eobp))
- (not (looking-at paragraph-separate))
+ (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
-What this expression does is move point forward line by line so long
-as three conditions are true:
+This expression moves point forward line by line so long
+as four conditions are true:
@enumerate
@item
Point is not at the end of the buffer.
@item
+We can move to the left margin of the text and are
+not at the end of the buffer.
+
address@hidden
The text following point does not separate paragraphs.
@item
@@ -12526,101 +13477,93 @@
function. This means that if the text has a fill prefix, the
@code{looking-at} function will see it.
address@hidden fwd-para summary, , fwd-para with fill prefix, forward-paragraph
address@hidden Summary
-
-In summary, when moving forward, the @code{forward-paragraph} function
-does the following:
-
address@hidden @bullet
address@hidden
-Move point to the beginning of the line.
-
address@hidden
-Skip over lines between paragraphs.
-
address@hidden
-Check whether there is a fill prefix, and if there is:
-
address@hidden ---
-
address@hidden
-Go forward line by line so long as the line is not a paragraph
-separating line.
address@hidden itemize
-
address@hidden
-But if there is no fill prefix,
-
address@hidden ---
-
address@hidden
-Search for the next paragraph start pattern.
address@hidden 1250
+Consider what happens when there is no fill prefix.
address@hidden
-Go to the beginning of the paragraph start pattern, which will be the
-end of the previous paragraph.
address@hidden
address@hidden
+ (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))
address@hidden group
address@hidden smallexample
address@hidden
-Or else go to the end of the accessible portion of the buffer.
address@hidden itemize
address@hidden itemize
address@hidden
+This @code{while} loop has us searching forward for
address@hidden, 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
address@hidden(?:} so that they are not referenced by the
address@hidden function.)
address@hidden 1200
-For review, here is the code we have just been discussing, formatted
-for clarity:
address@hidden 800
+The two expressions,
@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)))
+(setq start (match-beginning 0))
+(goto-char start)
@end group
address@hidden smallexample
address@hidden
- (paragraph-separate
- (if fill-prefix-regexp
- (concat paragraph-separate
- "\\|^"
- fill-prefix-regexp
- "[ \t]*$")
- paragraph-separate)))
address@hidden
+mean go to the start of the text matched by the regular expression
+search.
- @var{omitted-backward-moving-code} @dots{}
address@hidden group
+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.
address@hidden
- (while (> arg 0) ; @r{forward-moving-code}
- (beginning-of-line)
+The @code{match-beginning} function is used here because of a
+characteristic of a forward search: a successful forward search,
+regardless of whether it is a plain search or a regular expression
+search, moves point to the end of the text that is found. In this
+case, a successful search moves point to the end of the pattern for
address@hidden
+
+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}.
+
address@hidden match-beginning
+When given an argument of 0, @code{match-beginning} returns the
+position that is the start of the text matched by the most recent
+search. In this case, the most recent search looks for
address@hidden 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
address@hidden 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.)
- (while (prog1 (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1)))
address@hidden group
address@hidden 1250
+The last expression when there is no fill prefix is
address@hidden
@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))
address@hidden group
address@hidden
- ; @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
address@hidden
+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})
@@ -12631,26 +13574,25 @@
your sources! Without them, you are like a person who tries to drive
a car with his eyes shut!)
address@hidden !!! 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
address@hidden/usr/local/share/emacs/21.0.100/lisp/TAGS}. (The exact path to
your
address@hidden file depends on how your copy of Emacs was installed.)
-
-You can also create your own @file{TAGS} file for directories that
-lack one.
address@hidden
address@hidden, , Create Your Own @file{TAGS} File}.
address@hidden 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
address@hidden function first asks you for the name of a @file{TAGS}
+table, give it the name of a @file{TAGS} file such as
address@hidden/usr/local/src/emacs/src/TAGS}. (The exact path to your
address@hidden 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.
@@ -12720,11 +13662,11 @@
you want, but do not know where it is, you can use the @code{locate}
program to attempt to find it.
-Type @address@hidden 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 @address@hidden 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
address@hidden 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
@@ -12784,6 +13726,7 @@
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
@@ -12800,6 +13743,7 @@
@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.
@@ -12844,20 +13788,6 @@
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.
-
address@hidden prog1
-Evaluate each argument in sequence and then return the value of the
address@hidden
-
address@hidden 1250
-For example:
-
address@hidden
address@hidden
-(prog1 1 2 3 4)
- @result{} 1
address@hidden group
address@hidden smallexample
@end table
@need 1500
@@ -12891,8 +13821,8 @@
@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
@@ -12928,8 +13858,8 @@
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
address@hidden@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
@@ -12938,8 +13868,8 @@
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
@@ -13043,11 +13973,13 @@
@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
@@ -13312,21 +14244,21 @@
@iftex
@noindent
(For information about @code{and}, see
address@hidden, , @code{forward-paragraph}: a Goldmine of
-Functions}.)
address@hidden 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!).
@@ -13590,6 +14522,7 @@
each word, the counting mechanism must be an expression that adds one
to the value returned by a call to @code{recursive-count-words}.
address@hidden 800
Consider several cases:
@itemize @bullet
@@ -13776,15 +14709,15 @@
@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
@@ -14161,7 +15094,7 @@
@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.
@@ -14223,9 +15156,7 @@
problem.
@need 1200
-Let's look at the source for @code{find-file} (you can use the
address@hidden 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
@@ -14238,18 +15169,54 @@
@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}.
address@hidden
+(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
address@hidden (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).)
+
address@hidden
+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))))
address@hidden 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
address@hidden
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}.)
@@ -14345,10 +15312,10 @@
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
@@ -14358,20 +15325,29 @@
place your cursor after the following expression and type @kbd{C-x
C-e} (@code{eval-last-sexp}).
address@hidden !!! 21.0.100 lisp sources location here
address@hidden !!! 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")
address@hidden !!! as of 21, Info file is in
address@hidden /usr/share/info/emacs-lisp-intro.info.gz
address@hidden but debug.el is in
/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/debug.el
address@hidden
+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")
address@hidden 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
@@ -14389,10 +15365,10 @@
@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
@@ -14421,8 +15397,8 @@
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
@@ -14499,11 +15475,19 @@
name to the absolute, long, path name form of the directory in which
the function is called.
address@hidden !!! 21.0.100 lisp sources location here
address@hidden
+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")
address@hidden ignore
+
address@hidden !!! 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
address@hidden/usr/local/share/emacs/21.0.100/lisp/emacs-lisp/} directory,
address@hidden/usr/local/share/emacs/22.0.100/lisp/emacs-lisp/} directory,
@smallexample
debug.el
@@ -14513,9 +15497,9 @@
@noindent
becomes
address@hidden !!! 21.0.100 lisp sources location here
address@hidden !!! 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
@@ -14604,34 +15588,69 @@
the @file{*scratch*} buffer, edit them, and then evaluate them.
The results are shown after the @address@hidden (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.)
address@hidden !!! 21.0.100 lisp sources location here
address@hidden
+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")
address@hidden ignore
+
address@hidden !!! 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
address@hidden
+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")
address@hidden 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
address@hidden
+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")
address@hidden ignore
+
@group
(lengths-list-file "./lisp/makesum.el")
@result{} (85 181)
@end group
address@hidden
+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")))
address@hidden ignore
+
@group
-(recursive-lengths-list-many-files
+ (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)
+ @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181)
@end group
@end smallexample
@@ -14671,8 +15690,8 @@
that we will need.
@menu
-* Sorting:: Sorting lists.
-* Files List:: Making a list of files.
+* Sorting::
+* Files List::
* Counting function definitions::
@end menu
@@ -14717,13 +15736,27 @@
@code{recursive-lengths-list-many-files} function is straightforward;
it uses the @code{<} function:
address@hidden
+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"))
+ '<))
+
address@hidden 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
@@ -14733,7 +15766,7 @@
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
@@ -14779,9 +15812,9 @@
@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
@@ -14793,55 +15826,76 @@
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}.
address@hidden
+(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))
address@hidden ignore
+
+
For example, the first @samp{.el} file in the @file{lisp/} directory
is @file{abbrev.el}. Its name is
address@hidden/usr/local/share/emacs/21.0.100/lisp/abbrev.el} and it is not a
address@hidden/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:
address@hidden
+(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) ...)
address@hidden 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
address@hidden
+(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) ...)
address@hidden 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
address@hidden 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
address@hidden Bear in mind that the @code{file-attributes}
+function does not list the filename, so its first element is
address@hidden'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
@@ -14893,11 +15947,14 @@
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
address@hidden /usr/local/share/emacs/21.0.100/lisp/
address@hidden /usr/local/share/emacs/22.0.100/lisp/
@need 800
Here is the function:
@@ -14909,7 +15966,7 @@
;; 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
@@ -14953,7 +16010,8 @@
@end group
@end smallexample
address@hidden (files-in-below-directory
"/usr/local/share/emacs/21.0.100/lisp/")
address@hidden (files-in-below-directory "/usr/local/src/emacs/lisp/")
address@hidden (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.
@@ -14961,17 +16019,19 @@
@need 1250
Thus, on my system,
address@hidden !!! 21.0.100 lisp sources location here
address@hidden (length (files-in-below-directory "/usr/local/src/emacs/lisp/"))
+
address@hidden !!! 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
address@hidden 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
@@ -14980,24 +16040,21 @@
@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
@@ -15259,11 +16316,14 @@
@c colon in printed section title causes problem in Info cross reference
This way, we avoid an error.
@iftex
address@hidden, , @code{forward-paragraph}: a Goldmine of
-Functions}, for more information about @code{and}.
address@hidden
+(For information about @code{and}, see
address@hidden function, , The @code{kill-new} function}.)
@end iftex
@ifinfo
address@hidden, for more information about @code{and}.
address@hidden
+(@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,
@@ -15301,7 +16361,6 @@
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
@@ -15328,7 +16387,7 @@
@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::
@@ -15363,7 +16422,7 @@
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.
@@ -15374,9 +16433,11 @@
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
address@hidden
@need 1200
Indeed, this is the function we want; its documentation says:
@@ -15388,6 +16449,8 @@
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
@@ -15403,8 +16466,7 @@
@group
(insert-rectangle '("first" "second" "third"))first
second
- third
-nil
+ thirdnil
@end group
@end smallexample
@@ -15418,12 +16480,14 @@
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
address@hidden 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
@@ -15983,20 +17047,20 @@
@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
@@ -16011,7 +17075,11 @@
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
@@ -16169,8 +17237,8 @@
@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
@@ -16183,24 +17251,22 @@
@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
address@hidden 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.
address@hidden 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
@@ -16221,7 +17287,7 @@
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
@@ -16338,12 +17404,11 @@
@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
@@ -16404,33 +17469,28 @@
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
address@hidden to the variable called
address@hidden and then adds @code{turn-on-auto-fill} to the
-variable.
+In this line, the @code{add-hook} command adds
address@hidden 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
@@ -16439,11 +17499,10 @@
@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
@@ -16785,7 +17844,10 @@
(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
@@ -16822,12 +17884,12 @@
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
@@ -16916,18 +17978,18 @@
@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
@@ -16940,6 +18002,10 @@
@smallexample
emacs -q --no-site-file -eval '(blink-cursor-mode nil)'
+
address@hidden Or nowadays, using an even more sophisticated set of options,
+
+emacs -Q - D
@end smallexample
}:
@@ -17055,16 +18121,12 @@
@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 address@hidden
-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 address@hidden 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
address@hidden
-# I use TWM for window manager.
xsetroot -solid Navy -fg white &
address@hidden group
@end smallexample
@node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization
@@ -17076,6 +18138,7 @@
@itemize @minus
@item
Set the shape and color of the mouse cursor:
+
@smallexample
@group
; Cursor shapes are defined in
@@ -17099,6 +18162,32 @@
@end smallexample
@item
+Or you can set the values of a variety of features in an alist, like
+this:
+
address@hidden
address@hidden
+(setq-default
+ default-frame-alist
+ '((cursor-color . "white")
+ (mouse-color . "white")
+ (foreground-color . "white")
+ (background-color . "DodgerBlue4")
+ ;; (cursor-type . bar)
+ (cursor-type . box)
address@hidden group
address@hidden
+ (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")
+ ))
address@hidden group
address@hidden smallexample
+
address@hidden
Convert @address@hidden into @key{DEL} and @key{DEL}
into @address@hidden@*
(Some older keyboards needed this, although I have not seen the
@@ -17123,6 +18212,9 @@
@end group
@end smallexample
address@hidden
+or start GNU Emacs with the command @code{emacs -nbc}.
+
@item Ignore case when using `grep'@*
@address@hidden } Prefix each line of output with line address@hidden
@address@hidden } Ignore case address@hidden
@@ -17132,11 +18224,16 @@
(setq grep-command "grep -n -i -e ")
@end smallexample
address@hidden Automatically uncompress compressed files when visiting them
address@hidden
address@hidden Evidently, no longer needed in GNU Emacs 22
address@hidden
+item Automatically uncompress compressed files when visiting them
+
+smallexample
(load "uncompress")
address@hidden smallexample
+end smallexample
+
address@hidden ignore
@item Find an existing buffer, even if it has a different address@hidden
This avoids problems with symbolic links.
@@ -17305,8 +18402,8 @@
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:
@@ -17344,7 +18441,7 @@
characters; this length works well in a typical 80 column wide
window.)
address@hidden:eval} is a new feature in GNU Emacs version 21. It says to
address@hidden: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'),
@@ -17399,10 +18496,10 @@
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
@@ -17479,6 +18576,7 @@
tell you what you need to know to correct the definition. The
function @code{1=} is `void'.
address@hidden
@need 800
In GNU Emacs 20 and before, you will see:
@@ -17489,11 +18587,12 @@
@noindent
which has the same meaning as the @file{*Backtrace*} buffer line in
version 21.
address@hidden 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.
@@ -17535,14 +18634,18 @@
@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.
+
address@hidden
+GNU Emacs version 20 and before did not; it simply
presented you with an error message. You had to start the debugger
manually.
address@hidden 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}.
@@ -17796,13 +18899,13 @@
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:
@@ -17872,7 +18975,7 @@
@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
@@ -17922,8 +19025,8 @@
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
@@ -17932,21 +19035,16 @@
function, for example, looks complicated.
You may want to walk through this function slowly, as we did with the
address@hidden function.
address@hidden
-(@xref{forward-sentence}.)
address@hidden ifnottex
address@hidden
-(@xref{forward-sentence, , @code{forward-sentence}}.)
address@hidden iftex
-Or you may want to skip that function and look at another, such as
address@hidden 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.
address@hidden function. (@xref{forward-sentence, The
address@hidden 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
address@hidden, the @code{split-line} function contains
+102 words and symbols.
-Even though it is short, @code{split-line} contains four expressions
+Even though it is short, @code{split-line} contains expressions
we have not studied: @code{skip-chars-forward}, @code{indent-to},
address@hidden and @samp{?\n}.
address@hidden 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
@@ -17974,25 +19072,17 @@
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
address@hidden 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
address@hidden 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
address@hidden
Other interesting source files include @file{paragraphs.el},
@file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el}
@@ -18115,162 +19205,375 @@
You can substitute the other regular expressions shown above in the
function definition and try each of them on this list.
address@hidden done til here 2006 Oct 29
+
address@hidden
+
+
+
address@hidden ignore
+
+
address@hidden
+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 (address@hidden)
+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.
+
address@hidden 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{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.
+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
address@hidden 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.
+
address@hidden 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:
+
address@hidden
address@hidden
+(setq old-kill-ring-max kill-ring-max)
+(setq kill-ring-max 4)
address@hidden group
address@hidden smallexample
+
address@hidden
+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}.
+
address@hidden
+(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.)
+
address@hidden 1250
address@hidden
+Please invoke the calls in order, so that five elements attempt to
+fill the kill ring:
+
address@hidden
address@hidden
+first some text
+second piece of text
+third line
+fourth line of text
+fifth bit of text
address@hidden group
address@hidden smallexample
+
address@hidden 1250
address@hidden
+Then find the value of @code{kill-ring} by evaluating
+
address@hidden
+kill-ring
address@hidden smallexample
+
address@hidden 800
address@hidden
+It is:
+
address@hidden
address@hidden
+("fifth bit of text" "fourth line of text"
+"third line" "second piece of text")
address@hidden group
address@hidden smallexample
+
address@hidden
+The first element, @samp{first some text}, was dropped.
+
address@hidden 1250
+To return to the old value for the length of the kill ring, evaluate:
+
address@hidden
+(setq kill-ring-max old-kill-ring-max)
address@hidden 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
address@hidden rotate-yank-pointer, yank, Kill Ring, Kill Ring
address@hidden current-kill, yank, Kill Ring, Kill Ring
@comment node-name, next, previous, up
address@hidden The @code{rotate-yank-pointer} Function
address@hidden rotate-yank-pointer
address@hidden The @code{current-kill} Function
address@hidden 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
address@hidden function sets @code{kill-ring-yank-pointer} to point
+to the latest element of the the kill ring.)
address@hidden 800
-Here is the code for @code{rotate-yank-pointer}:
address@hidden 1500
+The @code{current-kill} function is used by @code{yank} and by
address@hidden 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)
address@hidden group
address@hidden
+ (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
address@hidden to the latest element of the the kill
+ring. And indirectly so does @code{kill-append}, since it calls
address@hidden In addition, @code{kill-region} and @code{kill-line}
+call the @code{kill-new} function.
+
address@hidden 1500
+Here is the line in @code{kill-new}, which is explained in
address@hidden function, , The @code{kill-new} function}.
+
address@hidden
+(setq kill-ring-yank-pointer kill-ring)
address@hidden smallexample
+
@menu
-* Understanding rotate-yk-ptr::
-* rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}.
+* Understanding current-kill::
@end menu
address@hidden Understanding rotate-yk-ptr, rotate-yk-ptr body,
rotate-yank-pointer, rotate-yank-pointer
address@hidden Understanding current-kill, , current-kill, current-kill
@ifnottex
address@hidden @code{rotate-yank-pointer} in Outline
address@hidden @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}
@address@hidden)
@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
address@hidden 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
address@hidden (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.")
address@hidden 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.
-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.
+The @code{if} expression has two parts, one if there exists
address@hidden and one if not.
address@hidden rotate-yk-ptr body, , Understanding rotate-yk-ptr,
rotate-yank-pointer
address@hidden node-name, next, previous, up
address@hidden The Body of @code{rotate-yank-pointer}
address@hidden 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
address@hidden function}.)
-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.
address@hidden
address@hidden
+(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))
address@hidden group
address@hidden 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.
address@hidden
+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:
address@hidden 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
address@hidden 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.
address@hidden 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
address@hidden 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
address@hidden Digression concerning error, rotate-yk-ptr else-part,
rotate-yk-ptr body, rotate-yk-ptr body
address@hidden 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
@@ -18285,86 +19588,38 @@
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.)
-
address@hidden rotate-yk-ptr else-part, Remainder Function, Digression
concerning error, rotate-yk-ptr body
address@hidden 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:
-
address@hidden
address@hidden
-(setq kill-ring-yank-pointer
- (nthcdr (% (+ arg
- (- length
- (length kill-ring-yank-pointer)))
- length)
- kill-ring)))))
address@hidden group
address@hidden 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
address@hidden 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
address@hidden points to. If
address@hidden 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
address@hidden 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.
-
address@hidden 1250
-That is, under these circumstances,
+`cancel' would have a clearer connotation.
address@hidden
address@hidden
-(setq kill-ring-yank-pointer
- ("some text" "a different piece of text" "yet more text"))
address@hidden Determining the Element , , Digression concerning error,
Understanding current-kill
address@hidden
address@hidden Determining the Element
address@hidden ifnottex
-(setq kill-ring
- ("some text" "a different piece of text" "yet more text"))
address@hidden group
address@hidden smallexample
+Among other actions, the else-part of the @code{if} expression sets
+the value of @code{kill-ring-yank-pointer} to
address@hidden when the kill ring has something in it and
+the value of @code{do-not-move} is @code{nil}.
@need 800
address@hidden
-the code should do this:
-
address@hidden
-(setq kill-ring-yank-pointer (cdr kill-ring))
address@hidden smallexample
-
address@hidden 1000
address@hidden
-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
address@hidden points.
+That is what the
address@hidden@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
address@hidden 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
@@ -18381,477 +19636,222 @@
@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:
-
address@hidden
address@hidden
-(% (+ arg
- (- length
- (length kill-ring-yank-pointer)))
- length)
address@hidden group
address@hidden 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
address@hidden 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:
-
address@hidden
-(- length (length kill-ring-yank-pointer))
address@hidden smallexample
-
address@hidden
-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
address@hidden 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
address@hidden points to the first element of the kill
-ring, just as @code{kill-ring} does, and see what happens when
address@hidden is called with an argument of 1.
-
-The variable @code{length} and the value of the expression
address@hidden(length kill-ring-yank-pointer)} will be the same since the
-variable @code{length} is the length of the kill ring and the
address@hidden is pointing to the whole kill ring.
-Consequently, the value of
-
address@hidden
-(- length (length kill-ring-yank-pointer))
address@hidden smallexample
-
address@hidden
-will be zero. Since the value of @code{arg} will be 1, this will mean
-that the value of the whole expression
-
address@hidden
-(+ arg (- length (length kill-ring-yank-pointer)))
address@hidden smallexample
-
address@hidden
-will be 1.
-
address@hidden 1200
-Consequently, the argument to @code{nthcdr} will be found as the result of
-the expression
-
address@hidden
-(% 1 length)
address@hidden smallexample
-
address@hidden Remainder Function, rotate-yk-ptr remainder, rotate-yk-ptr
else-part, rotate-yk-ptr body
address@hidden 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:
-
address@hidden @bullet
address@hidden
-5 divided by 5 is 1 with a remainder of 0;
-
address@hidden
-6 divided by 5 is 1 with a remainder of 1;
-
address@hidden
-7 divided by 5 is 1 with a remainder of 2.
-
address@hidden
-Similarly, 10 divided by 5 is 2 with a remainder of 0;
-
address@hidden
-11 divided by 5 is 2 with a remainder of 1;
-
address@hidden
-12 divided by 5 is 1 with a remainder of 2.
address@hidden itemize
-
address@hidden 1250
address@hidden
-By considering the cases as parallel, we can see that
-
address@hidden @bullet
address@hidden
-zero divided by 5 must be zero with a remainder of zero;
-
address@hidden
-1 divided by 5 must be zero with a remainder of 1;
-
address@hidden
-2 divided by 5 must be zero with a remainder of 2;
address@hidden itemize
-
address@hidden
-and so on.
-
address@hidden 1250
-So, in this code, if the value of @code{length} is 5, then the result of
-evaluating
-
address@hidden
-(% 1 5)
address@hidden smallexample
-
address@hidden
-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.)
-
address@hidden 2000
address@hidden rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder
Function, rotate-yk-ptr body
address@hidden 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
address@hidden is 1, the @code{%} expression returns 1:
-
address@hidden
address@hidden
-(- length (length kill-ring-yank-pointer))
- @result{} 0
address@hidden group
address@hidden smallexample
-
address@hidden 1250
address@hidden
-therefore,
+Thus,
@smallexample
@group
-(+ arg (- length (length kill-ring-yank-pointer)))
+(mod 12 4)
+ @result{} 0 ;; @r{because there is no remainder}
+(mod 13 4)
@result{} 1
@end group
@end smallexample
@need 1250
address@hidden
-and consequently:
+In this case, the first argument is often smaller than the second.
+That is fine.
@smallexample
@group
-(% (+ arg (- length (length kill-ring-yank-pointer)))
- length)
+(mod 0 4)
+ @result{} 0
+(mod 1 4)
@result{} 1
@end group
@end smallexample
address@hidden
-regardless of the value of @code{length}.
-
address@hidden 1250
address@hidden
-As a result of this, the @code{setq kill-ring-yank-pointer} expression
-simplifies to:
-
address@hidden
-(setq kill-ring-yank-pointer (nthcdr 1 kill-ring))
address@hidden smallexample
-
address@hidden
-What it does is now easy to understand. Instead of pointing as it did
-to the first element of the kill ring, the
address@hidden 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
address@hidden is 1.
+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.
address@hidden kill-rng-yk-ptr last elt, , rotate-yk-ptr remainder,
rotate-yk-ptr body
address@hidden 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
address@hidden 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:
-
address@hidden
-(% (+ arg (- length (length kill-ring-yank-pointer))) length)
address@hidden smallexample
+And @code{n} is the name of the required argument to the
address@hidden function.
@need 1250
-When the variables are replaced by their numeric values, the expression
-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
-(% (+ 1 (- 5 1)) 5)
address@hidden
+;; 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"))
address@hidden group
@end smallexample
address@hidden
-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
address@hidden 1250
+When the first argument to the @code{current-kill} function is one,
+the @code{nthcdr} expression returns the list without its first
+element.
@smallexample
-(setq kill-ring-yank-pointer (nthcdr 0 kill-ring))
address@hidden
+(nthcdr (mod (- 1 4) 4)
+ '("fourth line of text"
+ "third line"
+ "second piece of text"
+ "first some text"))
address@hidden group
@end smallexample
address@hidden
-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?)
address@hidden @samp{global variable} defined
address@hidden @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
address@hidden (@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).
address@hidden yank, yank-pop, rotate-yank-pointer, Kill Ring
address@hidden 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:
address@hidden 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)))
address@hidden group
address@hidden 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
address@hidden, 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
address@hidden"*P"}. This means it will not work on a read-only buffer, and
that
-the unprocessed prefix argument is passed to the function.
-
address@hidden
-* rotate-yk-ptr arg:: Pass the argument to
@code{rotate-yank-pointer}.
-* rotate-yk-ptr negative arg:: Pass a negative argument.
address@hidden menu
-
address@hidden rotate-yk-ptr arg, rotate-yk-ptr negative arg, yank, yank
address@hidden Passing the argument
-
-The hard part of @code{yank} is understanding the computation that
-determines the value of the argument passed to
address@hidden 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
address@hidden expressions will be a number and that number will be the
-argument passed to @code{rotate-yank-pointer}.
-
address@hidden 1250
-Laid out with comments, the code looks like this:
-
address@hidden
address@hidden
-(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}
@end group
address@hidden smallexample
-
address@hidden
-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
address@hidden 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
address@hidden inside of @code{yank} is zero. This means
-the pointer is not moved and the first element to which
address@hidden 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
address@hidden (@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
address@hidden 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
address@hidden 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.
-
address@hidden rotate-yk-ptr negative arg, , rotate-yk-ptr arg, yank
address@hidden 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 @address@hidden 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.
-
address@hidden
@group
-(% -1 5)
- @result{} -1
+ (insert-for-yank (current-kill (cond
+ ((listp arg) 0)
+ ((eq arg '-) -2)
+ (t (1- arg)))))
+ (if (consp arg)
+ ;; This is like exchange-point-and-mark,
+ ;; but doesn't activate the mark.
+ ;; It is cleaner to avoid activation, even though the command
+ ;; loop would deactivate the mark because we inserted text.
+ (goto-char (prog1 (mark t)
+ (set-marker (mark-marker) (point) (current-buffer)))))
@end group
-
@group
-(setq animals '(cats dogs elephants))
- @result{} (cats dogs elephants)
+ ;; 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
address@hidden smallexample
address@hidden
-(nthcdr 1 animals)
- @result{} (dogs elephants)
address@hidden 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.
address@hidden
-(nthcdr 0 animals)
- @result{} (cats dogs elephants)
address@hidden group
+However, before getting to that expression, the function set the value
+of @code{yank-window-start} to the position returned by the
address@hidden(window-start)} expression, the position at which the display
+currently starts. It also set @code{this-command} and pushed the
+mark.
+
+After it yanks the appropriate element, if the optional argument is a
address@hidden 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.)
address@hidden
-(nthcdr -1 animals)
- @result{} (cats dogs elephants)
address@hidden group
address@hidden 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
address@hidden 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:
address@hidden 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)
address@hidden group
address@hidden
- (set-mark (point))
- (insert (car kill-ring-yank-pointer))
- (if before (exchange-point-and-mark))))
+ (unless arg (setq arg 1))
+ (let ((inhibit-read-only t)
+ (before (< (point) (mark t))))
address@hidden group
address@hidden
+ (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)
address@hidden group
address@hidden
+ (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)
address@hidden group
address@hidden
+ (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
@@ -18859,20 +19859,20 @@
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.
+
address@hidden calls its first argument as a function, passing
+remaining arguments to it. The first argument is whatever the
address@hidden 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
@@ -18895,10 +19895,10 @@
@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
@@ -19073,11 +20073,11 @@
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
@@ -19129,10 +20129,7 @@
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
address@hidden)
+as this or in the Emacs Lisp sources.
You can try the @code{%} function by evaluating the following two
expressions:
@@ -19515,8 +20512,8 @@
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
@@ -19864,13 +20861,13 @@
@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
- [Emacs-diffs] Changes to emacs/lispintro/emacs-lisp-intro.texi,v,
Robert J. Chassell <=