EasyArguments 1.0.4

<div align="center">

EasyArguments

EasyArguments is a lightweight .NET library that simplifies the process of parsing command-line arguments into strongly-typed objects. It provides attributes to define metadata for arguments and a controller to handle the parsing logic.

</div>

Table of Contents

• EasyArguments
  • Table of Contents
  • Installation
  • Usage
    • Configuring the Controller
    • Defining Arguments
    • Parsing Arguments
    • Handling Errors
  • Full Example
  • Plans for the future
  • Contribution
    • How to Contribute
  • License

Installation

dotnet add package EasyArguments

Usage

Configuring the Controller

Use the ArgumentsControllerAttribute to configure the behavior of the class that defines the arguments. You can specify whether an automatic help argument should be included, and the character used as a separator.

using EasyArguments.Attributes;

[ArgumentsController(AutoHelpArgument = true, Separator = '=')]
public class MyArgs
{
    // Argument definitions
}

Defining Arguments

To define command-line arguments, use the ArgumentAttribute on properties within a class. You can specify short and long names, help messages, and whether the argument is required.

using EasyArguments.Attributes;

[ArgumentsController(AutoHelpArgument = true, Separator = '=')]
public class MyArguments
{
    // A string argument with both short and long forms:
    [Argument("-n", "--name", "Specifies the user name", Required = true)]
    public string? Name { get; set; }

    // A boolean argument that defaults to false unless called:
    [Argument("-v", "--verbose", "Enable verbose output", Required = false)]
    public bool? Verbose { get; set; }

    // A boolean argument that is "inverted," meaning it defaults to true
    // and becomes false if specified:
    [Argument(null, "--no-gui", "Disable the GUI", InvertBoolean = true)]
    public bool GuiEnabled { get; set; }

    // A sub-command (nested class) holding its own arguments:
    [Argument(null, "start", "Start command options")]
    public StartArgs? Start { get; set; }
}

public class StartArgs
{
    // Arguments that only apply when "start" is used:
    [Argument("-u", "--url", "URL of the service")]
    public string? Url { get; set; }

    [Argument("-o", "--output", "Output directory")]
    public string? Output { get; set; }
}

Parsing Arguments

Create an ArgumentsController instance and call the method Parse(string[] args) to parse the command-line arguments into an instance of your class.

using EasyArguments;

static void Main(string[] args)
{
    // Instantiate a controller for your argument class
    var controller = new ArgumentsController<MyArgs>();

    // Parse the given args
    var parsed = controller.Parse(args);

    // Now you can use the strongly-typed properties:
    Console.WriteLine($"Name: {parsed.Name}");
    Console.WriteLine($"Verbose: {parsed.Verbose}");
    Console.WriteLine($"GUI enabled? {parsed.GuiEnabled}");
    
    // If the user included "start" on the CLI, 
    // then parsed.Start != null and has its own parsed values:
    if (parsed.Start != null)
    {
        Console.WriteLine($"Starting with URL={parsed.Start.Url}, output={parsed.Start.Output}");
    }
}

Handling Errors

The ArgumentsController provides a mechanism to handle errors that are thrown as exceptions. You can simply print the error message to the console to get a nice result.

using EasyArguments;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            
            ArgumentsController.RedirectErrorToConsole = true; // Errors will be shown in the console
            MyArguments parsedArgs = ArgumentsController.Parse<MyArguments>(args);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}

OUTPUT:

> -a
Unknown argument '-a'. Please use -h or --help for usage information.

Full Example

Here is a complete example:

using EasyArguments;
using EasyArguments.Attributes;
using System;

[ArgumentsController]
public class MyArgs
{
    [Argument("-n", "--name", "Specifies the user name", Required = true)]
    public string? Name { get; set; }

    [Argument("-v", "--verbose", "Enable verbose output", Required = false)]
    public bool? Verbose { get; set; }

    [Argument(null, "--no-gui", "Disable the GUI", InvertBoolean = true)]
    public bool GuiEnabled { get; set; }

    [Argument(null, "start", "Start command options")]
    public StartArgs? Start { get; set; }
}

public class StartArgs
{
    // Arguments that only apply when "start" is used:
    [Argument("-u", "--url", "URL of the service")]
    public string? Url { get; set; }

    [Argument("-o", "--output", "Output directory")]
    public string? Output { get; set; }
}


class Program
{
    static void Main(string[] args)
    {
        // Instantiate a controller for your argument class
        var controller = new ArgumentsController<MyArgs>();

        // Parse the given args
        var parsed = controller.Parse(args);

        // Now you can use the strongly-typed properties:
        Console.WriteLine($"Name: {parsed.Name}");
        Console.WriteLine($"Verbose: {parsed.Verbose}");
        Console.WriteLine($"GUI enabled? {parsed.GuiEnabled}");
        
        // If the user included "start" on the CLI, 
        // then parsed.Start != null and has its own parsed values:
        if (parsed.Start != null)
        {
            Console.WriteLine($"Starting with URL={parsed.Start.Url}, output={parsed.Start.Output}");
        }
    }
}

Plans for the future

• ExecutorAttribute (Issue #7) I plan to introduce an attribute—tentatively named [ExecutorAttribute] that allows developers to associate a static method call with a particular argument. Once that argument is successfully parsed, the library will invoke the specified method. This can be used to trigger special actions without cluttering the main application logic (e.g., displaying a version number, stopping a service, etc.).

• Improved Parser with Tokenization (Issue #8) In order to support arguments that include spaces or special characters (e.g., --path = "my folder with spaces"), so I plan to implement a more sophisticated tokenization step before parsing. This will allow the library to correctly extract multi-word values, quoted strings, and potentially other advanced CLI patterns.

• Enhanced Help Customization (Issue #9) While EasyArguments already generate automatic usage information, I want to give developers more control over the help text’s layout and content. Plans include support for:

  • Customizing headings, sections, and formatting in the auto-generated help.
  • Displaying examples inline with each argument’s description.
  • Condition-based or role-based help, where certain arguments appear only when relevant.

Contribution

Contributions are welcome! If you have ideas to improve EasyArguments feel free to open an issue.

How to Contribute

• Fork the repository.
• Create a issue or get an existing one
• Create a new branch for your issue.
• Submit a pull request with a detailed explanation of your changes.
• 😃

License

This project is licensed under the GPLv3 License. See the LICENSE file for details.