Remove the ability to specify command and option name prefixes

[dbuenzli]

Background

From the onset cmdliner had the ability to let user specify prefixes of command and option names as long as they were not ambiguous.

While this was perceived to be nice to users, especially in light of the lack of auto-completion support (#1). It makes tools and user experience unstable with respect to command line evolution: former user established shortcuts or invocation in scripts may be broken by future additions of options and commands. This is undesirable.

As we are in the process of solving auto-completion for 2.0 by ingesting the work of #187, benefits thwart the drawbacks and arguments to keep the feature become rather weak.

Quite a few options to kill the feature were considered¹. Notably around opt-in, opt-out and warnings. Eventually it was decided to settle on the action plan below. It should be noted that this affects both cmdliner users and users of cmdliner based tools.

Action plan

1. In cmdliner 2.0 the ability to specify command and option names by their prefix is removed by default. Except for being advertised in the release notes, this will be a silent change for cmdliner user and users of cmdliner based tools.

2. In order to quickly salvage scripts that may be relying on the old behaviour, it can be restored by setting the environment variable CMDLINER_LEGACY_PREFIXES=true. This behaviour will be removed cmdliner 3.0 (which is likely years away).

3. Cmdliner users distributing command line tools to end-users should warn them about the change when they start using 2.0 for releasing their software. Here is a CHANGES line you can use in your release notes:

   Command line interface: the tool no longer accept unambiguous command and option names prefixes. If this breaks some of your scripts you can quickly salvage them by setting CMDLINER_LEGACY_PREFIXES=true in the environment. You should however correct them: this will be removed in the future.

   Note that if you distribute your software via opam and have open bounds this may happen unbeknownst to you. Constrain your software in the opam repository before 2.0 is released if you think it is a problem.

Footnotes

1. Yet another error was to not forsee this change and start warning on ambiguous changes a couple of releases ago. Oh well… ↩

[kit-ty-kate]

Thanks for the heads up. This change is likely to be a huge problem for opam itself. Many people use this behaviour (e.g. opam pin --dev is in fact opam pin --dev-repo or opam repo as a shortcut for opam repository). Telling everyone to use the environment variable in case they need to copy a command that is in fact shortened doesn't seem practical for us.

I understand the reasoning for not allowing prefixes by default but is there any chance there could be a more static opt-in option? Since we have our own auto-completion script, disabling the builtin auto-completion would be a totally fine trade-off.

[dbuenzli]

Since the actual shortcuts seem to be quite established, you can simply add them as concrete definitions no ?

[kit-ty-kate]

Those were only examples. There are too many possible combination that opam users could use and making an exhaustive list of them is virtually impossible. Our naming process for options and commands did take into account the prefixes and tried to give nice names that would shorten nicely. We'd rather avoid such drastic CLI change before an eventual opam 3.0.

Is there any chance some sort of static ?enable_prefixes:bool option or even global could be added to the proposal?

[zapashcanon]

former user established shortcuts or invocation in scripts may be broken by future additions of options and commands.

Was the option of adding some kind of explicit priority to the various commands and option names considered? The one with the highest priority would be chosen amongst all the commands sharing the prefix used in the shortcuts.

[dbuenzli]

Was the option of adding some kind of explicit priority to the various commands and option names considered? The one with the highest priority would be chosen amongst all the commands sharing the prefix used in the shortcuts.

I'm not sure I see how how this solves any problem, if I a user used --dev in a script instead of --dev-repo and a subsequent version of your cli introduces the --dev option to mean something else, all these users are busted, no priority is going to solve that (and the last thing I would like is to inflict some kind of priority system onto cli users).

Those were only examples. There are too many possible combination that opam users could use and making an exhaustive list of them is virtually impossible.

Well of course they could use any prefix, this is true for any other tool. Let's be pragmatic there's likely only a few shortcuts that are in use in scripts and/or mentioned in the docs. Already looking at the commands only I see only repo and conf.

Is there any chance some sort of static ?enable_prefixes:bool option or even global could be added to the proposal?

I'd rather not provide a choice here. That being said you have your own vendored version of cmdliner. If you are too afraid to make the switch it will likely be easy for you to patch the lookup for CMDLINER_LEGACY_PREFIXES=true with a hardcoded true to restore the previous behaviour.

But still I think you'd be better off making an analysis of your options and simply add aliases. Since apparently your design process did "design names that would shorten nicely" it should be easy for you to find them.

[zapashcanon]

I'm not sure I see how how this solves any problem, if I a user used --dev in a script instead of --dev-repo and a subsequent version of your cli introduces the --dev option to mean something else, all these users are busted, no priority is going to solve that (and the last thing I would like is to inflict some kind of priority system onto cli users).

I was thinking about the case where a command owi concolic exists, and users have owi conc as a shortcut. Then, you add a new command owi concrete.

Your code was:

  Cmd.group info ~default
    [ Cmd.v symbolic_info symbolic_cmd 0
    ; Cmd.v concolic_info concolic_cmd 1
    ]

And it becomes:

  Cmd.group info ~default
    [ Cmd.v symbolic_info symbolic_cmd 0
    ; Cmd.v concolic_info concolic_cmd 1
    ; Cmd.v concrete_info concrete_cmd 2
    ]

That is, each time you add a new command, you give it a bigger number to denote the fact it was added after and should have a lower priority. (Nothing is imposed on the users, only on the programmer). So here owi conc should indeed be owi concolic, but owi concr would be owi concrete.

Indeed, this does not help if you add a new command that is a prefix of an existing one. This is asking for troubles and I'd like to get an error at runtime if I did something like this (at program initialization).

Regarding the burden it adds for developers, I think this is quite low for commands. For options names, I agree it may not be easy to offer a nice API, I havn't tried to find one. But for commands, I believe what I proposed above is quite straightforward.

[dbuenzli]

Regarding the burden it adds for developers, I think this is quite low for commands. For options names, I agree it may not be easy to offer a nice API, I havn't tried to find one. But for commands, I believe what I proposed above is quite straightforward.

I don't care about developers. The system you propose is hard to properly document in the manpages, complex to understand, and hard to remember and operate for cli end-users. Don't make me think.

[kit-ty-kate]

I'd rather not provide a choice here. That being said you have your own vendored version of cmdliner. If you are too afraid to make the switch it will likely be easy for you to patch the lookup for CMDLINER_LEGACY_PREFIXES=true with a hardcoded true to restore the previous behaviour.

We're not "vendoring" any of our dependencies. The only "vendoring" is just a simple distribution or download of the upstream tarballs if requested and the dependency is not available on your system already.

Forking cmdliner is obviously an option but we'd rather use upstream if possible.