| // | |
| // Copyright 2019 The Abseil Authors. | |
| // | |
| // Licensed under the Apache License, Version 2.0 (the "License"); | |
| // you may not use this file except in compliance with the License. | |
| // You may obtain a copy of the License at | |
| // | |
| // https://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, software | |
| // distributed under the License is distributed on an "AS IS" BASIS, | |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| // See the License for the specific language governing permissions and | |
| // limitations under the License. | |
| // | |
| // ----------------------------------------------------------------------------- | |
| // File: parse.h | |
| // ----------------------------------------------------------------------------- | |
| // | |
| // This file defines the main parsing function for Abseil flags: | |
| // `absl::ParseCommandLine()`. | |
| namespace absl { | |
| ABSL_NAMESPACE_BEGIN | |
| // This type represent information about an unrecognized flag in the command | |
| // line. | |
| struct UnrecognizedFlag { | |
| enum Source { kFromArgv, kFromFlagfile }; | |
| explicit UnrecognizedFlag(Source s, absl::string_view f) | |
| : source(s), flag_name(f) {} | |
| // This field indicates where we found this flag: on the original command line | |
| // or read in some flag file. | |
| Source source; | |
| // Name of the flag we did not recognize in --flag_name=value or --flag_name. | |
| std::string flag_name; | |
| }; | |
| inline bool operator==(const UnrecognizedFlag& lhs, | |
| const UnrecognizedFlag& rhs) { | |
| return lhs.source == rhs.source && lhs.flag_name == rhs.flag_name; | |
| } | |
| namespace flags_internal { | |
| HelpMode ParseAbseilFlagsOnlyImpl( | |
| int argc, char* argv[], std::vector<char*>& positional_args, | |
| std::vector<UnrecognizedFlag>& unrecognized_flags, | |
| UsageFlagsAction usage_flag_action); | |
| } // namespace flags_internal | |
| // ParseAbseilFlagsOnly() | |
| // | |
| // Parses a list of command-line arguments, passed in the `argc` and `argv[]` | |
| // parameters, into a set of Abseil Flag values, returning any unparsed | |
| // arguments in `positional_args` and `unrecognized_flags` output parameters. | |
| // | |
| // This function classifies all the arguments (including content of the | |
| // flagfiles, if any) into one of the following groups: | |
| // | |
| // * arguments specified as "--flag=value" or "--flag value" that match | |
| // registered or built-in Abseil Flags. These are "Abseil Flag arguments." | |
| // * arguments specified as "--flag" that are unrecognized as Abseil Flags | |
| // * arguments that are not specified as "--flag" are positional arguments | |
| // * arguments that follow the flag-terminating delimiter (`--`) are also | |
| // treated as positional arguments regardless of their syntax. | |
| // | |
| // All of the deduced Abseil Flag arguments are then parsed into their | |
| // corresponding flag values. If any syntax errors are found in these arguments, | |
| // the binary exits with code 1. | |
| // | |
| // This function also handles Abseil Flags built-in usage flags (e.g. --help) | |
| // if any were present on the command line. | |
| // | |
| // All the remaining positional arguments including original program name | |
| // (argv[0]) are are returned in the `positional_args` output parameter. | |
| // | |
| // All unrecognized flags that are not otherwise ignored are returned in the | |
| // `unrecognized_flags` output parameter. Note that the special `undefok` | |
| // flag allows you to specify flags which can be safely ignored; `undefok` | |
| // specifies these flags as a comma-separated list. Any unrecognized flags | |
| // that appear within `undefok` will therefore be ignored and not included in | |
| // the `unrecognized_flag` output parameter. | |
| // | |
| void ParseAbseilFlagsOnly(int argc, char* argv[], | |
| std::vector<char*>& positional_args, | |
| std::vector<UnrecognizedFlag>& unrecognized_flags); | |
| // ReportUnrecognizedFlags() | |
| // | |
| // Reports an error to `stderr` for all non-ignored unrecognized flags in | |
| // the provided `unrecognized_flags` list. | |
| void ReportUnrecognizedFlags( | |
| const std::vector<UnrecognizedFlag>& unrecognized_flags); | |
| // ParseCommandLine() | |
| // | |
| // First parses Abseil Flags only from the command line according to the | |
| // description in `ParseAbseilFlagsOnly`. In addition this function handles | |
| // unrecognized and usage flags. | |
| // | |
| // If any unrecognized flags are located they are reported using | |
| // `ReportUnrecognizedFlags`. | |
| // | |
| // If any errors detected during command line parsing, this routine reports a | |
| // usage message and aborts the program. | |
| // | |
| // If any built-in usage flags were specified on the command line (e.g. | |
| // `--help`), this function reports help messages and then gracefully exits the | |
| // program. | |
| // | |
| // This function returns all the remaining positional arguments collected by | |
| // `ParseAbseilFlagsOnly`. | |
| std::vector<char*> ParseCommandLine(int argc, char* argv[]); | |
| ABSL_NAMESPACE_END | |
| } // namespace absl | |