Herramientas
El playground, la extensión, la línea de comandos, las bibliotecas y el editor implementan las mismas cinco especificaciones y devuelven los mismos códigos de error.
Según el uso:
| Uso | Herramienta |
|---|---|
| Probar el lenguaje sin instalar nada | El playground |
| Escribir documentos habitualmente | La extensión de VS Code |
Validar en un script, un Makefile o en CI |
La línea de comandos stxt |
| Leer o generar STXT desde un programa | Una biblioteca: TypeScript, Java o Python |
| Editar o colorear STXT en una página web | El editor @stxt-lang/editor |
| Generar PDF a partir de documentos STXT | stxt-pdf (biblioteca Java) o stxt-press (servicio) |
Playground
play.stxt.dev es un editor en el navegador: varios documentos a la vez, sus esquemas o plantillas al lado, errores de sintaxis y de validación durante la edición, autocompletado guiado por la gramática y hover con la definición de cada nodo.
- No requiere instalación ni cuenta; el trabajo se guarda en el propio navegador.
- Incluye una semilla de documentos de ejemplo.
- El workspace entero se puede compartir con un enlace que lleva el contenido dentro.
Extensión de VS Code
La extensión oficial es
STXT Language (stxt-lang.stxt).
Se instala desde el panel de extensiones, buscando stxt, o desde el terminal:
code --install-extension stxt-lang.stxt
Funciones:
- Errores de sintaxis en tiempo real, y de esquema; un namespace que ningún nivel define
se marca con
SCHEMA_NOT_FOUNDcomo aviso. - Coloreado semántico.
- Autocompletado con los nodos que permite el esquema y los valores de un
ENUM. - Información al pasar el ratón: la descripción que dé la definición, el tipo y, en un
ENUM, sus valores. - Ir a la definición (F12): del nodo al
Node:de su esquema o a su línea en laStructurede su plantilla. - Formateo del documento.
- Resolución de esquemas y plantillas desde los directorios
.stxt/del proyecto, del usuario y del sistema, tal como describe la referencia de resolución.
Línea de comandos
El comando stxt se publica en npm como
@stxt-lang/cli y necesita
Node 20 o superior.
npm install -g @stxt-lang/cli
stxt --version
Sin instalación, con npx:
npx @stxt-lang/cli validate --recursive docs/
Los comandos:
| Comando | Qué hace |
|---|---|
stxt validate |
Parsea y valida uno o varios ficheros o directorios; sin salida si todo pasa |
stxt format |
Reformatea (--tabs / --spaces); --check para CI, --write para guardar |
stxt describe |
Muestra el árbol lógico de un documento en JSON (STXT-TREE-SPEC) |
stxt schemas |
Muestra qué esquemas y plantillas aplican en un directorio, y de qué nivel |
stxt install |
Instala una definición en ./.stxt, ~/.stxt o el nivel del sistema |
El código de salida distingue los errores de los documentos (1) del uso incorrecto
del comando (2). Ningún comando reescribe ficheros sin una opción explícita. Las
opciones, las salidas y los códigos de salida están en la
referencia de la línea de comandos.
Bibliotecas
Hay tres implementaciones oficiales: TypeScript/JavaScript, Java y Python. Las tres pasan el kit de conformidad, que sirve también para comprobar un puerto a otro lenguaje.
TypeScript / JavaScript
@stxt-lang/core en npm. Es el
parser que usan la extensión, la línea de comandos y el playground. La guía está en
la biblioteca TypeScript. En el navegador se carga también con
un <script> desde un CDN.
npm install @stxt-lang/core
Un ejemplo mínimo:
import { Parser, InlineNode } from '@stxt-lang/core';
const result = new Parser().parseResult(text);
for (const error of result.getErrors()) {
console.error(`line ${error.line} [${error.code}]: ${error.message}`);
}
const root = result.getNodes()[0];
if (root instanceof InlineNode) {
console.log(root.getChild('Title')?.getText());
}
Java
dev.stxt:stxt-core
en Maven Central. Java 17 o superior; módulo automático dev.stxt. La guía está en
la biblioteca Java.
<dependency>
<groupId>dev.stxt</groupId>
<artifactId>stxt-core</artifactId>
<version>1.0.4</version>
</dependency>
O con Gradle:
implementation 'dev.stxt:stxt-core:1.0.4'
Python
stxt en PyPI. Python puro, 3.10 o superior. La
guía está en la biblioteca Python.
pip install stxt
Un ejemplo mínimo:
from stxt import Parser, InlineNode
result = Parser().parse_result(text)
for error in result.get_errors():
print(f"line {error.line} [{error.code}]: {error.message}")
root = result.get_nodes()[0]
if isinstance(root, InlineNode):
print(root.get_child("Title").get_text())
Editor para páginas web
@stxt-lang/editor en npm. Es el
editor del playground como biblioteca: convierte un <textarea> en un editor con
coloreado, errores durante la edición y autocompletado guiado por la gramática.
Incluye un coloreado estático para las páginas que solo muestran STXT. La guía
está en el editor para páginas web.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@stxt-lang/editor@0.4.0/dist/stxt-editor.css">
<script src="https://cdn.jsdelivr.net/npm/@stxt-lang/editor@0.4.0/dist/stxt-editor.js"></script>
<textarea id="doc"></textarea>
<script>
StxtEditor.fromTextArea(document.getElementById('doc'));
</script>
Generación de PDF
Dos proyectos generan PDF a partir de documentos con el namespace dev.stxt.pdf, que
describe las páginas, el contenido y sus estilos:
Document (dev.stxt.pdf):
Language: es
Title: Informe del trimestre
Page:
Paper: A4
Margin: 50
Styles:
For element: Document
Typography:
Font: IBM Plex Sans
Size: 10
Section:
Heading 1:
Text: Informe del trimestre
Paragraph: Las ventas han crecido un 12 % respecto al trimestre anterior.Los dos leen el STXT con la biblioteca Java y no son implementaciones del lenguaje.
Están en 0.x: el namespace dev.stxt.pdf y su API todavía pueden cambiar entre
versiones menores. La guía está en PDF y Press.
stxt-pdf
stxt-pdf es el motor: una biblioteca Java
que maqueta el documento, lo reparte en páginas y escribe el PDF, con las fuentes
incrustadas, etiquetado para accesibilidad (PDF/UA) y PDF/A si se pide. Se publica en
Maven Central como
dev.stxt:stxt-pdf y
necesita Java 17 o superior. El manual, la referencia y los ejemplos, con su PDF,
están en el repositorio.
<dependency>
<groupId>dev.stxt</groupId>
<artifactId>stxt-pdf</artifactId>
<version>0.19.0</version>
</dependency>
O con Gradle:
implementation 'dev.stxt:stxt-pdf:0.19.0'
Un ejemplo mínimo, que convierte el documento de arriba:
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import dev.stxt.InlineNode;
import dev.stxt.pdf.convert.Converter;
import dev.stxt.pdf.stxt.DocumentReader;
InlineNode doc = new DocumentReader().read(Path.of("informe.stxt"));
try (OutputStream out = Files.newOutputStream(Path.of("informe.pdf"))) {
Converter.create().toPdf(doc, out);
}
Las fuentes y las imágenes se buscan en la carpeta resources/ del directorio de
trabajo, en fonts/ e images/. Solo se usan las fuentes de esa carpeta, nunca las
del sistema. El repositorio incluye IBM Plex Sans, Serif y Mono.
stxt-press
stxt-press es un servicio sobre stxt-pdf:
genera PDF y SVG a partir de plantillas, con sus Slots rellenados con datos JSON, o de
documentos sin datos. Tiene una API HTTP, un editor web y una línea de comandos, en un
solo jar. Se publica como imagen Docker en
ghcr.io/stxt-lang/stxt-press:
docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/stxt-lang/stxt-press:0.7.0
En http://127.0.0.1:8080/ están el índice y el editor, con plantillas y documentos
de ejemplo. Una plantilla, rellenada con sus datos de ejemplo o con los de un fichero
JSON:
curl -o invoice.pdf http://127.0.0.1:8080/print/examples/invoice
curl -o invoice.pdf -d @invoice.json http://127.0.0.1:8080/print/examples/invoice
Sin Docker, la carpeta server/ del repositorio es un servidor completo (el jar, su
configuración, las fuentes y los ejemplos) y se arranca con server/start.sh y
Java 17 o superior.
Código fuente
Todo el ecosistema vive en la organización stxt-lang de GitHub, con licencia MIT:
| Repositorio | Contenido |
|---|---|
| stxt-lang | Este sitio: las especificaciones, el kit de conformidad y el corpus de ejemplos |
| stxt-js | @stxt-lang/core, la biblioteca TypeScript |
| stxt-java | dev.stxt:stxt-core, la biblioteca Java |
| stxt-python | stxt, la biblioteca Python |
| stxt-cli | @stxt-lang/cli, la línea de comandos |
| stxt-vscode | La extensión de VS Code |
| stxt-play | El playground |
| stxt-editor | @stxt-lang/editor, el editor para páginas web |
| stxt-pdf | dev.stxt:stxt-pdf, el motor de PDF |
| stxt-press | El servicio de PDF y SVG |
Las preguntas y las ideas sobre el lenguaje van a las discusiones de la organización; los errores, a las incidencias del repositorio de la herramienta afectada.