Semantics : UsageDeclaration

UsageDeclaration  ::=  usage { IDENTIFIER = Expr ; )+ }

Used by:  

The usage declaration helps to document the usage of the script. It serves two purposes:

  1. If -? or --help is specified, or if the number of arguments is less than the required number, the JudoScript engine displays the usage information.
  2. For a JudoScript companion tool extracts usage information from scripts for indexing and documentation purposes.

The usage information, if specified, is stored in a predefined constants, #usage , as a hashtable. Its content is a list of comma-separated name=value pairs. The names can be anything, but there are a number of predefined attributes:
NameSourceDescription
minArgs user The minimum number of arguments (excluding options). If not specified, assumed 0. If specified and greater than 0, and the actual argument number is less than that, JudoScript prints out the usage help message and exits.
args user The command-line arguments. Can use any format but do not include the program name.
desc user The description of this script. Can be anything.
author user The author(s). Use comma to separate multiple names.
created user The created date, in the format of 2002-08-18.
lastMod user The last modified date, in the format of 2002-08-18.
prog parser The script name. The same as the predefined constant #prog .
firstLine parser The first line number for the usage block.
lastLine parser The last line number for the usage block.

Every script can have one usage block, but only the main one is stored; the usage blocks of included scripts are ignored. The usage block should appear at the beginning of a script, although it can appear anywhere.

The system function obtainUsage() retrieves the usage information for the specified script.