flags/internal/usage.h

0001 //
0002 //  Copyright 2019 The Abseil Authors.
0003 //
0004 // Licensed under the Apache License, Version 2.0 (the "License");
0005 // you may not use this file except in compliance with the License.
0006 // You may obtain a copy of the License at
0007 //
0008 //      https://www.apache.org/licenses/LICENSE-2.0
0009 //
0010 // Unless required by applicable law or agreed to in writing, software
0011 // distributed under the License is distributed on an "AS IS" BASIS,
0012 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0013 // See the License for the specific language governing permissions and
0014 // limitations under the License.
0015
0016 #ifndef ABSL_FLAGS_INTERNAL_USAGE_H_
0017 #define ABSL_FLAGS_INTERNAL_USAGE_H_
0018
0019 #include <iosfwd>
0020 #include <ostream>
0021 #include <string>
0022
0023 #include "absl/base/config.h"
0024 #include "absl/flags/commandlineflag.h"
0025 #include "absl/strings/string_view.h"
0026
0027 // --------------------------------------------------------------------
0028 // Usage reporting interfaces
0029
0030 namespace absl {
0031 ABSL_NAMESPACE_BEGIN
0032 namespace flags_internal {
0033
0034 // The format to report the help messages in.
0035 enum class HelpFormat {
0036   kHumanReadable,
0037 };
0038
0039 // The kind of usage help requested.
0040 enum class HelpMode {
0041   kNone,
0042   kImportant,
0043   kShort,
0044   kFull,
0045   kPackage,
0046   kMatch,
0047   kVersion,
0048   kOnlyCheckArgs
0049 };
0050
0051 // Streams the help message describing `flag` to `out`.
0052 // The default value for `flag` is included in the output.
0053 void FlagHelp(std::ostream& out, const CommandLineFlag& flag,
0054               HelpFormat format = HelpFormat::kHumanReadable);
0055
0056 // Produces the help messages for all flags matching the filter. A flag matches
0057 // the filter if it is defined in a file with a filename which includes
0058 // filter string as a substring. You can use '/' and '.' to restrict the
0059 // matching to a specific file names. For example:
0060 //   FlagsHelp(out, "/path/to/file.");
0061 // restricts help to only flags which resides in files named like:
0062 //  .../path/to/file.<ext>
0063 // for any extension 'ext'. If the filter is empty this function produces help
0064 // messages for all flags.
0065 void FlagsHelp(std::ostream& out, absl::string_view filter,
0066                HelpFormat format, absl::string_view program_usage_message);
0067
0068 // --------------------------------------------------------------------
0069
0070 // If any of the 'usage' related command line flags (listed on the bottom of
0071 // this file) has been set this routine produces corresponding help message in
0072 // the specified output stream and returns HelpMode that was handled. Otherwise
0073 // it returns HelpMode::kNone.
0074 HelpMode HandleUsageFlags(std::ostream& out,
0075                           absl::string_view program_usage_message);
0076
0077 // --------------------------------------------------------------------
0078 // Encapsulates the logic of exiting the binary depending on handled help mode.
0079
0080 void MaybeExit(HelpMode mode);
0081
0082 // --------------------------------------------------------------------
0083 // Globals representing usage reporting flags
0084
0085 // Returns substring to filter help output (--help=substr argument)
0086 std::string GetFlagsHelpMatchSubstr();
0087 // Returns the requested help mode.
0088 HelpMode GetFlagsHelpMode();
0089 // Returns the requested help format.
0090 HelpFormat GetFlagsHelpFormat();
0091
0092 // These are corresponding setters to the attributes above.
0093 void SetFlagsHelpMatchSubstr(absl::string_view);
0094 void SetFlagsHelpMode(HelpMode);
0095 void SetFlagsHelpFormat(HelpFormat);
0096
0097 // Deduces usage flags from the input argument in a form --name=value or
0098 // --name. argument is already split into name and value before we call this
0099 // function.
0100 bool DeduceUsageFlags(absl::string_view name, absl::string_view value);
0101
0102 }  // namespace flags_internal
0103 ABSL_NAMESPACE_END
0104 }  // namespace absl
0105
0106 #endif  // ABSL_FLAGS_INTERNAL_USAGE_H_