mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-04 08:47:11 +00:00
97 lines
3.2 KiB
Plaintext
97 lines
3.2 KiB
Plaintext
@c -*-texinfo-*-
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
|
@c Copyright (C) 2017--2020 Free Software Foundation, Inc.
|
|
@c See the file elisp.texi for copying conditions.
|
|
@node Records
|
|
@chapter Records
|
|
@cindex records
|
|
|
|
The purpose of records is to allow programmers to create objects
|
|
with new types that are not built into Emacs. They are used as the
|
|
underlying representation of @code{cl-defstruct} and @code{defclass}
|
|
instances.
|
|
|
|
Internally, a record object is much like a vector; its slots can be
|
|
accessed using @code{aref} and it can be copied using
|
|
@code{copy-sequence}. However, the first slot is used to hold its
|
|
type as returned by @code{type-of}. Also, in the current
|
|
implementation records can have at most 4096 slots, whereas vectors
|
|
can be much larger. Like arrays, records use zero-origin indexing:
|
|
the first slot has index 0.
|
|
|
|
The type slot should be a symbol or a type descriptor. If it's a
|
|
type descriptor, the symbol naming its type will be returned;
|
|
@ref{Type Descriptors}. Any other kind of object is returned as-is.
|
|
|
|
The printed representation of records is @samp{#s} followed by a
|
|
list specifying the contents. The first list element must be the
|
|
record type. The following elements are the record slots.
|
|
|
|
To avoid conflicts with other type names, Lisp programs that define
|
|
new types of records should normally use the naming conventions of the
|
|
package where these record types are introduced for the names of the
|
|
types. Note that the names of the types which could possibly conflict
|
|
might not be known at the time the package defining a record type is
|
|
loaded; they could be loaded at some future point in time.
|
|
|
|
A record is considered a constant for evaluation: the result of
|
|
evaluating it is the same record. This does not evaluate or even
|
|
examine the slots. @xref{Self-Evaluating Forms}.
|
|
|
|
@menu
|
|
* Record Functions:: Functions for records.
|
|
* Backward Compatibility:: Compatibility for cl-defstruct.
|
|
@end menu
|
|
|
|
@node Record Functions
|
|
@section Record Functions
|
|
|
|
@defun recordp object
|
|
This function returns @code{t} if @var{object} is a record.
|
|
|
|
@example
|
|
@group
|
|
(recordp #s(a))
|
|
@result{} t
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun record type &rest objects
|
|
This function creates and returns a record whose type is @var{type}
|
|
and remaining slots are the rest of the arguments, @var{objects}.
|
|
|
|
@example
|
|
@group
|
|
(record 'foo 23 [bar baz] "rats")
|
|
@result{} #s(foo 23 [bar baz] "rats")
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun make-record type length object
|
|
This function returns a new record with type @var{type} and
|
|
@var{length} more slots, each initialized to @var{object}.
|
|
|
|
@example
|
|
@group
|
|
(setq sleepy (make-record 'foo 9 'Z))
|
|
@result{} #s(foo Z Z Z Z Z Z Z Z Z)
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@node Backward Compatibility
|
|
@section Backward Compatibility
|
|
|
|
Code compiled with older versions of @code{cl-defstruct} that
|
|
doesn't use records may run into problems when used in a new Emacs.
|
|
To alleviate this, Emacs detects when an old @code{cl-defstruct} is
|
|
used, and enables a mode in which @code{type-of} handles old struct
|
|
objects as if they were records.
|
|
|
|
@defun cl-old-struct-compat-mode arg
|
|
If @var{arg} is positive, enable backward compatibility with old-style
|
|
structs.
|
|
@end defun
|