# orion.edit.command

The `orion.edit.command` service is the simplest kind of editor extension. A command service simply provides a function that takes some 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)
  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.

## Service attributes

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

img
  `String` The URL of an icon to associate with the command.
name
  `String` The command text show to the user.
key
  `Array` An optional 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.

## 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.

     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}};
     }