Visualizza wikitesto di Progetto:BridgeShape API

Documentazione BridgeShape: [[Progetto:BridgeShape Motore e frontend|Motore e frontend]] · [[Progetto:BridgeShape Ricette DSL|Ricette DSL]]

= BridgeShape — API per Generatori di Smazzate =

Documentazione tecnica per chi sviluppa un generatore di smazzate di test
che legge i vincoli di distribuzione (shape constraints) dalle convenzioni
di BridgePedia.

== Panoramica ==

Ogni pagina wiki di convenzione su BridgePedia può definire nel template
<code><nowiki>{{Convenzione}}</nowiki></code> un campo <code><nowiki>shape_constraints</nowiki></code> che descrive, in un formato
DSL compatto, i vincoli di distribuzione delle mani dei 4 giocatori al tavolo.

L'estensione '''BridgeShape''' espone un'API REST/JSON per leggere questi
vincoli in modo strutturato.

----

== API Endpoint ==

<syntaxhighlight lang="text">
GET /api.php?action=bridgeshape&shapeaction=ACTION&format=json
</syntaxhighlight>

=== Azioni disponibili ===

{| class="wikitable"
! Azione
! Descrizione
! Parametri
|-
| <code><nowiki>get</nowiki></code>
| Vincoli per una singola convenzione
| <code><nowiki>pageid</nowiki></code> oppure <code><nowiki>title</nowiki></code>
|-
| <code><nowiki>list</nowiki></code>
| Elenco convenzioni con vincoli definiti
| —
|-
| <code><nowiki>listall</nowiki></code>
| Elenco tutte le convenzioni (con/senza vincoli)
| —
|-
| <code><nowiki>validate</nowiki></code>
| Valida una stringa DSL senza bisogno di una pagina wiki
| <code><nowiki>dsl</nowiki></code>
|}

=== Esempi di chiamata ===

<syntaxhighlight lang="bash">
# Per titolo pagina
curl "https://bridgepedia.it/api.php?action=bridgeshape&shapeaction=get&title=Splinter&format=json"

# Per page ID
curl "https://bridgepedia.it/api.php?action=bridgeshape&shapeaction=get&pageid=42&format=json"

# Elenco pagine con vincoli
curl "https://bridgepedia.it/api.php?action=bridgeshape&shapeaction=list&format=json"

# Validare una stringa DSL
curl "https://bridgepedia.it/api.php?action=bridgeshape&shapeaction=validate&dsl=opener+H:5%2B+hcp:12-21&format=json"
</syntaxhighlight>

----

== Formato risposta JSON ==

=== <code><nowiki>shapeaction=get</nowiki></code> ===

<syntaxhighlight lang="json">
{
  "shapeconstraints": {
    "pageId": 42,
    "raw": "1H-4C: opener H:5+ hcp:12-21; responder H:4+ C:0-1 Chcp:0 hcp:10-15 // ...",
    "scenarios": [
      {
        "label": "1H-4C",
        "positions": {
          "opener": {
            "suits": {
              "H": { "min": 5, "max": null }
            },
            "hcp": { "min": 12, "max": 21 }
          },
          "responder": {
            "suits": {
              "H": { "min": 4, "max": null },
              "C": { "min": 0, "max": 1 }
            },
            "suit_hcp": {
              "C": { "min": 0, "max": 0 }
            },
            "hcp": { "min": 10, "max": 15 }
          }
        },
        "fit": []
      }
    ]
  }
}
</syntaxhighlight>

'''Descrizioni leggibili.''' Insieme a <code><nowiki>scenarios</nowiki></code>, <code><nowiki>get</nowiki></code> e <code><nowiki>validate</nowiki></code> restituiscono
<code><nowiki>descriptions</nowiki></code> (stesso ordine): per ogni scenario <code><nowiki>label</nowiki></code>, <code><nowiki>positions</nowiki></code>
(per posizione, elenco di frasi già tradotte, es. <code><nowiki>"♠: ha K J 10 (e non A Q 9)"</nowiki></code>),
<code><nowiki>positionLabels</nowiki></code> (nome del ruolo, es. "Attaccante" se la pagina ha <code><nowiki>shape_roles</nowiki></code>;
altrimenti "Apertore (chi usa la convenzione)", "Compagno", ...) e <code><nowiki>fit</nowiki></code>.
Parametro opzionale <code><nowiki>lang</nowiki></code> (it, en, ...; default lingua dell'API, di solito <code><nowiki>it</nowiki></code>).
Serve a mostrare nell'interfaccia di Play '''perché''' la mano è fatta così.
Nella posizione compare anche <code><nowiki>quiet: 1</nowiki></code> se è stata usata la macro <code><nowiki>quiet</nowiki></code>.

=== <code><nowiki>shapeaction=list</nowiki></code> ===

<syntaxhighlight lang="json">
{
  "pages": [
    {
      "pageId": 42,
      "title": "Splinter",
      "scenarioCount": 6,
      "labels": ["1H-4C", "1H-4D", "1H-4S", "1S-4C", "1S-4D", "1S-4H"]
    },
    {
      "pageId": 15,
      "title": "Stayman",
      "scenarioCount": 2,
      "labels": ["fit a cuori", "fit a picche"]
    }
  ]
}
</syntaxhighlight>

----

== Formato DSL ==

Il DSL (Domain Specific Language) è la stringa scritta nel campo
<code><nowiki>shape_constraints</nowiki></code> del template wiki.

=== Struttura ===

<syntaxhighlight lang="text">
etichetta: vincoli posizione; vincoli posizione // etichetta: vincoli // ...
</syntaxhighlight>

* '''<code><nowiki>//</nowiki></code>''' separa gli scenari (il generatore ne sceglie uno random o li presenta all'utente)
* '''<code><nowiki>;</nowiki></code>''' separa le posizioni dentro uno scenario
* Ogni scenario ha un''''etichetta''' opzionale seguita da <code><nowiki>:</nowiki></code>
* Ogni posizione inizia col nome del ruolo, seguito da vincoli separati da spazi

=== Posizioni ===

{| class="wikitable"
! Nome
! Ruolo
|-
| <code><nowiki>opener</nowiki></code>
| Chi apre o fa la prima licita convenzionale
|-
| <code><nowiki>responder</nowiki></code>
| Il compagno dell'opener
|-
| <code><nowiki>opp1</nowiki></code>
| Avversario a sinistra dell'opener
|-
| <code><nowiki>opp2</nowiki></code>
| Avversario a destra dell'opener (compagno di opp1)
|}

=== Vincoli ===

==== Lunghezza seme (specifico) ====

<syntaxhighlight lang="text">
S:5+       — almeno 5 picche
H:0-1      — 0 o 1 cuori
D:3        — esattamente 3 quadri
C:2-5      — da 2 a 5 fiori
</syntaxhighlight>

Semi: <code><nowiki>S</nowiki></code> = Spades/Picche, <code><nowiki>H</nowiki></code> = Hearts/Cuori, <code><nowiki>D</nowiki></code> = Diamonds/Quadri, <code><nowiki>C</nowiki></code> = Clubs/Fiori

==== Lunghezza seme (wildcard) ====

<syntaxhighlight lang="text">
x:0-1      — un seme qualsiasi (tra quelli non specificati) con 0-1 carte
x:6+       — un seme non specificato con almeno 6 carte
</syntaxhighlight>

Il generatore sceglie casualmente quale seme assegnare a <code><nowiki>x</nowiki></code> tra quelli
non già vincolati esplicitamente (S/H/D/C).

==== HCP totali ====

<syntaxhighlight lang="text">
hcp:15-17  — da 15 a 17 punti onore
hcp:12+    — almeno 12 punti
hcp:0-7    — da 0 a 7 punti
</syntaxhighlight>

==== HCP nel seme (specifico) ====

<syntaxhighlight lang="text">
Shcp:3+    — almeno 3 HCP a picche
Chcp:0     — 0 HCP a fiori (nessun onore)
Hhcp:0-2   — da 0 a 2 HCP a cuori
</syntaxhighlight>

==== HCP nel seme (wildcard) ====

<syntaxhighlight lang="text">
xhcp:0     — 0 HCP nel seme wildcard (x)
xhcp:0-1   — 0-1 HCP nel seme x
</syntaxhighlight>

==== Shape class ====

<syntaxhighlight lang="text">
shape:balanced      — distribuzione bilanciata (4333, 4432, 5332)
shape:semi_balanced — semibilanciata (5422, 6322)
shape:one_suiter    — monocolore
shape:two_suiter    — bicolore
shape:three_suiter  — tricolore
shape:any           — qualsiasi (default)
</syntaxhighlight>

==== Onori esatti in un seme (<code><nowiki>S=KJT</nowiki></code>) ====

<syntaxhighlight lang="text">
S=KJT      — in picche ha K, J e 10; NON ha A, Q, 9 (le carte basse 8-2 completano)
S=KT9      — sequenza interna: K, 10, 9; NON ha A, Q, J
H=Q        — a cuori ha la Q come unico onore tra A K Q J 10
D=x        — nessun onore a quadri (solo carte basse)
</syntaxhighlight>

Le lettere ammesse sono <code><nowiki>A K Q J T 9</nowiki></code> (anche <code><nowiki>10</nowiki></code>). La regola è: '''le carte elencate sono possedute, le altre tra A K Q J 10 9 NON lo sono'''; le carte
dall'8 in giù sono libere e riempiono fino alla lunghezza del seme. Serve a
descrivere attacchi (sequenza interrotta <code><nowiki>KJT</nowiki></code>, interna <code><nowiki>KT</nowiki></code>, sotto onore <code><nowiki>K</nowiki></code> o
<code><nowiki>Q</nowiki></code>) e le carte del compagno. Si combina con la lunghezza (<code><nowiki>S:5 S=KJT</nowiki></code>).

Nel JSON compare <code><nowiki>suit_cards</nowiki></code> nella posizione, es. <code><nowiki>{"S": "KJT", "H": ""}</nowiki></code>
(stringa vuota = nessuna carta alta). Il generatore deve:
* assegnare esattamente quegli onori alla mano e '''escluderli''' dalle altre mani del seme; gli onori non nominati da nessuna posizione sono distribuiti a caso, ma mai a una posizione con <code><nowiki>suit_cards</nowiki></code> per quel seme che non li elenca;
* rispettare comunque <code><nowiki>suits</nowiki></code> e <code><nowiki>suit_hcp</nowiki></code> (la validazione segnala le contraddizioni, es. <code><nowiki>S=KQ Shcp:0-2</nowiki></code> o lo stesso onore a due mani).

==== Pattern di mano in un seme (<code><nowiki>S~...</nowiki></code>, stile regex) ====

Descrive '''l'intera mano in quel seme''', dall'alto in basso, come una piccola
espressione regolare ancorata (inizio e fine):

<syntaxhighlight lang="text">
S~AKQ.          — A, K, Q + una carta bassa (4 carte)
S~A...          — A + tre carte basse (4 carte)
S~AJT9.         — A, J, 10, 9 + una bassa
S~AKQ.|A...     — alternative: una OPPURE l'altra
S~[KQ]x{2,3}    — K o Q (come unico onore) + 2 o 3 carte basse
S~KJT.*         — K, J, 10 + qualunque numero di basse (anche zero)
</syntaxhighlight>

Elementi:
* '''Carte alte''' <code><nowiki>A K Q J T 9</nowiki></code> (anche <code><nowiki>10</nowiki></code>), '''sempre in ordine decrescente''', ciascuna posseduta; quelle non nominate tra A K Q J 10 9 NON sono possedute.
* '''Classe''' <code><nowiki>[KQ]</nowiki></code> = una carta tra quelle (si espande in alternative).
* '''Carta bassa''' <code><nowiki>.</nowiki></code> (o <code><nowiki>x</nowiki></code>) = una carta qualsiasi tra 8 e 2; compare solo in fondo. Quantificatori: <code><nowiki>?</nowiki></code> (0-1), <code><nowiki>*</nowiki></code> (0 o più), <code><nowiki>+</nowiki></code> (1 o più), <code><nowiki>{n}</nowiki></code>, <code><nowiki>{n,m}</nowiki></code>. Più punti si sommano (<code><nowiki>...</nowiki></code> = tre basse).
* '''Alternative''' <code><nowiki>&#124;</nowiki></code>: il generatore ne sceglie una a caso per ogni mano.

È la forma più espressiva di <code><nowiki>S=KJT</nowiki></code> (che resta valida): il pattern fissa anche
la lunghezza (<code><nowiki>S~A...</nowiki></code> = 4 carte). Se c'è anche <code><nowiki>S:N</nowiki></code> i due vincoli devono
essere compatibili (la validazione API segnala le incompatibilità).

Nel JSON compare <code><nowiki>suit_patterns</nowiki></code> nella posizione, già '''normalizzato''' (classi
espanse, quantificatori risolti), così il generatore non deve interpretare la
regex:

<syntaxhighlight lang="json">
"suit_patterns": {
  "S": [
    {"cards": "AKQ", "low_min": 1, "low_max": 1},
    {"cards": "A",   "low_min": 3, "low_max": 3}
  ]
}
</syntaxhighlight>

<code><nowiki>cards</nowiki></code> = carte alte possedute (ordine A K Q J T 9); <code><nowiki>low_min</nowiki></code>/<code><nowiki>low_max</nowiki></code> =
numero di carte basse (2-8), <code><nowiki>low_max: null</nowiki></code> = nessun limite. La lunghezza del
seme è <code><nowiki>len(cards) + numero di basse</nowiki></code>. Il generatore sceglie una alternativa e
rispetta anche <code><nowiki>suits</nowiki></code> e <code><nowiki>suit_hcp</nowiki></code>. Gli onori di <code><nowiki>cards</nowiki></code> vanno esclusi dalle altre
mani; quelli non nominati nella mano vanno ad altri a caso.

==== Avversari "quiet" (nessun intervento) ====

<syntaxhighlight lang="text">
opp1 quiet           — solo per opp1/opp2
opp2 quiet:0-7       — come quiet, ma con HCP personalizzati
</syntaxhighlight>

<code><nowiki>quiet</nowiki></code> è una '''macro espansa dall'API''': nel JSON non compare mai la parola
<code><nowiki>quiet</nowiki></code>, ma i vincoli già risolti. Chi legge l'API (il generatore) non deve
implementare nulla di nuovo. Si espande in:

<syntaxhighlight lang="text">
S:0-4 H:0-4 D:0-5 C:0-5 hcp:0-9 Shcp:0-3 Hhcp:0-3 Dhcp:0-4 Chcp:0-4
(con quiet:0-7 → hcp:0-7)
</syntaxhighlight>

Significato: gli avversari possono avere colori lunghi (così le mani sono
varie), ma poveri di onori e con pochi punti: nessun colore da 6+ carte
(niente apertura di sbarramento), nessun contro informativo, nessun intervento
naturale credibile. Le distribuzioni ammesse sono quindi molte, ma con punti
ridotti: il generatore ha meno margine sugli HCP della coppia dichiarante
(40 punti totali: apertore+rispondente restano sopra ~22).
I token espliciti scritti sulla stessa posizione '''sostituiscono''' i default,
in qualsiasi ordine: <code><nowiki>opp1 quiet S:0-4</nowiki></code> lascia le picche 0-4 e tiene il resto.
Su <code><nowiki>opener</nowiki></code>/<code><nowiki>responder</nowiki></code> la macro viene ignorata.

==== Fit (vincolo cross-posizione) ====

<syntaxhighlight lang="text">
fit:H8+    — almeno 8 cuori totali tra i compagni
fit:S9+    — almeno 9 picche totali tra i compagni
fit:M8+    — almeno 8 carte in un seme maggiore (H o S)
fit:m8+    — almeno 8 carte in un seme minore (D o C)
fit:8+     — almeno 8 carte in un seme qualsiasi
</syntaxhighlight>

Il fit si applica tra '''compagni''':
* Se appare su <code><nowiki>opener</nowiki></code> o <code><nowiki>responder</nowiki></code>, o a livello di scenario → coppia dichiarante
* Se appare su <code><nowiki>opp1</nowiki></code> o <code><nowiki>opp2</nowiki></code> → coppia difensiva

=== Formato range ===

{| class="wikitable"
! Sintassi
! Significato
|-
| <code><nowiki>5+</nowiki></code>
| Almeno 5 (min=5, max=null)
|-
| <code><nowiki>0-1</nowiki></code>
| Da 0 a 1 (min=0, max=1)
|-
| <code><nowiki>3</nowiki></code>
| Esattamente 3 (min=3, max=3)
|-
| <code><nowiki>12-21</nowiki></code>
| Da 12 a 21 (min=12, max=21)
|}

Nella risposta JSON, <code><nowiki>max: null</nowiki></code> significa "nessun limite superiore".

=== Semi non menzionati ===

I semi '''non vincolati''' e non coperti da <code><nowiki>x:</nowiki></code> sono distribuiti '''casualmente'''
dal generatore, rispettando il vincolo che il totale delle carte per mano sia 13.

----

== DSL versione 2 (<code><nowiki>dslVersion: 2</nowiki></code>) ==

Tutto ciò che sopra resta valido e '''invariato''': i campi v1 hanno lo stesso significato di prima.
La v2 aggiunge sintassi nuova; '''ogni scenario ha nel JSON il campo <code><nowiki>requires</nowiki></code>''' (elenco di tag,
vuoto se usa solo la v1; vedi sotto) così un motore parziale può rifiutare uno scenario con un
errore esplicito invece di generare mani sbagliate. <code><nowiki>descriptions[].context</nowiki></code> è sempre presente
(array, eventualmente vuoto).
Le definizioni normative (cosa è una fermata, i punti totali, le perdenti...) e
l'architettura del motore sono in '''<code><nowiki>DEAL_ENGINE_SPEC.md</nowiki></code>'''.

=== Macro di scrittura (<code><nowiki>@NOME=v1,v2</nowiki></code>) — risolte dal parser, il motore non le vede ===

<syntaxhighlight lang="text">
@M=H,S  1${M}: opener ${M}:5+ hcp:12-21; responder ${M}:3+
</syntaxhighlight>
Genera due scenari (<code><nowiki>1H</nowiki></code>, <code><nowiki>1S</nowiki></code>) sostituendo <code><nowiki>${M}</nowiki></code> ovunque, etichetta compresa.
Più prefissi fanno il prodotto cartesiano (max 64 scenari): <code><nowiki>@M=H,S @N=15-17,12-14</nowiki></code>.
I valori possono essere intervalli (<code><nowiki>hcp:${N}</nowiki></code>): servono anche come parametri del
sistema (SA 15-17 contro 14-16).

=== Semi variabili <code><nowiki>$a $b $c $d</nowiki></code> ===

Un seme "da scegliere" condiviso da più posizioni dello stesso scenario. Ogni
variabile è un seme diverso dalle altre. Dominio dichiarato a livello di scenario
(prima delle posizioni):

<syntaxhighlight lang="text">
Landy: $a=M $b=any  opener hcp:12-21 ; opp1 $a:5+ $b:4+ ; responder $a:0-2
</syntaxhighlight>
<code><nowiki>$a=M</nowiki></code> nobili, <code><nowiki>$a=m</nowiki></code> minori, <code><nowiki>$a=any</nowiki></code> (default) qualunque, <code><nowiki>$a=SH</nowiki></code> insieme esplicito.
Una variabile non dichiarata vale <code><nowiki>any</nowiki></code> (tutti i semi). Si usano al posto di <code><nowiki>S H D C</nowiki></code> in: <code><nowiki>$a:5+</nowiki></code> (lunghezza), <code><nowiki>$ahcp:</nowiki></code>, <code><nowiki>$a=KQ</nowiki></code>, <code><nowiki>$a~...</nowiki></code>,
<code><nowiki>stop:$a</nowiki></code>, <code><nowiki>has:$aQ</nowiki></code>, <code><nowiki>kc:$a3</nowiki></code>, confronti (<code><nowiki>$a>$b</nowiki></code>), <code><nowiki>longest:$a</nowiki></code>.
Differisce da <code><nowiki>x:</nowiki></code> (che vale per una sola posizione).
JSON: lo stesso dizionario <code><nowiki>suits</nowiki></code>, <code><nowiki>suit_hcp</nowiki></code>, ... ma con chiave <code><nowiki>"$a"</nowiki></code>;
a livello di scenario <code><nowiki>"vars": {"$a": ["S","H"]}</nowiki></code>.

=== Controlli, carte chiave, carte precise ===

{| class="wikitable"
! Token
! Significato
|-
| <code><nowiki>aces:2</nowiki></code> <code><nowiki>kings:1-2</nowiki></code> <code><nowiki>queens:0</nowiki></code>
| numero di assi / re / dame nella mano
|-
| <code><nowiki>controls:6+</nowiki></code>
| controlli (A=2, K=1)
|-
| <code><nowiki>kc:H3</nowiki></code> <code><nowiki>kc:H2-3</nowiki></code> <code><nowiki>kc:$a3</nowiki></code>
| carte chiave con atout H: i 4 assi + il Re di H (0-5)
|-
| <code><nowiki>has:HQ</nowiki></code> <code><nowiki>has:S10</nowiki></code>
| possiede quella carta precisa
|-
| <code><nowiki>lacks:HQ</nowiki></code>
| NON possiede quella carta
|-
| <code><nowiki>stop:S</nowiki></code> <code><nowiki>nostop:S</nowiki></code>
| ha / non ha una fermata nel seme (definizione in SPEC)
|}

JSON: <code><nowiki>aces</nowiki></code>, <code><nowiki>kings</nowiki></code>, <code><nowiki>queens</nowiki></code>, <code><nowiki>controls</nowiki></code> (Range); <code><nowiki>keycards: {"H": Range}</nowiki></code>;
<code><nowiki>cards_held: ["HQ"]</nowiki></code>, <code><nowiki>cards_not_held: ["SK"]</nowiki></code>; <code><nowiki>stoppers: {"S": 1, "H": 0}</nowiki></code>
(1 = deve averla, 0 = non deve averla).

=== Punti e perdenti ===

<code><nowiki>tp:</nowiki></code> punti totali (PO + 1 per ogni carta oltre la quarta in ogni seme),
<code><nowiki>dp:</nowiki></code> punti distribuzione (PO + 3 chicane + 2 singolo + 1 doubleton),
<code><nowiki>ltc:</nowiki></code> perdenti (Losing Trick Count). A livello di scenario: <code><nowiki>pairhcp:25+</nowiki></code>
(PO della coppia dichiarante), <code><nowiki>defhcp:0-14</nowiki></code> (coppia avversaria), <code><nowiki>pairtp:26+</nowiki></code>.
JSON: <code><nowiki>tp</nowiki></code>, <code><nowiki>dp</nowiki></code>, <code><nowiki>ltc</nowiki></code> (Range) nella posizione; <code><nowiki>pair_hcp: {"declarer": R, "defense": R}</nowiki></code>,
<code><nowiki>pair_tp: {"declarer": R}</nowiki></code> nello scenario.

=== Confronti tra semi e forme precise ===

<syntaxhighlight lang="text">
H>S   H>=S   H<S   H<=S   H==S   $a>$b      — confronto di lunghezze nella stessa mano
longest:H                                      — H è tra i semi più lunghi (pari merito ammesso)
shape:5-4-x-x   shape:5422   shape:54xx        — lunghezze ordinate in modo decrescente, x = qualsiasi
shape:semi_balanced                            — 5422 e 6322 (si aggiunge alle classi esistenti)
</syntaxhighlight>
JSON: <code><nowiki>compare: [{"left":"H","op":">=","right":"S"}]</nowiki></code>, <code><nowiki>longest: ["H"]</nowiki></code>,
<code><nowiki>shape_pattern: "54xx"</nowiki></code>.

=== Alternative e negazioni nella stessa mano: <code><nowiki>any(...)</nowiki></code> e <code><nowiki>not(...)</nowiki></code> ===

<syntaxhighlight lang="text">
opener any(S:4+ hcp:12+, H:4+)   not(D:6+)
</syntaxhighlight>
<code><nowiki>any(A, B)</nowiki></code>: la mano soddisfa '''almeno una''' delle alternative (separate da virgola;
ogni alternativa è una congiunzione di token). <code><nowiki>not(A, B)</nowiki></code>: la mano non soddisfa
'''nessuna''' delle alternative. Si possono scrivere più gruppi (si combinano in AND);
niente annidamenti.
JSON: <code><nowiki>any: [[altA, altB], ...]</nowiki></code> (lista di gruppi; ogni alternativa è un oggetto
con gli stessi campi di una posizione), <code><nowiki>not: [altA, altB]</nowiki></code>.

=== Contesto dello scenario ===

Token prima delle posizioni: <code><nowiki>weight:3</nowiki></code> (frequenza relativa, 1-100, default 1),
<code><nowiki>dealer:opener</nowiki></code>, <code><nowiki>vul:none&#124;us&#124;them&#124;both</nowiki></code> (<code><nowiki>us</nowiki></code> = apertore+rispondente),
<code><nowiki>auction:1SA,P,2C,P</nowiki></code> (licite, notazione BridgeCards; SA = NT), <code><nowiki>contract:4H</nowiki></code>,
<code><nowiki>declarer:responder</nowiki></code>, <code><nowiki>lead:SK</nowiki></code>.
JSON: <code><nowiki>weight</nowiki></code> (int) e <code><nowiki>context: {"dealer":..,"vul":..,"auction":[..],"contract":"4H","declarer":..,"lead":"SK"}</nowiki></code>.
Il motore deve usare <code><nowiki>dealer</nowiki></code>/<code><nowiki>vul</nowiki></code> quando li espone (per la numerazione del tavolo) e,
se c'è <code><nowiki>lead</nowiki></code>, la carta deve stare nella mano dell'attaccante (a sinistra del
dichiarante) e rispettare i vincoli di quella mano.

=== Tag <code><nowiki>requires</nowiki></code> ===

<code><nowiki>suit_cards</nowiki></code>, <code><nowiki>suit_patterns</nowiki></code>, <code><nowiki>vars</nowiki></code>, <code><nowiki>stoppers</nowiki></code>, <code><nowiki>card_presence</nowiki></code> (has/lacks),
<code><nowiki>controls</nowiki></code> (aces/kings/queens/controls/kc), <code><nowiki>points</nowiki></code> (tp/dp/ltc), <code><nowiki>pair_points</nowiki></code>,
<code><nowiki>compare</nowiki></code> (confronti, longest), <code><nowiki>shape_pattern</nowiki></code>, <code><nowiki>any_not</nowiki></code>, <code><nowiki>context</nowiki></code>, <code><nowiki>weight</nowiki></code>.
Le macro <code><nowiki>@</nowiki></code> e <code><nowiki>quiet</nowiki></code> non compaiono: sono già espanse.

=== Avvisi di parsing (<code><nowiki>warnings</nowiki></code>) ===

<code><nowiki>get</nowiki></code> e <code><nowiki>validate</nowiki></code> restituiscono <code><nowiki>warnings</nowiki></code> quando un frammento del DSL non è stato
capito e quindi '''scartato''': nome di posizione sbagliato, token sconosciuto o con valore
non valido (<code><nowiki>aces:5</nowiki></code>, <code><nowiki>S=Kx</nowiki></code>, <code><nowiki>shape:4-5-x-x</nowiki></code>), token di scenario dopo le posizioni, posizione
definita due volte, <code><nowiki>quiet</nowiki></code> su opener/responder, gruppo <code><nowiki>any()</nowiki></code>/<code><nowiki>not()</nowiki></code> con alternative non
valide (in tal caso '''l'intero gruppo è ignorato''', mai applicato a metà). <code><nowiki>validate.valid</nowiki></code> è 1
solo se non ci sono né <code><nowiki>errors</nowiki></code> né <code><nowiki>warnings</nowiki></code>. Un motore non deve generare se ci sono
<code><nowiki>warnings</nowiki></code> o <code><nowiki>errors</nowiki></code>.

Limiti (oltre i quali il parser avvisa e tronca): 60.000 caratteri di input, 200 scenari, 6
prefissi <code><nowiki>@</nowiki></code>, 64 valori per macro, 64 scenari per espansione, 8 gruppi <code><nowiki>any/not</nowiki></code> e 16 alternative
per posizione. Le etichette non possono contenere <code><nowiki>:</nowiki></code>.

----

== Struttura JSON di uno scenario ==

<syntaxhighlight lang="typescript">
interface Scenario {
  label: string;           // Etichetta (es. "1H-4C"), vuota se non specificata
  positions: {
    [posName: string]: Position;  // "opener", "responder", "opp1", "opp2"
  };
  fit: FitConstraint[];    // Vincoli di fit (array, può essere vuoto)
}

interface Position {
  suit_patterns?: {         // Pattern regex-like normalizzati: {"S":[{"cards":"AKQ","low_min":1,"low_max":1}]}
    [suit: string]: { cards: string; low_min: number; low_max: number | null }[];
  };
  suit_cards?: { [suit: string]: string };  // Onori esatti, es. {"S":"KJT"}; "" = nessuna carta alta
  suits?: {                // Vincoli lunghezza seme (solo semi esplicitati)
    [suit: string]: Range; // "S", "H", "D", "C"
  };
  hcp?: Range;             // HCP totali
  suit_hcp?: {             // HCP per seme specifico
    [suit: string]: Range;
  };
  x?: Range;               // Lunghezza seme wildcard
  x_hcp?: Range;           // HCP seme wildcard
  shape?: string;          // Shape class: "balanced", "one_suiter", etc.
}

interface Range {
  min: number;
  max: number | null;      // null = nessun limite superiore
}

interface FitConstraint {
  suit: string | null;      // "S","H","D","C" o null
  suit_class: string | null; // "major", "minor" o null
  min: number;              // Numero minimo di carte (es. 8)
  pair: string;             // "declarer" o "defense"
}
</syntaxhighlight>

----

== Logica per il generatore ==

=== Algoritmo base ===

Per ogni scenario:

# '''Scegli lo scenario''': random tra quelli disponibili, oppure lascia scegliere all'utente
# '''Risolvi wildcard''':
#* Se una posizione ha <code><nowiki>x:</nowiki></code>, scegli un seme casuale tra quelli non esplicitamente vincolati
#* <code><nowiki>xhcp:</nowiki></code> si applica allo stesso seme scelto per <code><nowiki>x:</nowiki></code>
# '''Risolvi fit''':
#* Se <code><nowiki>fit.suit</nowiki></code> è specificato, entrambi i compagni devono avere un totale >= <code><nowiki>fit.min</nowiki></code> in quel seme
#* Se <code><nowiki>fit.suit_class</nowiki></code> è "major", scegli tra H e S; se "minor", tra D e C
#* Se entrambi sono null, scegli un seme qualsiasi
#* <code><nowiki>fit.pair</nowiki></code> indica quale coppia: "declarer" (opener+responder) o "defense" (opp1+opp2)
# '''Genera le mani''':
#* Per ogni posizione, genera una mano che rispetti tutti i vincoli
#* I semi senza vincoli vengono riempiti casualmente
#* Il totale delle carte per mano deve essere esattamente 13
#* Il totale delle carte per seme (tutte e 4 le mani) deve essere esattamente 13
# '''Posizioni non menzionate''': se uno scenario non menziona <code><nowiki>opp1</nowiki></code>/<code><nowiki>opp2</nowiki></code>, distribuisci le carte rimanenti casualmente tra gli avversari

=== Priorità dei vincoli ===

# Vincoli di fit (cross-posizione) — determinano la distribuzione di base
# Vincoli di seme specifico (S:, H:, D:, C:) — limitano i singoli semi
# Vincoli wildcard (x:) — dopo aver fissato i semi specifici
# Vincoli HCP (hcp:, Shcp:, xhcp:) — filtro finale
# Shape class (shape:) — validazione della forma complessiva

=== Gestione di <code><nowiki>max: null</nowiki></code> ===

Quando <code><nowiki>max</nowiki></code> è <code><nowiki>null</nowiki></code>, non c'è limite superiore esplicito. I limiti fisici
del bridge si applicano comunque:
* Massimo 13 carte per seme (tutte e 4 le mani)
* Massimo 13 carte per mano
* Massimo 10 HCP per seme (A+K+Q+J = 4+3+2+1)
* Massimo 37 HCP per mano (raro ma teoricamente possibile con tutti gli onori)

----

== Esempi completi ==

=== Splinter (tutti gli scenari specifici) ===

DSL nel template wiki:
<syntaxhighlight lang="text">
1H-4C: opener H:5+ hcp:12-21; responder H:4+ C:0-1 Chcp:0 hcp:10-15 //
1H-4D: opener H:5+ hcp:12-21; responder H:4+ D:0-1 Dhcp:0 hcp:10-15 //
1H-4S: opener H:5+ hcp:12-21; responder H:4+ S:0-1 Shcp:0 hcp:10-15 //
1S-4C: opener S:5+ hcp:12-21; responder S:4+ C:0-1 Chcp:0 hcp:10-15 //
1S-4D: opener S:5+ hcp:12-21; responder S:4+ D:0-1 Dhcp:0 hcp:10-15 //
1S-4H: opener S:5+ hcp:12-21; responder S:4+ H:0-1 Hhcp:0 hcp:10-15
</syntaxhighlight>

=== Splinter (compatto con fit e wildcard) ===

<syntaxhighlight lang="text">
dopo 1H: fit:H8+ opener H:5+ hcp:12-21; responder x:0-1 xhcp:0 hcp:10-15 //
dopo 1S: fit:S8+ opener S:5+ hcp:12-21; responder x:0-1 xhcp:0 hcp:10-15
</syntaxhighlight>

=== Stayman ===

<syntaxhighlight lang="text">
fit a cuori: fit:H8+ opener hcp:15-17 S:2-4 H:2-4 D:2-5 C:2-5; responder H:4+ hcp:8+ //
fit a picche: fit:S8+ opener hcp:15-17 S:2-4 H:2-4 D:2-5 C:2-5; responder S:4+ hcp:8+
</syntaxhighlight>

=== Contro informativo ===

<syntaxhighlight lang="text">
base: opener hcp:12-21 x:5+; opp1 hcp:12+ S:3+ H:3+ D:3+ C:3+; responder hcp:0-8 //
con intervento: opener hcp:12-21 x:5+; opp1 hcp:12+ S:3+ H:3+ D:3+ C:3+; opp2 hcp:8+ x:5+
</syntaxhighlight>

=== Preempt 3-a-livello ===

<syntaxhighlight lang="text">
opener H:7+ x:0-1 hcp:5-10
</syntaxhighlight>

=== Overcall con fit avversari ===

<syntaxhighlight lang="text">
overcall semplice: opener hcp:12-21 x:5+; opp1 hcp:10+ x:5+; opp2 fit:8+ //
con barrage: opener hcp:12-21 x:5+; opp1 hcp:6-10 x:6+; opp2 fit:9+
</syntaxhighlight>

----

== Note implementative ==

* L'API è read-only, non richiede token CSRF
* L'accesso anonimo è abilitato di default (<code><nowiki>BridgeShapeAllowAnonymous: true</nowiki></code>) perché i dati sono pubblici e i tool esterni ne hanno bisogno
* Il campo <code><nowiki>raw</nowiki></code> nella risposta <code><nowiki>get</nowiki></code> contiene la stringa DSL originale, utile per debug
* L'azione <code><nowiki>validate</nowiki></code> permette di testare stringhe DSL senza creare pagine wiki
* I calcoli HCP usano la scala standard: A=4, K=3, Q=2, J=1


[[Categoria:Documentazione tecnica]]