getopt.h@ 38507

Last change on this file since 38507 was 37665, checked in by vboxsync, 13 years ago
Runtime/getopt: add new option flag to switch to case insensitive matching
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 17.1 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	/** The mask of the valid required types. */
86	#define RTGETOPT_REQ_MASK 31
87	/** Treat the value as hexadecimal - only applicable with the RTGETOPT_REQ_INT. */
88	#define RTGETOPT_FLAG_HEX RT_BIT(16)
89	/** Treat the value as octal - only applicable with the RTGETOPT_REQ_INT. */
90	#define RTGETOPT_FLAG_OCT RT_BIT(17)
91	/** Treat the value as decimal - only applicable with the RTGETOPT_REQ_INT. */
92	#define RTGETOPT_FLAG_DEC RT_BIT(18)
93	/** The index value is attached to the argument - only valid for long arguments. */
94	#define RTGETOPT_FLAG_INDEX RT_BIT(19)
95	/** Treat the long option as case insensitive. */
96	#define RTGETOPT_FLAG_ICASE RT_BIT(20)
97	/** Mask of valid bits - for validation. */
98	#define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK \
99	\| RTGETOPT_FLAG_HEX \
100	\| RTGETOPT_FLAG_OCT \
101	\| RTGETOPT_FLAG_DEC \
102	\| RTGETOPT_FLAG_INDEX \
103	\| RTGETOPT_FLAG_ICASE)
104	/** @} */
105
106	/**
107	* An option definition.
108	*/
109	typedef struct RTGETOPTDEF
110	{
111	/** The long option.
112	* This is optional */
113	const char *pszLong;
114	/** The short option character.
115	* This doesn't have to be a character, it may also be a \#define or enum value if
116	* there isn't any short version of this option. Must be greater than 0. */
117	int iShort;
118	/** The flags (RTGETOPT_). /
119	unsigned fFlags;
120	} RTGETOPTDEF;
121	/** Pointer to an option definition. */
122	typedef RTGETOPTDEF *PRTGETOPTDEF;
123	/** Pointer to an const option definition. */
124	typedef const RTGETOPTDEF *PCRTGETOPTDEF;
125
126	/**
127	* Option argument union.
128	*
129	* What ends up here depends on argument format in the option definition.
130	*
131	* @remarks Integers will bet put in the \a i and \a u members and sign/zero extended
132	* according to the signedness indicated by the \a fFlags. So, you can choose
133	* use which ever of the integer members for accessing the value regardless
134	* of restrictions indicated in the \a fFlags.
135	*/
136	typedef union RTGETOPTUNION
137	{
138	/** Pointer to the definition on failure or when the option doesn't take an argument.
139	* This can be NULL for some errors. */
140	PCRTGETOPTDEF pDef;
141	/** A RTGETOPT_REQ_STRING option argument. */
142	const char *psz;
143
144	/** A RTGETOPT_REQ_INT8 option argument. */
145	int8_t i8;
146	/** A RTGETOPT_REQ_UINT8 option argument . */
147	uint8_t u8;
148	/** A RTGETOPT_REQ_INT16 option argument. */
149	int16_t i16;
150	/** A RTGETOPT_REQ_UINT16 option argument . */
151	uint16_t u16;
152	/** A RTGETOPT_REQ_INT16 option argument. */
153	int32_t i32;
154	/** A RTGETOPT_REQ_UINT32 option argument . */
155	uint32_t u32;
156	/** A RTGETOPT_REQ_INT64 option argument. */
157	int64_t i64;
158	/** A RTGETOPT_REQ_UINT64 option argument. */
159	uint64_t u64;
160	#ifdef ___iprt_net_h
161	/** A RTGETOPT_REQ_IPV4ADDR option argument. */
162	RTNETADDRIPV4 IPv4Addr;
163	#endif
164	/** A RTGETOPT_REQ_MACADDR option argument. */
165	RTMAC MacAddr;
166	/** A RTGETOPT_REQ_UUID option argument. */
167	RTUUID Uuid;
168	/** A boolean flag. */
169	bool f;
170	} RTGETOPTUNION;
171	/** Pointer to an option argument union. */
172	typedef RTGETOPTUNION *PRTGETOPTUNION;
173	/** Pointer to a const option argument union. */
174	typedef RTGETOPTUNION const *PCRTGETOPTUNION;
175
176
177	/**
178	* RTGetOpt state.
179	*/
180	typedef struct RTGETOPTSTATE
181	{
182	/** The next argument. */
183	int iNext;
184	/** Argument array. */
185	char **argv;
186	/** Number of items in argv. */
187	int argc;
188	/** Option definition array. */
189	PCRTGETOPTDEF paOptions;
190	/** Number of items in paOptions. */
191	size_t cOptions;
192	/** The next short option.
193	* (For parsing ls -latrT4 kind of option lists.) */
194	const char *pszNextShort;
195	/** The option definition which matched. NULL otherwise. */
196	PCRTGETOPTDEF pDef;
197	/** The index of an index option, otherwise UINT32_MAX. */
198	uint32_t uIndex;
199	/** The flags passed to RTGetOptInit. */
200	uint32_t fFlags;
201	/** Number of non-options that we're skipping during a sorted get. The value
202	* INT32_MAX is used to indicate that there are no more options. This is used
203	* to implement '--'. */
204	int32_t cNonOptions;
205
206	/* More members may be added later for dealing with new features. */
207	} RTGETOPTSTATE;
208	/** Pointer to RTGetOpt state. */
209	typedef RTGETOPTSTATE *PRTGETOPTSTATE;
210
211
212	/**
213	* Initialize the RTGetOpt state.
214	*
215	* The passed in argument vector may be sorted if fFlags indicates that this is
216	* desired (to be implemented).
217	*
218	* @returns VINF_SUCCESS, VERR_INVALID_PARAMETER or VERR_INVALID_POINTER.
219	* @param pState The state.
220	*
221	* @param argc Argument count, to be copied from what comes in with
222	* main().
223	* @param argv Argument array, to be copied from what comes in with
224	* main(). This may end up being modified by the
225	* option/argument sorting.
226	* @param paOptions Array of RTGETOPTDEF structures, which must specify what
227	* options are understood by the program.
228	* @param cOptions Number of array items passed in with paOptions.
229	* @param iFirst The argument to start with (in argv).
230	* @param fFlags The flags, see RTGETOPTINIT_FLAGS_XXX.
231	*/
232	RTDECL(int) RTGetOptInit(PRTGETOPTSTATE pState, int argc, char **argv,
233	PCRTGETOPTDEF paOptions, size_t cOptions,
234	int iFirst, uint32_t fFlags);
235
236	/** @name RTGetOptInit flags.
237	* @{ */
238	/** Sort the arguments so that options comes first, then non-options. */
239	#define RTGETOPTINIT_FLAGS_OPTS_FIRST RT_BIT_32(0)
240	/** Prevent add the standard version and help options:
241	* - "--help", "-h" and "-?" returns 'h'.
242	* - "--version" and "-V" return 'V'.
243	*/
244	#define RTGETOPTINIT_FLAGS_NO_STD_OPTS RT_BIT_32(1)
245	/** @} */
246
247	/**
248	* Command line argument parser, handling both long and short options and checking
249	* argument formats, if desired.
250	*
251	* This is to be called in a loop until it returns 0 (meaning that all options
252	* were parsed) or a negative value (meaning that an error occurred). How non-option
253	* arguments are dealt with depends on the flags passed to RTGetOptInit. The default
254	* (fFlags = 0) is to return VINF_GETOPT_NOT_OPTION with pValueUnion->psz pointing to
255	* the argument string.
256	*
257	* For example, for a program which takes the following options:
258	*
259	* --optwithstring (or -s) and a string argument;
260	* --optwithint (or -i) and a 32-bit signed integer argument;
261	* --verbose (or -v) with no arguments,
262	*
263	* code would look something like this:
264	*
265	* @code
266	int main(int argc, char **argv)
267	{
268	int rc = RTR3Init();
269	if (RT_FAILURE(rc))
270	return RTMsgInitFailure(rc);
271
272	static const RTGETOPTDEF s_aOptions[] =
273	{
274	{ "--optwithstring", 's', RTGETOPT_REQ_STRING },
275	{ "--optwithint", 'i', RTGETOPT_REQ_INT32 },
276	{ "--verbose", 'v', 0 },
277	};
278
279	int ch;
280	RTGETOPTUNION ValueUnion;
281	RTGETOPTSTATE GetState;
282	RTGetOptInit(&GetState, argc, argv, s_aOptions, RT_ELEMENTS(s_aOptions), 1, 0);
283	while ((ch = RTGetOpt(&GetState, &ValueUnion)))
284	{
285	// for options that require an argument, ValueUnion has received the value
286	switch (ch)
287	{
288	case 's': // --optwithstring or -s
289	// string argument, copy ValueUnion.psz
290	break;
291
292	case 'i': // --optwithint or -i
293	// integer argument, copy ValueUnion.i32
294	break;
295
296	case 'v': // --verbose or -v
297	g_fOptVerbose = true;
298	break;
299
300	case VINF_GETOPT_NOT_OPTION:
301	// handle non-option argument in ValueUnion.psz.
302	break;
303
304	default:
305	return RTGetOptPrintError(ch, &ValueUnion);
306	}
307	}
308
309	return RTEXITCODE_SUCCESS;
310	}
311	@endcode
312	*
313	* @returns 0 when done parsing.
314	* @returns the iShort value of the option. pState->pDef points to the option
315	* definition which matched.
316	* @returns IPRT error status on parse error.
317	* @returns VINF_GETOPT_NOT_OPTION when encountering a non-option argument and
318	* RTGETOPT_FLAG_SORT was not specified. pValueUnion->psz points to the
319	* argument string.
320	* @returns VERR_GETOPT_UNKNOWN_OPTION when encountering an unknown option.
321	* pValueUnion->psz points to the option string.
322	* @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING and pValueUnion->pDef if
323	* a required argument (aka value) was missing for an option.
324	* @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
325	* argument (aka value) conversion failed.
326	*
327	* @param pState The state previously initialized with RTGetOptInit.
328	* @param pValueUnion Union with value; in the event of an error, psz member
329	* points to erroneous parameter; otherwise, for options
330	* that require an argument, this contains the value of
331	* that argument, depending on the type that is required.
332	*/
333	RTDECL(int) RTGetOpt(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion);
334
335	/**
336	* Fetch an additional value.
337	*
338	* This is used for special cases where an option have more than one value.
339	*
340	*
341	* @returns VINF_SUCCESS on success.
342	* @returns IPRT error status on parse error.
343	* @returns VERR_INVALID_PARAMETER if the flags are wrong.
344	* @returns VERR_GETOPT_UNKNOWN_OPTION when pState->pDef is null.
345	* @returns VERR_GETOPT_REQUIRED_ARGUMENT_MISSING if there are no more
346	* available arguments. pValueUnion->pDef is NULL.
347	* @returns VERR_GETOPT_INVALID_ARGUMENT_FORMAT and pValueUnion->pDef if
348	* value conversion failed.
349	*
350	* @param pState The state previously initialized with RTGetOptInit.
351	* @param pValueUnion Union with value; in the event of an error, psz member
352	* points to erroneous parameter; otherwise, for options
353	* that require an argument, this contains the value of
354	* that argument, depending on the type that is required.
355	* @param fFlags What to get, that is RTGETOPT_REQ_XXX.
356	*/
357	RTDECL(int) RTGetOptFetchValue(PRTGETOPTSTATE pState, PRTGETOPTUNION pValueUnion, uint32_t fFlags);
358
359	/**
360	* Print error messages for a RTGetOpt default case.
361	*
362	* Uses RTMsgError.
363	*
364	* @returns Suitable exit code.
365	*
366	* @param ch The RTGetOpt return value.
367	* @param pValueUnion The value union returned by RTGetOpt.
368	*/
369	RTDECL(RTEXITCODE) RTGetOptPrintError(int ch, PCRTGETOPTUNION pValueUnion);
370
371	/**
372	* Parses the @a pszCmdLine string into an argv array.
373	*
374	* This is useful for converting a response file or similar to an argument
375	* vector that can be used with RTGetOptInit().
376	*
377	* This function aims at following the bourn shell string quoting rules.
378	*
379	* @returns IPRT status code.
380	*
381	* @param ppapszArgv Where to return the argument vector. This must be
382	* freed by calling RTGetOptArgvFree.
383	* @param pcArgs Where to return the argument count.
384	* @param pszCmdLine The string to parse.
385	* @param pszSeparators String containing the argument separators. If NULL,
386	* then space, tab, line feed (\\n) and return (\\r)
387	* are used.
388	*/
389	RTDECL(int) RTGetOptArgvFromString(char **ppapszArgv, int pcArgs, const char pszCmdLine, const char pszSeparators);
390
391	/**
392	* Frees and argument vector returned by RTGetOptStringToArgv.
393	*
394	* @param papszArgv Argument vector. NULL is fine.
395	*/
396	RTDECL(void) RTGetOptArgvFree(char **paArgv);
397
398	/**
399	* Turns an argv array into a command line string.
400	*
401	* This is useful for calling CreateProcess on Windows, but can also be used for
402	* displaying an argv array.
403	*
404	* This function aims at following the bourn shell string quoting rules.
405	*
406	* @returns IPRT status code.
407	*
408	* @param ppszCmdLine Where to return the command line string. This must
409	* be freed by calling RTStrFree.
410	* @param papszArgs The argument vector to convert.
411	* @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags.
412	*/
413	RTDECL(int) RTGetOptArgvToString(char *ppszCmdLine, const char const *papszArgv, uint32_t fFlags);
414
415	/** @name RTGetOptArgvToString and RTGetOptArgvToUtf16String flags
416	* @{ */
417	/** Quote strings according to the Microsoft CRT rules. */
418	#define RTGETOPTARGV_CNV_QUOTE_MS_CRT UINT32_C(0)
419	/** Quote strings according to the Unix Bourne Shell. */
420	#define RTGETOPTARGV_CNV_QUOTE_BOURNE_SH UINT32_C(1)
421	/** Mask for the quoting style. */
422	#define RTGETOPTARGV_CNV_QUOTE_MASK UINT32_C(1)
423	/** @} */
424
425	/**
426	* Convenience wrapper around RTGetOpArgvToString and RTStrToUtf16.
427	*
428	* @returns IPRT status code.
429	*
430	* @param ppwszCmdLine Where to return the command line string. This must
431	* be freed by calling RTUtf16Free.
432	* @param papszArgs The argument vector to convert.
433	* @param fFlags A combination of the RTGETOPTARGV_CNV_XXX flags.
434	*/
435	RTDECL(int) RTGetOptArgvToUtf16String(PRTUTF16 ppwszCmdLine, const char const *papszArgv, uint32_t fFlags);
436
437	/** @} */
438
439	RT_C_DECLS_END
440
441	#endif
442

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

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

Download in other formats: