From 4753f3f0af33c5defe3a340f82265db6a6863030 Mon Sep 17 00:00:00 2001 From: Lars Brinkhoff Date: Wed, 5 Apr 2017 08:42:25 +0200 Subject: [PATCH] Update documentation for type semantics of records. * objects.texi (Record Type): improve description of what `type-of' returns for records. (Type Descriptors): new section. * elisp.texi: reference it. * records.texi (Records): reference it. Document behaviour when type slot is a record. * alloc.c (Fmake_record, Frecord): mention type desciptors. --- doc/lispref/elisp.texi | 1 + doc/lispref/objects.texi | 16 +++++++++++++++- doc/lispref/records.texi | 4 ++++ src/alloc.c | 10 ++++++---- 4 files changed, 26 insertions(+), 5 deletions(-) diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 3a348aae98e..bff3112d73b 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -316,6 +316,7 @@ Programming Types * Primitive Function Type:: A function written in C, callable from Lisp. * Byte-Code Type:: A function written in Lisp, then compiled. * Record Type:: Compound objects with programmer-defined types. +* Type Descriptors:: Objects holding information about types. * Autoload Type:: A type used for automatically loading seldom-used functions. * Finalizer Type:: Runs code when no longer reachable. diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 90cafbef642..cc9320987f2 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -156,6 +156,7 @@ latter are unique to Emacs Lisp. * Primitive Function Type:: A function written in C, callable from Lisp. * Byte-Code Type:: A function written in Lisp, then compiled. * Record Type:: Compound objects with programmer-defined types. +* Type Descriptors:: Objects holding information about types. * Autoload Type:: A type used for automatically loading seldom-used functions. * Finalizer Type:: Runs code when no longer reachable. @@ -1359,6 +1360,18 @@ types that are not built into Emacs. @xref{Records}, for functions that work with records. +@node Type Descriptors +@subsection Type Descriptors + + A @dfn{type decriptor} is a @code{record} which holds information +about a type. Slot 1 in the record must be a symbol naming the type. +@code{type-of} relies on this to return the type of @code{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 +@code{cl-structure-class}. + @node Autoload Type @subsection Autoload Type @@ -2037,7 +2050,8 @@ This function returns a symbol naming the primitive type of @code{marker}, @code{mutex}, @code{overlay}, @code{process}, @code{string}, @code{subr}, @code{symbol}, @code{thread}, @code{vector}, @code{window}, or @code{window-configuration}. -However, if @var{object} is a record, its first slot is returned. +However, if @var{object} is a record, the type specified by its first +slot is returned; @ref{Records}. @example (type-of 1) diff --git a/doc/lispref/records.texi b/doc/lispref/records.texi index a6c560cbcb9..a924bafbb96 100644 --- a/doc/lispref/records.texi +++ b/doc/lispref/records.texi @@ -19,6 +19,10 @@ 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. diff --git a/src/alloc.c b/src/alloc.c index a58824fb0f3..fad84b8a0b3 100644 --- a/src/alloc.c +++ b/src/alloc.c @@ -3411,8 +3411,9 @@ allocate_record (EMACS_INT count) DEFUN ("make-record", Fmake_record, Smake_record, 3, 3, 0, doc: /* Create a new record. -TYPE is its type as returned by `type-of'. SLOTS is the number of -non-type slots, each initialized to INIT. */) +TYPE is its type as returned by `type-of'; it should be either a +symbol or a type descriptor. SLOTS is the number of non-type slots, +each initialized to INIT. */) (Lisp_Object type, Lisp_Object slots, Lisp_Object init) { CHECK_NATNUM (slots); @@ -3427,8 +3428,9 @@ non-type slots, each initialized to INIT. */) DEFUN ("record", Frecord, Srecord, 1, MANY, 0, doc: /* Create a new record. -TYPE is its type as returned by `type-of'. SLOTS is used to -initialize the record slots with shallow copies of the arguments. +TYPE is its type as returned by `type-of'; it should be either a +symbol or a type descriptor. SLOTS is used to initialize the record +slots with shallow copies of the arguments. usage: (record TYPE &rest SLOTS) */) (ptrdiff_t nargs, Lisp_Object *args) { -- 2.39.2