From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros Date: Tue, 12 Apr 2022 22:25:43 +0300 Message-ID: <83k0bu3xzc.fsf@gnu.org> References: <164974332528.14217.12591424007013368601@vcs2.savannah.gnu.org> <20220412060205.8B446C01687@vcs2.savannah.gnu.org> <87wnfux0ok.fsf@yahoo.com> <8735iicfcd.fsf@melete.silentflame.com> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34282"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Sean Whitton Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Tue Apr 12 21:26:40 2022 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 1neM9w-0008kd-Jp for ged-emacs-devel@m.gmane-mx.org; Tue, 12 Apr 2022 21:26:40 +0200 Original-Received: from localhost ([::1]:47590 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1neM9v-0001MB-9e for ged-emacs-devel@m.gmane-mx.org; Tue, 12 Apr 2022 15:26:39 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:50398) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1neM8y-0000AZ-FI for emacs-devel@gnu.org; Tue, 12 Apr 2022 15:25:40 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:46794) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1neM8x-0004N5-D0; Tue, 12 Apr 2022 15:25:40 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=fTWaCN07uU1LUEpjYahqsQRMf5HpJYDOu6a/yb9FdXc=; b=J0AIJ0MhApuS mdYxqcJ/3kurokNrXxPDhyLKssqRgpQwdTcIK8jlGEgY+7Y/4bhrrxlTB/5eY0uB/qOlGnhkfZFDr Pmus5ThxC+PjylDbmDDT/h8CeF8S7Xdjjk9oflx+6krkC9olXpzHKTPblNE/GJ/6l/y7iZyUWYCpS VIrjLMEs8WFFODuEOyyJvHHCYuqKsuo7WQqD2UO62ZWTUAQ7hJJp1cuVKfg5gilgf6xMDennAn1Hk W4Y0M7buAshhAb4B+Ny/9B/KT5qRBMAO9xP0Xr9hxD/v6fhZveV7bCb3gqV1CnGJf3CITwMeh5nQK bc2/8UJoRdx5FxW0QiUJIQ==; Original-Received: from [87.69.77.57] (port=2150 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1neM8w-0000Ld-Rv; Tue, 12 Apr 2022 15:25:39 -0400 In-Reply-To: <8735iicfcd.fsf@melete.silentflame.com> (message from Sean Whitton on Tue, 12 Apr 2022 11:43:30 -0700) 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" Xref: news.gmane.io gmane.emacs.devel:288336 Archived-At: > From: Sean Whitton > Date: Tue, 12 Apr 2022 11:43:30 -0700 > > Here's my docs patch if anyone has any comments. Thanks for writing the documentation. > +@defmac cl-with-gensyms names body@dots{} Shouldn't @dots{} follow NAMES? There's just one BODY, but any number of NAMES, right? > +This macro expands to code that executes @var{body} with each of the > +variables in @var{names} bound to a fresh uninterned symbol or > +``gensym''. Instead of "or" I suggest to say "a.k.a.@: @dfn{gensym}" (and add a @cindex entry for "gensym", as usual with any term in @dfn). > +@defmac cl-once-only ((name form)@dots{}) body@dots{} > +This macro is primarily to help the macro programmer ensure that forms > +supplied by the user of the macro are evaluated just once by its > +expansion even though the result of evaluating the form is to occur > +more than once. Less often, this macro is used to ensure that forms > +supplied by the macro programmer are evaluated just once. > + > +Each @var{name} is a variable which can be used to refer to the result > +of evaluating @var{form} in @var{body}. @code{cl-once-only} binds > +each @var{name} to a fresh uninterned symbol during the evaluation of > +@var{body}. My recommendation is always to try to name parameters after their roles. In this case, I'd use VAR or VARIABLE instead of the less specific NAME. Then you could make the text shorter and thus clearer: Each @var{variable} can be used to refer to the result of evaluating @var{form} in @var{body}. @code{cl-once-only} binds each @var{variable} to a fresh uninterned symbol... (And why not use "gensym" instead of the wordier "uninterned symbol"? that's why you introduced that terminology, right?) > Then, @code{cl-once-only} wraps the final expansion in > +code to evaluate each @var{form} and bind it to the corresponding > +uninterned symbol. How can a form be bound to a symbol? > +In a call like @code{(my-list (pop foo) ...)} the intermediate binding ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Long stretches of @code which have embedded whitespace, like that one above, should be wrapped in @w{..}, to prevent them from being broken between two lines. Also, why a literal "..." instead of @dots{}? > ++++ > +** New macro-writing macros, 'cl-with-gensyms' and 'cl-once-only'. I suggest to add here a pointer to the node in the manual where they are described, since this entry tells nothing about that to someone who doesn't already know CL well enough. Thanks.