Home | History | Annotate | Download | only in toolutil
      1 /*
      2 *******************************************************************************
      3 *
      4 *   Copyright (C) 2000-2011, International Business Machines
      5 *   Corporation and others.  All Rights Reserved.
      6 *
      7 *******************************************************************************
      8 *   file name:  uoptions.h
      9 *   encoding:   US-ASCII
     10 *   tab size:   8 (not used)
     11 *   indentation:4
     12 *
     13 *   created on: 2000apr17
     14 *   created by: Markus W. Scherer
     15 *
     16 *   This file provides a command line argument parser.
     17 */
     18 
     19 #ifndef __UOPTIONS_H__
     20 #define __UOPTIONS_H__
     21 
     22 #include "unicode/utypes.h"
     23 
     24 /* This should usually be called before calling u_parseArgs */
     25 /*#if U_PLATFORM == U_PF_OS390 && (U_CHARSET_FAMILY == U_ASCII_FAMILY)*/
     26     /* translate args from EBCDIC to ASCII */
     27 /*#   define U_MAIN_INIT_ARGS(argc, argv) __argvtoascii_a(argc, argv)*/
     28 /*#elif defined(XP_MAC_CONSOLE)*/
     29 #if defined(XP_MAC_CONSOLE)
     30 #   include <console.h>
     31     /* Get the arguments from the GUI, since old Macs don't have a console Window. */
     32 #   define U_MAIN_INIT_ARGS(argc, argv) argc = ccommand((char***)&argv)
     33 #else
     34     /* Normally we do nothing. */
     35 #   define U_MAIN_INIT_ARGS(argc, argv)
     36 #endif
     37 
     38 
     39 
     40 /* forward declarations for the function declaration */
     41 struct UOption;
     42 typedef struct UOption UOption;
     43 
     44 /* function to be called for a command line option */
     45 typedef int UOptionFn(void *context, UOption *option);
     46 
     47 /* values of UOption.hasArg */
     48 enum { UOPT_NO_ARG, UOPT_REQUIRES_ARG, UOPT_OPTIONAL_ARG };
     49 
     50 /* structure describing a command line option */
     51 struct UOption {
     52     const char *longName;   /* "foo" for --foo */
     53     const char *value;      /* output placeholder, will point to the argument string, if any */
     54     UOptionFn *optionFn;    /* function to be called when this option occurs */
     55     void *context;          /* parameter for the function */
     56     char shortName;         /* 'f' for -f */
     57     char hasArg;            /* enum value: option takes no/requires/may have argument */
     58     char doesOccur;         /* boolean for "this one occured" */
     59 };
     60 
     61 /* macro for an entry in a declaration of UOption[] */
     62 #define UOPTION_DEF(longName, shortName, hasArg) \
     63     { longName, NULL, NULL, NULL, shortName, hasArg, 0 }
     64 
     65 /* ICU Tools option definitions */
     66 #define UOPTION_HELP_H              UOPTION_DEF("help", 'h', UOPT_NO_ARG)
     67 #define UOPTION_HELP_QUESTION_MARK  UOPTION_DEF("help", '?', UOPT_NO_ARG)
     68 #define UOPTION_VERBOSE             UOPTION_DEF("verbose", 'v', UOPT_NO_ARG)
     69 #define UOPTION_QUIET               UOPTION_DEF("quiet", 'q', UOPT_NO_ARG)
     70 #define UOPTION_VERSION             UOPTION_DEF("version", 'V', UOPT_NO_ARG)
     71 #define UOPTION_COPYRIGHT           UOPTION_DEF("copyright", 'c', UOPT_NO_ARG)
     72 
     73 #define UOPTION_DESTDIR             UOPTION_DEF("destdir", 'd', UOPT_REQUIRES_ARG)
     74 #define UOPTION_SOURCEDIR           UOPTION_DEF("sourcedir", 's', UOPT_REQUIRES_ARG)
     75 #define UOPTION_ENCODING            UOPTION_DEF("encoding", 'e', UOPT_REQUIRES_ARG)
     76 #define UOPTION_ICUDATADIR          UOPTION_DEF("icudatadir", 'i', UOPT_REQUIRES_ARG)
     77 #define UOPTION_WRITE_JAVA          UOPTION_DEF("write-java", 'j', UOPT_OPTIONAL_ARG)
     78 #define UOPTION_PACKAGE_NAME        UOPTION_DEF("package-name", 'p', UOPT_REQUIRES_ARG)
     79 #define UOPTION_BUNDLE_NAME         UOPTION_DEF("bundle-name", 'b', UOPT_REQUIRES_ARG)
     80 
     81 /**
     82  * C Command line argument parser.
     83  *
     84  * This function takes the argv[argc] command line and a description of
     85  * the program's options in form of an array of UOption structures.
     86  * Each UOption defines a long and a short name (a string and a character)
     87  * for options like "--foo" and "-f".
     88  *
     89  * Each option is marked with whether it does not take an argument,
     90  * requires one, or optionally takes one. The argument may follow in
     91  * the same argv[] entry for short options, or it may always follow
     92  * in the next argv[] entry.
     93  *
     94  * An argument is in the next argv[] entry for both long and short name
     95  * options, except it is taken from directly behind the short name in
     96  * its own argv[] entry if there are characters following the option letter.
     97  * An argument in its own argv[] entry must not begin with a '-'
     98  * unless it is only the '-' itself. There is no restriction of the
     99  * argument format if it is part of the short name options's argv[] entry.
    100  *
    101  * The argument is stored in the value field of the corresponding
    102  * UOption entry, and the doesOccur field is set to 1 if the option
    103  * is found at all.
    104  *
    105  * Short name options without arguments can be collapsed into a single
    106  * argv[] entry. After an option letter takes an argument, following
    107  * letters will be taken as its argument.
    108  *
    109  * If the same option is found several times, then the last
    110  * argument value will be stored in the value field.
    111  *
    112  * For each option, a function can be called. This could be used
    113  * for options that occur multiple times and all arguments are to
    114  * be collected.
    115  *
    116  * All options are removed from the argv[] array itself. If the parser
    117  * is successful, then it returns the number of remaining non-option
    118  * strings (including argv[0]).
    119  * argv[0], the program name, is never read or modified.
    120  *
    121  * An option "--" ends option processing; everything after this
    122  * remains in the argv[] array.
    123  *
    124  * An option string "-" alone is treated as a non-option.
    125  *
    126  * If an option is not recognized or an argument missing, then
    127  * the parser returns with the negative index of the argv[] entry
    128  * where the error was detected.
    129  *
    130  * The OS/400 compiler requires that argv either be "char* argv[]",
    131  * or "const char* const argv[]", and it will not accept,
    132  * "const char* argv[]" as a definition for main().
    133  *
    134  * @param argv This parameter is modified
    135  * @param options This parameter is modified
    136  */
    137 U_CAPI int U_EXPORT2
    138 u_parseArgs(int argc, char* argv[],
    139             int optionCount, UOption options[]);
    140 
    141 #endif
    142