summaryrefslogtreecommitdiffstats
path: root/tdecore/kcmdlineargs.h
blob: 7b6a33e2e65ffe5fb44088391404fd6620dc6e42 (plain)
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
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
/* 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., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/

#ifndef _KCMDLINEARGS_H_
#define _KCMDLINEARGS_H_

#include "tdelibs_export.h"
#include <kurl.h>

#include <tqptrlist.h>
#include <tqstring.h>
#include <tqvaluelist.h>

typedef TQValueList<TQCString> QCStringList;

/**
 * @short Structure that holds command line options.
 *
 * This class is intended to be used with the KCmdLineArgs class, which
 * provides convenient and powerful command line argument parsing and
 * handling functionality.
 *
 * @see KCmdLineArgs for additional usage information
 */
struct TDECORE_EXPORT KCmdLineOptions
{
   /**
    * The name of the argument as it should be called on the command line and
    * appear in <i>myapp --help</i>.
    *
    * Note that if this option starts with "no" that you will need to test for
    * the name without the "no" and the result will be the inverse of what is
    * specified. i.e. if "nofoo" is the name of the option and
    * <i>myapp --nofoo</i> is called:
    *
    * \code
    * KCmdLineArgs::parsedArgs()->isSet("foo"); // false
    * \endcode
    */
   const char *name;
   /**
    * The text description of the option as should appear in
    * <i>myapp --help</i>.  This value should be wrapped with I18N_NOOP().
    */
   const char *description;
   /**
    * The default value for the option, if it is not specified on the
    * command line.
    */
   const char *def; // Default
};

#define KCmdLineLastOption { 0, 0, 0 }

class KCmdLineArgsList;
class KApplication;
class KUniqueApplication;
class KCmdLineParsedOptions;
class KCmdLineParsedArgs;
class KAboutData;
class KCmdLineArgsPrivate;

/**
 *  @short A class for command-line argument handling.
 *
 *  KCmdLineArgs provides simple access to the command-line arguments
 *  for an application. It takes into account Qt-specific options,
 *  KDE-specific options and application specific options.
 *
 *  This class is used in %main() via the static method
 *  init().
 *
 *  A typical %KDE application using %KCmdLineArgs should look like this:
 *
 *  \code
 *  int main(int argc, char *argv[])
 *  {
 *     // Initialize command line args
 *     KCmdLineArgs::init(argc, argv, appName, programName, 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/arguments
 *     // A KApplication will usually do this in main but this is not
 *     // necessary.
 *     // 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
 *     TQCString 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( TQFile::decodeName( args->arg(i)));
 *        // Or more convenient:
 *        // openURL( args->url(i));
 *
 *     }
 *
 *     args->clear(); // Free up some memory.
 *     ....
 *  }
 *  \endcode
 *
 *  The options that an application supports are configured using the
 *  KCmdLineOptions class. An example is shown below:
 *
 *  \code
 *  static const 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 },
 *     { ":", I18N_NOOP("Extra options:"), 0 },
 *     { "option3 \<file>", I18N_NOOP("A long option which takes an argument"), 0 },
 *     { "option4 \<speed>", I18N_NOOP("A long option which takes an argument, defaulting to 9600"), "9600" },
 *     { "d", 0, 0 },
 *     { "option5", I18N_NOOP("A long option which has a short option as alias"), 0 },
 *     { "e", 0, 0 },
 *     { "nooption6", I18N_NOOP("Another long option with an alias"), 0 },
 *     { "f", 0, 0 },
 *     { "option7 \<speed>", I18N_NOOP("'--option7 speed' is the same as '-f speed'"), 0 },
 *     { "!option8 \<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 },
 *     { "", I18N_NOOP("Additional help text not associated with any particular option") 0 },
 *     KCmdLineLastOption // End of options.
 *  };
 *  \endcode
 *
 *  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 an alias, a program should
 *  only test for the long option.
 *
 *  With the above options a command line could look like:
 *  \code
 *     myapp -a -c 4800 --display localhost:0.0 --nooption5 -d /tmp/file
 *  \endcode
 *
 *  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:
 *  \code
 *     myapp --nooption4 --option4 --nooption4
 *  \endcode
 *  is the same as:
 *  \code
 *     myapp --nooption4
 *  \endcode
 *
 *  If an option value is provided multiple times, normally only the last
 *  value is used:
 *  \code
 *     myapp -c 1200 -c 2400 -c 4800
 *  \endcode
 *  is usually the same as:
 *  \code
 *     myapp -c 4800
 *  \endcode
 *
 *  However, an application can choose to use all values specified as well.
 *  As an example of this, consider that you may wish to specify a
 *  number of directories to use:
 *  \code
 *     myapp -I /usr/include -I /opt/kde/include -I /usr/X11/include
 *  \endcode
 *  When an application does this it should mention this in the description
 *  of the option. To access these options, use getOptionList()
 *
 *  Tips for end-users:
 *
 *  @li Single char options like "-a -b -c" may be combined into "-abc"
 *  @li The option "--foo bar" may also be written "--foo=bar"
 *  @li The option "-P lp1" may also be written "-P=lp1" or "-Plp1"
 *  @li The option "--foo bar" may also be written "-foo bar"
 *
 *  @author Waldo Bastian
 *  @version 0.0.4
 */
class TDECORE_EXPORT KCmdLineArgs
{
  friend class KApplication;
  friend class KUniqueApplication;
  friend class TQPtrList<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 programName A program name string to be used for display
   *        purposes. This string should be marked for
   *        translation. Example: I18N_NOOP("KEdit")
   * @param _description A short description of what your application is about.
   * @param _version A version.
   * @param noKApp Set this true to not add commandline options for
   *        TQApplication / KApplication
   *
   * @since 3.2
   */
   static void init(int _argc, char **_argv, const char *_appname,
                    const char* programName, const char *_description,
                    const char *_version, bool noKApp = false);
   /**
    * @deprecated
    * You should convert any calls to this method to use the one
    * above, by adding in the program name to be used for display
    * purposes. Do not forget to mark it for translation using I18N_NOOP.
    */
  static void init(int _argc, char **_argv,
                   const char *_appname, const char *_description,
                   const char *_version, bool noKApp = false) KDE_DEPRECATED;

  /**
   * Initialize class.
   *
   * This function should be called as the very first thing in
   *  your application. It uses KAboutData to replace some of the
   *  arguments that would otherwise be required.
   *
   * @param _argc As passed to @p main(...).
   * @param _argv As passed to @p main(...).
   * @param about A KAboutData object describing your program.
   * @param noKApp Set this true to not add commandline options for
   *        TQApplication / 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 will rarely be used, since it doesn't
   * provide any argument parsing. It does provide access to the
   * KAboutData information.
   * This method is exactly the same as calling
   * init(0,0, const KAboutData *about, true).
   *
   * @param about the about data.
   * \see KAboutData
   */
  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.
   *
   * The list of options should look like this:
   *
   * \code
   * static KCmdLineOptions options[] =
   * {
   *    { "option1 \<argument>", I18N_NOOP("Description 1"), "my_extra_arg" },
   *    { "o", 0, 0 },
   *    { "option2", I18N_NOOP("Description 2"), 0 },
   *    { "nooption3", I18N_NOOP("Description 3"), 0 },
   *    KCmdLineLastOption
   * }
   * \endcode
   *
   * @li "option1" is an option that requires an additional argument,
   *     but if one is not provided, it uses "my_extra_arg".
   * @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. Note that the reverse is not
   *     true. If required, you must check yourself the number of arguments
   *     specified by the user:
   *     \code
   *       KCmdLineArgs *args = KCmdLineArgs::parsedArgs();
   *       if (args->count() == 0) KCmdLineArgs::usage(i18n("No file specified!"));
   *     \endcode
   *
   * In BNF:
   * \code
   * cmd = myapp [options] file
   * options = (option)*
   * option = --option1 \<argument> |
   *          (-o | --option2 | --nooption2) |
   *          ( --option3 | --nooption3 )
   * \endcode
   *
   * Instead of "--option3" one may also use "-option3"
   *
   * Usage examples:
   *
   * @li "myapp --option1 test"
   * @li "myapp" (same as "myapp --option1 my_extra_arg")
   * @li "myapp --option2"
   * @li "myapp --nooption2" (same as "myapp", since it is off by default)
   * @li "myapp -o" (same as "myapp --option2")
   * @li "myapp --nooption3"
   * @li "myapp --option3 (same as "myapp", since it is on by default)
   * @li "myapp --option2 --nooption2" (same as "myapp", because it
   *     option2 is off by default, and the last usage applies)
   * @li "myapp /tmp/file"
   *
   * @param options A list of options that your code supplies.
   * @param name the name of the option, can be 0.
   * @param id A name with which these options can be identified, can be 0.
   * @param afterId The options are inserted after this set of options, can be 0.
   */
  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, can be 0.
   */
  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.
   * @return the current working directory
   **/
  static TQString cwd();

  /**
   * Get the appname according to argv[0].
   * @return the name of the application
   **/
  static const char *appName();

  /**
   * Print the usage help to stdout and exit.
   *
   * @param id if 0, print all options. If id is set, only print the
   *        option specified by id. The id is the value set by
   *        addCmdLineOptions().
   **/
  static void usage(const char *id = 0);

  /**
   * Print an error to stderr and the usage help to stdout and exit.
   * @param error the error to print
   **/
  static void usage(const TQString &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 usage()).
   **/
  static void enable_i18n();

  // Member functions:


  /**
   *  Read out a string option.
   *
   *  The option must have a corresponding KCmdLineOptions entry
   *  of the form:
   *  \code
   *    { "option \<argument>", I18N_NOOP("Description"), "default" }
   *  \endcode
   *  You cannot test for the presence of an alias - you must always
   *  test for the full 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 occurrence is used.
   */
  TQCString getOption(const char *option) const;

  /**
   *  Read out all occurrences of a string option.
   *
   *  The option must have a corresponding KCmdLineOptions entry
   *  of the form:
   *  \code
   *    { "option \<argument>", I18N_NOOP("Description"), "default" }
   *  \endcode
   *  You cannot test for the presence of an alias - you must always
   *  test for the full option.
   *
   *  @param option The name of the option, without '-' or '-no'.
   *
   *  @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) const;

  /**
   *  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. It will be true if the option
   *  was specifically turned on in the command line, or if the option
   *  is turned on by default (in the KCmdLineOptions list) and was
   *  not specifically turned off in the command line. Equivalently,
   *  it will be false if the option was specifically turned off in
   *  the command line, or if the option is turned off by default (in
   *  the KCmdLineOptions list) and was not specifically turned on in
   *  the command line.
   */
  bool isSet(const char *option) const;

  /**
   *  Read the number of arguments that aren't options (but,
   *  for example, filenames).
   *
   *  @return The number of arguments that aren't options
   */
  int count() const;

  /**
   *  Read out an argument.
   *
   *  @param n The argument to read. 0 is the first argument.
   * count()-1 is the last argument.
   *
   *  @return A @p const @p char @p * pointer to the n'th argument.
   */
  const char *arg(int n) const;

  /**
   *  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.
   * count()-1 is the last argument.
   *
   *  @return a URL representing the n'th argument.
   */
  KURL url(int n) const;

  /**
   * Used by url().
   * Made public for apps that don't use KCmdLineArgs
   * @param urlArg the argument
   * @return the url.
   */
  static KURL makeURL( const char * urlArg );

  /**
   * Made public for apps that don't use KCmdLineArgs
   * To be done before makeURL, to set the current working
   * directory in case makeURL needs it.
   * @param cwd the new working directory
   */
  static void setCwd( char * cwd ) { mCwd = cwd; }

  /**
   *  Clear all options and arguments.
   */
  void clear();

  /**
   *  Reset all option definitions, i.e. cancel all addCmdLineOptions calls.
   *  Note that KApplication's options are removed too, you might want to
   *  call KApplication::addCmdLineOptions if you want them back.
   *
   *  You usually don't want to call this method.
   */
  static void reset();

  /**
   * Load arguments from a stream.
   */
  static void loadAppArgs( TQDataStream &);

  /**
   * Add standard option --tempfile
   * @since 3.4
   */
  static void addTempFileOption();

  // this avoids having to know the "id" used by addTempFileOption
  // but this approach doesn't scale well, we can't have 50 standard options here...
  /**
   * @return true if --tempfile was set
   * @since 3.4
   */
  static bool isTempFileSet();

protected:
  /**
   * @internal
   *  Constructor.
   */
  KCmdLineArgs( const KCmdLineOptions *_options, const char *_name,
                const char *_id);

  /**
   *  @internal use only.
   *
   *  Use 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, TQCString 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 *tqt_argc();

  /**
   * @internal for KApplication only:
   *
   * Return argv
   */

  static char ***tqt_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( TQDataStream &);

  /**
   * @internal
   *
   *  Set a boolean option
   */
  void setOption(const TQCString &option, bool enabled);

  /**
   * @internal
   *
   *  Set a string option
   */
  void setOption(const TQCString &option, const char *value);

  /**
   * @internal
   *
   * Add an argument
   */
  void addArgument(const char *argument);

  /**
   * @internal
   *
   * Save to a stream.
   */
  void save( TQDataStream &) const;

  /**
   * @internal
   *
   * Restore from a stream.
   */
  void load( TQDataStream &);

  /**
   * @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 TQString &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!
  static bool parseArgs;

  KCmdLineArgsPrivate *d;
};

#endif