Epsitec.Bcx.CommandLine 6.9.2.2623

Bcx.CommandLine

A powerful command-line parsing library for .NET Standard 2.0, based on NDesk.Options with extended functionality.

Overview

Bcx.CommandLine provides extensions to the Base Class Library (hence the name Bcx) for parsing command-line arguments. It offers a flexible, intuitive API for defining and processing command-line options with support for:

• Short and long option names (e.g., -v, --verbose)
• Required and optional values
• Type conversion using TypeConverter
• Option bundling (e.g., -abc instead of -a -b -c)
• Boolean options with explicit enable/disable (-a+, -a-)
• Help text generation
• Verb-based subcommands

Installation

This library targets .NET Standard 2.0 and can be used in .NET Core, .NET Framework 4.6.1+, and .NET 5+.

dotnet add package Epsitec.Bcx.CommandLine

Core Components

OptionSet

The main class for defining and parsing command-line options.

using NDesk.Options;

var verbose = 0;
var name = string.Empty;
var help = false;

var options = new OptionSet
{
    { "v|verbose", "Increase verbosity level", v => { if (v != null) verbose++; } },
    { "n|name=", "The {NAME} of the person", v => name = v },
    { "h|?|help", "Show this message and exit", v => help = v != null }
};

List<string> extra = options.Parse(args);

Option Format

Options are defined using a format string with the following syntax:

prototype[separator]

Prototype parts:

• name - The option name (without leading - or --)
• | - Separates aliases (e.g., h|help|?)
• = - Indicates a required value
• : - Indicates an optional value
• No suffix - Boolean option (no value)

Examples:

• "v" - Boolean flag -v
• "n|name=" - Required value: -n NAME or --name=NAME
• "o|output:" - Optional value: -o[FILE] or --output[=FILE]
• "D|define={:}" - Key-value pairs: -D:KEY:VALUE or -D=KEY=VALUE

VerbOptionSet

Extends OptionSet to support verb-based subcommands with conditional option parsing.

using NDesk.Options;

var verbArgs = new List<string>();

var rootOptions = new VerbOptionSet
{
    { "s|stop", "Stop server", c => verbArgs.Count == 0, v => Console.WriteLine("Stop") },
    { "h|help", "Show help", c => verbArgs.Count == 0, v => ShowHelp() },
    { "<>", v => verbArgs.Add(v) }  // Capture unprocessed arguments
};

var sendOptions = new OptionSet
{
    { "s|store:", "Specify store path", v => Console.WriteLine($"Store: {v}") },
    { "h|help", "Show help", v => ShowHelp() }
};

// Parse root options first
var extra = rootOptions.Parse(args);

// Parse verb-specific options
if (verbArgs.Count > 0)
{
    var verb = verbArgs[0];
    var verbOptions = GetVerbOptions(verb); // Get appropriate OptionSet
    extra = verbOptions.Parse(verbArgs.Skip(1));
}

OptionSetExtensions

Provides convenience methods for working with OptionSet:

using NDesk.Options;

var options = new OptionSet();

// Parse with params array
List<string> extra = options.ParseEx("-v", "--name=John");

// Add multiple options at once
options.AddRange(additionalOptions);

// Get formatted help text
string helpText = options.GetDescription();
Console.WriteLine(helpText);

Features

Type Conversion

Automatically converts string values to typed parameters using TypeConverter:

int port = 8080;
var options = new OptionSet
{
    { "p|port=", "Server {PORT} number", (int v) => port = v }
};

options.Parse(new[] { "-p", "3000" }); // port = 3000

Option Bundling

Short options can be bundled together:

var options = new OptionSet
{
    { "a", v => Console.WriteLine("Option A") },
    { "b", v => Console.WriteLine("Option B") },
    { "c", v => Console.WriteLine("Option C") }
};

options.Parse(new[] { "-abc" }); // Equivalent to: -a -b -c

Boolean Options

Boolean options support explicit enable/disable:

var options = new OptionSet
{
    { "verbose", v => Console.WriteLine($"Verbose: {v != null}") }
};

options.Parse(new[] { "-verbose" });   // Verbose: True
options.Parse(new[] { "-verbose+" });  // Verbose: True
options.Parse(new[] { "-verbose-" });  // Verbose: False

Help Text Generation

Automatically format and display help text:

var options = new OptionSet
{
    { "v|verbose", "Increase verbosity level", v => { } },
    { "n|name=", "The {NAME} of the person", v => { } },
    { "o|output:", "Output to {FILE} (optional)", v => { } }
};

options.WriteOptionDescriptions(Console.Out);

Output:

  -v, --verbose              Increase verbosity level
  -n, --name=NAME           The NAME of the person
  -o, --output[=FILE]       Output to FILE (optional)

Multiple Values

Options can accept multiple values with custom separators:

var options = new OptionSet
{
    { "D|define={:}", "Define {KEY}:{VALUE} pair", (k, v) => 
        Console.WriteLine($"Key: {k}, Value: {v}") }
};

options.Parse(new[] { "-D:MyKey:MyValue" });
// Output: Key: MyKey, Value: MyValue

Default Option Handler

Capture unprocessed arguments with the <> special option:

var files = new List<string>();
var options = new OptionSet
{
    { "v|verbose", v => { } },
    { "<>", v => files.Add(v) }  // Capture remaining arguments
};

options.Parse(new[] { "-v", "file1.txt", "file2.txt" });
// files contains: ["file1.txt", "file2.txt"]

Advanced Usage

Exit After Action

Force the application to exit after processing an option:

var options = new OptionSet
{
    { "version", "Show version and exit", 
        v => Console.WriteLine("Version 1.0.0"), 
        exitAfterAction: true }
};

options.Parse(args); // Application exits after showing version

Custom Message Localization

Provide custom message localization:

var localizer = new Converter<string, string>(msg => 
{
    // Your localization logic
    return TranslateMessage(msg);
});

var options = new OptionSet(localizer)
{
    // ... options
};

Verb-Based Commands

Implement git-style subcommands:

var verbArgs = new List<string>();
var rootOptions = new VerbOptionSet
{
    { "h|help", "Show help", c => verbArgs.Count == 0, ShowHelp },
    { "<>", v => verbArgs.Add(v) }
};

var commands = new Dictionary<string, OptionSet>
{
    { "send", new OptionSet { /* send options */ } },
    { "status", new OptionSet { /* status options */ } }
};

rootOptions.Parse(args);

if (verbArgs.Count > 0)
{
    var command = verbArgs[0];
    if (commands.TryGetValue(command, out var commandOptions))
    {
        commandOptions.Parse(verbArgs.Skip(1));
    }
}

Error Handling

The library throws OptionException for parsing errors:

try
{
    var extra = options.Parse(args);
}
catch (OptionException e)
{
    Console.WriteLine($"Error: {e.Message}");
    Console.WriteLine($"Option: {e.OptionName}");
    options.WriteOptionDescriptions(Console.Out);
}

Credits

This library is based on NDesk.Options by Jonathan Pryor, with extensions and enhancements by EPSITEC SA.

Original NDesk.Options:

• Author: Jonathan Pryor
• Copyright (C) 2008 Novell (http://www.novell.com)
• License: MIT

Extensions:

• Copyright © 2013-2025, EPSITEC SA, CH-1400 Yverdon-les-Bains, Switzerland
• Author: Roger VUISTINER
• License: MIT

License

MIT License - See the package license for details.