1 /* Copyright 2015 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 #ifndef TENSORFLOW_CORE_UTIL_COMMAND_LINE_FLAGS_H 17 #define TENSORFLOW_CORE_UTIL_COMMAND_LINE_FLAGS_H 18 19 #include <functional> 20 #include <string> 21 #include <vector> 22 #include "tensorflow/core/platform/types.h" 23 24 namespace tensorflow { 25 26 // N.B. This library is for INTERNAL use only. 27 // 28 // This is a simple command-line argument parsing module to help us handle 29 // parameters for C++ binaries. The recommended way of using it is with local 30 // variables and an initializer list of Flag objects, for example: 31 // 32 // int some_int = 10; 33 // bool some_switch = false; 34 // string some_name = "something"; 35 // std::vector<tensorFlow::Flag> flag_list = { 36 // Flag("some_int", &some_int, "an integer that affects X"), 37 // Flag("some_switch", &some_switch, "a bool that affects Y"), 38 // Flag("some_name", &some_name, "a string that affects Z") 39 // }; 40 // // Get usage message before ParseFlags() to capture default values. 41 // string usage = Flag::Usage(argv[0], flag_list); 42 // bool parsed_values_ok = Flags::Parse(&argc, argv, flag_list); 43 // 44 // tensorflow::port::InitMain(usage.c_str(), &argc, &argv); 45 // if (argc != 1 || !parsed_values_ok) { 46 // ...output usage and error message... 47 // } 48 // 49 // The argc and argv values are adjusted by the Parse function so all that 50 // remains is the program name (at argv[0]) and any unknown arguments fill the 51 // rest of the array. This means you can check for flags that weren't understood 52 // by seeing if argv is greater than 1. 53 // The result indicates if there were any errors parsing the values that were 54 // passed to the command-line switches. For example, --some_int=foo would return 55 // false because the argument is expected to be an integer. 56 // 57 // NOTE: Unlike gflags-style libraries, this library is intended to be 58 // used in the `main()` function of your binary. It does not handle 59 // flag definitions that are scattered around the source code. 60 61 // A description of a single command line flag, holding its name, type, usage 62 // text, and a pointer to the corresponding variable. 63 class Flag { 64 public: 65 Flag(const char* name, int32* dst, const string& usage_text, 66 bool* dst_updated = nullptr); 67 Flag(const char* name, int64* dst, const string& usage_text, 68 bool* dst_updated = nullptr); 69 Flag(const char* name, bool* dst, const string& usage_text, 70 bool* dst_updated = nullptr); 71 Flag(const char* name, string* dst, const string& usage_text, 72 bool* dst_updated = nullptr); 73 Flag(const char* name, float* dst, const string& usage_text, 74 bool* dst_updated = nullptr); 75 76 // These constructors invoke a hook on a match instead of writing to a 77 // specific memory location. The hook may return false to signal a malformed 78 // or illegal value, which will then fail the command line parse. 79 // 80 // "default_value_for_display" is shown as the default value of this flag in 81 // Flags::Usage(). 82 Flag(const char* name, std::function<bool(int32)> int32_hook, 83 int32 default_value_for_display, const string& usage_text); 84 Flag(const char* name, std::function<bool(int64)> int64_hook, 85 int64 default_value_for_display, const string& usage_text); 86 Flag(const char* name, std::function<bool(float)> float_hook, 87 float default_value_for_display, const string& usage_text); 88 Flag(const char* name, std::function<bool(bool)> bool_hook, 89 bool default_value_for_display, const string& usage_text); 90 Flag(const char* name, std::function<bool(string)> string_hook, 91 string default_value_for_display, const string& usage_text); 92 is_default_initialized()93 bool is_default_initialized() const { return default_initialized_; } 94 95 private: 96 friend class Flags; 97 98 bool Parse(string arg, bool* value_parsing_ok) const; 99 100 string name_; 101 enum { 102 TYPE_INT32, 103 TYPE_INT64, 104 TYPE_BOOL, 105 TYPE_STRING, 106 TYPE_FLOAT, 107 } type_; 108 109 std::function<bool(int32)> int32_hook_; 110 int32 int32_default_for_display_; 111 112 std::function<bool(int64)> int64_hook_; 113 int64 int64_default_for_display_; 114 115 std::function<bool(float)> float_hook_; 116 float float_default_for_display_; 117 118 std::function<bool(bool)> bool_hook_; 119 bool bool_default_for_display_; 120 121 std::function<bool(string)> string_hook_; 122 string string_default_for_display_; 123 124 string usage_text_; 125 bool default_initialized_ = true; 126 }; 127 128 class Flags { 129 public: 130 // Parse the command line represented by argv[0, ..., (*argc)-1] to find flag 131 // instances matching flags in flaglist[]. Update the variables associated 132 // with matching flags, and remove the matching arguments from (*argc, argv). 133 // Return true iff all recognized flag values were parsed correctly, and the 134 // first remaining argument is not "--help". 135 static bool Parse(int* argc, char** argv, const std::vector<Flag>& flag_list); 136 137 // Return a usage message with command line cmdline, and the 138 // usage_text strings in flag_list[]. 139 static string Usage(const string& cmdline, 140 const std::vector<Flag>& flag_list); 141 }; 142 143 } // namespace tensorflow 144 145 #endif // TENSORFLOW_CORE_UTIL_COMMAND_LINE_FLAGS_H 146