## Using the code formatter

The JDT API allows other plug-ins to use the default code formatter or to implement their own code formatter.

- To use the default code formatter, the two methods to consider are:

- ToolFactory.createCodeFormatter(Map)
- ToolFactory.createCodeFormatter(Map, int)

- To define a new code formatter, you need to define a subclass of CodeFormatter.

### Using the default code formatter

#### Getting a code formatter instance

The factory methods on ToolFactory can be invoked to create a new instance of the default code formatter. Before invoking one of those, you need to define a map that contains the code formatter options. In order to create such a map, you can use the methods defined in the class DefaultCodeFormatterConstants like DefaultCodeFormatterConstants.getEclipseDefaultSettings()

NOTE: These predefined maps contain only the code formatter specific options. In order to invoke the code formatter, you also need to specify what kind of source the code formatter will format. In order to do so, specify the three options:

- JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM
- JavaCore.COMPILER_SOURCE
- JavaCore.COMPILER_COMPLIANCE

The possible values of these options are given by the constants:

- JavaCore.VERSION_1_1
- JavaCore.VERSION_1_2
- JavaCore.VERSION_1_3
- JavaCore.VERSION_1_4
- JavaCore.VERSION_1_5
- JavaCore.VERSION_1_6
- JavaCore.VERSION_1_7

If you want to modify the default maps, it is recommended that you use the methods defined on DefaultCodeFormatterConstants to create the values of the corresponding options. This is especially true for the options relative to code wrapping.

#### Invoking the code formatter

Once you have the code formatter instance, the goal is to use it to format code snippets. The default code formatter allows you to format different kind of code snippets. These kinds are specified in the documentation of the format method. The returned value of this method is a text edit. This text edit then needs to be applied to an IDocument instance in order to get the formatted result.

#### Example

    		// take default Eclipse formatting options
    		Map options = DefaultCodeFormatterConstants.getEclipseDefaultSettings();

    		// initialize the compiler settings to be able to format 1.5 code
    		options.put(JavaCore.COMPILER_COMPLIANCE, JavaCore.VERSION_1_5);
    		options.put(JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM, JavaCore.VERSION_1_5);
    		options.put(JavaCore.COMPILER_SOURCE, JavaCore.VERSION_1_5);

    		// change the option to wrap each enum constant on a new line
    		options.put(
    			DefaultCodeFormatterConstants.FORMATTER_ALIGNMENT_FOR_ENUM_CONSTANTS,
    			DefaultCodeFormatterConstants.createAlignmentValue(
    				true,
    				DefaultCodeFormatterConstants.WRAP_ONE_PER_LINE,
    				DefaultCodeFormatterConstants.INDENT_ON_COLUMN));

    		// instanciate the default code formatter with the given options
    		final CodeFormatter codeFormatter = ToolFactory.createCodeFormatter(options);

    		// retrieve the source to format
    		String source = null;
    		try {
    			source = ...; // retrieve the source
    		} catch (IOException e) {
    			System.err.println("Could not retrieve the source"); //$NON-NLS-1$
    			e.printStackTrace();
    			return;
    		}
    		final TextEdit edit = codeFormatter.format(
    			CodeFormatter.K_COMPILATION_UNIT, // format a compilation unit
    			source, // source to format
    			0, // starting position
    			source.length(), // length
    			0, // initial indentation
    			System.getProperty("line.separator") // line separator
    		);

    		IDocument document = new Document(source);
    		try {
    			edit.apply(document);
    		} catch (MalformedTreeException e) {
    			e.printStackTrace();
    		} catch (BadLocationException e) {
    			e.printStackTrace();
    		}

    		// display the formatted string on the System out
    		System.out.println(document.get());

On this example,

    public enum X { A,B,C,D,E,F}

the result would be:

    public enum X {
    	A,
    	B,
    	C,
    	D,
    	E,
    	F
    }

### Defining a new code formatter

To do so, you need to implement the class CodeFormatter.