| # 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. |