# Formatting Library

<!--*
freshness: { owner: 'hzeller' reviewed: '2020-10-04' }
*-->

This library contains language-agnostic formatting capabilities, including
representations useful for formatting algorithms.

## Key Data Structures

[PreFormatToken](format_token.h) is a markup layer over a token stream that
annotates each token with [InterTokenInfo](format_token.h) that influences
formatting (e.g. minimum spacing between tokens).

[FormattedToken](format_token.h) is similar, but represents the result of
formatting, **after** analysis and transformations have completed and decisions
have been bound.

[FormatTokenRange](format_token.h) is an iterator range over an array of
PreFormatTokens.

[UnwrappedLine](unwrapped_line.h) represents an indentable unit of formatting
and contains a FormatTokenRange and indentation information.

[TokenPartitionTree](token_partition_tree.h) is a language-agnostic hierarchical
representation of subranges of tokens and text. The data nodes of this tree are
UnwrappedLines. From any language-specific text and structural representation,
producing a language-agnostic TokenPartitionTree will gain access to a wide
variety of formatting functions.

## Concepts

Don't mutate text/syntax tree data structures, present a form that looks like a
mutation and render it. What the formatting functions do is produce annotated
scaffoling over the original representation that, when printed to stream,
produces the same effect as having mutated the original form. By treating the
orignal representation as read-only, this strategy allows one to easily explore
multiple formatting subsolutions.