legacy-libs/grpc-cloned/deps/grpc/third_party/abseil-cpp/absl/flags/usage_config.h

   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
  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.
  66 struct 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.
 112 void SetFlagsUsageConfig(FlagsUsageConfig usage_config);
 113
 114 namespace flags_internal {
 115
 116 FlagsUsageConfig GetUsageConfig();
 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.
 127 void AbslInternalReportFatalUsageError(absl::string_view);
 128
 129 }  // extern "C"
 130
 131 #endif  // ABSL_FLAGS_USAGE_CONFIG_H_