El libro de HoopLang

0. Introducción#

Bienvenida, bienvenido. Este libro te enseña HoopLang, un lenguaje para escribir diseños de bordado como código, y de paso te enseña por qué un bordado se diseña como se diseña: por qué un borde va en satín y un fondo en relleno, por qué el fondo se borda primero, qué hace la subcapa, por qué la tela importa.

No necesitas saber bordar ni haber programado antes. Si ya programas, vas a reconocer ideas de TypeScript, Go o Rust; si ya bordas, vas a reconocer las decisiones que tomas a diario en un programa de digitalización, sólo que escritas.

Qué es HoopLang#

Un archivo .hoop describe qué se borda: formas en milímetros reales, hilos, el tipo de puntada de cada objeto y el orden de las capas. El compilador hoop lo traduce, de forma determinista, a los archivos que leen las máquinas: PES (Brother), JEF (Janome), DST y EXP (Tajima, Melco), VP3 (Husqvarna/Pfaff) y XXX (Singer).

tu .hoop ──► hoop check ──► hoop build ──► PES / JEF / DST / EXP / VP3 / XXX
             (errores con     (puntadas,      + vista previa SVG
              línea y código)  orden, cortes)

Un ejemplo completo, para que veas el sabor del lenguaje (lo vas a escribir tú mismo en el capítulo 1):

design "Hola" {
  canvas: rect(size: (40mm, 40mm))
}

thread azul = #1f3a8a "Azul"

layer fondo {
  fill azul { shape: circle(center: (20mm, 20mm), r: 15mm) }
}

Un círculo azul de 30 mm, relleno con puntada tatami, en un espacio de 40 × 40 mm. El compilador decide cada una de las ~1 500 puntadas.

Por qué un lenguaje para bordar#

Los programas de bordado guardan el diseño en archivos binarios que sólo ellos abren. Escrito como texto, un diseño:

• se versiona: puedes ver qué cambió entre la versión 3 y la 4 del escudo del club, con git diff;
• se reutiliza: el escudo es un componente que pones en la polera, en el gorro y en el parche, y la paleta del club se escribe una sola vez;
• se parametriza: doce parches con doce nombres distintos son un for, no doce archivos;
• se revisa antes de bordar: el compilador te dice que el satín de 9 mm no va a quedar bien, que el texto se sale del pecho por 10.9 mm a la derecha o que te equivocaste al escribir el nombre de un hilo. Un error al compilar cuesta un segundo; uno en la máquina cuesta una prenda.

Y como es tipado, las unidades son parte del lenguaje: 2.5mm es una longitud, 45deg un ángulo, 30% una proporción. Escribir 2.5 a secas es un error, porque en bordado un número sin unidad es una puntada mal puesta.

Cómo leer este libro#

Los capítulos son progresivos: cada uno construye sobre el anterior, con diseños reales que puedes compilar y bordar.

Cada capítulo termina con un Resumen y con enlaces a la referencia, que describe cada regla con todo detalle. El libro explica; la referencia es para consultar.

Los ejemplos de código van en bloques como éste:

const borde = 3mm

y los comandos de terminal, así:

hoop check hola.hoop

Cuando el libro muestra un error del compilador, es la salida real, copiada tal cual. Los mensajes del compilador están en inglés, como los de la mayoría de los lenguajes profesionales; los nombres del lenguaje (fill, satin, canvas…) también. Tus nombres (escudo, borde_negro, azul) pueden ir en español, con tildes y eñes si quieres.

Instalar y usar la herramienta hoop#

hoop es una herramienta de línea de comandos escrita en Rust. Desde el repositorio del proyecto:

cargo build --release --bin hoop

deja el ejecutable en target/release/hoop. También puedes ejecutarlo sin instalar nada aparte:

cargo run -q --release --bin hoop -- check docs/lenguaje/galeria/insignia.hoop

En este libro escribimos simplemente hoop. Tiene tres órdenes:

hoop check archivo.hoop          # verifica: errores y advertencias, sin escribir nada
hoop build archivo.hoop salida/  # compila: PES, DST, EXP, JEF, VP3, XXX y vistas SVG
hoop fmt [--check] archivos…     # da formato al código (con --check, sólo avisa)

hoop check termina en una línea de resumen cuando todo está bien:

insignia.hoop: ok — 5 threads, 3 layers, 5 objects

y hoop build escribe, junto a los seis archivos de máquina, dos vistas previas: nombre.svg (cómo se verá el bordado) y nombre.needles.svg (dónde entra la aguja). Su resumen te da el tamaño real, las puntadas, los hilos y los cortes:

insignia.hoop: 70.4 × 84.3 mm, 11498 stitches, 5 threads, 9 trims, 94 ms

hoop fmt aplica el único estilo del lenguaje (sangría de 2 espacios, espacios alrededor de = y después de : y ,, los = de los thread y const seguidos alineados). Nunca cambia el significado: sólo el espacio en blanco. Úsalo y no discutas formato nunca más.

El playground#

Si prefieres no instalar nada, el playground de HoopLang (apps/playground en el repositorio) es un editor en el navegador: escribes a la izquierda y ves el bordado en vivo, con el bastidor, el lienzo, las puntadas y los saltos; los errores aparecen en la línea exacta, y puedes descargar PES, DST, EXP, JEF, VP3 y XXX. Todo corre en tu navegador (el mismo compilador, en WebAssembly), así que el resultado es idéntico byte por byte al de la terminal. Trae como proyecto inicial la galería de ejemplos de docs/lenguaje/ y guarda tu proyecto en el navegador ("Proyecto → Descargar" lo baja en .zip).

Puedes seguir todo el libro en el playground o en tu editor favorito con hoop check en una terminal al lado.

Resumen#

• HoopLang describe un bordado como código tipado: formas en mm reales, hilos, puntadas y capas.
• El compilador hoop verifica (check), compila (build) y da formato (fmt); el playground hace lo mismo en el navegador.
• Las unidades son tipos: mm, cm, deg, %.
• Los mensajes del compilador están en inglés y traen archivo, línea, columna y código.

Referencia: herramientas · léxico · diagnósticos