argparser -- Command line argument parser library
*************************************************

Copyright © 2013 Mattias Andrée

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Overview
********

Command line argument parser library for multiple languages with the capability of both - and + short options and both -- and ++ long options. It supports variadic options, colours and -- and temporary -- using ++.

A variadic option is a option that takes all arguments placed after it as an argument associated with it, rather than just the directly following argument as an argumented option does.

Options that are missing descriptions are not printed by the help functions.

Python version
**************

To use argparser you need to import ArgParser from argparser using the instruction from argparser import *.

The class ArgParser is used for parsing argument and requires an instance. ArgParser's constructor takes two manditory arguments and three optional arguments. The first argument, description, is a short, single-line, description of the program. The second argument, usage, is multi-line usage text that is recommended to contain ANSI colour escape sequences (for portability ESC 39m, ESC 49m and colours beyond the lower 8 are not recommended to be used); None can be used if you do not have a usage descriptor. ArgParser's constructors there optional arguments are: longdescription, program and usestderr. longdescription is a long, multi-line, description of the program; None can be used if you do not have a long description. program is the program part of the executed command, but if you rather, you can provide an exact name. You can also use the static function ArgParser.parent_name to get the program part of the executed command of a parent proces, it takes two optional arguments: levels, the number of parent levels, by default 1; and hasinterpretor, whether to get the name from an invocation of Python, by default false. usestderr is by default False which means that printing is done to stdout, otherwise, printing is done to stderr.

Before parsing arguments you need to populate the ArgParser instance with valid options. There are three methods for this, add_argumentless, add_argumented and add_variadic, that adds argumentless options, argumented options and variadic options respectively. With the exception that add_argumentless does not have the parameter arg, these three arguments has one manditory argument, alternatives, and three optional arguments: default, arg, help. default's deault value is zero, and either the primary alternative or its index in alternatives. alternatives is a list of alternatives, for example, a help option could have ['-h', '--help']. arg is a descriptive short name of a argument associated with the option, and help is description of the option and may span multiple lines but should only do so if the lines below the first is just extra details.

When you have populated your ArgParser with options, it is time to parse arguments, it is done with the method parse that optional takes and list of arguments. If you choose to use a list of arguments rather than letting ArgParser use arguments used to start the program, the first element will not be parsed as it is assumed to be the executable. If you want long options with just one dash or plus, which disables short options, you can pass True, as the second (option) argument.

If you now want to use any option alternative rather than just the primary (using just the primary is good to keep your code consistent) invoke the nulladic method support_alternatives.

Before using your options you should so some checks that the combination of options and arguments are valid. There are some methods provided to do this. test_exclusiveness checks that no confliction options are used, as the first argument, a set of options provided from which at most one may be used; as a optional second argument, a return code can be provided if you want the program to exit if there are option conflicts. test_allowed checks that only allowed options are used, as the first argument, a set of options provided in which all used arguments must exist; as a optional second argument, a return code can be provided if you want the program to exit if there are out of context option. test_files checks that the number of arguments not associated with an option is within an acccepted range, it takes three option arguments, min, max and exit_value. min is the minimum count, max is the maximum count, None if unlimited, and exit_value is a return code can be provided if you want the program to exit if there are out of context option. Remember that you should also check that the number of times an option is used is acceptable.

After running parse, your ArgParser has five attributes: unrecognisedCount, the number of unrecognised options; and message, the join of files which is all arguments not associated with an option, arguments the parsed arguments, and argcount, the number of arguments in arguments.

All valid options are stored in your ArgParser's opts, it is a dictionary from the option to either None if the option has not been used, or a list of all used values, in order. A variadic option without any argumnt will have a empty list and a argumentless option will have list filled with None.

To print a help page based on the constructor arguments and populated options invoke the nulladic method help.

Java version
************

The JAR for ArgParser, ArgParser.jar, is located in /usr/lib. When using it you need to import argparser.ArgParser.

ArgParser has six constructors, conforming to: description, usage, [longDescription, [program]], [useStderr]. These correspond to those in the Python version.

ArgParser.parent_name from the Python version is named ArgParser.parentName in the Java version and is identical except it parses Java invocation rather then Python invocation. Further support_alternatives, test_exclusiveness, test_allowed, test_files and help are named supportAlternatives, testExclusiveness, testAllowed, testFiles and help respectively and testFiles without min is named testFilesMax and testFiles without max is named testFilesMin.

parse takes an array of arguments, which excludes the executable, and optionally whether to use long options with one dash or plus and no short options.

message is a String, files is a ArrayList<String>, unrecognisedCount is a int, arguments is a String[], and opts is a HashMap<String, String[]>. argcount does not exist.

To populate the ArgParser with valid options, use the method add with the option and optional, before or after, the description. An option is created using a constructor for either Argumentless, Argumented or Variadic. Argumentless's constructor takes an String[] of alternatives and optional, before or after, the index of the primary alternative. If the index is not after the alternative array, the alternatives parameter is variadic and each alternative can be an argument. Argumentless's constructor and Variadic's constructor also takes a descriptive short name of a argument associated with the option optioned anywhere, and the alterantive array is variadic if places last.

C version
*********

To use ArgParser, compile with the linker option -largparser and use the include #include <argparser.h>. ArgParser uses the namespace args. When you are done using ArgParser you should free its resources using function args_dispose.

args_init corresponds the the ArgParser constructor in the Python version, but all parameters are manditory, additionally there as an argument that should be set to be true if you want to use long options with one dash or plus but not short options, as well as a seventh argument that you should set to null until you have read Abbreviations.

args_arguments, args_arguments_count, args_unrecognised_count, args_message and args_files works as their Python version counterparts, and args_files_count tells how many elements there are in args_files.

args_parent_name takes the number of levels as a manditory parameters, and no other parameter. args_help and args_support_alternatives takes no parameters, and args_parse takes argc and argv, the arguments in your main method.

args_test_files_min, args_test_files_max and args_test_files works are their Java version counterparts, except that an return code may not be specified. args_test_allowed and args_test_exclusiveness both takes a string array followed by the number of strings in that array, and no return code.

To popule ArgParser with valid options, use the method args_add_option which takes the options followed by a description as its parameters, the description can be NULL. To create an options use either args_new_argumentless, args_new_argumented or args_new_variadic. With the exception that args_new_argumentless does not have the second parameters, these methods have three parameters: a trigger function pointer a descriptive short name of a argument associated with the option, the index of the primary alternative, and finally a variadic parameter with the alternatives, meaning that each alternative is an argument.

To list all valid options, use the method args_get_opts which returns a string array of all options, and args_get_opts_count which returns the number of strings in the array returned by args_get_opts. args_opts_contains with a option checks whether the option is available, while args_opts_used checks whether it is used. args_opts_new adds option and args_opts_clear removes all values stored for a option. args_opts_append which takes a option and a value as parameters store a value for a option and args_opts_put sets all value for an option, it works the same way, except a string array of values is used rather than just a string with a value, args_opts_put_count stores the number of values. The get a number of values for a option, which include NULL for argumentless occurrences, use args_opts_get_count, and to retrieve the array of values, use args_opts_get. Both takes only the option as parameter.

Bash version
************

The Bash version is written to be supported for older versions of Bash, and is used by source:ing /usr/lib/argparser.bash. It works similarly to the C version and args_dispose should be invoked when done, optionally with the ID of the process that allocated the resouces.

Rather than a boolean, args_init takes a file descriptor as the fifth argument, 1 for stdout (default) and 2 for stderr.

args_parent_name takes a boolean as a second parameter that tells whether to return all arguments, on one line each, and defaults to false. Booleans are true if and only if the value is 1.

args_test_exclusiveness and args_test_allowed are variadic and does not have a parameter for the number of options.

args_test_files_min and args_test_files_max does not exist, but args_test_files takes the minimum count and optionally the maxmimum count.

To add valid options use the methods args_add_argumentless, args_add_argumented and args_add_variadic. With the except that args_add_argumentless does not take a name of the argument, these methods takes the name of the trigger function, index of the primary alternative, a one word name of the argument, a description (empty for none), and then one argument per alternative.

args_argcount is the number of elements in args_arguments and args_files does not have any such counterpart. args_has_message is 1 if there is a message, that is, if the length of args_files is not zero, and otherwise 0.

To read the parsed arguments, the method args_option is used. Its exit value is 0 if successful or if the return is true, 1 if the return is false, and 2 on failure. args_option has with a option name is used to check if a option is used. args_option count with a option name echos the number of values associated with the option. args_option null with a option name and value index checks whether the value with that index is null. args_option get with a option name echos all values, one line each, but if any number of indices are also used only those values are echoed.

Trigger functions
*****************

If you do not want to add a trigger function, use an empty string instead in the Bash version, and NULL in the C version. In the Python version, the trigger function is the last parameter in the functions for creating options, and defaults to None.

Trigger functions are invoked at the time an option is found an can be used to keep track of the order of the options, or to add additional options.

The trigger functions are functions that does not return any value, and has two or three parameters: the used option alternative, the standard option alternative, and for argumented but not variadic options: the used value but null (Or NULL or None depending on language) if there was not argument. In the Bash version only two arguments are used if there was not argument is the value of $# will be 2 instead of 3.

The the Java version, the standard option is not passed, so there are only one or two parameters. Instead, the function is defined by overriding the function trigger when creating the option, and this.standard can be used to get the standard option alternative.

Optional arguments
******************

Optionally argumented options work like argumented options. They are named Optargumented options the Java version and optargumented in the other version. The differense from argumented options are that the argument must be sticky, that is, not separated to another command line argument, unless its stickless method returns true. The default behaviour is that the stickless method returns true if and only if the argument does not start with - nor +.

The stickless method is the last argument in the Python version, the first argument in the Bash version as well as in the C version (and returns a long int). The the Java version it is definied by reimplementing it when creating a subclass to Optargumented. The stickless method only has one parameter, the argument that is being tested for using without being sticky.

Abbreviations
*************

Abbreviations is a functionallity that lets the user just write the beginning of an option and not the complete name. Conside you have the options --help and --help-all. If the user types --help- we know that he probably meant --help-all, but if less then --help is written so do not know.

The author of the software that uses the library can chose whether to enable this, disable this or something completely different with it, for example typo correction.

The constructor in the Python version and the initialisers in the C version and the Bash version are blessed with an additionall parameter. A function pointer that is used to get the correction of an unrecognised option. If this is left out — not possible in the C version — or is is null (C), None (Python) or empty (Bash) this feature is disabled. The function should take one string, the unrecognised option, an array (a list in Python) of strings, all recognised options, and return a string, the selection options (the expansion of the unrecognised option). If exactly one option cannot be selected null (C, Java) or None (Python) should be returned and in the Bash version the exit value for function should not equal zero. In the Java version you override the class's function abbreviations.

For the standard behaviour of abbreviation expansion, use the function args_standard_abbreviations (C and Bash), ArgParser.standard_abbreviations (Python) or ArgParser.standardAbbreviations (Java). In the Java version you can do this by simply using ArgParser.Abbreviations instead of ArgParser.

Colours in help message
***********************

The help methods, in ArgParser and an optional argument, if use you can set, using a true value, to always use colours, or, using a false value, to never user colours. Otherwise, colours will be used if the output is not piped.

In the Bash version, 0 is considered to be true, all other values are considered to be false, except an empty string (used if obmitted) which is used for automatic, that is, true if the output is not piped.

In the C version, 1 is considered to be true, 0 is considered to be false and all other values, including if the argument is obmitted (it is an optional argument), are used for automatic mode.

GNU Free Documentation License
******************************

     [file fdl.texinfo not included]