Skip to content

Latest commit

 

History

History
439 lines (355 loc) · 52.1 KB

integrate-with-autocomplete-plus.md

File metadata and controls

439 lines (355 loc) · 52.1 KB
title layout
Integrate with Autocomplete Plus
doc.ejs

Provider API - Docs for writing your own provider

The Provider API allows you to make autocomplete+ awesome. The Pulsar community will ultimately judge the quality of Pulsar's autocomplete experience by the breadth and depth of the provider ecosystem. We're so excited that you're here reading about how to make Pulsar awesome.

Defining a Provider

provider =
  # This will work on JavaScript and CoffeeScript files, but not in js comments.
  selector: '.source.js, .source.coffee'
  disableForSelector: '.source.js .comment'

  # This will take priority over the default provider, which has an inclusionPriority of 0.
  # `excludeLowerPriority` will suppress any providers with a lower priority
  # i.e. The default provider will be suppressed
  inclusionPriority: 1
  excludeLowerPriority: true

  # This will be suggested before the default provider, which has a suggestionPriority of 1.
  suggestionPriority: 2

  # Let autocomplete+ filter and sort the suggestions you provide.
  filterSuggestions: true

  # Required: Return a promise, an array of suggestions, or null.
  getSuggestions: ({editor, bufferPosition, scopeDescriptor, prefix, activatedManually}) ->
    new Promise (resolve) ->
      resolve([text: 'something'])

  # (optional): (*experimental*) called when the user selects a suggestion for
  # the purpose of loading additional information about the suggestion.
  getSuggestionDetailsOnSelect: (suggestion) ->
    new Promise (resolve) ->
      resolve(newSuggestion)

  # (optional): called _after_ the suggestion `replacementPrefix` is replaced
  # by the suggestion `text` in the buffer
  onDidInsertSuggestion: ({editor, triggerPosition, suggestion}) ->

  # (optional): called when your provider needs to be cleaned up. Unsubscribe
  # from things, kill any processes, etc.
  dispose: ->

The properties of a provider:

  • selector (required): Defines the scope selector(s) (can be comma-separated) for which your provider should receive suggestion requests
  • getSuggestions (required): Is called when a suggestion request has been dispatched by autocomplete+ to your provider. Return an array of suggestions (if any) in the order you would like them displayed to the user. Returning a Promise of an array of suggestions is also supported.
  • getSuggestionDetailsOnSelect (optional): (experimental) Is called when a suggestion is selected by the user for the purpose of loading more information about the suggestion. Return a Promise of the new suggestion to replace it with or return null if no change is needed.
  • disableForSelector (optional): Defines the scope selector(s) (can be comma-separated) for which your provider should not be used
  • inclusionPriority (optional): A number to indicate its priority to be included in a suggestions request. The default provider has an inclusion priority of 0. Higher priority providers can suppress lower priority providers with excludeLowerPriority.
  • excludeLowerPriority (optional): Will not use lower priority providers when this provider is used.
  • suggestionPriority (optional): A number to determine the sort order of suggestions. The default provider has a suggestion priority of 1
  • filterSuggestions (optional): If set to true, autocomplete+ will preform fuzzy filtering and sorting on the list of matches returned by getSuggestions.
  • dispose (optional): Will be called if your provider is being destroyed by autocomplete+
  • onDidInsertSuggestion (optional): Function that is called when a suggestion from your provider was inserted into the buffer.
    • editor: The {TextEditor} your suggestion was inserted in
    • triggerPosition: A {Point} where autocomplete was triggered
    • suggestion: The suggestion object that was inserted

Support for Asynchronous Request Handling

Some providers satisfy a suggestion request in an asynchronous way (e.g. it may need to dispatch request to an external process to get suggestions). To asynchronously provide suggestions, simply return a Promise from your getSuggestions:

getSuggestions: (options) ->
  return new Promise (resolve) ->
    # Build your suggestions here asynchronously...
    resolve(suggestions) # When you are done, call resolve and pass your suggestions to it

The Suggestion Request's Options Object

An options object will be passed to your getSuggestions function, with the following properties:

  • editor: The current {TextEditor}
  • bufferPosition: The position of the cursor
  • scopeDescriptor: The {ScopeDescriptor} for the current cursor position
  • prefix: The word characters immediately preceding the current cursor position
  • activatedManually: Whether the autocomplete request was initiated by the user (e.g. with [[Ctrl+Space]])

Suggestions

provider =
  selector: '.source.js, .source.coffee'
  disableForSelector: '.source.js .comment'

  getSuggestions: ({editor, bufferPosition, scopeDescriptor, prefix}) ->
    new Promise (resolve) ->
      # Find your suggestions here
      suggestion =
        text: 'someText' # OR
        snippet: 'someText(${1:myArg})'
        displayText: 'someText' # (optional)
        replacementPrefix: 'so' # (optional)
        type: 'function' # (optional)
        leftLabel: '' # (optional)
        leftLabelHTML: '' # (optional)
        rightLabel: '' # (optional)
        rightLabelHTML: '' # (optional)
        className: '' # (optional)
        iconHTML: '' # (optional)
        description: '' # (optional)
        descriptionMoreURL: '' # (optional)
        characterMatchIndices: [0, 1, 2] # (optional)
      resolve([suggestion])

Your suggestions should be returned from getSuggestions as an array of objects with the following properties:

  • text (required; or snippet): The text which will be inserted into the editor, in place of the prefix.
  • snippet (required; or text): A snippet string. This will allow users to tab through function arguments or other options. e.g. 'myFunction(${1:arg1}, ${2:arg2})'. See the {snippets} package for more information.
  • displayText (optional): A string that will show in the UI for this suggestion. When not set, snippet || text is displayed. This is useful when snippet or text displays too much, and you want to simplify. e.g. {type: 'attribute', snippet: 'class="$0"$1', displayText: 'class'}
  • replacementPrefix (optional): The text immediately preceding the cursor, which will be replaced by the text. If not provided, the prefix passed into getSuggestions will be used
  • type (optional): The suggestion type, it will be converted into an icon shown against the suggestion. Predefined styles exist for variable, constant, property, value, method, function, class, type, keyword, tag, snippet, import, require. This list represents nearly everything being colorized.
  • leftLabel (optional): This is shown before the suggestion. Useful for return values.
  • leftLabelHTML (optional): Use this instead of leftLabel if you want to use html for the left label.
  • rightLabel (optional): An indicator (e.g. function, variable) denoting the "kind" of suggestion this represents.
  • rightLabelHTML (optional): Use this instead of rightLabel if you want to use html for the right label.
  • className (optional): Class name for the suggestion in the suggestion list. Allows you to style your suggestion via CSS, if desired.
  • iconHTML (optional): If you want complete control over the icon shown against the suggestion. e.g. iconHTML: '<i class="icon-move-right"></i>'. THe background color of the icon will still be determined (by default) from the type.
  • description (optional): A doc-string summary or short description of the suggestion. WHen specified, it will be displayed at the bottom of the suggestions list.
  • descriptionMoreURL (optional): A url to the documentation or more information about this suggestion. WHen specified, a More.. link will be displayed in the description area. autocomplete-description
  • characterMatchIndices (optional): A list of indexes where the characters in the prefix appear in this suggestion's text. e.g. "foo" in "foo_bar" would be [0, 1, 2].

Registering your provider with autocomplete+

API 4.0.0

In your package.json add:

"providedServices": {
  "autocomplete.provider": {
    "versions": {
      "4.0.0": "provide"
    }
  }
}

THen, in your main.coffee (or whatever file you define as your main in package.json i.e. "main": "./lib/your-main" would imply your-main.coffee), add the following:

For a single provider:

module.exports =
  provide: -> @yourProviderHere

For multiple providers, just return an array:

module.exports =
  provide: -> [@yourProviderHere, @yourOtherProviderHere]

Provider Examples

These providers are bundled within the Pulsar repository:

  • {autocomplete-css}
  • {autocomplete-html}
  • {autocomplete-snippets}

Check out the lib directory in each of these for the code!

Tips

Generating a new prefix

The prefix passed to getSuggestions may not be sufficient for your language. You may need to generate your own prefix. Here is a pattern to use your own prefix:

provider =
  selector: '.source.js, .source.coffee'

  getSuggestions: ({editor, bufferPosition}) ->
    prefix = @getPrefix(editor, bufferPosition)

    new Promise (resolve) ->
      suggestion =
        text: 'someText'
        replacementPrefix: prefix
      resolve([suggestion])

  getPrefix: (editor, bufferPosition) ->
    # Whatever your prefix regex might be
    regex = /[\w0-9_-]+$

    # Get the text for the line up to the triggered buffer position
    line = editor.getTextInRange([[bufferPosition.row, 0], bufferPosition])

    # Match the regex to the line, and return the match
    line.match(regex)?[0] or ''

SymbolProvider Config API - Docs for supporting your language in the default SymbolProvider

The builtin SymbolProvider allows showing the types of symbols in the suggestion list.

symbol-provider-notes

The icon colors are intended to match the syntax color of the symbol type. e.g. functions are blue in this theme, so the function icon is also blue.

Each language can tune how the SymbolProvider tags symbols by modifying the config of the language package.

# An example for the CoffeeScript language
'.source.coffee':
  autocomplete:
    symbols:
      class:
        selector: '.class.name, .inherited-class, .instance.type'
        typePriority: 4
      function:
        selector: '.function.name'
        typePriority: 3
      variable:
        selector: '.variable'
        typePriority: 2
      '': # the catch-all
        selector: '.source'
        typePriority: 1
      builtin:
        suggestions: [
          'one'
          'two'
        ]

A more generic example:

'.source.language':
  autocomplete:
    symbols:
      typename1:
        selector: '.some, .selectors'
        typePriority: 1
      typename2:
        suggestions: [...]
      typename3:
        ...

Any number of Typename objects are supported, and typename can be anything you choose. However, you are encouraged to use one of the predefined typenames. There are predefined styles for the following types:

  • bultin
  • class
  • constant
  • function
  • import
  • keyword
  • method
  • module
  • mixin
  • package
  • property
  • require
  • snippet
  • tag
  • type
  • value
  • variable

Typename Objects

Typename objects support the following properties:

  • selector: The selector that matches your symbol types. e.g. '.variable.name'. You can also have several selectors separated by commas, just like in CSS '.variable.name, .storage.variable'
  • typePriority: The priority this Typename object has over others. e.g. in our CoffeeScript example above, if a symbol is tagged with the function type in one part of the code, but class in another part of the code, it will be displayed to the user as a class because class has a higher typePriority
  • suggestions: This allows you to specify explicit completions for some scope. A good use is builtins: e.g. ['Math', 'Array', ...] in JavaScript.
    • Items in the suggestions list can also be objects using any of the properties from the provider API.

Finding Scope Selectors

Coming up with the selectors for a given Typename object might be the hardest part of defining the autocomplete.symbols config. Fortunately there is a tool to help.

Open the {Command Palette}, then search for log cursor scope. You will be presented with a blue box like the following:

scopenames

Each bullet in the box is a node. The last bullet is the symbol itself, and each preceding line is a parent of the symbol — just like CSS. With this information, you can see that the symbol can be matched with several selectors: '.variable', '.variable.assignment', '.source.coffee .variable', etc.

Autocomplete Providers - A list of the providers out there

::: warning Warning

The below list was originally pulled from the atom/autocomplete-plus wiki and has not been updated sense. It is still a wonderful starting point to find out about the different autocompletion providers that exist, but it should not be considering comprehensive.

:::

While this list serves as a jumping off point into known quality packages, the Pulsar Package Registry allows you to easily search for all Autocomplete Providers published.

Built-In Providers

Grammar Selector Provider Status
All * SymbolProvider Default Provider
All * FuzzyProvider Deprecated

Providers for Built-In Grammars

Grammar Selector Provider API Status
Null Grammar .text.plain.null-grammar    
CoffeeScript (Literate) .source.litcoffee
CoffeeScript .source.coffee
JSON .source.json
Shell Session .text.shell-session
Shell Script .source.shell
Hyperlink .text.hyperlink
TODO .text.todo
C .source.c autocomplete-clang
C++ .source.cpp autocomplete-clang 2.0.0
Clojure .source.clojure proto-repl
CSS .source.css autocomplete-css 2.0.0
GitHub Markdown .source.gfm autocomplete-bibtex 1.1.0
Git Config .source.git-config
Git Commit Message .text.git-commit
Git Rebase Message .text.git-rebase
HTML (Go) .text.html.gohtml
Go .source.go go-plus, autocomplete-go 2.0.0
Go Template .source.gotemplate
HTML .text.html.basic autocomplete-html 2.0.0
JavaScript .source.js atom-ternjs 2.0.0
Java Properties .source.java-properties
Regular Expressions (JavaScript) .source.js.regexp
JavaServer Pages .text.html.jsp autocomplete-jsp 2.0.0
Java .source.java autocomplete-java-minus 2.0.0
JUnit Test Report .text.junit-test-report
Makefile .source.makefile
LESS .source.css.less
SQL (Mustache) .source.sql.mustache
HTML (Mustache) .text.html.mustache
Objective-C++ .source.objcpp autocomplete-clang
Strings File .source.strings
Objective-C .source.objc autocomplete-clang
Property List (XML) .text.xml.plist
Property List (Old-Style) .source.plist
Perl .source.perl
PHP .text.html.php
PHP .source.php php-integrator-autocomplete-plus, atom-autocomplete-php, autocomplete-php 2.0.0
Python Console .text.python.console
Python Traceback .text.python.traceback
Regular Expressions (Python) .source.regexp.python
Python .source.python autocomplete-python, autocomplete-python-jedi
Ruby on Rails (RJS) .source.ruby.rails.rjs
Ruby .source.ruby
HTML (Ruby - ERB) .text.html.erb
HTML (Rails) .text.html.ruby
SQL (Rails) .source.sql.ruby
JavaScript (Rails) .source.js.rails .source.js.jquery
Ruby on Rails .source.ruby.rails
Sass .source.sass
Plain Text .text.plain
SCSS .source.css.scss
SQL .source.sql autocomplete-sql 2.0.0
TOML .source.toml
XSL .text.xml.xsl
XML .text.xml autocomplete-xml 2.0.0
YAML .source.yaml

Providers For Third-Party Grammars

Grammar Selector Provider API Status
Apex .source.apex mavensmate-atom 1.0.0
AsciiDoc .source.asciidoc autocomplete-asciidoc 2.0.0
C# .source.cs omnisharp-atom 2.0.0
ComputerCraft .source.computercraft autocomplete-computercraft 1.0.0
Curry .source.curry autocomplete-curry 4.0.0
Dart .source.dart dart-tools
Dart .source.dart dartlang
Elixir .source.elixir autocomplete-elixir 2.0.0
Erlang .source.erlang autocomplete-erlang 2.0.0
GLSL .source.glsl autocomplete-glsl 2.0.0
HackLang .source.hack autocomplete-hack 2.0.0
Haskell .source.haskell autocomplete-haskell 1.0.0
Haskell .source.haskell ide-haskell 1.0.0
Haxe .source.haxe autocomplete-haxe 1.1.0
LaTeX .text.tex.latex autocomplete-latex-cite, autocomplete-latex-references, autocomplete-glossaries 2.0.0
Marko .text.marko autocomplete-marko 2.0.0
Nunjucks .source.nunjucks, .text.html.nunjucks autocomplete-nunjucks 2.0.0
Pig .source.pig pig 2.0.0
Q/K .source.q autocomplete-kdb-q 2.0.0
Rust .source.rust racer 2.0.0
Turtle .source.turtle turtle-completer 2.0.0
TypeScript .source.ts atom-typescript 8.11.0
Visualforce .visualforce mavensmate-atom 1.1.0
WordPress Coding Standard Whitelist Flags .php .comment autocomplete-wpcs-flags 2.0.0

Providers Not Tied To A Specific Grammar

Selector Provider Status
* autocomplete-emojis 1.0.0
* autocomplete-snippets 2.0.0
* autocomplete-paths 1.0.0
* atom-path-intellisense 1.2.1
* atom-ctags 2.0.0
.source.js, .source.jsx ide-flow 1.1.0
.source.js, .source.jsx, .source.coffee autocomplete-underdash 2.0.0
.source.css, .source.css.less, .source.sass, .source.css.scss, .source.stylus project-palette-finder 1.1.0
* you-complete-me 2.0.0
English word autocompletion with the hint of explanation. autocomplete-en-en 2.0.0

--

Providers Requested By The Community

If you'd like to contribute and are interested in learning how to write an autocomplete-plus Provider, start here:

Packages That Claim Autocomplete, But Are Not API 1.0.0 Compatible

Deprecated Providers

If you are using one of these providers, please uninstall the package as it is no longer maintained.

Other Forks Of Autocomplete