bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_codeformatter.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><html>
 <head>
 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
 <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
 <meta HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

 <link REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
 <title>Using the code formatter</title>

 <link rel="stylesheet" type="text/css" HREF="../book.css">
 </head>
 <body>
 <h2>Using the code formatter</h2>
 <P>
 The JDT API allows other plug-ins to use the default code formatter or to implement their own code formatter.</p>
 <ul>
 <li>To use the default code formatter, the two methods to consider are:
 <ul>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/ToolFactory.html#createCodeFormatter(java.util.Map)">ToolFactory.createCodeFormatter(Map)</a></b></li>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/ToolFactory.html#createCodeFormatter(java.util.Map, int)">ToolFactory.createCodeFormatter(Map, int)</a></b></li>
 </ul>
 </li>
 <li>To define a new code formatter, you need to define a subclass of <b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">CodeFormatter</a></b>.
 </li>
 </ul>
 <h3>Using the default code formatter</h3>

 <h4>Getting a code formatter instance</h4>
 <p>
 The factory methods on <b><a href="../reference/api/org/eclipse/jdt/core/ToolFactory.html">ToolFactory</a></b> 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
 <b><a href="../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">DefaultCodeFormatterConstants</a></b> like
 <b><a href="../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#getEclipseDefaultSettings()">DefaultCodeFormatterConstants.getEclipseDefaultSettings()</a></b></p>
 <p>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:</p>
 <ul>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_CODEGEN_TARGET_PLATFORM">JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM</a></b></li>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_SOURCE">JavaCore.COMPILER_SOURCE</a></b></li>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_COMPLIANCE">JavaCore.COMPILER_COMPLIANCE</a></b></li>
 </ul>
 <p>The possible values of these options are given by the constants:</p>
 <ul>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_1">JavaCore.VERSION_1_1</a></b></li>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_2">JavaCore.VERSION_1_2</a></b></li>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_3">JavaCore.VERSION_1_3</a></b></li>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_4">JavaCore.VERSION_1_4</a></b></li>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_5">JavaCore.VERSION_1_5</a></b></li>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_6">JavaCore.VERSION_1_6</a></b></li>
 <li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_7">JavaCore.VERSION_1_7</a></b></li>
 </ul>
 <p>If you want to modify the default maps, it is recommended that you use the methods defined on <b><a href="../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">DefaultCodeFormatterConstants</a></b>
 to create the values of the corresponding options. This is especially true for the options relative to code wrapping.
 </p>

 <h4>Invoking the code formatter</h4>
 <p>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 <b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int, java.lang.String, int, int, int, java.lang.String)">format</a></b> method.
 The returned value of this method is a text edit. This text edit then needs to be applied to an <b><a href="../../org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/text/IDocument.html">IDocument</a></b> instance
 in order to get the formatted result.</p>

 <h4>Example</h4>
 <font color="#4444CC"><pre>
 		// 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());
 </pre></font>
 <p>On this example,</p>
 <font color="#4444CC"><pre>
 public enum X { A,B,C,D,E,F}
 </pre></font>
 the result would be:
 <font color="#4444CC"><pre>
 public enum X {
 	A,
 	B,
 	C,
 	D,
 	E,
 	F
 }
 </pre></font>
 <h3>Defining a new code formatter</h3>
 To do so, you need to implement the class <b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">CodeFormatter</a></b>.
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><html>
	<head>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
	<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
	<meta HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">

	<link REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
	<title>Using the code formatter</title>

	<link rel="stylesheet" type="text/css" HREF="../book.css">
	</head>
	<body>
	<h2>Using the code formatter</h2>
	<P>
	The JDT API allows other plug-ins to use the default code formatter or to implement their own code formatter.</p>
	<ul>
	<li>To use the default code formatter, the two methods to consider are:
	<ul>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/ToolFactory.html#createCodeFormatter(java.util.Map)">ToolFactory.createCodeFormatter(Map)</a></b></li>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/ToolFactory.html#createCodeFormatter(java.util.Map, int)">ToolFactory.createCodeFormatter(Map, int)</a></b></li>
	</ul>
	</li>
	<li>To define a new code formatter, you need to define a subclass of <b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">CodeFormatter</a></b>.
	</li>
	</ul>
	<h3>Using the default code formatter</h3>

	<h4>Getting a code formatter instance</h4>
	<p>
	The factory methods on <b><a href="../reference/api/org/eclipse/jdt/core/ToolFactory.html">ToolFactory</a></b> 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
	<b><a href="../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">DefaultCodeFormatterConstants</a></b> like
	<b><a href="../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html#getEclipseDefaultSettings()">DefaultCodeFormatterConstants.getEclipseDefaultSettings()</a></b></p>
	<p>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:</p>
	<ul>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_CODEGEN_TARGET_PLATFORM">JavaCore.COMPILER_CODEGEN_TARGET_PLATFORM</a></b></li>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_SOURCE">JavaCore.COMPILER_SOURCE</a></b></li>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#COMPILER_COMPLIANCE">JavaCore.COMPILER_COMPLIANCE</a></b></li>
	</ul>
	<p>The possible values of these options are given by the constants:</p>
	<ul>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_1">JavaCore.VERSION_1_1</a></b></li>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_2">JavaCore.VERSION_1_2</a></b></li>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_3">JavaCore.VERSION_1_3</a></b></li>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_4">JavaCore.VERSION_1_4</a></b></li>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_5">JavaCore.VERSION_1_5</a></b></li>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_6">JavaCore.VERSION_1_6</a></b></li>
	<li><b><a href="../reference/api/org/eclipse/jdt/core/JavaCore.html#VERSION_1_7">JavaCore.VERSION_1_7</a></b></li>
	</ul>
	<p>If you want to modify the default maps, it is recommended that you use the methods defined on <b><a href="../reference/api/org/eclipse/jdt/core/formatter/DefaultCodeFormatterConstants.html">DefaultCodeFormatterConstants</a></b>
	to create the values of the corresponding options. This is especially true for the options relative to code wrapping.
	</p>

	<h4>Invoking the code formatter</h4>
	<p>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 <b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html#format(int, java.lang.String, int, int, int, java.lang.String)">format</a></b> method.
	The returned value of this method is a text edit. This text edit then needs to be applied to an <b><a href="../../org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/text/IDocument.html">IDocument</a></b> instance
	in order to get the formatted result.</p>

	<h4>Example</h4>
	<font color="#4444CC"><pre>
	// 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());
	</pre></font>
	<p>On this example,</p>
	<font color="#4444CC"><pre>
	public enum X { A,B,C,D,E,F}
	</pre></font>
	the result would be:
	<font color="#4444CC"><pre>
	public enum X {
	A,
	B,
	C,
	D,
	E,
	F
	}
	</pre></font>
	<h3>Defining a new code formatter</h3>
	To do so, you need to implement the class <b><a href="../reference/api/org/eclipse/jdt/core/formatter/CodeFormatter.html">CodeFormatter</a></b>.
	</body>
	</html>