branch: externals/xr commit d7325b3c1fe2e8a64c0057e6d790aa46d7c27700 Author: Mattias Engdegård <matti...@acm.org> Commit: Mattias Engdegård <matti...@acm.org>
Edit the package doc comment --- xr.el | 61 ++++++++++++++++++++++++++++--------------------------------- 1 file changed, 28 insertions(+), 33 deletions(-) diff --git a/xr.el b/xr.el index 410de13..55465e9 100644 --- a/xr.el +++ b/xr.el @@ -31,54 +31,51 @@ ;; Please refer to `rx' for more information about the notation. ;; ;; In addition to Emacs regexps, this package can also parse and -;; troubleshoot skip set strings, which are arguments to +;; find mistakes in skip set strings, which are arguments to ;; `skip-chars-forward' and `skip-chars-backward'. ;; -;; The exported functions for regexps are: +;; The exported functions are: ;; +;; Regexps: ;; `xr' - returns the converted rx expression ;; `xr-pp' - converts to rx and pretty-prints ;; `xr-lint' - finds mistakes in a regexp string ;; -;; For skip sets we also have: -;; +;; Skip sets: ;; `xr-skip-set' - return the converted rx expression ;; `xr-skip-set-pp' - converts to rx and pretty-prints ;; `xr-skip-set-lint' - finds mistakes in a skip set string ;; -;; There is finally the generally useful: -;; +;; General: ;; `xr-pp-rx-to-str' - pretty-prints an rx expression to a string ;; -;; Suggested use is from an interactive elisp buffer. -;; ;; Example (regexp found in compile.el): ;; ;; (xr-pp "\\`\\(?:[^^]\\|\\^\\(?: \\*\\|\\[\\)\\)") ;; => ;; (seq bos -;; (or -;; (not (any "^")) -;; (seq "^" -;; (or " *" "[")))) +;; (or (not (any "^")) +;; (seq "^" +;; (or " *" "[")))) ;; -;; The rx notation admits many synonyms; the xr functions mostly -;; prefer brief variants, such as `seq' to `sequence' and `nonl' to -;; `not-newline'. The user is encouraged to edit the result for -;; maximum readability, consistency and personal preference when -;; replacing existing regexps in elisp code. +;; The rx notation admits many synonyms. The user is encouraged to +;; edit the result for maximum readability, consistency and personal +;; preference when replacing existing regexps in elisp code. ;; Related work: ;; ;; The `lex' package, a lexical analyser generator, provides the -;; `lex-parse-re' function which performs a similar task, but does not -;; attempt to handle all the edge cases of Elisp's regexp syntax or -;; pretty-print the result. +;; `lex-parse-re' function which translates regexps to rx, but does +;; not attempt to handle all the edge cases of Elisp's regexp syntax +;; or pretty-print the result. +;; +;; The `pcre2el' package, a regexp syntax converter and interactive +;; regexp explainer, could also be used for translating regexps to rx. +;; `xr' is narrower in scope but more accurate for the purpose of +;; parsing Emacs regexps and printing the results in rx form. ;; -;; The `pcre2el' package, a regexp syntax converter and interactive regexp -;; explainer, could also be used for the same tasks. `xr' is narrower in -;; scope but more accurate for the purpose of parsing Emacs regexps and -;; printing the results in rx form. +;; Neither of these packages parse skip-set strings or provide +;; mistake-finding functions. ;;; Code: @@ -606,17 +603,15 @@ ;; Grammar for skip-set strings: ;; -;; skip-set ::= `^'? item* +;; skip-set ::= `^'? item* dangling? ;; item ::= range | single -;; range ::= single `-' end -;; single ::= (any char but `\') -;; | `\' (any char) -;; end ::= single | `\' +;; range ::= single `-' endpoint +;; single ::= {any char but `\'} +;; | `\' {any char} +;; endpoint ::= single | `\' +;; dangling ::= `\' ;; -;; The grammar is ambiguous, resolved left-to-right: -;; - a leading ^ is always a negation marker -;; - an item is always a range if possible -;; - an end is only `\' if last in the string +;; Ambiguities in the above are resolved greedily left-to-right. (defun xr--parse-skip-set-buffer (warnings) ;; An ad-hoc check, but one that catches lots of mistakes.