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

Previous Next

Full log

View this message in rfc822 format

From: "Yue Yi" <include_yy <at> qq.com>
To: "76555" <76555 <at> debbugs.gnu.org>
Subject: bug#76555: 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)]

Previous Next

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