improved PHP parser
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / internal / compiler / IDocumentElementRequestor.java
1 /*******************************************************************************
2  * Copyright (c) 2000, 2003 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.internal.compiler;
12
13 import net.sourceforge.phpdt.core.compiler.IProblem;
14
15 /**
16  * Part of the source element parser responsible for building the output.
17  * It gets notified of structural information as they are detected, relying
18  * on the requestor to assemble them together, based on the notifications it got.
19  *
20  * The structural investigation includes:
21  * - package statement
22  * - import statements
23  * - top-level types: package member, member types (member types of member types...)
24  * - fields
25  * - methods
26  *
27  * If reference information is requested, then all source constructs are
28  * investigated and type, field & method references are provided as well.
29  *
30  * Any (parsing) problem encountered is also provided.
31  *
32  * All positions are relative to the exact source fed to the parser.
33  *
34  * Elements which are complex are notified in two steps:
35  * - enter<Element> : once the element header has been identified
36  * - exit<Element> : once the element has been fully consumed
37  *
38  * other simpler elements (package, import) are read all at once:
39  * - accept<Element>
40  */
41  
42 public interface IDocumentElementRequestor {
43 /**
44  * @param declarationStart - a source position corresponding to the start of the package
45  *  declaration
46  * @param declarationEnd - a source position corresponding to the end of the package
47  *  declaration
48  * @param javaDocPositions - answer back an array of sourceStart/sourceEnd
49  * positions of the available JavaDoc comments. The array is a flattened 
50  * structure: 2*n entries with consecutives start and end positions.
51  * If no JavaDoc is available, then null is answered instead of an empty array.
52  * e.g. { 10, 20, 25, 45 }  --> javadoc1 from 10 to 20, javadoc2 from 25 to 45
53  * The array is equals to null if there are no javadoc comments
54  * @param name - the name of the package
55  * @param nameStartPosition - a source position corresponding to the first character of the
56  *  name
57  * @param onDemand - a boolean equals to true if the import is an import on demand
58  */
59 void acceptImport(
60         int declarationStart, 
61         int declarationEnd,
62         int[] javaDocPositions, 
63         char[] name, 
64         int nameStartPosition,
65         boolean onDemand);
66 /**
67  * @param declarationStart - a source position corresponding to the start of the package
68  *  declaration
69  * @param declarationEnd - a source position corresponding to the end of the package
70  *  declaration
71  * @param javaDocPositions - answer back an array of sourceStart/sourceEnd
72  * positions of the available JavaDoc comments. The array is a flattened 
73  * structure: 2*n entries with consecutives start and end positions.
74  * If no JavaDoc is available, then null is answered instead of an empty array.
75  * e.g. { 10, 20, 25, 45 }  --> javadoc1 from 10 to 20, javadoc2 from 25 to 45
76  * The array is equals to null if there are no javadoc comments
77  * @param modifiers - the modifiers for this initializer
78  * @param modifiersStart - a source position corresponding to the start
79  *  of the textual modifiers, is < 0 if there are no textual modifiers
80  * @param bodyStart - the position of the '{'
81  * @param bodyEnd - the position of the '}'
82  */
83 void acceptInitializer(
84         int declarationStart,
85         int declarationEnd,
86         int[] javaDocPositions, 
87         int modifiers,
88         int modifiersStart,
89         int bodyStart,
90         int bodyEnd);
91 /*
92  * Table of line separator position. This table is passed once at the end
93  * of the parse action, so as to allow computation of normalized ranges.
94  *
95  * A line separator might corresponds to several characters in the source,
96  * 
97  */
98 void acceptLineSeparatorPositions(int[] positions);
99 /**
100  * @param declarationStart - a source position corresponding to the start of the package
101  *  declaration
102  * @param declarationEnd - a source position corresponding to the end of the package
103  *  declaration
104  * @param javaDocPositions - answer back an array of sourceStart/sourceEnd
105  * positions of the available JavaDoc comments. The array is a flattened 
106  * structure: 2*n entries with consecutives start and end positions.
107  * If no JavaDoc is available, then null is answered instead of an empty array.
108  * e.g. { 10, 20, 25, 45 }  --> javadoc1 from 10 to 20, javadoc2 from 25 to 45
109  * The array is equals to null if there are no javadoc comments
110  * @param name - the name of the package
111  * @param nameStartPosition - a source position corresponding to the first character of the
112  *  name
113  */
114 void acceptPackage(
115         int declarationStart, 
116         int declarationEnd,
117         int[] javaDocPositions, 
118         char[] name, 
119         int nameStartPosition);
120 /**
121  * @param problem - Used to report a problem while running the JDOM
122  */
123 void acceptProblem(IProblem problem);
124 /**
125  * @param declarationStart - a source position corresponding to the start
126  *  of this class.
127  * @param javaDocPositions - answer back an array of sourceStart/sourceEnd
128  * positions of the available JavaDoc comments. The array is a flattened 
129  * structure: 2*n entries with consecutives start and end positions.
130  * If no JavaDoc is available, then null is answered instead of an empty array.
131  * e.g. { 10, 20, 25, 45 }  --> javadoc1 from 10 to 20, javadoc2 from 25 to 45
132  * The array is equals to null if there are no javadoc comments
133  * @param modifiers - the modifiers for this class
134  * @param modifiersStart - a source position corresponding to the start
135  *  of the textual modifiers, is < 0 if there are no textual modifiers
136  * @param classStart - a source position corresponding to the start
137  *  of the keyword 'class'
138  * @param name - the name of the class
139  * @param nameStart - a source position corresponding to the start of the name
140  * @param nameEnd - a source position corresponding to the end of the name
141  * @param superclass - the name of the superclass
142  * @param superclassStart - a source position corresponding to the start
143  *  of the superclass name
144  * @param superclassEnd - a source position corresponding to the end of the
145  *  superclass name
146  * @param superinterfaces - the name of the superinterfaces
147  * @param superinterfaceStarts - an array of source positions corresponding
148  *  to the start of their respective superinterface names
149  * @param superinterfaceEnds - an array of source positions corresponding
150  *  to the end of their respective superinterface names
151  * @param bodyStart - a source position corresponding to the open bracket
152  *  of the class body
153  */
154 void enterClass(
155         int declarationStart,
156         int[] javaDocPositions,
157         int modifiers,
158         int modifiersStart,
159         int classStart, 
160         char[] name,
161         int nameStart,
162         int nameEnd,
163         char[] superclass,
164         int superclassStart,
165         int superclassEnd,
166         char[][] superinterfaces,
167         int[] superinterfaceStarts,
168         int[] superinterfaceEnds,
169         int bodyStart);
170 void enterCompilationUnit();
171 /**
172  * @param declarationStart - a source position corresponding to the first character 
173  *  of this constructor declaration
174  * @param javaDocPositions - answer back an array of sourceStart/sourceEnd
175  * positions of the available JavaDoc comments. The array is a flattened 
176  * structure: 2*n entries with consecutives start and end positions.
177  * If no JavaDoc is available, then null is answered instead of an empty array.
178  * e.g. { 10, 20, 25, 45 }  --> javadoc1 from 10 to 20, javadoc2 from 25 to 45
179  * The array is equals to null if there are no javadoc comments
180  * @param modifiers - the modifiers for this constructor converted to a flag
181  * @param modifiersStart - a source position corresponding to the first character of the
182  *  textual modifiers
183  * @param name - the name of this constructor
184  * @param nameStart - a source position corresponding to the first character of the name
185  * @param nameEnd - a source position corresponding to the last character of the name
186  * @param parameterTypes - a list of parameter type names
187  * @param parameterTypeStarts - a list of source positions corresponding to the
188  *  first character of each parameter type name
189  * @param parameterTypeEnds - a list of source positions corresponding to the
190  *  last character of each parameter type name
191  * @param parameterNames - a list of the names of the parameters
192  * @param parametersEnd - a source position corresponding to the last character of the
193  *  parameter list
194  * @param exceptionTypes - a list of the exception types
195  * @param exceptionTypeStarts - a list of source positions corresponding to the first
196  *  character of the respective exception types
197  * @param exceptionTypeEnds - a list of source positions corresponding to the last
198  *  character of the respective exception types
199  * @param bodyStart - a source position corresponding to the start of this 
200  *  constructor's body
201  */
202 void enterConstructor(
203         int declarationStart,
204         int[] javaDocPositions, 
205         int modifiers,
206         int modifiersStart, 
207         char[] name,
208         int nameStart,
209         int nameEnd,
210         char[][] parameterTypes,
211         int [] parameterTypeStarts,
212         int [] parameterTypeEnds,                       
213         char[][] parameterNames,
214         int [] parameterNameStarts,
215         int [] parameterNameEnds,
216         int parametersEnd,      
217         char[][] exceptionTypes,
218         int [] exceptionTypeStarts,
219         int [] exceptionTypeEnds,
220         int bodyStart);
221 /**
222  * @param declarationStart - a source position corresponding to the first character 
223  *  of this field
224  * @param javaDocPositions - answer back an array of sourceStart/sourceEnd
225  * positions of the available JavaDoc comments. The array is a flattened 
226  * structure: 2*n entries with consecutives start and end positions.
227  * If no JavaDoc is available, then null is answered instead of an empty array.
228  * e.g. { 10, 20, 25, 45 }  --> javadoc1 from 10 to 20, javadoc2 from 25 to 45
229  * The array is equals to null if there are no javadoc comments
230  * @param modifiers - the modifiers for this field converted to a flag
231  * @param modifiersStart - a source position corresponding to the first character of the
232  *  textual modifiers
233  * @param type - the name of the field type
234  * @param typeStart - a source position corresponding to the start of the fields type
235  * @param typeEnd - a source position corresponding to the end of the fields type
236  * @param typeDimensionCount - the array dimension indicated on the type (for example, 'int[] v')
237  * @param name - the name of this constructor
238  * @param nameStart - a source position corresponding to the first character of the name
239  * @param nameEnd - a source position corresponding to the last character of the name
240  * @param extendedTypeDimensionCount - the array dimension indicated on the variable,
241  *  (for example, 'int v[]')
242  * @param extendedTypeDimnesionEnd - a source position corresponding to the end of
243  *  the extened type dimension. This position should be -1 in case there is no extended
244  *  dimension for the type.
245  */
246 void enterField(
247         int declarationStart,
248         int[] javaDocPositions, 
249         int modifiers,
250         int modifiersStart,
251         char[] type,
252         int typeStart,
253         int typeEnd,
254         int typeDimensionCount,
255         char[] name,
256         int nameStart,
257         int nameEnd,
258         int extendedTypeDimensionCount,
259         int extendedTypeDimensionEnd);
260 /**
261  * @param declarationStart - a source position corresponding to the start
262  *  of this class.
263  * @param javaDocPositions - answer back an array of sourceStart/sourceEnd
264  * positions of the available JavaDoc comments. The array is a flattened 
265  * structure: 2*n entries with consecutives start and end positions.
266  * If no JavaDoc is available, then null is answered instead of an empty array.
267  * e.g. { 10, 20, 25, 45 }  --> javadoc1 from 10 to 20, javadoc2 from 25 to 45
268  * The array is equals to null if there are no javadoc comments
269  * @param modifiers - the modifiers for this class
270  * @param modifiersStart - a source position corresponding to the start
271  *  of the textual modifiers, is < 0 if there are no textual modifiers
272  * @param interfaceStart - a source position corresponding to the start
273  *  of the keyword 'interface'
274  * @param name - the name of the class
275  * @param nameStart - a source position corresponding to the start of the name
276  * @param nameEnd - a source position corresponding to the end of the name
277  * @param superinterfaces - the name of the superinterfaces
278  * @param superinterfaceStarts - an array of source positions corresponding
279  *  to the start of their respective superinterface names
280  * @param superinterfaceEnds - an array of source positions corresponding
281  *  to the end of their respective superinterface names
282  * @param bodyStart - a source position corresponding to the open bracket
283  *  of the class body
284  */
285 void enterInterface(
286         int declarationStart,
287         int[] javaDocPositions, 
288         int modifiers,
289         int modifiersStart,
290         int interfaceStart,
291         char[] name,
292         int nameStart,
293         int nameEnd,
294         char[][] superinterfaces,
295         int[] superinterfaceStarts,
296         int[] superinterfaceEnds,
297         int bodyStart);
298 /**
299  * @param declarationStart - a source position corresponding to the first character 
300  *  of this constructor declaration
301  * @param javaDocPositions - answer back an array of sourceStart/sourceEnd
302  * positions of the available JavaDoc comments. The array is a flattened 
303  * structure: 2*n entries with consecutives start and end positions.
304  * If no JavaDoc is available, then null is answered instead of an empty array.
305  * e.g. { 10, 20, 25, 45 }  --> javadoc1 from 10 to 20, javadoc2 from 25 to 45
306  * The array is equals to null if there are no javadoc comments
307  * @param modifiers - the modifiers for this constructor converted to a flag
308  * @param modifiersStart - a source position corresponding to the first character of the
309  *  textual modifiers
310  * @param returnType - the name of the return type
311  * @param returnTypeStart - a source position corresponding to the first character
312  *  of the return type
313  * @param returnTypeEnd - a source position corresponding to the last character
314  *  of the return type
315  * @param returnTypeDimensionCount - the array dimension count as supplied on the
316  *  return type (for example, 'public int[] foo() {}')
317  * @param name - the name of this constructor
318  * @param nameStart - a source position corresponding to the first character of the name
319  * @param nameEnd - a source position corresponding to the last character of the name
320  * @param parameterTypes - a list of parameter type names
321  * @param parameterTypeStarts - a list of source positions corresponding to the
322  *  first character of each parameter type name
323  * @param parameterTypeEnds - a list of source positions corresponding to the
324  *  last character of each parameter type name
325  * @param parameterNames - a list of the names of the parameters
326  * @param parametersEnd - a source position corresponding to the last character of the
327  *  parameter list
328  * @param extendedReturnTypeDimensionCount - the array dimension count as supplied on the
329  *  end of the parameter list (for example, 'public int foo()[] {}')
330  * @param extendedReturnTypeDimensionEnd - a source position corresponding to the last character
331  *  of the extended return type dimension. This position should be -1 in case there is no extended
332  *  dimension for the type.
333  * @param exceptionTypes - a list of the exception types
334  * @param exceptionTypeStarts - a list of source positions corresponding to the first
335  *  character of the respective exception types
336  * @param exceptionTypeEnds - a list of source positions corresponding to the last
337  *  character of the respective exception types
338  * @param bodyStart - a source position corresponding to the start of this 
339  *  method's body
340  */
341 void enterMethod(
342         int declarationStart,
343         int[] javaDocPositions, 
344         int modifiers,
345         int modifiersStart, 
346         char[] returnType,
347         int returnTypeStart,
348         int returnTypeEnd,
349         int returnTypeDimensionCount,
350         char[] name,
351         int nameStart,
352         int nameEnd,
353         char[][] parameterTypes,
354         int [] parameterTypeStarts,
355         int [] parameterTypeEnds,                       
356         char[][] parameterNames,
357         int [] parameterNameStarts,
358         int [] parameterNameEnds,
359         int parametersEnd,
360         int extendedReturnTypeDimensionCount,
361         int extendedReturnTypeDimensionEnd,     
362         char[][] exceptionTypes,
363         int [] exceptionTypeStarts,
364         int [] exceptionTypeEnds,
365         int bodyStart);
366 /**
367  * @param bodyEnd - a source position corresponding to the closing bracket of the class
368  * @param declarationEnd - a source position corresponding to the end of the class
369  *  declaration.  This can include whitespace and comments following the closing bracket.
370  */
371 void exitClass(
372         int bodyEnd,
373         int declarationEnd);
374 /**
375  * @param declarationEnd - a source position corresponding to the end of the compilation unit
376  */
377 void exitCompilationUnit(
378         int declarationEnd);
379 /**
380  * @param bodyEnd - a source position corresponding to the closing bracket of the method
381  * @param declarationEnd - a source position corresponding to the end of the method
382  *  declaration.  This can include whitespace and comments following the closing bracket.
383  */
384 void exitConstructor(
385         int bodyEnd,
386         int declarationEnd);
387 /**
388  * @param bodyEnd - a source position corresponding to the end of the field.
389  * @param declarationEnd - a source position corresponding to the end of the field.
390  *  This can include whitespace and comments following the semi-colon.
391  */
392 void exitField(
393         int bodyEnd,
394         int declarationEnd);
395 /**
396  * @param bodyEnd - a source position corresponding to the closing bracket of the interface
397  * @param declarationEnd - a source position corresponding to the end of the interface
398  *  declaration.  This can include whitespace and comments following the closing bracket.
399  */
400 void exitInterface(
401         int bodyEnd,
402         int declarationEnd);
403 /**
404  * @param bodyEnd - a source position corresponding to the closing bracket of the method
405  * @param declarationEnd - a source position corresponding to the end of the method
406  *  declaration.  This can include whitespace and comments following the closing bracket.
407  */
408 void exitMethod(
409         int bodyEnd,
410         int declarationEnd);
411 }