Implicit Button Link Types ​

If you understand Emacs regular expressions (see Syntax of Regular Expressions in the GNU Emacs Manual), you can create new implicit button types without understanding how to program in Emacs Lisp, aside from the instructions provided here.

A call to the defil macro of the form:

(defil TYPE START-DELIM END-DELIM TEXT-REGEXP LINK-EXPR &optional START-REGEXP-FLAG END-REGEXP-FLAG DOC)

will create a new Hyperbole implicit button link TYPE (an unquoted symbol), recognized in a buffer via START-DELIM and END-DELIM (strings) and the TEXT-REGEXP pattern between the delimiters. With optional START-REGEXP-FLAG true, START-DELIM is treated as a regular expression. Similarly, a true value of END-REGEXP-FLAG treats END-DELIM as a regular expression. Hyperbole automatically creates a doc string for the type but you can override this by providing an optional DOC string.

When the Action Key is pressed in a buffer between the start and end delimiters and the text in-between matches to TEXT-REGEXP, then the button is activated and does one of four things with LINK-EXPR:

  1. executes it as a brace-delimited key series;
  2. displays it in a web browser as a URL;
  3. displays it as a path (possibly with trailing colon-separated line and column numbers);
  4. invokes a function or action type of one argument, the button text (sans the function name if an Action Button), to display it.

Prior to activation, for the first three kinds of LINK-EXPR, a replace-match is done on the expression to generate the button-specific referent to display. Thus, either the whole button text (‘\\&’) or any numbered grouping from TEXT-REGEXP, e.g. ‘\\1’, may be referenced in the LINK-EXPR to form the link referent.

Here is a sample use case. Let’s create a button type whose buttons perform a grep-like function over a current repo’s git log entries. The buttons use this format: [<text to match>].

The following defines the button type called search-git-log with a a key series action surrounded by braces:

(defil search-git-log "[<" ">]" ".*" "{M-: (hypb:fgrep-git-log \"\\&\") RET}")

or this simpler version skips the explicit text substitution (\\\\&) and instead uses the function that takes the button text as an argument:

(defil search-git-log "[<" ">]" ".*" #’hypb:fgrep-git-log)

Place point after one of the above expressions and evaluate it with {C-x C-e} eval-last-sexp to define the implicit button type. Then if you have cloned the Hyperbole repo and are in a Hyperbole source buffer, an Action Key press on a button of the form:

;; [<test release>]

will display one line per commit whose change set matches ’test release’. An Action Key press on any such line will then display the commit changes.

If you don’t mind extra text for every button, you could instead use Action Buttons of the form: <hypb:fgrep-git-log "string"> to do the same thing without any special definitions.