michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: /* michael@0: ** File: plgetopt.h michael@0: ** Description: utilities to parse argc/argv michael@0: */ michael@0: michael@0: #if defined(PLGETOPT_H_) michael@0: #else michael@0: #define PLGETOPT_H_ michael@0: michael@0: #include "prtypes.h" michael@0: michael@0: PR_BEGIN_EXTERN_C michael@0: michael@0: typedef struct PLOptionInternal PLOptionInternal; michael@0: michael@0: typedef enum michael@0: { michael@0: PL_OPT_OK, /* all's well with the option */ michael@0: PL_OPT_EOL, /* end of options list */ michael@0: PL_OPT_BAD /* invalid option (and value) */ michael@0: } PLOptStatus; michael@0: michael@0: typedef struct PLLongOpt michael@0: { michael@0: const char * longOptName; /* long option name string */ michael@0: PRIntn longOption; /* value put in PLOptState for this option. */ michael@0: PRBool valueRequired; /* If option name not followed by '=', */ michael@0: /* value is the next argument from argv. */ michael@0: } PLLongOpt; michael@0: michael@0: typedef struct PLOptState michael@0: { michael@0: char option; /* the name of the option */ michael@0: const char *value; /* the value of that option | NULL */ michael@0: michael@0: PLOptionInternal *internal; /* private processing state */ michael@0: michael@0: PRIntn longOption; /* value from PLLongOpt put here */ michael@0: PRIntn longOptIndex; /* index into caller's array of PLLongOpts */ michael@0: } PLOptState; michael@0: michael@0: /* michael@0: * PL_CreateOptState michael@0: * michael@0: * The argument "options" points to a string of single-character option michael@0: * names. Option names that may have an option argument value must be michael@0: * followed immediately by a ':' character. michael@0: */ michael@0: PR_EXTERN(PLOptState*) PL_CreateOptState( michael@0: PRIntn argc, char **argv, const char *options); michael@0: michael@0: /* michael@0: * PL_CreateLongOptState michael@0: * michael@0: * Alternative to PL_CreateOptState. michael@0: * Allows caller to specify BOTH a string of single-character option names, michael@0: * AND an array of structures describing "long" (keyword) option names. michael@0: * The array is terminated by a structure in which longOptName is NULL. michael@0: * Long option values (arguments) may always be given as "--name=value". michael@0: * If PLLongOpt.valueRequired is not PR_FALSE, and the option name was not michael@0: * followed by '=' then the next argument from argv is taken as the value. michael@0: */ michael@0: PR_EXTERN(PLOptState*) PL_CreateLongOptState( michael@0: PRIntn argc, char **argv, const char *options, michael@0: const PLLongOpt *longOpts); michael@0: /* michael@0: * PL_DestroyOptState michael@0: * michael@0: * Call this to destroy the PLOptState returned from PL_CreateOptState or michael@0: * PL_CreateLongOptState. michael@0: */ michael@0: PR_EXTERN(void) PL_DestroyOptState(PLOptState *opt); michael@0: michael@0: /* michael@0: * PL_GetNextOpt michael@0: * michael@0: * When this function returns PL_OPT_OK, michael@0: * - opt->option will hold the single-character option name that was parsed, michael@0: * or zero. michael@0: * When opt->option is zero, the token parsed was either a "long" (keyword) michael@0: * option or a positional parameter. michael@0: * For a positional parameter, michael@0: * - opt->longOptIndex will contain -1, and michael@0: * - opt->value will point to the positional parameter string. michael@0: * For a long option name, michael@0: * - opt->longOptIndex will contain the non-negative index of the michael@0: * PLLongOpt structure in the caller's array of PLLongOpt structures michael@0: * corresponding to the long option name, and michael@0: * For a single-character or long option, michael@0: * - opt->longOption will contain the value of the single-character option michael@0: * name, or the value of the longOption from the PLLongOpt structure michael@0: * for that long option. See notes below. michael@0: * - opt->value will point to the argument option string, or will michael@0: * be NULL if option does not require argument. If option requires michael@0: * argument but it is not provided, PL_OPT_BAD is returned. michael@0: * When opt->option is non-zero, michael@0: * - opt->longOptIndex will be -1 michael@0: * When this function returns PL_OPT_EOL, or PL_OPT_BAD, the contents of michael@0: * opt are undefined. michael@0: * michael@0: * Notes: It is possible to ignore opt->option, and always look at michael@0: * opt->longOption instead. opt->longOption will contain the same value michael@0: * as opt->option for single-character option names, and will contain the michael@0: * value of longOption from the PLLongOpt structure for long option names. michael@0: * This means that it is possible to equivalence long option names to michael@0: * single character names by giving the longOption in the PLLongOpt struct michael@0: * the same value as the single-character option name. michael@0: * For long options that are NOT intended to be equivalent to any single- michael@0: * character option, the longOption value should be chosen to not match michael@0: * any possible single character name. It might be advisable to choose michael@0: * longOption values greater than 0xff for such long options. michael@0: */ michael@0: PR_EXTERN(PLOptStatus) PL_GetNextOpt(PLOptState *opt); michael@0: michael@0: PR_END_EXTERN_C michael@0: michael@0: #endif /* defined(PLGETOPT_H_) */ michael@0: michael@0: /* plgetopt.h */ michael@0: