From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stephen Gildea Newsgroups: gmane.emacs.devel Subject: Re: a property "definition-type" would help find macro-defined tests Date: Thu, 09 Jan 2025 20:47:28 -0800 Message-ID: <409838.1736484448@pental.sg.gildea.net> References: <86frls3265.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="39513"; mail-complaints-to="usenet@ciao.gmane.io" To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Fri Jan 10 05:48:40 2025 Return-path: Envelope-to: ged-emacs-devel@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 1tW6wn-000A7d-ML for ged-emacs-devel@m.gmane-mx.org; Fri, 10 Jan 2025 05:48:40 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tW6wD-0006bF-DN; Thu, 09 Jan 2025 23:48:01 -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 1tW6vv-0006aa-CZ for emacs-devel@gnu.org; Thu, 09 Jan 2025 23:47:44 -0500 Original-Received: from tigger.sg.gildea.net ([99.65.78.170] helo=tigger3.gildea.net) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tW6vs-00082u-0p for emacs-devel@gnu.org; Thu, 09 Jan 2025 23:47:42 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gildea.com; i=@gildea.com; q=dns/txt; s=2023b; t=1736484448; h=from : to : subject : in-reply-to : mime-version : content-type : date : message-id : from; bh=lzi7x69m8gnjCdTtpeN1ahZPPssozGVzxvmirrEtpYc=; b=ILWHeMkOHlzvZX9AygIqsCN9oXHFb0b/qVKJkyRmuScB+Di6SuAfph8sL74W6eZ7BuRWq cvcAU4PGdifcfEaldiPHNusOZuF+0rS+88unvF1wlaYJI6CFsm9EMsDBFkcUMwrXVOdRFtH wPUeaE9fOhQAMScn3aG8rLG2tOibbZ/qybBYiVswfOPvyUOlYjklWLKRaH9LrBmgh1EJLOV u+pPpypuV53j8JvReBjoGO0YGIXDImS32TAvpxrF6ZcWdJsDMJ7lFt8t7QajSEw8Mlso++p bUbHT6SzyPjCxuAHmDGrkjJupfv4dNDi/RaAdUk7B+rneGkSfUc+IihAs5kQ== Original-Received: from pental.sg.gildea.net (pental.wg.gildea.net [192.168.113.18]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "pental-mail", Issuer "gildea.net Mail Root CA" (verified OK)) by tigger3.gildea.net (Postfix) with ESMTPS id BC5D63E07DE for ; Thu, 9 Jan 2025 20:47:28 -0800 (PST) Original-Received: from pental.sg.gildea.net (localhost [127.0.0.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by pental.sg.gildea.net (Postfix) with ESMTPS id A4EA22BF7F3 for ; Thu, 9 Jan 2025 20:47:28 -0800 (PST) In-Reply-To: Message from eliz@gnu.org of 9 Jan 2025 08:57:06 +0200 <86frls3265.fsf@gnu.org> X-Mailer: MH-E 8.6+git; nmh 1.8+dev; Emacs 31.0.50 Received-SPF: pass client-ip=99.65.78.170; envelope-from=stepheng+emacs@gildea.com; helo=tigger3.gildea.net X-Spam_score_int: -2 X-Spam_score: -0.3 X-Spam_bar: / X-Spam_report: (-0.3 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, NULL_IN_BODY=1.596, PP_MIME_FAKE_ASCII_TEXT=0.241, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:327825 Archived-At: --=-=-= Content-Type: text/plain I have made the changes requested and one other: - added a NEWS entry - find-function-search-for-symbol doc string additions trimmed of detail that is available from the manual. - in the manual, added an index entry for the new property, definition-type, and for all the existing properties that did not have index entries (which was most of them). - in the code example, put each top-level form in @group. - new in this version of the patch: added a cross reference from where Coding Conventions discusses how to write macros that define functions. --=-=-= Content-Type: text/x-diff Content-Disposition: inline; filename=definition-type-2.patch Content-Description: new property definition-type, version 2 diff --git a/etc/NEWS b/etc/NEWS index 37e5669b139..50928cd9264 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1137,6 +1137,13 @@ It offers a more concise way to create a completion table with metadata. +++ ** 'all-completions' and 'unintern' no longer support old calling conventions. ++++ +** New property 'definition-type' used by find-function and friends. +Macros that define an object in a way makes the object's name and the +macro call site defining the object hard to associate can put the +property 'definition-type' on the object's name to provide instructions +for finding the definition. + * Changes in Emacs 31.1 on Non-Free Operating Systems diff --git a/lisp/emacs-lisp/find-func.el b/lisp/emacs-lisp/find-func.el index 0837b37023e..643b6aba2a6 100644 --- a/lisp/emacs-lisp/find-func.el +++ b/lisp/emacs-lisp/find-func.el @@ -400,9 +400,12 @@ find-function-search-for-symbol Visit the library in a buffer, and return a cons cell (BUFFER . POSITION), or just (BUFFER . nil) if the definition can't be found in the file. -If TYPE is nil, look for a function definition. -Otherwise, TYPE specifies the kind of definition, -and it is interpreted via `find-function-regexp-alist'. +If TYPE is nil, look for a function definition, +otherwise, TYPE specifies the kind of definition. +If SYMBOL has a property `definition-type', +the property value is used instead of TYPE. +TYPE is interpreted via `find-function-regexp-alist'. + The search is done in the source for library LIBRARY." (if (null library) (error "Don't know where `%s' is defined" symbol)) @@ -410,6 +413,8 @@ find-function-search-for-symbol ;; that defines something else. (while (and (symbolp symbol) (get symbol 'definition-name)) (setq symbol (get symbol 'definition-name))) + (setq type (or (get symbol 'definition-type) + type)) (if (string-match "\\`src/\\(.*\\.\\(c\\|m\\)\\)\\'" library) (find-function-C-source symbol (match-string 1 library) type) (when (string-match "\\.el\\(c\\)\\'" library) diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 24b4e892024..7990e2a8f75 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -510,35 +510,54 @@ Standard Properties @table @code @item :advertised-binding +@cindex @code{:advertised-binding} property This property value specifies the preferred key binding, when showing documentation, for the named function. @xref{Keys in Documentation}. @item char-table-extra-slots +@cindex @code{char-table-extra-slots} property The value, if non-@code{nil}, specifies the number of extra slots in the named char-table type. @xref{Char-Tables}. @item customized-face +@cindex @code{customized-face} property @itemx face-defface-spec +@cindex @code{face-defface-spec} property @itemx saved-face +@cindex @code{saved-face} property @itemx theme-face +@cindex @code{theme-face} property These properties are used to record a face's standard, saved, customized, and themed face specs. Do not set them directly; they are managed by @code{defface} and related functions. @xref{Defining Faces}. @item customized-value +@cindex @code{customized-value} property @itemx saved-value +@cindex @code{saved-value} property @itemx standard-value +@cindex @code{standard-value} property @itemx theme-value +@cindex @code{theme-value} property These properties are used to record a customizable variable's standard value, saved value, customized-but-unsaved value, and themed values. Do not set them directly; they are managed by @code{defcustom} and related functions. @xref{Variable Definitions}. @item definition-name -This property is used to find the definition of a symbol in the source -code, when it might be hard to find the definition by textual search -of the source file. For example, a @code{define-derived-mode} +@cindex @code{definition-name} property +@itemx definition-type +@cindex @code{definition-type} property +These properties help find the definition of a symbol in the source +code when it might be hard to find the definition by textual search +of the source file. +The Emacs Help commands such as @kbd{C-h f} (@pxref{Help,,, +emacs, The GNU Emacs Manual}) use these properties to show the definition +of a symbol via a button in the @file{*Help*} buffer where the +symbol's documentation is shown. + +For example, a @code{define-derived-mode} (@pxref{Derived Modes}) might define a mode-specific function or a variable implicitly; or your Lisp program might generate a run-time call to @code{defun} to define a function (@pxref{Defining @@ -547,43 +566,101 @@ Standard Properties be found by textual search and whose code defines the original symbol. In the example with @code{define-derived-mode}, the value of this property of the functions and variables it defines should be the mode -symbol. The Emacs Help commands such as @kbd{C-h f} (@pxref{Help,,, -emacs, The GNU Emacs Manual}) use this property to show the definition -of a symbol via a button in the @file{*Help*} buffer where the -symbol's documentation is shown. +symbol. + +In some cases, the definition cannot be found by looking for the +definition of another symbol. For example, a test file might use a +macro to generate calls to @code{ert-deftest} +(@pxref{,,,ert, ERT: Emacs Lisp Regression Testing}) where the code +is boiler plate and only varying data need to be passed in. +In such cases, the @code{definition-type} property of the symbol can +be a symbol that has an entry in @code{find-function-regexp-alist} +telling how to find the definition of symbols of this type. + +In the example of a macro defining calls to @code{ert-deftest}, +the macro could put the property @code{definition-type} on each +test defined. The file defining the macro would also define a +definition-finding function or regexp and add it to +@code{find-function-regexp-alist} after that variable is loaded. +Here is an example using a function to find the definition: + +@example +@group +(defmacro define-foo-test (data) + "Define a test of the foo system using DATA." + (declare (debug (&rest sexp))) + (let ((test-name (intern (concat ...)))) + `(progn + (put ',test-name 'definition-type 'foo-test-type) + (ert-deftest ,test-name () + ,(concat "Test foo with " ...) + ...)))) +@end group +@end example + +@example +@group +(defun foo-find-test-def-function (test-name) + "Search for the `define-foo-test' call defining TEST-NAME. +Return non-nil if the definition is found." + (save-match-data + (let ((regexp ...)) + (save-restriction + (widen) + (goto-char (point-min)) + (re-search-forward regexp nil t))))) +@end group +@end example + +@example +@group +(with-eval-after-load "find-func" + (add-to-list + 'find-function-regexp-alist + '(foo-test-type . foo-find-test-def-function))) +@end group +@end example @item disabled +@cindex @code{disabled} property If the value is non-@code{nil}, the named function is disabled