1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 /* 7 ** File: plgetopt.h 8 ** Description: utilities to parse argc/argv 9 */ 10 11 #if defined(PLGETOPT_H_) 12 #else 13 #define PLGETOPT_H_ 14 15 #include "prtypes.h" 16 17 PR_BEGIN_EXTERN_C 18 19 typedef struct PLOptionInternal PLOptionInternal; 20 21 typedef enum 22 { 23 PL_OPT_OK, /* all's well with the option */ 24 PL_OPT_EOL, /* end of options list */ 25 PL_OPT_BAD /* invalid option (and value) */ 26 } PLOptStatus; 27 28 typedef struct PLLongOpt 29 { 30 const char * longOptName; /* long option name string */ 31 PRIntn longOption; /* value put in PLOptState for this option. */ 32 PRBool valueRequired; /* If option name not followed by '=', */ 33 /* value is the next argument from argv. */ 34 } PLLongOpt; 35 36 typedef struct PLOptState 37 { 38 char option; /* the name of the option */ 39 const char *value; /* the value of that option | NULL */ 40 41 PLOptionInternal *internal; /* private processing state */ 42 43 PRIntn longOption; /* value from PLLongOpt put here */ 44 PRIntn longOptIndex; /* index into caller's array of PLLongOpts */ 45 } PLOptState; 46 47 /* 48 * PL_CreateOptState 49 * 50 * The argument "options" points to a string of single-character option 51 * names. Option names that may have an option argument value must be 52 * followed immediately by a ':' character. 53 */ 54 PR_EXTERN(PLOptState*) PL_CreateOptState( 55 PRIntn argc, char **argv, const char *options); 56 57 /* 58 * PL_CreateLongOptState 59 * 60 * Alternative to PL_CreateOptState. 61 * Allows caller to specify BOTH a string of single-character option names, 62 * AND an array of structures describing "long" (keyword) option names. 63 * The array is terminated by a structure in which longOptName is NULL. 64 * Long option values (arguments) may always be given as "--name=value". 65 * If PLLongOpt.valueRequired is not PR_FALSE, and the option name was not 66 * followed by '=' then the next argument from argv is taken as the value. 67 */ 68 PR_EXTERN(PLOptState*) PL_CreateLongOptState( 69 PRIntn argc, char **argv, const char *options, 70 const PLLongOpt *longOpts); 71 /* 72 * PL_DestroyOptState 73 * 74 * Call this to destroy the PLOptState returned from PL_CreateOptState or 75 * PL_CreateLongOptState. 76 */ 77 PR_EXTERN(void) PL_DestroyOptState(PLOptState *opt); 78 79 /* 80 * PL_GetNextOpt 81 * 82 * When this function returns PL_OPT_OK, 83 * - opt->option will hold the single-character option name that was parsed, 84 * or zero. 85 * When opt->option is zero, the token parsed was either a "long" (keyword) 86 * option or a positional parameter. 87 * For a positional parameter, 88 * - opt->longOptIndex will contain -1, and 89 * - opt->value will point to the positional parameter string. 90 * For a long option name, 91 * - opt->longOptIndex will contain the non-negative index of the 92 * PLLongOpt structure in the caller's array of PLLongOpt structures 93 * corresponding to the long option name, and 94 * For a single-character or long option, 95 * - opt->longOption will contain the value of the single-character option 96 * name, or the value of the longOption from the PLLongOpt structure 97 * for that long option. See notes below. 98 * - opt->value will point to the argument option string, or will 99 * be NULL if option does not require argument. If option requires 100 * argument but it is not provided, PL_OPT_BAD is returned. 101 * When opt->option is non-zero, 102 * - opt->longOptIndex will be -1 103 * When this function returns PL_OPT_EOL, or PL_OPT_BAD, the contents of 104 * opt are undefined. 105 * 106 * Notes: It is possible to ignore opt->option, and always look at 107 * opt->longOption instead. opt->longOption will contain the same value 108 * as opt->option for single-character option names, and will contain the 109 * value of longOption from the PLLongOpt structure for long option names. 110 * This means that it is possible to equivalence long option names to 111 * single character names by giving the longOption in the PLLongOpt struct 112 * the same value as the single-character option name. 113 * For long options that are NOT intended to be equivalent to any single- 114 * character option, the longOption value should be chosen to not match 115 * any possible single character name. It might be advisable to choose 116 * longOption values greater than 0xff for such long options. 117 */ 118 PR_EXTERN(PLOptStatus) PL_GetNextOpt(PLOptState *opt); 119 120 PR_END_EXTERN_C 121 122 #endif /* defined(PLGETOPT_H_) */ 123 124 /* plgetopt.h */ 125 126