From: Eric Abrahamsen <eric@ericabrahamsen.net>
To: emacs-devel@gnu.org
Cc: Michael Heerdegen <michael_heerdegen@web.de>
Subject: Re: Make peg.el a built-in library?
Date: Sat, 09 Oct 2021 09:47:44 -0700 [thread overview]
Message-ID: <874k9qxhzj.fsf@ericabrahamsen.net> (raw)
In-Reply-To: jwv35paxsur.fsf-monnier+emacs@gnu.org
[-- Attachment #1: Type: text/plain, Size: 456 bytes --]
Stefan Monnier <monnier@iro.umontreal.ca> writes:
>> (1) Can we improve the introduction in the file header a bit? I would
>> add a link to the wikipedia page:
>>
>> https://en.wikipedia.org/wiki/Parsing_expression_grammar
>>
>> it explains some background.
>
> I can't speak for Helmut, but I think you should feel free to make such
> a change, yes.
I've still got this documentation patch I haven't applied, I can just
add that link to this patch?
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: peg-doc-patch.diff --]
[-- Type: text/x-patch, Size: 4172 bytes --]
diff --git a/peg.el b/peg.el
index d71c707dc0..0e4221eeb7 100644
--- a/peg.el
+++ b/peg.el
@@ -79,17 +79,69 @@
;; Beginning-of-Symbol (bos)
;; End-of-Symbol (eos)
;;
-;; PEXs also support parsing actions, i.e. Lisp snippets which
-;; are executed when a pex matches. This can be used to construct
-;; syntax trees or for similar tasks. Actions are written as
+;; Rules can refer to other rules, and a grammar is often structured
+;; as a tree, with a root rule referring to one or more "branch
+;; rules", all the way down to the "leaf rules" that deal with actual
+;; buffer text. Rules can be recursive or mutually referential,
+;; though care must be taken not to create infinite loops.
+;;
+;; PEXs also support parsing actions, i.e. Lisp snippets which are
+;; executed when a pex matches. This can be used to construct syntax
+;; trees or for similar tasks. The most basic form of action is
+;; written as:
;;
;; (action FORM) ; evaluate FORM for its side-effects
-;; `(VAR... -- FORM...) ; stack action
;;
;; Actions don't consume input, but are executed at the point of
-;; match. A "stack action" takes VARs from the "value stack" and
-;; pushes the result of evaluating FORMs to that stack.
-;; See `peg-ex-parse-int' in `peg-tests.el' for an example.
+;; match. Another kind of action is called a "stack action", and
+;; looks like this:
+;;
+;; `(VAR... -- FORM...) ; stack action
+;;
+;; A stack action takes VARs from the "value stack" and pushes the
+;; results of evaluating FORMs to that stack.
+
+;; The value stack is created during the course of parsing. Certain
+;; operators (see below) that match buffer text can push values onto
+;; this stack. "Upstream" rules can then draw values from the stack,
+;; and optionally push new ones back. For instance, consider this
+;; very simple grammar:
+;;
+;; (with-peg-rules
+;; ((query (+ term) (eol))
+;; (term key ":" value (opt (+ [space]))
+;; `(k v -- (cons (intern k) v)))
+;; (key (substring (and (not ":") (+ [word]))))
+;; (value (or string-value number-value))
+;; (string-value (substring (+ [alpha])))
+;; (number-value (substring (+ [digit]))
+;; `(val -- (string-to-number val))))
+;; (peg-run (peg query)))
+;;
+;; This invocation of `peg-run' would parse this buffer text:
+;;
+;; name:Jane age:30
+;;
+;; And return this Elisp sexp:
+;;
+;; ((age . 30) (name . "Jane"))
+;;
+;; Note that, in complex grammars, some care must be taken to make
+;; sure that the number and type of values drawn from the stack always
+;; match those pushed. In the example above, both `string-value' and
+;; `number-value' push a single value to the stack. Since the `value'
+;; rule only includes these two sub-rules, any upstream rule that
+;; makes use of `value' can be confident it will always and only push
+;; a single value to the stack.
+;;
+;; Stack action forms are in a sense analogous to lambda forms: the
+;; symbols before the "--" are the equivalent of lambda arguments,
+;; while the forms after the "--" are return values. The difference
+;; being that a lambda form can only return a single value, while a
+;; stack action can push multiple values onto the stack. It's also
+;; perfectly valid to use `(-- FORM...)' or `(VAR... --)': the former
+;; pushes values to the stack without consuming any, and the latter
+;; pops values from the stack and discards them.
;;
;; Derived Operators:
;;
@@ -101,6 +153,8 @@
;; (replace E RPL); Match E and replace the matched region with RPL.
;; (list E) ; Match E and push a list of the items that E produced.
;;
+;; See `peg-ex-parse-int' in `peg-tests.el' for further examples.
+;;
;; Regexp equivalents:
;;
;; Here a some examples for regexps and how those could be written as pex.
@@ -177,7 +231,7 @@ EXPS is a list of rules/expressions that failed.")
;;;; Main entry points
-;; Sometimes (with-peg-rule ... (peg-run (peg ...))) is too
+;; Sometimes (with-peg-rules ... (peg-run (peg ...))) is too
;; longwinded for the task at hand, so `peg-parse' comes in handy.
(defmacro peg-parse (&rest pexs)
"Match PEXS at point.
next prev parent reply other threads:[~2021-10-09 16:47 UTC|newest]
Thread overview: 100+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-08-25 18:52 Make peg.el a built-in library? Eric Abrahamsen
2021-08-26 6:17 ` Eli Zaretskii
2021-08-26 15:34 ` Eric Abrahamsen
2021-09-09 4:36 ` Eric Abrahamsen
2021-09-19 15:25 ` Eric Abrahamsen
2021-09-30 19:44 ` Stefan Monnier
2021-09-30 20:34 ` Adam Porter
2021-10-01 8:14 ` Augusto Stoffel
2021-10-01 18:05 ` Stefan Monnier
2021-10-01 18:40 ` Eric Abrahamsen
2021-10-02 3:57 ` Stefan Monnier
2021-10-02 7:32 ` Adam Porter
2021-10-02 14:45 ` Stefan Monnier
2021-10-02 15:13 ` Adam Porter
2021-08-26 17:02 ` Adam Porter
2021-08-26 17:25 ` Eric Abrahamsen
2021-08-27 3:17 ` Eric Abrahamsen
2021-08-27 6:41 ` Helmut Eller
2021-08-27 16:57 ` Eric Abrahamsen
2021-09-26 10:59 ` Augusto Stoffel
2021-09-26 15:06 ` Eric Abrahamsen
2021-09-26 18:36 ` Augusto Stoffel
2021-09-27 16:18 ` Eric Abrahamsen
2021-09-27 22:34 ` Richard Stallman
2021-09-28 3:52 ` Eric Abrahamsen
2021-09-28 8:09 ` tomas
2021-09-28 9:32 ` Helmut Eller
2021-09-28 10:45 ` tomas
2021-09-28 15:24 ` Augusto Stoffel
2021-09-30 6:04 ` Richard Stallman
2021-10-01 3:27 ` Eric Abrahamsen
2021-10-09 1:31 ` Michael Heerdegen
2021-10-09 5:28 ` Michael Heerdegen
2021-10-09 8:12 ` Helmut Eller
2021-10-09 12:52 ` Stefan Monnier
2021-10-10 5:49 ` Helmut Eller
2021-10-14 10:25 ` Michael Heerdegen
2021-10-09 12:54 ` Stefan Monnier
2021-10-09 16:47 ` Eric Abrahamsen [this message]
2021-10-10 4:20 ` Michael Heerdegen
2021-10-10 21:40 ` Eric Abrahamsen
2021-10-13 2:58 ` Michael Heerdegen
2021-10-09 16:49 ` Eric Abrahamsen
2021-10-10 3:43 ` Stefan Monnier
2021-10-10 4:46 ` Michael Heerdegen
2021-10-10 5:58 ` Helmut Eller
2021-10-10 13:56 ` Stefan Monnier
2021-10-22 16:33 ` Michael Heerdegen
2021-10-31 23:43 ` Michael Heerdegen
2021-11-15 23:16 ` Michael Heerdegen
2022-11-07 3:33 ` Ihor Radchenko
2022-11-07 19:46 ` Eric Abrahamsen
2022-11-08 6:57 ` Helmut Eller
2022-11-08 8:51 ` Ihor Radchenko
2022-11-10 4:04 ` Richard Stallman
2022-11-10 5:25 ` tomas
2022-11-10 8:15 ` Eli Zaretskii
2022-11-10 8:29 ` tomas
2022-11-11 4:36 ` Richard Stallman
2022-11-08 8:47 ` Ihor Radchenko
2022-11-08 16:18 ` Eric Abrahamsen
2022-11-08 19:08 ` tomas
2022-11-08 19:42 ` Eric Abrahamsen
2022-11-16 4:27 ` [PATCH] " Eric Abrahamsen
2022-11-16 5:07 ` tomas
2022-11-16 5:39 ` Eric Abrahamsen
2022-11-16 15:53 ` tomas
2022-11-16 6:24 ` Ihor Radchenko
2022-11-16 18:15 ` Eric Abrahamsen
2022-11-17 12:21 ` Ihor Radchenko
2022-11-27 1:46 ` Eric Abrahamsen
2022-11-27 8:57 ` Eli Zaretskii
2022-11-28 1:09 ` Eric Abrahamsen
2022-11-28 12:16 ` Eli Zaretskii
2023-09-25 1:30 ` Eric Abrahamsen
2023-09-25 2:27 ` Adam Porter
2023-09-25 13:00 ` Alexander Adolf
2024-03-24 14:19 ` Ihor Radchenko
2024-03-24 15:32 ` Eli Zaretskii
2024-03-25 1:45 ` Eric Abrahamsen
2023-01-11 7:39 ` Michael Heerdegen
2023-01-11 8:04 ` Ihor Radchenko
2023-01-11 11:01 ` Michael Heerdegen
2023-01-11 11:32 ` tomas
2023-02-05 12:10 ` Ihor Radchenko
2023-02-05 15:41 ` Eduardo Ochs
2023-02-05 15:45 ` Ihor Radchenko
2023-02-05 16:19 ` Eduardo Ochs
2023-02-05 16:50 ` Ihor Radchenko
2023-02-09 5:44 ` Jean Louis
2023-02-06 0:33 ` Michael Heerdegen
2022-11-08 14:01 ` Stefan Monnier
2022-11-08 14:42 ` tomas
2022-11-08 15:08 ` Visuwesh
2022-11-08 16:29 ` Juanma Barranquero
2022-12-02 20:20 ` Augusto Stoffel
2022-11-08 16:10 ` Eric Abrahamsen
2022-11-08 18:59 ` tomas
2022-11-08 19:42 ` Eric Abrahamsen
2022-11-08 22:03 ` Tim Cross
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=874k9qxhzj.fsf@ericabrahamsen.net \
--to=eric@ericabrahamsen.net \
--cc=emacs-devel@gnu.org \
--cc=michael_heerdegen@web.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).