From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: "Miguel V. S. Frasson" Newsgroups: gmane.emacs.bugs Subject: bug#34708: alist-get has unclear documentation Date: Sun, 3 Mar 2019 08:32:45 -0300 Message-ID: References: <87wolhr5k6.fsf@web.de> <87y35xdu4w.fsf@web.de> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="0000000000007bc5ea05832f0028" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="263700"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 34708@debbugs.gnu.org To: Michael Heerdegen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Mar 03 12:34:15 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1h0PNm-0016SY-BU for geb-bug-gnu-emacs@m.gmane.org; Sun, 03 Mar 2019 12:34:14 +0100 Original-Received: from localhost ([127.0.0.1]:37364 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h0PNl-0006cd-3a for geb-bug-gnu-emacs@m.gmane.org; Sun, 03 Mar 2019 06:34:13 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:46650) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h0PNc-0006cO-35 for bug-gnu-emacs@gnu.org; Sun, 03 Mar 2019 06:34:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h0PNb-0000kx-1b for bug-gnu-emacs@gnu.org; Sun, 03 Mar 2019 06:34:04 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:44561) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h0PNa-0000kb-Af for bug-gnu-emacs@gnu.org; Sun, 03 Mar 2019 06:34:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1h0PNa-0001Ij-6S for bug-gnu-emacs@gnu.org; Sun, 03 Mar 2019 06:34:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: "Miguel V. S. Frasson" Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 03 Mar 2019 11:34:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 34708 X-GNU-PR-Package: emacs Original-Received: via spool by 34708-submit@debbugs.gnu.org id=B34708.15516127874935 (code B ref 34708); Sun, 03 Mar 2019 11:34:02 +0000 Original-Received: (at 34708) by debbugs.gnu.org; 3 Mar 2019 11:33:07 +0000 Original-Received: from localhost ([127.0.0.1]:58105 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h0PMg-0001HW-Nm for submit@debbugs.gnu.org; Sun, 03 Mar 2019 06:33:07 -0500 Original-Received: from mail-it1-f178.google.com ([209.85.166.178]:38814) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1h0PMe-0001H2-8N for 34708@debbugs.gnu.org; Sun, 03 Mar 2019 06:33:04 -0500 Original-Received: by mail-it1-f178.google.com with SMTP id l66so3508040itg.3 for <34708@debbugs.gnu.org>; Sun, 03 Mar 2019 03:33:04 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=ml9NS7sFeEnhWwU5qEpw/NTSpjKEi8p/F94GtrGDg2Q=; b=eXzK1MU6pDiTzThfDv5wMzSgQpvKGNfefnTDz8kV0zd9BXX+tDJun2RIQsPyASQWYr 20K5KssdBdyFHey/tf0jxQaIHIpFsi5WZ95/GuxnXy5u8iOl6rFx0v7uGKjUFMJsOqTN oz33whlXiZahWQ8gqd8hxVDcqYNhwtNaITUd5n17jspHDRKqmOc0CY4N4N4EE6jzG4n1 2kacXTFnXc2s/ULojdd/qa2h7RpcIE9D4s9NwcTocHjxBS8VJLxCIrrKTYx36PhglrY/ aA3Kisf3B6YcJ7t/d7Cls+V5dsdJ1bVOGW3aRavVFfYF6YNVLO51ONZSUTEYFVeQvusz Mp9A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=ml9NS7sFeEnhWwU5qEpw/NTSpjKEi8p/F94GtrGDg2Q=; b=P1YmL9MEfz62PVp2o6VDMj8JaCur5AWcZh4F0swDwUxEwoRXlxgaKjPL0P/2zQLzpv z7/GHg2NMZIbT1BZq/TBl5G+2rS5+2iSfunqmKJE5QfcP0GbTz4KnbCIWVfGaWztSqQl 7C76rzLSw97217jV3PBXB8b3yPYj8eodtiYMawV0jLohd/yTRQHGPSrs0cDF/i5xBGID hDSAGIN3/oG+kahk0aQvdm17z2OFHuS6etD+gqdsxPNpAqQBFDGrejYFP+wQDWTmy/Fn xKqb+Ibc/lBcqeGEnrFpqrbaIE4XtV0lNkIIe/KSduxEtjoIGZLyi2QgTTwo845iFnBk j1uw== X-Gm-Message-State: APjAAAU2rP6weddYriwT8pRJSxgWSZrjHEOOeu0I+8v+2fF5eAWUjGxM ENMudvsZwjHURuf9un/pCH9OROogdJm/DlWWbLI= X-Google-Smtp-Source: APXvYqxXmsvccw6GKo8Gn+hA27rDyBHiuZpVt6pamHh39nH34mdj/1KX3nXavG8K3+OvPjM8I3JAi75hOWPZ3/W/wfc= X-Received: by 2002:a24:4e0f:: with SMTP id r15mr8054740ita.163.1551612778364; Sun, 03 Mar 2019 03:32:58 -0800 (PST) In-Reply-To: <87y35xdu4w.fsf@web.de> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 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.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:155991 Archived-At: --0000000000007bc5ea05832f0028 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi I think the sentence below is a good and short explanation for the doc-string. The return value can be conveniently used as a generalized variable (a place) to set the value associated with KEY in ALIST, like in the example (setf (alist-get key alist) new-value) Miguel Em s=C3=A1b, 2 de mar de 2019 15:10, Michael Heerdegen escreveu: > "Miguel V. S. Frasson" writes: > > > I can't imagine how to *set* anything with alist-get. It seams to me > > that it just use the value of ALIST for look up, so talk about > > generalized variables is meaningless to me here. > > You use it like this: say variable V is bound to an alist, then you can > do (setf (alist-get key V) value). After that, (alist-get key V) will > evaluate to VALUE, so you have "set" that place. In the general case, V > can also be a generalized variable, e.g. (car SOMETHING-ELSE). > > To replace the word "this" with something better is not so easy. We > could write "The name of this function can be used to build expressions > that can be used as a generalized variable", but I doubt it will make > things clearer for somebody not familiar with the concept of generalized > variables. Using this function name to build place expressions is not > different from using other function names that allow to be used for > generalized variables. > > I would rather go with an example, which I think is justified because > using this function name in place expressions is the canonical way to > modify alists and people need to use it (there is no `alist-put') no > matter if they are familiar with generalized variables. > > Michael. > > > --0000000000007bc5ea05832f0028 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi

I think t= he sentence below is a good and short explanation for the doc-string.
=

The return value can be conve= niently used as a generalized variable (a place) to set the value associate= d with KEY in ALIST, like in the example
=C2=A0(setf (alis= t-get key alist) new-value)

Miguel=C2=A0


Em s=C3=A1b, 2 de m= ar de 2019 15:10, Michael Heerdegen <michael_heerdegen@web.de> escreveu:
"Miguel V. S. Frasson" <mvsfrasson@gmail.co= m> writes:

> I can't imagine how to *set* anything with alist-get. It seams to = me
> that it just use the value of ALIST for look up, so talk about
> generalized variables is meaningless to me here.

You use it like this: say variable V is bound to an alist, then you can
do (setf (alist-get key V) value).=C2=A0 After that, (alist-get key V) will=
evaluate to VALUE, so you have "set" that place.=C2=A0 In the gen= eral case, V
can also be a generalized variable, e.g. (car SOMETHING-ELSE).

To replace the word "this" with something better is not so easy.= =C2=A0 We
could write "The name of this function can be used to build expression= s
that can be used as a generalized variable", but I doubt it will make<= br> things clearer for somebody not familiar with the concept of generalized variables.=C2=A0 Using this function name to build place expressions is not=
different from using other function names that allow to be used for
generalized variables.

I would rather go with an example, which I think is justified because
using this function name in place expressions is the canonical way to
modify alists and people need to use it (there is no `alist-put') no matter if they are familiar with generalized variables.

Michael.


--0000000000007bc5ea05832f0028--