Declaraciones

Un archivo .hoop es una secuencia de declaraciones de nivel superior. Este capítulo describe la estructura del archivo, cada declaración (design, thread, const, shape, param, layer) y las reglas de nombres. El contenido de las capas está en Control y en Primitivas; hoop en Bastidor; import en Módulos.

Estructura del archivo#

archivo     = { declaración } ;
declaración = import | design | hoop | thread | param | const | shape | layer ;

• Las declaraciones se procesan de arriba abajo, en el orden escrito. Cada una se evalúa en el momento: solo ve lo declarado antes (ver Nombres).
• Un archivo de diseño tiene exactamente uno de design o hoop. Sin ninguno: E007: missing design (or hoop) declaration (salvo una biblioteca: un archivo con sólo import, thread, const y shape, que hoop check verifica como tal). Con dos (dos design, dos hoop o uno de cada): E007: a file has a single design (or a single hoop).
• Un archivo con hoop no tiene capas: E007: a hoop places designs with place; layers go in each design's file.
• Un archivo que solo se importa (una biblioteca) no necesita design; ver Módulos.
• Las separaciones son libres: no hay ; y los saltos de línea no importan.

En un bloque de propiedades ({ nombre: valor … }), la coma entre propiedades es opcional:

props = "{" { identificador ":" expr [ "," ] } "}" ;

// archivo completo
design "Club Ejemplo" {
  canvas: rect(size: (60mm, 72mm))
  margin: 1mm
  fabric: Pique
}
thread negro = #1c1616 "Negro"
thread oro = #d8a21b "Oro" { brand: "Madeira", code: "1172" }
const borde = 3mm
shape escudo = canvas.inset(borde)
layer fondo { fill oro { shape: escudo } }
layer contorno { satin negro { border: escudo, width: borde } }

design#

design = "design" texto props ;

Declara que el archivo es un diseño, con su nombre (un texto) y sus propiedades. Todas son opcionales:

canvas#

El espacio disponible en la prenda, en milímetros reales. El compilador verifica que lo cosido (la huella real de cada objeto) no salga del lienzo; si sale, es un error E006. Sin canvas, el diseño compila con la advertencia W008, que informa cuánto mide. Ver Diagnósticos.

Al procesar el design, su lienzo queda disponible como una forma más bajo el nombre canvas para las declaraciones siguientes (fill azul { shape: canvas }, canvas.inset(5mm), canvas.center). Declarar luego otro nombre canvas es E007: canvas is already defined.

margin#

Distancia mínima entre lo cosido y el borde del lienzo: la verificación de límites usa el lienzo contraído en margin. Fuera de rango: E002: margin = 25 mm: 0 to 20 mm.

fit#

Escala explícita del diseño completo (lo cosido y el lienzo), respecto del origen (0mm, 0mm):

• fit: 70mm escala para que el ancho del lienzo (o de lo cosido, si no hay lienzo) sea 70 mm.
• fit: (70mm, 84mm) escala de manera uniforme lo máximo posible sin exceder esa caja.

Una medida fuera de 5–1000 mm es E002: fit: a design is 5 to 1000 mm; otro tipo es E001: fit is Length (width) or (width, height), not Int.

fabric#

La tela, que fija los valores por defecto de las primitivas (densidad, subcapa, compensación; ver Primitivas). Un nombre fuera de la lista es E002 con sugerencia (`Twil` is not valid for fabric; did you mean `Twill`?).

origin#

Dónde está (0, 0) en las coordenadas del diseño. En los dos casos, x va hacia la derecha e y hacia abajo.

Con center, todo lo demás (formas, at, path) se escribe ya en esas coordenadas: el centro es (0, 0), la izquierda es negativa.

design "Escudo" {
  canvas: rect(size: (60mm, 72mm))
  origin: center
}
thread azul = #1f4e9c "Azul"
shape escudo = path {
  from (-30mm, -36mm) line (30mm, -36mm) line (30mm, 12mm)
  curve (30mm, 24mm) (10mm, 30mm) (0mm, 36mm)
  curve (-10mm, 30mm) (-30mm, 24mm) (-30mm, 12mm)
  close
}
layer fondo { fill azul { shape: escudo } }

• Requiere canvas: sin lienzo no hay centro (E007 origin: center needs a canvas: its center is (0, 0)).
• No cambia las puntadas: el mismo diseño escrito desde la esquina o desde el centro da el mismo archivo de máquina.
• El archivo de máquina siempre tiene su origen en el centro (ver bastidor), con top_left o con center.

frame#

El bastidor en que se bordará el diseño: un nombre del catálogo (por ejemplo Brother_100x100) o custom(ancho, alto) con dos Length. Ver Bastidor y Catálogos. Un nombre desconocido es E002: unknown frame Foo (catalog: …); un custom con otros tipos es E001: custom(width, height) takes two Length.

Propiedades retiradas y desconocidas#

width y height ya no existen; usarlas es un E007 que explica cómo pasar a canvas o fit. Cualquier otra propiedad es E007: a design has no colour (canvas, margin, fit, fabric, origin, frame), con sugerencia si hay una parecida. Una propiedad repetida es E007: duplicate canvas``.

design "Gorra" {
  canvas: rect(size: (120mm, 55mm), radius: 6mm)
  margin: 2mm
  fit: (110mm, 50mm)
  fabric: Cap
  frame: Cap_130x60
}

thread#

thread = "thread" identificador "=" color [ texto ] [ props ] ;

Declara un hilo: un nombre, su color (obligatorio, un literal #rrggbb) y una etiqueta opcional. Toda primitiva cose con un hilo declarado; un hilo no declarado en una primitiva es E003 (ver Primitivas).

Propiedades opcionales del bloque:

• Otro tipo: E001: brand is a String, not Int.
• Otra propiedad: E007: a thread has no foo (brand, code).
• Sin color literal: E000: expected the thread color (#rrggbb).

Los hilos se listan en el orden en que se declaran. Las paletas de marca pueden importarse (ver Módulos y Catálogos).

thread rojo = #c8102e
thread oro = #d8a21b "Oro" { brand: "Madeira", code: "1172" }

const#

const = "const" identificador [ ":" identificador ] "=" expr ;

Da nombre a un valor de cualquier tipo. El tipo se infiere del valor; si se anota, debe coincidir (E001: giro is declared Angle but its value is Length; ver Tipos § Anotaciones). Si el valor no se puede evaluar (por un error), la constante no queda definida.

const trazo = 1.2mm
const giro: Angle = 30deg
const nombres = ["ANA", "LUIS"]

shape#

shape = "shape" identificador "=" expr ;

Da nombre a una forma. El valor debe ser una Shape o un Path cerrado (que se convierte); si no, E001: expected a Shape, not Length o el E004 del camino (ver Tipos § Conversiones). Una forma con nombre tiene miembros (escudo.center, escudo.width).

shape s = e equivale a const s: Shape = e, salvo que además acepta (y convierte) un camino cerrado.

shape escudo = polygon((20mm, 15mm), (80mm, 15mm), (80mm, 63mm), (50mm, 85mm), (20mm, 63mm))
shape centro = escudo.inset(3mm)
shape gota = path { from (50mm, 20mm) line (60mm, 40mm) line (40mm, 40mm) close }

param#

param = "param" identificador [ ":" identificador ] "=" expr ;

Como const, pero el valor es un valor por defecto que puede cambiar quien coloque este diseño como componente: place "parche.hoop"(nombre: "LUIS") at … (ver Control § place y Bastidor).

• El tipo del parámetro es el anotado o, sin anotación, el del valor por defecto. Si se anota y el defecto no coincide: E001: alto is declared Length but its default is Int.
• Un argumento de otro tipo es E001: nombre is String but it was given Int y se usa el valor por defecto.
• Un argumento para un parámetro que no existe es un error en el place (E007: parche.hoophas no paramnombr; did you mean nombre?).
• Como cualquier nombre, un param debe declararse antes de usarse.

// archivo completo
param nombre = "ANA"
param alto: Length = 6mm
design "Parche" { canvas: rect(size: (30mm, 12mm)) }
thread blanco = #ffffff "Blanco"
layer texto { text blanco { value: nombre, height: alto, at: (15mm, 9mm), align: center } }

layer#

layer = "layer" identificador "{" { item_de_capa } "}" ;

Una capa agrupa objetos de bordado. Las capas se bordan en el orden en que se escriben: la primera queda debajo. Dentro de una capa el compilador elige el orden de los objetos, salvo lo que fija un seq. Los elementos posibles (primitivas, seq, inside, for, if, place) están en Control y Primitivas.

• Los nombres de capa forman su propio espacio: una capa puede llamarse igual que un hilo o una constante.
• Dos capas con el mismo nombre: E007: layer a is already defined.
• Una capa puede estar vacía.

shape escudo = rect(at: (10mm, 10mm), size: (80mm, 80mm), radius: 5mm)
layer fondo { fill blanco { shape: escudo } }
layer borde { satin negro { border: escudo, width: 3mm } }

Nombres y alcance#

Todas las declaraciones con nombre de un archivo (thread, const, shape, param, los nombres importados y canvas) comparten un único espacio de nombres global. Las variables de un for se agregan a ese espacio solo durante el cuerpo del bucle (ver Control § for).

Reglas:

1. Declarar antes de usar. Un nombre se resuelve con lo declarado hasta ese punto del archivo. Usar un nombre que se declara más abajo es E007: `x` is used before it is declared (line N); uno que no se declara en ninguna parte (ni es un valor de enumerado, ver Tipos § Name), E007: unknown name x`` con sugerencia si hay uno parecido. Si la declaración de un nombre falló, sus usos no repiten el error.
2. Sin redeclaración. Un nombre ya definido como constante, forma, parámetro o hilo no puede declararse otra vez: E007: n is already defined. Si choca con un nombre importado: E007: `negro` is already imported from `colores.hoop`; rename one of them (`as` in the import).
3. Sin sombras. Una variable de for (o su índice) no puede tapar un nombre existente: E007: the loop variable i hides another name: choose another.
4. true y false siempre son Bool, aunque se declaren constantes con esos nombres.
5. Los nombres de capa no participan de este espacio.

// error E007
const a = 3mm
const a = 4mm // error E007