emacs-elpa-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[elpa] externals/eev 1bb2338af8 1/2: Rewrote most of (find-templates-int


From: ELPA Syncer
Subject: [elpa] externals/eev 1bb2338af8 1/2: Rewrote most of (find-templates-intro).
Date: Thu, 21 Dec 2023 21:57:43 -0500 (EST)

branch: externals/eev
commit 1bb2338af872544601cc5be86dce60a41adc5b4c
Author: Eduardo Ochs <eduardoochs@gmail.com>
Commit: Eduardo Ochs <eduardoochs@gmail.com>

    Rewrote most of (find-templates-intro).
---
 ChangeLog        |  11 +++
 VERSION          |   4 +-
 eev-blinks.el    |  34 ++++++-
 eev-intro.el     | 277 +++++++++++++++++++++++++++++++++++++++++++++----------
 eev-template0.el |   4 +-
 eev-tlinks.el    |  18 +++-
 eev-wrap.el      |   6 +-
 7 files changed, 296 insertions(+), 58 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f442be3f1d..294f30bb1c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2023-12-21  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-intro.el (find-templates-intro): rewrote many sections.
+
+2023-12-20  Eduardo Ochs  <eduardoochs@gmail.com>
+
+       * eev-blinks.el (find-eaproposf, ee-eaproposf0): new functions.
+
+       * eev-tlinks.el (ee-ffll-deftest): new function.
+       (find-find-links-links-new): use `ee-ffll-deftest'.
+
 2023-12-19  Eduardo Ochs  <eduardoochs@gmail.com>
 
        * eev-intro.el (find-show2-intro): added a section for Arch Linux.
diff --git a/VERSION b/VERSION
index f71150a636..87947bd4de 100644
--- a/VERSION
+++ b/VERSION
@@ -1,2 +1,2 @@
-Wed Dec 20 01:14:50 GMT 2023
-Tue Dec 19 22:14:50 -03 2023
+Fri Dec 22 00:59:04 GMT 2023
+Thu Dec 21 21:59:04 -03 2023
diff --git a/eev-blinks.el b/eev-blinks.el
index 0296aceae1..94e70739a5 100644
--- a/eev-blinks.el
+++ b/eev-blinks.el
@@ -21,7 +21,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20231106
+;; Version:    20231220
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://anggtwu.net/eev-current/eev-blinks.el>
@@ -73,6 +73,7 @@
 ;; «.find-eunicode»            (to "find-eunicode")
 ;; «.find-eejumps»             (to "find-eejumps")
 ;; «.find-eeshortdefs»         (to "find-eeshortdefs")
+;; «.find-eaproposf»           (to "find-eaproposf")
 
 
 
@@ -1681,6 +1682,37 @@ Hint: install the Debian package \"unicode-data\".")
 
 
 
+;;;   __ _           _                                                   __ 
+;;;  / _(_)_ __   __| |       ___  __ _ _ __  _ __ ___  _ __   ___  ___ / _|
+;;; | |_| | '_ \ / _` |_____ / _ \/ _` | '_ \| '__/ _ \| '_ \ / _ \/ __| |_ 
+;;; |  _| | | | | (_| |_____|  __/ (_| | |_) | | | (_) | |_) | (_) \__ \  _|
+;;; |_| |_|_| |_|\__,_|      \___|\__,_| .__/|_|  \___/| .__/ \___/|___/_|  
+;;;                                    |_|             |_|                  
+;;
+;; «find-eaproposf»  (to ".find-eaproposf")
+;; Tests: (find-eaproposf "^find-.*-links$")
+;;        (find-estring (ee-eaproposf0 "^find-.*-links$" 'fboundp ": %s\n"))
+
+(defun find-eaproposf (regexp &rest rest)
+  "Go to a temporary buffer listing all functions whose names match REGEXP."
+  (apply 'find-elinks-elisp
+        `(,(ee-template0 "\
+;; (find-eaproposf {(ee-S regexp)})
+;; (find-eapropos  {(ee-S regexp)})
+")
+          ,(ee-eaproposf0 regexp 'fboundp "(find-efunction '%s)\n"))
+        rest))
+
+(defun ee-eaproposf0 (regexp predicate fmt)
+  "An internal function used by `find-eaproposf'."
+  (mapconcat (lambda (sym) (format fmt sym))
+            (apropos-internal regexp predicate)
+            ""))
+
+
+
+
+
 (provide 'eev-blinks)
 
 
diff --git a/eev-intro.el b/eev-intro.el
index df87d54a66..897ac6e8c4 100644
--- a/eev-intro.el
+++ b/eev-intro.el
@@ -19,7 +19,7 @@
 ;;
 ;; Author:     Eduardo Ochs <eduardoochs@gmail.com>
 ;; Maintainer: Eduardo Ochs <eduardoochs@gmail.com>
-;; Version:    20231219
+;; Version:    20231221
 ;; Keywords:   e-scripts
 ;;
 ;; Latest version: <http://anggtwu.net/eev-current/eev-intro.el>
@@ -10286,15 +10286,237 @@ It is meant as both a tutorial and a sandbox.
 
 
 This intro is being rewritten!
-The prerequisites for understand this are:
+You will need a lot of knowledge of elisp to understand this.
+See:
   (find-elisp-intro)
-  (find-links-conv-intro \"3. Classification\")
 
 
 
 
 1. Introduction
 ===============
+The functions of eev that are meant to be used as hyperlinks can
+be classified in this way - look at the class (c):
+
+  (find-links-conv-intro \"3. Classification\")
+  (find-links-conv-intro \"3. Classification\" \"c)\")
+
+I will refer to these functions are \"`find-*-links' functions\".
+You can see a list of `find-*-links' functions by running:
+
+  (find-eaproposf \"^find-.*-links$\")
+  (find-eev \"eev-tlinks.el\" \".find-debpkg-links\")
+
+Most of them were written as \"5-minute hacks\". I explained the
+main ideas in this part of my presentation at the EmacsConf2020:
+
+  (find-eev2020video \"43:49\" \"(find-emacs-tangents-links)\")
+  (find-eev2020lsubs \"43:49\" \"(find-emacs-tangents-links)\")
+
+The final definition of `find-emacs-tangents-links' is here:
+
+  (find-eev \"eev-tlinks.el\" \"find-emacs-tangents-links\")
+
+Creating a new `find-*-links' function involves four steps:
+
+  1. generate a bare skeleton
+  2. generate an adjusted skeleton
+  3. add meat
+  4. debug the meat
+
+
+
+
+2. Skeletons
+============
+To generate a bare skeleton we run `find-find-links-links-new'.
+Try:
+
+  (eek \"M-x find-find-links-links-new\")
+
+To adjust the skeleton we edit the first line in that buffer and
+run it again \"to regenerate the buffer\". Remember this slogan:
+
+  (find-links-intro \"5. The first line regenerates the buffer\")
+
+This sexp generates (an example of) an \"adjusted skeleton\",
+
+  (find-find-links-links-new \"yttranscript\" \"c hash\" \"\")
+
+in which we have adjusted the name of the function -
+`find-yttranscript-links' - and its arguments, \"c\" and
+\"hash\".
+
+Look at the comments before the definition of
+`find-yttranscript-links':
+
+  (find-eev \"eev-tlinks.el\" \"find-yttranscript-links\")
+
+it has this line,
+
+;; Skel: (find-find-links-links-new \"yttranscript\" \"c hash\" \"\")
+
+that recreates the adjusted skeleton in a temporary buffer. Check
+these other \"Skel:\" lines:
+
+  (find-eevgrep \"grep --color=auto -nH --null -e Skel: eev-tlinks.el\")
+
+
+
+
+
+3. Meat
+=======
+Most of the \"meat\" in a `find-*-links' function is in the
+argument to `ee-template0'. See:
+
+  (find-eev \"eev-tlinks.el\" \"find-yttranscript-links\")
+  (find-eev \"eev-tlinks.el\" \"find-yttranscript-links\" \"ee-template0\")
+
+The docstrings of `ee-template0' and `ee-template00' have some
+examples of how they expand substrings of the form \"{expr}\":
+
+  (find-efunctiondescr 'ee-template0)
+  (find-efunctiondescr 'ee-template00)
+
+Here are some other examples with comments indicating how each
+substitution works:
+
+  (ee-template0 \"_{(+ 2 3)}_\")
+                  \\-------/
+                       5
+
+  (let ((hello \"Hi! \")
+        (a 2)
+        (b 3))
+     (ee-template0 \"{hello}{a}+{b}={(+ a b)}\"))
+                    \\-----/\\-/ \\-/ \\-------/
+                     \"Hi! \" 2   3      5
+
+The first example returns \"_5_\" - note that the (+ 2 3) returns
+a number, but its result gets converted to a string - and the
+second example returns \"Hi! 2+3=5\".
+
+In the second example the `ee-template0' only has access to the
+values variables `hello', `a' and `b' if it is run in dynamic
+binding. Try to execute it again, now both with `M-e', that uses
+dynamic binding, and with `M-1 M-1 M-e', that uses lexical
+biding; with `M-11e' you will get an error. The gory details are
+explained here,
+
+  (find-lexical-intro)
+
+...and this one of the reasons why I use dynamic binding in all
+the files of eev.
+
+Note that `ee-template0' expands \"{<}\"s to \"{\"s and \"{>}\"s
+to \"}\"s. Try:
+
+  (ee-template0 \"{<}bla{>}\")
+                 \\-/   \\-/
+                 \"{\"   \"}\"
+
+This trick is explained here:
+
+  (find-efunctiondescr 'ee-template0)
+  (find-efunction      'ee-template0)
+
+Some functions in eev need use `{(ee-S expr)}' instead of
+`{expr}'. Here are some links to examples and to the explanation
+of what `ee-S' does:
+
+  (find-eev \"eepitch.el\" \"find-eepitch-debug-links\")
+  (find-eev \"eepitch.el\" \"find-eepitch-debug-links\" \"ee-S\")
+  (find-eev \"eev-tlinks.el\" \"find-extra-file-links\")
+  (find-eev \"eev-tlinks.el\" \"find-extra-file-links\" \"ee-S\")
+  (find-eev \"eev-wrap.el\" \"ee-S\")
+
+
+
+
+4. Adding meat
+==============
+(TODO: explain how to quote certain characters)
+
+
+
+
+5. Debugging the meat
+=====================
+TODO: explain `M-x tt' and `M-x tt0',
+and explain which parts this video they replace:
+
+  (find-1stclassvideo-links \"2021ffll\")
+
+
+
+
+6. The `let*' block
+===================
+The third argument to `find-find-links-links-new' is a list of
+local variables in a `let*'. Compare the temporary buffers
+generated by:
+
+  (find-find-links-links-new \"mytaskC\" \"foo bar\" \"\")
+  (find-find-links-links-new \"mytaskC\" \"foo bar\" \"plic\")
+  (find-find-links-links-new \"mytaskC\" \"foo bar\" \"plic bletch\")
+
+In the second and the third cases the `(apply ...)' of the first
+case get wrapped in `(let* ...)'s, like this:
+  
+  (apply ...
+   pos-spec-list)
+
+  (let* ((plic \"{plic}\"))
+    (apply ...
+     pos-spec-list))
+
+  (let* ((plic \"{plic}\")
+         (bletch \"{bletch}\"))
+    (apply ...
+     pos-spec-list))
+
+The \"{plic}\" and the \"{bletch}\" are placeholders, and in real
+`find-*-links' functions they are replaced by non-trivial
+expressions - that are a second kind of meat that needs to be
+added to the `defun's by hand. For examples, see:
+
+  (find-eevgrep \"grep --color=auto -nH --null -e 'let\\\\*' eev-tlinks.el\")
+
+
+
+
+
+
+Garbage (to be recycled)
+========================
+
+  (find-eev \"eev-tlinks.el\" \".find-debpkg-links\")
+  (find-eev-quick-intro \"8.3. Creating index/section anchor pairs\")
+
+In the beginning I wrote the code of all those functions by hand.
+Then some patterns start to emerge, and I wrote some functions to
+help me to write those functions. The basic idea is explained in
+this part of my talk at the EmacsConf2020, in which I presented
+an example of a \"5-minute hack\":
+
+Its comments have these two lines:
+
+;; Skel: (find-find-links-links-new \"emacs-tangents\" \"yyyy mm dd msg 
txtstem\" \"\")
+;; Test: (find-emacs-tangents-links \"2022\" \"06\" \"06\")
+
+The \"Skel:\" line indicates that the code of
+`find-emacs-tangents-links' was written using
+`find-find-links-links-new', in several steps:
+
+In 2021 I recorded a video, called
+
+  How I write 5-minute hacks in eev using `M-x find-find-links-links-new'
+
+  (find-1stclassvideo-links \"2021ffll\")
+
+1. Introduction
+---------------
 In dec/2019 I sent this e-mail to the eev mailing list:
 
   https://lists.gnu.org/archive/html/eev/2019-12/msg00001.html
@@ -10330,36 +10552,8 @@ To learn how to write your own templated functions you 
need to:
 
   3) learn how to use `find-find-links-links-new'.
 
-
-
-
-
-2. `ee-template0'
-=================
-See:
-
-  (find-efunction 'ee-template0)
-  (find-eev \"eev-template0.el\")
-
-Try:
-
-  (ee-template00 \"a{(+ 2 3)}b\")
-
-  (let ((hi \"Here: \")
-        (a 22)
-        (b 33))
-    (ee-template00 \"{hi}{a}+{b}={(+ a b)}\"))
-
-  (defun foo (a b) (ee-template00 \"{a}+{b}={(+ a b)}\"))
-  (foo 22 33)
-
-  (ee-template0 \"{<} a{(+ 2 3)} {>}\")
-
-
-
-
 3. `find-elinks'
-================
+----------------
 See:
 
   (find-efunction 'find-elinks)
@@ -10433,10 +10627,8 @@ LIST that are sexps are converted to strings using 
`ee-HS'. See:
 
   (find-eev \"eev-wrap.el\" \"ee-S\")
 
-
-
 4. Skels
-========
+--------
 Many functions in eev have comments that start with \";; Skel:\",
 like this:
 
@@ -10452,13 +10644,9 @@ Try:
   (find-eev \"eev-tlinks.el\" \"find-fossil-links\")
   (find-eevgrep \"grep --color -nH --null -e Skel: *.el\")
 
-
-
-
-
 5. `find-find-links-links'
 ==========================
-(Note: `find-find-links-links' is obsolete, and is superseded by
+(Note: `find-find-links-links' is obsolete, and was superseded by
 `find-find-links-links-new')
 
 ALL my `find-*-links' started as quick hacks.
@@ -10486,9 +10674,6 @@ they generate:
   (find-find-links-links \"\\\\M-u\" \"macports\" \"pkgname\")
   (find-find-links-links \"\\\\M-u\" \"macports\" \"pkgname anotherarg\")
 
-
-
-
 So: start by running something like
 
   (find-find-links-links \"\\\\M-u\" \"macports\" \"pkgname\")
@@ -10525,14 +10710,8 @@ I will try to update this intro in the next days:
   (find-templates-intro)
   http://anggtwu.net/eev-intros/find-templates-intro.html
 
-
-
-
-
 Etc:
 
-  (find-links-conv-intro)
-  (find-links-conv-intro \"3. Classification\")
   (find-eev \"eev-tlinks.el\" \"find-find-links-links\")
   (find-eev \"eev-tlinks.el\" \"find-intro-links\")
   (find-eev \"eev-wrap.el\" \"find-eewrap-links\")
diff --git a/eev-template0.el b/eev-template0.el
index 9b6166b9e7..4de6e3d6be 100644
--- a/eev-template0.el
+++ b/eev-template0.el
@@ -130,8 +130,8 @@ Examples:\n
   (ee-template00 \"a{(+ 2 3)}b\")
     -->  \"a5b\"\n
   (let ((hi \"Here:\") (a 22) (b 33))
-    (ee-template00 \"{hi} {a} + {b} = {(+ a b)}\"))  
-    -->  \"22 + 33 = 55\""
+    (ee-template00 \"{hi} {a} + {b} = {(+ a b)}\"))
+    -->  \"Here: 22 + 33 = 55\""
   (save-match-data
     (replace-regexp-in-string
      ee-template00-re
diff --git a/eev-tlinks.el b/eev-tlinks.el
index 8c7e04ad7d..85fef31f73 100644
--- a/eev-tlinks.el
+++ b/eev-tlinks.el
@@ -408,7 +408,9 @@ This is an internal function used by `find-{stem}-links'.\"
      ,(concat       ";; Skel: " (ee-S `(find-find-links-links-new ,stem ,args 
,vars)))
      ,(ee-template0 ";; Test: (find-{stem}-links)")
      ";;"
-     ,(ee-ffll-defun stem args vars)
+     ,(ee-ffll-defun   stem args vars)
+     ""
+     ,(ee-ffll-deftest stem args vars)
      )
    pos-spec-list))
 
@@ -506,6 +508,20 @@ This is an internal function used by `find-{stem}-links'.\"
   (if vars (ee-ffll-defun-with-lets stem args vars)
      (ee-ffll-defun-without-lets stem args)))
 
+(defun ee-ffll-deftest (stem args &optional vars)
+  (ee-template0 "\
+;; A function to test changes in the template of `find-{stem}-links'.
+;; To use it type `M-x tt' inside the `(defun find-{stem}-links ...)'.
+;; See: (find-enode \"Lisp Eval\" \"eval-defun\" \"C-M-x\" \"containing\")
+;;
+(defun ee-template-test (&rest args)
+  (let ((ee-buffer-name \"*ee-template-test*\"))
+    (find-2a nil `(find-{stem}-links ,@args))))
+
+(defun tt0 () (interactive) (eek \"C-M-x\") (ee-template-test))
+(defun tt  () (interactive) (eek \"C-M-x\") (ee-template-test \"A\" \"B\"))
+"))
+
 
 
 
diff --git a/eev-wrap.el b/eev-wrap.el
index 3ce41b2235..bbeda93257 100644
--- a/eev-wrap.el
+++ b/eev-wrap.el
@@ -62,12 +62,12 @@ The best way to change this variable interactively is by 
running
 ;;;  \___|\___|    |____/ 
 ;;;                       
 ;;; «ee-S» (to ".ee-S")
-;; ee-S and ee-HS, for pretty-printing of sexps (mainly for use in
-;; ee-template0).
+;; `ee-S' and `ee-HS', for pretty-printing of sexps (mainly for use in
+;; `ee-template0').
 ;; Tests:
 ;;   (find-estring (ee-S  '(foo   "bar\nplic")))
 ;;   (find-estring (ee-HS '(foo   "bar\nplic")))
-;;   (find-estring (ee-H  "Some string")
+;;   (find-estring (ee-H  "Some string"))
 ;;         `(setq a ,(ee-add-quote "foo"))
 ;;         `(setq a ,(ee-add-quote '(+ 1 2)))
 ;;   (ee-S `(setq a ,(ee-add-quote '(+ 1 2))))



reply via email to

[Prev in Thread] Current Thread [Next in Thread]