The handler

The handler field designates the program that handles this bookmark’s location.

Hence, a program must be able to open the protocol or file type in the location field.

Strictly speaking, a handler is a required field.

It is optional if:

The location field has an address, or command that is used by other handlers;
In other words, the protocol or URL scheme is common that hlg can deduce its handler from the way the location is entered.
This is true with locations of the link type whose addresses show the scheme being used.

hlg classifies handlers into four common groups:

A browser for dealing with web pages;
A file manager for filesystem paths;
A command for executing scripts; and
Programs for handling file extensions.

A handler field is denoted by a colon, then the name of the program, then optionally the arguments to be passed to the handler.

For example, :firefox

You can choose to enter the full path to the program executable or simply enter the name of the program as you would type it on your terminal. hlg uses the $PATH environment variable to resolve names of programs with no absolute paths.

If you enter a program that hlg fails to find, it will inform you of this and exit. It will advise you to consider installing the program or else providing the full path to the program if you are sure the program is installed.

How hlg deals with empty handler fields

Unlike the the bookmark name and the location fields which are both mandatory for a bookmark entry, a handler field is optional only if:

This is because these types of locations rely on URL schemes to function.

Of course, we can also leave out a handler field with reference locations as they often resolve to the name of another bookmark, such that the targeted bookmark’s location will provide a link that hlg will use.

Even with links, it may not always be the case that the handler will be correctly deduced. This is the case with a link that targets a resource which is a file.

So, though the handler field is optional, you are advised to provide it when it is not obvious from the location field which program will resolve that location.

You can also enter a program in the handler field simply because you do not want to use the program provided as the location’s default handler, as will be demonstrated in the example below.

hlg uses the so-called “default handlers” that are provided for each class of handler in the configuration file. These classes are for the web browser, file manager and the command interpreter.

As for file extensions, hlg provides an auxiliary configuration file for file formats which is known as the formats file. This file comes with a list of programs along with the possible file extensions the individual programs can handle. You are advised to add new programs along with the extensions you often use to help hlg deal with empty handler fields that these bookmark entries may have, but with detectable extensions in their location fields.

Examples of handler field entries

For example, this entry:

shop <https://www.amazon.co.uk/>

means that:

hlg will use the default handler as the handler field is empty; and
As the protocol is http, hlg will choose to pick the default handler for web-browsing.

This rule applies even for command locations:

You must provide a program that runs your scripts,
Otherwise, bash will be used.

Even though you have a default handler, you can override it by entering another one in the handler field. For example, if your browser is set to firefox in the configuration file, you can choose to use another browser in the handler field. This may be because the bookmarked page is better presented in the chosen browser, or simply to demonstrate that you have a wide pool of choices for browsers to use for different locations.

Using another handler to override the default

shopping <https://www.amazon.co.uk/>
audible <https://audible.com/> :opera
mail <https://mail.google.com/> :brave

The first bookmark, “shoping” uses the default browser while the other two will use the provided handlers to override the default.

This demonstrates that it is not always the case that when you set a default handler, you are forced to use it.

You are thus advised to use handlers, and only leave them when you want to rely on what is set in the configuration file or its auxiliary, the formats file.

Command-line processing

Some handlers require command-line arguments to run. Command-line options help to change the behavior in which a program runs.

In that case, hlg accommodates command-line options-processing for a handler when placed inside parentheses like (this).

The command-line options are attached to the name of the handler. Which means, the handler field is structured as follows:

The colon to indicate that this is a handler field;
The name of the program, and
The pair of parentheses with a list of command-line options inside.

For example:

hlg <https://hlg.access-computing.com/> :w3m(-Ws)

In this case, w3m has got two command line options passed to it in an abbreviated form, the -W and -s short options.

Just enter the options as you would on a terminal:

Prepend the dashes or single dashes for long or short options, respectively.
Supply any required arguments to these options.
Remember that all these options are entered inside parentheses.
Options are separated by whitespace.

It is possible to supply arguments to a default handler. So even if you did not enter the handler in the handler field, you can still pass the arguments to it.

You do so by first typing the colon symbol (:) to indicate an entry in the handler field.
Then you place the parentheses next to the colon.
Finally, you enter the command-line options inside the parentheses like this: `:(-c -w )

For command locations, if you leave out the handler field, and decide to pass in some options to your command interpreter, you do not have to pass the -c option. It is already assumed that it is the first command-line option to a command interpreter. Just pass in other options and not the c option.