GNU bug report logs - #76555
30.1; PEG's doc needs some correction

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 76555 in the body.
You can then email your comments to 76555 AT debbugs.gnu.org in the normal way.

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

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

From: "Yue Yi" <include_yy <at> qq.com>
To: "bug-gnu-emacs" <bug-gnu-emacs <at> gnu.org>
Subject: 30.1; PEG's doc needs some correction
Date: Tue, 25 Feb 2025 22:52:22 +0800

[Message part 1 (text/plain, inline)]

Hello Emacs, As we know, Emacs 30 introduced a PEG implementation, peg.el. I found that the following code doesn't work properly when reading the PEG documentation with folks: -------------- code from lispref/peg.texi ------------------------- (define-peg-rule digit ()   [0-9]) (define-peg-ruleset number-grammar         '((number sign digit (* digit))           digit  ;; A reference to the definition above.           (sign (or "+" "-" "")))) ------------------------------------------------------------------- We noticed that the correct usage of this macro is provided in peg.el. --------------code from peg.el ------------------------------------ ;;;; Named rulesets: ;; ;; You can define a set of rules for later use with: ;; ;;     (define-peg-ruleset myrules ;;       (sign  () (or "+" "-" "")) ;;       (digit () [0-9]) ;;       (nat   () digit (* digit)) ;;       (int   () sign digit (* digit)) ;;       (float () int "." nat)) ------------------------------------------------------------------- Perhaps we can correct the errors in the documentation through a simple replacement.  Regards, Yue Yi

[Message part 2 (text/html, inline)]

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

From: "Yue Yi" <include_yy <at> qq.com>
To: "76555" <76555 <at> debbugs.gnu.org>
Subject: 30.1; PEG's doc needs some correction
Date: Wed, 26 Feb 2025 00:36:49 +0800

[Message part 1 (text/plain, inline)]

BTW, could indent of define-peg-rule be changed from 1 to 2: ------------------------------------------------------------ (defmacro define-peg-rule (name args &rest pexs)   "Define PEG rule NAME as equivalent to PEXS. The PEG expressions in PEXS are implicitly combined with the sequencing `and' operator of PEG grammars."   (declare (indent 1))                   ^^^ to 2 ------------------------------------------------------------ Currently the indentation of define-peg-rule looks strange: ------------------------------------------------------------ (define-peg-rule t--comment () 		 hello 		 world 		 ...) ------------------------------------------------------------ By using (setf (get 'define-peg-rule 'lisp-indent-function) 2), It looks better: ------------------------------------------------------------ (define-peg-rule t--comment ()   hello   world   ...) ------------------------------------------------------------

[Message part 2 (text/html, inline)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Yue Yi" <include_yy <at> qq.com>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 76555 <at> debbugs.gnu.org
Subject: Re: bug#76555: 30.1; PEG's doc needs some correction
Date: Tue, 25 Feb 2025 19:08:02 +0200

> Date: Tue, 25 Feb 2025 22:52:22 +0800
> From:  "Yue Yi" via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> As we know, Emacs 30 introduced a PEG implementation, peg.el. I found
> that the following code doesn't work properly when reading the PEG
> documentation with folks:
> 
> -------------- code from lispref/peg.texi -------------------------
> (define-peg-rule digit ()
>   [0-9])
> (define-peg-ruleset number-grammar
>         '((number sign digit (* digit))
>           digit  ;; A reference to the definition above.
>           (sign (or "+" "-" ""))))
> -------------------------------------------------------------------
> 
> We noticed that the correct usage of this macro is provided in peg.el.
> 
> --------------code from peg.el ------------------------------------
> ;;;; Named rulesets:
> ;;
> ;; You can define a set of rules for later use with:
> ;;
> ;;     (define-peg-ruleset myrules
> ;;       (sign  () (or "+" "-" ""))
> ;;       (digit () [0-9])
> ;;       (nat   () digit (* digit))
> ;;       (int   () sign digit (* digit))
> ;;       (float () int "." nat))
> -------------------------------------------------------------------
> 
> Perhaps we can correct the errors in the documentation through a simple
> replacement. 

Stefan, could you please look into this?

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eric Abrahamsen <eric <at> ericabrahamsen.net>
Cc: 76555 <at> debbugs.gnu.org, Yue Yi <include_yy <at> qq.com>
Subject: Re: bug#76555: 30.1; PEG's doc needs some correction
Date: Tue, 25 Feb 2025 13:14:18 -0500

>> As we know, Emacs 30 introduced a PEG implementation, peg.el. I found
>> that the following code doesn't work properly when reading the PEG
>> documentation with folks:
>> -------------- code from lispref/peg.texi -------------------------
>> (define-peg-rule digit ()
>>   [0-9])
>> (define-peg-ruleset number-grammar
>>         '((number sign digit (* digit))
>>           digit  ;; A reference to the definition above.
>>           (sign (or "+" "-" ""))))
>> -------------------------------------------------------------------

Eric, where does this "reference" line come from?
I don't think we've ever supported such a thing, nor needed it.
Did you mean something like what I have in the patch below?


        Stefan


diff --git a/doc/lispref/peg.texi b/doc/lispref/peg.texi
index 80e2581e7bb..e03ec57a457 100644
--- a/doc/lispref/peg.texi
+++ b/doc/lispref/peg.texi
@@ -141,8 +141,8 @@ Parsing Expression Grammars
 @example
 @group
 (define-peg-ruleset number-grammar
+        ;; `digit' here references the definition above.
         '((number sign digit (* digit))
-          digit  ;; A reference to the definition above.
           (sign (or "+" "-" ""))))
 @end group
 @end example

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

From: "Yue Yi" <include_yy <at> qq.com>
To: "76555" <76555 <at> debbugs.gnu.org>
Subject: 30.1; PEG's doc needs some correction
Date: Wed, 26 Feb 2025 22:09:19 +0800

[Message part 1 (text/plain, inline)]

BTW^2, according to the comments, the documentation for `peg-parse' may need further improvement. The Emacs Lisp Manual Chapter 37: Parsing Expression Grammars says that: -------------quote start-------------------------------------- The `peg-parse' macro is the simplest:  -- Macro: peg-parse &rest pexs      Match PEXS at point.      (peg-parse        (number sign digit (* digit))        (sign   (or "+" "-" ""))        (digit  [0-9])) [...] The `peg-parse' example above expands to a set of calls to these functions, and could be written in full as:      (with-peg-rules          ((number sign digit (* digit))           (sign   (or "+" "-" ""))           (digit  [0-9]))        (peg-run (peg number))) This approach allows more explicit control over the "entry-point" of parsing, and allows the combination of rules from different sources. -------------quote end----------------------------------------- According to this documentation, `peg-parse' is a simplified form of the combination of `with-peg-rules' and `peg-run'. However, based on the docstring and implementation comments of `peg-parse', there is another way of usage for `peg-parse': ---------------------peg.el------------------------------------ [line 100] ;; and later refer to it: ;; ;;     (with-peg-rules ;;         (myrules ;;          (complex float "+i" float)) ;;       ... (peg-parse nat "," nat "," complex) ...) [line 220] ;; Rules can take arguments and those arguments can themselves be PEGs. ;; For example: ;; ;;     (define-peg-rule 2-or-more (peg) ;;       (funcall peg) ;;       (funcall peg) ;;       (* (funcall peg))) ;; ;;     ... (peg-parse ;;          ... ;;          (2-or-more (peg foo)) ;;          ... ;;          (2-or-more (peg bar)) ;;          ...) [line 313] ;; Sometimes (with-peg-rules ... (peg-run (peg ...))) is too ;; long-winded for the task at hand, so `peg-parse' comes in handy. (defmacro peg-parse (&rest pexs)   "Match PEXS at point. PEXS is a sequence of PEG expressions, implicitly combined with `and'. Returns STACK if the match succeed and signals an error on failure, moving point along the way." -------------------end------------------------------------------ According to the comment at line 100, we know that `peg-parse' can also be used to combine (AND) multiple PEXes, rather than expanding (EXPAND) into `with-peg-rules'. The comment at line 220 demonstrates this (AND) usage with a rule that takes parameters. Line 313, where `peg-parse' is defined, explains the EXPAND usage in the comment above it, while its docstring explains the AND usage. According to the implementation of `peg-parse', the specific method used depends on its first argument (if it is a list that meets the conditions, the EXPAND method is used). However, people like me, who have seen the example at line 220, might write code like this (One might think that `peg-parse' would help us omit the outermost peg.) and get an error: (define-peg-rule minifycss--comment ()   "/*" (* (not "*/") (any)) "*/") (define-peg-rule two (x) (funcall x) (funcall x)) (with-temp-buffer   (insert "/* *//**/")   (goto-char (point-min))   (peg-parse (two (peg minifycss--comment))))) After some thought and reading the implementation, one might think of adding a symbol, or using an inconsequential value in the position of the first element: (with-temp-buffer   (insert "/* *//**/")   (goto-char (point-min))   (peg-parse (_ (two (peg minifycss--comment))))) ;; OR (with-temp-buffer   (insert "/* *//**/")   (goto-char (point-min))   (peg-parse "" (two (peg minifycss--comment)))) To summarize, I think the info documentation only introduces one usage of `peg-parse', while the docstring of `peg-parse' describes another. Combined with the comments in peg.el, this could lead to confusion for users. Please consider clearly explaining the differences between the two usages in both the documentation and the docstring, or perhaps suggest another better approach? Regards

[Message part 2 (text/html, inline)]

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Eric Abrahamsen <eric <at> ericabrahamsen.net>, 76555 <at> debbugs.gnu.org,
 Yue Yi <include_yy <at> qq.com>
Subject: Re: bug#76555: 30.1; PEG's doc needs some correction
Date: Tue, 4 Mar 2025 02:37:04 +0000

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

>>> As we know, Emacs 30 introduced a PEG implementation, peg.el. I found
>>> that the following code doesn't work properly when reading the PEG
>>> documentation with folks:
>>> -------------- code from lispref/peg.texi -------------------------
>>> (define-peg-rule digit ()
>>>   [0-9])
>>> (define-peg-ruleset number-grammar
>>>         '((number sign digit (* digit))
>>>           digit  ;; A reference to the definition above.
>>>           (sign (or "+" "-" ""))))
>>> -------------------------------------------------------------------
>
> Eric, where does this "reference" line come from?
> I don't think we've ever supported such a thing, nor needed it.
> Did you mean something like what I have in the patch below?

Ping, Eric, WDYT?  Can we install the below change?

> diff --git a/doc/lispref/peg.texi b/doc/lispref/peg.texi
> index 80e2581e7bb..e03ec57a457 100644
> --- a/doc/lispref/peg.texi
> +++ b/doc/lispref/peg.texi
> @@ -141,8 +141,8 @@ Parsing Expression Grammars
>  @example
>  @group
>  (define-peg-ruleset number-grammar
> +        ;; `digit' here references the definition above.
>          '((number sign digit (* digit))
> -          digit  ;; A reference to the definition above.
>            (sign (or "+" "-" ""))))
>  @end group
>  @end example

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

From: "Yue Yi" <include_yy <at> qq.com>
To: "Stefan Kangas" <stefankangas <at> gmail.com>,
 "Stefan Monnier" <monnier <at> iro.umontreal.ca>
Cc: Eric Abrahamsen <eric <at> ericabrahamsen.net>,
 76555 <76555 <at> debbugs.gnu.org>
Subject: Re: bug#76555: 30.1; PEG's doc needs some correction
Date: Wed, 19 Mar 2025 00:01:30 +0800

[Message part 1 (text/plain, inline)]

Stefan Kangas writes: > Ping, Eric, WDYT?  Can we install the below change? >  > > diff --git a/doc/lispref/peg.texi b/doc/lispref/peg.texi > > index 80e2581e7bb..e03ec57a457 100644 > > --- a/doc/lispref/peg.texi > > +++ b/doc/lispref/peg.texi > > @@ -141,8 +141,8 @@ Parsing Expression Grammars > >  @example > >  @group > >  (define-peg-ruleset number-grammar > > +        ;; `digit' here references the definition above. > >          '((number sign digit (* digit)) > > -          digit  ;; A reference to the definition above. > >            (sign (or "+" "-" "")))) > >  @end group > >  @end example The example in peg.texi is incorrect, and we should not modify it this way. Refer to peg.el for the correct usage: @@ -141,9 +141,9 @@ Parsing Expression Grammars  @example  @group  (define-peg-ruleset number-grammar -        '((number sign digit (* digit)) -          digit  ;; A reference to the definition above. -          (sign (or "+" "-" "")))) +  (number () sign digit (* digit)) +  (digit () [0-9]) +  (sign () (or "+" "-" "")))  @end group  @end example BTW, as I mentioned last month, the indentation of `define-peg-rule' has an issue. I'm not very familiar with the history of peg.el, but could it be that the indentation rule was forgotten to be updated after introducing the parameter? Please consider fixing it. I believe the documentation of `peg-parse' may contain some potentially misleading parts. If needed, I can provide a simple patch.

[Message part 2 (text/html, inline)]

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Yue Yi" <include_yy <at> qq.com>
Cc: Eric Abrahamsen <eric <at> ericabrahamsen.net>, 76555 <76555 <at> debbugs.gnu.org>,
 Stefan Kangas <stefankangas <at> gmail.com>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#76555: 30.1; PEG's doc needs some correction
Date: Tue, 25 Mar 2025 22:24:18 -0400

OK, I think I managed to push a proper fix to `emacs-30`, tho
very laboriously.  Clearly lack of sleep does not impact my
cognitive abilities.


        Stefan

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

From: "Yue Yi" <include_yy <at> qq.com>
To: "Stefan Monnier" <monnier <at> iro.umontreal.ca>
Cc: Eric Abrahamsen <eric <at> ericabrahamsen.net>,
 76555 <76555 <at> debbugs.gnu.org>,
 Stefan Kangas <stefankangas <at> gmail.com>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#76555: 30.1; PEG's doc needs some correction
Date: Thu, 27 Mar 2025 08:46:35 +0800

[Message part 1 (text/plain, inline)]

> OK, I think I managed to push a proper fix to `emacs-30`, tho > very laboriously.  Clearly lack of sleep does not impact my > cognitive abilities. Thanks, three commits :p

[Message part 2 (text/html, inline)]

Message #39 received at 76555-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Yue Yi" <include_yy <at> qq.com>
Cc: Eric Abrahamsen <eric <at> ericabrahamsen.net>,
 76555 <76555-done <at> debbugs.gnu.org>, Stefan Kangas <stefankangas <at> gmail.com>
Subject: Re: bug#76555: 30.1; PEG's doc needs some correction
Date: Wed, 26 Mar 2025 21:06:31 -0400

> Thanks, three commits :p

And that's because I caught a first problem before the first push!
Otherwise it would have been 4 commits!  <eye-roll>
I really outdid myself.


        Stefan

Previous Next

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