Function: defal

defal is a macro defined in hbut.el.

Signature

(defal TYPE LINK-EXPR &optional DOC)

Documentation

Create Hyperbole action button link TYPE (an unquoted symbol).

Buttons of the type look like: <TYPE link-text> where link-text is substituted into LINK-EXPR as grouping 1 (specified either as %s or \\1). Hyperbole automatically creates a doc string for the type but you can override this by providing an optional DOC string.

LINK-EXPR may be:
  (1) a brace-delimited key series;
  (2) a URL;
  (3) a path (possibly with trailing colon-separated line and column numbers);
  (4) or a function or action type of one argument, the button text sans the
      function name.

Prior to button 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, substituting
%s or \\1 in the LINK-EXPR for the text/label from the button.

For the fourth kind, LINK-EXPR is a function of one argument which is either the full button text or in the case of an Action Button, the text following the function name at the start of the button.

Here is a sample use case. If you use Python and have a PYTHONPATH environment variable setup, then pressing C-x C-e (eval-last-sexp) after this expression:

   (defal pylib "${PYTHONPATH}/%s")

defines a new action button link type called pylib whose buttons take the form of:

   <pylib PYTHON-LIBRARY-FILENAME>

and display the associated Python libraries (typically Python source files). Optional colon separated line and column numbers may be given as well.

Therefore an Action Key press on:

   <pylib string.py:5:7>

would display the source for "string.py" (wherever it is installed on your system) from the Python standard library with point on the fifth line at the seventh character.

For more flexible regular expression-based link type creation, see defil. For the most general implicit button type creation, use defib.

Aliases

ibtype:create-action-link-type

Source Code

;; Defined in ~/.emacs.d/elpa/hyperbole-20260414.325/hbut.el
(defmacro defal (type link-expr &optional doc)
  "Create Hyperbole action button link TYPE (an unquoted symbol).
Buttons of the type look like: <TYPE link-text> where link-text is
substituted into LINK-EXPR as grouping 1 (specified either as %s
or \\\\1).  Hyperbole automatically creates a doc string for the
type but you can override this by providing an optional DOC
string.

LINK-EXPR may be:
  (1) a brace-delimited key series;
  (2) a URL;
  (3) a path (possibly with trailing colon-separated line and column numbers);
  (4) or a function or action type of one argument, the button text sans the
      function name.

Prior to button 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, substituting
%s or \\\\1 in the LINK-EXPR for the text/label from the button.

For the fourth kind, LINK-EXPR is a function of one argument which is
either the full button text or in the case of an Action Button, the
text following the function name at the start of the button.

Here is a sample use case.  If you use Python and have a
PYTHONPATH environment variable setup, then pressing
\\[eval-last-sexp] after this expression:

   (defal pylib \"${PYTHONPATH}/%s\")

defines a new action button link type called `pylib' whose buttons
take the form of:

   <pylib PYTHON-LIBRARY-FILENAME>

and display the associated Python libraries (typically Python source
files).  Optional colon separated line and column numbers may be given
as well.

Therefore an Action Key press on:

   <pylib string.py:5:7>

would display the source for \"string.py\" (wherever it is installed
on your system) from the Python standard library with point on the
fifth line at the seventh character.

For more flexible regular expression-based link type creation, see
`defil'.  For the most general implicit button type creation,
use `defib'."
  (declare (debug (&define name [&or stringp lambda-list]
                           [&optional stringp])))
  (when type
    `(defil ,type "<" ">" (format "%s\\s-+\"?\\([^\t\n\r\f'`\"]+\\)\"?" ',type)
       ,link-expr nil nil ,doc)))   ; Match the doc string, if present.