XenoAtom.CommandLine

XenoAtom.CommandLine is a lightweight, powerful and NativeAOT friendly command line parser.

It is a fork of the excellent NDesk.Options/Mono.Options with several small improvements and new features.

✨ Features

• Lightweight library with no dependencies
• net8.0+ ready and NativeAOT friendly, no System.Reflection used
• Provides a simple API to parse command line arguments
• Generates a help message from the command line definition
  • What you declare is what you get!
• Supports
  • Commands and sub-command parsing (e.g. git commit -m "message")
  • Tar and POSIX style options (e.g. -abc is equivalent to -a -b -c)
  • -, / and -- option prefixes (e.g. -v, /v, --verbose))
  • Multiple option values (e.g. -i foo -i bar)
  • Optional and required option values : (e.g. -o[BAR] -oBAR)
  • Key/value pairs (e.g. `-DMACRO=VALUE1)
  • Option aliases (e.g. -v, -verbose)
  • -- to stop option parsing
  • --help and --version built-in options
  • Parsing of values to specific target types (e.g. int, bool, enum, etc.))
  • Response files e.g @file.txt
  • Grouping of command/options that can be activated together when a specific condition is met.

🧪 Example

using System;
using XenoAtom.CommandLine;

const string _ = "";
string? name = null;
int age = 0;
List<(string, string?)> keyValues = new List<(string, string?)>();
List<string> messages = new List<string>();

var commandApp = new CommandApp("myexe")
{
    _,
    {"D:", "Defines a {0:name} and optional {1:value}", (key, value) =>
    {
        if (key is null) throw new OptionException("The key is mandatory for a define", "D");
        keyValues.Add((key, value));
    }},
    {"n|name=", "Your {NAME}", v => name = v},
    {"a|age=", "Your {AGE}", (int v) => age = v},
    new HelpOption(),
    _,
    "Available commands:",
    new Command("commit")
    {
        _,
        {"m|message=", "Add a {MESSAGE} to this commit", messages},
        new HelpOption(),

        // Action for the commit command
        (ctx, arguments) =>
        {
            ctx.Out.WriteLine($"Committing with name={name}, age={age}");
            foreach (var message in messages)
            {
                ctx.Out.WriteLine($"Commit message: {message}");
            }
            return ValueTask.FromResult(0);
        }
    },
    // Default action if no command is specified
    (ctx, _) =>
    {
        ctx.Out.WriteLine($"Hello {name}! You are {age} years old.");
        if (keyValues.Count > 0)
        {
            foreach (var keyValue in keyValues)
            {
                ctx.Out.WriteLine($"Define: {keyValue.Item1} => {keyValue.Item2}");
            }
        }

        return ValueTask.FromResult(0);
    }
};

await commandApp.RunAsync(args);

Running myexe --help will output:

Usage: myexe [Options] COMMAND

  -D[=name:value]            Defines a name and optional value
  -n, --name=NAME            Your NAME
  -a, --age=AGE              Your AGE
  -h, -?, --help             Show this message and exit

Available commands:
  commit

Running myexe --name John -a50 will output:

Hello John! You are 50 years old.

Running myexe --name John -a50 -DHello -DWorld=121 will output:

Hello John! You are 50 years old.
Define: Hello =>
Define: World => 121

Running myexe commit --help will output:

Usage: myexe commit [Options]

  -m, --message=MESSAGE      Add a MESSAGE to this commit
  -h, -?, --help             Show this message and exit

Running myexe --name John -a50 commit --message "Hello!" --message "World!" will output:

Committing with name=John, age=50
Commit message: Hello!
Commit message: World!

📃 User Guide

For more details on how to use XenoAtom.CommandLine, please visit the user guide.

🏗️ Build

You need to install the .NET 8 SDK. Then from the root folder:

$ dotnet build src -c Release

🪪 License

This software is released under the BSD-2-Clause license.

The license also integrate the original MIT license from Mono.Options.

🤗 Author

Alexandre Mutel aka xoofx.