[elpa] externals/eev 4a7bfcf 11/64: High-level words for `find-wset' (code and docs)

[Stefan Monnier]

branch: externals/eev
commit 4a7bfcf7775da90afaeb57c1bf205f8e23795195
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    High-level words for `find-wset' (code and docs)
---
 VERSION            |   4 +-
 eev-blinks.el      |   5 +-
 eev-elinks.el      |  74 +++++++++++++++--------
 eev-intro.el       | 170 ++++++++++++++++++++++++++++++++++++++++++++++-------
 eev-multiwindow.el |   5 ++
 eev-wrap.el        |  27 ++++++++-
 6 files changed, 233 insertions(+), 52 deletions(-)

diff --git a/VERSION b/VERSION
index 7a65f48..48896da 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Mon Nov 18 01:35:52 GMT 2013
-Sun Nov 17 23:35:52 BRST 2013
+Mon Nov 18 17:27:46 GMT 2013
+Mon Nov 18 15:27:46 BRST 2013
diff --git a/eev-blinks.el b/eev-blinks.el
index 982cd17..6532d93 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -22,7 +22,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2013nov17
+;; Version:    2013nov18
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-blinks.el>
@@ -76,7 +76,8 @@
 (autoload 'word-at-point "thingatpt")
 (autoload 'list-iso-charset-chars     "mule-diag")
 (autoload 'list-non-iso-charset-chars "mule-diag")
-(autoload 'customize-read-group "cus-edit")
+(autoload 'customize-read-group      "cus-edit")
+(autoload 'custom-unlispify-tag-name "cus-edit")
 
 
 ;;;            _    
diff --git a/eev-elinks.el b/eev-elinks.el
index 0e4a1ca..35a1b24 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2013nov17
+;; Version:    2013nov18
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-elinks.el>
@@ -372,8 +372,19 @@ This is an internal function used by `find-ekey-links' and
   (if (string-match "^\\*(find-\\(.*\\)-intro)\\*$" bufname)
       (match-string 1 bufname)))
 
+;; (defun ee-find-intro-links (&optional stem)
+;;   `((,(ee-intern "find-%s-intro" (or stem (ee-intro-stem))))))
+
 (defun ee-find-intro-links (&optional stem)
-  `((,(ee-intern "find-%s-intro" (or stem (ee-intro-stem))))))
+  (setq stem (or stem (ee-intro-stem)))
+  (let ((find-xxx-intro (ee-intern "find-%s-intro" stem))
+       (url (format "http://angg.twu.net/eev-intros/find-%s-intro.html"; stem)))
+    `(,(ee-H url)
+      (,find-xxx-intro)
+      )))
+
+  
+
 
 ;; A test: (ee-intro-stem "*(find-foo-intro)*")
 
@@ -873,14 +884,15 @@ This needs a temporary directory; see: 
(find-prepared-intro)"
 (defun ee-buffer-help (re n) (intern (or (ee-buffer-help-re0 re n) "nil")))
 
 ;; By major mode
-(defun ee-grep-bufferp     () (eq major-mode 'grep-mode))
-(defun ee-man-bufferp      () (eq major-mode 'Man-mode))
-(defun ee-rcirc-bufferp    () (eq major-mode 'rcirc-mode))
-(defun ee-info-bufferp     () (eq major-mode 'Info-mode))
-(defun ee-dired-bufferp    () (eq major-mode 'dired-mode))
-(defun ee-wdired-bufferp   () (eq major-mode 'wdired-mode))
-(defun ee-w3m-bufferp      () (eq major-mode 'w3m-mode))
-(defun ee-custom-bufferp   () (eq major-mode 'Custom-mode))
+(defun ee-grep-bufferp      () (eq major-mode 'grep-mode))
+(defun ee-man-bufferp       () (eq major-mode 'Man-mode))
+(defun ee-rcirc-bufferp     () (eq major-mode 'rcirc-mode))
+(defun ee-info-bufferp      () (eq major-mode 'Info-mode))
+(defun ee-dired-bufferp     () (eq major-mode 'dired-mode))
+(defun ee-wdired-bufferp    () (eq major-mode 'wdired-mode))
+(defun ee-w3m-bufferp       () (eq major-mode 'w3m-mode))
+(defun ee-custom-bufferp    () (eq major-mode 'Custom-mode))
+(defun ee-epackages-bufferp () (eq major-mode 'package-menu-mode))
 
 ;; By buffer name
 (defun ee-intro-bufferp    () (ee-buffer-re "^\\*(find-\\(.*\\)-intro)\\*$"))
@@ -911,6 +923,13 @@ This needs a temporary directory; see: 
(find-prepared-intro)"
     `((find-eface-links ',f)
       (find-efacedescr ',f))))
 
+(defvar ee-epackage-re "^\\([^ \t\n]+\\) is a[ -~]+ package")
+(defun  ee-epackage-bufferp () (ee-buffer-help ee-epackage-re 1))
+(defun  ee-find-epackage-links ()
+  (let ((p (ee-epackage-bufferp)))
+    `((find-epackages ,(format "\n  %s " p) t)
+      (find-epackage ',p))))
+
 ;; By buffer name (when the mode is man)
 (defvar ee-man-re "^\\*Man \\(.*\\)\\*$")
 (defun  ee-find-man-links () 
@@ -928,9 +947,10 @@ This needs a temporary directory; see: 
(find-prepared-intro)"
 
 
 
-(defun ee-find-efaces-links  () `((find-efaces)))
-(defun ee-find-ecolors-links () `((find-ecolors)))
-(defun ee-find-pdftext-links () (ee-pdflike-page-links))
+(defun ee-find-efaces-links    () `((find-efaces)))
+(defun ee-find-ecolors-links   () `((find-ecolors)))
+(defun ee-find-epackages-links () `((find-epackages)))
+(defun ee-find-pdftext-links   () (ee-pdflike-page-links))
 
 ;; to to:
 ;; ee-find-w3m-links
@@ -939,25 +959,27 @@ This needs a temporary directory; see: 
(find-prepared-intro)"
 
 (defun ee-find-here-links ()
   (cond ;; by major mode
-       ((ee-info-bufferp)     (cons "" (ee-find-info-links)))     ; M-h M-i
-       ((ee-man-bufferp)      (cons "" (ee-find-man-links)))      ; ?
-       ((ee-grep-bufferp)     (cons "" (ee-find-grep-links)))     ; M-h M-g
-       ((ee-w3m-bufferp)      (cons "" (ee-find-w3m-links)))      ; M-h M-w
-       ((ee-dired-bufferp)    (cons "" (ee-find-file-links)))     ; M-h f
-       ((ee-wdired-bufferp)   (cons "" (ee-find-file-links)))     ; M-h f
-       ((ee-custom-bufferp)   (cons "" (ee-find-custom-links)))   ; ?
+       ((ee-info-bufferp)      (cons "" (ee-find-info-links)))      ; M-h M-i
+       ((ee-man-bufferp)       (cons "" (ee-find-man-links)))       ; ?
+       ((ee-grep-bufferp)      (cons "" (ee-find-grep-links)))      ; M-h M-g
+       ((ee-w3m-bufferp)       (cons "" (ee-find-w3m-links)))       ; M-h M-w
+       ((ee-dired-bufferp)     (cons "" (ee-find-file-links)))      ; M-h f
+       ((ee-wdired-bufferp)    (cons "" (ee-find-file-links)))      ; M-h f
+       ((ee-custom-bufferp)    (cons "" (ee-find-custom-links)))    ; ?
+       ((ee-epackages-bufferp) (cons "" (ee-find-epackages-links))) ; ?
        ;; by buffer name
-       ((ee-intro-bufferp)    (cons "" (ee-find-intro-links)))    ; M-h M-i
-       ((ee-freenode-bufferp) (cons "" (ee-find-freenode-links))) ; ?
-       ((ee-ecolors-bufferp)  (cons "" (ee-find-ecolors-links)))  ; ?
-       ((ee-efaces-bufferp)   (cons "" (ee-find-efaces-links)))   ; ?
-       ((ee-pdftext-bufferp)  (cons "" (ee-find-pdftext-links)))  ; ?
+       ((ee-intro-bufferp)     (cons "" (ee-find-intro-links)))     ; M-h M-i
+       ((ee-freenode-bufferp)  (cons "" (ee-find-freenode-links)))  ; ?
+       ((ee-ecolors-bufferp)   (cons "" (ee-find-ecolors-links)))   ; ?
+       ((ee-efaces-bufferp)    (cons "" (ee-find-efaces-links)))    ; ?
+       ((ee-pdftext-bufferp)   (cons "" (ee-find-pdftext-links)))   ; ?
        ;; by buffer name, when it is "*Help*"
        ((ee-efunctiondescr-bufferp) (cons "" (ee-find-efunctiondescr-links)))
        ((ee-efacedescr-bufferp)     (cons "" (ee-find-efacedescr-links)))
        ((ee-evardescr-bufferp)      (cons "" (ee-find-evardescr-links)))
+       ((ee-epackage-bufferp)       (cons "" (ee-find-epackage-links)))
        ;; other cases
-       ((ee-file-bufferp)     (cons "" (ee-find-file-links)))     ; M-h f
+       ((ee-file-bufferp)      (cons "" (ee-find-file-links)))    ; M-h f
        (t (list "" "Not implemented!" "See:"
                 '(find-efunction 'ee-find-here-links)))
        ))
diff --git a/eev-intro.el b/eev-intro.el
index 0ea16b6..8c331d1 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2013nov15
+;; Version:    2013nov18
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -40,8 +40,9 @@
 ;; Note (2013nov12):
 ;; I am using this code to edit these intros:
 ;;
-;; (defun ee-sexp-at (str) (save-excursion (search-forward str) 
(ee-last-sexp)))
-;; (defun ee-intro-here () (eval (read (ee-sexp-at "rest)))"))))
+;; (defun ee-sexp-at (re) (save-excursion (re-search-forward re) 
(ee-last-sexp)))
+;; (setq ee-intro-end-re "\\(rest\\|pos-spec-list\\))))")
+;; (defun ee-intro-here () (eval (read (ee-sexp-at ee-intro-end-re))))
 ;; (defun d0 () (funcall (ee-intro-here) (ee-last-kill)))
 ;; (defun d () (interactive) (find-2b nil '(d0)))
 
@@ -1296,6 +1297,7 @@ for a few other cases. Try the sexps below:
 
   (find-here-links-test '(find-ecolors \"\\nred\"))
   (find-here-links-test '(find-efaces  \"eepitch-star-face\"))
+  (find-here-links-test '(find-customizegroup 'rcirc))
 
   (find-here-links-test '(find-man \"1 cat\"))
    [^ oops, this test doesn't work on multi-window settings...]
@@ -3345,6 +3347,48 @@ how to extend it - see the source:
 
 
 
+High-level words
+================
+Very often we want to create window setups like
+
+   _______________            _______________ 
+  |       |       |         |       |       |
+  |       |       |         |       |   B   |
+  |   A   |   B   |    or    |   A   |_______| ;
+  |       |       |         |       |       |
+  |       |       |         |       |   C   |
+  |_______|_______|         |_______|_______|
+
+there are shorthands for that. If you run
+
+  (find-2a sexpA sexpB)
+
+that will create a window setting like the one at the left above,
+initially with two copies of the current buffer, then will run
+sexpA at the window \"A\" and sexpB at the window \"B\", and
+finally will select the window \"A\", i.e., leave the cursor at
+the window at the left; this
+
+  (find-2b sexpA sexpB)
+
+will do exactly the same as the `(find-2a ...)' above, but will
+select the window \"B\" - the one at the right - at the end of
+the process. For three-window settings we have these:
+
+  (find-3a sexpA sexpB sexpC)
+  (find-3b sexpA sexpB sexpC)
+  (find-3c sexpA sexpB sexpC)
+
+all three create the three-window setting at the right above,
+initially with all three windows displaying the current buffer,
+then run sexpA at the window \"A\", sexpB at the window \"B\",
+and sexpC at the window \"C\"; the difference is that find-3a
+selects the window \"A\", find-3b the window \"B\", find-3c the
+window \"C\".
+
+
+
+
 Several eepitch targets
 =======================
 If we try to build a window setup like this one, with two eepitch
@@ -3376,12 +3420,107 @@ target. We can use this to create the window setting 
above,
              ' (ee-here '(eepitch-shell2))
              )
 
-This is too long - and would make a very bad one-liner - but a
-workaround is easy:
+This is too long - and would make a very bad one-liner - but
+there are two shorthands. First, \"e\" is a variant of \"_\" that
+runs its sexp inside an `(ee-here ...) - so this is equivalent
+the thing above,
+
+  (find-wset \"13o2eoeo\"
+             '(eepitch-shell)
+             '(eepitch-shell2)
+             )
+
+Second, these things are useful enough to deserve a high-level
+word, so this is equivalent to:
+
+  (find-3ee '(eepitch-shell) '(eepitch-shell2))
 
 
 
 
+Restarting eepitch targets
+==========================
+Sometimes we want to do the same as above, but restarting both
+eepitch targets, i.e., something like this:
+
+  (find-3ee '(progn (eepitch-shell)  (eepitch-kill) (eepitch-shell))
+            '(progn (eepitch-shell2) (eepitch-kill) (eepitch-shell2))
+            )
+
+There's a variant of `ee-here' that does that: `ee-here-reset'.
+For example,
+
+  (ee-here-reset '(eepitch-shell2))
+
+is equivalent to:
+
+  (ee-here '(progn (eepitch-shell2) (eepitch-kill) (eepitch-shell2)))
+
+and the letter \"E\" is a variant of \"e\" that uses
+`ee-here-reset' instead of `ee-here'; also, `find-3EE' is a
+variant of `find-3ee' that restarts both targets. Let's adapt
+this example,
+
+  (find-eepitch-intro \"Other targets\")
+
+to make it show the two eepitch targets at once in a three-window
+settings. It becomes:
+
+ (find-3EE '(eepitch-shell) '(eepitch-python))
+ (eepitch-shell)
+echo Hello... > /tmp/o
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
+ (eepitch-shell)
+echo ...and bye >> /tmp/o
+ (eepitch-python)
+print(open(\"/tmp/o\").read())
+
+ Now compare:
+ (eek \"C-x 1\")
+ (find-3ee '(eepitch-shell) '(eepitch-python))
+ (find-3EE '(eepitch-shell) '(eepitch-python))
+
+
+
+Non-trivial examples
+====================
+See:
+
+  (find-prepared-intro \"An `ee' for Python\")
+
+
+
+
+Eepitch blocks for two targets
+==============================
+An eepitch script with two targets uses several different kinds
+of red star lines - `(eepitch-target1)', `(eepitch-target2)',
+`(find-3EE ...)', `(find-3ee ...)', etc. We don't want to have to
+type all those by hand, so there is a hack similar to `M-T' that
+generates all those kinds from just \"target1\" and \"target2\"
+to let us just copy around the sexps we need. It is bound to
+`meta-shift-3', which Emacs sees as `M-#'. Compare the result of
+typing `M-T' here,
+
+python
+
+with the result of typing `M-#' on this line,
+
+shell python
+
+which yield this:
+
+ (find-3EE '(eepitch-shell) '(eepitch-python))
+ (find-3ee '(eepitch-shell) '(eepitch-python))
+ (eepitch-shell)
+ (eepitch-python)
+
+Note that we use to `find-3EE' to restart targets instead of
+`eepitch-kill' (this is non-trivial - think about it =/)...
+
+
+
 Adding support for new characters in `find-wset'
 ================================================
 The standard characters supported by `find-wset' are these:
@@ -3409,19 +3548,10 @@ The source code is simple enough, so take a look:
 
 Note that `find-wset-!' restarts an eepitch target, while
 `find-wset-=' will reuse an eepitch target if its buffer already
-exists.
-
-
+exists. [Obs: \"=\" and \"!\" have been mostly superseded by
+\"e\" and \"E\"... to do: explain this]
 
 
-Eepitch to two targets
-======================
-Examples:
-
- (defun eepitch2  (s1 s2) (find-wset \"13o2=o=o\" s1 s2))
- (defun eepitch2! (s1 s2) (find-wset \"13o2!o!o\" s1 s2))
- (eepitch2! '(eepitch-shell) '(eepitch-shell2))
-
 See: (find-prepared-intro)
 
   [Example at find-prepared-intro]
@@ -3964,12 +4094,10 @@ region from the current buffer as the temporary script.
 Note that the demo below uses `find-wset', which is an
 advanced (i.e., hackish) feature explained here:
 
-  (find-multiwindow-intro)
-
+  (find-multiwindow-intro \"Several eepitch targets\")
 
- (ee-kill-buffer \"*shell*\")
- (ee-kill-buffer \"*python*\")
- (find-wset \"13o2=o=o\" '(eepitch-shell) '(eepitch-python))
+ (find-3EE '(eepitch-shell) '(eepitch-python))
+ (find-3ee '(eepitch-shell) '(eepitch-python))
  (eepitch-python)
 import os
 def ee():
diff --git a/eev-multiwindow.el b/eev-multiwindow.el
index f601f64..0d8aef0 100644
--- a/eev-multiwindow.el
+++ b/eev-multiwindow.el
@@ -101,6 +101,11 @@ that. This is mainly for `find-wset'."
 (defun find-wset-! () (ee-here-reset (car sexps)) (setq sexps (cdr sexps)))
 (defun find-wset-O () (other-window -1))
 
+;; Mnemonic: "e" and "E" are both to prepare eepitch windows;
+;; "E" is more aggressive. See:
+(defun find-wset-e () (ee-here       (car sexps)) (setq sexps (cdr sexps)))
+(defun find-wset-E () (ee-here-reset (car sexps)) (setq sexps (cdr sexps)))
+
 
 
 ;; (find-multiwindow-intro)
diff --git a/eev-wrap.el b/eev-wrap.el
index d915b8e..ebe305c 100644
--- a/eev-wrap.el
+++ b/eev-wrap.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2013aug10
+;; Version:    2013nov18
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-wrap.el>
@@ -419,6 +419,31 @@ cd     {dir}"))
 
 
 
+;;;  __  __         _  _       ____                    _ _       _             
  
+;;; |  \/  |      _| || |_ _  |___ \    ___  ___ _ __ (_) |_ ___| |__   ___  
___ 
+;;; | |\/| |_____|_  ..  _(_)   __) |  / _ \/ _ \ '_ \| | __/ __| '_ \ / _ \/ 
__|
+;;; | |  | |_____|_      _|_   / __/  |  __/  __/ |_) | | || (__| | | |  
__/\__ \
+;;; |_|  |_|       |_||_| (_) |_____|  \___|\___| .__/|_|\__\___|_| 
|_|\___||___/
+;;;                                             |_|                            
  
+;; See: (find-multiwindow-intro "Several eepitch targets")
+;; (find-eewrap-links "#" "two-eepitches" "b c")
+;; M-#: two-eepitches
+(define-key eev-mode-map "\M-#" 'eewrap-two-eepitches)
+
+(defun  eewrap-two-eepitches () (interactive)
+  (ee-this-line-wrapn 2 'ee-wrap-two-eepitches))
+(defun ee-wrap-two-eepitches (b c)
+  "An internal function used by `eewrap-two-eepitches'."
+  (ee-template0 "\
+ (find-3EE '(eepitch-{b}) '(eepitch-{c}))
+ (find-3ee '(eepitch-{b}) '(eepitch-{c}))
+ (eepitch-{b})
+ (eepitch-{c})
+"))
+
+
+
+
 
 
 ;;;                                    /\ ____