Help

Usage

use Help;

or

import Help;

Warning

The ‘Help’ module is unstable

Functions for producing program help and usage.

Note

You must declare your main function to take an array of string arguments to use the Help module. See the examples below or the technical note about getting arguments from main() for more information on this feature.

Chapel programs can declare main to take arguments like this:

proc main(args: [] string) {
  for a in args {
    // process arguments
    writeln("Got argument ", a);
  }
}

Programs that use this feature might need to expand upon the usage message that explains which config variables are available. To do so, this module includes the printUsage function.

proc printUsage()

Print out a usage message for config variables. This function does not exit. A typical use of this function would be to call it when "--help" or "-h" are encountered when doing custom argument processing. In addition to calling this function, programs with custom argument processing should probably also print out a description of the arguments that they take. Once both help messages have been output, the program would normally exit early - for example, by returning from main.

A typical example might be this program, that accumulates a list of filenames in addition to handling config variable arguments:

use Help;

config const x = 5;

proc main(args: [] string) {
  var filenames: [1..0] string;

  var programName = args[0];

  for a in args[1..] {
    if a == "-h" || a == "--help" {
      writeln("Usage: ", programName, " <options> filename [filenames]");
      printUsage();
      exit(1); // returning 1 from main is also an option
    } else {
      filenames.push_back(a);
    }
  }

  writef("Got filenames = %ht\n", filenames);
  writef("Got configuration variable x = %ht\n", x);
}