Services API

Services API

This page describes the snippets.resolver service, as well as it's subcomponents snippets.resolver.transform and snippets.resolver.variable. You can provide whatever you like using the base service, or use the subservices to provide a specific kind of resolver more directly.

Regardless of which you use, any transform and variable providers you register will automatically be removed when your package is deactivated.

snippets.resolver v0.0.0

The API for providing custom named transformation and variable evaluation. To use, add the method provideSnippetsResolver (or whatever name you prefer) to your package main module, and add following to your packages package.json file

"providedServices": {
  "snippets.resolver": {
    "versions": {
      "0.0.0": "provideSnippetsResolver"
    }
  }
},

This provider should return a single object. This object can have the following optional keys:

• transformResolver (see snippets.resolver.transform)
• variableResolver (see snippets.resolver.variable)

snippets.resolver.transform v0.0.0

Use this to provide custom named transforms. These are transforms of the form ${1:/upcase} inside of transformation replacement definitions.

This API takes an object of the following form:

• priority: A number indicating the priority of this resolver. The default resolver has a priority of -1. Resolvers with higher priority values are tried before those with lower.
• resolver: A function, or an object with a resolve method. Either will be called with 3 arguments:
  • name: The name of the named transform. E.g., if the backreference is ${1:/upcase} then the name is upcase.
  • input: The string value of the capture group used in this transform.
  • context: See below.

If no resolver with higher priority has resolved the input, then this resolver will be called. There is no need to indicate the transform names it accepts; this can be determined dynamically in the call. This allows resolvers to decide whether they are case sensitive, and allows a crude form of passing arguments by using special names (e.g., date__yycmmcdd might be interpreted as a date formatted as yy:mm:dd.

If the resolver returns a string value, it is considered to have succeeded and the returned value will be used. Prefer to return undefined to indicate failure, as the possible return value kinds may be increased in future.

The third argument to the resolver is the snippet context object. This is not yet finialised, but the idea is it contains details about the context of the place and moment the snippet was expanded. Currently it has the following properties:

• prefix: The prefix this snippet was expanded with (may be undefined if no prefix was used)
• editor: The TextEditor this snippet was expanded in
• indent: The indent (string) of the line the snippet was expanded on. Note indentation is not automatically applied to resolved values. Autoindent support may possibly be revisited in future (e.g., maybe support return an object with value and autoIndent properties).
• cursor: The Cursor used to expand this snippet. May be undefined if no cursor was used, and may be removed in future.
• selectionRange: The Range of the last selection before the snippet was expanded. Semantically it is intended to be used for TM_SELECTED_TEXT, so refer to TextMate for expected behaviour. It is possibly not implemented correctly yet.
• start: The start Point of the range of text that the snippet was inserted into.
• time: The time (new Date()) this snippet was expanded. Use this instead of Date.now() or similar to ensure all times are consistent. Other properties should be considered private and subject to change / removal.

snippets.resolver.variable v0.0.0

Use this to provide custom variables. Variables are evaluated upon snippet expansion. If you need to react to what the user typed, consider using a named transform resolver.

This API takes an object of the following form:

• priority: A number indicating the priority of this resolver. The default resolver has a priority of -1. Resolvers with higher priority values are tried before those with lower.
• resolver: A function, or an object with a resolve method. Either will be called with 3 arguments:
  • name: The name of the variable. E.g., if the variable is $FOO then the name is FOO.
  • context: See the section under named transforms.

Priority and context are as in the named transform service.