1 // Copyright (c) 1999, Google Inc. 2 // All rights reserved. 3 // 4 // Redistribution and use in source and binary forms, with or without 5 // modification, are permitted provided that the following conditions are 6 // met: 7 // 8 // * Redistributions of source code must retain the above copyright 9 // notice, this list of conditions and the following disclaimer. 10 // * Redistributions in binary form must reproduce the above 11 // copyright notice, this list of conditions and the following disclaimer 12 // in the documentation and/or other materials provided with the 13 // distribution. 14 // * Neither the name of Google Inc. nor the names of its 15 // contributors may be used to endorse or promote products derived from 16 // this software without specific prior written permission. 17 // 18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30 // --- 31 // 32 // Revamped and reorganized by Craig Silverstein 33 // 34 // This file contains code for handling the 'reporting' flags. These 35 // are flags that, when present, cause the program to report some 36 // information and then exit. --help and --version are the canonical 37 // reporting flags, but we also have flags like --helpxml, etc. 38 // 39 // There's only one function that's meant to be called externally: 40 // HandleCommandLineHelpFlags(). (Well, actually, ShowUsageWithFlags(), 41 // ShowUsageWithFlagsRestrict(), and DescribeOneFlag() can be called 42 // externally too, but there's little need for it.) These are all 43 // declared in the main gflags.h header file. 44 // 45 // HandleCommandLineHelpFlags() will check what 'reporting' flags have 46 // been defined, if any -- the "help" part of the function name is a 47 // bit misleading -- and do the relevant reporting. It should be 48 // called after all flag-values have been assigned, that is, after 49 // parsing the command-line. 50 51 #include <stdio.h> 52 #include <string.h> 53 #include <ctype.h> 54 #include <assert.h> 55 #include <string> 56 #include <vector> 57 58 #include "config.h" 59 #include "gflags/gflags.h" 60 #include "gflags/gflags_completions.h" 61 #include "util.h" 62 63 64 // The 'reporting' flags. They all call gflags_exitfunc(). 65 DEFINE_bool (help, false, "show help on all flags [tip: all flags can have two dashes]"); 66 DEFINE_bool (helpfull, false, "show help on all flags -- same as -help"); 67 DEFINE_bool (helpshort, false, "show help on only the main module for this program"); 68 DEFINE_string(helpon, "", "show help on the modules named by this flag value"); 69 DEFINE_string(helpmatch, "", "show help on modules whose name contains the specified substr"); 70 DEFINE_bool (helppackage, false, "show help on all modules in the main package"); 71 DEFINE_bool (helpxml, false, "produce an xml version of help"); 72 DEFINE_bool (version, false, "show version and build info and exit"); 73 74 75 namespace GFLAGS_NAMESPACE { 76 77 78 using std::string; 79 using std::vector; 80 81 82 // -------------------------------------------------------------------- 83 // DescribeOneFlag() 84 // DescribeOneFlagInXML() 85 // Routines that pretty-print info about a flag. These use 86 // a CommandLineFlagInfo, which is the way the gflags 87 // API exposes static info about a flag. 88 // -------------------------------------------------------------------- 89 90 static const int kLineLength = 80; 91 92 static void AddString(const string& s, 93 string* final_string, int* chars_in_line) { 94 const int slen = static_cast<int>(s.length()); 95 if (*chars_in_line + 1 + slen >= kLineLength) { // < 80 chars/line 96 *final_string += "\n "; 97 *chars_in_line = 6; 98 } else { 99 *final_string += " "; 100 *chars_in_line += 1; 101 } 102 *final_string += s; 103 *chars_in_line += slen; 104 } 105 106 static string PrintStringFlagsWithQuotes(const CommandLineFlagInfo& flag, 107 const string& text, bool current) { 108 const char* c_string = (current ? flag.current_value.c_str() : 109 flag.default_value.c_str()); 110 if (strcmp(flag.type.c_str(), "string") == 0) { // add quotes for strings 111 return StringPrintf("%s: \"%s\"", text.c_str(), c_string); 112 } else { 113 return StringPrintf("%s: %s", text.c_str(), c_string); 114 } 115 } 116 117 // Create a descriptive string for a flag. 118 // Goes to some trouble to make pretty line breaks. 119 string DescribeOneFlag(const CommandLineFlagInfo& flag) { 120 string main_part; 121 SStringPrintf(&main_part, " -%s (%s)", 122 flag.name.c_str(), 123 flag.description.c_str()); 124 const char* c_string = main_part.c_str(); 125 int chars_left = static_cast<int>(main_part.length()); 126 string final_string = ""; 127 int chars_in_line = 0; // how many chars in current line so far? 128 while (1) { 129 assert(static_cast<size_t>(chars_left) 130 == strlen(c_string)); // Unless there's a \0 in there? 131 const char* newline = strchr(c_string, '\n'); 132 if (newline == NULL && chars_in_line+chars_left < kLineLength) { 133 // The whole remainder of the string fits on this line 134 final_string += c_string; 135 chars_in_line += chars_left; 136 break; 137 } 138 if (newline != NULL && newline - c_string < kLineLength - chars_in_line) { 139 int n = static_cast<int>(newline - c_string); 140 final_string.append(c_string, n); 141 chars_left -= n + 1; 142 c_string += n + 1; 143 } else { 144 // Find the last whitespace on this 80-char line 145 int whitespace = kLineLength-chars_in_line-1; // < 80 chars/line 146 while ( whitespace > 0 && !isspace(c_string[whitespace]) ) { 147 --whitespace; 148 } 149 if (whitespace <= 0) { 150 // Couldn't find any whitespace to make a line break. Just dump the 151 // rest out! 152 final_string += c_string; 153 chars_in_line = kLineLength; // next part gets its own line for sure! 154 break; 155 } 156 final_string += string(c_string, whitespace); 157 chars_in_line += whitespace; 158 while (isspace(c_string[whitespace])) ++whitespace; 159 c_string += whitespace; 160 chars_left -= whitespace; 161 } 162 if (*c_string == '\0') 163 break; 164 StringAppendF(&final_string, "\n "); 165 chars_in_line = 6; 166 } 167 168 // Append data type 169 AddString(string("type: ") + flag.type, &final_string, &chars_in_line); 170 // The listed default value will be the actual default from the flag 171 // definition in the originating source file, unless the value has 172 // subsequently been modified using SetCommandLineOptionWithMode() with mode 173 // SET_FLAGS_DEFAULT, or by setting FLAGS_foo = bar before ParseCommandLineFlags(). 174 AddString(PrintStringFlagsWithQuotes(flag, "default", false), &final_string, 175 &chars_in_line); 176 if (!flag.is_default) { 177 AddString(PrintStringFlagsWithQuotes(flag, "currently", true), 178 &final_string, &chars_in_line); 179 } 180 181 StringAppendF(&final_string, "\n"); 182 return final_string; 183 } 184 185 // Simple routine to xml-escape a string: escape & and < only. 186 static string XMLText(const string& txt) { 187 string ans = txt; 188 for (string::size_type pos = 0; (pos = ans.find("&", pos)) != string::npos; ) 189 ans.replace(pos++, 1, "&"); 190 for (string::size_type pos = 0; (pos = ans.find("<", pos)) != string::npos; ) 191 ans.replace(pos++, 1, "<"); 192 return ans; 193 } 194 195 static void AddXMLTag(string* r, const char* tag, const string& txt) { 196 StringAppendF(r, "<%s>%s</%s>", tag, XMLText(txt).c_str(), tag); 197 } 198 199 200 static string DescribeOneFlagInXML(const CommandLineFlagInfo& flag) { 201 // The file and flagname could have been attributes, but default 202 // and meaning need to avoid attribute normalization. This way it 203 // can be parsed by simple programs, in addition to xml parsers. 204 string r("<flag>"); 205 AddXMLTag(&r, "file", flag.filename); 206 AddXMLTag(&r, "name", flag.name); 207 AddXMLTag(&r, "meaning", flag.description); 208 AddXMLTag(&r, "default", flag.default_value); 209 AddXMLTag(&r, "current", flag.current_value); 210 AddXMLTag(&r, "type", flag.type); 211 r += "</flag>"; 212 return r; 213 } 214 215 // -------------------------------------------------------------------- 216 // ShowUsageWithFlags() 217 // ShowUsageWithFlagsRestrict() 218 // ShowXMLOfFlags() 219 // These routines variously expose the registry's list of flag 220 // values. ShowUsage*() prints the flag-value information 221 // to stdout in a user-readable format (that's what --help uses). 222 // The Restrict() version limits what flags are shown. 223 // ShowXMLOfFlags() prints the flag-value information to stdout 224 // in a machine-readable format. In all cases, the flags are 225 // sorted: first by filename they are defined in, then by flagname. 226 // -------------------------------------------------------------------- 227 228 static const char* Basename(const char* filename) { 229 const char* sep = strrchr(filename, PATH_SEPARATOR); 230 return sep ? sep + 1 : filename; 231 } 232 233 static string Dirname(const string& filename) { 234 string::size_type sep = filename.rfind(PATH_SEPARATOR); 235 return filename.substr(0, (sep == string::npos) ? 0 : sep); 236 } 237 238 // Test whether a filename contains at least one of the substrings. 239 static bool FileMatchesSubstring(const string& filename, 240 const vector<string>& substrings) { 241 for (vector<string>::const_iterator target = substrings.begin(); 242 target != substrings.end(); 243 ++target) { 244 if (strstr(filename.c_str(), target->c_str()) != NULL) 245 return true; 246 // If the substring starts with a '/', that means that we want 247 // the string to be at the beginning of a directory component. 248 // That should match the first directory component as well, so 249 // we allow '/foo' to match a filename of 'foo'. 250 if (!target->empty() && (*target)[0] == PATH_SEPARATOR && 251 strncmp(filename.c_str(), target->c_str() + 1, 252 strlen(target->c_str() + 1)) == 0) 253 return true; 254 } 255 return false; 256 } 257 258 // Show help for every filename which matches any of the target substrings. 259 // If substrings is empty, shows help for every file. If a flag's help message 260 // has been stripped (e.g. by adding '#define STRIP_FLAG_HELP 1' 261 // before including gflags/gflags.h), then this flag will not be displayed 262 // by '--help' and its variants. 263 static void ShowUsageWithFlagsMatching(const char *argv0, 264 const vector<string> &substrings) { 265 fprintf(stdout, "%s: %s\n", Basename(argv0), ProgramUsage()); 266 267 vector<CommandLineFlagInfo> flags; 268 GetAllFlags(&flags); // flags are sorted by filename, then flagname 269 270 string last_filename; // so we know when we're at a new file 271 bool first_directory = true; // controls blank lines between dirs 272 bool found_match = false; // stays false iff no dir matches restrict 273 for (vector<CommandLineFlagInfo>::const_iterator flag = flags.begin(); 274 flag != flags.end(); 275 ++flag) { 276 if (substrings.empty() || 277 FileMatchesSubstring(flag->filename, substrings)) { 278 // If the flag has been stripped, pretend that it doesn't exist. 279 if (flag->description == kStrippedFlagHelp) continue; 280 found_match = true; // this flag passed the match! 281 if (flag->filename != last_filename) { // new file 282 if (Dirname(flag->filename) != Dirname(last_filename)) { // new dir! 283 if (!first_directory) 284 fprintf(stdout, "\n\n"); // put blank lines between directories 285 first_directory = false; 286 } 287 fprintf(stdout, "\n Flags from %s:\n", flag->filename.c_str()); 288 last_filename = flag->filename; 289 } 290 // Now print this flag 291 fprintf(stdout, "%s", DescribeOneFlag(*flag).c_str()); 292 } 293 } 294 if (!found_match && !substrings.empty()) { 295 fprintf(stdout, "\n No modules matched: use -help\n"); 296 } 297 } 298 299 void ShowUsageWithFlagsRestrict(const char *argv0, const char *restrict) { 300 vector<string> substrings; 301 if (restrict != NULL && *restrict != '\0') { 302 substrings.push_back(restrict); 303 } 304 ShowUsageWithFlagsMatching(argv0, substrings); 305 } 306 307 void ShowUsageWithFlags(const char *argv0) { 308 ShowUsageWithFlagsRestrict(argv0, ""); 309 } 310 311 // Convert the help, program, and usage to xml. 312 static void ShowXMLOfFlags(const char *prog_name) { 313 vector<CommandLineFlagInfo> flags; 314 GetAllFlags(&flags); // flags are sorted: by filename, then flagname 315 316 // XML. There is no corresponding schema yet 317 fprintf(stdout, "<?xml version=\"1.0\"?>\n"); 318 // The document 319 fprintf(stdout, "<AllFlags>\n"); 320 // the program name and usage 321 fprintf(stdout, "<program>%s</program>\n", 322 XMLText(Basename(prog_name)).c_str()); 323 fprintf(stdout, "<usage>%s</usage>\n", 324 XMLText(ProgramUsage()).c_str()); 325 // All the flags 326 for (vector<CommandLineFlagInfo>::const_iterator flag = flags.begin(); 327 flag != flags.end(); 328 ++flag) { 329 if (flag->description != kStrippedFlagHelp) 330 fprintf(stdout, "%s\n", DescribeOneFlagInXML(*flag).c_str()); 331 } 332 // The end of the document 333 fprintf(stdout, "</AllFlags>\n"); 334 } 335 336 // -------------------------------------------------------------------- 337 // ShowVersion() 338 // Called upon --version. Prints build-related info. 339 // -------------------------------------------------------------------- 340 341 static void ShowVersion() { 342 const char* version_string = VersionString(); 343 if (version_string && *version_string) { 344 fprintf(stdout, "%s version %s\n", 345 ProgramInvocationShortName(), version_string); 346 } else { 347 fprintf(stdout, "%s\n", ProgramInvocationShortName()); 348 } 349 # if !defined(NDEBUG) 350 fprintf(stdout, "Debug build (NDEBUG not #defined)\n"); 351 # endif 352 } 353 354 static void AppendPrognameStrings(vector<string>* substrings, 355 const char* progname) { 356 string r(""); 357 r += PATH_SEPARATOR; 358 r += progname; 359 substrings->push_back(r + "."); 360 substrings->push_back(r + "-main."); 361 substrings->push_back(r + "_main."); 362 } 363 364 // -------------------------------------------------------------------- 365 // HandleCommandLineHelpFlags() 366 // Checks all the 'reporting' commandline flags to see if any 367 // have been set. If so, handles them appropriately. Note 368 // that all of them, by definition, cause the program to exit 369 // if they trigger. 370 // -------------------------------------------------------------------- 371 372 void HandleCommandLineHelpFlags() { 373 const char* progname = ProgramInvocationShortName(); 374 375 HandleCommandLineCompletions(); 376 377 vector<string> substrings; 378 AppendPrognameStrings(&substrings, progname); 379 380 if (FLAGS_helpshort) { 381 // show only flags related to this binary: 382 // E.g. for fileutil.cc, want flags containing ... "/fileutil." cc 383 ShowUsageWithFlagsMatching(progname, substrings); 384 gflags_exitfunc(1); 385 386 } else if (FLAGS_help || FLAGS_helpfull) { 387 // show all options 388 ShowUsageWithFlagsRestrict(progname, ""); // empty restrict 389 gflags_exitfunc(1); 390 391 } else if (!FLAGS_helpon.empty()) { 392 string restrict = PATH_SEPARATOR + FLAGS_helpon + "."; 393 ShowUsageWithFlagsRestrict(progname, restrict.c_str()); 394 gflags_exitfunc(1); 395 396 } else if (!FLAGS_helpmatch.empty()) { 397 ShowUsageWithFlagsRestrict(progname, FLAGS_helpmatch.c_str()); 398 gflags_exitfunc(1); 399 400 } else if (FLAGS_helppackage) { 401 // Shows help for all files in the same directory as main(). We 402 // don't want to resort to looking at dirname(progname), because 403 // the user can pick progname, and it may not relate to the file 404 // where main() resides. So instead, we search the flags for a 405 // filename like "/progname.cc", and take the dirname of that. 406 vector<CommandLineFlagInfo> flags; 407 GetAllFlags(&flags); 408 string last_package; 409 for (vector<CommandLineFlagInfo>::const_iterator flag = flags.begin(); 410 flag != flags.end(); 411 ++flag) { 412 if (!FileMatchesSubstring(flag->filename, substrings)) 413 continue; 414 const string package = Dirname(flag->filename) + PATH_SEPARATOR; 415 if (package != last_package) { 416 ShowUsageWithFlagsRestrict(progname, package.c_str()); 417 VLOG(7) << "Found package: " << package; 418 if (!last_package.empty()) { // means this isn't our first pkg 419 LOG(WARNING) << "Multiple packages contain a file=" << progname; 420 } 421 last_package = package; 422 } 423 } 424 if (last_package.empty()) { // never found a package to print 425 LOG(WARNING) << "Unable to find a package for file=" << progname; 426 } 427 gflags_exitfunc(1); 428 429 } else if (FLAGS_helpxml) { 430 ShowXMLOfFlags(progname); 431 gflags_exitfunc(1); 432 433 } else if (FLAGS_version) { 434 ShowVersion(); 435 // Unlike help, we may be asking for version in a script, so return 0 436 gflags_exitfunc(0); 437 438 } 439 } 440 441 442 } // namespace GFLAGS_NAMESPACE 443
