Thinkmine.CommandLine 1.0.6

Thinkmine Command line processor

Provides a simple attribute-driven low-code API for command-line processing, using an approach similar to Web API routing.

Usage

Creating patterns

For any given class -

1. Add static methods that return a bool for each method you want to handle a given command pattern.
2. Decorate the method with CommandPatternAttribute
3. As a catch-all for any input that does not match you can optionally provide another method (with a similar signature as is described above) and decorate it with CommandNotFoundAttribute instead

CommandPatternAttribute accepts a string as an argument. This string can contain any sequence of characters. To add placeholders to the pattern use the open and close brakets. In the following example a command pattern handler is created

[CommandPattern("say -what {something} -to {someone}")]
static bool SaySomething(string something, string someone, int i)
{
    Console.WriteLine($"You said {something} to {someone}");
    return true;
}

This method will be invoked whenever the following pattern is passed to the interpreter say -what [...] -to [...] . The placeholders in the pattern must match the parameter names of the method that it decorates (similar to Web API).
If placeholders are provided but the method does not have paramters (or they dont match) then the parameters will hold their default value when the method is run. This is also true in the reverse scenario; if no placeholders are included the method will be called with the default values of any parameters that exist. The return value is not used by the processor; rather, it is meant to be used in REPL scenarios to indicate whether the loop should continue. THe convension is to return true to continue the program and false to exit it.

In the following example we pass the following:

say hello world to the man next door

The result of this would be:

You said hello world to the man next door

A single method may be decorated with more than one command pattern (thus allowing it to handle multiple scenarios). In the following example the same SayHello method is used to handle three different patterns.

[CommandPattern("test {arg}")]
[CommandPattern("test")]
[CommandPattern("hello there")]
static bool SayHello(string arg)
{
    Console.WriteLine($"Calling hello there command with {arg}");
    return true;
}

This method will be invoked if any of the following patterns is passed into the processor.

1. test
2. test 123
3. hello there

Running the Processor

To initialize the processor use the following code:

CommandLineProcessor.Initialize();

This will traverse the current assembly and any referenced assemblies and identify all the command patterns that have been specified. A command pattern is declared by decorating a method of a certain signature: static with a boolean return type with the CommandPatternAttribute. Initialize must always be called first, and must be called again each time a new assembly is added to the AppDomain it was initially called in.

The processor can be used in two ways: For 1-time command line argument processing you can call CommandLineProcessor.Execute(string[]);

This version of the execute method accepts an array of strings. This can be the arguments passed into the console itself (but it really could be anything). No special processing is performed on the array other than turning it into a space-delimited string. So if the array: [hello,world,i,like,to,code] it would be converted to hello world i like to code. This version of the method returns void.

For creating something like a REPL (Read-evaluate-print loop) the other version of the method is more ideal. CommandLineProcessor.Execute(string);

This version of the method takes the entire string as input and processes it with no additional manipulation. This version returns a bool that can be used to determine whether it should be called again.

The following shows how a simple console REPL might look.

static void Main(string[] args)
{
    Console.WriteLine("Pidgin REPL Test");
    //call initialization
    CommandLineProcessor.Initialize();

    while (true)
    {
        Console.Write("> ");
        var command_line = Console.ReadLine();
        var continue_to_run = CommandLineProcessor.Execute(command_line);

        if (!continue_to_run)
            break;
    }

}

As can be seen from the sample, the Execute method returns a boolean value that is then used to determine whether the loop continues to run. The alternate method does not have a return type.

static void Main(string[] args)
{
    CommandLineProcessor.Initialize();
    CommandLineProcessor.Execute(args);
}