(Re)generate: (find-code-c-d-intro)
Source code:  (find-eev "eev-intro.el" "find-code-c-d-intro")
More intros:  (find-eev-quick-intro)
              (find-eval-intro)
              (find-eepitch-intro)
This buffer is _temporary_ and _editable_.
It is meant as both a tutorial and a sandbox.



Note: this intro needs to be rewritten!
Ideally it should _complement_ the material in:
  (find-eev-quick-intro "9. Shorter hyperlinks")
  (find-eev-quick-intro "9.1. `code-c-d'")



1. Avoiding full path names

Suppose that you have downloaded ("psne"-ed) this URL, http://www.lua.org/ftp/lua-5.1.4.tar.gz with `M-x brep' - see: (find-psne-intro) and you unpacked that tarball into the directory ~/usrc/ (I prefer to use that instead of /usr/src/) with: tar -C ~/usrc/ -xvzf $S/http/www.lua.org/ftp/lua-5.1.4.tar.gz Now you can access some directories and files of the unpacked tarball with: (find-fline "~/usrc/lua-5.1.4/") (find-fline "~/usrc/lua-5.1.4/src/") (find-fline "~/usrc/lua-5.1.4/src/lstrlib.c") (find-fline "~/usrc/lua-5.1.4/test/") (find-fline "~/usrc/lua-5.1.4/test/README") (find-fline "~/usrc/lua-5.1.4/doc/") (find-w3m "~/usrc/lua-5.1.4/doc/contents.html") but it's a bit clumsy to have to use the "~/usrc/lua-5.1.4/" every time, so eev provides a nice way to define shorthands. We want to be able to write just this instead of the sexps above, (find-lua51file "") (find-lua51file "src/") (find-lua51file "src/lstrlib.c") (find-lua51file "test/") (find-lua51file "test/README") (find-lua51file "doc/") (find-lua51w3m "doc/contents.html") and here the directory "~/usrc/lua-5.1.4/" became a mnemonic "lua51" in the middle of the names of some functions. We will call these sexps with "lua51" "shorter hyperlinks".

2. Shorter hyperlinks

How can we generate the definitions for `find-lua51file' and `find-lua51w3m' from just the strings "lua51" and "~/usrc/lua-5.1.4/"? Try this: (find-code-c-d "lua51" "~/usrc/lua-5.1.4/") you will get a temporary buffer with a lot of Lisp code - including a definition for `find-lua51file' and another one for `find-lua51w3m'. That Lisp code has not been executed yet; the function `find-code-c-d' is just for debugging, and we can regard it as a hyperlink to the code that this sexp would execute: (code-c-d "lua51" "~/usrc/lua-5.1.4/") So, to define a family of functions including `find-lua51file' and `find-lua51w3m', for a given "mnemonic" - "lua51" in this case - and a given "directory" - "~/usrc/lua-5.1.4/" - we run this: (code-c-d "lua51" "~/usrc/lua-5.1.4/") which generates a block of Lisp code, as a string, and evaluates it. Note: the original (and rather confusing) terminology for the "mnemonic" was "code"; that's why the "c" in `code-c-d'.

3. Extra arguments to `code-c-d'

`code-c-d' supports extra arguments - for example, this works: (find-code-c-d "el" "~/usrc/emacs/lisp/" :info "elisp") Look at the end of the generated code and you will see that it has a definition for `find-elnode' - such that (find-elnode "Constant Variables") is a shorthand (a "shorter hyperlink") for: (find-node "(elisp)Constant Variables") What is important to understand here is how these definitions with extra arguments are structured - so that you will be able to understand the source code when you need to. Both `code-c-d' and `find-code-c-d' are defined with a `&rest' in their argument lists, like this (**NOTE: do not execute these defuns!**): (defun code-c-d (c d &rest rest) ...) (defun find-code-c-d (c d &rest rest) ...) and they both invoke `ee-code-c-d', which does all the template work and returns a big string; `ee-code-c-d' passes its `rest' argument to a recursive function called `ee-code-c-d-rest', and for each one of the supported keywords there is a corresponding function, also recursive; for `:info' it is called `ee-code-c-d-:info'. Their specifications are like this: (defun ee-code-c-d (c d &rest rest) ...) (defun ee-code-c-d-rest (rest) ...) (defun ee-code-c-d-:info (manual &rest rest) ...) and one very non-obvious trick is used to make the code short. When `ee-code-c-d-rest' and `ee-code-c-d-:info' are run they can access the values the `c' and the `d' that were passed to `ee-code-c-d' (due to dynamic scoping), so `c' and `d' do not need to be passed down explicitly as arguments. Try: (find-code-c-d "CODE" "/DIR/" :info "INFO")

4. Other similar functions

See: (find-brxxx-intro) (find-pdf-like-intro) (find-audiovideo-intro) Try: (find-code-pdf "CODE" "FILE.pdf") (find-code-pdf-text "CODE" "FILE.pdf") (find-code-audio "CODE" "FILE.mp3") (find-code-video "CODE" "FILE.mp4")