1 Programming Jade

This chapter of the manual is a full guide to Jade’s Lisp programming language, including documentation for most of the built-in functions.

1.1 Introduction

As you have probably gathered by now, Jade is largely controlled by its built in programming language: a dialect of Lisp containing many extensions (non-standard data types and functions) to make it suitable for controlling an editor. Through this language Jade can be customised and extended.

I have attempted to make the “standard” portion of the language (i.e. anything a normal Lisp would have; not related to editing) as compatible with GNU Emacs Lisp as possible. In some areas this rule doesn’t apply, there will usually be a good reason for this. A few functions have been inspired by Common Lisp.

The areas of the language which control the editor are not compatible with Emacs; some functions may be similar but since the two editors are fundamentally different I have not attempted to conform with the Emacs API.

All programs written using only the information in this manual should be compatible with future revisions of Jade.

This following sections explain some of the most important Lisp concepts and the conventions I’ve used in this manual.

1.1.1 nil and t

The two boolean values in Lisp are the symbols nil (FALSE) and t (TRUE). Both these symbols always evaluate to themselves (so they do not have to be quoted), any attempt to change their values is an error.

All of the conditional instructions regard anything which is not nil as being TRUE (i.e. not-FALSE). The actual symbol t should be used where a TRUE boolean value must be explicitly stated to increase the clarity of the code.

This is not the end of the story; nil actually has another meaning: it represents the empty list. This is a consequence of how lists are constructed in Lisp, a list of zero elements is stored as the symbol nil.

To the Lisp system itself there is absolutely no difference between () (the notation for a list with zero elements) and nil (the symbol nil). When writing code however, the list notation is usually used when the programmer regards the value as a list and the nil notation when its value as a boolean is to be emphasised.

1.1.2 The Lisp Reader

Lisp programs and functions are stored internally as normal Lisp data objects, the Lisp Reader is the process used to translate textual descriptions of Lisp objects into the data structures used to represent the objects.

The Lisp Reader is the collection of internal functions accessed by the read Lisp function. It reads a character at a time from an input stream until it has parsed a whole Lisp object.

See section Data Types.

1.1.3 Notation

Wherever an example of evaluating a Lisp form is shown it will be formatted like this,

(+ 1 2)
    ⇒ 3

The glyph ‘⇒’ is used to show the computed value of a form.

When two forms are shown as being exactly equivalent to one another the glyph ‘≡’ is used, for example,

(car some-variable) ≡ (nth 0 some-variable)

Evaluating some forms result in an error being signalled, this is denoted by the ‘error-->’ glyph.

(read-file "/tmp/foo")
    error--> File error: No such file or directory, /tmp/foo

1.1.4 Descriptions

The simplest type of descriptions are the descriptions of variables (see section Variables), they look something like,

Variable: grains-of-sand

This imaginary variable contains the number of grains of sand in a one-mile long stretch of an averagely sandy beach.

Hooks (see section Hooks) are also described in this format, the only difference is that ‘Variable:’ is replaced by ‘Hook:’.

Functions (see section Functions) and macros (see section Macros) have more complex descriptions; as well as the name of the thing being described, they also have a list of arguments which the thing will accept. Each argument in the list is named and may be referred to in the body of the description.

Two ‘special’ arguments may be used, ‘&optional’ and &rest. They have the same meaning as when used in the lambda-list of a function definition (see section Lambda Expressions), that is ‘&optional’ means that all further arguments are optional, and ‘&rest’ means that zero or more argument values are coalesced into a list to be used as the value of the following argument.

An example function definition follows.

Function: useless-function first &optional second &rest tail

This function returns a list consisting of the values second (when undefined the number 42 is used), all the items in the list tail and first.

(useless-function 'foo 'bar 'xyz 20)
    ⇒ (bar xyz 20 foo)

(useless-function '50)
    ⇒ (42 50)

Macros and commands (see section Commands) are defined in the same way with ‘Macro:’ or ‘Command:’ replacing ‘Function:’.

Special forms (see section Special Forms) are described similarly to functions except that the argument list is formatted differently since special forms are, by definition, more flexible in how they treat their arguments. Optional values are enclosed in square brackets (‘[optional-arg]’) and three dots (‘repeated-arg…’) indicate where zero or more arguments are allowed.

1.2 Data Types

The way that data values are represented in Lisp is fundamentally different to more “conventional” languages such as C or Pascal: in Lisp each piece of data (a Lisp Object) has two basic attributes, the actual data and a tag value defining the type of the object. This means that type checking is performed on the actual data itself, not on the “variable” holding the data.

All Lisp objects are a member of one of the primitive types; these are types built into the Lisp system and can represent things like strings, integers, cons cells, vectors, etc…

More complex types of object can be constructed from these primitive types, for example a vector of three elements could be regarded as a type triple if necessary. In general, each separate type provides a predicate function which returns t when applied to an object of its type.

1.2.1 Types Summary

Each separate data type is documented in its own section, this is a just a table of the more common types.

Integer

32-bit signed integers. See section Numbers.

Cons cell

An object containing two other Lisp objects. See section Cons Cells.

List

A sequence of objects, in Lisp lists are not primitive types, instead they are made by chaining together Cons cells. See section Lists.

Vector

A one-dimensional array of objects. See section Vectors.

String

A vector of characters. See section Strings.

Array

An ordered sequence of objects which can be accessed in constant time, either a vector or a string. See section Sequences.

Sequence

An ordered sequence of objects, either a list or an array. See section Sequences.

Symbol

A symbol is a named object; they are used to provide named variables and functions. See section Symbols.

File

A link to a file in the operating system’s filing system, allows access to the file as a stream. See section Files.

Stream

Serial data sinks and sources. See section Streams.

Void

No type, only used in symbols to represent an unset function or variable value.

Buffer

A “space” in which text can be edited, buffers may be displayed in a window and hence edited by the user. See section Buffers.

Window

A physical window in the underlying window-system, used for input and output.

Position

A pair of integers, used to represent the coordinates of a character in a buffer. See section Positions.

Mark

A position in a specified file, this file may either be a buffer in memory or a named file. See section Marks.

Process

An object through which processes may be created and controlled. See section Processes.

Glyph Table

A lookup-table which is used to map characters in a buffer to the sequence of glyphs they are rendered as. See section Glyph Tables.

Keymap

A set of key-sequence-to-command mappings; when installed in a buffer it controls how the editor reacts to all input from the user. See section Keymaps.

Event

An (input-) event from a window.

1.2.2 Read Syntax

As previously noted the Lisp reader translates textual descriptions of Lisp objects into the object they describe (source files are simply descriptions of objects). However, not all data types can be created in this way: in fact the only types which can are integers, strings, symbols, cons cells (or lists) and vectors, all others have to be created by calling functions.

Note that comments in a Lisp program are introduced by the semi-colon character (‘;’). Whenever the Lisp reader encounters a semi-colon where it’s looking for the read syntax of a new Lisp object it will discard the rest of the line of input. See section Comment Styles.

The read syntax of an object is the string which when given to the reader as input will produce the object. The read syntax of each type of object is documented in that type’s main section of this manual but here is a small taste of how to write each type.

Integers

An integer is simply the number written in either decimal, octal (when the number is preceded by ‘0’) or hexadecimal (when the number is preceded by ‘0x’). An optional minus sign may be the first character in a number. Some examples are,

42
    ⇒ 42

0177
    ⇒ 127

0xff
    ⇒ 255

-0x10
    ⇒ -16

Strings

The read syntax of a string is simply the string with a double-quote character (‘"’) at each end, for more details see Strings.

"This is a string"

Cons cells

A cons cell is written in what is known as dotted pair notation and is just the two objects in the cell separated by a dot and the whole thing in parentheses,

(car . cdr)

Lists

The syntax of a list is similar to a cons cell (since this is what lists are made of): no dot is used and there may be zero or more objects,

(object1 object2 object3 …)

("foo" ("bar" "baz") 100)

The second example is a list of three elements, a string, another list and a number.

Vectors

The read syntax of a vector is very similar to that of a list, simply use square brackets instead of parentheses,

[object1 object2 object3 …]

Symbols

A symbol’s read syntax is simply its name, for example the read syntax of a symbol called ‘my-symbol’ is,

my-symbol

1.2.3 Printed Representation

The printed representation of an object is the string produced when the object is printed (with one of the print functions), this will usually be very similar to the read syntax of the object (see section Read Syntax).

Objects which do not have a read syntax do have a printed representation, it will normally be of the form,

#<relevant text>

where the “relevant text” is object-dependent and usually describes the object and its contents. The reader will signal an error if it encounters a description of an object in the format ‘#<…>’.

1.2.4 Equality Predicates

Function: eq arg1 arg2

Returns t when arg1 and arg2 are the same object. Two objects are the same object when they occupy the same place in memory and hence modifying one object would alter the other. The following Lisp fragments may illustrate this,

(eq "foo" "foo")	;the objects are distinct
    ⇒ nil

(eq t t)		;the same object -- the symbol t
    ⇒ t

Note that the result of eq is undefined when called on two integer objects with the same value, see eql.

Function: equal arg1 arg2

The function equal compares the structure of the two objects arg1 and arg2. If they are considered to be equivalent then t is returned, otherwise nil is returned.

(equal "foo" "foo")
    ⇒ t

(equal 42 42)
    ⇒ t

(equal 42 0)
    ⇒ nil

(equal '(x . y) '(x . y))
    ⇒ t

Function: eql arg1 arg2

This function is a cross between eq and equal: if arg1 and arg2 are both numbers then the value of these numbers are compared. Otherwise it behaves in exactly the same manner as eq does.

(eql 3 3)
    ⇒ t

(eql 1 2)
    ⇒ nil

(eql "foo" "foo")
    ⇒ nil

(eql 'x 'x)
    ⇒ t

1.2.5 Comparison Predicates

These functions compare their two arguments in a scalar fashion, the arguments may be of any type but the results are only meaningful for numbers, strings (ASCII values of each byte compared until a non-matching pair is found then those two values are compared as numbers) and positions.

Function: > arg1 arg2

Returns t when arg1 is ‘greater than’ arg2.

Function: >= arg1 arg2

Returns t when arg1 is ‘greater than or equal to’ arg2.

Function: < arg1 arg2

Returns t when arg1 is ‘less than’ arg2.

Function: <= arg1 arg2

Returns t when arg1 is ‘less than or equal to’ arg2.

1.2.6 Type Predicates

Each type has a corresponding predicate which defines the objects which are members of that type.

• integerp
• numberp
• null
• consp
• listp
• vectorp
• subrp
• functionp
• sequencep
• stringp
• symbolp
• posp
• bufferp
• windowp
• markp
• processp
• filep
• keymapp
• eventp
• commandp

The documentation for these functions is with the documentation for the relevant type.

1.2.7 Garbage Collection

In Lisp, data objects are used very freely; a side effect of this is that it is not possible to (easily) know when an object is stale, that is, no references to it exist and it can therefore be reused.

The garbage collector is used to overcome this problem; whenever enough new data objects have been allocated to make it worthwhile, everything stops and the garbage collector works its way through memory deciding which objects are still in use and which are stale. The stale objects are then recorded as being available for reuse and evaluation continues again.

Function: garbage-collect

Runs the garbage collector, usually this function doesn’t need to be called manually.

Variable: garbage-threshold

The number of bytes of data which must be allocated before evaluation will pause and the garbage collector called.

Its default value is about 100K.

See section Idle Actions.

1.3 Numbers

Currently Jade is only capable of representing integers, for this it uses signed 32-bit integers: this gives a range of -2147483648 through 0 to 2147483647.

The read syntax of an integer is simply the number written in decimal, octal or hexadecimal. If the integer starts with the string ‘0x’ it is assumed to be hexadecimal or if it starts with a zero it is treated as octal. The first character may be an optional minus or plus sign (this should come before any base-specifier). Examples of valid integer read syntaxes for the number 42 could be ‘42’, ‘0x2a’, ‘052’, ‘+052’, …

An integer’s printed representation is simply the number printed in decimal with a preceding minus sign if it is negative.

Function: numberp object

This function returns t if object is a number.

Function: integerp object

This function returns t when object is an integer.

1.4 Arithmetic Functions

There are a number of functions which perform arithmetic operations on numbers, they take a varying number of integer objects as their arguments then return a new integer object as their result.

Note that none of these functions check for overflow.

Function: + number1 &rest numbers

This functions adds its arguments then returns their sum.

Function: - number1 &rest numbers

If this function is just given one argument (number1) that number is negated and returned. Otherwise each of numbers is subtracted from a running total starting with the value of number1.

(- 20)
    ⇒ -20

(- 20 10 5)
    ⇒ 5

Function: * number1 &rest numbers

This function multiplies its arguments then returns the result.

Function: / number1 &rest numbers

This function performs division, a running-total (initialised from number1 is successively divided by each of numbers then the result is returned.

(/ 100 2)
    ⇒ 50

(/ 200 2 5)
    ⇒ 20

Function: % dividend divisor

Returns the remainder from dividing dividend by divisor.

(mod 5 3)
    ⇒ 2

Function: 1+ number

This function returns the result of adding one to number.

(1+ 42)
    ⇒ 43

Function: 1- number

Returns number minus one.

1.5 Bitwise Functions

These functions operate on the bit string which an integer is made of.

Function: lsh number count

This function bit-shifts the integer number count bits to the left, if count is negative number is shifted to the right instead.

(lsh 1 8)
    ⇒ 256

(lsh 256 -8)
    ⇒ 1

Function: ash number count

Similar to lsh except that an arithmetical shift is done, this means that the sign of number is always preserved.

(ash 1 8)
    ⇒ 256

(ash -1 2)
    ⇒ -4

Function: logand number1 &rest numbers

This function uses a bit-wise logical ‘and’ operation to combine all its arguments (there must be at least one argument).

(logand 15 8)
    ⇒ 8

(logand 15 7 20)
    ⇒ 4

Function: logior number1 &rest numbers

Uses a bit-wise logical ‘inclusive-or’ to combine all its arguments (there must always be at least one argument).

(logior 1 2 4)
    ⇒ 7

Function: logxor number1 &rest numbers

Uses a bitwise logical ‘exclusive-or’ to combine all its arguments (there must be at least one).

(logxor 7 3)
    ⇒ 4

Function: lognot number

This function inverts all the bits in number.

(lognot 0)
    ⇒ -1

(lognot 2)
    ⇒ -3

(lognot -1)
    ⇒ 0

1.6 Numeric Predicates

For the documentation of the functions >, <, >= and <= see Comparison Predicates.

Function: = number1 number2

This function returns t if the two integers number1 and number2 have the same value.

(= 1 1)
    ⇒ t

(= 1 0)
    ⇒ nil

Function: /= number1 number2

This function will return t if number1 and number2 and not equal to each other.

(/= 1 1)
    ⇒ nil

(/= 1 0)
    ⇒ t

Function: zerop number

Returns t if number is equal to zero.

1.6.1 Characters

In Jade characters are stored in integers. Their read syntax is a question mark followed by the character itself which may be an escape sequence introduced by a backslash. For details of the available escape sequences see Strings.

?a
    ⇒ 97

?\n
    ⇒ 10

?\177
    ⇒ 127

Function: alpha-char-p character

This function returns t when character is one of the alphabetic characters.

(alpha-char-p ?a)
    ⇒ t

Function: upper-case-p character

When character is one of the upper-case characters this function returns t.

Function: lower-case-p character

Returns t when character is lower-case.

Function: digit-char-p character

This function returns t when character is one of the decimal digit characters.

Function: alphanumericp character

This function returns t when character is either an alphabetic character or a decimal digit character.

Function: space-char-p character

Returns t when character is a white-space character (space, tab, newline or form feed).

Function: char-upcase character

This function returns the upper-case equivalent of character. If character is already upper-case or has no upper-case equivalent it is returned unchanged.

(char-upcase ?a)
    ⇒ 65                       ;`A'

(char-upcase ?A)
    ⇒ 65                       ;`A'

(char-upcase ?!)
    ⇒ 33                       ;`!'

Function: char-downcase character

Returns the lower-case equivalent of the character character.

1.7 Sequences

Sequences are ordered groups of objects, there are several primitive types which can be considered sequences, each with its own good and bad points.

A sequence is either an array or a list, where an array is either a vector or a string.

Function: sequencep object

This function returns t if object is a sequence, nil otherwise.

1.7.1 Cons Cells

A cons cell is an ordered pair of two objects, the car and the cdr.

The read syntax of a cons cell is an opening parenthesis followed by the read syntax of the car, a dot, the read syntax of the cdr and a closing parenthesis. For example a cons cell with a car of 10 and a cdr of the string ‘foo’ would be written as,

(10 . "foo")

Function: cons car cdr

This function creates a new cons cell. It will have a car of car and a cdr of cdr.

(cons 10 "foo")
    ⇒ (10 . "foo")

Function: consp object

This function returns t if object is a cons cell and nil otherwise.

(consp '(1 . 2))
    ⇒ t

(consp nil)
    ⇒ nil

(consp (cons 1 2))
    ⇒ t

In Lisp an atom is any object which is not a cons cell (and is, therefore, atomic).

Function: atom object

Returns t if object is an atom (not a cons cell).

Given a cons cell there are a number of operations which can be performed on it.

Function: car cons-cell

This function returns the object which the car of the cons cell cons-cell.

(car (cons 1 2))
    ⇒ 1

(car '(1 . 2))
    ⇒ 1

Function: cdr cons-cell

This function returns the cdr of the cons cell cons-cell.

(cdr (cons 1 2))
    ⇒ 2

(cdr '(1 . 2))
    ⇒ 2

Function: rplaca cons-cell new-car

This function sets the value of the car in the cons cell cons-cell to new-car. The value returned is new-car.

(setq x (cons 1 2))
    ⇒ (1 . 2)
(rplaca x 3)
    ⇒ 3
x
    ⇒ (3 . 2)

Function: rplacd cons-cell new-cdr

This function is similar to rplacd except that the cdr slot of cons-cell is modified.

1.7.2 Lists

A list is a sequence of zero or more objects, the main difference between lists and vectors is that lists are more dynamic: they can change size, be split, reversed, concatenated, etc… very easily.

In Lisp lists are not a primitive type; instead singly-linked lists are created by chaining cons cells together (see section Cons Cells).

Function: listp object

This functions returns t when its argument, object, is a list (i.e. either a cons cell or nil).

1.7.2.1 List Structure

Each element in a list is given its own cons cell and stored in the car of that cell. The list object is then constructed by making the cdr of a cell contain the cons cell of the next element (and hence the whole tail of the list). The cdr of the cell containing the last element in the list is nil. A list of zero elements is represented by the symbol nil.

The read syntax of a list is an opening parenthesis, followed by the read syntax of zero or more space-separated objects, followed by a closing parenthesis. Alternatively, lists can be constructed ‘manually’ using dotted-pair notation.

All of the following examples result in the same list of five elements: the numbers from zero to four.

(0 1 2 3 4)

(0 . (1 . (2 . (3 . (4 . nil)))))

(0 1 2 . (3 4))

An easy way to visualise lists and how they are constructed is to see each cons cell in the list as a separate box with pointers to its car and cdr,

+-----+-----+
|  o  |  o----> cdr
+--|--+-----+
   |
    --> car

Complex box-diagrams can now be drawn to represent lists. For example the following diagram represents the list (1 2 3 4).

+-----+-----+   +-----+-----+   +-----+-----+   +-----+-----+
|  o  |  o----> |  o  |  o----> |  o  |  o----> |  o  |  o----> nil
+--|--+-----+   +--|--+-----+   +--|--+-----+   +--|--+-----+
   |               |               |               |
    --> 1           --> 2           --> 3           --> 4

A more complex example, the list ((1 2) (foo bar)) can be drawn as,

+-----+-----+                          +-----+-----+
|  o  |  o---------------------------> |  o  |  o----> nil
+--|--+-----+                          +--|--+-----+
   |                                      |
+-----+-----+   +-----+-----+          +-----+-----+   +-----+-----+
|  o  |  o----> |  o  |  o----> nil    |  o  |  o----> |  o  |  o----> nil
+--|--+-----+   +--|--+-----+          +--|--+-----+   +--|--+-----+
   |               |                      |               |
    --> 1           --> 2                  --> foo         --> bar

Sometimes when manipulating complex list structures it is very helpful to make a diagram of what it is that’s being manipulated.

1.7.2.2 Building Lists

It has already been shown how you can create lists using the Lisp reader; this method does have a drawback though: the list created is effectively static. If you modify the contents of the list and that list was created when a function was defined the list will remain modified for all future invocations of that function. This is not usually a good idea, consider the following function definition,

(defun bogus-function (x)
  "Return a list whose first element is nil and whose second element is X."
  (let
      ((result '(nil nil)))     ;Static list which is filled in each time
    (rplaca (cdr result) x)     ; the function is called
    result))

This function does in fact do what its documentation claims, but a problem arises when it is called more than once,

(setq x (bogus-function 'foo))
    ⇒ (nil foo)
(setq y (bogus-function 'bar))
    ⇒ (nil bar)               ;The first result has been destroyed
x
    ⇒ (nil bar)               ;See!

This example is totally contrived — no one would ever write a function like the one in the example but it nicely demonstrates the need for a dynamic method of creating lists.

Function: list &rest elements

This function creates a list out of its arguments, if zero arguments are given the empty list, nil, is returned.

(list 1 2 3)
    ⇒ (1 2 3)

(list (major-version-number) (minor-version-number))
    ⇒ (3 2)

(list)
    ⇒ nil               ;Equivalent to `()'

Function: make-list length &optional initial-value

This function creates a list length elements long. If the initial-value argument is given it defines the value of all elements in the list, if it is not given they are all nil.

(make-list 2)
    ⇒ (nil nil)

(make-list 3 t)
    ⇒ (t t t)

(make-list 0)
    ⇒ nil

Function: append &rest lists

This function creates a new list with the elements of each of its arguments (which must be lists). Unlike the function nconc this function preserves all of its arguments.

(append '(1 2 3) '(4 5))
    ⇒ (1 2 3 4 5)

(append)
    ⇒ nil

What actually happens is that all arguments but the last are copied then the last argument is linked on to the end of the list (uncopied).

(setq foo '(1 2))
    ⇒ (1 2)
(setq bar '(3 4))
    ⇒ (3 4)
(setq baz (append foo bar))
    ⇒ (1 2 3 4)
(eq (nthcdr 2 baz) bar)
    ⇒ t

The following diagram shows the final state of the three variables more clearly,

foo--> +-----+-----+   +-----+-----+
       |  o  |  o----> |  o  |     |
       +--|--+-----+   +--|--+-----+
          |               |
          o--> 1          o--> 2   bar
          |               |          ->
baz--> +--|--+-----+   +--|--+-----+   +-----+-----+   +-----+-----+
       |  o  |  o----> |  o  |  o----> |  o  |  o----> |  o  |     |
       +-----+-----+   +-----+-----+   +--|--+-----+   +--|--+-----+
                                          |               |
                                           --> 3           --> 4

Note how foo and the first half of baz use the same objects for their elements — copying a list only copies its cons cells, its elements are reused. Also note how the variable bar actually references the mid-point of baz since the last list in an append call is not copied.

Function: reverse list

This function returns a new list; it is made from the elements of the list list in reverse order. Note that this function does not alter its argument.

(reverse '(1 2 3 4))
    ⇒ (4 3 2 1)

As a postscript to this section, the function used as an example at the beginning could now be written as,

(defun not-so-bogus-function (x)
  (list nil x))

Also note that the cons function can be used to create lists by hand and to add new elements onto the front of a list.

1.7.2.3 Accessing List Elements

The most powerful method of accessing an element in a list is via a combination of the car and cdr functions. There are other functions which provide an easier way to get at the elements in a flat list. These will usually be faster than a string of car and cdr operations.

Function: nth count list

This function returns the element count elements down the list, therefore to access the first element use a count of zero (or even better the car function). If there are too few elements in the list and no element number count can be found nil is returned.

(nth 3 '(0 1 2 3 4 5))
    ⇒ 3

(nth 0 '(foo bar)
    ⇒ foo

Function: nthcdr count list

This function takes the cdr of the list list count times, returning the last cdr taken.

(nthcdr 3 '(0 1 2 3 4 5))
    ⇒ (3 4 5)

(nthcdr 0 '(foo bar))
    ⇒ (foo bar)

Function: last list

This function returns the last element in the list list. If the list has zero elements nil is returned.

(last '(1 2 3))
    ⇒ 3

(last '())
    ⇒ nil

Function: member object list

This function scans through the list list until it finds an element which is equal to object. The tail of the list (the cons cell whose car is the matched object) is then returned. If no elements match object then the empty list nil is returned.

(member 'c '(a b c d e))
    ⇒ (c d e)

(member 20 '(1 2))
    ⇒ nil

Function: memq object list

This function is similar to member except that comparisons are performed by the eq function not equal.

1.7.2.4 Modifying Lists

The nthcdr function can be used in conjunction with the rplaca function to modify an arbitrary element in a list. For example,

(rplaca (nthcdr 2 '(0 1 2 3 4 5)) 'foo)
    ⇒ foo

sets the third element of the list (0 1 2 3 4 5) to the symbol called foo.

There are also functions which modify the structure of a whole list. These are called destructive operations because they modify the actual structure of a list — no copy is made. This can lead to unpleasant side effects if care is not taken.

Function: nconc &rest lists

This function is the destructive equivalent of the function append, it modifies its arguments so that it can return a list which is the concatenation of the elements in its arguments lists.

Like all the destructive functions this means that the lists given as arguments are modified (specifically, the cdr of their last cons cell is made to point to the next list). This can be seen with the following example (similar to the example in the append documentation).

(setq foo '(1 2))
    ⇒ (1 2)
(setq bar '(3 4))
    ⇒ (3 4)
(setq baz (nconc foo bar))
    ⇒ (1 2 3 4)
foo
    ⇒ (1 2 3 4)                ;`foo' has been altered!
(eq (nthcdr 2 baz) bar)
    ⇒ t

The following diagram shows the final state of the three variables more clearly,

foo-->                           bar-->
baz--> +-----+-----+   +-----+-----+   +-----+-----+   +-----+-----+
       |  o  |  o----> |  o  |  o----> |  o  |  o----> |  o  |     |
       +--|--+-----+   +--|--+-----+   +--|--+-----+   +--|--+-----+
          |               |               |               |
           --> 1           --> 2             --> 3           --> 4

Function: nreverse list

This function rearranges the cons cells constituting the list list so that the elements are in the reverse order to what they were.

(setq foo '(1 2 3))
    ⇒ (1 2 3)
(nreverse foo)
    ⇒ (3 2 1)
foo
    ⇒ (1)                      ;`foo' wasn't updated when the list
                                ; was altered.

Function: delete object list

This function destructively removes all elements of the list list which are equal to object then returns the modified list.

(delete t '(nil t nil t nil))
    ⇒ (nil nil nil)

When this function is used to remove an element from a list which is stored in a variable that variable must be set to the return value of the delete function. Otherwise, if the first element of the list has to be deleted (because it is equal to object) the value of the variable will not change.

(setq foo '(1 2 3))
    ⇒ (1 2 3)
(delete 1 foo)
    ⇒ (2 3)
foo
    ⇒ (1 2 3)
(setq foo (delete 1 foo))
    ⇒ (2 3)

Function: delq object list

This function is similar to the delete function, the only difference is that the eq function is used to compare object with each of the elements in list, instead of the equal function which is used by delete.

1.7.2.5 Association Lists

An association list (or alist) is a list mapping key values to to other values. Each element of the alist is a cons cell, the car of which is the key, the cdr is the value that it associates to. For example an alist could look like,

((fred . 20)
 (bill . 30))

this alist has two keys, fred and bill which both associate to an integer (20 and 30 respectively).

It is possible to make the associated values lists, this looks like,

((fred 20 male)
 (bill 30 male)
 (sue  25 female))

in this alist the symbol fred is associated with the list (20 male).

There are a number of functions which let you interrogate an alist with a given key for its association.

Function: assoc key alist

This function scans the association list alist for the first element whose car is equal to key, this element is then returned. If no match of key is found nil is returned.

(assoc 'two '((one . 1) (two . 2) (three . 3)))
    ⇒ (two . 2)

Function: assq key alist

Similar to the function assoc except that the function eq is used to compare elements instead of equal.

It is not usually wise to use assq when the keys of the alist may not be symbols — eq won’t think two objects are equivalent unless they are the same object!

(assq "foo" '(("bar" . 1) ("foo" . 2)))
    ⇒ nil
(assoc "foo" '(("bar" . 1) ("foo" . 2)))
    ⇒ ("foo" . 2)

Function: rassoc association alist

This function searches through alist until it finds an element whose cdr is equal to association, that element is then returned. nil will be returned if no elements match.

(rassoc 2 '((one . 1) (two . 2) (three . 3)))
    ⇒ (two . 2)

Function: rassq association alist

This function is equivalent to rassoc except that it uses eq to make comparisons.

1.7.2.6 Infinite Lists

Sometimes it is useful to be able to create ‘infinite’ lists — that is, lists which appear to have no last element — this can easily be done in Lisp by linking the cdr of the last cons cell in the list structure back to the beginning of the list.

 ----------------------------------- 
|                                   |
 --> +-----+-----+   +-----+-----+  |
     |  o  |  o----> |  o  |  o----- 
     +--|--+-----+   +--|--+-----+
        |               |
         --> 1           --> 2

The diagram above represents the infinite list (1 2 1 2 1 2 …).

Infinite lists have a major drawback though, many of the standard list manipulation functions can not be used on them. These functions work by moving through the list until they reach the end. If the list has no end the function may never terminate and the only option is to send Jade an interrupt signal (@pxref{Interrupting Jade}).

The only functions which may be used on circular lists are: the cons cell primitives (cons, car, cdr, rplaca, rplacd), nth and nthcdr.

Also note that infinite lists can’t be printed.

1.7.3 Vectors

A vector is a fixed-size sequence of Lisp objects, each element may be accessed in constant time — unlike lists where the time taken to access an element is proportional to the position of the element.

The read syntax of a vector is an opening square bracket, followed by zero or more space-separated objects, followed by a closing square bracket. For example,

[zero one two three]

In general it is best to use vectors when the number of elements to be stored is known and lists when the sequence must be more dynamic.

Function: vectorp object

This function returns t if its argument, object, is a vector.

Function: vector &rest elements

This function creates a new vector containing the arguments given to the function.

(vector 1 2 3)
    ⇒ [1 2 3]

(vector)
    ⇒ []

Function: make-vector size &optional initial-value

Returns a new vector, size elements big. If initial-value is defined each element of the new vector is set to initial-value, otherwise they are all nil.

(make-vector 4)
    ⇒ [nil nil nil nil]

(make-vector 2 t)
    ⇒ [t t]

1.7.4 Strings

A string is a vector of characters (see section Characters), they are generally used for storing and manipulating pieces of text. Jade puts no restrictions on the values which may be stored in a string — specifically, the null character (‘^@’) may be stored with no problems.

The read syntax of a string is a double quote character, followed by the contents of the string, the object is terminated by a second double quote character. For example, "abc" is the read syntax of the string ‘abc’.

Any backslash characters in the string’s read syntax introduce an escape sequence; one or more of the following characters are treated specially to produce the next actual character in the string.

The following escape sequences are supported (all are shown without their leading backslash ‘\’ character).

‘n’

A newline character.

‘r’

A carriage return character.

‘f’

A form feed character.

‘t’

A TAB character.

‘a’

A ‘bell’ character (this is Ctrl-g).

‘^c’

The ‘control’ code of the character c. This is calculated by toggling the seventh bit of the upper-case version of c.

For example,

\^C             ;A Ctrl-c character (ASCII value 3)
\^@            ;The NUL character (ASCII value 0)

‘012’

The character whose ASCII value is the octal value ‘012’. After the backslash character the Lisp reader reads up to three octal digits and combines them into one character.

‘x12’

The character whose ASCII value is the hexadecimal value ‘12’, i.e. an ‘x’ character followed by one or two hex digits.

Function: stringp object

This function returns t if its argument is a string.

Function: make-string length &optional initial-character

Creates a new string containing length characters, each character is initialised to initial-character (or to spaces if initial-character is not defined).

(make-string 3)
    ⇒ "   "

(make-string 2 ?$)
    ⇒ "$$"

Function: concat &rest args

This function concatenates all of its arguments, args, into a single string which is returned. If no arguments are given then the null string (‘’) results.

Each of the args may be a string, a character or a list or vector of characters. Characters are stored in strings modulo 256.

(concat "foo" "bar")
    ⇒ "foobar"

(concat "a" ?b)
    ⇒ "ab"

(concat "foo" [?b ?a ?r])
    ⇒ "foobar"

(concat)
    ⇒ ""

Function: substring string start &optional end

This function creates a new string which is a partial copy of the string string. The first character copied is start characters from the beginning of the string. If the end argument is defined it is the index of the character to stop copying at, if it is not defined all characters until the end of the string are copied.

(substring "xxyfoozwx" 3 6)
    ⇒ "foo"

(substring "xyzfoobar" 3)
    ⇒ "foobar"

Function: string= string1 string2

This function compares the two strings string1 and string2 — if they are made from the same characters in the same order then t is returned, else nil.

(string= "one" "one")
    ⇒ t

(string= "one" "two")
    ⇒ nil

Note that an alternate way to compare strings (or anything!) is to use the equal function.

Function: string< string1 string2

This function returns t if string1 is ‘less’ than string2. This is determined by comparing the two strings a character at a time, the first pair of characters which do not match each other are then compared with a normal ‘less-than’ function.

In Jade the standard < function understands strings so string< is just a macro calling that function.

(string< "abc" "abd")
    ⇒ t

(string< "abc" "abb")
    ⇒ nil

Functions are also available which match regular expressions with strings (see section Searching and Matching Functions) and which apply a mapping to each character in a string (see section Translation Functions).

1.7.5 Array Functions

Function: arrayp object

This function returns t if object is an array.

Function: aref array position

Returns the element of the array (vector or string) array position elements from the first element (i.e. the first element is numbered zero). If no element exists at position in array, nil is returned.

(aref [0 1 2 3] 2)
    ⇒ 2

(aref "abcdef" 3)
    ⇒ 100                      ;`d'

Function: aset array position value

This function sets the element of the array array with an index of position (counting from zero) to value. An error is signalled if element position does not exist. The result of the function is value.

(setq x [0 1 2 3])
    ⇒ [0 1 2 3]
(aset x 2 'foo)
    ⇒ foo
x
    ⇒ [0 1 foo 3]

1.7.6 Sequence Functions

Function: length sequence

This function returns the length (an integer) of the sequence sequence.

(length "abc")
    ⇒ 3

(length '(1 2 3 4))
    ⇒ 4

(length [x y])
    ⇒ 2

Function: copy-sequence sequence

Returns a new copy of the sequence sequence. Where possible (in lists and vectors) only the ‘structure’ of the sequence is newly allocated: the same objects are used for the elements in both sequences.

(copy-sequence "xy")
    ⇒ "xy"

(setq x '("one" "two"))
    ⇒ ("one" "two")
(setq y (copy-sequence x))
    ⇒ ("one" "two")
(eq x y)
    ⇒ nil
(eq (car x) (car y))
    ⇒ t

Function: elt sequence position

This function returns the element of sequence position elements from the beginning of the sequence.

This function is a combination of the nth and aref functions.

(elt [0 1 2 3] 1)
    ⇒ 1

(elt '(foo bar) 0)
    ⇒ foo

1.8 Symbols

Symbols are objects with a name (usually a unique name), they are one of the most important data structures in Lisp since they are used to provided named variables (see section Variables) and functions (see section Functions).

Function: symbolp object

This function returns t when its argument is a symbol.

1.8.1 Symbol Syntax

The read syntax of a symbol is simply its name; if the name contains any meta-characters (whitespace or any from ‘()[]'";|’) they will have to be entered specially. There are two ways to tell the reader that a meta-character is actually part of the symbol’s name:

1. Precede the meta-character by a backslash character (‘\’), for example:

   xy\(z\)                 ;the symbol whose name is ‘xy(z)’
   

2. Enclose part of the name in vertical lines (two ‘|’ characters). All characters after the starting vertical line are copied as-is until the closing vertical line is encountered. For example:

   xy|(z)|                 ;the symbol ‘xy(z)’
   

Here are some example read syntaxes.

setq                    ; ‘setq’
|setq|                  ; ‘setq’
\s\e\t\q                ; ‘setq’
1                       ; the number 1
\1                      ; the symbol ‘1’
|!$%zf78&|              ; ‘!$%zf78&’
foo|(bar)|              ; ‘foo(bar)’
foo\(bar\)              ; ‘foo(bar)’

1.8.2 Symbol Attributes

All symbols have four basic attributes, most important is the print name of the symbol. This is a string containing the name of the symbol, after it has been defined (when the symbol is first created) it may not be changed.

Function: symbol-name symbol

This function returns the print name of the symbol symbol.

(symbol-name 'unwind-protect)
    ⇒ "unwind-protect"

Each symbol also has a value cell storing the value of this symbol when it is referenced as a variable. Usually this cell is accessed implicitly by evaluating a variable form but it can also be read via the symbol-value function(1) (see section Variables).

Similar to the value cell each symbol also has a function cell which contains the function definition of the symbol (see section Named Functions). The symbol-function function can be used to read this cell and the fset function to set it.

Lastly, there is the symbol’s property list, this is similar to an alist (see section Association Lists) and provides a method of storing arbitrary extra values in each symbol. See section Property Lists.

1.8.3 Obarrays

An obarray is the structure used to ensure that no two symbols have the same name and to provide quick access to a symbol given its name. An obarray is basically a vector (with a slight wrinkle), each element of the vector is a chain of symbols which share the same hash-value (a bucket). These symbols are chained together through links which are invisible to Lisp programs: if you examine an obarray you will see that each bucket looks as though it has at most one symbol stored in it.

The normal way to reference a symbol is simply to type its name in the program, when the Lisp reader encounters a name of a symbol it looks in the default obarray for a symbol of that name. If the named symbol doesn’t exist it is created and hashed into the obarray — this process is known as interning the symbol, for more details see Interning.

Variable: obarray

This variable contains the obarray that the read function uses when interning symbols. If you change this I hope you know what you’re doing.

Function: make-obarray size

This function creates a new obarray with size hash buckets (this should be a prime number for best results).

This is the only correct way of making an obarray.

Function: find-symbol symbol-name &optional obarray

This function scans the specified obarray (obarray or the value of the variable obarray if obarray is undefined) for a symbol whose name is the string symbol-name. The value returned is the symbol if it can be found or nil otherwise.

(find-symbol "setq")
    ⇒ setq

Function: apropos regexp &optional predicate obarray

Returns a list of symbols from the obarray obarray (or the default) whose print name matches the regular expression regexp. If predicate is defined and not nil, each symbol which matches regexp is applied to the function predicate, if the value is t it is considered a match.

The predicate argument is useful for restricting matches to a certain type of symbol, for example only commands.

(apropos "^yank" 'commandp)
    ⇒ (yank-rectangle yank yank-to-mouse)

1.8.4 Creating Symbols

It is possible to allocate symbols dynamically, this is normally only necessary when the symbol is to be interned in the non-default obarray or the symbol is a temporary object which should not be interned (for example: labels in a compiler?).

Function: make-symbol print-name

This function creates and returns a new, uninterned, symbol whose print name is the string print-name. Its variable and function value cells are void and it will have an empty property list.

(make-symbol "foo")
    ⇒ foo

Function: gensym

This function returns a new, uninterned, symbol which has a unique print name.

(gensym)
    ⇒ G0001

(gensym)
    ⇒ G0002

1.8.5 Interning

Interning a symbol means to store it in an obarray so that it can be found in the future: all variables and named-functions are stored in interned symbols.

When a symbol is interned a hash function is applied to its print name to determine which bucket in the obarray it should be stored in. Then it is simply pushed onto the front of that bucket’s chain of symbols.

Normally all interning is done automatically by the Lisp reader. When it encounters the name of a symbol which it can’t find in the default obarray (the value of the variable obarray) it creates a new symbol of that name and interns it. This means that no two symbols can have the same print name, and that the read syntax of a particular symbol always produces the same object (unless the value of obarray is altered).

(eq 'some-symbol 'some-symbol)
    ⇒ t

Function: intern symbol-name &optional obarray

This function uses find-symbol to search the obarray (or the standard obarray) for a symbol called symbol-name. If a symbol of that name is found it is returned, otherwise a new symbol of that name is created, interned into the obarray, and returned.

(intern "setq")
    ⇒ setq

(intern "my-symbol" my-obarray)
    ⇒ my-symbol

Function: intern-symbol symbol &optional obarray

Interns the symbol symbol into the obarray obarray (or the standard one) then returns the symbol. If symbol is currently interned in an obarray an error is signalled.

(intern-symbol (make-symbol "foo"))
    ⇒ foo

(intern-symbol 'foo)
    error--> Error: Symbol is already interned, foo

Function: unintern symbol &optional obarray

This function removes the symbol symbol from the obarray obarray then returns the symbol.

Beware! this function must be used with extreme caution — once you unintern a symbol there’s no way to recover it.

(unintern 'setq)                ;This is extremely stupid
    ⇒ setq

1.8.6 Property Lists

Each symbol has a property list (or plist), this is a structure which associates an arbitrary Lisp object with a key (usually a symbol). The keys in a plist may not have any duplications (so that each property is only defined once).

The concept of a property list is very similar to an association list (see section Association Lists) but there are two main differences:

1. Structure; each element of an alist represents one key/association pair. In a plist each pair of elements represents an association: the first is the key, the second the property. For example, where an alist may be,

   ((one . 1) (two . 2) (three . 3))
   

   a property list would be,

   (one 1 two 2 three 3)
   

2. Plists have their own set of functions to modify the list. This is done destructively, altering the property list (since the plist is stored in only one location, the symbol, this is quite safe).

Function: get symbol property

This function searches the property list of the symbol symbol for a property eq to property. If such a property is found it is returned, else the value nil is returned.

(get 'if 'lisp-indent)
    ⇒ 2

(get 'set 'lisp-indent)
    ⇒ nil

Function: put symbol property new-value

put sets the value of the property property to new-value in the property list of the symbol symbol. If there is an existing value for this property it is overwritten. The value returned is new-value.

(put 'foo 'prop 200)
    ⇒ 200

Function: symbol-plist symbol

Returns the property list of the symbol symbol.

(symbol-plist 'if)
    ⇒ (lisp-indent 2)

Function: setplist symbol plist

This function sets the property list of the symbol symbol to plist.

(setplist 'foo '(zombie yes))
    ⇒ (zombie yes)

1.9 Evaluation

So far I have only discussed a few of the various data types available and how the Lisp reader can convert textual descriptions of these types into Lisp objects. Obviously there has to be a way of actually computing something — it would be difficult to write a useful program otherwise.

What sets Lisp apart from other languages is that in Lisp there is no difference between programs and data: a Lisp program is just a sequence of Lisp objects which will be interpreted when the program is run.

The subsystem which does this interpreting is called the Lisp evaluator and each expression to be evaluated is called a form. The evaluator (the function eval) examines the structure of the form that is applied to and computes the value of the form within the current environment.

A form can be any type of data object; the only types which the evaluator treats specially are symbols (which stand for variables) and lists, anything else is returned as-is (and is called a self-evaluating form).

Function: eval form

This function computes the value of the form which is its argument, within the current environment. The computed value is then returned. eval is the basic function for interpreting Lisp objects.

1.9.1 Symbol Forms

When the evaluator is applied to a symbol the computed value of the form is the object stored in the symbol’s variable slot. Basically this means that to get the value of a variable you simply write its name. For example,

buffer-list
    ⇒ (#<buffer *jade*> #<buffer programmer.texi>)

this extract from a Lisp session shows the read syntax of a form to get the value of the variable buffer-list and the result when this form is evaluated.

Since forms are evaluated within the current environment the value of a variable is its newest binding, or in the case of buffer-local variables, its value in the current buffer. See section Variables.

If the value of an evaluated symbol is void an error is signalled.

1.9.2 List Forms

Forms which are lists are used to call a subroutine. The first element of the list is the subroutine which is to be called; all further elements are arguments to be applied to the subroutine.

There are several different types of subroutines available: functions, macros, special forms and autoloads. When the evaluator finds a form which is a list it tries to classify the form into one of these four types. First of all it looks at the first element of the list, if it is a symbol it gets the value from the function slot of the symbol (note that the first element of a list form is never evaluated itself). This value (either the first element or the symbol’s function value) is enough to classify the form into one of the four types.

1.9.2.1 Function Call Forms

The first element of a function call form is the name of the function, this can be either a symbol (in which case the symbol’s function value is indirected through to get the real function definition) or a lambda expression (see section Lambda Expressions).

Any other elements of the list are forms to be evaluated (in left to right order) and their values become the arguments to the function. The function is applied to these arguments and the result that it returns becomes the value of the form.

For example, consider the form (/ 100 (1+ 4)). This is a function call to the function /. First the 100 form is evaluated: it returns the value 100, next the form (1+ 4) is evaluated. This is also a function call and computes to a value of 5 which becomes the second argument to the / function. Now the / function is applied to its arguments of 100 and 5 and it returns the value 20 which then becomes the value of the form (/ 100 (1+ 4)).

(/ 100 (1+ 4))
≡ (/ 100 5)
⇒ 20

Or another example,

(+ (- 10 (1- 7)) (* (1+ 2) 4)
≡ (+ (- 10 6) (* (1+ 2) 4)
≡ (+ 4 (* (1+ 2) 4)
≡ (+ 4 (* 3 4))
≡ (+ 4 12)
⇒ 16

1.9.2.2 Macro Call Forms

Macros are source code expansions, the general idea is that a macro is a function which using the unevaluated arguments applied to it, computes another form (the expansion of the macro and its arguments) which is then evaluated to provide the value of the form. For more details see Macros.

1.9.2.3 Special Forms

Special forms are built-in functions which the evaluator knows must be handled specially. The main difference between a special form and a function is that the arguments applied to a special form are not automatically evaluated — if necessary the special form will evaluate arguments itself. This will be noted in the documentation of the special form.

Special forms are generally used to provide control structures, for example, all of the conditional constructs are special forms (if all of their arguments, including the forms to be conditionally evaluated, were evaluated automatically this would defeat the object of being conditional!).

The special forms supported by Jade are: and, catch, cond, defconst, defmacro, defun, defvar, error-protect, function, if, let, let*, or, prog1, prog2, progn, quote, setq, setq-default, unless, unwind-protect, when, while, with-buffer, with-window.

1.9.2.4 Autoload Forms

Not all modules of Jade are needed at once, autoload forms provide a means of marking that a function (or macro) is contained by a specific file of Lisp code. The first time that the function is accessed the autoload form will be evaluated; this loads the file that the function is contained by then re-evaluates the list form.

By then the autoload form will have been overwritten in the symbol’s function slot by the true function (when it was loaded) so the form will execute properly.

An autoload form is a list whose first element is the symbol autoload, for full details see Autoloading.

1.9.3 Self-Evaluating Forms

The computed value of any form which is not a symbol or a list will simply be the form itself and the form is said to be a self-evaluating form.

Usually the only forms to be evaluated in this way will be numbers, strings and vectors (since they are the only other data types which have read syntaxes) but the effect is the same for other types of data.

This means that forms you know are self-evaluating do not have to be quoted to be used as constants (like lists and symbols do).

"foo"
    ⇒ "foo"

(eval (current-buffer))
    ⇒ #<buffer programmer.texi>

1.9.4 Quoting

As the above sections explain some types of Lisp object have special meaning to the Lisp evaluator (namely the symbol and list types) this means that if you want to refer to a symbol or a list in a program you can’t (yet) because the evaluator will treat the form as either a variable reference or a function call respectively.

To get around this Lisp uses something called quoting, the quote special form simply returns its argument, without evaluating it. For example,

(quote my-symbol)
    ⇒ my-symbol

the quote form prevents the my-symbol being treated as a variable — it is effectively ‘hidden’ from the evaluator.

Writing ‘quote’ all the time would be a bit boring so there is a shortcut: the Lisp reader treats any form x preceded by a single quote character (‘'’) as the form (quote x). So the example above would normally be written as,

'my-symbol
    ⇒ my-symbol

Special Form: quote form

This special form returns its single argument without evaluating it. This is used to quote constant objects to prevent them from being evaluated.

1.10 Control Structures

Control structures are special forms or macros which control which forms get evaluated, when they get evaluated and the number of times to evaluate them. This includes conditional structures, loops, etc…

The simplest control structures are the sequencing structures; they are used to evaluate a list of forms in left to right order.

1.10.1 Sequencing Structures

Each of the special forms in this section simply evaluates its argument forms in left-to-right order. The only difference is the result they return.

The most widely used sequencing special form is progn: it evaluates all its argument forms and returns the computed value of the last one. Many other control structures are said to perform an implicit progn, this means that they call progn with a list of forms.

progn in Lisp is nearly analogous to a begin…end block in Pascal; it is used in much the same places — to allow you to evaluate a sequence of form where only one form was allowed (for example the true clause of an if structure).

Special Form: progn forms…

All of the forms are evaluated sequentially (from left-to-right), the result of the last evaluated form is the return value of this structure. If no arguments are given to progn it returns nil.

(progn 'one (+ 1 1) "three")
    ⇒ "three"

(progn)
    ⇒ nil

Special Form: prog1 first forms…

This special form evaluates its first form then performs an implicit progn on the rest of its arguments. The result of this structure is the computed value of the first form.

(prog1 'one (+ 1 1) "three")
    ⇒ one

Special Form: prog2 first second forms…

This is similar to prog1 except that the evaluated value of its second form is returned.

The first form is evaluated, then its second, then it performs an implicit progn on the remaining arguments.

(prog2 'one (+ 1 1) "three")
    ⇒ 2

1.10.2 Conditional Structures

Lisp provides a number of conditional constructs, the most complex of which (cond) will take a list of conditions, the first of which is t then has its associated list of forms evaluated. Theoretically this is the only conditional special form necessary — the rest could be implemented as macros.

Special Form: if condition true-form else-forms…

The if construct is the nearest thing in Lisp to the if-then-else construct found in most programming languages.

First the condition form is evaluated, if it returns t (not nil) the true-form is evaluated and its result returned. Otherwise the result of an implicit progn on the else-forms is returned. If there are no else-forms nil is returned.

Note that one of the true-form or the else-forms is completely ignored — it is not evaluated.

(if (special-form-p 'if)
    "`if' is a special form"
  "`if' is not a special form")
    ⇒ "`if' is a special form"

Special Form: when condition true-forms…

condition is evaluated, if it is t the result of an implicit progn on the true-forms is returned, otherwise nil is returned.

(when t
  (message "Pointless")
  'foo)
    ⇒ foo

Special Form: unless condition else-forms…

This special forms first evaluates condition, if its computed value is not nil its value is returned. Otherwise the else-forms are evaluated sequentially, the value of the last is returned.

Special Form: cond clause…

The cond special form is used to choose between an arbitrary number of conditions. Each clause is a list; its car is the condition the list which is the cdr of the clause is the body-forms. This means that each clause looks something like:

(condition body-forms…)

and a whole cond form looks like:

(cond
 (condition-1 body-forms-1…)
 (condition-2 body-forms-2…)
 …)

The condition in each clause is evaluated in sequence (condition-1, then condition-2, …), the first one which evaluates to a non-nil has an implicit progn performed on its body-forms, the value of which is the value returned by the cond form.

If the true condition has no body-forms the value returned by cond is the value of the condition. If none of the clauses has a non-nil condition the value of the cond is nil.

Often you want a default clause; one which has its body-forms to be evaluated if none of the other clauses are true. The way to do this is to add a clause with a condition of t and body-forms of whatever you want the default action to be.

(cond
 ((stringp buffer-list))        ;Clause with no body-forms
 ((consp buffer-list)
  (setq x buffer-list)          ;Two body-forms
  t)
 (t                             ;Default clause
  (error "`buffer-list' is corrupted!")))
    ⇒ t

All of the other conditionals can be written in terms of cond,

(if c t e…) ≡ (cond (c t) (t e…))

(when c t…) ≡ (cond (c t…))

(unless c e…) ≡ (cond (e) (t e…))

There are also a number of special forms which combine conditions together by the normal logical rules.

Special Form: or forms…

The first of the forms is evaluated, if it is non-nil its value becomes the value of the or form and no more of forms are evaluated. Otherwise this step is repeated for the next member of forms.

If all of the forms have been evaluated and none have a non-nil value nil becomes the value of the or form.

If there are no forms nil is returned.

(or nil 1 nil (beep))           ;(beep) won't be evaluated
    ⇒ 1

Special Form: and forms…

The first of the forms is evaluated. If it is nil no more of the forms are evaluated and nil becomes the value of the and structure. Otherwise the next member of forms is evaluated and its value tested. If none of the forms are nil the computed value of the last member of forms becomes the value of the and form.

(and 1 2 nil (beep))            ;(beep) won't be evaluated
    ⇒ nil

(and 1 2 3)                     ;All forms are evaluated
    ⇒ 3

Function: not object

This function inverts the boolean value of its argument. If object is non-nil, nil is returned, otherwise t is returned.

(not nil)
    ⇒ t

(not t)
    ⇒ nil

(not 42)
    ⇒ nil

1.10.3 Looping Structures

Jade’s version of Lisp has only one structure for looping — a while loop similar to those found in most programming languages.

Special Form: while condition body-forms…

The condition form is evaluated. If it is non-nil an implicit progn is performed on the body-forms and the whole thing is repeated again.

This continues until the condition form evaluates to nil. The value of any while structure is nil.

while can be recursively defined in terms of when:

(while c b …)
≡
(when c (progn b … (while c b …)))

;; Step through a list x
(while x
  ;; Do something with the current element, (car x)
  (setq x (cdr x)))

1.10.4 Non-Local Exits

A non-local exit is a transfer of control from the current point of evaluation to a different point (somewhat similar to the much-maligned goto statement in some imperative languages).

Non-local exits can either be used explicitly (catch and throw) or implicitly (errors).

1.10.4.1 Catch and Throw

The catch and throw structures are used to perform explicit transfers of control. First a catch form is used to setup a tag, this acts like a label for the C language’s goto statement. To transfer control a throw form is then used to transfer to the named tag. The tag is destroyed and the catch form exits with the value provided by the throw.

In a program this looks like,

(catch 'tag
  ;; Forms which may `throw' back to tag
  …
  (throw 'tag value)
  ;; Control has now passed to the `catch',
  ;; no more forms in this progn will be evaluated.
  …)
    ⇒ value

where tag is the tag to be used (this is normally a symbol) and value is the result of the catch form.

When a throw actually happens all catches in scope are searched for one with a tag which is eq to the tag in the throw. If more than one exists the most-recent is chosen. Now that the catch has been located the environment is ‘wound-back’ to the catch’s position (i.e. local variables are unbound, cleanup forms removed, unused catches forgotten, etc…) and all Lisp constructs between the current point of control and the catch are exited.

For example,

(let
    ((test 'outer))
  (cons (catch 'foo
          (let
              ((test 'inner))
            (throw 'foo test)
            (setq test 'unreachable)))  ;Never reached
        test))
    ⇒ (inner . outer)

when the throw executes the second binding of test is unwound and the first binding comes back into effect. For more details on variable binding see Local Variables.

Note that catch tags are dynamically scoped, the thrower does not have to be within the same lexical scope (this means you can throw through functions).

Special Form: catch tag body-forms…

This special form defines a catch tag which will be accessible while the body-forms are being evaluated.

tag is evaluated and recorded as the tag for this catch. Next the body-forms are evaluated as an implicit progn. The value of the catch form is either the value of the progn, or, if a throw happened, the value specified in the throw form.

Before exiting the tag installed by this form is removed.

Function: throw tag &optional catch-value

This function transfers the point of control to the catch form with a tag which is eq to tag. The value returned by this catch form is either catch-value or nil if catch-value is undefined.

If there is no catch with a tag of tag an error is signalled and the editor returns to the top-level of evaluation.

1.10.4.2 Function Exits

It is often useful to be able to immediately return control from a function definition (like the C return statement). Jade’s version of Lisp has the return function for this.

Function: return &optional value

This function transfers control out of the most-recent lambda-expression (i.e. a function or macro definition) so that the result of the lambda- expression is value.

(funcall '(lambda () (return 'x) 'y))
    ⇒ x

The 'y form is never evaluated since control is passed straight from the (return 'y) form back to the funcall form.

1.10.4.3 Cleanup Forms

It is sometimes necessary to be sure that a certain form is always evaluated, even when a non-local exit would normally bypass that form. The unwind-protect special form is used to stop this happening.

Special Form: unwind-protect body-form cleanup-forms…

The body-form is evaluated, if it exits normally the cleanup-forms are evaluated sequentially then the value which the body-form returned becomes the value of the unwind-protect form. If the body-form exits abnormally though (i.e. a non-local exit happened) the cleanup-forms are evaluated anyway and the non-local exit continues.

One use of this is to ensure that an opened file is always closed, for example,

(catch 'foo
  (unwind-protect
      (let
          ((temporary-file (open (tmp-file-name) "w")))
        ;; Use temporary-file
        (write temporary-file "A test\n")
        ;; Now force a non-local exit
        (throw 'foo))
    ;; This is the cleanup-form it will always
    ;; be evaluated no matter what happens.
    (close temporary-file)))
    ⇒ nil

1.10.4.4 Errors

Errors are a type of non-local exit; when a form can not be evaluated properly an error is normally signalled. If an error-handler has been installed for that type of error control is unwound back to the handler and evaluation continues. If there is no suitable handler control is passed back to the event loop of the most-recent recursive edit and a suitable error message is printed.

Function: signal error-symbol data

Signals that an error has happened. error-symbol is a symbol classifying the type of error, it should have a property error-message (a string) which is the error message to be printed.

data is a list of objects which are relevant to the error — they will be made available to any error-handler or printed with the error message otherwise.

(signal 'void-value '(some-symbol))
    error--> Value as variable is void: some-symbol

Variable: debug-on-error

This variable is consulted by the function signal. If its value is either t or a list containing the error-symbol to signal as one of its elements, the Lisp debugger is entered. When the debugger exits the error is signalled as normal.

When you expect an error to occur and need to be able to regain control afterwards the error-protect form can be used.

Special Form: error-protect body-form error-handlers…

error-protect evaluates the body-form with error handlers in place.

Each of the error-handlers is a list whose car is a symbol defining the type of error which this handler catches. The cdr of the list is a list of forms to be evaluated sequentially when the handler is invoked.

While the forms of the error handler are being evaluated the variable error-info is bound to the value (error-symbol . data) (these were the arguments to the signal form which caused the error).

The special value, the symbol error, in the car of one of the error-handlers will catch all types of errors.

(error-protect
    (signal 'file-error '("File not found" "/tmp/foo"))
  (file-error
   error-info)
  (error
   (setq x z)))         ;Default handler
    ⇒ (file-error "File not found" "/tmp/foo")

1.11 Variables

In Lisp symbols are used to represent variables. Each symbol contains a slot which is used to contain the value of the symbol when it is used as a symbol.

The normal way to obtain the current value of a variable is simply to evaluate the symbol it lives in (i.e. write the name of the variable in your program).

Function: symbol-value variable

This function returns the value of the symbol variable in the current environment.

1.11.1 Local Variables

A local variable is a variable which has a temporary value while a program is executing, for example, when a function is called the variables which are the names of its arguments are temporarily bound (a binding is a particular instance of a local variable) to the values of the arguments passed to the function. When the function call exits its arguments are unbound and the previous definitions of the variables come back into view.

Even if a variable has more than one binding still ‘active’ only the most recent is visible — there is absolutely no way the previous bindings can be accessed until the bindings are unbound one-by-one.

A nice way of visualising variable binding is to think of each variable as a stack. When the variable is bound to, a new value is pushed onto the stack, when it is unbound the top of the stack is popped. Similarly when the stack is empty the value of the variable is void (see section Void Variables). Assigning a value to the variable (see section Setting Variables) overwrites the top value on the stack with a new value. When the value of the variable is required it is simply read from the top of the stack.

Apart from function calls there are two special forms which perform variable binding (i.e. creating local variables), let and let*.

Special Form: let bindings body-forms…

let creates new variable bindings as specified by the bindings argument then evaluates the body-forms in order. The variables are then unbound to their state before this let form and the value of the implicit progn of the body-forms becomes the value of the let form.

The bindings argument is a list of the bindings to perform. Each binding is either a symbol, in which case that variable is bound to nil, or a list whose car is a symbol. The cdr of this list is a list of forms which, when evaluated, give the value to bind the variable to.

(setq foo 42)
    ⇒ 42
(let
    ((foo (+ 1 2))
     bar)
  ;; Body forms
  (setq foo (1+ foo))   ;This sets the new binding
  (cons foo bar))
    ⇒ (4 . nil)
foo
    ⇒ 42        ;The original values is back

Note that no variables are bound until all the new values have been computed (unlike in let*). For example,

(setq foo 42)
    ⇒ 42
(let
    ((foo 100)
     (bar foo))
  (cons foo bar))
    ⇒ (100 . 42)

Although foo is given a new binding this is not actually done until all the new bindings have been computed, hence bar is bound to the old value of foo.

Special Form: let* bindings body-forms…

This special form is exactly the same as let except for one important difference: the new bindings are installed as they are computed.

You can see the difference by comparing the following example with the last example in the let documentation (above),

(setq foo 42)
    ⇒ 42
(let*                   ;Using let* this time
    ((foo 100)
     (bar foo))
  (cons foo bar))
    ⇒ (100 . 100)

By the time the binding of bar is computed the new binding of foo has already been installed.

1.11.2 Setting Variables

Setting a variable means to overwrite its current value (that is, the value of its most recent binding) with a new one. The old value is irretrievably lost (unlike when a new value is bound to a variable, see section Local Variables).

Special Form: setq variable form …

The special form setq is the usual method of altering the value of a variable. Each variable is set to the result of evaluating its corresponding form. The last value assigned becomes the value of the setq form.

(setq x 20 y (+ 2 3))
    ⇒ 5

In the above example the variable x is set to 20 and y is set to the value of the form (+ 2 3) (5).

When the variable is marked as being buffer-local (see section Buffer-Local Variables) the current buffer’s instance of the variable is set.

Function: set variable new-value

The value of the variable variable (a symbol) is set to new-value and the new-value is returned.

This function is used when the variable is unknown until run-time, and therefore has to be computed from a form.

(set 'foo 20)
≡
(setq foo 20)           ;setq means `set-quoted'
    ⇒ 20

1.11.3 Scope and Extent

In Jade’s version of Lisp all variables have indefinite scope and dynamic extent. What this means is that references to variables may occur anywhere in a program (i.e. bindings established in one function are not only accessible within that function, that’s lexical scope) and that references may occur at any point in the time between the binding being created and it being unbound.

The combination of indefinite scope and dynamic extent is often termed dynamic scope.

As an aside, Lisp objects have indefinite extent, meaning that the object will exist for as long as there is a possibility of it being referenced (and possibly longer — until the garbage collector runs).

Note that in Common Lisp only those variables declared ‘special’ have indefinite scope and dynamic extent.

Try not to abuse the dynamic scoping, although it is often very useful to be able to bind a variable in one function and use it in another this can be confusing if not controlled and documented properly.

A quick example of the use of dynamic scope,

(defun foo (x)
  (let
      ((foo-var (* x 20)))
    (bar x)
    …

(defun bar (y)
  ;; Since this function is called from
  ;; the function foo it can refer
  ;; to any bindings which foo can.
  (setq y (+ y foo-var))
  …

1.11.4 Buffer-Local Variables

It is often very useful to be able to give variables different values for different editor buffers — most major modes need to record some buffer-specific information. Jade allows you to do this by giving a variable buffer-local bindings.

There are two strengths of buffer-local variables: you can either give a variable a buffer-local value in a single buffer, with other buffers treating the variable as normal, or a variable can be marked as being automatically buffer-local, each time the variable is set the current buffer’s value of the variable is updated.

Each buffer maintains an alist of the symbols which have buffer-local values in the buffer and the actual values themselves, this alist may be read with the buffer-variables function.

When the value of a variable is referenced (via the symbol-value function) the current buffer’s alist of local values is examined for a binding of the variable being referenced; if one is found that is the value of the variable, otherwise the default value (the value stored in the symbol’s value cell) is used.

Setting a variable also searches for a buffer-local binding; if one exists its value is modified, not the default value. If the variable has previously been marked as being automatically buffer-local (by make-variable-buffer-local) a buffer-local binding is automatically created if one doesn’t already exist.

Currently there is one main problem with buffer-local variables: they can’t have temporary values bound to them (or rather, they can but I guarantee it won’t work how you expect), so for the time being, don’t try to bind local values (with let or let*) to a buffer-local variable.

Function: make-local-variable symbol

This function gives the variable symbol a buffer-local binding in the current buffer. The value of this binding will be the same as the variable’s default value.

If symbol already has a buffer-local value in this buffer nothing happens.

Returns symbol.

Function: make-variable-buffer-local symbol

This function marks the variable symbol as being automatically buffer-local.

This means that any attempts at setting the value of symbol will actually set the current buffer’s local value (if necessary a new buffer-local binding will be created in the buffer).

Returns symbol.

(make-variable-buffer-local 'buffer-modtime)
    ⇒ buffer-modtime

Function: default-value symbol

This function returns the default value of the variable symbol.

(setq foo 'default)
    ⇒ default
(make-local-variable 'foo)      ;Create a value in this buffer
    ⇒ foo
(setq foo 'local)
    ⇒ local
foo
    ⇒ local
(symbol-value 'foo)
    ⇒ local
(default-value 'foo)
    ⇒ default

Function: default-boundp symbol

Returns t if the variable symbol has a non-void default value.

Special Form: setq-default symbol form …

Similar to the setq special form except that the default value of each variable is set. In non-buffer-local symbols there is no difference between setq and setq-default.

Function: set-default symbol new-value

Sets the default value of the variable symbol to new-value, then returns new-value.

Function: kill-local-variable symbol

This function removes the buffer-local binding of the variable symbol from the current buffer (if one exists) then returns symbol.

Function: kill-all-local-variables

This function removes all the buffer-local bindings associated with the current buffer. Subsequently, any buffer-local variables referenced while this buffer is current will use their default values.

The usual way to define an automatically buffer-local variable is to use defvar and make-variable-buffer-local, for example,

(defvar my-local-variable default-value
  "Doc string for my-local-variable.")
(make-variable-buffer-local 'my-local-variable)

Note that if you want to reference the value of a buffer-local variable in a buffer other than the current buffer, use the with-buffer special form (see section The Current Buffer). For example, the form,

(with-buffer other-buffer some-variable)

will produce the value of the variable some-variable in the buffer other-buffer.

1.11.5 Void Variables

A variable which has no value is said to be void, attempting to reference the value of such a symbol will result in an error. It is possible for the most recent binding of a variable to be void even though the inactive bindings may have values.

Function: boundp variable

Returns t if the symbol variable has a value, nil if its value is void.

Function: makunbound variable

This function makes the current binding of the symbol variable be void, then returns variable.

(setq foo 42)
    ⇒ 42
foo
    ⇒ 42
(boundp 'foo)
    ⇒ t
(makunbound 'foo)
    ⇒ foo
(boundp 'foo)
    ⇒ nil
foo
    error--> Value as variable is void: foo

1.11.6 Constant Variables

In Lisp constants are represented by variables which have been marked as being read-only. Any attempt to alter the value of a constant results in an error.

Two of the most commonly used constants are nil and t.

Function: set-const-variable variable &optional read-write

This function defines whether or not the value of the symbol variable may be modified. If read-write is nil or undefined the variable is marked to be constant, otherwise it’s marked to be a normal variable. The value returned is variable.

Function: const-variable-p variable

Returns t if the value of the symbol variable may be altered, nil otherwise.

Constants may behave a bit strangely when you compile the program they are used in: the value of the constant is likely to be hardwired into the compiled functions it is used in, and the constant is unlikely to be eq to itself!

The compiler assumes that constant is always the same, whenever it is evaluated. It may even be evaluated more than once. See section Compiled Lisp.

The special form defconst can be used to define constants, see Defining Variables.

1.11.7 Defining Variables

The special forms defvar and defconst allow you to define the global variables which will be used in a program. This is entirely optional; it is highly recommended though.

Special Form: defvar variable form [doc-string]

This special form defines a global variable, the symbol variable. If the value of variable is void the form is evaluated and its value is stored as the value of variable (note that the default value is modified, never a buffer-local value).

If the doc-string argument is defined it is a string documenting variable. This string is then stored as the symbol’s variable-documentation property and can be accessed by the describe-variable function.

(defvar my-variable '(x y)
  "This variable is an example showing the usage of the defvar
special form.")
    ⇒ my-variable

Special Form: defconst constant form [doc-string]

defconst defines a constant, the symbol constant. Its value (in the case of a buffer-local symbol, its default value) is set to the result of evaluating form. Note that unlike defvar the value of the symbol is always set, even if it already has a value.

The doc-string argument, if defined, is the documentation string for the constant.

(defconst the-answer 42
  "An example constant.")
    ⇒ the-answer

See section Constant Variables.

1.12 Functions

A function is a Lisp object which, when applied to a sequence of argument values, produces a value — the function’s result. It may also produce side-effects. All Lisp functions return results — there is nothing like a procedure in Pascal.

Functions are the main building-block in Lisp programs, each program is usually a system of inter-related functions.

There are two types of function: primitive functions are functions written in the C language, these are sometimes called built-in functions, the object containing the C code itself is called a subr. All other functions are written in Lisp.

Function: functionp object

Returns t if object is a function (i.e. it can be used as the function argument of funcall.

(functionp 'set)
    ⇒ t

(functionp 'setq)
    ⇒ nil

(functionp #'(lambda (x) (+ x 2)))
   ⇒ t

1.12.1 Lambda Expressions

Lambda expressions are used to create an object of type function from other Lisp objects, it is a list whose first element is the symbol lambda. All functions written in Lisp (as opposed to the primitive functions in C) are represented by a lambda expression.

Note that a lambda expression is not an expression, evaluating a lambda expression will give an error (unless there is a function called lambda).

The format of a lambda expression is:

(lambda lambda-list [doc] [interactive-declaration] body-forms… )

Where lambda-list is the argument specification of the function, doc is an optional documentation string, interactive-declaration is only required by editor commands (see section Commands) and the body-forms is the actual function code (when the function is called each form is evaluated in sequence, the last form’s value is the result returned by the function).

The lambda-list is a list, it defines how the argument values applied to the function are bound to local variables which represent the arguments within the function. At its simplest it is simply a list of symbols, each symbol will have the corresponding argument value bound to it. For example, the lambda list,

(lambda (x y) (+ x y))

takes two arguments, x and y. When this function is called with two arguments the first will be bound to x and the second to y (then the function will return their sum).

To complicate matters there are several lambda-list keywords which modify the meaning of symbols in the lambda-list. Each keyword is a symbol whose name begins with an ampersand, they are:

&optional

All the variables following this keyword are considered optional (all variables before the first keyword are required: an error will be signalled if a required argument is undefined in a function call). If an optional argument is undefined it will simply be given the value nil.

Note that optional arguments must be specified if a later optional argument is also specified. Use nil to explicitly show that an optional argument is undefined.

For example, if a function foo takes two optional arguments and you want to call it with only the second argument defined, the first argument must be specified as nil to ensure that the correct argument value is bound to the correct variable.

(defun foo (&optional arg-1 arg-2)
  …

(foo nil arg-2-value)   ;Leave the first argument undefined

&rest

The &rest keyword allows a variable number of arguments to be applied to a function, all the argument values which have not been bound to argument variables are simply consed into a list and bound to the variable after the &rest keyword. For example, in,

(lambda (x &rest y) …)

the first argument, x, is required. Any other arguments applied to this function are made into a list and this list is bound to the y variable.

When a function represented by a lambda-list is called the first thing that happens is to bind the argument values to the argument variables. The lambda-list and the list of argument values applied to the function are worked through in parallel. Any required arguments which are left undefined when the end of the argument values has been reached causes an error.

After the arguments have been processed the body-forms are evaluated by an implicit progn, the value of which becomes the value of the function call. Finally, all argument variables are unbound and control passes back to the caller.

1.12.2 Named Functions

Functions are normally associated with symbols, the name of the symbol being the same as the name of its associated function. Each symbol has a special function cell (this is totally separate from the symbol’s value as a variable — variables and functions may have the same name without any problems occurring) which is used to store the function’s definition, either a lambda expression (see section Lambda Expressions) or a subr (C code) object.

The evaluator knows to indirect through the function value of a symbol in any function call (see section Function Call Forms) so the normal way to call a function is simply write its name as the first element in a list, any arguments making up the other elements in the list. See section List Forms.

The functions and special forms which take functions as their arguments (i.e. funcall) can also take symbols. For example,

(funcall 'message "An example")
≡
(message "An example")

Function: symbol-function symbol

Returns the value of the function cell in the symbol symbol.

(symbol-function 'symbol-function)
    ⇒ #<subr symbol-function>

Function: fboundp symbol

This function returns t if the symbol symbol has a non-void value in its function cell, nil otherwise.

(fboundp 'setq)
    ⇒ t

Function: fset symbol new-value

Sets the value of the function cell in the symbol symbol to new-value, then returns new-value.

This function is rarely used, see Defining Functions.

Function: fmakunbound symbol

This function makes the value of the function cell in symbol void, then returns symbol.

1.12.3 Anonymous Functions

When giving function names as arguments to functions it is useful to give an actual function definition (i.e. a lambda expression) instead of the name of a function.

In Lisp, unlike most other programming languages, functions have no inherent name. As seen in the last section named-functions are created by storing a function in a special slot of a symbol, if you want, a function can have many different names: simply store the function in many different symbols!

So, when you want to pass a function as an argument there is the option of just writing down its definition. This is especially useful with functions like mapcar and delete-if. For example, the following form removes all elements from the list which are even and greater than 20.

(setq list (delete-if #'(lambda (x)
                                (and (zerop (% x 2))
                                     (> x 20)))
                            list))

The lambda expression is very simple, it combines two predicates applied to its argument.

Note that the function definition is quoted by #', not the normal '. This is a special shortcut for the function special form (like ' is a shortcut to quote). In general, #'x is expanded by the Lisp reader to (function x).

Special Form: function arg

This special form is nearly identical to the quote form, it always returns its argument without evaluating it. The difference is that the Lisp compiler knows to compile the arg into a byte-code form (unless arg is a symbol in which case it is not compiled).

What this means is when you have to quote a function, use the #' syntax.

1.12.4 Predicate Functions

In Lisp, a function which returns a boolean ‘true’ or boolean ‘false’ value is called a predicate. As is the convention in Lisp a value of nil means false, anything else means true. The symbol t is often used to represent a true value (in fact, sometimes the symbol t should be read as any non-nil value).

Another Lisp convention is that the names of predicate functions should be the concept the predicate is testing for and either ‘p’ or ‘-p’.

The ‘p’ variant is used when the concept name does not contain any hyphens.

For example a predicate to test for the concept const-variable (a variable which has a constant value, see section Constant Variables) would be called const-variable-p. On the other hand a predicate to test for the concept buffer (a Lisp object which is a buffer) would be called bufferp.

1.12.5 Defining Functions

Named functions are normally defined by the defun special form.

Special Form: defun name lambda-list body-forms…

defun initialises the function definition of the symbol name to the lambda expression resulting from the concatenation of the symbol lambda, lambda-list and the body-forms. So,

(defun foo (x y)
  …
≡
(fset 'foo #'(lambda (x y)
               …

The body-forms may contain a documentation string for the function as its first form and an interactive calling specification as its first (if there is no doc-string) or second form if the function may be called interactively by the user (see section Commands).

An example function definition (actually a command) taken from Jade’s source is,

(defun upcase-word (count)
  "Makes the next COUNT words from the cursor upper-case."
  (interactive "p")
  (let
      ((pos (forward-word count)))
    (upcase-area (cursor-pos) pos)
    (goto-char pos)))

1.12.6 Calling Functions

Most of the time function calls are done by the evaluator when it detects a function call form (see section List Forms); when the function to be called is not known until run-time it is easier to use a special function to call the function directly than create a custom form to apply to the eval function.

Function: funcall function &rest args

Applies the argument values args to the function function, then returns its result.

Note that the argument values args are not evaluated again. This also means that funcall can not be used to call macros or special forms — they would need the unevaluated versions of args, which are not available to funcall.

(funcall '+ 1 2 3)
    ⇒ 6

Function: apply function &rest args

Similar to funcall except that the last of its arguments is a list of arguments which are appended to the other members of args to form the list of argument values to apply to the function function.

Constructs a list of arguments to apply to the function function from args.

1.12.7 Mapping Functions

A mapping function applies a function to each of a collection of objects. Jade currently has two mapping functions, mapcar and mapc.

Function: mapcar function list

Each element in the list list is individually applied to the function function. The values returned are made into a new list which is returned.

The function should be able to be called with one argument.

(mapcar '1+ '(1 2 3 4 5))
    ⇒ (2 3 4 5 6)

Function: mapc function list

Similar to mapcar except that the values returned when each element is applied to the function function are discarded. The value returned is list.

This function is generally used where the side effects of calling the function are the important thing, not the results.

The two following functions are also mapping functions of a sort. They are variants of the delete function (see section Modifying Lists) and use predicate functions to classify the elements of the list which are to be deleted.

Function: delete-if predicate list

This function is a variant of the delete function. Instead of comparing each element of list with a specified object, each element of list is applied to the predicate function predicate. If it returns t (i.e. not nil) then the element is destructively removed from list.

(delete-if 'stringp '(1 "foo" 2 "bar" 3 "baz"))
    ⇒ (1 2 3)

Function: delete-if-not predicate list

This function does the inverse of delete-if. It applies predicate to each element of list, if it returns nil then the element is destructively removed from the list.

(delete-if-not 'stringp '(1 "foo" 2 "bar" 3 "baz"))
    ⇒ ("foo" "bar" "baz")

1.13 Macros

Macros are used to extend the Lisp language, they are basically a function which instead of returning its value, return a new form which will produce the macro call’s value when evaluated.

When a function being compiled calls a macro the macro is expanded immediately and the resultant form is open-coded into the compiler’s output.

1.13.1 Defining Macros

Macros are defined in the same style as functions, the only difference is the name of the special form used to define them.

A macro object is a list whose car is the symbol macro, its cdr is the function which creates the expansion of the macro when applied to the macro calls unevaluated arguments.

Special Form: defmacro name lambda-list body-forms…

Defines the macro stored in the function cell of the symbol name. lambda-list is the lambda-list specifying the arguments to the macro (see section Lambda Expressions) and body-forms are the forms evaluated when the macro is expanded. The first of body-forms may be a documentation string describing the macro’s use.

Here is a simple macro definition, it is a possible definition for the when construct (which might even be useful if when wasn’t already defined as a special form…),

(defmacro when (condition &rest body)
  "Evaluates condition, if it's non-nil evaluates the body
forms."
  (list 'if condition (cons 'progn body)))

When a form of the type (when c b …) is evaluated the macro definition of when expands to the form (if c (progn b …)) which is then evaluated to perform my when-construct.

When you define a macro ensure that the forms which produce the expansion have no side effects; it would fail spectacularly when you attempt to compile your program!

1.13.2 Macro Expansion

When a macro call is detected (see section List Forms) the function which is the cdr of the macro’s definition (see section Defining Macros) is applied to the macro call’s arguments. Unlike in a function call, the arguments are not evaluated, the actual forms are the arguments to the macro’s expansion function. This is so these forms can be rearranged by the macro’s expansion function to create the new form which will be evaluated.

There is a function which performs macro expansion, its main use is to let the Lisp compiler expand macro calls at compile time.

Function: macroexpand form &optional environment

If form is a macro call macroexpand will expand that call by calling the macro’s expansion function (the cdr of the macro definition). If this expansion is another macro call the process is repeated until an expansion is obtained which is not a macro call, this form is then returned.

The optional environment argument is an alist of macro definitions to use as well as the existing macros; this is mainly used for compiling purposes.

(defmacro when (condition &rest body)
  "Evaluates condition, if it's non-nil evaluates the body
forms."
  (list 'if condition (cons 'progn body)))
    ⇒ when

(macroexpand '(when x (setq foo bar)))
    ⇒ (if x (progn (setq foo bar)))

1.13.3 Compiling Macros

Although it may seem odd that macros return a form to produce a result and not simply the result this is their most important feature. It allows the expansion and the evaluation of the expansion to happen at different times.

The Lisp compiler makes use of this; when it comes across a macro call in a form it is compiling it uses the macroexpand function to produce the expansion of that form which it then compiles straight into the object code. Obviously this is good for performance (why evaluate the expansion every time it is needed when once will do?).

Some rules do need to be observed to make this work properly:

• When the compiler compiles a file it remembers the macros which have been defined by that file; it can only expand a macro call if the definition of the macro appears before the macro call itself (it can’t read your mind).
• The macro expansion function (i.e. the definition of the macro) should not have any side effects or evaluate its arguments (the value of a symbol at compile-time probably won’t be the same as its value at run-time).
• Macros which are defined by another file must be loaded so they can be recognised. Use the require function, the compiler will evaluate any top-level require forms it sees to bring in any macro definitions used.

1.14 Streams

A stream is a Lisp object which is either a data sink (an output stream) or a data source (an input stream). In Jade all streams produce or consume sequences of 8-bit characters.

Streams are very flexible, functions using streams for their input and output do not need to know what type of stream it is. For example the Lisp reader (the read function) takes an input stream as its one argument, it then reads characters from this stream until it has parsed a whole object. This stream could be a file, a position in a buffer, a function or even a string; the read function can not tell the difference.

Function: streamp object

This function returns t if its argument is a stream.

1.14.1 Input Streams

These are the possible types of input stream, for the functions which use them see Input Functions.

file

Characters are read from the file object file, for the functions which manipulate file objects see Files.

mark

The marker mark points to the next character that will be read. Each time a character is read the position that mark points to will be advanced to the following character. See section Marks.

buffer

Reads from the position of the cursor in the buffer buffer. This position is advanced as characters are read.

(buffer . position)

Characters are read from the position position in the buffer buffer. position is advanced to the next character as each character is read.

function

Each time an input character is required the function is called with no arguments. It should return the character read (an integer) or nil if for some reason no character is available.

function should also be able to ‘unread’ one character. When this happens the function will be called with one argument — the value of the last character read. The function should arrange it so that the next time it is called it returns this character. A possible implementation could be,

(defvar ms-unread-char nil
  "If non-nil the character which was pushed back.")

(defun my-stream (&optional unread-char)
  (if unread-char
      (setq ms-unread-char unread-char)
    (if ms-unread-char
        (prog1
          ms-unread-char
          (setq ms-unread-char nil))
      ;; Normal case -- read and return a character from somewhere
      …

nil

Read from the stream stored in the variable standard-input.

It is also possible to use a string as an input stream. The string to be read from must be applied to the make-string-input-stream function and the result from this function used as the input stream.

Function: make-string-input-stream string &optional start

Returns an input stream which will supply the characters of the string string in order starting with the character at position start (or from position zero if this argument is undefined).

(read (make-string-input-stream "(1 . 2)"))
    ⇒ (1 . 2)

Variable: standard-input

The input stream which is used when no other is specified or is nil.

1.14.2 Output Streams

These are the different types of output stream, for the functions which use them see Output Functions.

file

Writes to the file object file. See section Files.

mark

Writes to the position pointed to by the marked mark, then advances the position of the mark.

buffer

Writes to buffer at the position of the cursor in that buffer, which is then advanced.

(buffer . position)

position in the buffer buffer. position is then moved over the written text.

(buffer . t)

Writes to the end of the buffer buffer.

function

The function function is called with one argument, either a string or a character. This should be used as the circumstances dictate. If the function returns a number it is the number of characters actually used, otherwise it is assumed that all the characters were successful.

process

Writes to the standard input of the process object process. If process isn’t running an error is signalled. See section Processes.

t

Appends the character(s) to the end of the status line message.

nil

Write to the stream stored in the variable standard-output.

It is also possible to store the characters sent to an output stream in a string.

Function: make-string-output-stream

Returns an output stream. It accumulates the text sent to it for the benefit of the get-output-stream-string function.

Function: get-output-stream-string string-output-stream

Returns a string consisting of the text sent to the string-output-stream since the last call to get-output-stream-string (or since this stream was created by make-string-output-stream).

(setq stream (make-string-output-stream))
    ⇒ ("" . 0)
(prin1 keymap-path stream)
    ⇒ ("(lisp-mode-keymap global-keymap)" . 64)
(get-output-stream-string stream)
    ⇒ "(lisp-mode-keymap global-keymap)"

Variable: standard-output

This variable contains the output stream which is used when no other is specified (or when the given output stream is nil).

1.14.3 Input Functions

Function: read-char stream

Read and return the next character from the input stream stream. If the end of the stream is reached nil is returned.

Function: read-line stream

This function reads one line of characters from the input stream stream, creates a string containing the line (including the newline character which terminates the line) and returns it.

If the end of stream is reached before any characters can be read nil is returned, if the end of stream is reached but some characters have been read (but not the newline) these characters are made into a string and returned.

Note that unlike the Common Lisp function of the same name, the newline character is not removed from the returned string.

Function: read stream

This function is the function which contains the Lisp reader (see section The Lisp Reader). It reads as many characters from the input stream stream as it needs to make the read syntax of a single Lisp object (see section Read Syntax), this object is then returned.

Function: read-from-string string &optional start

Reads one Lisp object from the string string, the first character is read from position start (or position zero).

(read-from-string string start)
≡
(read (make-string-input-stream string start))

1.14.4 Output Functions

Function: write stream data &optional length

Writes the specified character(s) to the output stream stream. data is either the character or the string to be written. If data is a string the optional argument length may specify how many characters are to be written. The value returned is the number of characters successfully written.

(write standard-output "Testing 1.. 2.. 3..")
    -| Testing 1.. 2.. 3..
    ⇒ 19

Function: copy-stream input-stream output-stream

This function copies all characters which may be read from input-stream to output-stream. The copying process is not stopped until the end of the input stream is read. Returns the number of characters copied.

Be warned, if you don’t choose the streams carefully you may get a deadlock which only an interrupt signal can break!

Function: print object &optional stream

Outputs a newline character to the output stream stream, then writes a textual representation of object to the stream.

If possible, this representation will be such that read can turn it into an object structurally similar to object. This will not be possible if object does not have a read syntax.

object is returned.

(print '(1 2 3))
    -|
    -| (1 2 3)
    ⇒ (1 2 3)

Function: prin1 object &optional stream

Similar to print but no initial newline is output.

(prin1 '(1 2 3))
    -| (1 2 3)
    ⇒ (1 2 3)

(prin1 '|(xy((z]|)              ;A strange symbol
    -| \(xy\(\(z\]
    ⇒ \(xy\(\(z\]

Function: prin1-to-string object

Returns a string containing the characters that prin1 would output when it prints object.

(prin1-to-string '(1 2 3))
    ⇒ "(1 2 3)"

Function: princ object &optional stream

Prints a textual representation of object to the output stream stream. No steps are taken to create output that read can parse and no quote characters surround strings.

(princ "foo")
    -| foo
    ⇒ "foo"

(princ '|(xy((z]|)
    -| (xy((z]
    ⇒ \(xy\(\(z\]

Function: format stream template &rest values

Writes to a stream, stream, a string constructed from the format string, template, and the argument values.

If stream is nil the resulting string will be returned, not written to a stream.

template is a string which may contain format specifiers, these are a ‘%’ character followed by another character telling how to print the next of the values. The following options are available

‘s’

Write the printed representation of the value without quoting (as if from the princ function).

‘S’

Write the printed representation with quoting enabled (like the prin1 function).

‘d’

Output the value as a decimal number.

‘o’

Write the value in octal.

‘x’

In hexadecimal.

‘c’

Write the character specified by the value.

‘%’

Print a literal percent character. None of the values are used.

The function works through the template a character at a time. If the character is a format specifier (a ‘%’) it inserts the correct string (as defined above) into the output. Otherwise, the character is simply put into the output stream.

If stream isn’t nil (i.e. the formatted string is returned) the value of stream is returned.

(format nil "foo %S bar 0x%x" '(x . y) 255)
    ⇒ "foo (x . y) bar 0xff"

(format standard-output "The %s is %s!" "dog" "purple")
    -| The dog is purple!
    ⇒ #<buffer *jade*>

1.15 Loading

In Lisp, programs (also called modules) are stored in files. Each file is a sequence of Lisp forms (known as top-level forms). Most of the top-level forms in a program will be definitions (i.e. function, macro or variable definitions) since generally each module is a system of related functions and variables.

Before the program can be used it has to be loaded into the editor’s workspace; this involves reading and evaluating each top-level form in the file.

1.15.1 Load Function

Function: load program &optional no-error no-path no-suffix

This function loads the file containing the program called program; first the file is located then each top-level form contained by the file is read and evaluated in order.

Each directory named by the variable load-path is searched until the file containing program is found. In each directory three different file names are tried,

1. program with ‘.jlc’ appended to it. Files with a ‘.jlc’ suffix are usually compiled Lisp files. See section Compiled Lisp.
2. program with ‘.jl’ appended, most uncompiled Lisp programs are stored in files with names like this.
3. program with no modifications.

If none of these gives a result the next directory is searched in the same way, when all directories in load-path have been exhausted and the file still has not been found an error is signalled.

Next the file is opened for reading and Lisp forms are read from it one at a time, each form is evaluated before the next form is read. When the end of the file is reached the file has been loaded and this function returns t.

The optional arguments to this function are used to modify its behaviour,

no-error

When this argument is non-nil no error is signalled if the file can not be located. Instead the function returns nil.

no-path

The variable load-path is not used, program must point to the file from the current working directory.

no-suffix

When non-nil no ‘.jlc’ or ‘.jl’ suffixes are applied to the program argument when locating the file.

If a version of the program whose name ends in ‘.jlc’ is older than a ‘.jl’ version of the same file (i.e. the source code is newer than the compiled version) a warning is displayed and the ‘.jl’ version is used.

(load "foobar")
    error--> File error: Can't open lisp-file, foobar

(load "foobar" t)
    ⇒ nil

Variable: load-path

A list of strings, each element is the name of a directory which is prefixed to the name of a program when Lisp program files are being searched for.

load-path
    ⇒ ("" "/usr/local/lib/jade/3.2/lisp/")

The element "" means the current directory, note that directory names should have an ending ‘/’ (or whatever) so that when concatenated with the name of the file they make a meaningful filename.

Variable: lisp-lib-dir

The name of the directory in which the standard Lisp files are stored.

lisp-lib-dir
    ⇒ "/usr/local/lib/jade/3.2/lisp/"

1.15.2 Autoloading

Obviously, not all the features of the editor are always used. Autoloading allows modules to be loaded when they are referenced. This speeds up the initialisation process and may save memory.

Functions which may be autoloaded have a special form in their symbol’s function cell — an autoload form. This is a list whose first element is the symbol autoload. When the function call dispatcher finds one of these forms it loads the program file specified in the form then re-evaluates the function call. The true function definition will have been loaded and therefore the call may proceed as normal.

The structure of an autoload form is:

(autoload program-file [is-command])

program-file is the argument to give to the load function when the function is to be loaded. It should be the program containing a definition of the autoloaded function.

The optional is-command object specifies whether or not the function may be called interactively (i.e. it is an editor command).

Function: autoload symbol &rest autoload-defn

Installs an autoload form into the function cell of the symbol symbol. The form is a cons cell whose car is autoload and whose cdr is the argument autoload-defn.

Returns the resulting autoload form.

(autoload 'foo "foos-file")
    ⇒ (autoload "foos-file")
(symbol-function 'foo)
    ⇒ (autoload "foos-file")

(autoload 'bar "bars-file" t)
    ⇒ (autoload "bars-file" t)
(commandp 'bar)
    ⇒ t

It is not necessary to call the autoload function manually. Simply prefix the definitions of all the functions which may be autoloaded (i.e. the entry points to your module; not all the internal functions!) with the magic comment ;;;###autoload. Then the add-autoloads command can be used to create the necessary calls to the autoload function in the ‘autoloads.jl’ Lisp file (this file which lives in the Lisp library directory is loaded when the editor is initialised).

Meta-x add-autoloads

Scans the current buffer for any autoload definitions. Functions with the comment ;;;###autoload preceding them have autoload forms inserted into the ‘autoloads.jl’ file. Simply save this file’s buffer and the new autoloads will be used the next time Jade is initialised.

It is also possible to mark arbitrary forms for inclusion in the ‘autoloads.jl’ file: put them on a single line which starts with the comment ;;;###autoload call the command.

The unsaved ‘autoloads.jl’ buffer will become the current buffer.

;;;###autoload
(defun foo (bar)                ;foo is to be autoloaded
  …

;;;###autoload (setq x y)       ;Form to eval on initialisation

Meta-x remove-autoloads

Remove all autoload forms from the ‘autoloads.jl’ file which are marked by the ;;;###autoload comment in the current buffer.

The unsaved ‘autoloads.jl’ buffer will become the current buffer.

1.15.3 Features

Features correspond to modules of the editor. Each feature is loaded separately. Each feature has a name, when a certain feature is required its user asks for it to be present (with the require function), the feature may then be used as normal.

When a feature is loaded one of the top-level forms evaluated is a call to the provide function. This names the feature and installs it into the list of present features.

Variable: features

A list of the features currently present (that is, loaded). Each feature is represented by a symbol. Usually the print name of the symbol (the name of the feature) is the same as the name of the file it was loaded from, minus any ‘.jl’ or ‘.jlc’ suffix.

features
    ⇒ (info isearch fill-mode texinfo-mode lisp-mode xc)

Function: provide feature

Adds feature (a symbol) to the list of features present. A call to this function is normally one of the top-level forms in a module.

;;;; maths.jl -- the maths module

(provide 'maths)
…

Function: require feature &optional file

Show that the caller is planning to use the feature feature (a symbol). This function will check the features variable to see if feature is already loaded, if so it will return immediately.

If feature is not present it will be loaded. If file is non-nil it specifies the first argument to the load function, else the print name of the symbol feature is used.

;;;; physics.jl -- the physics module

(require 'maths)                ;Need the maths module
(provide 'physics)
…

1.16 Compiled Lisp

Jade contains a rudimentary Lisp compiler; this takes a Lisp form or program and compiles it into a byte-code form. This byte-code form contains a string of byte instructions, a vector of data constants and some other information.

The main reason for compiling your programs is to increase their speed, it is difficult to quantify the speed increase gained — some programs (especially those using a lot of macros) will execute many times quicker than their uncompiled version whereas others may only execute a bit quicker.

1.16.1 Compilation Functions

Function: compile-form form

This function compiles the Lisp form form into a byte-code form which is returned.

(compile-form '(setq foo bar))
    ⇒ (jade-byte-code "F!" [bar foo] 2)

Command: compile-file file-name

This function compiles the file called file-name into a file of compiled Lisp forms whose name is file-name with ‘c’ appended to it (i.e. if file-name is ‘foo.jl’ it will be compiled to ‘foo.jlc’).

If an error occurs while the file is being compiled any semi-written file will be deleted.

When called interactively this function will ask for the value of file-name.

Command: compile-directory directory &optional force exclude

Compiles all the Lisp files in the directory called directory which either haven’t been compiled or whose compiled version is older than the source file (Lisp files are those ending in ‘.jl’).

If the optional argument force is non-nil all Lisp files will be recompiled whatever the status of their compiled version.

The exclude argument may be a list of filenames, these files will not be compiled.

When this function is called interactively it prompts for the directory.

Function: compile-lisp-lib &optional force

Uses compile-directory to compile the library of standard Lisp files. If force is non-nil all of these files will be compiled.

The ‘autoloads.jl’ is never compiled since it is often modified and wouldn’t really benefit from compilation anyway.

Function: jade-byte-code byte-codes constants max-stack

Interprets the string of byte instructions byte-codes with the vector of constants constants. max-stack defines the maximum number of stack cells required to interpret the code.

This function is never called by hand. The compiler will produce calls to this function when it compiles a form or a function.

(setq x 1
      y 3)
    ⇒ 3
(setq comp (compile-form '(cons x y)))
    ⇒ (jade-byte-code "K" [x y] 2)
(eval comp)
    ⇒ (1 . 3)

1.16.2 Compilation Tips

Here are some tips for making compiled code run fast:

• Always favour iteration over recursion; function calls are relatively slow. The compiler doesn’t know about tail recursion or whatever so you’ll have to do this explicitly.

  For example, the most elegant way of searching a list is to use recursion,

  (defun scan-list (list elt)
    "Search the LIST for an element ELT. Return it if one is found."
    (if (eq (car list) elt)
        elt
      (scan-list (cdr list) elt)))
  

  but this is fairly slow. Instead, iterate through each element,

  (defun scan-list (list elt)
    (while (consp list)
      (when (eq (car list) elt)
        (return elt))
      (setq list (cdr list))))
  

• In some cases the functions member, memq, assoc, etc… can be used to search lists. Since these are primitives written in C they will run much faster than an equivalent Lisp function.

  So the above scan-list example can be rewritten as,

  (defun scan-list (list elt)
    (car (memq elt list)))
  

  Also note that the mapcar and mapc functions are useful (and efficient) when using lists.

• Whenever possible use the when and unless conditional structures; they are more efficient than cond or if.
• Careful use of named constants (see section Constant Variables) can increase the speed of some programs. For example, in the Lisp compiler itself all the opcode values (small integers) are defined as constants.

  I must stress that in some cases constants are not suitable; they may drastically increase the size of the compiled program (when the constants are ‘big’ objects, i.e. long lists) or even introduce subtle bugs (since two references to the same constant may not be eq whereas two references to the same variable are always eq).

• Many primitives have corresponding byte-code instructions; these primitives will be quicker to call than those that don’t (and incur a normal function call). Currently, the functions which have byte-code instructions (apart from all the special forms) are:

  cons, car, cdr, rplaca, rplacd, nth, nthcdr, aset, aref, length, eval, +, *, /, %, lognot, not, logior, logand, equal, eq, =, /=, >, <, >=, <=, 1+, 1-, -, set, fset, lsh, zerop, null, atom, consp, listp, numberp, stringp, vectorp, throw, fboundp, boundp, symbolp, get, put, signal, return, reverse, nreverse, assoc, assq, rassoc, rassq, last, mapcar, mapc, member, memq, delete, delq, delete-if, delete-if-not, copy-sequence, sequencep, functionp, special-formp, subrp, eql, set-current-buffer, current-buffer, bufferp, markp, windowp.

• When a file is being compiled each top-level form it contains is inspected to see if it should be compiled into a byte-code form. Different types of form are processed in different ways:
  • Function and macro definitions have their body forms compiled into a single byte-code form. The doc-string and interactive declaration are not compiled.
  • Calls to the require function are evaluated then the unevaluated form is written as-is to the output file. The reason it is evaluated is so that any macros defined in the required module are loaded before they are called by the program being compiled.
  • If the form is a list form (see section List Forms) and the symbol which is the car of the list is one of:

    if, cond, when, unless, let, let*, catch, unwind-protect, error-protect, with-buffer, with-window, progn, prog1, prog2, while, and, or.

    then the form is compiled. Otherwise it is just written to the output file in its uncompiled state.

  If your program contains a lot of top-level forms which you know will not be compiled automatically, consider putting them in a progn block to make the compiler coalesce them into one byte-code form.

1.16.3 Disassembly

It is possible to disassemble byte-code forms; originally this was so I could figure out why the compiler wasn’t working but if you’re curious about how the compiler compiles a form it may be of use to you.

Naturally, the output of the disassembler is a listing in Jade’s pseudo-machine language — it won’t take a byte-code form and produce the equivalent Lisp code!

Command: disassemble-fun function &optional stream

This function disassembles the compile Lisp function function. It writes a listing to the output stream stream (normally the value of the standard-output variable).

When called interactively it will prompt for a function to disassemble.

When reading the output of the disassembler bear in mind that Jade simulates a stack machine for the code to run on. All calculations are performed on the stack, the value left on the stack when the piece of code ends is the value of the byte-code form.

1.17 Hooks

A hook allows you to wedge your own pieces of Lisp code into the editor’s operations. These pieces of code are evaluated via the hook and the result is available to the hook’s caller.

1.17.1 Functions As Hooks

Some hooks only allow a single piece of code to be hooked in. Usually a normally-undefined function is used; to install your hook defined a function with the name of the hook. When the hook is to be evaluated the function is called.

Generally the name of the hook’s function will end in -function.

An alternative scheme is to use a variable to store the hook, its value should be the function to call.

1.17.2 Normal Hooks

This is the standard type of hook, it is a variable whose value is a list of functions. When the hook is evaluated each of the named functions will be called in turn until one of them returns a value which is not nil. This value becomes the value of the hook and no more of the functions are called. If all of the functions in the hook return nil the value of the hook is nil.

The names of hooks of this type will normally end in -hook.

Function: add-hook hook function &optional at-end

This function adds a new function function to the list of functions installed in the (list) hook hook (a symbol).

If at-end is non-nil the new function is added at the end of the hook’s list of functions (and therefore will be called last when the hook is evaluated), otherwise the new function is added to the front of the list.

text-mode-hook
    ⇒ (fill-mode-on)
(add-hook 'text-mode-hook 'my-function)
    ⇒ (my-function fill-mode-on)

Function: remove-hook hook function

This function removes the function function from the list of functions stored in the (list) hook hook (a symbol).

All instances of function are deleted from the hook.

text-mode-hook
    ⇒ (my-function fill-mode-on)
(remove-hook 'text-mode-hook 'my-function)
    ⇒ (fill-mode-on)

Function: eval-hook hook &rest args

Evaluates the (list) hook hook (a symbol) with argument values args.

Each function stored in the hook is applied to the args in turn until one returns non-nil. This non-nil value becomes the result of the hook. If all functions return nil then the result of the hook is nil.

Note that most functions which are installed in hooks should always return nil to ensure that all the functions in the hook are evaluated.

1.17.3 Standard Hooks

This is a table of the predefined hooks in Jade:

asm-cpp-mode-hook

@xref{Asm mode}.

asm-mode-hook

@xref{Asm mode}.

auto-save-hook

See section Controlling Auto-Saves.

buffer-menu-mode-hook

c-mode-hook

@xref{C mode}.

destroy-window-hook

See section Closing Windows.

gdb-hook

idle-hook

See section Idle Actions.

indented-text-mode-hook

@xref{Indented-Text mode}.

insert-file-hook

See section Reading Files Info Buffers.

kill-buffer-hook

See section Destroying Buffers.

lisp-mode-hook

@xref{Lisp mode}.

make-window-hook

See section Opening Windows.

open-file-hook

See section Reading Files Info Buffers.

read-file-hook

See section Reading Files Info Buffers.

shell-callback-function

shell-mode-hook

texinfo-mode-hook

@xref{Texinfo mode}.

text-mode-hook

@xref{Text mode}.

unbound-key-hook

See section Event Loop.

window-closed-hook

See section Event Loop.

write-file-hook

See section Writing Buffers.

1.18 Buffers

A buffer is a Lisp object containing a ‘space’ in which files (or any pieces of text) may be edited, either directly by the user or by Lisp programs.

Each window (see section Windows) may display any one buffer at any time, the buffer being displayed by the current window is known as the current buffer. This is the buffer which functions will operate on by default.

Function: bufferp object

Returns t if its argument is a buffer.

1.18.1 Buffer Attributes

All buffer objects store a set of basic attributes, some of these are:

name

Each buffer has a unique name.

Function: buffer-name &optional buffer

Returns the name of the buffer buffer, or of the current buffer if buffer is undefined.

(buffer-name)
    ⇒ "programmer.texi"

Function: set-buffer-name name &optional buffer

Sets the name of the buffer buffer (or the current buffer) to the string name.

Note that name is not checked for uniqueness, use the make-buffer-name function if you want a guaranteed unique name.

Function: make-buffer-name name

Returns a unique version of the string name so that no existing buffer has the same string as its name. If a clash occurs a suffix ‘<N>’ is appended to name, where n is the first number which guarantees the uniqueness of the result.

Function: get-buffer name

Returns the existing buffer whose name is name, or nil if no such buffer exists.

file name

Since buffers often contain text belonging to files on disk the buffer stores the name of the file its text was read from. See section Editing Files.

Function: buffer-file-name &optional buffer

Returns the name of the file stored in buffer. If no file is stored in the buffer the null string (‘’) is returned.

(buffer-file-name)
    ⇒ "man/programmer.texi"

Function: set-buffer-file-name name &optional buffer

This function sets the file-name of the buffer to the string name.

Function: get-file-buffer file-name

Searches for an existing buffer containing the file file-name then returns it, or nil if no such buffer exists.

contents

The contents of a buffer is the text it holds. This is stored as an array of lines. See section Text.

tab size

This is the spacing of tab stops. When the contents of the buffer is being displayed (in a window) this value is used.

Variable: tab-size

A buffer-local variable which holds the size of tab stops in the buffer.

glyph table

Each buffer has its own glyph table which is used when the buffer is being displayed. See section Buffer Glyph Tables.

local variables

Each buffer can have its own value for any variable, these local values are stored in an alist which lives in the buffer object. See section Buffer-Local Variables.

Function: buffer-variables &optional buffer

Returns the alist of local variables in the buffer. Each alist element is structured like, (symbol . local-value).

modification counter

Each modification made to the buffer increments its modification counter. See section Modifications to Buffers.

Function: buffer-changes &optional buffer

Returns the number of modifications made to the buffer since it was created.

undo information

When a modification is made to a buffer enough information is recorded so that the modification can later be undone. See section Controlling Undo.

All other buffer-specific information is kept in buffer-local variables.

1.18.2 Creating Buffers

Function: make-buffer name

Creates and returns a new buffer object. Its name will be a unique version of name (created by the make-buffer-name function).

The buffer will be totally empty and all its attributes will have standard values.

(make-buffer "foo")
    ⇒ #<buffer foo>

Function: open-buffer name

If no buffer called name exists, creates a new buffer of that name and adds it to the end of each windows buffer-list. This function always returns the buffer called name.

For more ways of creating buffers see Editing Files.

1.18.3 Modifications to Buffers

Each buffer maintains a counter which is incremented each time the contents of the buffer is modified. It also holds the value of this counter when the buffer was last saved, when the two numbers are different the buffer is classed as have being modified.

Function: buffer-modified-p &optional buffer

This function returns t when the buffer has been modified.

Function: set-buffer-modified buffer status

Sets the modified status of the buffer buffer. When status is nil the buffer will appear to be unmodified, otherwise it will look modified.

1.18.4 Read-Only Buffers

When a buffer has been marked as being read-only no modifications may be made to its contents (neither by the user nor a Lisp program).

Function: buffer-read-only-p &optional buffer

Returns t when the buffer is read-only.

Function: set-buffer-read-only buffer read-only

When read-only is non-nil the buffer buffer is marked as being read-only, otherwise it is read-write.

Variable: inhibit-read-only

When this variable is non-nil any buffer may be modified, even if it is marked as being read-only.

Lisp programs can temporarily bind a non-nil value to this variable when they want to edit one of their normally read-only buffers.

1.18.5 Destroying Buffers

Since all Lisp objects have indefinite extent (i.e. they live until there are no references to them) a buffer will be automatically destroyed when all references to it disappear.

Alternatively one of the following functions can be used to explicitly kill a buffer; the buffer object will still exist but all data associated with it (including the text it contains) will be released.

Command: kill-buffer buffer

Removes the buffer buffer (a buffer or the name of a buffer) from all windows (any windows displaying buffer will be changed to display the previous buffer they showed) and destroys the buffer.

The hook kill-buffer-hook is evaluated before the buffer is killed with buffer as its argument.

If the buffer contains unsaved modifications the user will be asked if they really want to lose them before the buffer is killed (if the answer is yes).

When called interactively a buffer will be prompted for.

Hook: kill-buffer-hook

Hook called by kill-buffer before it does anything. If a function in the hook doesn’t want the buffer deleted it should signal some sort of error.

Function: destroy-buffer buffer

This function may be used to remove all data stored in the buffer object manually. Also, any marks in this buffer are made non-resident.

After applying this function to a buffer the buffer will contain one empty line.

Use this function wisely, there are no safety measures taken to ensure valuable data is not lost.

1.18.6 Special Buffers

When a buffer is special it means that it is controlled by a Lisp program, not by the user typing into it (although this can happen as well).

Special buffers are used for things like the ‘*jade*’ or ‘*Info*’ buffers (in fact most of the buffers whose names are surrounded by asterisks are special).

What the special attribute actually does is make sure that the buffer is never truly killed (kill-buffer removes it from each window’s buffer-list but doesn’t call destroy-buffer on it) and modifications don’t cause the ‘+’ flag to appear in the status line.

Function: buffer-special-p &optional buffer

Returns t if the buffer is marked as being special.

Function: set-buffer-special buffer special

Sets the value of the special flag in the buffer buffer to the value of special (nil means non-special, anything else means special).

Another type of special buffer exists; the mildly-special buffer.

Variable: mildly-special-buffer

When this buffer-local variable is set to t (it is nil by default) and the buffer is marked as being special, the kill-buffer function is allowed to totally destroy the buffer.

1.18.7 The Buffer List

Each window (see section Windows) has a list of buffers which may be displayed in that window. It is arranged is most-recently-used order, so that the car of the list is the buffer currently being shown in the window, the second element the window previously being shown and so on.

Variable: buffer-list

A variable, local to each window, which contains a list of the buffers available in the window. The list is maintained in most-recently-used order.

buffer-list
    ⇒ (#<buffer programmer.texi> #<buffer *Help*>
               #<buffer buffers.c> #<buffer buffers.jl>
               #<buffer edit.c> #<buffer edit.h>
               #<buffer *jade*> #<buffer lisp.jl>
               #<buffer *compilation*> #<buffer *Info*>)

Generally each window’s buffer-list contains the same buffers, each window has its own value for the variable so it can be kept in the correct order (each window will probably be displaying different buffers).

Function: add-buffer buffer

This function ensures that the buffer buffer is in each window’s buffer-list. If it isn’t it is appended to the end of the list.

Function: remove-buffer buffer

Deletes all references to buffer in each window’s buffer-list.

Command: bury-buffer &optional buffer all-windows

Puts buffer (or the currently displayed buffer) at the end of the current window’s buffer-list then switch to the buffer at the head of the list.

If all-windows is non-nil this is done in all windows (the same buffer will be buried in each window though).

Command: rotate-buffers-forward

Moves the buffer at the head of the buffer-list to be last in the list, the new head of the buffer-list is displayed in the current window.

1.18.8 The Current Buffer

The current buffer is the buffer being displayed in the current window (see section Windows), all functions which take an optional buffer argument will operate on the current buffer if this argument is undefined. Similarly if a window argument to a function is left undefined the current window will be used.

Function: current-buffer &optional window

Returns the buffer being displayed by the window window (or the current window).

(current-buffer)
    ⇒ #<buffer programmer.texi>

The set-current-buffer function sets the current buffer of a window. If, when the window is next redisplayed (i.e. after each command), the current buffer is different to what it was at the last redisplay the new buffer will be displayed in the window.

Function: set-current-buffer buffer &optional window

Sets the buffer that the window is displaying.

Usually a window’s current buffer will be the buffer which is at the head of the window’s buffer-list. The function goto-buffer can be used to set both of these at once.

Function: goto-buffer buffer

Set the current buffer to buffer which is either a buffer or a string naming a buffer. The selected buffer is moved to the head of the window’s buffer-list.

If buffer is a string and no buffer exists of that name a new one is created.

Often you will want to temporarily switch to a different current buffer, that is what the with-buffer special form is for.

Special Form: with-buffer buffer forms…

Temporarily sets the current buffer to the value of evaluating buffer, then evaluates the forms in sequence. The old value of the current buffer is reinstated and the structure returns the value of the last of the forms to be evaluated.

If the implicit progn evaluating forms is exited abnormally the old value of the current buffer will still be reinstated.

If the window is redisplayed while the forms are being evaluated (i.e. in a recursive edit) the new buffer will be drawn into the window.

(with-buffer new-buffer         ;Enter a recursive edit in
  (recursive-edit))             ; the buffer new-buffer.

1.19 Windows

A window is a Lisp object representing a window (a rectangular section of the display) open in the windowing-system you are running Jade in.

Windows have two main functions, firstly to provide a means of seeing the contents of a buffer and secondly to receive input events. For more details about event handling see Event Loop.

A window always displays a buffer and there is always at least one window open. The editor remembers which of the open windows is the current window, this is normally the window it last received an input event from, though it can be set by programs.

For some basic details about using windows see @ref{Using Windows}.

Function: windowp object

This function returns t if its argument is a window.

Variable: window-list

This variable’s value is a list of all the currently open windows. The order of the elements in the list is insignificant.

window-list
    ⇒ (#<window 20971528 *Info*> #<window 20971524 *jade*>)

1.19.1 Opening Windows

Function: open-window &optional buffer x y width height

Opens a new window and returns it. If buffer is defined it is the buffer to display in the new window, otherwise the current buffer is displayed.

The x and y arguments are the pixel coordinates of the new window’s top left corner in the display. The width and height arguments are the size of the window in columns and rows of characters respectively.

What happens when the position and size of the window is undefined will depend on the underlying window system, on the Amiga the window will probably be the same as the current window, in X11 the window manager will probably let the user size it interactively.

The new window will have its buffer-list variable initialised suitably and it will be added to the head of the window-list variable.

The make-window function is the lowest level of creating a new window, open-window uses it to open the window.

Function: make-window &optional x y width height

Creates a new window and returns it, the arguments are similar to those of the same name in the open-window function. The window will display the current buffer.

After the window is created the make-window-hook will be called with the window as its argument.

Hook: make-window-hook

Hook called each time a new window is created. It has one argument, the new window.

Variable: pub-screen

This window-local variable is only used on the Amiga version of Jade; it holds the name of the public screen which windows are opened on. By default this is the Workbench screen.

When a window is opened it inherits this value from the current window at the time.

1.19.2 Closing Windows

Unlike buffers, window objects don’t have indefinite extent, even when a window is incapable of being referenced the object will not be destroyed by the garbage collector; count the user looking at the window as a reference!

When the window is closed (by the destroy-window function) the object loses its ‘window-ness’ and the garbage collector is free to reclaim its memory.

Function: close-window &optional window

This function closes the window window (or the current window) and deletes its entry from the window-list variable.

If this window is the only one the editor has open the user is asked if it’s okay to lose any modified buffers before the window is closed.

Function: close-other-windows &optional window

Uses close-window to close all windows except window (or the current window).

Function: destroy-window window

Closes the window window. After a window object has been closed it is no longer a member of the type ‘window’.

Before closing the window the destroy-window-hook is evaluated with the window being destroyed as an argument.

When the last window is closed the editor will exit automatically.

Like the destroy-buffer function, this function is dangerous if used carelessly.

Both close-window and close-other-windows eventually call this function.

Hook: destroy-window-hook

Hook called by destroy-window before it does anything. It has one argument — the window to be destroyed.

1.19.3 Iconifying Windows

When you don’t want a window cluttering the display, but don’t want to kill it totally it can be iconified; the window will be displayed as a small icon which can be reactivated when the window is wanted again.

Function: sleep-window &optional window

Iconifies the specified window.

Function: unsleep-window &optional window

Uniconifies the specified window. This may be done automatically if the user needs to be prompted.

Function: toggle-iconic

Toggles the current window between the iconified and normal states. This command is bound to the key sequence Ctrl-z.

Function: window-asleep-p

Returns t when the current window is iconified.

1.19.4 Displaying Messages

Often it is useful to be able to show the user a short one-line message, this is what the message function does.

Function: message message &optional display-now

This function displays the string message in the status line of the current window, then returns message.

If display-now is non-nil the message is rendered into the window immediately, otherwise it will not be visible until the next general redisplay (usually after each command exits).

Note that an alternate way of writing in the status line is to use the output stream t. See section Output Streams.

When writing interactive programs it is sometimes useful to be able to render the cursor in the status line. This shows that the next key press will not be subject to normal editing key bindings but to the special user interface (usually explained by a message in the status line).

For example the y-or-n-p function uses this technique to show that it needs an answer.

Variable: status-line-cursor

When this window-local variable is non-nil the window’s cursor is rendered at the end of the message in the status line, not at the cursor’s position in the main display.

Another way of alerting the user is to use the beep function,

Function: beep

This function rings a bell or flashes the current window or screen depending on your system.

1.19.5 The Current Window

The current window is the window that functions operate on by default; every time the event loop receives some input from the user the window which the input event originated in becomes the current window. It is also possible for Lisp programs to set the current window, either permanently or temporarily.

The active window is the window which the windowing system will send any keyboard input to. Since Jade sets the current window to where it receives input from, it is often the case that the current window is the same as the active window. Jade also provides the means to set the active window; in some cases this may be best left to the user though.

Function: current-window

This function returns the current window.

(current-window)
    ⇒ #<window 20971524 programmer.texi>

Function: set-current-window window &optional activate

This function sets the current window to be the window window. If the optional argument activate is non-nil this window will also become the active window.

When using the activate argument bear in mind that it may be confusing for the user if the active window is suddenly changed; only change the active window synchronously with some input from the user.

Special Form: with-window window forms…

Temporarily sets the current window to the value of evaluating the form window, then uses an implicit progn to evaluate the forms. The old current window is then reinstated before returning the value of the implicit progn.