/******************************************************************************* * Copyright (c) 2004 IBM Corporation and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Common Public License v1.0 * which accompanies this distribution, and is available at * http://www.eclipse.org/legal/cpl-v10.html * * Contributors: * IBM Corporation - initial API and implementation *******************************************************************************/ package net.sourceforge.phpdt.core; import net.sourceforge.phpdt.core.compiler.CharOperation; //import org.eclipse.core.runtime.IProgressMonitor; /** * Completion proposal. *

* In typical usage, the user working in a Java code editor issues a code assist * command. This command results in a call to * ICodeAssist.codeComplete(position, completionRequestor) * passing the current position in the source code. The code assist engine * analyzes the code in the buffer, determines what kind of Java language * construct is at that position, and proposes ways to complete that construct. * These proposals are instances of subclasses of * CompletionProposal. These proposals, perhaps after sorting * and filtering, are presented to the user to make a choice. *

*

* The proposal is as follows: insert the * {@linkplain #getCompletion() completion string} into the source file buffer, * replacing the characters between {@linkplain #getReplaceStart() the start} * and {@linkplain #getReplaceEnd() end}. The string can be arbitrary; for * example, it might include not only the name of a method but a set of * parentheses. Moreover, the source range may include source positions before * or after the source position where ICodeAssist.codeComplete * was invoked. The rest of the information associated with the proposal is to * provide context that may help a user to choose from among competing * proposals. *

*

* The completion engine creates instances of this class; it is not intended to * be used by other clients. *

* * @see ICodeAssist#codeComplete(int, CompletionRequestor) * @since 3.0 */ public final class CompletionProposal { /** * Completion is a declaration of an anonymous class. This kind of * completion might occur in a context like "new List^;" and * complete it to "new List() {}". *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int ANONYMOUS_CLASS_DECLARATION = 1; /** * Completion is a reference to a field. This kind of completion might occur * in a context like "this.ref^ = 0;" and complete it to * "this.refcount = 0;". *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int FIELD_REF = 2; /** * Completion is a keyword. This kind of completion might occur in a context * like "public cl^ Foo {}" and complete it to * "public class Foo {}". *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int KEYWORD = 3; /** * Completion is a reference to a label. This kind of completion might occur * in a context like "break lo^;" and complete it to * "break loop;". *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int LABEL_REF = 4; /** * Completion is a reference to a local variable. This kind of completion * might occur in a context like "ke^ = 4;" and complete it * to "keys = 4;". *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int LOCAL_VARIABLE_REF = 5; /** * Completion is a reference to a method. This kind of completion might * occur in a context like "System.out.pr^();" and complete * it to ""System.out.println();". *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int METHOD_REF = 6; /** * Completion is a declaration of a method. This kind of completion might * occur in a context like "new List() {si^};" and complete * it to "new List() {public int size() {} };". *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int METHOD_DECLARATION = 7; /** * Completion is a reference to a package. This kind of completion might * occur in a context like "import java.u^.*;" and complete * it to "import java.util.*;". *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int PACKAGE_REF = 8; /** * Completion is a reference to a type. Any kind of type is allowed, * including primitive types, reference types, array types, parameterized * types, and type variables. This kind of completion might occur in a * context like "public static Str^ key;" and complete it to * "public static String key;". *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int TYPE_REF = 9; /** * Completion is a declaration of a variable (locals, parameters, fields, * etc.). *

* The following additional context information is available for this kind * of completion proposal at little extra cost: *

*

* * @see #getKind() */ public static final int VARIABLE_DECLARATION = 10; /** * Kind of completion request. */ private int completionKind; /** * Offset in original buffer where ICodeAssist.codeComplete() was requested. */ //private int completionLocation; /** * Start position (inclusive) of source range in original buffer containing * the relevant token defaults to empty subrange at [0,0). */ //private int tokenStart = 0; /** * End position (exclusive) of source range in original buffer containing * the relevant token; defaults to empty subrange at [0,0). */ //private int tokenEnd = 0; /** * Completion string; defaults to empty string. */ private char[] completion = CharOperation.NO_CHAR; /** * Start position (inclusive) of source range in original buffer to be * replaced by completion string; defaults to empty subrange at [0,0). */ private int replaceStart = 0; /** * End position (exclusive) of source range in original buffer to be * replaced by completion string; defaults to empty subrange at [0,0). */ private int replaceEnd = 0; /** * Relevance rating; positive; higher means better; defaults to minimum * rating. */ //private int relevance = 1; /** * Signature of the relevant package or type declaration in the context, or * null if none. Defaults to null. */ private char[] declarationSignature = null; /** * Simple name of the method, field, member, or variable relevant in the * context, or null if none. Defaults to null. */ private char[] name = null; /** * Signature of the method, field type, member type, relevant in the * context, or null if none. Defaults to null. */ private char[] signature = null; /** * Modifier flags relevant in the context, or Flags.AccDefault * if none. Defaults to Flags.AccDefault. */ private int flags = Flags.AccDefault; /** * Parameter names (for method completions), or null if none. * Lazily computed. Defaults to null. */ //private char[][] parameterNames = null; /** * Indicates whether parameter names have been computed. */ //private boolean parameterNamesComputed = false; /** * Creates a basic completion proposal. All instance field have plausible * default values unless otherwise noted. *

* Note that the constructors for this class are internal to the Java model * implementation. Clients cannot directly create CompletionProposal * objects. *

* * @param kind * one of the kind constants declared on this class * @param completionOffset * original offset of code completion request * @return a new completion proposal */ public static CompletionProposal create(int kind, int completionOffset) { return new CompletionProposal(kind, completionOffset); } /** * Creates a basic completion proposal. All instance field have plausible * default values unless otherwise noted. *

* Note that the constructors for this class are internal to the Java model * implementation. Clients cannot directly create CompletionProposal * objects. *

* * @param kind * one of the kind constants declared on this class * @param completionLocation * original offset of code completion request */ CompletionProposal(int kind, int completionLocation) { if ((kind < CompletionProposal.ANONYMOUS_CLASS_DECLARATION) || (kind > CompletionProposal.VARIABLE_DECLARATION)) { throw new IllegalArgumentException(); } if (this.completion == null || completionLocation < 0) { throw new IllegalArgumentException(); } this.completionKind = kind; //this.completionLocation = completionLocation; } /** * Returns the kind of completion being proposed. *

* The set of different kinds of completion proposals is expected to change * over time. It is strongly recommended that clients do not assume * that the kind is one of the ones they know about, and code defensively * for the possibility of unexpected future growth. *

* * @return the kind; one of the kind constants declared on this class, or * possibly a kind unknown to the caller */ public int getKind() { return this.completionKind; } /** * Returns the character index in the source file buffer where source * completion was requested (the offsetparameter to * ICodeAssist.codeComplete. * * @return character index in source file buffer * @see ICodeAssist#codeComplete(int,CompletionRequestor) */ // public int getCompletionLocation() { // return this.completionLocation; // } /** * Returns the character index of the start of the subrange in the source * file buffer containing the relevant token being completed. This token is * either the identifier or Java language keyword under, or immediately * preceding, the original request offset. If the original request offset is * not within or immediately after an identifier or keyword, then the * position returned is original request offset and the token range is * empty. * * @return character index of token start position (inclusive) */ // public int getTokenStart() { // return this.tokenStart; // } /** * Returns the character index of the end (exclusive) of the subrange in the * source file buffer containing the relevant token. When there is no * relevant token, the range is empty (getEndToken() == getStartToken()). * * @return character index of token end position (exclusive) */ // public int getTokenEnd() { // return this.tokenEnd; // } /** * Sets the character indices of the subrange in the source file buffer * containing the relevant token being completed. This token is either the * identifier or Java language keyword under, or immediately preceding, the * original request offset. If the original request offset is not within or * immediately after an identifier or keyword, then the source range begins * at original request offset and is empty. *

* If not set, defaults to empty subrange at [0,0). *

* * @param startIndex * character index of token start position (inclusive) * @param endIndex * character index of token end position (exclusive) */ // public void setTokenRange(int startIndex, int endIndex) { // if (startIndex < 0 || endIndex < startIndex) { // throw new IllegalArgumentException(); // } // this.tokenStart = startIndex; // this.tokenEnd = endIndex; // } /** * Returns the proposed sequence of characters to insert into the source * file buffer, replacing the characters at the specified source range. The * string can be arbitrary; for example, it might include not only the name * of a method but a set of parentheses. *

* The client must not modify the array returned. *

* * @return the completion string */ public char[] getCompletion() { return this.completion; } /** * Sets the proposed sequence of characters to insert into the source file * buffer, replacing the characters at the specified source range. The * string can be arbitrary; for example, it might include not only the name * of a method but a set of parentheses. *

* If not set, defaults to an empty character array. *

*

* The completion engine creates instances of this class and sets its * properties; this method is not intended to be used by other clients. *

* * @param completion * the completion string */ // public void setCompletion(char[] completion) { // this.completion = completion; // } /** * Returns the character index of the start of the subrange in the source * file buffer to be replaced by the completion string. If the subrange is * empty (getReplaceEnd() == getReplaceStart()), the * completion string is to be inserted at this index. *

* Note that while the token subrange is precisely specified, the * replacement range is loosely constrained and may not bear any direct * relation to the original request offset. For example, a it would be * possible for a type completion to propose inserting an import declaration * at the top of the compilation unit; or the completion might include * trailing parentheses and punctuation for a method completion. *

* * @return replacement start position (inclusive) */ public int getReplaceStart() { return this.replaceStart; } /** * Returns the character index of the end of the subrange in the source file * buffer to be replaced by the completion string. If the subrange is empty (getReplaceEnd() == getReplaceStart()), * the completion string is to be inserted at this index. * * @return replacement end position (exclusive) */ public int getReplaceEnd() { return this.replaceEnd; } /** * Sets the character indices of the subrange in the source file buffer to * be replaced by the completion string. If the subrange is empty (startIndex == endIndex), * the completion string is to be inserted at this index. *

* If not set, defaults to empty subrange at [0,0). *

*

* The completion engine creates instances of this class and sets its * properties; this method is not intended to be used by other clients. *

* * @param startIndex * character index of replacement start position (inclusive) * @param endIndex * character index of replacement end position (exclusive) */ // public void setReplaceRange(int startIndex, int endIndex) { // if (startIndex < 0 || endIndex < startIndex) { // throw new IllegalArgumentException(); // } // this.replaceStart = startIndex; // this.replaceEnd = endIndex; // } /** * Returns the relative relevance rating of this proposal. * * @return relevance rating of this proposal; ratings are positive; higher * means better */ // public int getRelevance() { // return this.relevance; // } /** * Sets the relative relevance rating of this proposal. *

* If not set, defaults to the lowest possible rating (1). *

*

* The completion engine creates instances of this class and sets its * properties; this method is not intended to be used by other clients. *

* * @param rating * relevance rating of this proposal; ratings are positive; * higher means better */ // public void setRelevance(int rating) { // if (rating <= 0) { // throw new IllegalArgumentException(); // } // this.relevance = rating; // } /** * Returns the type or package signature of the relevant declaration in the * context, or null if none. *

* This field is available for the following kinds of completion proposals: *

* For kinds of completion proposals, this method returns null. * Clients must not modify the array returned. *

* * @return the declaration signature, or null if none * @see Signature */ public char[] getDeclarationSignature() { return this.declarationSignature; } /** * Sets the type or package signature of the relevant declaration in the * context, or null if none. *

* If not set, defaults to none. *

*

* The completion engine creates instances of this class and sets its * properties; this method is not intended to be used by other clients. *

* * @param signature * the type or package signature, or null if none */ // public void setDeclarationSignature(char[] signature) { // this.declarationSignature = signature; // } /** * Returns the simple name of the method, field, member, or variable * relevant in the context, or null if none. *

* This field is available for the following kinds of completion proposals: *

* For kinds of completion proposals, this method returns null. * Clients must not modify the array returned. *

* * @return the keyword, field, method, local variable, or member name, or * null if none */ public char[] getName() { return this.name; } /** * Sets the simple name of the method, field, member, or variable relevant * in the context, or null if none. *

* If not set, defaults to none. *

*

* The completion engine creates instances of this class and sets its * properties; this method is not intended to be used by other clients. *

* * @param name * the keyword, field, method, local variable, or member name, or * null if none */ public void setName(char[] name) { this.name = name; } /** * Returns the signature of the method or type relevant in the context, or * null if none. *

* This field is available for the following kinds of completion proposals: *

* For kinds of completion proposals, this method returns null. * Clients must not modify the array returned. *

* * @return the signature, or null if none * @see Signature */ public char[] getSignature() { return this.signature; } /** * Sets the signature of the method, field type, member type, relevant in * the context, or null if none. *

* If not set, defaults to none. *

*

* The completion engine creates instances of this class and sets its * properties; this method is not intended to be used by other clients. *

* * @param signature * the signature, or null if none */ // public void setSignature(char[] signature) { // this.signature = signature; // } /** * Returns the modifier flags relevant in the context, or * Flags.AccDefault if none. *

* This field is available for the following kinds of completion proposals: *

* For kinds of completion proposals, this method returns * Flags.AccDefault. *

* * @return the modifier flags, or Flags.AccDefault if none * @see Flags */ public int getFlags() { return this.flags; } /** * Sets the modifier flags relevant in the context. *

* If not set, defaults to none. *

*

* The completion engine creates instances of this class and sets its * properties; this method is not intended to be used by other clients. *

* * @param flags * the modifier flags, or Flags.AccDefault if none */ // public void setFlags(int flags) { // this.flags = flags; // } /** * Finds the method parameter names. This information is relevant to method * reference (and method declaration proposals). Returns null * if not available or not relevant. *

* The client must not modify the array returned. *

*

* Note that this is an expensive thing to compute, which may require * parsing Java source files, etc. Use sparingly. *

* * @param monitor * the progress monitor, or null if none * @return the parameter names, or null if none or not * available or not relevant */ // public char[][] findParameterNames(IProgressMonitor monitor) { // if (!this.parameterNamesComputed) { // this.parameterNamesComputed = true; // // TODO (jerome) - Missing implementation // } // return this.parameterNames; // } /** * Sets the method parameter names. This information is relevant to method * reference (and method declaration proposals). *

* The completion engine creates instances of this class and sets its * properties; this method is not intended to be used by other clients. *

* * @param parameterNames * the parameter names, or null if none */ // public void setParameterNames(char[][] parameterNames) { // this.parameterNames = parameterNames; // this.parameterNamesComputed = true; // } }