com.google.googlejavaformat.java

Class Formatter

java.lang.Object

com.google.googlejavaformat.java.Formatter

public final class Formatter
extends Object

This is google-java-format, a new Java formatter that follows the Google Java Style Guide quite precisely---to the letter and to the spirit.

This formatter uses the Eclipse parser to generate an AST. Because the Eclipse 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/Dereck Oppen-style list of formatting Ops [1--2] that then generate 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.

[1] Nelson, Greg, and John DeTreville. Personal communication.

[2] Oppen, Dereck C. "Prettyprinting". ACM Transactions on Programming Languages and Systems, Volume 2 Issue 4, Oct. 1980, pp. 465–483.

Constructor Summary

Constructors

Constructor and Description
Formatter()

Method Summary

Modifier and Type	Method and Description
static void	format(JavaInput javaInput, JavaOutput javaOutput, int maxWidth, List<FormatterDiagnostic> errors, int indentationMultiplier) Construct a Formatter given Java compilation unit.
void	formatSource(CharSource input, CharSink output) Format the given input (a Java compilation unit) into the output stream.
String	formatSource(String input) Format an input string (a Java compilation unit) into an output string.
String	formatSource(String input, List<Range<Integer>> characterRanges) Format an input string (a compilation), for only the specified character ranges.
ImmutableList<Replacement>	getFormatReplacements(String input, List<Range<Integer>> characterRanges) Emit a list of Replacements to convert from input to output.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Formatter

public Formatter()

Method Detail

format

public static void format(JavaInput javaInput,
                          JavaOutput javaOutput,
                          int maxWidth,
                          List<FormatterDiagnostic> errors,
                          int indentationMultiplier)

Construct a Formatter given Java compilation unit. Parses the code; builds a JavaInput and the corresponding JavaOutput.

Parameters:

javaInput - the input, a Java compilation unit

javaOutput - the JavaOutput

maxWidth - the maximum formatted width

errors - mutable list to receive errors

indentationMultiplier - the multiplier for the unit of indent; the default is 1

formatSource

public void formatSource(CharSource input,
                         CharSink output)
                  throws FormatterException,
                         IOException

Format the given input (a Java compilation unit) into the output stream.

Throws:

FormatterException - if the input cannot be parsed

IOException

formatSource

public String formatSource(String input)
                    throws FormatterException

Format an input string (a Java compilation unit) into an output string.

Parameters:

input - the input string

Returns:

the output string

Throws:

FormatterException - if the input string cannot be parsed

formatSource

public String formatSource(String input,
                           List<Range<Integer>> characterRanges)
                    throws FormatterException

Format an input string (a compilation), for only the specified character ranges. These ranges are extended as necessary (e.g., to encompass whole lines).

Parameters:

input - the input string

characterRanges - the character ranges to be reformatted

Returns:

the output string

Throws:

FormatterException - if the input string cannot be parsed

getFormatReplacements

public ImmutableList<Replacement> getFormatReplacements(String input,
                                                        List<Range<Integer>> characterRanges)
                                                 throws FormatterException

Emit a list of Replacements to convert from input to output.

Parameters:

input - the input compilation unit

characterRanges - the character ranges to reformat

Returns:

a list of Replacements, sorted from low index to high index, without overlaps

Throws:

FormatterException - if the input string cannot be parsed