arg

KCmdLineArgs(3)             Library Functions Manual             KCmdLineArgs(3)



NAME
       KCmdLineArgs - Simple access to the command-line arguments. A class for
       command-line argument handling.


SYNOPSIS
       #include <kcmdlineargs.h>

   Public Member Functions
       QCString getOption (const  char *option) const
           Read out a string option.
       QCStringList getOptionList (const  char *option) const
           Read out all occurences of a string option.
       bool isSet (const  char *option) const
           Read out a boolean option or check for the presence of string option.
       int count () const
           Read the number of arguments that aren't options (but, for example,
           filenames).
       const  char * arg (int n) const
           Read out an argument.
       KURL url (int n) const
           Read out an argument representing a URL.
       void clear ()
           Clear all options and arguments.

   Static Public Member Functions
       void init (int _argc, char **_argv, const  char *_appname, const  char
           *_description, const  char *_version, bool noKApp=false)
           Initialize class.
       void init (int _argc, char **_argv, const  KAboutData *about, bool
           noKApp=false)
           Initialize class.
       void init (const  KAboutData *about)
           Initialize Class.
       void addCmdLineOptions (const  KCmdLineOptions *options, const  char
           *name=0, const  char *id=0, const  char *afterId=0)
           Add options to your application.
       KCmdLineArgs * parsedArgs (const  char *id=0)
           Access parsed arguments.
       QString cwd ()
           Get the CWD (Current Working Directory) associated with the current
           command line arguments.
       const  char * appName ()
           Get the appname according to argv[0].
       void usage (const  char *id=0)
           Print the usage help to stdout and exit.
       void usage (const  QString &error)
           Print an error to stderr and the usage help to stdout and exit.
       void enable_i18n ()
           Enable i18n to be able to print a translated error message.
       KURL makeURL (const  char *urlArg)
           Used by url().
       void setCwd (char *cwd)
           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.

   Protected Member Functions
       KCmdLineArgs (const  KCmdLineOptions *_options, const  char *_id, const
           char *_name)
           Constructor.
       ~KCmdLineArgs ()
           Destructor.

   Friends
       class KApplication
       class KUniqueApplication
       class QPtrList< KCmdLineArgs >

Detailed Description
       Simple access to the command-line arguments. A class for command-line
       argument handling.

       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 should look like this:

         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.
            ....
         }

       options are defined as follow

        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. };

       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:

            myapp -a -c 4800 --display localhost:0.0 --nooption5 -d /tmp/file


       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:

            myapp --nooption4 --option4 --nooption4


        is the same as:

            myapp --nooption4


       Normally if an option value is provided multiple times only the last value is used:

            myapp -c 1200 -c 2400 -c 4800


        is usually the same as:

            myapp -c 4800


       However, an application can choose to use all values specified as well. E.g. to specify a number of directories to use:

            myapp -I /usr/include -I /opt/kde/include -I /usr/X11/include


        When an application does this it should mention this in the description of the option. getOptionList()

       Tips for end-users:

       • Single char options like '-a -b -c' may be combined into '-abc'

       • The option '--foo bar' may also be written '--foo=bar'

       • The option '-P lp1' may also be written '-P=lp1' or '-Plp1'

       • The option '--foo bar' may also be written '-foo bar'

       Author:
           Waldo Bastian

       Version:
           0.0.4

       Definition at line 190 of file kcmdlineargs.h.

Constructor & Destructor Documentation
   KCmdLineArgs::KCmdLineArgs (const KCmdLineOptions * _options, const char *
       _name, const char * _id) [protected]
       Constructor. The given arguments are assumed to be constants. Definition
       at line 913 of file kcmdlineargs.cpp.

       References KStdAction::name().

       Referenced by addCmdLineOptions().

   KCmdLineArgs::~KCmdLineArgs () [protected]
       Destructor. Definition at line 925 of file kcmdlineargs.cpp.

Member Function Documentation
   void KCmdLineArgs::init (int _argc, char ** _argv, const char * _appname,
       const char * _description, const char * _version, bool noKApp = false)
       [static]
       Initialize class. This function should be called as the very first thing
       in your application.

       Parameters:
           argc As passed to main(...).
           argv As passed to main(...).
           appname The untranslated name of your application. This should match
           with argv[0].
           description A short description of what your application is about.
           version A version.
           noKApp Don't add commandline options for QApplication/KApplication

       Definition at line 122 of file kcmdlineargs.cpp.

       Referenced by init().

   void KCmdLineArgs::init (int _argc, char ** _argv, const KAboutData * about,
       bool noKApp = false) [static]
       Initialize class. This function should be called as the very first thing
       in your application.

       Parameters:
           argc As passed to main(...).
           argv As passed to main(...).
           about A KAboutData object describing your program.
           noKApp Don't add commandline options for QApplication / KApplication

       Definition at line 146 of file kcmdlineargs.cpp.

       References KApplication::addCmdLineOptions().

   void KCmdLineArgs::init (const KAboutData * about) [static]
       Initialize Class. This function should be called as the very first thing
       in your application. This method is exactly the same as calling init(0,0,
       const KAboutData *about, true) This method will rarely be used

       Parameters:
           about the about data.

       Definition at line 139 of file kcmdlineargs.cpp.

       References init().

   void KCmdLineArgs::addCmdLineOptions (const KCmdLineOptions * options, const
       char * name = 0, const char * id = 0, const char * afterId = 0) [static]
       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:

       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} }

       •

       •

       •

       •

       •

       In BNF: cmd = myapp [options] file options = (option)* option = --option1
       | (-o | --option2 | --nooption2) | ( --option3 | --nooption3 )

       Instead of '--option3' one may also use '-option3'

       Usage examples:

       •

       •

       •

       •

       •

       •

       •

       •

       •

       Parameters:
           options A list of options thath your code supplies.
           name the name of the option, can be 0.
           id A name with which these options can be identified, can be 0.
           afterId The options are inserted after this set of options, can be 0.

       Definition at line 191 of file kcmdlineargs.cpp.

       References id, KCmdLineArgs(), and KStdAction::name().

       Referenced by KUniqueApplication::addCmdLineOptions(), and
       KApplication::addCmdLineOptions().

   KCmdLineArgs * KCmdLineArgs::parsedArgs (const char * id = 0) [static]
       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.

       Parameters:
           id The name of the options you are interested in, can be 0.

       Definition at line 290 of file kcmdlineargs.cpp.

       References id.

       Referenced by KApplication::dcopClient(), and
       KUniqueApplication::start().

   QString KCmdLineArgs::cwd () [static]
       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.

       Returns:
           the current working directory

       Definition at line 179 of file kcmdlineargs.cpp.

       References QFile::decodeName().

       Referenced by makeURL().

   const  char * KCmdLineArgs::appName () [static]
       Get the appname according to argv[0]. Returns:
           the name of the application

       Definition at line 184 of file kcmdlineargs.cpp.

       Referenced by KApplication::setTopWidget().

   void KCmdLineArgs::usage (const char * id = 0) [static]
       Print the usage help to stdout and exit. Parameters:
           id if 0, print all options. If id is set, only print the option
           specified by id. The id is the value set by #ref addCmdLineOptions().

       Definition at line 729 of file kcmdlineargs.cpp.

       References arg(), QString::arg(), KCmdLineOptions::def,
       KCmdLineOptions::description, KStdAccel::description(), enable_i18n(),
       QString::fromLatin1(), id, KStdAction::name(), name,
       KCmdLineOptions::name, options, KAboutData::shortDescription(),
       QStringList::split(), and usage().

       Referenced by usage().

   void KCmdLineArgs::usage (const QString & error) [static]
       Print an error to stderr and the usage help to stdout and exit.
       Parameters:
           the error to print

       Definition at line 714 of file kcmdlineargs.cpp.

       References QCString::left(), QString::length(), and QString::local8Bit().

   void KCmdLineArgs::enable_i18n () [static]
       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()). Definition at line 700 of file
       kcmdlineargs.cpp.

       References KInstance::config(), and KNotifyClient::instance().

       Referenced by usage().

   QCString KCmdLineArgs::getOption (const char * option) const
       Read out a string option. The option must have a corresponding
       KCmdLineOptions entry of the form:

           { 'option <argument>', I18N_NOOP('Description'), 'default' }


       Parameters:
           option The name of the option without '-'.

       Returns:
           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.

       Definition at line 1034 of file kcmdlineargs.cpp.

       Referenced by KApplication::dcopClient().

   QCStringList KCmdLineArgs::getOptionList (const char * option) const
       Read out all occurences of a string option. The option must have a
       corresponding KCmdLineOptions entry of the form:

           { 'option <argument>', I18N_NOOP('Description'), 'default' }


       Parameters:
           option The name of the option without '-'.

       Returns:
           A list of all option values. If no option was present on the command line, an empty list is returned.

       Definition at line 1066 of file kcmdlineargs.cpp.

       References QValueList< QCString >::begin(), QValueList< QCString >::end(), and QValueList< QCString >::prepend().

   bool KCmdLineArgs::isSet (const char * option) const
       Read out a boolean option or check for the presence of string option.
       Parameters:
           option The name of the option without '-' or '-no'.

       Returns:
           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' the
           default is true. If the option is listed as '' the default is false.

       If the option is listed as ' ' this function returns true if the option
       was present and false otherwise. Definition at line 1096 of file
       kcmdlineargs.cpp.

       Referenced by KApplication::dcopClient(), and
       KUniqueApplication::start().

   int KCmdLineArgs::count () const
       Read the number of arguments that aren't options (but, for example,
       filenames). Returns:
           The number of arguments that aren't options

       Definition at line 1139 of file kcmdlineargs.cpp.

   const  char * KCmdLineArgs::arg (int n) const
       Read out an argument. Parameters:
           n The argument to read. 0 is the first argument. count()-1 is the
           last argument.

       Returns:
           A const char * pointer to the n'th argument.

       Definition at line 1147 of file kcmdlineargs.cpp.

       Referenced by url(), and usage().

   KURL KCmdLineArgs::url (int n) const
       Read out an argument representing a URL. The argument can be

       • an absolute filename

       • a relative filename

       • a URL

       Parameters:
           n The argument to read. 0 is the first argument. count()-1 is the
           last argument.

       Returns:
           a URL representing the n'th argument.

       Definition at line 1163 of file kcmdlineargs.cpp.

       References arg(), and makeURL().

   KURL KCmdLineArgs::makeURL (const char * urlArg) [static]
       Used by url(). Made public for apps that don't use KCmdLineArgs

       Parameters:
           urlArgs the argument

       Returns:
           the url.

       Definition at line 1168 of file kcmdlineargs.cpp.

       References KURL::cleanPath(), cwd(), QFile::decodeName(),
       QString::fromLocal8Bit(), KURL::isRelativeURL(), and KURL::setPath().

       Referenced by url().

   void KCmdLineArgs::setCwd (char * cwd) [inline, static]
       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.
       Parameters:
           cwd the new working directory

       Definition at line 449 of file kcmdlineargs.h.

   void KCmdLineArgs::clear ()
       Clear all options and arguments. Definition at line 941 of file
       kcmdlineargs.cpp.


Author
       Generated automatically by Doxygen for kdecore Library from the source
       code.




kdecore Library                    28 Jan 2004                   KCmdLineArgs(3)