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 metaonlymodule 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,371; 11-16-2011 11:00:43; /db/ztree/library/trees/xdc/xdc-y13x/src/packages/
189 */
190