module xdc.tools.Cmdr

metaonly module xdc.tools.Cmdr

index URL

Command line tool context

XDCscript usage
Individual elements

XDCscript usage meta-domain sourced in xdc/tools/Cmdr.xdc

var Cmdr = xdc.useModule('xdc.tools.Cmdr');

module-wide constants & types

values of type Cmdr.Context//

const Cmdr.SHELL;

const Cmdr.SCRIPT;

per-instance config parameters

var params = new Cmdr.Params// Instance config-params object;

params.tid// = Int 0;

per-instance creation

var inst = Cmdr.create// Create an instance-object(Any cmdmod, params);

per-instance functions

inst.error// Throw an error exception with the specified message(Any msg) returns Any

inst.getopts// Parse command-line arguments into config params(Any inst, Any args) returns Any

inst.info// Output informational message to stdout(Any msg) returns Any

inst.time// Output elapsed time since command start to stderr(Any msg) returns Any

inst.usage// Output command usage message to stderr(Any msg) returns Any

inst.verbose// Set verbose flag as specified(Any flag) returns Any

inst.warning// Output specified warning message to stderr(Any msg) returns Any

enum Cmdr.Context

index URL

XDCscript usage meta-domain

values of type Cmdr.Context

const Cmdr.SHELL;

const Cmdr.SCRIPT;

Instance Config Parameters

index URL

XDCscript usage meta-domain

var params = new Cmdr.Params;

// Instance config-params object

params.tid = Int 0;

config Cmdr.tid // instance

index URL

XDCscript usage meta-domain

var params = new Cmdr.Params;

...

params.tid = Int 0;

Instance Creation

index URL

XDCscript usage meta-domain

var params = new Cmdr.Params;

// Allocate instance config-params

params.config = ...

// Assign individual configs

var inst = Cmdr.create(Any cmdmod, params);

// Create an instance-object

Cmdr.error() // instance

index URL

Throw an error exception with the specified message

XDCscript usage meta-domain

inst.error(Any msg) returns Any

DETAILS

If msg is null or the empty string (""), the message "fatal error" is used.

Cmdr.getopts() // instance

index URL

Parse command-line arguments into config params

XDCscript usage meta-domain

inst.getopts(Any inst, Any args) returns Any

ARGUMENTS

inst — instance with config parameters to set

args — an array of command-line arguments

DETAILS

This function accepts an array of command-line arguments, and uses them to set the values of config parameters in a module instance. Parsing is controlled by the XDC declarations of the instance config params.

USAGE

The following command-line argument syntaxes are supported, following the syntax supported by GNU getopt() and getopt_long():

    -f                a boolean flag with short name
    -f value          a number or string with short name
    -fvalue
    -f=value
    --longname        a boolean flag with long name
    --longname value  a number or string with long name
    --longname=value  a number or string with long name

In addition the following non-standard syntaxes are supported:

    -f:value
    --longnamevalue
    --longname:value

DECLARATION

The long and short names of the config parameter are declared by the @CommandOption() attribute of the XDC spec language. For example to declare a boolean flag with a short name of "-f" and a long name of "--flag", and a default value of false:

     @ CommandOption("f,flag")
     config Bool myFlag = false;

Options of type Bool with no argument are assigned the value "true". The types String and Int can also be used, and always require an argument to be given on the command line.

COMBINING SHORT FLAGS

Short-name options can be combined on the command line where there is no ambiguity, for example the following usages are equivalent:

    -a -b -c -f filename
    -abcf filename

MULTIPLE OCCURRENCES

If the config param is declared as an array, the option may be used multiple times on the command line and each occurence will be recorded. For example the following records all -I options, in order:

    @ CommandOption("I")
    config String includeDirs[] = [];

REQUIRED OPTIONS

If the config param has no default value declared, then it is required on the command line.

RETURNS

The following return values are used to determine whether or not to proceed with the command and, if not, what the exit status of the command should be.

undefined: the command options have been successfully parsed and the command should be run.
0 (zero): the command options have been successfully parsed and the command does not need to be run and should exit with a successful exit status (0).
non-zero integral value: an error occured in the parsing the options and the command should not be run and should exit with a non-zero exit status.

Cmdr.info() // instance

index URL

Output informational message to stdout

XDCscript usage meta-domain

inst.info(Any msg) returns Any

Cmdr.time() // instance

index URL

Output elapsed time since command start to stderr

XDCscript usage meta-domain

inst.time(Any msg) returns Any

Cmdr.usage() // instance

index URL