# orion.edit.command

The `orion.edit.command` service is the simplest kind of editor extension. An editor command simply provides a function that takes some editor text as input, performs some operation or transformation on the text, and returns a new text value. The command can also optionally receive and return selection information for changing the editor selection.

## Service methods

Implementations of `orion.edit.command` must define the following function:

run(selectedText, text, selection, resource)
  selectedText is a string containing the text that is currently selected in the editor. The `text` argument provides the entire editor buffer. The `selection` argument is a selection object with `start` and `end` fields. The `resource` argument describes the full path name of the text being edited. The return value is either a string which will replace the current editor selection, or an object. The object must have a `text` property which will be the replacement string for the entire editor buffer, and may optionally have a `selection` object indicating the new selection value.

## Service attributes

Implementations of `orion.edit.command` may define the following attributes:

name
  `String` The command text to show to the user.
id
  `String` The id of the command contribution.
tooltip

`String` Optional. A tooltip describing the command.

img
  `String` Optional. The URL of an icon to associate with the command. The icon may not appear in all situations. For example, the main toolbar may not show the icon, but a menu item might show the icon.
key
  `Array` Optional. A key binding for the command. The structure of this array matches the arguments of the `orion.textview.KeyBinding` constructor. See its entry in the Client API reference for details.
validationProperties
  `Array` Optional. An array Validation Properties that must match the editor's file in order for the command to appear.
contentType
  `Array` Optional. An array of Content Type IDs for which this command is valid.

## Examples

The following simple example just converts the selected text to upper case. In this example the function return value is a simple string, so this is interpreted by the editor as replacement for the original editor selection. In the service properties, we see the command provides a key binding of Ctrl+U (or Cmd+U on Mac).

     var provider = new eclipse.PluginProvider();
     provider.registerServiceProvider("orion.edit.command", {
       run : function(text) {
         return text.toUpperCase();
       }
     }, {
       name : "UPPERCASE",
       img : "/images/gear.gif",
       key : [ "u", true ]
     });
     provider.connect();

Here is an example of a slightly more complex run function that takes the selection and wraps it in C-style block comments. In this example the function returns a complex object with both `text` and `selection` fields. These are interpreted by the editor as the new editor buffer contents, and the new editor selection. A content type is used so that this command is only available for javascript files.

     contentType: ["application/javascript"],
     run : function(selectedText, text, selection) {
       return {text: text.substring(0,selection.start) + "/*" +
         text.substring(selection.start,selection.end) + "*/" +
         text.substring(selection.end),
         selection: {start:selection.start,end:selection.end+4}};
     }