1 2 3 4 5 6 7 8 9 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 30 31
32 config Int tid = 0;
33
34 /*!
35 * ======== socket ========
36 * @_nodoc
37 */
38 config Any socket = null;
39
40 41 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 189
190