<commit_before>[Models](#different-models)
| [Options](#options)
| [Operands](#operands)
| [Command Line](#command-line-syntax)
| [Usage Text](#usage-text-syntax)
| [Help Facilities](#help-facilities)
| [Operating Modes](#operating-modes)

ArgFace
=======
Have you ever seen this kind of message from a computer program?

    Usage:
        program [-a] [-b|--brand] [-c <name>] [find <pattern>] <file>...
    Options:
        -a                 Process all files as a unit.
        -b, --brand		   Brand each line.
        -c          <name> Prefix name.

Of course!
It's the "usage" text that is printed when you ask for `--help`.
Most people *do* find that this message is helpful.
So why not design a command line interface that understands this specification?

That's exactly what **ArgFace** does.
It creates the command line interface from a program's "usage" text.
Then it parses the command line to yield values for corresponding options and arguments.

Here's a brief example:

    public class SampleOne {
	    private final String usageText =
                "Usage: program [-a] [-b/--brand] [-c <name>] [find <pattern>] <file>...";
        private boolean aOption;
        private boolean bOption;
        private boolean cOption;
        private String  cName;
        private boolean findOperand;
        private String  patternOperand;
        private String [] fileOperand;

        public static void main (String [] args) {
            SampleOne prog = new SampleOne();
            ArgFace argFace = ArgPrototype.create(prog.usageText, prog);
            if (argFace == null) {
                System.exit(1);
            }
            int nArg = argFace.parse(args);
            if (nArg < 0) {
                System.exit(1);
            }
            if (prog.aOption) {
                System.out.println("-a option specified");
            ...

This example creates an ArgFace object using the ArgPrototype model.
Then the command line arguments are parsed.
Finally, the boolean class member variable `aOption` is used
to navigate through the program.

The ArgPrototype model uses reflection to access private member variables.
Another model provides standard access through public getter and setter methods.
There is also a procedural model that uses no reflection at all.
See: [Models](#different-models)

The example shows private member variables that represent the command line options
and arguments that use names determined from the usage text.
The "-a" option requires a `boolean` variable with the name "aOption".
If the option includes an alternative, as with the "-b/--brand" specification,
the variable can be named either "bOption" or "brandOption".
See: [Options](#options)

The naming convention uses lower camel case throughout.
Thus, an option "--dir-path" would use the variable declaration:

	private boolean dirPathOption;

Anything in the usage text that is not an option is an operand.
Operands come in two flavors: literals and variables.
The literal operand "find" is followed by a variable operand "&lt;pattern&gt;".
The "&lt;file&gt;" specifier indicates a variable operand.<commit_msg>README update.<commit_after>[Models](#different-models)
| [Options](#options)
| [Operands](#operands)
| [Command Line](#command-line-syntax)
| [Usage Text](#usage-text-syntax)
| [Help Facilities](#help-facilities)
| [Operating Modes](#operating-modes)

ArgFace
=======
Have you ever seen this kind of message from a computer program?

    Usage:
        program [-a] [-b|--brand] [-c <name>] [find <pattern>] <file>...
    Options:
        -a                 Process all files as a unit.
        -b, --brand		   Brand each line.
        -c          <name> Prefix name.

Of course!
It's the "usage" text that is printed when you ask for `--help`.
Most people *do* find that this message is helpful.
So why not design a command line interface that understands this specification?

That's exactly what **ArgFace** does.
It creates the command line interface from a program's "usage" text.
Then it parses the command line to yield values for corresponding options and arguments.

Here's a brief example:

    public class SampleOne {
	    private final String usageText =
                "Usage: program [-a] [-b/--brand] [-c <name>] [find <pattern>] <file>...";
        private boolean aOption;
        private boolean bOption;
        private boolean cOption;
        private String  cName;
        private boolean findOperand;
        private String  patternOperand;
        private String [] fileOperand;

        public static void main (String [] args) {
            SampleOne prog = new SampleOne();
            ArgFace argFace = ArgPrototype.create(prog.usageText, prog);
            if (argFace == null) {
                System.exit(1);
            }
            int nArg = argFace.parse(args);
            if (nArg < 0) {
                System.exit(1);
            }
            if (prog.aOption) {
                System.out.println("-a option specified");
            ...

This example creates an ArgFace object using the ArgPrototype model.
Then the command line arguments are parsed.
Lastly, the boolean class member variable `aOption` is used
to navigate the program.

The ArgPrototype model uses reflection to access private member variables.
Another model provides standard access through public getter and setter methods.
There is also a procedural model that uses no reflection at all.
See: [Models](#different-models)

The example shows private member variables that represent the command line options
and arguments that use names determined from the usage text.
The "-a" option requires a `boolean` variable with the name "aOption".
If the option includes an alternative, as with the "-b/--brand" specification,
the variable can be named either "bOption" or "brandOption".
See: [Options](#options)

The naming convention uses lower camel case throughout.
Thus, an option "--dir-path" would use the variable declaration:

	private boolean dirPathOption;

Anything in the usage text that is not an option is an operand.
Operands come in two flavors: literals and variables.
The literal operand "find" is followed by a variable operand "&lt;pattern&gt;".
The "&lt;file&gt;" specifier indicates a variable operand.
{'fraction_non_alphanumeric': 0.0914458984998404, 'fraction_numerical': 0.000957548675390999, 'mean_word_length': 2.951450189155107, 'pattern_counts': {'":': 0, '<': 19, '<?xml version=': 0, '>': 17, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1707945', 'n_tokens_mistral': 1663, 'n_tokens_neox': 1584, 'n_words': 731}