org.kde.koala

Class KCmdLineArgs

public class KCmdLineArgs extends Object implements QtSupport

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(String[] args)
  {
     // Initialize command line args
     KCmdLineArgs.init(args, 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
     String 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.
     ....
  }
  
The options that an application supports are configured using the String[][] class. An example is shown below:
  static String[][] options =
  {
     { "a", I18N_NOOP("A short binary option"), 0 },
     { "b \", I18N_NOOP("A short option which takes an argument"), 0 },
     { "c \", 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 \", I18N_NOOP("A long option which takes an argument"), 0 },
     { "option4 \", 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 \", I18N_NOOP("'--option7 speed' is the same as '-f speed'"), 0 },
     { "!option8 \", 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 },
      // 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 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"
  • Version: 0.0.4

    Author: Waldo Bastian

    UNKNOWN: A class for command-line argument handling.

    Constructor Summary
    protected KCmdLineArgs(Class dummy)
    KCmdLineArgs(String[][] _options, String _name, String _id)
    Constructor.
    Method Summary
    static voidaddCmdLineOptions(String[][] options, String name, String id, String afterId)
    Add options to your application.
    static voidaddCmdLineOptions(String[][] options, String name, String id)
    static voidaddCmdLineOptions(String[][] options, String name)
    static voidaddCmdLineOptions(String[][] options)
    static voidaddTempFileOption()
    Add standard option --tempfile
    static StringappName()
    Get the appname according to argv[0].
    Stringarg(int n)
    Read out an argument.
    voidclear()
    Clear all options and arguments.
    intcount()
    Read the number of arguments that aren't options (but, for example, filenames).
    static Stringcwd()
    Get the CWD (Current Working Directory) associated with the current command line arguments.
    static voidenable_i18n()
    Enable i18n to be able to print a translated error message.
    StringgetOption(String option)
    Read out a string option.
    ArrayListgetOptionList(String option)
    Read out all occurrences of a string option.
    static voidinit(String[] _argv, String _appname, String programName, String _description, String _version, boolean noKApp)
    Initialize class.
    static voidinit(String[] _argv, String _appname, String programName, String _description, String _version)
    static voidinit(String[] _argv, KAboutData about, boolean noKApp)
    Initialize class.
    static voidinit(String[] _argv, KAboutData about)
    static voidinit(KAboutData about)
    Initialize Class This function should be called as the very first thing in your application.
    booleanisSet(String option)
    Read out a booleanean option or check for the presence of string option.
    static booleanisTempFileSet()
    static voidloadAppArgs(QDataStream arg1)
    Load arguments from a stream.
    static KURLmakeURL(String urlArg)
    Used by url().
    static KCmdLineArgsparsedArgs(String id)
    Access parsed arguments.
    static KCmdLineArgsparsedArgs()
    static voidreset()
    Reset all option definitions, i.e. cancel all addCmdLineOptions calls.
    static voidsetCwd(String 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.
    KURLurl(int n)
    Read out an argument representing a URL.
    static voidusage(String id)
    Print the usage help to stdout and exit.
    static voidusage()

    Constructor Detail

    KCmdLineArgs

    protected KCmdLineArgs(Class dummy)

    KCmdLineArgs

    public KCmdLineArgs(String[][] _options, String _name, String _id)
    Constructor.

    UNKNOWN:

    Method Detail

    addCmdLineOptions

    public static void addCmdLineOptions(String[][] options, String name, String id, String afterId)
    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 String[][] options =
    		 {
    		    { "option1 \", I18N_NOOP("Description 1"), "my_extra_arg" },
    		    { "o", 0, 0 },
    		    { "option2", I18N_NOOP("Description 2"), 0 },
    		    { "nooption3", I18N_NOOP("Description 3"), 0 },
    		    
    		 }
    		 
  • "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 \ |
    		          (-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, 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.

    UNKNOWN: Add options to your application.

    addCmdLineOptions

    public static void addCmdLineOptions(String[][] options, String name, String id)

    addCmdLineOptions

    public static void addCmdLineOptions(String[][] options, String name)

    addCmdLineOptions

    public static void addCmdLineOptions(String[][] options)

    addTempFileOption

    public static void addTempFileOption()
    Add standard option --tempfile

    UNKNOWN: Add standard option --tempfile

    appName

    public static String appName()
    Get the appname according to argv[0].

    Returns: the name of the application

    UNKNOWN: Get the appname according to argv[0].

    arg

    public String arg(int n)
    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.

    UNKNOWN: Read out an argument.

    clear

    public void clear()
    Clear all options and arguments.

    UNKNOWN: Clear all options and arguments.

    count

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

    Returns: The number of arguments that aren't options

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

    cwd

    public static String 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

    UNKNOWN: Get the CWD (Current Working Directory) associated with the current command line arguments.

    enable_i18n

    public static void 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()).

    UNKNOWN: Enable i18n to be able to print a translated error message.

    getOption

    public String getOption(String option)
    Read out a string option. The option must have a corresponding String[][] entry of the form:
    		    { "option \", I18N_NOOP("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 the value of the last occurrence is used.

    UNKNOWN: Read out a string option.

    getOptionList

    public ArrayList getOptionList(String option)
    Read out all occurrences of a string option. The option must have a corresponding String[][] entry of the form:
    		    { "option \", I18N_NOOP("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.

    UNKNOWN: Read out all occurrences of a string option.

    init

    public static void init(String[] _argv, String _appname, String programName, String _description, String _version, boolean noKApp)
    Initialize class. This function should be called as the very first thing in your application.

    Parameters: _argv As passed to main(...). _appname The untranslated name of your application. This should match with argv[0]. programName A program name string to be used for display purposes. This string should be marked for translation. Example: I18N_NOOP("KEdit") _description A short description of what your application is about. _version A version. noKApp Set this true to not add commandline options for QApplication / KApplication

    UNKNOWN: Initialize class.

    init

    public static void init(String[] _argv, String _appname, String programName, String _description, String _version)

    init

    public static void init(String[] _argv, KAboutData about, boolean noKApp)
    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: _argv As passed to main(...). about A KAboutData object describing your program. noKApp Set this true to not add commandline options for QApplication / KApplication

    UNKNOWN: Initialize class.

    init

    public static void init(String[] _argv, KAboutData about)

    init

    public static void 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, true).

    Parameters: about the about data. \see KAboutData

    UNKNOWN: Initialize Class

    isSet

    public boolean isSet(String option)
    Read out a booleanean 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 String[][] 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.

    UNKNOWN: Read out a boolean option or check for the presence of string option.

    isTempFileSet

    public static boolean isTempFileSet()

    Returns: true if --tempfile was set

    UNKNOWN:

    loadAppArgs

    public static void loadAppArgs(QDataStream arg1)
    Load arguments from a stream.

    UNKNOWN: Load arguments from a stream.

    makeURL

    public static KURL makeURL(String urlArg)
    Used by url(). Made public for apps that don't use KCmdLineArgs

    Parameters: urlArg the argument

    Returns: the url.

    UNKNOWN: Used by url().

    parsedArgs

    public static KCmdLineArgs parsedArgs(String id)
    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.

    UNKNOWN: Access parsed arguments.

    parsedArgs

    public static KCmdLineArgs parsedArgs()

    reset

    public static void 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.

    UNKNOWN: Reset all option definitions, i.

    setCwd

    public static void setCwd(String 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

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

    url

    public KURL url(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.

    UNKNOWN: Read out an argument representing a URL.

    usage

    public static void usage(String id)
    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 addCmdLineOptions().

    UNKNOWN: Print the usage help to stdout and exit.

    usage

    public static void usage()