donaldp 02/03/20 01:58:54
Added: cli/src/xdocs index.xml
Log:
Add a text document describing component.
Revision Changes Path
1.1 jakarta-avalon-excalibur/cli/src/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Excalibur CLI</title>
<subtitle>Command-line Utilities</subtitle>
<authors>
<person name="Peter Donald" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Introduction">
<p>
This component allows you to parse Command Line Options during
startup
of your application. It is designed to parse the command line
options in
the same manner as the C getopt() function in glibc (the GNU C
runtime
library). It attempts to do this in a simpler Java flavour from
original
product.
</p>
<p>
The component a number of examples in the examples/ directory
of the release. These examples allow you to get started fast and
easy.
See the examples/README.txt file for further details.
</p>
</s1>
<s1 title="Parsing Rules">
<p>
The command line is parsed accoridn to the following rules. There
are
two forms of options in this package, the Long form and the Short
form.
The long form of an option is preceeded by the '--' characters
while the
short form is preceeded by a single '-'. Some example options
would be;
--an-option, -a, --day, -s -f -a.
</p>
<p>
In the tradition of UNIX programs, the short form of an option
can occur
immediately after another short form option. So if 'a', 'b' and
'c' are
short forms of options that take no parameters then the following
command lines are equivelent; "-abc", "-a -bc", "-a -b -c", "-ab
-c" etc
</p>
<p>
Options can also accept arguments if specified. You can specify
that an
option requires an argument in which the text imediately
following the
option will be considered to be the argument to option. So if 'a'
was an
option that required an argument then the following would be
equivelent;
"-abc", "-a bc" (namely the option 'a' with argument 'bc').
</p>
<p>
Options can also specify optional arguments. In this case if
there is any
text immediately following the option character then it is
considered an
argument otherwise the option has no arguments. For example if
'a' was an
option that required an optional argument then "-abc" is an
option 'a' with
argument "bc" while "-a bc" is an option 'a' with no argument,
followed by
the text "bc". It is also possible to place an '=' sign between
the option
and it's argument. ie The following are all equivelent; "-a=bc",
"-a bc",
"-abc".
</p>
<p>
In some cases it is also necessary to disable commandline parsing
so that you
can pass a text argument to program that starts with a '-'
character. To do
this insert the sequence '--' onto command line with no text
immediately
following it. This will disable processing for the rest of the
command line.
The '--' characters will not be passed to the user program. For
instance the
line "-- -b" would result in the program being passed the text
"-b" (ie not an
option).
</p>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/03/20 09:58:54 $
</legal>
</footer>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
