doc/lispref/records.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Emacs Lisp Reference Manual.
   3 @c Copyright (C) 2017 Free Software
   4 @c Foundation, Inc.
   5 @c See the file elisp.texi for copying conditions.
   6 @node Records
   7 @chapter Records
   8 @cindex record
   9
  10   The purpose of records is to allow programmers to create objects
  11 with new types that are not built into Emacs.  They are used as the
  12 underlying representation of @code{cl-defstruct} and @code{defclass}
  13 instances.
  14
  15   Internally, a record object is much like a vector; its slots can be
  16 accessed using @code{aref} and it can be copied using
  17 @code{copy-sequence}.  However, the first slot is used to hold its
  18 type as returned by @code{type-of}.  Also, in the current
  19 implementation records can have at most 4096 slots, whereas vectors
  20 can be much larger.  Like arrays, records use zero-origin indexing:
  21 the first slot has index 0.
  22
  23   The type slot should be a symbol or a type descriptor.  If it's a
  24 type descriptor, the symbol naming its type will be returned;
  25 @ref{Type Descriptors}.  Any other kind of object is returned as-is.
  26
  27   The printed representation of records is @samp{#s} followed by a
  28 list specifying the contents.  The first list element must be the
  29 record type.  The following elements are the record slots.
  30
  31   A record is considered a constant for evaluation: the result of
  32 evaluating it is the same record.  This does not evaluate or even
  33 examine the slots.  @xref{Self-Evaluating Forms}.
  34
  35 @menu
  36 * Record Functions::        Functions for records.
  37 * Backward Compatibility::  Compatibility for cl-defstruct.
  38 @end menu
  39
  40 @node Record Functions
  41 @section Record Functions
  42
  43 @defun recordp object
  44 This function returns @code{t} if @var{object} is a record.
  45
  46 @example
  47 @group
  48 (recordp #s(a))
  49      @result{} t
  50 @end group
  51 @end example
  52 @end defun
  53
  54 @defun record type &rest objects
  55 This function creates and returns a record whose type is @var{type}
  56 and remaining slots are the rest of the arguments, @var{objects}.
  57
  58 @example
  59 @group
  60 (record 'foo 23 [bar baz] "rats")
  61      @result{} #s(foo 23 [bar baz] "rats")
  62 @end group
  63 @end example
  64 @end defun
  65
  66 @defun make-record type length object
  67 This function returns a new record with type @var{type} and
  68 @var{length} more slots, each initialized to @var{object}.
  69
  70 @example
  71 @group
  72 (setq sleepy (make-record 'foo 9 'Z))
  73      @result{} #s(foo Z Z Z Z Z Z Z Z Z)
  74 @end group
  75 @end example
  76 @end defun
  77
  78 @node Backward Compatibility
  79 @section Backward Compatibility
  80
  81   Code compiled with older versions of @code{cl-defstruct} that
  82 doesn't use records may run into problems when used in a new Emacs.
  83 To alleviate this, Emacs detects when an old @code{cl-defstruct} is
  84 used, and enables a mode in which @code{type-of} handles old struct
  85 objects as if they were records.
  86
  87 @defun cl-old-struct-compat-mode arg
  88 If @var{arg} is positive, enable backward compatibility with old-style
  89 structs.
  90 @end defun