usage_config.h (5173B)
1 // 2 // Copyright 2019 The Abseil Authors. 3 // 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // 8 // https://www.apache.org/licenses/LICENSE-2.0 9 // 10 // Unless required by applicable law or agreed to in writing, software 11 // distributed under the License is distributed on an "AS IS" BASIS, 12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 // See the License for the specific language governing permissions and 14 // limitations under the License. 15 // 16 // ----------------------------------------------------------------------------- 17 // File: usage_config.h 18 // ----------------------------------------------------------------------------- 19 // 20 // This file defines the main usage reporting configuration interfaces and 21 // documents Abseil's supported built-in usage flags. If these flags are found 22 // when parsing a command-line, Abseil will exit the program and display 23 // appropriate help messages. 24 #ifndef ABSL_FLAGS_USAGE_CONFIG_H_ 25 #define ABSL_FLAGS_USAGE_CONFIG_H_ 26 27 #include <functional> 28 #include <string> 29 30 #include "absl/base/config.h" 31 #include "absl/strings/string_view.h" 32 33 // ----------------------------------------------------------------------------- 34 // Built-in Usage Flags 35 // ----------------------------------------------------------------------------- 36 // 37 // Abseil supports the following built-in usage flags. When passed, these flags 38 // exit the program and : 39 // 40 // * --help 41 // Shows help on important flags for this binary 42 // * --helpfull 43 // Shows help on all flags 44 // * --helpshort 45 // Shows help on only the main module for this program 46 // * --helppackage 47 // Shows help on all modules in the main package 48 // * --version 49 // Shows the version and build info for this binary and exits 50 // * --only_check_args 51 // Exits after checking all flags 52 // * --helpon 53 // Shows help on the modules named by this flag value 54 // * --helpmatch 55 // Shows help on modules whose name contains the specified substring 56 57 namespace absl { 58 ABSL_NAMESPACE_BEGIN 59 60 namespace flags_internal { 61 using FlagKindFilter = std::function<bool (absl::string_view)>; 62 } // namespace flags_internal 63 64 // FlagsUsageConfig 65 // 66 // This structure contains the collection of callbacks for changing the behavior 67 // of the usage reporting routines in Abseil Flags. 68 struct FlagsUsageConfig { 69 // Returns true if flags defined in the given source code file should be 70 // reported with --helpshort flag. For example, if the file 71 // "path/to/my/code.cc" defines the flag "--my_flag", and 72 // contains_helpshort_flags("path/to/my/code.cc") returns true, invoking the 73 // program with --helpshort will include information about --my_flag in the 74 // program output. 75 flags_internal::FlagKindFilter contains_helpshort_flags; 76 77 // Returns true if flags defined in the filename should be reported with 78 // --help flag. For example, if the file 79 // "path/to/my/code.cc" defines the flag "--my_flag", and 80 // contains_help_flags("path/to/my/code.cc") returns true, invoking the 81 // program with --help will include information about --my_flag in the 82 // program output. 83 flags_internal::FlagKindFilter contains_help_flags; 84 85 // Returns true if flags defined in the filename should be reported with 86 // --helppackage flag. For example, if the file 87 // "path/to/my/code.cc" defines the flag "--my_flag", and 88 // contains_helppackage_flags("path/to/my/code.cc") returns true, invoking the 89 // program with --helppackage will include information about --my_flag in the 90 // program output. 91 flags_internal::FlagKindFilter contains_helppackage_flags; 92 93 // Generates string containing program version. This is the string reported 94 // when user specifies --version in a command line. 95 std::function<std::string()> version_string; 96 97 // Normalizes the filename specific to the build system/filesystem used. This 98 // routine is used when we report the information about the flag definition 99 // location. For instance, if your build resides at some location you do not 100 // want to expose in the usage output, you can trim it to show only relevant 101 // part. 102 // For example: 103 // normalize_filename("/my_company/some_long_path/src/project/file.cc") 104 // might produce 105 // "project/file.cc". 106 std::function<std::string(absl::string_view)> normalize_filename; 107 }; 108 109 // SetFlagsUsageConfig() 110 // 111 // Sets the usage reporting configuration callbacks. If any of the callbacks are 112 // not set in usage_config instance, then the default value of the callback is 113 // used. 114 void SetFlagsUsageConfig(FlagsUsageConfig usage_config); 115 116 namespace flags_internal { 117 118 FlagsUsageConfig GetUsageConfig(); 119 120 void ReportUsageError(absl::string_view msg, bool is_fatal); 121 122 } // namespace flags_internal 123 ABSL_NAMESPACE_END 124 } // namespace absl 125 126 extern "C" { 127 128 // Additional report of fatal usage error message before we std::exit. Error is 129 // fatal if is_fatal argument to ReportUsageError is true. 130 void ABSL_INTERNAL_C_SYMBOL(AbslInternalReportFatalUsageError)( 131 absl::string_view); 132 133 } // extern "C" 134 135 #endif // ABSL_FLAGS_USAGE_CONFIG_H_