1    /* --COPYRIGHT--,EPL
     2     *  Copyright (c) 2008 Texas Instruments and others.
     3     *  All rights reserved. This program and the accompanying materials
     4     *  are made available under the terms of the Eclipse Public License v1.0
     5     *  which accompanies this distribution, and is available at
     6     *  http://www.eclipse.org/legal/epl-v10.html
     7     * 
     8     *  Contributors:
     9     *      Texas Instruments - initial implementation
    10     * 
    11     * --/COPYRIGHT--*/
    12    /*!
    13     *  ======== Cmdr ========
    14     *  Command line tool context
    15     */
    16    metaonly module Cmdr {
    17    
    18        enum Context { SHELL, SCRIPT };
    19    
    20    instance:
    21    
    22        config Context context = SHELL;
    23        config Int tid = 0;
    24        config Any socket = null;
    25        
    26        create(Any cmdmod);
    27        
    28        function error(msg);
    29    
    30        /*!
    31         * Parse command-line arguments into config params.
    32         *
    33         * This function accepts an array of command-line arguments, and
    34         * uses them to set the values of config parameters in a module
    35         * instance. Parsing is controlled by the XDC declarations of the
    36         * instance config params.
    37         *
    38         * @a(Usage)
    39         * The following command-line argument syntaxes are supported,
    40         * following the syntax supported by GNU getopt() and getopt_long():
    41         *
    42         * @p(code)
    43         *   -f                a boolean flag with short name
    44         *   -f value          a number or string with short name
    45         *   -fvalue
    46         *   -f=value
    47         *   --longname        a boolean flag with long name
    48         *   --longname value  a number or string with long name
    49         *   --longname=value  a number or string with long name
    50         * @p
    51         *
    52         * In addition the following non-standard syntaxes are supported:
    53         * @p(code)
    54         *   -f:value
    55         *   --longnamevalue
    56         *   --longname:value
    57         * @p
    58         *
    59         * @a(Declaration)
    60         * The long and short names of the config parameter are declared
    61         * by the @CommandOption() attribute of the XDC spec language. For
    62         * example to declare a boolean flag with a short name of "-f" and
    63         * a long name of "--flag", and a default value of false:
    64         * @p(code)
    65         *    @ CommandOption("f,flag")
    66         *    config Bool myFlag = false;
    67         * @p
    68         *
    69         * Options of type Bool with no argument are assigned the value
    70         * "true". The types String and Int can also be used, and always
    71         * require an argument to be given on the command line.
    72         *
    73         * @a(Combining Short Flags)
    74         * Short-name options can be combined on the command line where there
    75         * is no ambiguity, for example the following usages are equivalent:
    76         * @p(code)
    77         *   -a -b -c -f filename
    78         *   -abcf filename
    79         * @p
    80         *
    81         * @a(Multiple Occurrences)
    82         * If the config param is declared as an array, the option may
    83         * be used multiple times on the command line and each occurence
    84         * will be recorded. For example the following records all -I
    85         * options, in order:
    86         * @p(code)
    87         *   @ CommandOption("I")
    88         *   config String includeDirs[] = [];
    89         * @p
    90         *
    91         * @a(Required Options)
    92         * If the config param has no default value declared, then it
    93         * is required on the command line, and a Javascript exception will
    94         * be raised if it is omitted.
    95         *
    96         * @param(inst)  instance with config parameters to set
    97         * @param(args)  an array of command-line arguments
    98         */
    99        function getopts(inst, args);
   100    
   101        function info(msg);
   102        function read();
   103        function usage();
   104        function time(msg);
   105        function verbose(flag);
   106        function warning(msg);
   107        function write(s);
   108    
   109    }