java-diff-utils : ce que le dépôt permet réellement de faire

Origine et objectif

java-diff-utils est une bibliothèque Java open source pour effectuer des opérations de comparaison entre textes. Le périmètre annoncé couvre le calcul de diffs, l'application de patchs, la génération ou l'analyse de diffs unifiés, et la production de sorties de diff faciles à afficher ensuite, par exemple en vue côte à côte. La README explique que la raison principale de la création de cette bibliothèque était le manque de bibliothèques faciles à utiliser avec toutes les fonctions habituelles nécessaires pour travailler avec des fichiers de diff. Elle s'est inspirée à l'origine de la bibliothèque JRCS et de son module diff, et ce projet est lui-même un fork de java-diff-utils provenant de Google Code Archive. La section Status du dépôt est actuellement vide, donc la README ne précise pas l'état de maintenance ou de publication actuel.

Fonctionnalités principales

Les principales fonctionnalités énumérées dans la README sont le calcul de la différence entre deux textes, l'application et l'annulation d'un patch sur un texte, l'analyse du format unifié, la production de différences lisibles par un humain et la construction de différences en ligne. La bibliothèque ne se limite pas à l'ASCII pur : les tableaux ou listes de tout type qui implémentent correctement hashCode() et equals() peuvent être soumis au différenciateur. Cela signifie que les mêmes opérations de base s'appliquent à d'autres structures de données que les chaînes, tant que l'égalité est définie. La README ne donne pas de détails sur les performances ou l'utilisation en production, donc ces aspects restent à vérifier à partir du code source ou de la documentation.

Algorithmes de diff

Deux algorithmes sont nommés dans la README : l'algorithme de diff de Myers et HistogramDiff, qui utilise la bibliothèque JGit. Par ailleurs, la liste des fonctionnalités mentionne Myers avec amélioration de l'espace linéaire, mais la section Algorithms ne nomme que Myers diff et HistogramDiff. La README indique que l'algorithme peut facilement être remplacé par un autre mieux adapté à vos textes, et que l'auteur a l'intention d'ajouter d'autres implémentations à l'avenir. Aucune version spécifique de Myers ou HistogramDiff n'est fournie et aucun benchmark comparatif n'est inclus.

Exemples avec DiffRowGenerator

La README présente deux exemples construits sur DiffRowGenerator. Dans le premier, le générateur est configuré avec showInlineDiffs(true), mergeOriginalRevised(true), inlineDiffByWord(true), et des fonctions oldTag/newTag qui entourent le texte supprimé et inséré avec des marqueurs de style Markdown. Après avoir appelé generateDiffRows sur deux listes à un élément, l'ancienne ligne est affichée avec le mot modifié marqué. Le deuxième exemple produit un tableau côte à côte en parcourant les lignes et en affichant les anciennes et nouvelles lignes. La README renvoie également à la page Examples du wiki pour plus d'informations, mais elle ne documente pas toute l'API de DiffRowGenerator dans la README elle-même.

Installation et conventions de code

Pour Maven, la README donne une dépendance avec groupId io.github.java-diff-utils, artifactId java-diff-utils et version 4.15. Pour Gradle, elle montre implementation "io.github.java-diff-utils:java-diff-utils:4.12" avec un commentaire renvoyant à Maven Central. Les deux versions diffèrent, donc la coordonnée Gradle actuelle exacte doit être vérifiée. Le code source suit la convention de format Sun Java et utilise des espaces, pas de tabulations. Un processus checkstyle a été intégré au processus de construction. Parmi les exemples de règles : les blocs sans accolades ne sont pas autorisés, une espace est attendue après les instructions de contrôle comme if, while, for, et l'accolade ouvrante doit être sur la même ligne que l'instruction de contrôle.

Documentation, signatures et licence

La README fournit un lien vers les javadocs de la version 4.10 à l'adresse java-diff-utils.github.io/java-diff-utils/4.10/docs/apidocs, et mentionne un fichier KEYS pour la validation des signatures GPG des artefacts du projet. Le projet est sous licence Apache 2.0, qui accorde une licence de droit d'auteur perpétuelle, mondiale, non exclusive, gratuite et irrévocable pour reproduire, préparer des œuvres dérivées, afficher et exécuter publiquement, sous-licencier et distribuer l'œuvre. Le texte de la licence ne couvre pas la garantie, le support ou les garanties de sécurité ; la README n'en parle pas non plus. Les métadonnées du dépôt enregistrent 1 543 étoiles et 221 forks, avec deux problèmes ouverts, mais la README elle-même ne discute ni de l'adoption ni de l'historique des problèmes.

Contrôler java-diff-utils dans son environnement

Lancez les tests Maven de java-diff-utils, puis comparez deux textes connus avec PatchGenerator et Patch.applyTo. Inspectez les objets Patch, les lignes modifiées et les cas d échec afin de vérifier le format attendu par votre intégration. Cette séquence porte sur java-diff-utils, ses fichiers et ses sorties documentées ; elle ne remplace pas les informations absentes du README.

Conclusion éditoriale

java-diff-utils convient aux lecteurs dont le besoin correspond aux fonctions décrites dans le README et qui peuvent fournir son environnement requis. Il convient moins à ceux qui attendent une garantie absente du dépôt. Avant décision, exécutez ce contrôle propre au projet : Lancez les tests Maven de java-diff-utils, puis comparez deux textes connus avec PatchGenerator et Patch.applyTo. Inspectez les objets Patch, les lignes modifiées et les cas d échec afin de vérifier le format attendu par votre intégration.

Sources officielles

1. Official documentation
2. Official README
3. Project repository
4. Release notes