1 /*******************************************************************************
2 * Copyright (c) 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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import net.sourceforge.phpdt.core.compiler.CharOperation;
15 import org.eclipse.core.runtime.IProgressMonitor;
18 * Completion proposal.
20 * In typical usage, the user working in a Java code editor issues
21 * a code assist command. This command results in a call to
22 * <code>ICodeAssist.codeComplete(position, completionRequestor)</code>
23 * passing the current position in the source code. The code assist
24 * engine analyzes the code in the buffer, determines what kind of
25 * Java language construct is at that position, and proposes ways
26 * to complete that construct. These proposals are instances of
27 * subclasses of <code>CompletionProposal</code>. These proposals,
28 * perhaps after sorting and filtering, are presented to the user
32 * The proposal is as follows: insert
33 * the {@linkplain #getCompletion() completion string} into the
34 * source file buffer, replacing the characters between
35 * {@linkplain #getReplaceStart() the start}
36 * and {@linkplain #getReplaceEnd() end}. The string
37 * can be arbitrary; for example, it might include not only the
38 * name of a method but a set of parentheses. Moreover, the source
39 * range may include source positions before or after the source
40 * position where <code>ICodeAssist.codeComplete</code> was invoked.
41 * The rest of the information associated with the proposal is
42 * to provide context that may help a user to choose from among
43 * competing proposals.
46 * The completion engine creates instances of this class; it is not
47 * intended to be used by other clients.
50 * @see ICodeAssist#codeComplete(int, CompletionRequestor)
53 public final class CompletionProposal {
56 * Completion is a declaration of an anonymous class.
57 * This kind of completion might occur in a context like
58 * <code>"new List^;"</code> and complete it to
59 * <code>"new List() {}"</code>.
61 * The following additional context information is available
62 * for this kind of completion proposal at little extra cost:
64 * <li>{@link #getDeclarationSignature()} -
65 * the type signature of the type being implemented or subclassed
68 * <li>{@link #getSignature()} -
69 * the method signature of the constructor that is referenced
71 * <li>{@link #getFlags()} -
72 * the modifiers flags of the constructor that is referenced
79 public static final int ANONYMOUS_CLASS_DECLARATION = 1;
82 * Completion is a reference to a field.
83 * This kind of completion might occur in a context like
84 * <code>"this.ref^ = 0;"</code> and complete it to
85 * <code>"this.refcount = 0;"</code>.
87 * The following additional context information is available
88 * for this kind of completion proposal at little extra cost:
90 * <li>{@link #getDeclarationSignature()} -
91 * the type signature of the type that declares the field that is referenced
93 * <li>{@link #getFlags()} -
94 * the modifiers flags (including ACC_ENUM) of the field that is referenced
96 * <li>{@link #getName()} -
97 * the simple name of the field that is referenced
99 * <li>{@link #getSignature()} -
100 * the type signature of the field's type (as opposed to the
101 * signature of the type in which the referenced field
109 public static final int FIELD_REF = 2;
112 * Completion is a keyword.
113 * This kind of completion might occur in a context like
114 * <code>"public cl^ Foo {}"</code> and complete it to
115 * <code>"public class Foo {}"</code>.
117 * The following additional context information is available
118 * for this kind of completion proposal at little extra cost:
120 * <li>{@link #getName()} -
123 * <li>{@link #getFlags()} -
124 * the corresponding modifier flags if the keyword is a modifier
131 public static final int KEYWORD = 3;
134 * Completion is a reference to a label.
135 * This kind of completion might occur in a context like
136 * <code>"break lo^;"</code> and complete it to
137 * <code>"break loop;"</code>.
139 * The following additional context information is available
140 * for this kind of completion proposal at little extra cost:
142 * <li>{@link #getName()} -
143 * the simple name of the label that is referenced
150 public static final int LABEL_REF = 4;
153 * Completion is a reference to a local variable.
154 * This kind of completion might occur in a context like
155 * <code>"ke^ = 4;"</code> and complete it to
156 * <code>"keys = 4;"</code>.
158 * The following additional context information is available
159 * for this kind of completion proposal at little extra cost:
161 * <li>{@link #getFlags()} -
162 * the modifiers flags of the local variable that is referenced
164 * <li>{@link #getName()} -
165 * the simple name of the local variable that is referenced
167 * <li>{@link #getSignature()} -
168 * the type signature of the local variable's type
175 public static final int LOCAL_VARIABLE_REF = 5;
178 * Completion is a reference to a method.
179 * This kind of completion might occur in a context like
180 * <code>"System.out.pr^();"</code> and complete it to
181 * <code>""System.out.println();"</code>.
183 * The following additional context information is available
184 * for this kind of completion proposal at little extra cost:
186 * <li>{@link #getDeclarationSignature()} -
187 * the type signature of the type that declares the method that is referenced
189 * <li>{@link #getFlags()} -
190 * the modifiers flags of the method that is referenced
192 * <li>{@link #getName()} -
193 * the simple name of the method that is referenced
195 * <li>{@link #getSignature()} -
196 * the method signature of the method that is referenced
203 public static final int METHOD_REF = 6;
206 * Completion is a declaration of a method.
207 * This kind of completion might occur in a context like
208 * <code>"new List() {si^};"</code> and complete it to
209 * <code>"new List() {public int size() {} };"</code>.
211 * The following additional context information is available
212 * for this kind of completion proposal at little extra cost:
214 * <li>{@link #getDeclarationSignature()} -
215 * the type signature of the type that declares the
216 * method that is being overridden or implemented
218 * <li>{@link #getName()} -
219 * the simple name of the method that is being overridden
222 * <li>{@link #getSignature()} -
223 * the method signature of the method that is being
224 * overridden or implemented
226 * <li>{@link #getFlags()} -
227 * the modifiers flags of the method that is being
228 * overridden or implemented
235 public static final int METHOD_DECLARATION = 7;
238 * Completion is a reference to a package.
239 * This kind of completion might occur in a context like
240 * <code>"import java.u^.*;"</code> and complete it to
241 * <code>"import java.util.*;"</code>.
243 * The following additional context information is available
244 * for this kind of completion proposal at little extra cost:
246 * <li>{@link #getDeclarationSignature()} -
247 * the dot-based package signature of the package that is referenced
254 public static final int PACKAGE_REF = 8;
257 * Completion is a reference to a type. Any kind of type
258 * is allowed, including primitive types, reference types,
259 * array types, parameterized types, and type variables.
260 * This kind of completion might occur in a context like
261 * <code>"public static Str^ key;"</code> and complete it to
262 * <code>"public static String key;"</code>.
264 * The following additional context information is available
265 * for this kind of completion proposal at little extra cost:
267 * <li>{@link #getDeclarationSignature()} -
268 * the dot-based package signature of the package that contains
269 * the type that is referenced
271 * <li>{@link #getSignature()} -
272 * the type signature of the type that is referenced
274 * <li>{@link #getFlags()} -
275 * the modifiers flags (including Flags.AccInterface, AccEnum,
276 * and AccAnnotation) of the type that is referenced
283 public static final int TYPE_REF = 9;
286 * Completion is a declaration of a variable (locals, parameters,
289 * The following additional context information is available
290 * for this kind of completion proposal at little extra cost:
292 * <li>{@link #getName()} -
293 * the simple name of the variable being declared
295 * <li>{@link #getSignature()} -
296 * the type signature of the type of the variable
299 * <li>{@link #getFlags()} -
300 * the modifiers flags of the variable being declared
306 public static final int VARIABLE_DECLARATION = 10;
309 * Kind of completion request.
311 private int completionKind;
314 * Offset in original buffer where ICodeAssist.codeComplete() was
317 private int completionLocation;
320 * Start position (inclusive) of source range in original buffer
321 * containing the relevant token
322 * defaults to empty subrange at [0,0).
324 private int tokenStart = 0;
327 * End position (exclusive) of source range in original buffer
328 * containing the relevant token;
329 * defaults to empty subrange at [0,0).
331 private int tokenEnd = 0;
334 * Completion string; defaults to empty string.
336 private char[] completion = CharOperation.NO_CHAR;
339 * Start position (inclusive) of source range in original buffer
340 * to be replaced by completion string;
341 * defaults to empty subrange at [0,0).
343 private int replaceStart = 0;
346 * End position (exclusive) of source range in original buffer
347 * to be replaced by completion string;
348 * defaults to empty subrange at [0,0).
350 private int replaceEnd = 0;
353 * Relevance rating; positive; higher means better;
354 * defaults to minimum rating.
356 private int relevance = 1;
359 * Signature of the relevant package or type declaration
360 * in the context, or <code>null</code> if none.
363 private char[] declarationSignature = null;
366 * Simple name of the method, field,
367 * member, or variable relevant in the context, or
368 * <code>null</code> if none.
371 private char[] name = null;
374 * Signature of the method, field type, member type,
375 * relevant in the context, or <code>null</code> if none.
378 private char[] signature = null;
381 * Modifier flags relevant in the context, or
382 * <code>Flags.AccDefault</code> if none.
383 * Defaults to <code>Flags.AccDefault</code>.
385 private int flags = Flags.AccDefault;
388 * Parameter names (for method completions), or
389 * <code>null</code> if none. Lazily computed.
390 * Defaults to <code>null</code>.
392 private char[][] parameterNames = null;
395 * Indicates whether parameter names have been computed.
397 private boolean parameterNamesComputed = false;
400 * Creates a basic completion proposal. All instance
401 * field have plausible default values unless otherwise noted.
403 * Note that the constructors for this class are internal to the
404 * Java model implementation. Clients cannot directly create
405 * CompletionProposal objects.
408 * @param kind one of the kind constants declared on this class
409 * @param completionOffset original offset of code completion request
410 * @return a new completion proposal
412 public static CompletionProposal create(int kind, int completionOffset) {
413 return new CompletionProposal(kind, completionOffset);
417 * Creates a basic completion proposal. All instance
418 * field have plausible default values unless otherwise noted.
420 * Note that the constructors for this class are internal to the
421 * Java model implementation. Clients cannot directly create
422 * CompletionProposal objects.
425 * @param kind one of the kind constants declared on this class
426 * @param completionLocation original offset of code completion request
428 CompletionProposal(int kind, int completionLocation) {
429 if ((kind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION)
430 || (kind > CompletionProposal.VARIABLE_DECLARATION)) {
431 throw new IllegalArgumentException();
433 if (this.completion == null || completionLocation < 0) {
434 throw new IllegalArgumentException();
436 this.completionKind = kind;
437 this.completionLocation = completionLocation;
441 * Returns the kind of completion being proposed.
443 * The set of different kinds of completion proposals is
444 * expected to change over time. It is strongly recommended
445 * that clients do <b>not</b> assume that the kind is one of the
446 * ones they know about, and code defensively for the
447 * possibility of unexpected future growth.
450 * @return the kind; one of the kind constants
451 * declared on this class, or possibly a kind unknown
454 public int getKind() {
455 return this.completionKind;
459 * Returns the character index in the source file buffer
460 * where source completion was requested (the
461 * <code>offset</code>parameter to
462 * <code>ICodeAssist.codeComplete</code>.
464 * @return character index in source file buffer
465 * @see ICodeAssist#codeComplete(int,CompletionRequestor)
467 public int getCompletionLocation() {
468 return this.completionLocation;
472 * Returns the character index of the start of the
473 * subrange in the source file buffer containing the
474 * relevant token being completed. This
475 * token is either the identifier or Java language keyword
476 * under, or immediately preceding, the original request
477 * offset. If the original request offset is not within
478 * or immediately after an identifier or keyword, then the
479 * position returned is original request offset and the
480 * token range is empty.
482 * @return character index of token start position (inclusive)
484 public int getTokenStart() {
485 return this.tokenStart;
489 * Returns the character index of the end (exclusive) of the subrange
490 * in the source file buffer containing the
491 * relevant token. When there is no relevant token, the
493 * (<code>getEndToken() == getStartToken()</code>).
495 * @return character index of token end position (exclusive)
497 public int getTokenEnd() {
498 return this.tokenEnd;
502 * Sets the character indices of the subrange in the
503 * source file buffer containing the relevant token being
504 * completed. This token is either the identifier or
505 * Java language keyword under, or immediately preceding,
506 * the original request offset. If the original request
507 * offset is not within or immediately after an identifier
508 * or keyword, then the source range begins at original
509 * request offset and is empty.
511 * If not set, defaults to empty subrange at [0,0).
514 * @param startIndex character index of token start position (inclusive)
515 * @param endIndex character index of token end position (exclusive)
517 public void setTokenRange(int startIndex, int endIndex) {
518 if (startIndex < 0 || endIndex < startIndex) {
519 throw new IllegalArgumentException();
521 this.tokenStart = startIndex;
522 this.tokenEnd = endIndex;
526 * Returns the proposed sequence of characters to insert into the
527 * source file buffer, replacing the characters at the specified
528 * source range. The string can be arbitrary; for example, it might
529 * include not only the name of a method but a set of parentheses.
531 * The client must not modify the array returned.
534 * @return the completion string
536 public char[] getCompletion() {
537 return this.completion;
541 * Sets the proposed sequence of characters to insert into the
542 * source file buffer, replacing the characters at the specified
543 * source range. The string can be arbitrary; for example, it might
544 * include not only the name of a method but a set of parentheses.
546 * If not set, defaults to an empty character array.
549 * The completion engine creates instances of this class and sets
550 * its properties; this method is not intended to be used by other clients.
553 * @param completion the completion string
555 public void setCompletion(char[] completion) {
556 this.completion = completion;
560 * Returns the character index of the start of the
561 * subrange in the source file buffer to be replaced
562 * by the completion string. If the subrange is empty
563 * (<code>getReplaceEnd() == getReplaceStart()</code>),
564 * the completion string is to be inserted at this
567 * Note that while the token subrange is precisely
568 * specified, the replacement range is loosely
569 * constrained and may not bear any direct relation
570 * to the original request offset. For example, a
571 * it would be possible for a type completion to
572 * propose inserting an import declaration at the
573 * top of the compilation unit; or the completion
574 * might include trailing parentheses and
575 * punctuation for a method completion.
578 * @return replacement start position (inclusive)
580 public int getReplaceStart() {
581 return this.replaceStart;
585 * Returns the character index of the end of the
586 * subrange in the source file buffer to be replaced
587 * by the completion string. If the subrange is empty
588 * (<code>getReplaceEnd() == getReplaceStart()</code>),
589 * the completion string is to be inserted at this
592 * @return replacement end position (exclusive)
594 public int getReplaceEnd() {
595 return this.replaceEnd;
599 * Sets the character indices of the subrange in the
600 * source file buffer to be replaced by the completion
601 * string. If the subrange is empty
602 * (<code>startIndex == endIndex</code>),
603 * the completion string is to be inserted at this
606 * If not set, defaults to empty subrange at [0,0).
609 * The completion engine creates instances of this class and sets
610 * its properties; this method is not intended to be used by other clients.
613 * @param startIndex character index of replacement start position (inclusive)
614 * @param endIndex character index of replacement end position (exclusive)
616 public void setReplaceRange(int startIndex, int endIndex) {
617 if (startIndex < 0 || endIndex < startIndex) {
618 throw new IllegalArgumentException();
620 this.replaceStart = startIndex;
621 this.replaceEnd = endIndex;
625 * Returns the relative relevance rating of this proposal.
627 * @return relevance rating of this proposal; ratings are positive; higher means better
629 public int getRelevance() {
630 return this.relevance;
634 * Sets the relative relevance rating of this proposal.
636 * If not set, defaults to the lowest possible rating (1).
639 * The completion engine creates instances of this class and sets
640 * its properties; this method is not intended to be used by other clients.
643 * @param rating relevance rating of this proposal; ratings are positive; higher means better
645 public void setRelevance(int rating) {
647 throw new IllegalArgumentException();
649 this.relevance = rating;
653 * Returns the type or package signature of the relevant
654 * declaration in the context, or <code>null</code> if none.
656 * This field is available for the following kinds of
657 * completion proposals:
659 * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - type signature
660 * of the type that is being subclassed or implemented</li>
661 * <li><code>FIELD_REF</code> - type signature
662 * of the type that declares the field that is referenced</li>
663 * <li><code>METHOD_REF</code> - type signature
664 * of the type that declares the method that is referenced</li>
665 * <li><code>METHOD_DECLARATION</code> - type signature
666 * of the type that declares the method that is being
667 * implemented or overridden</li>
668 * <li><code>PACKAGE_REF</code> - dot-based package
669 * signature of the package that is referenced</li>
670 * <li><code>TYPE_REF</code> - dot-based package
671 * signature of the package containing the type that is referenced</li>
673 * For kinds of completion proposals, this method returns
674 * <code>null</code>. Clients must not modify the array
678 * @return the declaration signature, or
679 * <code>null</code> if none
682 public char[] getDeclarationSignature() {
683 return this.declarationSignature;
687 * Sets the type or package signature of the relevant
688 * declaration in the context, or <code>null</code> if none.
690 * If not set, defaults to none.
693 * The completion engine creates instances of this class and sets
694 * its properties; this method is not intended to be used by other clients.
697 * @param signature the type or package signature, or
698 * <code>null</code> if none
700 public void setDeclarationSignature(char[] signature) {
701 this.declarationSignature = signature;
705 * Returns the simple name of the method, field,
706 * member, or variable relevant in the context, or
707 * <code>null</code> if none.
709 * This field is available for the following kinds of
710 * completion proposals:
712 * <li><code>FIELD_REF</code> - the name of the field</li>
713 * <li><code>KEYWORD</code> - the keyword</li>
714 * <li><code>LABEL_REF</code> - the name of the label</li>
715 * <li><code>LOCAL_VARIABLE_REF</code> - the name of the local variable</li>
716 * <li><code>METHOD_REF</code> - the name of the method</li>
717 * <li><code>METHOD_DECLARATION</code> - the name of the method</li>
718 * <li><code>VARIABLE_DECLARATION</code> - the name of the variable</li>
720 * For kinds of completion proposals, this method returns
721 * <code>null</code>. Clients must not modify the array
725 * @return the keyword, field, method, local variable, or member
726 * name, or <code>null</code> if none
728 public char[] getName() {
734 * Sets the simple name of the method, field,
735 * member, or variable relevant in the context, or
736 * <code>null</code> if none.
738 * If not set, defaults to none.
741 * The completion engine creates instances of this class and sets
742 * its properties; this method is not intended to be used by other clients.
745 * @param name the keyword, field, method, local variable,
746 * or member name, or <code>null</code> if none
748 public void setName(char[] name) {
753 * Returns the signature of the method or type
754 * relevant in the context, or <code>null</code> if none.
756 * This field is available for the following kinds of
757 * completion proposals:
759 * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - method signature
760 * of the constructor that is being invoked</li>
761 * <li><code>FIELD_REF</code> - the type signature
762 * of the referenced field's type</li>
763 * <li><code>LOCAL_VARIABLE_REF</code> - the type signature
764 * of the referenced local variable's type</li>
765 * <li><code>METHOD_REF</code> - method signature
766 * of the method that is referenced</li>
767 * <li><code>METHOD_DECLARATION</code> - method signature
768 * of the method that is being implemented or overridden</li>
769 * <li><code>TYPE_REF</code> - type signature
770 * of the type that is referenced</li>
771 * <li><code>VARIABLE_DECLARATION</code> - the type signature
772 * of the type of the variable being declared</li>
774 * For kinds of completion proposals, this method returns
775 * <code>null</code>. Clients must not modify the array
779 * @return the signature, or <code>null</code> if none
782 public char[] getSignature() {
783 return this.signature;
787 * Sets the signature of the method, field type, member type,
788 * relevant in the context, or <code>null</code> if none.
790 * If not set, defaults to none.
793 * The completion engine creates instances of this class and sets
794 * its properties; this method is not intended to be used by other clients.
797 * @param signature the signature, or <code>null</code> if none
799 public void setSignature(char[] signature) {
800 this.signature = signature;
804 * Returns the modifier flags relevant in the context, or
805 * <code>Flags.AccDefault</code> if none.
807 * This field is available for the following kinds of
808 * completion proposals:
810 * <li><code>ANONYMOUS_CLASS_DECLARATION</code> - modifier flags
811 * of the constructor that is referenced</li>
812 * <li><code>FIELD_REF</code> - modifier flags
813 * of the field that is referenced;
814 * <code>Flags.AccEnum</code> can be used to recognize
815 * references to enum constants
817 * <li><code>KEYWORD</code> - modifier flag
818 * corrresponding to the modifier keyword</li>
819 * <li><code>LOCAL_VARIABLE_REF</code> - modifier flags
820 * of the local variable that is referenced</li>
821 * <li><code>METHOD_REF</code> - modifier flags
822 * of the method that is referenced;
823 * <code>Flags.AccAnnotation</code> can be used to recognize
824 * references to annotation type members
826 * <li><code>METHOD_DECLARATION</code> - modifier flags
827 * for the method that is being implemented or overridden</li>
828 * <li><code>TYPE_REF</code> - modifier flags
829 * of the type that is referenced; <code>Flags.AccInterface</code>
830 * can be used to recognize references to interfaces,
831 * <code>Flags.AccEnum</code> enum types,
832 * and <code>Flags.AccAnnotation</code> annotation types
834 * <li><code>VARIABLE_DECLARATION</code> - modifier flags
835 * for the variable being declared</li>
837 * For kinds of completion proposals, this method returns
838 * <code>Flags.AccDefault</code>.
841 * @return the modifier flags, or
842 * <code>Flags.AccDefault</code> if none
845 public int getFlags() {
850 * Sets the modifier flags relevant in the context.
852 * If not set, defaults to none.
855 * The completion engine creates instances of this class and sets
856 * its properties; this method is not intended to be used by other clients.
859 * @param flags the modifier flags, or
860 * <code>Flags.AccDefault</code> if none
862 public void setFlags(int flags) {
867 * Finds the method parameter names.
868 * This information is relevant to method reference (and
869 * method declaration proposals). Returns <code>null</code>
870 * if not available or not relevant.
872 * The client must not modify the array returned.
875 * <b>Note that this is an expensive thing to compute, which may require
876 * parsing Java source files, etc. Use sparingly.
879 * @param monitor the progress monitor, or <code>null</code> if none
880 * @return the parameter names, or <code>null</code> if none
881 * or not available or not relevant
883 public char[][] findParameterNames(IProgressMonitor monitor) {
884 if (!this.parameterNamesComputed) {
885 this.parameterNamesComputed = true;
886 // TODO (jerome) - Missing implementation
888 return this.parameterNames;
892 * Sets the method parameter names.
893 * This information is relevant to method reference (and
894 * method declaration proposals).
896 * The completion engine creates instances of this class and sets
897 * its properties; this method is not intended to be used by other clients.
900 * @param parameterNames the parameter names, or <code>null</code> if none
902 public void setParameterNames(char[][] parameterNames) {
903 this.parameterNames = parameterNames;
904 this.parameterNamesComputed = true;