libag

libag - La bibliothèque Silver Searcher

libag - Le célèbre The Silver Searcher, mais bibliothèque

Introduction

Il y a quelques semaines, un ami m'a demandé si je connaissais un outil de recherche récursive d'expressions régulières dans des fichiers texte et binaires. Ag m'est immédiatement venu à l'esprit, mais malheureusement, ag(1) est un programme, pas une bibliothèque.

Bien que ce ne soit pas impossible, analyser la sortie Ag serait un peu un casse-tête, et générer un nouveau processus pour chaque recherche semble fastidieux. Des outils similaires comme ripgrep(1) peuvent produire des résultats au format JSON, ce qui rend certainement les choses beaucoup plus faciles, mais nous parlons toujours de processus de génération et d'analyse des sorties.

C'est ainsi qu'est né Libag. Libag vous permet d'utiliser le moteur de recherche agricole (et ses fonctionnalités), mais de la bonne manière (ou presque).

Utilisation et fonctionnalités

Libag se veut aussi simple que possible et divise donc le processus de recherche en trois étapes simples :

1. Initialiser toutes les structures AG internes (via ag_init() )

2. Effectuez autant de recherches que vous le souhaitez (via ag_search() ).

3. Nettoyez les ressources (via ag_finish() ).

Les paramètres de recherche personnalisés sont effectués via ag_init_config() et ag_set_config() . Les résultats sont une liste de struct ag_result*, qui contient le fichier, une liste de correspondances (contenant la correspondance et les décalages de fichier correspondant à la correspondance) et des indicateurs.

Un exemple minimal :

(Des exemples complets peuvent être trouvés dans Exemples/)

 #include <libag.h>

...
struct ag_result * * results ;
size_t nresults ;

char * query    = "foo" ;
char * paths [ 1 ] = { "." };

/* Initiate Ag library with default options. */
ag_init ();

/* Searches for foo in the current path. */
results = ag_search ( query , 1 , paths , & nresults );
if (! results ) {
    printf ( "No result foundn" );
    return ( 1 );
}

printf ( "%zu results found\n" , nresults );

/* Show them on the screen, if any. */
for ( size_t i = 0 ; i < nresults ; i ++ ) {
    for ( size_t j = 0 ; j < results [ i ] -> nmatches ; j ++ ) {
        printf ( "file: %s, match: %sn" ,
            results [ i ] -> file , results [ i ] -> matches [ j ] -> match ,
    }
}

/* Free all results. */
ag_free_all_results ( results , nresults );

/* Release Ag resources. */
ag_finish ();
...

Libag a l'intention de prendre en charge toutes les fonctionnalités (travail en cours) d'ag (ou du moins celles qui ont du sens pour une bibliothèque). De plus, il permet un contrôle détaillé sur les threads de travail, via ag_start_workers() et ag_stop_workers() (voir la documentation pour plus de détails).

Reliures

Libag prend en charge les liaisons (expérimentales) avec d'autres langages de programmation : Python et Node.js. Pour plus d’informations et une documentation plus détaillée, consultez liaisons/python et liaisons/javascript.

Construction/Installation

Dépendances

Libag nécessite les mêmes dépendances que le compilateur ag : c99 et les bibliothèques : zlib, lzma et pcre. Ces bibliothèques peuvent être installées une par une ou par votre gestionnaire de packages.

Pour les distributions de type Debian, quelque chose comme :

$ sudo apt install libpcre3-dev zlib1g-dev liblzma-dev

(ou suivez les recommandations Ag ici)

Construire à partir de la source

Une fois les dépendances résolues, clonez le référentiel et construisez. Libag prend en charge Makefile et CMake. Choisissez celui qui correspond le mieux à vos besoins :

$ git clone https://github.com/Theldus/libag.git
$ cd libag/

Makefile

$ make -j4

# Optionally (if you want to install):
$ make install # (PREFIX and DESTDIR allowed here, defaults to /usr/local/) 

CMake

$ mkdir build/ && cd build/
$ cmake .. -DCMAKE_BUILD_TYPE=Release
$ make -j4

# Optionally (if you want to install):
$ make install

Documentation

Une documentation détaillée de chaque routine disponible peut être trouvée sur les pages de manuel. De plus, le code source est largement commenté (libag.h est à lire absolument !). De la documentation sur les liaisons et des exemples peuvent être trouvés ici.

Des exemples complets sont également disponibles dans le dossier examples/ et sont automatiquement construits avec la bibliothèque pour votre commodité ;-).

Contribuer

Libag est toujours ouvert à la communauté et disposé à accepter des contributions, qu'il s'agisse de problèmes, de documentation, de tests, de nouvelles fonctionnalités, de corrections de bugs, de fautes de frappe, etc. Bienvenue à bord.

Licence

Libag est sous licence Apache v2.