Typin

See TypinExamples website for interective examples.

Typin is a simple to use, ASP.NET Core inspired framework for building both interactive command line applications and command line tools (direct mode). However, it is not limited to direct and interactive modes, because you can create your own modes.

Etymology: Typin is made out of "Typ" for "Type" and "in" for "interactively". It's pronounced as "Ty pin".

Typin is not just a parser but a complete application framework. Its main goal is to provide an enjoyable, similar to ASP.NET Core, development experience when building command line applications. Its primary goal is to completely take over the user input layer, letting you forget about the infrastructure and instead focus on writing your application.

Typin roots in CliFx

Typin is build based on the source code of CliFx, but it wants to be a ASP.NET Core for CLI like Cocona but faster. It has many additional features compared to CliFx:

• Interactive mode with auto-completion, parameter escaping with ", and support for user-defined shortcuts,
• Middleware pipeline,
• Custom directives,
• IOptionFallbackProvider for custom fallback providers instead of only environment variable fallback,
• Build-in DI support with Microsoft.Extensions.DependencyInjection that is used accross entire framework,
• Build-in options support with Microsoft.Extensions.Options,
• Ability to modify exception handling messages,
• DI injectable ICliContext with lots of useful data,
• Manual property in CommandAttribute that can be used to provide a long, extended description of a commmand,
• Custom help writer.
• Custom modes support and application lifetime.
• Startup message color personalization through a callback method.
• Console IO wrapper classes (StandardStreamReader and StandardStreamWriter) and IO interfaces.
• Logging with Microsoft.Extensions.Logging.
• Optional option names by providing a kebab case name.
• Better char parsing: support for the following escape sequences: '\0', '\a', '\b', '\f', '\n', '\r', '\t', '\v', '\\', and Unicode escape e.g. \u006A).

Overall, Typin is a framework that is much more flexible and rich with both features and metadata about defined commands etc.

See CHANGELOG.md for a complete list of changes.

Features

• Complete application framework, not just an argument parser
• Requires minimal amount of code to get started
• Configuration via attributes
• Handles conversions to various types, including custom types
• Supports multi-level command hierarchies
• Supports interactive mode
• Intuitive auto-completion (Tab / Shift + Tab) in interactive mode.
• Intuitive command history (Up and Down arrows) in interactive mode, accessible also from user code.
• Exposes raw input, output, error streams to handle binary data
• Allows graceful command cancellation
• Prints errors and routes exit codes on exceptions
• Provides comprehensive and colorful auto-generated help text
• Highly testable and easy to debug
• Comes with built-in analyzers to help catch common mistakes
• Targets .NET Standard 2.0, .NET Standard 2.1. .NET 5.0
• Uses Microsoft.Extensions.DependencyInjection. Microsoft.Extensions.Logging.Debug and Microsoft.Extensions.Options but no other non essential dependencies

Installing Typin

You should install Typin with NuGet:

Install-Package Typin

Or via the .NET Core command line interface:

dotnet add package Typin

Both commands will download and install Typin with all required dependencies.

Typin.Core

If you need only API interfaces, you can install TypinCore with NuGet.

Install-Package Typin.Core

Or via the .NET Core command line interface:

dotnet add package Typin.Core

Both commands will download and install Typin.Core with all required dependencies.

Getting started and Documentation

public static class Program
{
    public static async Task<int> Main() =>
        await new CliApplicationBuilder()
            .AddCommandsFromThisAssembly()
            .Build()
            .RunAsync();
}

[Command]
public class HelloWorldCommand : ICommand
{
    public async ValueTask ExecuteAsync(IConsole console)
    {
        await console.Output.WriteLineAsync("Hello world!");
    }
}

See wiki for detailed instructions and documentation.

Screenshots

Benchmarks

Here's how Typin's execution overhead compares to that of other libraries (single command comparison) and with increasing number of commands.

Typin 3.0

BenchmarkDotNet=v0.12.0, OS=Windows 10.0.19042
Intel Core i7-4790 CPU 3.60GHz (Haswell), 1 CPU, 8 logical and 4 physical cores
.NET Core SDK=5.0.103
  [Host]     : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT
  DefaultJob : .NET Core 3.1.12 (CoreCLR 4.700.21.6504, CoreFX 4.700.21.6905), X64 RyuJIT

Typin 3.x oraz 4.0 will focus on optimizations, further API improvements, and usage of source code generators.

Typin <= 2.1.1

BenchmarkDotNet=v0.12.0, OS=Windows 10.0.19041
Intel Core i7-4790 CPU 3.60GHz (Haswell), 1 CPU, 8 logical and 4 physical cores
.NET Core SDK=3.1.402
  [Host]     : .NET Core 3.1.8 (CoreCLR 4.700.20.41105, CoreFX 4.700.20.41903), X64 RyuJIT
  DefaultJob : .NET Core 3.1.8 (CoreCLR 4.700.20.41105, CoreFX 4.700.20.41903), X64 RyuJIT

Legends:

• Mean : Arithmetic mean of all measurements
• Error : Half of 99.9% confidence interval
• StdDev : Standard deviation of all measurements
• Ratio : Mean of the ratio distribution ([Current]/[Baseline])
• RatioSD : Standard deviation of the ratio distribution ([Current]/[Baseline])
• Rank : Relative position of current benchmark mean among all benchmarks (Arabic style)
• 1 us : 1 Microsecond (0.000001 sec)