STXT
ESEN .stxt

Preguntas frecuentes

El lenguaje

¿Qué significa el nombre STXT?

La primera versión del lenguaje se llamaba STxT (Semantic Text); de ahí vienen el nombre y la pronunciación «S-text». STXT es su evolución: conserva el espíritu, la motivación y la sintaxis base, pero ha cambiado significativamente desde entonces. Las referencias a STxT que puedan encontrarse corresponden al lenguaje antiguo. El término Semantic Text se puede seguir usando sin problema, aunque oficialmente se ha retirado. El nombre actual es STXT.

¿Cómo se pronuncia STXT?

«ESS-text» o «ESE-text»: primero la letra S y después text, como S-text.

¿Es un lenguaje o un formato?

Las dos. STXT se define como lenguaje: una gramática pensada para escribirse a mano, especificaciones normativas, esquemas y herramientas. También actúa como formato, ya que los sistemas lo pueden usar para guardar o mostrar información. Las dos palabras no se excluyen; XML es Extensible Markup Language y también un fichero en formato XML.

¿Es un formato de datos o de documentos?

Los dos. Un email tiene campos y un cuerpo; un contrato, cláusulas y metadatos; una configuración, valores y comentarios largos. STXT es un árbol de nodos con nombre, y cada nodo lleva un valor, unos hijos o un bloque de texto. Con esto se describe tanto un documento como un formato de datos.

¿Qué lo distingue de otros formatos?

STXT está diseñado para las personas, y de ese principio salen las características que lo definen:

  • Pocas reglas.
    • Un nodo es Nombre: valor o Nombre >>
    • La jerarquía es la indentación
    • No hay llaves, corchetes, comillas, etiquetas de cierre ni sintaxis de lista
  • Sin caracteres de escape.
  • Parseo lineal. Línea a línea, en una sola pasada, sin retroceso ni referencias.
  • Seguridad del parseo por diseño. Sin entidades, referencias, anclas, inclusión de ficheros ni ejecución de código; namespaces en ASCII, sin ambigüedad de identificadores.
  • Namespaces y validación en el lenguaje. Un documento declara a qué namespace pertenece. Además, se puede añadir una capa de esquemas, que lo valida contra su definición.

¿Qué extensión y qué media type se usan?

Extensión .stxt; media type text/stxt (registro en IANA previsto, aún no registrado), y text/plain como alternativa compatible. Codificación UTF-8 sin BOM (un parser acepta también el BOM), finales de línea LF (se acepta CRLF).

¿Nos enseñas un uso real?

Este portal. Todas las páginas de stxt.dev están escritas en STXT. El generador las convierte en HTML. El enlace .stxt de la cabecera abre el fuente de la página actual. También se puede añadir .stxt a la dirección de cualquier página para ver el código fuente; por ejemplo faq.stxt.

¿Por qué no...?

¿Por qué no XML, YAML o TOML?

Se puede ver la comparación completa con cada formato en las siguientes páginas:

¿Por qué no Markdown o KDL?

Markdown da formato al texto, y STXT da estructura al documento, con Markdown como tipo de texto de sus nodos. KDL es un árbol de nodos como STXT, con la prosa entre comillas.

La misma lección en Markdown con Frontmatter, MDX y Markdoc, en YAML, en KDL y en STXT, y qué valida cada uno: STXT, prosa dentro de la estructura.

¿Por qué no JSON?

Porque JSON es un formato de serialización y no está pensado para escribirse a mano. Todo va entre comillas, llaves y comas; los saltos de línea se escriben \n; no hay comentarios, y un texto largo es una sola línea con escapes. STXT tiene como objetivo principal la escritura de documentos por personas, que puedan leerlos y modificarlos sin otras herramientas.

¿Por qué no hay listas?

Porque todo son listas. Los hijos de un nodo son una secuencia ordenada, y un mismo nombre puede repetirse tantas veces como haga falta. Además, el árbol conserva el orden de aparición. Un documento STXT es ya una lista de nodos raíz, y cada nodo inline es una lista de hijos. Por eso no hace falta una sintaxis aparte para expresarla. Ejemplo:

Authors:
	Author: María Pérez
	Author: Juan García
	Author: Ana López

¿Por qué no hay caracteres de escape?

Porque no hacen falta. La sintaxis de STXT solo valida el nombre del nodo y que exista un separador (: o >>). Todo lo que hay a continuación es valor o texto literal. Un valor puede contener :, un bloque puede contener # o >>, y una barra invertida es una barra invertida.

Ruta: C:\Users\ana\docs
Nota >>
	Los símbolos :, #, >>, \n no significan nada aquí.

¿Por qué no se permiten otros caracteres en los nombres?

Técnicamente era posible excluir solo los caracteres que delimitan la sintaxis (:, > y los paréntesis), pero por el principio Human-First se limitan a letras, dígitos y los separadores -, _ y espacio. De esta forma no se sugiere un significado que no existe en STXT.

¿Por qué un bloque de texto no puede tener hijos?

Por diseño:

  • Ruido visual. Para saber dónde acaba el texto y empiezan los hijos haría falta una marca de fin de bloque, y un documento dejaría de leerse como un esquema de notas.
  • Más complejidad en el parser.
  • Mezcla de significado. Un nodo que necesita a la vez hijos y un bloque de texto está describiendo dos cosas distintas, y eso apunta a que son dos nodos.

Por eso un nodo solo es inline o bloque, y no las dos cosas a la vez. En caso de necesitarse, hay que desdoblarlo en dos nodos de forma explícita.

Chapter: Introducción
	Author: María Pérez
	Summary >>
		Conceptos básicos: monolitos, microservicios y criterios de diseño.
	Content >>
		El capítulo presenta...

Escribir documentos

¿Tabuladores o espacios?

Ambos son válidos y equivalentes:

  • Un tabulador es un nivel y cuatro espacios son un nivel.
  • No es válido mezclarlos en la indentación de una misma línea.
  • Un documento puede usar estilos distintos para distintas líneas, aunque no se recomienda.

¿Por qué un ancho fijo?

El ancho fijo es deliberado: el nivel de una línea se calcula a partir de su indentación, con independencia de las otras líneas. Esto se deriva del principio KISS, con parsers más sencillos de implementar y documentos más sencillos de escribir.

¿Importan las mayúsculas, los acentos y los espacios en los nombres?

Los nombres se comparan case-insensitive, pero conservando los acentos. Los espacios se comparan reduciéndolos a un guion (y se eliminan los iniciales y finales). Así:

  • Fecha de nacimiento, fecha_de_nacimiento y Fecha-De-Nacimiento son el mismo nodo.
  • Título y título son el mismo nodo; Titulo es otro.
  • Caña y cana, o Peña y pena, son nodos distintos.

Los namespaces son más estrictos: solo ASCII [a-z0-9] y puntos, y al menos a.b. Además, se pasan a minúsculas en el proceso de parseo.

¿Cómo se escribe un valor con dos puntos o almohadilla dentro?

Sin ninguna marca. En un nodo inline el valor es todo lo que sigue al primer :, de modo que Hora: 10:30 vale 10:30, y # solo abre un comentario cuando es el primer carácter no blanco de la línea. En un bloque >> todo es texto literal.

Cita: 10:30 en la sala 2 # esto forma parte del valor
Notas >>
	# esto también es texto, no un comentario
	Clave: valor >> tampoco es un nodo

¿Puede un documento tener varios nodos raíz?

Sí. Un fichero puede contener varios nodos de nivel 0, cada uno con su árbol. Eso permite parsear en streaming ficheros grandes. Además, los namespaces no se heredan lateralmente entre raíces, ya que cada una declara el suyo.

¿Puede un documento usar varios namespaces?

Sí. Cualquier nodo puede declarar su propio namespace y sus descendientes lo heredan directamente a partir de él. Además, cada namespace tiene su propia validación independiente. Ejemplo:

Book (com.acme.book):
	Title: Arquitectura de software moderna
	Review (com.acme.reviews):
		Reviewer: Ana López
		Score: 9

Y las plantillas de los dos namespaces:

Template (@stxt.template): com.acme.book
	Structure >>
		Book:
			Title: (1)
			Review (com.acme.reviews): (*)

Template (@stxt.template): com.acme.reviews
	Structure >>
		Review:
			Reviewer: (1)
			Score: (1) NUMBER

Reviewer y Score pertenecen a com.acme.reviews, y cada namespace se valida contra su propia plantilla.

¿Se indentan los comentarios?

Un comentario se indenta igual que un nodo. Esto no es estrictamente necesario, pero es para que no quede fuera del estilo homogéneo de STXT (principio Human-First).

Esquemas y plantillas

¿Los esquemas son obligatorios?

No. Un documento sin namespace se puede parsear sin problema, y uno con namespace contiene más información que otro sin él. Si tiene namespace, es la herramienta de parseo la que decide si validar o no el documento con el esquema.

¿Esquema o plantilla?

Son dos sintaxis distintas para el mismo modelo, y toda plantilla equivale a un esquema. La plantilla (@stxt.template) se escribe de forma muy similar al documento que describe, por lo que es la forma más directa de crear una definición. Aun así, una plantilla tiene decisiones implícitas, que deben tenerse en cuenta. En cambio, un esquema es más explícito, pero menos compacto que una plantilla.

¿Cómo encuentra una herramienta los esquemas y plantillas?

Depende de la herramienta, porque la resolución de definiciones no forma parte del lenguaje base: es una capa opcional más, como los propios esquemas y plantillas. Una aplicación sin sistema de ficheros la resuelve a su manera (el playground, por ejemplo, asocia documentos y gramáticas por namespace dentro del workspace). Para cuando intervienen ficheros y proyectos, STXT-DISCOVERY-SPEC define una resolución común, que una herramienta puede implementar o no. Actualmente, la CLI, la extensión de VS Code y las tres bibliotecas implementan STXT-DISCOVERY-SPEC.

¿Dónde se colocan los esquemas y plantillas?

En las herramientas que siguen STXT-DISCOVERY-SPEC, en un directorio llamado .stxt/ en el proyecto: se cargan todos los .stxt que haya dentro, recursivamente, con independencia de los nombres de fichero y de los subdirectorios. La cadena de resolución de un documento son todos los .stxt/ de sus directorios ascendentes, luego ~/.stxt y por último /etc/stxt (en Windows, %USERPROFILE%\.stxt y %ProgramData%\stxt). Gana el nivel más cercano, namespace a namespace. La variable STXT_PATH sustituye la cadena entera por una lista de directorios, por ejemplo en CI.

¿Qué pasa si se escribe Titel en vez de Title?

Con validación habilitada, se rechaza, ya que el modelo de contenido es cerrado. Un nodo solo admite los hijos definidos, y si no tiene hijos definidos, no admite ninguno.

¿Se valida el orden de los hijos?

No. Se valida la cardinalidad, pero no la posición. Dos documentos con los mismos hijos en distinto orden validan de la misma forma. Además, el orden se conserva en el árbol, de modo que el significado depende de la aplicación que lo consume y no del validador.

¿Cómo se evoluciona un esquema sin romper documentos?

Ampliando la definición sin invalidar lo ya escrito: todo documento que validaba sigue validando si el cambio solo permite más casos. No hace falta una versión nueva para:

  • Añadir un nodo opcional: con cardinalidad (?), (*) o cualquier otra de mínimo cero.
  • Relajar una cardinalidad: rebajar un mínimo o ampliar un máximo, como pasar de (2,5) a (1,5) o a (2,6).

Un matiz: la compatibilidad es respecto a la definición ampliada. Un documento que use lo añadido no valida contra una copia anterior, así que si los consumidores del namespace no actualizan la definición a la vez, conviene versionar también las ampliaciones.

Añadir un nodo obligatorio, retirar uno o estrechar una cardinalidad rompe siempre la compatibilidad. Para esos cambios se recomienda versionar el namespace, por ejemplo com.example.docs.v1 → com.example.docs.v2.

Herramientas

¿Cómo se valida en CI?

Si se tiene Node.js instalado, se puede hacer desde la línea de comandos, sin añadir nada más:

npx @stxt-lang/cli validate --recursive docs/
npx @stxt-lang/cli format --check --recursive docs/

¿Existe una representación canónica de un documento STXT?

Sí. Todo documento válido tiene un árbol canónico en JSON, definido en STXT-TREE-SPEC: un array de raíces con name, canonicalName, namespace y value, más children (inline) o lines (bloque).

No incluye posiciones ni comentarios: es el contenido lógico del documento.

¿En qué lenguajes hay parser?

La organización stxt-lang mantiene tres: TypeScript/JavaScript (@stxt-lang/core), Java (dev.stxt:stxt-core) y Python (stxt).

¿Qué estabilidad se puede esperar?

La estabilidad está explicada en Estabilidad y versiones.

Las especificaciones no llevan número de versión: cada una lleva una fecha (la de su texto vigente) y un estado, que solo avanza y define el grado de estabilidad:

  • Genesis: en construcción, inestable.
  • Aurora: usable; pocos cambios incompatibles esperados.
  • Zenith: sin cambios incompatibles, y solo se añade.
  • Twilight: cerrada/obsoleta.

¿Dónde pregunto, o doy mi opinión?

En las discusiones de la organización stxt-lang en GitHub: preguntas, ideas, ambigüedades de las especificaciones y lo que hayas construido con STXT. Los errores de una herramienta concreta deben reportarse en su repositorio.