(Re)generate: (find-kla-intro)
Source code:  (find-efunction 'find-kla-intro)
More intros:  (find-eev-quick-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.

  See: http://anggtwu.net/emacsconf2022-kla.html
    (find-eev "eev-kla.el")
    `kla' means "kill link to anchor".
  The prerequisites for this tutorial are:
    (find-eev-quick-intro "8. Anchors")
    (find-eev-quick-intro "9.1. `code-c-d'")
    (find-eev-quick-intro "9.2. Extra arguments to `code-c-d'")
    (find-eev-quick-intro "9.2. Extra arguments to `code-c-d'" "to anchors")
    (find-eev-quick-intro "4. Creating Elisp Hyperlinks")
    (find-eev-quick-intro "4.1. `find-here-links'")

  Video: (find-eev2022klavideo "0:00")

1. Introduction

When we run this `code-c-d', (code-c-d "foo" "/tmp/FOO/") it defines several functions; one of them is a function called `find-foofile', that points to the directory "/tmp/FOO/". I will refer to the first argument of the `code-c-d', "foo" as the `code', or the `c', and to the second argument, "/tmp/FOO/" as the `directory', or the `d'. Running (find-foofile "BAR/PLIC/bletch") is equivalent to running this: (find-file "/tmp/FOO/BAR/PLIC/bletch") Let's consider that the `code' "foo" in the middle of the name of the function `find-foofile' was expanded, or converted, to the `directory' "/tmp/FOO". So the function `find-foofile' converts a `code' to a `directory', or a `c' to a `d'. We can represent this as: (find-foofile "BAR/PLIC/bletch") foo -> "/tmp/FOO/" (find-fline "/tmp/FOO/BAR/PLIC/bletch") In this section of the main tutorial (find-eev-quick-intro "10.1. Generating short hyperlinks to files") we saw that after running these three `code-c-d's, (code-c-d "foo" "/tmp/FOO/" :anchor) (code-c-d "bar" "/tmp/FOO/BAR/" :anchor) (code-c-d "plic" "/tmp/FOO/BAR/PLIC/" :anchor) the three `find-*file's below would point to the same file: (find-foofile "BAR/PLIC/bletch") (find-barfile "PLIC/bletch") (find-plicfile "bletch") foo -> "/tmp/FOO/" bar -> "/tmp/FOO/BAR/" plic -> "/tmp/FOO/BAR/PLIC/" (find-fline "/tmp/FOO/BAR/PLIC/bletch") How can we do the opposite? I.e., how do we start with a filename, like: "/tmp/FOO/BAR/PLIC/bletch" and then convert it to a pair made of a `c' and a `d'? In that example we have these three options, (foo "/tmp/FOO/") (bar "/tmp/FOO/BAR/") (plic "/tmp/FOO/BAR/PLIC/") that are associated to these three short hyperlinks to that filename: (find-foofile "BAR/PLIC/bletch") (find-barfile "PLIC/bletch") (find-plicfile "bletch") So: in eev conversions of the from c->d are trivial, but conversions in the other direction, like c<-d or c,d<-filename, are harder to perform... sometimes there will be several possible results, and sometimes none.

2. The old way

From here onwards I will suppose that you have run the three `code-c-d's that are in the middle of the previous section. Now all these links will point to the same file: (find-file "/tmp/FOO/BAR/PLIC/bletch") (find-fline "/tmp/FOO/BAR/PLIC/bletch") (find-foofile "BAR/PLIC/bletch") (find-barfile "PLIC/bletch") (find-plicfile "bletch") Run this (mkdir "/tmp/FOO/BAR/PLIC/" 'make-parents) to avoid some warning messages, then run one of the `find-*'s above to visit the file "/tmp/FOO/BAR/PLIC/bletch", and then type `M-h M-h' - i.e., `find-here-links' - there. The `find-here-links' will detect that "here" is a file, and will try to create links to that file. It will create a temporary buffer whose core will be the five `find-*'s above... The function `find-here-links' doesn't know how to choose the "best" hyperlink to "/tmp/FOO/BAR/PLIC/bletch", so it shows all the five options. The slogan is: "The old way shows all options". The old way to save a hyperlink to "/tmp/FOO/BAR/PLIC/bletch" is to use `find-here-links' as above, then choose the "best" of those five hyperlinks, then edit it - or: "refine" it - with these keys, (find-emacs-keys-intro "1. Basic keys (eev)") (find-emacs-keys-intro "1. Basic keys (eev)" "refining hyperlinks") and then copy it to our notes. This takes MANY keystrokes. For example, suppose that we have anchors in /tmp/FOO/BAR/PLIC/bletch, in this sense, (find-eev-quick-intro "8. Anchors") and we want to create a hyperlink to the anchor just before point and to put that link in the kill ring. One sequence of keystrokes that would do that is this one: M-1 M-h M-w ;; ee-copy-preceding-tag-to-kill-ring M-h M-h ;; find-here-links 8*<down> ;; go to the line with the `(find-plicfile ...)' M-h M-2 ;; ee-duplicate-this-line M-h M-y ;; ee-yank-pos-spec M-h M-- ;; ee-shrink-hyperlink-at-eol C-a ;; move-beginning-of-line C-SPC ;; set-mark-command <down> ;; next-line M-w ;; kill-ring-save M-k ;; ee-kill-this-buffer That key sequence is explained here: (find-saving-links-intro) (find-saving-links-intro "2.3. The base case 3")

3. The new way

The file eev-kla.el implements another way - a "new way" - to do something similar to that old way, but with fewer keystrokes. The slogan is: "The new way chooses the best link itself". If we are in the file "/tmp/FOO/BAR/PLIC/bletch" and we type `M-x eeklf' or `M-x klf', then this will "kill a link to a file", which is a mnemonic for "create the best link to this file and put in the kill ring". In this case the best link will be: (find-plicfile "bletch") Try it - visit that file with either the `find-plicfile' above or with this, (find-fline "/tmp/FOO/BAR/PLIC/bletch") and then type `M-x eeklf'. You should see this message in the echo area: Copied to the kill ring: (find-plicfile "bletch") Note that it chose to use `find-plicfile' instead of the other options. The algorithm that chooses the "best link": 1. needs to do several conversions of the form c,d<-fname, 2. doesn't always give the result that _I_ want, 3. is hard to summarize, 4. may need tinkering by the user. So we will see it in detail.

4. Aliases

In the other examples of this tutorial I will suppose that you have run the `defalias'es below: ;; From: (find-kla-intro "2. Aliases") (defalias 'kla 'eekla) (defalias 'kla0 'eekla0) (defalias 'klas 'eeklas) (defalias 'klf 'eeklf) (defalias 'klfs 'eeklfs) (defalias 'klt 'eeklt) (defalias 'klts 'eeklts) (defalias 'kli 'ee-kl-insert) (defalias 'kla2 'eekla2) To make these aliases permanent, copy them to your ~/.emacs. Without these aliases everything in eev-kla.el will still work, but you will have to type `M-x eekla' instead of `M-x kla', `M-x eeklas' instead of `M-x klas', and so on.

5. `ee-code-c-d-pairs'

A call to (code-c-d "foo" "/tmp/FOO/" :anchor) does a bit more than just running the code shown by this sexp: (find-code-c-d "foo" "/tmp/FOO/" :anchor) It also runs this, (ee-code-c-d-add-pair "foo" "/tmp/FOO/") that modifies the variable `ee-code-c-d-pairs' in two steps: it first deletes all the elements of `ee-code-c-d-pairs' that are of the form ("foo" ...), and then it adds the pair ("foo" "/tmp/FOO/") to the front of the list. If you want to look at the code that does that, it is here: (find-eev "eev-code.el" "code-c-d") (find-eev "eev-code.el" "code-c-d-pairs") and you can inspect the variable `ee-code-c-d-pairs' with: (find-eppp ee-code-c-d-pairs) We will refer to the elements of `ee-code-c-d-pairs' as `c-d's. A `c-d' is a pair made of a `c' and a `d', where these `c' and `d' were the arguments given to a `code-c-d'.

6. The components

In order to convert a filename like "/tmp/FOO/BAR/PLIC/bletch" to a sexp like (find-plicfile "bletch") or: (find-plic "bletch") eev needs to: 1. select all the `c-d's in `ee-code-c-d-pairs' whose `d's are initial substrings of "/tmp/FOO/BAR/PLIC/bletch", 2. select the "best one" among these `c-d's; in our example it will be ("plic" "/tmp/FOO/BAR/PLIC/") 3. remove the prefix "/tmp/FOO/BAR/PLIC/" from "/tmp/FOO/BAR/PLIC/bletch" to obtain "bletch"; we will refer to "/tmp/FOO/BAR/PLIC/bletch" as the `fname', and to the "bletch" as the "rest". We will abbreviate the "rest" as `r', and we will refer to the length of `r' as `l'. So in this case we have: /tmp/FOO/BAR/PLIC/bletch \----------------/\----/ d r \----------------------/ fname and "bletch" has 6 characters, so `l' is 6. 4. build the sexp. We will refer to its components as: (find-plicfile "bletch") \--/ \----/ c shortfname \-----------/ find-cfile (find-plic "bletch") \--/ \----/ c shorterfname \-------/ find-c `shortfname' and `shorterfname' are usually equal to `r'. In my machine I override the function that calculates the `shorterfname' to add support for some "living fossils", (find-angg-es-links "living fossil") but very few people will need that.

7. The best `l-r-c-d'

The algorithm that chooses the "best" `c-d' is here: (find-eev "eev-kla.el" "best-lrcd") If `fname' is "/tmp/FOO/BAR/PLIC/bletch" and `ee-code-c-d-pairs' is this list, (("plic" "/tmp/FOO/BAR/PLIC/") ("bar" "/tmp/FOO/BAR/") ("foo" "/tmp/FOO/") ("eev" "/home/edrx/eev-current/") ("e" "/usr/share/emacs/27.1/lisp/")) then the `c-d's in `ee-code-c-d-pairs' that "match" `fname', in the sense their `d's are initial substrings of "/tmp/FOO/BAR/PLIC/bletch" will be these ones: (("plic" "/tmp/FOO/BAR/PLIC/") ("bar" "/tmp/FOO/BAR/") ("foo" "/tmp/FOO/")) Try this: (find-eppp (ee-kl-lrcds "/tmp/FOO/BAR/PLIC/bletch")) It will show something like this: ((6 "bletch" "plic" "/tmp/FOO/BAR/PLIC/") (11 "PLIC/bletch" "bar" "/tmp/FOO/BAR/") (15 "BAR/PLIC/bletch" "foo" "/tmp/FOO/")) note that each `c-d' that matched `fname' was converted to an `l-r-c-d'; the `r' is the "rest" that remains of `fname' after the deleting the initial `d', and the `l' is the length of the "rest". This sexp (ee-kl-lrcds "/tmp/FOO/BAR/PLIC/bletch") returns _all_ the `l-r-c-d's that match that filename; this sexp (ee-kl-lrcd "/tmp/FOO/BAR/PLIC/bletch") returns _the_ `l-r-c-d' that matches that filename - i.e., the "best" `l-r-c-d' that matches that filename. The best one is chosen by sorting the `l-r-c-d's by their `l's and then returning the first `l-r-c-d' in the sorted list. In that example the best `l-r-c-d' will be this one: (6 "bletch" "plic" "/tmp/FOO/BAR/PLIC/") Note that its `r' is as short as possible. When there are no `c-d's matching the filename the function `ee-kl-lrcd' returns nil.

8. `cl-loop'

The functions that produce the best `l-r-c-d' are implemented using `cl-loop'. I didn't explain `cl-loop' in (find-elisp-intro) because it was too complex, but let's see it now. The features of `cl-loop' that we will need are explained here: (find-clnode "Loop Basics") (find-clnode "Accumulation Clauses" "collect FORM") (find-clnode "Accumulation Clauses" "append FORM") (find-clnode "For Clauses" "for VAR in LIST by FUNCTION") (find-clnode "For Clauses" "for VAR on LIST by FUNCTION") (find-clnode "For Clauses" "for VAR = EXPR1 then EXPR2") (find-clnode "For Clauses" "destructuring") (find-clnode "Other Clauses" "if CONDITION CLAUSE") Try to understand these examples: (cl-loop for x in '(1 2 3 4 5 6) collect (* 10 x)) (cl-loop for sublist on '(a b c d e f) collect sublist) (cl-loop for sublist on '(a b c d e f) by 'cddr collect sublist) (cl-loop for (x y . rest) on '(a b c d e f) by 'cddr collect (list x y rest)) (cl-loop for (x y) on '(a b c d e f) by 'cddr collect (list x y)) (cl-loop for a in '(-3 -2 -1 0 1 2 3) for sq = (* a a) if (>= sq 4) collect (list a sq)) Note that this (cl-loop for a in '(1 2 3) for b in '(4 5 6) collect (list a b)) returns ((1 4) (2 5) (3 6)) - `cl-loop' runs the two `for's "in parallel" instead of treating them as nested. This is explained here: (find-clnode "For Clauses" "several" "for" "clauses in a row") One way to make the `for's of the example above behave as nested is by nesting `cl-loop's and using `append' in the outer one instead of `collect', like this: (cl-loop for a in '(1 2 3) append (cl-loop for b in '(4 5 6) collect (list a b)))

9. `cl-defun'

Some functions in eev-kla.el are defined with `cl-defun' to make them easy to test. If you execute this `cl-defun', (cl-defun foo (&key a (b 2) (c (* b 10))) (list a b c)) this defines a function that can be called with the arguments `a', `b', and `c' given in any order. Try: (foo :a 4 :b 5 :c 6) (foo :c 70 :b 80 :a 90) These ":keyword-value" pairs can also be omitted. The (&key a (b 2) (c (* b 10))) means: 1. when there isn't a pair `:a value-for-a', then set a to nil, 2. when there isn't a pair `:b value-for-b', then set b to 2, 3. when there isn't a pair `:c value-for-c', then set 3 to the result of (* b 10). Try: (foo ) (foo :c 6) (foo :b 5 ) (foo :b 5 :c 6) (foo :a 4 ) (foo :a 4 :c 6) (foo :a 4 :b 5 ) (foo :a 4 :b 5 :c 6) The keyword arguments for `cl-defun' are explained here: (find-clnode "Argument Lists" "cl-defun") (find-clnode "Argument Lists" "&key ((KEYWORD VAR) INITFORM SVAR)") (find-clnode "Argument Lists" "&key c d (e 17)") Some functions in eev-kla.el use a trick to make nil arguments be ignored. For example, try: ;; «aaa» (ee-kl-sexp-klt) (ee-kl-sexp-klt :anchor nil) (ee-kl-sexp-klt :anchor "bbb") The source code for `ee-kl-sexp-klt' is here: (find-eev "eev-kla.el" "generate-sexps") (find-eev "eev-kla.el" "generate-sexps" "ee-kl-sexp-klt")

10. The default `c', `d', and `r'

The functions `ee-kl-c', `ee-kl-d', and `ee-kl-r' are defined here: (find-eev "eev-kla.el" "ee-kl-r-c-d") If they receive a `fname' they convert it to an `l-r-c-d' using the ideas in sections 3 and 4, and then they extract the `r', the `c', and the `d' from the `l-r-c-d'. If they don't receive a `fname' they use this as the default: (find-eev "eev-kla.el" "default-args") (find-eev "eev-kla.el" "default-args" "(defun ee-kl-fname")

11. `find-kla-links'

One way to explore these data structures - and to debug what's going on when the functions in eev-kla.el select `c's and `d's that are not the ones that we expected - is to use `find-kla-links'. Try this, and explore the sexps in the buffer that it generates: (find-kla-links "/tmp/FOO/BAR/PLIC/bletch") If you run `M-x find-kla-links' it behaves like this: (find-kla-links (ee-expand (ee-kl-fname))) i.e., it uses the function `(ee-kl-fname)' to determine the current file name. "Intro"s are shown in temporary buffers with no associated files, so running (ee-kl-fname) in this intro returns a directory instead of "real" filename, and some things in `find-kla-links' may not work.

12. The functions that generate sexps

Commands like `M-x kla' only work in files in certain directories... so, before proceeding, try the tests in: (find-eev "eev-kla.el" "a-test") (find-eev "eev-kla.el" "more-tests") `M-x kla' and friends generate a sexp and then "kill it". The functions that generate sexps can be tested using keyword arguments like `:fname', `:anchor', and `:region', but the top-level functions like `M-x kla' can't be tested in that way. Try: (ee-kl-lrcd :fname "/tmp/FOO/BAR/PLIC/bletch") (ee-kl-c :fname "/tmp/FOO/BAR/PLIC/bletch") (ee-kl-r :fname "/tmp/FOO/BAR/PLIC/bletch") (ee-kl-find-cfile :fname "/tmp/FOO/BAR/PLIC/bletch") (ee-kl-find-c :fname "/tmp/FOO/BAR/PLIC/bletch") (ee-kl-sexp-klf :fname "/tmp/FOO/BAR/PLIC/bletch") (ee-kl-sexp-klfs :fname "/tmp/FOO/BAR/PLIC/bletch" :region "rrr") (ee-kl-sexp-kla :fname "/tmp/FOO/BAR/PLIC/bletch" :anchor "aaa") (ee-kl-sexp-klas :fname "/tmp/FOO/BAR/PLIC/bletch" :anchor "aaa" :region "rrr") The `ee-kl-sexp-*'s are the "functions that generate sexps". They are defined here: (find-eev "eev-kla.el" "generate-sexps")

13. Killing and inserting

Commands like `M-x kla' generate a sexp, and then "kill" it using `ee-kl-kill'. See: (find-eev "eev-kla.el" "kill-sexps") (find-eev "eev-kla.el" "ee-kl-kill") (find-eev "eev-kla.el" "ee-kl-kill" "message") (find-eev "eev-kla.el" "ee-kl-kill" "append" "a newline") I usually insert these sexps with `C-y' - i.e., with a plain "yank" - but sometimes I use `M-x kli', that adds a comment prefix; `kli' is an alias for `ee-kl-insert'. See: (find-eev "eev-kla.el" "ee-kl-insert") Note that `ee-kl-insert' is quite primitive, and it supports just a few languages and prefixes... it supposes that the user will redefine it to add more features to it.

14. Bidirectional hyperlinks

(TODO: document this! See:) (find-eev "eev-kla.el" "eekla2")

15. Symlinks

See: (find-eev "eev-kla.el" "ee-kl-expand")