From unknown Fri Jun 20 07:17:47 2025 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-Mailer: MIME-tools 5.509 (Entity 5.509) Content-Type: text/plain; charset=utf-8 From: bug#62511 <62511@debbugs.gnu.org> To: bug#62511 <62511@debbugs.gnu.org> Subject: Status: [PATCH] docs: Add example clarifying how syntax-case renames symbols Reply-To: bug#62511 <62511@debbugs.gnu.org> Date: Fri, 20 Jun 2025 14:17:47 +0000 retitle 62511 [PATCH] docs: Add example clarifying how syntax-case renames = symbols reassign 62511 guile submitter 62511 "Elijah Harding" severity 62511 normal tag 62511 patch thanks From debbugs-submit-bounces@debbugs.gnu.org Tue Mar 28 21:37:43 2023 Received: (at submit) by debbugs.gnu.org; 29 Mar 2023 01:37:43 +0000 Received: from localhost ([127.0.0.1]:50991 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1phKkx-0002pF-8E for submit@debbugs.gnu.org; Tue, 28 Mar 2023 21:37:43 -0400 Received: from lists.gnu.org ([209.51.188.17]:50100) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1phIVS-0002aI-Hw for submit@debbugs.gnu.org; Tue, 28 Mar 2023 19:13:35 -0400 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 1phIVQ-0001kd-TX for bug-guile@gnu.org; Tue, 28 Mar 2023 19:13:34 -0400 Received: from wnew4-smtp.messagingengine.com ([64.147.123.18]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1phIVO-0001Mi-KR for bug-guile@gnu.org; Tue, 28 Mar 2023 19:13:32 -0400 Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailnew.west.internal (Postfix) with ESMTP id 12B962B068A2 for ; Tue, 28 Mar 2023 19:13:23 -0400 (EDT) Received: from imap44 ([10.202.2.94]) by compute4.internal (MEProxy); Tue, 28 Mar 2023 19:13:23 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=illucid.net; h= cc:content-type:content-type:date:date:from:from:in-reply-to :message-id:mime-version:reply-to:sender:subject:subject:to:to; s=fm1; t=1680045202; x=1680048802; bh=14Q7tPfnYPvCLKcxi3GKBaty7 yX9mh4TiZvht1ZdJDE=; b=Ih3tllf62cER/TYQ9DpQntApANstBRhUEHPdVtoQs Ta1VBc59suLSW1NS8x9l8mTup3DGeBwz7Rqpv0TJhupmp95sx0GgsibS4osd5WAu HMst2C3QL5bCuD64CczoHxwlaX/nMmN6no6K91hv++H9kbFw69taJ4Qlc6hAxwxw W7XQGdj29X7Fdj9g+Pe2W03W8Vlwz2qUCdT2dhBbP5g7lon33ZX51pDgEAj8Jm90 tCRhiveLBY1qy135hfOE1/XNm5ex4iiFuDursr5YyMGhW+MWZK4fKQovJftNCBko FVyPnYgOY7wM/v15KVNX9mKashCmNqVuL9mtcDsN+IHhQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:message-id :mime-version:reply-to:sender:subject:subject:to:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm2; t= 1680045202; x=1680048802; bh=14Q7tPfnYPvCLKcxi3GKBaty7yX9mh4TiZv ht1ZdJDE=; b=kA29O3koCD4SOr69feChqyagby0dmCGgHyoprWF0gIc+j3H7uTv C44Y8GjEnpLgelbwLlsJBxGpB08t3gTwaUPN272fALrUy2MEGR1JtIS/NZtzAdje mloc6fqbHHUo4xdj4KYywMRM7HORGHOoXAMB8KngjR19v+ZCenGD83gib7vRLJOl Z7wlSAAATGgiTK2iwUU3+yCjiyb9wmdtKOOd8XSBCVn5NdvBf0kn3YjyFSOW4ybD QpPD4XQIsGz0B61waEErarfDCGuV1p3B98Z7xMH3gC8QEvjaeyXxOV1qZcPU6Tba RRWEVVY63nUmzgbBCgpVr2hVxu6Ij6fWBoQ== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedrvdehhedgvddtucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefofgggkfffhffvufgtsehttdertd erredtnecuhfhrohhmpedfgfhlihhjrghhucfjrghrughinhhgfdcuoegvlhhisehilhhl uhgtihgurdhnvghtqeenucggtffrrghtthgvrhhnpeevgfdvvefgleehtdeggeehheekhe duheevvdeffeffueevudekkeekjefftdeiteenucevlhhushhtvghrufhiiigvpedtnecu rfgrrhgrmhepmhgrihhlfhhrohhmpegvlhhisehilhhluhgtihgurdhnvght X-ME-Proxy: Feedback-ID: i7f19465a:Fastmail Received: by mailuser.nyi.internal (Postfix, from userid 501) id 2D23E36A0080; Tue, 28 Mar 2023 19:13:22 -0400 (EDT) X-Mailer: MessagingEngine.com Webmail Interface User-Agent: Cyrus-JMAP/3.9.0-alpha0-237-g62623e8e3f-fm-20230327.001-g62623e8e Mime-Version: 1.0 Message-Id: <964025bb-345c-4738-b61b-b5b45fd104b3@app.fastmail.com> Date: Tue, 28 Mar 2023 23:12:56 +0000 From: "Elijah Harding" To: bug-guile@gnu.org Subject: [PATCH] docs: Add example clarifying how syntax-case renames symbols Content-Type: text/plain Received-SPF: pass client-ip=64.147.123.18; envelope-from=eli@illucid.net; helo=wnew4-smtp.messagingengine.com X-Spam_score_int: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 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, RCVD_IN_DNSWL_LOW=-0.7, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-Spam-Score: -1.4 (-) X-Debbugs-Envelope-To: submit X-Mailman-Approved-At: Tue, 28 Mar 2023 21:37:42 -0400 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.4 (--) I encountered these renamed symbols in the wild, and it took quite a while for me to figure out what was going on. I'm glad to have learned a lot about syntax-case in the process, all the way through to Primer for the Mildly Insane, but I think it would spare future learners some trouble to have an example of this behavior just so that they know what's going on when they run into it. I've kinda awkwardly shoved the example into the most relevant place in the manual, but I'm not sure that I'm happy with how it all flows, as I am kinda taking a tangent for the sake of exposing these ideas. The segue back is especially rough as I didn't want to cut the existing example, so there are now code blocks two serving the same purpose. Oh and I'm new to this Thx! * doc/ref/api-macros.texi (Why syntax-case?): Document symbol renaming more clearly. --- doc/ref/api-macros.texi | 89 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 84 insertions(+), 5 deletions(-) diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi index a353719cb..5777eda7b 100644 --- a/doc/ref/api-macros.texi +++ b/doc/ref/api-macros.texi @@ -630,6 +630,8 @@ To begin with, we should mention a solution that doesn't work: ((_ test then else) #'(let ((it test)) (if it then else)))))) +(aif 't it #f) +;; => Unbound variable: it @end example The reason that this doesn't work is that, by default, the expander will @@ -682,6 +684,8 @@ Here's another solution that doesn't work: (let ((it (datum->syntax x 'it))) #'(let ((it test)) (if it then else))))))) +(aif 't it #f) +;; => Unbound variable: it @end example The reason that this one doesn't work is that there are really two @@ -689,9 +693,85 @@ environments at work here -- the environment of pattern variables, as bound by @code{syntax-case}, and the environment of lexical variables, as bound by normal Scheme. The outer let form establishes a binding in the environment of lexical variables, but the inner let form is inside a -syntax form, where only pattern variables will be substituted. Here we -need to introduce a piece of the lexical environment into the pattern -variable environment, and we can do so using @code{syntax-case} itself: +syntax form, where only pattern variables will be substituted. + +We can observe this effect with a similar macro that calls @code{(define +it ...)} by examining the resulting binding, using @code{it-1} and +@code{it-2} to distinguish the pattern variable from the syntax that we +intend to bind it to. + +@example +(define-syntax set-it-to-test + (lambda (x) + (syntax-case x () + ((_) + (let ((it-1 (datum->syntax x 'it-2))) + #'(define it-1 'test)))))) +(set-it-to-test) + +;; This hasn't worked: +(module-bound? (current-module) 'it-2) +;; => #f + +;; And hasn't bound it-1: +(module-bound? (current-module) 'it-1) +;; => #f + +;; But if we search for bindings that resolves to 'test, +;; we see something strange: +(module-map (lambda (sym val) + (when (eq? (variable-ref val) 'test) + (display (cons sym val)))) + (current-module)) +@print{} (it-1-ee83545680dc7ed . #) +@end example + +We can now see that the pattern symbol @code{it-1} has not been substituted to +@code{it-2} by the lexical binding, because the resulting variable binding +still carries the prefix @code{it-1}. + +However @code{it-1} has not been bound either! This is because it has been +renamed by the implementation of @code{syntax-case}, producing the gensym +@code{it-1-ee83545680dc7ed}. This is done to preserve referential transparency, +distinguishing our use of symbols like @code{if}, @code{define}, and @code{it} +in the @code{syntax} forms of the transformer's definition from their use in the +context of the form under expansion. + +This is the same mechanism which would rename the let-bound @code{it} in our +first example to prevent the @var{then} and @var{else} expressions from +accessing its binding. These internally renamed symbols aren't usually visible +in eg. macroexpansions or @code{display}'d symbols, but can sometimes be +observed doing their behind-the-scenes work within the top-level bindings of a +module. + +What we need to do is introduce the new syntax created by @code{datum->syntax} +into the pattern variable environment, which we can do with @code{syntax-case} +itself. + +@example +(define-syntax set-it-to-test + (lambda (x) + (syntax-case x () + ((_) + (syntax-case (datum->syntax x 'it-2) () + (it-1 + #'(define it-1 'test))))))) +(set-it-to-test) +it-2 +=> test +@end example + +Note that by providing the template-id @code{x} we explicitly specify +@emph{which} binding of @code{it-2} the new @code{syntax} inside our pattern +variable @code{it-1} refers to, namely the binding within the context of the +form being manipulated by the transformer, and we clarify to Guile that no +distinction should be created between these two uses of @code{it-2}. If we +provide a template-id from another (or no) context, the implementation might +still rename our @emph{new} syntax to something like +@code{it-2-ee83545680dc7ed} to prevent what might appear to be unintended +variable capture. + +Returning to our previous, pragmatic example: @example ;; works, but is obtuse @@ -710,8 +790,7 @@ variable environment, and we can do so using @code{syntax-case} itself: @print{} 500 @end example -However there are easier ways to write this. @code{with-syntax} is often -convenient: +There are easier ways to write this. @code{with-syntax} is often convenient: @deffn {Syntax} with-syntax ((pat val) @dots{}) exp @dots{} Bind patterns @var{pat} from their corresponding values @var{val}, within the -- 2.39.2 From debbugs-submit-bounces@debbugs.gnu.org Tue Mar 28 21:43:57 2023 Received: (at 62511-done) by debbugs.gnu.org; 29 Mar 2023 01:43:57 +0000 Received: from localhost ([127.0.0.1]:51007 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1phKqz-0002z2-A3 for submit@debbugs.gnu.org; Tue, 28 Mar 2023 21:43:57 -0400 Received: from wnew1-smtp.messagingengine.com ([64.147.123.26]:50935) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1phKqx-0002yn-TI for 62511-done@debbugs.gnu.org; Tue, 28 Mar 2023 21:43:56 -0400 Received: from compute4.internal (compute4.nyi.internal [10.202.2.44]) by mailnew.west.internal (Postfix) with ESMTP id E12162B06891 for <62511-done@debbugs.gnu.org>; Tue, 28 Mar 2023 21:43:49 -0400 (EDT) Received: from imap44 ([10.202.2.94]) by compute4.internal (MEProxy); Tue, 28 Mar 2023 21:43:50 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=illucid.net; h= cc:content-type:content-type:date:date:from:from:in-reply-to :message-id:mime-version:reply-to:sender:subject:subject:to:to; s=fm1; t=1680054229; x=1680057829; bh=+QPjATsB6yq1Qd5u5qaBeXZz4 b4b0Yr7dPwQjoC/+Hc=; b=hZWWO7XkmZI39bboDHa9NQWvd7vr8dXWXGrFXwLIE nGC1R9jqCvFbgCArGvqDGkqLivz/c6Oa94pythbe2rUEFOJXkaxOcTwEWI4038sm FZE+hMbRJw2n+fHwBI9Ln65ivW/FiIhfyG1Uui3oPDBRLZy9W+kunREqSGMHM7CP RO4t+2GWReb4MH9mcZt0IB3sMGdeCqGPkc77J1OPQC6wqU133gBOeRwKZ52WsNXM rqFHJI/qEmaNVkN+FqH7MIMY+wrubjSJuxWkTBWUw+ZB0dMGoDGDBmGuiw7H+qOf 0kS7sf23G0PrRoKngq8PVFkOKUjOX55BJvibY1Q5SWXKg== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:message-id :mime-version:reply-to:sender:subject:subject:to:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm2; t= 1680054229; x=1680057829; bh=+QPjATsB6yq1Qd5u5qaBeXZz4b4b0Yr7dPw QjoC/+Hc=; b=b34CwWO+OkKXDyN+ElSorME/FsSjaGD/I5og7o6OXsLMeo45Ahs kJZc/FJU5237wgyF4/cO/6sK41sBVg8r+lYobQyps1QFnY1r29EcMB0oMhzzrRyj agZIYVzrMh6uyYFvSr9JUzJer0E7WF4ychm207JmTZdR+guaPjZQ9rj7KDp5J9ms lgxld2t8zbpJusmCECjcdcDFspJxTcjuX0IfO8PLNI/ExsGWc8emtBv7eFgHMZGx KcWaZf4ypMTPIaGt8lgonBp+7fswpFq8H4DwJ1+8/Xl739TwVjG98V4kIPDXnrJ4 1gIXdTkC5tkTS6SF47Tf9/KvyxPSIklfrNQ== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvhedrvdehhedghedtucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefofgggkfffhffvufgtsehttdertd erredtnecuhfhrohhmpedfgfhlihhjrghhucfjrghrughinhhgfdcuoegvlhhisehilhhl uhgtihgurdhnvghtqeenucggtffrrghtthgvrhhnpeevgfdvvefgleehtdeggeehheekhe duheevvdeffeffueevudekkeekjefftdeiteenucevlhhushhtvghrufhiiigvpedtnecu rfgrrhgrmhepmhgrihhlfhhrohhmpegvlhhisehilhhluhgtihgurdhnvght X-ME-Proxy: Feedback-ID: i7f19465a:Fastmail Received: by mailuser.nyi.internal (Postfix, from userid 501) id E1A5936A007B; Tue, 28 Mar 2023 21:43:48 -0400 (EDT) X-Mailer: MessagingEngine.com Webmail Interface User-Agent: Cyrus-JMAP/3.9.0-alpha0-237-g62623e8e3f-fm-20230327.001-g62623e8e Mime-Version: 1.0 Message-Id: Date: Wed, 29 Mar 2023 01:43:28 +0000 From: "Elijah Harding" To: 62511-done@debbugs.gnu.org Subject: RE: bug#62511: Acknowledgement ([PATCH] docs: Add example clarifying how syntax-case renames symbols) Content-Type: text/plain X-Spam-Score: -0.7 (/) X-Debbugs-Envelope-To: 62511-done X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.7 (-) Close as dupe From unknown Fri Jun 20 07:17:47 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Wed, 26 Apr 2023 11:24:05 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator