Sagittarius 1.0.2

Suggested Alternatives

Sharpify.CommandLineInterface

Additional Details

Sagittarius was deprecated, it was reworked and further optimized in Sharpify.CommandLineInterface, the new library will provide a more complete entire framework for creating clis, better performing and easier to use apis and more. To provide all the features the design of the usage is very different, so migrating large packages might not be very easy but still highly encouraged.

dotnet add package Sagittarius --version 1.0.2                
NuGet\Install-Package Sagittarius -Version 1.0.2                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Sagittarius" Version="1.0.2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Sagittarius --version 1.0.2                
#r "nuget: Sagittarius, 1.0.2"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Sagittarius as a Cake Addin
#addin nuget:?package=Sagittarius&version=1.0.2

// Install Sagittarius as a Cake Tool
#tool nuget:?package=Sagittarius&version=1.0.2                

Sagittarius ðŸđ

Sagittarius is a package created with the purpose of making it easier to parse command line arguments without using reflection. While there are many other packages that parse arguments, I have yet to see an easy to use one that doesn't use reflection. This feature is crucial when you want to be able to compile your cli's to native code, as we are now able with .NET 7.

Features

  • 🚀 High performance, Low memory usage and allocation
  • ðŸŠķ Very lightweight (No external dependencies)
  • 🔌 Plug and play (most of the time you don't need to change your code much)
  • ✂ Trimming friendly (no reflection uses at all)
  • Supports all platforms (Windows, Linux, Mac)

⮇ Installation

  • Nuget alternate text is missing from this package README image

Usage

Parser.Split() is a static method that allows splitting all components of the arguments into a collection of string. This is different from string.Split() as it is both more efficient, and respects quotes which allows you to put everything in between quotes in a single argument.

Parser.ParseArguments() is a static method that allows parsing the arguments into an Arguments object that is a wrapper over a Dictionary<string, string> that allows very convenient access to the arguments.

Features of the Arguments object

  • Access to named arguments by name
  • Access to positional arguments by index as int e.g: "0" for the first positional argument
  • Conversion of arguments to int, double or decimal with validation.
  • Validation of any value of an argument with custom Func<string, bool> validationFunc
  • Access to underlying Dictionary<string, string> with Arguments.GetInnerDictionary()
  • An option to lower the index of all positional arguments by 1 with Arguments.ForwardPositionalArguments which means "1" will now become "0" and what was "0" will be removed, this is very useful for commands that have sub-commands, and you want each sub-command to be implemented purely.
  • A validation method does not do anything if the argument is valid, but throws an exception if it is not.
  • A conversion or retrieval method such as Arguments.GetValue(key) or Arguments.GetValueAsInteger(key) have an optional parameter named throwIfUnable which is set to false by default. when it is set to false if any error arises, the value returned will be null. but if set to true, an exception will be thrown if any error arises, but if the value is guaranteed to be not null.

Usage tips and tricks

  • If you want to a boolean arguments, as it is argument only but without value, such as command --verbose, you don't need to retrieve the value rather just use Arguments.Validate("verbose") this will throw an exception if the argument is not present.
  • If you want something that is optional and has a default value, you can use the Arguments.GetValue(key) without the throwIfUnable parameter to get the value only if present and valid, otherwise a null. Which means you can do something like this: var val = Arguments.GetValue("key") ?? "default";. Same goes for all conversion variants of GetValue like GetValueAsInteger etc.
  • If you have required arguments, make sure you put at least the parsing or retrieving method in a try catch block, and handle the exception.
  • If you get your args from the main method such like this: Main(string[] args) you can pass the args parameter directly to Parser.ParseArguments(args). But make sure it is not empty. The result of Parser.ParseArguments(args) can be nullable and that is only if the arguments that were passed are empty.

Source Code

from the point of public release, the master branch will only contain stable and tested code, so to get the source code you can clone the master branch.

Product Compatible and additional computed target framework versions.
.NET net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net7.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.