Non-hidden command alias, similar to long but non-hidden

[tyrone-wu]

Hi 👋 , awesome library! 🐱

Is there a way to specify non-char alias' for a command, similar to long but not hidden?

[pacak]

You want to visible long names for the same command? There's no direct way to implement it - my assumption is for command line interface you want one and only one way for users to specify whatever they want, but you can always make two commands that parse in the same thing with minimal code duplication:

fn command_body() -> OptionParser<Command> {
    // make parser for command body here
}

fn commands() -> impl Parser<Command> {
    let a = command_body().command("alpha");
    let b = command_body().command("beta");
    construct!([a, b])
}

If you use derive macro - command_body would be #[bpaf(options)], commands is a standalone function that you use with external.

I wonder, why do you want that?

[tyrone-wu]

I have some commands (k8s resource types) that have their normal names and a short name, e.g. pod and po, service and svc. If possible, I'd like to also have their normal and short names be displayed together, sorta like this I suppose:

Usage: kctl-rs get [--TODO-get] RESOURCE

Available resources:
    pod, po                        TODO: pod type description
    service, svc                   TODO: service type description
    customresourcedefinition, crd  TODO: crd type description

The cli im constructing is based off of kubectl.

[pacak]

I see. Seems like a reasonable request. I need to think about it a bit. Something like a way to customize how items are rendered maybe...

[pacak]

As a horrible workaround you can try giving your command 3 different names: command_body().command("pod, po").long("pod").long("po"), first one will be visible, later two will be used for parsing. It will display , in a wrong color using highlights (as a literal instead of a plain text) and will mess up shell completion a bit, but should work in a first approximation.

I'm still thinking about solving this problem in a better way.

[teohhanhui]

Need this too, in the case of hyfetch:

  --distro DISTRO, --test-distro DISTRO
                        Test for a specific distro

Using parallel composition for now:

    let distro = long("distro")
        .help("Test for a specific distro")
        .argument("DISTRO")
        .optional();
    let test_distro = long("test-distro")
        .help("Test for a specific distro")
        .argument("DISTRO")
        .optional();
    let test_distro = construct!([distro, test_distro]);

Seems to be working correctly:

        --distro=DISTRO       Test for a specific distro
        --test-distro=DISTRO  Test for a specific distro

$ hyfetch --distro test --test-distro test
Error: `--test-distro` cannot be used at the same time as `--distro`

$ hyfetch --test-distro test --distro test
Error: `--distro` cannot be used at the same time as `--test-distro`

[eugenesvk]

One more idea for the help output for visible aliases :

Available options (↑ indicates alias):
    -u, --undo      Something about undo
    ↑r    restore   undo help text continues
    ⮬r    restore   with a fancier arrow
                    more undo help text

(if there is not enough text then the 2nd/3rd lines would just be empty, providing another visual cue that it's an alias without separate content)

the aliases could be highlighted differently

• maybe with some arrow like ↑ or ⮬?
• maybe in italic
• maybe in a different color
• or maybe the lack of -/-- is enough?

[eugenesvk]

the confusion can be resolved with the help message as in the example -

↑ indicates alias

could be

argument in italics indicate alias

or

argument indicate alias

(where argument is colored in the alias color)

But the cli world isn't well known for much art :), so haven't seen any great examples, usually you'd have some ugliness like this

-a our main option
-b something else
-c something else
-r alias for -a

where alias isn't tied to the main argument. But that's a sorting issue, should be easy to fix. Though I still think indicating an alias without the alias for -a is visually superior as it's cleaner

Similarly, you'd sometimes have aliases in the description, which is also worse as it's harder to see them

config       Manage config files [aliases: cfg]

Re. compatibiliy - you could have a compatibility compilation flag that would replace the arrow with ^, but the arrow has the benefit that it's never used as an argument, so can't be confused with some legitimate shell symbol

(think the only time where inline aliases are better is when you have very many of them (or have very many arguments) and it's better to save the precious vertical space, but that might also be an extra complication flag you'd add to each alias - whether to add them on a line or in the help message like aliases: und, uu, r, res, restore, rs)

[pacak]

usually you'd have some ugliness like this
Similarly, you'd sometimes have aliases in the description, which is also worse as it's harder to see them

I think this might work as long as aliases go on a separate line, right after option description similar to how default values or env values are printed right now:

-a our main option
   Alias: -r
-b something else
...

and

config     Manage config files
           Alias: cfg

I don't think exact representation matters right now, we can start with something that is good enough and improve from there. Most important part is how to represent it in the API (I don't want to add two separate commands to add visible aliases - short/long) and how to represent it internally.

In the API this is probably going to be short('a').short('r').show_alias()

[eugenesvk]

your examples suffer from the same issue - they move the same thing (argument) to a totally different place (description) and as such require more verbose/repeated description - by the way, that's also where different style would help, a bold cfg is easier to see as alias than Alias: cfg (not sure, does bpaf support cusomt styling in help messages?)

Would your api work selectively?
short('a').short('u').show_alias().short('r') would show u, but not r in case you'd still need hidden aliases for compatibility reasons, but wouldn't want any current users learning them?

That could also signal formatting like .show_alias("inline") or .show_alias_inline()

[pacak]

and as such require more verbose/repeated description

I don't think description needs to be repeated, just the alias names are

Would your api work selectively?

Yup. This requires some internal changes that I'm probably going to make anyway. Experimenting with that right now.

the way, that's also where different style would help, a bold cfg is easier to see as alias than Alias: cfg (not sure, does bpaf support cusomt styling in help messages?)

It does via Doc datatype and cfg/-r are going to be styled the same as config/-a so they should be visible.

That could also signal formatting like

Maybe. We'll see once I get something closer to beta stage

[eugenesvk]

By the description that gets repeated I meant this Alias: -