Support positional arguments

[rvesse]

Currently @Arguments is a general annotation that can only be applied to a single field and collects all non-option values into that field. There are various use cases where it might be nicer to support true positional arguments i.e. a new @PositionalArgument annotation such that arguments could be captured on separate fields and provide more detailed help specific to each argument

e.g.

@Command(name = "pos-args")
public class PositionalArgumentExample {

  @PositionalArgument(title = "Source", description = "The source file", position = { 0 })
  private String source;

  @PositionalArgument(title = "Target", description = "The target file", position = { 1 })
  private String target;

  @Arguments(title = "ExtraArg", description = "Extra arguments")
  private List<String> extraArgs = new ArrayList();
}

Which would be used as follows:

> pos-args source.txt target.txt foo bar

Where source.txt would be set to the source field, target.txt set to the target field and the additional arguments passed to the extraArgs field

[rvesse]

Concrete tasks:

• [x] New @PositionalArgument annotation
• [x] New PositionalArgumentMetadata to hold the metadata for a positional argument
• [x] Extend CommandMetadata with positional arguments support
• [x] Extend AbstractCommandParser with positional arguments support
• [ ] Help generations updated to generate help for new positional arguments ArgumentMetadata
  • [x] CLI
  • [ ] HTML
  • [ ] Markdown
  • [x] Man
  • [ ] Bash
• [x] ArgumentsRestriction extended to work with positional arguments as well
  • [x] Implementations updated appropriately
  • [ ] Unit test coverage for the restrictions
• [x] Migration Guide updated for behavioural changes around positional arguments

[rvesse]

Moved out to 2.8

[rvesse]

Moved to 3.x branch

[gsmet]

Hey @rvesse ,

I'm working on integrating Airline into Quarkus GitHub App (it's a framework used to develop GitHub Apps) to parse commands included in GitHub comments (basically to have a comment-based commands bot).

This @PositionalArgument feature is THE missing feature I would need to make things completely smooth.

Anything I can do to help make it happen? AFAICS, you have made a lot of progress on this already.

And btw, a good opportunity to thank you for your work on this: it was exactly what I was looking for and it's flexible enough to meet my requirement even if it's not the typical use case of this library.

[rvesse]

Hey @gsmet,

So the core implementation was done a long time ago as the commits show, this was being done in aid of $dayjob usage of this library but priorities changed and we never ended up adopting this feature so it didn't get finished up. I would really like to finish it and get a 3.x release out at some point.

The main areas of this feature that need finishing are:

• Converting all the help generators to include support for documenting positional arguments (Bash auto-complete being particularly thorny looking at my commit history). This is partially done.
  • Making sure the unit test coverage verified that the built-in restrictions continue to work with.

There are Alpha builds available via https://central.sonatype.org/publish/publish-guide/#accessing-repositories if you want to experiment with it in your project. Note Airline counts as a legacy project so you'll need to use the older oss.sonatype.org URLs. Most recent Alpha version is 3.0.0-alpha-2-SNAPSHOT