--- name: "ACE_Arg_Shifter" section: "3" platform: "linux" package: "libace-doc" version: "5.0.7-4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/ACE_Arg_Shifter" --- # ACE\_Arg\_Shifter(3) This ADT shifts known args to the back of the argv vector, so deeper levels of argument parsing can locate the yet unprocessed arguments at the beginning of the vector. ## NAME ACE\_Arg\_Shifter - This ADT shifts known args to the back of the argv vector, so deeper levels of argument parsing can locate the yet unprocessed arguments at the beginning of the vector. ## SYNOPSIS ``` #include class ACE_Arg_Shifter { public: ACE_Arg_Shifter (int& argc, char** argv, char** temp = 0); ~ACE_Arg_Shifter (void); char* get_current (void) const; char* get_the_parameter (const char* flag); int cur_arg_strncasecmp (const char* flag); int consume_arg (int number = 1); int ignore_arg (int number = 1); int is_anything_left (void) const; int is_option_next (void) const; int is_parameter_next (void) const; int num_ignored_args (void) const; private: int& argc_; int total_size_; char** temp_; char** argv_; int current_index_; int back_; int front_; }; ``` ## DESCRIPTION The ACE\_Arg\_Shifter copies the pointers of the argv vector into a temporary array. As the ACE\_Arg\_Shifter iterates over the temp, is places known arguments in the rear of the argv and unknown ones in the beginning. So, after having visited all the arguments in the temp vector, ACE\_Arg\_Shifter has placed all the unknown arguments in their original order at the front of argv. ## Initialization and termination methods. ``` ACE_Arg_Shifter (int& argc, char** argv, char** temp = 0); ``` Initialize the ACE\_Arg\_Shifter to the vector over which to iterate, also providing the temporary array if the client doesn't want the arg\_shifter to dynamically allocate its own. If internal dynamic allocation fails, the ACE\_Arg\_Shifter will set all the indices to the end of the vector, forbidding iteration. Following iteration over argv, the argc value will contain the number of unconsumed arguments. ``` ~ACE_Arg_Shifter (void); ``` Destructor. ``` char* get_current (void) const; ``` Get the current head of the vector. ``` char* get_the_parameter (const char* flag); ``` If the flag matches the current\_arg of arg shifter this method will attempt to return the associated parameter value Safe to call without checking that a current arg exists In the following examples, a pointer to the char\* "value" is ret eg: main -foobar value, main -FooBar value\ main -FOOBARvalue all of the above will all match the flag == -FooBar\ and will return a char\* to "value" main -foobar 4 would succeed and return a char\* to "4"\ main -foobar -4 does not succeed (-4 is not a parameter)\ but instead, would return 0 0 is returned:\ If the current argument does not match flag\ If there is no parameter found after a 'matched' flag If the flag is matched and the flag and paramter DO NOT RUN together, the flag is consumed, the parameter is returned, and the new current argument is the parameter value. ie '-foobarflag VALUE' leaves the new cur arg == "VALUE" If the flag is matched and the flag and parameter RUN together '-foobarflagVALUE', the flag is NOT consumed and the cur arg is left pointing to the entire flag/value pair ``` int cur_arg_strncasecmp (const char* flag); ``` Check if the current argument matches (case insensitive) flag \------------------------------------------------------------ Case A: Perfect Match (case insensitive) 0 is returned. ie: when current\_arg = "-foobar" or "-FOOBAR" or "-fooBAR"\ this-cur\_arg\_strncasecmp ("-FooBar);\ will return 0 \------------------------------------------------------------ Case B: Perfect Match (case insensitive) but the current\_arg is longer than the flag. Returns a number equal to the index in the char\* indicating the start of the extra characters ie: when current\_arg = "-foobar98023"\ this-cur\_arg\_strncasecmp ("-FooBar);\ will return 7 Notice: this number will always be 0 \------------------------------------------------------------ Case C: If neither of Case A or B is met (no match) then -1 is returned ``` int consume_arg (int number = 1); ``` Consume number argument(s) by sticking them/it on the end of the vector. ``` int ignore_arg (int number = 1); ``` Place number arguments in the same relative order ahead of the known arguemnts in the vector. ``` int is_anything_left (void) const; ``` Returns the number of args left to see in the vector. ``` int is_option_next (void) const; ``` Returns 1 if there's a next item in the vector and it begins with ``` int is_parameter_next (void) const; ``` Returns 1 if there's a next item in the vector and it doesn't begin with '-'. ``` int num_ignored_args (void) const; ``` Returns the number of irrelevant args seen. ## AUTHOR Seth Widoff ## LIBRARY ace