Commands

The second type of location in hlg is a command.

This type of location creates a command bookmark.

  • Unlike a a link that has a target, a command location has no target:

  • It results into the execution of a bookmarked command.

  • The code can be stored in a script file or in the location field.

  • Because the command location can hold code, this is the only type of location that can have embedded spaces in it if it is inline.

The advantage with command locations is that you can bookmark some frequently used commands. If you regularly type some commands on the terminal, you can take advantage of hlg to save those commands and run them with hlg

Commands can be bookmarked in two ways, either as:

  • Using scripts, or

  • Just typing in the command in the location field.

To indicate that a location is a command location, you enter the colon symbol as the first character in the location field.

Script files

Scripts are written in some programming language but are saved in text files. They are like any other program, except that they are interpreted and not compiled.

Scripts are interpreted programs that are saved in text files. Usually they are commands you often type on the command-line and help you save time by just running a file, instead of repeatedly typing the same commands over and over.

The advantage with a script file is that:

  • It is a text file. You can open it and see its code before you run it.

  • You can record a series of commands, including functions and variables, and save them to disk instead of repeating the commands on the terminal.

  • hlg will only run scripts if they are saved in the "scripts" directory inside the $HLG_HOME directory.

    • You can, however, set another path in the configuration file by changing the "script-dir" option to your chosen path. For example, script-dir = "~/.scripts/"

    • After the colon symbol, you type in the file in which the script is found. So hlg will look for the script with the given name in the "script-dir" as set in the configuration file.

Some examples of script files in the location field are:

time <:tell-time> :bash

This tells hlg that a script called "tell-time" is in the "script-dir" directory, and that bash is its handler.

If you do not provide a handler for a script, the default will be used. The default is set in the "command" option in the configuration file.

You can save scripts of any language that is recognized on your machine. Thus, you need to install the command interpreter for the script you wish to link to in your location field.

The following sample entries all show how different script interpreters are used. The last entry has no handler, so it will use the one specified in the "command" option in the configuration file:

now <:tell-time> :bash
analyze <:stats.py> :python
mail <:mailer.rb> :ruby
keep <:backup>

It is still possible to link to a script like any other linking location.

In that case, you need not use the : symbol to tell hlg that this is a script. Just provide a full path to the script file and the handler like this:

time <~/.scripts/tell-time.sh> :bash

The colon only helps to tell hlg that the named script is in the set script directory, whose entry is “script-dir” in the configuration file.

Inline scripts

Instead of linking to a script file, a command location can contain the code itself.

This is ideal for short, one-liners that you want to run from time to time. Instead of saving that one line in a script file, or typing it on the terminal, you can embed it in the location field of your bookmark entry.

For this to work, instead of entering the script filename, you put an exclamation mark ! after the colon, then followed by the command.

This means that you cannot have a script that begins with an exclamation mark in the "scripts" directory!

When hlg sees a ! after : symbol, it knows that the rest of the location field is a command and so passes it to whichever handler is indicated in the handler field or uses the one in the configuration file with the "command" entry.

So, you can do this:

greeting <:!echo "Hello world!">

This makes hlg to run the default command handler in the configuration file.

By default, the "command" option in your configuration file is set to "bash"

Feel free to change to some other command interpreter.

For example, this script will be run by Python:

greeting <:!name = "Access Computing";print("hello from", name)> :python

This will print: "Hello from Access Computing" using the python handler.

From this example, you can see that:

  • It is possible to create a one-liner complete with variables

  • If a command requires newlines, you use a semicolon to represent a newline

  • This means that in a language like Python which is sensitive to spaces and indentations, do not add any space after a semicolon unless you want to create a conditional block or a function block

Scripts that you enter in the location field must not be interactive in nature: they need to do whatever you set them to do and be done with. In other words, the type of script that can be run by a crone job are the ones suitable for bookmarking.

For instance, if you open in your default bookmarks that ship with hlg, you will see one inline script, “time”, for showing the time of the day.

Limitations of command

A command cannot work with references

  • A command bookmark cannot have references in them. So if your scripting language relies on a token that looks like a reference, that is @{..} consider placing it in a script file rather than typing it inline.

  • Conversely, a a reference is not allowed to target a command. References are only meant to target link locations and not commands. It would be strange if a bookmark tried to resolve to a target with a command in it, especially if it has other code in it.

Only inline scripts can have spaces

Only inline scripts are allowed to have embedded spaces in them. A command that runs a script is treated just like any other link, so it must not have spaces in it.

After all, a script filename is taken as a URL so it must not have embedded spaces. If the filename has spaces, consider using dashes (--) or underscores (_) to separate words.

hlg does not check for command syntax

While hlg can bookmark a command, whether inline or in a script file, it does not check for the syntax or semantic errors.

  • Syntax errors are those errors that have to do with the correctness of the language, that is the grammar of the language you are using.

  • On the other hand, semantic errors have to do with the logic of the command. While the syntax may be okay, yet the meaning of the commands may not be what you intended.

hlg had no way of knowing what’s syntactically correct or not. This is the job of the command interpreter you set in the handler field.