GSF - Generic Scripting Framework
David Strupl 9.3.2009: GSF work towards stable APIs has been replaced by ParsingAPI.
GSF versus Schliemann
Schliemann is an infrastructure in NetBeans for easily adding editing support for new languages. That may sound identical to GSF... so why is there two, and which one should you choose?
Schliemann makes adding a new language trivial. All you have to do is write a "config" file, called an NBS file, which just describes your language at a high level - patterns for recognizing comments, keywords, and so on - and the syntax highlighting is provided automatically. If you provide some grammar rules, the IDE will also parse your code and add error highlights, populate the navigator, etc. This is pretty similar to how Emacs, Vim and other editors add support for hundreds of languages. Writing a config file is easy and fast.
However, this can get you only so far. If you want to write very strong editing support for your language, you can't easily express refactoring, deep code completion, parser error recovery etc. in a config file. (Schliemann does have hooks which let you write custom code for a lot of these things, but once you do things may get trickier since you start depending on the abstract tree nodes and parse tree structure from Schliemann's parser implementation).
This is where GSF comes in. GSF requires a high level of investment on your part: -YOU- have to supply the lexer and the parser for the language. You also need to implement the logic which for example extract navigation items from your parse tree, or the logic which produces code completion items from your parse trees. However, the philosophy here is that you are writing language support for some language you already have a parser/lexer for (for example, JRuby in the case of Ruby, Jython in the case of Python, and so on). And the key part about GSF is that it takes care of the IDE side for you. You focus on your language, your parser, your lexer, and the feature implementations driven off of those data structures. For example, let's say you hook up JRuby as your Ruby parser. GSF will call the parser at the right times (e.g. during startup indexing, when a file is first opened, after a few seconds of idle activity, or synchronously when the user is asking for parse information during code completion right after editing the file). You are asked at the right times to extract for example navigation items and handed back your parse tree. All you have to do is skim through your parse tree and pick out for example your class and methods AST nodes, and tell IDE where they are located. The UI code for the navigator etc. is taken care of by GSF.
Generic -Scripting- Framework?
What if my language isn't a scripting language? Is GSF for me? And why is Ruby using GSF, Ruby isn't a "scripting" language?
The name is mostly historic; GSF is used for HTML today :) Early on I was trying to scope GSF a bit down, since trying to support ALL langauges meant making everything very generic. To take an example, there's an ElementKind enumeration in the interface which lists common types of things in the language -- classes, modules, packages, methods, functions, and so on. Having these things in the API means that GSF is targeting a certain class of languages. This makes some things a lot easier; GSF knows a lot about the UI for this and automatically supplies the right kinds of icons during code completion or in code outline views, and so on.
I'd still like to keep GSF practical such that it gives a lot of help to common languages we're trying to address, but I'd also like to make it flexible enough to accommodate a wide range of languages. This will be part of the API-work going into the next release.
GSF is included in NetBeans 6.0 and 6.1. However, it does NOT have a public API. The APIs are not final yet and not only are they subject to change, they WILL change. This means that if you want to use GSF you have to be willing to put up with incompatible changes. (You can be notified of these by asking to be added to the email@example.com alias). One of my top priorities for the next release (once 6.1 is wrapped up) is to work on formalizing the APIs such that we can "freeze" and support the APIs.
New: There is a lot of documentation on GSF now as part of the javadoc build for the gsf.api module. No, it's not just class and method references, there are separate documents which give an overview of GSF, explanations of the lexer, parser and indexing roles, and so on. Run ant javadoc in gsf.api to view the documentation; most documents are linked from the main index.html.
Caoyuan has started a blog series on how to develop a GSF-based editor. The first installment is here.
- Caoyuan Deng has developed several GSF-based editors and his blog is here.
- Martin Adamek and Matthias Schmidth have been working on GSF-based Groovy support and their blogs are
First, see the documentation listed in the Getting Started section above.
GSF started as part of the Ruby work (and shipped with the Ruby cluster in 6.0) so more information about it (especially how to build etc.) can be found in the Ruby pages. For now, you can also raise GSF-related issues on firstname.lastname@example.org but for the next release I'll be looking at finding a separate home for GSF.
Issues that need to be resolved are listed in the GsfIssues document.