getopt.h@ 64721

Last change on this file since 64721 was 64603, checked in by vboxsync, 8 years ago
IPRT: Added RTGetOptNonOptionArrayPtr.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 18.6 KB

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

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

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

Download in other formats: