[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))))