# Formatting

HTML: [altophp.com/rst/editing/formatting](https://altophp.com/rst/editing/formatting/)

`Formatter` normalizes selected layout while preserving document semantics. It
returns changed bytes and patches without writing a file.

```php
use Alto\Rst\Format\FormatOptions;
use Alto\Rst\Format\Formatter;
use Alto\Rst\Profile\Profile;

$result = new Formatter()->format(
    $input,
    new FormatOptions(
        normalizeSectionAdornments: true,
        bulletMarker: '-',
        alignSimpleTables: true,
        lineWidth: 80,
    ),
    Profile::symfony(),
);
```

The formatter can normalize section adornments and bullet markers, align
simple tables, and wrap eligible plain prose. It skips ambiguous Unicode title
widths, structural list boundaries, complex tables, directives, literals,
markup-heavy prose, and any candidate that changes the reparsed tree.

Formatting is idempotent:

```php
$first = new Formatter()->format($input);
$second = new Formatter()->format($first->bytes);

assert([] === $second->patches);
```

Extension passes use the same parse guard. See [Patches](https://altophp.com/rst/editing/patches.md) to preview
the accepted changes.

`Formatter::format(string $bytes, ?FormatOptions, ?Profile)` returns a
`FormatResult`. Formatting candidates pass a semantic reparse guard before
their patches are accepted.

---

Previous: [Editing](https://altophp.com/rst/editing.md)
Next: [Patches](https://altophp.com/rst/editing/patches.md)

---

ALTO\RST: [altophp.com/rst](https://altophp.com/rst/)
ALTO(PHP): [altophp.com](https://altophp.com/)