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

Note: this intro needs to be rewritten!
It expands an idea that was mentioned briefly at:
  (find-eev-quick-intro "3.1. Non-elisp hyperlinks")

1. Introduction

We saw in (find-psne-intro) (find-psne-intro "M-x brep") (find-psne-intro "M-x brfl") (find-psne-intro "`browse-url' and friends") that we can use `M-x brep' to download local copies of files from the internet, and that `M-x brfl' on a URL runs `find-fline' on the local copy of that URL. `brep' and `brfl' are "`browse-url'-like functions" defined by eev; we will refer to them, and to other such functions, as "brxxx-functions". Every brxxx-function is an interactive interface to some "base function"; for `brep' and `brfl' we have: brxxx-function base function -------------- ------------- brep find-psne-links brfl find-fline What we will see here is how `code-brfile' and `code-brurl' - which are somewhat similar to `code-c-d' - can be used to define brxxx-functions from base functions.

2. A first example

Let's define two trivial base functions, one that expects a URL, and another one that expects a file name: (defun foo-url (url) (format "Got URL: %s" url)) (defun foo-file (filename) (format "Got filename: %s" filename)) Note that they don't do much - they just return explanatory strings. These two calls, (code-brurl 'foo-url :remote 'brshowu :local 'brshowul) (code-brfile 'foo-file :local 'brshowfl) define three brxxx-functions: `brshowu' and `brshowul' for the base function `foo-url', and `brshowfl' for the base function `foo-file'. You can inspect the definitions by running these sexps, (find-code-brurl 'foo-url :remote 'brshowu :local 'brshowul) (find-code-brfile 'foo-file :local 'brshowfl) and you can test what `foo-url', `foo-file', `brshowu', `brshowul', and `brshowfl' do by running the sexps below. (foo-url "http://a/b") => "Got URL: http://a/b" (foo-file "/c/d/e/f") => "Got filename: /c/d/e/f" (brshowu "http://a/b") => `(foo-url "http://a/b") -> "Got URL: http://a/b"' (brshowul "http://a/b") => `(foo-url "file:///home/edrx/snarf/http/a/b") -> "Got URL: file:///home/edrx/snarf/http/a/b"' (brshowfl "http://a/b") => `(foo-file "/home/edrx/snarf/http/a/b") -> "Got filename: /home/edrx/snarf/http/a/b"' Now let's go to what matters. Put the point on the URL below, and run `M-x brshowu', `M-x brshowul' and `M-x brshowfl': http://a/b you will see that `brshowu', `brshowul', and `brshowfl' can be called interactively, and when they are called interactively they use as their argument either the URL around point, or something obtained from it - the local file name or a local URL associated to that URL.

3. The conversions

One underlying idea behind all this is that we have two conversion functions, one from URLs to file names, and another from (absolute) file names to URLs starting with "file:///". They work like this: http://a/b -> $S/http/a/b -> file:///home/edrx/snarf/http/a/b /tmp/c -> file:///tmp/c try: (ee-url-to-fname "http://a/b") (ee-fname-to-url "/tmp/c") (ee-url-to-local-url "http://a/b") Now execute the sexps below (with `M-2 M-e') to examine the code that calls to `code-brurl' and `code-brfile' generate and execute: (find-code-brurl 'foo-url :remote 'brshowu :local 'brshowul) (find-code-brfile 'foo-file :local 'brshowfl)

4. Naming conventions for brxxx-functions

By convention, each name for a brxxx-function is composed of a prefix, a stem, and a suffix. The prefix is always "br", the stem is a mnemonic for the base function, and the suffix is either "", "l", or "d", meaning: "" - use the URL without changes "l" - use the local copy "d" - dired variation (see below) Here are the stems for some of the brxxx-functions defined by eev: Base function receives stem ------------- -------- ---- find-psne-links URL "ep" browse-url-firefox URL "m" find-googlechrome URL "g" find-w3m URL "w" find-fline file name "f" find-audio file name "audio" find-video file name "video" find-xpdf-page file name "xpdf" find-evince-page file name "evince" find-xdvi-page file name "xdvi" find-djvu-page file name "djvu" find-pdf-text file name "pdftext" find-djvu-text file name "djvutext" In our example with `foo-url' and `foo-file' we had: Base function receives stem ------------- -------- ---- foo-url URL showu foo-file file name showf

5. Calling `code-brurl' and `code-brfile'

(code-brurl '<U-function> :remote 'br<stem> :local 'br<stem>l :dired 'br<stem>d) \---------------/ \---------------/ \----------------/ optional optional optional (code-brfile '<F-function> :local 'br<stem>l :dired 'br<stem>d) \---------------/ \----------------/ optional optional This, like many other parts of eev, is a hack with a very concise calling syntax - so we will see an example first, and then dissect it to understand precisely how it works. If you are curious about the inspirations behind it, here they are: (find-code-c-d-intro) (find-code-c-d-intro "find-code-c-d") (find-code-c-d-intro "Extra arguments") (find-enode "Browse-URL")

6. The dired variation

In dired mode each line corresponds to a file