Difficulty of autocomplete generation?

[scottbilas]

Hi @atifaziz - I've been loving this library and especially the new sourcegen you added. Works great, thank you. :)

Have you considered what it might take to have an autocomplete feature?

I've seen two styles so far - something like starship where you give an init command and a shell type and it feeds back code to add to the session. The other style is like dotnet where you run a complete command with the command line so far and it does all the work.

I'd like to support autocomplete for powershell and bash/zsh in my own cli app, and am considering the best way to do it. Seems like integrating into the docopt parsing would be best, though I'm totally unfamiliar with that code.

[atifaziz]

Glad to hear you're enjoying the source generator addition.

Have you considered what it might take to have an autocomplete feature?

Not at all and to be perfectly honest, I have never really investigated how that's accomplished for various shells. It's also not an itch I have to do scratch so far.

I'm totally unfamiliar with that code.

I wasn't either when I added the source generator piece and it took many sittings spread throughout a year! I had to get familiar with the existing code and then figure out a way to add the source generator version without breaking any existing code relying on previous versions. It wasn't easy and required a careful set of refactorings so I wouldn't underestimate the effort. Since the C# version was a pretty mechanical port of the Python version, I sometimes even consulted the latter since everything didn't translate over idiomatically. That said, I am a lot more familiar with the code and I can try guide a bit, but I am not sure if that's what you're looking for here.

In essence, the parser builds a tree of branch patterns that lead to leaf nodes like command, option and argument. The branch nodes are rules like required, optional and so on:

docopt.net/src/DocoptNet/Internals/BranchPatterns.cs

Lines 109 to 135 in 1428fff

	class Required : BranchPattern
	{
	public Required(params Pattern[] patterns) : base(patterns) { }
	}
	class Optional : BranchPattern
	{
	public Optional(params Pattern[] patterns) : base(patterns) { }
	}
	// Marker/placeholder for [options] shortcut.
	class OptionsShortcut : Optional
	{
	// TODO consider single pattern
	public OptionsShortcut(params Pattern[] patterns) : base(patterns) { }
	}
	partial class Either : BranchPattern
	{
	public Either(params Pattern[] patterns) : base(patterns) { }
	}
	class OneOrMore : BranchPattern
	{
	// TODO consider single pattern
	public OneOrMore(params Pattern[] patterns) : base(patterns) { }
	}

From this, you can try and prototype what the code for completion could look like to get an idea of the effort. Taking the canonical Naval Fate example:

Naval Fate.

Usage:
  naval_fate ship new <name>...
  naval_fate ship <name> move <x> <y> [--speed=<kn>]
  naval_fate ship shoot <x> <y>
  naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
  naval_fate -h | --help
  naval_fate --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.

The parsed tree for the above docopt looks like the following pseudo object representation in memory:

Required:
  Either:
    Required:
      Command(ship, False)
      Command(new, False)
      OneOrMore:
        Argument(<name>, [])
    Required:
      Command(ship, False)
      Argument(<name>, [])
      Command(move, False)
      Argument(<x>, )
      Argument(<y>, )
      Optional:
        Option(,--speed,1,10)
    Required:
      Command(ship, False)
      Command(shoot, False)
      Argument(<x>, )
      Argument(<y>, )
    Required:
      Command(mine, False)
      Required:
        Either:
          Command(set, False)
          Command(remove, False)
      Argument(<x>, )
      Argument(<y>, )
      Optional:
        Either:
          Option(,--moored,0,False)
          Option(,--drifting,0,False)
    Required:
      Option(-h,--help,0,False)
    Required:
      Option(,--version,0,False)

During parsing of actual command-line arguments, matchers are used to execute the branch node rules until the leaves are encountered and value(s) established. I guess in the case of completion, you'd see how far you got into the tree and what are possible set of suggestions to offer.

Hope this helps as a starting point.

[scottbilas]

Thank you for this detailed help, this is a great head start. :)