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  * defintion of a error function 
00039  */
00040 typedef void (apr_getopt_err_fn_t)(void *arg, const char *err, ...);
00041 
00042 /** @see apr_getopt_t */
00043 typedef struct apr_getopt_t apr_getopt_t;
00044 
00045 /**
00046  * Structure to store command line argument information.
00047  */ 
00048 struct apr_getopt_t {
00049     /** context for processing */
00050     apr_pool_t *cont;
00051     /** function to print error message (NULL == no messages) */
00052     apr_getopt_err_fn_t *errfn;
00053     /** user defined first arg to pass to error message  */
00054     void *errarg;
00055     /** index into parent argv vector */
00056     int ind;
00057     /** character checked for validity */
00058     int opt;
00059     /** reset getopt */
00060     int reset;
00061     /** count of arguments */
00062     int argc;
00063     /** array of pointers to arguments */
00064     const char **argv;
00065     /** argument associated with option */
00066     char const* place;
00067     /** set to nonzero to support interleaving options with regular args */
00068     int interleave;
00069     /** start of non-option arguments skipped for interleaving */
00070     int skip_start;
00071     /** end of non-option arguments skipped for interleaving */
00072     int skip_end;
00073 };
00074 
00075 /** @see apr_getopt_option_t */
00076 typedef struct apr_getopt_option_t apr_getopt_option_t;
00077 
00078 /**
00079  * Structure used to describe options that getopt should search for.
00080  */
00081 struct apr_getopt_option_t {
00082     /** long option name, or NULL if option has no long name */
00083     const char *name;
00084     /** option letter, or a value greater than 255 if option has no letter */
00085     int optch;
00086     /** nonzero if option takes an argument */
00087     int has_arg;
00088     /** a description of the option */
00089     const char *description;
00090 };
00091 
00092 /**
00093  * Initialize the arguments for parsing by apr_getopt().
00094  * @param os   The options structure created for apr_getopt()
00095  * @param cont The pool to operate on
00096  * @param argc The number of arguments to parse
00097  * @param argv The array of arguments to parse
00098  * @remark Arguments 2 and 3 are most commonly argc and argv from main(argc, argv)
00099  * The errfn is initialized to fprintf(stderr... but may be overridden.
00100  */
00101 APR_DECLARE(apr_status_t) apr_getopt_init(apr_getopt_t **os, apr_pool_t *cont,
00102                                       int argc, const char * const *argv);
00103 
00104 /**
00105  * Parse the options initialized by apr_getopt_init().
00106  * @param os     The apr_opt_t structure returned by apr_getopt_init()
00107  * @param opts   A string of characters that are acceptable options to the 
00108  *               program.  Characters followed by ":" are required to have an 
00109  *               option associated
00110  * @param option_ch  The next option character parsed
00111  * @param option_arg The argument following the option character:
00112  * @return There are four potential status values on exit. They are:
00113  * <PRE>
00114  *             APR_EOF      --  No more options to parse
00115  *             APR_BADCH    --  Found a bad option character
00116  *             APR_BADARG   --  No argument followed the option flag
00117  *             APR_SUCCESS  --  The next option was found.
00118  * </PRE>
00119  */
00120 APR_DECLARE(apr_status_t) apr_getopt(apr_getopt_t *os, const char *opts, 
00121                                      char *option_ch, const char **option_arg);
00122 
00123 /**
00124  * Parse the options initialized by apr_getopt_init(), accepting long
00125  * options beginning with "--" in addition to single-character
00126  * options beginning with "-".
00127  * @param os     The apr_getopt_t structure created by apr_getopt_init()
00128  * @param opts   A pointer to a list of apr_getopt_option_t structures, which
00129  *               can be initialized with { "name", optch, has_args }.  has_args
00130  *               is nonzero if the option requires an argument.  A structure
00131  *               with an optch value of 0 terminates the list.
00132  * @param option_ch  Receives the value of "optch" from the apr_getopt_option_t
00133  *                   structure corresponding to the next option matched.
00134  * @param option_arg Receives the argument following the option, if any.
00135  * @return There are four potential status values on exit.   They are:
00136  * <PRE>
00137  *             APR_EOF      --  No more options to parse
00138  *             APR_BADCH    --  Found a bad option character
00139  *             APR_BADARG   --  No argument followed the option flag
00140  *             APR_SUCCESS  --  The next option was found.
00141  * </PRE>
00142  * When APR_SUCCESS is returned, os->ind gives the index of the first
00143  * non-option argument.  On error, a message will be printed to stdout unless
00144  * os->err is set to 0.  If os->interleave is set to nonzero, options can come
00145  * after arguments, and os->argv will be permuted to leave non-option arguments
00146  * at the end (the original argv is unaffected).
00147  */
00148 APR_DECLARE(apr_status_t) apr_getopt_long(apr_getopt_t *os,
00149                                           const apr_getopt_option_t *opts,
00150                                           int *option_ch,
00151                                           const char **option_arg);
00152 /** @} */
00153 
00154 #ifdef __cplusplus
00155 }
00156 #endif
00157 
00158 #endif  /* ! APR_GETOPT_H */

Generated on Mon Nov 26 11:23:52 2007 for Apache Portable Runtime by  doxygen 1.5.2