Action Types ​

Action types are Emacs Lisp commands that specify Hyperbole button behaviors. Hyperbole includes a useful set of action types defined within their own namespace and created with the defact macro. See the Hyperbole file, hactypes.el, for examples of how to define your own Hyperbole action types.

Each action type may be used by any category of button: global, explicit, or implicit. The arguments needed by an action type are prompted for at button creation time or in the case of an implicit button, computed when the button is activated. During button activation, the arguments are fed to the action type’s body to achieve the desired result. This body is called the button action.

Hyperbole handles all of this processing transparently. As a user, all you need know is the set of action types that you can work with when creating explicit or global buttons.

Hyperbole action types in alphabetical order are:

annot-bib ​

Follow an internal reference KEY within an annotated bibliography, delimiters = [ ].

completion ​

Insert a completion at point into the minibuffer or a buffer. Unless point is at the end of buffer or if a completion has already been inserted, in which case, delete the completions window.

debbugs-gnu-query ​

Display the discussion of Gnu debbugs ID (a positive integer).

display-boolean ​

Display a message showing the result value of a BOOL-EXPR. Return any non-‘nil’ value or ‘t’.

display-value ​

Display a message showing VALUE (a symbol) and its value. Return any non-‘nil’ value or ‘t’.

display-variable ​

Display a message showing the given variable name and its value.

eval-elisp ​

Evaluate a Lisp expression LISP-EXPR for its side-effects and return any non-nil value.

exec-kbd-macro ​

Execute a KBD-MACRO REPEAT-COUNT times. KBD-MACRO may be a string of editor command characters, a function symbol or nil to use the last defined keyboard macro. Optional REPEAT-COUNT nil means execute once, zero means repeat until error.

exec-shell-cmd ​

Execute a SHELL-CMD string asynchronously. Optional non-nil second argument INTERNAL-CMD inhibits display of the shell command line executed. Optional non-nil third argument KILL-PREV means kill the last output to the shell buffer before executing SHELL-CMD.

exec-window-cmd ​

Asynchronously execute an external window-based SHELL-CMD string.

git-reference ​

Display the git entity associated with REFERENCE and optional PROJECT. See ${hyperb:dir}/DEMO#Git (Local) References for examples.

REFERENCE is a string of one of the following forms:

  • <ref-item>
  • /?<project>/<ref-item>
  • /<project>.

<ref-item> is one of these:

one of the words: branches, commits, or tags ​

the associated items are listed

one of the words: branch, commit, or tag followed by a ’/’ and item id ​

the item is shown

a commit reference given by a hex number, 55a1f0 ​

the commit diff is displayed

a branch or tag reference given by an alphanumeric name, e.g. hyper20 ​

the files in the branch are listed.

If given, PROJECT overrides any project value in REFERENCE. If no PROJECT value is provided, it defaults to the value of hibtypes-git-default-project.

github-reference ​

Display the Github entity associated with REFERENCE and optional USER and PROJECT. See ${hyperb:dir}/DEMO#Github (Remote) References for examples.

REFERENCE is a string of one of the following forms:

  • <ref-item>
  • <user>/<project>/<ref-item>
  • <project>/<ref-item>
  • /<project>.

<ref-item> is one of these:

• one of the words: branches, commits, issues, pulls, or tags ​

the associated items are listed

• one of the words: branch, commit, issue, pull or tag followed by a ’/’, ’-’, or ’=’, and item id ​

the item is shown

• an issue reference given by a positive integer, e.g. 92 or prefaced with GH-, like GH-92 ​

the issue is displayed

• a commit reference given by a hex number, 55a1f0 ​

the commit diff is displayed

• a filename reference given by an alphanumeric name; the file ​

is displayed.

USER defaults to the value of hibtypes-github-default-user. If given, PROJECT overrides any project value in REFERENCE. If no PROJECT value is provided, it defaults to the value of hibtypes-github-default-project.

gitlab-reference ​

Display the Gitlab entity associated with REFERENCE and optional USER and PROJECT. See ../DEMO#Gitlab (Remote) References for examples.

REFERENCE is a string of one of the following forms:

  • <ref-item>
  • <user>/<project>/<ref-item>
  • <project>/<ref-item>
  • /<group>/<project>. or
  • /<project-or-group> (where a group is a collection of projects)

<ref-item> is one of these:

• one of the words: activity, analytics, boards or kanban, branches, commits, contributors, groups, issues or list, jobs, labels, merge_requests, milestones, pages, pipelines, pipeline_charts, members or people or staff, projects, pulls, schedules, snippets, status or tags ​

the associated items are listed

• one of the words: branch, commit(s), issue(s), milestone(s), pull(s), snippet(s) or tag(s) followed by a ’/’, ’-’, or ’=’, and an item-id ​

the item is shown

• an issue reference given by a positive integer, e.g. 92 or prefaced with GL-, like GL-92 ​

the issue is displayed

• a commit reference given by a hex number, 55a1f0 ​

the commit diff is displayed

• a branch or tag reference given by an alphanumeric name, e.g. hyper20 ​

the files in the branch are listed.

USER defaults to the value of hibtypes-gitlab-default-user. If given, PROJECT overrides any project value in REFERENCE. If no PROJECT value is provided, it defaults to the value of hibtypes-gitlab-default-project.

hyp-config ​

Insert Hyperbole configuration and debugging information at the end of the current buffer or within optional OUT-BUF.

hyp-request ​

Insert help for composing a Hyperbole support/discussion message into the current buffer or the optional OUT-BUF.

hyp-source ​

Display a buffer or file from a line beginning with hbut:source-prefix.

kbd-key ​

Execute a normalized KEY-SERIES (series of key sequences) without curly braces. Each key sequence within KEY-SERIES must be a string of one of the following:

  • a Hyperbole minibuffer menu item key sequence,
  • a HyControl key sequence,
  • a M-x extended command,
  • or a valid key sequence together with its interactive arguments.

Return ‘t’ if the sequence appears to be valid, else ‘nil’.

Display an Emacs BOOKMARK. When creating the button, if in Bookmark Menu mode, use the bookmark nearest point as the default. Otherwise, utilize the most recently used bookmark in the current file (bookmark-current-bookmark) as the default, if any.

Display a BUFFER. This type of link is for use in a single editor session. Use link-to-file instead for a permanent link.

Display a DIRECTORY in Dired mode.

Display an online version of a document given by DOC-ID. If the online version of a document is not found in doc-id-indices, signal an error.

Perform an action given by an explicit button, specified by KEY and KEY-FILE.

Display the documentation for FUNC-SYMBOL.

Display a file given by PATH scrolled to optional POINT. If POINT is given, display the buffer with POINT at the top of the window.

Display a file given by PATH scrolled to LINE-NUM.

Perform an action given by an existing global button, specified by KEY.

Display an Info index ITEM cross-reference. ITEM must be a string of the form (filename)item-name. During button creation, completion for both filename and item-name is available. Filename may be given without the .info suffix."

Display an Info NODE. NODE must be a string of the form (filename)nodename. During button creation, completion for both filename and nodename is available. Filename may be given without the .info suffix.

Perform implicit button action specified by KEY, optional BUT-SRC and POINT. BUT-SRC defaults to the current buffer’s file or if there is no attached file, then to its buffer name. POINT defaults to the current point.

When the button with this action type is created, point must be on the implicit button to which to link.

Display a Hyperbole outline cell, given by FILE and CELL-REF, at the top of a window. See the documentation for (kcell:ref-to-id) for valid CELL-REF formats.

If FILE is ‘nil’, use the current buffer. If CELL-REF is ‘nil’, show the first cell in the view.

Display at the top of a window the referent pointed to by LINK. LINK may be of any of the following forms:

  < pathname [, cell-ref] >
  < [-!&] pathname >
  < @ cell-ref >

See the documentation for (kcell:ref-to-id) for valid cell-ref formats.

Display a mail message with MAIL-MSG-ID from optional MAIL-FILE. See the documentation for the variable hmail:init-function for information on how to specify the mail reader to use.

Find REGEXP’s Nth occurrence in SOURCE and display the location at the top of the selected window. SOURCE is a pathname unless optional BUFFER-P is non-nil, then SOURCE must be a buffer name or buffer. Return ‘t’ if found, signal an error if not.

Retrieve and display an Internet rfc given by RFC-NUM. RFC-NUM may be a string or an integer.

Find STRING’s Nth occurrence in SOURCE and display the location at the top of the selected window. SOURCE is a pathname unless optional BUFFER-P is non-nil, then SOURCE must be a buffer name or buffer. Return ‘t’ if found, ‘nil’ if not.

Display the Texinfo node with NODENAME (a string) from the current buffer.

Search web SERVICE-NAME for SEARCH-TERM. Uses hyperbole-web-search-alist to match each service to its search url or Emacs command. Uses hyperbole-web-search-browser-function and the browse-url package to display search results.

man-show ​

Display a man page on TOPIC, which may be of the form ‘<command>(<section>’). Use hpath:display-where setting to control where the man page is displayed.

Follow an optional Org mode <<INTERNAL-TARGET>> back to any first link to it. If INTERNAL-TARGET is nil, follow any internal target link at point. Otherwise, trigger an error.

Follow an optional Org mode LINK to its target. If LINK is nil, follow any link at point. Otherwise, trigger an error.

Follow an optional Org mode radio <<TARGET>> back to any first link to it. If TARGET is nil, follow any radio target link at point. Otherwise, trigger an error.

rfc-toc ​

Compute and display a summary of an Internet rfc in BUF-NAME. Assume point has already been moved to the start of the region to summarize. Optional OPOINT is the point to return to in BUF-NAME after displaying the summary.

text-toc ​

Jump to the text file SECTION referenced by a table of contents entry at point.

www-url ​

Follow a link given by a URL. The variable, browse-url-browser-function, customizes the url browser that is used. Valid values of this variable include browse-url-default-browser and browse-url-generic. See its documentation string for details.

yt-info ​

Display a web page with the metadata information about VIDEO-ID.

yt-play ​

Play a VIDEO-ID from the point specified by optional START-TIME-STRING. If not given, START-TIME-STRING is set to "0s" representing the beginning of the video. START-TIME-STRING is a colon-separated hours:minutes:seconds string, e.g. 1:2:44 (1 hour, two minutes, 45 seconds), where the hours and minutes are optional.

Search Youtube for SEARCH-TERM.

yt-url ​

Return url to play VIDEO-ID from point specified by optional START-TIME-STRING. Return nil if START-TIME-STRING is given but is invalid. If not given, START-TIME-STRING is set to "0s" representing the beginning of the video.

START-TIME-STRING is a colon-separated hours:minutes:seconds string, e.g. 1:2:44 (1 hour, two minutes, 45 seconds), where the hours and minutes are optional.

Action types create a convenient way of specifying button behavior without the need to know how to program. Expert users who are familiar with Emacs Lisp, however, may find that they often want to tailor button actions in a variety of ways not easily captured within a type system. In such cases, hui:ebut-prompt-for-action should be set to ‘t’. This will cause Hyperbole to prompt for an action to override the button’s action type at each explicit button creation. For those cases where the action type is sufficient, a ‘nil’ value should be entered for the action. An action may be any Lisp form that Emacs Lisp can evaluate.