HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
argparse.h
Go to the documentation of this file.
1 /*
2  Copyright 2008 Larry Gritz and the other authors and contributors.
3  All Rights Reserved.
4 
5  Redistribution and use in source and binary forms, with or without
6  modification, are permitted provided that the following conditions are
7  met:
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 copyright
11  notice, this list of conditions and the following disclaimer in the
12  documentation and/or other materials provided with the distribution.
13  * Neither the name of the software's owners nor the names of its
14  contributors may be used to endorse or promote products derived from
15  this software without specific prior written permission.
16  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 
28  (This is the Modified BSD License)
29 */
30 
31 
32 /// \file
33 /// \brief Simple parsing of program command-line arguments.
34 
35 #pragma once
36 
37 #if defined(_MSC_VER)
38 // Ignore warnings about DLL exported classes with member variables that are template classes.
39 // This happens with the std::string m_errmessage member of ArgParse below.
40 # pragma warning(disable : 4251)
41 #endif
42 
43 #include <functional>
44 #include <memory>
45 #include <vector>
46 
47 #include <OpenImageIO/export.h>
49 #include <OpenImageIO/strutil.h>
50 
51 
53 
54 
55 class ArgOption; // Forward declaration
56 
57 
58 
59 /////////////////////////////////////////////////////////////////////////////
60 ///
61 /// \class ArgParse
62 ///
63 /// Argument Parsing
64 ///
65 /// The parse function takes a list of options and variables or functions
66 /// for storing option values and return <0 on failure:
67 ///
68 /// \code
69 /// static int parse_files (int argc, const char *argv[])
70 /// {
71 /// for (int i = 0; i < argc; i++)
72 /// filenames.push_back (argv[i]);
73 /// return 0;
74 /// }
75 ///
76 /// static int blah_callback (int argc, const char *argv[])
77 /// {
78 /// std::cout << "blah argument was " << argv[1] << "\n";
79 /// return 0;
80 /// }
81 ///
82 /// ...
83 ///
84 /// ArgParse ap;
85 ///
86 /// ap.options ("Usage: myapp [options] filename...",
87 /// "%*", parse_objects, "",
88 /// "-camera %f %f %f", &camera[0], &camera[1], &camera[2],
89 /// "set the camera position",
90 /// "-lookat %f %f %f", &lx, &ly, &lz,
91 /// "set the position of interest",
92 /// "-oversampling %d", &oversampling, "oversamping rate",
93 /// "-passes %d", &passes, "number of passes",
94 /// "-lens %f %f %f", &aperture, &focalDistance, &focalLength,
95 /// "set aperture, focal distance, focal length",
96 /// "-format %d %d %f", &width, &height, &aspect,
97 /// "set width, height, aspect ratio",
98 /// "-v", &verbose, "verbose output",
99 /// "-q %!", &verbose, "quiet mode",
100 /// "--blah %@ %s", blahcallback, "Make the callback",
101 /// NULL);
102 ///
103 /// if (ap.parse (argc, argv) < 0) {
104 /// std::cerr << ap.geterror() << std::endl;
105 /// ap.usage ();
106 /// return EXIT_FAILURE;
107 /// }
108 /// \endcode
109 ///
110 /// The available argument types are:
111 /// - no \% argument - bool flag
112 /// - \%! - a bool flag, but set it to false if the option is set
113 /// - \%d - 32bit integer
114 /// - \%f - 32bit float
115 /// - \%F - 64bit float (double)
116 /// - \%s - std::string
117 /// - \%L - std::vector<std::string> (takes 1 arg, appends to list)
118 /// - \%@ - a function pointer for a callback function will be invoked
119 /// immediately. The prototype for the callback is
120 /// int callback (int argc, char *argv[])
121 /// - \%* - catch all non-options and pass individually as an (argc,argv)
122 /// sublist to a callback, each immediately after it's found
123 /// - \%1 - catch all non-options that occur before any option is
124 /// encountered (like %*, but only for those prior to the first
125 /// real option.
126 ///
127 /// There are several special format tokens:
128 /// - "<SEPARATOR>" - not an option at all, just a description to print
129 /// in the usage output.
130 ///
131 /// Notes:
132 /// - If an option doesn't have any arguments, a bool flag argument is
133 /// assumed.
134 /// - No argument destinations are initialized.
135 /// - The empty string, "", is used as a global sublist (ie. "%*").
136 /// - Sublist functions are all of the form "int func(int argc, char **argv)".
137 /// - If a sublist function returns -1, parse() will terminate early.
138 /// - It is perfectly legal for the user to append ':' and more characters
139 /// to the end of an option name, it will match only the portion before
140 /// the semicolon (but a callback can detect the full string, this is
141 /// useful for making arguments: myprog --flag:myopt=1 foobar
142 ///
143 /////////////////////////////////////////////////////////////////////////////
144 
145 
147 public:
148  ArgParse(int argc = 0, const char** argv = NULL);
149  ~ArgParse();
150 
151  /// Declare the command line options. After the introductory
152  /// message, parameters are a set of format strings and variable
153  /// pointers. Each string contains an option name and a scanf-like
154  /// format string to enumerate the arguments of that option
155  /// (eg. "-option %d %f %s"). The format string is followed by a
156  /// list of pointers to the argument variables, just like scanf. A
157  /// NULL terminates the list. Multiple calls to options() will
158  /// append additional options.
159  int options(const char* intro, ...);
160 
161  /// With the options already set up, parse the command line.
162  /// Return 0 if ok, -1 if it's a malformed command line.
163  int parse(int argc, const char** argv);
164 
165  /// Return any error messages generated during the course of parse()
166  /// (and clear any error flags). If no error has occurred since the
167  /// last time geterror() was called, it will return an empty string.
168  std::string geterror() const;
169 
170  /// Print the usage message to stdout. The usage message is
171  /// generated and formatted automatically based on the command and
172  /// description arguments passed to parse().
173  void usage() const;
174 
175  /// Print a brief usage message to stdout. The usage message is
176  /// generated and formatted automatically based on the command and
177  /// description arguments passed to parse().
178  void briefusage() const;
179 
180  /// Return the entire command-line as one string.
181  ///
182  std::string command_line() const;
183 
184  // Type for a callback that writes something to the output stream.
185  typedef std::function<void(const ArgParse& ap, std::ostream&)> callback_t;
186 
187  // Set callbacks to run that will print any matter you want as part
188  // of the verbose usage, before and after the options are detailed.
189  void set_preoption_help(callback_t callback);
190  void set_postoption_help(callback_t callback);
191 
192 private:
193  class Impl;
194  std::unique_ptr<Impl> m_impl; // PIMPL pattern
195 };
196 
197 
198 
199 // Define symbols that let client applications determine if newly added
200 // features are supported.
201 #define OIIO_ARGPARSE_SUPPORTS_BRIEFUSAGE 1
202 
203 
String-related utilities, all in namespace Strutil.
OIIO_API std::string geterror()
GLsizeiptr const void GLenum usage
Definition: glew.h:1681
GLsizei const GLchar *const * string
Definition: glew.h:1844
std::function< void(const ArgParse &ap, std::ostream &)> callback_t
Definition: argparse.h:185
#define OIIO_NAMESPACE_END
Definition: oiioversion.h:66
#define OIIO_NAMESPACE_BEGIN
Definition: oiioversion.h:65
#define OIIO_API
Definition: export.h:91