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_FOUND como 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 la Structure de 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.