@Immutable
public final class Formatter
extends java.lang.Object
This formatter uses the javac parser to generate an AST. Because the AST loses information about the non-tokens in the input (including newlines, comments, etc.), and even some tokens (e.g., optional commas or semicolons), this formatter lexes the input again and follows along in the resulting list of tokens. Its lexer splits all multi-character operators (like ">>") into multiple single-character operators. Each non-token is assigned to a token---non-tokens following a token on the same line go with that token; those following go with the next token--- and there is a final EOF token to hold final comments.
The formatter walks the AST to generate a Greg Nelson/Derek Oppen-style list of formatting Ops [1--2] that
then generates a structured Doc. Each AST node type has a visitor to emit a sequence of Ops for the
node.
Some data-structure operations are easier in the list of Ops, while others become easier in the
Doc. The Ops are walked to attach the comments. As the Ops are generated, missing input
tokens are inserted and incorrect output tokens are dropped, ensuring that the output matches the input even in the
face of formatter errors. Finally, the formatter walks the Doc to format it in the given width.
This formatter also produces data structures of which tokens and comments appear where on the input, and on the output, to help output a partial reformatting of a slightly edited input.
Instances of the formatter are immutable and thread-safe.
[1] Nelson, Greg, and John DeTreville. Personal communication.
[2] Oppen, Derek C. "Prettyprinting". ACM Transactions on Programming Languages and Systems, Volume 2 Issue 4, Oct. 1980, pp. 465–483.
| Modifier and Type | Method and Description |
|---|---|
static Formatter |
create()
A new Formatter instance with default options.
|
static Formatter |
createFormatter(com.palantir.javaformat.java.JavaFormatterOptions options) |
void |
formatSource(com.google.common.io.CharSource input,
com.google.common.io.CharSink output)
Format the given input (a Java compilation unit) into the output stream.
|
java.lang.String |
formatSource(java.lang.String input)
Format an input string (a Java compilation unit) into an output string.
|
java.lang.String |
formatSource(java.lang.String input,
java.util.Collection<com.google.common.collect.Range<java.lang.Integer>> characterRanges)
Format an input string (a Java compilation unit), for only the specified character ranges.
|
java.lang.String |
formatSourceAndFixImports(java.lang.String input)
Formats an input string (a Java compilation unit) and fixes imports.
|
com.google.common.collect.ImmutableList<com.palantir.javaformat.java.Replacement> |
getFormatReplacements(java.lang.String input,
java.util.Collection<com.google.common.collect.Range<java.lang.Integer>> characterRanges)
Emit a list of
Replacements to convert from input to output. |
public static Formatter create()
public static Formatter createFormatter(com.palantir.javaformat.java.JavaFormatterOptions options)
public void formatSource(com.google.common.io.CharSource input,
com.google.common.io.CharSink output)
throws com.palantir.javaformat.java.FormatterException,
java.io.IOException
FormatterException - if the input cannot be parsedjava.io.IOExceptionpublic java.lang.String formatSource(java.lang.String input)
throws com.palantir.javaformat.java.FormatterException
Leaves import statements untouched.
input - the input stringFormatterException - if the input string cannot be parsedpublic java.lang.String formatSourceAndFixImports(java.lang.String input)
throws com.palantir.javaformat.java.FormatterException
Fixing imports includes ordering, spacing, and removal of unused import statements.
input - the input stringFormatterException - if the input string cannot be parsedpublic java.lang.String formatSource(java.lang.String input,
java.util.Collection<com.google.common.collect.Range<java.lang.Integer>> characterRanges)
throws com.palantir.javaformat.java.FormatterException
input - the input stringcharacterRanges - the character ranges to be reformattedFormatterException - if the input string cannot be parsedpublic com.google.common.collect.ImmutableList<com.palantir.javaformat.java.Replacement> getFormatReplacements(java.lang.String input,
java.util.Collection<com.google.common.collect.Range<java.lang.Integer>> characterRanges)
throws com.palantir.javaformat.java.FormatterException
Replacements to convert from input to output.input - the input compilation unitcharacterRanges - the character ranges to reformatReplacements, sorted from low index to high index, without overlapsFormatterException - if the input string cannot be parsed