Principios de diseño

Las especificaciones dicen qué es válido; esta página dice por qué. No añade ninguna regla: cada principio enlaza a la sección de la referencia que lo fija, y ante cualquier discrepancia manda la referencia.

1. El documento se escribe para personas

Este es el principio del que salen los demás. Un documento STXT debe poder leerse y escribirse sin herramientas: la forma natural del texto es la forma correcta, y la máquina se adapta a esa forma, no al revés. De ahí que no haya llaves, corchetes, comillas obligatorias ni etiquetas de cierre, y que un documento parezca un esquema de notas. Donde la comodidad de la persona y la de la máquina entran en conflicto, gana la persona.

Coste. Lo que una persona no necesita leer ni escribir no existe en el lenguaje, aunque a un programa le resultara cómodo: no hay referencias internas, ni tipos implícitos, ni notaciones compactas. Cada uno de los principios siguientes es una consecuencia de este, con su propio coste.

Referencia: STXT-SPEC §1.

2. La sencillez por encima de todo

La sencillez es un requisito del lenguaje en tres planos a la vez, y ninguno se sacrifica por los otros dos:

• Sencillo de escribir y leer. Las reglas que una persona necesita conocer caben en una página del tutorial: un nodo, un bloque de texto, la indentación, un comentario.
• Sencillo de implementar. Un parser conforme es un recorrido línea a línea con una pila; la gramática completa cabe en un apéndice y el lenguaje se describe en pseudocódigo neutro del que se han derivado los puertos existentes. Escribir un parser nuevo es un trabajo de días, no de meses, y no requiere ninguna biblioteca.
• Sencillo de procesar. El coste de parsear es lineal en el tamaño del documento: una sola pasada, sin retroceso, sin resolver referencias y sin segundo recorrido. El nivel de cada línea se decide con esa sola línea, y un parser puede emitir cada árbol raíz en cuanto empieza el siguiente, con memoria del orden de la profundidad de anidamiento y no del tamaño del fichero.

Coste. Lo que no cabe en un lenguaje sencillo se queda fuera, aunque sea útil: no hay atajos sintácticos, ni azúcar, ni extensiones. Cada propuesta de añadir algo se mide contra los tres planos, y basta con que encarezca uno para descartarla.

Referencia: STXT-SPEC §8.1, §15 y §16.

3. La indentación es la estructura

La jerarquía se expresa únicamente con la indentación: un tabulador o cuatro espacios por nivel, sin mezclarlos en una misma línea, y sin saltar niveles. El nivel de una línea se calcula a partir de esa sola línea, sin recordar las anteriores, y la jerarquía se ve igual en cualquier editor.

Coste. Dos espacios no son medio nivel: son un error. Un documento con indentación inconsistente no se interpreta con la mejor intención; se rechaza (INDENTATION_MIXED, INDENTATION_SPACES_NOT_VALID). La herramienta stxt format existe para normalizar un fichero, no el parser para adivinarlo.

Referencia: STXT-SPEC §8.1 y §8.3.

4. Pocas formas, y ninguna redundante

Un nodo es Nombre: valor o Nombre >>. No hay sintaxis de lista, ni de cadena entre comillas, ni de escape, ni notación abreviada para el caso frecuente. Una lista es un nodo repetido:

Authors:
	Author: María Pérez
	Author: Juan García

Esto no es un fin en sí mismo, sino lo que sale de aplicar la sencillez a la sintaxis: cada forma adicional sería una regla más que aprender, que implementar y que mantener.

Coste. Algunas cosas son más largas de escribir que en otros formatos. A cambio, dos autores escriben el mismo documento de la misma manera, un lector no tiene que conocer varias notaciones equivalentes, y el parser no tiene casos especiales.

Referencia: STXT-SPEC §4, §5 y §6.

5. El texto libre es literal

Todo lo indentado bajo un nodo >> es texto tal cual: :, # y >> no significan nada dentro, no hay secuencias de escape y la indentación relativa se conserva. Un párrafo, un fragmento de código o un bloque de Markdown se pegan en el documento sin transformarlos.

Coste. Dentro de un bloque no hay estructura STXT ni comentarios: un # al nivel del bloque cierra el bloque en lugar de comentarlo. Lo que necesita estructura se escribe como nodos; lo que es texto, como bloque. No hay un punto intermedio.

Referencia: STXT-SPEC §6 y §9.1.

6. No hay caracteres de escape

STXT no tiene secuencias de escape. Un carácter de escape es lo menos Human-First que existe: obliga a quien escribe a pensar en el parser en lugar de en el texto, y a quien lee a descifrar lo que hay detrás de una barra. Se han eliminado de forma consciente. Un valor es lo que hay tras los dos puntos; un bloque es lo que hay indentado debajo del >>; y cualquier carácter vale dentro de ambos, incluidos :, # y >>.

Coste. La ausencia de escapes se paga en los nombres de nodo: como un nombre no puede contener los caracteres que delimitan la sintaxis, el lenguaje no los permite, ni a ellos ni a ningún otro signo. Un nombre se compone únicamente de letras, dígitos, marcas combinantes y los separadores -, _ y espacio; :, (, ), >, # o @ en un nombre son un error (INVALID_NODE_NAME). Es una restricción asumida en el diseño del lenguaje, a cambio de que ni los valores ni los bloques necesiten escape nunca.

Referencia: STXT-SPEC §4.2, §5 y §6.

7. La seguridad del parseo por delante de la expresividad

STXT no tiene entidades, referencias, anclas, inclusión de ficheros, etiquetas que instancien objetos ni ninguna forma de evaluación. Los namespaces se restringen a ASCII para excluir los ataques homográficos. El resultado de parsear es siempre un árbol de nodos y texto, y un parser conforme puede procesar un documento de una fuente no confiable con memoria acotada.

Coste. No hay forma de reutilizar un fragmento dentro de un documento ni de componer varios ficheros desde el lenguaje. Lo que se repite, se repite; lo que se compone, lo compone la aplicación.

Referencia: STXT-SPEC §15 y §7.1.

8. Los nombres se comparan por su forma canónica

Título, título y TÍTULO son el mismo nodo; Fecha de alta, fecha-de-alta y fecha_de_alta, también. La comparación pasa a minúsculas y unifica los separadores, pero conserva los acentos y las letras no latinas: Peña y Pena son dos nodos distintos, como lo son dos palabras distintas.

Coste. Un acento olvidado en un nombre no se corrige en silencio: produce un nodo distinto, que con un esquema se detecta como no declarado. Es el mismo criterio que aplican los nombres de dominio internacionalizados.

Referencia: STXT-SPEC §4.3.

9. La validación es una capa aparte, opcional y cerrada

El parser no necesita esquemas. Un documento sin namespace, o con un namespace para el que no hay definición, es un documento válido que no se puede validar. Cuando hay esquema, el modelo de contenido es cerrado: un nodo no declarado es un error, no un dato extra que se ignora. El orden de los hijos se conserva en el árbol pero no se valida.

Coste. Cada campo que un documento usa debe estar declarado. Y hay cosas que un esquema STXT no expresa a propósito: patrones sobre valores, valores por defecto, reglas condicionales entre campos, orden obligatorio y tipos para formatos incrustados. Esa semántica pertenece a la aplicación; el esquema se mantiene pequeño y predecible.

Referencia: STXT-SCHEMA-SPEC §5, §6 y §11; STXT-DISCOVERY-SPEC §4 para cómo se localizan las definiciones.

10. El mismo árbol en todas partes

Dos implementaciones conformes producen, para el mismo documento, el mismo árbol canónico y los mismos códigos de error. El árbol tiene una representación JSON normativa, y los códigos son idénticos en todas las bibliotecas y no cambian a partir de la 1.0. La salida para personas —el texto de un mensaje, el formato de un informe— queda deliberadamente fuera de esa garantía.

Coste. Un puerto nuevo no tiene libertad en la forma del árbol ni en los códigos, y debe pasar el mismo corpus de conformidad que los demás.

Referencia: STXT-TREE-SPEC, STXT-SPEC §11.1 y Estabilidad y versiones.

Lo que STXT no es

• No es un lenguaje de marcado ligero. Markdown da formato a un texto; STXT da estructura a un documento, y el texto con formato va dentro de sus bloques.
• No es un lenguaje de programación ni de plantillas. No hay variables, inclusiones, condicionales ni expresiones, y no las habrá.
• No tiene tipos implícitos. Todo valor es texto hasta que un esquema lo valida: true, 007 o 2026-01-01 no cambian de naturaleza por su forma, y un parser nunca decide por su cuenta que un valor es un booleano, un número o una fecha.

Estas decisiones están cerradas: un cambio en cualquiera de ellas sería una versión mayor de la especificación correspondiente, no una ampliación.