HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Extending hscript: New Command

hscript is a command-line interpreter interface for scripting actions in Houdini. The built-in Houdini commands can listed by typing help in the textport. This section will show you how to add your own custom commands to Houdini.

As an example, suppose we want to add the command date which simply prints out the current date. We want date to behave as follows:

/ -> date
Mon Mar  2 15:16:18 EST 2009

For pedagogical reasons, let's also make date accept an option -s num_spaces which left pads the returned date string with the specified number of spaces.

/ -> date -s 5
     Mon Mar  2 15:16:18 EST 2009

The command can be implemented with the following C++ code:

/*
* simple example of adding a 'date' command to Houdini
*/
#include <CMD/CMD_Args.h>
#include <time.h>
/*
* cmd_date()
* callback function for the new 'date' command
*/
static void
cmd_date( CMD_Args &args )
{
char *time_string;
time_t time_struct;
int i;
// the 's' option left pads with some spaces,
// just for an example
if( args.found('s') )
{
int num_spaces = args.iargp( 's' );
for( i = num_spaces; i>0; i-- )
args.out() << " ";
}
// call the standard C function 'time'.
// see 'man time' for details
time_struct = time(0);
time_string = ctime( &time_struct );
// printout the date to the args out stream
args.out() << time_string;
}
/*
* this function gets called once during Houdini initialization
*/
void
{
// install the date command into the command manager
// name = "date", options_string = "s:",
// callback = cmd_date
cman->installCommand("date", "s:", cmd_date);
}

When Houdini loads the dso during start-up, it looks for the function named:

and calls this function during initialization. The function is passed a pointer to the Houdini command manager, which is the object we will use to install our new command. The call to:

cman->installCommand("date", "s:", cmd_date );

actually installs the date command. The first argument specifies the new command's name. The second argument specifies the option string that the new command will take. This string is similar to the option parsing string of the standard C function getopt. The string contains the option letters that the new command will recognize. If the letter is followed by a colon, the option is expected to have an argument (use two or three colons to indicate two or three arguments respectively).

The last argument is the name of the C++ callback function for the new command, in this case cmd_date.

The callback function should be declared static to avoid possible name clashes with other Houdini functions. The callback takes one argument, a reference to a CMD_Args object. This object has two main functions: to provide access to the command line options for the command and to provide an output stream so you can return output to the Houdini shell.

In this example, we used the found method to check if date was called with the -s option. We then use the iargp method to get an integer version of the argument of this option (the command manager knows that -s expects one argument because we used an option string of "s:" when we installed the command). Similar methods exist for getting a floating point representation (fargp) and string representation (argp) of the argument. Please refer to the CMD_Args.h header file for more details.

Create a file called "command.help" anywhere within the Houdini search path (i.e. /usr/local/houdini/help, $HOME/houdini/help, $HIP/houdini/help, etc.) to contain the help for your commands. A help entry should start with a line containing the name of the function followed by indented lines containing the help text. For example:

date
prints the current date
USAGES
1. date [-s <pad>]
This command prints with current date optionally padding the output by
<pad> spaces.
OPTIONS
-s <pad>
specify a number of spaces to pad the output on the left

All help files found in the Houdini search path are all merged together when displaying help.