Autocompletion
Sorbet supports autocompletion via LSP.
Some basic features of autocompletion in Sorbet:
Sorbet supports completion for method calls, local, instance, and class variables, Ruby keywords, classes, and constants.
Completion items will include documentation for the suggestion, when available. Sorbet assumes that a comment immediately above the definition of things like classes, methods, and constants is the documentation for a given item.
Different language clients may or may not show this information by default.
Completion items are sorted by inheritance. Methods defined lower in the inheritance hierarchy show up higher in the completion results. (This is not a perfect heuristic, but it is how Sorbet works.)
There are some more complicated features worth calling out in their own section.
Troubleshooting
No completion results
Support for autocompletion is minimal in # typed: false files,
like most other LSP features.
If the file is # typed: true and there are still no completion results, it
might be that Sorbet is busy with an ongoing operation. See
Showing the Language Server Status to understand what the
server statuses mean, and whether Sorbet is able to respond to completion
requests given a certain status.
If Sorbet is “Idle” (or “Typechecking in background…”) and there are still no completion results, it might be that Sorbet failed to recover from a syntax error in the file. See Syntax error recovery and completion.
If there is no syntax error, it might be that the code path is unreachable. Sorbet does not show completion results for dead/unreachable code paths.
Wrong completion results
If the completion results are present but look wrong, inspect the kind of completion item. For example, VS Code uses these icons to show the completion item kinds:
Sorbet will only ever return completion items with the kind method,
variable, field, class, interface, module, enum, or keyword (and
sometimes snippet).
Notably, the “abc” icon (word) means the results came either from VS
Code’s editor.wordBasedSuggestions setting or some other generic autocomplete
extension. (Or, if not using VS Code, then from some other plugin.) Sorbet
never produces word completion items.
In specific circumstances (see
Completion for method signatures and
Completion for YARD snippets), Sorbet will also
produce snippet items. In all other cases, snippet items come from some
other snippet provider, not Sorbet.
If the completion results still look wrong, please report a bug.
Syntax error recovery and completion
One of the biggest reasons why Sorbet fails to produce completion results is because it failed to recover from a syntax error in the file.
Sorbet has a custom Ruby syntax parser which attempts to recover from many common syntax errors, but it is not perfect. For example:
def foo(x)
x.
end
This Ruby program has a syntax error, and yet Sorbet is able to recover from it,
understanding that this method contains a call on x which is missing the
method name.
To see all the known cases where Sorbet fails to recover from parsing a file
with a syntax error, see
all issues labeled parser.
The biggest known case where Sorbet fails to recover is with mismatched parentheses, brackets, and quotes.
If you think you’ve found another example that Sorbet should be able to recover
from, please open an issue. The Sorbet Playground allows
showing the parse result for a file, which is useful for debugging whether
Sorbet parsed or failed to parse a given syntax error: simply pass the
?arg=--print=parse-tree-whitequark flag in the query string.
Completion for method signatures
Sorbet can suggest signatures for methods without signatures. Simply typing
sig above a method without a signature will trigger a completion item that
expands to a snippet with one parameter in the sig for each parameter in the
method definition immediately following the sig.
For more information, see Automatically suggesting method signatures
Pre-declared snippets
Snippets expand a pre-defined template and allow pieces of the template to be
filled in with values (most language clients allow pressing TAB to cycle
through the parts of the template that need to be filled in).
Sorbet includes some snippet autocompletion results. These show up in addition
to any snippets that editors might already be configured with. Snippets from
Sorbet always show up prefixed with (sorbet):
In VS Code, snippets also show up with a “square with dashed bottom line” icon. See Wrong completion results.
If a snippet has the “square with dashed bottom line” icon but does not start
with (sorbet), it came from some other extension in your developer environment
and is configured separately.
These are the snippets Sorbet includes.
Snippets for all Ruby keywords.
For example, typing case brings up a completion item which, when accepted,
expands to
case expr
when expr
else
end
Other notable keyword snippets include snippets for def, class, module,
and if.
Snippets for Sorbet-specific constructs.
You can type struct or enum and have these auto-expand to
T::Struct and T::Enum classes:
The struct and enum snippet triggers are not methods that exist at runtime:
they’re only indicators to Sorbet that you’re trying to define a T::Struct or
T::Enum.
These completions will only show up if there is no explicit receiver for a
method call (e.g., x.struct will not show the T::Struct snippet suggestion,
only struct).
Completion for YARD snippets
Sorbet can suggest a YARD doc snippet for methods.
It will appear after typing ## above a Ruby method or signature, and
pre-populate the snippet with one @param for each parameter the method has.
Some reminders about these docs:
Sorbet recognizes Markdown syntax in these docs, and VS Code will render the Markdown to rich text when showing the documentation.
Get creative and show examples of how to use your API!
These docs show up on hover and in autocompletion items.
Sorbet does not read YARD docs for type annotations.
See the YARD docs for a list of available tags.