KDELibs4Support

kcmdlineargs.h
1 /* This file is part of the KDE project
2  Copyright (C) 1999 Waldo Bastian <[email protected]>
3 
4  This library is free software; you can redistribute it and/or
5  modify it under the terms of the GNU Library General Public
6  License version 2 as published by the Free Software Foundation.
7 
8  This library is distributed in the hope that it will be useful,
9  but WITHOUT ANY WARRANTY; without even the implied warranty of
10  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11  Library General Public License for more details.
12 
13  You should have received a copy of the GNU Library General Public License
14  along with this library; see the file COPYING.LIB. If not, write to
15  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16  Boston, MA 02110-1301, USA.
17 */
18 
19 #ifndef KCMDLINEARGS_H
20 #define KCMDLINEARGS_H
21 
22 #include <kdelibs4support_export.h>
23 
24 #ifdef KDELIBS4SUPPORT_NO_DEPRECATED_NOISE
25 #warning "This file is deprecated."
26 #endif
27 
28 #include <klocalizedstring.h>
29 
30 template <class T> class QList;
31 class QString;
32 class QStringList;
33 class QByteArray;
34 class QDataStream;
35 class QUrl;
36 
37 class KCmdLineArgs;
38 class KCmdLineArgsPrivate;
39 class KCmdLineArgsStatic;
40 class KCmdLineOptionsPrivate;
41 
42 /**
43  * @short Class that holds command line options.
44  *
45  * This class is intended to be used with the KCmdLineArgs class, which
46  * provides convenient and powerful command line argument parsing and
47  * handling functionality.
48  *
49  * @see KCmdLineArgs for additional usage information
50  *
51  * @deprecated since 5.0, port to QCommandLineParser in QtCore
52  */
53 class KDELIBS4SUPPORT_DEPRECATED_EXPORT_NOISE KCmdLineOptions
54 {
55  friend class KCmdLineArgs;
56  friend class KCmdLineArgsStatic;
57 
58 public:
59  /**
60  * Constructor.
61  */
63 
64  /**
65  * Copy constructor.
66  */
67  KCmdLineOptions(const KCmdLineOptions &options);
68 
69  /**
70  * Assignment operator.
71  */
72  KCmdLineOptions &operator= (const KCmdLineOptions &options);
73 
74  /**
75  * Destructor.
76  */
77  ~KCmdLineOptions();
78 
79  /**
80  * Add command line option, by providing its name, description, and
81  * possibly a default value. These will print out when <i>myapp --help</i>
82  * is called on the command line.
83  *
84  * Note that a long option can only have one short (single character) alias
85  *
86  * @since 4.6 Note that the following does not apply to options that begin
87  * with "no" and expect a parameter, like "nooption4" in the example below.
88  *
89  * Note that if the option name begin with "no" that you will need to test
90  * for the name without the "no" and the result will be the inverse of what
91  * is specified. i.e. if "nofoo" is the name of the option and
92  * <i>myapp --nofoo</i> is called:
93  *
94  * @code
95  * KCmdLineArgs::parsedArgs()->isSet("foo"); // false
96  * @endcode
97  *
98  * Here are some more examples showing various features:
99  *
100  * @code
101  * KCmdLineOptions options;
102  * options.add("a", ki18n("A short binary option"));
103  * options.add("b <file>", ki18n("A short option which takes an argument"));
104  * options.add("c <speed>", ki18n("As above but with a default value"), "9600");
105  * options.add("option1", ki18n("A long binary option, off by default"));
106  * options.add("nooption2", ki18n("A long binary option, on by default"));
107  * options.add(":", ki18n("Extra options:"));
108  * options.add("option3 <file>", ki18n("A long option which takes an argument"));
109  * options.add("nooption4 <speed>", ki18n("A long option which takes an argument, defaulting to 9600"), "9600");
110  * options.add("d").add("option5", ki18n("A long option which has a short option as alias"));
111  * options.add("e").add("nooption6", ki18n("Another long option with an alias"));
112  * options.add("f").add("option7 <speed>", ki18n("'--option7 speed' is the same as '-f speed'"));
113  * options.add("!option8 <cmd>", ki18n("All options following this one will be treated as arguments"));
114  * options.add("+file", ki18n("A required argument 'file'"));
115  * options.add("+[arg1]", ki18n("An optional argument 'arg1'"));
116  * options.add("!+command", ki18n("A required argument 'command', that can contain multiple words, even starting with '-'"));
117  * options.add("", ki18n("Additional help text not associated with any particular option"));
118  * @endcode
119  *
120  * @param name option name
121  * @param description option description, made available for translation;
122  * can be left off
123  * @param defaultValue default option value, when the value is not specified
124  * on the command line; can be left off
125  */
126  KCmdLineOptions &add(const QByteArray &name,
127  const KLocalizedString &description = KLocalizedString(),
128  const QByteArray &defaultValue = QByteArray());
129 
130  /**
131  * Add all options from another KCmdLineOptions object.
132  *
133  * @param options options to add
134  */
135  KCmdLineOptions &add(const KCmdLineOptions &options);
136 
137 private:
138 
139  KCmdLineOptionsPrivate *d; //krazy:exclude=dpointer (for operator=)
140 };
141 
142 class KCmdLineArgsList;
143 class KApplication;
144 class K4AboutData;
145 
146 /**
147  * @short A class for command-line argument handling.
148  *
149  * KCmdLineArgs provides simple access to the command-line arguments
150  * for an application. It takes into account Qt-specific options,
151  * KDE-specific options and application specific options.
152  *
153  * This class is used in %main() via the static method
154  * init().
155  *
156  * A typical %KDE application using %KCmdLineArgs should look like this:
157  *
158  * @code
159  * int main(int argc, char *argv[])
160  * {
161  * // Initialize command line args
162  * KCmdLineArgs::init(argc, argv, appName, programName, version, description);
163  *
164  * // Define the command line options using KCmdLineOptions
165  * KCmdLineOptions options;
166  * ....
167  *
168  * // Register the supported options
169  * KCmdLineArgs::addCmdLineOptions( options );
170  *
171  * // Add options from other components
172  * KUniqueApplication::addCmdLineOptions();
173  *
174  * ....
175  *
176  * // Create application object without passing 'argc' and 'argv' again.
177  * KUniqueApplication app;
178  *
179  * ....
180  *
181  * // Handle our own options/arguments
182  * // A KApplication will usually do this in main but this is not
183  * // necessary.
184  * // A KUniqueApplication might want to handle it in newInstance().
185  *
186  * KCmdLineArgs *args = KCmdLineArgs::parsedArgs();
187  *
188  * // A binary option (on / off)
189  * if (args->isSet("some-option"))
190  * ....
191  *
192  * // An option which takes an additional argument
193  * QString anotherOptionArg = args->getOption("another-option");
194  *
195  * // Arguments (e.g. files to open)
196  * for(int i = 0; i < args->count(); i++) // Counting start at 0!
197  * {
198  * openFile( args->arg(i));
199  * // Or more convenient:
200  * // openUrl( args->url(i));
201  *
202  * }
203  *
204  * args->clear(); // Free up some memory.
205  * ....
206  * }
207  * @endcode
208  *
209  * The options that an application supports are configured using the
210  * KCmdLineOptions class. An example is shown below:
211  *
212  * @code
213  * KCmdLineOptions options;
214  * options.add("a", ki18n("A short binary option"));
215  * options.add("b <file>", ki18n("A short option which takes an argument"));
216  * options.add("c <speed>", ki18n("As above but with a default value"), "9600");
217  * options.add("option1", ki18n("A long binary option, off by default"));
218  * options.add("nooption2", ki18n("A long binary option, on by default"));
219  * options.add(":", ki18n("Extra options:"));
220  * options.add("option3 <file>", ki18n("A long option which takes an argument"));
221  * options.add("option4 <speed>", ki18n("A long option which takes an argument, defaulting to 9600"), "9600");
222  * options.add("d").add("option5", ki18n("A long option which has a short option as alias"));
223  * options.add("e").add("nooption6", ki18n("Another long option with an alias"));
224  * options.add("f").add("option7 <speed>", ki18n("'--option7 speed' is the same as '-f speed'"));
225  * options.add("!option8 <cmd>", ki18n("All options following this one will be treated as arguments"));
226  * options.add("+file", ki18n("A required argument 'file'"));
227  * options.add("+[arg1]", ki18n("An optional argument 'arg1'"));
228  * options.add("!+command", ki18n("A required argument 'command', that can contain multiple words, even starting with '-'"));
229  * options.add("", ki18n("Additional help text not associated with any particular option"));
230  * @endcode
231  *
232  * The ki18n calls are used for translation instead of the more usual i18n
233  * calls, because the translation needs to be delayed until after the
234  * message catalogs have been initialized.
235  *
236  * Note that a program should define the options before any arguments.
237  *
238  * When a long option has a short option as an alias, a program should
239  * only test for the long option.
240  *
241  * With the above options a command line could look like:
242  * @code
243  * myapp -a -c 4800 --display localhost:0.0 --nooption5 -d /tmp/file
244  * @endcode
245  *
246  * Long binary options can be in the form 'option' and 'nooption'.
247  * A command line may contain the same binary option multiple times,
248  * the last option determines the outcome:
249  * @code
250  * myapp --nooption4 --option4 --nooption4
251  * @endcode
252  * is the same as:
253  * @code
254  * myapp --nooption4
255  * @endcode
256  *
257  * If an option value is provided multiple times, normally only the last
258  * value is used:
259  * @code
260  * myapp -c 1200 -c 2400 -c 4800
261  * @endcode
262  * is usually the same as:
263  * @code
264  * myapp -c 4800
265  * @endcode
266  *
267  * However, an application can choose to use all values specified as well.
268  * As an example of this, consider that you may wish to specify a
269  * number of directories to use:
270  * @code
271  * myapp -I /usr/include -I /opt/kde/include -I /usr/X11/include
272  * @endcode
273  * When an application does this it should mention this in the description
274  * of the option. To access these options, use getOptionList()
275  *
276  * Tips for end-users:
277  *
278  * @li Single char options like "-a -b -c" may be combined into "-abc"
279  * @li The option "--foo bar" may also be written "--foo=bar"
280  * @li The option "-P lp1" may also be written "-P=lp1" or "-Plp1"
281  * @li The option "--foo bar" may also be written "-foo bar"
282  *
283  * @author Waldo Bastian
284  * @version 0.0.4
285  */
286 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KCmdLineArgs
287 {
288  friend class KApplication;
289  friend class KCmdLineArgsList;
290  friend class KCmdLineArgsStatic;
291 public:
292  // Static functions:
293 
294  enum StdCmdLineArg {
295  CmdLineArgQt = 0x01,
296  CmdLineArgKDE = 0x02,
297  CmdLineArgsMask = 0x03,
298  CmdLineArgNone = 0x00,
299  Reserved = 0xff
300  };
301  Q_DECLARE_FLAGS(StdCmdLineArgs, StdCmdLineArg)
302  /**
303  * Initialize class.
304  *
305  * This function should be called as the very first thing in
306  * your application.
307  * @param argc As passed to @p main(...).
308  * @param argv As passed to @p main(...).
309  * @param appname The untranslated name of your application. This should
310  * match with @p argv[0].
311  * @param catalog Translation catalog name, if empty @p appname will be used.
312  * @param programName A program name string to be used for display
313  * purposes. This string should be marked for translation.
314  * Example: ki18n("KEdit")
315  * @param version A version.
316  * @param description A short description of what your application is about.
317  * Also marked for translation.
318  * @param stdargs KDE/Qt or no default parameters
319  */
320  static void init(int argc, char **argv,
321  const QByteArray &appname,
322  const QByteArray &catalog,
323  const KLocalizedString &programName,
324  const QByteArray &version,
325  const KLocalizedString &description = KLocalizedString(),
326  StdCmdLineArgs stdargs = StdCmdLineArgs(CmdLineArgQt | CmdLineArgKDE));
327 
328  /**
329  * Initialize class.
330  *
331  * This function should be called as the very first thing in
332  * your application. It uses K4AboutData to replace some of the
333  * arguments that would otherwise be required.
334  *
335  * @param _argc As passed to @p main(...).
336  * @param _argv As passed to @p main(...).
337  * @param about A K4AboutData object describing your program.
338  * @param stdargs KDE/Qt or no default parameters
339  */
340  static void init(int _argc,
341  char **_argv,
342  const K4AboutData *about,
343  StdCmdLineArgs stdargs = StdCmdLineArgs(CmdLineArgQt | CmdLineArgKDE));
344  /**
345  * Initialize Class
346  *
347  * This function should be called as the very first thing in your
348  * application. This method will rarely be used, since it doesn't
349  * provide any argument parsing. It does provide access to the
350  * K4AboutData information.
351  * This method is exactly the same as calling
352  * init(0,0, const K4AboutData *about, CmdLineArgNone).
353  *
354  * @param about the about data.
355  * @see K4AboutData
356  */
357  static void init(const K4AboutData *about);
358 
359  /**
360  * add standard Qt/KDE command-line args
361  */
362  static void addStdCmdLineOptions(StdCmdLineArgs stdargs = StdCmdLineArgs(CmdLineArgQt | CmdLineArgKDE));
363 
364  /**
365  * Add options to your application.
366  *
367  * You must make sure that all possible options have been added before
368  * any class uses the command line arguments.
369  *
370  * The list of options should look like this:
371  *
372  * @code
373  * KCmdLineOptions options;
374  * options.add("option1 <argument>", ki18n("Description 1"), "my_extra_arg");
375  * options.add("o");
376  * options.add("option2", ki18n("Description 2"));
377  * options.add("nooption3", ki18n("Description 3"));
378  * options.add("+file", ki18n("A required argument 'file'"));
379  * @endcode
380  *
381  * @li "option1" is an option that requires an additional argument,
382  * but if one is not provided, it uses "my_extra_arg".
383  * @li "option2" is an option that can be turned on. The default is off.
384  * @li "option3" is an option that can be turned off. The default is on.
385  * @li "o" does not have a description. It is an alias for the option
386  * that follows. In this case "option2".
387  * @li "+file" specifies an argument. The '+' is removed. If your program
388  * doesn't specify that it can use arguments your program will abort
389  * when an argument is passed to it. Note that the reverse is not
390  * true. If required, you must check yourself the number of arguments
391  * specified by the user:
392  * @code
393  * KCmdLineArgs *args = KCmdLineArgs::parsedArgs();
394  * if (args->count() == 0) KCmdLineArgs::usage(i18n("No file specified"));
395  * @endcode
396  *
397  * In BNF:
398  * @code
399  * cmd = myapp [options] file
400  * options = (option)*
401  * option = --option1 <argument> |
402  * (-o | --option2 | --nooption2) |
403  * ( --option3 | --nooption3 )
404  * @endcode
405  *
406  * Instead of "--option3" one may also use "-option3"
407  *
408  * Usage examples:
409  *
410  * @li "myapp --option1 test"
411  * @li "myapp" (same as "myapp --option1 my_extra_arg")
412  * @li "myapp --option2"
413  * @li "myapp --nooption2" (same as "myapp", since it is off by default)
414  * @li "myapp -o" (same as "myapp --option2")
415  * @li "myapp --nooption3"
416  * @li "myapp --option3 (same as "myapp", since it is on by default)
417  * @li "myapp --option2 --nooption2" (same as "myapp", because it
418  * option2 is off by default, and the last usage applies)
419  * @li "myapp /tmp/file"
420  *
421  * @param options A list of options that your code supplies.
422  * @param name the name of the option list, as displayed by
423  * the help output. Can be empty.
424  * @param id A name with which these options can be identified, can be empty.
425  * @param afterId The options are inserted after this set of options, can be empty.
426  */
427  static void addCmdLineOptions(const KCmdLineOptions &options,
428  const KLocalizedString &name = KLocalizedString(),
429  const QByteArray &id = QByteArray(),
430  const QByteArray &afterId = QByteArray());
431 
432  /**
433  * Access parsed arguments.
434  *
435  * This function returns all command line arguments that your code
436  * handles. If unknown command-line arguments are encountered the program
437  * is aborted and usage information is shown.
438  *
439  * @param id The name of the options you are interested in, can be empty.
440  */
441  static KCmdLineArgs *parsedArgs(const QByteArray &id = QByteArray());
442 
443  /**
444  * Get the CWD (Current Working Directory) associated with the
445  * current command line arguments.
446  *
447  * Typically this is needed in KUniqueApplication::newInstance()
448  * since the CWD of the process may be different from the CWD
449  * where the user started a second instance.
450  * @return the current working directory
451  **/
452  static QString cwd();
453 
454  /**
455  * Get the appname according to argv[0].
456  * @return the name of the application
457  **/
458  static QString appName();
459 
460  /**
461  * Print the usage help to stdout and exit.
462  *
463  * @param id if empty, print all options. If id is set, only print the
464  * option specified by id. The id is the value set by
465  * addCmdLineOptions().
466  **/
467  static void usage(const QByteArray &id = QByteArray());
468 
469  /**
470  * Print an error to stderr and the usage help to stdout and exit.
471  * @param error the error to print
472  **/
473  static void usageError(const QString &error);
474 
475  /**
476  * Enable i18n to be able to print a translated error message.
477  *
478  * N.B.: This function leaks memory, therefore you are expected to exit
479  * afterwards (e.g., by calling usage()).
480  **/
481  static void enable_i18n();
482 
483  // Member functions:
484 
485  /**
486  * Read out a string option.
487  *
488  * The option must have a corresponding KCmdLineOptions entry
489  * of the form:
490  * @code
491  * options.add("option <argument>", ki18n("Description"), "default");
492  * @endcode
493  * You cannot test for the presence of an alias - you must always
494  * test for the full option.
495  *
496  * @param option The name of the option without '-'.
497  *
498  * @return The value of the option. If the option was not
499  * present on the command line the default is returned.
500  * If the option was present more than once, the value of the
501  * last occurrence is used.
502  */
503  QString getOption(const QByteArray &option) const;
504 
505  /**
506  * Read out all occurrences of a string option.
507  *
508  * The option must have a corresponding KCmdLineOptions entry
509  * of the form:
510  * @code
511  * options.add("option <argument>", ki18n("Description"), "default");
512  * @endcode
513  * You cannot test for the presence of an alias - you must always
514  * test for the full option.
515  *
516  * @param option The name of the option, without '-' or '-no'.
517  *
518  * @return A list of all option values. If no option was present
519  * on the command line, an empty list is returned.
520  */
521  QStringList getOptionList(const QByteArray &option) const;
522 
523  /**
524  * Read out a boolean option or check for the presence of string option.
525  *
526  * @param option The name of the option without '-' or '-no'.
527  *
528  * @return The value of the option. It will be true if the option
529  * was specifically turned on in the command line, or if the option
530  * is turned on by default (in the KCmdLineOptions list) and was
531  * not specifically turned off in the command line. Equivalently,
532  * it will be false if the option was specifically turned off in
533  * the command line, or if the option is turned off by default (in
534  * the KCmdLineOptions list) and was not specifically turned on in
535  * the command line.
536  */
537  bool isSet(const QByteArray &option) const;
538 
539  /**
540  * Read the number of arguments that aren't options (but,
541  * for example, filenames).
542  *
543  * @return The number of arguments that aren't options
544  */
545  int count() const;
546 
547  /**
548  * Read out an argument.
549  *
550  * @param n The argument to read. 0 is the first argument.
551  * count()-1 is the last argument.
552  *
553  * @return n-th argument
554  */
555  QString arg(int n) const;
556 
557  /**
558  * Read out an argument representing a URL.
559  *
560  * The argument can be
561  * @li an absolute filename
562  * @li a relative filename
563  * @li a URL
564  *
565  * @param n The argument to read. 0 is the first argument.
566  * count()-1 is the last argument.
567  *
568  * @return a URL representing the n'th argument.
569  */
570  QUrl url(int n) const;
571 
572  /**
573  * Used by url().
574  * Made public for apps that don't use KCmdLineArgs
575  * @param urlArg the argument
576  * @return the url.
577  */
578  static QUrl makeURL(const QByteArray &urlArg);
579 
580  /**
581  * Made public for apps that don't use KCmdLineArgs
582  * To be done before makeURL, to set the current working
583  * directory in case makeURL needs it.
584  * @param cwd the new working directory
585  */
586  static void setCwd(const QByteArray &cwd);
587 
588  /**
589  * Clear all options and arguments.
590  */
591  void clear();
592 
593  /**
594  * Reset all option definitions, i.e. cancel all addCmdLineOptions calls.
595  * Note that KApplication's options are removed too, you might want to
596  * call KApplication::addCmdLineOptions if you want them back.
597  *
598  * You usually don't want to call this method.
599  */
600  static void reset();
601 
602  /**
603  * Load arguments from a stream.
604  */
605  static void loadAppArgs(QDataStream &);
606 
607  /**
608  * @internal for KUniqueApplication only:
609  *
610  * Save all but the Qt and KDE arguments to a stream.
611  */
612  static void saveAppArgs(QDataStream &);
613 
614  /**
615  * Add standard option --tempfile
616  */
617  static void addTempFileOption();
618 
619  // this avoids having to know the "id" used by addTempFileOption
620  // but this approach doesn't scale well, we can't have 50 standard options here...
621  /**
622  * @return true if --tempfile was set
623  */
624  static bool isTempFileSet();
625 
626  /**
627  * Returns the number of arguments returned by qtArgv()
628  *
629  * @see qtArgv
630  */
631  static int &qtArgc();
632 
633  /**
634  * Returns command line options for consumption by Qt after parsing them in a way that
635  * is consistent with KDE's general command line handling. In particular this ensures
636  * that Qt command line options can be specified as either -option or --option and that
637  * any options specified after '--' will be ignored.
638  *
639  * @see qt_argc
640  */
641  static char **qtArgv();
642 
643  /**
644  * Returns the list of command-line arguments.
645  * @since 4.6
646  */
647  static QStringList allArguments();
648 
649  /**
650  * Returns the K4AboutData for consumption by KComponentData
651  */
652  static const K4AboutData *aboutData();
653 
654 protected:
655  /**
656  * @internal
657  * Constructor.
658  */
659  KCmdLineArgs(const KCmdLineOptions &_options, const KLocalizedString &_name,
660  const QByteArray &_id);
661 
662  /**
663  * @internal use only.
664  *
665  * Use clear() if you want to free up some memory.
666  *
667  * Destructor.
668  */
669  ~KCmdLineArgs();
670 
671 private:
672 
673  /**
674  * @internal for KApplication only
675  *
676  * Initialize class.
677  *
678  * This function should be called as the very first thing in
679  * your application.
680  * @param argc As passed to @p main(...).
681  * @param argv As passed to @p main(...).
682  * @param appname The untranslated name of your application. This should
683  * match with @p argv[0].
684  *
685  * This function makes KCmdLineArgs ignore all unknown options as well as
686  * all arguments.
687  */
688  static void initIgnore(int _argc, char **_argv, const QByteArray &_appname);
689 
690  KCmdLineArgsPrivate *const d;
691 };
692 
693 Q_DECLARE_OPERATORS_FOR_FLAGS(KCmdLineArgs::StdCmdLineArgs)
694 
695 #endif
696 
Controls and provides information to all KDE applications.
Definition: kapplication.h:76
A class for command-line argument handling.
Definition: kcmdlineargs.h:286
This class is used to store information about a program.
Definition: k4aboutdata.h:199
QCA_EXPORT void init()
unsigned int version()
Returns the encoded number of KDE&#39;s version, see the KDE_VERSION macro.
Definition: kdeversion.cpp:24
Class that holds command line options.
Definition: kcmdlineargs.h:53
QCA_EXPORT QString appName()
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Aug 1 2021 22:58:35 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.