HyRolo Settings ​

The files used in any rolo search are given by the hyrolo-file-list variable, whose default value is typically "~/.rolo.otl", in which case, searches scan only your personal rolo file. But you can customize this to include files with variables in them, wildcard patterns and directories, as explained below. Any paths added to this list should be absolute.

If you include file wildcards in paths for this variable and find-file-wildcards is non-nil (the default), then any files matching the pattern (which can include [char-matches] or * wildcards and regular text) when the variable is set will be included in HyRolo searches. For more on wildcards, see Wildcards in the GNU Emacs Manual.

If you include an Environment variable or Emacs Lisp variable with the ${var} format in a path, they also are resolved when hyrolo-file-list is set. Variables with values that include multiple paths, e.g. PATH, are resolved to the first existing entry that matches.

If you include an existing directory (invalid ones are ignored) in your hyrolo-file-list, HyRolo will expand it recursively across all of its files that match hyrolo-file-suffix-regexp. By default, this is Org files (.org), Emacs outlines (.otl), Koutlines (.kotl), or Markdown files (.md). See hpath.el#hpath:expand-list.

Once expanded, if a file in the list does not exist or is not readable, it is dropped. Paths are searched in the order in which they appear in the list. You should leave your personal rolo file as the first entry in the list, since this is the only file to which the HyRolo menu Add command adds entries.

Hyperbole releases earlier than 4.17 used a different filename for the personal rolo. If such a file exists, you will be prompted to rename it whenever the HyRolo system is loaded.

If you want to have HyRolo search your directory of Org files, add the following to your Emacs initialization file:

emacs-lisp
(add-hook ’hyperbole-init-hook
	  (lambda ()
	    (require ’org)
	    (setq hyrolo-file-list (append (hyrolo-initialize-file-list)
                                           (list org-directory)))))

If you use the Big Brother DataBase (BBDB) Emacs package to capture email addresses and store contact information, the rolo automatically works with it. If the BBDB package is loaded before HyRolo, then your bbdb-file of contacts is added as the second entry in hyrolo-file-list and will be searched automatically for any matches by the rolo find commands. Presently there is no support for editing BBDB entries, just finding them.

For finding matches within only BBDB, there are the commands hyrolo-bbdb-fgrep (string finding) and hyrolo-bbdb-grep (regular expression finding). They may be bound to keys if desired.

If you use Google/Gmail Contacts, you can configure the HyRolo to query your Google Contacts for matches. First you must download and install the external google-contacts package using the Emacs Package Manager. Then you must install the non-Emacs GNU Privacy Guard (GPG) package from https://gnupg.org so that the gpg or gpg2 executable is in your command-line search path. Once these are in place, either restart Emacs or use {M-x hyrolo-initialize-file-list RET} to add Google Contacts to your searches.

When you next do a search, you will be prompted for your Google Contacts password and may also have to enter an authorization code that will be displayed on your screen. After authorization, your your information will be cached so that you are not prompted for it again within this Emacs session.

For finding matches within only Google Contacts, there are the commands hyrolo-google-contacts-fgrep (string finding) and hyrolo-google-contacts-grep (regular expression finding). They may be bound to keys if desired.

If you ever need to disable Google Contacts usage, there is a flag, hyrolo-google-contacts-flag, which when set to ‘nil’ disables searching of your Google Contacts.

Below are the rest of the settings available with HyRolo:

hyrolo-highlight-face ​

If textual highlighting is available in your emacs on your current display type, the rolo uses the value of hyrolo-highlight-face as the face which highlights search matches.

hyrolo-kill-buffers-after-use ​

HyRolo file buffers are left around after they are searched, on the assumption that another search is likely to follow within this emacs session. You may wish to change this behavior with the following setting: (setq hyrolo-kill-buffers-after-use t).

hyrolo-save-buffers-after-use ​

After an entry is killed, the modified rolo file is automatically saved. If you would rather always save files yourself, use this setting: (setq hyrolo-save-buffers-after-use nil).

hyrolo-email-format ​

When an entry is being added from within a mail reader buffer, the rolo extracts the sender’s name and e-mail address and prompts you with the name as a default. If you accept the default, it will enter the name and the email address using the format given by the hyrolo-email-format variable. See its documentation if you want to change its value.

hyrolo-hdr-regexp ​

A rolo file may begin with an optional header section which is copied to the match display buffer whenever any matches are found during a search. The start and end lines of this header are controlled by the regular expression variable, hyrolo-hdr-regexp, whose default value is "^===". This allows lines of all equal signs to visually separate matching entries retrieved from multiple files during a single search.

hyrolo-hdr-and-entry-regexp ​

The rolo entry start delimiter is given by the regular expression variable, hyrolo-hdr-and-entry-regexp, whose default value is "^\*+", i.e. one or more asterisks at the beginning of a line.

hyrolo-display-format-function ​

When a rolo search is done, each matching entry is passed through the function given by the variable, hyrolo-display-format-function, before it is displayed. This should be a function of one argument, namely the matching rolo entry as a string. The string that this function returns is what is displayed in the rolo match buffer. The default function used is identity which passes the string through unchanged. If you use the rolo code to search other kinds of record-oriented data, this variable can be used to format each entry however you would like to see it displayed. With a little experience, you can quickly write functions that use local bindings of the rolo entry and file settings to search all kinds of record-oriented data. There is never a need to learn a complicated query language.