[elpa] externals/eev 6e40458 03/10: Added eev-testblocks.el and a section about it in (find-eepitch-intro).

[Stefan Monnier]

branch: externals/eev
commit 6e40458c47108dd057bcc7f858dfc1a806c241de
Author: Eduardo Ochs <address@hidden>
Commit: Eduardo Ochs <address@hidden>

    Added eev-testblocks.el and a section about it in (find-eepitch-intro).
---
 ChangeLog         |  17 +++++++
 VERSION           |   4 +-
 eepitch.el        |  38 +++++++++++++--
 eev-blinks.el     |   8 +++-
 eev-elinks.el     |   1 -
 eev-intro.el      | 127 ++++++++++++++++++++++++++++++++++++++++++++++---
 eev-load.el       |   3 +-
 eev-plinks.el     |   4 +-
 eev-testblocks.el | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 eev-wrap.el       |  89 +----------------------------------
 eev.el            |   2 +-
 11 files changed, 323 insertions(+), 108 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d7a1dd5..0bd739f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,20 @@
+2019-09-29  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-eepitch-intro): rewrote some sections, added
+       a section about \"test blocks\".
+
+       * eev-testblocks.el: new file.
+       (eeit, ee-insert-test, ee-insert-test-lua)
+       (ee-insert-test-python, ee-insert-test-ruby, ee-insert-test-sh)
+       (ee-insert-test-tcl): moved all these functions from eev-wrap.el
+       to eev-testblocks.el.
+
+       * eev-load.el: load eev-testblocks.el.
+
+2019-09-28  Eduardo Ochs  <address@hidden>
+
+       * eev-intro.el (find-eev-install-intro): small changes.
+
 2019-09-27  Eduardo Ochs  <address@hidden>
 
        * eev-elinks.el (ee-file-name-nondirectory-slash): new function.
diff --git a/VERSION b/VERSION
index c213c09..b4485ee 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Fri Sep 27 05:51:18 GMT 2019
-Fri Sep 27 02:51:18 -03 2019
+Sun Sep 29 05:39:11 GMT 2019
+Sun Sep 29 02:39:11 -03 2019
diff --git a/eepitch.el b/eepitch.el
index 126b87f..156b273 100644
--- a/eepitch.el
+++ b/eepitch.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019sep26
+;; Version:    2019sep28
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eepitch.el>
@@ -36,6 +36,7 @@
 ;; «.eepitch-shell»            (to "eepitch-shell")
 ;; «.eepitch-kill»             (to "eepitch-kill")
 ;; «.ee-expand»                        (to "ee-expand")
+;; «.ee-split-and-expand»      (to "ee-split-and-expand")
 ;; «.find-comintprocess»       (to "find-comintprocess")
 ;;
 ;; «.eewrap-eepitch»           (to "eewrap-eepitch")
@@ -86,6 +87,15 @@
 ;; that also generalizes this "send lines to an interpreter" thing.
 ;; TODO: integrate eepitch and isend-mode!
 ;;
+;; See also the `run-<lang>' functions:
+;;
+;;   (find-eapropos "^run-*")
+;;   (find-eapropos "^inferior-*")
+;;   (find-enode "External Lisp" "run-lisp")
+;;   (find-enode "Executing Lisp" "Inferior Lisp mode")
+;;   (find-enode "Executing Lisp" "Inferior Scheme mode")
+;;   (find-elnode "Example Major Modes" "inferior Lisp job")
+;;
 ;;
 ;;
 ;; NOTE 2: eepitch is based on code that Rubikitch sent to the eev
@@ -475,7 +485,13 @@ scratch."
 ;;;  \___|\___|      \___/_/\_\ .__/ \__,_|_| |_|\__,_|
 ;;;                           |_|                      
 ;;
-;; «ee-expand»  (to ".ee-expand")
+;; «ee-expand»            (to ".ee-expand")
+;; «ee-split-and-expand»  (to ".ee-split-and-expand")
+;; Tests: (ee-split              "ls   ~/foo")
+;;        (ee-split-and-expand   "ls   ~/foo")
+;;        (ee-split            '("ls" "~/foo"))
+;;        (ee-split-and-expand '("ls" "~/foo"))
+;;        (ee-split-and-expand '("ls" "~/foo bar"))
 
 (defun ee-expand (fname)
 "Expand \"~\"s and \"$ENVVAR\"s in file names, but only at the beginning."
@@ -487,7 +503,13 @@ scratch."
                 (match-string 3 fname)))
        (t fname)))
 
-(defun ee-split (str) (if (stringp str) (split-string str "[ \t\n]+") str))
+(defun ee-split (str)
+  "If STR is a string, split it on whitespace and return the resulting list.
+If STR if a list, return it unchanged."
+  (if (stringp str)
+      (split-string str "[ \t\n]+")
+    str))
+
 (defun ee-split-and-expand (str)
 "Convert STR to a list (if it's a string) and apply `ee-expand' to each 
element.
 This function is used by `find-comintprocess', `find-bgprocess'
@@ -496,6 +518,7 @@ and `find-callprocess'."
 
 
 
+
 ;;;                      _       _   
 ;;;   ___ ___  _ __ ___ (_)_ __ | |_ 
 ;;;  / __/ _ \| '_ ` _ \| | '_ \| __|
@@ -504,6 +527,13 @@ and `find-callprocess'."
 ;;;                                  
 ;; «find-comintprocess»  (to ".find-comintprocess")
 ;; See: (find-eepitch-intro "2.5. `find-comintprocess'")
+;;      (find-eev "eev-plinks.el" "find-comintprocess")
+;;      (find-eev "eev-plinks.el" "find-bgprocess")
+;;      (find-enode "Shell Mode" "Comint mode")
+;;      (find-enode "Terminal emulator")
+;;      (find-elnode "Process Buffers")
+;; This is a variant of `find-bgprocess' that runs the process inside
+;; an Emacs buffer.
 
 (defun find-comintprocess-ne (name &optional program-and-args)
   "Switch to the buffer named *NAME* and run the command PROGRAM-AND-ARGS 
there.
@@ -743,7 +773,7 @@ This is useful for for running processes that use pagers 
like
 ;;;                   |___/             |___/           
 ;;
 ;; «eepitch-langs»  (to ".eepitch-langs")
-;; See: (find-eepitch-intro "2.4. `(eepitch-python)'")
+;; See: (find-eepitch-intro "2.5. `find-comintprocess'")
 
 ;; Shells:
 ;; These three are commented out because they are defined above.
diff --git a/eev-blinks.el b/eev-blinks.el
index f18a7e2..70eaf06 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -21,7 +21,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019sep24
+;; Version:    2019sep27
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-blinks.el>
@@ -318,10 +318,14 @@ then go to the position specified by POS-SPEC-LIST.\n
         "*Packages*" pos-spec-list))
 
 ;; Test: (find-epackage 'bdo)
+;; Note: `M-x find-epackage' currently doesn't work well.
+;;  See: (find-elnode "Interactive Codes" "S" "An interned symbol")
+;;       (find-elnode "Index" "* read-no-blanks-input:")
 ;;
 (defun find-epackage (&optional pkg-desc &rest pos-spec-list)
   "Hyperlink to the output of `describe-package'."
-  (interactive "P")
+  ;; (interactive "Spackage name: ")
+  (interactive (list (intern (read-no-blanks-input "Package name: " ""))))
   (apply 'find-wottb-call '(describe-package pkg-desc)
         "*Help*" pos-spec-list))
 
diff --git a/eev-elinks.el b/eev-elinks.el
index 42ccd4a..b9254cd 100644
--- a/eev-elinks.el
+++ b/eev-elinks.el
@@ -1104,7 +1104,6 @@ This needs a temporary directory; see: 
(find-prepared-intro)"
 ;; «find-epackage-links»  (to ".find-epackage-links")
 ;; Tests: (find-epackage-links "eev")
 ;;        (find-estring (ee-find-epackage-links0 "0x0"))
-;;        (find-estring (ee-find-epackage-links0 "eev"))
 ;;
 (defun find-epackage-links (&optional pkgname &rest pos-spec-list)
 "Visit a temporary buffer containing hyperlinks for an Emacs package."
diff --git a/eev-intro.el b/eev-intro.el
index 6b8adeb..a5df6d8 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019sep24
+;; Version:    2019sep29
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-intro.el>
@@ -2231,6 +2231,53 @@ and also:
 
   (find-eev \"README\")
   (find-eev \"eev-beginner.el\")
+
+
+
+6. Updates, sep. 2019
+---------------------
+These are the current ways to download and install eev:
+
+  1. as an Emacs package, with `M-x list-packages';
+
+  2. as an Emacs package, by downloading a file named
+     eev-YYYYMMDD.tar from either ELPA or angg.twu.net using
+     links like these ones,
+
+       http://elpa.gnu.org/packages/eev.html
+       http://elpa.gnu.org/packages/eev-20190902.tar
+       http://angg.twu.net/eev-current/
+       http://angg.twu.net/eev-current/eev-20190902.tar
+
+     and then running `M-x package-install-file';
+
+  3. by using the script in section 1, that downloads a .tgz from
+
+       http://angg.twu.net/eev-current/eev2.tgz ,
+
+     unpacks it in the directory ~/eev/ and creates a script
+     called \"~/eev\" that starts Emacs loading eev and opening
+     the main tutorial,
+
+  4. by downloading the .tgz above and unpacking it, and then
+     running these lines yourself:
+
+       (add-to-list 'load-path \"~/path-to-the-eev-source/\")
+       (require 'eev-load)
+       (eev-mode 1)               ; optional
+
+  5. by downloading the git repo and then running this:
+
+       (add-to-list 'load-path \"~/path-to-the-eev-source/\")
+       (require 'eev-load)
+       (eev-mode 1)               ; optional
+
+
+
+See:
+  (find-eev \"eev-load.el\")
+  (find-eev \"eev-mode.el\")
+
 " pos-spec-list)))
 
 ;; (find-eev-install-intro)
@@ -4756,19 +4803,87 @@ The sexp
 
 switches to a buffer called \"*buffer name*\" and if that buffer
 does not have an associated process then it runs \"program and
-args\" there in comint mode. See:
+args\" there in comint mode.
+
+The sexp
+
+  (eepitch-comint \"buffer name\" \"program and args\")
+
+works as an abbreviation for:
+
+  (eepitch '(find-comintprocess \"buffer name\" \"program and args\"))
+
+Most `eepitch-<lang>' functions are defined using
+`eepitch-comint'. See:
+
+  (find-eev \"eepitch.el\" \"eepitch-langs\")
+  (find-eev \"eepitch.el\" \"find-comintprocess\")
+  (find-eev \"eepitch.el\" \"find-comintprocess\" \"defun eepitch-comint \")
+
+
+
+
+3. Test blocks
+==============
+Suppose that we have a file \"foo.py\" containing this (without
+the indentation):
+
+  def square (x):
+      return x*x
+
+  \"\"\"
+   (eepitch-python)
+   (eepitch-kill)
+   (eepitch-python)
+  execfile(\"foo.py\", globals())
+  print(square(5))
+
+  \"\"\"
+
+Python treats everything between the first and the second
+`\"\"\"'s as a multiline comment, and ignores it - but for us
+this multiline comment contains an eepitch block that starts a
+Python interpreter, then a line that loads \"foo.py\" in it, then
+a line that tests the function \"square\" defined in foo.py. We
+call the block between the `\"\"\"'s a \"test block\".
+
+A \"test block\" is a multiline comment in a Python script, a Lua
+script, or in a script in one of the other supported languages -
+we call them the \"ambient script\" and the \"ambient language\"
+- that contains at least:
+
+  1) an eepitch block that runs an interpreter for the ambient
+     language,
+
+  2) a line that loads the ambient script in that interpreter,
+
+  3) code that tests functions defined in the ambient script.
+
+We can insert a test block in the current buffer by running `M-x
+ee-insert-test-python', `M-x ee-insert-test-lua', etc... for the
+list of supported languages, see:
+
+  (find-eev \"eev-testblocks.el\" \"ee-insert-test\")
+
+These `ee-insert-test-<lang>'s use the name of the current buffer
+in the line that loads the ambient script into in the
+interpreter.
+
+The command `M-x eeit' runs `ee-insert-test', that tries to
+detect the ambient language from major mode and then runs the
+correct `ee-insert-test-<lang>' based on it. `M-x eeit' is
+currently not very smart - see the source:
 
-  (find-enode \"Shell Mode\" \"Comint mode\")
-  (find-elnode \"Process Buffers\")
+  (find-eev \"eev-testblocks.el\" \"ee-insert-test\")
 
 
 
 
 
+-=-=-=-=-
+Old stuff:
 
 
-   (find-enode \"Shell\")
-   (find-enode \"Terminal emulator\")
 
 1. Motivation
 =============
diff --git a/eev-load.el b/eev-load.el
index 4275783..b6ddd2d 100644
--- a/eev-load.el
+++ b/eev-load.el
@@ -20,7 +20,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019apr06
+;; Version:    2019sep29
 ;; Keywords:   e-scripts
 ;;
 ;; Supersedes: (find-eev "eev-all.el")
@@ -139,6 +139,7 @@
 (require 'eev-codings)        ; (find-eev "eev-codings.el")
 (require 'eev-env)            ; (find-eev "eev-env.el")
 (require 'eev-edit)            ; (find-eev "eev-edit.el")
+(require 'eev-testblocks)      ; (find-eev "eev-testblocks.el")
 ;;
 ;; Hyperlinks to audio, video, and IRC. Not well documented. See:
 ;;   (find-audiovideo-intro)
diff --git a/eev-plinks.el b/eev-plinks.el
index b02346a..6936b76 100644
--- a/eev-plinks.el
+++ b/eev-plinks.el
@@ -242,9 +242,7 @@
 ;; «find-comintprocess» (to ".find-comintprocess")
 ;; `find-comintprocess-ne' and `find-comintprocess' are defined in
 ;; eepitch.el. See:
-;;   (find-eevfile "eepitch.el" "defun find-comintprocess-ne ")
-;;   (find-eevfile "eepitch.el" "defun find-comintprocess ")
-
+;;   (find-eev "eepitch.el" "find-comintprocess")
 
 
 
diff --git a/eev-testblocks.el b/eev-testblocks.el
new file mode 100644
index 0000000..538b921
--- /dev/null
+++ b/eev-testblocks.el
@@ -0,0 +1,138 @@
+;;; eev-testblocks.el - create "test blocks" using multiline comments.
+
+;; Copyright (C) 2019 Free Software Foundation, Inc.
+;;
+;; This file is part of GNU eev.
+;;
+;; GNU eev is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+;;
+;; GNU eev is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
+;;
+;; Author:     Eduardo Ochs <address@hidden>
+;; Maintainer: Eduardo Ochs <address@hidden>
+;; Version:    2019sep29
+;; Keywords:   e-scripts
+;;
+;; Latest version: <http://angg.twu.net/eev-current/eev-testblocks.el>
+;;       htmlized: <http://angg.twu.net/eev-current/eev-testblocks.el.html>
+;;       See also: <http://angg.twu.net/eev-current/eev-readme.el.html>
+;;                 <http://angg.twu.net/eev-intros/find-eev-intro.html>
+;;                 <http://angg.twu.net/eev-intros/find-links-intro.html>
+;;                                                (find-eev-intro)
+;;                                                (find-links-intro)
+
+;;; Commentary:
+
+;; A "test block" is a multiline comment that... see:
+;;
+;;   (find-eepitch-intro "3. Test blocks")
+
+
+
+
+;;;                  _                     _        _            _   
+;;;   ___  ___      (_)_ __  ___  ___ _ __| |_     | |_ ___  ___| |_ 
+;;;  / _ \/ _ \_____| | '_ \/ __|/ _ \ '__| __|____| __/ _ \/ __| __|
+;;; |  __/  __/_____| | | | \__ \  __/ |  | ||_____| ||  __/\__ \ |_ 
+;;;  \___|\___|     |_|_| |_|___/\___|_|   \__|     \__\___||___/\__|
+;;;                                                                  
+;; «ee-insert-test»  (to ".ee-insert-test")
+;; See: (find-eepitch-intro "3. Test blocks")
+;; Insert a "test block" in a Lua/Python/Ruby/shell/Tcl script.
+
+
+(defalias 'eeit 'ee-insert-test)
+
+(defun ee-insert-test ()
+  "Insert an \"test block\" - an eepitch block in a multiline comment."
+  (interactive)
+  (cond ((eq major-mode 'lua-mode)    (ee-insert-test-lua))
+        ((eq major-mode 'python-mode) (ee-insert-test-python))
+        ((eq major-mode 'ruby-mode)   (ee-insert-test-ruby))
+        ((eq major-mode 'sh-mode)     (ee-insert-test-sh))
+        ((eq major-mode 'tcl-mode)    (ee-insert-test-tcl))
+       (t (error "ee-insert-test: Unsupported major mode"))))
+
+(defun ee-insert-test-lua ()
+  (interactive)
+  (insert (format "
+--[[
+ (eepitch-lua51)
+ (eepitch-kill)
+ (eepitch-lua51)
+dofile \"%s\"
+
+--]]
+" (buffer-name))))
+
+(defun ee-insert-test-python ()
+  (interactive)
+  (insert (format "
+\"\"\"
+ (eepitch-python)
+ (eepitch-kill)
+ (eepitch-python)
+execfile(\"%s\", globals())
+
+\"\"\"
+" (buffer-name))))
+
+(defun ee-insert-test-ruby ()
+  (interactive)
+  (insert (format "
+=begin
+ (eepitch-ruby)
+ (eepitch-kill)
+ (eepitch-ruby)
+load \"%s\"
+
+=end
+" (buffer-name))))
+
+(defun ee-insert-test-sh ()
+  (interactive)
+  (insert (format "
+: <<'%%%%%%%%%%'
+ (eepitch-sh)
+ (eepitch-kill)
+ (eepitch-sh)
+. %s
+
+%%%%%%%%%%
+" (buffer-name))))
+
+(defun ee-insert-test-tcl ()
+  (interactive)
+  (insert (format "
+set COMMENTED_OUT {
+ (eepitch-tclsh)
+ (eepitch-kill)
+ (eepitch-tclsh)
+source %s
+
+}
+" (buffer-name))))
+
+
+
+
+
+(provide 'eev-testblocks)
+
+
+
+
+
+;; Local Variables:
+;; coding:            utf-8-unix
+;; no-byte-compile:   t
+;; End:
diff --git a/eev-wrap.el b/eev-wrap.el
index 70bbad3..01f80f6 100644
--- a/eev-wrap.el
+++ b/eev-wrap.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <address@hidden>
 ;; Maintainer: Eduardo Ochs <address@hidden>
-;; Version:    2019mar29
+;; Version:    2019sep28
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://angg.twu.net/eev-current/eev-wrap.el>
@@ -41,7 +41,6 @@
 ;; «.ee-S»                     (to "ee-S")
 ;; «.ee-this-line-wrapn»       (to "ee-this-line-wrapn")
 ;; «.find-eewrap-links»                (to "find-eewrap-links")
-;; «.ee-insert-test»           (to "ee-insert-test")
 
 
 (require 'eev-template0)      ; (find-eev "eev-template0.el")
@@ -526,92 +525,6 @@ cd     {dir}"))
 
 
 
-;;;                  _                     _        _            _   
-;;;   ___  ___      (_)_ __  ___  ___ _ __| |_     | |_ ___  ___| |_ 
-;;;  / _ \/ _ \_____| | '_ \/ __|/ _ \ '__| __|____| __/ _ \/ __| __|
-;;; |  __/  __/_____| | | | \__ \  __/ |  | ||_____| ||  __/\__ \ |_ 
-;;;  \___|\___|     |_|_| |_|___/\___|_|   \__|     \__\___||___/\__|
-;;;                                                                  
-;; «ee-insert-test»  (to ".ee-insert-test")
-;; Insert a "test block" in a Lua/Python/Ruby/shell/Tcl script.
-
-(defalias 'eeit 'ee-insert-test)
-
-(defun ee-insert-test ()
-  "Insert an \"test block\" - an eepitch block in a multiline comment."
-  (interactive)
-  (cond ((eq major-mode 'lua-mode)    (ee-insert-test-lua))
-        ((eq major-mode 'python-mode) (ee-insert-test-python))
-        ((eq major-mode 'ruby-mode)   (ee-insert-test-ruby))
-        ((eq major-mode 'sh-mode)     (ee-insert-test-sh))
-        ((eq major-mode 'tcl-mode)    (ee-insert-test-tcl))
-       (t (error "ee-insert-test: Unsupported major mode"))))
-
-(defun ee-insert-test-lua ()
-  (interactive)
-  (insert (format "
---[[
- (eepitch-lua51)
- (eepitch-kill)
- (eepitch-lua51)
-dofile \"%s\"
-
---]]
-" (buffer-name))))
-
-(defun ee-insert-test-python ()
-  (interactive)
-  (insert (format "
-\"\"\"
- (eepitch-python)
- (eepitch-kill)
- (eepitch-python)
-execfile(\"%s\", globals())
-
-\"\"\"
-" (buffer-name))))
-
-(defun ee-insert-test-ruby ()
-  (interactive)
-  (insert (format "
-=begin
- (eepitch-ruby)
- (eepitch-kill)
- (eepitch-ruby)
-load \"%s\"
-
-=end
-" (buffer-name))))
-
-(defun ee-insert-test-sh ()
-  (interactive)
-  (insert (format "
-: <<'%%%%%%%%%%'
- (eepitch-sh)
- (eepitch-kill)
- (eepitch-sh)
-. %s
-
-%%%%%%%%%%
-" (buffer-name))))
-
-(defun ee-insert-test-tcl ()
-  (interactive)
-  (insert (format "
-set COMMENTED_OUT {
- (eepitch-tclsh)
- (eepitch-kill)
- (eepitch-tclsh)
-source %s
-
-}
-" (buffer-name))))
-
-
-
-
-
-
 ;;;                                  _   
 ;;;   ___ ___  _ __ ___  _ __   __ _| |_ 
 ;;;  / __/ _ \| '_ ` _ \| '_ \ / _` | __|
diff --git a/eev.el b/eev.el
index 9eb7ba4..2888d80 100644
--- a/eev.el
+++ b/eev.el
@@ -6,7 +6,7 @@
 ;; Package-Requires: ((emacs "24.1"))
 ;; Keywords: lisp e-scripts
 ;; URL: http://angg.twu.net/#eev
-;; Version: 20190926
+;; Version: 20190929
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by