Diagnósticos

El compilador de HoopLang informa los problemas como diagnósticos: un código, una gravedad, una posición (línea y columna) y un mensaje en inglés. Los errores (E0xx) impiden compilar; las advertencias (W0xx) dejan compilar e informan. Este capítulo describe el formato de salida, cómo se informan los problemas de otros archivos y, para cada código que emite el compilador, sus mensajes, cuándo se producen, un ejemplo verificado y cómo corregirlo.

Códigos que existen hoy: E000, E001, E002, E003, E004, E006, E007, W001, W003, W004, W006, W007, W008, W009 y W010. Los números que faltan (E005, W002, W005) no los emite el compilador actual.

Formato#

Cada diagnóstico se imprime en una línea:

<archivo>:<línea>:<columna>: <error|warning> <CÓDIGO>: <mensaje>

e003.hoop:4:3: error E003: undeclared thread `negor`; did you mean `negro`?
w001.hoop:4:16: warning W001: shape of 1.00 mm²: under 1.5 mm² does not sew cleanly

• Líneas y columnas empiezan en 1. La columna cuenta caracteres.
• El prefijo <archivo>: lo agrega la herramienta (hoop check, hoop build); el diagnóstico en sí es línea:columna: gravedad CÓDIGO: mensaje.
• Un diagnóstico que no corresponde a una línea usa la posición 1:1 (por ejemplo missing design (or hoop) declaration). Los del hoop entero (the hoop is missing frame, the hoop places no designs) van en la línea de su declaración.
• Los mensajes sugieren el nombre correcto cuando hay uno parecido (distancia de edición de a lo más un tercio de su largo, o de 2 en los nombres cortos, contando una trasposición como un solo cambio) o cuando es un nombre anterior de una fuente (ArialNegrita → ArialBold): …; did you mean negro?. Si no hay uno parecido, muchos mensajes listan los valores válidos entre paréntesis.
• En la API (WASM y Rust) cada diagnóstico es una estructura con code, severity ("Error" o "Warning"), pos (line, col) y msg.

Cuántos se informan#

• Un error léxico o de sintaxis (E000, y el E001 de unidad desconocida, que detecta el analizador léxico) detiene el análisis: se informa sólo ese.
• Los errores de tipos, nombres y reglas se juntan todos en una pasada.
• Un mismo diagnóstico en el mismo lugar se informa una vez (por ejemplo, un error dentro de un for de 100 vueltas).
• Las dos ramas de un if se verifican; sus errores se informan aunque la rama no se borde.
• Si una declaración falla (shape s = … con un error), usar s después no repite el error; tampoco un frame desconocido arrastra errores por cada place.
• Los límites (E006 del lienzo, W008, W009) y W007 dependen de la geometría compilada: se revisan sólo si la verificación no encontró errores.

Diagnósticos de otros archivos#

Un problema dentro de un archivo importado (import) o colocado (place) se informa en la línea del import o del place, con el código original, y el mensaje lleva el archivo y la posición dentro de él:

in `<archivo>` <línea>:<columna>: <error|warning>: <mensaje original>

h_noparam.hoop:4:3: error E001: in `parche.hoop` 1:1: error: `nombre` is String but it was given Length

Con varios niveles, los prefijos se encadenan, del más externo al más interno:

imp_lib.hoop:2:1: error E007: in `lib/ca.hoop` 1:1: error: in `lib/cb.hoop` 1:1: error: import cycle: lib/ca.hoop → lib/cb.hoop → lib/ca.hoop

El nombre de archivo es el que se escribió en el import o place. El playground muestra estos diagnósticos también en el archivo de origen, en su línea.

Errores#

E000 — sintaxis#

El texto no se puede analizar: un carácter, número, color o cadena mal escrito, o una construcción que no corresponde.

// error E000
design "D" { canvas: rect(size: (20mm, 20mm)) }
thread negro = #1c16

e000a.hoop:2:16: error E000: a color is written #rrggbb (6 hex digits)

// error E000
design "D" { canvas: rect(size: (20mm, 20mm)) }
thread negro = #1c1616
layer a {
  relleno negro { shape: canvas }
}

e000b.hoop:4:3: error E000: `relleno` is not a primitive (fill, satin, run, triple or text)

Corrección: escribir la construcción como indica el mensaje (ver Léxico y Declaraciones).

E001 — tipo incorrecto#

Un valor no es del tipo que se espera, falta una unidad o una operación no existe entre esos tipos. Mensajes principales:

// error E001
design "D" { canvas: rect(size: (20mm, 20mm)) }
thread negro = #1c1616
layer a {
  fill negro { shape: canvas, angle: 2mm }
}

e001a.hoop:4:31: error E001: `angle` is Angle or auto, not Length

// error E001
design "D" { canvas: rect(size: (20mm, 20mm)) }
thread negro = #1c1616
layer a {
  fill negro { shape: canvas, density: 0.4 }
}

e001b.hoop:4:40: error E001: 0.4 has no unit: add mm, cm, deg or %

// error E001
const x: Angle = 3mm
design "D" { canvas: rect(size: (20mm, 20mm)) }

e001c.hoop:1:10: error E001: `x` is declared Angle but its value is Length

Corrección: dar el valor con el tipo y la unidad que pide la propiedad (ver Tipos y Expresiones).

E002 — valor fuera de rango#

El tipo es correcto pero el valor no está permitido: fuera del rango de una propiedad, un nombre que no está en la lista de valores válidos o un bucle demasiado largo.

// error E002
design "D" { canvas: rect(size: (40mm, 20mm)) }
thread negro = #1c1616
layer a {
  satin negro { border: canvas, width: 9mm }
}

e002a.hoop:4:33: error E002: `width` = 9 mm: valid range is 0.8 to 8 mm

// error E002
design "D" { canvas: rect(size: (40mm, 20mm)) }
thread negro = #1c1616
layer a {
  text negro { value: "ANA", height: 8mm, at: (5mm, 15mm), font: ArialNegrita }
}

e002b.hoop:4:60: error E002: `ArialNegrita` is not valid for font; did you mean `ArialBold`?

Corrección: usar un valor dentro del rango o de la lista indicada (ver Catálogos). Un satín más ancho que 8 mm se borda mejor como relleno.

Límites de recursos#

E002 también rechaza entradas que exceden los presupuestos del compilador o del formateador. No se modifica el diseño para hacerlo pasar: se debe reducir la entrada o dividir el proyecto.

Los enteros no se envuelven al desbordarse: integer overflow es E002 tanto en debug como en release. Un fit que produciría coordenadas no finitas también es E002. La carga que excede el presupuesto de lecturas se informa como un error del cargador (E007, file loading exceeds … reads). Los valores exactos viven en crates/hoop/src/limits.rs y se ejercitan en resource_limits; ver pruebas de robustez.

E003 — hilo no declarado#

Una primitiva usa un hilo que no está declarado con thread ni importado.

undeclared thread `x`; did you mean `y`?
undeclared thread `x` (declare it with thread)

// error E003
design "D" { canvas: rect(size: (20mm, 20mm)) }
thread negro = #1c1616
layer a {
  fill negor { shape: canvas }
}

e003.hoop:4:3: error E003: undeclared thread `negor`; did you mean `negro`?

Corrección: declarar el hilo (thread negor = #rrggbb), corregir el nombre o importarlo (ver Módulos). Un color suelto en lugar del hilo (fill #000000 { … }) es E000.

E004 — geometría inválida o vacía#

Una forma, camino o texto que no se puede bordar.

// error E004
design "D" { canvas: rect(size: (20mm, 20mm)) }
thread negro = #1c1616
layer a {
  fill negro { shape: path { from (0mm, 0mm) line (5mm, 0mm) line (5mm, 5mm) } }
}

e004.hoop:4:23: error E004: a closed shape is required: the path is missing close

Corrección: cerrar el camino con close, dar medidas positivas o separar la forma en piezas.

E006 — fuera de los límites#

Algo cosido queda fuera de su espacio: el canvas de un diseño (menos su margin), el área útil de un bastidor (menos su margin) o la caja de un texto.

// error E006
design "D" {
  canvas: rect(size: (40mm, 20mm))
  margin: 2mm
}
thread negro = #1c1616
layer a {
  fill negro { shape: rect(at: (30mm, 5mm), size: (15mm, 5mm)) }
}

e006.hoop:7:3: error E006: fill overflows the canvas minus its 2 mm margin by 7.0 mm on the right

En un hoop:

// error E006
hoop "H" {
  frame: Brother_100x100
  place "cuadro.hoop" at (12mm, 50mm)
}

h_e006b.hoop:3:3: error E006: `cuadro.hoop` spans (2.0, 40.0)–(22.0, 60.0) mm, outside the sewing area minus its 5 mm margin (100 × 100 mm frame)

(cuadro.hoop es un cuadrado de 20 × 20 mm; ver Bastidor.)

Corrección: mover o achicar el objeto, ampliar el canvas o reducir el margin; en un texto con box, acortar el texto, ampliar la caja o bajar min_height.

E007 — nombres y estructura#

Un nombre repetido, desconocido o mal usado, una propiedad que no existe o que falta, o un archivo que no se puede usar.

Nombres y propiedades:

Estructura del archivo:

Archivos (import y place, ver Módulos):

// error E007
design "D" { canvas: rect(size: (20mm, 20mm)) }
thread negro = #1c1616
layer a {
  fill negro { shape: canvas, densty: 0.4mm }
}

e007a.hoop:4:31: error E007: fill has no `densty`; did you mean `density`?

// error E007
design "D" { canvas: rect(size: (20mm, 20mm)) }
thread negro = #1c1616
thread negro = #000000

e007b.hoop:3:1: error E007: `negro` is already defined

Corrección: renombrar (o usar as en el import), corregir la clave según la sugerencia, agregar la propiedad que falta o corregir la ruta.

Advertencias#

W001 — detalle demasiado chico#

shape of A mm²: under 1.5 mm² does not sew cleanly: la forma de un fill o de un satin con border tiene menos de 1.5 mm² de área.

design "D" { canvas: rect(size: (20mm, 20mm)) }
thread negro = #1c1616
layer a {
  fill negro { shape: rect(at: (2mm, 2mm), size: (1mm, 1mm)) }
}

w001.hoop:4:16: warning W001: shape of 1.00 mm²: under 1.5 mm² does not sew cleanly
w001.hoop: ok — 1 threads, 1 layers, 1 objects

Corrección: agrandar el detalle, borrarlo o hacerlo con un corrido.

W003 — satín ancho#

W mm satin: from 7 mm on, split it or use fill: un satín de más de 7 mm de ancho (hasta 8 mm es válido; desde ahí es E002). Las puntadas largas se enganchan y no cubren parejo.

design "D" { canvas: rect(size: (40mm, 30mm)) }
thread negro = #1c1616
layer a {
  satin negro { border: canvas, width: 7.5mm }
}

w003.hoop:4:33: warning W003: 7.5 mm satin: from 7 mm on, split it or use fill
w003.hoop: ok — 1 threads, 1 layers, 1 objects

Corrección: bajar width a 7 mm o menos, o usar fill.

W004 — texto más chico que el mínimo de su fuente#

text H mm high is below the minimum for FUENTE (M mm): its letters do not sew cleanly: un texto con height (sin box) más bajo que el alto mínimo de su fuente (el mismo que usa box como piso; ver Texto). Con place … scale:, si el achicado deja un texto bajo ese mínimo, se informa en el place: at scale S%, text in x.hoop is H mm high, below the minimum for FUENTE (M mm).

design "D" { canvas: rect(size: (40mm, 20mm)) }
thread negro = #1c1616
layer a {
  text negro { value: "ABC", font: ArialBold, height: 4mm, at: (5mm, 12mm) }
}

w004.hoop:4:3: warning W004: text 4 mm high is below the minimum for ArialBold (6 mm): its letters do not sew cleanly
w004.hoop: ok — 1 threads, 1 layers, 1 objects

Corrección: subir height, o usar una fuente con un mínimo menor.

W006 — diseños de un bastidor que se pisan#

`a.hoop` overlaps `b.hoop` by A mm²: dos diseños de un hoop tienen más de 0.5 mm² de huella en común. Se informa en el place posterior.

hoop "H" {
  frame: Brother_100x100
  place "cuadro.hoop" at (40mm, 50mm)
  place "cuadro.hoop" at (50mm, 50mm)
}

h_w006.hoop:4:3: warning W006: `cuadro.hoop` overlaps `cuadro.hoop` by 200.0 mm²
h_w006.hoop: ok — 2 designs, 1 threads, 2 objects

Corrección: separar los at, si el solape no es intencional.

W007 — caracteres que la fuente no tiene#

FUENTE has no c, …: left out of the text: el texto tiene caracteres que la fuente no trae; no se bordan (los espacios no cuentan).

design "D" { canvas: rect(size: (60mm, 20mm)) }
thread negro = #1c1616
layer a {
  text negro { value: "TÉ 中", font: Arial, height: 8mm, at: (5mm, 14mm) }
}

w007.hoop:4:3: warning W007: Arial has no `中`: left out of the text
w007.hoop: ok — 1 threads, 1 layers, 1 objects

Corrección: quitar esos caracteres o elegir una fuente que los tenga.

W008 — diseño sin lienzo#

no canvas: bounds are not checked; the design measures W × H mm (declare canvas: rect(size: (Wmm, Hmm))): el design no declara canvas, así que no se revisa que lo cosido quede dentro de un espacio. Se informa en la línea del design.

design "D" { fabric: Twill }
thread negro = #1c1616
layer a {
  fill negro { shape: rect(at: (0mm, 0mm), size: (30mm, 20mm)) }
}

w008.hoop:1:1: warning W008: no canvas: bounds are not checked; the design measures 30.0 × 20.0 mm (declare `canvas: rect(size: (30mm, 20mm))`)
w008.hoop: ok — 1 threads, 1 layers, 1 objects

Corrección: declarar canvas, por ejemplo el que propone el mensaje.

W009 — fuera de su contenedor#

KIND overflows its container nombre (inside at L:C) by D mm SIDE (o … overflows the inside shape at L:C … si el contenedor no es un nombre): un objeto dentro de un bloque inside se sale de su forma (tolerancia 0.3 mm).

design "D" { canvas: rect(size: (40mm, 40mm)) }
thread negro = #1c1616
shape caja = rect(at: (5mm, 5mm), size: (20mm, 20mm))
layer a {
  inside caja {
    fill negro { shape: rect(at: (10mm, 10mm), size: (20mm, 5mm)) }
  }
}

w009.hoop:6:5: warning W009: fill overflows its container `caja` (inside at 5:3) by 5.0 mm on the right
w009.hoop: ok — 1 threads, 1 layers, 1 objects

Corrección: mover o achicar el objeto, o agrandar el contenedor.

W010 — propiedad sin efecto todavía#

Una propiedad que se acepta y se valida, pero que el compilador actual no usa: `rungs` is not used yet: the satin follows its rails without them (en un satin).

design "D" { canvas: rect(size: (40mm, 20mm)) }
thread negro = #1c1616
layer a {
  satin negro {
    rails: (path { from (5mm, 5mm) line (35mm, 5mm) }, path { from (5mm, 9mm) line (35mm, 9mm) })
    rungs: [path { from (20mm, 5mm) line (20mm, 9mm) }]
  }
}

w010.hoop:6:5: warning W010: `rungs` is not used yet: the satin follows its rails without them
w010.hoop: ok — 1 threads, 1 layers, 1 objects

Corrección: quitar la propiedad (no cambia las puntadas).

Avisos de máquina (sin código)#

Al producir los archivos (hoop build, descargas del playground), el motor revisa los límites de cada formato de máquina y del bastidor declarado (frame de un design o de un hoop). Estos avisos no tienen código ni línea; hoop build los imprime como <archivo>:<error|warning> (FORMATO): mensaje o <archivo>:<error|warning>: mensaje. No detienen la escritura de los archivos, pero si alguno es error, hoop build termina con código de salida 1:

design "Grande" { canvas: rect(size: (120mm, 40mm)), frame: Brother_100x100 }
thread negro = #1c1616
layer a { fill negro { shape: canvas } }

$ hoop build grande.hoop out
grande.hoop:error: the design is 120.4 × 39.8 mm and does not fit the 100 × 100 mm frame
grande.hoop: 120.4 × 39.8 mm, 7338 stitches, 1 threads, 1 trims, 21 ms

hoop check revisa el frame de un design sin coser, con la caja de los objetos (puede diferir en décimas de lo bordado), y termina con 1:

$ hoop check grande.hoop
grande.hoop: error: the design is 120.0 × 40.0 mm and does not fit the 100 × 100 mm frame

Los demás avisos de máquina (colores por formato, puntadas largas, saltos JEF) dependen de las puntadas: sólo los da hoop build.