From 51dc9396d8bd8f0971a59f4e3aa11e8315c394cd Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Wed, 2 Jun 2010 18:48:40 +0200
Subject: Add support for quoting in option file scanner

---
 doc/guide/index.xhtml | 38 +++++++++++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 7 deletions(-)

(limited to 'doc')

diff --git a/doc/guide/index.xhtml b/doc/guide/index.xhtml
index 2ae7f1e..098fcd7 100644
--- a/doc/guide/index.xhtml
+++ b/doc/guide/index.xhtml
@@ -749,12 +749,19 @@ namespace cli
      that should be recognized as specifying the file containing additional
      options. Such a file contains a set of options, each appearing on a
      separate line optionally followed by space and an option value. Empty lines
-     and lines starting with <code>#</code> are ignored. The semantics
-     of providing options in a file is equivalent to providing the same set
-     of options in the same order on the command line at the point where the
-     options file is specified, except that shell escaping and quoting is not
-     required. Multiple files can be specified by including several file
-     options on the command line or inside other files.</p>
+     and lines starting with <code>#</code> are ignored. Option values can
+     be enclosed in double quotes (<code>" "</code>) to preserve leading
+     and trailing whitespaces as well as to specify empty values. If the
+     value itself contains trailing or leading double quote, enclose
+     it into an extra pair of double quotes, for example <code>""x""</code>.
+     Non-leading and non-trailing quotes are interpreted as being part of
+     the option value.</p>
+
+  <p>The semantics of providing options in a file is equivalent to providing
+     the same set of options in the same order on the command line at the
+     point where the options file is specified, except that shell escaping
+     and quoting is not required. Multiple files can be specified by including
+     several file options on the command line or inside other files.</p>
 
   <p>The parsing constructor (those with the <code>argc/argv</code> or
      <code>cli::scanner</code> arguments) can throw the following exceptions: <code>cli::unknown_option</code>,
@@ -774,7 +781,9 @@ namespace cli
      error in an option parser implementation. The <code>argv_file_scanner</code>
      class can also throw the <code>cli::file_io_failure</code> exception
      which indicates that a file could not be opened or there was a reading
-     error.</p>
+     error as well as the <code>cli::unmatched_quote</code> exception
+     which indicates that an unmatched leading or trailing quote was
+     found in an option value.</p>
 
   <p>All CLI exceptions are derived from the common <code>cli::exception</code>
      class which implements the polymorphic <code>std::ostream</code> insertion.
@@ -893,6 +902,21 @@ namespace cli
     virtual const char*
     what () const throw ();
   };
+
+  class unmatched_quote: public exception
+  {
+  public:
+    unmatched_quote (const std::string&amp; argument);
+
+    const std::string&amp;
+    argument () const;
+
+    virtual void
+    print (std::ostream&amp;) const;
+
+    virtual const char*
+    what () const throw ();
+  };
 }
   </pre>
 
-- 
cgit v1.1