diff options
Diffstat (limited to 'doc/lispintro/emacs-lisp-intro.texi')
| -rw-r--r-- | doc/lispintro/emacs-lisp-intro.texi | 183 |
1 files changed, 76 insertions, 107 deletions
diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 860a758e75c..e981cbd119f 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -1,8 +1,6 @@ \input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @comment %**start of header @setfilename ../../info/eintr.info -@c setfilename emacs-lisp-intro.info -@c sethtmlfilename emacs-lisp-intro.html @settitle Programming in Emacs Lisp @include docstyle.texi @syncodeindex vr cp @@ -688,7 +686,7 @@ Your @file{.emacs} File * Text and Auto-fill:: Automatically wrap lines. * Mail Aliases:: Use abbreviations for email addresses. * Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. +* Key Bindings:: Create some personal key bindings. * Keymaps:: More about key binding. * Loading Files:: Load (i.e., evaluate) files automatically. * Autoload:: Make functions available. @@ -3357,7 +3355,7 @@ Both the examples just mentioned work identically to move point forward three sentences. (Since @code{multiply-by-seven} is not bound to a key, it could not be used as an example of key binding.) -(@xref{Keybindings, , Some Keybindings}, to learn how to bind a command +(@xref{Key Bindings, , Some Key Bindings}, to learn how to bind a command to a key.) A @dfn{prefix argument} is passed to an interactive function by typing the @@ -4895,8 +4893,6 @@ result of this, point is placed at the beginning of the buffer and mark is set at the end of the buffer. The whole buffer is, therefore, the region. -@c FIXME: the definition of append-to-buffer has been changed (in -@c 2010-03-30). @node append-to-buffer @section The Definition of @code{append-to-buffer} @findex append-to-buffer @@ -4931,8 +4927,9 @@ 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: +Here is a possible implementation of the function: +@c GNU Emacs 22 @smallexample @group (defun append-to-buffer (buffer start end) @@ -4999,7 +4996,9 @@ name. (The function can handle either.) Since the @code{append-to-buffer} function will be used interactively, the function must have an @code{interactive} expression. (For a review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: +Function Interactive}.) + +The expression reads as follows: @smallexample @group @@ -5028,7 +5027,7 @@ 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 +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). @@ -5064,33 +5063,6 @@ point and mark. That argument worked fine.) @node append-to-buffer body @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 @@ -5109,7 +5081,7 @@ whole by showing a template for @code{append-to-buffer} with the "@var{documentation}@dots{}" (interactive @dots{}) (let ((@var{variable} @var{value})) - @var{body}@dots{}) + @var{body}@dots{})) @end group @end smallexample @@ -5229,19 +5201,39 @@ of filling in the slots of a template: @need 1200 @noindent +@anchor{let* introduced} +@findex let* In this function, the body of the @code{save-excursion} contains only 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. +@code{let} function. The @code{let*} function is different. It +enables Emacs to set each variable in its varlist in sequence, one +after another; such that variables in the latter part of the varlist +can make use of the values to which Emacs set variables earlier in the +varlist. -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}. +Looking at the @code{let*} expression in @code{append-to-buffer}: -We will skip functions like @code{let*} and focus on two: the -@code{set-buffer} function and the @code{insert-buffer-substring} -function. +@smallexample +@group +(let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + BODY...) +@end group +@end smallexample + +@noindent +we see that @code{append-to} is bound to the value returned by the +@w{@code{(get-buffer-create buffer)}}. On the next line, +@code{append-to} is used as an argument to +@code{get-buffer-window-list}; this would not be possible with the +@code{let} expression. Note that @code{point} is automatically bound +to @code{nil}, the same way as it would be done in the @code{let} +statement. + +Now let's focus on the functions @code{set-buffer} and +@code{insert-buffer-substring} in the body of the @code{let*} +expression. @need 1250 In the old days, the @code{set-buffer} expression was simply @@ -5259,27 +5251,8 @@ but now it is @end smallexample @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 +This is because @code{append-to} was bound to @code{(get-buffer-create +buffer)} earlier on in the @code{let*} expression. The @code{append-to-buffer} function definition inserts text from the buffer in which you are currently to a named buffer. It happens that @@ -5376,6 +5349,12 @@ an argument and insert the region into the current buffer. @item mark-whole-buffer Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. +@item let* +Declare a list of variables and give them an initial value; then +evaluate the rest of the expressions in the body of @code{let*}. The +values of the variables can be used to bind ensuing variables in the +list. + @item set-buffer Switch the attention of Emacs to another buffer, but do not change the window being displayed. Used when the program rather than a human is @@ -8771,7 +8750,7 @@ keeps the kill ring from growing too long. It looks like this: The code checks whether the length of the kill ring is greater than the maximum permitted length. This is the value of -@code{kill-ring-max} (which is 60, by default). If the length of the +@code{kill-ring-max} (which is 120, by default). If the length of the kill ring is too long, then this code sets the last element of the kill ring to @code{nil}. It does this by using two functions, @code{nthcdr} and @code{setcdr}. @@ -12877,25 +12856,12 @@ familiar part of this function. @node fwd-para let @unnumberedsubsec The @code{let*} expression -The next line of the @code{forward-paragraph} function begins a -@code{let*} expression. This is different from @code{let}. The -symbol is @code{let*} not @code{let}. - @findex let* -The @code{let*} special form is like @code{let} except that Emacs sets -each variable in sequence, one after another, and variables in the -latter part of the varlist can make use of the values to which Emacs -set variables in the earlier part of the varlist. - -@ignore -( refappend save-excursion, , code save-excursion in code append-to-buffer .) -@end ignore - -(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) - -In the @code{let*} expression in this function, Emacs binds a total of -seven variables: @code{opoint}, @code{fill-prefix-regexp}, -@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and +The next line of the @code{forward-paragraph} function begins a +@code{let*} expression (@pxref{let* introduced,,@code{let*} +introduced}), in which Emacs binds a total of seven variables: +@code{opoint}, @code{fill-prefix-regexp}, @code{parstart}, +@code{parsep}, @code{sp-parstart}, @code{start}, and @code{found-start}. The variable @code{parsep} appears twice, first, to remove instances @@ -13692,7 +13658,7 @@ syntax table determines which characters these are." @end ifinfo @need 1000 -If you wish, you can also install this keybinding by evaluating it: +If you wish, you can also install this key binding by evaluating it: @smallexample (global-set-key "\C-c=" '@value{COUNT-WORDS}) @@ -14644,7 +14610,7 @@ almost the same code as for the recursive version of @need 800 @noindent -Let's re-use @kbd{C-c =} as a convenient keybinding: +Let's re-use @kbd{C-c =} as a convenient key binding: @smallexample (global-set-key "\C-c=" 'count-words-defun) @@ -14652,7 +14618,7 @@ Let's re-use @kbd{C-c =} as a convenient keybinding: Now we can try out @code{count-words-defun}: install both @code{count-words-in-defun} and @code{count-words-defun}, and set the -keybinding. Then copy the following to an Emacs Lisp buffer (like, +key binding. Then copy the following to an Emacs Lisp buffer (like, for instance, @file{*scratch*}), place the cursor within the definition, and use the @kbd{C-c =} command. @@ -15377,7 +15343,10 @@ nil @group (20615 27034 579989 697000) (17905 55681 0 0) -(20615 26327 734791 805000) +(20615 26327 734791 805000)@footnote{If @code{current-time-list} is +@code{nil} the three timestamps are @code{(1351051674579989697 +. 1000000000)}, @code{(1173477761000000000 . 1000000000)}, and +@code{(1351050967734791805 . 1000000000)}, respectively.} 13188 "-rw-r--r--" @end group @@ -15994,7 +15963,7 @@ placing point somewhere in the buffer, typing @kbd{M-:}, typing the and then typing @key{RET}. This causes Emacs to evaluate the expression in the minibuffer, but to use as the value of point the position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the -keybinding for @code{eval-expression}. Also, @code{nil} does not +key binding for @code{eval-expression}. Also, @code{nil} does not appear in the @file{*scratch*} buffer since the expression is evaluated in the minibuffer.) @@ -16561,7 +16530,7 @@ expressions in Emacs Lisp you can change or extend Emacs. * Text and Auto-fill:: Automatically wrap lines. * Mail Aliases:: Use abbreviations for email addresses. * Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. +* Key Bindings:: Create some personal key bindings. * Keymaps:: More about key binding. * Loading Files:: Load (i.e., evaluate) files automatically. * Autoload:: Make functions available. @@ -17105,10 +17074,10 @@ Files'' in @cite{The GNU Emacs Manual}. @end iftex @need 1700 -@node Keybindings -@section Some Keybindings +@node Key Bindings +@section Some Key Bindings -Now for some personal keybindings: +Now for some personal key bindings: @smallexample @group @@ -17130,10 +17099,10 @@ This also shows how to set a key globally, for all modes. @cindex Key setting globally @findex global-set-key The command is @code{global-set-key}. It is followed by the -keybinding. In a @file{.emacs} file, the keybinding is written as +key binding. In a @file{.emacs} file, the keybinding is written as shown: @code{\C-c} stands for Control-C, which means to press the control key and the @kbd{c} key at the same time. The @code{w} means -to press the @kbd{w} key. The keybinding is surrounded by double +to press the @kbd{w} key. The key binding is surrounded by double quotation marks. In documentation, you would write this as @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as @kbd{M-c}, rather than a @key{CTRL} key, you would write @@ -17147,26 +17116,26 @@ would first try to evaluate the symbol to determine its value. These three things, the double quotation marks, the backslash before the @samp{C}, and the single-quote are necessary parts of -keybinding that I tend to forget. Fortunately, I have come to +key binding that I tend to forget. Fortunately, I have come to remember that I should look at my existing @file{.emacs} file, and adapt what is there. -As for the keybinding itself: @kbd{C-c w}. This combines the prefix +As for the key binding itself: @kbd{C-c w}. This combines the prefix key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This set of keys, @kbd{C-c} followed by a single character, is strictly reserved for individuals' own use. (I call these @dfn{own} keys, since these are for my own use.) You should always be able to create such a -keybinding for your own use without stomping on someone else's -keybinding. If you ever write an extension to Emacs, please avoid +key binding for your own use without stomping on someone else's +key binding. If you ever write an extension to Emacs, please avoid taking any of these keys for public use. Create a key like @kbd{C-c C-w} instead. Otherwise, we will run out of own keys. @need 1250 -Here is another keybinding, with a comment: +Here is another key binding, with a comment: @smallexample @group -;;; Keybinding for 'occur' +;;; Key binding for 'occur' ; I use occur a lot, so let's bind it to a key: (global-set-key "\C-co" 'occur) @end group @@ -17226,8 +17195,8 @@ but moves point into that window. @cindex Rebinding keys Emacs uses @dfn{keymaps} to record which keys call which commands. -When you use @code{global-set-key} to set the keybinding for a single -command in all parts of Emacs, you are specifying the keybinding in +When you use @code{global-set-key} to set the key binding for a single +command in all parts of Emacs, you are specifying the key binding in @code{current-global-map}. Specific modes, such as C mode or Text mode, have their own keymaps; @@ -17482,7 +17451,7 @@ Here is the definition: @end smallexample @need 1250 -Now for the keybinding. +Now for the key binding. Function keys as well as mouse button events and non-@sc{ascii} characters are written within square brackets, without quotation @@ -17776,7 +17745,7 @@ Some systems bind keys unpleasantly. Sometimes, for example, the @key{CTRL} key appears in an awkward spot rather than at the far left of the home row. -Usually, when people fix these sorts of keybindings, they do not +Usually, when people fix these sorts of key bindings, they do not change their @file{~/.emacs} file. Instead, they bind the proper keys on their consoles with the @code{loadkeys} or @code{install-keymap} commands in their boot script and then include @code{xmodmap} commands |