Apache Portable Runtime
apr_getopt.h
Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_GETOPT_H
00018 #define APR_GETOPT_H
00019 
00020 /**
00021  * @file apr_getopt.h
00022  * @brief APR Command Arguments (getopt)
00023  */
00024 
00025 #include "apr_pools.h"
00026 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif /* __cplusplus */
00030 
00031 /**
00032  * @defgroup apr_getopt Command Argument Parsing
00033  * @ingroup APR 
00034  * @{
00035  */
00036 
00037 /** 
00038  * An @c apr_getopt_t error callback function.
00039  *
00040  * @a arg is this @c apr_getopt_t's @c errarg member.
00041  */
00042 typedef void (apr_getopt_err_fn_t)(void *arg, const char *err, ...);
00043 
00044 /** @see apr_getopt_t */
00045 typedef struct apr_getopt_t apr_getopt_t;
00046 
00047 /**
00048  * Structure to store command line argument information.
00049  */ 
00050 struct apr_getopt_t {
00051     /** context for processing */
00052     apr_pool_t *cont;
00053     /** function to print error message (NULL == no messages) */
00054     apr_getopt_err_fn_t *errfn;
00055     /** user defined first arg to pass to error message  */
00056     void *errarg;
00057     /** index into parent argv vector */
00058     int ind;
00059     /** character checked for validity */
00060     int opt;
00061     /** reset getopt */
00062     int reset;
00063     /** count of arguments */
00064     int argc;
00065     /** array of pointers to arguments */
00066     const char **argv;
00067     /** argument associated with option */
00068     char const* place;
00069     /** set to nonzero to support interleaving options with regular args */
00070     int interleave;
00071     /** start of non-option arguments skipped for interleaving */
00072     int skip_start;
00073     /** end of non-option arguments skipped for interleaving */
00074     int skip_end;
00075 };
00076 
00077 /** @see apr_getopt_option_t */
00078 typedef struct apr_getopt_option_t apr_getopt_option_t;
00079 
00080 /**
00081  * Structure used to describe options that getopt should search for.
00082  */
00083 struct apr_getopt_option_t {
00084     /** long option name, or NULL if option has no long name */
00085     const char *name;
00086     /** option letter, or a value greater than 255 if option has no letter */
00087     int optch;
00088     /** nonzero if option takes an argument */
00089     int has_arg;
00090     /** a description of the option */
00091     const char *description;
00092 };
00093 
00094 /**
00095  * Initialize the arguments for parsing by apr_getopt().
00096  * @param os   The options structure created for apr_getopt()
00097  * @param cont The pool to operate on
00098  * @param argc The number of arguments to parse
00099  * @param argv The array of arguments to parse
00100  * @remark Arguments 3 and 4 are most commonly argc and argv from main(argc, argv)
00101  * The (*os)->errfn is initialized to fprintf(stderr... but may be overridden.
00102  */
00103 APR_DECLARE(apr_status_t) apr_getopt_init(apr_getopt_t **os, apr_pool_t *cont,
00104                                       int argc, const char * const *argv);
00105 
00106 /**
00107  * Parse the options initialized by apr_getopt_init().
00108  * @param os     The apr_opt_t structure returned by apr_getopt_init()
00109  * @param opts   A string of characters that are acceptable options to the 
00110  *               program.  Characters followed by ":" are required to have an 
00111  *               option associated
00112  * @param option_ch  The next option character parsed
00113  * @param option_arg The argument following the option character:
00114  * @return There are four potential status values on exit. They are:
00115  * <PRE>
00116  *             APR_EOF      --  No more options to parse
00117  *             APR_BADCH    --  Found a bad option character
00118  *             APR_BADARG   --  No argument followed the option flag
00119  *             APR_SUCCESS  --  The next option was found.
00120  * </PRE>
00121  */
00122 APR_DECLARE(apr_status_t) apr_getopt(apr_getopt_t *os, const char *opts, 
00123                                      char *option_ch, const char **option_arg);
00124 
00125 /**
00126  * Parse the options initialized by apr_getopt_init(), accepting long
00127  * options beginning with "--" in addition to single-character
00128  * options beginning with "-".
00129  * @param os     The apr_getopt_t structure created by apr_getopt_init()
00130  * @param opts   A pointer to a list of apr_getopt_option_t structures, which
00131  *               can be initialized with { "name", optch, has_args }.  has_args
00132  *               is nonzero if the option requires an argument.  A structure
00133  *               with an optch value of 0 terminates the list.
00134  * @param option_ch  Receives the value of "optch" from the apr_getopt_option_t
00135  *                   structure corresponding to the next option matched.
00136  * @param option_arg Receives the argument following the option, if any.
00137  * @return There are four potential status values on exit.   They are:
00138  * <PRE>
00139  *             APR_EOF      --  No more options to parse
00140  *             APR_BADCH    --  Found a bad option character
00141  *             APR_BADARG   --  No argument followed the option flag
00142  *             APR_SUCCESS  --  The next option was found.
00143  * </PRE>
00144  * When APR_SUCCESS is returned, os->ind gives the index of the first
00145  * non-option argument.  On error, a message will be printed to stdout unless
00146  * os->err is set to 0.  If os->interleave is set to nonzero, options can come
00147  * after arguments, and os->argv will be permuted to leave non-option arguments
00148  * at the end (the original argv is unaffected).
00149  */
00150 APR_DECLARE(apr_status_t) apr_getopt_long(apr_getopt_t *os,
00151                                           const apr_getopt_option_t *opts,
00152                                           int *option_ch,
00153                                           const char **option_arg);
00154 /** @} */
00155 
00156 #ifdef __cplusplus
00157 }
00158 #endif
00159 
00160 #endif  /* ! APR_GETOPT_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines