001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041: package org.netbeans.modules.gsf.api;
042:
043: import java.util.List;
044: import java.util.Map;
045: import java.util.Set;
046: import javax.swing.text.JTextComponent;
047:
048: import org.netbeans.modules.gsf.api.annotations.CheckForNull;
049: import org.netbeans.modules.gsf.api.annotations.NonNull;
050:
051: /**
052: * Provide code completion for this language. This implementation
053: * is responsible for all the analysis around the given caret offset.
054: * A code completion provider should be smart and for example limit
055: * alternatives not just by the given identifier prefix at the caret offset,
056: * but also by the surrounding context; for example, if we're doing
057: * code completion inside an expression that is part of a {@code return}
058: * statement, the types should be limited by the return type of the current
059: * method, and so on.
060: *
061: * A default SPI implementation is available that will perform some of this
062: * analysis assuming it's applied to a parse tree using the other SPI default
063: * implementation classes.
064: *
065: * @todo Rename me to CodeCompletion or CompletionProvider or Completer or something like that
066: * @todo Instead of passing in caseSensitive, should I pass in a Comparator which should be used
067: * for determining eligibility? That way it's completely insulated from the clients
068: * @todo Pass in completion mode such that I can do different stuff for smart-completion
069: *
070: * @author Tor Norbye
071: */
072: public interface Completable {
073: enum QueryType {
074: COMPLETION, DOCUMENTATION, TOOLTIP, ALL_COMPLETION, NONE, STOP
075: }
076:
077: List<CompletionProposal> complete(@NonNull
078: CompilationInfo info, int caretOffset, String prefix, @NonNull
079: NameKind kind, @NonNull
080: QueryType queryType, boolean caseSensitive, @NonNull
081: HtmlFormatter formatter);
082:
083: /**
084: * Return the HTML documentation for the given program element (returned in CompletionProposals
085: * by the complete method)
086: */
087: String document(@NonNull
088: CompilationInfo info, @NonNull
089: ElementHandle element);
090:
091: /**
092: * Resolve a link that was written into the HTML returned by {@link #document}.
093: *
094: * @param link The link, which can be in any format chosen by the {@link #document} method.
095: * However, links starting with www or standard URL format (http://, etc.)
096: * will automatically be handled by the browser, so avoid this format.
097: * @param originalHandle The handle to the documentation item where the link was generated.
098: * @return An ElementHandle that will be passed in to {@link #document} to
099: * compute the new documentation to be warped to.
100: */
101: @CheckForNull
102: ElementHandle resolveLink(@NonNull
103: String link, ElementHandle originalHandle);
104:
105: /**
106: * Compute the prefix to be used for completion at the given caretOffset
107: * @param info The compilation info with parse tree info etc.
108: * @param caretOffset The caret offset where completion was requested
109: * @param upToOffset If true, provide a prefix only up to the caretOffset. Otherwise,
110: * compute the entire completion symbol under the caret. (The former is used
111: * to bring up a set of completion alternatives, whereas the latter is used
112: * to for example bring up the documentation under the symbol.)
113: */
114: String getPrefix(@NonNull
115: CompilationInfo info, int caretOffset, boolean upToOffset);
116:
117: /**
118: * Consider a keystroke and decide whether it should automatically invoke some type
119: * of completion. If so, return the desired type, otherwise return QueryType.NONE.
120: * @return A QueryType if automatic completion should be initiated, or {@link QueryType.NONE}
121: * if it should be left alon, or {@link QueryType.STOP} if completion should be terminated
122: */
123: QueryType getAutoQuery(@NonNull
124: JTextComponent component, String typedText);
125:
126: // TODO:
127: // processKey action stuff from GsfCompletionItem to handle "(", "." etc.
128:
129: /**
130: * Perform code template parameter evaluation for use in code template completion
131: * or editing. The actual set of parameters defined by the language plugins
132: * is not defined and will be language specific. Return null if the variable
133: * is not known or supported.
134: *
135: * @todo This may need a better home than the Code Completion interface;
136: * while templates are used in template code completion it's unrelated to
137: * the regular Ruby code completion.
138: */
139: String resolveTemplateVariable(String variable, @NonNull
140: CompilationInfo info, int caretOffset, @NonNull
141: String name, Map parameters);
142:
143: /**
144: * Compute the set of applicable templates for a given text selection
145: */
146: Set<String> getApplicableTemplates(@NonNull
147: CompilationInfo info, int selectionBegin, int selectionEnd);
148:
149: /**
150: * Compute parameter info for the given offset - parameters surrounding the given
151: * offset, which particular parameter in that list we're currently on, and so on.
152: * @param info The compilation info to pick an AST from
153: * @param caretOFfset The caret offset for the completion request
154: * @param proposal May be null, but if not, provide the specific completion proposal
155: * that the parameter list is requested for
156: */
157: ParameterInfo parameters(@NonNull
158: CompilationInfo info, int caretOffset, CompletionProposal proposal);
159: }
|