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