Package com.google.googlejavaformat.java

Class Formatter

  • @Immutable
public final class Formatter
extends java.lang.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 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.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private static JavaInputAstVisitor createVisitor​(java.lang.String className, OpsBuilder builder, JavaFormatterOptions options)  
      (package private) static boolean errorDiagnostic​(javax.tools.Diagnostic<?> input)  
      (package private) static void format​(JavaInput javaInput, JavaOutput javaOutput, JavaFormatterOptions options)
      Construct a Formatter given a Java compilation unit.
      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<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.
      static com.google.common.collect.RangeSet<java.lang.Integer> lineRangesToCharRanges​(java.lang.String input, com.google.common.collect.RangeSet<java.lang.Integer> lineRanges)
      Converts zero-indexed, [closed, open) line ranges in the given source file to character ranges.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • EMPTY_RANGE

        static final com.google.common.collect.Range<java.lang.Integer> EMPTY_RANGE

    • Constructor Detail

      • Formatter

        public Formatter()
        A new Formatter instance with default options.

    • Method Detail

      • errorDiagnostic

        static boolean errorDiagnostic​(javax.tools.Diagnostic<?> input)

      • formatSource

        public void formatSource​(com.google.common.io.CharSource input,
                         com.google.common.io.CharSink output)
                  throws FormatterException,
                         java.io.IOException
        Format the given input (a Java compilation unit) into the output stream.
        Throws:
        FormatterException - if the input cannot be parsed
        java.io.IOException

      • formatSource

        public java.lang.String formatSource​(java.lang.String input)
                              throws FormatterException
        Format an input string (a Java compilation unit) into an output string.

        Leaves import statements untouched.

        Parameters:
        input - the input string
        Returns:
        the output string
        Throws:
        FormatterException - if the input string cannot be parsed

      • formatSourceAndFixImports

        public java.lang.String formatSourceAndFixImports​(java.lang.String input)
                                           throws FormatterException
        Formats an input string (a Java compilation unit) and fixes imports.

        Fixing imports includes ordering, spacing, and removal of unused import statements.

        Parameters:
        input - the input string
        Returns:
        the output string
        Throws:
        FormatterException - if the input string cannot be parsed
        See Also:
        Google Java Style Guide - 3.3.3 Import ordering and spacing

      • formatSource

        public java.lang.String formatSource​(java.lang.String input,
                                     java.util.Collection<com.google.common.collect.Range<java.lang.Integer>> characterRanges)
                              throws FormatterException
        Format an input string (a Java compilation unit), 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 com.google.common.collect.ImmutableList<Replacement> getFormatReplacements​(java.lang.String input,
                                                                                  java.util.Collection<com.google.common.collect.Range<java.lang.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

      • lineRangesToCharRanges

        public static com.google.common.collect.RangeSet<java.lang.Integer> lineRangesToCharRanges​(java.lang.String input,
                                                                                           com.google.common.collect.RangeSet<java.lang.Integer> lineRanges)
        Converts zero-indexed, [closed, open) line ranges in the given source file to character ranges.