# Auto-Generated IDs

Wasot automatically generates IDs for blocks that don't have explicit IDs. This document explains how auto-ID generation works and how to control it.

## How It Works

By default, when parsing a Wasot file, the parser:

1. **Pre-scans the file** to find the maximum existing numeric ID (using base36 encoding)
2. **Assigns auto-generated IDs** to blocks without explicit IDs, starting from `max_id + 1`

This ensures that auto-generated IDs never conflict with existing explicit IDs in the document.

### Example

Given this input:

```wasot
.block
Some text

.another :abc
More text
```

The parser will output:

```wasot
.block :1
Some text

.another :abc
More text
```

The first block gets auto-ID `1`, while the second block keeps its explicit ID `abc`.

## Disabling Auto-ID Generation

You can disable auto-ID generation using the `--no-auto-ids` CLI flag:

```bash
wasot --no-auto-ids input.wasot -o output.jsonl
wasot --no-auto-ids --to xml < input.wasot
```

When disabled:
- The pre-scan pass is skipped (slightly faster for large files)
- Blocks without explicit IDs will have empty/null IDs in the output

### Use Cases for Disabling Auto-IDs

- **Preserving original structure**: When you want output to exactly match input
- **Performance**: Skip the pre-scan pass for very large files where IDs aren't needed
- **Testing**: Verify behavior with missing IDs
- **Custom ID generation**: When you have a downstream process that generates IDs differently

## API Usage

The `WasotFileEmitter` provides a builder method to control auto-ID generation:

```rust
use wasot_compiler::WasotFileEmitter;

// Default: auto-IDs enabled
let emitter = WasotFileEmitter::from_file("input.wasot");

// Disable auto-ID generation
let emitter = WasotFileEmitter::from_file("input.wasot")
    .with_auto_generate_ids(false);
```

## ID Format

Auto-generated IDs use base36 encoding (0-9, a-z) for compact representation:

| Decimal | Base36 |
|---------|--------|
| 1       | 1      |
| 10      | a      |
| 35      | z      |
| 36      | 10     |
| 100     | 2s     |

This keeps IDs short even for large documents with many blocks.

## Related

- [CLI Reference](cli.md) - Full CLI documentation
- [Document IDs](document_ids.md) - Document-level ID management
