[5767] | 1 | /** @file
|
---|
| 2 | * innotek Portable Runtime - Command Line Parsing.
|
---|
| 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[8155] | 6 | * Copyright (C) 2007 Sun Microsystems, Inc.
|
---|
[5767] | 7 | *
|
---|
[6000] | 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.
|
---|
[8155] | 24 | *
|
---|
| 25 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
|
---|
| 26 | * Clara, CA 95054 USA or visit http://www.sun.com if you need
|
---|
| 27 | * additional information or have any questions.
|
---|
[5767] | 28 | */
|
---|
| 29 |
|
---|
| 30 | #ifndef ___iprt_getopt_h
|
---|
| 31 | #define ___iprt_getopt_h
|
---|
| 32 |
|
---|
| 33 |
|
---|
| 34 | #include <iprt/cdefs.h>
|
---|
| 35 | #include <iprt/types.h>
|
---|
| 36 |
|
---|
| 37 | __BEGIN_DECLS
|
---|
| 38 |
|
---|
| 39 | /** @defgroup grp_rt_getopt RTGetOpt - Command Line Parsing
|
---|
| 40 | * @ingroup grp_rt
|
---|
| 41 | * @{
|
---|
| 42 | */
|
---|
| 43 |
|
---|
[8147] | 44 | /** @name RTOPTIONDEF::fFlags
|
---|
| 45 | *
|
---|
| 46 | * @remarks When neither of the RTGETOPT_FLAG_HEX, RTGETOPT_FLAG_OCT and RTGETOPT_FLAG_DEC
|
---|
| 47 | * flags are specified with a integer value format, RTGetOpt will default to
|
---|
| 48 | * decimal but recognize the 0x prefix when present. RTGetOpt will not look for
|
---|
| 49 | * for the octal prefix (0).
|
---|
[5843] | 50 | * @{ */
|
---|
[8147] | 51 | /** Requires no extra argument.
|
---|
[5843] | 52 | * (Can be assumed to be 0 for ever.) */
|
---|
| 53 | #define RTGETOPT_REQ_NOTHING 0
|
---|
| 54 | /** A value is required or error will be returned. */
|
---|
| 55 | #define RTGETOPT_REQ_STRING 1
|
---|
[8147] | 56 | /** The value must be a valid signed 8-bit integer or an error will be returned. */
|
---|
| 57 | #define RTGETOPT_REQ_INT8 2
|
---|
| 58 | /** The value must be a valid unsigned 8-bit integer or an error will be returned. */
|
---|
| 59 | #define RTGETOPT_REQ_UINT8 3
|
---|
| 60 | /** The value must be a valid signed 16-bit integer or an error will be returned. */
|
---|
| 61 | #define RTGETOPT_REQ_INT16 4
|
---|
| 62 | /** The value must be a valid unsigned 16-bit integer or an error will be returned. */
|
---|
| 63 | #define RTGETOPT_REQ_UINT16 5
|
---|
[5843] | 64 | /** The value must be a valid signed 32-bit integer or an error will be returned. */
|
---|
[8147] | 65 | #define RTGETOPT_REQ_INT32 6
|
---|
| 66 | /** The value must be a valid unsigned 32-bit integer or an error will be returned. */
|
---|
| 67 | #define RTGETOPT_REQ_UINT32 7
|
---|
| 68 | /** The value must be a valid signed 64-bit integer or an error will be returned. */
|
---|
| 69 | #define RTGETOPT_REQ_INT64 8
|
---|
| 70 | /** The value must be a valid unsigned 64-bit integer or an error will be returned. */
|
---|
| 71 | #define RTGETOPT_REQ_UINT64 9
|
---|
[5843] | 72 | /** The mask of the valid required types. */
|
---|
[8147] | 73 | #define RTGETOPT_REQ_MASK 15
|
---|
| 74 | /** Treat the value as hexadecimal - only applicable with the RTGETOPT_REQ_*INT*. */
|
---|
| 75 | #define RTGETOPT_FLAG_HEX RT_BIT(16)
|
---|
| 76 | /** Treat the value as octal - only applicable with the RTGETOPT_REQ_*INT*. */
|
---|
| 77 | #define RTGETOPT_FLAG_OCT RT_BIT(17)
|
---|
| 78 | /** Treat the value as decimal - only applicable with the RTGETOPT_REQ_*INT*. */
|
---|
| 79 | #define RTGETOPT_FLAG_DEC RT_BIT(18)
|
---|
| 80 | /** Mask of valid bits - for validation. */
|
---|
| 81 | #define RTGETOPT_VALID_MASK ( RTGETOPT_REQ_MASK | RTGETOPT_FLAG_HEX | RTGETOPT_FLAG_OCT | RTGETOPT_FLAG_DEC )
|
---|
[5843] | 82 | /** @} */
|
---|
[5767] | 83 |
|
---|
[5843] | 84 | /**
|
---|
| 85 | * An option definition.
|
---|
[5767] | 86 | */
|
---|
[5843] | 87 | typedef struct RTOPTIONDEF
|
---|
[5767] | 88 | {
|
---|
[5843] | 89 | /** The long option.
|
---|
| 90 | * This is optional */
|
---|
| 91 | const char *pszLong;
|
---|
[8147] | 92 | /** The short option character.
|
---|
| 93 | * This doesn't have to be a character, it may also be a \#define or enum value if
|
---|
[5843] | 94 | * there isn't any short version of this option. */
|
---|
| 95 | int iShort;
|
---|
| 96 | /** The flags (RTGETOPT_*). */
|
---|
| 97 | unsigned fFlags;
|
---|
[5767] | 98 | } RTOPTIONDEF;
|
---|
[5843] | 99 | /** Pointer to an option definition. */
|
---|
| 100 | typedef RTOPTIONDEF *PRTOPTIONDEF;
|
---|
| 101 | /** Pointer to an const option definition. */
|
---|
| 102 | typedef const RTOPTIONDEF *PCRTOPTIONDEF;
|
---|
[5767] | 103 |
|
---|
[5843] | 104 | /**
|
---|
| 105 | * Option argument union.
|
---|
[8147] | 106 | *
|
---|
[5843] | 107 | * What ends up here depends on argument format in the option definition.
|
---|
[8147] | 108 | *
|
---|
| 109 | * @remarks Integers will bet put in the \a i and \a u members and sign/zero extended
|
---|
| 110 | * according to the signedness indicated by the \a fFlags. So, you can choose
|
---|
| 111 | * use which ever of the integer members for accessing the value regardless
|
---|
| 112 | * of restrictions indicated in the \a fFlags.
|
---|
[5843] | 113 | */
|
---|
| 114 | typedef union RTOPTIONUNION
|
---|
[5767] | 115 | {
|
---|
[5843] | 116 | /** Pointer to the definition on failure or when the option doesn't take an argument.
|
---|
| 117 | * This can be NULL for some errors. */
|
---|
| 118 | PCRTOPTIONDEF pDef;
|
---|
| 119 | /** A RTGETOPT_ARG_FORMAT_STRING option argument. */
|
---|
| 120 | const char *psz;
|
---|
[8147] | 121 |
|
---|
| 122 | #if !defined(RT_ARCH_AMD64) && !defined(RT_ARCH_X86)
|
---|
| 123 | # error "PORTME: big-endian systems will need to fix the layout here to get the next two fields working right"
|
---|
| 124 | #endif
|
---|
| 125 |
|
---|
| 126 | /** A RTGETOPT_ARG_FORMAT_INT8 option argument. */
|
---|
| 127 | int8_t i8;
|
---|
| 128 | /** A RTGETOPT_ARG_FORMAT_UINT8 option argument . */
|
---|
| 129 | uint8_t u8;
|
---|
| 130 | /** A RTGETOPT_ARG_FORMAT_INT16 option argument. */
|
---|
| 131 | int16_t i16;
|
---|
| 132 | /** A RTGETOPT_ARG_FORMAT_UINT16 option argument . */
|
---|
| 133 | uint16_t u16;
|
---|
| 134 | /** A RTGETOPT_ARG_FORMAT_INT16 option argument. */
|
---|
[5843] | 135 | int32_t i32;
|
---|
| 136 | /** A RTGETOPT_ARG_FORMAT_UINT32 option argument . */
|
---|
| 137 | uint32_t u32;
|
---|
[8147] | 138 | /** A RTGETOPT_ARG_FORMAT_INT64 option argument. */
|
---|
| 139 | int64_t i64;
|
---|
| 140 | /** A RTGETOPT_ARG_FORMAT_UINT64 option argument. */
|
---|
| 141 | uint64_t u64;
|
---|
| 142 | /** A signed integer value. */
|
---|
| 143 | int64_t i;
|
---|
| 144 | /** An unsigned integer value. */
|
---|
| 145 | uint64_t u;
|
---|
[5767] | 146 | } RTOPTIONUNION;
|
---|
[5843] | 147 | /** Pointer to an option argument union. */
|
---|
| 148 | typedef RTOPTIONUNION *PRTOPTIONUNION;
|
---|
[8147] | 149 | /** Pointer to a const option argument union. */
|
---|
| 150 | typedef RTOPTIONUNION const *PCRTOPTIONUNION;
|
---|
[5767] | 151 |
|
---|
| 152 |
|
---|
| 153 | /**
|
---|
| 154 | * Command line argument parser, handling both long and short options and checking
|
---|
| 155 | * argument formats, if desired.
|
---|
| 156 | *
|
---|
[5843] | 157 | * This is to be called in a loop until it returns 0 (meaning that all options
|
---|
[8147] | 158 | * were parsed) or a negative value (meaning that an error occured). The passed in
|
---|
[5843] | 159 | * argument vector is sorted into options and non-option arguments, such that when
|
---|
| 160 | * returning 0 the *piThis is the index of the first non-option argument.
|
---|
[5767] | 161 | *
|
---|
| 162 | * For example, for a program which takes the following options:
|
---|
| 163 | *
|
---|
| 164 | * --optwithstring (or -s) and a string argument;
|
---|
[5843] | 165 | * --optwithint (or -i) and a 32-bit signed integer argument;
|
---|
[5767] | 166 | * --verbose (or -v) with no arguments,
|
---|
| 167 | *
|
---|
| 168 | * code would look something like this:
|
---|
| 169 | *
|
---|
| 170 | * @code
|
---|
[5843] | 171 | * int main(int argc, char *argv[])
|
---|
[5767] | 172 | * {
|
---|
[8147] | 173 | * static const RTOPTIONDEF g_aOptions[] =
|
---|
[5843] | 174 | * {
|
---|
| 175 | * { "--optwithstring", 's', RTGETOPT_REQ_STRING },
|
---|
| 176 | * { "--optwithint", 'i', RTGETOPT_REQ_INT32 },
|
---|
| 177 | * { "--verbose", 'v', 0 },
|
---|
| 178 | * };
|
---|
[5767] | 179 | *
|
---|
[5843] | 180 | * int ch;
|
---|
[5767] | 181 | * int i = 1;
|
---|
| 182 | * RTOPTIONUNION ValueUnion;
|
---|
[5843] | 183 | * while ((ch = RTGetOpt(argc, argv, g_aOptions, RT_ELEMENTS(g_aOptions), &i, &ValueUnion)))
|
---|
[5767] | 184 | * {
|
---|
[5843] | 185 | * if (ch < 0) { .... error }
|
---|
[5767] | 186 | *
|
---|
| 187 | * // for options that require an argument, ValueUnion has received the value
|
---|
[5843] | 188 | * switch (ch)
|
---|
[5767] | 189 | * {
|
---|
| 190 | * case 's': // --optwithstring or -s
|
---|
[5843] | 191 | * // string argument, copy ValueUnion.psz
|
---|
| 192 | * break;
|
---|
[5767] | 193 | *
|
---|
| 194 | * case 'i': // --optwithint or -i
|
---|
[5843] | 195 | * // integer argument, copy ValueUnion.i32
|
---|
| 196 | * break;
|
---|
[5767] | 197 | *
|
---|
| 198 | * case 'v': // --verbose or -v
|
---|
[5843] | 199 | * g_fOptVerbose = true;
|
---|
| 200 | * break;
|
---|
[5767] | 201 | * }
|
---|
| 202 | * }
|
---|
[8147] | 203 | *
|
---|
[5843] | 204 | * while (i < argc)
|
---|
| 205 | * {
|
---|
| 206 | * //do stuff to argv[i].
|
---|
| 207 | * }
|
---|
[8147] | 208 | *
|
---|
[5843] | 209 | * return 0;
|
---|
[5767] | 210 | * }
|
---|
| 211 | * @endcode
|
---|
| 212 | *
|
---|
[5843] | 213 | * @param argc argument count, to be copied from what comes in with main().
|
---|
| 214 | * @param argv argument array, to be copied from what comes in with main().
|
---|
| 215 | * This may end up being modified by the option/argument sorting.
|
---|
| 216 | * @param paOptions array of RTOPTIONDEF structures, which must specify what options are understood by the program.
|
---|
| 217 | * @param cOptions number of array items passed in with paOptions.
|
---|
| 218 | * @param piThis address of stack counter used internally by RTGetOpt; value must be initialized to 1 before the first call!
|
---|
| 219 | * @param pValueUnion union with value; in the event of an error, psz member points to erroneous parameter; otherwise, for options
|
---|
| 220 | * that require an argument, this contains the value of that argument, depending on the type that is required.
|
---|
[5767] | 221 | */
|
---|
[8147] | 222 | RTDECL(int) RTGetOpt(int argc, char **argv, PCRTOPTIONDEF paOptions, size_t cOptions, int *piThis, PRTOPTIONUNION pValueUnion);
|
---|
[5767] | 223 |
|
---|
| 224 | /** @} */
|
---|
| 225 |
|
---|
| 226 | __END_DECLS
|
---|
| 227 |
|
---|
| 228 | #endif
|
---|
| 229 |
|
---|