bisql

# bisql bisql es un motor de plantillas SQL bidireccional para Go. Permite escribir plantillas SQL que son simultáneamente sentencias SQL válidas (ejecutables en un cliente SQL) y constructores de consultas parametrizadas para aplicaciones. Las directivas se expresan como comentarios SQL, por lo que el mismo texto funciona en ambos contextos. ## Características clave - **SQL bidireccional**: Las plantillas son SQL válido; las directivas son comentarios. El mismo texto se ejecuta en un cliente (con valores de muestra) y construye sentencias parametrizadas `(SQL, Args)` en Go. - **Modelo explícito**: Sin eliminación implícita de cláusulas vacías o conectores colgantes. Los autores anclan fragmentos dinámicos (por ejemplo, `1 = 1`) para una salida predecible. - **Directivas**: Enlace (`/* expr */literal`), interpolación literal (`/*^ expr */literal`), condicionales (`/*%if*/`, `/*%elseif*/`, `/*%else*/`, `/*%end*/`), bucles (`/*%for x in xs*/`) e inclusiones (`/*%! @include name */`). - **Inclusión de fragmentos**: Fragmentos SQL reutilizables compuestos mediante `@include`, resueltos desde `fs.FS`, registros en memoria o cargadores personalizados. Recursivo con protecciones de ciclo/profundidad. - **Soporte de dialectos**: Generación de marcadores de posición para MySQL, SQLite, PostgreSQL, Oracle y SQL Server. Enlace de arreglos para PostgreSQL. - **Lenguaje de expresiones**: Usa expr-lang para condiciones e iterables, soportando comparación, operadores lógicos, encadenamiento opcional, coalescencia nula, `in` y `len`. - **Seguro por diseño**: Sin sustitución de texto sin procesar de valores arbitrarios; los identificadores dinámicos deben estar en la lista blanca mediante ramas `/*%if*/`. ## Uso Las plantillas son archivos `.sql`. Analice con `ParseFile` desde cualquier `fs.FS` (por ejemplo, incrustado) y luego construya con un mapa de parámetros o una estructura. ```go p := bisql.NewParser(bisql.WithDialect(dialect.PostgreSQL)) tmpl, err := p.ParseFile(sqlFS, "users/search.sql") stmt, err := tmpl.Build(map[string]any{"name": "Alice", "activeOnly": true, "status": "active"}) fmt.Println(stmt.SQL) // SQL parametrizado fmt.Println(stmt.Args) // argumentos de enlace ``` ## Reglas de autoría - Ancle fragmentos dinámicos (por ejemplo, `1 = 1` para cadenas `AND`, `1 = 0` para cadenas `OR`). - Para listas, use conectores iniciales (`and`/`or`) o `union all select` desde una semilla de cero filas para listas separadas por comas. - Cite cadenas/identificadores con duplicación estándar SQL; no se reconoce el escape con barra invertida. - Use `/*%! … */` para comentarios de analizador (eliminados) o `/** … */` para comentarios de bloque ordinarios. ## Diseño del paquete - `bisql`: API pública (Parser, Parse, Expand, loaders). - `dialect/`: Definiciones de dialectos. - `expr/`: Interfaz de evaluador y Scope. - `internal/`: Capa de plantilla y evaluador predeterminado. ## Desarrollo Cadena de herramientas fijada en `mise.toml`; ejecute `mise run check` para fmt, build, vet, lint y pruebas. Las pruebas de integración con PostgreSQL requieren una etiqueta de compilación y DSN. Para documentación completa, consulte la [Referencia de Go](https://pkg.go.dev/github.com/mpyw/bisql).