Cambiar idioma: English

Complementos

See also

Referencia: API
Más información acerca de la API de Python.
Referencia: Complementos
Más información acerca de los complementos.

_st es programable con Python. Los complementos utilizan instrucciones existentes o crean otras nuevas para componer una función nueva. Los complementos son una entidad lógica, no física.

Prerrequisitos

Para escribir complementos, es necesario conocer el lenguaje Python.

Dónde guardar los complementos

_st buscará complementos en las siguientes ubicaciones:

  • Packages
  • Packages/<nombre_módulo>/

En consecuencia, no encontrará los complementos en directorios más profundos de Packages.

No es recomendable guardar complementos directamente en Packages porque _st ordena los módulos antes de cargarlos, y, por lo tanto, el resultado podría ser inesperado.

Un complemento sencillo

A continuación, escribiremos un complemento muy simple para _st:

  1. selecciona Tools | New Plugin… en el menú;
  2. guardar el archivo como Packages/User/hello_world.py.

Listo. Ya has escrito tu primer complemento. Veamos cómo utilizarlo:

  1. crea un búfer nuevo (Ctrl+n);
  2. abre la consola de Python (Ctrl+`);
  3. teclea view.run_command("example") y presiona intro.

Deberías ver el texto “Hello, World!” en el nuevo búfer.

Análisis del complemento

El complemento creado en la sección anterior debería presentar el siguiente aspecto:

import sublime, sublime_plugin

class ExampleCommand(sublime_plugin.TextCommand):
    def run(self, edit):
        self.view.insert(edit, 0, "Hello, World!")

Los módulos sulbime y sublime_plugin los suministra Sublime Text.

Las instrucciones derivan de las clases *Command definidas en sublime_plugin (más adelante se proporciona más información).

El resto del código consiste en particularidades de TextCommand y de la API, aspectos que trataremos en las siguientes secciones.

Sin embargo, antes de continuar, observemos cómo hemos ejecutado la nueva instrucción: En primer lugar, hemos abierto la consola de Python para realizar una llamada a view.run_command(). Este no es un método muy práctico de utilizar los complementos, pero es un recurso útil durante su creación. Por el momento, baste decir que las instrucciones que creemos son accesibles mediante combinaciones de teclas y otros métodos, al igual que el resto de las instrucciones.

Convenciones en la nomenclatura de instrucciones

Pese a que hemos llamado a nuestra insstrucción ExampleCommand en su definición, hemos pasado la cadena example a la función de la API. Esta asimetría está impuesta por Sublime Text: los nombres de las instrucciones se unifican de tal manera que se elimina el sufijo Command de ellas y las FrasesJorobadas se separan con guiones bajos, como en frases_jorobadas.

Los nombres de las instrucciones creadas deben seguir el mismo patrón..

Tipos de instrucciones

Se pueden crear los siguientes tipos de instrucciones:

  • instrucciones para la aplicación (ApplicationCommand);
  • instrucciones para la ventana (WindowCommand)
  • instrucciones para el búfer (TextCommand)

Antes de crear una nueva instrucción, piensa en su función y selecciona el tipo de instrucción adecuado.

Rasgos comunes de las instrucciones

Todas las instrucciones deben implementar el método .run(). Además, pueden recibir un número arbitrario de parámetros nominados.

Ejemplo:

window.run_command("echo", {"To": "Be", "Or": "Not", "Two": "Bees"})

Instrucciones para la aplicación

Las instrucciones globales derivan de sublime_plugin.ApplicationCommand. Debido al estado de la API en el momento de redactar este texto, no nos extendermos más con este tema.

Instrucciones para la ventana

Las instrucciones para la ventana también pueden realizar operaciones en el búfer, pero requieren la existencia de ninguno para estar disponibles. Por ejemplo, la instrucción básica new_file está definida como WindowCommand, de tal manera que funciona cuando no hay ningún búfer abierto. Lo contrario no tendría sentido.

Instrucciones para el búfer

Estas instrucciones requieren la existencia de un búfer para estar disponibles.

Instrucciones para el búfer y el objeto edit

El objeto edit agrupa modificaciones al búfer para que las macros y la instrucción deshacer funcionen de manera coherente. El programador es responsable de crear y cerrar los objetos edit. A tal efecto, se pueden realizar las llamadas view.begin_edit() y edit.end_edit(). Las instrucciones para el búfer reciben un objeto edit en su método .run() por comodidad. Muchos métodos de View requieren un objeto edit.

Eventos

Las instrucciones derivadas de EventListener pueden reaccionar a eventos.

Ejemplo: Rellenando la lista de sugerencias

A continuación crearemos un complemento que extrae datos del servicio de Google Autocomplete y los inyecta en la lista de sugerencias de Sublime Text. Ten en cuenta que este es un buen ejemplo de una muy mala idea para un complemento real.

import sublime, sublime_plugin

from xml.etree import ElementTree as ET
from urllib import urlopen

GOOGLE_AC = r"http://google.com/complete/search?output=toolbar&q=%s"

class GoogleAutocomplete(sublime_plugin.EventListener):
    def on_query_completions(self, view, prefix, locations):
        elements = ET.parse(
                        urlopen(GOOGLE_AC % prefix)
                    ).getroot().findall("./CompleteSuggestion/suggestion")

        sugs = [(x.attrib["data"],) * 2 for x in elements]

        return sugs

Note

Una vez hayas probado este complemento, bórralo. De lo contrario, interferirá con el sistema de búsqueda de sugerencias de Sublime Text.

Aprendizaje de la API

Para crear complementos, es necesario familiarizarse con la API de Sublime Text, y también con las instrucciones básicas y distribuidas. La documentación sobre estos temas es escasa en el momento de redactar este texto, pero puedes consultar código existente y aprender de él. En particular, el directorio Packages/Default contienen numerosos ejemplos de instrucciones y funciones de la API sin documentar.