| // | |
| // 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: usage_config.h | |
| // ----------------------------------------------------------------------------- | |
| // | |
| // This file defines the main usage reporting configuration interfaces and | |
| // documents Abseil's supported built-in usage flags. If these flags are found | |
| // when parsing a command-line, Abseil will exit the program and display | |
| // appropriate help messages. | |
| // ----------------------------------------------------------------------------- | |
| // Built-in Usage Flags | |
| // ----------------------------------------------------------------------------- | |
| // | |
| // Abseil supports the following built-in usage flags. When passed, these flags | |
| // exit the program and : | |
| // | |
| // * --help | |
| // Shows help on important flags for this binary | |
| // * --helpfull | |
| // Shows help on all flags | |
| // * --helpshort | |
| // Shows help on only the main module for this program | |
| // * --helppackage | |
| // Shows help on all modules in the main package | |
| // * --version | |
| // Shows the version and build info for this binary and exits | |
| // * --only_check_args | |
| // Exits after checking all flags | |
| // * --helpon | |
| // Shows help on the modules named by this flag value | |
| // * --helpmatch | |
| // Shows help on modules whose name contains the specified substring | |
| namespace absl { | |
| ABSL_NAMESPACE_BEGIN | |
| namespace flags_internal { | |
| using FlagKindFilter = std::function<bool (absl::string_view)>; | |
| } // namespace flags_internal | |
| // FlagsUsageConfig | |
| // | |
| // This structure contains the collection of callbacks for changing the behavior | |
| // of the usage reporting routines in Abseil Flags. | |
| struct FlagsUsageConfig { | |
| // Returns true if flags defined in the given source code file should be | |
| // reported with --helpshort flag. For example, if the file | |
| // "path/to/my/code.cc" defines the flag "--my_flag", and | |
| // contains_helpshort_flags("path/to/my/code.cc") returns true, invoking the | |
| // program with --helpshort will include information about --my_flag in the | |
| // program output. | |
| flags_internal::FlagKindFilter contains_helpshort_flags; | |
| // Returns true if flags defined in the filename should be reported with | |
| // --help flag. For example, if the file | |
| // "path/to/my/code.cc" defines the flag "--my_flag", and | |
| // contains_help_flags("path/to/my/code.cc") returns true, invoking the | |
| // program with --help will include information about --my_flag in the | |
| // program output. | |
| flags_internal::FlagKindFilter contains_help_flags; | |
| // Returns true if flags defined in the filename should be reported with | |
| // --helppackage flag. For example, if the file | |
| // "path/to/my/code.cc" defines the flag "--my_flag", and | |
| // contains_helppackage_flags("path/to/my/code.cc") returns true, invoking the | |
| // program with --helppackage will include information about --my_flag in the | |
| // program output. | |
| flags_internal::FlagKindFilter contains_helppackage_flags; | |
| // Generates string containing program version. This is the string reported | |
| // when user specifies --version in a command line. | |
| std::function<std::string()> version_string; | |
| // Normalizes the filename specific to the build system/filesystem used. This | |
| // routine is used when we report the information about the flag definition | |
| // location. For instance, if your build resides at some location you do not | |
| // want to expose in the usage output, you can trim it to show only relevant | |
| // part. | |
| // For example: | |
| // normalize_filename("/my_company/some_long_path/src/project/file.cc") | |
| // might produce | |
| // "project/file.cc". | |
| std::function<std::string(absl::string_view)> normalize_filename; | |
| }; | |
| // SetFlagsUsageConfig() | |
| // | |
| // Sets the usage reporting configuration callbacks. If any of the callbacks are | |
| // not set in usage_config instance, then the default value of the callback is | |
| // used. | |
| void SetFlagsUsageConfig(FlagsUsageConfig usage_config); | |
| namespace flags_internal { | |
| FlagsUsageConfig GetUsageConfig(); | |
| void ReportUsageError(absl::string_view msg, bool is_fatal); | |
| } // namespace flags_internal | |
| ABSL_NAMESPACE_END | |
| } // namespace absl | |
| extern "C" { | |
| // Additional report of fatal usage error message before we std::exit. Error is | |
| // fatal if is_fatal argument to ReportUsageError is true. | |
| void ABSL_INTERNAL_C_SYMBOL(AbslInternalReportFatalUsageError)( | |
| absl::string_view); | |
| } // extern "C" | |