The COMMAND_LINE_ARGS routine was introduced in IDL 6.2, allowing IDL programs to access command line args passed to IDL when starting it. For example, to pass command line arguments into the MYPROGRAM routine, call IDL like below:

$ idl -e "myprogram" -args a b c

Then, in MYPROGRAM, the command line arguments could be retrieved with:

args = command_line_args()

The args string array would contain “a”, “b”, and “c”. To make it more convenient to launch IDL this way, you can create a script that calls IDL in the proper way, passing arguments of the script to arguments listed after the -args in the IDL call. If you name the wrapper script myprogram also, your calls would look like:

$ myprogram a b c

But, suppose you wanted your routine to have command line switches like:

$ myprogram --verbose --header=test.hdr test.dat

Then you had to parse the args received from COMMAND_LINE_ARGS yourself. The mg_options class simplifies this parsing and adds several other conveniences.

The mg_options class can be instantiated with the optional APP_NAME and VERSION properties:

opts = obj_new('mg_options', app_name='mgunit', version='1.0.0beta')

Next, add options using the addOption method:

opts->addOption, 'color', 'c', /boolean, $
                 help='produce color output on STDOUT'
opts->addOption, 'filename', $
                 help='specify a log filename'
opts->addOption, 'gui', 'g', /boolean, $
                 help='start a GUI to run the tests'
opts->addOption, 'html', 'm', /boolean, $
                 help='produce HTML output'

The two positional parameters of addOption are the full name of the option (used with “–“) and an optional short name (used with just a single “-“). The help keyword gives a description of the option displayed when the help option is given (the help option is automatically created for you). The boolean keyword indicates that the option does not take a value, it’s presence indicates it is “on”.

Next, add the positional parameters:

opts->addParams, [0, -1]

This indicates the minimum and maximum number of positional parameters, with -1 indicating there is no maximum number.

After defining all the options and parameters, the arguments to the program can be parsed:

opts->parseArgs, error_message=errorMsg

The ERROR_MESSAGE keyword will contain parse error message if they occur, otherwise it will be an empty string.

After the parsing, use the get method to retrieve the value of the parameters:

if (errorMsg eq '') then begin
  params = opts->get(/params, n_params=nparams)

  if (nparams gt 0L && ~opts->get('help')) then begin
    filename = opts->get('filename', present=filenamePresent)
    if (filenamePresent) then begin
      mgunit, params, $
              color=opts->get('color'), $
              filename=opts->get('filename'), $
              gui=opts->get('gui'), $
              html=opts->get('html')
    endif else begin
      mgunit, params, $
              color=opts->get('color'), $
              gui=opts->get('gui'), $
              html=opts->get('html')
    endelse
  endif
endif else begin
  message, errorMsg, /informational, /noname
endelse

Don’t forget to free the options object when finished:

obj_destroy, opts

A help option is automatically created to display information about the options:

$ mgunit --help
usage: mgunit [options] ...

options:
  --color, -c          produce color output on STDOUT
  --filename=FILENAME  specify a log filename
  --gui, -g            start a GUI to run the tests
  --help, -h           display this help
  --html, -m           produce HTML output
  --version            display version information

Because we set the APP_NAME and VERSION properties when instantiating the options object, the version option gives useful information:

$ mgunit --version
mgunit 1.0.0beta

So the command line options can be used as follows:

$ mgunit --color --filename=unittests.txt gpu_alltests_uts

This is translated in the wrapper to:

IDL> mgunit, 'gpu_alltests_uts', /color, filename='unittests.txt'

Here’s the source code (docs). You will need the hash table, array list, and abstract list classes also.