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/strings/string_view.h"
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
56namespace absl {
57
58namespace flags_internal {
59using 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.
66struct FlagsUsageConfig {
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.
73 flags_internal::FlagKindFilter contains_helpshort_flags;
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.
81 flags_internal::FlagKindFilter contains_help_flags;
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.
89 flags_internal::FlagKindFilter contains_helppackage_flags;
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.
112void SetFlagsUsageConfig(FlagsUsageConfig usage_config);
113
114namespace flags_internal {
115
116FlagsUsageConfig GetUsageConfig();
117
118void ReportUsageError(absl::string_view msg, bool is_fatal);
119
120} // namespace flags_internal
121} // namespace absl
122
123extern "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.
127void AbslInternalReportFatalUsageError(absl::string_view);
128
129} // extern "C"
130
131#endif // ABSL_FLAGS_USAGE_CONFIG_H_
132