From 5fb9c53c678be2bbfdf038eae7f80167014c8e87 Mon Sep 17 00:00:00 2001 From: "Robert J. Chassell" Date: Mon, 30 Oct 2006 22:15:21 +0000 Subject: * emacs-lisp-intro.texi: Many changes since it turned out that many `simple' functions were rewritten. Changes to the text regarding zap-to-char, mark-whole-buffer, append-to-buffer, copy-to-buffer, beginning-of-buffer, what-line, and possibly others. (I have not reviewed all yet.) This instance does build for Info and TeX. --- lispintro/emacs-lisp-intro.texi | 6275 +++++++++++++++++++++++---------------- 1 file changed, 3636 insertions(+), 2639 deletions(-) (limited to 'lispintro/emacs-lisp-intro.texi') diff --git a/lispintro/emacs-lisp-intro.texi b/lispintro/emacs-lisp-intro.texi index cb04acc2062..0318b2b2c79 100644 --- a/lispintro/emacs-lisp-intro.texi +++ b/lispintro/emacs-lisp-intro.texi @@ -1,5 +1,6 @@ \input ../man/texinfo @c -*-texinfo-*- -@c change above to \input texinfo if building on own. +@c \input texinfo @c -*-texinfo-*- +@c change to \input texinfo if building on own. @comment %**start of header @setfilename ../info/eintr @c setfilename emacs-lisp-intro.info @@ -23,19 +24,25 @@ @comment %**end of header -@set edition-number 2.14 -@set update-date 2004 Oct 12 +@set edition-number 2.15 +@set update-date 2006 Oct 30 @ignore ## Summary of shell commands to create various output formats: pushd /usr/local/src/emacs/lispintro/ + ## pushd /u/intro/ ## Info output makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi + ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/u/intro/emacs-lisp-intro.info")) + ## DVI output - texi2dvi emacs-lisp-intro.texi + texi2dvi /u/intro/emacs-lisp-intro.texi + + ## View DVI output; see below also + # xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 /u/intro/emacs-lisp-intro.dvi & ## HTML output makeinfo --html --no-split --verbose emacs-lisp-intro.texi @@ -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 @@ -63,7 +72,20 @@ ## View Info output with standalone reader info emacs-lisp-intro.info - ## popd + ## popd + +Need to explain defcustom see (elisp)Customization (elisp)Variable Definitions + defsubst + defconst + + + +# as user `root' +# insert thumbdrive + mtusb # mount -v -t ext3 /dev/sda /mnt + cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi + umtusb # umount -v /mnt +# remove thumbdrive @end ignore @@ -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 @@ This master menu first lists each chapter and index; then it lists every node in every chapter. @end ifnottex +@c >>>> Set pageno appropriately <<<< + +@c The first page of the Preface is a roman numeral; it is the first +@c right handed page after the Table of Contents; hence the following +@c setting must be for an odd negative number. + +@iftex +@global@pageno = -11 +@end iftex + @menu * Preface:: What to look for. * List Processing:: What is Lisp? @@ -371,34 +404,34 @@ Arguments Setting the Value of a Variable -* Using set:: Setting values. -* Using setq:: Setting a quoted value. -* Counting:: Using @code{setq} to count. +* Using set:: Setting values. +* Using setq:: Setting a quoted value. +* Counting:: Using @code{setq} to count. Practicing Evaluation -* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} - causes evaluation. -* Buffer Names:: Buffers and files are different. -* Getting Buffers:: Getting a buffer itself, not merely its name. -* Switching Buffers:: How to change to another buffer. -* Buffer Size & Locations:: Where point is located and the size of - the buffer. +* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} + causes evaluation. +* Buffer Names:: Buffers and files are different. +* Getting Buffers:: Getting a buffer itself, not merely its name. +* Switching Buffers:: How to change to another buffer. +* Buffer Size & Locations:: Where point is located and the size of + the buffer. * Evaluation Exercise:: How To Write Function Definitions * Primitive Functions:: -* defun:: The @code{defun} special form. -* Install:: Install a function definition. -* Interactive:: Making a function interactive. -* Interactive Options:: Different options for @code{interactive}. -* Permanent Installation:: Installing code permanently. -* let:: Creating and initializing local variables. -* if:: What if? -* else:: If--then--else expressions. -* Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. +* defun:: The @code{defun} special form. +* Install:: Install a function definition. +* Interactive:: Making a function interactive. +* Interactive Options:: Different options for @code{interactive}. +* Permanent Installation:: Installing code permanently. +* let:: Creating and initializing local variables. +* if:: What if? +* else:: If--then--else expressions. +* Truth & Falsehood:: What Lisp considers false and true. +* save-excursion:: Keeping track of point, mark, and buffer. * Review:: * defun Exercises:: @@ -473,6 +506,7 @@ The Definition of @code{insert-buffer} * 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 @@ Cutting and Storing Text * 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 @@ Cutting and Storing Text * 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 @@ The Body of @code{copy-region-as-kill} * kill-append function:: * kill-new function:: +Initializing a Variable with @code{defvar} + +* See variable current value:: +* defvar and asterisk:: + How Lists are Implemented * Lists diagrammed:: @@ -564,9 +598,9 @@ How Lists are Implemented 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 @@ Regular Expression Searches * 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 @@ Debugging Handling the Kill Ring -* rotate-yank-pointer:: Move a pointer along a list and around. +* current-kill:: * yank:: Paste a copy of a clipped element. -* yank-pop:: Insert first element pointed to. +* yank-pop:: Insert element pointed to. * ring file:: -The @code{rotate-yank-pointer} Function +The @code{current-kill} Function -* Understanding rotate-yk-ptr:: -* rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}. +* Understanding current-kill:: -The Body of @code{rotate-yank-pointer} +@code{current-kill} in Outline * Digression concerning error:: How to mislead humans, but not computers. -* rotate-yk-ptr else-part:: The else-part of the @code{if} expression. -* Remainder Function:: The remainder, @code{%}, function. -* rotate-yk-ptr remainder:: Using @code{%} in @code{rotate-yank-pointer}. -* kill-rng-yk-ptr last elt:: Pointing to the last element. - -@code{yank} - -* rotate-yk-ptr arg:: Pass the argument to @code{rotate-yank-pointer}. -* rotate-yk-ptr negative arg:: Pass a negative argument. +* Determining the Element:: A Graph with Labelled Axes @@ -778,16 +798,6 @@ Printing the Whole Graph @end detailmenu @end menu -@c >>>> Set pageno appropriately <<<< - -@c The first page of the Preface is a roman numeral; it is the first -@c right handed page after the Table of Contents; hence the following -@c setting must be for an odd negative number. - -@iftex -@global@pageno = -11 -@end iftex - @node Preface, List Processing, Top, Top @comment node-name, next, previous, up @unnumbered Preface @@ -809,11 +819,11 @@ files, read letters, write books---all these activities are kinds of 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 @@ think about functions now; functions are defined in @ref{Making 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 @@ like flowers in a field with a stone wall around them. @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 @@ term comes from the historical meaning of the word atom, which means using in the lists cannot be divided into any smaller parts and still mean the same thing as part of a program; likewise with numbers and single character symbols like @samp{+}. On the other hand, unlike an -atom, a list can be split into parts. (@xref{car cdr & cons, , -@code{car} @code{cdr} & @code{cons} Fundamental Functions}.) +ancient atom, a list can be split into parts. (@xref{car cdr & cons, +, @code{car} @code{cdr} & @code{cons} Fundamental Functions}.) In a list, atoms are separated from each other by whitespace. They can be right next to a parenthesis. @@ -1378,13 +1388,13 @@ C-e}: @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 @@ carry out. Instead, the symbol is used, perhaps temporarily, as a way of locating the definition or set of instructions. What we see is the name through which the instructions can be found. Names of people work the same way. I can be referred to as @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 @@ and attach them to names, and how to do this without confusing either 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 @@ Lisp interpreter to return a value and perhaps carry out a side effect; 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 @@ function definition, and vice-versa. @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 @@ Try evaluating this: @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 @@ Debugger entered--Lisp error: (void-function fill-column) (Remember, to quit the debugger and make the debugger window go away, type @kbd{q} in the @file{*Backtrace*} buffer.) +@ignore @need 800 In GNU Emacs 20 and before, you will produce an error message that says: @@ -1833,8 +1843,9 @@ Symbol's function definition is void:@: fill-column @end smallexample @noindent -(The message will go away away as soon as you move the cursor or type +(The message will go away as soon as you move the cursor or type another key.) +@end ignore @node Void Variable, , Void Function, Variables @comment node-name, next, previous, up @@ -1854,7 +1865,7 @@ type @kbd{C-x C-e}: @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 @@ Since @code{+} does not have a value bound to it, just the function definition, the error message reported that the symbol's value as a variable was void. +@ignore @need 800 In GNU Emacs version 20 and before, your error message will say: @@ -1899,7 +1911,8 @@ Symbol's value as variable is void:@: + @end example @noindent -The meaning is the same as in GNU Emacs 21. +The meaning is the same as in GNU Emacs 22. +@end ignore @node Arguments, set & setq, Variables, List Processing @comment node-name, next, previous, up @@ -1945,14 +1958,11 @@ to it at the same time. By contrast, in Emacs Lisp, a symbol cannot 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 @@ C-e}: @noindent The value will be a number two more than what you get by evaluating -@code{fill-column} alone. For me, this is 74, because the value of +@code{fill-column} alone. For me, this is 74, because my value of @code{fill-column} is 72. As we have just seen, an argument can be a symbol that returns a value @@ -2038,7 +2048,7 @@ the arguments to the function @code{concat} are the strings @w{@code{"The "}} and @w{@code{" red foxes."}} and the list @code{(number-to-string (+ 2 fill-column))}. -@c For Emacs 21, need number-to-string +@c For GNU Emacs 22, need number-to-string @smallexample (concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") @end smallexample @@ -2122,7 +2132,7 @@ is that @code{+} has tried to add the 2 to the value returned by 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 @@ addition had been passed the correct type of object, the value passed would have been a number, such as 37, rather than a symbol like @code{hello}. But then you would not have got the error message. +@ignore @need 1250 In GNU Emacs version 20 and before, the echo area displays an error message that says: @@ -2190,6 +2201,7 @@ Wrong type argument:@: number-or-marker-p, hello This says, in different words, the same as the top line of the @file{*Backtrace*} buffer. +@end ignore @node message, , Wrong Type of Argument, Arguments @comment node-name, next, previous, up @@ -2300,8 +2312,9 @@ resulting from the evaluation of @code{(- fill-column 32)} is inserted 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 @@ The following sections not only describe how @code{set} and @code{setq} 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 @@ positioning the cursor after the expression and typing @kbd{C-x C-e}. @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 @@ in the list and then at the function definition bound to that symbol. Then the instructions in the function definition are carried out. @item -A single-quote, @code{'}, tells the Lisp interpreter that it should +A single quotation mark, +@ifinfo +' +@end ifinfo +@ifnotinfo +@code{'} +@end ifnotinfo +, tells the Lisp interpreter that it should return the following expression as written, and not evaluate it as it would if the quote were not there. @@ -2584,13 +2604,11 @@ these. In another section, we will study the code of several other 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 @@ If you are reading this in Info inside of GNU Emacs, you can evaluate each of the following expressions by positioning the cursor after it and typing @kbd{C-x C-e}. -@smallexample +@example @group (buffer-name) (buffer-file-name) @end group -@end smallexample +@end example @noindent -When I do this, @file{"introduction.texinfo"} is the value returned by -evaluating @code{(buffer-name)}, and -@file{"/gnu/work/intro/introduction.texinfo"} is the value returned by -evaluating @code{(buffer-file-name)}. The former is the name of the -buffer and the latter is the name of the file. (In the expressions, the -parentheses tell the Lisp interpreter to treat @code{buffer-name} and -@code{buffer-file-name} as functions; without the parentheses, the -interpreter would attempt to evaluate the symbols as variables. -@xref{Variables}.) +When I do this in Info, the value returned by evaluating +@code{(buffer-name)} is @file{"*info*"}, and the value returned by +evaluating @code{(buffer-file-name)} is @file{nil}. + +On the other hand, while I am writing this Introduction, the value +returned by evaluating @code{(buffer-name)} is +@file{"introduction.texinfo"}, and the value returned by evaluating +@code{(buffer-file-name)} is +@file{"/gnu/work/intro/introduction.texinfo"}. + +@cindex @code{nil}, history of word +The former is the name of the buffer and the latter is the name of the +file. In Info, the buffer name is @file{"*info*"}. Info does not +point to any file, so the result of evaluating +@code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is +from the Latin word for `nothing'; in this case, it means that the +buffer is not associated with any file. (In Lisp, @code{nil} is also +used to mean `false' and is a synonym for the empty list, @code{()}.) + +When I am writing, the name of my buffer is +@file{"introduction.texinfo"}. The name of the file to which it +points is @file{"/gnu/work/intro/introduction.texinfo"}. + +(In the expressions, the parentheses tell the Lisp interpreter to +treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as +functions; without the parentheses, the interpreter would attempt to +evaluate the symbols as variables. @xref{Variables}.) In spite of the distinction between files and buffers, you will often find that people refer to a file when they mean a buffer and vice-versa. @@ -2698,23 +2734,25 @@ great city: once it was merely the place where cargo was warehoused temporarily before being loaded onto ships; then it became a business and cultural center in its own right. -Not all buffers are associated with files. For example, when you start -an Emacs session by typing the command @code{emacs} alone, without -naming any files, Emacs will start with the @file{*scratch*} buffer on -the screen. This buffer is not visiting any file. Similarly, a +Not all buffers are associated with files. For example, a +@file{*scratch*} buffer does not visit any file. Similarly, a @file{*Help*} buffer is not associated with any file. -@cindex @code{nil}, history of word -If you switch to the @file{*scratch*} buffer, type @code{(buffer-name)}, -position the cursor after it, and type @kbd{C-x C-e} to evaluate the -expression, the name @code{"*scratch*"} is returned and will appear in -the echo area. @code{"*scratch*"} is the name of the buffer. However, -if you type @code{(buffer-file-name)} in the @file{*scratch*} buffer and -evaluate that, @code{nil} will appear in the echo area. @code{nil} is -from the Latin word for `nothing'; in this case, it means that the -@file{*scratch*} buffer is not associated with any file. (In Lisp, -@code{nil} is also used to mean `false' and is a synonym for the empty -list, @code{()}.) +In the old days, when you lacked a @file{~/.emacs} file and started an +Emacs session by typing the command @code{emacs} alone, without naming +any files, Emacs started with the @file{*scratch*} buffer visible. +Nowadays, you will see a splash screen. You can follow one of the +commands suggested on the splash screen, visit a file, or press the +spacebar to reach the @file{*scratch*} buffer. + +If you switch to the @file{*scratch*} buffer, type +@code{(buffer-name)}, position the cursor after it, and then type +@kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"} +will be returned and will appear in the echo area. @code{"*scratch*"} +is the name of the buffer. When you type @code{(buffer-file-name)} in +the @file{*scratch*} buffer and evaluate that, @code{nil} will appear +in the echo area, just as it does when you evaluate +@code{(buffer-file-name)} in Info. Incidentally, if you are in the @file{*scratch*} buffer and want the value returned by an expression to appear in the @file{*scratch*} @@ -2771,18 +2809,20 @@ Here is an expression containing the function: @end smallexample @noindent -If you evaluate the expression in the usual way, @file{#} -appears in the echo area. The special format indicates that the -buffer itself is being returned, rather than just its name. +If you evaluate this expression in Info in Emacs in the usual way, +@file{#} 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 @@ But first, a brief introduction to the @code{switch-to-buffer} function. When you switched back and forth from Info to the @file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or -rather, to save typing, you probably typed just part of the name, such -as @code{*sc}, and then pressed your @kbd{TAB} key to cause it to -expand to the full name; and then typed your @kbd{RET} key.} when -prompted in the minibuffer for the name of the buffer to which you -wanted to switch. The keystrokes, @kbd{C-x b}, cause the Lisp -interpreter to evaluate the interactive function +rather, to save typing, you probably only typed @kbd{RET} if the +default buffer was @file{*scratch*}, or if it was different, then you +typed just part of the name, such as @code{*sc}, pressed your +@kbd{TAB} key to cause it to expand to the full name, and then typed +your @kbd{RET} key.} when prompted in the minibuffer for the name of +the buffer to which you wanted to switch. The keystrokes, @kbd{C-x +b}, cause the Lisp interpreter to evaluate the interactive function @code{switch-to-buffer}. As we said before, this is how Emacs works: different keystrokes call or run different functions. For example, @kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls @@ -2980,16 +3021,16 @@ symbol refers to it.) @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 @@ use. (@code{multiply-by-seven} will stay installed until you quit 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 @@ function, @code{multiply-by-seven}. When you do this, a @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 @@ value returned. If the returned value were displayed in the echo area 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 @@ will evaluate the outer list, passing the values of the second and subsequent elements of the list to the function @code{message}. As we have seen, @code{message} is an Emacs Lisp function especially -designed for sending a one line message to a user. (@xref{message, , The -@code{message} function}.) -In summary, the @code{message} function prints its first argument in the -echo area as is, except for occurrences of @samp{%d}, @samp{%s}, or -@samp{%c}. When it sees one of these control sequences, the function -looks to the second and subsequent arguments and prints the value of the -argument in the location in the string where the control sequence is -located. +designed for sending a one line message to a user. (@xref{message, , +The @code{message} function}.) In summary, the @code{message} +function prints its first argument in the echo area as is, except for +occurrences of @samp{%d} or @samp{%s} (and various other %-sequences +which we have not mentioned). When it sees a control sequence, the +function looks to the second or subsequent arguments and prints the +value of the argument in the location in the string where the control +sequence is located. In the interactive @code{multiply-by-seven} function, the control string is @samp{%d}, which requires a number, and the value returned by @@ -3476,62 +3518,67 @@ a function. (@xref{Interactive Codes, , Code Characters for @code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.) @need 1250 -For example, the character @samp{r} causes Emacs to pass the beginning -and end of the region (the current values of point and mark) to the -function as two separate arguments. It is used as follows: +Consider the function @code{zap-to-char}. Its interactive expression +is @smallexample -(interactive "r") +(interactive "p\ncZap to char: ") @end smallexample -On the other hand, a @samp{B} tells Emacs to ask for the name of a -buffer that will be passed to the function. When it sees a @samp{B}, -Emacs will ask for the name by prompting the user in the minibuffer, -using a string that follows the @samp{B}, as in @code{"BAppend to -buffer:@: "}. Not only will Emacs prompt for the name, but Emacs will -complete the name if you type enough of it and press @key{TAB}. +The first part of the argument to @code{interactive} is @samp{p}, with +which you are already familiar. This argument tells Emacs to +interpret a `prefix', as a number to be passed to the function. You +can specify a prefix either by typing @kbd{C-u} followed by a number +or by typing @key{META} followed by a number. The prefix is the +number of specified characters. Thus, if your prefix is three and the +specified character is @samp{x}, then you will delete all the text up +to and including the third next @samp{x}. If you do not set a prefix, +then you delete all the text up to and including the specified +character, but no more. + +The @samp{c} tells the function the name of the character to which to delete. -A function with two or more arguments can have information passed to -each argument by adding parts to the string that follows -@code{interactive}. When you do this, the information is passed to -each argument in the same order it is specified in the +More formally, a function with two or more arguments can have +information passed to each argument by adding parts to the string that +follows @code{interactive}. When you do this, the information is +passed to each argument in the same order it is specified in the @code{interactive} list. In the string, each part is separated from the next part by a @samp{\n}, which is a newline. For example, you -could follow @code{"BAppend to buffer:@: "} with a @samp{\n} and an -@samp{r}. This would cause Emacs to pass the values of point and mark -to the function as well as prompt you for the buffer---three arguments -in all. +can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }. +This causes Emacs to pass the value of the prefix argument (if there +is one) and the character. -In this case, the function definition would look like the following, -where @code{buffer}, @code{start}, and @code{end} are the symbols to -which @code{interactive} binds the buffer and the current values of the -beginning and ending of the region: +In this case, the function definition looks like the following, where +@code{arg} and @code{char} are the symbols to which @code{interactive} +binds the prefix argument and the specified character: @smallexample @group -(defun @var{name-of-function} (buffer start end) +(defun @var{name-of-function} (arg char) "@var{documentation}@dots{}" - (interactive "BAppend to buffer:@: \nr") + (interactive "p\ncZap to char: ") @var{body-of-function}@dots{}) @end group @end smallexample @noindent (The space after the colon in the prompt makes it look better when you -are prompted. The @code{append-to-buffer} function looks exactly like -this. @xref{append-to-buffer, , The Definition of -@code{append-to-buffer}}.) +are prompted. @xref{copy-to-buffer, , The Definition of +@code{copy-to-buffer}}, for an example.) -If a function does not have arguments, then @code{interactive} does not +When a function does not take arguments, @code{interactive} does not require any. Such a function contains the simple expression @code{(interactive)}. The @code{mark-whole-buffer} function is like this. Alternatively, if the special letter-codes are not right for your application, you can pass your own arguments to @code{interactive} as -a list. @xref{Using Interactive, , Using @code{Interactive}, elisp, The -GNU Emacs Lisp Reference Manual}, for more information about this advanced -technique. +a list. + +@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}, +for an example. @xref{Using Interactive, , Using @code{Interactive}, +elisp, The GNU Emacs Lisp Reference Manual}, for a more complete +explanation about this technique. @node Permanent Installation, let, Interactive Options, Writing Defuns @comment node-name, next, previous, up @@ -3565,11 +3612,11 @@ functions in the files. @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 @@ and the two are not intended to refer to the same value. The @end ifnottex @cindex @samp{local variable} defined +@cindex @samp{variable, local}, defined The @code{let} special form prevents confusion. @code{let} creates a name for a @dfn{local variable} that overshadows any use of the same name outside the @code{let} expression. This is like understanding @@ -3726,13 +3774,17 @@ Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. The two variables are @code{zebra} and @code{tiger}. Each variable is the first element of a two-element list and each value is the second element of its two-element list. In the varlist, Emacs binds the -variable @code{zebra} to the value @code{stripes}, and binds the +variable @code{zebra} to the value @code{stripes}@footnote{According +to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras +become impossibly dangerous as they grow older'' but the claim here is +that they do not become fierce like a tiger. (1997, W. W. Norton and +Co., ISBN 0-393-03894-2, page 171)}, and binds the variable @code{tiger} to the value @code{fierce}. In this example, both values are symbols preceded by a quote. The values could just as well have been another list or a string. The body of the @code{let} -follows after the list holding the variables. In this example, the body -is a list that uses the @code{message} function to print a string in -the echo area. +follows after the list holding the variables. In this example, the +body is a list that uses the @code{message} function to print a string +in the echo area. @need 1500 You may evaluate the example in the usual fashion, by placing the @@ -3818,7 +3870,7 @@ such as, ``if it is warm and sunny, then go to the beach!'' @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 @@ when you evaluate @code{(type-of-animal 'zebra)}, you will see (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 @@ The expression that tests for truth is interpreted as @dfn{true} 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 @@ purpose is to keep the user from being surprised and disturbed by 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 @@ abnormal exit''). This feature is very helpful. 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 @@ documentation, an optional interactive declaration, and the body of the 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 @@ For example: @end group @end smallexample +@ignore +In GNU Emacs 22, + +(defun backward-to-indentation (&optional arg) + "Move backward ARG lines and position at first nonblank character." + (interactive "p") + (forward-line (- (or arg 1))) + (skip-chars-forward " \t")) + +(defun back-to-indentation () + "Move point to the first non-whitespace character on this line." + (interactive) + (beginning-of-line 1) + (skip-syntax-forward " " (line-end-position)) + ;; Move back over chars that have whitespace syntax but have the p flag. + (backward-prefix-chars)) +@end ignore + @item interactive Declare to the interpreter that the function can be used interactively. This special form may be followed by a string with one @@ -4430,10 +4502,10 @@ For example, @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 @@ arguments that follow the string. The argument used by @samp{%s} must 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 @@ these definitions. The functions described here are all related to 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 @@ variable by typing @kbd{C-h v} and then the name of the variable (and then @key{RET}). @cindex Find source of function -In versions 20 and higher, when a function is written in Emacs Lisp, -@code{describe-function} will also tell you the location of the -function definition. If you move point over the file name and press +@c In version 22 +When a function is written in Emacs Lisp, @code{describe-function} +will also tell you the location of the function definition. + +Put point into the name of the file that contains the function and +press the @key{RET} key. In this case, @key{RET} means +@code{push-button} rather than `return' or `enter'. Emacs will take +you directly to the function definition. + +@ignore +Not In version 22 + +If you move point over the file name and press the @key{RET} key, which in this case means @code{help-follow} rather than `return' or `enter', Emacs will take you directly to the function definition. +@end ignore More generally, if you want to see a function in its original source file, you can use the @code{find-tags} function to jump to it. @@ -4619,7 +4701,7 @@ screen. To switch back to your current buffer, type @kbd{C-x b @key{RET}}. (On some keyboards, the @key{META} key is labelled @key{ALT}.) -@c !!! 21.0.100 tags table location in this paragraph +@c !!! 22.0.100 tags table location in this paragraph @cindex TAGS table, specifying @findex find-tags Depending on how the initial default values of your copy of Emacs are @@ -4629,15 +4711,15 @@ interested in Emacs sources, the tags table you will most likely want, if it has already been created for you, will be in a subdirectory of the @file{/usr/local/share/emacs/} directory; thus you would use the @code{M-x visit-tags-table} command and specify a pathname such as -@file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or -@file{/usr/local/src/emacs/src/TAGS}. If the tags table has -not already been created, you will have to create it yourself. +@file{/usr/local/share/emacs/22.0.100/lisp/TAGS}. If the tags table +has not already been created, you will have to create it yourself. It +will in a file such as @file{/usr/local/src/emacs/src/TAGS}. @need 1250 To create a @file{TAGS} file in a specific directory, switch to that directory in Emacs using @kbd{M-x cd} command, or list the directory with @kbd{C-x d} (@code{dired}). Then run the compile command, with -@w{@code{etags *.el}} as the command to execute +@w{@code{etags *.el}} as the command to execute: @smallexample M-x compile RET etags *.el RET @@ -4773,12 +4855,14 @@ example, the documentation for @code{goto-char} is: @smallexample @group -One arg, a number. Set point to that number. -Beginning of buffer is position (point-min), -end is (point-max). +Set point to POSITION, a number or marker. +Beginning of buffer is position (point-min), end is (point-max). @end group @end smallexample +@noindent +The function's one argument is the desired position. + @noindent (The prompt for @code{describe-function} will offer you the symbol under or preceding the cursor, so you can save typing by positioning @@ -4805,28 +4889,29 @@ marks a whole buffer as a region by putting point at the beginning and a mark at the end of the buffer. It is generally bound to @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 @@ previous section. The body of the @code{mark-whole-buffer} function consists of three lines of code: +@c GNU Emacs 22 @smallexample @group (push-mark (point)) -(push-mark (point-max)) +(push-mark (point-max) nil t) (goto-char (point-min)) @end group @end smallexample @@ -4889,34 +4975,36 @@ so as to parallel the structure of the next line. In any case, the line causes Emacs to determine the position of point and set a mark there. -The next line of @code{mark-whole-buffer} is @code{(push-mark (point-max)}. -This expression sets a mark at the point in the buffer -that has the highest number. This will be the end of the buffer (or, -if the buffer is narrowed, the end of the accessible portion of the -buffer. @xref{Narrowing & Widening, , Narrowing and Widening}, for -more about narrowing.) After this mark has been set, the previous -mark, the one set at point, is no longer set, but Emacs remembers its -position, just as all other recent marks are always remembered. This -means that you can, if you wish, go back to that position by typing -@kbd{C-u C-@key{SPC}} twice. +In earlier versions of GNU Emacs, the next line of +@code{mark-whole-buffer} was @code{(push-mark (point-max))}. This +expression sets a mark at the point in the buffer that has the highest +number. This will be the end of the buffer (or, if the buffer is +narrowed, the end of the accessible portion of the buffer. +@xref{Narrowing & Widening, , Narrowing and Widening}, for more about +narrowing.) After this mark has been set, the previous mark, the one +set at point, is no longer set, but Emacs remembers its position, just +as all other recent marks are always remembered. This means that you +can, if you wish, go back to that position by typing @kbd{C-u +C-@key{SPC}} twice. -(In GNU Emacs 21, the @code{(push-mark (point-max)} is slightly more -complicated than shown here. The line reads +@need 1250 +In GNU Emacs 22, the @code{(point-max)} is slightly more complicated. +The line reads @smallexample (push-mark (point-max) nil t) @end smallexample @noindent -(The expression works nearly the same as before. It sets a mark at -the highest numbered place in the buffer that it can. However, in -this version, @code{push-mark} has two additional arguments. The -second argument to @code{push-mark} is @code{nil}. This tells the -function it @emph{should} display a message that says `Mark set' when -it pushes the mark. The third argument is @code{t}. This tells +The expression works nearly the same as before. It sets a mark at the +highest numbered place in the buffer that it can. However, in this +version, @code{push-mark} has two additional arguments. The second +argument to @code{push-mark} is @code{nil}. This tells the function +it @emph{should} display a message that says `Mark set' when it pushes +the mark. The third argument is @code{t}. This tells @code{push-mark} to activate the mark when Transient Mark mode is turned on. Transient Mark mode highlights the currently active -region. It is usually turned off.) +region. It is often turned off. Finally, the last line of the function is @code{(goto-char (point-min)))}. This is written exactly the same way as it is written @@ -4932,16 +5020,16 @@ region. @section The Definition of @code{append-to-buffer} @findex append-to-buffer -The @code{append-to-buffer} command is very nearly as simple as the -@code{mark-whole-buffer} command. What it does is copy the region (that -is, the part of the buffer between point and mark) from the current -buffer to a specified buffer. +The @code{append-to-buffer} command is more complex than the +@code{mark-whole-buffer} command. What it does is copy the region +(that is, the part of the buffer between point and mark) from the +current buffer to a specified buffer. @menu * append-to-buffer overview:: -* append interactive:: A two part interactive expression. -* append-to-buffer body:: Incorporates a @code{let} expression. -* append save-excursion:: How the @code{save-excursion} works. +* append interactive:: +* append-to-buffer body:: +* append save-excursion:: @end menu @node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer @@ -4954,10 +5042,15 @@ The @code{append-to-buffer} command uses the @code{insert-buffer-substring} function to copy the region. @code{insert-buffer-substring} is described by its name: it takes a string of characters from part of a buffer, a ``substring'', and -inserts them into another buffer. Most of @code{append-to-buffer} is +inserts them into another buffer. + +Most of @code{append-to-buffer} is concerned with setting up the conditions for @code{insert-buffer-substring} to work: the code must specify both the -buffer to which the text will go and the region that will be copied. +buffer to which the text will go, the window it comes from and goes +to, and the region that will be copied. + +@need 1250 Here is the complete text of the function: @smallexample @@ -4969,13 +5062,26 @@ It is inserted into that buffer before its point. @group When calling from a program, give three arguments: -a buffer or the name of one, and two character numbers -specifying the portion of the current buffer to be copied." - (interactive "BAppend to buffer:@: \nr") +BUFFER (or buffer name), START and END. +START and END specify the portion of the current buffer to be copied." + (interactive + (list (read-buffer "Append to buffer: " (other-buffer + (current-buffer) t)) + (region-beginning) (region-end))) +@end group +@group (let ((oldbuf (current-buffer))) (save-excursion - (set-buffer (get-buffer-create buffer)) - (insert-buffer-substring oldbuf start end)))) + (let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + (set-buffer append-to) + (setq point (point)) + (barf-if-buffer-read-only) + (insert-buffer-substring oldbuf start end) + (dolist (window windows) + (when (= (window-point window) point) + (set-window-point window (point)))))))) @end group @end smallexample @@ -4989,7 +5095,7 @@ function, it looks like this (with several slots filled in): @group (defun append-to-buffer (buffer start end) "@var{documentation}@dots{}" - (interactive "BAppend to buffer:@: \nr") + (interactive @dots{}) @var{body}@dots{}) @end group @end smallexample @@ -5000,7 +5106,12 @@ the @code{start} and @code{end} of the region in the current buffer that will be copied. The next part of the function is the documentation, which is clear and -complete. +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 @@ review of @code{interactive}, see @ref{Interactive, , Making a Function Interactive}.) The expression reads as follows: @smallexample -(interactive "BAppend to buffer:@: \nr") +(interactive + (list (read-buffer + "Append to buffer: " + (other-buffer (current-buffer) t)) + (region-beginning) + (region-end))) @end smallexample @noindent -This expression has an argument inside of quotation marks and that -argument has two parts, separated by @samp{\n}. +This expression is not one with letters standing for parts, as +described earlier. Instead, it starts a list with thee parts. + +The first part of the list is an expression to read the name of a +buffer and return it as a string. That is @code{read-buffer}. The +function requires a prompt as its first argument, @samp{"Append to +buffer: "}. Its second argument tells the command what value to +provide if you don't specify anything. + +In this case that second argument is an expression containing the +function @code{other-buffer}, an exception, and a @samp{t}, standing +for true. + +The first argument to @code{other-buffer}, the exception, is yet +another function, @code{current-buffer}. That is not going to be +returned. The second argument is the symbol for true, @code{t}. that +tells @code{other-buffer} that it may show visible buffers (except in +this case, it will not show the current buffer, which makes sense). + +@need 1250 +The expression looks like this: + +@smallexample +(other-buffer (current-buffer) t) +@end smallexample + +The second and third arguments to the @code{list} expression are +@code{(region-beginning)} and @code{(region-end)}. These two +functions specify the beginning and end of the text to be appended. + +@need 1250 +Originally, the command used the letters @samp{B} and @samp{r}. +The whole @code{interactive} expression looked like this: + +@smallexample +(interactive "BAppend to buffer:@: \nr") +@end smallexample -The first part is @samp{BAppend to buffer:@: }. Here, the @samp{B} -tells Emacs to ask for the name of the buffer that will be passed to the -function. Emacs will ask for the name by prompting the user in the -minibuffer, using the string following the @samp{B}, which is the string -@samp{Append to buffer:@: }. Emacs then binds the variable @code{buffer} -in the function's argument list to the specified buffer. +@noindent +But when that was done, the default value of the buffer switched to +was invisible. That was not wanted. -The newline, @samp{\n}, separates the first part of the argument from -the second part. It is followed by an @samp{r} that tells Emacs to bind -the two arguments that follow the symbol @code{buffer} in the function's +(The prompt was separated from the second argument with a newline, +@samp{\n}. It was followed by an @samp{r} that told Emacs to bind the +two arguments that follow the symbol @code{buffer} in the function's argument list (that is, @code{start} and @code{end}) to the values of -point and mark. +point and mark. That argument worked fine.) @node append-to-buffer body, append save-excursion, append interactive, append-to-buffer @comment node-name, next, previous, up @subsection The Body of @code{append-to-buffer} +@ignore +in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el + +(defun append-to-buffer (buffer start end) + "Append to specified buffer the text of the region. +It is inserted into that buffer before its point. + +When calling from a program, give three arguments: +BUFFER (or buffer name), START and END. +START and END specify the portion of the current buffer to be copied." + (interactive + (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) + (region-beginning) (region-end))) + (let ((oldbuf (current-buffer))) + (save-excursion + (let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + (set-buffer append-to) + (setq point (point)) + (barf-if-buffer-read-only) + (insert-buffer-substring oldbuf start end) + (dolist (window windows) + (when (= (window-point window) point) + (set-window-point window (point)))))))) +@end ignore + The body of the @code{append-to-buffer} function begins with @code{let}. As we have seen before (@pxref{let, , @code{let}}), the purpose of a @@ -5052,7 +5227,7 @@ whole by showing a template for @code{append-to-buffer} with the @group (defun append-to-buffer (buffer start end) "@var{documentation}@dots{}" - (interactive "BAppend to buffer:@: \nr") + (interactive @dots{}) (let ((@var{variable} @var{value})) @var{body}@dots{}) @end group @@ -5142,7 +5317,7 @@ this: @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 @@ with the @code{let}: @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 @@ of filling in the slots of a template: @need 1200 @noindent In this function, the body of the @code{save-excursion} contains only -two expressions. The body looks like this: +one expression, the @code{let*} expression. You know about a +@code{let} function. The @code{let*} function is different. It has a +@samp{*} in its name. It enables Emacs to set each variable in its +varlist in sequence, one after another. -@smallexample -@group -(set-buffer (get-buffer-create buffer)) -(insert-buffer-substring oldbuf start end) -@end group -@end smallexample +Its critical feature is that variables later in the varlist can make +use of the values to which Emacs set variables earlier in the varlist. +@xref{fwd-para let, , The @code{let*} expression}. -When the @code{append-to-buffer} function is evaluated, the two -expressions in the body of the @code{save-excursion} are evaluated in -sequence. The value of the last expression is returned as the value of -the @code{save-excursion} function; the other expression is evaluated -only for its side effects. +We will skip functions like @code{let*} and focus on two: the +@code{set-buffer} function and the @code{insert-buffer-substring} +function. -The first line in the body of the @code{save-excursion} uses the -@code{set-buffer} function to change the current buffer to the one -specified in the first argument to @code{append-to-buffer}. (Changing -the buffer is the side effect; as we have said before, in Lisp, a side -effect is often the primary thing we want.) The second line does the -primary work of the function. +@need 1250 +In the old days, the @code{set-buffer} expression was simply -The @code{set-buffer} function changes Emacs' attention to the buffer to -which the text will be copied and from which @code{save-excursion} will -return. +@smallexample +(set-buffer (get-buffer-create buffer)) +@end smallexample -@need 800 -The line looks like this: +@need 1250 +@noindent +but now it is @smallexample -(set-buffer (get-buffer-create buffer)) +(set-buffer append-to) @end smallexample -The innermost expression of this list is @code{(get-buffer-create -buffer)}. This expression uses the @code{get-buffer-create} function, -which either gets the named buffer, or if it does not exist, creates one -with the given name. This means you can use @code{append-to-buffer} to -put text into a buffer that did not previously exist. +@noindent +@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier +on in the @code{let*} expression. That extra binding would not be +necessary except for that @code{append-to} is used later in the +varlist as an argument to @code{get-buffer-window-list}. + +@ignore +in GNU Emacs 22 + + (let ((oldbuf (current-buffer))) + (save-excursion + (let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + (set-buffer append-to) + (setq point (point)) + (barf-if-buffer-read-only) + (insert-buffer-substring oldbuf start end) + (dolist (window windows) + (when (= (window-point window) point) + (set-window-point window (point)))))))) +@end ignore -@code{get-buffer-create} also keeps @code{set-buffer} from getting an -unnecessary error: @code{set-buffer} needs a buffer to go to; if you -were to specify a buffer that does not exist, Emacs would baulk. -Since @code{get-buffer-create} will create a buffer if none exists, -@code{set-buffer} is always provided with a buffer. +The @code{append-to-buffer} function definition inserts text from the +buffer in which you are currently to a named buffer. It happens that +@code{insert-buffer-substring} copies text from another buffer to the +current buffer, just the reverse---that is why the +@code{append-to-buffer} definition starts out with a @code{let} that +binds the local symbol @code{oldbuf} to the value returned by +@code{current-buffer}. @need 1250 -The last line of @code{append-to-buffer} does the work of appending -the text: +The @code{insert-buffer-substring} expression looks like this: @smallexample (insert-buffer-substring oldbuf start end) @end smallexample @noindent -The @code{insert-buffer-substring} function copies a string @emph{from} -the buffer specified as its first argument and inserts the string into -the present buffer. In this case, the argument to -@code{insert-buffer-substring} is the value of the variable created and -bound by the @code{let}, namely the value of @code{oldbuf}, which was -the current buffer when you gave the @code{append-to-buffer} command. +The @code{insert-buffer-substring} function copies a string +@emph{from} the buffer specified as its first argument and inserts the +string into the present buffer. In this case, the argument to +@code{insert-buffer-substring} is the value of the variable created +and bound by the @code{let}, namely the value of @code{oldbuf}, which +was the current buffer when you gave the @code{append-to-buffer} +command. After @code{insert-buffer-substring} has done its work, -@code{save-excursion} will restore the action to the original buffer and -@code{append-to-buffer} will have done its job. +@code{save-excursion} will restore the action to the original buffer +and @code{append-to-buffer} will have done its job. @need 800 Written in skeletal form, the workings of the body look like this: @@ -5251,16 +5442,15 @@ Written in skeletal form, the workings of the body look like this: @var{change-back-to-original-buffer-when-finished} @var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished} - @end group @end smallexample -In summary, @code{append-to-buffer} works as follows: it saves the value -of the current buffer in the variable called @code{oldbuf}. It gets the -new buffer, creating one if need be, and switches Emacs to it. Using -the value of @code{oldbuf}, it inserts the region of text from the old -buffer into the new buffer; and then using @code{save-excursion}, it -brings you back to your original buffer. +In summary, @code{append-to-buffer} works as follows: it saves the +value of the current buffer in the variable called @code{oldbuf}. It +gets the new buffer (creating one if need be) and switches Emacs' +attention to it. Using the value of @code{oldbuf}, it inserts the +region of text from the old buffer into the new buffer; and then using +@code{save-excursion}, it brings you back to your original buffer. In looking at @code{append-to-buffer}, you have explored a fairly complex function. It shows how to use @code{let} and @@ -5351,10 +5541,9 @@ use of an asterisk in an @code{interactive} expression, use of 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 @@ to which the name refers. After understanding how @code{append-to-buffer} works, it is easy to understand @code{copy-to-buffer}. This function copies text into a -buffer, but instead of adding to the second buffer, it replaces the -previous text in the second buffer. The code for the -@code{copy-to-buffer} function is almost the same as the code for -@code{append-to-buffer}, except that @code{erase-buffer} and a second -@code{save-excursion} are used. (@xref{append-to-buffer, , The -Definition of @code{append-to-buffer}}, for the description of -@code{append-to-buffer}.) +buffer, but instead of adding to the second buffer, it replaces all the +previous text in the second buffer. @need 800 -The body of @code{copy-to-buffer} looks like this +The body of @code{copy-to-buffer} looks like this, @smallexample @group @dots{} -(interactive "BCopy to buffer:@: \nr") - (let ((oldbuf (current-buffer))) +(interactive "BCopy to buffer: \nr") +(let ((oldbuf (current-buffer))) + (with-current-buffer (get-buffer-create buffer) + (barf-if-buffer-read-only) + (erase-buffer) (save-excursion - (set-buffer (get-buffer-create buffer)) - (erase-buffer) - (save-excursion - (insert-buffer-substring oldbuf start end))))) + (insert-buffer-substring oldbuf start end))))) @end group @end smallexample -This code is similar to the code in @code{append-to-buffer}: it is -only after changing to the buffer to which the text will be copied -that the definition for this function diverges from the definition for -@code{append-to-buffer}: the @code{copy-to-buffer} function erases the -buffer's former contents. (This is what is meant by `replacement'; to -replace text, Emacs erases the previous text and then inserts new -text.) After erasing the previous contents of the buffer, -@code{save-excursion} is used for a second time and the new text is -inserted. +The @code{copy-to-buffer} function has a simpler @code{interactive} +expression than @code{append-to-buffer}. + +@need 800 +The definition then says + +@smallexample +(with-current-buffer (get-buffer-create buffer) @dots{} +@end smallexample + +First, look at the earliest inner expression; that is evaluated first. +That expression starts with @code{get-buffer-create buffer}. The +function tells the computer to use the buffer with the name specified +as the one to which you are copying, or if such a buffer does not +exist, to create it. Then, the @code{with-current-buffer} function +evaluates its body with that buffer temporarily current. + +(This demonstrates another way to shift the computer's attention but +not the user's. The @code{append-to-buffer} function showed how to do +the same with @code{save-excursion} and @code{set-buffer}. +@code{with-current-buffer} is a newer, and arguably easier, +mechanism.) + +The @code{barf-if-buffer-read-only} function sends you an error +message saying the buffer is read-only if you cannot modify it. -Why is @code{save-excursion} used twice? Consider again what the -function does. +The next line has the @code{erase-buffer} function as its sole +contents. That function erases the buffer. + +Finally, the last two lines contain the @code{save-excursion} +expression with @code{insert-buffer-substring} as its body. +The @code{insert-buffer-substring} expression copies the text from +the buffer you are in (and you have not seen the computer shift its +attention, so you don't know that that buffer is now called +@code{oldbuf}). + +Incidently, this is what is meant by `replacement'. To replace text, +Emacs erases the previous text and then inserts new text. @need 1250 In outline, the body of @code{copy-to-buffer} looks like this: @@ -5409,27 +5619,14 @@ In outline, the body of @code{copy-to-buffer} looks like this: @smallexample @group (let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) - (save-excursion ; @r{First use of @code{save-excursion}.} - @var{change-buffer} + (@var{with-the-buffer-you-are-copying-to} + (@var{but-do-not-erase-or-copy-to-a-read-only-buffer}) (erase-buffer) - (save-excursion ; @r{Second use of @code{save-excursion}.} + (save-excursion @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}))) @end group @end smallexample -The first use of @code{save-excursion} returns Emacs to the buffer from -which the text is being copied. That is clear, and is just like its use -in @code{append-to-buffer}. Why the second use? The reason is that -@code{insert-buffer-substring} always leaves point at the @emph{end} of -the region being inserted. The second @code{save-excursion} causes -Emacs to leave point at the beginning of the text being inserted. In -most circumstances, users prefer to find point at the beginning of -inserted text. (Of course, the @code{copy-to-buffer} function returns -the user to the original buffer when done---but if the user @emph{then} -switches to the copied-to buffer, point will go to the beginning of the -text. Thus, this use of a second @code{save-excursion} is a little -nicety.) - @node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex @comment node-name, next, previous, up @section The Definition of @code{insert-buffer} @@ -5443,17 +5640,21 @@ copy a region of text @emph{from} the current buffer to another buffer. Here is a discussion based on the original code. The code was simplified in 2003 and is harder to understand. +@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see +a discussion of the new body.) + In addition, this code illustrates the use of @code{interactive} with a buffer that might be @dfn{read-only} and the important distinction between the name of an object and the object actually referred to. @menu * insert-buffer code:: -* insert-buffer interactive:: When you can read, but not write. -* insert-buffer body:: The body has an @code{or} and a @code{let}. -* if & or:: Using an @code{if} instead of an @code{or}. -* Insert or:: How the @code{or} expression works. -* Insert let:: Two @code{save-excursion} expressions. +* insert-buffer interactive:: +* insert-buffer body:: +* if & or:: +* Insert or:: +* Insert let:: +* New insert-buffer :: @end menu @node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer @@ -5462,7 +5663,7 @@ between the name of an object and the object actually referred to. @end ifnottex @need 800 -Here is the code: +Here is the earlier code: @smallexample @group @@ -5511,8 +5712,8 @@ declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert 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 @@ of the buffer, offering you a default buffer, with name completion enabled. If the buffer does not exist, you receive a message that says ``No match''; your terminal may beep at you as well. +The 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 @@ written like this: (or (holding-on-to-guest) (find-and-take-arm-of-guest)) @end smallexample -@node Insert let, , Insert or, insert-buffer +@node Insert let, New insert-buffer , Insert or, insert-buffer @comment node-name, next, previous, up @subsection The @code{let} Expression in @code{insert-buffer} @@ -5821,6 +6027,45 @@ function uses @code{let}, @code{save-excursion}, and use @code{or}. All these functions are building blocks that we will find and use again and again. +@node New insert-buffer , , Insert let, insert-buffer +@comment node-name, next, previous, up +@subsection New Body for @code{insert-buffer} +@findex insert-buffer, new version body +@findex new version body for insert-buffer + +The body in the GNU Emacs 22 version is more confusing than the original. + +@need 1250 +It consists of two expressions, + +@smallexample +@group + (push-mark + (save-excursion + (insert-buffer-substring (get-buffer buffer)) + (point))) + + nil +@end group +@end smallexample + +@noindent +except, and this is what confuses novices, very important work is done +inside the @code{push-mark} expression. + +The @code{get-buffer} function returns a buffer with the name +provided. You will note that the function is @emph{not} called +@code{get-buffer-create}; it does not create a buffer if one does not +already exist. The buffer returned by @code{get-buffer}, an existing +buffer, is passed to @code{insert-buffer-substring}, which inserts the +whole of the buffer (since you did not specify anything else). + +The location into which the buffer is inserted is recorded by +@code{push-mark}. Then the function returns @code{nil}, the value of +its last command. Put another way, the @code{insert-buffer} function +exists only to produce a side effect, inserting another buffer, not to +return any value. + @node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex @comment node-name, next, previous, up @section Complete Definition of @code{beginning-of-buffer} @@ -5833,23 +6078,24 @@ 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 @@ If that does not happen, you get an error and a message that says @cindex Optional arguments @cindex Keyword @findex optional -However, optional arguments are a feature of Lisp: a @dfn{keyword} may -be used to tell the Lisp interpreter that an argument is optional. -The keyword is @code{&optional}. (The @samp{&} in front of +However, optional arguments are a feature of Lisp: a particular +@dfn{keyword} is used to tell the Lisp interpreter that an argument is +optional. The keyword is @code{&optional}. (The @samp{&} in front of @samp{optional} is part of the keyword.) In a function definition, if -an argument follows the keyword @code{&optional}, a value does not -need to be passed to that argument when the function is called. +an argument follows the keyword @code{&optional}, no value need be +passed to that argument when the function is called. @need 1200 The first line of the function definition of @code{beginning-of-buffer} @@ -5887,12 +6133,16 @@ In outline, the whole function looks like this: (defun beginning-of-buffer (&optional arg) "@var{documentation}@dots{}" (interactive "P") - (push-mark) + (or (@var{is-the-argument-a-cons-cell} arg) + (and @var{are-both-transient-mark-mode-and-mark-active-true}) + (push-mark)) + (let (@var{determine-size-and-set-it}) (goto-char (@var{if-there-is-an-argument} @var{figure-out-where-to-go} @var{else-go-to} (point-min)))) + @var{do-nicety} @end group @end smallexample @@ -5900,26 +6150,37 @@ The function is similar to the @code{simplified-beginning-of-buffer} function except that the @code{interactive} expression has @code{"P"} as an argument and the @code{goto-char} function is followed by an if-then-else expression that figures out where to put the cursor if -there is an argument. - -The @code{"P"} in the @code{interactive} expression tells Emacs to pass -a prefix argument, if there is one, to the function. A prefix argument -is made by typing the @key{META} key followed by a number, or by typing -@kbd{C-u} and then a number (if you don't type a number, @kbd{C-u} -defaults to 4). - -The true-or-false-test of the @code{if} expression is simple: it is -simply the argument @code{arg}. If @code{arg} has a value that is not -@code{nil}, which will be the case if @code{beginning-of-buffer} is -called with an argument, then this true-or-false-test will return true -and the then-part of the @code{if} expression will be evaluated. On the +there is an argument that is not a cons cell. + +(Since I do not explain a cons cell for many more chapters, please +consider ignoring the function @code{consp}. @xref{List +Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type, +, Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference +Manual}.) + +The @code{"P"} in the @code{interactive} expression tells Emacs to +pass a prefix argument, if there is one, to the function in raw form. +A prefix argument is made by typing the @key{META} key followed by a +number, or by typing @kbd{C-u} and then a number. (If you don't type +a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase +@code{"p"} in the @code{interactive} expression causes the function to +convert a prefix arg to a number.) + +The true-or-false-test of the @code{if} expression looks complex, but +it is not: it checks whether @code{arg} has a value that is not +@code{nil} and whether it is a cons cell. (That is what @code{consp} +does; it checks whether its argument is a cons cell.) If @code{arg} +has a value that is not @code{nil} (and is not a cons cell), which +will be the case if @code{beginning-of-buffer} is called with a +numeric argument, then this true-or-false-test will return true and +the then-part of the @code{if} expression will be evaluated. On the other hand, if @code{beginning-of-buffer} is not called with an argument, the value of @code{arg} will be @code{nil} and the else-part -of the @code{if} expression will be evaluated. The else-part is simply -@code{point-min}, and when this is the outcome, the whole -@code{goto-char} expression is @code{(goto-char (point-min))}, which is -how we saw the @code{beginning-of-buffer} function in its simplified -form. +of the @code{if} expression will be evaluated. The else-part is +simply @code{point-min}, and when this is the outcome, the whole +@code{goto-char} expression is @code{(goto-char (point-min))}, which +is how we saw the @code{beginning-of-buffer} function in its +simplified form. @node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer @subsection @code{beginning-of-buffer} with an Argument @@ -5934,11 +6195,12 @@ like this: @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 @@ There are two cases: if the buffer is large and if it is not. 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 @@ evaluated. It reads like this (after formatting for easy reading): @group (* (prefix-numeric-value arg) - (/ (buffer-size) 10)) + (/ size 10)) @end group @end smallexample @@ -6019,11 +6289,12 @@ the arithmetic, a conversion is necessary, and @findex / @r{(division)} @cindex Division -The second argument is @code{(/ (buffer-size) 10)}. This expression -divides the numeric value of the buffer by ten. This produces a number -that tells how many characters make up one tenth of the buffer size. -(In Lisp, @code{/} is used for division, just as @code{*} is -used for multiplication.) +The second argument is @code{(/ size 10)}. This expression divides +the numeric value by ten --- the numeric value of the size of the +accessible portion of the buffer. This produces a number that tells +how many characters make up one tenth of the buffer size. (In Lisp, +@code{/} is used for division, just as @code{*} is used for +multiplication.) @need 1200 In the multiplication expression as a whole, this amount is multiplied @@ -6032,23 +6303,22 @@ by the value of the prefix argument---the multiplication looks like this: @smallexample @group (* @var{numeric-value-of-prefix-arg} - @var{number-of-characters-in-one-tenth-of-the-buffer}) + @var{number-of-characters-in-one-tenth-of-the-accessible-buffer}) @end group @end smallexample @noindent If, for example, the prefix argument is @samp{7}, the one-tenth value -will be multiplied by 7 to give a position 70% of the way through the -buffer. +will be multiplied by 7 to give a position 70% of the way through. @need 1200 -The result of all this is that if the buffer is large, the -@code{goto-char} expression reads like this: +The result of all this is that if the accessible portion of the buffer +is large, the @code{goto-char} expression reads like this: @smallexample @group (goto-char (* (prefix-numeric-value arg) - (/ (buffer-size) 10))) + (/ size 10))) @end group @end smallexample @@ -6069,7 +6339,7 @@ The code looks like this: @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 @@ enclosing expression: (/ (+ 10 (* - (buffer-size) + size (prefix-numeric-value arg))) 10)) @end group @@ -6093,12 +6363,12 @@ enclosing expression: @need 1200 @noindent Looking at parentheses, we see that the innermost operation is -@code{(prefix-numeric-value arg)}, which converts the raw argument to a -number. This number is multiplied by the buffer size in the following -expression: +@code{(prefix-numeric-value arg)}, which converts the raw argument to +a number. In the following expression, this number is multiplied by +the size of the accessible portion of the buffer: @smallexample -(* (buffer-size) (prefix-numeric-value arg)) +(* size (prefix-numeric-value arg)) @end smallexample @noindent @@ -6120,6 +6390,47 @@ the cursor is moved to that point. Here is the complete text of the @code{beginning-of-buffer} function: @sp 1 +@c In GNU Emacs 22 +@smallexample +@group +(defun beginning-of-buffer (&optional arg) + "Move point to the beginning of the buffer; +leave mark at previous position. +With \\[universal-argument] prefix, +do not set mark at previous position. +With numeric arg N, +put point N/10 of the way from the beginning. + +If the buffer is narrowed, +this command uses the beginning and size +of the accessible part of the buffer. +@end group + +@group +Don't use this command in Lisp programs! +\(goto-char (point-min)) is faster +and avoids clobbering the mark." + (interactive "P") + (or (consp arg) + (and transient-mark-mode mark-active) + (push-mark)) +@end group +@group + (let ((size (- (point-max) (point-min)))) + (goto-char (if (and arg (not (consp arg))) + (+ (point-min) + (if (> size 10000) + ;; Avoid overflow for large buffer sizes! + (* (prefix-numeric-value arg) + (/ size 10)) + (/ (+ 10 (* size (prefix-numeric-value arg))) 10))) + (point-min)))) + (if arg (forward-line 1))) +@end group +@end smallexample + +@ignore +From before GNU Emacs 22 @smallexample @group (defun beginning-of-buffer (&optional arg) @@ -6151,6 +6462,7 @@ and does not set the mark." (if arg (forward-line 1))) @end group @end smallexample +@end ignore @noindent Except for two small points, the previous discussion shows how this @@ -6162,18 +6474,21 @@ the function. In the documentation string, there is reference to an expression: @smallexample -\(goto-char (point-min)) +\\[universal-argument] @end smallexample @noindent -A @samp{\} is used before the first parenthesis of this expression. -This @samp{\} tells the Lisp interpreter that the expression should be -printed as shown in the documentation rather than evaluated as a -symbolic expression, which is what it looks like. +A @samp{\\} is used before the first square bracket of this +expression. This @samp{\\} tells the Lisp interpreter to substitute +whatever key is currently bound to the @samp{[@dots{}]}. In the case +of @code{universal-argument}, that is usually @kbd{C-u}, but it might +be different. (@xref{Documentation Tips, , Tips for Documentation +Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more +information.) @need 1200 -Finally, the last line of the @code{beginning-of-buffer} command says to -move point to the beginning of the next line if the command is +Finally, the last line of the @code{beginning-of-buffer} command says +to move point to the beginning of the next line if the command is invoked with an argument: @smallexample @@ -6185,8 +6500,15 @@ This puts the cursor at the beginning of the first line after the appropriate tenths position in the buffer. This is a flourish that means that the cursor is always located @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 @@ Evaluate each argument in sequence, and return the value of the first 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 @@ other parts. Narrowing is normally disabled since it can confuse 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 @@ For example, @end group @end smallexample +@ignore +Emacs 22 +/usr/local/src/emacs/lisp/simple.el + +(defun what-line () + "Print the current buffer line number and narrowed line number of point." + (interactive) + (let ((start (point-min)) + (n (line-number-at-pos))) + (if (= start 1) + (message "Line %d" n) + (save-excursion + (save-restriction + (widen) + (message "line %d (narrowed line %d)" + (+ n (line-number-at-pos start) -1) n)))))) + +(defun line-number-at-pos (&optional pos) + "Return (narrowed) buffer line number at position POS. +If POS is nil, use current buffer location. +Counting starts at (point-min), so the value refers +to the contents of the accessible portion of the buffer." + (let ((opoint (or pos (point))) start) + (save-excursion + (goto-char (point-min)) + (setq start (point)) + (goto-char opoint) + (forward-line 0) + (1+ (count-lines start (point)))))) + +(defun count-lines (start end) + "Return number of lines between START and END. +This is usually the number of newlines between them, +but can be one more if START is not equal to END +and the greater of them is not at the start of a line." + (save-excursion + (save-restriction + (narrow-to-region start end) + (goto-char (point-min)) + (if (eq selective-display t) + (save-match-data + (let ((done 0)) + (while (re-search-forward "[\n\C-m]" nil t 40) + (setq done (+ 40 done))) + (while (re-search-forward "[\n\C-m]" nil t 1) + (setq done (+ 1 done))) + (goto-char (point-max)) + (if (and (/= start end) + (not (bolp))) + (1+ done) + done))) + (- (buffer-size) (forward-line (buffer-size))))))) +@end ignore + @node what-line, narrow Exercise, save-restriction, Narrowing & Widening @comment node-name, next, previous, up @section @code{what-line} @@ -6389,13 +6765,17 @@ been expanded to tell you your line number in a narrowed buffer as well as your line number in a widened buffer. The recent version is more complex than the version shown here. If you feel adventurous, you might want to look at it after figuring out how this version -works. The newer version uses a conditional to determine whether the -buffer has been narrowed, and rather than use @code{beginning-of-line} -to move point to the beginning of the current line, if need be, the -function uses @code{(forward-line 0)}.) +works. You will probably need to use @kbd{C-h f} +(@code{describe-function}). The newer version uses a conditional to +determine whether the buffer has been narrowed. -The function as shown here has a documentation line and is -interactive, as you would expect. The next two lines use the +(Also, it uses @code{line-number-at-pos}, which among other simple +expressions, such as @code{(goto-char (point-min))}, moves point to +the beginning of the current line with @code{(forward-line 0)} rather +than @code{beginning-of-line}.) + +The @code{what-line} function as shown here has a documentation line +and is interactive, as you would expect. The next two lines use the functions @code{save-restriction} and @code{widen}. The @code{save-restriction} special form notes whatever narrowing is in @@ -6434,15 +6814,14 @@ echo area. @end group @end smallexample -The @code{message} function prints a one-line message at the bottom of the -Emacs screen. The first argument is inside of quotation marks and is -printed as a string of characters. However, it may contain @samp{%d}, -@samp{%s}, or @samp{%c} to print arguments that follow the string. -@samp{%d} prints the argument as a decimal, so the message will say -something such as @samp{Line 243}. +The @code{message} function prints a one-line message at the bottom of +the Emacs screen. The first argument is inside of quotation marks and +is printed as a string of characters. However, it may contain a +@samp{%d} expression to print a following argument. @samp{%d} prints +the argument as a decimal, so the message will say something such as +@samp{Line 243}. @need 1200 - The number that is printed in place of the @samp{%d} is computed by the last line of the function: @@ -6450,6 +6829,33 @@ last line of the function: (1+ (count-lines 1 (point))) @end smallexample +@ignore +GNU Emacs 22 + +(defun count-lines (start end) + "Return number of lines between START and END. +This is usually the number of newlines between them, +but can be one more if START is not equal to END +and the greater of them is not at the start of a line." + (save-excursion + (save-restriction + (narrow-to-region start end) + (goto-char (point-min)) + (if (eq selective-display t) + (save-match-data + (let ((done 0)) + (while (re-search-forward "[\n\C-m]" nil t 40) + (setq done (+ 40 done))) + (while (re-search-forward "[\n\C-m]" nil t 1) + (setq done (+ 1 done))) + (goto-char (point-max)) + (if (and (/= start end) + (not (bolp))) + (1+ done) + done))) + (- (buffer-size) (forward-line (buffer-size))))))) +@end ignore + @noindent What this does is count the lines from the first position of the buffer, indicated by the @code{1}, up to @code{(point)}, and then add @@ -6477,12 +6883,14 @@ functions, including @code{save-restriction}, @code{widen}, @cindex Properties, mention of @code{buffer-substring-no-properties} (@code{buffer-substring} is a previously unmentioned function you will have to investigate yourself; or perhaps you will have to use -@code{buffer-substring-no-properties} @dots{}, yet another function -and one that introduces text properties, a feature otherwise not -discussed here. @xref{Text Properties, , Text Properties, elisp, The -GNU Emacs Lisp Reference Manual}. Additionally, do you really need -@code{goto-char} or @code{point-min}? Or can you write the function -without them?) +@code{buffer-substring-no-properties} or +@code{filter-buffer-substring} @dots{}, yet other functions. Text +properties are a feature otherwise not discussed here. @xref{Text +Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference +Manual}. + +Additionally, do you really need @code{goto-char} or @code{point-min}? +Or can you write the function without them?) @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top @comment node-name, next, previous, up @@ -6499,13 +6907,13 @@ will see @code{cons} as well as two variants on @code{cdr}, 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 @@ Like @code{car} and @code{cdr}, @code{cons} is non-destructive. @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 @@ without giving it an argument, not even an empty list: What you see, if you evaluate this, is the error message @smallexample -Wrong number of arguments: #, 0 +Lisp error: (wrong-number-of-arguments length 0) @end smallexample @noindent @@ -6808,13 +7216,20 @@ this case, one argument is expected, the argument being a list whose 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{#} is the -name of the function. This is written with a special notation, -@samp{#