Programming in Emacs Lisp

Joe Brenner has a nice ELisp <-> Perl comparison table, which is interesting to read:

http://obsidianrook.com/devnotes/elisp-for-perl-programmers.html

Data Types

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:

  • single character symbols like +,
  • multi-character symbols, like forward-paragraph,
  • strings of characters between double quotation marks, or
  • numbers (integer or floating point number).

Logical Functions

equal

Return t (true) if the two Lisp objects have the same value.

eq

Return t if both arguments are actually the same Lisp object.

<, >, <=, >=

The < function tests whether the first argument is smaller than the second argument. A corresponding function, >, tests whether the first argument is greater than the second. Likewise, <= tests whether the first argument is less than or equal to the second and >= tests whether the first argument is greater than or equal to the second. In all cases, both arguments must be numbers.

Evaluation

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.

eval-last-sexp

Evaluate the last sexp (symbolic expression) before the current location of point. The value is printed in the echo area unless the function is invoked with an argument; in that case, the output is printed in the current buffer.

Fundamental List Functions

Note - In dotted pair notation, the list `(1 2 3)' is written as `(1 . (2 . (3 . nil)))'

car

Return the first element of a list.

cdr

Return the second and subsequent elements of a list.

cons

Construct a list by prepending its first argument to its second argument, and return it.

nthcdr

Return the result of taking cdr `n' times on a list. The `rest of the rest' as it were.

setcar

Change the first element of a list.

setcdr

Change the second and subsequent elements of a list.

list

TODO.

append

TODO.

reverse

TODO.

Variables

(let (bindings…) forms…) :: Declare that a list of variables is for use within the body of the let and give them an initial value, either nil or a specified value; then evaluate the rest of the expressions in the body of the let and return the value of the last one. Inside the body of the let, the Lisp interpreter does not see the values of the variables of the same names that are bound outside of the let.

(let* (bindings…) forms…) :: Bind some variables locally to particular values, and then evaluate the remaining arguments, returning the value of the last one. While binding the local variables, use the local values of variables bound earlier, if any.

(setq [symbol form]…) :: Set the value of its first argument to the value of the second argument. The first argument is automatically quoted by setq. It does the same for succeeding pairs of arguments.

Function Template

(defun name argument-list documentation-string interactive-declaration body-forms) :: Define function.

Interactive :: Declare to the interpreter that the function can be used interactively. This special form may be followed by a string with one or more parts that pass the information to the arguments of the function, in sequence. These parts may also tell the interpreter to prompt for information. Parts of the string are separated by newlines, `\n'. Common code characters are:

  • b The name of an existing buffer.
  • f The name of an existing file.
  • p The numeric prefix argument. (Note that this `p' is lower case.)
  • r Point and the mark, as two numeric arguments, smallest first. This is the only code letter that specifies two successive arguments rather than one.

Control Structures

Sequencing

(progn a b c …)

Evaluate each argument in sequence and then return the value of the last.

(prog1 a b c …)

Evaluate each argument in sequence and then return the value of the first.

Conditionals

(if condition then-form else-form)

Evaluate the first argument to the function; if it is true, evaluate the second argument; else evaluate the third argument, if there is one.

Combining Conditions

or

Evaluate each argument in sequence, and return the value of the first argument that is not nil; if none return a value that is not nil, return nil. In brief, return the first true value of the arguments; return a true value if one or any of the other are true.

<example> (or arg1 arg2 arg3) == (if arg1 arg1 (if arg2 arg2 arg3)) </example>

and

Evaluate each argument in sequence, and if any are nil, return nil; if none are nil, return the value of the last argument. In brief, return a true value only if all the arguments are true; return a true value if one and each of the others is true.

<example> (and arg1 arg2 arg3) == (if arg1 (if arg2 arg3)) </example>

Iteration

(while condition forms…)

Repeatedly evaluate the body of the expression so long as the first element of the body tests true. Then return nil. (The expression is evaluated only for its side effects.)

Buffers

buffer-name

Without an argument, return the name of the buffer, as a string.

buffer-file-name

Without an argument, return the name of the file the buffer is visiting.

current-buffer

Return the buffer in which Emacs is active; it may not be the buffer that is visible on the screen.

other-buffer

Return the most recently selected buffer (other than the buffer passed to other buffer as an argument and other than the current buffer).

switch-to-buffer

Select a buffer for Emacs to be active in and display it in the current window so users can look at it.

set-buffer

Switch Emacs's attention to a buffer on which programs will run. Don't alter what the window is showing.

buffer-size

Return the number of characters in the current buffer.

Positions

save-excursion

Record the values of point and mark and the current buffer before evaluating the body of this special form. Restore the values of point and mark and return to the current buffer afterward.

point

Return the value of the current position of the cursor, as an integer counting the number of characters from the beginning of the buffer.

point-min

Return the minimum permissible value of point in the current buffer. This is 1, unless narrowing is in effect.

point-max

Return the value of the maximum permissible value of point in the current buffer. This is the end of the buffer, unless narrowing is in effect.

save-restriction

Record whatever narrowing is in effect in the current buffer, if any, and restore that narrowing after evaluating the arguments.

Emacs Display

message

Print a message in the echo area. The message can be only one line long. The first argument is a string that can contain `%s', `%d', or `%c' to print the value of arguments that follow the string.

  • The argument used by `%s' must be a string or a symbol;
  • the argument used by `%d' must be a number.
  • The argument used by `%c' must be a number; it will be printed as the character with that ascii code.

A Few Buffer-Related Functions

describe-function

Print the documentation for a function.

describe-variable

Print the documentation for a function

find-tag

Find the file containing the source for a function or variable and switch buffers to it, positioning point at the beginning of the item.

push-mark

Set mark at a location and record the value of the previous mark on the mark ring. The mark is a location in the buffer that will keep its relative position even if text is added to or removed from the buffer.

goto-char

Set point to the location specified by the value of the argument, which can be a number, a marker, or an expression that returns the number of a position, such as (point-min).

insert-buffer-substring

Copy a region of text from a buffer that is passed to the function as an argument and insert the region into the current buffer.

mark-whole-buffer

Mark the whole buffer as a region. Normally bound to C-x h.

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 to work on a different buffer.

get-buffer-create

Find a named buffer or create one if a buffer of that name does not exist

get-buffer

Find a named buffer or return nil if the named buffer does not exist.

A Few More Complex Functions

&optional

A keyword used to indicate that an argument to a function definition is optional; this means that the function can be evaluated without the argument, if desired.

prefix-numeric-value

Convert the `raw prefix argument' produced by (interactive "P") to a numeric value.

forward-line

Move point forward to the beginning of the next line, or if the argument is greater than one, forward that many lines. If it can't move as far forward as it is supposed to, forward-line goes forward as far as it can and then returns a count of the number of additional lines it was supposed to move but couldn't.

erase-buffer

Delete the entire contents of the current buffer.

bufferp

Return t if its argument is a buffer; otherwise return nil.

Cutting and Storing Text

search-forward

Search for a string, and if the string is found, move point. Takes four arguments:

  1. The string to search for.
  2. Optionally, the limit of the search.
  3. Optionally, what to do if the search fails, return nil or an error message.
  4. Optionally, how many times to repeat the search; if negative, the search goes backwards.
kill-region

cuts the text between point and mark from the buffer and stores that text in the kill ring, so you can get it back by yanking.

delete-region

removes the text between point and mark from the buffer and throws it away. You cannot get it back.

copy-region-as-kill

copies the text between point and mark into the kill ring, from which you can get it by yanking. The function does not cut or remove the text from the buffer.

insert

inserts its arguments at point

format

returns a string formatted from its arguments the way message formats its arguments; \n produces a new line.

re-search-forward

Search for a pattern, and if the pattern is found, move point to rest just after it. Takes four arguments, like search-forward:

  1. A regular expression that specifies the pattern to search for.
  2. Optionally, the limit of the search.
  3. Optionally, what to do if the search fails, return nil or an error message.
  4. Optionally, how many times to repeat the search; if negative, the search goes backwards.
match-beginning

Return the position of the start of the text found by the last regular expression search.

looking-at

Return t for true if the text after point matches the argument, which should be a regular expression.

eobp

Return t for true if point is at the end of the accessible part of a buffer. The end of the accessible part is the end of the buffer if the buffer is not narrowed; it is the end of the narrowed part if the buffer is narrowed.