Completion: Silent install, better handling of descriptions

[mklabs]

Follow up to the completion feature.

This PR tries to implement what we discussed before, and fix a few issues we had for bash / zsh shell (mklabs/tabtab#21)

• I update tabtab to handle a new flag --auto for both install / uninstall. It'll use the shell configuration file without prompting user for a decision. It goes in pair with tabtab uninstall --auto
  • Doing so, npm i yo -g and npm uninstall yo -g will automatically update the SHELL configuration file (~/.bashrc, ~/.zshrc or ~/.config/fish/config.fish). This should be totally transparent.
• Fixed bad zsh / bash behavior with cache
• Implemented zsh description for completion items, a bit like fish.

$ yo <tab>
--force              -- description for --force
--generators         -- description for --generators
--insight            -- description for --insight
--no-color           -- description for --no-color
--no-insight         -- description for --no-insight
--version            -- description for --version
-f                   -- description for -f
backbone:all         -- all from backbone generator
backbone:app         -- app from backbone generator
backbone:collection  -- collection from backbone generator
backbone:model       -- model from backbone generator
backbone:router      -- router from backbone generator
backbone:view        -- view from backbone generator
jekyllrb:app         -- app from jekyllrb generator
jekyllrb:post        -- post from jekyllrb generator
react:app            -- app from react generator

• Removed yo generator <tab> completion where we try to parse the help output. I got a lot of issues with it, and decided to put it aside for the moment. Plus, the --help output exec is really slow and not ideal. I'm thinking about trying to require the generator and try to see if I can inspect the options / arguments hash.

---

Question: While implementing descriptions, I wondered what we should set as description for flags and generators. For now I went for %subgenerator from %name generator, if you can think of something better 👍

[mklabs]

@SBoudrias node v0.10 fails on travis because of https://travis-ci.org/yeoman/yo/jobs/131948386#L190

not sure how to fix it, or if I should. Let me know, this PR fixes an important bug as reported in #441

If you'd like more time to review, a bump to package.json to force install of [email protected] instead of [email protected], that was just published should fix it as well.

[kevva]

Should really just remove 0.10 from Travis since we only support >=0.12 anyway.

[SBoudrias]

Let's keep using ^ range. The issue you had with 1.4 is that you published a breaking change without a major version bump which broke npm semver reliance.

[mklabs]

Yeah I know :/

I was't aware it was a breaking change, and really don't want to bump a major version because of a misconfigured Babel and yo integration (this .default thing ..)

I'll keep at that way (using range) and will publish [email protected] alongside this pull request.

[SBoudrias]

About node 0.10, you can use pinkie-promise to load a promise polyfill that will work in any version. It's easy to do, so not a big reason for us to drop 0.10 support from the core.

[mklabs]

@SBoudrias I'll see if I can add pinkie-promise

btw, would it be better / safer change the target branch of this PR to a feature branch on yeoman repo ? I'd recommend merging this request (when good to merge) in a specific branch where contributors and users willing to give feedback on the completion system can do.

I'd like to avoid introducing issues for peoples that don't care about this completion thing. I've spent a lot of energy on this already, and feel there is still more work to do. This is quite tricky due to the 3 different shell environments, and kinda hard to test (that's whay any feedbacks / bug reports on this is really important to me).

[SBoudrias]

btw, would it be better / safer change the target branch of this PR to a feature branch on yeoman repo ? I'd recommend merging this request (when good to merge) in a specific branch where contributors and users willing to give feedback on the completion system can do.

Usually that's kind of useless as we end up getting no feedback at all.

We should merge on master, but make sure we're failing gracefully.

[mklabs]

Okay.

Let's use this PR to extensively test it out, on different shells etc. I still have this bash bug with ":" character a bit tricky to fix: mklabs/tabtab#22 (occurs with generator:subgenerator)

[mklabs]

@binduwavell did some great testing and provided amazing feedbacks. Good progress.

zsh is confirmed to work way better. We'll next try to work on the generator completion, eg.

yo generator:<tab> => expand to subgeneator
yo generator:sub <tab> => expand to generator options and arguments
yo generator:sub --name <tab> => expand to a custom list names provided by the generator

We were thinking about some kind of API for generator authors to be able to customize the completion.

• easy way: Define a list of completion results in package.json. Possible field value would be "tabtab" or "completions"

"tabtab": ['--flag', '--name', ... ]

// extended with completion description (fish / zsh)
"tabtab": [
   // flags
  { name: '--name', description: 'Name definition for the ... Model'}, 
  { name: '--template', description: 'Template engine to use with view generator'}, 

  // arguments (subgenerators)
  { name: 'view', description: 'Create a new model for your application'}
  { name: 'model', description: 'Create a new model for your application'}
]

• do anything way: Define a "tabtab" field in package.json that points to a completion handler.

// in package.json
"tabtab": "lib/completions.js"

// lib/completions.js
module.exports = function (data, done) {
  // yo generator foo <tab>
  data.line;         // line value for the completed command: yo generator foo
  data.prev;        // value of the previous word: foo
  data.cursor;    // number cursor position: 17

  return done(null, ['--help', '--name', ...]);
};

// possibly use promise
module.exports = function (data) {
  // yo generator foo <tab>
  data.line;         // line value for the completed command: yo generator foo
  data.prev;        // value of the previous word: foo
  data.cursor;    // number cursor position: 17

  return new Promise(function(resolve, reject) {
    resolve(['--help', '--name', ...]);
  });
};

@SBoudrias @sindresorhus @kevva Let us know what you think. Particularly on this completion API for generator authors. Would love more feedbacks :)

Thanks!

[sindresorhus]

I like the latter. It gives maximum flexibility and completions are rarely only static.

[binduwavell]

I don't see how the first option will work when main generator and sub generators have different options and arguments. If we can nest completion definitions that could be nice.

I agree that the second option would be better. If we go that route, it would be nice if data could include some yeoman specific properties: subgenerator at least.

I suspect we could do better by generalising handling of: subgenerator names, positional argument awareness, option and option aliases, vales by type and singular vs multi valued values.

Maybe fall back to this proposal for folks that need ultimate control.

In my generators, I have tied arguments and options to prompts and can run the filter function from the prompt on values provided via the commandline, would be nice to be able to plug that in to completion as well. With the completion function being a standalone module, I would likely have to duplicate a bunch of specification.

I'd love to be able to have the choices for a prompt drive the completion values for an argument or option.

[mklabs]

I'd like to see both options implemented. If "tabtab" package.json value is a string, require the file and use the handler, if it's an Array, then register the completion results directly.

Good idea on providing yeoman specific info like subgenerator.

A third option like you described would be to require a given generator and inspect this.arguments / this.options to build completions automatically from these.

[SBoudrias]

I feel options and arguments are relevant information for any person implementing another adapter for our generators. I think we should go with a generic option.

Right now you're loading a generator an inspecting the results of the gen.help() method right? Maybe we could just expose these rules as an object on yeoman-generator.

[SBoudrias]

@mklabs @binduwavell I see some commits have been added on top of the last PR. What is the state currently, is this in a working state?

[mklabs]

Hi @SBoudrias

No i dont think so. There is still a few things to test out.

If you'd like to see how well it behaves ans provide us feedbacks, you could fetch and check in the approriate branch.

[mklabs]

I'm going to close this long running pull request for the moment, I might reopen and rework on it at a latter time.