/******************************************************************************* * 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 org.eclipse.core.runtime.IProgressMonitor; import net.sourceforge.phpdt.core.compiler.CharOperation; /** * 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: *
"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: *
"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: *
"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: *
"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: *
"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: *
"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: *
"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: *
"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: *
* The following additional context information is available * for this kind of completion proposal at little extra cost: *
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 *offset
parameter 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, ornull
if none.
* * This field is available for the following kinds of * completion proposals: *
ANONYMOUS_CLASS_DECLARATION
- type signature
* of the type that is being subclassed or implementedFIELD_REF
- type signature
* of the type that declares the field that is referencedMETHOD_REF
- type signature
* of the type that declares the method that is referencedMETHOD_DECLARATION
- type signature
* of the type that declares the method that is being
* implemented or overriddenPACKAGE_REF
- dot-based package
* signature of the package that is referencedTYPE_REF
- dot-based package
* signature of the package containing the type that is referencednull
. 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: *
FIELD_REF
- the name of the fieldKEYWORD
- the keywordLABEL_REF
- the name of the labelLOCAL_VARIABLE_REF
- the name of the local variableMETHOD_REF
- the name of the methodMETHOD_DECLARATION
- the name of the methodVARIABLE_DECLARATION
- the name of the variablenull
. 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, ornull
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: *
ANONYMOUS_CLASS_DECLARATION
- method signature
* of the constructor that is being invokedFIELD_REF
- the type signature
* of the referenced field's typeLOCAL_VARIABLE_REF
- the type signature
* of the referenced local variable's typeMETHOD_REF
- method signature
* of the method that is referencedMETHOD_DECLARATION
- method signature
* of the method that is being implemented or overriddenTYPE_REF
- type signature
* of the type that is referencedVARIABLE_DECLARATION
- the type signature
* of the type of the variable being declarednull
. 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, ornull
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: *
ANONYMOUS_CLASS_DECLARATION
- modifier flags
* of the constructor that is referencedFIELD_REF
- modifier flags
* of the field that is referenced;
* Flags.AccEnum
can be used to recognize
* references to enum constants
* KEYWORD
- modifier flag
* corrresponding to the modifier keywordLOCAL_VARIABLE_REF
- modifier flags
* of the local variable that is referencedMETHOD_REF
- modifier flags
* of the method that is referenced;
* Flags.AccAnnotation
can be used to recognize
* references to annotation type members
* METHOD_DECLARATION
- modifier flags
* for the method that is being implemented or overriddenTYPE_REF
- modifier flags
* of the type that is referenced; Flags.AccInterface
* can be used to recognize references to interfaces,
* Flags.AccEnum
enum types,
* and Flags.AccAnnotation
annotation types
* VARIABLE_DECLARATION
- modifier flags
* for the variable being declaredFlags.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, ornull
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, ornull
if none
*/
public void setParameterNames(char[][] parameterNames) {
this.parameterNames = parameterNames;
this.parameterNamesComputed = true;
}
}