# The Editor Context object

Orion 4.0 introduces <dfn>Object References</dfn>, which allow two-way communication between a service provider and the host Orion page. An Object Reference exposes functions that a service provider can call to help it fulfill a service contract. Like everything in Orion's service framework, Object References work asynchronously: all functions return Promises and the caller must wait for them to fulfill to an actual value. An Object Reference is valid only during the lifetime of its parent service call. Once the provider has fulfilled the service call, any Object References created for that call are unregistered by the framework, and cannot be used thereafter.

Many of the service APIs documented on this page now provide a special Object Reference, called the <dfn>Editor Context object</dfn>, as the first parameter in their function signatures. The Editor Context object contains various functions to query the state of the Orion editor, and to cause side effects. For example, if a provider needs the text from the editor buffer to fulfill its service contract, it can invoke the Editor Context's getText() method:

    editorContextObject.getText().then(function(text) {
        // Use text to fulfill the provider's service contract
    });

## API versions

The older API signatures are labelled as "Orion 3.0" in the documentation. These are still supported, but date from Orion releases when Object References were not available. It is preferable to use the "Orion 4.0" version of an API whenever available, as these provide greater consistency, are somewhat more efficient, and can be more easily evolved in future releases without changing method signatures.

## Editor Context methods

The Editor Context object provides the following methods:

  getAST(options)
    Resolves to `Object`. Returns an AST for the file being edited, if an AST provider is available. Orion ships with an Esprima AST provider for JavaScript files. Additional providers can be contributed by plugins.
  getCaretOffset()
    Resolves to `Number`. Returns the offset of the editing caret.
  getSelection()
    Resolves to `Selection`. Returns the editor's current selection.
  getText(start?, end?)
    Resolves to `String`. Returns the text in the given range.
  setCaretOffset(offset, show?)
    Resolves to `undefined`. Sets the caret offset. If `show` is true, the editor will scroll to the new caret position.
  setSelection(selection)
    Resolves to `undefined`. Sets the editor's selection.
  setText(text, start?, end?)
    Resolves to `undefined`. Sets the text in the given range.