1 2 3 4 5 6 7 8 9 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 98
99