diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index f15b4c5e89d..079ea76156f 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -322,6 +322,15 @@ Name Help yet further information is often reachable by clicking or typing @key{RET} on emphasized parts of the text. +@cindex function type specifier + +The function type, if known, is expressed with a @dfn{function type +specifier} (@pxref{Type Specifiers,,,elisp, The Emacs Lisp Reference +Manual}), it will be specified if the type was manually declared by the +programmer or inferred by the compiler. Note that function type +inference works only when native compilation is enabled (@pxref{native +compilation,,, elisp, The Emacs Lisp Reference Manual}). + @vindex help-enable-symbol-autoload If you request help for an autoloaded function whose @code{autoload} form (@pxref{Autoload,,, elisp, The Emacs Lisp Reference Manual}) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index bf80a21ee9f..bb548441cbc 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2733,10 +2733,10 @@ Declare Form generation and for deriving more precisely the type of other functions without type declaration. -@var{type} is a type specifier in the form @w{@code{(function -(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. Argument types can be -interleaved with symbols @code{&optional} and @code{&rest} to match the -function's arguments (@pxref{Argument List}). +@var{type} is a @dfn{type specifier} (@pxref{Type Specifiers}) in the +form @w{@code{(function (ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}}. +Argument types can be interleaved with symbols @code{&optional} and +@code{&rest} to match the function's arguments (@pxref{Argument List}). @var{function} if present should be the name of function being defined. diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 34ea7cf4996..d847f438e0f 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -247,6 +247,7 @@ Programming Types * Closure Type:: A function written in Lisp. * Record Type:: Compound objects with programmer-defined types. * Type Descriptors:: Objects holding information about types. +* Type Specifiers:: Expressions which describe types. * Autoload Type:: A type used for automatically loading seldom-used functions. * Finalizer Type:: Runs code when no longer reachable. @@ -1499,6 +1500,92 @@ Type Descriptors An example of a type descriptor is any instance of @code{cl-structure-class}. +@node Type Specifiers +@subsection Type Specifiers +@cindex type specifier + +A type specifier is an expression that denotes a type. A type +represents a set of possible values. Type specifiers can be classified +in primitives and compounds. + +Type specifiers are in use for several purposes including: documenting +function interfaces through declaration (@pxref{Declare Form}), +specifying structure slot values (@pxref{Structures,,, cl, Common Lisp +Extensions for GNU Emacs Lisp}), type-checking through @code{cl-the} +(@pxref{Declarations,,, cl, Common Lisp Extensions for GNU Emacs Lisp}) +and others. + +@table @asis +@item Primitive type specifiers +Primitive types specifiers are the basic types (i.e.@: not composed by other +type specifiers). + +Built-in primitive types (like @code{integer}, @code{float}, +@code{string} etc) are listed in @ref{Type Hierarchy}. + +@item 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: + +@table @code +@item (or @var{type-1} .. @var{type-n}) +The @code{or} type specifier describes a type that satisfies at least +one of the given types. + +@item (and @var{type-1} .. @var{type-n}) +Similarly the @code{and} type specifier describes a type that satisfies +all the given types. + +@item (not @var{type}) +The @code{not} type specifier defines any type except the specified one. + +@item (member @var{value-1} .. @var{value-n}) +The @code{member} type specifier allows to specify a type that includes +only the explicitly listed values. + +@item (function (@var{arg-1-type} ... @var{arg-n-type}) @var{return-type}) +The @code{function} type specifier is used to describe the argument +types and return type of a function. Argument types can be interleaved +with symbols @code{&optional} and @code{&rest} to match the function's +arguments (@pxref{Argument List}). + +The following is to represent a function with: a first parameter of type +@code{symbol}, a second optional parameter of type @code{float} and +returning an @code{integer}: +@example +(function (symbol &optional float) integer) +@end example + +@item (integer @var{lower-bound} @var{upper-bound}) + +@code{integer} can be used as well as a compound type specifier to +define a subset of integers by specifying a range. This allows to +precisely control which integers are valid for a given type. + +@var{lower-bound} is the minimum integer value in the range and +@var{upper-bound} the maximum. It is possible to use @code{*} to +indicate no lower or uper limit. + +The following represents all integers from -10 to 10. +@example +(integer -10 10) +@end example + +The following represents 10. +@example +(integer 10 10) +@end example + +The following represents all integers from negative infinity to 10. +@example +(integer * 10) +@end example + +@end table +@end table + @node Autoload Type @subsection Autoload Type