pjt222/validate-piles-notation

PILES-Notation validieren

PILES-Notationszeichenketten fuer Puzzle-Teilefusionsgruppen parsen und validieren.

Wann verwenden

• Benutzerdefinierte PILES-Zeichenketten vor der Uebergabe an generate_puzzle() validieren
• Fusionsgruppen-Probleme debuggen (falsche Teile zusammengefuegt, unerwartete Ergebnisse)
• PILES-Notation fuer Benutzer in Klartext erklaeren
• Round-Trip-Treue testen: Parsen -> Gruppen -> Serialisieren -> Parsen

Eingaben

• Erforderlich: PILES-Notationszeichenkette (z.B. "1-2-3,4-5")
• Optional: Puzzle-Ergebnisobjekt (fuer Adjazenzvalidierung und Schluesselwortaufloesung)
• Optional: Puzzletyp (fuer Schluesselwort-Unterstuetzung wie "center", "ring1", "R1")

Vorgehensweise

Schritt 1: Syntaxvalidierung

library(jigsawR)
result <- validate_piles_syntax("1-2-3,4-5")
# Gibt TRUE zurueck wenn gueltig, Fehlermeldung wenn ungueltig

Auf haeufige Syntaxfehler pruefen:

• Ungepaarte Klammern: "1-2(-3)-4" mit nicht zusammenpassenden ()
• Ungueltige Zeichen: nur Ziffern, -, ,, :, (, ) und Schluesselwoerter erlaubt
• Leere Gruppen: "1-2,,3-4" (doppeltes Komma)

Erwartet: TRUE fuer gueltige Syntax, beschreibender Fehler fuer ungueltige.

Bei Fehler: Die genaue PILES-Zeichenkette und die Validierungsfehlermeldung ausgeben.

Schritt 2: In Gruppen parsen

groups <- parse_piles("1-2-3,4-5")
# Gibt zurueck: list(c(1, 2, 3), c(4, 5))

Fuer Zeichenketten mit Bereichen:

groups <- parse_piles("1:6,7-8")
# Gibt zurueck: list(c(1, 2, 3, 4, 5, 6), c(7, 8))

Erwartet: Liste von Integer-Vektoren, einer pro Fusionsgruppe, mit korrekten Teil-IDs und Gruppengrenzen.

Bei Fehler: Zuerst pruefen ob die PILES-Zeichenkette die Syntaxvalidierung in Schritt 1 bestanden hat. Wenn das Parsen unerwartete Gruppen zurueckgibt, ueberpruefen ob - Teile innerhalb einer Gruppe trennt und , Gruppen trennt, und dass die Bereichsnotation (:) zu inklusiven Endpunkten expandiert.

Schritt 3: In Klartext erklaeren

Jede Gruppe fuer den Benutzer beschreiben:

• "1-2-3,4-5" -> "Gruppe 1: Teile 1, 2 und 3 fusionieren. Gruppe 2: Teile 4 und 5 fusionieren."
• "1:6" -> "Gruppe 1: Teile 1 bis 6 fusionieren (6 Teile)."
• "center,ring1" -> "Gruppe 1: Mittelteil. Gruppe 2: alle Teile in Ring 1."

Erwartet: Jede Fusionsgruppe wird in Klartext beschrieben mit Teilezahlen und Bezeichnern, sodass die Notation fuer nicht-technische Benutzer verstaendlich wird.

Bei Fehler: Wenn Schluesselwoerter nicht erklaert werden koennen (z.B. hat "ring1" keine klare Bedeutung), braucht die Notation moeglicherweise ein Puzzle-Ergebnisobjekt fuer Kontext. Den Benutzer empfehlen den Puzzletyp anzugeben oder stattdessen numerische Teil-IDs zu verwenden.

Schritt 4: Gegen Puzzle-Ergebnis validieren (Optional)

Wenn ein Puzzle-Ergebnisobjekt verfuegbar ist, verifizieren:

# Zuerst das Puzzle generieren
puzzle <- generate_puzzle(type = "hexagonal", grid = c(3), size = c(200))

# Mit Puzzle-Kontext parsen (loest Schluesselwoerter auf)
groups <- parse_fusion("center,ring1", puzzle)

Pruefen:

• Alle Teil-IDs existieren im Puzzle
• Schluesselwoerter loesen zu gueltigen Teilemengen auf
• Fusionierte Teile sind tatsaechlich benachbart (Warnung wenn nicht)

Erwartet: Alle Teil-IDs gueltig. Benachbarte Teile fusionieren sauber.

Bei Fehler: Ungueltige Teil-IDs oder nicht benachbarte Paare auflisten.

Schritt 5: Round-Trip-Serialisierung

Parse/Serialize-Treue verifizieren:

original <- "1-2-3,4-5"
groups <- parse_piles(original)
roundtrip <- to_piles(groups)
# roundtrip sollte gleich original sein (oder kanonisch aequivalent)

groups2 <- parse_piles(roundtrip)
identical(groups, groups2)  # Muss TRUE sein

Erwartet: Der Round-Trip erzeugt identische Gruppenlisten, was bestaetigt dass parse_piles() und to_piles() zueinander invers sind.

Bei Fehler: Wenn der Round-Trip abweicht, pruefen ob der Serialisierer die Notation normalisiert (z.B. Teil-IDs sortiert oder Bereiche in explizite Listen konvertiert). Kanonische Unterschiede sind akzeptabel solange identical(groups, groups2) TRUE zurueckgibt.

PILES-Kurzreferenz

# Grundsyntax
"1-2"           # Teile 1 und 2 fusionieren
"1-2-3,4-5"     # Zwei Gruppen: (1,2,3) und (4,5)
"1:6"           # Bereich: Teile 1 bis 6

# Schluesselwoerter (benoetigen puzzle_result)
"center"        # Mittelteil (hex/concentric)
"ring1"         # Alle Teile in Ring 1
"R1"            # Reihe 1 (rectangular)
"boundary"      # Alle Randteile

# Funktionen
parse_piles("1-2-3,4-5")                    # PILES-Zeichenkette parsen
parse_fusion("1-2-3", puzzle)               # Format automatisch erkennen
to_piles(list(c(1,2), c(3,4)))              # In PILES konvertieren
validate_piles_syntax("1-2(-3)-4")          # Syntax validieren

Validierung

• [ ] validate_piles_syntax() gibt TRUE fuer gueltige Zeichenketten zurueck
• [ ] parse_piles() gibt korrekte Gruppenlisten zurueck
• [ ] Round-Trip-Serialisierung bewahrt die Gruppen
• [ ] Schluesselwoerter loesen korrekt mit Puzzle-Kontext auf
• [ ] Ungueltige Syntax erzeugt klare Fehlermeldungen

Haeufige Stolperfallen

• Schluesselwort ohne Puzzle-Kontext: Schluesselwoerter wie "center" benoetigen ein Puzzle-Ergebnisobjekt. Es an parse_fusion() uebergeben, nicht an parse_piles().
• 1-indizierte Teile: Teil-IDs beginnen bei 1, nicht bei 0.
• Benachbarte vs. nicht benachbarte Fusion: Nicht benachbarte Teile zu fusionieren funktioniert, kann aber unerwartete visuelle Ergebnisse erzeugen. Adjazenz validieren wenn moeglich.
• Bereichsnotation: "1:6" schliesst beide Endpunkte ein (1, 2, 3, 4, 5, 6).

Verwandte Skills

• generate-puzzle — Puzzles mit Fusionsgruppen generieren
• add-puzzle-type — neue Typen brauchen PILES/Fusions-Unterstuetzung
• run-puzzle-tests — PILES-Parsing mit der vollstaendigen Suite testen