Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

EclipseJDT Plug-in Developer Guide
Previous Page Home Next Page

Using the code formatter

The JDT API allows other plug-ins to use the default code formatter to format source code.

The two methods to consider are: Note: The CodeFormatter class is not intended to be subclassed by clients.

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:

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

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

Use the newly created code formatter 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
}

Formatting a set of regions

The default code formatter allows to format a set of regions of a given source file.
This can be achieved by calling the format(int, String, IRegion[], int, String) method of the code formatter, with a given source kind and an array of regions .
  • Each of the region to format must be within source range and should not overlap with another region.
  • The array of regions to format must contain at least one region. Regions should be sorted by their offsets, smaller offset first.

Comment Formatter API

The default code formatter API offers the possibility to format comments during the processing of the code snippet.
This can be achieved by combining the appropriate flag F_INCLUDE_COMMENTS with K_COMPILATION_UNIT and K_UNKNOWN flags.

This flag is effective only if the corresponding formatting option was enabled when calling format(int, String, int, int, int, String) or format(int, String, IRegion[], int, String) methods:

Comment formatter options

Various formatting options are available in order to format comments:
  • General options to enable or disable the formatting of specific comments (javadoc, multi or single line comments), set maximum line width for comments.
  • javadoc comments options to enable the formatting of code snippets or HTML sections inside javadoc comments, indent tag descriptions, etc.
  • block comments option to keep or remove blanks lines within such comment
For detailed information about these settings, refer to the DefaultCodeFormatterConstants

Formatting comments with the stand-alone formatter

The default code formatter can be used to format comments (javadoc, multi or single line). In this case, the source passed to the format method should only contain a specific kind of comments, and corresponding kind K_JAVA_DOC , K_MULTI_LINE_COMMENT or K_SINGLE_LINE_COMMENT should be used.
  • Formatting javadoc comments

    The following unformatted javadoc:
    
     	/**
     * This is just a simple example to show how javadoc comments can 			 be formatted .
     * @param str The input string
     	 * @return 		 		The resulting 		string
     	 */
    
    
    should be formatted as follows:
    
    /**
     * This is just a simple example to show how javadoc comments can be formatted .
     * 
     * @param str
     *            The input string
     * @return The resulting string
     */
    
    
    using command:
    
    (...)
     final TextEdit edit = codeFormatter.format(
    	
    
    CodeFormatter.K_JAVA_DOC
    , // specify the kind: javadoc
    	source, // source to format (as per the above example)
    	0, // starting position
    	source.length(), // length
    	0, // initial indentation
    	System.getProperty("line.separator") // line separator
    );
    (...)
    
    
  • Formatting multi-line comments

    The following unformatted multi-line comment:
    
    /*
    	 * This is just an example of multi- line comment intended to demonstrate the default code formatter ability to format multi-line comments .
    	 * 
    	 * 		These possibilities include:	Formatting of javadoc 				comments, 
    	 * 				formatting of multi-line comments
     */
    
    
    should be formatted as follows:
    
    /*
     * This is just an example of multi- line comment intended to demonstrate
     * the default code formatter ability to format multi-line comments .
     * 
     * These possibilities include: Formatting of javadoc comments, formatting
     * of multi-line comments
     */
    
    
    using command:
    
    (...)
     final TextEdit edit = codeFormatter.format(
    	
    
    CodeFormatter.K_MULTI_LINE_COMMENT
    , // specify the kind: multi-line comments
    	source, // source to format (as per the above example)
    	0, // starting position
    	source.length(), // length
    	0, // initial indentation
    	System.getProperty("line.separator") // line separator
    );
    (...)
    
    
  • Formatting single line comments

    The following unformatted single line comments:
    
    // This is a long comment that should be split in multiple line comments in case the line comment formatting is enabled
    
    
    should be formatted as follows:
    
    // This is a long comment that should be split in multiple line comments in
    // case the line comment formatting is enabled
     
    using command:
    
    (...)
     final TextEdit edit = codeFormatter.format(
    	
    
    CodeFormatter.K_SINGLE_LINE_COMMENT
    ,  // specify the kind: single-line comments
    	source, // source to format (as per the above example)
    	0, // starting position
    	source.length(), // length
    	0, // initial indentation
    	System.getProperty("line.separator") // line separator
    );
    (...)
    
    

 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire