module xdc.tools.Cmdr

metaonly module xdc.tools.Cmdr

index URL

Command line tool context

XDCscript usage
XDCspec declarations
Individual elements

XDCspec summary sourced in xdc/tools/Cmdr.xdc

metaonly module Cmdr { ...

instance: ...

XDCscript usage meta-domain

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.context// = Cmdr.Context Cmdr.SHELL;

params.socket// = Any null;

params.tid// = Int 0;

per-instance creation

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

per-instance functions

inst.error// ( Any msg ) returns Any

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

inst.info// ( Any msg ) returns Any

inst.read// ( ) returns Any

inst.time// ( Any msg ) returns Any

inst.usage// ( ) returns Any

inst.verbose// ( Any flag ) returns Any

inst.warning// ( Any msg ) returns Any

inst.write// ( Any s ) returns Any

XDCspec declarations sourced in xdc/tools/Cmdr.xdc

package xdc.tools;

metaonly module Cmdr {

module-wide constants & types

enum Context// {

SHELL,

SCRIPT

};

instance:

per-instance config parameters

config Cmdr.Context context// = Cmdr.SHELL;

config Any socket// = null;

config Int tid// = 0;

per-instance creation

create// Create an instance-object( Any cmdmod );

per-instance functions

function error// ( msg );

function getopts// Parse command-line arguments into config params( inst, args );

function info// ( msg );

function read// ( );

function time// ( msg );

function usage// ( );

function verbose// ( flag );

function warning// ( msg );

function write// ( s );

}

enum Cmdr.Context

index URL

XDCscript usage meta-domain

values of type Cmdr.Context

const Cmdr.SHELL;

const Cmdr.SCRIPT;

per-instance config parameters

index URL

XDCscript usage meta-domain

var params = new Cmdr.Params;

// Instance config-params object

params.context = Cmdr.Context Cmdr.SHELL;

params.socket = Any null;

params.tid = Int 0;

config Cmdr.context // per-instance

index URL

XDCscript usage meta-domain

var params = new Cmdr.Params;

...

params.context = Cmdr.Context Cmdr.SHELL;

config Cmdr.socket // per-instance

index URL

XDCscript usage meta-domain

var params = new Cmdr.Params;

...

params.socket = Any null;

config Cmdr.tid // per-instance

index URL

XDCscript usage meta-domain

var params = new Cmdr.Params;

...

params.tid = Int 0;

per-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( ) // per-instance

index URL

XDCscript usage meta-domain

inst.error( Any msg ) returns Any

Cmdr.getopts( ) // per-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, and a Javascript exception will be raised if it is omitted.

Cmdr.info( ) // per-instance

index URL

XDCscript usage meta-domain

inst.info( Any msg ) returns Any

Cmdr.read( ) // per-instance

index URL

XDCscript usage meta-domain

inst.read( ) returns Any

Cmdr.time( ) // per-instance

index URL

XDCscript usage meta-domain

inst.time( Any msg ) returns Any