JSSoft.Terminals 7.0.0-pr.35

Commands

Summary

Parses a string to set a value to a specified property or invoke a specified method.

Like Terminal or Powershell, it provides a REPL environment to provide a command-based development environment.

Requirements

dotnet sdk 8.0.100 or later
c# 12

Clone

git clone https://github.com/s2quake/commands.git

Build - NET 8.0

dotnet build

Other Framework Build

# net7.0
dotnet build -p:TargetFrameworks=net7.0 --framework net7.0

# netcoreapp3.1
dotnet build -p:TargetFrameworks=netcoreapp3.1 --framework netcoreapp3.1

# netstandard2.1
dotnet build -p:TargetFrameworks=netstandard2.1 --framework netstandard2.1

# net481
dotnet build -p:TargetFrameworks=net481 --framework net481

Run Examples

# Run the property settings example project
dotnet run --project JSSoft.Commands.Parse --framework net8.0 -- --help

# Run the method call example project
dotnet run --project JSSoft.Commands.Invoke --framework net8.0 -- --help

# Run the CommandContext Execution example Project
dotnet run --project JSSoft.Commands.Sets --framework net8.0 -- --help

# Run the CommandContext Execution Example Project in the REPL environment
dotnet run --project JSSoft.Commands.Repl --framework net8.0

# Run the CommandContext Execution Example Project with Avalonia UI
dotnet run --project JSSoft.Commands.AppUI --framework net8.0

Parse

This is the most basic way to parse the command. Provides a function to set a value for a specified property.

var settings = new Settings();
var parser = new CommandParser(settings);
parser.Parse(args);

See the JSSoft.Commands.Parse project

Invoke

As an extension of Parse, it provides the ability to call a specified method by parsing the command.

var commands = new Commands();
var invoker = new CommandInvoker(commands);
invoker.Invoke(args);

See the JSSoft.Commands.Invoke project

CommandContext

It provides various functions to manage and process more commands.

var commands = new ICommand[]
{
    new LoginCommand(),
    new LogoutCommand(),
    new ExitCommand()
};
var commandContext = new CommandContext(commands);
commandContext.Execute(args);

or

await commandContext.ExecuteAsync(args);

See the JSSoft.Commands.Sets project

It can be combined with user input such as EditBox, TextBox, InputText to build a console or REPL-like environment.

var commands = new ICommand[]
{
    new LoginCommand(),
    new LogoutCommand(),
    new ExitCommand()
};
var commandContext = new CommandContext(commands);
var terminal = new SystemTerminal(commandContext);
await terminal.StartAsync(CancellationToken.None);

See the JSSoft.Commands.Repl project

Property

Required argument definition

To define the value required for command syntax, define CommandPropertyRequired in the property.

[CommandPropertyRequired]
public string Value1 { get; set; } = string.Empty;

[CommandPropertyRequired]
public int Value2 { get; set; }

"value"   // error! value for Value2 does not exists.
3         // format error!
"value" 3 // Value1 is "value", Value2 is 3

You can set default values ​​like this: If there is no value in the command syntax, it is replaced with the default value.

[CommandPropertyRequired]
public string Value1 { get; set; } = string.Empty;

[CommandPropertyRequired(DefaultValue = 1)]
public int Value2 { get; set; }

"value" 2 // Value1 is "value", Value2 is 2
"value"   // Value1 is "value", Value2 is 1

Explicit required argument definition

An explicit required argument indicates that the command syntax must have a value, but must include a switch statement, such as --value "2".

[CommandPropertyRequired]
public string Value1 { get; set; } = string.Empty;

[CommandPropertyExplicitRequired]
public int Value2 { get; set; }

"value"            // error!
"value" 2          // error!
"value" --value2   // error!
"value" --value2 3 // Value1 is "value", Value2 is 3
--value2 3 "value" // Value1 is "value", Value2 is 3

In order to use the default values ​​of explicit required arguments, the command syntax must include a switch statement such as --value.

[CommandPropertyRequired]
public string Value1 { get; set; } = string.Empty;

[CommandPropertyExplicitRequired(DefaultValue = 1)]
public int Value2 { get; set; }

"value"            // error!
"value" 2          // error!
"value" --value2   // Value1 is "value", Value2 is 1
"value" --value2 3 // Value1 is "value", Value2 is 3
--value2 3 "value" // Value1 is "value", Value2 is 3
--value2 "value"   // error! "value" is not int

Optional argument definition

The optional argument can be set whether or not to use a value using a switch statement.

[CommandProperty]
public string Value { get; set; } = string.Empty;

--value      // error
--value text // value is "text"

To use the default, the command syntax must include a switch statement such as --value.

[CommandProperty(DefaultValue = "1")]
public string Value { get; set; } = string.Empty;

--value      // value is "1"
--value text // value is "text"

A bool type switch statement that does not use a value should be defined as follows.

[CommandPropertySwitch]
public bool Switch { get; set; }

Variable arguments definition

Variable arguments represent the values ​​of the remaining arguments that were not parsed in the command syntax.

The property type of a variable arguments must be an array and must be defined for only one property.

[CommandPropertyArray]
public string[] Values { get; set; } = Array.Empty<string>();

-- value1 value2 value3 "value4"

Method

Method definition

To execute an attribute method through command syntax, you must define a CommandMethod in the method as follows.

Each parameter of the method is automatically defined as a required argument.

[CommandMethod]
public void Save(string message)
{
}

save "message"

If you want to additionally define optional arguments in the method, you can use CommandMethodProperty and add the name of the property defined as CommandProperty.

[CommandMethod]
[CommandMethodProperty("Value")]
public void Save(string message)
{
}

save "comment"
save "comment" --value text

You can use params as below as a variable arguments.

[CommandMethod]
public void Save(string message, params string[] args)
{
}

save "comment"
save "comment" -- "1" "text" "string"

Enable or Disable Method

Define the properties by prefixing "Can" to the method name as shown below.

public bool Can{MethodName} { get; }

example:

public bool CanSave => true;

Static properties and methods

Properties and methods defined as static can be included in the object and used.

static class GlobalSettings
{
    [CommandProperty]
    public static string ID { get; set; } = string.Empty;

    [CommandProperty]
    public static string Password { get; set; }
}

[CommandStaticProperty(typeof(GlobalSettings))]
class Settings
{
}

static class StaticCommand
{
    [CommandMethod]
    [CommandMethodProperty(nameof(Value))]
    public static void List()
    {
    }

    [CommandProperty]
    public static int Value { get; set; }
}

[CommandStaticMethod(typeof(StaticCommand))]
class Commands
{
}

Naming

The property and method names defined as CommandProperty and CommandMethod are changed to kebab-case (spinal-case, Train-Case, Lisp-case).

Property name example

When using a name and a short name

[CommandProperty("custom-value", 'v')]
public string Value { get; set; } = string.Empty;

--custom-value or -v

When using only short names

[CommandProperty('v')]
public string Value { get; set; } = string.Empty;

-v

When using a short name and a default name

[CommandProperty('v', AllowName = true)]
public string Value { get; set; } = string.Empty;

-v or --value

Method name example

You can also set the method name yourself.

[CommandMethod("save")]
public void Save(string message)
{
}

Command

You can define commands in the CommandContext.

class ExitCommand : CommandBase
{
    [CommandPropertyRequired(DefaultValue = 0)]
    public int ExitCode { get; set; }

    protected override void OnExecute()
    {
        Environment.Exit(ExitCode);
    }
}

exit
exit 0

SubCommand

You can define commands that have subcommands in CommandContext.

class UserCommand : CommandMethodBase
{
    [CommandMethod]
    [CommandMethodProperty(nameof(Message))]
    public void Create(string userID)
    {
    }

    [CommandMethod]
    public void Delete(string userID)
    {
    }

    [CommandMethod]
    public void List()
    {
    }

    [CommandProperty]
    public string Message { get; set; }
}

user create "user1"
user create "user1" --message "new user"
user delete "user1"
user list

SubCommand extension

By implementing a partial class, you can add subcommand to the already implemented command.

[PartialCommand]
class UserPartialCommand : CommandMethodBase
{
    public UserPartialCommand()
        : base("user")
    {
    }

    [CommandMethod]
    public void SendMessage(string userID, string message)
    {
    }
}

SubCommand AsyncMethod

You can use asynchronous methods, as shown in the example below. The parameters CancellationToken and IProgress<ProgressInfo> are optional, but should always be the last declaration.

For more information, see the Choosing the overloads to provide topic in the TAP.

The name of an asynchronous method is used without the suffix Async.

class UserCommand : CommandMethodBase
{
    [CommandMethod]
    public Task Invoke1Async()
    {
        return Task.CompletedTask;
    }

    [CommandMethod]
    public Task Invoke2Async(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    [CommandMethod]
    public Task Invoke3Async(IProgress<ProgressInfo> progress)
    {
        return Task.CompletedTask;
    }

    [CommandMethod]
    public Task Invoke4Async(CancellationToken cancellationToken, IProgress<ProgressInfo> progress)
    {
        return Task.CompletedTask;
    }
}

License

Released under the MIT License.

Copyright (c) 2024 Jeesu Choi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.