1    /* 
     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     * */
    12    /*!
    13     *  ======== Cmdr ========
    14     *  Command line tool context
    15     */
    16    metaonly module Cmdr {
    17    
    18        enum Context { SHELL, SCRIPT };
    19    
    20    instance:
    21    
    22        /*!
    23         *  ======== context ========
    24         *  @_nodoc
    25         */
    26        config Context context = SHELL;
    27    
    28        /*
    29         *  ======== tid ========
    30         *  @_nodoc
    31         */
    32        config Int tid = 0;
    33    
    34        /*!
    35         *  ======== socket ========
    36         *  @_nodoc
    37         */
    38        config Any socket = null;
    39        
    40        /*
    41         *  ======== create ========
    42         */
    43        create(Any cmdmod);
    44        
    45        /*!
    46         *  ======== error ========
    47         *  Throw an error exception with the specified message
    48         *
    49         *  If `msg` is null or the empty string (""), the message
    50         *  `"fatal error"` is used.
    51         */
    52        function error(msg);
    53    
    54        /*!
    55         *  ======== getopts ========
    56         *  Parse command-line arguments into config params.
    57         *
    58         *  This function accepts an array of command-line arguments, and
    59         *  uses them to set the values of config parameters in a module
    60         *  instance. Parsing is controlled by the XDC declarations of the
    61         *  instance config params.
    62         *
    63         *  @a(Usage)
    64         *  The following command-line argument syntaxes are supported,
    65         *  following the syntax supported by GNU getopt() and getopt_long():
    66         *
    67         *  @p(code)
    68         *    -f                a boolean flag with short name
    69         *    -f value          a number or string with short name
    70         *    -fvalue
    71         *    -f=value
    72         *    --longname        a boolean flag with long name
    73         *    --longname value  a number or string with long name
    74         *    --longname=value  a number or string with long name
    75         *  @p
    76         *
    77         *  In addition the following non-standard syntaxes are supported:
    78         *  @p(code)
    79         *    -f:value
    80         *    --longnamevalue
    81         *    --longname:value
    82         *  @p
    83         *
    84         *  @a(Declaration)
    85         *  The long and short names of the config parameter are declared
    86         *  by the @CommandOption() attribute of the XDC spec language. For
    87         *  example to declare a boolean flag with a short name of "-f" and
    88         *  a long name of "--flag", and a default value of false:
    89         *  @p(code)
    90         *     @ CommandOption("f,flag")
    91         *     config Bool myFlag = false;
    92         *  @p
    93         *
    94         *  Options of type Bool with no argument are assigned the value
    95         *  "true". The types String and Int can also be used, and always
    96         *  require an argument to be given on the command line.
    97         *
    98         *  @a(Combining Short Flags)
    99         *  Short-name options can be combined on the command line where there
   100         *  is no ambiguity, for example the following usages are equivalent:
   101         *  @p(code)
   102         *    -a -b -c -f filename
   103         *    -abcf filename
   104         *  @p
   105         *
   106         *  @a(Multiple Occurrences)
   107         *  If the config param is declared as an array, the option may
   108         *  be used multiple times on the command line and each occurence
   109         *  will be recorded. For example the following records all -I
   110         *  options, in order:
   111         *  @p(code)
   112         *    @ CommandOption("I")
   113         *    config String includeDirs[] = [];
   114         *  @p
   115         *
   116         *  @a(Required Options)
   117         *  If the config param has no default value declared, then it
   118         *  is required on the command line.
   119         *
   120         *  @a(Returns)
   121         *  The following return values are used to determine whether or not to
   122         *  proceed with the command and, if not, what the exit status of the
   123         *  command should be.
   124         *  @p(dlist)
   125         *      - `undefined`
   126         *        the command options have been successfully parsed and the 
   127         *        command should be run.
   128         *      - `0` (zero)
   129         *        the command options have been successfully parsed and the 
   130         *        command does not need to be run and should exit with a
   131         *        successful exit status (0).
   132         *      - non-zero integral value
   133         *        an error occured in the parsing the options and the 
   134         *        command should not be run and should exit with a non-zero
   135         *        exit status.
   136         *      
   137         *  @param(inst)  instance with config parameters to set
   138         *  @param(args)  an array of command-line arguments
   139         */
   140        function getopts(inst, args);
   141    
   142        /*!
   143         *  ======== info ========
   144         *  Output informational message to stdout
   145         */
   146        function info(msg);
   147    
   148        /*!
   149         *  ======== read ========
   150         *  @_nodoc
   151         */
   152        function read();
   153    
   154        /*!
   155         *  ======== time ========
   156         *  Output elapsed time since command start to stderr
   157         */
   158        function time(msg);
   159    
   160        /*!
   161         *  ======== usage ========
   162         *  Output command usage message to stderr
   163         *
   164         *  If `msg` is defined and non-empty, the command name and `msg` are
   165         *  output before the usage information.
   166         */
   167        function usage(msg);
   168    
   169        /*!
   170         *  ======== verbose ========
   171         *  Set verbose flag as specified
   172         */
   173        function verbose(flag);
   174    
   175        /*!
   176         *  ======== warning ========
   177         *  Output specified warning message to stderr
   178         */
   179        function warning(msg);
   180    
   181        /*!
   182         *  ======== write ========
   183         *  @_nodoc
   184         */
   185        function write(s);
   186    }
   187    /*
   188     *  @(#) xdc.tools; 1, 0, 0, 0,397; 9-20-2012 15:02:22; /db/ztree/library/trees/xdc/xdc-y36x/src/packages/
   189     */
   190