Simple.ArgumentParser 1.0.3

Simple.ArgumentParser

This is a really simple, yet powerful and dynamic .NET command line argument parser library.

Table of Contents

1. Quick guide
   • Key points
   • Basic setup
   • Usage
     • Overall validity
     • Help section requested
     • Application version requested
     • Invalid arguments
     • Missing required arguments
     • Valid arguments
2. Technical information
3. Known issues & limitations

Key points

• Super quick and easy
• Supports long (--long) and short (-s) options
• Type validation (see Type.cs enum definition for supported types)
• Dynamic help section included
• Supports required arguments
• ~Supports default values~ (not yet implemented)
• ~Suppoert customizable prefixes~ (not yet implemented)

Quick guide

Basic setup

To use the parser, simply set it up to your liking, and pass the raw arguments (the string[] args) as shown in the example setup below:

var arguments = new Parser()
    .Options
        .Add(name: "key",
            shortName: "k",
            description: "An alphanumeric value",
            type: Type.Alpha,
            required: true)
        .Add(name: "flag",
            shortName: "f",
            description: "Just a simple flag",
            type: Type.None,
            required: false)
        .Add(name: "bool",
            shortName: "b",
            description: "A boolean value (true/false)",
            type: Type.Boolean,
            required: true)
        .Add(name: "a-super-long-option",
            shortName: "l",
            description: "This is a really long option",
            type: Type.Alpha,
            required: false)
        .Add(name: "number",
            shortName: "n",
            description: "An integer value",
            type: Type.Integer,
            required: true)
        .AddHelp()
        .AddVersion()
        .AddDescription("A description of the application.")
        .Build()
    .Parse(args);

That's it, really.

Usage

Now, let's try --help:

$ <executable> --help

Description:
    A description of the application.

Usage:
    <executable> [OPTIONS]

Options:
    --key                  -k  <Alpha>    (required)  An alphanumeric value
    --flag                 -f                         Just a simple flag
    --bool                 -b  <Boolean>  (required)  A boolean value (true/false)
    --a-super-long-option  -l  <Alpha>                This is a really long option
    --number               -n  <Integer>  (required)  An integer value
    --help                 -h                         Show help section
    --version              -v                         Show version information

Okay, that looks simple enough. Let's try using it with some real arguments:

$ <executable> --key just a key --bool true --number 42

Now, let's access the parsed arguments. There are many ways to interact with the parsed result.

Overall validity

For instance, you could evaluate the overall status by checking arguments.IsValid (returns false if either required arguments are missing, or invalid value has been provided for an argument - otherwise true).

Help section requested

There is an easy way of finding out if a user has requested to print the help section (--help or -h). Check arguments.ShowHelpRequested for true, and take the opportunity to actually print the help section to the user:

// handle help command
if (arguments.ShowHelpRequested)
{
    Console.WriteLine(arguments.HelpSection);
    return;
}

Application version requested

It's equally easy to find out if user has requested the application version (--version or -v):

// handle version command
if (arguments.ShowVersionRequested)
{
    Console.WriteLine(arguments.Version);
    return;
}

Invalid arguments

To find out if a user has provided invalid arguments (that is, invalid value for an option), you can check arguments.InvalidCommands, which is a list of strings representing a validation message for each invalid argument provided:

// handle invalid commands
if (arguments.InvalidCommands.Count > 0)
{
    arguments.InvalidCommands.ForEach(Console.WriteLine);
    return;
}

Missing required arguments

To find out which - if any - required arguments are missing, you can check arguments.MissingCommands, which is a list of strings representing the missing options:

// handle missing required commands
if (arguments.MissingCommands.Count > 0)
{
    arguments.MissingCommands.ForEach(c => Console.WriteLine($"Required command is missing: {c}"));
    return;
}

Valid arguments

Okay, we have now evaluated every aspect of the parsed arguments, except the good part - the valid arguments. They reside in a list of Command:s named - yup, you guessed it - ValidCommands:

// just for demo purpose
arguments.ValidCommands.ForEach(c => Console.WriteLine($"Name: {c.Name}, Type: {c.Type}, Value: {c.Value}"));

Given no bad or missing input (let's re-use the valid arguments a few paragraphs above), that would give the following output to the Console:

$ <executable> --key just a key --bool true --number 42
Name: key, Type: Alpha, Value: just a key
Name: bool, Type: Boolean, Value: true
Name: number, Type: Integer, Value: 42

That's basically it! 🙂

Technical information

Known issues & limitations

There are some issues yet to be resolved:

• there's currently no handling of conflicting argument names, be it long or short names. Be aware of this!
• at the moment, short names are mandatory for each option. They should be optional!
• option prefix should be definable - currently only -- and - are implemented