Org-mode: Index dynamique de documents Org-mode

Pour le formatage des éléments de la liste, on pourra indiquer une chaine de caractère avec le paramètre :format. Cette chaine sera utilisée pour chacun des éléments.

Dans cette chaine de caractère, on aura accès à des gabarits, comme le titre, la description ou le chemin vers le fichier. Certains de ces gabarits reprennent la valeur des mots-clés présents dans les documents Org-mode trouvés.

Les gabarits suivants seront utilisable:

Exemple de chaine de formatage:

"%d: [[%p][%t]]"

Et voici ce que donnerait cette exemple une fois formaté:

2023.07.05: Org-mode: Dynamic block

Voici un exemple d'utilisation d'un bloc de type index:

#+BEGIN index :directory "posts/"

#+END

Et voici un exemple de ce que le bloc va générer:

#+BEGIN: index :directory "posts/"
- 2023.07.05 : Org-mode: Dynamic block
- 2023.07.03 : Org-mode: Dupliquer une note
- 2023.06.06 : Fedora: OSTree Native Container
- 2023.05.09 : Org-noter
- 2023.04.30 : Ouverture
#+end

Pour chaque fichiers trouvés dans le dossier parcouru, il faudra récupérer les mots-clés ainsi que le chemin vers le fichier. On doit donc générer, pour chaque document Org-mode, une liste d'informations.

Ici, j'ai choisi le format associated list, ou alist. Il s'agit d'une liste, où chaque élément est lui-même une liste dans laquelle on trouve 2 éléments. Le premier élément sert de clé, le second de valeur associée. D'où le nom associated list.

Voici un exemple de alist:

'(("TITLE" "Titre de mon document")
  ("DATE" "2023.07.08"))

Je vais donc créer une première fonction Emacs-Lisp, dont le but sera d'extraire les informations d'un seul fichier. Cette fonction nous retournera ces informations sous la forme d'une alist. Sa signature sera: (my/org-index-extract-infos file-path). Son seul paramètre d'entrée, file-path, est une chaine de caractère représentant le chemin vers le fichier.

• Fonction: (my/org-index-extract-infos file-path)
• Paramètres:
  • file-path: Chemin vers le fichier à analyser
• Retour:
  • Une alist de toutes les informations extraites du document analysé

Pour la deuxième fonction, je vais en créer une qui retournera la liste des fichiers Org-mode trouvés dans un dossier. Sa signature est: (my/org-index-get-file-paths-list directory). Son seul paramètre, directory, est le chemin vers le dossier à parcourir. Sous forme de chaine de caractère.

• Fonction: (my/org-index-get-file-paths-list directory)
• Paramètres:
  • directory: Chemin vers le dossier à parcourir
• Retour:
  • Une liste de chemins, sous la forme d'une chaine de caractère

Cette fonction ne donnera que le chemin vers chaque document Org-mode. Mais je pourrais utiliser la fonction (mapcar), pour exécuter la fonction d'extraction sur chaque chemin retourné par la fonction de parcours.

Il me faudra aussi une fonction capable de trier la liste de plusieurs alist, selon le critère de trie définit dans la section "Objectif" de ce billet.

• Fonction: (my/org-index-sort-documents documents-list)
• Paramètres:
  • documents-list: La liste des documents Org-mode, sous la forme d'une liste de plusieurs alist
• Retour:
  • La liste des documents Org-mode, triés selon la date

Pour rappelle, le bloc dynamique devra générer une liste, au format Org-mode, de tout les documents Org-mode trouvés.

Mais chaque éléments de cette liste devra être formaté en utilisant une chaine de caractère. (Voir section Formatage des éléments de la liste).

Pour ça, je dois créer une fonction nommée (my/org-index-format-element document-alist format-str) qui s'occupera de formater une chaine de caractère. Le premier argument est une alist de toutes les informations sur un seul document. Le second argument est la chaine de caractère utilisée pour le formatage.

• Fonction: (my/org-index-format-element document-infos fmt)
• Paramètres:
  • document-infos: Les information d'un document Org-mode trouvé, au format alist
  • fmt: La chaine de caractère utilisée pour le formatage
• Retour:
  • Une chaine de caractère formatée, à insérer dans le bloc dynamique

Ensuite, je vais créer la fonction (org-dblock-write:index params), qui va insérer le contenu du bloc dynamique. Elle utilisera les fonctions précédemment écrites, pour récupérer toutes les informations nécessaires sur chacun des fichiers Org-mode trouvés dans le dossier parcouru. Elle utilisera ensuite les fonctions (mapcar), (insert) et (format-spec) pour générer le contenue du block, à partir des informations extraites et de la chaine de formatage.

En enfin, j'intégrerai le nouveau type de bloc avec la fonction org-dynamic-block-insert-dblock.

Voici la fonction, (my/org-index-extract-infos), qui va récupérer toutes les informations utiles d'un seul fichier Org-mode:

(defun my/org-index-extract-infos (file-path)
  "Extract, from one file, all the info needed for building an index"
  (with-temp-buffer
    (insert-file-contents file-path)
    (append
     (org-element-map (org-element-parse-buffer) 'keyword
       (lambda (keyword)
         (list
          (org-element-property :key keyword)
          (org-element-property :value keyword))))
     (list (list "FILE-PATH" file-path)
           (list "FILE-FULL-PATH" (expand-file-name file-path))))))

Le paramètre d'entrée est file-path, le chemin vers le fichier à traiter. Le retour est une alist représentant toutes les informations extraites du fichier.

Il faut l'écrire dans le fichier index-test.el.

Maintenant, une explication du code.

Voici la fonction, (my/org-index-list-files-path), qui va trouver tous les documents Org-mode d'un dossier:

(defun my/org-index-list-files-path (directory)
  "Get relative path of all Org-mode document of a directory"
  (mapcar
   (lambda (file-name)
     (concat directory file-name))
   (directory-files directory nil ".org$")))

Cette fonction reçoit comme paramètre le chemin vers le dossier à parcourir. Elle retourne une liste de chemins, un vers chaque document Org-mode trouvé.

Il faut l'écrire dans le fichier index-test.el.

Cette fonction va appeler (directory-files) en lui indiquant:

• Le dossier à parcourir (premier paramètre)
• De ne pas retourner des chemins absolues (deuxième paramètre)
• La regex à utiliser pour trouver les fichiers qui nous intéressent (troisième paramètre)

La fonction (directiory-files) retourne les noms des fichiers trouvés, sous la forme d'une liste de chaines de caractères. Mais on souhaite avoir une liste de chemins vers chaque documents, pas uniquement les noms des fichiers.

C'est pour cela qu'on utilise (mapcar): Pour chaque nom de fichier trouvés par (directory-files), on exécute la fonction anonyme suivante:

(lambda (file-name)
  (concat directory file-name))

Cette fonction va simplement concaténer le chemin vers le dossier parcourus et le nom du fichier trouvé.

Le résultat de chaque exécution de la fonction anonyme est ajouté à une liste retournée par (mapcar). Et c'est cette liste que notre fonction retourne.

Voici la fonction de trie, (my/org-index-sort-documents documents-list):

(defun my/org-index-sort-documents (documents-list)
  "Sort an Org-documents list by its date"
  (sort
   documents-list
   (lambda (file-a file-b)
     (string>
      (car (cdr (assoc '"DATE" file-a)))
      (car (cdr (assoc '"DATE" file-b)))))))

Elle accepte une liste de alist et retourne la liste triée. Elle utilise la fonction (sort), à laquelle on a passé 2 paramètres: La liste à trier et une fonction utilisée pour faire la comparaison entre 2 éléments à trier.

Il faut l'écrire dans le fichier index-test.el.

La fonction de trie est une fonction anonyme et ressemble à ceci:

(lambda (file-a file-b)
  (string>
   (car (cdr (assoc '"DATE" file-a)))
   (car (cdr (assoc '"DATE" file-b)))))

Elle accepte comme paramètres les 2 éléments à comparer et utilise la fonction (string>) pour comparer les dates. Ici, pour des raisons de simplification, on va traiter les dates comme de simples chaines de caractères.

Pour extraire la date de file-a et file-b, qui sont des alist, on utilise la fonction (assoc). En indiquant la clé '"DATE", (assoc) nous renvoie la cellule dont le premier élément est "DATE". Ce qui nous donne, par exemple: ("DATE" "2023.07.08"). On utilise ensuite (cdr) pour extraire le deuxième élément de la cellule.

(cdr) retourne toujours la liste qu'on lui donne, sans le premier élément. Dans le cas d'une liste de 2 éléments, il nous retourne donc une liste d'un seul élément. C'est pour ça qu'on utilise (car), pour extraire ce seul élément de la liste.

Voici le code de la fonction (my/org-index-format-element document-infos fmt):

(defun my/org-index-format-element (document-infos fmt)
  "Generate a string with document infos"
  (format-spec
   fmt
   (list (cons ?t (car (cdr (assoc '"TITLE" document-infos))))
         (cons ?d (car (cdr (assoc '"DATE" document-infos))))
         (cons ?a (car (cdr (assoc '"AUTHOR" document-infos))))
         (cons ?c (car (cdr (assoc '"CREATOR" document-infos))))
         (cons ?D (car (cdr (assoc '"DESCRIPTION" document-infos))))
         (cons ?p (car (cdr (assoc '"FILE-PATH" document-infos))))
         (cons ?P (car (cdr (assoc '"FILE-FULL-PATH" document-infos))))
         (cons ?l (car (cdr (assoc '"LANGUAGE" document-infos))))
         (cons ?o (car (cdr (assoc '"OPTIONS" document-infos)))))))

Pour rappelle, cette fonction accepte 2 paramètres: Les informations sur un document (document-infos), au format alist, et la chaine de caractère servant au formatage. Elle retourne la chaine de caractère formatée.

Il faut l'écrire dans le fichier index-test.el.

Pour le formatage, on utilise la fonction (format-spec) avec 2 paramètres: La chaine de caractère de formatage et la liste des gabarits.

La liste de gabarits est une alist, où les cellules utilisent un caractère . pour séparer la clé et la valeur.

Exemple de liste de gabarit :

'((?t . "Title of document")
  (?a . "Name of the author"))

On doit construire cette liste et associer chaque informations extraites du document avec une lettre de gabarit.

On arrive presque à la fin. Accroche toi, c'est bientôt terminé.

Voici le code de la fonction (org-dblock-write:index), qui sert à écrire le contenu d'un bloc de type index:

(defun org-dblock-write:index (params)
  "Generate an index of a director, as a list"
  (let ((directory (or
                    (plist-get params :directory )
                    (file-name-directory (buffer-file-name))))
        (sort-recent (plist-get params :sort-recent))
        (fmt (or (plist-get params :format) "%d: [[file:%p][%t]]"))
        (documents-infos nil))
    (if sort-recent
        (setq documents-infos (my/org-index-sort-documents
                               (mapcar
                                'my/org-index-extract-infos
                                (my/org-index-list-files-path directory))))
      (setq documents-infos (mapcar
                             'my/org-index-extract-infos
                             (my/org-index-list-files-path directory))))
    (mapcar
     (lambda (one-document-infos)
       (insert
        "- "
        (my/org-index-format-element one-document-infos fmt)
        "\n"))
     documents-infos)))

Cette fonction sera appelée directement par Org-mode, quand on demandera à générer le contenu d'un bloc de type index. Elle recevra tout les paramètres du bloc avec le paramètre params et elle va simplement insérer du texte: La liste, au format Org-mode, représentant tous les documents Org-mode trouvés.

Il faut l'écrire dans le fichier index-test.el.

Cette fonction est séparée en 3 parties: Définition des variables locales, récupération des informations sur chaque documents Org-mode et génération de la liste au format Org-mode.

Avec le code décrit jusque là, on a tout ce qu'il faut pour avoir un bloc de type index fonctionnel. Mais on aimerait aussi pouvoir demander à Emacs de créer un bloc de type index à notre place, après avoir demandé le chemin vers le dossier à parcourir.

Pour ça, ajoutez ce code au fichier index-test.el:

(defun my/org-index-insert-dblock (directory)
  "Insert a new dynamic bloc of type index"
  (interactive
   (list (string-replace
          (file-name-directory (buffer-file-name))
          ""
          (expand-file-name (read-directory-name "Dirictory to build index on: ")))))
  (org-create-dblock
   (list :name "index"
         :directory directory)))

(org-dynamic-block-define "Index" 'my/org-index-insert-dblock)

Ici, on déclare une nouvelle fonction interactive, nommée (my/org-index-insert-dblock). Elle accepte un paramètre: directory. Ce paramètre sera répété, comme paramètre du bloc écrit par cette fonction.

On peut distinguer 2 parties dans cette fonction:

• La partie que demande à l'utilisateur/utilisatrice quel dossier parcourir
• La partie qui crée le bloc dynamique

Pour insérer un bloc de type index dans un document Org-mode, on doit:

• Ouvrir le document
• Placer le curseur d'écriture là où on souhaite insérer le bloc
• Appeler org-dynamic-block-insert-dblock (raccourcis C-c C-x x)
• Choisir Index
• Indiquer le dossier à parcourir

Emacs va ensuite insérer un nouveau bloc:

#+BEGIN: index :directory "posts/"

#+END:

On peut également écrire sois-même le bloc, ou appeler la fonction interactive (my/org-index-insert-dblock).

Pour générer le contenu, on place le curseur d'écriture sur la ligne #+BEGIN: et on appelle le raccourcis clavier C-c C-c.

Voici le résultat de notre exemple:

#+BEGIN: index :directory "posts/"
- 2023.06.08 : Article 1
- 2023.07.04 : Article 2

#+END:

Si on ajoute le paramètre :sort-recent t au bloc et qu'on génère à nouveau le contenu:

#+BEGIN: index :directory "posts/" :sort-recent t
- 2023.07.04 : Article 2
- 2023.06.08 : Article 1

#+END: