CommandLinePlus 2.4.0

CommandLinePlus

This project started because I needed a command line parser that could:

• Have a primary option
• Have a sub option
• Accept command line parameters

This allows a developer to construct a command line in the following form:

myprog.exe Option SubOption -param:value

Supports

• .NET 9.0
• .NET Standard 2.0

How it works

Create a class which descends from BaseCommandLine, specify the Name (primary option) and create methods (each method is a sub option).

Add CmdLineDescription and CmdLineAbbreviation attributes to methods, parameters and processor classes for self-describing help information.

In the following example we can use these command lines:

myprog.exe Plugin
myprog.exe Plugin Add -p:myplugin
myprog.exe Plugin Remove --p:myplugin
myprog.exe Plugin Disable /p:myplugin
myprog.exe Plugin Enable -p:myplugin

    using CommandLinePlus;

    [CmdLineDescription("Processes plugins for entire application")]
    internal class PluginProcessor : BaseCommandLine, IDisposable
    {
        public override string Name => "Plugin";

        public override int SortOrder => 0;

        public override bool IsEnabled => true;

        public override void DisplayHelp()
        {

        }

        public override int Execute(string[] args)
        {
            return 0;
        }

        [CmdLineDescription("Adds a new plugin to the application")]
        public void Add(
            [CmdLineAbbreviation("p", "Name of the plugin to be added")] string pluginName)
        {
            if (IsEnabled)
                Display.WriteLine(VerbosityLevel.Quiet, $"Add plugin {pluginName}");
        }

        [CmdLineDescription("Removes an existing plugin from the application")]
        public void Remove(
            [CmdLineAbbreviation("p", "Name of the plugin to be removed")] string pluginName)
        {
            if (IsEnabled)
                Display.WriteLine(VerbosityLevel.Quiet, $"Remove plugin {pluginName}");
        }

        [CmdLineDescription("Disables a plugin from being used by the application")]
        public void Disable(
            [CmdLineAbbreviation("p", "Name of the plugin to be disabled")] string pluginName)
        {
            if (IsEnabled)
                Display.WriteLine(VerbosityLevel.Quiet, $"Disable plugin {pluginName}");
        }

        [CmdLineDescription("Enables a plugin within the application")]
        public void Enable(
            [CmdLineAbbreviation("p", "Name of the plugin to be enabled")] string pluginName)
        {
            if (IsEnabled)
                Display.WriteLine(VerbosityLevel.Quiet, $"Enable plugin {pluginName}");
        }

        [CmdLineDescription("Updates a plugins configuration")]
        public void Update(
            [CmdLineDescription("Name of the plugin to be enabled")] string pluginName)
        {
            if (IsEnabled)
                Display.WriteLine(VerbosityLevel.Quiet, $"Enable plugin {pluginName}");
        }

        [CmdLineDescription("Updates a plugins configuration")]
        public void Update(
            [CmdLineAbbreviation("p", "Name of the plugin to be enabled")] string pluginName,
            [CmdLineDescription("Boolean option A")] bool optionA,
            [CmdLineDescription("Int options B")] int optionB)
        {
            if (IsEnabled)
                Display.WriteLine(VerbosityLevel.Quiet, $"Enable plugin {pluginName}; Option A: {optionA}; Options B: {optionB}");
        }

        [CmdLineHidden]
        public void Dispose()
        {
            throw new NotImplementedException();
        }
    }

Wiring it up

Add a reference to the CommandLinePlus package, create your processors, then bootstrap them from the application entry point. The demo (CmdLineTest) uses C# top-level statements:

using CmdLineTest;

IConsoleProcessorFactory factory = new ConsoleProcessorFactory();

object[] processors = new object[]
{
    new PluginProcessor(),
};

IConsoleProcessor consoleProcessor = factory.Create("MyProg", processors);

switch (consoleProcessor.Run(out int resultCode))
{
    case RunResult.CandidateFound:
        Console.WriteLine("finished");
        break;

    case RunResult.DisplayHelp:
        break;

    default:
        throw new InvalidOperationException("Didn't work");
}

return resultCode;

The demo project makes the CommandLinePlus types available via a global using in its .csproj:

<Using Include="CommandLinePlus" />

If you don't use that, add using CommandLinePlus; to your file instead. The MyProg argument passed to Create is the process name shown in help; replace it with your application's name.

Run returns a RunResult:

Built-in options

• -? (or /?) shows help for all processors, one processor's sub-options, or a sub-option's parameters.
• -v:<level> (or /v:<level>) sets the verbosity level: 0 Quiet, 1 Normal, 2 Diagnostic, 3 Full. The default is 1 (Normal).

Parameters

Sub-option methods receive values from command-line parameters. Parameter names are matched case-insensitively, sub-option method names are matched case-insensitively, and the primary option name is case-sensitive by default.

• bool, int, enum and Guid values are converted automatically.
• Parameters with a default value are optional.
• A method may return void or int; an int result becomes the process exit code.

Available parameter separators

The following characters can be used as parameter separators

• = (equals)
• : (colon)

Available parameter identifiers

The following are used to identify parameter values

• - (single dash)
• -- (double dash)
• / (forward slash)