summaryrefslogtreecommitdiff
path: root/doc/guide
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2010-06-02 18:48:40 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2010-06-02 18:48:40 +0200
commit51dc9396d8bd8f0971a59f4e3aa11e8315c394cd (patch)
treed24a2258506584644e0b74468ac22bbdad9af8ab /doc/guide
parented60746355044dd39acd82b8f42c4d9886914567 (diff)
Add support for quoting in option file scanner
Diffstat (limited to 'doc/guide')
-rw-r--r--doc/guide/index.xhtml38
1 files changed, 31 insertions, 7 deletions
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>