libbb/getopt_ulflags.c

   1 /* vi: set sw=4 ts=4: */
   2 /*
   3  * universal getopt_ulflags implementation for busybox
   4  *
   5  * Copyright (C) 2003  Vladimir Oleynik  <dzo@simtreas.ru>
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  15  * General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  20  *
  21  */
  22
  23 #include <getopt.h>
  24 #include <string.h>
  25 #include <assert.h>
  26 #include <stdlib.h>
  27 #include "libbb.h"
  28
  29 /*                  Documentation !
  30
  31 unsigned long
  32 bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...)
  33
  34           The command line options must be declared in const char
  35           *applet_opts as a string of chars, for example:
  36
  37           flags = bb_getopt_ulflags(argc, argv, "rnug");
  38
  39           If one of the given options is found, a flag value is added to
  40           the return value (an unsigned long).
  41
  42           The flag value is determined by the position of the char in
  43           applet_opts string.  For example, in the above case:
  44
  45           flags = bb_getopt_ulflags(argc, argv, "rnug");
  46
  47           "r" will add 1    (bit 1 : 0x01)
  48           "n" will add 2    (bit 2 : 0x02)
  49           "u  will add 4    (bit 3 : 0x03)
  50           "g" will add 8    (bit 4 : 0x04)
  51
  52            and so on.  You can also look at the return value as a bit
  53            field and each option sets one of bits.
  54
  55    ":"     If one of the options requires an argument, then add a ":"
  56            after the char in applet_opts and provide a pointer to store
  57            the argument.  For example:
  58
  59            char *pointer_to_arg_for_a;
  60            char *pointer_to_arg_for_b;
  61            char *pointer_to_arg_for_c;
  62            char *pointer_to_arg_for_d;
  63
  64            flags = bb_getopt_ulflags(argc, argv, "a:b:c:d:",
  65                             &pointer_to_arg_for_a, &pointer_to_arg_for_b,
  66                             &pointer_to_arg_for_c, &pointer_to_arg_for_d);
  67
  68            The type of the pointer (char* or llist_t *) may be controlled
  69            by the "*" special character that is set in the external string
  70            bb_opt_complementaly (see below for more info).
  71
  72 static const struct option bb_default_long_options[]
  73
  74            This struct allows you to define long options.  The syntax for
  75            declaring the array is just like that of getopt's longopts.
  76
  77            static const struct option applet_long_options[] = {
  78                    { "verbose", 0, 0, "v" },
  79                    { 0, 0, 0, 0 }
  80            };
  81            bb_applet_long_options = applet_long_options;
  82
  83            The first parameter is the long option name that you would pass
  84            to the applet (without the dashes).
  85
  86            The second field determines whether the option has an argument.
  87            You can set this to 0, 1, or 2, or you can use the long named
  88            defines of no_argument, required_argument, and optional_argument.
  89
  90            The third argument is used only when the long option does not
  91            have a corresponding short option.  In that case, it should be
  92            an integer pointer.  Otherwise (and normally), it should just
  93            bet set to NULL.
  94
  95            The last argument is the corresponding short option (if there
  96            is one of course).
  97
  98            Note: a good applet will make long options configurable via the
  99            config process and not a required feature.  The current standard
 100            is to name the config option CONFIG_FEATURE_<applet>_LONG_OPTIONS.
 101
 102 const char *bb_opt_complementaly
 103
 104    ":"     The colon (":") is used to separate groups of two or more chars
 105            and/or groups of chars and special characters (stating some
 106            conditions to be checked).
 107
 108    "abc"   If groups of two or more chars are specified, the first char
 109            is the main option and the other chars are secondary options.
 110            Their flags will be turned on if the main option is found even
 111            if they are not specifed on the command line.  For example:
 112
 113            bb_opt_complementaly = "abc";
 114
 115            flags = bb_getopt_ulflags(argc, argv, "abcd")
 116
 117            If getopt() finds "-a" on the command line, then
 118            bb_getopt_ulflags's return value will be as if "-a -b -c" were
 119            found.
 120
 121 Special characters:
 122
 123    "-"     A dash between two options causes the second of the two
 124            to be unset (and ignored) if it is given on the command line.
 125
 126            For example:
 127            The du applet has the options "-s" and "-d depth".  If
 128            bb_getopt_ulflags finds -s, then -d is unset or if it finds -d
 129            then -s is unset.  (Note:  busybox implements the GNU
 130            "--max-depth" option as "-d".)  To obtain this behavior, you
 131            set bb_opt_complementaly = "s-d:d-s".  Only one flag value is
 132            added to bb_getopt_ulflags's return value depending on the
 133            position of the options on the command line.  If one of the
 134            two options requires an argument pointer (":" in applet_opts
 135            as in "d:") optarg is set accordingly.
 136
 137            char *smax_print_depth;
 138
 139            bb_opt_complementaly = "s-d:d-s";
 140            opt = bb_getopt_ulflags(argc, argv, "sd:", &smax_print_depth);
 141
 142            if (opt & 2) {
 143                     max_print_depth = bb_xgetularg10_bnd(smax_print_depth,
 144                                 0, INT_MAX);
 145            }
 146
 147    "~"     A tilde between two options, or between an option and a group
 148            of options, means that they are mutually exclusive.  Unlike
 149            the "-" case above, an error will be forced if the options
 150            are used together.
 151
 152            For example:
 153            The cut applet must have only one type of list specified, so
 154            -b, -c and -f are mutally exclusive and should raise an error
 155            if specified together.  In this case you must set
 156            bb_opt_complementaly = "b~cf:c~bf:f~bc".  If two of the
 157            mutually exclusive options are found, bb_getopt_ulflags's
 158            return value will have the error flag set (BB_GETOPT_ERROR) so
 159            that we can check for it:
 160
 161            if (flags & BB_GETOPT_ERROR)
 162                    bb_show_usage();
 163
 164    "*"     A star after a char in bb_opt_complementaly means that the
 165            option can occur multiple times:
 166
 167            For example:
 168            The grep applet can have one or more "-e pattern" arguments.
 169            In this case you should use bb_getopt_ulflags() as follows:
 170
 171            llist_t *patterns = NULL;
 172
 173            (this pointer must be initializated to NULL if the list is empty
 174            as required by *llist_add_to(llist_t *old_head, char *new_item).)
 175
 176            bb_opt_complementaly = "e*";
 177
 178            bb_getopt_ulflags(argc, argv, "e:", &patterns);
 179            $ grep -e user -e root /etc/passwd
 180            root:x:0:0:root:/root:/bin/bash
 181            user:x:500:500::/home/user:/bin/bash
 182
 183 */
 184
 185 const char *bb_opt_complementaly;
 186
 187 typedef struct {
 188         unsigned char opt;
 189         char list_flg;
 190         unsigned long switch_on;
 191         unsigned long switch_off;
 192         unsigned long incongruously;
 193         void **optarg;               /* char **optarg or llist_t **optarg */
 194 } t_complementaly;
 195
 196 /* You can set bb_applet_long_options for parse called long options */
 197
 198 static const struct option bb_default_long_options[] = {
 199 /*      { "help", 0, NULL, '?' }, */
 200         { 0, 0, 0, 0 }
 201 };
 202
 203 const struct option *bb_applet_long_options = bb_default_long_options;
 204
 205 unsigned long
 206 bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...)
 207 {
 208         unsigned long flags = 0;
 209         t_complementaly complementaly[sizeof(flags) * 8 + 1];
 210         int c;
 211         const unsigned char *s;
 212         t_complementaly *on_off;
 213         va_list p;
 214
 215         va_start (p, applet_opts);
 216
 217         /* skip GNU extension */
 218         s = applet_opts;
 219         if(*s == '+' || *s == '-')
 220                 s++;
 221
 222         c = 0;
 223         on_off = complementaly;
 224         for (; *s; s++) {
 225                 if(c >= (sizeof(flags)*8))
 226                         break;
 227                 on_off->opt = *s;
 228                 on_off->switch_on = (1 << c);
 229                 on_off->list_flg = 0;
 230                 on_off->switch_off = 0;
 231                 on_off->incongruously = 0;
 232                 on_off->optarg = NULL;
 233                 if (s[1] == ':') {
 234                         on_off->optarg = va_arg (p, void **);
 235                         do
 236                                 s++;
 237                         while (s[1] == ':');
 238                 }
 239                 on_off++;
 240                 c++;
 241         }
 242         on_off->opt = 0;
 243         c = 0;
 244         for (s = bb_opt_complementaly; s && *s; s++) {
 245                 t_complementaly *pair;
 246
 247                 if (*s == ':') {
 248                         c = 0;
 249                         continue;
 250                 }
 251                 if (c)
 252                         continue;
 253                 for (on_off = complementaly; on_off->opt; on_off++)
 254                         if (on_off->opt == *s)
 255                                 break;
 256                 pair = on_off;
 257                 for(s++; *s && *s != ':'; s++) {
 258                         if (*s == '-' || *s == '~') {
 259                                 c = *s;
 260                         } else if(*s == '*') {
 261                                 pair->list_flg++;
 262                         } else {
 263                                 unsigned long *pair_switch = &(pair->switch_on);
 264                                 if(c)
 265                                         pair_switch = c == '-' ? &(pair->switch_off) : &(pair->incongruously);
 266                                 for (on_off = complementaly; on_off->opt; on_off++)
 267                                         if (on_off->opt == *s) {
 268                                                 *pair_switch |= on_off->switch_on;
 269                                                 break;
 270                                         }
 271                         }
 272                 }
 273                 s--;
 274         }
 275
 276         while ((c = getopt_long (argc, argv, applet_opts,
 277                                  bb_applet_long_options, NULL)) > 0) {
 278                 for (on_off = complementaly; on_off->opt != c; on_off++) {
 279                         if(!on_off->opt)
 280                                 bb_show_usage ();
 281                 }
 282                 if(flags & on_off->incongruously)
 283                         flags |= BB_GETOPT_ERROR;
 284                 flags &= ~on_off->switch_off;
 285                 flags |= on_off->switch_on;
 286                 if(on_off->list_flg) {
 287                         *(llist_t **)(on_off->optarg) =
 288                                 llist_add_to(*(llist_t **)(on_off->optarg), optarg);
 289                 } else if (on_off->optarg) {
 290                         *(char **)(on_off->optarg) = optarg;
 291                 }
 292         }
 293
 294         return flags;
 295 }