Next: Floating-Point Type, Up: Programming Types   [Contents][Index]

2.4.1 Integer Type ¶

Under the hood, there are two kinds of integers—small integers, called fixnums, and large integers, called bignums.

The range of values for a fixnum depends on the machine. The minimum range is −536,870,912 to 536,870,911 (30 bits; i.e., −2**29 to 2**29 − 1) but many machines provide a wider range.

Bignums can have arbitrary precision. Operations that overflow a fixnum will return a bignum instead.

All numbers can be compared with eql or =; fixnums can also be compared with eq. To test whether an integer is a fixnum or a bignum, you can compare it to most-negative-fixnum and most-positive-fixnum, or you can use the convenience predicates fixnump and bignump on any object.

The read syntax for integers is a sequence of (base ten) digits with an optional sign at the beginning and an optional period at the end. The printed representation produced by the Lisp interpreter never has a leading ‘+’ or a final ‘.’.

-1               ; The integer −1.
1                ; The integer 1.
1.               ; Also the integer 1.
+1               ; Also the integer 1.

See Numbers, for more information.

Next: Character Type, Previous: Integer Type, Up: Programming Types   [Contents][Index]

2.4.2 Floating-Point Type ¶

Floating-point numbers are the computer equivalent of scientific notation; you can think of a floating-point number as a fraction together with a power of ten. The precise number of significant figures and the range of possible exponents is machine-specific; Emacs uses the C data type double to store the value, and internally this records a power of 2 rather than a power of 10.

The printed representation for floating-point numbers requires either a decimal point (with at least one digit following), an exponent, or both. For example, ‘1500.0’, ‘+15e2’, ‘15.0e+2’, ‘+1500000e-3’, and ‘.15e4’ are five ways of writing a floating-point number whose value is 1500. They are all equivalent.

See Numbers, for more information.

Next: Symbol Type, Previous: Floating-Point Type, Up: Programming Types   [Contents][Index]

2.4.3 Character Type ¶

A character in Emacs Lisp is nothing more than an integer. In other words, characters are represented by their character codes. For example, the character A is represented as the integer 65. That is also their usual printed representation; see Basic Char Syntax.

Individual characters are used occasionally in programs, but it is more common to work with strings, which are sequences composed of characters. See String Type.

Characters in strings and buffers are currently limited to the range of 0 to 4194303—twenty two bits (see Character Codes). Codes 0 through 127 are ASCII codes; the rest are non-ASCII (see Non-ASCII Characters). Characters that represent keyboard input have a much wider range, to encode modifier keys such as Control, Meta and Shift.

There are special functions for producing a human-readable textual description of a character for the sake of messages. See Describing Characters for Help Messages.

• Basic Char Syntax
• General Escape Syntax
• Control-Character Syntax
• Meta-Character Syntax
• Other Character Modifier Bits

?Q ⇒ 81     ?q ⇒ 113

?\a ⇒ 7                 ; control-g, C-g
?\b ⇒ 8                 ; backspace, BS, C-h
?\t ⇒ 9                 ; tab, TAB, C-i
?\n ⇒ 10                ; newline, C-j
?\v ⇒ 11                ; vertical tab, C-k
?\f ⇒ 12                ; formfeed character, C-l
?\r ⇒ 13                ; carriage return, RET, C-m
?\e ⇒ 27                ; escape character, ESC, C-[
?\s ⇒ 32                ; space character, SPC
?\\ ⇒ 92                ; backslash character, \
?\d ⇒ 127               ; delete character, DEL

?\^I ⇒ 9     ?\C-I ⇒ 9

?\^? ⇒ 127     ?\C-? ⇒ 127

Next: Sequence Types, Previous: Character Type, Up: Programming Types   [Contents][Index]

2.4.4 Symbol Type ¶

A symbol in GNU Emacs Lisp is an object with a name. The symbol name serves as the printed representation of the symbol. In ordinary Lisp use, with one single obarray (see Creating and Interning Symbols), a symbol’s name is unique—no two symbols have the same name.

A symbol can serve as a variable, as a function name, or to hold a property list. Or it may serve only to be distinct from all other Lisp objects, so that its presence in a data structure may be recognized reliably. In a given context, usually only one of these uses is intended. But you can use one symbol in all of these ways, independently.

A symbol whose name starts with a colon (‘:’) is called a keyword symbol. These symbols automatically act as constants, and are normally used only by comparing an unknown symbol with a few specific alternatives. See Variables that Never Change.

A symbol name can contain any characters whatever. Most symbol names are written with letters, digits, and the punctuation characters ‘-+=*/’. Such names require no special punctuation; the characters of the name suffice as long as the name does not look like a number. (If it does, write a ‘\’ at the beginning of the name to force interpretation as a symbol.) The characters ‘_~!@$%^&:<>{}?’ are less often used but also require no special punctuation. Any other characters may be included in a symbol’s name by escaping them with a backslash. In contrast to its use in strings, however, a backslash in the name of a symbol simply quotes the single character that follows the backslash. For example, in a string, ‘\t’ represents a tab character; in the name of a symbol, however, ‘\t’ merely quotes the letter ‘t’. To have a symbol with a tab character in its name, you must actually use a tab (preceded with a backslash). But it’s rare to do such a thing.

Common Lisp note: In Common Lisp, lower case letters are always folded to upper case, unless they are explicitly escaped. In Emacs Lisp, upper case and lower case letters are distinct.

Here are several examples of symbol names. Note that the ‘+’ in the fourth example is escaped to prevent it from being read as a number. This is not necessary in the sixth example because the rest of the name makes it invalid as a number.

foo                 ; A symbol named ‘foo’.
FOO                 ; A symbol named ‘FOO’, different from ‘foo’.

1+                  ; A symbol named ‘1+’
                    ;   (not ‘+1’, which is an integer).

\+1                 ; A symbol named ‘+1’
                    ;   (not a very readable name).

\(*\ 1\ 2\)         ; A symbol named ‘(* 1 2)’ (a worse name).
+-*/_~!@$%^&=:<>{}  ; A symbol named ‘+-*/_~!@$%^&=:<>{}’.
                    ;   These characters need not be escaped.

As an exception to the rule that a symbol’s name serves as its printed representation, ‘##’ is the printed representation for an interned symbol whose name is an empty string. Furthermore, ‘#:foo’ is the printed representation for an uninterned symbol whose name is foo. (Normally, the Lisp reader interns all symbols; see Creating and Interning Symbols.)

Next: Cons Cell and List Types, Previous: Symbol Type, Up: Programming Types   [Contents][Index]

2.4.5 Sequence Types ¶

A sequence is a Lisp object that represents an ordered set of elements. There are two kinds of sequence in Emacs Lisp: lists and arrays.

Lists are the most commonly-used sequences. A list can hold elements of any type, and its length can be easily changed by adding or removing elements. See the next subsection for more about lists.

Arrays are fixed-length sequences. They are further subdivided into strings, vectors, char-tables and bool-vectors. Vectors can hold elements of any type, whereas string elements must be characters, and bool-vector elements must be t or nil. Char-tables are like vectors except that they are indexed by any valid character code. The characters in a string can have text properties like characters in a buffer (see Text Properties), but vectors do not support text properties, even when their elements happen to be characters.

Lists, strings and the other array types also share important similarities. For example, all have a length l, and all have elements which can be indexed from zero to l minus one. Several functions, called sequence functions, accept any kind of sequence. For example, the function length reports the length of any kind of sequence. See Sequences, Arrays, and Vectors.

It is generally impossible to read the same sequence twice, since sequences are always created anew upon reading. If you read the read syntax for a sequence twice, you get two sequences with equal contents. There is one exception: the empty list () always stands for the same object, nil.

Next: Array Type, Previous: Sequence Types, Up: Programming Types   [Contents][Index]

2.4.6 Cons Cell and List Types ¶

A cons cell is an object that consists of two slots, called the CAR slot and the CDR slot. Each slot can hold any Lisp object. We also say that the CAR of this cons cell is whatever object its CAR slot currently holds, and likewise for the CDR.

A list is a series of cons cells, linked together so that the CDR slot of each cons cell holds either the next cons cell or the empty list. The empty list is actually the symbol nil. See Lists, for details. Because most cons cells are used as part of lists, we refer to any structure made out of cons cells as a list structure.

A note to C programmers: a Lisp list thus works as a linked list built up of cons cells. Because pointers in Lisp are implicit, we do not distinguish between a cons cell slot holding a value versus pointing to the value.

Because cons cells are so central to Lisp, we also have a word for an object which is not a cons cell. These objects are called atoms.

The read syntax and printed representation for lists are identical, and consist of a left parenthesis, an arbitrary number of elements, and a right parenthesis. Here are examples of lists:

(A 2 "A")            ; A list of three elements.
()                   ; A list of no elements (the empty list).
nil                  ; A list of no elements (the empty list).
("A ()")             ; A list of one element: the string "A ()".
(A ())               ; A list of two elements: A and the empty list.
(A nil)              ; Equivalent to the previous.
((A B C))            ; A list of one element
                     ;   (which is a list of three elements).

Upon reading, each object inside the parentheses becomes an element of the list. That is, a cons cell is made for each element. The CAR slot of the cons cell holds the element, and its CDR slot refers to the next cons cell of the list, which holds the next element in the list. The CDR slot of the last cons cell is set to hold nil.

The names CAR and CDR derive from the history of Lisp. The original Lisp implementation ran on an IBM 704 computer which divided words into two parts, the address and the decrement; CAR was an instruction to extract the contents of the address part of a register, and CDR an instruction to extract the contents of the decrement. By contrast, cons cells are named for the function cons that creates them, which in turn was named for its purpose, the construction of cells.

• Drawing Lists as Box Diagrams
• Dotted Pair Notation
• Association List Type

    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup

 ---------------       ----------------       -------------------
| car   | cdr   |     | car    | cdr   |     | car       | cdr   |
| rose  |   o-------->| violet |   o-------->| buttercup |  nil  |
|       |       |     |        |       |     |           |       |
 ---------------       ----------------       -------------------

    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> A        --> nil

    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
     |             --> oak      --> maple
     |
     |     --- ---      --- ---
      --> |   |   |--> |   |   |--> nil
           --- ---      --- ---
            |            |
            |            |
             --> pine     --> needles

 --------------       --------------       --------------
| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
|   o   |   o------->| oak   |   o------->| maple |  nil |
|   |   |      |     |       |      |     |       |      |
 -- | ---------       --------------       --------------
    |
    |
    |        --------------       ----------------
    |       | car   | cdr  |     | car     | cdr  |
     ------>| pine  |   o------->| needles |  nil |
            |       |      |     |         |      |
             --------------       ----------------

    --- ---
   |   |   |--> violet
    --- ---
     |
     |
      --> rose

    --- ---      --- ---
   |   |   |--> |   |   |--> buttercup
    --- ---      --- ---
     |            |
     |            |
      --> rose     --> violet

    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> rose     --> violet

    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup

(setq alist-of-colors
      '((rose . red) (lily . white) (buttercup . yellow)))

Next: String Type, Previous: Cons Cell and List Types, Up: Programming Types   [Contents][Index]

2.4.7 Array Type ¶

An array is composed of an arbitrary number of slots for holding or referring to other Lisp objects, arranged in a contiguous block of memory. Accessing any element of an array takes approximately the same amount of time. In contrast, accessing an element of a list requires time proportional to the position of the element in the list. (Elements at the end of a list take longer to access than elements at the beginning of a list.)

Emacs defines four types of array: strings, vectors, bool-vectors, and char-tables.

A string is an array of characters and a vector is an array of arbitrary objects. A bool-vector can hold only t or nil. These kinds of array may have any length up to the largest fixnum, subject to system architecture limits and available memory. Char-tables are sparse arrays indexed by any valid character code; they can hold arbitrary objects.

The first element of an array has index zero, the second element has index 1, and so on. This is called zero-origin indexing. For example, an array of four elements has indices 0, 1, 2, and 3. The largest possible index value is one less than the length of the array. Once an array is created, its length is fixed.

All Emacs Lisp arrays are one-dimensional. (Most other programming languages support multidimensional arrays, but they are not essential; you can get the same effect with nested one-dimensional arrays.) Each type of array has its own read syntax; see the following sections for details.

The array type is a subset of the sequence type, and contains the string type, the vector type, the bool-vector type, and the char-table type.

Next: Vector Type, Previous: Array Type, Up: Programming Types   [Contents][Index]

2.4.8 String Type ¶

A string is an array of characters. Strings are used for many purposes in Emacs, as can be expected in a text editor; for example, as the names of Lisp symbols, as messages for the user, and to represent text extracted from buffers. Strings in Lisp are constants: evaluation of a string returns the same string.

See Strings and Characters, for functions that operate on strings.

• Syntax for Strings
• Non-ASCII Characters in Strings
• Nonprinting Characters in Strings
• Text Properties in Strings

"It is useful to include newlines
in documentation strings,
but the newline is \
ignored if escaped."
     ⇒ "It is useful to include newlines
in documentation strings,
but the newline is ignored if escaped."

#("characters" property-data...)

beg end plist

#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))

Next: Char-Table Type, Previous: String Type, Up: Programming Types   [Contents][Index]

2.4.9 Vector Type ¶

A vector is a one-dimensional array of elements of any type. It takes a constant amount of time to access any element of a vector. (In a list, the access time of an element is proportional to the distance of the element from the beginning of the list.)

The printed representation of a vector consists of a left square bracket, the elements, and a right square bracket. This is also the read syntax. Like numbers and strings, vectors are considered constants for evaluation.

[1 "two" (three)]      ; A vector of three elements.
     ⇒ [1 "two" (three)]

See Vectors, for functions that work with vectors.

Next: Bool-Vector Type, Previous: Vector Type, Up: Programming Types   [Contents][Index]

2.4.10 Char-Table Type ¶

A char-table is a one-dimensional array of elements of any type, indexed by character codes. Char-tables have certain extra features to make them more useful for many jobs that involve assigning information to character codes—for example, a char-table can have a parent to inherit from, a default value, and a small number of extra slots to use for special purposes. A char-table can also specify a single value for a whole character set.

The printed representation of a char-table is like a vector except that there is an extra ‘#^’ at the beginning.¹

See Char-Tables, for special functions to operate on char-tables. Uses of char-tables include:

• Case tables (see The Case Table).
• Character category tables (see Categories).
• Display tables (see Display Tables).
• Syntax tables (see Syntax Tables).

Next: Hash Table Type, Previous: Char-Table Type, Up: Programming Types   [Contents][Index]

2.4.11 Bool-Vector Type ¶

A bool-vector is a one-dimensional array whose elements must be t or nil.

The printed representation of a bool-vector is like a string, except that it begins with ‘#&’ followed by the length. The string constant that follows actually specifies the contents of the bool-vector as a bitmap—each character in the string contains 8 bits, which specify the next 8 elements of the bool-vector (1 stands for t, and 0 for nil). The least significant bits of the character correspond to the lowest indices in the bool-vector.

(make-bool-vector 3 t)
     ⇒ #&3"^G"
(make-bool-vector 3 nil)
     ⇒ #&3"^@"

These results make sense, because the binary code for ‘C-g’ is 111 and ‘C-@’ is the character with code 0.

If the length is not a multiple of 8, the printed representation shows extra elements, but these extras really make no difference. For instance, in the next example, the two bool-vectors are equal, because only the first 3 bits are used:

(equal #&3"\377" #&3"\007")
     ⇒ t

Next: Function Type, Previous: Bool-Vector Type, Up: Programming Types   [Contents][Index]

2.4.12 Hash Table Type ¶

A hash table is a very fast kind of lookup table, somewhat like an alist in that it maps keys to corresponding values, but much faster. The printed representation of a hash table specifies its properties and contents, like this:

(make-hash-table)
     ⇒ #s(hash-table)

See Hash Tables, for more information about hash tables.

Next: Macro Type, Previous: Hash Table Type, Up: Programming Types   [Contents][Index]

2.4.13 Function Type ¶

Lisp functions are executable code, just like functions in other programming languages. In Lisp, unlike most languages, functions are also Lisp objects. A non-compiled function in Lisp is a lambda expression: that is, a list whose first element is the symbol lambda (see Lambda Expressions).

In most programming languages, it is impossible to have a function without a name. In Lisp, a function has no intrinsic name. A lambda expression can be called as a function even though it has no name; to emphasize this, we also call it an anonymous function (see Anonymous Functions). A named function in Lisp is just a symbol with a valid function in its function cell (see Defining Functions).

Most of the time, functions are called when their names are written in Lisp expressions in Lisp programs. However, you can construct or obtain a function object at run time and then call it with the primitive functions funcall and apply. See Calling Functions.

Next: Primitive Function Type, Previous: Function Type, Up: Programming Types   [Contents][Index]

2.4.14 Macro Type ¶

A Lisp macro is a user-defined construct that extends the Lisp language. It is represented as an object much like a function, but with different argument-passing semantics. A Lisp macro has the form of a list whose first element is the symbol macro and whose CDR is a Lisp function object, including the lambda symbol.

Lisp macro objects are usually defined with the built-in defmacro macro, but any list that begins with macro is a macro as far as Emacs is concerned. See Macros, for an explanation of how to write a macro.

Warning: Lisp macros and keyboard macros (see Keyboard Macros) are entirely different things. When we use the word “macro” without qualification, we mean a Lisp macro, not a keyboard macro.

Next: Closure Function Type, Previous: Macro Type, Up: Programming Types   [Contents][Index]

2.4.15 Primitive Function Type ¶

A primitive function is a function callable from Lisp but written in the C programming language. Primitive functions are also called subrs or built-in functions. (The word “subr” is derived from “subroutine”.) Most primitive functions evaluate all their arguments when they are called. A primitive function that does not evaluate all its arguments is called a special form (see Special Forms).

It does not matter to the caller of a function whether the function is primitive. However, this does matter if you try to redefine a primitive with a function written in Lisp. The reason is that the primitive function may be called directly from C code. Calls to the redefined function from Lisp will use the new definition, but calls from C code may still use the built-in definition. Therefore, we discourage redefinition of primitive functions.

The term function refers to all Emacs functions, whether written in Lisp or C. See Function Type, for information about the functions written in Lisp.

Primitive functions have no read syntax and print in hash notation with the name of the subroutine.

(symbol-function 'car)          ; Access the function cell
                                ;   of the symbol.
     ⇒ #<subr car>
(subrp (symbol-function 'car))  ; Is this a primitive function?
     ⇒ t                       ; Yes.

Next: Record Type, Previous: Primitive Function Type, Up: Programming Types   [Contents][Index]

2.4.16 Closure Function Type ¶

Closures are function objects produced when turning a function definition into a function value. Closures are used both for byte-compiled Lisp functions as well as for interpreted Lisp functions. Closures can be produced by byte-compiling Lisp code (see Byte Compilation) or simply by evaluating a lambda expression without compiling it, resulting in an interpreted function. Internally, a closure is much like a vector; however, the evaluator handles this data type specially when it appears in a function call. See Closure Function Objects.

The printed representation and read syntax for a byte-code function object is like that for a vector, with an additional ‘#’ before the opening ‘[’. When printed for human consumption, it is printed as a special kind of list with an additional ‘#f’ before the opening ‘(’.

Next: Type Descriptors, Previous: Closure Function Type, Up: Programming Types   [Contents][Index]

2.4.17 Record Type ¶

A record is much like a vector. However, the first element is used to hold its type as returned by type-of. The purpose of records is to allow programmers to create objects with new types that are not built into Emacs.

See Records, for functions that work with records.

Next: Type Specifiers, Previous: Record Type, Up: Programming Types   [Contents][Index]

2.4.18 Type Descriptors ¶

A type descriptor is a record which holds information about a type. The first slot in the record must be a symbol naming the type, and type-of relies on this to return the type of record objects. No other type descriptor slot is used by Emacs; they are free for use by Lisp extensions.

An example of a type descriptor is any instance of cl-structure-class.

Next: Autoload Type, Previous: Type Descriptors, Up: Programming Types   [Contents][Index]

2.4.19 Type Specifiers ¶

A type specifier is an expression that denotes a type. A type represents a set of possible values. Type specifiers can be classified into primitive types and compound types.

Type specifiers are used for several purposes, including: documenting function interfaces through declarations (see The declare Form), specifying structure slot types (see Structures in Common Lisp Extensions for GNU Emacs Lisp), performing type checks with cl-the (see Declarations in Common Lisp Extensions for GNU Emacs Lisp), and aiding the native compiler (see Compilation of Lisp to Native Code) in optimizing code generation and inferring function signatures.

Primitive type specifiers

Primitive types specifiers are the basic types (i.e. not composed by other type specifiers).

Built-in primitive types (like integer, float, string etc.) are listed in Type Hierarchy of Emacs Lisp Objects.

Compound type specifiers

Compound types serve the purpose of defining more complex or precise type specifications by combining or modifying simpler types.

List of compound type specifiers:

(or type-1 … type-n)

The or type specifier describes a type that satisfies at least one of the given types.

(and type-1 … type-n)

Similarly the and type specifier describes a type that satisfies all of the given types.

(not type)

The not type specifier defines any type except the specified one.

(member value-1 … value-n)

The member type specifier allows to specify a type that includes only the explicitly listed values.

(function (arg-1-type … arg-n-type) return-type) ¶

The function type specifier is used to describe the argument types and the return type of a function. Argument types can be interleaved with symbols &optional and &rest to match the function’s arguments (see Features of Argument Lists).

The following type specifier represents a function whose first parameter is of type symbol, the second optional parameter is of type float, and which returns an integer:

 (function (symbol &optional float) integer)

(integer lower-bound upper-bound)

The integer type specifier can also be used as a compound type specifier to define a subset of integer values by specifying a range. This allows to precisely control which integers are valid for a given type.

lower-bound is the minimum integer value in the range and upper-bound the maximum. You can use * instead of the lower or upper bound to indicate no limit.

The following represents all integers from -10 to 10:

(integer -10 10)

The following represents the single value of 10:

(integer 10 10)

The following represents all the integers from negative infinity to 10:

(integer * 10)

Next: Finalizer Type, Previous: Type Specifiers, Up: Programming Types   [Contents][Index]

2.4.20 Autoload Type ¶

An autoload object is a list whose first element is the symbol autoload. It is stored as the function definition of a symbol, where it serves as a placeholder for the real definition. The autoload object says that the real definition is found in a file of Lisp code that should be loaded when necessary. It contains the name of the file, plus some other information about the real definition.

After the file has been loaded, the symbol should have a new function definition that is not an autoload object. The new definition is then called as if it had been there to begin with. From the user’s point of view, the function call works as expected, using the function definition in the loaded file.

An autoload object is usually created with the function autoload, which stores the object in the function cell of a symbol. See Autoload, for more details.

Previous: Autoload Type, Up: Programming Types   [Contents][Index]

2.4.21 Finalizer Type ¶

A finalizer object helps Lisp code clean up after objects that are no longer needed. A finalizer holds a Lisp function object. When a finalizer object becomes unreachable after a garbage collection pass, Emacs calls the finalizer’s associated function object. When deciding whether a finalizer is reachable, Emacs does not count references from finalizer objects themselves, allowing you to use finalizers without having to worry about accidentally capturing references to finalized objects themselves.

Errors in finalizers are printed to *Messages*. Emacs runs a given finalizer object’s associated function exactly once, even if that function fails.

Function: make-finalizer function ¶

Make a finalizer that will run function. function will be called after garbage collection when the returned finalizer object becomes unreachable. If the finalizer object is reachable only through references from finalizer objects, it does not count as reachable for the purpose of deciding whether to run function. function will be run once per finalizer object.

Next: Marker Type, Up: Editing Types   [Contents][Index]

2.5.1 Buffer Type ¶

A buffer is an object that holds text that can be edited (see Buffers). Most buffers hold the contents of a disk file (see Files) so they can be edited, but some are used for other purposes. Most buffers are also meant to be seen by the user, and therefore displayed, at some time, in a window (see Windows). But a buffer need not be displayed in any window. Each buffer has a designated position called point (see Positions); most editing commands act on the contents of the current buffer in the neighborhood of point. At any time, one buffer is the current buffer.

The contents of a buffer are much like a string, but buffers are not used like strings in Emacs Lisp, and the available operations are different. For example, you can insert text efficiently into an existing buffer, altering the buffer’s contents, whereas inserting text into a string requires concatenating substrings, and the result is an entirely new string object.

Many of the standard Emacs functions manipulate or test the characters in the current buffer; a whole chapter in this manual is devoted to describing these functions (see Text).

Several other data structures are associated with each buffer:

• a local syntax table (see Syntax Tables);
• a local keymap (see Keymaps); and,
• a list of buffer-local variable bindings (see Buffer-Local Variables).
• overlays (see Overlays).
• text properties for the text in the buffer (see Text Properties).

The local keymap and variable list contain entries that individually override global bindings or values. These are used to customize the behavior of programs in different buffers, without actually changing the programs.

A buffer may be indirect, which means it shares the text of another buffer, but presents it differently. See Indirect Buffers.

Buffers have no read syntax. They print in hash notation, showing the buffer name.

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

Next: Window Type, Previous: Buffer Type, Up: Editing Types   [Contents][Index]

2.5.2 Marker Type ¶

A marker denotes a position in a specific buffer. Markers therefore have two components: one for the buffer, and one for the position. Changes in the buffer’s text automatically relocate the position value as necessary to ensure that the marker always points between the same two characters in the buffer.

Markers have no read syntax. They print in hash notation, giving the current character position and the name of the buffer.

(point-marker)
     ⇒ #<marker at 10779 in objects.texi>

See Markers, for information on how to test, create, copy, and move markers.

Next: Frame Type, Previous: Marker Type, Up: Editing Types   [Contents][Index]

2.5.3 Window Type ¶

A window describes the portion of the screen that Emacs uses to display buffers. Every live window (see Basic Concepts of Emacs Windows) has one associated buffer, whose contents appear in that window. By contrast, a given buffer may appear in one window, no window, or several windows. Windows are grouped on the screen into frames; each window belongs to one and only one frame. See Frame Type.

Though many windows may exist simultaneously, at any time one window is designated the selected window (see Selecting Windows). This is the window where the cursor is (usually) displayed when Emacs is ready for a command. The selected window usually displays the current buffer (see The Current Buffer), but this is not necessarily the case.

Windows have no read syntax. They print in hash notation, giving the window number and the name of the buffer being displayed. The window numbers exist to identify windows uniquely, since the buffer displayed in any given window can change frequently.

(selected-window)
     ⇒ #<window 1 on objects.texi>

See Windows, for a description of the functions that work on windows.

Next: Terminal Type, Previous: Window Type, Up: Editing Types   [Contents][Index]

2.5.4 Frame Type ¶

A frame is a screen area that contains one or more Emacs windows; we also use the term “frame” to refer to the Lisp object that Emacs uses to refer to the screen area.

Frames have no read syntax. They print in hash notation, giving the frame’s title, plus its address in core (useful to identify the frame uniquely).

(selected-frame)
     ⇒ #<frame emacs@psilocin.gnu.org 0xdac80>

See Frames, for a description of the functions that work on frames.

Next: Window Configuration Type, Previous: Frame Type, Up: Editing Types   [Contents][Index]

2.5.5 Terminal Type ¶

A terminal is a device capable of displaying one or more Emacs frames (see Frame Type).

Terminals have no read syntax. They print in hash notation giving the terminal’s ordinal number and its TTY device file name.

(get-device-terminal nil)
     ⇒ #<terminal 1 on /dev/tty>

Next: Frame Configuration Type, Previous: Terminal Type, Up: Editing Types   [Contents][Index]

2.5.6 Window Configuration Type ¶

A window configuration stores information about the positions, sizes, and contents of the windows in a frame, so you can recreate the same arrangement of windows later.

Window configurations do not have a read syntax; their print syntax looks like ‘#<window-configuration>’. See Window Configurations, for a description of several functions related to window configurations.

Next: Process Type, Previous: Window Configuration Type, Up: Editing Types   [Contents][Index]

2.5.7 Frame Configuration Type ¶

A frame configuration stores information about the positions, sizes, and contents of the windows in all frames. It is not a primitive type—it is actually a list whose CAR is frame-configuration and whose CDR is an alist. Each alist element describes one frame, which appears as the CAR of that element.

See Frame Configurations, for a description of several functions related to frame configurations.

Next: Thread Type, Previous: Frame Configuration Type, Up: Editing Types   [Contents][Index]

2.5.8 Process Type ¶

The word process usually means a running program. Emacs itself runs in a process of this sort. However, in Emacs Lisp, a process is a Lisp object that designates a subprocess created by the Emacs process. Programs such as shells, GDB, ftp, and compilers, running in subprocesses of Emacs, extend the capabilities of Emacs. An Emacs subprocess takes textual input from Emacs and returns textual output to Emacs for further manipulation. Emacs can also send signals to the subprocess.

Process objects have no read syntax. They print in hash notation, giving the name of the process:

(process-list)
     ⇒ (#<process shell>)

See Processes, for information about functions that create, delete, return information about, send input or signals to, and receive output from processes.

Next: Mutex Type, Previous: Process Type, Up: Editing Types   [Contents][Index]

2.5.9 Thread Type ¶

A thread in Emacs represents a separate thread of Emacs Lisp execution. It runs its own Lisp program, has its own current buffer, and can have subprocesses locked to it, i.e. subprocesses whose output only this thread can accept. See Threads.

Thread objects have no read syntax. They print in hash notation, giving the name of the thread (if it has been given a name) or its address in core:

(all-threads)
    ⇒ (#<thread 0176fc40>)

Next: Condition Variable Type, Previous: Thread Type, Up: Editing Types   [Contents][Index]

2.5.10 Mutex Type ¶

A mutex is an exclusive lock that threads can own and disown, in order to synchronize between them. See Mutexes.

Mutex objects have no read syntax. They print in hash notation, giving the name of the mutex (if it has been given a name) or its address in core:

(make-mutex "my-mutex")
    ⇒ #<mutex my-mutex>
(make-mutex)
    ⇒ #<mutex 01c7e4e0>

Next: Stream Type, Previous: Mutex Type, Up: Editing Types   [Contents][Index]

2.5.11 Condition Variable Type ¶

A condition variable is a device for a more complex thread synchronization than the one supported by a mutex. A thread can wait on a condition variable, to be woken up when some other thread notifies the condition.

Condition variable objects have no read syntax. They print in hash notation, giving the name of the condition variable (if it has been given a name) or its address in core:

(make-condition-variable (make-mutex))
    ⇒ #<condvar 01c45ae8>

Next: Keymap Type, Previous: Condition Variable Type, Up: Editing Types   [Contents][Index]

2.5.12 Stream Type ¶

A stream is an object that can be used as a source or sink for characters—either to supply characters for input or to accept them as output. Many different types can be used this way: markers, buffers, strings, and functions. Most often, input streams (character sources) obtain characters from the keyboard, a buffer, or a file, and output streams (character sinks) send characters to a buffer, such as a *Help* buffer, or to the echo area.

The object nil, in addition to its other meanings, may be used as a stream. It stands for the value of the variable standard-input or standard-output. Also, the object t as a stream specifies input using the minibuffer (see Minibuffers) or output in the echo area (see The Echo Area).

Streams have no special printed representation or read syntax, and print as whatever primitive type they are.

See Reading and Printing Lisp Objects, for a description of functions related to streams, including parsing and printing functions.

Next: Overlay Type, Previous: Stream Type, Up: Editing Types   [Contents][Index]

2.5.13 Keymap Type ¶

A keymap maps keys typed by the user to commands. This mapping controls how the user’s command input is executed. A keymap is actually a list whose CAR is the symbol keymap.

See Keymaps, for information about creating keymaps, handling prefix keys, local as well as global keymaps, and changing key bindings.

Next: Font Type, Previous: Keymap Type, Up: Editing Types   [Contents][Index]

2.5.14 Overlay Type ¶

An overlay specifies properties that apply to a part of a buffer. Each overlay applies to a specified range of the buffer, and contains a property list (a list whose elements are alternating property names and values). Overlay properties are used to present parts of the buffer temporarily in a different display style. Overlays have no read syntax, and print in hash notation, giving the buffer name and range of positions.

See Overlays, for information on how you can create and use overlays.

Next: Xwidget Type, Previous: Overlay Type, Up: Editing Types   [Contents][Index]

2.5.15 Font Type ¶

A font specifies how to display text on a graphical terminal. There are actually three separate font types—font objects, font specs, and font entities—each of which has slightly different properties. None of them have a read syntax; their print syntax looks like ‘#<font-object>’, ‘#<font-spec>’, and ‘#<font-entity>’ respectively. See Low-Level Font Representation, for a description of these Lisp objects.

Previous: Font Type, Up: Editing Types   [Contents][Index]

2.5.16 Xwidget Type ¶

An xwidget is a special display element, such as a web browser, that can be embedded inside a buffer. Each window that displays an xwidget will also have an xwidget view, which on X-Windows corresponds to a single X window used to display the widget.

Neither of these objects are readable; their print syntaxes look like ‘#<xwidget>’ and ‘#<xwidget-view>’, respectively. See Embedded Native Widgets, for a more detailed description of xwidgets.