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    /*!
    14     *  ======== ICmd ========
    15     *  Generic xdc-script (xs) command
    16     *
    17     *  Modules that implement this interface can serve as "commands" that
    18     *  can be executed from the command line (via `xs`) or from within
    19     *  XDCscript scripts (without having to fork a separate process to run
    20     *  `xs`).
    21     *
    22     *  @a(Command Line Example)
    23     *  The following example runs the `xdc.tools.path` tool from the command 
    24     *  line to get an array of names of all packages below the current
    25     *  working directory (".").
    26     *  @p(code)
    27     *      xs xdc.tools.path -n -a -PR .
    28     *  @p
    29     *  
    30     *  @a(XDCscript Example)
    31     *  The following example runs the `xdc.tools.path` tool from within
    32     *  a script to get an array of names of all packages below the current
    33     *  working directory (".").
    34     *  @p(code)
    35     *      var Main = xdc.module('xdc.tools.path.Main');
    36     *      var result = Main.exec(["-n", "-a", "-PR", "."]);
    37     *  @p
    38     */
    39    metaonly interface ICmd {
    40    
    41        //! Usage for this command
    42        config String usage[] = [];
    43    
    44        /*!
    45         *  ======== main ========
    46         *  `xs` shell entry point
    47         *
    48         *  This function
    49         *  @p(blist)
    50         *   - creates a no-arg instance, `inst`, of the module inheriting
    51         *     this interface;
    52         *   - parses command line arguments placing all options in the config
    53         *     params of the inheriting module;
    54         *   - creates a `{@link xdc.tools.Cmdr}` instance, `cmdr`;
    55         *   - calls `{@link #run inst.run()}` with the `cmdr` and any command
    56         *     line command line arguments not parsed as options; and
    57         *   - outputs the return result from `inst.run()`
    58         *   @p
    59         */
    60        final function main(args);
    61    
    62        /*!
    63         *  ======== exec ========
    64         *  `xs` script entry point
    65         *
    66         *  This function is called from within other XDCscript scripts and
    67         *  performs the same operations as `{@link #main()}` except that,
    68         *  rather than output the return value of `inst.run()`, this value
    69         *  is simply returned to the caller of `exec()`.
    70         */
    71        final function exec(args);
    72    
    73    instance:
    74    
    75        /*!
    76         *  ======== run ========
    77         *  Underlying implementation of the command
    78         *
    79         *  Since this method is used to support both command line tools and
    80         *  other XDCscript scripts, it is important to avoid explicit
    81         *  termination of the JVM via `java.lang.System.exit()`; doing so
    82         *  precludes callers from handling failures.
    83         *
    84         *  Implementations should instead call
    85         *  @p(blist)
    86         *  - `{@link xdc.tools.Cmdr#error cmdr.error()}` when encountering a
    87         *     fatal error.
    88         *  - `{@link xdc.tools.Cmdr#warning cmdr.warning()}` when encountering a
    89         *     non-fatal error.
    90         *  - `{@link xdc.tools.Cmdr#info cmdr.info()}` when simply generating
    91         *     an informative message.
    92         *  @p
    93         */
    94        Any run(Cmdr.Instance cmdr, String args[]);
    95    }
    96    /*
    97     *  @(#) xdc.tools; 1, 0, 0,483; 3-20-2014 17:06:44; /db/ztree/library/trees/xdc/xdc-A32x/src/packages/
    98     */
    99