hederson / Cli.NET

πŸ–₯ Easy-to-use library for creating command line tools in C#

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

πŸ–₯ Cli.NET

CLI.NET is a library for creating command line interfaces, command listeners and scripting languages quickly.

Supports .NET 6+ | Version 2.1.0

Usage:

Cli.NET package can be installed using the command:

PM > Install-Package Cli.NET -Version 2.1.0

Example

using Cli.NET.Actions;
using Cli.NET.Tools;

var container = new CommandContainer();

container.Register(new()
{
    { "exit", new ExitCommand() },
    { "echo", new EchoCommand() },
    { "sum", new SumCommand() },
    { "clear", new ClearCommand() },
    { "cls", new ClearCommand() }
});

container.WaitForNextCommand();

Creating, registering and using a command

A command can be created by just implementing the interface "ICommand" from Cli.NET.Abstractions, you can implement any logic inside Execute() and extend the class functions. Example:

using Cli.NET.Abstractions.Actions;

namespace Cli.NET.Actions
{
    /// <summary>
    /// Default example "echo" command to display data in the console.
    /// </summary>
    public class EchoCommand : IConsoleCommand
    {
        public void Execute(string[] arguments) => Console.WriteLine(string.Join(" ", arguments));
    }
}

To register a command, we will need a CommandContainer. Example:

using Cli.NET.Actions;
using Cli.NET.Tools;

var container = new CommandContainer();

container.Register("echo", new EchoCommand());

container.WaitForNextCommand();

Now, the "echo" command can be used in the console application:

Initializing the command listener

To read commands, Cli.NET needs a method called WaitForNextCommand(), that method can receive a boolean telling if the command flow will be infinite or if that is a unique command.

container.WaitForNextCommand(true); //or
container.WaitForNextCommand(); //Will make an infinity command listener
container.WaitForNextCommand(false); //Will only read the first typed input or command

Managing outputs/exceptions

An easy way to manage command outputs and exceptions and sharing the data between all the application is using an OutputProvider.

Example:

Program.cs

using Cli.NET.Actions;
using Cli.NET.Tools;

var container = new CommandContainer();
var outputProvider = new OutputProvider();

container.Register("log", new LogCommand(outputProvider));
container.CallCommandByName("log", "Test output");

LogCommand.cs

using Cli.NET.Abstractions.Actions;

namespace Cli.NET.Actions
{
    public class LogCommand : IConsoleCommand
    {
        private readonly OutputProvider _provider;

        public LogCommand(OutputProvider provider) 
        {
            _provider = provider;
        }

        public void Execute(string[] arguments) 
        {
            _provider.AddLog(string.Join("", arguments), OutputType.Message);
            Console.WriteLine(_provider.GetOutput().LastOrDefault());
        }
    }
}

Cancelling the loop flow

You can cancel a loop flow passing the container by reference to a command. Example:

CancelLoopCommand.cs

using Cli.NET.Abstractions.Actions;

namespace Cli.NET.Actions
{
    public class CancelLoopCommand : IConsoleCommand
    {
        private readonly CommandContainer _container;

        public CancelLoopCommand(CommandContainer container) 
        {
            _container = container;
        }

        public void Execute(string[] arguments) 
        {
            _container.CancelLoop();
        }
    }
}

Program.cs

using Cli.NET.Actions;
using Cli.NET.Tools;

var container = new CommandContainer();

container.Register("cancel-loop", new CancelLoopCommand(container));

container.WaitForNextCommand(); //If you call "cancel-loop", the loop will be cancelled

Customizing the console appearance

You can create a customized CommandContainer by changing the constructor parameter values, the default configuration (empty constructor) is:

public CommandContainer(
    string indicator = "Command > ", 
    string notFoundMessage = "Command {x} not found.", 
    ConsoleColor notFoundColor = ConsoleColor.DarkRed,
    ConsoleColor indicatorColor = ConsoleColor.White)
{
    _commands = new();
    _indicator = indicator;
    _notFoundMessage = notFoundMessage;
    _notFoundColor = notFoundColor;
    _indicatorColor = indicatorColor;
}

List of customizable parameters:

Name Description Type
indicator The command indicator, will be placed to show the current location to the user string
notFoundMessage A message that will be displayed when the insert command does not exist string
notFoundColor A color to the notFoundMessage ConsoleColor
indicatorColor A color to the indicator ConsoleColor

You can use the methods SetNotFoundMessage() and SetIndicator() to customize the container in any moment of the application execution, example:

container.SetNotFoundMessage("Oops! Command not found.", ConsoleColor.Red);
container.SetIndicator("Insert command here >", ConsoleColor.Yellow);

Cli.NET CLNConsole class tools (only console applications)

There are some built-in console application tools in Cli.NET.Tools.CLNConsole class, check the list below:

Method Parameters Description
WriteLine message: string Display a new line with a message in the console
WriteLine message: string
color: string
Show a new line with a message in the console with a color (string)
WriteLine message: string
color: int
Show a new line with a message in the console with a color (int)
WriteLine message: string
color: ConsoleColor
Show a new line with a message in the console with a ConsoleColor
- - -
Write message: string Show a message in the current console location
Write message: string
color: string
Show a message in the current console location with a color (string)
Write message: string
color: int
Show a message in the current console location with a color (int)
Write message: string
color: ConsoleColor
Show a message in the current console location with a ConsoleColor
- - -
ReadText Reads the next text input followed by "Enter" command
ReadText minLength: uint
maxLength: uint
Reads the next text input with a Min/Max length
- - -
DataQuestion message: string Displays a text to the user and waits for a response
DataQuestion message: string
color: string
minLength: string
maxLength: string
Displays a text and waits for a response with a Min/Max length and color
DataQuestion message: string
color: int
minLength: string
maxLength: string
Displays a text and waits for a response with a Min/Max length and color
DataQuestion message: string
color: ConsoleColor
minLength: string
maxLength: string
Displays a text and waits for a response with a Min/Max length and color

Calling the environment commands

Sometimes we need to pass parameters before the application execution, to execute them the ExecuteEnvironmentCommand() method can be used, example:

container.ExecuteEnvironmentCommand();

Calling commands in the application execution

To call registered commands programatically during the application execution you can use the method CallCommandByName, passing one unique string argument or a string array of arguments, example:

container.CallCommandByName("echo", "argument one");
container.CallCommandByName("echo", new string[] { "argument one", "argument two" });

Predefined built-in commands

In Cli.NET.Actions, there are some predefined built-in example commands that can be used for any purpose.

Name Constructor Description
echo EchoCommand() Display a text in the screen
clear ClearCommand() Clear the console screen and displays a new text - if provided
exit ExitCommand() Finish the current process
sum SumCommand() Performs the sum of all numerical values offered

Finishing...

You can support that library/repository by leaving a contribution, star or sharing in communities. Thanks for the attention. You can also create issues or give a feedback in my Twitter.

About

πŸ–₯ Easy-to-use library for creating command line tools in C#

License:MIT License


Languages

Language:C# 100.0%