Clap.Net 0.1.28-beta

Clap.Net

Clap.Net is an attempt to port clap-rs over to .NET, with almost feature-parity, to make source generated parsers for applications.

Installation

dotnet add package Clap.Net

Notes to the user

If you are having issues with generation and want to see what's going on, sometimes it's not enough to rely on the in-editor generated file, add this to your project to see the MSBuild-generated files.

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
    <CompilerGeneratedFilesOutputPath>bin/Generated</CompilerGeneratedFilesOutputPath>
</PropertyGroup>

Usage

Define your command-line interface using classes and properties. Use attributes to specify the command-line options and arguments.

using Clap.Net;

namespace Clap.Examples;

[Command(Name = "image-converter", Summary = "My app is pretty cool!")]
public partial class ImageConverter
{
    [Arg(Description = "The path of the image to convert")]
    public required string Path { get; init; }

    [Arg(Description = "The destination path of the converted image (default: <file-name>.[new-ext])", Last = true)]
    public string? DestinationPath { get; init; }

    [Arg(ShortName = 'e', LongName = "extension")]
    public string? Extension { get; init; }

    [Arg(ShortName = 'v', LongName= "verbose")]
    public bool Verbose { get; set; }

    [Command(SubCommand = true)]
    public ImageConverterCommands? Command { get; init; }
}

[SubCommand]
public partial class ImageConverterCommands 
{
    [Command]
    public partial class History : ImageConverterCommands;

    [Command]
    public partial class Publish : ImageConverterCommands 
    {
        [Arg(Description = "The url to publish the new image to")]
        public required string[] UploadUrl { get; init; }
    }
}

Parse the command-line arguments using the Parser class.

using System;
using Clap.Examples;

var app = ImageConverter.Parse(args);

switch (app.Command) 
{
    case ImageConverterCommands.History history:
        // do something with history
        break;

    case ImageConverterCommands.Publish publish:
        // do something with publish
        break;

    default:
        // do something with app
        break;
}

Run the application with command-line arguments.

dotnet run -- -v "~/Downloads/tree.png" "~/Downloads/tree.jpg" 
dotnet run -- "~/Downloads/tree.png" -e "jpg" publish "https://yourdomain.com/upload"

Features

• Strongly-typed: Define your command-line interface using classes and properties.
• Subcommands: Define subcommands using nested classes.
• Options and Arguments: Define options and arguments using attributes.
• Automatic help generation: Generate help messages automatically.

Core Feature Parity

• [Command] support
  • Define the root command type
  • Support for Name, Description, Version
• [Subcommand] support
  • Nesting subcommands as classes
  • Subcommand help messages
• [Option] (named arguments)
  • Short and long flags (e.g., -v, --verbose)
  • Aliases for options
  • Environment variable fallback
  • Default values (handled by language)
  • Required vs optional
  • Action (Set, Append, Count, etc.)
• [Switch] (bool flags)
  • Basic presence/absence flag
  • Default to false unless specified
  • Negatable flags (--no-flag)
• [Positional] arguments
  • Order-based argument mapping
  • Optional vs Required
  • Default values (handled by language)
  • Multiple values (e.g., list)
  • Custom parsers
  • TryParse support for complex types
  • Validation attributes
• Help and version handling
  • Automatic --help
  • Automatic --version
  • Custom help text

Contributing

There is still loads to do, pull-requests are welcome

License

MIT