*if_pyth.txt* For Vim version 6.2c. Dernière modification : 2003 mai 22 MANUEL de RÉFÉRENCE VIM - par Paul Moore L'interface Python de Vim *python* *Python* 1. Les commandes |python-commands| 2. Le module vim |python-vim| 3. Les objets buffer |python-buffer| 4. Les objets range |python-range| 5. Les objets window |python-window| {Vi n'a aucune de ces commandes} L'interface Python n'est disponible que si Vim a été compilé avec la fonctionnalité |+python|. ============================================================================== 1. Les commandes *python-commands* *:python* *:py* *E205* *E263* *E264* :[plage]py[thon] {instr} Exécute une instruction Python {instr}. :[plage]py[thon] << {balisefin} {script} {balisefin} Exécute un script Python {script} NOTE : Cette commande ne fonctionne pas si la fonctionnalité Python n'a pas été activée lors de la compilation. Pour éviter des erreurs, voir |script-here|. {balisefin} ne doit être précédé d'AUCUN espace blanc. Si {balisefin} est omis après le "<<", un point '.' doit être utilisé après {script}, comme pour les commandes |:append| et |:insert|. Cette forme de commandes |:python| est principalement utile pour inclure du code Python dans les scripts Vim. Exemple : > function! IcecreamInitialize() python << EOF class GlaceALaFraise: def __call__(self): print 'Mangez-moi' EOF endfunction < NOTE : Python est très sensible à l'indentation. Par conséquent, faites très attention à ce que les lignes contenant "class" et "EOF" n'aient aucune indentation. *:pyfile* *:pyf* :[plage]pyf[ile] {fichier} Exécute le script Python contenu dans {fichier}. {absent de Vi} Ces deux dernières commandes font essentiellement la même chose : elles exécutent un morceau de code Python, avec la « plage courante » |python-range| fixée à la plage spécifiée. Dans le cas de ":python", le code à exécuter est inclus dans la ligne de commande. Dans le cas de ":pyfile", le code à exécuter est contenu dans le fichier donné en argument. Il n'est pas possible d'utiliser les commandes Python dans le bac-à-sable |sand-box|. Voici quelques exemples : *python-examples* > :python from vim import * :python from string import upper :python current.line = upper(current.line) :python print "Salut" :python str = current.buffer[42] < (NOTE : les modifications - telles que les imports - persistent d'une commande à l'autre, exactement comme dans l'interpréteur Python.) ============================================================================== 2. Le module vim *python-vim* Le code Python accède à toutes les fonctionnalités Vim via le module "vim" (à une exception près, voir plus loin |python-output|). Le module "vim" met à disposition deux méthodes, trois constantes et un objet erreur. Résumé > print "Salut" # affiche un message vim.command(cmd) # exécute une commande Ex w = vim.windows[n] # récupère la fenêtre "n" cw = vim.current.window # récupère la fenêtre courante b = vim.buffers[n] # récupère le tampon "n" cb = vim.current.buffer # récupère le tampon courant w.height = lines # fixe la hauteur de la fenêtre w.cursor = (row, col) # fixe la position du curseur pos = w.cursor # récupère un tuple (row, col) name = b.name # récupère le nom du fichier # associé au tampon line = b[n] # récupère une ligne du tampon lines = b[n:m] # récupère une liste de lignes num = len(b) # récupère le nombre de lignes b[n] = str # insère une ligne dans le tampon b[n:m] = [str1, str2, str3] # insère plusieurs lignes d'un coup del b[n] # efface une ligne del b[n:m] # efface plusieurs lignes > MÉTHODES vim.command(str) *python-command* Exécute la commande Vim "str" (en mode Ex). Retourne None. Exemples : > vim.command("set tw=72") vim.command("%s/aaa/bbb/g") < La définition suivante exécute une commande en mode Normal : > def normal(str): vim.command("normal "+str) # Remarquez l'utilisation des apostrophes simples pour # délimiter une chaîne contenant des doublea-apostrophes. normal('"a2dd"aP') < vim.eval(str) *python-eval* Évalue l'expression "str" en utilisant l'évaluateur interne de Vim (voir |expression|). Retourne le résultat sous la forme d'une chaîne. Exemples : > text_width = vim.eval("&tw") str = vim.eval("12+12") # NB : le résultat est une # chaîne ! utilisez # string.atoi() pour la # convertir en nombre. < OBJET ERREUR *python-error* vim.error Lorsqu'il rencontre une erreur dans Vim, Python lève une exception de type vim.error. Exemple > try: vim.command("put a") except vim.error: # Le registre a est vide < CONSTANTES NOTE : ce ne sont pas réellement des constantes - vous pourriez les réassigner. Mais ce serait stupide, car vous perdriez l'accès aux objets Vim qu'elles référençaient. vim.buffers *python-buffers* Un objet séquence donnant accès la liste des tampons de Vim. Cet objet supporte les opérations suivantes : > b = vim.buffers[i] # Accès par index (en lecture seule) b in vim.buffers # Test d'appartenance n = len(vim.buffers) # Nombre d'éléments for b in vim.buffers: # Accès séquentiel < vim.windows *python-windows* Un objet séquence donnant accès à la liste des fenêtres de Vim. Cet objet supporte les opérations suivantes : > w = vim.windows[i] # Accès par index (en lecture seule) w in vim.windows # Test d'appartenance n = len(vim.windows) # Nombre d'éléments for w in vim.windows: # Accès séquentiel < vim.current *python-current* Un objet donnant accès (via des attributs spécifiques) à divers objets « courants » disponibles dans Vim : vim.current.line La ligne courante (Lect/Écr) String vim.current.buffer Le tampon courant (Lect) Buffer vim.current.window La fenêtre courante (Lect) Window vim.current.range La plage courante (Lect) Range Le dernier objet mérite une petite explication. Lorsqu'une plage a été spécifiée avec les commandes ":python" et ":pyfile", cette plage de lignes devient « la plage courante ». Une plage est un peu comme un tampon, mais dont tous les accès sont restreints à un sous-ensemble de lignes. Voir |python-range| pour plus de détails. SORTIE VENANT DE PYTHON *python-output* Vim affiche toutes les sorties d'un code Python dans la zone de messages de Vim. Les sortie normales apparaissent comme des messages d'information, et les erreurs comme des messages d'erreur. En terme de mise en oeuvre, cela signifie que toutes les sorties vers sys.stdout apparaissent comme des messages d'information (y compris les sorties de l'instruction print), et que toutes les sorties vers sys.stderr apparaissent comme des messages d'erreur (y compris le traçage des erreurs) *python-input* Les entrées (via sys.stdin, input() et raw_input() y compris) ne sont pas supportées, et peuvent provoquer un plantage du programme. Il faudrait vraisemblablement corrigé cela. ============================================================================== 3. Les objets buffer *python-buffer* Les objets "buffer" représentent les tampons de vim. Vous pouvez les obtenir de différentes manières : - via vim.current.buffer (|python-current|) ; - par indexation de vim.buffers (|python-buffers|) ; - par l'attribut "buffer" d'une fenêtre (|python-widow|). Les objets buffer ont un attribut - name - en lecture seule, c'est le nom complet du fichier associé au tampon. Ils possèdent aussi trois méthodes (append, mark, et range ; voir plus loin). Vous pouvez aussi voir les objets buffer comme des objets de type séquence. Dans ce contexte, ils agissent comme s'ils étaient des listes (oui, ils sont mutables) de chaînes, chaque élément étant une ligne du tampon. Toutes les opérations usuelles sur des séquences, y compris l'indexation, l'affectation par indice, les intervalles et affectation par intervalles, fonctionnent comme vous pourriez vous y attendre. NOTE : le résultat d'une indexation (resp. intervalle) d'un tampon est une chaîne (resp. liste de chaînes). Cela a une conséquence inhabituelle - b[:] est différent de b. En particulier, "b[:] = None" efface tout le tampon, tandis que "b = None" met simplement à jour la variable b, sans aucun effet sur le tampon. Les indices de tampon commencent à zéro, comme habituellement en Python. Cela diffère du décompte des lignes de Vim, qui commence à 1. Cette remarque est particulièrement pertinente lorsqu'on manipule des marques (voir plus loin) qui utilisent quant à elles le décompte de Vim. Les méthodes d'un objet buffer sont : b.append(str) Ajoute une ligne au tampon b.append(list) Ajoute une liste de lignes au tampon NOTE : la manière de fournir une liste de chaînes à cette méthode diffèrent des méthodes équivalentes des objets internes de type liste de Python. b.mark(nom) Retourne un tuple (row,col) représentant la position de la marque nommée (peut aussi accéder aux marques []"<>) b.range(s,e) Retourne un objet range (voir |python-range| qui représentent la partie du tampon courant comprise entre les lignes numérotées s et e (incluse). Exemples (en supposant que b est le tampon courant) > b[0] = "Salut !!!" # remplace la première ligne b[:] = None # efface tout le contenu du tampon del b[:] # efface tout le contenu du tampon (comme # ci-dessus) b[0:0] = [ "ligne" ] # ajoute une ligne en haut du tampon del b[2] # efface une ligne (la troisième) b.append("en bas") # ajoute une ligne en bas du tampon n = len(b) # nombre de lignes (row,col) = b.mark('a') # marque nommée r = b.range(1,5) # une partie du tampon < ============================================================================== 4. Les objets range *python-range* Les objets "range" représentent une partie d'un tampon Vim. Vous pouvez les obtenir de plusieurs manières : - via vim.current.range (|python-current|) ; - grâce a la méthode range() d'un objet buffer (|python-buffer|). Les opérations d'un objet range sont pratiquement identiques à celles d'un objet buffer. Toutefois, toutes les opérations sont limitées aux lignes contenues dans la plage correspondante (cet ensemble de lignes peut bien sûr être modifié à la suite d'affectations par intervalle, d'effacements de lignes ou de l'utilisation de la méthode range.append()). A la différence des tampons, les plages n'ont pas d'attribut "name", ni de méthode mark() ou range(). Elles disposent en revanche de la méthode append(), qui ajoute des lignes à la fin de la plage. ============================================================================== 5. Les objets window *python-window* Les objets "window" représentent les fenêtres de Vim. Vous pouvez les obtenir de différentes manières : - via vim.current.window (|python-current|) ; - en indexant vim.windows (|python-windows|). Vous ne pouvez manipuler les objets window que par leurs attributs. Ils n'ont pas de méthode, ni l'interface des objets de type séquence, ni même d'autres interfaces. Les attributs d'une fenêtre sont : buffer (lecture seule) Le tampon affiché dans cette fenêtre cursor (lecture/écriture) La position courante du curseur dans la fenêtre. C'est un tuple (row,col) height (lecture/écriture) La hauteur de la fenêtre en lignes width (lecture/écriture) La largeur de la fenêtre, en colonnes L'attribut height est accessible en écriture uniquement si l'écran est partagé horizontalement. L'attribut width est accessible en écriture uniquement si l'écran est partagé verticalement. ============================================================================== vim:tw=78:ts=8:ft=help:norl: