X-ToolZ.SimpleParser 2.0.1

SimpleParser

A simple, attribute-based command line argument parser for .NET.

Define options using attributes and let SimpleParser handle the rest.

Installation

dotnet add package X-ToolZ.SimpleParser

Quick Start

using X_ToolZ;

class Options
{
    [Option("n", "name", "Your name")]
    public string Name { get; set; }

    [BoolOption("v", "verbose", "Enable verbose output")]
    public bool Verbose { get; set; }
}

var options = new Options();
var result = SimpleParser.Parse(args, options);

if (result.IsSuccessful)
{
    Console.WriteLine($"Hello, {options.Name}!");
}
else
{
    Console.WriteLine($"Error: {result.Message}");
}

Option Attributes

Option

Standard option for string, int, and other value types.

[Option("o", "output", "Output file path")]
public string OutputPath { get; set; }

[Option("c", "count", "Number of iterations")]
public int Count { get; set; }

Supports multiple syntaxes:

• -o value
• --output value
• --output=value

BoolOption

Flag option that sets a boolean to true when present.

[BoolOption("v", "verbose", "Enable verbose mode")]
public bool Verbose { get; set; }

[BoolOption("q", "quiet")]
public bool Quiet { get; set; }

Usage: -v or --verbose

ListOption

Parse comma-separated (or custom separator) values into a typed list.

[ListOption("f", "files", "Input files")]
public List<string> Files { get; set; }

[ListOption("n", "numbers", "List of numbers")]
public List<int> Numbers { get; set; }

[ListOption("v", "values", ';', "Semicolon-separated values")]
public List<double> Values { get; set; }

Usage: -f file1.txt,file2.txt,file3.txt

IndexOption

Get argument by position (zero-based index).

[IndexOption(0, "Command to execute")]
public string Command { get; set; }

[IndexOption(1, "Target file")]
public string Target { get; set; }

Usage: myapp build project.csproj → Command="build", Target="project.csproj"

EnumOption

Parse string values into enum types (case-insensitive).

public enum LogLevel { None, Info, Warning, Error }

[EnumOption("l", "level", "Log level")]
public LogLevel Level { get; set; }

[EnumOption("m", "mode")]
public LogLevel? OptionalMode { get; set; }  // Nullable enum supported

Usage: -l warning or --level=Error

Constructor Overloads

When using 2-argument attribute constructors, C# matches (shortName, description) not (shortName, longName). To specify a long name with only 2 arguments, use named parameters:

// These are equivalent:
[Option("n", "name", "")]           // 3 args: shortName, longName, description
[Option("n", longName: "name")]     // Named parameter for longName

Error Handling

SimpleParser returns a ParseResult with detailed error messages:

var result = SimpleParser.Parse(args, options);

if (!result.IsSuccessful)
{
    Console.WriteLine(result.Message);
    // Examples:
    // "Option '--output' for property 'OutputPath' requires a value."
    // "Cannot convert 'abc' to type 'Int32' for property 'Count'."
    // "Value 'invalid' is not valid for enum 'LogLevel'. Valid values: None, Info, Warning, Error."
    return 1;
}

Usage Help

Generate usage information automatically:

Console.WriteLine(SimpleParser.CreateUsage(options));

Output:

Command line options for MyApp:
Option [string] Name -n or --name (Your name)
BoolOption [bool] Verbose -v or --verbose (Enable verbose output)
ListOption [list`1] Files -f or --files (Input files)
EnumOption [LogLevel] Level -l or --level (Log level)

Complete Example

using X_ToolZ;

class Options
{
    [IndexOption(0, "Command")]
    public string Command { get; set; }

    [Option("o", "output", "Output directory")]
    public string OutputDir { get; set; }

    [BoolOption("v", "verbose", "Verbose output")]
    public bool Verbose { get; set; }

    [BoolOption("f", "force", "Force overwrite")]
    public bool Force { get; set; }

    [ListOption("i", "input", "Input files")]
    public List<string> InputFiles { get; set; }

    [EnumOption("l", "level", "Log level")]
    public LogLevel LogLevel { get; set; }
}

public enum LogLevel { None, Info, Warning, Error }

class Program
{
    static int Main(string[] args)
    {
        var options = new Options();
        var result = SimpleParser.Parse(args, options);

        if (!result.IsSuccessful)
        {
            Console.WriteLine($"Error: {result.Message}");
            Console.WriteLine(SimpleParser.CreateUsage(options));
            return 1;
        }

        Console.WriteLine($"Command: {options.Command}");
        Console.WriteLine($"Output: {options.OutputDir}");
        Console.WriteLine($"Verbose: {options.Verbose}");
        Console.WriteLine($"Files: {string.Join(", ", options.InputFiles ?? new())}");
        Console.WriteLine($"Log Level: {options.LogLevel}");

        return 0;
    }
}

Example usage:

myapp build -o ./dist -v --input=src/a.cs,src/b.cs --level=Info

License

MIT