docs/PILES-notation.md

# PILES: Puzzle Input Line Entry System

A SMILES-inspired notation for specifying puzzle piece fusion groups in jigsawR.

## Overview

PILES (Puzzle Input Line Entry System) is a domain-specific notation for describing which puzzle pieces should be fused together. It is inspired by chemistry's [SMILES notation](https://en.wikipedia.org/wiki/Simplified_Molecular_Input_Line_Entry_System) for representing molecular structures.

Just as SMILES uses simple ASCII strings to represent complex molecular bonds, PILES uses simple strings to represent puzzle piece connections.

## Quick Reference

| Syntax | Meaning | Example |
|--------|---------|---------|
| `n` | Piece ID | `1`, `15`, `42` |
| `-` | Fusion bond | `1-2` (fuse pieces 1 and 2) |
| `,` | Separate groups | `1-2,3-4` (two independent groups) |
| `.` | Separate groups (alt) | `1-2.3-4` (same as comma) |
| `n:m` | Range | `1:6` (pieces 1 through 6) |
| `()` | Branching | `1-2(-3)-4` (2 bonds to 1, 3, and 4) |
| `@n` | Ring closure | `1-2-3-4@1` (4 connects back to 1) |
| `[D]` | Direction hint | `1-2[E]-3` (optional validation) |
| `ALL-n` | Exclusion | `ALL-5` (all except piece 5) |
| `!n` | Exclusion (alt) | `!5` (same as ALL-5) |

## Basic Syntax

### Piece IDs
Numbers represent piece IDs (1-indexed):
```

1       # Piece 1 alone

15      # Piece 15 alone

```

### Fusion Bonds (-)
Hyphens indicate pieces that should be fused together:
```

1-2         # Fuse pieces 1 and 2

1-2-3       # Linear chain: 1 + 2 + 3 fused together

1-2-3-4-5   # Longer chain

```

### Multiple Groups (,)
Commas separate independent fusion groups:
```

1-2,3-4         # Two groups: (1,2) and (3,4)

1-2-3,4-5,6-7   # Three groups

```

### Range Notation (:)
Colons specify consecutive piece ranges:
```

1:6         # Pieces 1, 2, 3, 4, 5, 6 fused together

10:15       # Pieces 10 through 15

```

## Advanced Syntax

### Branching
Parentheses define branches from a junction piece:
```

1-2(-3)-4   # Piece 2 connects to 1, 3, AND 4

            # Forms a T-junction



1-2(-3)(-4)-5   # Piece 2 connects to 1, 3, 4, AND 5

                # Multiple branches from piece 2

```

### Ring Closures
The `@` symbol with a piece number indicates a ring closure (connecting back to form a cycle):
```

1-2-3-4@1       # Piece 4 connects back to piece 1

                # Forms a closed ring: 1-2-3-4-1



1-2-3-4-5-6@1   # Hexagonal ring closure

```

### Direction Specifiers (Optional)
Square brackets can specify connection directions for validation:
```

# Rectangular puzzles

1-2[E]-3        # 2's East edge connects to 3

1[S]-5          # 1's South edge connects to 5

# Directions: [N]orth, [E]ast, [S]outh, [W]est



# Hexagonal puzzles

1-2[0]-3        # Side 0 connection

# Sides: [0] through [5]



# Concentric puzzles

1-2[O]-3        # Outer edge connection

# Directions: [I]nner, [R]ight, [O]uter, [L]eft

```

## Special Keywords

PILES supports special keywords that expand to groups of pieces based on puzzle structure.

> **Note:** All keywords are **case-insensitive**. `all`, `ALL`, and `All` are equivalent.

### Universal Keywords
| Keyword | Meaning |
|---------|---------|
| `all` | All pieces in the puzzle (creates a single meta piece) |
| `boundary` | All boundary/edge pieces |
| `border` | Same as `boundary` |
| `edge` | Same as `boundary` |
| `inner` | All non-boundary pieces |
| `center` | Center piece (hexagonal/concentric) |

### The `all` Keyword - Single Meta Piece

The `all` keyword fuses every piece in the puzzle into a single "meta piece". This is useful for:
- Creating a puzzle where all internal edges are styled differently (dashed/hidden)
- Generating a single connected piece with complex internal structure
- Testing fusion rendering across all edges

```r

# Create a puzzle where all pieces are fused into one

result <- generate_puzzle(

  type = "rectangular",

  grid = c(3, 3),

  size = c(300, 300),

  fusion_groups = "all",       # Fuse ALL pieces

  fusion_style = "dashed",     # Show internal edges as dashed

  save_files = FALSE

)



# All 9 pieces will have the same fusion_group

# All internal edges will be rendered with dashed style

# Only the outer boundary remains solid

```

### Hexagonal & Concentric Keywords
| Keyword | Meaning |
|---------|---------|
| `ring0` | Center piece (same as `center`) |
| `ring1` | All pieces in ring 1 |
| `ring2` | All pieces in ring 2 |
| `ringN` | All pieces in ring N |

### Rectangular Keywords
| Keyword | Meaning |
|---------|---------|
| `R1` or `row1` | All pieces in row 1 (top) |
| `R2` or `row2` | All pieces in row 2 |
| `C1` or `col1` | All pieces in column 1 (left) |
| `C2` or `col2` | All pieces in column 2 |

### Keyword Examples
```r

# Fuse all boundary pieces together

parse_piles("boundary", puzzle_result)



# Fuse center with first ring

parse_piles("center-ring1", puzzle_result)



# Fuse entire first row

parse_piles("R1", puzzle_result)



# Fuse columns 1 and 2

parse_piles("C1,C2", puzzle_result)

```

## Exclusion Syntax

PILES supports exclusion patterns to fuse "all pieces except..." This is useful when you want to fuse most pieces but leave a few separate.

### Exclusion Patterns

| Syntax | Meaning | Example |
|--------|---------|---------|
| `ALL-n` | All pieces except n | `ALL-5` (all except piece 5) |
| `ALL-n-m` | All pieces except n and m | `ALL-1-9` (all except 1 and 9) |
| `!n` | All pieces except n | `!5` (same as `ALL-5`) |
| `!n!m` | All pieces except n and m | `!1!7` (all except 1 and 7) |

### Exclusion Examples

```r

# Create a 3x3 puzzle (9 pieces)

puzzle <- generate_puzzle(

  type = "rectangular",

  grid = c(3, 3),

  seed = 42

)



# Fuse all except the center piece (piece 5)

parse_piles("ALL-5", puzzle)

# Returns: list(c(1L, 2L, 3L, 4L, 6L, 7L, 8L, 9L))



# Fuse all except corners (pieces 1, 3, 7, 9)

parse_piles("!1!3!7!9", puzzle)

# Returns: list(c(2L, 4L, 5L, 6L, 8L))



# Direct use with generate_puzzle

result <- generate_puzzle(

  type = "rectangular",

  grid = c(3, 3),

  fusion_groups = "ALL-5",  # Fuse all except center

  save_files = FALSE

)

```

### Combining Exclusion with Other Syntax

Exclusion patterns create single fusion groups. To create multiple groups with exclusions, use comma separation:

```r

# NOT YET SUPPORTED: combining exclusion with regular groups

# "ALL-5,1-2" would need future implementation

```

**Note**: Exclusion syntax requires puzzle context to know the total number of pieces. It cannot be used with `parse_piles()` without providing a `puzzle_result`.

## R Functions

### Core Functions

#### `parse_piles()`

Parse PILES notation into fusion groups:

```r

parse_piles("1-2-3,4-5")
# Returns: list(c(1L, 2L, 3L), c(4L, 5L))

parse_piles("1:6")

# Returns: list(c(1L, 2L, 3L, 4L, 5L, 6L))



# With puzzle context for keywords

puzzle <- generate_puzzle(type = "rectangular", grid = c(3, 2))
parse_piles("R1", puzzle)

# Returns: list(c(1L, 2L, 3L))  # First row

```



#### `to_piles()`
Convert fusion groups back to PILES notation:
```r

to_piles(list(c(1, 2), c(3, 4, 5)))

# Returns: "1-2,3-4-5"



to_piles(list(1:6))

# Returns: "1:6"  # Compact range notation



to_piles(list(c(3, 1, 2)), compact = FALSE)

# Returns: "1-2-3"  # Sorted, hyphen-separated

```

#### `parse_fusion()`

Universal parser that auto-detects format:

```r

# PILES format

parse_fusion("1-2-3,4-5")

# Legacy format (also supported)
parse_fusion("(1,2),(3,4)")



# List format (also supported)

parse_fusion(list(c(1, 2), c(3, 4)))
```



#### `validate_piles_syntax()`

Validate PILES string syntax:

```r

validate_piles_syntax("1-2-3,4-5")

# Returns: list(valid = TRUE, message = "Valid PILES syntax", warnings = character())



validate_piles_syntax("1-2((3")

# Returns: list(valid = FALSE, message = "Unbalanced parentheses: 2 open, 1 close")

```

## Examples

### Rectangular Puzzle Fusions
```r

puzzle <- generate_puzzle(type = "rectangular", grid = c(4, 3), seed = 42)



# Fuse horizontal pairs

parse_piles("1-2,3-4,5-6,7-8,9-10,11-12", puzzle)



# Fuse entire rows

parse_piles("R1,R2,R3", puzzle)



# Create 2x2 meta-pieces

parse_piles("1-2-5-6,3-4-7-8,9-10,11-12", puzzle)

```

### Hexagonal Puzzle Fusions
```r

puzzle <- generate_puzzle(type = "hexagonal", grid = c(3), seed = 42)



# Fuse center with first ring

parse_piles("center-ring1", puzzle)



# Fuse adjacent pairs in outer ring

parse_piles("8-9,10-11,12-13,14-15,16-17,18-19", puzzle)

```

### Concentric Puzzle Fusions
```r

puzzle <- generate_puzzle(type = "concentric", grid = c(3), seed = 42)



# Fuse entire rings

parse_piles("ring0,ring1,ring2", puzzle)



# Fuse center to all neighbors

parse_piles("1-2-3-4-5-6-7", puzzle)

```

## Comparison with SMILES

| Feature | SMILES (Chemistry) | PILES (Puzzles) |
|---------|-------------------|-----------------|
| Atoms/Pieces | C, N, O... | 1, 2, 3... |
| Bonds | `-`, `=`, `#` | `-` only |
| Branching | `()` | `()` |
| Ring closure | Digit pairs | `@n` |
| Groups | `.` | `,` or `.` |

### Key Differences
1. **PILES uses explicit ring closure syntax** (`@n`) instead of SMILES' implicit digit matching
2. **PILES has puzzle-specific keywords** (`ring1`, `R1`, `boundary`, etc.)
3. **PILES only has single bonds** (fusion is binary: connected or not)
4. **PILES uses numeric IDs** instead of element symbols

## Technical Details

### Parsing Order
1. Split by group separators (`,` or `.`)
2. Check for special keywords
3. Handle range notation (`:`)
4. Process ring closures (`@n`)
5. Remove direction specifiers (`[...]`)
6. Parse structure with branching
7. Validate adjacency (optional)

### Auto-Detection
The `parse_fusion()` function auto-detects format:
- **Legacy format**: Starts with `(` or contains `(n,n)` pattern
- **PILES format**: Contains `-` or keywords

### Performance
- Tokenization is O(n) where n is string length
- Keyword expansion may require puzzle structure lookup
- Pre-allocated vectors used for O(n) performance

## References

- [SMILES Notation (Wikipedia)](https://en.wikipedia.org/wiki/Simplified_Molecular_Input_Line_Entry_System)
- [OpenSMILES Specification](http://opensmiles.org/opensmiles.html)
- [jigsawR Package Documentation](../README.md)