// Copyright (c) 2006, Google Inc.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
// * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// ---
// Author: Ray Sidney
// Revamped and reorganized by Craig Silverstein
//
// This file contains code for handling the 'reporting' flags. These
// are flags that, when present, cause the program to report some
// information and then exit. --help and --version are the canonical
// reporting flags, but we also have flags like --helpxml, etc.
//
// There's only one function that's meant to be called externally:
// HandleCommandLineHelpFlags(). (Well, actually, ShowUsageWithFlags(),
// ShowUsageWithFlagsRestrict(), and DescribeOneFlag() can be called
// externally too, but there's little need for it.) These are all
// declared in the main commandlineflags.h header file.
//
// HandleCommandLineHelpFlags() will check what 'reporting' flags have
// been defined, if any -- the "help" part of the function name is a
// bit misleading -- and do the relevant reporting. It should be
// called after all flag-values have been assigned, that is, after
// parsing the command-line.
#include "config.h"
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <assert.h>
#include <string>
#include <vector>
#include "gflags/gflags.h"
#ifndef PATH_SEPARATOR
#define PATH_SEPARATOR '/'
#endif
using std::vector;
// The 'reporting' flags. They all call exit().
DEFINE_bool(help, false,
"show help on all flags [tip: all flags can have two dashes]");
DEFINE_bool(helpfull, false,
"show help on all flags -- same as -help");
DEFINE_bool(helpshort, false,
"show help on only the main module for this program");
DEFINE_string(helpon, "",
"show help on the modules named by this flag value");
DEFINE_string(helpmatch, "",
"show help on modules whose name contains the specified substr");
DEFINE_bool(helppackage, false,
"show help on all modules in the main package");
DEFINE_bool(helpxml, false,
"produce an xml version of help");
DEFINE_bool(version, false,
"show version and build info and exit");
namespace google {
using std::string;
// --------------------------------------------------------------------
// DescribeOneFlag()
// DescribeOneFlagInXML()
// Routines that pretty-print info about a flag. These use
// a CommandLineFlagInfo, which is the way the commandlineflags
// API exposes static info about a flag.
// --------------------------------------------------------------------
static const int kLineLength = 80;
static void AddString(const string& s,
string* final_string, int* chars_in_line) {
const int slen = static_cast<int>(s.length());
if (*chars_in_line + 1 + slen >= kLineLength) { // < 80 chars/line
*final_string += "\n ";
*chars_in_line = 6;
} else {
*final_string += " ";
*chars_in_line += 1;
}
*final_string += s;
*chars_in_line += slen;
}
// Create a descriptive string for a flag.
// Goes to some trouble to make pretty line breaks.
string DescribeOneFlag(const CommandLineFlagInfo& flag) {
string main_part = (string(" -") + flag.name +
" (" + flag.description + ')');
const char* c_string = main_part.c_str();
int chars_left = static_cast<int>(main_part.length());
string final_string = "";
int chars_in_line = 0; // how many chars in current line so far?
while (1) {
assert(chars_left == strlen(c_string)); // Unless there's a \0 in there?
const char* newline = strchr(c_string, '\n');
if (newline == NULL && chars_in_line+chars_left < kLineLength) {
// The whole remainder of the string fits on this line
final_string += c_string;
chars_in_line += chars_left;
break;
}
if (newline != NULL && newline - c_string < kLineLength - chars_in_line) {
int n = static_cast<int>(newline - c_string);
final_string.append(c_string, n);
chars_left -= n + 1;
c_string += n + 1;
} else {
// Find the last whitespace on this 80-char line
int whitespace = kLineLength-chars_in_line-1; // < 80 chars/line
while ( whitespace > 0 && !isspace(c_string[whitespace]) ) {
--whitespace;
}
if (whitespace <= 0) {
// Couldn't find any whitespace to make a line break. Just dump the
// rest out!
final_string += c_string;
chars_in_line = kLineLength; // next part gets its own line for sure!
break;
}
final_string += string(c_string, whitespace);
chars_in_line += whitespace;
while (isspace(c_string[whitespace])) ++whitespace;
c_string += whitespace;
chars_left -= whitespace;
}
if (*c_string == '\0')
break;
final_string += "\n ";
chars_in_line = 6;
}
// Append data type
AddString(string("type: ") + flag.type, &final_string, &chars_in_line);
// Append the effective default value (i.e., the value that the flag
// will have after the command line is parsed if the flag is not
// specified on the command line), which may be different from the
// stored default value. This would happen if the value of the flag
// was modified before the command line was parsed. (Unless the
// value was modified using SetCommandLineOptionWithMode() with mode
// SET_FLAGS_DEFAULT.)
// Note that we are assuming this code is being executed because a help
// request was just parsed from the command line, in which case the
// printed value is indeed the effective default, as long as no value
// for the flag was parsed from the command line before "--help".
if (strcmp(flag.type.c_str(), "string") == 0) { // add quotes for strings
AddString(string("default: \"") + flag.current_value + string("\""),
&final_string, &chars_in_line);
} else {
AddString(string("default: ") + flag.current_value,
&final_string, &chars_in_line);
}
final_string += '\n';
return final_string;
}
// Simple routine to xml-escape a string: escape & and < only.
static string XMLText(const string& txt) {
string ans = txt;
for (string::size_type pos = 0; (pos = ans.find("&", pos)) != string::npos; )
ans.replace(pos++, 1, "&");
for (string::size_type pos = 0; (pos = ans.find("<", pos)) != string::npos; )
ans.replace(pos++, 1, "<");
return ans;
}
static void AddXMLTag(string* r, const char* tag, const string& txt) {
*r += ('<');
*r += (tag);
*r += ('>');
*r += (XMLText(txt));
*r += ("</");
*r += (tag);
*r += ('>');
}
static string DescribeOneFlagInXML(const CommandLineFlagInfo& flag) {
// The file and flagname could have been attributes, but default
// and meaning need to avoid attribute normalization. This way it
// can be parsed by simple programs, in addition to xml parsers.
string r("<flag>");
AddXMLTag(&r, "file", flag.filename);
AddXMLTag(&r, "name", flag.name);
AddXMLTag(&r, "meaning", flag.description);
AddXMLTag(&r, "default", flag.default_value);
AddXMLTag(&r, "current", flag.current_value);
AddXMLTag(&r, "type", flag.type);
r += "</flag>";
return r;
}
// --------------------------------------------------------------------
// ShowUsageWithFlags()
// ShowUsageWithFlagsRestrict()
// ShowXMLOfFlags()
// These routines variously expose the registry's list of flag
// values. ShowUsage*() prints the flag-value information
// to stdout in a user-readable format (that's what --help uses).
// The Restrict() version limits what flags are shown.
// ShowXMLOfFlags() prints the flag-value information to stdout
// in a machine-readable format. In all cases, the flags are
// sorted: first by filename they are defined in, then by flagname.
// --------------------------------------------------------------------
static const char* Basename(const char* filename) {
const char* sep = strrchr(filename, PATH_SEPARATOR);
return sep ? sep + 1 : filename;
}
static string Dirname(const string& filename) {
string::size_type sep = filename.rfind(PATH_SEPARATOR);
return filename.substr(0, (sep == string::npos) ? 0 : sep);
}
// Test whether a filename contains at least one of the substrings.
static bool FileMatchesSubstring(const string& filename,
const vector<string>& substrings) {
for (vector<string>::const_iterator target = substrings.begin();
target != substrings.end();
++target) {
if (strstr(filename.c_str(), target->c_str()) != NULL)
return true;
// If the substring starts with a '/', that means that we want
// the string to be at the beginning of a directory component.
// That should match the first directory component as well, so
// we allow '/foo' to match a filename of 'foo'.
if (!target->empty() && (*target)[0] == '/' &&
strncmp(filename.c_str(), target->c_str() + 1,
strlen(target->c_str() + 1)) == 0)
return true;
}
return false;
}
// Show help for every filename which matches any of the target substrings.
// If substrings is empty, shows help for every file. If a flag's help message
// has been stripped (e.g. by adding '#define STRIP_FLAG_HELP 1' before
// including gflags/gflags.h), then this flag will not be displayed by
// '--help' and its variants.
static void ShowUsageWithFlagsMatching(const char *argv0,
const vector<string> &substrings) {
fprintf(stdout, "%s: %s\n", Basename(argv0), ProgramUsage());
vector<CommandLineFlagInfo> flags;
GetAllFlags(&flags); // flags are sorted by filename, then flagname
string last_filename; // so we know when we're at a new file
bool first_directory = true; // controls blank lines between dirs
bool found_match = false; // stays false iff no dir matches restrict
for (vector<CommandLineFlagInfo>::const_iterator flag = flags.begin();
flag != flags.end();
++flag) {
if (substrings.empty() ||
FileMatchesSubstring(flag->filename, substrings)) {
// If the flag has been stripped, pretend that it doesn't exist.
if (flag->description == kStrippedFlagHelp) continue;
found_match = true; // this flag passed the match!
if (flag->filename != last_filename) { // new file
if (Dirname(flag->filename) != Dirname(last_filename)) { // new dir!
if (!first_directory)
fprintf(stdout, "\n\n"); // put blank lines between directories
first_directory = false;
}
fprintf(stdout, "\n Flags from %s:\n", flag->filename.c_str());
last_filename = flag->filename;
}
// Now print this flag
fprintf(stdout, "%s", DescribeOneFlag(*flag).c_str());
}
}
if (!found_match && !substrings.empty()) {
fprintf(stdout, "\n No modules matched: use -help\n");
}
}
void ShowUsageWithFlagsRestrict(const char *argv0, const char *restrict) {
vector<string> substrings;
if (restrict != NULL && *restrict != '\0') {
substrings.push_back(restrict);
}
ShowUsageWithFlagsMatching(argv0, substrings);
}
void ShowUsageWithFlags(const char *argv0) {
ShowUsageWithFlagsRestrict(argv0, "");
}
// Convert the help, program, and usage to xml.
static void ShowXMLOfFlags(const char *prog_name) {
vector<CommandLineFlagInfo> flags;
GetAllFlags(&flags); // flags are sorted: by filename, then flagname
// XML. There is no corresponding schema yet
fprintf(stdout, "<?xml version=\"1.0\"?>\n");
// The document
fprintf(stdout, "<AllFlags>\n");
// the program name and usage
fprintf(stdout, "<program>%s</program>\n",
XMLText(Basename(prog_name)).c_str());
fprintf(stdout, "<usage>%s</usage>\n",
XMLText(ProgramUsage()).c_str());
// All the flags
for (vector<CommandLineFlagInfo>::const_iterator flag = flags.begin();
flag != flags.end();
++flag) {
if (flag->description != kStrippedFlagHelp)
fprintf(stdout, "%s\n", DescribeOneFlagInXML(*flag).c_str());
}
// The end of the document
fprintf(stdout, "</AllFlags>\n");
}
// --------------------------------------------------------------------
// ShowVersion()
// Called upon --version. Prints build-related info.
// --------------------------------------------------------------------
static void ShowVersion() {
fprintf(stdout, "%s\n", ProgramInvocationShortName());
// TODO: add other stuff, like a timestamp, who built it, what
// target they built, etc.
# if !defined(NDEBUG)
fprintf(stdout, "Debug build (NDEBUG not #defined)\n");
# endif
}
static void AppendPrognameStrings(vector<string>* substrings,
const char* progname) {
string r("/");
r += progname;
substrings->push_back(r + ".");
substrings->push_back(r + "-main.");
substrings->push_back(r + "_main.");
}
// --------------------------------------------------------------------
// HandleCommandLineHelpFlags()
// Checks all the 'reporting' commandline flags to see if any
// have been set. If so, handles them appropriately. Note
// that all of them, by definition, cause the program to exit
// if they trigger.
// --------------------------------------------------------------------
void HandleCommandLineHelpFlags() {
const char* progname = ProgramInvocationShortName();
extern void (*commandlineflags_exitfunc)(int); // in gflags.cc
vector<string> substrings;
AppendPrognameStrings(&substrings, progname);
if (FLAGS_helpshort) {
// show only flags related to this binary:
// E.g. for fileutil.cc, want flags containing ... "/fileutil." cc
ShowUsageWithFlagsMatching(progname, substrings);
commandlineflags_exitfunc(1); // almost certainly exit()
} else if (FLAGS_help || FLAGS_helpfull) {
// show all options
ShowUsageWithFlagsRestrict(progname, ""); // empty restrict
commandlineflags_exitfunc(1);
} else if (!FLAGS_helpon.empty()) {
string restrict = "/" + FLAGS_helpon + ".";
ShowUsageWithFlagsRestrict(progname, restrict.c_str());
commandlineflags_exitfunc(1);
} else if (!FLAGS_helpmatch.empty()) {
ShowUsageWithFlagsRestrict(progname, FLAGS_helpmatch.c_str());
commandlineflags_exitfunc(1);
} else if (FLAGS_helppackage) {
// Shows help for all files in the same directory as main(). We
// don't want to resort to looking at dirname(progname), because
// the user can pick progname, and it may not relate to the file
// where main() resides. So instead, we search the flags for a
// filename like "/progname.cc", and take the dirname of that.
vector<CommandLineFlagInfo> flags;
GetAllFlags(&flags);
string last_package;
for (vector<CommandLineFlagInfo>::const_iterator flag = flags.begin();
flag != flags.end();
++flag) {
if (!FileMatchesSubstring(flag->filename, substrings))
continue;
const string package = Dirname(flag->filename) + "/";
if (package != last_package) {
ShowUsageWithFlagsRestrict(progname, package.c_str());
if (!last_package.empty()) { // means this isn't our first pkg
fprintf(stderr, "WARNING: Multiple packages contain a file=%s\n",
progname);
}
last_package = package;
}
}
if (last_package.empty()) { // never found a package to print
fprintf(stderr, "WARNING: Unable to find a package for file=%s\n",
progname);
}
commandlineflags_exitfunc(1);
} else if (FLAGS_helpxml) {
ShowXMLOfFlags(progname);
commandlineflags_exitfunc(1);
} else if (FLAGS_version) {
ShowVersion();
// Unlike help, we may be asking for version in a script, so return 0
commandlineflags_exitfunc(0);
}
}
} // namespace google