Prosody installation guide: test programs: command line options

All of the test programs supplied with Prosody use a single convention for interpreting options. The program code to implement this is automatically generated, and you can use this in your own programs. See Using the automatic option parser in your own programs for how to do this. Here are the rules for interpreting options.

All options start with a dash (-). For example, options can be "-x", "-ts", or "-AnOption".
The option "-?" should never be valid, so if you don't know what options a program uses, try:
```
	command -?
```
and it should print a usage message like this:
```
	Usage: command [-a =agc] [-v volume] file
```
This shows that the command takes two options, "-a" and "-v", and an extra argument. The "-v" option is used to specify a value, while the "-a" is either present or absent (signified by the "=" symbol at the start of its name). So any of these would be valid:
```
	command x.tmp
	command -a x.tmp
	command -v 10 x.tmp
	command -v10 x.tmp
	command -a -v10 x.tmp
	command -av10 x.tmp
```
but these wouldn't:
```
	command 
	command -ax x.tmp
	command -v x.tmp
	command -a -v10
	command -q x.tmp
```
Note in particular the middle one, which might look correct until you realise that the value for the "-v" option has been omitted, so what was presumably intended to be the file name is taken to be the value of the option.
All options must come before any other arguments (e.g. file names). For example, if the command is
```
	command -o 1 -x x:10.0.1.2/mykey one two -q 2
```
Then the items "-o 1 -x x:10.0.1.2/mykey" are options and the rest, "one two -q 2" are not options (they're just file names or other arguments whose interpretation depends on the command).
Some options specify a value, which must immediately follow the option. For example:
```
	command -x x:10.0.1.2/mykey
	command -y 23
	command -caller 1234567
```
The space between the option name and the value is optional, but it's usually a good idea to use a space after an option name unless the name is only a single character because it's easier to read.
If an option specifies a value, a value must always be given with the option.
If an option does not specify a value, it can be merged with the next option. For example
```
	command -a -y 23
```
is equivalent to both of these:
```
	command -ay 23
	command -ay23
```
It is a good idea to avoid doing this with options longer than one letter because something like
```
	command -AnOption -AnotherOption 23
```
is clearer than
```
	command -AnOptionAnotherOption 23
```
If an option specifies a number, then the default is zero if the option is entirely omitted.
Some options specify a timeslot. They are used like this:
```
	command -ts 1:2
	command -ts 1:2:u
```
The first number is the stream number, the second is the timeslot within that stream, and the optional third part is:

Letter Meaning
a A-law (default)
u mu-law
r raw (not companded)
If you omit an option which specifies a timeslot, the default is stream zero, timeslot zero, A-law (i.e. the same as 0:0:a).
The special option "--" indicates that there are no more options. This is useful when you want to specify the first non-option argument as a string starting with a dash. For example,
```
	command -a -- -3
```
specifies only one option: "-a".
All programs have the special option "-version" which makes them print their version number.

Letter	Meaning
a	A-law (default)
u	mu-law
r	raw (not companded)