source/tools/toolutil/uoptions.h

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