summaryrefslogtreecommitdiffstats
path: root/kdejava/koala/org/kde/koala/TDECmdLineArgs.java
blob: 423df7a3c3ea15313e7b40598fe48c0864be8b5b (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
//Auto-generated by kalyptus. DO NOT EDIT.
package org.kde.koala;

import org.kde.qt.Qt;
import org.kde.qt.QtSupport;
import org.kde.qt.TQDataStream;
import java.util.ArrayList;

/**

  TDECmdLineArgs 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 %TDECmdLineArgs should look like this:
  <pre>
  int main(String[] args)
  {
     // Initialize command line args
     TDECmdLineArgs.init(args, appName, programName, description, version);
     // Tell which options are supported
     TDECmdLineArgs.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 TDEApplication will usually do this in main but this is not
     // necessary.
     // A KUniqueApplication might want to handle it in newInstance().
     TDECmdLineArgs args = TDECmdLineArgs.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( TQFile.decodeName( args.arg(i)));
        // Or more convenient:
        // openURL( args.url(i));
     }
     args.clear(); // Free up some memory.
     ....
  }
  </pre>
  The options that an application supports are configured using the
  String[][] class. An example is shown below:
  <pre>
  static String[][] 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 },
      // End of options.
  }
  </pre>
  The I18N_NOOP macro is used to indicate that these strings should be
  marked for translation. The actual translation is done by TDECmdLineArgs.
  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:
  <pre>
     myapp -a -c 4800 --display localhost:0.0 --nooption5 -d /tmp/file
  </pre>
  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:
  <pre>
     myapp --nooption4 --option4 --nooption4
  </pre>
  is the same as:
  <pre>
     myapp --nooption4
  </pre>
  If an option value is provided multiple times, normally only the last
  value is used:
  <pre>
     myapp -c 1200 -c 2400 -c 4800
  </pre>
  is usually the same as:
  <pre>
     myapp -c 4800
  </pre>
  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:
  <pre>
     myapp -I /usr/include -I /opt/kde/include -I /usr/X11/include
  </pre>
  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>
	
	<li>
	The option "--foo bar" may also be written "--foo=bar"
	</li>
	
	<li>
	The option "-P lp1" may also be written "-P=lp1" or "-Plp1"
	</li>
	
	<li>
	The option "--foo bar" may also be written "-foo bar"
	</li>
			@author Waldo Bastian

		@version 0.0.4
 
		@short A class for command-line argument handling.

*/
public class TDECmdLineArgs implements QtSupport {
	private long _qt;
	private boolean _allocatedInJavaWorld = true;
	protected TDECmdLineArgs(Class dummy){}

	/**	
		  Read out a string option.
			  The option must have a corresponding String[][] entry
		  of the form:
		  <pre>
		    { "option \<argument>", I18N_NOOP("Description"), "default" }
		  </pre>
		  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.
   
		@short     Read out a string option.
	*/
	public native String getOption(String option);
	/**	
		  Read out all occurrences of a string option.
			  The option must have a corresponding String[][] entry
		  of the form:
		  <pre>
		    { "option \<argument>", I18N_NOOP("Description"), "default" }
		  </pre>
		  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.
   
		@short     Read out all occurrences of a string option.
	*/
	public native ArrayList getOptionList(String option);
	/**	
		  Read out a booleanean 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 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.
   
		@short     Read out a boolean option or check for the presence of string option.
	*/
	public native boolean isSet(String option);
	/**	
		  Read the number of arguments that aren't options (but,
		  for example, filenames).
				@return The number of arguments that aren't options
   
		@short     Read the number of arguments that aren't options (but,   for example, filenames).
	*/
	public native int count();
	/**	
		  Read out an argument.
			@param n The argument to read. 0 is the first argument.
		 count()-1 is the last argument.
				@return A <code>const</code> <code>char</code> <code></code>* pointer to the n'th argument.
   
		@short     Read out an argument.
	*/
	public native String arg(int n);
	/**	
		  Read out an argument representing a URL.
			  The argument can be
		
			<li>
			an absolute filename
			</li>
			
			<li>
			a relative filename
			</li>
			
			<li>
			a URL
			</li>
				@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.
   
		@short     Read out an argument representing a URL.
	*/
	public native KURL url(int n);
	/**	
		  Clear all options and arguments.
		   		@short     Clear all options and arguments.
	*/
	public native void clear();
	/**	
		 Initialize class.
			 This function should be called as the very first thing in
		  your application.
				@param _argv As passed to <code>main</code>(...).
			@param _appname The untranslated name of your application. This should
		                match with <code>argv</code>[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 / TDEApplication
				@short    Initialize class.
	*/
	public static native void init(String[] _argv, String _appname, String programName, String _description, String _version, boolean noKApp);
	public static native void init(String[] _argv, String _appname, String programName, String _description, String _version);
	/**	
		 Initialize class.
			 This function should be called as the very first thing in
		  your application. It uses TDEAboutData to replace some of the
		  arguments that would otherwise be required.
				@param _argv As passed to <code>main</code>(...).
			@param about A TDEAboutData object describing your program.
			@param noKApp Set this true to not add commandline options for
		        TQApplication / TDEApplication
		   		@short    Initialize class.
	*/
	public static native void init(String[] _argv, TDEAboutData about, boolean noKApp);
	public static native void init(String[] _argv, TDEAboutData 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
		 TDEAboutData information.
		 This method is exactly the same as calling
		 init(0,0, const TDEAboutData about, true).
			@param about the about data.
		 \see TDEAboutData
		   		@short    Initialize Class
	*/
	public static native void init(TDEAboutData 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:
			 <pre>
		 static String[][] 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 },
		    
		 }
		 </pre>
		
			<li>
			"option1" is an option that requires an additional argument,
			     but if one is not provided, it uses "my_extra_arg".
			</li>
			
			<li>
			"option2" is an option that can be turned on. The default is off.
			</li>
			
			<li>
			"option3" is an option that can be turned off. The default is on.
			</li>
			
			<li>
			"o" does not have a description. It is an alias for the option
			     that follows. In this case "option2".
			</li>
			
			<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:
			     <pre>
			       TDECmdLineArgs args = TDECmdLineArgs.parsedArgs();
			       if (args.count() == 0) TDECmdLineArgs.usage(i18n("No file specified!"));
			     </pre>
			</li>
				 In BNF:
		 <pre>
		 cmd = myapp [options] file
		 options = (option)
		 option = --option1 \<argument> |
		          (-o | --option2 | --nooption2) |
		          ( --option3 | --nooption3 )
		 </pre>
			 Instead of "--option3" one may also use "-option3"
			 Usage examples:
		
			<li>
			"myapp --option1 test"
			</li>
			
			<li>
			"myapp" (same as "myapp --option1 my_extra_arg")
			</li>
			
			<li>
			"myapp --option2"
			</li>
			
			<li>
			"myapp --nooption2" (same as "myapp", since it is off by default)
			</li>
			
			<li>
			"myapp -o" (same as "myapp --option2")
			</li>
			
			<li>
			"myapp --nooption3"
			</li>
			
			<li>
			"myapp --option3 (same as "myapp", since it is on by default)
			</li>
			
			<li>
			"myapp --option2 --nooption2" (same as "myapp", because it
			     option2 is off by default, and the last usage applies)
			</li>
			
			<li>
			"myapp /tmp/file"
			</li>
				@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.
		   		@short    Add options to your application.
	*/
	public static native void addCmdLineOptions(String[][] options, String name, String id, String afterId);
	public static native void addCmdLineOptions(String[][] options, String name, String id);
	public static native void addCmdLineOptions(String[][] options, String name);
	public static native void addCmdLineOptions(String[][] options);
	/**	
		 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.
		   		@short    Access parsed arguments.
	*/
	public static native TDECmdLineArgs parsedArgs(String id);
	public static native TDECmdLineArgs parsedArgs();
	/**	
		 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

		@short    Get the CWD (Current Working Directory) associated with the  current command line arguments.
	*/
	public static native String cwd();
	/**	
		 Get the appname according to argv[0].
				@return the name of the application

		@short    Get the appname according to argv[0].
	*/
	public static native String 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().
				@short    Print the usage help to stdout and exit.
	*/
	public static native void usage(String id);
	public static native void usage();
	/**	
		 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()).
				@short    Enable i18n to be able to print a translated error message.
	*/
	public static native void enable_i18n();
	/**	
		 Used by url().
		 Made public for apps that don't use TDECmdLineArgs
			@param urlArg the argument
				@return the url.
   
		@short    Used by url().
	*/
	public static native KURL makeURL(String urlArg);
	/**	
		 Made public for apps that don't use TDECmdLineArgs
		 To be done before makeURL, to set the current working
		 directory in case makeURL needs it.
			@param cwd the new working directory
		   		@short    Made public for apps that don't use TDECmdLineArgs  To be done before makeURL, to set the current working  directory in case makeURL needs it.
	*/
	public static native void setCwd(String cwd);
	/**	
		  Reset all option definitions, i.e. cancel all addCmdLineOptions calls.
		  Note that TDEApplication's options are removed too, you might want to
		  call TDEApplication.addCmdLineOptions if you want them back.
			  You usually don't want to call this method.
		   		@short     Reset all option definitions, i.
	*/
	public static native void reset();
	/**	
		 Load arguments from a stream.
		   		@short    Load arguments from a stream.
	*/
	public static native void loadAppArgs(TQDataStream arg1);
	/**	
		 Add standard option --tempfile
				@short    Add standard option --tempfile
	*/
	public static native void addTempFileOption();
	/**	
				@return true if --tempfile was set

		@short
	*/
	public static native boolean isTempFileSet();
	/**	
			  Constructor.
		   		@short
	*/
	public TDECmdLineArgs(String[][] _options, String _name, String _id) {
		newTDECmdLineArgs(_options,_name,_id);
	}
	private native void newTDECmdLineArgs(String[][] _options, String _name, String _id);
}