Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Allow subcommands to have alias names #248

Closed
mlaster opened this issue Oct 11, 2020 · 5 comments · Fixed by #627
Closed

Allow subcommands to have alias names #248

mlaster opened this issue Oct 11, 2020 · 5 comments · Fixed by #627
Labels
enhancement New feature or request good first issue Good for newcomers

Comments

@mlaster
Copy link

mlaster commented Oct 11, 2020

Since ArgumentParser is case-sensitive, it would be nice to allow commands to have alias names. For example, if I have a subcommand named "fetchResults", if the user types "fetchresults", I would like either of these arguments to run my subcommand.

This would also be useful to have both a verbose subcommand name and a short form like "fr"
@natecook1000 natecook1000 added enhancement New feature or request good first issue Good for newcomers labels Oct 12, 2020
@Zoha131
Copy link
Contributor

Zoha131 commented Oct 16, 2020

@natecook1000 I would like to work on this issue. I am some questions in my mind:

  1. Would the aliasing be an opt-in feature?
  2. Would this only be available for that subcommand whose commandName is not nil?

@MPLew-is
Copy link
Contributor

Just my two cents, I would love the ability to be able to have a parent command be able to define a [String: ParsableCommand] dictionary for its subcommands, regardless of what the auto-inferred or overridden name is. I can't say I've ever had a need do it, but it'd be nice to able to bring in existing Argument Parser code from other projects as subcommands if the need arises, and be able to change their names as needed.

In regards to point 1, I would absolutely think that this should be opt-in somehow so that things "just work" out of the box - it certainly feels more Swifty to have the option requiring more complexity (manual command names) be the one that's opted into, to not overcomplicate getting a project started. And we probably also don't want to break whatever existing code there is that relies on the current API, either, if it can be avoided.

I don't have any concrete ideas about what the implementation of this would look like, but it's certainly something I'd be excited to see!

@ghost
Copy link

ghost commented Oct 24, 2020

Another aspect to this which would be nice to have is "forwardable aliasing" — an alias that forwards to another subcommand with some default options already set.

For example, one could define a command alias named "reinstall", which would forward to the "install" command, with the "--reinstall" flag set to true by default.

@natecook1000
Copy link
Member

@Zoha131 Thanks for your interest in working on this!

  1. Would the aliasing be an opt-in feature?

Yes — I think the aliases could just be an array of strings, with the default as an empty array.

  1. Would this only be available for that subcommand whose commandName is not nil?

Right — a nil value for commandName means the primary name should be generated automatically from the type name.

You might want to think about how to present the aliases to users in the help, as well.

@MPLew-is / @ajh17: I'm disinclined to add this kind of aliasing, as it somewhat inverts the command tree metaphor. I think we have enough opportunities with composition that this kind of forwarding can be handled by existing language features. For example, you could create a generic wrapper command that includes another command as an @OptionGroup and then runs it automatically:

struct ForwardingCommand<Base: ParsableCommand>: ParsableCommand {
  static var configuration: CommandConfiguration {
    Base.configuration // might need a little extra something here
  }
  
  @OptionGroup
  var command: Base
  
  mutating func run() throws {
    try command.run()
  }
}

@importRyan
Copy link

Enjoying the library. Wanted to say thanks via this issue.

@natecook1000 I'd submit a PR from this branch, but am still sorting how to update completion scripting.

  1. Would you be comfortable with an implementation that also offers a hiddenCommandAliases parameter in CommandConfiguration? Showing in --help all capitalizations/options could be distracting in some cases.

  2. For help presentation, this simply appends a line that reads ALIASES: b BBQ barbeque. For branching commands, the subcommands section simply lists aliases and the command on the same line. In both, terms are size sorted, then alphabetized.

  3. Re: enabling in completion scripting. Reading through docs. Is it that command aliases would each get an identical block _base() { ... } _b() { ... } or is there specific syntax for this concept that I've missed?

dcantah added a commit to dcantah/swift-argument-parser that referenced this issue Apr 1, 2024
@dcantah
Add aliases support for sub commands
0e86c69 
This adds support for aliases for subcommands via a new parameter to
CommandConfigurations constructors. The aliases are passed as an array
of strings, where the default is just an empty array that signifies there
are no aliases. The aliases are supported regardless of if a different
commandName is chosen or not. This also updates how subcommands show up
in the help text. Any aliases are now displayed to the right of the original
command.

In addition to the functionality itself, this change:

1. Updates some of the EndToEnd parsing tests to make sure they function
while using aliases.
2. Sprinkles mentions where I saw fit in the documentation.
3. Updates the Math example to have aliases for `math stats average`
(`math stats avg`), and `math multiply` (`math mul`).

`math`'s help text now looks like the below:

```
~ math --help
OVERVIEW: A utility for performing maths.

USAGE: math <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  add (default)           Print the sum of the values.
  multiply, mul           Print the product of the values.
  stats                   Calculate descriptive statistics.

  See 'math help <subcommand>' for detailed help.

~ math stats --help
OVERVIEW: Calculate descriptive statistics.

USAGE: math stats <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  average, avg            Print the average of the values.
  stdev                   Print the standard deviation of the values.
  quantiles               Print the quantiles of the values (TBD).

  See 'math help stats <subcommand>' for detailed help.
```

and use of the aliases:

```
~ math mul 10 10
100

~ math stats avg 10 20
15.0
```

This change does NOT add any updates to the shell completion logic for
this feature.

Fixes apple#248
@dcantah dcantah mentioned this issue Apr 1, 2024
Merged
4 tasks
dcantah added a commit to dcantah/swift-argument-parser that referenced this issue Apr 2, 2024
@dcantah
Add aliases support for sub commands
c0e5f6b 
This adds support for aliases for subcommands via a new parameter to
CommandConfigurations constructors. The aliases are passed as an array
of strings, where the default is just an empty array that signifies there
are no aliases. The aliases are supported regardless of if a different
commandName is chosen or not. This also updates how subcommands show up
in the help text. Any aliases are now displayed to the right of the original
command.

In addition to the functionality itself, this change:

1. Updates some of the EndToEnd parsing tests to make sure they function
while using aliases.
2. Sprinkles mentions where I saw fit in the documentation.
3. Updates the Math example to have aliases for `math stats average`
(`math stats avg`), and `math multiply` (`math mul`).

`math`'s help text now looks like the below:

```
~ math --help
OVERVIEW: A utility for performing maths.

USAGE: math <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  add (default)           Print the sum of the values.
  multiply, mul           Print the product of the values.
  stats                   Calculate descriptive statistics.

  See 'math help <subcommand>' for detailed help.

~ math stats --help
OVERVIEW: Calculate descriptive statistics.

USAGE: math stats <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  average, avg            Print the average of the values.
  stdev                   Print the standard deviation of the values.
  quantiles               Print the quantiles of the values (TBD).

  See 'math help stats <subcommand>' for detailed help.
```

and use of the aliases:

```
~ math mul 10 10
100

~ math stats avg 10 20
15.0
```

This change does NOT add any updates to the shell completion logic for
this feature.

Fixes apple#248
dcantah added a commit to dcantah/swift-argument-parser that referenced this issue Apr 23, 2024
@dcantah
Add aliases support for sub commands
891e893 
This adds support for aliases for subcommands via a new parameter to
CommandConfigurations constructors. The aliases are passed as an array
of strings, where the default is just an empty array that signifies there
are no aliases. The aliases are supported regardless of if a different
commandName is chosen or not. This also updates how subcommands show up
in the help text. Any aliases are now displayed to the right of the original
command.

In addition to the functionality itself, this change:

1. Updates some of the EndToEnd parsing tests to make sure they function
while using aliases.
2. Sprinkles mentions where I saw fit in the documentation.
3. Updates the Math example to have aliases for `math stats average`
(`math stats avg`), and `math multiply` (`math mul`).

`math`'s help text now looks like the below:

```
~ math --help
OVERVIEW: A utility for performing maths.

USAGE: math <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  add (default)           Print the sum of the values.
  multiply, mul           Print the product of the values.
  stats                   Calculate descriptive statistics.

  See 'math help <subcommand>' for detailed help.

~ math stats --help
OVERVIEW: Calculate descriptive statistics.

USAGE: math stats <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  average, avg            Print the average of the values.
  stdev                   Print the standard deviation of the values.
  quantiles               Print the quantiles of the values (TBD).

  See 'math help stats <subcommand>' for detailed help.
```

and use of the aliases:

```
~ math mul 10 10
100

~ math stats avg 10 20
15.0
```

This change does NOT add any updates to the shell completion logic for
this feature.

Fixes apple#248
natecook1000 pushed a commit that referenced this issue Apr 30, 2024
@dcantah
Add aliases support for sub commands (#627)
2b96293 
This adds support for aliases for subcommands via a new parameter to
CommandConfigurations constructors. The aliases are passed as an array
of strings, where the default is just an empty array that signifies there
are no aliases. The aliases are supported regardless of if a different
commandName is chosen or not. This also updates how subcommands show up
in the help text. Any aliases are now displayed to the right of the original
command.

In addition to the functionality itself, this change:

1. Updates some of the EndToEnd parsing tests to make sure they function
while using aliases.
2. Sprinkles mentions where I saw fit in the documentation.
3. Updates the Math example to have aliases for `math stats average`
(`math stats avg`), and `math multiply` (`math mul`).

`math`'s help text now looks like the below:

```
~ math --help
OVERVIEW: A utility for performing maths.

USAGE: math <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  add (default)           Print the sum of the values.
  multiply, mul           Print the product of the values.
  stats                   Calculate descriptive statistics.

  See 'math help <subcommand>' for detailed help.

~ math stats --help
OVERVIEW: Calculate descriptive statistics.

USAGE: math stats <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  average, avg            Print the average of the values.
  stdev                   Print the standard deviation of the values.
  quantiles               Print the quantiles of the values (TBD).

  See 'math help stats <subcommand>' for detailed help.
```

and use of the aliases:

```
~ math mul 10 10
100

~ math stats avg 10 20
15.0
```

This change does NOT add any updates to the shell completion logic for
this feature.

Fixes #248
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request good first issue Good for newcomers
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add aliases support for sub commands dcantah/swift-argument-parser
6 participants
@mlaster @natecook1000 @MPLew-is @Zoha131 @importRyan and others