getopt.h@ 44023

Last change on this file since 44023 was 40598, checked in by vboxsync, 13 years ago
getopt: Added RTGETOPT_REQ_BOOL.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 17.4 KB

Line
1	/** @file
2	* IPRT - Command Line Parsing.
3	*/
4
5	/*
6	* Copyright (C) 2007-2011 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___iprt_getopt_h
27	#define ___iprt_getopt_h
28
29
30	#include <iprt/cdefs.h>
31	#include <iprt/types.h>
32
33	RT_C_DECLS_BEGIN
34
35	/** @defgroup grp_rt_getopt RTGetOpt - Command Line Parsing
36	* @ingroup grp_rt
37	* @{
38	*/
39
40	/** @name Values for RTGETOPTDEF::fFlags and the fFlags parameter of
41	* RTGetOptFetchValue.
42	*
43	* @remarks When neither of the RTGETOPT_FLAG_HEX, RTGETOPT_FLAG_OCT and RTGETOPT_FLAG_DEC
44	* flags are specified with a integer value format, RTGetOpt will default to
45	* decimal but recognize the 0x prefix when present. RTGetOpt will not look for
46	* for the octal prefix (0).
47	* @{ */
48	/** Requires no extra argument.
49	* (Can be assumed to be 0 for ever.) */
50	#define RTGETOPT_REQ_NOTHING 0
51	/** A value is required or error will be returned. */
52	#define RTGETOPT_REQ_STRING 1
53	/** The value must be a valid signed 8-bit integer or an error will be returned. */
54	#define RTGETOPT_REQ_INT8 2
55	/** The value must be a valid unsigned 8-bit integer or an error will be returned. */
56	#define RTGETOPT_REQ_UINT8 3
57	/** The value must be a valid signed 16-bit integer or an error will be returned. */
58	#define RTGETOPT_REQ_INT16 4
59	/** The value must be a valid unsigned 16-bit integer or an error will be returned. */
60	#define RTGETOPT_REQ_UINT16 5
61	/** The value must be a valid signed 32-bit integer or an error will be returned. */
62	#define RTGETOPT_REQ_INT32 6
63	/** The value must be a valid unsigned 32-bit integer or an error will be returned. */
64	#define RTGETOPT_REQ_UINT32 7
65	/** The value must be a valid signed 64-bit integer or an error will be returned. */
66	#define RTGETOPT_REQ_INT64 8
67	/** The value must be a valid unsigned 64-bit integer or an error will be returned. */
68	#define RTGETOPT_REQ_UINT64 9
69	/** The value must be a valid IPv4 address.
70	* (Not a name, but 4 values in the 0..255 range with dots separating them). */
71	#define RTGETOPT_REQ_IPV4ADDR 10
72	#if 0
73	/** The value must be a valid IPv4 CIDR.
74	* As with RTGETOPT_REQ_IPV4ADDR, no name.
75	* @todo Mix CIDR with types.h or/and net.h first and find a way to make the
76	* mask optional like with ifconfig. See RTCidrStrToIPv4. */
77	#define RTGETOPT_REQ_IPV4CIDR 11
78	#endif
79	/** The value must be a valid ethernet MAC address. */
80	#define RTGETOPT_REQ_MACADDR 14
81	/** The value must be a valid UUID. */
82	#define RTGETOPT_REQ_UUID 15
83	/** The value must be a string with value as "on" or "off". */
84	#define RTGETOPT_REQ_BOOL_ONOFF 16
85	/** Boolean option accepting a wide range of typical ways of
86	* expression true and false. */
87	#define RTGETOPT_REQ_BOOL 17
88	/** The mask of the valid required types. */
89	#define RTGETOPT_REQ_MASK 31
90	/** Treat the value as hexadecimal - only applicable with the RTGETOPT_REQ_INT. */
91	#define RTGETOPT_FLAG_HEX RT_BIT(16)
92	/** Treat the value as octal - only applicable with the RTGETOPT_REQ_INT. */
93	#define RTGETOPT_FLAG_OCT RT_BIT(17)
94	/** Treat the value as decimal - only applicable with the RTGETOPT_REQ_INT. */
95	#define RTGETOPT_FLAG_DEC RT_BIT(18)
96	/** The index value is attached to the argument - only valid for long arguments. */
97	#define RTGETOPT_FLAG_INDEX RT_BIT(19)
98	/** Treat the long option as case insensitive. */
99	#define RTGETOPT_FLAG_ICASE RT_BIT(20)
100	/** Mask of valid bits - for validation. */
101	#define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK \
102	\| RTGETOPT_FLAG_HEX \
103	\| RTGETOPT_FLAG_OCT \
104	\| RTGETOPT_FLAG_DEC \
105	\| RTGETOPT_FLAG_INDEX \
106	\| RTGETOPT_FLAG_ICASE)
107	/** @} */
108
109	/**
110	* An option definition.
111	*/
112	typedef struct RTGETOPTDEF
113	{
114	/** The long option.
115	* This is optional */
116	const char *pszLong;
117	/** The short option character.
118	* This doesn't have to be a character, it may also be a \#define or enum value if
119	* there isn't any short version of this option. Must be greater than 0. */
120	int iShort;
121	/** The flags (RTGETOPT_). /
122	unsigned fFlags;
123	} RTGETOPTDEF;
124	/** Pointer to an option definition. */
125	typedef RTGETOPTDEF *PRTGETOPTDEF;
126	/** Pointer to an const option definition. */
127	typedef const RTGETOPTDEF *PCRTGETOPTDEF;
128
129	/**
130	* Option argument union.
131	*
132	* What ends up here depends on argument format in the option definition.
133	*
134	* @remarks Integers will bet put in the \a i and \a u members and sign/zero extended
135	* according to the signedness indicated by the \a fFlags. So, you can choose
136	* use which ever of the integer members for accessing the value regardless
137	* of restrictions indicated in the \a fFlags.
138	*/
139	typedef union RTGETOPTUNION
140	{
141	/** Pointer to the definition on failure or when the option doesn't take an argument.
142	* This can be NULL for some errors. */
143	PCRTGETOPTDEF pDef;
144	/** A RTGETOPT_REQ_STRING option argument. */
145	const char *psz;
146
147	/** A RTGETOPT_REQ_INT8 option argument. */
148	int8_t i8;
149	/** A RTGETOPT_REQ_UINT8 option argument . */
150	uint8_t u8;
151	/** A RTGETOPT_REQ_INT16 option argument. */
152	int16_t i16;
153	/** A RTGETOPT_REQ_UINT16 option argument . */
154	uint16_t u16;
155	/** A RTGETOPT_REQ_INT16 option argument. */
156	int32_t i32;
157	/** A RTGETOPT_REQ_UINT32 option argument . */
158	uint32_t u32;
159	/** A RTGETOPT_REQ_INT64 option argument. */
160	int64_t i64;
161	/** A RTGETOPT_REQ_UINT64 option argument. */
162	uint64_t u64;
163	#ifdef ___iprt_net_h
164	/** A RTGETOPT_REQ_IPV4ADDR option argument. */
165	RTNETADDRIPV4 IPv4Addr;
166	#endif
167	/** A RTGETOPT_REQ_MACADDR option argument. */
168	RTMAC MacAddr;
169	/** A RTGETOPT_REQ_UUID option argument. */
170	RTUUID Uuid;
171	/** A boolean flag. */
172	bool f;
173	} RTGETOPTUNION;
174	/** Pointer to an option argument union. */
175	typedef RTGETOPTUNION *PRTGETOPTUNION;
176	/** Pointer to a const option argument union. */
177	typedef RTGETOPTUNION const *PCRTGETOPTUNION;
178
179
180	/**
181	* RTGetOpt state.
182	*/
183	typedef struct RTGETOPTSTATE
184	{
185	/** The next argument. */
186	int iNext;
187	/** Argument array. */
188	char **argv;
189	/** Number of items in argv. */
190	int argc;
191	/** Option definition array. */
192	PCRTGETOPTDEF paOptions;
193	/** Number of items in paOptions. */
194	size_t cOptions;
195	/** The next short option.
196	* (For parsing ls -latrT4 kind of option lists.) */
197	const char *pszNextShort;
198	/** The option definition which matched. NULL otherwise. */
199	PCRTGETOPTDEF pDef;
200	/** The index of an index option, otherwise UINT32_MAX. */
201	uint32_t uIndex;
202	/** The flags passed to RTGetOptInit. */
203	uint32_t fFlags;
204	/** Number of non-options that we're skipping during a sorted get. The value
205	* INT32_MAX is used to indicate that there are no more options. This is used
206	* to implement '--'. */
207	int32_t cNonOptions;
208
209	/* More members may be added later for dealing with new features. */
210	} RTGETOPTSTATE;
211	/** Pointer to RTGetOpt state. */
212	typedef RTGETOPTSTATE *PRTGETOPTSTATE;
213
214
215	/**
216	* Initialize the RTGetOpt state.
217	*
218	* The passed in argument vector may be sorted if fFlags indicates that this is
219	* desired (to be implemented).
220	*
221	* @returns VINF_SUCCESS, VERR_INVALID_PARAMETER or VERR_INVALID_POINTER.
222	* @param pState The state.
223	*
224	* @param argc Argument count, to be copied from what comes in with
225	* main().
226	* @param argv Argument array, to be copied from what comes in with
227	* main(). This may end up being modified by the
228	* option/argument sorting.
229	* @param paOptions Array of RTGETOPTDEF structures, which must specify what
230	* options are understood by the program.
231	* @param cOptions Number of array items passed in with paOptions.
232	* @param iFirst The argument to start with (in argv).
233	* @param fFlags The flags, see RTGETOPTINIT_FLAGS_XXX.
234	*/
235	RTDECL(int) RTGetOptInit(PRTGETOPTSTATE pState, int argc, char **argv,
236	PCRTGETOPTDEF paOptions, size_t cOptions,
237	int iFirst, uint32_t fFlags);
238
239	/** @name RTGetOptInit flags.
240	* @{ */
241	/** Sort the arguments so that options comes first, then non-options. */
242	#define RTGETOPTINIT_FLAGS_OPTS_FIRST RT_BIT_32(0)
243	/** Prevent add the standard version and help options:
244	* - "--help", "-h" and "-?" returns 'h'.
245	* - "--version" and "-V" return 'V'.
246	*/
247	#define RTGETOPTINIT_FLAGS_NO_STD_OPTS RT_BIT_32(1)
248	/** @} */
249
250	/**
251	* Command line argument parser, handling both long and short options and checking
252	* argument formats, if desired.
253	*
254	* This is to be called in a loop until it returns 0 (meaning that all options
255	* were parsed) or a negative value (meaning that an error occurred). How non-option
256	* arguments are dealt with depends on the flags passed to RTGetOptInit. The default
257	* (fFlags = 0) is to return VINF_GETOPT_NOT_OPTION with pValueUnion->psz pointing to
258	* the argument string.
259	*
260	* For example, for a program which takes the following options:
261	*
262	* --optwithstring (or -s) and a string argument;
263	* --optwithint (or -i) and a 32-bit signed integer argument;
264	* --verbose (or -v) with no arguments,
265	*
266	* code would look something like this:
267	*
268	* @code
269	int main(int argc, char **argv)
270	{
271	int rc = RTR3Init();
272	if (RT_FAILURE(rc))
273	return RTMsgInitFailure(rc);
274
275	static const RTGETOPTDEF s_aOptions[] =
276	{
277	{ "--optwithstring", 's', RTGETOPT_REQ_STRING },
278	{ "--optwithint", 'i', RTGETOPT_REQ_INT32 },
279	{ "--verbose", 'v', 0 },
280	};
281
282	int ch;
283	RTGETOPTUNION ValueUnion;
284	RTGETOPTSTATE GetState;
285	RTGetOptInit(&GetState, argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), 1, 0);
286	while ((ch = RTGetOpt(&GetState, &ValueUnion)))
287	{
288	// for options that require an argument, ValueUnion has received the value
289	switch (ch)
290	{
291	case 's': // --optwithstring or -s
292	// string argument, copy ValueUnion.psz
293	break;
294
295	case 'i': // --optwithint or -i
296	// integer argument, copy ValueUnion.i32
297	break;
298
299	case 'v': // --verbose or -v
300	g_fOptVerbose = true;
301	break;
302
303	case VINF_GETOPT_NOT_OPTION:
304	// handle non-option argument in ValueUnion.psz.
305	break;
306
307	default:
308	return RTGetOptPrintError(ch, &ValueUnion);
309	}
310	}
311
312	return RTEXITCODE_SUCCESS;
313	}
314	@endcode
315	*
316	* @returns 0 when done parsing.
317	* @returns the iShort value of the option. pState->pDef points to the option
318	* definition which matched.
319	* @returns IPRT error status on parse error.
320	* @returns VINF_GETOPT_NOT_OPTION when encountering a non-option argument and
321	* RTGETOPT_FLAG_SORT was not specified. pValueUnion->psz points to the
322	* argument string.
323	* @returns VERR_GETOPT_UNKNOWN_OPTION when encountering an unknown option.
324	* pValueUnion->psz points to the option string.
325	* @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING and pValueUnion->pDef if
326	* a required argument (aka value) was missing for an option.
327	* @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
328	* argument (aka value) conversion failed.
329	*
330	* @param pState The state previously initialized with RTGetOptInit.
331	* @param pValueUnion Union with value; in the event of an error, psz member
332	* points to erroneous parameter; otherwise, for options
333	* that require an argument, this contains the value of
334	* that argument, depending on the type that is required.
335	*/
336	RTDECL(int) RTGetOpt(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion);
337
338	/**
339	* Fetch a value.
340	*
341	* Used to retrive a value argument in a manner similar to what RTGetOpt does
342	* (@a fFlags -> @a pValueUnion). This can be used when handling
343	* VINF_GETOPT_NOT_OPTION, but is equally useful for decoding options that
344	* takes more than one value.
345	*
346	* @returns VINF_SUCCESS on success.
347	* @returns IPRT error status on parse error.
348	* @returns VERR_INVALID_PARAMETER if the flags are wrong.
349	* @returns VERR_GETOPT_UNKNOWN_OPTION when pState->pDef is null.
350	* @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING if there are no more
351	* available arguments. pValueUnion->pDef is NULL.
352	* @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef is
353	* unchanged if value conversion failed.
354	*
355	* @param pState The state previously initialized with RTGetOptInit.
356	* @param pValueUnion Union with value; in the event of an error, psz member
357	* points to erroneous parameter; otherwise, for options
358	* that require an argument, this contains the value of
359	* that argument, depending on the type that is required.
360	* @param fFlags What to get, that is RTGETOPT_REQ_XXX.
361	*/
362	RTDECL(int) RTGetOptFetchValue(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion, uint32_t fFlags);
363
364	/**
365	* Print error messages for a RTGetOpt default case.
366	*
367	* Uses RTMsgError.
368	*
369	* @returns Suitable exit code.
370	*
371	* @param ch The RTGetOpt return value.
372	* @param pValueUnion The value union returned by RTGetOpt.
373	*/
374	RTDECL(RTEXITCODE) RTGetOptPrintError(int ch, PCRTGETOPTUNION pValueUnion);
375
376	/**
377	* Parses the @a pszCmdLine string into an argv array.
378	*
379	* This is useful for converting a response file or similar to an argument
380	* vector that can be used with RTGetOptInit().
381	*
382	* This function aims at following the bourn shell string quoting rules.
383	*
384	* @returns IPRT status code.
385	*
386	* @param ppapszArgv Where to return the argument vector. This must be
387	* freed by calling RTGetOptArgvFree.
388	* @param pcArgs Where to return the argument count.
389	* @param pszCmdLine The string to parse.
390	* @param pszSeparators String containing the argument separators. If NULL,
391	* then space, tab, line feed (\\n) and return (\\r)
392	* are used.
393	*/
394	RTDECL(int) RTGetOptArgvFromString(char **ppapszArgv, int pcArgs, const char pszCmdLine, const char pszSeparators);
395
396	/**
397	* Frees and argument vector returned by RTGetOptStringToArgv.
398	*
399	* @param papszArgv Argument vector. NULL is fine.
400	*/
401	RTDECL(void) RTGetOptArgvFree(char **paArgv);
402
403	/**
404	* Turns an argv array into a command line string.
405	*
406	* This is useful for calling CreateProcess on Windows, but can also be used for
407	* displaying an argv array.
408	*
409	* This function aims at following the bourn shell string quoting rules.
410	*
411	* @returns IPRT status code.
412	*
413	* @param ppszCmdLine Where to return the command line string. This must
414	* be freed by calling RTStrFree.
415	* @param papszArgs The argument vector to convert.
416	* @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags.
417	*/
418	RTDECL(int) RTGetOptArgvToString(char *ppszCmdLine, const char const *papszArgv, uint32_t fFlags);
419
420	/** @name RTGetOptArgvToString and RTGetOptArgvToUtf16String flags
421	* @{ */
422	/** Quote strings according to the Microsoft CRT rules. */
423	#define RTGETOPTARGV_CNV_QUOTE_MS_CRT UINT32_C(0)
424	/** Quote strings according to the Unix Bourne Shell. */
425	#define RTGETOPTARGV_CNV_QUOTE_BOURNE_SH UINT32_C(1)
426	/** Mask for the quoting style. */
427	#define RTGETOPTARGV_CNV_QUOTE_MASK UINT32_C(1)
428	/** @} */
429
430	/**
431	* Convenience wrapper around RTGetOpArgvToString and RTStrToUtf16.
432	*
433	* @returns IPRT status code.
434	*
435	* @param ppwszCmdLine Where to return the command line string. This must
436	* be freed by calling RTUtf16Free.
437	* @param papszArgs The argument vector to convert.
438	* @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags.
439	*/
440	RTDECL(int) RTGetOptArgvToUtf16String(PRTUTF16 ppwszCmdLine, const char const *papszArgv, uint32_t fFlags);
441
442	/** @} */
443
444	RT_C_DECLS_END
445
446	#endif
447

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/getopt.h@ 44023

Download in other formats: