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;
042:
043: import javax.swing.Action;
044: import org.netbeans.modules.gsf.api.*;
045: import org.netbeans.modules.gsf.api.Completable;
046: import org.netbeans.modules.gsf.api.DeclarationFinder;
047: import org.netbeans.modules.gsf.api.InstantRenamer;
048: import org.netbeans.modules.gsf.api.Parser;
049: import org.netbeans.modules.gsf.api.GsfLanguage;
050: import org.netbeans.modules.gsf.api.annotations.CheckForNull;
051: import org.netbeans.modules.gsf.api.annotations.NonNull;
052: import org.netbeans.modules.gsf.api.BracketCompletion;
053: import org.netbeans.modules.gsf.api.Formatter;
054: import org.netbeans.modules.gsf.api.Indexer;
055: import org.netbeans.modules.gsf.api.StructureScanner; //import org.netbeans.spi.palette.PaletteController;
056: import org.netbeans.modules.gsfret.editor.semantic.ColoringManager;
057:
058: /**
059: * @todo Should languages get to declared "priorities"? In case there are
060: * overlaps in extensions that is.
061: * @todo Can I devise a way where one language can "extend" another?
062: * For example, the Jackpot Rule language should simply be the Java language
063: * with a couple of simple changes.
064: * @todo Add LanguageVersion list property. For example, for Java, they could be
065: * JDK 1.4, 5.0, 6.0. This would be exposed as a property somewhere (perhaps
066: * on a project basis) and would be used by plugins to drive parser specific
067: * info. Similarly for JavaScript I have multiple language versions - 1.0 through 1.6
068: * in the case of Rhino (corresponding to different JavaScript/EcmaScript versions).
069: *
070: * @author <a href="mailto:tor.norbye@sun.com">Tor Norbye</a>
071: */
072: public interface Language {
073:
074: /**
075: * HACK: Some language supports may want to use their own editor kit
076: * implementation (such as Schliemann) for some services. By returning
077: * true here (which can be done by registering "useCustomEditorKit" on the
078: * GsfPlugin folder for the mime type) GSF will not register its own editing
079: * services for this mime type.
080: * <p>
081: * If you set this flag, you may need to register additional services on your
082: * own. For example, if you still want GSF "Go To Declaration" functionality,
083: * you need to register the GsfHyperlinkProvider.
084: * The ruby/rhtml/ module provides an example of this.
085: * <p>
086: * NOTE: Code folding doesn't work until you enable code folding for your
087: * editor kit; see GsfEditorKitFactory's reference to CODE_FOLDING_ENABLE for
088: * an example.
089: */
090: boolean useCustomEditorKit();
091:
092: /** Return the display-name (user visible, and localized) name of this language.
093: * It should be brief (one or two words). For example "Java", "C++", "Groovy",
094: * "Visual Basic", etc.
095: */
096: @NonNull
097: String getDisplayName();
098:
099: /** Return the mime-type of this language. For example text/x-java.
100: */
101: @NonNull
102: String getMimeType();
103:
104: /** Return the set of common file extensions used for source files in this
105: * type of language. It should not include the dot.
106: * For example, for Java it would be { "java" }. For C++ it might
107: * be { "cpp", "cc", "c++", "cxx" }. The first item in the array will be
108: * considered the "primary" extension that will be used when creating new
109: * files etc.
110: */
111: String[] getExtensions();
112:
113: /** Return a scanner (lexical analyzer, tokenizer) for use with this language.
114: * @todo Clarify whether clients should cache instances of this or if it will
115: * be called only once and management done by the IDE
116: */
117: @CheckForNull
118: GsfLanguage getGsfLanguage();
119:
120: /** Return a parser for use with this language. A parser is optional (in which
121: * case getParser() may return null) but in that case a lot of functionality
122: * will be disabled for this language.
123: * @todo Clarify whether clients should cache instances of this or if it will
124: * be called only once and management done by the IDE
125: */
126: @CheckForNull
127: Parser getParser();
128:
129: /** Return Actions that will be provided in the editor context menu for this language.
130: */
131: Action[] getEditorActions();
132:
133: /** Return an icon to be used for files of this language type.
134: * @see org.openide.util.Utilities#loadImage
135: */
136:
137: //public Image getIcon();
138: /** Hmmmm this is a bit rough. The path would have to be relative to some resource...
139: * I guess it would be relative to the specific plugin language class?
140: * Example: "com/foo/bar/javascript.gif"
141: * @todo More documentation here, or revise API entirely
142: */
143: String getIconBase();
144:
145: /**
146: * Get a code completion handler, if any
147: */
148: @CheckForNull
149: Completable getCompletionProvider();
150:
151: /**
152: * Get a rename helper, if any, for instant renaming
153: */
154: @CheckForNull
155: InstantRenamer getInstantRenamer();
156:
157: /**
158: * Get a Declaration finder, if any, for resolving declarations for a given identifier
159: */
160: @CheckForNull
161: DeclarationFinder getDeclarationFinder();
162:
163: /**
164: * Get an Formatter, if any, for helping indent and reformat code
165: */
166: @CheckForNull
167: Formatter getFormatter();
168:
169: /**
170: * Get a BracketCompletion helper, if any, for helping with bracket completion
171: */
172: @CheckForNull
173: BracketCompletion getBracketCompletion();
174:
175: /**
176: * Get an associated palette controller, if any
177: */
178: /*
179: @CheckForNull
180: PaletteController getPalette();
181: */
182:
183: /**
184: * Get an associated indexer, if any
185: */
186: @CheckForNull
187: Indexer getIndexer();
188:
189: /**
190: * Get an associated hints provider, if any
191: */
192: @CheckForNull
193: HintsProvider getHintsProvider();
194:
195: /**
196: * Get a structure scanner which produces navigation/outline contents
197: */
198: @CheckForNull
199: StructureScanner getStructure();
200:
201: /**
202: * Return the coloring manager for this language
203: */
204: @NonNull
205: ColoringManager getColoringManager();
206:
207: /**
208: * Return the semantic analyzer for this language
209: */
210: @NonNull
211: SemanticAnalyzer getSemanticAnalyzer();
212:
213: /**
214: * Return the occurrences finder for this language
215: */
216: @NonNull
217: OccurrencesFinder getOccurrencesFinder();
218:
219: }
|