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 <UT/UT_DSOVersion.h>
#include <CMD/CMD_Manager.h>
#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
CMDextendLibrary( CMD_Manager *cman )
{
    // 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:

void CMDextendLibrary( CMD_Manager *cman )

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.