PLAY) e FORM)¶

Questo documento definisce la sintassi e la semantica delle due sezioni di neumaRk dedicate alla forma del brano:

PLAY) — sub-programma di esecuzione, inline fra datapack, letto nell'ordine del documento;
FORM) — descrizione panoramica della forma, una sola per documento, posizionata in fondo, per uso umano e di indicizzazione.

Le due sezioni condividono la stessa grammatica di box di sezione e lo stesso vocabolario di postfix, ma differiscono per posizione, molteplicità e ruolo semantico (imperativo vs descrittivo).

1. Definizione¶

1.1 PLAY)¶

Una sezione PLAY) contiene un sub-programma di esecuzione: una sequenza di box di sezione (con eventuali ripetizioni, dinamiche, fermate, prosa libera) eseguita al momento in cui la si incontra nel documento.

Più sezioni PLAY) possono coesistere nello stesso documento; sono lette dall'alto in basso, nell'ordine in cui appaiono.

1.2 FORM)¶

Una sezione FORM) contiene una descrizione panoramica della forma del brano (es. "AABA con coda", oppure prosa estesa che dettaglia articolazione e dinamica delle sezioni). Esiste al massimo una FORM) per documento, posizionata in fondo.

FORM) non è eseguibile: ha valore descrittivo, per il lettore umano e per l'indicizzazione/ricerca.

In una playlist, una voce può dichiarare un proprio form che sostituisce la FORM) del brano per quell'occorrenza ("la forma di stasera è questa"). È un overlay descrittivo a livello di scaletta, non eseguito; PLAY), essendo posizionale, non è esprimibile a quel livello. Vedi neumaRk_collections.md §8.

1.3 Distinzione semantica¶

Aspetto	`PLAY)`	`FORM)`
Ruolo	imperativo ("esegui questo")	descrittivo ("ecco la forma")
Molteplicità	multiple, inline	al massimo una, in fondo
Esecuzione	segue	ignora
Uso	guida all'esecuzione	summary, ricerca, didattica

La scelta fra "l'esecuzione segue PLAY" e "l'esecuzione segue il flusso naturale dei datapack" non è una proprietà del documento: è una preferenza di chi legge, conservata dall'host. Il documento contiene entrambe le forme di informazione; chi legge decide cosa visualizzare/eseguire.

2. Posizione strutturale¶

2.1 PLAY)¶

È una riga di sezione, marcata da PLAY) come primo token.
Compare fra datapack, mai dentro un datapack.
È non ricorsiva by design: una PLAY) non può apparire come riga interna di un'altra PLAY). Garanzia statica del parser.
Una PLAY) può estendersi su più righe del documento: il newline è whitespace dentro la sezione (vedi §6).

La sezione PLAY) termina alla riga vuota (§6.1) o al primo marcatore di riga esplicito non escapato: regola unica dei blocchi a testo libero, neumaRk_datapack.md §13. Un box [NOME] da solo su una riga resta contenuto della PLAY).

2.2 FORM)¶

È una riga di sezione, marcata da FORM) come primo token.
Compare alla fine del documento, dopo l'ultimo datapack.
È unica per documento. Più FORM) producono warning W140.
Una FORM) può estendersi su più righe (newline = whitespace).

FORM) termina come PLAY) (§2.1): alla riga vuota o al primo marcatore di riga esplicito (neumaRk_datapack.md §13).

3. Grammatica del box di sezione¶

Sia in PLAY) sia in FORM), l'unità atomica è il box di sezione:

SECTION_BOX  := TOP_LABEL? '[' NAME ('|' BARS)? ']' POSTFIX*
TOP_LABEL    := '"text"'           // adiacente, no spazio
POSTFIX      := REPEAT | DYNAMIC | HAIRPIN | KEYWORD | BOTTOM_LABEL
                                    // tutti adiacenti al precedente

Tutti i token del box sono adiacenti: nessuno spazio fra top-label, parentesi quadre, postfix.

3.1 NAME¶

Il NAME dentro […] è il nome di una sezione definita da una riga M) del documento (neumaRk_markers.md §3). Il matching è per text-equality sul contenuto della sezione (dopo strip del markup, vedi neumaRk_text_markup.md).

Il binding è selettivo: vengono considerate solo le sezioni […] di M) (incluse le collassabili [? NAME], con il prefisso ? ignorato nel matching). Le annotazioni "…" di M) non sono referenziabili da PLAY) / FORM) (vedi neumaRk_markers.md §3.1).

Nel NAME \] è una ] letterale e non chiude il box (neumaRk_text_markup.md §4): [Coda \] finale] riferisce la sezione scritta [Coda \] finale] in M), che si legge Coda ] finale.

Esempi:

[A]       riferisce una sezione [A] in M)
[Intro]   riferisce [Intro] o [? Intro] (prefisso ? ignorato)
[Solo 1]  multi-parola, riferisce [Solo 1] o [? Solo 1]

Una "freely" in M) non è target valido: [freely] in PLAY/FORM sarebbe reference broken (vedi §7.3).

Se il NAME non corrisponde a nessun marker definito nel documento, il box è reference broken: viene renderizzato come testo non-cliccabile, non eseguito, e non genera errore o warning (vedi §7.3).

3.2 Durata in misure `[NAME|BARS]`¶

Opzionale: un | interno e un numero di battute.

[A|8]     A per 8 misure (informativo)
[B|4]     B per 4 misure
[A]       A senza durata dichiarata

BARS è un intero positivo (1–999). Decimali, zero o negativi producono warning W141.

La durata in [NAME|BARS] ha valore puramente informativo: è un hint grafico per il lettore. Non viene confrontata con l'estensione reale della sezione marcata M); è responsabilità di chi scrive mantenere coerenza. Nessun warning o errore in caso di discrepanza.

Le durate sono ammesse solo in PLAY) / FORM). Un marker in M) non ammette |N (vedi neumaRk_markers.md).

3.3 Top e bottom label¶

Top label: container "…" adiacente prima di [. Bottom label: container "…" adiacente dopo la parentesi quadra chiusa (può apparire come postfix in qualsiasi ordine, vedi §3.4).

"Tema"[A|8]                  solo top
[A|8]"Variazione"            solo bottom
"Tema"[A|8]"con feeling"     top + bottom

Le label ammettono solo il container "…" (senza box). La forma […] collide grammaticalmente con il box di sezione e non è ammessa come label.

Le label sono soggette al markup unificato di neumaRk_text_markup.md. Stile di default: plain, dimensione media.

Una label va a capo sul ; (neumaRk_text_markup.md §3bis) e, riga per riga, anche quando è più larga del box. Le righe restano centrate sul box; la label sopra cresce verso l'alto, quella sotto verso il basso.

"Tema;uno"[A|8]"con;feeling"     top e bottom su due righe

3.4 Postfix¶

Sono tutti adiacenti al token precedente (no spazi). L'ordine fra postfix è libero: il parser identifica ogni postfix per la sua forma. La pluralità è ammessa solo per la bottom label (una sola per box) e per le keyword (più keyword distinte possibili).

3.4.1 Repeat count¶

xN con N in 2–99 indica numero di esecuzioni:

[A|8]x2       esegui A due volte (×2)
[A|8]x4       esegui A quattro volte

x1 o xN con N > 99 produce warning W142 (recuperabile, count clampato). x0 invece è contraddittorio («esegui 0 volte» → il materiale non viene mai eseguito) e produce l'errore E302.

3.4.2 Dynamic¶

Dynamic puntuale del vocabolario D) (vedi neumaRk_dynamics.md §3.1):

[A|8]ff       sezione A a fortissimo
[B|4]p        sezione B a piano

Vale per tutta la durata della sezione.

3.4.3 Hairpin¶

< o > adiacenti aprono un hairpin solo dentro il box di apertura: si chiude alla prossima dynamic adiacente, anch'essa dentro lo stesso postfix-stack.

[A|8]<ff      cresc. fino a ff alla fine della sezione
[B|4]>p       decresc. fino a p

Hairpin non cross-box: [A|8]< [B|4]ff apre un hairpin che non trova chiusura nel box A e viene chiuso implicitamente a fine box. Nessun errore, render decide la rappresentazione.

3.4.4 Keyword¶

Famiglia &keyword, case-insensitive, prefix per estensioni future.

Keyword	Effetto
`&fermata`	corona sul beat finale della sezione
`&caesura`	cesura dopo la sezione
`&breath`	respiro dopo la sezione
`&GP`	grand pause dopo la sezione
`&niente`	dinamica "al niente" (decresc. fino a estinguersi)

Le keyword sono riservate: keyword sconosciute producono warning W143. La lista è estendibile in versioni future della spec.

3.4.5 Bottom label¶

Container "…" adiacente, vedi §3.3.

3.5 Esempi di box completi¶

[A]                            riferimento minimale
[A|8]                          A per 8 misure
"Tema"[A|8]                    A con top label
[A|8]x2&fermata                A ripetuto 2× con corona finale
"Tema"[A|8]ff<>p"crescendo"x2  combinazione complessa
[FREE IMPRO!]                  reference broken (no marker omonimo)

4. Token speciali ammessi in PLAY/FORM¶

Oltre ai box di sezione, sono ammessi:

Token	Effetto
`$`	segno (segno musicale, target di D.S.)
`@`	coda (target di D.C. al Coda)
`&fermata`	corona stand-alone (fuori da un box)
`;`	a capo nella resa (§6.3), nessun effetto sull'esecuzione

I primi tre token mantengono la stessa semantica dei decorator inline omonimi delle righe musicali (vedi neumaRk_flow_and_repeats.md).

5. Prosa libera¶

Tutto ciò che non è un token strutturale (box, &keyword, $, @, ;) è prosa libera in modalità markup neumaRk_text_markup.md.

PLAY) [Intro] then go to [A|8] twice [A|8]x2 finally [Outro]

In questo esempio "then go to", "twice", "finally" sono prosa libera interpolata fra box. Vengono renderizzate come testo descrittivo nel display della PLAY (es. in una banda separata o accanto al box).

La prosa libera in PLAY) non è eseguita: si eseguono solo i box e i token strutturali. La prosa libera è valore esclusivamente informativo per il lettore.

Due forme fra parentesi quadre sono prosa, non box: il richiamo footnote [^etichetta] e il link [testo=>url] (neumaRk_text_markup.md §3ter e §3quater). Un […] che comincia con ^ o contiene => non apre mai un box di sezione:

PLAY) [A|8]x2 come nel [disco del 1961=>https://example.org/lp] [B|8]

In FORM), l'intero contenuto è prosa descrittiva con box di sezione interpolati: di FORM) non si esegue nulla in ogni caso.

Lo stesso corpo descrittivo si scrive anche nella riga di formato F), accanto a un sistema corto: F) |* On cue, D.S. al @ (neumaRk_datapack.md §9.1).

6. Whitespace e continuazione¶

6.1 Newline = whitespace, blank line = terminator¶

Dentro PLAY) e FORM), un singolo newline ha lo stesso valore di uno spazio: la sezione può estendersi su quante righe l'utente preferisce, semplicemente proseguendo (eventualmente con indentazione) sulla riga successiva.

PLAY) [Intro]
      [A|8]x4
      [B|8]
      [A|8]
      [Outro]&fermata

è equivalente a:

PLAY) [Intro] [A|8]x4 [B|8] [A|8] [Outro]&fermata

Una riga vuota (blank line) invece chiude la sezione, coerentemente con la convenzione del resto del linguaggio NRK dove una blank line separa i datapack. Quanto segue è quindi interpretato fuori dalla PLAY):

PLAY) [Intro]
      [A|8]

C7
a

Le tre righe C7 / a formano un nuovo datapack indipendente; la sezione PLAY) si è chiusa dopo [A|8].

6.2 Continuazione esplicita¶

Non è richiesto alcun carattere di continuazione. La sezione termina alla riga vuota, al primo marcatore di riga esplicito non escapato (neumaRk_datapack.md §13) o a fine documento. Una riga di prosa che comincia con un marcatore si scrive con \ davanti (\N) …); il \ si toglie alla resa.

6.3 A capo forzato: `;`¶

Gli elementi di una sezione si dispongono in riga e vanno a capo da soli solo quando la riga è piena. Per andare a capo in un punto preciso si scrive un ;, come nei container (neumaRk_text_markup.md §3bis):

PLAY) [Intro] [A|8]x2 ; [B|8] [A|8] [Outro]&fermata

[Intro] e [A|8]x2 stanno sulla prima riga, il resto sulla seconda.

Ogni ; non escapato va a capo, anche attaccato a una parola: poi;[B] è «poi», a capo, [B]. Per stampare un ; si scrive \; (neumaRk_text_markup.md §4).
Il ; separa come uno spazio: @;[B] è una coda, poi a capo.
Un ; in testa, in coda o ripetuto (; ;) non produce righe vuote.
Il ; è solo resa: non cambia l'esecuzione e non separa la sezione in due.

7. Semantica di esecuzione¶

7.1 Modello base¶

Senza alcun PLAY) nel documento, i datapack sono eseguiti nell'ordine del documento, applicando i decorator standard (volte, ripetizioni, D.S., D.C., coda) descritti in neumaRk_flow_and_repeats.md.

7.2 Con `PLAY)`¶

Quando si incontra una sezione PLAY), si esegue il sub-programma in essa contenuto al posto del flusso naturale dei datapack a quel punto. Esaurita la PLAY), l'esecuzione prosegue dal datapack immediatamente successivo nel documento.

Multiple PLAY) consecutive sono lette in ordine ed eseguite ciascuna a turno. Datapack interposti fra una PLAY) e l'altra sono ignorati dal flusso eseguito, se referenziati da box di sezione dentro le PLAY) (i datapack sono comunque tabellati per nome marker; servono come "definizione" delle sezioni, non come flusso lineare).

7.3 Reference broken¶

Un box [NAME] il cui NAME non corrisponde a nessun marker M) del documento è reference broken:

viene renderizzato come testo non-cliccabile (visibile, marcato come irrisolvibile);
non viene eseguito;
non genera warning o errore.

Questo permette di scrivere PLAY/FORM come sketch o annotazione informale senza vincoli sulla coerenza con i marker del documento.

7.4 Esecuzione di un box¶

L'esecuzione di un box [A|8]ff<x2&fermata consiste in:

salto al primo datapack la cui riga M) contiene il marker A;
applicazione della dinamica ff come dynamic iniziale della sezione;
esecuzione di tutti i datapack della sezione A (fino al prossimo marker o fine documento), con hairpin < se presente;
ripetizione N volte (per xN);
corona finale (per &fermata).

La durata |8 non influisce sull'esecuzione: l'estensione effettiva è data dai datapack del documento.

8. Render¶

8.1 PLAY)¶

Le sezioni PLAY) sono renderizzate come banda compatta sopra o sotto lo score, con i box di sezione disegnati come rettangoli con NAME e durata (se presente). Le label, dinamiche, hairpin e keyword sono renderizzate accanto al box secondo le convenzioni tipografiche musicali.

I box reference broken sono renderizzati con un riquadro distinto da quello dei riferimenti risolti (bordo più sottile, angoli più arrotondati), con il testo nello stile normale: segnalano l'irrisolvibilità senza ostacolare la lettura.

8.2 FORM)¶

Le sezioni FORM) sono renderizzate come blocco descrittivo in calce al documento, con prosa Markdown interpolata ai box di sezione. Lo stile è meno enfatico di PLAY): testo body, box con bordo sottile.

8.3 Markup¶

Tutti i testi (top/bottom label, prosa libera) supportano il markup unificato di neumaRk_text_markup.md §3. Lo stile di default è quello indicato in neumaRk_text_markup.md §5 (label: plain ridotto; prosa PLAY/FORM: plain body).

9. Diagnostica¶

9.1 Codici diagnostici¶

Codice	Descrizione
W140	Più di una sezione `FORM)` nel documento
W141	Durata `\|BARS` non valida (atteso intero 1–999)
W142	Repeat count `xN` fuori range (atteso 2–99)
W143	Keyword `&xxx` non riservata
W145	`FORM)` non in fondo al documento (datapack successivi a `FORM)`)
E302	Repeat count `x0` (contraddittorio: «esegui 0 volte»)

PLAY) nidificata (dentro un'altra PLAY) o dentro un datapack) è impedita strutturalmente (§3, non-ricorsiva by design): il parser non la produce mai e non emette alcuna diagnostica. Il codice W144 è usato dal parser per la legatura A) malformata (vedi neumaRk_articulations.md).

9.2 Non-errori¶

I seguenti non sono errori (vedi §3.1, §3.2):

box [NAME] con NAME non riconducibile a nessun marker (reference broken);
discrepanza fra durata |N dichiarata e numero reale di misure della sezione;
hairpin aperto senza chiusura entro fine box;
prosa libera con caratteri arbitrari (purché non coincida con pattern strutturali).

10. Esempi¶

10.1 PLAY minimale¶

M) [Intro]
// … datapack Intro …

M) [A]
// … datapack A …

M) [B]
// … datapack B …

PLAY) [Intro] [A|8]x2 [B|8] [A|8]

Esecuzione: Intro → A → A → B → A.

10.2 PLAY con dinamiche e keyword¶

PLAY) [Intro]p [A|8]<ff [B|4]x2 [A|8]>pp&fermata

Intro a piano.
A con crescendo fino a ff su 8 misure.
B ripetuto 2 volte (mantiene ff).
A con decresc. fino a pp, corona finale.

10.3 PLAY con prosa libera¶

PLAY) Start with [Intro] freely.
      Then [A|8] twice, then [B|8].
      Optional [C|4] if vibe is right.
      End on [Outro] &fermata.

Prosa interpolata serve il lettore; si eseguono solo i box: Intro → A → A → B → C → Outro+fermata.

10.4 FORM descrittiva¶

M) [Intro]
// …

M) [A]
// …

M) [B]
// …

FORM) Standard AABA jazz: [Intro|4] sets the mood, then
      [A|8] is the main theme, [A|8] repeats with melodic
      variation, [B|8] is the bridge (modulating to IV), and
      a final [A|8] resolves to a [Coda|4] tag.

FORM) descrive la forma; non è eseguita (l'esecuzione segue il flusso documento o eventuali PLAY) separate).

10.5 Reference broken (sketch informale)¶

PLAY) [Intro] [FREE IMPRO! whatever feels right] [A|8] [Outro]

[FREE IMPRO! whatever feels right] non è un marker definito: viene renderizzato come testo descrittivo (irrisolvibile) e saltato. Esecuzione: Intro → A → Outro.

10.6 Multiple PLAY in sequenza¶

M) [A]
// …

M) [B]
// …

PLAY) [A|8] [B|8]

M) [C]
// …

PLAY) [C|8]x3 &fermata

Esecuzione: A → B (prima PLAY), poi C → C → C con corona (seconda PLAY). Il datapack [C] definisce la sezione referenziata dalla seconda PLAY ma non viene eseguito linearmente dal flusso documento (è già coperto dalla seconda PLAY).

10.7 Toggle PLAY vs flow naturale¶

Lo stesso documento può essere:

letto come PLAY: si seguono la/le PLAY) e si ignora il flusso lineare dei datapack;
letto come flow: le PLAY) sono ignorate e si seguono i datapack in ordine documento.

La scelta è una preferenza di chi legge (§1.3), non proprietà del documento.

11. Riassunto¶

Concetto	Sintassi	Sezione
Sezione PLAY	`PLAY) …`	§1.1
Sezione FORM	`FORM) …`	§1.2
Box di sezione	`"top"?[NAME(\|BARS)?]POSTFIX*`	§3
Top label	`"text"` adiacente prima di `[`	§3.3
Bottom label	`"text"` adiacente come postfix	§3.3
Repeat count	`xN` (N 2–99)	§3.4.1
Dynamic	`p`/`mp`/`mf`/`f`/`ff`/`sf`/`sfz` postfix	§3.4.2
Hairpin	`<` / `>` postfix (no cross-box)	§3.4.3
Keyword	`&fermata`/`&caesura`/`&breath`/`&GP`/`&niente`	§3.4.4
Segno / coda	`$` / `@`	§4
Prosa libera	tutto ciò che non è token strutturale	§5
Whitespace	newline = spazio	§6
A capo	`;` (letterale: `\;`)	§6.3
Reference broken	`[NAME]` senza marker omonimo, non eseguito	§7.3
Durata informativa	`\|BARS` solo grafica, no controllo	§3.2
Toggle PLAY/flow	preferenza di chi legge, non nel file	§1.3

Questo documento definisce PLAY) e FORM) come le due sezioni di neumaRk dedicate alla forma del brano, completando il vocabolario strutturale del linguaggio insieme a M) marker, D) annotation e play directive.