The Helga Shell
The Helga Shell is an implementation of version 1.0 of the Helga Language Specification in the Tcl programming language. It provides all functionality as laid out by the Language Specification. All Helga data and functionality are accessed through the Helga Shell, whether you're working on the command line directly with the Shell or through the Web App. As you work in the Helga Web App, it makes calls directly to the Helga Shell.
This document serves as an introduction on how to access and use the Helga Shell. The Helga Shell is written as a Tcl package, so that in writing Helga scripts you are able to use both standard Tcl commands and Helga-specific commands. The Helga Shell v1.0 uses Tcl 8.5. For information on the Tcl commands available, see the Tcl documentation at http://www.tcl.tk/man/tcl8.5/TclCmd/contents.htm. For information on the Helga commands available and their usage, consult the separate Helga Command Reference.
Invoking the Helga shell
There are three ways of invoking the Helga Shell:
- Live via the "tclsh" command - this will initiate the Tcl shell, and you must manually load the Helga Tcl libraries:
$ tclsh % package require helga 3.0 />
You may avoid manually loading the Helga Tcl library by placing the line "package require helga" in the file ~/.tclshrc on your Helga server.
- With a script via the "tclsh <filename>" command - this command would run the contents of a file named "<filename>" as a Tcl script. If the first Tcl command of your script is "package require helga", you will be able to run it as a Helga script - a series of Helga commands. Any additional arguments can be made available to the script by placing them after <filename>.
- Via the "helgash" script. This is the method used by the Web App, and is generally too cumbersome to be desirable for use over methods #1 and #2. It is not overly complex, though, and there's nothing stopping developers from writing tools to make use of the Shell via this method. More information on this in the Web App Documentation.
Commands
The Helga Tcl library creates new Tcl commands for the Helga Shell. Throughout this documentation you may see the words "command" and "proc", the Tcl word for a function or procedure, used interchangeably.
The Helga Tcl library contains many commands; only the most commonly used ones are exposed directly to the global namespace. The rest can be found in the ::helga namespace and its associated subnamespaces. Commands exposed globally should be prefaced with an "h" to avoid conflict or confusion with preexisting core Tcl commands.
For complete documentation of all Helga commands please refer to the separate Helga Command Reference.
Common Arguments
These arguments are not supported by all commands, but many commands need similar functionality. For ease of use these standards are used:
- -tags : Filters output by the tags stored with returned assets or tasks. The following argument must be either a tag or a comma-separated list of tags. If a command returns a list of either assets or tasks, it should support the -tags arg. There are several Helga commands available to make this task easier for developers. Refer to the Helga Code Notes for more information on these commands.
- -v : Verbose output mode; print additional text from the resulting command. For many commands, this is useful if you want your output to be human readable, but not useful if you want to feed the output of one command into the input for another, i.e. in a Helga script.
- -web : Output in web mode. Given this argument a command will return its output in a web-parseable JavaScript object or array.
Refer to the Helga Command Reference for more information on exactly how each command implements these arguments.
