GNU bug report logs - #68370
30.0.50; pcase eieio, map, seq, and cl-struct constructs are not described in the manual

Previous Next

To reply to this bug, email your comments to 68370 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 30.0.50; pcase eieio, map, seq, and cl-struct constructs are not
 described in the manual
Date: Wed, 10 Jan 2024 12:46:26 +0000

Hello,

RMS recently pointed that `pcase' docstring describes map, seq, and
radix-tree-leaf constructs.

However, they are not documented in the 11.4.1 The ‘pcase’ macro section
of Elisp manual.

AFAIU, eieio, map, seq, cl-struct, and a number of other constructs
mentioned in the docstring are automatically added there by
`pcase-defmacro'.

I see no need to document specialized pcase constructs like
`eshell-index-range', but eieie, map, seq, and cl-struct appears to be
matching common Elisp data structures. I think that they should be
documented in the manual.

In GNU Emacs 30.0.50 (build 3, x86_64-pc-linux-gnu, GTK+ Version
 3.24.38, cairo version 1.18.0) of 2024-01-07 built on localhost
Repository revision: fa559d058d4d286201f785e5248bc609865bc3b6
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101009
System Description: Gentoo Linux

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Message #8 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Ihor Radchenko <yantar92 <at> posteo.net>, 68370 <at> debbugs.gnu.org
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct
 constructs are not described in the manual
Date: Wed, 10 Jan 2024 06:56:41 -0800

Ihor Radchenko <yantar92 <at> posteo.net> writes:

> RMS recently pointed that `pcase' docstring describes map, seq, and
> radix-tree-leaf constructs.
>
> However, they are not documented in the 11.4.1 The ‘pcase’ macro section
> of Elisp manual.
>
> AFAIU, eieio, map, seq, cl-struct, and a number of other constructs
> mentioned in the docstring are automatically added there by
> `pcase-defmacro'.
>
> I see no need to document specialized pcase constructs like
> `eshell-index-range', but eieie, map, seq, and cl-struct appears to be
> matching common Elisp data structures. I think that they should be
> documented in the manual.

Copying in Stefan Monnier.

Message #11 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: Ihor Radchenko <yantar92 <at> posteo.net>, 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct
 constructs are not described in the manual
Date: Wed, 10 Jan 2024 11:19:13 -0500

>> RMS recently pointed that `pcase' docstring describes map, seq, and
>> radix-tree-leaf constructs.
>>
>> However, they are not documented in the 11.4.1 The ‘pcase’ macro section
>> of Elisp manual.
>>
>> AFAIU, eieio, map, seq, cl-struct, and a number of other constructs
>> mentioned in the docstring are automatically added there by
>> `pcase-defmacro'.
>>
>> I see no need to document specialized pcase constructs like
>> `eshell-index-range', but eieie, map, seq, and cl-struct appears to be
>> matching common Elisp data structures. I think that they should be
>> documented in the manual.
>
> Copying in Stefan Monnier.

AFAIK these "belong" to `map.el`, `seq.el`, etc... so that's where they
should be documented.  The documentation for `pcase` could of course
include corresponding cross-references.


        Stefan

Message #14 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Stefan Kangas <stefankangas <at> gmail.com>, 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct
 constructs are not described in the manual
Date: Thu, 11 Jan 2024 12:44:48 +0000

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> AFAIK these "belong" to `map.el`, `seq.el`, etc... so that's where they
> should be documented.  The documentation for `pcase` could of course
> include corresponding cross-references.

Do you mean "6.1 Sequences" section of the manual? Or the source code?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Message #17 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: Ihor Radchenko <yantar92 <at> posteo.net>, 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct
 constructs are not described in the manual
Date: Thu, 11 Jan 2024 11:09:06 -0800

On 1/10/2024 4:46 AM, Ihor Radchenko wrote:
> I see no need to document specialized pcase constructs like
> `eshell-index-range'...
Indeed. If I could figure out a way to prevent that from being added to 
the 'pcase' docstring, I would. :) It's really just a utility function 
for Eshell so that it's easier to handle index ranges internally.

Message #22 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Ihor Radchenko <yantar92 <at> posteo.net>
Cc: Stefan Kangas <stefankangas <at> gmail.com>, 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct
 constructs are not described in the manual
Date: Thu, 11 Jan 2024 22:06:33 -0500

>> AFAIK these "belong" to `map.el`, `seq.el`, etc... so that's where they
>> should be documented.  The documentation for `pcase` could of course
>> include corresponding cross-references.
> Do you mean "6.1 Sequences" section of the manual?

I meant "where ever it's documented", so yes that sounds about right :-)

> Or the source code?

No, not that: we already have docstrings there, I think.


        Stefan

Message #25 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50;
 pcase eieio, map, seq, and cl-struct constructs are not described in
 the manual
Date: Thu, 11 Jan 2024 23:00:43 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > AFAIK these "belong" to `map.el`, `seq.el`, etc... so that's where they
  > should be documented.  The documentation for `pcase` could of course
  > include corresponding cross-references.

This suggests to me that there is no need for cond* to define how to
handle these.  It can be done by extensions for cond* also.

Thanks.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Message #28 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Stefan Kangas <stefankangas <at> gmail.com>, 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct
 constructs are not described in the manual
Date: Fri, 12 Jan 2024 12:47:42 +0000

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>>> AFAIK these "belong" to `map.el`, `seq.el`, etc... so that's where they
>>> should be documented.  The documentation for `pcase` could of course
>>> include corresponding cross-references.
>> Do you mean "6.1 Sequences" section of the manual?
>
> I meant "where ever it's documented", so yes that sounds about right :-)

This might be tricky in practice:

1. eieio is more or less clear - it is a separate manual
2. seq.el is documented in 6.1 section, which may be a problem - the
   very concept of pattern matching is only introduced in 11.4.1 (pcase)
   section. So, it might be confusing for the readers to see information
   about pattern matching so early in the manual.
3. map.el does not have any documentation in manual. It may mean that
   (map ..) pattern should not be documented. Or it may mean that we
   need to add a map.el section to the manual.
4. 11.4.1 The ‘pcase’ macro section already documents ‘(cl-type TYPE)’,
   but not (cl-struct TYPE &rest FIELDS). It will be awkward to document
   cl-struct pattern in CL manual, while leaving cl-type in the 11.4.1
   section of the Elisp manual.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Message #31 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Jim Porter <jporterbugs <at> gmail.com>
Cc: 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct
 constructs are not described in the manual
Date: Fri, 12 Jan 2024 23:07:23 +0000

Jim Porter <jporterbugs <at> gmail.com> writes:

> On 1/10/2024 4:46 AM, Ihor Radchenko wrote:
>> I see no need to document specialized pcase constructs like
>> `eshell-index-range'...
> Indeed. If I could figure out a way to prevent that from being added to 
> the 'pcase' docstring, I would. :) It's really just a utility function 
> for Eshell so that it's easier to handle index ranges internally.

I think that it might be something akin `rx-let', but binds the pcase
macros temporarily. Looking into `pcase-defun', I do not see anything
difficult in implementing an equivalent feature `pcase-let-defun'.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Message #34 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: yantar92 <at> posteo.net, monnier <at> iro.umontreal.ca, 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50;
 pcase eieio, map, seq, and cl-struct constructs are not described in
 the manual
Date: Fri, 12 Jan 2024 22:50:15 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > I see no need to document specialized pcase constructs like
  > > `eshell-index-range', but eieie, map, seq, and cl-struct appears to be
  > > matching common Elisp data structures. I think that they should be
  > > documented in the manual.

That makes sense to me.

However, what I'm actually asking for about these pcase constructs is
not any change in Emacs, simply for someone to explain to me what they
do so I can give cond* similar festures.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Message #37 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Ihor Radchenko <yantar92 <at> posteo.net>
Cc: 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50;
 pcase eieio, map, seq, and cl-struct constructs are not described in
 the manual
Date: Fri, 12 Jan 2024 22:54:28 -0500

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > 1. eieio is more or less clear - it is a separate manual

I don't think anything but eieio and its documentation needs to
describe how to use eieio.  I won't try to implement anything about
eieio in cond*.

If there is a general need for such a construct in cond*, it can
be added later.

  > 2. seq.el is documented in 6.1 section, which may be a problem - the
  >    very concept of pattern matching is only introduced in 11.4.1 (pcase)
  >    section. So, it might be confusing for the readers to see information
  >    about pattern matching so early in the manual.

Can someone please describe for me the construct used in pcase
for matching sequences -- tell me how to use it and what it does?
Then I could implement that facility in cond*.

  > 4. 11.4.1 The ‘pcase’ macro section already documents ‘(cl-type TYPE)’,
  >    but not (cl-struct TYPE &rest FIELDS). It will be awkward to document
  >    cl-struct pattern in CL manual, while leaving cl-type in the 11.4.1
  >    section of the Elisp manual.

I would like to implement matching of cl-structs in cond*.  But I have
never used cl-structs and I don't know how they are used.

Can someone tell me about the constructs for constructing a structure
of a specified type with specified field values?  Please tell me how
to use it and what it does.  Then I could implement that for cond*.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Message #40 received at 68370 <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: rms <at> gnu.org
Cc: Stefan Kangas <stefankangas <at> gmail.com>, monnier <at> iro.umontreal.ca,
 68370 <at> debbugs.gnu.org
Subject: Re: bug#68370: 30.0.50; pcase eieio, map, seq, and cl-struct
 constructs are not described in the manual
Date: Sat, 13 Jan 2024 13:31:34 +0000

Richard Stallman <rms <at> gnu.org> writes:

>   > > I see no need to document specialized pcase constructs like
>   > > `eshell-index-range', but eieie, map, seq, and cl-struct appears to be
>   > > matching common Elisp data structures. I think that they should be
>   > > documented in the manual.
>
> That makes sense to me.
>
> However, what I'm actually asking for about these pcase constructs is
> not any change in Emacs, simply for someone to explain to me what they
> do so I can give cond* similar festures.

My email is not an answer to your question. It is a bug report about
Elisp manual. I did not try to answer you - I myself is also not
familiar with these extra `pcase' constructs. I missed them because they
were not mentioned in the manual.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.