Improved support for comment folding
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / ui / CodeGeneration.java
1 /*******************************************************************************
2  * Copyright (c) 2000, 2004 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials 
4  * are made available under the terms of the Common Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/cpl-v10.html
7  * 
8  * Contributors:
9  *     IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package net.sourceforge.phpdt.ui;
12
13 import net.sourceforge.phpdt.core.ICompilationUnit;
14 import net.sourceforge.phpdt.core.IMethod;
15 import net.sourceforge.phpdt.internal.corext.codemanipulation.StubUtility;
16
17 import org.eclipse.core.runtime.CoreException;
18
19 /**
20  * Class that offers access to the templates contained in the 'code templates' preference page.
21  * 
22  * @since 2.1
23  */
24 public class CodeGeneration {
25         
26         private CodeGeneration() {
27         }
28         
29         /**
30          * Returns the content for a new compilation unit using the 'new Java file' code template.
31          * @param cu The compilation to create the source for. The compilation unit does not need to exist.
32          * @param typeComment The comment for the type to be created. Used when the code template contains a <i>${typecomment}</i> variable. Can be <code>null</code> if
33          * no comment should be added.
34          * @param typeContent The code of the type, including type declaration and body.
35          * @param lineDelimiter The line delimiter to be used.
36          * @return Returns the new content or <code>null</code> if the template is undefined or empty.
37          * @throws CoreException Thrown when the evaluation of the code template fails.
38          */
39         public static String getCompilationUnitContent(ICompilationUnit cu, String typeComment, String typeContent, String lineDelimiter) throws CoreException {        
40                 return StubUtility.getCompilationUnitContent(cu, typeComment, typeContent, lineDelimiter);
41         }
42         
43         /**
44          * Returns the content for a new type comment using the 'type comment' code template. The returned content is unformatted and is not indented.
45          * @param cu The compilation where the type is contained. The compilation unit does not need to exist.
46          * @param typeQualifiedName The name of the type to which the comment is added. For inner types the name must be qualified and include the outer
47          * types names (dot separated). See {@link net.sourceforge.phpdt.core.IType#getTypeQualifiedName(char)}.
48          * @param lineDelimiter The line delimiter to be used.
49          * @return Returns the new content or <code>null</code> if the code template is undefined or empty. The returned content is unformatted and is not indented.
50          * @throws CoreException Thrown when the evaluation of the code template fails.
51          */     
52         public static String getTypeComment(ICompilationUnit cu, String typeQualifiedName, String lineDelimiter) throws CoreException {
53                 return StubUtility.getTypeComment(cu, typeQualifiedName, lineDelimiter);
54         }
55
56         /**
57          * Returns the content for a new field comment using the 'field comment' code template. The returned content is unformatted and is not indented.
58          * @param cu The compilation where the field is contained. The compilation unit does not need to exist.
59          * @param typeName The name of the field declared type.
60          * @param fieldName The name of the field to which the comment is added.
61          * @param lineDelimiter The line delimiter to be used.
62          * @return Returns the new content or <code>null</code> if the code template is undefined or empty. The returned content is unformatted and is not indented.
63          * @throws CoreException Thrown when the evaluation of the code template fails.
64          * @since 3.0
65          */     
66         public static String getFieldComment(ICompilationUnit cu, String typeName, String fieldName, String lineDelimiter) throws CoreException {
67                 return StubUtility.getFieldComment(cu, typeName, fieldName, lineDelimiter);
68         }       
69         
70         /**
71          * Returns the comment for a method or constructor using the comment code templates (constructor / method / overriding method).
72          * <code>null</code> is returned if the template is empty.
73          * @param cu The compilation unit to which the method belongs. The compilation unit does not need to exist.
74          * @param declaringTypeName Name of the type to which the method belongs. For inner types the name must be qualified and include the outer
75          * types names (dot separated). See {@link net.sourceforge.phpdt.core.IType#getTypeQualifiedName(char)}.
76          * @param decl The MethodDeclaration AST node that will be added as new
77          * method. The node does not need to exist in an AST (no parent needed) and does not need to resolve.
78          * See {@link net.sourceforge.phpdt.core.dom.AST#newMethodDeclaration()} for how to create such a node.
79          * @param overridden The binding of the method that will be overridden by the created
80          * method or <code>null</code> if no method is overridden.
81          * @param lineDelimiter The line delimiter to be used.
82          * @return Returns the generated method comment or <code>null</code> if the
83          * code template is empty. The returned content is unformatted and not indented (formatting required).
84          * @throws CoreException Thrown when the evaluation of the code template fails.
85          */
86 //      public static String getMethodComment(ICompilationUnit cu, String declaringTypeName, MethodDeclaration decl, IMethodBinding overridden, String lineDelimiter) throws CoreException {
87 //              return StubUtility.getMethodComment(cu, declaringTypeName, decl, overridden, lineDelimiter);
88 //      }
89
90         /**
91          * Returns the comment for a method or constructor using the comment code templates (constructor / method / overriding method).
92          * <code>null</code> is returned if the template is empty.
93          * <p>The returned string is unformatted and not indented.
94          * <p>Exception types and return type are in signature notation. e.g. a source method declared as <code>public void foo(String text, int length)</code>
95          * would return the array <code>{"QString;","I"}</code> as parameter types. See {@link net.sourceforge.phpdt.core.Signature}.
96          * 
97          * @param cu The compilation unit to which the method belongs. The compilation unit does not need to exist.
98          * @param declaringTypeName Name of the type to which the method belongs. For inner types the name must be qualified and include the outer
99          * types names (dot separated). See {@link net.sourceforge.phpdt.core.IType#getTypeQualifiedName(char)}.
100          * @param methodName Name of the method.
101          * @param paramNames Names of the parameters for the method.
102          * @param excTypeSig Thrown exceptions (Signature notation).
103          * @param retTypeSig Return type (Signature notation) or <code>null</code>
104          * for constructors.
105          * @param overridden The method that will be overridden by the created method or
106          * <code>null</code> for non-overriding methods. If not <code>null</code>, the method must exist.
107          * @param lineDelimiter The line delimiter to be used.
108          * @return Returns the constructed comment or <code>null</code> if
109          * the comment code template is empty. The returned content is unformatted and not indented (formatting required).
110          * @throws CoreException Thrown when the evaluation of the code template fails.
111          */
112         public static String getMethodComment(ICompilationUnit cu, String declaringTypeName, String methodName, String[] paramNames, String[] excTypeSig, String retTypeSig, IMethod overridden, String lineDelimiter) throws CoreException {
113                 return StubUtility.getMethodComment(cu, declaringTypeName, methodName, paramNames, excTypeSig, retTypeSig, overridden, lineDelimiter);
114         }
115                 
116         /**
117          * Returns the comment for a method or constructor using the comment code templates (constructor / method / overriding method).
118          * <code>null</code> is returned if the template is empty.
119          * <p>The returned string is unformatted and not indented.
120          * 
121          * @param method The method to be documented. The method must exist.
122          * @param overridden The method that will be overridden by the created method or
123          * <code>null</code> for non-overriding methods. If not <code>null</code>, the method must exist.
124          * @param lineDelimiter The line delimiter to be used.
125          * @return Returns the constructed comment or <code>null</code> if
126          * the comment code template is empty. The returned string is unformatted and and has no indent (formatting required).
127          * @throws CoreException Thrown when the evaluation of the code template fails.
128          */
129         public static String getMethodComment(IMethod method, IMethod overridden, String lineDelimiter) throws CoreException {
130                 return StubUtility.getMethodComment(method, overridden, lineDelimiter);
131         }       
132
133         /**
134          * Returns the content of the body for a method or constructor using the method body templates.
135          * <code>null</code> is returned if the template is empty.
136          * <p>The returned string is unformatted and not indented.
137          * 
138          * @param cu The compilation unit to which the method belongs. The compilation unit does not need to exist.
139          * @param declaringTypeName Name of the type to which the method belongs. For inner types the name must be qualified and include the outer
140          * types names (dot separated). See {@link net.sourceforge.phpdt.core.IType#getTypeQualifiedName(char)}.
141          * @param methodName Name of the method.
142          * @param isConstructor Defines if the created body is for a constructor.
143          * @param bodyStatement The code to be entered at the place of the variable ${body_statement}. 
144          * @param lineDelimiter The line delimiter to be used.
145          * @return Returns the constructed body content or <code>null</code> if
146          * the comment code template is empty. The returned string is unformatted and and has no indent (formatting required).
147          * @throws CoreException Thrown when the evaluation of the code template fails.
148          */     
149         public static String getMethodBodyContent(ICompilationUnit cu, String declaringTypeName, String methodName, boolean isConstructor, String bodyStatement, String lineDelimiter) throws CoreException {
150                 return StubUtility.getMethodBodyContent(isConstructor, cu.getJavaProject(), declaringTypeName, methodName, bodyStatement, lineDelimiter);
151         }
152         
153         /**
154          * Returns the content of body for a getter method using the getter method body template.
155          * <code>null</code> is returned if the template is empty.
156          * <p>The returned string is unformatted and not indented.
157          * 
158          * @param cu The compilation unit to which the method belongs. The compilation unit does not need to exist.
159          * @param declaringTypeName Name of the type to which the method belongs. For inner types the name must be qualified and include the outer
160          * types names (dot separated). See {@link net.sourceforge.phpdt.core.IType#getTypeQualifiedName(char)}.
161          * @param methodName The name of the getter method.
162          * @param fieldName The name of the field to get in the getter method, corresponding to the template variable for ${field}. 
163          * @param lineDelimiter The line delimiter to be used.
164          * @return Returns the constructed body content or <code>null</code> if
165          * the comment code template is empty. The returned string is unformatted and and has no indent (formatting required).
166          * @throws CoreException Thrown when the evaluation of the code template fails.
167          * @since 3.0
168          */     
169         public static String getGetterMethodBodyContent(ICompilationUnit cu, String declaringTypeName, String methodName, String fieldName, String lineDelimiter) throws CoreException {
170                 return StubUtility.getGetterMethodBodyContent(cu.getJavaProject(), declaringTypeName, methodName, fieldName, lineDelimiter);
171         }
172         
173         /**
174          * Returns the content of body for a setter method using the setter method body template.
175          * <code>null</code> is returned if the template is empty.
176          * <p>The returned string is unformatted and not indented.
177          * 
178          * @param cu The compilation unit to which the method belongs. The compilation unit does not need to exist.
179          * @param declaringTypeName Name of the type to which the method belongs. For inner types the name must be qualified and include the outer
180          * types names (dot separated). See {@link net.sourceforge.phpdt.core.IType#getTypeQualifiedName(char)}.
181          * @param methodName The name of the setter method.
182          * @param fieldName The name of the field to be set in the setter method, corresponding to the template variable for ${field}.
183          * @param paramName The name of the parameter passed to the setter method, corresponding to the template variable for $(param).
184          * @param lineDelimiter The line delimiter to be used.
185          * @return Returns the constructed body content or <code>null</code> if
186          * the comment code template is empty. The returned string is unformatted and and has no indent (formatting required).
187          * @throws CoreException Thrown when the evaluation of the code template fails.
188          * @since 3.0
189          */     
190         public static String getSetterMethodBodyContent(ICompilationUnit cu, String declaringTypeName, String methodName, String fieldName, String paramName, String lineDelimiter) throws CoreException {
191                 return StubUtility.getSetterMethodBodyContent(cu.getJavaProject(), declaringTypeName, methodName, fieldName, paramName, lineDelimiter);
192         }
193         
194         /**
195          * Returns the comment for a getter method using the getter comment template.
196          * <code>null</code> is returned if the template is empty.
197          * <p>The returned string is unformatted and not indented.
198          * 
199          * @param cu The compilation unit to which the method belongs. The compilation unit does not need to exist.
200          * @param declaringTypeName Name of the type to which the method belongs. For inner types the name must be qualified and include the outer
201          * types names (dot separated). See {@link net.sourceforge.phpdt.core.IType#getTypeQualifiedName(char)}.
202          * @param methodName Name of the method.
203          * @param fieldName Name of the field to get.
204          * @param fieldType The type of the field to get.
205          * @param bareFieldName The field name without prefix or suffix.
206          * @param lineDelimiter The line delimiter to be used.
207          * @return Returns the generated getter comment or <code>null</code> if the
208          * code template is empty. The returned content is not indented.
209          * @throws CoreException Thrown when the evaluation of the code template fails.
210          * @since 3.0
211          */
212         public static String getGetterComment(ICompilationUnit cu, String declaringTypeName, String methodName, String fieldName, String fieldType, String bareFieldName, String lineDelimiter) throws CoreException {
213                 return StubUtility.getGetterComment(cu, declaringTypeName, methodName, fieldName, fieldType, bareFieldName, lineDelimiter);
214         }
215         
216         /**
217          * Returns the comment for a setter method using the setter method body template.
218          * <code>null</code> is returned if the template is empty.
219          * <p>The returned string is unformatted and not indented.
220          * 
221          * @param cu The compilation unit to which the method belongs. The compilation unit does not need to exist.
222          * @param declaringTypeName Name of the type to which the method belongs. For inner types the name must be qualified and include the outer
223          * types names (dot separated). See {@link net.sourceforge.phpdt.core.IType#getTypeQualifiedName(char)}.
224          * @param methodName Name of the method.
225          * @param fieldName Name of the field that is set.
226          * @param fieldType The type of the field that is to set.
227          * @param paramName The name of the parameter that used to set.
228          * @param bareFieldName The field name without prefix or suffix.
229          * @param lineDelimiter The line delimiter to be used.
230          * @return Returns the generated setter comment or <code>null</code> if the
231          * code template is empty. The returned comment is not indented.
232          * @throws CoreException Thrown when the evaluation of the code template fails.
233          * @since 3.0
234          */
235         public static String getSetterComment(ICompilationUnit cu, String declaringTypeName, String methodName, String fieldName, String fieldType, String paramName, String bareFieldName, String lineDelimiter) throws CoreException {
236                 return StubUtility.getSetterComment(cu, declaringTypeName, methodName, fieldName, fieldType, paramName, bareFieldName, lineDelimiter);
237         }               
238 }