Add completion script for Visual Studio Code by Mellbourn · Pull Request #24 · zsh-users/zsh

Mellbourn · 2018-04-05T19:44:43Z

This script adds command line completion for the code command, which is used to start Visual Studio Code (https://code.visualstudio.com/). Code is ranked the most popular developer environment in the Stack Overflow Developer Survey 2018, so I think there is a strong case for including completion functionality directly in zsh.

This implementation gives completion for all documented parameters and has specialized completion for parameters that don't take filenames as parameters, for example --add only takes directories as arguments.
I have tested that it works well on macOS and Windows Subsystem for Linux (Ubuntu).

I suggested this script to the maintainers of Visual Studio Code, but they felt it was out of scope of the product itself, and suggested I provide the script externally (microsoft/vscode#47101). So it would be great if it could be added directly to zsh instead.

I have also submitted this completion script to the zsh-completions repository, but it was pointed out to me that it could be a better idea to have the completion directly in zsh. So if you accept this pull request, I can withdraw the pull request from zsh-completions, since it will be redundant there.

danielshahaf · 2018-04-06T10:42:03Z

In --level and --locale, I suggest to move the example/default values to after the first colon.

In the helper function, ${${(f)"$(locale -a)"}%%.*} should be faster and split on newlines only (per POSIX). I think it would fit better as Type/_locales, though—doesn't that exist already?

Excuse brevity (touch keyboard).

okapia

Thanks. This looks good. I've added some comments on some fairly trivial things.

okapia · 2018-04-06T11:48:53Z

Completion/Unix/Command/_code

+  local -a locales
+  locales=($(locale -a | sed -e 's/\..*$//'))
+  _describe 'locale' locales
+}


There is an _locales function already but it appears that code does its own thing. To get German, using de_DE doesn't work but de-DE does.

I can get an accurate list with:
/usr/share/code/resources/app/out/vs/code/node/cli.nls.*.js(:r:t:s/cli.nls.//)

It might even be better to simply list the current 9 possible locales.

Agreed. I hard coded the list of actual possibilities. That makes the list straightforward, and more accurate.

okapia · 2018-04-06T11:57:02Z

Completion/Unix/Command/_code

+
+arguments=(
+  {-d,--diff}'[compare two files with each other]:file to compare:_files:file to compare with:_files'
+  {-a,--add}'[add folder(s) to the last active window]:folder:_directories'


The term "folder(s)" indicates that more than one directory can be specified. It appears that to do this, you need to specify -a more than once. By default, zsh excludes options that have already been used so we need a * at the start of the spec. So I'd suggest something like:

\*{-a,--add}'[add folder to the last active window]:folder:_directories'

Actually, I would also ditch the modern Windows term "folder" and stick with the traditional Unix term "directory", though that is less important.

Good point. I have added the asterisk. I changed to directory/directories. Wasn’t totally sure about how to handle the “(ies)” part. I chose “directory (or directories)”. Feel free to suggest a better wording.

okapia · 2018-04-06T12:08:42Z

Completion/Unix/Command/_code

+  {-a,--add}'[add folder(s) to the last active window]:folder:_directories'
+  {-g,--goto}'[open a file at the path on the specified]'
+  {-n,--new-window}'[force to open a new window]'
+  {-r,--reuse-window}'[force to open a file or folder in the last active window]'


Are these last two options mutually exclusive. If so, we can indicate to zsh that only one should be used. It is also usually the case that long and short option forms are mutually exclusive of each other. Furthermore, the English in these descriptions is not great. I know it comes from code's --help output but the word "force" when used as a verb like this should have an object. So, I'd suggest something like:

'(-n --new-window -r --reuse-window)'{-n,--new-window}'[open a new window]'

And similarly for -r.

Good point. I followed your advice regarding -r and -n. I have also made all long and short arguments exclusive

okapia · 2018-04-06T12:14:00Z

Completion/Unix/Command/_code

+  '--uninstall-extension[uninstalls an extension]:id or path:_files -g "*.vsix"'
+  '--enable-proposed-api[enables proposed api features for an extension]:extension id:'
+  '--verbose[print verbose output (implies --wait)]'
+  '--log[log level to use. Default is info]:level:(critical error warn info debug trace off)'


Usual zsh completion way to indicate defaults is with square brackets in the argument description. That ensures it is on screen when you need it, e.g:

'--log[specify log level to use]:level [info]:(critical error warn info debug trace off)'

I also add the word "specify" to the start of the description which is very common. In most cases, the first word of per-match descriptions will be a verb.

Ok, changed the defaults to be in square brackets. Added "specify"

okapia · 2018-04-06T12:17:26Z

Completion/Unix/Command/_code

+  {-r,--reuse-window}'[force to open a file or folder in the last active window]'
+  {-w,--wait}'[wait for the files to be closed before]'
+  '--locale[the locale to use (e.g. en-US or zh-TW)]:locale:__code_locales'
+  '--user-data-dir[specifies the directory that user data is in]:directory:_directories'


I'd change the verb "specifies" to "specify". Similarly later, I'd change enables to enable, uploads to upload and (un)installs to (un)install. It is more consistent to use the same form for the verbs in descriptions and you have "print", "set" and "list" elsewhere. Usual zsh convention is this short verb form.

Changed lots of verb cases and used “specify” more

okapia · 2018-04-06T12:19:22Z

Completion/Unix/Command/_code

+  '--inspect-brk-extensions[allow debugging and profiling of extensions with the extension host being paused after start]'
+  '--disable-gpu[disable GPU hardware acceleration]'
+  '--upload-logs[uploads logs from current session to a secure endpoint]'
+  '--max-memory[max memory size for a window]:size (in Mbytes):'


units in parentheses is a common convention anyway, the word "in" isn't needed.
Perhaps start the other description with "specify ", though.

Removed “in”

okapia · 2018-04-06T12:23:32Z

Completion/Unix/Command/_code

+  '*:filename:_files'
+)
+
+_arguments $arguments


We can pass -s and -S to _arguments - short forms like -wn for -w -n are allowed and no options are allowed after --. So this can be:
_arguments -s -S $arguments

Added parameters. I had no idea about the -- trick.

Thank you for all your comments!
I made some further improvements:

--upload-logs can now complete the confirmation.

Corrected --wait description

Made it easier to end --goto parameter with a colon

Added an optional = to some options that can accept it (unclear to me exactly which do, but it is not all)

Please let me know if I got something wrong or there is anything else I should improve.

Make locales a fixed list Allow multiple --add Make exclusive arguments exclusive Improve wording using "specify" Improve word case Add -s and -S Add --upload-logs completion Correct --wait description Add optional "=" to commands thatn can accept it Make it easier to end --goto parameter with a colon

okapia · 2018-04-06T23:10:37Z

Completion/Unix/Command/_code

+
+arguments=(
+  '(-d --diff)'{-d,--diff}'[compare two files with each other]:file to compare:_files:file to compare with:_files'
+  '(-a --add)'\*{-a,--add}'[add specified directory (or directories) to the last active window.]:directory:_directories'


You don't want the (-a --add) exclusion as well as *.
The * prevents -a excluding -a (i.e. itself) which it does by default. The option can be repeated so you can mix -a and --add. So no exclusion is needed.

I wouldn't bother with the "(or directories)". The fact that the option can be repeated conveys the information that more than one directory can be added. Admittedly, _arguments doesn't make that as obvious as it might in completion listings but it'd be better to try to make it do so for all completions than to use convoluted wording in each one.

Agreed. Removed (-a --add) exclusion and redundant pluralization.

okapia · 2018-04-06T23:12:07Z

Completion/Unix/Command/_code

+arguments=(
+  '(-d --diff)'{-d,--diff}'[compare two files with each other]:file to compare:_files:file to compare with:_files'
+  '(-a --add)'\*{-a,--add}'[add specified directory (or directories) to the last active window.]:directory:_directories'
+  '(-g --goto)'{-g,--goto}'[open a file at the path on the specified line and character position]:file\:line[\:character]:_files -r \:'


Unlike earlier, I don't have VS code available to check but I wouldn't be surprised if the -g option can also be repeated. Could be worth checking.

Nope. When I test, it seems to ignore the second -g

okapia · 2018-04-06T23:14:08Z

Completion/Unix/Command/_code

+  '--locale=[specify the locale to use]:locale (e.g. en-US or zh-TW):(de en en-US es fr it ja ko ru zh-CN zh-TW bg hu pt-br tr)'
+  '--user-data-dir[specify the directory that user data is in]:directory:_directories'
+  '(-v --version)'{-v,--version}'[print version]'
+  '(-h --help)'{-h,--help}'[print usage]'


I can't verify with code at the moment but it is common for options like -h and -V to not be applicable in combination with any other options. In which case the exclusion list can be just (- *)

Set exclusion list to (- *)

Maybe the obverse should be done too:
If any parameters have been added, disallow -v and -h?

okapia · 2018-04-06T23:16:00Z

Completion/Unix/Command/_code

+  '--list-extensions[list the installed extensions]'
+  '--show-versions[show versions of installed extensions, when using --list-extension]'
+  '--install-extension[specify extension to install]:id or path:_files -g "*.vsix"'
+  '--uninstall-extension[specify extension to uninstall]:id or path:_files -g "*.vsix"'


This is a very pedantic point but in completion, it is common to use the glob qualifier (-.) with _files -g.
So _files -g "*.vsix(-.)"
That only matters if you have something like a directory named with the extension.

Done.

Thanks again for your comments!

okapia

Sourceforge's git seems to be broken at the moment otherwise I'd have probably tweaked this and pushed. So anyway, here's a couple more comments on the update. Again all fairly minor but it'd be good to get this done and the function can make it in before 5.5 gets released.

Maybe the obverse should be done too: If any parameters have been added, disallow -v and -h?

Remove -a --add exclusion and redundant pluralization Use the glob qualifier (-.) with _files -g

These additional display languages are on the VS Code Marketplace

okapia · 2018-04-07T09:14:19Z

Merged in 5e10acc

Thanks for the contribution and for your patience with the petty comments.

Add completion script for Visual Studio Code

2872d87

okapia requested changes Apr 6, 2018

View reviewed changes

okapia reviewed Apr 6, 2018

View reviewed changes

Mellbourn added 4 commits April 7, 2018 01:37

make it impossible to add other arguments after -v or -h

b4843d9

Maybe the obverse should be done too: If any parameters have been added, disallow -v and -h?

Tweaked according to review comments

8c34005

Remove -a --add exclusion and redundant pluralization Use the glob qualifier (-.) with _files -g

Add display languages available as Language Pack extensions

9e7e3b7

These additional display languages are on the VS Code Marketplace

change 'character' to the clearer 'column'

f257d93

okapia closed this Apr 7, 2018

hubot pushed a commit that referenced this pull request Apr 7, 2018

github #24: Add completion script for Visual Studio Code

5e10acc

Mellbourn mentioned this pull request Apr 7, 2018

add completion script for Visual Studio Code zsh-users/zsh-completions#561

Closed

Mellbourn mentioned this pull request Aug 14, 2018

complete documentation of all command line options microsoft/vscode#56401

Closed

Mellbourn mentioned this pull request Sep 13, 2018

code command completions for Bash & Zsh microsoft/vscode#56670

Merged

5 tasks

Conversation

Mellbourn commented Apr 5, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

danielshahaf commented Apr 6, 2018

Uh oh!

okapia left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

okapia Apr 6, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

okapia left a comment

Choose a reason for hiding this comment

Uh oh!

okapia commented Apr 7, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Mellbourn commented Apr 5, 2018 •

edited

Loading

okapia Apr 6, 2018 •

edited

Loading