commands/subcommands API is awkward

[SidShetye]

Is your feature request related to a problem? Please describe.

Building a CLI tool that takes has multiple commands (verbs) when processing a given data store.

manage-store add <add params>
manage-store list <list param>
manage-store delete <delete params>

Describe the solution you'd like

I'd like to just define the add, list and delete classes decorated with something like the [Command] (?) attribute. And perhaps a single entrypoint into a library-standardized dispatcher e.g.

public static void Main(string[] args) 
{
    // making up this name but you get the point
    McMaster.Extensions.CommandLineUtils.RouteToCommand(args);
}

Describe alternatives you've considered

The current documentation just feels very awkward. It seems to offload CLI parsing and routing/dispatching back to user written code. Given that the concern is CLI parsing and routing, this should be handled from within the library itself.

On a related note, the documentation is unnecessarily complicated by cramming too many things into a single command/sub-command example.

IMHO, your root level readme.md should cover one quick example for regular CLIs (e.g. wget) and another example for verbs/commands based CLIs (like dotnet <verbs>).

Additional context

Don't really care about the builder API if it matters. Great tool by the way - thanks!

[SidShetye]

Slightly off-topic but still related: I noticed that you've got help-wanted on several issues and that this is your side project. There is another project at https://github.com/commandlineparser/commandline which does the same job (slightly different API surface) but that's stuck on an older .net standard (=lots of dependencies). Have you guys spoken to each other to consider pooling talent and time?

[natemcmaster]

The samples/Subcommands/Program.cs file you pointed to is not a representative sample. I recommend taking a look at these instead and tell me then if you think the API is still awkward.

https://github.com/natemcmaster/CommandLineUtils/blob/master/samples/Subcommands/Inheritance.cs
https://github.com/natemcmaster/CommandLineUtils/blob/master/samples/Subcommands/BuilderApi.cs
https://github.com/natemcmaster/CommandLineUtils/blob/master/samples/Subcommands/NestedTypes.cs

Agree, we should cleanup the samples and docs folder. They've grown organically and separately. Would be good to unify.

[natemcmaster]

Re your side note: I've seen https://github.com/commandlineparser/commandline, but there are no plans to unify with them. I'm hoping at some point to unify this library with System.CommandLine, when/if that lands.

[SidShetye]

@natemcmaster seems like you already have this functionality and it's actually quite simple and well designed. Documentation is definitely misleading/confusing about the minimal 'magic' / assumptions needed to get this working.

Program.cs

using McMaster.Extensions.CommandLineUtils;

namespace DataStore
{
    [Command(ThrowOnUnexpectedArgument = false)]
    [Subcommand("add", typeof(AddCmd))]
    [Subcommand("delete", typeof(DeleteCmd))]
    [HelpOption("--help")]
    class Program
    {
        public static void Main(string[] args)
        { 
            CommandLineApplication.Execute<Program>(args);
        }
    }
}

AddCmd.cs (DeleteCmd is similar)

using McMaster.Extensions.CommandLineUtils;
using System;
using System.ComponentModel.DataAnnotations;

namespace DataStore
{
    [HelpOption("--help")]
    public class AddCmd
    {
        [Required]
        [Option("--addParam1", Description = "1st parameter for add")]
        public string AddParam1 { get; set; }

        [Required]
        [Option("--addParam2", Description = "2nd parameter for add")]
        public MyEnum AddParam2 { get; set; }

        public void OnExecute()
        {
            // do work, AddParam1 and AddParam2 (enum auto-parsed) available here
        }
    }
}

Regarding System.Commandline that would be even better. IMHO as long as 'console application' is a supported flavor, this sort of CLI parsing should be right in the .net standard itself. Imagine having ASP.NET as a supported programming model but leaving Controllers or the router entirely as community effort libraries. So your work is very much appreciated!

[natemcmaster]

Ok, glad you found what you needed. I'll work on cleaning up docs to make it more discoverable. Of course, I'm happy to take contributions, too.

this sort of CLI parsing should be right in the .net standard itself.

There be dragons, my friend. There is a surprisingly contentious history on this matter.

[jerriep]

@natemcmaster

I'm hoping at some point to unify this library with System.CommandLine, when/if that lands.

What is System.CommandLine Nate? Anywhere one can find more info?

[ooo]

👋 Hey @jerriep...

Letting you know, @natemcmaster is currently OOO until Monday, September 24th 2018. ❤️

[natemcmaster]

@jerriep it's project that's been brewing on the .NET team for a while. I helped earlier this year on some of the early versions. I don't think there is a target date yet for making it a real thing. See dotnet/corefxlab#2245 (comment)

[jerriep]

Thanks Nate! I have subscribed to that issue to keep track of the progress.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Please comment if you believe this should remain open, otherwise it will be closed in 7 days.