* Added a contentful NEWS file (csilvers)

	* Fixed email address in maintainers to actually work (csilvers)
	* Update docs with info on validators (wojtekm)


git-svn-id: https://gflags.googlecode.com/svn/trunk@38 6586e3c6-dcc4-952a-343f-ff74eb82781d

NEWS

+==4 January 2010==
+
+I've just released gflags 1.3.  gflags now compiles under MSVC, and
+all tests pass.  I *really* never thought non-unix-y Windows folks
+would want gflags, but at least some of them do.
+
+The major news, though, is that I've separated out the python package
+into its own library, [http://code.google.com/p/python-gflags
+python-gflags].  If you're interested in the Python version of gflags,
+that's the place to get it now.
+
+===10 September 2009==
+
+I've just released gflags 1.2.  The major change from gflags 1.1 is it
+now compiles under MinGW (as well as cygwin), and all tests pass.  I
+never thought Windows folks would want unix-style command-line flags,
+since they're so different from the Windows style, but I guess I was
+wrong!
+
+The other changes are minor, such as support for --htmlxml in the
+python version of gflags.
+
+===15 April 2009===
+
+I've just released gflags 1.1.  It has only minor changes fdrom gflags
+1.0 (see the
+[http://code.google.com/p/google-gflags/source/browse/tags/gflags-1.1/ChangeLog
+ChangeLog] for details).  The major change is that I moved to a new
+system for creating .deb and .rpm files.  This allows me to create
+x86_64 deb and rpm files.
+
+In the process of moving to this new system, I noticed an
+inconsistency: the tar.gz and .rpm files created libraries named
+libgflags.so, but the deb file created libgoogle-gflags.so.  I have
+fixed the deb file to create libraries like the others.  I'm no expert
+in debian packaging, but I believe this has caused the package name to
+change as well.  Please let me know (at
+[mailto:google-gflags@googlegroups.com
+google-gflags@googlegroups.com]) if this causes problems for you --
+especially if you know of a fix!  I would be happy to change the deb
+packages to add symlinks from the old library name to the new
+(libgoogle-gflags.so -> libgflags.so), but that is beyond my knowledge
+of how to make .debs.
+
+If you've tried to install a .rpm or .deb and it doesn't work for you,
+let me know.  I'm excited to finally have 64-bit package files, but
+there may still be some wrinkles in the new system to iron out.
+
+===1 October 2008===
+
+gflags 1.0rc2 was out for a few weeks without any issues, so gflags
+1.0 is now released.  This is much like gflags 0.9.  The major change
+is that the .h files have been moved from `/usr/include/google` to
+`/usr/include/gflags`.  While I have backwards-compatibility
+forwarding headeds in place, please rewrite existing code to say
+{{{
+   #include <gflags/gflags.h>
+}}}
+instead of
+{{{
+   #include <google/gflags.h>
+}}}
+
+I've kept the default namespace to google.  You can still change with
+with the appropriate flag to the configure script (`./configure
+--help` to see the flags).  If you have feedback as to whether the
+default namespace should change to gflags, which would be a
+non-backwards-compatible change, send mail to
+`google-gflags@googlegroups.com`!
+
+Version 1.0 also has some neat new features, like support for bash
+commandline-completion of help flags.  See the
+[http://code.google.com/p/google-gflags/source/browse/tags/gflags-1.0rc2/ChangeLog
+ChangeLog] for more details.
+
+If I don't hear any bad news for a few weeks, I'll release 1.0-final.

doc/gflags.html

@@ -18,7 +18,7 @@
     color: #000;
     font-family: "Times Roman", times, serif;
   }
-  ul.blacklist li {  
+  ul.blacklist li {
     color: #000;
     font-family: "Times Roman", times, serif;
   }
@@ -37,6 +37,20 @@
 </small>
 <br>
 
+<blockquote><dl>
+  <dt> Table of contents </dt>
+  <dd> <a href="#intro">Introduction</a> </dd>
+  <dd> <a href="#define">DEFINE: Defining Flags In Program</A> </dd>
+  <dd> <a href="#using">Accessing the Flag</A> </dd>
+  <dd> <a href="#declare">DECLARE: Using the Flag in a Different File</a> </dd>
+  <dd> <a href="#validate">RegisterFlagValidator: Sanity-checking Flag Values</a> </dd>
+  <dd> <a href="#together">Putting It Together: How to Set Up Flags</a> </dd>
+  <dd> <a href="#commandline">Setting Flags on the Command Line</a> </dd>
+  <dd> <a href="#varz">Setting Flags at Runtime</a> </dd>
+  <dd> <a href="#special">Special Flags</a> </dd>
+  <dd> <a href="#api">The API</a> </dd>
+  <dd> <br/> </dd>
+</dl></blockquote>
 
 <h2> <A NAME=intro>Introduction, and Comparison to Other Commandline
      Flags Libraries</A> </h2>
@@ -122,6 +136,15 @@ HREF="#declare">DECLARE</A> it in the others.  Even better, DEFINE it
 in <code>foo.cc</code> and DECLARE it in <code>foo.h</code>; then
 everyone who <code>#includes foo.h</code> can use the flag.</p>
 
+<p>
+Defining flags in libraries rather than in main() is powerful, but
+does have some costs. One is that a library might not have a good
+default value for its flags, for example if the flag holds a
+filename that might not exist in some environments. To mitigate such problems,
+you can use <a href="#validate">flag validators</a> to ensure prompt
+notification (in the form of a crash) of an invalid flag value.
+</p>
+
 <p>Note that while most functions in this library are defined in the
 <code>google</code> namespace, <code>DEFINE_foo</code> (and
 <code>DECLARE_foo</code>, <A HREF="#declare">below</A>), should always
@@ -200,7 +223,7 @@ with the new value as an argument.  The validator function should
 return 'true' if the flag value is valid, and false otherwise.
 If the function returns false for the new setting of the
 flag, the flag will retain its current value. If it returns false for the
-default value, InitGoogle will die.
+default value, ParseCommandLineFlags will die.
 
 <p>Here is an example use of this functionality:</p>
 <pre>
@@ -417,7 +440,7 @@ that file as if these flags had been specified on the commandline.</p>
 
 <p>In its simplest form, <code>f</code> should just be a list of flag
 assignments, one per line.  Unlike on the commandline, the equals sign
-separating a flagname from its argument is <i>required</i> for 
+separating a flagname from its argument is <i>required</i> for
 flagfiles.  An example flagfile, <code>/tmp/myflags</code>:</p>
 <pre>
 --nobig_menus

packages/deb/control

 Source: gflags
 Priority: optional
-Maintainer: Google Inc. <opensource@google.com>
+Maintainer: Google Inc. <google-gflags@googlegroups.com>
 Build-Depends: debhelper (>= 4.0.0), binutils
 Standards-Version: 3.6.1
 

packages/rpm/rpm.spec

@@ -10,7 +10,7 @@ Group: Development/Libraries
 URL: http://code.google.com/p/google-gflags
 License: BSD
 Vendor: Google
-Packager: Google Inc. <opensource@google.com>
+Packager: Google Inc. <google-gflags@googlegroups.com>
 Source: http://%{NAME}.googlecode.com/files/%{NAME}-%{VERSION}.tar.gz
 Distribution: Redhat 7 and above.
 Buildroot: %{_tmppath}/%{name}-root

src/gflags.cc

@@ -106,7 +106,6 @@
 #ifdef HAVE_FNMATCH_H
 #include <fnmatch.h>
 #endif  // HAVE_FNMATCH_H
-#include <iostream>    // for cerr
 #include <string>
 #include <map>
 #include <vector>
@@ -162,7 +161,6 @@ DEFINE_string(undefok, "",
 
 _START_GOOGLE_NAMESPACE_
 
-using std::cerr;
 using std::map;
 using std::pair;
 using std::sort;
@@ -243,6 +241,7 @@ class FlagValue {
   bool Equal(const FlagValue& x) const;
   FlagValue* New() const;   // creates a new one with default value
   void CopyFrom(const FlagValue& x);
+  int ValueSize() const;
 
   // Calls the given validate-fn on value_buffer_, and returns
   // whatever it returns.  But first casts validate_fn_proto to a
@@ -250,6 +249,7 @@ class FlagValue {
   // (*validate_fn)(bool) for a bool flag).
   bool Validate(const char* flagname, ValidateFnProto validate_fn_proto) const;
 
+
   void* value_buffer_;          // points to the buffer holding our data
   ValueType type_;              // how to interpret value_
 
@@ -455,6 +455,18 @@ void FlagValue::CopyFrom(const FlagValue& x) {
   }
 }
 
+int FlagValue::ValueSize() const {
+  switch (type_) {
+    case FV_BOOL:   return sizeof(bool);
+    case FV_INT32:  return sizeof(int32);
+    case FV_INT64:  return sizeof(int64);
+    case FV_UINT64: return sizeof(uint64);
+    case FV_DOUBLE: return sizeof(double);
+    case FV_STRING: return sizeof(string);
+    default: assert(false); return 0; // unknown type
+  }
+}
+
 // --------------------------------------------------------------------
 // CommandLineFlag
 //    This represents a single flag, including its name, description,

src/gflags/gflags.h.in

@@ -37,8 +37,15 @@
 // flags).  Executive summary, in the form of an example foo.cc file:
 //
 //    #include "foo.h"         // foo.h has a line "DECLARE_int32(start);"
+//    #include "validators.h"  // hypothetical file defining ValidateIsFile()
 //
 //    DEFINE_int32(end, 1000, "The last record to read");
+//
+//    DEFINE_string(filename, "my_file.txt", "The file to read");
+//    // Crash if the specified file does not exist.
+//    static bool dummy = RegisterFlagValidator(&FLAGS_filename,
+//                                              &ValidateIsFile);
+//
 //    DECLARE_bool(verbose); // some other file has a DEFINE_bool(verbose, ...)
 //
 //    void MyFunc() {

src/windows/gflags/gflags.h

@@ -37,8 +37,15 @@
 // flags).  Executive summary, in the form of an example foo.cc file:
 //
 //    #include "foo.h"         // foo.h has a line "DECLARE_int32(start);"
+//    #include "validators.h"  // hypothetical file defining ValidateIsFile()
 //
 //    DEFINE_int32(end, 1000, "The last record to read");
+//
+//    DEFINE_string(filename, "my_file.txt", "The file to read");
+//    // Crash if the specified file does not exist.
+//    static bool dummy = RegisterFlagValidator(&FLAGS_filename,
+//                                              &ValidateIsFile);
+//
 //    DECLARE_bool(verbose); // some other file has a DEFINE_bool(verbose, ...)
 //
 //    void MyFunc() {