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

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

[Ihor Radchenko]

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>

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

[Stefan Kangas]

Ihor Radchenko <yantar92@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.

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

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> 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

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

[Ihor Radchenko]

Stefan Monnier <monnier@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>

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

[Jim Porter]

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.

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

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> 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

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

[Richard Stallman]

[[[ 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)

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

[Ihor Radchenko]

Stefan Monnier <monnier@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>

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

[Ihor Radchenko]

Jim Porter <jporterbugs@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>

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

[Richard Stallman]

[[[ 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)

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

[Richard Stallman]

[[[ 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)

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

[Ihor Radchenko]

Richard Stallman <rms@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>