From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: [PATCH] Re: Make peg.el a built-in library? Date: Sun, 27 Nov 2022 10:57:51 +0200 Message-ID: <831qporcz4.fsf@gnu.org> References: <875yvtbbn3.fsf@ericabrahamsen.net> <877d07a16u.fsf@localhost> <87tu3asg2r.fsf@ericabrahamsen.net> <87edud25ov.fsf@localhost> <87a6511ku0.fsf@ericabrahamsen.net> <87wn85z0zl.fsf@ericabrahamsen.net> <87leobplpv.fsf_-_@ericabrahamsen.net> <87bkp7ct7f.fsf@localhost> <875yfe7ols.fsf@ericabrahamsen.net> <87a64pbwkl.fsf@localhost> <878rjxkw4j.fsf@ericabrahamsen.net> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="4609"; mail-complaints-to="usenet@ciao.gmane.io" Cc: yantar92@posteo.net, emacs-devel@gnu.org To: Eric Abrahamsen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Nov 27 09:58:27 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ozDUY-0000wg-CC for ged-emacs-devel@m.gmane-mx.org; Sun, 27 Nov 2022 09:58:26 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ozDTc-0000pi-Kr; Sun, 27 Nov 2022 03:57:28 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ozDTa-0000pK-M5 for emacs-devel@gnu.org; Sun, 27 Nov 2022 03:57:26 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ozDTZ-0005gN-Tw; Sun, 27 Nov 2022 03:57:25 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=oWf/xoiqRTqQPzRKMq5ucr1PQiVnGRZYP/fjPg7oBdc=; b=pwx0ZJFU1pEf YSXr0FiSdgM1XySIKQqKYsVSTpwHgl5DU4Zx8trGNX0gV/Hig6k8a/OOskLuf4CjVNE6S1GYfgblt HLE+dznT3jOUVzjz7xHhN1i/4sP1w4qWXiBQoognahLvIqjTNCpv8pUxFIaSMMiQ6yQyy2pN4/t4t hDdwVOUZ7xAaXLSROBjhoaj7CIC81Xnq1AvpZJxJO8uEBZ6JPPHoNqiJKyHasEMlrg9LSYmFqgS9W XL75jxem+itprKtOp+qnwA2BwPz/uJAh/FiFGZdk8qGBfYbME2SM9DsKIsG+kiZDJcOP9gx4yf7bk Ak6DxRF/v9OcN1mqAjfzfg==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ozDTY-00023a-Aa; Sun, 27 Nov 2022 03:57:24 -0500 In-Reply-To: <878rjxkw4j.fsf@ericabrahamsen.net> (message from Eric Abrahamsen on Sat, 26 Nov 2022 17:46:04 -0800) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:300620 Archived-At: > From: Eric Abrahamsen > Cc: emacs-devel@gnu.org > Date: Sat, 26 Nov 2022 17:46:04 -0800 > > Here's a new version, that I hope clarifies these questions (instead of > doing the opposite). Thanks, a few minor comments below. > Lastly, nobody with a maintainer's hat on has actually given the green > light on this, and I assume we'll want to hold off until the next > version of Emacs is released; anyway it would be good to know what > Eli/Lars think. I haven't done any NEWS additions or anything, either. What exactly are you asking about here? > @c -*-texinfo-*- > @c This is part of the GNU Emacs Lisp Reference Manual. This would mean a suitable change to elisp.texi at the least, and probably also to another file that is part of the ELisp reference manual sources? > A @acronym{PEG} parser is defined as a list of named rules, each of > which match text patterns, and/or contain references to other rules. ^^^^^ ^^^^^^^ "matches" and "contains", in singular. > Parsing is initiated with the function @code{peg-run} or the macro > @code{peg-parse}, and parses text after point in the current buffer, > using a given set of rules. This function and this macro need to be formally documented with @defun and @defmac, as we do elsewhere in the ELisp reference. > The definition of each rule is referred to as a @dfn{parsing > expression} (@acronym{PEX}), and can consist of a literal string, a Ideally, each @dfn in the manual should have a @cindex entry, because people are likely to look up these terms. > Or set as the value of a variable, and the variable used in a > combination of calls to @code{with-peg-rules} and @code{peg-run}, > where the ``entry-point'' rule is given explicitly: This sentence reads awkwardly, because it starts with "Or set". Suggest to rephrase: Alternatively, use a variable whose value is a grammar, and use it in a combination of calls to... > @example > (defvar number-grammar > '((number sign digit (* digit)) > (sign (or "+" "-" "")) > (digit [0-9]))) Btw, this begs a question: how come the value of the variable is a (quoted) list, but the value you pass to peg-parse in the previous example was not quoted? > By default, calls to @code{peg-run} or @code{peg-parse} produce no > output: parsing simply moves point. In order to return or otherwise > act upon parsed strings, rules can include @dfn{actions}, see > @xref{Parsing Actions} for more information. Again, a @cindex for "actions" is in order here. Also, @xref produces a Capitalized "See", so you want a @ref here, not @xref. And please always follow the closing brace of a cross-reference with a period or a comma, because some versions of Texinfo insist on that. (The only exception from this rule is @pxref inside parentheses.) > Individual rules can also be defined using a more @code{defun}-like > syntax, using the macro @code{define-peg-rule}: > > @example > (define-peg-rule digit () > [0-9]) > @end example define-peg-rule should be documented with a @defmac. > @node PEX Definitions > @section PEX Definitions There should be a @menu in the parent @chapter's node for all the child @section nodes. Otherwise, makeinfo will barf. > @item "abc" > A literal string. You don't mean "abc" literally here, do you? The correct way of expressing "a string" is @item @var{string} > @item (char C) > A single character, as an Elisp character literal. Likewise here: @item @var{C} A single character @var{C}, as a Lisp character literal. > @item (* E) > Zero or more of an expression, as the regexp ``*''. Matching is > always ``greedy''. Likewise. Basically, all the elements here are meta-syntactic variables: they stand for something else. The right markup for them is @var. Also, "zero or more of an expression" reads awkwardly. I don't even think I understand what you mean. And please quote regexps using @samp, not literal quotes (here and elsewhere). > @item (+ E) > One or more of an expression, as the regexp ``+''. Matching is always > ``greedy''. Likewise about "one or more of an expression". > @item (opt E) > Zero or one of an expression, as the regexp ``?''. Same. > @item (range A B) > The character range between A and B, as the regexp ``[A-B]''. It is better to use CH1 and CH2 instead of A and B. > @item [a-b "+*" ?x] > A character set, including ranges, literal characters, or strings of > characters. Same comment about a and b. > @vindex peg-char-classes > Named character classes include the following: Instead of listing them, just use a cross-reference to the node where classes are documented as part of regexp syntax. > The first action pushes the initial value of point to the stack. The > intervening @acronym{PEX} moves point over the next word. The second ^^ Two spaces there. > action pops the previous value from the stack (binding it to the > variable @code{start}), and uses that value to extract a substring > from the buffer and push it to the stack. This pattern is so common > that peg.el provides a shorthand function that does exactly the above, ^^^^^^ @file{peg.el}. Or maybe just @acronym{PEG}. > @item (substring E) > Match @acronym{PEX} E and push the matched string to the stack. Same comments here regarding @var markup of meta-syntactic variables. > @item (replace E "repl") > Match E and replaced the matched region with the string "repl". "repl" is not a literal string, it's a meta-syntactic variable, just like E. Finally, this needs a lot of index entries to make it a useful reference that is easily looked up for stuff. Thanks.