Package org.eclipse.cdt.core.formatter

## Class CodeFormatter

- java.lang.Object
- - org.eclipse.cdt.core.formatter.CodeFormatter

    public abstract class CodeFormatter
    extends Object

Specification for a generic source code formatter.

Since:
  3.0

### Field Summary

Fields
`static String` `EMPTY_STRING`
`static int` `K_CLASS_BODY_DECLARATIONS` Kind used to format a set of class body declarations.
`static int` `K_COMPILATION_UNIT` Deprecated. Use #K_TRANSLATION_UNIT
`static int` `K_EXPRESSION` Kind used to format an expression.
`static int` `K_MULTI_LINE_COMMENT` Kind used to format a multi-line comment.
`static int` `K_SINGLE_LINE_COMMENT` Kind used to format a single-line comment.
`static int` `K_STATEMENTS` Kind used to format a set of statements.
`static int` `K_TRANSLATION_UNIT` Kind used to format a translation unit.
`static int` `K_UNKNOWN` Unknown kind.

### Constructor Summary

Constructors
`CodeFormatter()`

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`String` `createIndentationString​(int indentationLevel)` Answers the string that corresponds to the indentation to the given indentation level, or an empty string if the indentation cannot be computed.
`abstract org.eclipse.text.edits.TextEdit` `format​(int kind, String source, int offset, int length, int indentationLevel, String lineSeparator)` Formats `source`, and returns a text edit that correspond to the difference between the given string and the formatted string.
`org.eclipse.text.edits.TextEdit[]` `format​(int kind, String source, org.eclipse.jface.text.IRegion[] regions, String lineSeparator)` Formats one or more regions of `source`, and returns an array of edits, one edit per region.
`abstract void` `setOptions​(Map<String,​?> options)`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### EMPTY_STRING

    public static final String EMPTY_STRING

See Also:
  Constant Field Values

#### K_UNKNOWN

    public static final int K_UNKNOWN

Unknown kind.

See Also:
  Constant Field Values

#### K_EXPRESSION

    public static final int K_EXPRESSION

Kind used to format an expression.

See Also:
  Constant Field Values

#### K_STATEMENTS

    public static final int K_STATEMENTS

Kind used to format a set of statements.

See Also:
  Constant Field Values

#### K_CLASS_BODY_DECLARATIONS

    public static final int K_CLASS_BODY_DECLARATIONS

Kind used to format a set of class body declarations.

See Also:
  Constant Field Values

#### K_COMPILATION_UNIT

    @Deprecated
    public static final int K_COMPILATION_UNIT

Deprecated.
Use #K_TRANSLATION_UNIT
Kind used to format a compilation unit.

See Also:
  Constant Field Values

#### K_TRANSLATION_UNIT

    public static final int K_TRANSLATION_UNIT

Kind used to format a translation unit.

See Also:
  Constant Field Values

#### K_SINGLE_LINE_COMMENT

    public static final int K_SINGLE_LINE_COMMENT

Kind used to format a single-line comment.

See Also:
  Constant Field Values

#### K_MULTI_LINE_COMMENT

    public static final int K_MULTI_LINE_COMMENT

Kind used to format a multi-line comment.

See Also:
  Constant Field Values

### Constructor Detail

#### CodeFormatter

    public CodeFormatter()

### Method Detail

#### format

    public abstract org.eclipse.text.edits.TextEdit format​(int kind,
                                                           String source,
                                                           int offset,
                                                           int length,
                                                           int indentationLevel,
                                                           String lineSeparator)

Formats `source`, and returns a text edit that correspond to the difference between the given string and the formatted string. It returns null if the given string cannot be formatted. If the offset position is matching a whitespace, the result can include whitespaces. It would be up to the caller to get rid of preceding whitespaces.

Parameters:
  `kind` - Use to specify the kind of the code snippet to format. It can be any of these: K_EXPRESSION, K_STATEMENTS, K_CLASS_BODY_DECLARATIONS, K_TRANSLATION_UNIT, K_UNKNOWN
  `source` - the document to format
  `offset` - the given offset to start recording the edits (inclusive).
  `length` - the given length to stop recording the edits (exclusive).
  `indentationLevel` - the initial indentation level, used to shift left/right the entire source fragment. An initial indentation level of zero or below has no effect.
  `lineSeparator` - the line separator to use in formatted source, if set to `null`, then the platform default one will be used.
Returns:
  the text edit
Throws:
  `IllegalArgumentException` - if offset is lower than 0, length is lower than 0 or length is greater than source length.

#### format

    public org.eclipse.text.edits.TextEdit[] format​(int kind,
                                                    String source,
                                                    org.eclipse.jface.text.IRegion[] regions,
                                                    String lineSeparator)

Formats one or more regions of `source`, and returns an array of edits, one edit per region. If some of the regions cannot be formatted, the corresponding elements of the returned array will be `null`. If the offset of a region is matching a whitespace, the result can include whitespaces. It would be up to the caller to get rid of preceding whitespaces. Subclasses may override this method to provide a more efficient implementation.

Parameters:
  `kind` - Use to specify the kind of the code snippet to format. It can be any of these: K_EXPRESSION, K_STATEMENTS, K_CLASS_BODY_DECLARATIONS, K_TRANSLATION_UNIT, K_UNKNOWN.
  `source` - the document to format.
  `regions` - regions of the source to be formatted.
  `lineSeparator` - the line separator to use in formatted source, if set to `null`, then the platform default one will be used.
Returns:
  the text edits, one per region.
Throws:
  `IllegalArgumentException` - if any of the regions is invalid.
Since:
  5.4

#### setOptions

    public abstract void setOptions​(Map<String,​?> options)

Parameters:
  `options` - - general formatter options

#### createIndentationString

    public String createIndentationString​(int indentationLevel)

Answers the string that corresponds to the indentation to the given indentation level, or an empty string if the indentation cannot be computed.

This method needs to be overridden in a subclass.

The default implementation returns an empty string.

Parameters:
  `indentationLevel` - the given indentation level
Returns:
  the string corresponding to the right indentation level
Throws:
  `IllegalArgumentException` - if the given indentation level is lower than zero