SGI Freeware 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ SGI Freeware 2001 May / SGI Freeware 2001 May - Disc 3.iso / dist / fw_elisp-intro.idb / usr / freeware / info / emacs-lisp-intro.info-2.z / emacs-lisp-intro.info-2

Wrap

GNU Info File | 1998-10-28 | 47.9 KB | 1,099 lines

This is Info file emacs-lisp-intro.info, produced by Makeinfo version 1.67 from the input file emacs-lisp-intro.texi. This is an introduction to `Programming in Emacs Lisp', for people who are not programmers. Edition 1.05, 21 October 1997 Copyright (C) 1990, '91, '92, '93, '94, '95, '97 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled "Copying" and "GNU General Public License" are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. File: emacs-lisp-intro.info, Node: Evaluating Inner Lists, Prev: Evaluation, Up: Evaluation Evaluating Inner Lists ---------------------- If evaluation applies to a list that is inside another list, the outer list may use the value returned by the first evaluation as information when the outer list is evaluated. This explains why inner expressions are evaluated first: the values they return are used by the outer expressions. We can investigate this process by evaluating another addition example. Place your cursor after the following expression and type `C-x C-e': (+ 2 (+ 3 3)) The number 8 will appear in the echo area. What happens is that the Lisp interpreter first evaluates the inner expression, `(+ 3 3)', for which the value 6 is returned; then it evaluates the outer expression as if it were written `(+ 2 6)', which returns the value 8. Since there are no more enclosing expressions to evaluate, the interpreter prints that value in the echo area. Now it is easy to understand the name of the command invoked by the keystrokes `C-x C-e': the name is `eval-last-sexp'. The letters `sexp' are an abbreviation for `symbolic expression', and `eval' is an abbreviation for `evaluate'. The command means `evaluate last symbolic expression'. As an experiment, you can try evaluating the expression by putting the cursor at the beginning of the next line immediately following the expression, or inside the expression. Here is another copy of the expression: (+ 2 (+ 3 3)) If you place the cursor at the beginning of the blank line that immediately follows the expression and type `C-x C-e', you will still get the value 8 printed in the echo area. Now try putting the cursor inside the expression. If you put it right after the next to last parenthesis (so it appears to sit on top of the last parenthesis), you will get a 6 printed in the echo area! This is because the command evaluates the expression `(+ 3 3)'. Now put the cursor immediately after a number. Type `C-x C-e' and you will get the number itself. In Lisp, if you evaluate a number, you get the number itself--this is how numbers differ from symbols. If you evaluate a list starting with a symbol like `+', you will get a value returned that is the result of the computer carrying out the instructions in the function definition attached to that name. If a symbol by itself is evaluated, something different happens, as we will see in the next section. File: emacs-lisp-intro.info, Node: Variables, Next: Arguments, Prev: Evaluation, Up: List Processing Variables ========= In Lisp, a symbol can have a value attached to it just as it can have a function definition attached to it. The two are different. The function definition is a set of instructions that a computer will obey. A value, on the other hand, is something, such as number or a name, that can vary (which is why such a symbol is called a variable). The value of a symbol can be any expression in Lisp, such as a symbol, number, list, or string. A symbol that has a value is often called a "variable". A symbol can have both a function definition and a value attached to it at the same time. The two are separate. This is somewhat similar to the way the name Cambridge can refer to the city in Massachusetts and have some information attached to the name as well, such as "great programming center". Another way of thinking of this is to imagine a symbol as being a chest of drawers. The function definition is put in one drawer, the value in another, and so on. What is put in the drawer holding the value can be changed without affecting the contents of the drawer holding the function definition, and vice-versa. The variable `fill-column' illustrates a symbol with a value attached to it: in every GNU Emacs buffer, this symbol is set to some value, usually 72 or 70, but sometimes to some other value. To find the value of this symbol, evaluate it by itself. If you are reading this in Info inside of GNU Emacs, you can do this by putting the cursor after the symbol and typing `C-x C-e': fill-column After I typed `C-x C-e', Emacs printed the number 72 in my echo area. This is the value for which `fill-column' is set for me as I write this. It may be different for you in your Info buffer. Notice that the value returned as a variable is printed in exactly the same way as the value returned by a function carrying out its instructions. From the point of view of the Lisp interpreter, a value returned is a value returned. What kind of expression it came from ceases to matter once the value is known. A symbol can have any value attached to it or, to use the jargon, we can "bind" the variable to a value: to a number, such as 72; to a string, `"such as this"'; to a list, such as `(spruce pine oak)'; we can even bind a variable to a function definition. A symbol can be bound to a value in several ways. *Note Setting the Value of a Variable: set & setq, for information about one way to do this. Notice that there were no parentheses around the word `fill-column' when we evaluated it to find its value. This is because we did not intend to use it as a function name. If `fill-column' were the first or only element of a list, the Lisp interpreter would attempt to find the function definition attached to it. But `fill-column' has no function definition. Try evaluating this: (fill-column) You will produce an error message that says: Symbol's function definition is void: fill-column * Menu: * Void Variable:: The error message for a symbol without a value. File: emacs-lisp-intro.info, Node: Void Variable, Prev: Variables, Up: Variables Error Message for a Symbol Without a Value ------------------------------------------ If you attempt to evaluate a symbol that does not have a value bound to it, you will receive an error message. You can see this by experimenting with our 2 plus 2 addition. In the following expression, put your cursor right after the `+', before the first number 2, type `C-x C-e': (+ 2 2) You will get an error message that says: Symbol's value as variable is void: + This is different from the first error message we saw, which said, `Symbol's function definition is void: this'. In this case, the symbol does not have a value as a variable; in the other case, the symbol (which was the word `this') did not have a function definition. In this experiment with the `+', what we did was cause the Lisp interpreter to evaluate the `+' and look for the value of the variable instead of the function definition. We did this by placing the cursor right after the symbol rather than after the parenthesis of the enclosing list as we did before. As a consequence, the Lisp interpreter evaluated the preceding s-expression, which in this case was the `+' by itself. Since `+' 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. File: emacs-lisp-intro.info, Node: Arguments, Next: set & setq, Prev: Variables, Up: List Processing Arguments ========= To see how information is passed to functions, let's look again at our old standby, the addition of two plus two. In Lisp, this is written as follows: (+ 2 2) If you evaluate this expression, the number 4 will appear in your echo area. What the Lisp interpreter does is add the numbers that follow the `+'. The numbers added by `+' are called the "arguments" of the function `+'. These numbers are the information that is given to or "passed" to the function. The word `argument' comes from the way it is used in mathematics and does not refer to a disputation between two people; instead it refers to the information presented to the function, in this case, to the `+'. In Lisp, the arguments to a function are the atoms or lists that follow the function. The values returned by the evaluation of these atoms or lists are passed to the function. Different functions require different numbers of arguments; some functions require none at all.(1) * 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. ---------- Footnotes ---------- (1) It is curious to track the path by which the word `argument' came to have two different meanings, one in mathematics and the other in everyday English. According to the `Oxford English Dictionary', the word derives from the Latin for `to make clear, prove'; thus it came to mean, by one thread of derivation, `the evidence offered as proof', which is to say, `the information offered', which led to its meaning in Lisp. But in the other thread of derivation, it came to mean `to assert in a manner against which others may make counter assertions', which led to the meaning of the word as a disputation. (Note here that the English word has two different definitions attached to it at the same time. By contrast, in Emacs Lisp, a symbol cannot have two different function definitions at the same time.) File: emacs-lisp-intro.info, Node: Data types, Next: Args as Variable or List, Prev: Arguments, Up: Arguments Arguments' Data Types --------------------- The type of data that should be passed to a function depends on what kind of information it uses. The arguments to a function such as `+' must have values that are numbers, since `+' adds numbers. Other functions use different kinds of data for their arguments. For example, the `concat' function links together or unites two or more strings of text to produce a string. The arguments are strings. Concatenating the two character strings `abc', `def' produces the single string `abcdef'. This can be seen by evaluating the following: (concat "abc" "def") The value produced by evaluating this expression is `"abcdef"'. A function such as `substring' uses both a string and numbers as arguments. The function returns a part of the string, a substring of the first argument. This function takes three arguments. Its first argument is the string of characters, the second and third arguments are numbers that indicate the beginning and end of the substring. The numbers are a count of the number of characters (including spaces and punctuations) from the beginning of the string. For example, if you evaluate the following: (substring "The quick brown fox jumped." 16 19) you will see `"fox"' appear in the echo area. The arguments are the string and the two numbers. Note that the string passed to `substring' is a single atom even though it is made up of several words separated by spaces. Lisp counts everything between the two quotation marks as part of the string, including the spaces. You can think of the `substring' function as a kind of `atom smasher' since it takes an otherwise indivisible atom and extracts a part. However, `substring' is only able to extract a substring from an argument that is a string, not from another type of atom such as a number or symbol. File: emacs-lisp-intro.info, Node: Args as Variable or List, Next: Variable Number of Arguments, Prev: Data types, Up: Arguments An Argument as the Value of a Variable or List ---------------------------------------------- An argument can be a symbol that returns a value when it is evaluated. For example, when the symbol `fill-column' by itself is evaluated, it returns a number. This number can be used in an addition. Position the cursor after the following expression and type `C-x C-e': (+ 2 fill-column) The value will be a number two more than what you get by evaluating `fill-column' alone. For me, this is 74, because the value of `fill-column' is 72. As we have just seen, an argument can be a symbol that returns a value when evaluated. In addition, an argument can be a list that returns a value when it is evaluated. For example, in the following expression, the arguments to the function `concat' are the strings `"The "' and `" red foxes."' and the list `(+ 2 fill-column)'. (concat "The " (+ 2 fill-column) " red foxes.") If you evaluate this expression, `"The 74 red foxes."' will appear in the echo area. (Note that you must put spaces after the word `The' and before the word `red' so they will appear in the final string.) File: emacs-lisp-intro.info, Node: Variable Number of Arguments, Next: Wrong Type of Argument, Prev: Args as Variable or List, Up: Arguments Variable Number of Arguments ---------------------------- Some functions, such as `concat', `+' or `*', take any number of arguments. (The `*' is the symbol for multiplication.) This can be seen by evaluating each of the following expressions in the usual way. What you will see in the echo area is printed in this text after `=>', which you may read as `evaluates to'. In the first set, the functions have no arguments: (+) => 0 (*) => 1 In this set, the functions have one argument each: (+ 3) => 3 (* 3) => 3 In this set, the functions have three arguments each: (+ 3 4 5) => 12 (* 3 4 5) => 60 File: emacs-lisp-intro.info, Node: Wrong Type of Argument, Next: message, Prev: Variable Number of Arguments, Up: Arguments Using the Wrong Type Object as an Argument ------------------------------------------ When a function is passed an argument of the wrong type, the Lisp interpreter produces an error message. For example, the `+' function expects the values of its arguments to be numbers. As an experiment we can pass it the quoted symbol `hello' instead of a number. Position the cursor after the following expression and type `C-x C-e': (+ 2 'hello) When you do this you will generate an error message. What has happened is that `+' has tried to add the 2 to the value returned by `'hello', but the value returned by `'hello' is the symbol `hello', not a number. Only numbers can be added. So `+' could not carry out its addition. As usual, the error message tries to be helpful and makes sense after you learn how to read it. What it says is this: Wrong type argument: integer-or-marker-p, hello The first part of the error message is straightforward; it says `Wrong type argument'. Next comes the mysterious jargon word `integer-or-marker-p'. This word is trying to tell you what kind of argument the `+' expected. The symbol `integer-or-marker-p' says that the Lisp interpreter is trying to determine whether the information presented it (the value of the argument) is an integer (that is, a whole number) or a marker (a special object representing a buffer position). What it does is test to see whether the `+' is being given whole numbers to add. It also tests to see whether the argument is something called a marker, which is a specific feature of Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. When the mark is set with the `C-@' or `C-<SPC>' command, its position is kept as a marker. The mark can be considered a number--the number of characters the location is from the beginning of the buffer.) In Emacs Lisp, `+' can be used to add the numeric value of marker positions as numbers. The `p' of `integer-or-marker-p' is the embodiment of a practice started in the early days of Lisp programming. The `p' stands for `predicate'. In the jargon used by the early Lisp researchers, a predicate refers to a function to determine whether some property is true or false. So the `p' tells us that `integer-or-marker-p' is the name of a function that determines whether it is true or false that the argument supplied is an integer or a marker. Other Lisp symbols that end in `p' include `zerop', a function that tests whether its argument has the value of zero, and `listp', a function that tests whether its argument is a list. Finally, the last part of the error message is the symbol `hello'. This is the value of the argument that was passed to `+'. If the 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 `hello'. But then you would not have got the error message. File: emacs-lisp-intro.info, Node: message, Prev: Wrong Type of Argument, Up: Arguments The `message' Function ---------------------- Like `+', the `message' function takes a variable number of arguments. It is used to send messages to the user and is so useful that we will describe it here. A message is printed in the echo area. For example, you can print a message in your echo area by evaluating the following list: (message "This message appears in the echo area!") The whole string between double quotation marks is a single argument and is printed in toto. (Note that in this example, the message itself will appear in the echo area within double quotes; that is because you see the value returned by the `message' function. In most uses of `message' in programs that you write, the text will be printed in the echo area as a side-effect, without the quotes. *Note `multiply-by-seven' in detail: multiply-by-seven in detail, for an example of this.) However, if there is a `%s' in the quoted string of characters, the `message' function does not print the `%s' as such, but looks to the argument that follows the string. It evaluates the second argument and prints the value in the location in the string where the `%s' is. You can see this by positioning the cursor after the following expression and typing `C-x C-e': (message "The name of this buffer is: %s." (buffer-name)) In Info, `"The name of this buffer is: *info*."' will appear in the echo area. The function `buffer-name' returns the name of the buffer as a string, which the `message' function inserts in place of `%s'. To print a value as a decimal number, use `%d' in the same way as `%s'. For example, to print a message in the echo area that states the value of the `fill-column', evaluate the following: (message "The value of fill-column is %d." fill-column) On my system, when I evaluate this list, `"The value of fill-column is 72."' appears in my echo area. If there is more than one `%s' in the quoted string, the value of the first argument following the quoted string is printed at the location of the first `%s' and the value of the second argument is printed at the location of the second `%s', and so on. For example, if you evaluate the following, (message "There are %d %s in the office!" (- fill-column 14) "pink elephants") a rather whimsical message will appear in your echo area. On my system it says, `"There are 58 pink elephants in the office!"'. The expression `(- fill-column 14)' is evaluated and the resulting number is inserted in place of the `%d'; and the string in double quotes, `"pink elephants"', is treated as a single argument and inserted in place of the `%s'. (That is to say, a string between double quotes evaluates to itself, like a number.) Finally, here is a somewhat complex example that not only illustrates the computation of a number, but also shows how you can use an expression within an expression to generate the text that is substituted for `%s': (message "He saw %d %s" (- fill-column 34) (concat "red " (substring "The quick brown foxes jumped." 16 21) " leaping.")) In this example, `message' has three arguments: the string, `"He saw %d %s"', the expression, `(- fill-column 32)', and the expression beginning with the function `concat'. The value resulting from the evaluation of `(- fill-column 32)' is inserted in place of the `%d'; and the value returned by the expression beginning with `concat' is inserted in place of the `%s'. When I evaluate the expression, the message, `"He saw 38 red foxes leaping."', appears in my echo area. File: emacs-lisp-intro.info, Node: set & setq, Next: Summary, Prev: Arguments, Up: List Processing Setting the Value of a Variable =============================== There are several ways by which a variable can be given a value. One of the ways is to use either the function `set' or the function `setq'. Another way is to use `let' (*note let::.). (The jargon for this process is to "bind" a variable to a value.) The following sections not only describe how `set' and `setq' work but also illustrate how arguments are passed. * Menu: * Using set:: Setting values. * Using setq:: Setting a quoted value. * Counting:: Using `setq' to count. File: emacs-lisp-intro.info, Node: Using set, Next: Using setq, Prev: set & setq, Up: set & setq Using `set' ----------- To set the value of the symbol `flowers' to the list `'(rose violet daisy buttercup)', evaluate the following expression by positioning the cursor after the expression and typing `C-x C-e'. (set 'flowers '(rose violet daisy buttercup)) The list `(rose violet daisy buttercup)' will appear in the echo area. This is what is *returned* by the `set' function. As a side effect, the symbol `flowers' is bound to the list ; that is, the symbol `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 `set' expression, you can evaluate the symbol `flowers' and it will return the value you just set. Here is the symbol. Place your cursor after it and type `C-x C-e'. flowers When you evaluate `flowers', the list `(rose violet daisy buttercup)' appears in the echo area. Incidentally, if you evaluate `'flowers', the variable with a quote in front of it, what you will see in the echo area is the symbol itself, `flowers'. Here is the quoted symbol, so you can try this: 'flowers Note also, that when you use `set', you need to quote both arguments to `set', unless you want them evaluated. In this case, we do not want either argument evaluated, neither the variable `flowers' nor the list `(rose violet daisy buttercup)', so both are quoted. (When you use `set' without quoting its first argument, the first argument is evaluated before anything else is done. If you did this and `flowers' did not have a value already, you would get an error message that the `Symbol's value as variable is void'; on the other hand, if `flowers' did return a value after it was evaluated, the `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.) File: emacs-lisp-intro.info, Node: Using setq, Next: Counting, Prev: Using set, Up: set & setq Using `setq' ------------ As a practical matter, you almost always quote the first argument to `set'. The combination of `set' and a quoted first argument is so common that it has its own name: the special form `setq'. This special form is just like `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, `setq' permits you to set several different variables to different values, all in one expression. To set the value of the variable `carnivores' to the list `'(lion tiger leopard)' using `setq', the following expression is used: (setq carnivores '(lion tiger leopard)) This is exactly the same as using `set' except the first argument is automatically quoted by `setq'. (The `q' in `setq' means `quote'.) With `set', the expression would look like this: (set 'carnivores '(lion tiger leopard)) Also, `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 fourth argument, and so on. For example, you could use the following to assign a list of trees to the symbol `trees' and a list of herbivores to the symbol `herbivores': (setq trees '(pine fir oak maple) herbivores '(gazelle antelope zebra)) (The expression could just as well have been on one line, but it might 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 `set' and `setq'; and that is to say that `set' and `setq' make the symbol *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 in this other way, the symbol is set to "point" to the list. File: emacs-lisp-intro.info, Node: Counting, Prev: Using setq, Up: set & setq Counting -------- Here is an example that shows how to use `setq' in a counter. You might use this to count how many times a part of your program repeats itself. First set a variable to zero; then add one to the number each time the program repeats itself. To do this, you need a variable that serves as a counter, and two expressions: an initial `setq' expression that sets the counter variable to zero; and a second `setq' expression that increments the counter each time it is evaluated. (setq counter 0) ; Let's call this the initializer. (setq counter (+ counter 1)) ; This is the incrementer. counter ; This is the counter. (The text following the `;' are comments. *Note Change a Function Definition: Change a defun.) If you evaluate the first of these expressions, the initializer, `(setq counter 0)', and then evaluate the third expression, `counter', the number `0' will appear in the echo area. If you then evaluate the second expression, the incrementer, `(setq counter (+ counter 1))', the counter will get the value 1. So if you again evaluate `counter', the number `1' will appear in the echo area. Each time you evaluate the second expression, the value of the counter will be incremented. When you evaluate the incrementer, `(setq counter (+ counter 1))', the Lisp interpreter first evaluates the innermost list; this is the addition. In order to evaluate this list, it must evaluate the variable `counter' and the number `1'. When it evaluates the variable `counter', it receives its current value. It passes this value and the number `1' to the `+' which adds them together. The sum is then returned as the value of the inner list and passed to the `setq' which sets the variable `counter' to this new value. Thus, the value of the variable, `counter', is changed. File: emacs-lisp-intro.info, Node: Summary, Next: Error Message Exercises, Prev: set & setq, Up: List Processing Summary ======= Learning Lisp is like climbing a hill in which the first part is the steepest. You have now climbed the most difficult part; what remains becomes easier as you progress onwards. In summary, * Lisp programs are made up of expressions, which are lists or single atoms. * Lists are made up of zero or more atoms or inner lists, separated by whitespace and surrounded by parentheses. A list can be empty. * Atoms are multi-character symbols, like `forward-paragraph', single character symbols like `+', strings of characters between double quotation marks, or numbers. * A number evaluates to itself. * A string between double quotes also evaluates to itself. * When you evaluate a symbol by itself, its value is returned. * When you evaluate a list, the Lisp interpreter looks at the first symbol in the list and then at the function definition bound to that symbol. Then the instructions in the function definition are carried out. * A single-quote, `'', 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. * Arguments are the information passed to a function. The arguments to a function are computed by evaluating the rest of the elements of the list of which the function is the first element. * A function always returns a value when it is evaluated (unless it gets an error); in addition, it may also carry out some action called a "side effect". In many cases, a function's primary purpose is to create a side effect. File: emacs-lisp-intro.info, Node: Error Message Exercises, Prev: Summary, Up: List Processing Exercises ========= A few simple exercises: * Generate an error message by evaluating an appropriate symbol that is not within parentheses. * Generate an error message by evaluating an appropriate symbol that is between parentheses. * Create a counter that increments by two rather than one. * Write an expression that prints a message in the echo area when evaluated. File: emacs-lisp-intro.info, Node: Practicing Evaluation, Next: Writing Defuns, Prev: List Processing, Up: Top Practicing Evaluation ********************* Before learning how to write a function definition in Emacs Lisp, it is useful to spend a little time evaluating various expressions that have already been written. These expressions will be lists with the functions as their first (and often only) element. Since some of the functions associated with buffers are both simple and interesting, we will start with those. In this section, we will evaluate a few of 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 `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:: File: emacs-lisp-intro.info, Node: How to Evaluate, Next: Buffer Names, Prev: Practicing Evaluation, Up: Practicing Evaluation How to Evaluate =============== Whenever you give an editing command to Emacs Lisp, such as the command to move the cursor or to scroll the screen, you are evaluating an expression, the first element of which is the function. This is how Emacs works. When you type keys, you cause the Lisp interpreter to evaluate an expression and that is how you get your results. Even typing plain text involves evaluating an Emacs Lisp function, in this case, one that uses `self-insert-command', which simply inserts the character you typed. The functions you evaluate by typing keystrokes are called "interactive" functions, or "commands"; how you make a function interactive will be illustrated in the chapter on how to write function definitions. *Note Making a Function Interactive: Interactive. In addition to typing keyboard commands, we have seen a second way to evaluate an expression: by positioning the cursor after a list and typing `C-x C-e'. This is what we will do in the rest of this section. There are other ways to evaluate an expression as well; these ways will be described in other sections as we come to them. Besides being used for practicing evaluation, the functions shown in the next few sections are important in their own right. A study of these functions makes clear the distinction between buffers and files, how to switch to a buffer, and how to determine a location within it. File: emacs-lisp-intro.info, Node: Buffer Names, Next: Getting Buffers, Prev: How to Evaluate, Up: Practicing Evaluation Buffer Names ============ The two functions, `buffer-name' and `buffer-file-name', show the difference between a file and a buffer. When you evaluate the following expression, `(buffer-name)', the name of the buffer appears in the echo area. When you evaluate `(buffer-file-name)', the name of the file to which the buffer refers appears in the echo area. Usually, the name returned by `(buffer-name)' is the same as the name of the file to which it refers, and the name returned by `(buffer-file-name)' is the full path-name of the file. A file and a buffer are two different entities. A file is information recorded permanently in the computer (unless you delete it). A buffer, on the other hand, is information inside of Emacs that will vanish at the end of the editing session (or when you kill the buffer). Usually, a buffer contains information that you have copied from a file; we say the buffer is "visiting" that file. This copy is what you work on and modify. Changes to the buffer do not change the file, until you save the buffer. When you save the buffer, the buffer is copied to the file and is thus saved permanently. 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 `C-x C-e'. (buffer-name) (buffer-file-name) When I do this, `"introduction.texinfo"' is the value returned by evaluating `(buffer-name)', and `"/gnu/work/intro/introduction.texinfo"' is the value returned by evaluating `(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 `buffer-name' and `buffer-file-name' as functions; without the parentheses, the interpreter would attempt to evaluate the symbols as variables. *Note 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. Indeed, most people say, "I am editing a file," rather than saying, "I am editing a buffer which I will soon save to a file." It is almost always clear from context what people mean. When dealing with computer programs, however, it is important to keep the distinction in mind, since the computer is not as smart as a person. The word `buffer', by the way, comes from the meaning of the word as a cushion that deadens the force of a collision. In early computers, a buffer cushioned the interaction between files and the computer's central processing unit. The drums or tapes that held a file and the central processing unit were pieces of equipment that were very different from each other, working at their own speeds, in spurts. The buffer made it possible for them to work together effectively. Eventually, the buffer grew from being an intermediary, a temporary holding place, to being the place where work is done. This transformation is rather like that of a small seaport that grew into a 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 `emacs' alone, without naming any files, Emacs will start with the `*scratch*' buffer on the screen. This buffer is not visiting any file. Similarly, a `*Help*' buffer is not associated with any file. If you switch to the `*scratch*' buffer, type `(buffer-name)', position the cursor after it, and type `C-x C-e' to evaluate the expression, the name `"*scratch*"' is returned and will appear in the echo area. `"*scratch*"' is the name of the buffer. However, if you type `(buffer-file-name)' in the `*scratch*' buffer and evaluate that, `nil' will appear in the echo area. `nil' is from the Latin word for `nothing'; in this case, it means that the `*scratch*' buffer is not associated with any file. (In Lisp, `nil' is also used to mean `false' and is a synonym for the empty list, `()'.) Incidentally, if you are in the `*scratch*' buffer and want the value returned by an expression to appear in the `*scratch*' buffer itself rather than in the echo area, type `C-u C-x C-e' instead of `C-x C-e'. This causes the value returned to appear after the expression. The buffer will look like this: (buffer-name)"*scratch*" You cannot do this in Info since Info is read-only and it will not allow you to change the contents of the buffer. But you can do this in any buffer you can edit; and when you write code or documentation (such as this manual), this feature is very useful. File: emacs-lisp-intro.info, Node: Getting Buffers, Next: Switching Buffers, Prev: Buffer Names, Up: Practicing Evaluation Getting Buffers =============== The `buffer-name' function returns the *name* of the buffer; to get the buffer *itself*, a different function is needed: the `current-buffer' function. If you use this function in code, what you get is the buffer itself. A name and the object or entity to which the name refers are different from each other. You are not your name. You are a person to whom others refer by name. If you ask to speak to George and someone hands you a card with the letters `G', `e', `o', `r', `g', and `e' written on it, you might be amused, but you would not be satisfied. You do not want to speak to the name, but to the person to whom the name refers. A buffer is similar: the name of the scratch buffer is `*scratch*', but the name is not the buffer. To get a buffer itself, you need to use a function such as `current-buffer'. However, there is a slight complication: if you evaluate `current-buffer' in an expression on its own, as we will do here, what you see is a printed representation of the name of the buffer without the contents of the buffer. Emacs works this way for two reasons: the buffer may be thousands of lines long--too long to be conveniently displayed; and, another buffer may have the same contents but a different name, and it is important to distinguish between them. Here is an expression containing the function: (current-buffer) If you evaluate the expression in the usual way, `#<buffer *info*>' appears 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 `current-buffer'. A related function is `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 `*scratch*' buffer, `other-buffer' will return that buffer. You can see this by evaluating the expression: (other-buffer) You should see `#<buffer *scratch*>' appear in the echo area, or the name of whatever other buffer you switched back from most recently. File: emacs-lisp-intro.info, Node: Switching Buffers, Next: Buffer Size & Locations, Prev: Getting Buffers, Up: Practicing Evaluation Switching Buffers ================= The `other-buffer' function actually provides a buffer when it is used as an argument to a function that requires one. We can see this by using `other-buffer' and `switch-to-buffer' to switch to a different buffer. But first, a brief introduction to the `switch-to-buffer' function. When you switched back and forth from Info to the `*scratch*' buffer to evaluate `(buffer-name)', you most likely typed `C-x b' and then typed `*scratch*' when prompted in the minibuffer for the name of the buffer to which you wanted to switch. The keystrokes, `C-x b', cause the Lisp interpreter to evaluate the interactive Emacs Lisp function `switch-to-buffer'. As we said before, this is how Emacs works: different keystrokes call or run different functions. For example, `C-f' calls `forward-char', `M-e' calls `forward-sentence', and so on. By writing `switch-to-buffer' in an expression, and giving it a buffer to switch to, we can switch buffers just the way `C-x b' does. Here is the Lisp expression: (switch-to-buffer (other-buffer)) The symbol `switch-to-buffer' is the first element of the list, so the Lisp interpreter will treat it as a function and carry out the instructions that are attached to it. But before doing that, the interpreter will note that `other-buffer' is inside parentheses and work on that symbol first. `other-buffer' is the first (and in this case, the only) element of this list, so the Lisp interpreter calls or runs the function. It returns another buffer. Next, the interpreter runs `switch-to-buffer', passing to it, as an argument, the other buffer, which is what Emacs will switch to. If you are reading this in Info, try this now. Evaluate the expression. (To get back, type `C-x b <RET>'.) In the programming examples in later sections of this document, you will see the function `set-buffer' more often than `switch-to-buffer'. This is because of a difference between computer programs and humans: humans have eyes and expect to see the buffer on which they are working on their computer terminals. This is so obvious, it almost goes without saying. However, programs do not have eyes. When a computer program works on a buffer, that buffer does not need to be visible on the screen. `switch-to-buffer' is designed for humans and does two different things: it switches the buffer to which Emacs attention is directed; and it switches the buffer displayed in the window to the new buffer. `set-buffer', on the other hand, does only one thing: it switches the attention of the computer program to a different buffer. The buffer on the screen remains unchanged (of course, normally nothing happens there until the command finishes running). Also, we have just introduced another jargon term, the word "call". When you evaluate a list in which the first symbol is a function, you are calling that function. The use of the term comes from the notion of the function as an entity that can do something for you if you `call' it--just as a plumber is an entity who can fix a leak if you call him or her. File: emacs-lisp-intro.info, Node: Buffer Size & Locations, Next: Evaluation Exercise, Prev: Switching Buffers, Up: Practicing Evaluation Buffer Size and the Location of Point ===================================== Finally, let's look at several rather simple functions, `buffer-size', `point', `point-min', and `point-max'. These give information about the size of a buffer and the location of point within it. The function `buffer-size' tells you the size of the current buffer; that is, the function returns a count of the number of characters in the buffer. (buffer-size) You can evaluate this in the usual way, by positioning the cursor after the expression and typing `C-x C-e'. In Emacs, the current position of the cursor is called "point". The expression `(point)' returns a number that tells you where the cursor is located as a count of the number of characters from the beginning of the buffer up to point. You can see the character count for point in this buffer by evaluating the following expression in the usual way: (point) As I write this, the value of `point' is 65724. The `point' function is frequently used in some of the examples later in this manual. The value of point depends, of course, on its location within the buffer. If you evaluate point in this spot, the number will be larger: (point) For me, the value of point in this location is 66043, which means that there are 319 characters (including spaces) between the two expressions. The function `point-min' is somewhat similar to `point', but it returns the value of the minimum permissible value of point in the current buffer. This is the number 1 unless "narrowing" is in effect. (Narrowing is a mechanism whereby you can restrict yourself, or a program, to operations on just a part of a buffer. *Note Narrowing and Widening: Narrowing & Widening.) Likewise, the function `point-max' returns the value of the maximum permissible value of point in the current buffer. File: emacs-lisp-intro.info, Node: Evaluation Exercise, Prev: Buffer Size & Locations, Up: Practicing Evaluation Exercise ======== Find a file with which you are working and move towards its middle. Find its buffer name, file name, length, and your position in the file. File: emacs-lisp-intro.info, Node: Writing Defuns, Next: Buffer Walk Through, Prev: Practicing Evaluation, Up: Top How To Write Function Definitions ********************************* When the Lisp interpreter evaluates a list, it looks to see whether the first symbol on the list has a function definition attached to it; or, put another way, whether the symbol points to a function definition. If it does, the computer carries out the instructions in the definition. A symbol that has a function definition is called, simply, a function (although, properly speaking, the definition is the function and the symbol refers to it.) * Menu: * Primitive Functions:: Some functions are written in C. * defun:: The `defun' special form. * Install:: Install a Function Definition. * Interactive:: Making a function interactive. * Interactive Options:: Different options for `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:: File: emacs-lisp-intro.info, Node: Primitive Functions, Next: defun, Prev: Writing Defuns, Up: Writing Defuns An Aside about Primitive Functions ================================== All functions are defined in terms of other functions, except for a few "primitive" functions that are written in the C programming language. When you write functions' definitions, you will write them in Emacs Lisp and use other functions as your building blocks. Some of the functions you will use will themselves be written in Emacs Lisp (perhaps by you) and some will be primitives written in C. The primitive functions are used exactly like those written in Emacs Lisp and behave like them. They are written in C so we can easily run GNU Emacs on any computer that has sufficient power and can run C. Let me re-emphasize this: when you write code in Emacs Lisp, you do not distinguish between the use of functions written in C and the use of functions written in Emacs Lisp. The difference is irrelevant. I mention the distinction only because it is interesting to know. Indeed, unless you investigate, you won't know whether an already-written function is written in Emacs Lisp or C.