Documentation about template-strings

[OskarKlintrot]

Is there any documentation about the template for CommandArgumentAttribute etc? The hint just says The argument template. but I have no clue what that means. Does the [] or <> actually mean/do anything? What else can we use? I guess you can figure it out by reading the source code for TemplateTokenizer but a more convenient way would be appreciated :)

[patriksvensson]

@OskarKlintrot Excellent question. I'm a bit behind on documenting Spectre.Console.Cli, but to summarize:

[FOO] indicates an optional value
<FOO> indicates a required value.

public class ConsoleSettings : CommandSettings
{
    [CommandArgument(0, "<MANDATORY>")]
    [Description("Mandatory argument")]
    public string Mandatory { get; set; } = string.Empty;

    [CommandArgument(1, "[OPTIONAL]")]
    [Description("Optional argument")]
    public string? Optional { get; set; }

    [CommandOption("--command-option-flag")]
    [Description("Command option flag.")]
    public bool CommandOptionFlag { get; set; }

    [CommandOption("--command-option-value|-c1|--command-req <REQUIRED_VALUE>")]
    [Description("Command option value (required).")]
    public string? CommandOptionValue { get; set; }

    [CommandOption("--command-option-value-opt|-c2|--command-opt [OPTIONAL_VALUE]")]
    [Description("Command option value (optional).")]
    public FlagValue<string> CommandOptionValueOptional { get; set; }
}

[patriksvensson]

@Goffen Options are, well options. They can't be required per se.
The only thing we can validate is that if you pass an option with a required value, and don't provide one.

[CommandOption("--foo <THE_VALUE>")]
public string Foo { get; set; }

If I run the application with only --foo, that will fail validation.
Validation of settings is done automatically by the framework, so you don't need to call the Validate method yourself.

Custom validation - Overrides

You can provide your own validation code by overriding the Validate method in the command.

public override ValidationResult Validate(
    [NotNull] CommandContext context,
    [NotNull] Settings settings)
{
    //  Custom validation
    if (settings.Foo % 2 != 0)
    {
        return ValidationResult.Error("Number is not even");
    }

    // Return success
    return ValidationResult.Success();
}

Custom validation - Attributes

Or you can implement your own validation attribute and decorate the Option property

[AttributeUsage(AttributeTargets.Property, AllowMultiple = true)]
public sealed class EvenNumberValidatorAttribute : ParameterValidationAttribute
{
    public EvenNumberValidatorAttribute(string errorMessage)
        : base(errorMessage)
    {
    }

    public override ValidationResult Validate(CommandParameterContext context)
    {
        if (context.Value is int integer)
        {
            if (integer % 2 == 0)
            {
                return ValidationResult.Success();
            }

            return ValidationResult.Error($"Number is not even ({context.Parameter.PropertyName}).");
        }

        throw new InvalidOperationException($"Parameter is not a number ({context.Parameter.PropertyName}).");
    }
}

And then in your settings class

[CommandOption("--foo <THE_VALUE>")]
[EvenNumberValidator]
public int Foo { get; set; }

[Goffen]

Aaahhhh! Okey. That's kind of strange behaviour to have it only be required if you supply it ;)

And with CommandArguments you cannot use the -f|--foo notation.

For example the azure commandline client uses the -x|-xxx for required things. I find it very useful because parameters are named, instead if they only used CommandArgument you need to remember the ordering of everything.

For example
az group create --location westeurope --name myResourceGroup

is way better than

az group create westeurope myResourceGroup

[woutervanranst]

@Goffen this is the reason I stayed with System.Commandline... you can have mandatory required arguments there
https://github.com/dotnet/command-line-api/blob/main/docs/Your-first-app-with-System-CommandLine.md

[VictorioBerra]

Just landed here from Google, same exact gripe @patriksvensson, naming arguments is incredibly important. Is there no way we can introduce a required flag on [CommandOption(Required = true)]? If Required is true, the option MUST be provided. Or, allow named arguments.

[FrankRay78]

CommandLine does indeed support required options, as per: https://learn.microsoft.com/en-us/dotnet/standard/commandline/get-started-tutorial

Here's an example from their documentation:

        var searchTermsOption = new Option<string[]>(
            name: "--search-terms",
            description: "Strings to search for when deleting entries.")
            { IsRequired = true, AllowMultipleArgumentsPerToken = true };

I can see the logic behind explicitly named options on the command line, for readability.

@patriksvensson - Do you have thoughts about whether spectre.console should follow suit, or not?