1 // Generated by gmmproc 2.64.2 -- DO NOT MODIFY! 2 #ifndef _GLIBMM_OPTIONCONTEXT_H 3 #define _GLIBMM_OPTIONCONTEXT_H 4 5 6 /* Copyright (C) 2004 The glibmm Development Team 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 23 #include <glibmm/optionentry.h> 24 #include <glibmm/optiongroup.h> 25 #include <glibmm/error.h> 26 #include <sigc++/signal.h> 27 28 #ifndef DOXYGEN_SHOULD_SKIP_THIS 29 extern "C" { typedef struct _GOptionContext GOptionContext; } 30 #endif 31 32 33 namespace Glib 34 { 35 36 /** %Exception class for options. 37 */ 38 class GLIBMM_API OptionError : public Glib::Error 39 { 40 public: 41 /** @var Code UNKNOWN_OPTION 42 * An option was not known to the parser. 43 * This error will only be reported, if the parser hasn't been instructed 44 * to ignore unknown options, see g_option_context_set_ignore_unknown_options(). 45 * 46 * @var Code BAD_VALUE 47 * A value couldn't be parsed. 48 * 49 * @var Code FAILED 50 * A OptionArgFunc callback failed. 51 * 52 * @enum Code 53 * 54 * %Error codes returned by option parsing. 55 */ 56 enum Code 57 { 58 UNKNOWN_OPTION, 59 BAD_VALUE, 60 FAILED 61 }; 62 63 OptionError(Code error_code, const Glib::ustring& error_message); 64 explicit OptionError(GError* gobject); 65 Code code() const; 66 67 #ifndef DOXYGEN_SHOULD_SKIP_THIS 68 private: 69 70 static void throw_func(GError* gobject); 71 72 friend GLIBMM_API void wrap_init(); // uses throw_func() 73 74 #endif //DOXYGEN_SHOULD_SKIP_THIS 75 }; 76 77 78 /** An OptionContext defines and parses commandline options, using OptionGroup%s and \link OptionEntry option entries \endlink. 79 * 80 * It supports short and long commandline options, as shown in the following example: 81 * 82 * <tt>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</tt> 83 * 84 * The example demonstrates a number of features of the GOption 85 * commandline parser: 86 * - Options can be single letters, prefixed by a single dash. 87 * - Multiple short options can be grouped behind a single dash. 88 * - Long options are prefixed by two consecutive dashes. 89 * - Options can have an extra argument, which can be a number, a string or 90 * a filename. For long options, the extra argument can be appended with 91 * an equals sign after the option name, which is useful if the extra 92 * argument starts with a dash, which would otherwise cause it to be 93 * interpreted as another option. 94 * - Non-option arguments are returned to the application as rest arguments. 95 * - An argument consisting solely of two dashes turns off further parsing, 96 * any remaining arguments (even those starting with a dash) are returned 97 * to the application as rest arguments. 98 * 99 * The OptionContext groups options in OptionGroups, which makes it easy to 100 * incorporate options from multiple sources. The intended use for this is 101 * to let applications collect option groups from the libraries it uses, 102 * add them to their OptionContext, and parse all options by a single call 103 * to parse(). See Gtk::Main::add_gtk_option_group(), for an example. 104 * 105 * Add options by creating OptionEntry instances and appropriately-typed variables, 106 * and adding them to an OptionGroup with OptionGroup::add_entry() or 107 * OptionGroup::add_entry_filename(). The option group should then be added to 108 * the OptionContext with set_main_group() or add_group(). 109 * 110 * You might find it convenient to derive your own class from OptionGroup to 111 * contain these OptionEntry instances and member variables. 112 * 113 * If an option is of type string (see OptionGroup::add_entry()) or filename 114 * (see OptionGroup::add_entry_filename()), OptionContext takes 115 * care of converting it to the right encoding. strings are returned in 116 * UTF-8 encoding and filenames are returned in the GLib filename encoding. 117 * Note that this only works if setlocale() has been called before 118 * OptionContext::parse(). 119 * 120 * OptionContext can automatically generate nicely formatted help output. Unless it is 121 * explicitly turned off with set_help_enabled(), this will recognize 122 * the --help, -?, --help-all and --help-groupname options 123 * (where groupname is the name of an OptionGroup) and write suitable text to 124 * stdout. 125 * 126 * 127 */ 128 class GLIBMM_API OptionContext 129 { 130 public: 131 #ifndef DOXYGEN_SHOULD_SKIP_THIS 132 using CppObjectType = OptionContext; 133 using BaseObjectType = GOptionContext; 134 #endif /* DOXYGEN_SHOULD_SKIP_THIS */ 135 136 private: 137 138 139 public: 140 141 /** Creates a new option context. 142 * @param parameter_string A string which is displayed in the first line of --help output, after programname [OPTION...] 143 */ 144 explicit OptionContext(const Glib::ustring& parameter_string = Glib::ustring()); 145 146 //Note that, unlike Glib::wrap(), this would create a second C++ instance for the same C instance, 147 //so it should be used carefully. For instance you could not access data in a derived class via this second instance. 148 explicit OptionContext(GOptionContext* castitem, bool take_ownership = false); 149 150 //TODO?: 151 //OptionContext(const OptionContext& other) = delete; 152 //OptionContext& operator=(const OptionContext& other) = delete; 153 154 OptionContext(OptionContext&& other) noexcept; 155 OptionContext& operator=(OptionContext&& other) noexcept; 156 157 virtual ~OptionContext(); 158 159 160 /** Enables or disables automatic generation of `--help` output. 161 * By default, g_option_context_parse() recognizes `--help`, `-h`, 162 * `-?`, `--help-all` and `--help-groupname` and creates suitable 163 * output to stdout. 164 * 165 * @newin{2,6} 166 * 167 * @param help_enabled <tt>true</tt> to enable `--help`, <tt>false</tt> to disable it. 168 */ 169 void set_help_enabled(bool help_enabled = true); 170 171 /** Returns whether automatic `--help` generation 172 * is turned on for @a context. See g_option_context_set_help_enabled(). 173 * 174 * @newin{2,6} 175 * 176 * @return <tt>true</tt> if automatic help generation is turned on. 177 */ 178 bool get_help_enabled() const; 179 180 /** Sets whether to ignore unknown options or not. If an argument is 181 * ignored, it is left in the @a argv array after parsing. By default, 182 * g_option_context_parse() treats unknown options as error. 183 * 184 * This setting does not affect non-option arguments (i.e. arguments 185 * which don't start with a dash). But note that GOption cannot reliably 186 * determine whether a non-option belongs to a preceding unknown option. 187 * 188 * @newin{2,6} 189 * 190 * @param ignore_unknown <tt>true</tt> to ignore unknown options, <tt>false</tt> to produce 191 * an error when unknown options are met. 192 */ 193 void set_ignore_unknown_options(bool ignore_unknown = true); 194 195 /** Returns whether unknown options are ignored or not. See 196 * g_option_context_set_ignore_unknown_options(). 197 * 198 * @newin{2,6} 199 * 200 * @return <tt>true</tt> if unknown options are ignored. 201 */ 202 bool get_ignore_unknown_options() const; 203 204 205 /** Sets strict POSIX mode. 206 * 207 * By default, this mode is disabled. 208 * 209 * In strict POSIX mode, the first non-argument parameter encountered 210 * (eg: filename) terminates argument processing. Remaining arguments 211 * are treated as non-options and are not attempted to be parsed. 212 * 213 * If strict POSIX mode is disabled then parsing is done in the GNU way 214 * where option arguments can be freely mixed with non-options. 215 * 216 * As an example, consider "ls foo -l". With GNU style parsing, this 217 * will list "foo" in long mode. In strict POSIX style, this will list 218 * the files named "foo" and "-l". 219 * 220 * It may be useful to force strict POSIX mode when creating "verb 221 * style" command line tools. For example, the "gsettings" command line 222 * tool supports the global option "--schemadir" as well as many 223 * subcommands ("get", "set", etc.) which each have their own set of 224 * arguments. Using strict POSIX mode will allow parsing the global 225 * options up to the verb name while leaving the remaining options to be 226 * parsed by the relevant subcommand (which can be determined by 227 * examining the verb name, which should be present in argv[1] after 228 * parsing). 229 * 230 * @newin{2,44} 231 * 232 * @param strict_posix The new value. 233 */ 234 void set_strict_posix(bool strict_posix = true); 235 236 /** Returns whether strict POSIX code is enabled. 237 * 238 * See g_option_context_set_strict_posix() for more information. 239 * 240 * @newin{2,44} 241 * 242 * @return <tt>true</tt> if strict POSIX is enabled, <tt>false</tt> otherwise. 243 */ 244 bool get_strict_posix() const; 245 246 247 /** Parses the command line arguments, recognizing options 248 * which have been added to @a context. A side-effect of 249 * calling this function is that g_set_prgname() will be 250 * called. 251 * 252 * If the parsing is successful, any parsed arguments are 253 * removed from the array and @a argc and @a argv are updated 254 * accordingly. A '--' option is stripped from @a argv 255 * unless there are unparsed options before and after it, 256 * or some of the options after it start with '-'. In case 257 * of an error, @a argc and @a argv are left unmodified. 258 * 259 * If automatic `--help` support is enabled 260 * (see g_option_context_set_help_enabled()), and the 261 * @a argv array contains one of the recognized help options, 262 * this function will produce help output to stdout and 263 * call `exit (0)`. 264 * 265 * Note that function depends on the [current locale][setlocale] for 266 * automatic character set conversion of string and filename 267 * arguments. 268 * 269 * @newin{2,6} 270 * 271 * @param argc A pointer to the number of command line arguments. 272 * @param argv A pointer to the array of command line arguments. 273 * @return <tt>true</tt> if the parsing was successful, 274 * <tt>false</tt> if an error occurred. 275 * 276 * @throws Glib::OptionError 277 * @throws Glib::ConvertError 278 */ 279 bool parse(int& argc, char**& argv); 280 281 282 /** Parses the command line arguments. 283 * 284 * This function is similar to parse(int& argc, char**& argv) except that it 285 * respects the normal memory rules when dealing with a strv instead of 286 * assuming that the passed-in array is the argv of the main function. 287 * In particular, strings that are removed from the arguments list will 288 * be freed using g_free(). 289 * 290 * On Windows, the strings are expected to be in UTF-8. This is in 291 * contrast to parse(int& argc, char**& argv) which expects them to be in the 292 * system codepage, which is how they are passed as @a argv to main(). 293 * See g_win32_get_command_line() or Gio::ApplicationCommandLine::get_arguments() 294 * for a solution. 295 * 296 * This function is useful if you are trying to use OptionContext with 297 * Gio::Application. 298 * 299 * @newin{2,50} 300 * 301 * @param[in,out] argv A pointer to the command line arguments 302 * (which must be in UTF-8 on Windows). 303 * @return <tt>true</tt> if the parsing was successful, 304 * <tt>false</tt> if an error occurred. 305 * @throw Glib::OptionError 306 * @throw Glib::ConvertError 307 */ 308 bool parse(char**& argv); 309 310 //g_option_context_add_main_entries(), just creates a group internally, adds them to it, and does a set_main_group() 311 //- a group without callbacks seems to do some simple default parsing. 312 313 314 /** Adds an OptionGroup to the context, so that parsing with context will recognize the options in the group. 315 * Note that the group will not be copied, so it should exist for as long as the context exists. 316 * 317 * @param group The group to add. 318 */ 319 void add_group(OptionGroup& group); 320 321 322 /** Sets an OptionGroup as the main group of the context. This has the same effect as calling add_group(), the only 323 * difference is that the options in the main group are treated differently when generating --help output. 324 * Note that the group will not be copied, so it should exist for as long as the context exists. 325 * 326 * @param group The group to add. 327 */ 328 void set_main_group(OptionGroup& group); 329 330 331 //We don't need this (hopefully), and the memory management would be really awkward. 332 //OptionGroup& get_main_group(); 333 //const OptionGroup& get_main_group() const; 334 335 336 /** Returns a formatted, translated help text for the given context. 337 * To obtain the text produced by `--help`, call 338 * `g_option_context_get_help (context, <tt>true</tt>, <tt>nullptr</tt>)`. 339 * To obtain the text produced by `--help-all`, call 340 * `g_option_context_get_help (context, <tt>false</tt>, <tt>nullptr</tt>)`. 341 * To obtain the help text for an option group, call 342 * `g_option_context_get_help (context, <tt>false</tt>, group)`. 343 * 344 * @newin{2,14} 345 * 346 * @param main_help If <tt>true</tt>, only include the main group. 347 * @param group The OptionGroup to create help for, or <tt>nullptr</tt>. 348 * @return A newly allocated string containing the help text. 349 */ 350 Glib::ustring get_help(bool main_help, const OptionGroup& group) const; 351 352 /** Returns a formatted, translated help text for the given context. 353 * 354 * - To obtain the text produced by --help, call get_help(true). 355 * - To obtain the text produced by --help-all, call get_help(false). 356 * - To obtain the help text for an option group, call get_help(false, group). 357 * 358 * @param main_help If true, only include the main group. 359 * @result string containing the help text. 360 */ 361 Glib::ustring get_help(bool main_help = true) const; 362 gobj()363 GOptionContext* gobj() { return gobject_; } gobj()364 const GOptionContext* gobj() const { return gobject_; } 365 366 367 /** Adds a string to be displayed in `--help` output before the list 368 * of options. This is typically a summary of the program functionality. 369 * 370 * Note that the summary is translated (see 371 * g_option_context_set_translate_func() and 372 * g_option_context_set_translation_domain()). 373 * 374 * @newin{2,12} 375 * 376 * @param summary A string to be shown in --help output before the list of 377 * options. 378 */ 379 void set_summary(const Glib::ustring& summary); 380 381 /** Returns the summary. See g_option_context_set_summary(). 382 * 383 * @newin{2,12} 384 * 385 * @return The summary. 386 */ 387 Glib::ustring get_summary() const; 388 389 /** Adds a string to be displayed in `--help` output after the list 390 * of options. This text often includes a bug reporting address. 391 * 392 * Note that the summary is translated (see 393 * g_option_context_set_translate_func()). 394 * 395 * @newin{2,12} 396 * 397 * @param description A string to be shown in --help output 398 * after the list of options. 399 */ 400 void set_description(const Glib::ustring& description); 401 402 /** Returns the description. See g_option_context_set_description(). 403 * 404 * @newin{2,12} 405 * 406 * @return The description. 407 */ 408 Glib::ustring get_description() const; 409 410 411 /** A convenience function to use gettext() for translating 412 * user-visible strings. 413 * 414 * @newin{2,12} 415 * 416 * @param domain The domain to use. 417 */ 418 void set_translation_domain(const Glib::ustring& domain); 419 420 /** 421 * This function is used to translate user-visible strings, for --help output. 422 * The function takes an untranslated string and returns a translated string 423 */ 424 using SlotTranslate = sigc::slot<Glib::ustring, const Glib::ustring&>; 425 426 /** 427 * Sets the function which is used to translate user-visible 428 * strings, for --help output. Different groups can use different functions. 429 * 430 * If you are using gettext(), you only need to set the translation domain, 431 * see set_translation_domain(). 432 * 433 * @newin{2,14} 434 */ 435 void set_translate_func (const SlotTranslate& slot); 436 437 438 protected: 439 440 GOptionContext* gobject_; 441 bool has_ownership_; 442 443 444 }; 445 446 447 } // namespace Glib 448 449 450 #endif /* _GLIBMM_OPTIONCONTEXT_H */ 451 452