ide/csl.api/doc/getting-started.html - netbeans - Git at Google

 <!--

     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 &lt;tor@netbeans.org&gt;</span>
     </body>
 </html>
	<!--

	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>