Pliego language reference

(* Tórculo 1.0, part 1: the grammar of the pliego language (.mesa), epoch 2.

   Normative. Notation (SPEC §1.4):
     NAME            nonterminal; every nonterminal in capitals that is not defined
                     here is a closed vocabulary of Appendix A (spec/vocabularios/
                     vocabularios.json), and that correspondence is exhaustive.
     "literal"       literal text, compared after normalization (SPEC §4.5),
                     except reserved words, which are compared as written.
     A | B           alternative          [ A ]   optional       { A }  zero or more
     TEXT            any characters up to the end of the line
     NL              end of line
     IDENT           identifier (SPEC §4.5)
     NUMBER          integer or decimal with a point, optional sign
     QUOTE           "«" TEXT-WITHOUT-» "»"      (U+00AB … U+00BB; straight quotes are not equivalent)
     ·               the field separator, U+00B7 MIDDLE DOT, with optional spaces around it

   Analysis is line oriented: each line is classified by its prefix and the
   prefix always wins (SPEC §5.1). Only section blocks and "dentro:" span lines.
   Blank lines separate clips. *)

PLIEGO          = PREAMBLE { CHAPTER } [ END ] ;
PREAMBLE        = { PREAMBLE-LINE | UNIT-LINE | SECTION | COMMENT } ;

(* ---------- preamble ---------- *)
PREAMBLE-LINE   = "MESA" [ "v" NUMBER ] TITLE
                | "formato" PROPERTY { "·" PROPERTY }
                | "ARCO" ARCO
                | "MOTIVO" QUOTE [ "—" TEXT ]
                | "ECO" IDENT ( "→" | "->" ) IDENT
                | "REPARTO" SPEAKER ":" TAMBOR [ "," VOZ ] [ "," VOICE-COLOUR ] [ "," SIDE ] [ "," "alias:" ALIAS { "·" ALIAS } ]
                | "PERSONAJE" IDENT "—" TEXT
                | "LETRA" PATH
                | "PYTHON" PATH
                | "ARCHIVO" KEY { "·" KEY }
                | "FANTASMA" ( "foto" | "texto" | "numeral" ) NUMBER
                | "RELOJES" IDENT NUMBER { IDENT NUMBER }
                | "SONIDO" TEXT
                | "EFECTOS" PATH                       (* sound profile: folder of effects and ambiences *)
                | "BANDA" PATH                         (* sound profile: folder of music cues *)
                | "MEZCLA" MEZCLA { "·" MEZCLA }       (* sound profile: "para la web" | "para cine"; "con stems" | "sin stems" *)
                | "PARTITURA" PATH                     (* cartel profile *)
                | "SOPORTE" SOPORTE                    (* oído profile *)
                | "el dial es la línea de tiempo"      (* oído profile *)
                | "baño" BOBINA ;
PROPERTY        = ASPECT-RATIO | "sala" ( "crema" | "pizarra" ) | "tirada" ( "borrador" | "definitiva" )
                | "página desnuda" | "en dos" ;
ASPECT-RATIO    = FORMATO ;
VOICE-COLOUR    = "con radio" | "seca" ;
SIDE            = "a la izquierda" | "a la derecha" | "al centro" ;

(* ---------- sections: the mirror law (SPEC §5.3) ---------- *)
SECTION         = BLOCK | IMPORT ;
BLOCK           = "#" NOMBRE-SECCION [ IDENT ] NL { SECTION-LINE } "#FIN" ;
IMPORT          = NOMBRE-SECCION PATH ;
SECTION-LINE    = FAMILY [ VALUE ] { "·" FIELD } ;
FIELD           = KEY ( " " | ": " ) VALUE ;       (* keys of several words take a colon *)
FAMILY          = FAMILIA-TALLER | CLAVE-MANO ;

(* ---------- chapter and scene ---------- *)
CHAPTER         = CHAPTER-HEAD { UNIT-LINE | SECTION | COMMENT } { SCENE | CLIP } ;
CHAPTER-HEAD    = "==" TITLE { "·" CHAPTER-ATTR } { "=" } ;
CHAPTER-ATTR    = "tensión" TENSION | "nº" NUMBER | "tambor" TAMBOR | "gigante" WORD
                | "plano fijo" PLANTILLA | "tramo" NUMBER ( "→" | "->" | "a" ) NUMBER
                | "nocturno" | "diurno" ;
SCENE           = SCENE-HEAD { UNIT-LINE | SECTION | COMMENT } { CLIP } ;
SCENE-HEAD      = "--" TITLE [ "·" HORA ] "--" ;

(* Unit lines are valid in the preamble (whole pliego), a chapter or a scene;
   the scene prevails over the chapter, the chapter over the preamble. Several
   are also valid inside a clip, for that shot only (SPEC §5.6). *)
UNIT-LINE       = CORE-UNIT-LINE | ASPECT-UNIT-LINE | SOUND-UNIT-LINE
                | CARTEL-UNIT-LINE | OIDO-UNIT-LINE | CAMERA-UNIT-LINE ;
CORE-UNIT-LINE  = "EJE" "de" IDENT "a" IDENT
                | "LUZ" DIRECCION-LUZ { "·" ( DUREZA | "rasante" ) }
                | "MUNDO" MOVIMIENTO-MUNDO [ NUMBER ] [ "·" SENTIDO ]
                | "FONDO" KEY { ARG } "·" LEJANIA [ "·" NUMBER ]
                | "DELANTE" KEY { ARG } [ "·" LEJANIA ] [ "·" "cada" NUMBER ]
                | "ESCENARIO" TEXT
                | "TABLAS" { "·" ( HORA | "suelo" NUMBER | "a sangre" | "ancho" NUMBER | "alto" NUMBER ) }
                | "ARCHIVO" KEY { "·" KEY }
                | "REPITE" QUOTE ;
ASPECT-UNIT-LINE= "MATERIA" MATERIA-SPEC
                | "BOBINA" BOBINA
                | "FORMATO" FORMATO { "·" FORMATO-MODO }
                | "ESPEJO" [ ESPEJO-LADO ]
                | "PANTALLA PARTIDA" { "·" ( "con un espejo en medio" | "que se miran" | "desigual" | "inclinada" ) }
                | "RÍO TIPOGRÁFICO" [ "·" ( RIO-MODO | "no" ) ]
                | "SIMULTÁNEO" SIMULTANEO
                | "MONTAJE" MONTAJE-SPEC { "·" MONTAJE-SPEC }
                | "HERVOR" HERVOR ;
MATERIA-SPEC    = "papel" PAPEL
                | "acuarela" [ ON-PAPER ]
                | "risografía" TAMBOR-RISO "y" TAMBOR-RISO [ "y" TAMBOR-RISO ]
                     { "·" ( DESREGISTRO | "trama" TRAMA ) } [ ON-PAPER ]
                | "pincel" [ ON-PAPER ] | "tejido" [ TAMBOR-RISO ] | "tinta" [ ON-PAPER ] | "ninguna" ;
ON-PAPER        = "sobre papel" PAPEL ;
MONTAJE-SPEC    = MONTAJE | "mezcla" QUOTE { "·" QUOTE } ;
SOUND-UNIT-LINE = "MÚSICA" ( CUE | "ninguna" )
                | "AMBIENTE" EFFECT-NAME { "·" EFFECT-NAME }
                | "ESPACIO" ESPACIO
                | "CAMA" EFFECT-NAME | "JINGLE" EFFECT-NAME ;
CARTEL-UNIT-LINE= "PALETA" COLOR-CARTEL "," COLOR-CARTEL "y" COLOR-CARTEL
                | "CARTEL" COMPOSICION { "·" COMPOSICION } ;
OIDO-UNIT-LINE  = "INTENSIDAD" ( INTENSIDAD | "de" INTENSIDAD "a" INTENSIDAD ) { "·" ( "extraña" | "con" PISTA ) }
                | "SOPORTE" SOPORTE
                | "COLOR" ( "monocromo" [ TAMBOR-RISO ] | "pleno" )
                | "LUZ" ( "de" ( QUOTE | "los focos" ) { "·" ( DIRECCION-FUENTE | TAMBOR-RISO | "en contraluz" ) }
                        | "plana" [ "·" "de estudio" ] )
                | "la cámara respira con" PISTA | "el río mide la voz" | "la luz sube con" PISTA ;
CAMERA-UNIT-LINE= ( "CÁMARA" | "CAMARA" ) CAMERA-SPEC { "·" CAMERA-SPEC }
                | "HORIZONTE" HORIZONTE
                | "CADENCIA" BLANCO-CADENCIA CADENCIA { "·" BLANCO-CADENCIA CADENCIA }
                | "GOLPES" GOLPE { "·" GOLPE }
                | "PISTA ÓPTICA" [ PISTA-LADO ] ;
CAMERA-SPEC     = LENTE | PESO-CAMARA | MANO-CAMARA | PROFUNDIDAD ;

(* ---------- clip ---------- *)
CLIP            = CLIP-HEAD { CLIP-LINE } ;
CLIP-HEAD       = "*" [ BEAT-ID ] ( FUNCION | SHOT ) [ "·" AFECTO ] [ "(máquina)" ] ;
BEAT-ID         = IDENT ;                         (* optional, stable id for the sidecar (e.g. r01_02) *)
SHOT            = { TALLA | ALTURA | FRENTE | MODO } [ "de" [ ARTICLE ] IDENT ] ;

CLIP-LINE       = CONTENT | PIECE | REAL-VIDEO | PLACEMENT | SCENE-VERB | MAP | MOVEMENT | CAMERA
                | JOURNEY | SOUND | EVENT | NESTING | UNIT-LINE | SIGN | WEAVE | CHARACTER | COMMENT ;

CONTENT         = "di" [ "(" VOZ ")" ] ":" TEXT
                | SPEAKER-LIST ":" TEXT                (* the speaker MUST be declared (REPARTO, PERSONAJE) *)
                | "letrero" [ "(" REGISTRO-LETRERO ")" ] ":" TEXT { "/" TEXT }
                | "terminal:" TEXT | "canta:" TEXT | "contenido (máquina):" TEXT
                | QUOTE                              (* a shout: at most one per clip *)
                | TEXT ;                             (* prose: the beat's content *)
SPEAKER-LIST    = SPEAKER { "/" SPEAKER } ;        (* "VECINO / LOCUTOR": the split sentence *)

PIECE           = "pon:" TIPO-PIEZA QUOTE { "·" PIECE-ATTR }
                | ( "foto" | "recorte" | "prensada" ) ":" KEY
                | "ver:" CLAVE-VIS [ "—" BODY ]
                | "pica:" KEY [ "en" NUMBER ]
                | "python:" NAME { ARG | NAME "=" VALUE } { "·" PIECE-SIZE | "·" CORTE | "·" "sin leer" }
                | ( "arriba" | "pie" | "nota" ) ":" TEXT
                | "marca:" GESTO-MARCA QUOTE ;
PIECE-ATTR      = NUMBER | "id" PATH | TAMBOR ;
PIECE-SIZE      = "grande" | "enorme" | "gigante" | "a sangre" ;

REAL-VIDEO      = "clip" [ " de fondo" | " mudo" ] ":" PATH [ "de" TIME "a" TIME ] ;
TIME            = [ DIGITS ":" ] DIGITS [ "." DIGITS ] ;

PLACEMENT       = "en" NUMBER NUMBER ":" CLIP-LINE
                | "en" PARTE-CUERPO "de" IDENT [ NUMBER NUMBER ] ":" CLIP-LINE
                | RELATION OBJECT [ "a" NUMBER ] ":" CLIP-LINE
                | RELATION "cada uno:" IDENT TEXT
                | "juntos:" LIST "—" DISPOSICION
                | ( "en el mundo" | "en el documento" ) ":" CLIP-LINE
                | "en" MATERIA-SPEC ":" CLIP-LINE          (* the material of one piece *)
                | "de" QUOTE "a" QUOTE ":" CLIP-LINE       (* the sign that flies *)
                | ( "a la izquierda" | "a la derecha" ) ":" CLIP-LINE
                | DISTANCIA ":" CLIP-LINE                  (* camera profile: depth *)
                | "en silueta:" CLIP-LINE ;                (* cartel profile *)
RELATION        = "bajo" | "sobre" | "junto a" | "delante de" | "detrás de" ;

SCENE-VERB      = IDENT "con vista" VISTA
                | IDENT "se encaja en" HOLE | "en sus huecos:" LIST
                | "recoge" IDENT | "clava" IDENT "en" IDENT
                | ( "recorta" | "dobla" | "tapa" | "traslada" ) QUOTE TEXT
                | "retira:" ( "el escenario" | "las tablas" | "el teatro" )
                | "la truca" ( "se acerca a" IDENT | "vuelve" | "se aleja" ) ;

MAP             = "mapa:" MAP-ORDER ;
MAP-ORDER       = "territorio" QUOTE { "·" ( "con" LIST | "grande" | "en" PLACE ) }
                | "línea desde" QUOTE [ "hacia" QUOTE ]
                | "la línea de" QUOTE ( "llega a otro igual" | "se hunde" | "vuelve" )
                | "conecta" QUOTE { "·" QUOTE } | "el círculo se abre" | "mira a" QUOTE
                | "en fila abajo" | "en columna izquierda" | "se va" ;

(* Movement is recognized BY THE VERB (VERBO-MOV, VERBO-RELACIONAL), never by its suffixes. *)
MOVEMENT        = [ PLACEMENT-PREFIX ] [ ARTICLE ] SUBJECT ( VERBO-MOV | VERBO-RELACIONAL ) [ DESTINATION ]
                     { "·" ( [ "por" ] TRAYECTO | MANERA | GRANULADO | REGISTRO-MOV | RASTRO ) } [ VENTANA-SPEC ]
                | SUBJECT "se funde en" SUBJECT | SUBJECT "hierve con" SUBJECT
                | "el pelo pasa de" SUBJECT "a" SUBJECT
                | SUBJECT "se sale del cuadro" [ "por la" LADO ] ;
DESTINATION     = ( "hasta" | "a" | "hacia" ) OBJECT | "fuera de campo" [ "por la" LADO ] ;
VENTANA-SPEC    = "hasta decir" QUOTE | "mientras" ;

CAMERA          = "la truca" ORDEN-TRUCA [ IDENT ] [ "en" TALLA ]
                | IDENT "mira a" IDENT | IDENT "mira a cámara"
                | [ ARTICLE ] IDENT ( "sale" | "entra" ) "por la" LADO
                | "sonido:" CRUCE-SONIDO [ NUMBER ]
                | "fuera de campo" [ "por la" LADO ] ":" TEXT
                | [ "el" ] "foco" ( "en" | "pasa a" ) IDENT [ "y en" IDENT ] | "todo en foco"
                | IDENT "está" TEXT ;                   (* a state, for continuity *)

JOURNEY         = IDENT "viaja" | IDENT "se apea"
                | "el mundo" MOVIMIENTO-MUNDO [ NUMBER ]
                | "por la ventanilla:" LIST "desfilan"
                | "por" WINDOW-OF "de" IDENT "se ve el mundo" ;

SOUND           = "sonido:" EFFECT-NAME [ SIDE ] ;      (* an effect, at its place; anchorable with "al decir" *)

CHARACTER       = SUBJECT ( ACCION-FICHA | EXPRESION | "de espaldas" | "de perfil" | "de frente"
                          | "de tres cuartos" | "de tres cuartos de espaldas" ) ;

SIGN            = "LETRA" QUOTE { "·" ( "en" TIPO-LETRA | DISPOSICION-SIGNO | SITIO-SIGNO | PIECE-SIZE
                                      | "de" COLOR-CARTEL | "sin leer" ) }
                | QUOTE "es" ( "un" | "una" ) PAPEL-SIGNO [ ( "a" | "de" ) QUOTE ]
                | [ "la" | "el" ] LETTER "de" QUOTE ( "es" | "se convierte en" ) IDENT
                | IDENT "se convierte en" [ "la" | "el" ] LETTER "de" QUOTE
                | [ "las letras de" ] QUOTE VERBO-SIGNO
                | "la raya corta" QUOTE
                | QUOTE "forma" FORMA-PALABRA
                | QUOTE "tapa a" IDENT | IDENT "tapa" QUOTE
                | "el ojo completa" QUOTE
                | "ESCALA" IDENT "como" IDENT
                | "BOSQUE de" BOSQUE ;
WEAVE           = ( "TEJE" | "SINTONIZA" ) QUOTE { "·" ( "en" TIPO-LETRA | "con la aguja del dial" | PIECE-SIZE | DISPOSICION-SIGNO ) }
                | QUOTE "se interrumpe en" QUOTE | QUOTE "sigue"
                | "los hilos de" IDENT "y" IDENT "se entretejen"
                | "FRASES" QUOTE { "·" QUOTE } ;

(* Events: a closed vocabulary with state (alive | reserved). The union of
   EVENTO, EVENTO-CARTEL, EVENTO-OYE and EVENTO-CAMARA, some with an argument. *)
EVENT           = ">" EVENT-NAME [ ARG ] { "·" ">" EVENT-NAME [ ARG ] } ;
EVENT-NAME      = EVENTO | EVENTO-CARTEL | EVENTO-OYE | EVENTO-CAMARA | ROTURA-WITH-REASON | ENCUADRE-INCOMODO ;
ROTURA-WITH-REASON = ROTURA "porque" QUOTE ;      (* breaking a rule with permission: the reason is required *)

NESTING         = "dentro:" NL { CLIP-LINE }          (* sub-clips; at most three levels *)
                | "mientras:" CLIP-LINE
                | "al decir" QUOTE ":" CLIP-LINE
                | CLIP-LINE "hasta decir" QUOTE ;

(* ---------- end ---------- *)
END             = "==" "FIN" { "=" } { TEXT } [ NL ">" "silencio" NUMBER ] ;

(* ---------- comments ---------- *)
COMMENT         = "//" TEXT                  (* technical comment: not in the IR *)
                | "(" TEXT ")"               (* author's digression: in the IR, `digresiones` *)
                | "~" "deriva:" TEXT ;       (* a commission to the engine: in the IR, `derivas` *)

(* ---------- terminals ---------- *)
ARTICLE         = "el" | "la" | "los" | "las" ;
TITLE           = QUOTE | TEXT ;
SPEAKER         = IDENT ;          (* not a reserved word; compared as written *)
CUE             = WORD ;           (* a file of BANDA, by name, case-insensitive *)
EFFECT-NAME     = WORD { WORD } ;  (* a file of EFECTOS (or BANDA), by name *)
PATH            = TEXT ;           (* relative to the pliego's folder in a portable project *)
LIST            = IDENT { "·" IDENT } ;