1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577
|
/* This file is part of the KDE project
Copyright (C) 1999 Waldo Bastian <bastian@kde.org>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License version 2 as published by the Free Software Foundation.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*/
#ifndef _KCMDLINEARGS_H_
#define _KCMDLINEARGS_H_
#include <kurl.h>
#include <qlist.h>
#include <qstring.h>
#include <qvaluelist.h>
typedef QValueList<QCString> QCStringList;
/**
* @short Structure that holds command line options.
*/
struct KCmdLineOptions
{
const char *name;
const char *description;
const char *def; // Default
};
#define KCmdLineLastOption { 0, 0, 0 }
class KCmdLineArgsList;
class KApplication;
class KUniqueApplication;
class KCmdLineParsedOptions;
class KCmdLineParsedArgs;
class KAboutData;
class KCmdLineArgsPrivate;
/**
* Simple access to the command-line arguments.
*
* It takes into account Qt-specific options, KDE-specific options
* and application specific options.
*
* This class is used in main() via the static method
* @ref init().
*
* A typical KDE application should look like this:
*
* <pre>
* int main(int argc, char *argv[])
* {
* // Initialize command line args
* KCmdLineArgs::init(argc, argv, appName, description, version);
*
* // Tell which options are supported
* KCmdLineArgs::addCmdLineOptions( options );
*
* // Add options from other components
* KUniqueApplication::addCmdLineOptions();
*
* ....
*
* // Create application object without passing 'argc' and 'argv' again.
* KUniqueApplication app;
*
* ....
*
* // Handle our own options/argments
* // A KApplication will usually do this in main but this is not
* // necassery.
* // A KUniqueApplication might want to handle it in newInstance().
*
* KCmdLineArgs *args = KCmdLineArgs::parsedArgs();
*
* // A binary option (on / off)
* if (args->isSet("some-option"))
* ....
*
* // An option which takes an additional argument
* QCString anotherOptionArg = args->getOption("another-option");
*
* // Arguments (e.g. files to open)
* for(int i = 0; i < args->count(); i++) // Counting start at 0!
* {
* // don't forget to convert to Unicode!
* openFile( QFile::decodeName( args->arg(i)));
* // Or more convenient:
* // openURL( args->url(i));
*
* }
*
* args->clear(); // Free up some memory.
* ....
* }
* </pre>
*
* options are defined as follow
*
* <pre>
* static KCmdLineOptions options[] =
* {
* { "a", I18N_NOOP("A short binary option."), 0 },
* { "b <file>", I18N_NOOP("A short option which takes an argument."), 0 },
* { "c <speed>", I18N_NOOP("As above but with a default value."), "9600" },
* { "option1", I18N_NOOP("A long binary option, off by default."), 0 },
* { "nooption2", I18N_NOOP("A long binary option, on by default."), 0 },
* { "option3 <file>", I18N_NOOP("A long option which takes an argument."), 0 },
* { "option3 <speed>", I18N_NOOP("As above with 9600 as default."), "9600" },
* { "d", 0, 0 },
* { "option4", I18N_NOOP("A long option which has a short option as alias."), 0 },
* { "e", 0, 0 },
* { "nooption5", I18N_NOOP("Another long option with an alias."), 0 },
* { "f", 0, 0 },
* { "option6 <speed>", I18N_NOOP("'--option6 speed' is same a '-f speed'"), 0 },
* { "!option7 <cmd>", I18N_NOOP("All options following this one will be treated as arguments", 0 },
* { "+file", I18N_NOOP("A required argument 'file'.), 0 },
* { "+[arg1]", I18N_NOOP("An optional argument 'arg1'."), 0 },
* { "!+command", I18N_NOOP("A required argument 'command', that can contain multiple words, even starting with '-'.), 0 },
* { 0, 0, 0 } // End of options.
* };
* </pre>
*
* The I18N_NOOP macro is used to indicate that these strings should be
* marked for translation. The actual translation is done by KCmdLineArgs.
* You can't use i18n() here because we are setting up a static data
* structure and can't do translations at compile time.
*
* Note that a program should define the options before any arguments.
*
* When a long option has a short option as alias. A program should
* only check for the long option.
*
* With the above options a command line could look like:
* <pre>
* myapp -a -c 4800 --display localhost:0.0 --nooption5 -d /tmp/file
* </pre>
*
* Long binary options can be in the form 'option' and 'nooption'.
* A command line may contain the same binary option multiple times,
* the last option determines the outcome:
* <pre>
* myapp --nooption4 --option4 --nooption4
* </pre>
* is the same as:
* <pre>
* myapp --nooption4
* </pre>
*
* Normally if an option value is provided multiple times only the last
* value is used:
* <pre>
* myapp -c 1200 -c 2400 -c 4800
* </pre>
* is usually the same as:
* <pre>
* myapp -c 4800
* </pre>
*
* However, an application can choose to use all values specified as well.
* E.g. to specify a number of directories to use:
* <pre>
* myapp -I /usr/include -I /opt/kde/include -I /usr/X11/include
* </pre>
* When an application does this it should mention this in the description
* of the option. @ref getOptionList()
*
* @short A class for command-line argument handling.
* @author Waldo Bastian
* @version 0.0.4
*/
class KCmdLineArgs
{
friend class KApplication;
friend class KUniqueApplication;
friend class QList<KCmdLineArgs>;
public:
// Static functions:
/**
* Initialize class.
*
* This function should be called as the very first thing in
* your application.
* @param argc As passed to @p main(...).
* @param argv As passed to @p main(...).
* @param appname The untranslated name of your application. This should
* match with @p argv[0].
* @param description A short description of what your application is about.
* @param version A version.
* @param noKApp Don't add commandline options for @ref QApplication/@ref KApplication
*/
static void init(int _argc, char **_argv,
const char *_appname, const char *_description,
const char *_version, bool noKApp = false);
/**
* Initialize class.
*
* This function should be called as the very first thing in
* your application.
* @param argc As passed to @p main(...).
* @param argv As passed to @p main(...).
* @param about A KAboutData object describing your program.
* @param noKApp Don't add commandline options for @ref QApplication / @ref KApplication
*/
static void init(int _argc, char **_argv,
const KAboutData *about, bool noKApp = false);
/**
* Initialize Class
*
* This function should be called as the very first thing in
* your application.
* This method is exactly the same as calling
* @ref init(0,0, const KAboutData *about, true)
* This method will rarely be used
*
*/
static void init(const KAboutData *about);
/**
* Add options to your application.
*
* You must make sure that all possible options have been added before
* any class uses the command line arguments.
*
* @param options A list of options thath your code supplies.
* @param id A name with which these options can be identified.
* @param afterId The options are inserted after this set of options.
*
* The list of options should look like this:
*
* static KCmdLineOptions options[] =
* {
* { "option1 <argument>", I18N_NOOP("Description 1"), "default" },
* { "o", 0, 0 },
* { "option2", I18N_NOOP("Description 2"), 0 },
* { "nooption3", I18N_NOOP("Description 3"), 0 },
* { 0, 0, 0}
* }
*
* @li "option1" is an option that requires an additional argument
* @li "option2" is an option that can be turned on. The default is off.
* @li "option3" is an option that can be turned off. The default is on.
* @li "o" does not have a description. It is an alias for the option
* that follows. In this case "option2".
* @li "+file" specifies an argument. The '+' is removed. If your program
* doesn't specify that it can use arguments your program will abort
* when an argument is passed to it.
*
* In BNF:
* cmd = myapp [options] file
* options = (option)*
* option = --option1 <argument> |
* (-o | --option2 | --nooption2) |
* ( --option3 | --nooption3 )
*
* Instead of "--option3" one may also use "-option3"
*
* Usage examples:
*
* @li "myapp --option1 test"
* @li "myapp" (same as "myapp --option1 default")
* @li "myapp --option2"
* @li "myapp --nooption2" (same as "myapp")
* @li "myapp -o" (same as "myapp --option2")
* @li "myapp --nooption3"
* @li "myapp --option3 (same as "myapp")
* @li "myapp --option2 --nooption2" (same as "myapp")
* @li "myapp /tmp/file"
*/
static void addCmdLineOptions( const KCmdLineOptions *options,
const char *name=0, const char *id = 0,
const char *afterId=0);
/**
* Access parsed arguments.
*
* This function returns all command line arguments that your code
* handles. If unknown command-line arguments are encountered the program
* is aborted and usage information is shown.
*
* @param id The name of the options you are interested in.
*/
static KCmdLineArgs *parsedArgs(const char *id=0);
/**
* Get the CWD (Current Working Directory) associated with the
* current command line arguments.
*
* Typically this is needed in KUniqueApplication::newInstance()
* since the CWD of the process may be different from the CWD
* where the user started a second instance.
**/
static QString cwd();
/**
* Get the appname according to argv[0]
**/
static const char *appName();
/**
* Print the usage help to stdout and exit.
*
* @param complete If true, print all available options.
**/
static void usage(const char *id = 0);
/**
* Print an error to stderr and the usage help to stdout and exit.
*
**/
static void usage(const QString &error);
/**
* Enable i18n to be able to print a translated error message.
*
* N.B.: This function leaks memory, therefore you are expected to exit
* afterwards (e.g., by calling @ref usage()).
**/
static void enable_i18n();
// Member functions:
/**
* Read out a string option.
*
* @param option The name of the option without '-'.
*
* @return The value of the option. If the option was not
* present on the command line the default is returned.
* If the option was present more than the value of the
* last occurence is used.
*/
QCString getOption(const char *option);
/**
* Read out all occurences of a string option.
*
* @param option The name of the option without '-'.
*
* @return A list of all option values. If no option was present
* on the command line, an empty list is returned.
*/
QCStringList getOptionList(const char *option);
/**
* Read out a boolean option or check for the presence of string option.
*
* @param option The name of the option without '-' or '-no'.
*
* @return The value of the option. If the option was not
* present on the command line the default is returned.
* If the option is listed as 'no<option>' the
* default is true.
* If the option is listed as '<option>' the
* default is false.
*
* If the option is listed as '<option> <arg>'
* this function returns @p true if the option was present
* and @p false otherwise.
*
*/
bool isSet(const char *option);
/**
* Read the number of arguments that aren't options (but,
* for example, filenames).
*
* @return The number of arguments that aren't options
*/
int count();
/**
* Read out an argument.
*
* @param n The argument to read. 0 is the first argument.
* @ref count()-1 is the last argument.
*
* @return A @p const @p char @p * pointer to the n'th argument.
*/
const char *arg(int n);
/**
* Read out an argument representing a URL.
*
* The argument can be
* @li an absolute filename
* @li a relative filename
* @li a URL
*
* @param n The argument to read. 0 is the first argument.
* @ref count()-1 is the last argument.
*
* @return a @p URL representing the n'th argument.
*/
KURL url(int n);
/**
* Used by @ref url
* Made public for apps that don't use @ref KCmdLineArgs
* @param urlArgs the argument
*/
static KURL makeURL( const char * urlArg );
/**
* Made public for apps that don't use @ref KCmdLineArgs
* To be done before @ref makeURL, to set the current working
* directory in case @ref makeURL needs it.
*/
static void setCwd( char * cwd ) { mCwd = cwd; }
/**
* Clear all options and arguments.
*/
void clear();
protected:
/**
* @internal
* Constructor.
*/
KCmdLineArgs( const KCmdLineOptions *_options, const char *_id,
const char *_name);
/**
* @internal use only.
*
* Use @ref clear() if you want to free up some memory.
*
* Destructor.
*/
~KCmdLineArgs();
private:
/**
* @internal
*
* Checks what to do with a single option
*/
static void findOption(const char *_opt, QCString opt, int &i, bool enabled, bool &moreOptions);
/**
* @internal
*
* Parse all arguments, verify correct syntax and put all arguments
* where they belong.
*/
static void parseAllArgs();
/**
* @internal for KApplication only:
*
* Return argc
*/
static int *qt_argc();
/**
* @internal for KApplication only:
*
* Return argv
*/
static char ***qt_argv();
/**
* @internal
*
* Remove named options.
*
* @param id The name of the options to be removed.
*/
static void removeArgs(const char *id);
/**
* @internal for KUniqueApplication only:
*
* Save all but the Qt and KDE arguments to a stream.
*/
static void saveAppArgs( QDataStream &);
/**
* @internal for KUniqueApplication only:
*
* Load arguments from a stream.
*/
static void loadAppArgs( QDataStream &);
/**
* @internal
*
* Set a boolean option
*/
void setOption(const QCString &option, bool enabled);
/**
* @internal
*
* Set a string option
*/
void setOption(const QCString &option, const char *value);
/**
* @internal
*
* Add an argument
*/
void addArgument(const char *argument);
/**
* @internal
*
* Save to a stream.
*/
void save( QDataStream &) const;
/**
* @internal
*
* Restore from a stream.
*/
void load( QDataStream &);
/**
* @internal for KApplication only
*
* Initialize class.
*
* This function should be called as the very first thing in
* your application.
* @param argc As passed to @p main(...).
* @param argv As passed to @p main(...).
* @param appname The untranslated name of your application. This should
* match with @p argv[0].
*
* This function makes KCmdLineArgs ignore all unknown options as well as
* all arguments.
*/
static void initIgnore(int _argc, char **_argv, const char *_appname);
static void printQ(const QString &msg);
const KCmdLineOptions *options;
const char *name;
const char *id;
KCmdLineParsedOptions *parsedOptionList;
KCmdLineParsedArgs *parsedArgList;
bool isQt;
static KCmdLineArgsList *argsList; // All options.
static const KAboutData *about;
static int argc; // The original argc
static char **argv; // The original argv
static bool parsed; // Whether we have parsed the arguments since calling init
static bool ignoreUnknown; // Ignore unknown options and arguments
static char *mCwd; // Current working directory. Important for KUnqiueApp!
KCmdLineArgsPrivate *d;
};
#endif
|