In Bug 5, Tito writes:

This is a first attempt to improve the comments of getopt_ulflags.c.
Maybe under some aspects the text could be refined, but so
far it is already usable and should help people who "avoided getopt_ulflags as the pest" to understand how it works.

This patch was created with the help of
Vodz, the author of the code, who explained me patiently
how getopt_ulflags works
and with the help of
Paul Fox, who corrected my broken english.

So thanks and merits should go to them also.

1 files changed, 210 insertions, 116 deletions

diff --git a/libbb/getopt_ulflags.c b/libbb/getopt_ulflags.c
index 39a7d1d29..24bdcb653 100644
--- a/libbb/getopt_ulflags.c
+++ b/libbb/getopt_ulflags.c
@@ -26,146 +26,240 @@
 #include <stdlib.h>
 #include "libbb.h"
 
-/*
-You can set bb_opt_complementaly as string with one or more
-complementaly or incongruously options.
-If sequential founded option haved from this string
-then your incongruously pairs unsets and complementaly make add sets.
-Format:
-one char - option for check,
-chars - complementaly option for add sets.
-- chars - option triggered for unsets.
-~ chars - option incongruously.
-*       - option list, called add_to_list(*ptr_from_usaged, optarg)
-:       - separator.
-Example: du applet can have options "-s" and "-d size"
-If getopt found -s then -d option flag unset or if found -d then -s unset.
-For this result you must set bb_opt_complementaly = "s-d:d-s".
-Result have last option flag only from called arguments.
-Warning! You can check returned flag, pointer to "d:" argument seted
-to own optarg always.
-Example two: cut applet must only one type of list may be specified,
-and -b, -c and -f incongruously option, overwited option is error also.
-You must set bb_opt_complementaly = "b~cf:c~bf:f~bc".
-If called have more one specified, return value have error flag -
-high bite set (0x80000000UL).
-Example three: grep applet can have one or more "-e pattern" arguments.
-You should use bb_getopt_ulflags() as
-llist_t *paterns;
-bb_opt_complementaly = "e*";
-bb_getopt_ulflags (argc, argv, "e:", &paterns);
+/*                  Documentation !
+
+bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...)
+
+          The command line options must be declared in const char
+          *applet_opts as a string of chars, for example:
+
+          flags = bb_getopt_ulflags(argc, argv, "rnug");
+
+          If one of the given options is found a flag value is added to
+          the unsigned long returned by bb_getopt_ulflags.
+
+          The value of this flag is given by the position of the char in
+          const char *applet_opts so for example in this case:
+
+          flags = bb_getopt_ulflags(argc, argv, "rnug");
+
+          "r" will add 1
+          "n" will add 2
+          "u  will add 4
+          "g" will add 8
+
+           and so on.
+
+           If an argument is required by one of the options add a ":"
+           after the char in const char *applet_opts and provide a pointer
+           where the arg could be stored if it is found, for example:
+
+           char *pointer_to_arg_for_a;
+           char *pointer_to_arg_for_b;
+           char *pointer_to_arg_for_c;
+           char *pointer_to_arg_for_d;
+
+           flags = bb_getopt_ulflags(argc, argv, "a:b:c:d:",
+                            &pointer_to_arg_for_a, &pointer_to_arg_for_b,
+                            &pointer_to_arg_for_c, &pointer_to_arg_for_d);
+
+           The type of the pointer (char* or llist_t *) can be influenced
+           by the "*" special character that can be set in const char
+           *bb_opt_complementaly (see below).
+
+const char *bb_opt_complementaly
+
+   ":"     The colon (":") is used in bb_opt_complementaly as separator
+           between groups of two or more chars and/or groups of chars and
+           special characters (stating some conditions to be checked).
+
+   "abc"   If groups of two or more chars are specified the first char
+           is the main option and the other chars are secondary options
+           whose flags will be turned on if the main option is found even
+           if they are not specifed on the command line, for example:
+
+           bb_opt_complementaly = "abc";
+
+           flags = bb_getopt_ulflags(argc, argv, "abcd")
+
+           If getopt() finds "-a" on the command line, then
+           bb_getopt_ulflags's return value will be as if "-a -b -c" were
+           found.
+
+Special characters:
+
+   "-"     A dash between two options causes the second of the two
+           to be unset (and ignored) if it is given on the command line.
+
+           For example:
+           The du applet can have the options "-s" and "-d depth", if
+           bb_getopt_ulflags finds -s then -d is unset or if it finds -d
+           then -s is unset.  (Note:  busybox implements the GNU
+           "--max-depth" option as "-d".)  In this case bb_getopt_ulflags's
+           return value has no error flag set (0x80000000UL).  To achieve
+           this result you must set bb_opt_complementaly = "s-d:d-s".
+           Only one flag value is added to bb_getopt_ulflags's return
+           value depending on the position of the options on the command
+           line.  If one of the two options requires an argument pointer
+           (":" in const char *applet_opts as in "d:") optarg is set
+           accordingly.
+
+           char *smax_print_depth;
+
+           bb_opt_complementaly = "s-d:d-s";
+           opt = bb_getopt_ulflags(argc, argv, "sd:" , &smax_print_depth);
+
+           if (opt & 2) {
+                    max_print_depth = bb_xgetularg10_bnd(smax_print_depth,
+                                0, INT_MAX);
+           }
+
+   "~"     A tilde between two options or between an option and a group
+           of options means that they are mutually exclusive.  Unlike
+           the "-" case above, an error will be forced if the options
+           are used together.
+
+           For example:
+           The cut applet must have only one type of list specified, so
+           -b, -c and -f are mutally exclusive and should raise an error
+           if specified together.  In this case you must set
+           bb_opt_complementaly = "b~cf:c~bf:f~bc".  If two of the
+           mutually exclusive options are found, bb_getopt_ulflags's
+           return value will have the error flag set (0x80000000UL) so
+           that we can check for it:
+
+           if ((flags & 0x80000000UL)
+                   bb_show_usage();
+
+   "*"     A star after a char in bb_opt_complementaly means that the
+           option can occur multiple times:
+
+           For example:
+           The grep applet can have one or more "-e pattern" arguments.
+           In this case you should use bb_getopt_ulflags() as follows:
+
+           llist_t *patterns=NULL;
+
+           (this pointer must be initializated to NULL if the list is empty
+           as required by *llist_add_to(llist_t *old_head, char *new_item).)
+
+           bb_opt_complementaly = "e*";
+
+           bb_getopt_ulflags (argc, argv, "e:", &patterns);
+           grep -e user -e root /etc/passwd
+           root:x:0:0:root:/root:/bin/bash
+           user:x:500:500::/home/user:/bin/bash
+
 */
 
 const char *bb_opt_complementaly;
 
-typedef struct
-{
+typedef struct {
 	unsigned char opt;
 	char list_flg;
 	unsigned long switch_on;
 	unsigned long switch_off;
 	unsigned long incongruously;
-	void **optarg;              /* char **optarg or llist_t **optarg */
+	void **optarg;               /* char **optarg or llist_t **optarg */
 } t_complementaly;
 
 /* You can set bb_applet_long_options for parse called long options */
 
 static const struct option bb_default_long_options[] = {
-     /*   { "help", 0, NULL, '?' }, */
+/*	{ "help", 0, NULL, '?' }, */
 	{ 0, 0, 0, 0 }
 };
 
 const struct option *bb_applet_long_options = bb_default_long_options;
 
-
 unsigned long
 bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...)
 {
-  unsigned long flags = 0;
-  t_complementaly complementaly[sizeof(flags) * 8 + 1];
-  int c;
-  const unsigned char *s;
-  t_complementaly *on_off;
-  va_list p;
-
-  va_start (p, applet_opts);
-
-  /* skip GNU extension */
-  s = applet_opts;
-  if(*s == '+' || *s == '-')
-	s++;
-
-  c = 0;
-  on_off = complementaly;
-  for (; *s; s++) {
-	if(c >= (sizeof(flags)*8))
-		break;
-	on_off->opt = *s;
-	on_off->switch_on = (1 << c);
-	on_off->list_flg = 0;
-	on_off->switch_off = 0;
-	on_off->incongruously = 0;
-	on_off->optarg = NULL;
-	if (s[1] == ':') {
-	  on_off->optarg = va_arg (p, void **);
-	  do
+	unsigned long flags = 0;
+	t_complementaly complementaly[sizeof(flags) * 8 + 1];
+	int c;
+	const unsigned char *s;
+	t_complementaly *on_off;
+	va_list p;
+
+	va_start (p, applet_opts);
+
+	/* skip GNU extension */
+	s = applet_opts;
+	if(*s == '+' || *s == '-')
 		s++;
-	  while (s[1] == ':');
+
+	c = 0;
+	on_off = complementaly;
+	for (; *s; s++) {
+		if(c >= (sizeof(flags)*8))
+			break;
+		on_off->opt = *s;
+		on_off->switch_on = (1 << c);
+		on_off->list_flg = 0;
+		on_off->switch_off = 0;
+		on_off->incongruously = 0;
+		on_off->optarg = NULL;
+		if (s[1] == ':') {
+			on_off->optarg = va_arg (p, void **);
+			do
+				s++;
+			while (s[1] == ':');
+		}
+		on_off++;
+		c++;
 	}
-	on_off++;
-	c++;
-  }
-  on_off->opt = 0;
-  c = 0;
-  for (s = bb_opt_complementaly; s && *s; s++) {
-    t_complementaly *pair;
-
-    if (*s == ':') {
-	  c = 0;
-	  continue;
-    }
-    if (c)
-	  continue;
-    for (on_off = complementaly; on_off->opt; on_off++)
-	  if (on_off->opt == *s)
-	    break;
-    pair = on_off;
-    for(s++; *s && *s != ':'; s++) {
-      if (*s == '-' || *s == '~') {
-	  c = *s;
-      } else if(*s == '*') {
-	pair->list_flg++;
-      } else {
-	  unsigned long *pair_switch = &(pair->switch_on);
-
-	  if(c)
-	    pair_switch = c == '-' ? &(pair->switch_off) : &(pair->incongruously);
-	  for (on_off = complementaly; on_off->opt; on_off++)
-	    if (on_off->opt == *s) {
-		  *pair_switch |= on_off->switch_on;
-		  break;
-	    }
-      }
-    }
-    s--;
-  }
-
-  while ((c = getopt_long (argc, argv, applet_opts,
-			    bb_applet_long_options, NULL)) > 0) {
-	for (on_off = complementaly; on_off->opt != c; on_off++) {
-	    if(!on_off->opt)
-			bb_show_usage ();
+	on_off->opt = 0;
+	c = 0;
+	for (s = bb_opt_complementaly; s && *s; s++) {
+		t_complementaly *pair;
+
+		if (*s == ':') {
+			c = 0;
+			continue;
+		}
+		if (c)
+			continue;
+		for (on_off = complementaly; on_off->opt; on_off++)
+			if (on_off->opt == *s)
+				break;
+		pair = on_off;
+		for(s++; *s && *s != ':'; s++) {
+			if (*s == '-' || *s == '~') {
+				c = *s;
+			} else if(*s == '*') {
+				pair->list_flg++;
+			} else {
+				unsigned long *pair_switch = &(pair->switch_on);
+				if(c)
+					pair_switch = c == '-' ? &(pair->switch_off) : &(pair->incongruously);
+				for (on_off = complementaly; on_off->opt; on_off++)
+					if (on_off->opt == *s) {
+						*pair_switch |= on_off->switch_on;
+						break;
+					}
+			}
+		}
+		s--;
 	}
-	if(flags & on_off->incongruously)
-	    flags |= 0x80000000UL;
-	flags &= ~on_off->switch_off;
-	flags |= on_off->switch_on;
-	if(on_off->list_flg) {
-	   *(llist_t **)(on_off->optarg) =
-		llist_add_to(*(llist_t **)(on_off->optarg), optarg);
-	} else if (on_off->optarg) {
-	    *(char **)(on_off->optarg) = optarg;
+
+	while ((c = getopt_long (argc, argv, applet_opts,
+	                         bb_applet_long_options, NULL)) > 0) {
+		for (on_off = complementaly; on_off->opt != c; on_off++) {
+			if(!on_off->opt)
+				bb_show_usage ();
+		}
+		if(flags & on_off->incongruously)
+			flags |= 0x80000000UL;
+		flags &= ~on_off->switch_off;
+		flags |= on_off->switch_on;
+		if(on_off->list_flg) {
+			*(llist_t **)(on_off->optarg) =
+				llist_add_to(*(llist_t **)(on_off->optarg), optarg);
+		} else if (on_off->optarg) {
+			*(char **)(on_off->optarg) = optarg;
+		}
 	}
-  }
-  return flags;
+
+	return flags;
 }