KDE 4.1 PyKDE API Reference
  • KDE's Python API
  • Overview
  • PyKDE Home
  • Sitemap
  • Contact Us
 

KCmdLineArgs Class Reference

from PyKDE4.kdecore import *

Detailed Description

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: 

  int main(int argc, char *argv[])
  {
     // Initialize command line args
     KCmdLineArgs.init(argc, argv, appName, programName, version, description);

     // Define the command line options using KCmdLineOptions
     KCmdLineOptions options;
     ....

     // Register the supported options
     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
     QString anotherOptionArg = args->getOption("another-option");

     // Arguments (e.g. files to open)
     for(int i = 0; i < args->count(); i++) // Counting start at 0!
     {
        openFile( args->arg(i));
        // Or more convenient:
        // openUrl( args->url(i));

     }

     args->clear(); // Free up some memory.
     ....
  }

The options that an application supports are configured using the KCmdLineOptions class. An example is shown below: 

  KCmdLineOptions options;
  options.add("a", ki18n("A short binary option"));
  options.add("b \<file>", ki18n("A short option which takes an argument"));
  options.add("c \<speed>", ki18n("As above but with a default value"), "9600");
  options.add("option1", ki18n("A long binary option, off by default"));
  options.add("nooption2", ki18n("A long binary option, on by default"));
  options.add(":", ki18n("Extra options:"));
  options.add("option3 \<file>", ki18n("A long option which takes an argument"));
  options.add("option4 \<speed>", ki18n("A long option which takes an argument, defaulting to 9600"), "9600");
  options.add("d").add("option5", ki18n("A long option which has a short option as alias"));
  options.add("e").add("nooption6", ki18n("Another long option with an alias"));
  options.add("f").add("option7 \<speed>", ki18n("'--option7 speed' is the same as '-f speed'"));
  options.add("!option8 \<cmd>", ki18n("All options following this one will be treated as arguments"));
  options.add("+file", ki18n("A required argument 'file'"));
  options.add("+[arg1]", ki18n("An optional argument 'arg1'"));
  options.add("!+command", ki18n("A required argument 'command', that can contain multiple words, even starting with '-'"));
  options.add("", ki18n("Additional help text not associated with any particular option"));

The ki18n calls are used for translation instead of the more usual i18n calls, because the translation needs to be delayed until after the message catalogs have been initialized.

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: 

     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

If an option value is provided multiple times, normally 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. As an example of this, consider that you may wish 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. To access these options, use 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


    Enumerations

    StdCmdLineArg { CmdLineArgQt, CmdLineArgKDE, CmdLineArgsMask, CmdLineArgNone, Reserved }
    Typesafe wrapper: StdCmdLineArgs

    Methods

     __init__ (self, KCmdLineOptions _options, KLocalizedString _name, QByteArray _id)
     __init__ (self, KCmdLineArgs other)
    QString arg (self, int n)
     clear (self)
    int count (self)
    QString getOption (self, QByteArray option)
    QStringList getOptionList (self, QByteArray option)
    bool isSet (self, QByteArray option)
    KUrl url (self, int n)

    Static Methods

    KAboutData aboutData ()
     addCmdLineOptions (KCmdLineOptions options, KLocalizedString name=KLocalizedString(), QByteArray id=QByteArray(), QByteArray afterId=QByteArray())
     addStdCmdLineOptions (KCmdLineArgs.StdCmdLineArgs stdargs=KCmdLineArgs.StdCmdLineArgs(KCmdLineArgs.CmdLineArgQt|KCmdLineArgs.CmdLineArgKDE))
     addTempFileOption ()
    QString appName ()
    QString cwd ()
     enable_i18n ()
     init (SIP_PYLIST argv, QByteArray appname, QByteArray catalog, KLocalizedString programName, QByteArray version, KLocalizedString description=KLocalizedString(), int stdargs=3)
     init (SIP_PYLIST argv, KAboutData about, int stdargs=3)
     init (KAboutData about)
    bool isTempFileSet ()
     loadAppArgs (QDataStream a0)
    KUrl makeURL (QByteArray urlArg)
    KCmdLineArgs parsedArgs (QByteArray id=QByteArray())
    int qtArgc ()
    char qtArgv ()
     reset ()
     saveAppArgs (QDataStream a0)
     setCwd (QByteArray cwd)
     usage (QByteArray id=QByteArray())
     usageError (QString error)

    Method Documentation

    __init__ (  self,
    KCmdLineOptions  _options,
    KLocalizedString  _name,
    QByteArray  _id
    )

    Internal:
    Constructor.

    __init__ (  self,
    KCmdLineArgs  other
    )
    KAboutData aboutData (   )

    Returns the KAboutData for consumption by KComponentData

    addCmdLineOptions ( KCmdLineOptions  options,
    KLocalizedString  name=KLocalizedString(),
    QByteArray  id=QByteArray(),
    QByteArray  afterId=QByteArray()
    )

    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: 

     KCmdLineOptions options;
 options.add("option1 \<argument>", ki18n("Description 1"), "my_extra_arg");
 options.add("o");
 options.add("option2", ki18n("Description 2"));
 options.add("nooption3", ki18n("Description 3"));
 options.add("+file", ki18n("A required argument 'file'"));

  • "option1" is an option that requires an additional argument,
    • but if one is not provided, it uses "my_extra_arg".
  • "option2" is an option that can be turned on. The default is off.
  • "option3" is an option that can be turned off. The default is on.
  • "o" does not have a description. It is an alias for the option
    • that follows. In this case "option2".
  • "+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: 
           KCmdLineArgs *args = KCmdLineArgs.parsedArgs();
       if (args->count() == 0) KCmdLineArgs.usage(i18n("No file specified"));

    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:

  • "myapp --option1 test"
  • "myapp" (same as "myapp --option1 my_extra_arg")
  • "myapp --option2"
  • "myapp --nooption2" (same as "myapp", since it is off by default)
  • "myapp -o" (same as "myapp --option2")
  • "myapp --nooption3"
  • "myapp --option3 (same as "myapp", since it is on by default)
  • "myapp --option2 --nooption2" (same as "myapp", because it
    • option2 is off by default, and the last usage applies)
  • "myapp /tmp/file"

    • Parameters:
    options  A list of options that your code supplies.
    name  the name of the option list, as displayed by the help output. Can be empty.
    id  A name with which these options can be identified, can be empty.
    afterId  The options are inserted after this set of options, can be empty.

    addStdCmdLineOptions ( KCmdLineArgs.StdCmdLineArgs  stdargs=KCmdLineArgs.StdCmdLineArgs(KCmdLineArgs.CmdLineArgQt|KCmdLineArgs.CmdLineArgKDE)
    )

    add standard Qt/KDE command-line args

    addTempFileOption (   )

    Add standard option --tempfile

    QString appName (   )

    Get the appname according to argv[0].

    Returns:
    the name of the application

    QString arg (  self,
    int  n
    )

    Read out an argument.

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

    Returns:
    n-th argument

    clear (   self )

    Clear all options and arguments.

    int count (   self )

    Read the number of arguments that aren't options (but, for example, filenames).

    Returns:
    The number of arguments that aren't options

    QString cwd (   )

    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

    enable_i18n (   )

    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()).

    QString getOption (  self,
    QByteArray  option
    )

    Read out a string option.

    The option must have a corresponding KCmdLineOptions entry of the form: 

        options.add("option \<argument>", ki18n("Description"), "default");
    You cannot test for the presence of an alias - you must always test for the full option.

    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 once, the value of the last occurrence is used.

    QStringList getOptionList (  self,
    QByteArray  option
    )

    Read out all occurrences of a string option.

    The option must have a corresponding KCmdLineOptions entry of the form: 

        options.add("option \<argument>", ki18n("Description"), "default");
    You cannot test for the presence of an alias - you must always test for the full option.

    Parameters:
    option  The name of the option, without '-' or '-no'.

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

    init ( SIP_PYLIST  argv,
    QByteArray  appname,
    QByteArray  catalog,
    KLocalizedString  programName,
    QByteArray  version,
    KLocalizedString  description=KLocalizedString(),
    int  stdargs=3
    )

    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].
    catalog  Translation catalog name, if empty appname will be used.
    programName  A program name string to be used for display purposes. This string should be marked for translation. Example: ki18n("KEdit")
    version  A version.
    description  A short description of what your application is about. Also marked for translation.
    stdargs  KDE/Qt or no default parameters

    init ( SIP_PYLIST  argv,
    KAboutData  about,
    int  stdargs=3
    )

    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.

    Parameters:
    _argc  As passed to main(...).
    _argv  As passed to main(...).
    about  A KAboutData object describing your program.
    stdargs  KDE/Qt or no default parameters

    init ( KAboutData  about
    )

    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, CmdLineArgNone).

    Parameters:
    about  the about data.

    See also:
    KAboutData

    bool isSet (  self,
    QByteArray  option
    )

    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. 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 isTempFileSet (   )

    Returns:
    true if --tempfile was set

    loadAppArgs ( QDataStream  a0
    )

    Load arguments from a stream.

    KUrl makeURL ( QByteArray  urlArg
    )

    Used by url(). Made public for apps that don't use KCmdLineArgs

    Parameters:
    urlArg  the argument

    Returns:
    the url.

    KCmdLineArgs parsedArgs ( QByteArray  id=QByteArray()
    )

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

    int qtArgc (   )

    Returns the number of arguments returned by qtArgv()

    See also:
    qtArgv

    char qtArgv (   )

    Returns command line options for consumption by Qt after parsing them in a way that is consistent with KDE's general command line handling. In particular this ensures that Qt command line options can be specified as either -option or --option and that any options specified after '--' will be ignored.

    See also:
    qt_argc

    reset (   )

    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.

    saveAppArgs ( QDataStream  a0
    )

    Internal:
    for KUniqueApplication only:

    Save all but the Qt and KDE arguments to a stream.

    setCwd ( QByteArray  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.

    Parameters:
    cwd  the new working directory

    KUrl url (  self,
    int  n
    )

    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.

    usage ( QByteArray  id=QByteArray()
    )

    Print the usage help to stdout and exit.

    Parameters:
    id  if empty, print all options. If id is set, only print the option specified by id. The id is the value set by addCmdLineOptions().

    usageError ( QString  error
    )

    Print an error to stderr and the usage help to stdout and exit.

    Parameters:
    error  the error to print

    Enumeration Documentation

    StdCmdLineArg
    Note:
    It is necessary to wrap members of this enumeration in a StdCmdLineArgs instance when passing them to a method as group of flags. For example: StdCmdLineArgs( CmdLineArgQt | CmdLineArgKDE)
    Enumerator:
    CmdLineArgQt = 0x01
    CmdLineArgKDE = 0x02
    CmdLineArgsMask = 0x03
    CmdLineArgNone = 0x00
    Reserved = 0xff

    • Full Index

    Modules

    • akonadi
    • dnssd
    • kdecore
    • kdeui
    • khtml
    • kio
    • knewstuff
    • kparts
    • kutils
    • nepomuk
    • phonon
    • solid
    • soprano
    This documentation is maintained by Simon Edwards.
    KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal