1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
<!--
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>
|
