[elpa] externals/xr 4525d39 1/5: Comment cosmetics, and add a README.

[Mattias Engdegård]

branch: externals/xr
commit 4525d39687ae172b0defc6b8663cf55c12d03a87
Author: Mattias Engdegård <address@hidden>
Commit: Mattias Engdegård <address@hidden>

    Comment cosmetics, and add a README.
---
 README.org | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 xr.el      | 17 +++++++++--------
 2 files changed, 63 insertions(+), 8 deletions(-)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..05551a8
--- /dev/null
+++ b/README.org
@@ -0,0 +1,54 @@
+#+TITLE: xr.el
+
+XR converts Emacs regular expressions to the structured rx form, thus
+being an inverse of ~rx~. It can also find mistakes and questionable
+constructs inside regexp strings.
+
+It can be useful for:
+- Migrating existing code to rx form
+- Understanding what a regexp string really means
+- Finding errors in regexp strings
+
+It can also parse and find mistakes in skip-sets, the regexp-like
+arguments to ~skip-chars-forward~ and ~skip-chars-backward~.
+
+The xr package can be used interactively or by other code as a library.
+
+* Example
+
+: (xr-pp "\\`\\(?:[^^]\\|\\^\\(?: \\*\\|\\[\\)\\)")
+
+outputs
+
+: (seq bos 
+:      (or (not (any "^"))
+:          (seq "^"
+:               (or " *" "["))))
+
+* Installation
+
+From [[https://elpa.gnu.org/packages/xr.html][GNU ELPA]]:
+
+: M-x package-install RET xr RET
+
+* Interface
+
+Functions parsing regexp strings:
+
+| ~xr~      | convert regexp to rx                  |
+| ~xr-pp~   | convert regexp to rx and pretty-print |
+| ~xr-lint~ | find mistakes in regexp               |
+
+Functions parsing skip sets:
+
+| ~xr-skip-set~      | convert skip-set to rx                  |
+| ~xr-skip-set-pp~   | convert skip-set to rx and pretty-print |
+| ~xr-skip-set-lint~ | find mistakes in skip-set               |
+
+Utility:
+
+| ~xr-pp-rx-to-str~ | pretty-print rx expression to string |
+
+* See also
+
+The [[https://github.com/mattiase/relint][relint]] package uses xr to find 
regexp mistakes in elisp code.
diff --git a/xr.el b/xr.el
index 3a17487..014b001 100644
--- a/xr.el
+++ b/xr.el
@@ -47,7 +47,7 @@
 ;;  `xr-skip-set-lint' - finds mistakes in a skip set string
 ;;
 ;;  General:
-;;  `xr-pp-rx-to-str' - pretty-prints an rx expression to a string
+;;  `xr-pp-rx-to-str'  - pretty-prints an rx expression to a string
 ;;
 ;; Example (regexp found in compile.el):
 ;;
@@ -61,7 +61,7 @@
 ;; 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
@@ -616,10 +616,12 @@
 ;; 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.
   (when (and (looking-at (rx "[" (one-or-more anything) "]" eos))
              (not (looking-at (rx "[:" (one-or-more anything) ":]" eos))))
     (xr--report warnings (point) "Suspect skip set framed in `[...]'"))
+
   (let ((negated (looking-at (rx "^")))
         (ranges nil)
         (classes nil))
@@ -863,13 +865,9 @@ in SKIP-SET-STRING."
     (xr--parse-skip-set skip-set-string warnings)
     (sort (car warnings) #'car-less-than-car)))
 
-;; Escape non-printing characters in a string for maximum readability.
-;; If ESCAPE-PRINTABLE, also escape \ and ", otherwise don't.
 (defun xr--escape-string (string escape-printable)
-  ;; Translate control and raw chars to escape sequences for readability.
-  ;; We prefer hex escapes (\xHH) since that is usually what the user wants,
-  ;; but use octal (\OOO) if a legitimate hex digit follows, as
-  ;; hex escapes are not limited to two digits.
+  "Escape non-printing characters in a string for maximum readability.
+If ESCAPE-PRINTABLE, also escape \\ and \", otherwise don't."
   (replace-regexp-in-string
    "[\x00-\x1f\"\\\x7f\x80-\xff][[:xdigit:]]?"
    (lambda (s)
@@ -883,6 +881,9 @@ in SKIP-SET-STRING."
                             (?\f . "\\f")
                             (?\r . "\\r")
                             (?\e . "\\e")))))
+       ;; We prefer hex escapes (\xHH) because that is what most users
+       ;; want today, but use octal (\OOO) if the following character
+       ;; is a legitimate hex digit.
        (concat
         (cond (transl (cdr transl))
               ((memq c '(?\\ ?\"))