diff options
Diffstat (limited to 'doc/lispintro/emacs-lisp-intro.texi')
| -rw-r--r-- | doc/lispintro/emacs-lisp-intro.texi | 407 |
1 files changed, 277 insertions, 130 deletions
diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index fce7583fe91..a06822ce539 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -115,7 +115,7 @@ Edition @value{edition-number}, @value{update-date} @sp 1 Distributed with Emacs version @value{EMACSVER}. @sp 1 -Copyright @copyright{} 1990--1995, 1997, 2001--2023 Free Software +Copyright @copyright{} 1990--1995, 1997, 2001--2024 Free Software Foundation, Inc. @sp 1 @@ -317,7 +317,7 @@ List Processing * 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. +* setq:: Setting the value of a variable. * Summary:: The major points. * Error Message Exercises:: @@ -358,7 +358,6 @@ Arguments Setting the Value of a Variable -* Using set:: Setting values. * Using setq:: Setting a quoted value. * Counting:: Using @code{setq} to count. @@ -1060,7 +1059,7 @@ of Lisp. * 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. +* setq:: Setting the value of a variable. * Summary:: The major points. * Error Message Exercises:: @end menu @@ -1782,7 +1781,7 @@ A symbol can have any value attached to it or, to use the jargon, we can string, @code{"such as this"}; to a list, such as @code{(spruce pine oak)}; we can even bind a variable to a function definition. -A symbol can be bound to a value in several ways. @xref{set & setq, , +A symbol can be bound to a value in several ways. @xref{setq, , Setting the Value of a Variable}, for information about one way to do this. @@ -2273,52 +2272,52 @@ 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 +@node setq @section Setting the Value of a Variable @cindex Variable, setting value @cindex Setting value of variable @cindex @samp{bind} defined -There are several ways by which a variable can be given a value. One of -the ways is to use either the function @code{set} or the special form -@code{setq}. Another way is to use @code{let} (@pxref{let}). (The -jargon for this process is to @dfn{bind} a variable to a value.) +There are several ways by which a variable can be given a value. +One of the ways is to use the special form @code{setq}. Another way +is to use @code{let} (@pxref{let}). (The jargon for this process is +to @dfn{bind} a variable to a value.) -The following sections not only describe how @code{set} and @code{setq} -work but also illustrate how arguments are passed. +The following sections not only describe how @code{setq} works but +also illustrate how arguments are passed. @menu -* Using set:: Setting values. -* Using setq:: Setting a quoted value. +* Using setq:: Setting variables. * Counting:: Using @code{setq} to count. @end menu -@node Using set -@subsection Using @code{set} +@node Using setq +@subsection Using @code{setq} @findex set -To set the value of the symbol @code{flowers} to the list @code{'(rose +To set the value of the symbol @code{flowers} to the list @code{(rose violet daisy buttercup)}, evaluate the following expression by positioning the cursor after the expression and typing @kbd{C-x C-e}. @smallexample -(set 'flowers '(rose violet daisy buttercup)) +(setq flowers '(rose violet daisy buttercup)) @end smallexample @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, -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 -primary effect that we humans are interested in. This is because every -Lisp function must return a value if it does not get an error, but it -will only have a side effect if it is designed to have one.) +area. This is what is @emph{returned} by the @code{setq} special +form. As a 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 primary effect that we humans are interested in. +This is because every Lisp function must return a value if it does not +get an error, but it will only have a side effect if it is designed to +have one.) -After evaluating the @code{set} expression, you can evaluate the symbol -@code{flowers} and it will return the value you just set. Here is the -symbol. Place your cursor after it and type @kbd{C-x C-e}. +After evaluating the @code{setq} expression, you can evaluate the +symbol @code{flowers} and it will return the value you just set. +Here is the symbol. Place your cursor after it and type @kbd{C-x C-e}. @smallexample flowers @@ -2336,30 +2335,8 @@ in front of it, what you will see in the echo area is the symbol itself, 'flowers @end smallexample -Note also, that when you use @code{set}, you need to quote both -arguments to @code{set}, unless you want them evaluated. Since we do -not want either argument evaluated, neither the variable -@code{flowers} nor the list @code{(rose violet daisy buttercup)}, both -are quoted. (When you use @code{set} without quoting its first -argument, the first argument is evaluated before anything else is -done. If you did this and @code{flowers} did not have a value -already, you would get an error message that the @samp{Symbol's value -as variable is void}; on the other hand, if @code{flowers} did return -a value after it was evaluated, the @code{set} would attempt to set -the value that was returned. There are situations where this is the -right thing for the function to do; but such situations are rare.) - -@node Using setq -@subsection Using @code{setq} -@findex setq - -As a practical matter, you almost always quote the first argument to -@code{set}. The combination of @code{set} and a quoted first argument -is so common that it has its own name: the special form @code{setq}. -This special form is just like @code{set} except that the first argument -is quoted automatically, so you don't need to type the quote mark -yourself. Also, as an added convenience, @code{setq} permits you to set -several different variables to different values, all in one expression. +Also, as an added convenience, @code{setq} permits you to set several +different variables to different values, all in one expression. To set the value of the variable @code{carnivores} to the list @code{'(lion tiger leopard)} using @code{setq}, the following expression @@ -2369,18 +2346,6 @@ is used: (setq carnivores '(lion tiger leopard)) @end smallexample -@noindent -This is exactly the same as using @code{set} except the first argument -is automatically quoted by @code{setq}. (The @samp{q} in @code{setq} -means @code{quote}.) - -@need 1250 -With @code{set}, the expression would look like this: - -@smallexample -(set 'carnivores '(lion tiger leopard)) -@end smallexample - Also, @code{setq} can be used to assign different values to different variables. The first argument is bound to the value of the second argument, the third argument is bound to the value of the @@ -2400,14 +2365,14 @@ to the symbol @code{herbivores}: not have fit on a page; and humans find it easier to read nicely formatted lists.) -Although I have been using the term ``assign'', there is another way of -thinking about the workings of @code{set} and @code{setq}; and that is to -say that @code{set} and @code{setq} make the symbol @emph{point} to the -list. This latter way of thinking is very common and in forthcoming -chapters we shall come upon at least one symbol that has ``pointer'' as -part of its name. The name is chosen because the symbol has a value, -specifically a list, attached to it; or, expressed another way, -the symbol is set to point to the list. +Although I have been using the term ``assign'', there is another way +of thinking about the workings of @code{setq}; and that is to say that +@code{setq} makes the symbol @emph{point} to the list. This latter +way of thinking is very common and in forthcoming chapters we shall +come upon at least one symbol that has ``pointer'' as part of its +name. The name is chosen because the symbol has a value, specifically +a list, attached to it; or, expressed another way, the symbol is set +to point to the list. @node Counting @subsection Counting @@ -3591,6 +3556,7 @@ and the two are not intended to refer to the same value. The * Parts of let Expression:: * Sample let Expression:: * Uninitialized let Variables:: +* How let Binds Variables:: @end menu @ifnottex @@ -3598,28 +3564,32 @@ and the two are not intended to refer to the same value. The @unnumberedsubsec @code{let} Prevents Confusion @end ifnottex +@c FIXME!! lexbind!! + @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 -that whenever your host refers to ``the house'', he means his house, not -yours. (Symbols used in argument lists work the same way. +name outside the @code{let} expression (in computer science jargon, we +call this @dfn{binding} the variable). This is like understanding +that in your host's home, whenever he refers to ``the house'', he +means his house, not yours. (The symbols used to name function +arguments are bound as local variables in exactly the same way. @xref{defun, , The @code{defun} Macro}.) -Local variables created by a @code{let} expression retain their value -@emph{only} within the @code{let} expression itself (and within -expressions called within the @code{let} expression); the local -variables have no effect outside the @code{let} expression. - -Another way to think about @code{let} is that it is like a @code{setq} -that is temporary and local. The values set by @code{let} are -automatically undone when the @code{let} is finished. The setting -only affects expressions that are inside the bounds of the @code{let} -expression. In computer science jargon, we would say the binding of -a symbol is visible only in functions called in the @code{let} form; -in Emacs Lisp, the default scoping is dynamic, not lexical. (The -non-default lexical binding is not discussed in this manual.) +Another way to think about @code{let} is that it defines a special +region in your code: within the body of the @code{let} expression, the +variables you've named have their own local meaning. Outside of the +@code{let} body, they have other meanings (or they may not be defined +at all). This means that inside the @code{let} body, calling +@code{setq} for a variable named by the @code{let} expression will set +the value of the @emph{local} variable of that name. However, outside +of the @code{let} body (such as when calling a function that was +defined elsewhere), calling @code{setq} for a variable named by the +@code{let} expression will @emph{not} affect that local +variable.@footnote{This describes the behavior of @code{let} when +using a style called ``lexical binding'' (@pxref{How let Binds +Variables}).} @code{let} can create more than one variable at once. Also, @code{let} gives each variable it creates an initial value, either a @@ -3779,6 +3749,128 @@ number is printed in the message using a @samp{%d} rather than a @samp{%s}.) The four variables as a group are put into a list to delimit them from the body of the @code{let}. +@node How let Binds Variables +@subsection How @code{let} Binds Variables + +Emacs Lisp supports two different ways of binding variable names to +their values. These ways affect the parts of your program where a +particular binding is valid. For historical reasons, Emacs Lisp uses +a form of variable binding called @dfn{dynamic binding} by default. +However, in this manual we discuss the preferred form of binding, +called @dfn{lexical binding}, unless otherwise noted (in the future, +the Emacs maintainers plan to change the default to lexical binding). +If you have programmed in other languages before, you're likely +already familiar with how lexical binding behaves. + +In order to use lexical binding in a program, you should add this to +the first line of your Emacs Lisp file: + +@example +;;; -*- lexical-binding: t -*- +@end example + +For more information about this, @pxref{Variable Scoping, , , +elisp, The Emacs Lisp Reference Manual}. + +@menu +* Lexical & Dynamic Binding Differences:: +* Lexical vs. Dynamic Binding Example:: +@end menu + +@node Lexical & Dynamic Binding Differences +@unnumberedsubsubsec Differences Between Lexical and Dynamic Binding + +@cindex Lexical binding +@cindex Binding, lexical +As we discussed before (@pxref{Prevent confusion}), when you create +local variables with @code{let} under lexical binding, those variables +are valid only within the body of the @code{let} expression. In other +parts of your code, they have other meanings, so if you call a +function defined elsewhere within the @code{let} body, that function +would be unable to ``see'' the local variables you've created. (On +the other hand, if you call a function that was defined within a +@code{let} body, that function @emph{would} be able to see---and +modify---the local variables from that @code{let} expression.) + +@cindex Dynamic binding +@cindex Binding, dynamic +Under dynamic binding, the rules are different: instead, when you use +@code{let}, the local variables you've created are valid during +execution of the @code{let} expression. This means that, if your +@code{let} expression calls a function, that function can see these +local variables, regardless of where the function is defined +(including in another file entirely). + +Another way to think about @code{let} when using dynamic binding is +that every variable name has a global ``stack'' of bindings, and +whenever you use that variable's name, it refers to the binding on the +top of the stack. (You can imagine this like a stack of papers on +your desk with the values written on them.) When you bind a variable +dynamically with @code{let}, it puts the new binding you've specified +on the top of the stack, and then executes the @code{let} body. Once +the @code{let} body finishes, it takes that binding off of the stack, +revealing the one it had (if any) before the @code{let} expression. + +@node Lexical vs. Dynamic Binding Example +@unnumberedsubsubsec Example of Lexical vs. Dynamic Binding +In some cases, both lexical and dynamic binding behave identically. +However, in other cases, they can change the meaning of your program. +For example, see what happens in this code under lexical binding: + +@example +;;; -*- lexical-binding: t -*- + +(setq x 0) + +(defun getx () + x) + +(setq x 1) + +(let ((x 2)) + (getx)) + @result{} 1 +@end example + +@noindent +Here, the result of @code{(getx)} is @code{1}. Under lexical binding, +@code{getx} doesn't see the value from our @code{let} expression. +That's because the body of @code{getx} is outside of the body of our +@code{let} expression. Since @code{getx} is defined at the top, +global level of our code (i.e.@: not inside the body of any @code{let} +expression), it looks for and finds @code{x} at the global level as +well. When executing @code{getx}, the current global value of +@code{x} is @code{1}, so that's what @code{getx} returns. + +If we use dynamic binding instead, the behavior is different: + +@example +;;; -*- lexical-binding: nil -*- + +(setq x 0) + +(defun getx () + x) + +(setq x 1) + +(let ((x 2)) + (getx)) + @result{} 2 +@end example + +@noindent +Now, the result of @code{(getx)} is @code{2}! That's because under +dynamic binding, when executing @code{getx}, the current binding for +@code{x} at the top of our stack is the one from our @code{let} +binding. This time, @code{getx} doesn't see the global value for +@code{x}, since its binding is below the one from our @code{let} +expression in the stack of bindings. + +(Some variables are also ``special'', and they are always dynamically +bound even when @code{lexical-binding} is @code{t}. @xref{defvar, , +Initializing a Variable with @code{defvar}}.) + @node if @section The @code{if} Special Form @findex if @@ -4471,9 +4563,7 @@ number; it will be printed as the character with that @sc{ascii} code. The @code{setq} special form sets the value of its first argument to the value of the second argument. The first argument is automatically quoted by @code{setq}. It does the same for succeeding pairs of -arguments. Another function, @code{set}, takes only two arguments and -evaluates both of them before setting the value returned by its first -argument to the value returned by its second argument. +arguments. @item buffer-name Without an argument, return the name of the buffer, as a string. @@ -5445,7 +5535,11 @@ 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. +evaluates its body with that buffer temporarily current, after which +it will switch back to the buffer we are at now@footnote{It is like +calling @w{@code{(save-excursion (set-buffer @dots{}) @dots{})}} in +one go, though it is defined slightly differently which interested +reader can find out using @code{describe-function}.}. (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 @@ -5982,12 +6076,12 @@ In outline, the whole function looks like this: (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} + (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 @@ -6040,12 +6134,13 @@ like this: @group (if (> (buffer-size) 10000) ;; @r{Avoid overflow for large buffer sizes!} - (* (prefix-numeric-value arg) - (/ size 10)) + (* (prefix-numeric-value arg) + (/ size 10)) (/ (+ 10 - (* - size (prefix-numeric-value arg))) 10))) + (* size + (prefix-numeric-value arg))) + 10)) @end group @end smallexample @@ -6182,7 +6277,7 @@ The code looks like this: @c Keep this on one line. @smallexample -(/ (+ 10 (* size (prefix-numeric-value arg))) 10)) +(/ (+ 10 (* size (prefix-numeric-value arg))) 10) @end smallexample @need 1200 @@ -6199,7 +6294,7 @@ enclosing expression: (* size (prefix-numeric-value arg))) - 10)) + 10) @end group @end smallexample @@ -8165,9 +8260,9 @@ the expectation that all goes well has a @code{when}. The code uses text that exists. A @code{when} expression is simply a programmers' convenience. It is -an @code{if} without the possibility of an else clause. In your mind, -you can replace @code{when} with @code{if} and understand what goes -on. That is what the Lisp interpreter does. +like an @code{if} without the possibility of an else clause. In your +mind, you can replace @code{when} with @code{if} and understand what +goes on. That is what the Lisp interpreter does. Technically speaking, @code{when} is a Lisp macro. A Lisp macro enables you to define new control constructs and other language @@ -8176,8 +8271,9 @@ expression which will in turn compute the value. In this case, the other expression is an @code{if} expression. The @code{kill-region} function definition also has an @code{unless} -macro; it is the converse of @code{when}. The @code{unless} macro is -an @code{if} without a then clause +macro; it is the opposite of @code{when}. The @code{unless} macro is +like an @code{if} except that it has no then-clause, and it supplies +an implicit @code{nil} for that. For more about Lisp macros, see @ref{Macros, , Macros, elisp, The GNU Emacs Lisp Reference Manual}. The C programming language also @@ -9130,12 +9226,14 @@ In Emacs Lisp, a variable such as the @code{kill-ring} is created and given an initial value by using the @code{defvar} special form. The name comes from ``define variable''. -The @code{defvar} special form is similar to @code{setq} in that it sets -the value of a variable. It is unlike @code{setq} in two ways: first, -it only sets the value of the variable if the variable does not already -have a value. If the variable already has a value, @code{defvar} does -not override the existing value. Second, @code{defvar} has a -documentation string. +The @code{defvar} special form is similar to @code{setq} in that it +sets the value of a variable. It is unlike @code{setq} in three ways: +first, it marks the variable as ``special'' so that it is always +dynamically bound, even when @code{lexical-binding} is @code{t} +(@pxref{How let Binds Variables}). Second, it only sets the value of +the variable if the variable does not already have a value. If the +variable already has a value, @code{defvar} does not override the +existing value. Third, @code{defvar} has a documentation string. (There is a related macro, @code{defcustom}, designed for variables that people customize. It has more features than @code{defvar}. @@ -12876,7 +12974,40 @@ The next line of the @code{forward-paragraph} function begins a 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}. +@code{found-start}. The first part of the @code{let*} expression +looks like below: + +@smallexample +@group +(let* ((opoint (point)) + (fill-prefix-regexp + (and fill-prefix (not (equal fill-prefix "")) + (not paragraph-ignore-fill-prefix) + (regexp-quote fill-prefix))) + ;; Remove ^ from paragraph-start and paragraph-sep if they are there. + ;; These regexps shouldn't be anchored, because we look for them + ;; starting at the left-margin. This allows paragraph commands to + ;; work normally with indented text. + ;; This hack will not find problem cases like "whatever\\|^something". + (parstart (if (and (not (equal "" paragraph-start)) + (equal ?^ (aref paragraph-start 0))) + (substring paragraph-start 1) + paragraph-start)) + (parsep (if (and (not (equal "" paragraph-separate)) + (equal ?^ (aref paragraph-separate 0))) + (substring paragraph-separate 1) + paragraph-separate)) + (parsep + (if fill-prefix-regexp + (concat parsep "\\|" + fill-prefix-regexp "[ \t]*$") + parsep)) + ;; This is used for searching. + (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)")) + start found-start) + ...) +@end group +@end smallexample The variable @code{parsep} appears twice, first, to remove instances of @samp{^}, and second, to handle fill prefixes. @@ -13244,6 +13375,10 @@ The last expression when there is no fill prefix is @end smallexample @noindent +(Note that this code snippet is copied verbatim from the original code, +so the two extra ending parentheses are matching the previous @code{if} +and @code{while}.) + This says that if there is no fill prefix and if we are not at the end, point should move to the beginning of whatever was found by the regular expression search for @code{sp-parstart}. @@ -14624,7 +14759,7 @@ almost the same code as for the recursive version of @need 800 @noindent -Let's re-use @kbd{C-c =} as a convenient key binding: +Let's reuse @kbd{C-c =} as a convenient key binding: @smallexample (global-set-key "\C-c=" 'count-words-defun) @@ -15793,6 +15928,7 @@ of the @code{and} expression. @c colon in printed section title causes problem in Info cross reference This way, we avoid an error. + @iftex @noindent (For information about @code{and}, see @@ -16883,8 +17019,14 @@ remember to look here to remind myself. @node Text and Auto-fill @section Text and Auto Fill Mode -Now we come to the part that turns on Text mode and -Auto Fill mode. +Now we come to the part that turns on Text mode and Auto Fill +mode@footnote{ +This section suggests settings that are more suitable for writers. +For programmers, the default mode will be set to the corresponding +prog-mode automatically based on the type of the file. And it's +perfectly fine if you want to keep the fundamental mode as the default +mode. +}. @smallexample @group @@ -16936,21 +17078,26 @@ Here is the line again; how does it work? @cindex Text Mode turned on @smallexample -(setq major-mode 'text-mode) +(setq-default major-mode 'text-mode) @end smallexample @noindent This line is a short, but complete Emacs Lisp expression. -We are already familiar with @code{setq}. It sets the following variable, -@code{major-mode}, to the subsequent value, which is @code{text-mode}. -The single-quote before @code{text-mode} tells Emacs to deal directly -with the @code{text-mode} symbol, not with whatever it might stand for. -@xref{set & setq, , Setting the Value of a Variable}, -for a reminder of how @code{setq} works. -The main point is that there is no difference between the procedure you -use to set a value in your @file{.emacs} file and the procedure you use -anywhere else in Emacs. +We are already familiar with @code{setq}. We use a similar macro +@code{setq-default} to set the following variable, +@code{major-mode}@footnote{ +We use @code{setq-default} here because @code{text-mode} is +buffer-local. If we use @code{setq}, it will only apply to the +current buffer, whereas using @code{setq-default} will also apply to +newly created buffers. This is not recommended for programmers. +}, to the subsequent value, which is @code{text-mode}. The +single-quote before @code{text-mode} tells Emacs to deal directly with +the @code{text-mode} symbol, not with whatever it might stand for. +@xref{setq, , Setting the Value of a Variable}, for a reminder of how +@code{setq} works. The main point is that there is no difference +between the procedure you use to set a value in your @file{.emacs} +file and the procedure you use anywhere else in Emacs. @need 800 Here is the next line: |