usage_config.h
Go to the documentation of this file.
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 
31 
32 // -----------------------------------------------------------------------------
33 // Built-in Usage Flags
34 // -----------------------------------------------------------------------------
35 //
36 // Abseil supports the following built-in usage flags. When passed, these flags
37 // exit the program and :
38 //
39 // * --help
40 // Shows help on important flags for this binary
41 // * --helpfull
42 // Shows help on all flags
43 // * --helpshort
44 // Shows help on only the main module for this program
45 // * --helppackage
46 // Shows help on all modules in the main package
47 // * --version
48 // Shows the version and build info for this binary and exits
49 // * --only_check_args
50 // Exits after checking all flags
51 // * --helpon
52 // Shows help on the modules named by this flag value
53 // * --helpmatch
54 // Shows help on modules whose name contains the specified substring
55 
56 namespace absl {
57 
58 namespace flags_internal {
59 using FlagKindFilter = std::function<bool (absl::string_view)>;
60 } // namespace flags_internal
61 
62 // FlagsUsageConfig
63 //
64 // This structure contains the collection of callbacks for changing the behavior
65 // of the usage reporting routines in Abseil Flags.
67  // Returns true if flags defined in the given source code file should be
68  // reported with --helpshort flag. For example, if the file
69  // "path/to/my/code.cc" defines the flag "--my_flag", and
70  // contains_helpshort_flags("path/to/my/code.cc") returns true, invoking the
71  // program with --helpshort will include information about --my_flag in the
72  // program output.
74 
75  // Returns true if flags defined in the filename should be reported with
76  // --help flag. For example, if the file
77  // "path/to/my/code.cc" defines the flag "--my_flag", and
78  // contains_help_flags("path/to/my/code.cc") returns true, invoking the
79  // program with --help will include information about --my_flag in the
80  // program output.
82 
83  // Returns true if flags defined in the filename should be reported with
84  // --helppackage flag. For example, if the file
85  // "path/to/my/code.cc" defines the flag "--my_flag", and
86  // contains_helppackage_flags("path/to/my/code.cc") returns true, invoking the
87  // program with --helppackage will include information about --my_flag in the
88  // program output.
90 
91  // Generates std::string containing program version. This is the std::string reported
92  // when user specifies --version in a command line.
93  std::function<std::string()> version_string;
94 
95  // Normalizes the filename specific to the build system/filesystem used. This
96  // routine is used when we report the information about the flag definition
97  // location. For instance, if your build resides at some location you do not
98  // want to expose in the usage output, you can trim it to show only relevant
99  // part.
100  // For example:
101  // normalize_filename("/my_company/some_long_path/src/project/file.cc")
102  // might produce
103  // "project/file.cc".
104  std::function<std::string (absl::string_view)> normalize_filename;
105 };
106 
107 // SetFlagsUsageConfig()
108 //
109 // Sets the usage reporting configuration callbacks. If any of the callbacks are
110 // not set in usage_config instance, then the default value of the callback is
111 // used.
112 void SetFlagsUsageConfig(FlagsUsageConfig usage_config);
113 
114 namespace flags_internal {
115 
117 
118 void ReportUsageError(absl::string_view msg, bool is_fatal);
119 
120 } // namespace flags_internal
121 } // namespace absl
122 
123 extern "C" {
124 
125 // Additional report of fatal usage error message before we std::exit. Error is
126 // fatal if is_fatal argument to ReportUsageError is true.
128 
129 } // extern "C"
130 
131 #endif // ABSL_FLAGS_USAGE_CONFIG_H_
flags_internal::FlagKindFilter contains_help_flags
Definition: usage_config.h:81
Definition: algorithm.h:29
void SetFlagsUsageConfig(FlagsUsageConfig usage_config)
std::function< bool(absl::string_view)> FlagKindFilter
Definition: usage_config.h:59
const char * msg
Definition: mutex.cc:254
FlagsUsageConfig GetUsageConfig()
void AbslInternalReportFatalUsageError(absl::string_view)
Definition: usage_config.cc:32
flags_internal::FlagKindFilter contains_helppackage_flags
Definition: usage_config.h:89
void ReportUsageError(absl::string_view msg, bool is_fatal)
std::function< std::string()> version_string
Definition: usage_config.h:93
flags_internal::FlagKindFilter contains_helpshort_flags
Definition: usage_config.h:73
std::function< std::string(absl::string_view)> normalize_filename
Definition: usage_config.h:104


abseil_cpp
Author(s):
autogenerated on Mon Feb 28 2022 21:31:21