[prev in list] [next in list] [prev in thread] [next in thread]
List: busybox
Subject: [BusyBox] [PATCH] getopt_ulflags improved comments.
From: Tito <farmatito () tiscali ! it>
Date: 2004-12-12 12:59:03
Message-ID: 200412121359.03877.farmatito () tiscali ! it
[Download RAW message or body]
Hi to all,
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.
Please apply.
Ciao,
Tito
["getopt_ulflags_comments.patch" (text/x-diff)]
--- getopt_ulflags.c 2004-02-05 14:49:29.000000000 +0100
+++ getopt_ulflags_fixed_text_v3.c 2004-12-12 13:44:21.286944488 +0100
@@ -27,33 +27,132 @@
#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.
+bb_getopt_ulflags (int argc, char **argv, const char *applet_opts, ...)
+usage:
+
+ 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 usage:
+
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);
+
+ ":" 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;
_______________________________________________
busybox mailing list
busybox@mail.busybox.net
http://codepoet.org/mailman/listinfo/busybox
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic