| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| <html> |
| <body> |
| <h2>Getting Started with GSF</h2> |
| <p> |
| Here's a quick checklist for how to get started writing |
| language support with GSF. |
| </p> |
| <p> |
| <ul> |
| <li> |
| First, you need to write a mime resolver to |
| associate source files of your language with a given |
| mime type. Your language will be associated with this |
| unique mime type. This is described in the |
| <a href="mime-resolver.html">mime resolver document</a>. |
| <br/><br/> |
| </li> |
| <li> |
| Next, you need to write a lexer for your language. |
| This is described in the |
| <a href="lexing.html">lexing document</a>. |
| <br/><br/> |
| </li> |
| <li> |
| Next, you need to write register your lexer with |
| GSF and set up basic GSF registration for your language. |
| This is described in the |
| <a href="registration.html">registration document</a>. |
| At this point, you have basic support for you language - |
| you can recognize and open files in the IDE, and the |
| files are syntax highlighted. |
| <br/><br/> |
| </li> |
| <li> |
| Next, you can create an implementation of the |
| <a href="org/netbeans/modules/gsf/api/KeystrokeHandler.html">KeystrokeHandler</a> |
| and register it with GSF, to support keystroke handling for |
| your language. This is where you can make matching quotes, parentheses |
| etc. happen automatically, as well as implementing return-key handling |
| such that you provide smart-indent, inserting matching tags when you |
| open an if-clause, and so on. |
| <br/><br/> |
| <a href="org/netbeans/modules/gsf/api/Formatter.html">Formatter</a>. |
| This will provide basic indentation/formatting for your language. |
| <br/><br/> |
| </li> |
| <li> |
| At this point, you should be writing unit tests to check your features, |
| for all kinds of corner cases, as well as a guard against regressions |
| as you're improving your code. Unit testing GSF features is trivial; see |
| the <a href="unit-testing.html">unit testing document</a> for more details. |
| <br/><br/> |
| </li> |
| <li> |
| The above features only relied on lexical analysis of your language. |
| The next set of features will require semantic/parse information. |
| To do this, you need to implement a parser for your language by implementing a |
| <a href="org/netbeans/modules/gsf/api/Parser.html">Parser</a>. |
| Your parser will be called at the right times - and this topic |
| is explored in more detail in the |
| <a href="parsing.html">parsing document</a>. |
| <br/><br/> |
| </li> |
| <li> |
| Once you have a parser, you can implement some basic features that require |
| parser information. |
| First, implement the |
| <a href="org/netbeans/modules/gsf/api/StructureScanner.html">StructureScanner</a> |
| interface. This lets you to provide a code outline of the current |
| file in the navigation window, as well as code folding regions in the editor. |
| You basically just need to iterate over your own parse tree, decide which |
| regions should be code folding regions and register them with GSF. Similarly, |
| for navigation, you just need to identify relevant "code elements" from your |
| AST, and then tell GSF about them using logical descriptors like |
| "method", "attribute", "tag", etc. |
| <br/><br/> |
| </li> |
| <li> |
| Next, you can add some other related features which rely on your parsing result: |
| <a href="org/netbeans/modules/gsf/api/SemanticAnalyzer.html">SemanticAnalyzer</a>, |
| <a href="org/netbeans/modules/gsf/api/OccurrencesFinder.html">OccurrencesFinder</a>, and |
| <a href="org/netbeans/modules/gsf/api/InstantRenamer.html">InstantRenamer</a>. |
| These features let you provide semantic highlighting (e.g. highlighting unused |
| variables, method declarations, etc), mark occurrences, and instant rename - refactoring |
| for things like local variables and parameters which doesn't require full blown |
| multi-file refactoring. |
| <br/><br/> |
| </li> |
| <li> |
| If you are developing support for a language which can be embedded in other |
| languages (such as JavaScript, which is embedded in HTML files etc., or Ruby, |
| which is embedded in ERb files), you need to handle the embedding aspects |
| of languages. At the syntactic level, this is handled completely by the |
| embedding language support. But at the parse level, it will require coordination |
| as well as careful use of offset translation methods; you should never assume |
| that your AST node offsets correspond to the offsets in the document. |
| This is described in more detail in the <a href="embedding.html">embedding document</a>. |
| </li> |
| <li> |
| Now you are finally ready to attack the "hardest" features: Code Completion, |
| Go To Declaration, and other features that require multifile analysis. |
| To do this, you need to have a persistent store such that you can quickly |
| query and find information across files and libraries. To do this, you need |
| to implement an indexer. The indexer is called by the infrastructure when needed, |
| and lets you extract information from parse results and store them into an index. |
| This is all explained in greater detail in the <a href="indexer.html">indexing document</a>. |
| You will also need to tell GSF how the user's project related to source code, |
| such that multifile analysis can be properly scoped. This part is described in |
| the <a href="classpath.html">classpath document</a>. |
| <br/><br/> |
| </li> |
| <li> |
| With the index in place, you can now implement code completion using the |
| <a href="org/netbeans/modules/gsf/api/CodeCompletionHandler.html">CodeCompletionHandler</a> |
| interface. Here, you will most likely draw on everything you have built up to |
| this point. Lexical analysis, to for example determine if you're in a string or |
| a comment (where different completion alternatives present themselves), then the |
| parser AST to determine things like local variables, and finally the index to |
| determine other functions and classes in the project. Code completion also typically |
| involves attempting to analyze code which is broken (because you're in the middle |
| of typing an expression) so error recovery as discussed in the |
| <a href="parsing.html">parsing document</a> will also need to be perfected. |
| <br/><br/> |
| You can also implement Go To Declaration at this point, by implementing the |
| <a href="org/netbeans/modules/gsf/api/DeclarationFinder.html">DeclarationFinder</a> |
| interface and registering it with GSF. |
| <br/><br/> |
| I hope to write a more detailed document with information on how to write code |
| completion soon. |
| <br/><br/> |
| </li> |
| <li> |
| At some point, you should consider adding incremental updating support, |
| such as incremental parsing. This is described in detail in the |
| <a href="incremental-parsing.html">incremental parsing</a> document. |
| </li> |
| </ul> |
| </p> |
| <br/> |
| <span style="color: #cccccc">Tor Norbye <tor@netbeans.org></span> |
| </body> |
| </html> |