Ajouter du contenu aux carnet : écrire un plugin

Dans toute la suite, nous allons créer un plugin foo, associé au mot-clef foo, qui écrit dans le carnet le contenu de l’argument bar, quasiment sans traitement. Ce plugin se présente sous la forme d’un fichier foo.py (le nom de fichier est libre), présent dans un sous répertoire python/content d’un datadir.

Définition

Un plugin se présente sous la forme d’un fichier Python, présent dans un répertoire python/content (relativement à un des datadir). Ce fichier doit contenir une variable CONTENT_PLUGIN, qui est un dictionnaire dont les clefs sont des mots-clefs, et les valeurs des fonctions parse.

Lors de la compilation du carnet, au moment de l’analyse de la variable content du fichier .sb, lorsqu’un de ces mots-clefs est rencontré, la fonction parse() correspondante est appelée.

Notre plugin d’exemple contient donc le code suivant (où parse() est une fonction, définie plus tôt dans le fichier, dont nous allons parler dans la partie suivante).

CONTENT_PLUGIN = {'foo': parse}

Classe content.Content

L’objet qui produit quelque chose dans le recueil est une instance de la classe content.Content. La méthode d’initialisation est libre, et la méthode principale est la méthode content.Content.render(), qui prend en argument le contexte courant, et renvoie une chaîne de caractères à inclure dans le fichier .tex.

Plus de détails sur cette classe (ainsi que sur les autres méthodes utilisées) sont disponibles dans le docstring de cette classe.

Pour notre exemple, nous allons définir une nouvelle classe Foo, héritant de cette classe content.Content.

from patacrep.content import Content

class Foo(Content):

  def __init__(self, arguments):
    """Fonction d'initialisation

    Le moteur de plugin ne va pas appeler cette fonction directement : chaque
    plugin est donc libre de définir cette initialisation comme il l'entend.
    """
    self.arguments = arguments

  def render(self, __context):
    return self.arguments['bar']

Fonction parse()

La fonction parse() est appelée lorsque le mot clef est rencontré, avec comme arguments :

keyword

le mot clef ayant déclenché l’appel à cette fonction ;

argument

l’argument passé au mot-clef ;

config

le dictionnaire contenant la configuration du recueil en cours de construction. Le modifier est autorisé.

Ainsi, si le contenu du recueil comprend

- foo:
    bar: "something"
    content:
      - "one"
      - "two"

notre fonction parse() sera appelée avec comme arguments parse('foo', “bar”: « something », “content”: [“one”, “two”], config).

Cette fonction doit retourner une liste (éventuellement vide) d’objets de classe content.Content (ou une de ces sous-classes). Ces objets seront intégrés au carnet (en utilisant principalement leur méthode content.Content.render()) dans l’ordre dans lequel ils apparaissent dans cette liste.

Notre fonction va donc être la suivante :

def parse(keyword, argument, config):
  return [Foo(argument)]

Bilan

Notre plugin est maintenant fonctionnel et réagit au mot clé foo.