From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Andrea Corallo Newsgroups: gmane.emacs.bugs Subject: bug#73626: 30.0.91; Type specifiers of functions Date: Wed, 13 Nov 2024 19:27:52 -0500 Message-ID: References: <86msjkxdf5.fsf@gnu.org> <86ikthcxjx.fsf@gnu.org> <86seskbi2q.fsf@gnu.org> <86zfm8n51g.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="17804"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 73626@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Nov 14 01:28:19 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tBNic-0004Sn-Tj for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 14 Nov 2024 01:28:19 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tBNiQ-00031n-Hw; Wed, 13 Nov 2024 19:28:06 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tBNiO-00031e-1o for bug-gnu-emacs@gnu.org; Wed, 13 Nov 2024 19:28:04 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tBNiM-0000iX-I8 for bug-gnu-emacs@gnu.org; Wed, 13 Nov 2024 19:28:03 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:Date:References:In-Reply-To:From:To:Subject; bh=VRw+wulyG30+vCyZoqHnKUR4xSVtlZgR4fcB/q1PK8U=; b=asKLPIleU7yrifLW1FJH2veZ6mq7v/eEQeY5SHXCBa195cFb/lA0DQO6NHX7OhwS8u5VP2jj54SVXA/yTOj02CR3O4xJlo4aDygHL2Z22uKv3FsGFxTCs3y5/G1/0U1HQDQ+xsp9T+UtWgsmQDRPsCG1YW2lEZzyZBp+HU/GaJ1W5Pz1gN6dMJJhixkdcy9pU1FgWIMju/TNjswoQIyoaz3KYIvpJ3SfyxdW5fAhf8Iw1KT5btvUGMyctACRUCwfpDWNWa2rzVvuAoG9N1I3nzjacTbPDN0kV78sp9OqbnyD+gnEqw8POg5sGwNXnlLT3ZSAutyNXBo/iICOOXvjpw==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1tBNiL-0003Vq-QA for bug-gnu-emacs@gnu.org; Wed, 13 Nov 2024 19:28:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Andrea Corallo Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 14 Nov 2024 00:28:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 73626 X-GNU-PR-Package: emacs Original-Received: via spool by 73626-submit@debbugs.gnu.org id=B73626.173154408013495 (code B ref 73626); Thu, 14 Nov 2024 00:28:01 +0000 Original-Received: (at 73626) by debbugs.gnu.org; 14 Nov 2024 00:28:00 +0000 Original-Received: from localhost ([127.0.0.1]:44169 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tBNiJ-0003VZ-Pl for submit@debbugs.gnu.org; Wed, 13 Nov 2024 19:28:00 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:58750) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tBNiI-0003VN-BE for 73626@debbugs.gnu.org; Wed, 13 Nov 2024 19:27:59 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tBNiD-0000hy-3T for 73626@debbugs.gnu.org; Wed, 13 Nov 2024 19:27:53 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-Version:Date:References:In-Reply-To:Subject:To: From; bh=VRw+wulyG30+vCyZoqHnKUR4xSVtlZgR4fcB/q1PK8U=; b=ALLkq3fvW3HBayFiFz1B plyqHVqzuXCJvwJTrUjgebAMGr403HtpO+3ag6WCb1VWDi525LMEtSEBKoMN0vWD7v+LzBHAaEHoM Ph7uts9BwpXxkSa2NpjzQBEuSy34ngjIkK+JRTVyY/ldowoTpeuxj3KJ3z8mNISFKdrMo/HOUOtcE 6sArVsfNFUbot5KVSDzRBCdhCxf2W8TXIsasqwZv20LOR74Ml0jByU8Zbceq5dJRuNR0W5cfzIWTx cJ4hhHK1UDgPNyeiwUi3CGzfJfDmpImleLRQOIDF+rx0I0WddBxo4H91nki5dIUQ6RmjNy4MTovw2 iZC0jKImifR1LQ==; Original-Received: from acorallo by fencepost.gnu.org with local (Exim 4.90_1) (envelope-from ) id 1tBNiC-00014L-CZ; Wed, 13 Nov 2024 19:27:52 -0500 In-Reply-To: (Andrea Corallo's message of "Tue, 12 Nov 2024 14:17:24 -0500") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:295298 Archived-At: --=-=-= Content-Type: text/plain Andrea Corallo writes: > Eli Zaretskii writes: > >>> Cc: 73626@debbugs.gnu.org >>> Date: Fri, 25 Oct 2024 13:19:41 +0300 >>> From: Eli Zaretskii >>> >>> > From: Andrea Corallo >>> > Cc: 73626@debbugs.gnu.org >>> > Date: Fri, 25 Oct 2024 05:35:30 -0400 >>> > >>> > Eli Zaretskii writes: >>> > >>> > >> > Bottom line: we decided that this information is important enough to >>> > >> > show it in the *Help* buffer, so we should explain its arcane parts to >>> > >> > make them useful. >>> > >> >>> > >> Agree. Is '(elisp)Top > Lisp Data Types' a reasonable place for that? >>> > > >>> > > Yes, I think so. >>> > >>> > Ok gonna work on this. >>> >>> Thanks! >> >> Did you have a chance to work on this? > > Not so far sorry, it's on top of my todo list tho. > > Andrea Okay this is what I'm working on. I felt the need to add a more general '(elisp)Type Specifiers' node as this was never documented and I think deserves its own space. I referenced it from '(emacs)Name Help' where I mentioned we report function type specifiers. Also I could reference it from '(elisp) Declare Form' so that the concept of type specifier (there already mentioned) is explained. There are some mentions of type specifiers in cl.texi which I guess I'll add some xref as well. WDYT? Andrea --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=ts.patch diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index f15b4c5e89d..0f85ff0c832 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -322,6 +322,13 @@ Name Help yet further information is often reachable by clicking or typing @key{RET} on emphasized parts of the text. +The function type, if known, is expressed with a 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..c6953cdd25a 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2733,7 +2733,7 @@ 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 +@var{type} is a @ref{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}). diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 34ea7cf4996..e402eed9437 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,99 @@ Type Descriptors An example of a type descriptor is any instance of @code{cl-structure-class}. +@node Type Specifiers +@subsection 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 in +primitives and composites. + +@subsubsection 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 @xref{Type Hierarchy}. + +@subsubsection Composite type specifiers. +Composite type specifiers allow the definition of complex types by +combining simpler types. + +List of composite composite type specifiers: + +@itemize @bullet +@item @code{or} + +The @code{or} type specifier describes a type that satisfies at least one of +the given types. +@example +(or integer float) +@end example + +@item @code{and} + +Similarly the @code{and} type specifier describes a type that satisfies +at all the given types. + +@item @code{not} + +The @code{not} type specifier defines any type except the specified one. +@example +(not number) +@end example + +@item @code{member} + +The @code{member} type specifier allows to specify a type that includes +only the explicitly listed values. +@example +(member foo bar) +@end example + +@item @code{function} + +The @code{function} type specifier in the form @w{@code{(function +(ARG-1-TYPE ... ARG-N-TYPE) RETURN-TYPE)}} 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 @code{integer} + +The @code{integer} type specifier is used to define a subset of integers +by specifying a range. This allows to precisely control which integers +are valid for a given type. + +The general form is: +@example +(integer lower-bound upper-bound) +@end example +Where @code{lower-bound} is the minimum integer value in the range and +@code{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 + @node Autoload Type @subsection Autoload Type --=-=-=--