Command xgetopts


Name

xgetopts parses command line options

Synopsis

xgetopts [optstring] [--] args

Description


xgetopts runs the internal shell command option processor (Options) and emits the result as an XML document.
This is useful to be able to parse arguments from within shell scripts in a form similar to internal commands.

Options

a,argindexExit with argument index
o,optdef optstringOption string
c,command cmdnameCommand name
p,passthrough optstringpass through options
i,ignore optstringOption string to ignore
[+]s,serializeAdd (+ do not add) standard serialization options to optstring
[+]ps=pass-serializeAdd (+ do not add) standard serialization options to passthrough
noargsDo no output additional arguments
novaluesDo not output argument values

optstring A string containing the allowed options seperated by "," described below
args 0 or more arguments to be parsed using the optstring, typically $*


optstring


optstring is a single string describing the available options. It take the form of option_def "," option_def ...
Each "option_def" is the option name, optionally followed by "=longname" optionally followed by ":" or ":+".

If "=longname" is used then "longname" is an alias for the option.
If the option is followed by ":" the the option requires a value which is taken from the next argument.
If the option is followed by ":+" then the option can be specified multiple times and a list of values is produced.

If no -o or -p is given then the first argument is the optstring.

If -p is specified then an additional optstring is used as a "pass through". All arguments which match the passthrough optstring are serialized as is and remaining arguments are ignored. This is useful for a command to 'pass through' known arguments to another command.

if -novalues is specified then the character content of values are not output. This is useful for parameters which are not serializable or may be very large.

if -noargs is specified then the args element is omitted.

if -a is specified then the exit code is the relative position of the first non-option argument. This allows options to be parsed then remaining arguments shifted into $1 ... $N by using "shift $?"

if -i is specified then all options in the ignore optstring are ignored and not output in the result.


Examples


Example
xgetopts "a=all,b:,c:+"  -all -c c1 -c c2  arg1 arg2

Result
<xgetopts>
   <options>
	  <option name="a"/>
	  <option name="c">
		 <value>c1</value>
		 <value>c2</value>
	  </option>
   </options>
   <args>
	  <arg>arg1</arg>
	  <arg>arg2</arg>
   </args>
</xgetopts>



From within a script:

xgetopts "p:,o:,d:+" $* >{args}
echo $args
phase=<[ $args/xgetopts/options/option[@name='p']/value/text()]> 
echo Phase is ${phase}

shows as 

<xgetopts>
   <options>
	  <option name="p">
		 <value>phase1</value>
	  </option>
	  <option name="o">
		 <value>test.xml</value>
	  </option>
	  <option name="d">
		 <value>dir1</value>
		 <value>dir2</value>
	  </option>
   </options>
   <args/>
</xgetopts>
Phase is phase1

xgetopts "p:,o:,d:+" $* >{args} says that the p, o and d parameters are required and come from the command line. the output is put into the 'args' variable.

These lines extract the value of the p option and echo it to stdout.

phase=<[ $args/xgetopts/options/option[@name='p']/value/text()]> 
echo Phase is ${phase}



Argument count


From the above example, to retrieve the count of options
argcount=<[ count($args/xgetopts/options/option)]> 
echo $argcount args



Required Options


Note that there is no concept of "required" options. Its up to the application to check if options are supplied.


Passthrough Options


Using -p passthrough-options allows xgetops to parse an argument list only evalutating the passthrough-options and ignoring the main options.
This is useful in modules or scripts that implement a common set of options by another script or command but extend those options or get at the list of non-option arguments.

Example from the implementation of MarkLogic get command

_opts=$<(xgetopts -a -p "c=connect:,t=text" -ps -- "$@")
shift $?

for uri ; do
   :query $_opts -q "doc(\"$uri\")"
done


This collects all optional options used by the MarkLogic query command (-c,-t) into the _opts variable as a sequence, then sets $* to the remaining options.
The -a option causes xgetopts to exit with a return status of the first non-option arguement so the "shift $?" will discard all option arguments leaving the remaining args in $*.

The :query command is then passed any -c or -t option specified













Commands
CategoryCommands
There are no comments on this page.
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki