Command line arguments handling

Here is how argument handling works in Reflex as of today.

Argument handlers register to the argument manager. Each handler specifies which arguments it can handle by implementing the supportedArgs() method, which returns an array of Argument objects. These objects are argument descriptors that indicate:

• The tags that identify the argument. Tags must start with a dash ('-').
• The syntax and description of the argument. Both are human-readable strings that are presented to the user when argument usage information is requested. The syntax shows how the argument is used (eg. -configClasses class2:class2:…:classN), while the description explains what the argument does.
• The number (0..n) of parameters expected after the argument tag. Parameters are separated by space characters, If the argument can handle a variable number of arguments, it should specify one parameter, and when processing it, split it with the Argument.split() method.

The argument manager parses all command line arguments before passing them to the handlers for processing. The order in which the arguments are processed does not depend on their order on the command line, but rather on the priority of the argument handlers, which is indicated by the getPriority() method. Handlers that have a higher priority receive their arguments before handlers with a lower priority (the order in which handlers with equal priority receive their arguments is unspecified). It is recommanded that argument handler implementors use the predefined constants for priority (they are defined in the ArgumentHandler class).

Example argument handler:

public class CmdLineConfigHandler implements ArgumentHandler
{
        public static final Argument USE_ARG = new Argument(
             "--use", // This is the tag
             1,       // Number of parameters
             Argument.syntaxSplit("path"),  // Syntax (result is path1:path2:...:pathN)
             "use given configuration handlers and plugins (jar files or directories)");  // Description
 
        public static final Argument USE_CLASS_ARG = new Argument(
             "--useClasses",
             1,
             Argument.syntaxSplit("class"),
             "use a given classes as a configuration handler or plugins (must be in the classpath)");
 
        public Argument[] supportedArgs()
        {
                return new Argument[]{USE_ARG, USE_CLASS_ARG};
        }
 
        public int getPriority()
        {
                return PRIORITY_META;
        }
 
        public void handleArgs(Map<Argument, List<String>> aArguments)
        {
                // The following method retrieves the unique parameter to the USE_ARG argument,
                // and splits it with the default delimiter
                String[] thePaths = USE_ARG.getSplitValues(aArguments);
                if (thePaths != null)
                {
                        // (...)
                }
        }
}