src/gflags_reporting.cc

   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, "&amp;");
 190   for (string::size_type pos = 0; (pos = ans.find("<", pos)) != string::npos; )
 191     ans.replace(pos++, 1, "&lt;");
 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