libag

libag - La biblioteca del buscador de plata

libag - El famoso Buscador de Plata, pero biblioteca

Introducción

Hace unas semanas, un amigo me preguntó si conocía alguna herramienta para la búsqueda recursiva de expresiones regulares en archivos de texto y binarios. Ag inmediatamente me vino a la mente, pero desafortunadamente, ag(1) es un programa, no una biblioteca.

Si bien no es imposible, analizar la salida de Ag sería un dolor de cabeza, además generar un nuevo proceso para cada búsqueda suena tedioso. Herramientas similares como ripgrep(1) pueden generar resultados en formato JSON, lo que ciertamente lo hace mucho más fácil, pero todavía estamos hablando de procesos de generación y análisis de resultados.

Así nació libag. Libag le permite utilizar el motor de búsqueda agrícola (y sus funciones), pero de la manera correcta (o casi).

Uso y características

Libag pretende ser lo más sencillo posible y por ello divide el proceso de búsqueda en tres sencillos pasos:

1. Inicialice todas las estructuras ag internas (a través de ag_init() )

2. Realice tantas búsquedas como desee (a través de ag_search() ).

3. Limpiar los recursos (a través de ag_finish() ).

La configuración de búsqueda personalizada se realiza mediante ag_init_config() y ag_set_config() . Los resultados son una lista de struct ag_result*, que contiene el archivo, una lista de coincidencias (que contiene la coincidencia y los desplazamientos de archivos correspondientes a la coincidencia) y banderas.

Un ejemplo mínimo:

(Los ejemplos completos se pueden encontrar en ejemplos/)

 #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 tiene la intención de admitir todas las funciones (trabajo en progreso) de ag (o al menos aquellas que tienen sentido para una biblioteca). Además, permite un control detallado sobre los subprocesos de trabajo, a través de ag_start_workers() y ag_stop_workers() (consulte los documentos para obtener más detalles).

Fijaciones

Libag tiene soporte de enlaces (experimentales) para otros lenguajes de programación: Python y Node.js. Para obtener más información y documentación más detallada, consulte enlaces/python y enlaces/javascript.

Construcción/Instalación

Dependencias

Libag requiere las mismas dependencias que ag: compilador c99 y bibliotecas: zlib, lzma y pcre. Estas bibliotecas se pueden instalar una por una o mediante su administrador de paquetes.

Para distribuciones tipo Debian, algo como:

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

(o siga las recomendaciones Ag aquí)

Construyendo desde la fuente

Una vez que se resuelvan las dependencias, clone el repositorio y compílelo. Libag admite Makefile y CMake. Elige el que mejor se adapte a tus necesidades:

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

Archivo Make

$ make -j4

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

Chacer

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

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

Documentación

Puede encontrar documentación detallada de cada rutina disponible en las páginas de manual. Además, el código fuente está ampliamente comentado (¡libag.h es una lectura obligada!). La documentación sobre enlaces y ejemplos se puede encontrar aquí.

Los ejemplos completos también están disponibles en la carpeta ejemplos/ y se crean automáticamente junto con la biblioteca para su comodidad ;-).

Contribuyendo

Libag siempre está abierto a la comunidad y dispuesto a aceptar contribuciones, ya sea con problemas, documentación, pruebas, nuevas funciones, correcciones de errores, errores tipográficos, etc. Bienvenido a bordo.

Licencia

Libag tiene la licencia Apache v2.