|
org.netbeans.modules.parsing.api/1 1.26.0 2 | |||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||
See:
Description
| Parsing API | |
|---|---|
| org.netbeans.modules.parsing.api | Support for calling of high priority parser based user tasks in multi language environment. |
| org.netbeans.modules.parsing.api.indexing | |
| org.netbeans.modules.parsing.spi | Supports registration and automatic scheduling of various parser based tasks. |
| org.netbeans.modules.parsing.spi.indexing | |
| org.netbeans.modules.parsing.spi.indexing.support | |
Parsing API defines contract between parsers registerred for diferent languages and the rest of IDE. It is language neutral and it supports language embeddings.
The basic Parsing API constructs are Source, Snapshot and Embedding. Source identificates some concrete file or document. There is always at most one Source for one FileObject. Snapshot represents some concrete content of Source, and it is immutable. And Embedding represents some part of Snapshot written in different language. Embedding can contain some virtual code that is not contained in outside language too. Content of Embedding is represented by Snapshot and it can contain another Embeddings, so embeddings are recursive.
Parser is represented by abstract class called
Parser.
The only way how to register a new parser for some concrete mime type
is to implement
ParserFactory,
and register it in your manifest file in folder called
"Editors/" + mimeType. A new instance of Parser is always
created for some concrete Snapshot, or collection of Snapshots. One
instance of parser can be reused for more Snapshots created from the same
Source. Result of parsing (AST, syntax errors, semantic information) is
represented by
Parser.Result
class. Parser creates a new instance of Parser.Result for each Task.
Following example shows how to integrate parser to the NetBeans using
Parsing API:
class FooParserFactory extends ParserFactory {
public Parser createParser (
Collection<Snapshot> snapshots
) {
return new FooParser ();
}
private static class FooParser extends Parser {
private boolean cancelled = false;
private AST ast;
public void parse (
Snapshot snapshot,
Task task,
SchedulerEvent event
) throws ParseException {
cancelled = false;
for (...) {
// parsing snapshot.getText ();
if (cancelled) return;
}
ast = ...;
}
public abstract Result getResult (
Task task,
SchedulerEvent event
) throws ParseException {
return new FooResult (ast);
}
public void cancel () {
cancelled = true;
}
public void addChangeListener (
ChangeListener changeListener
) {
}
public void removeChangeListener (
ChangeListener changeListener
) {
}
}
public static class FooResult extends Result {
private AST ast;
private boolean valid = true;
FooResult (
AST ast
) {
this.ast = ast;
}
public AST getAST () {
if (!valid) throw new InvalidResultException ();
return ast;
}
public void invalidate () {
valid = false;
ast = null;
}
}
}
Parsing API defines two basic kinds of Tasks. High priority UserTasks and SchedulerTasks.
Execution of UserTask is synchnonous and it stops execution of all other tasks. There are two types of UserTask. Simple UserTask that supports some computations based on one block code written in one language. And MultiLanguageUserTask (???) that supports scanning of all blocks of code written in different languages embedded in one Source.
User of Parsing API can register various implementations of SchedulerTask for any language. Each SchedulerTask is registered for some specific Scheduler. Scheduler defines when task shoud be started (for example when current editor is changed, when some nodes are selected in Project View, or when cursor position is changed).
There are two specific tasks that can define language embedding. So task implementator can recognize blocks of embedded languages. Parsing API contains support for high priority ParsingAPI
Added IndexingManager.refreshAllIndices(boolean fullRescan, boolean wait, File... filesOrFolders),
<T> T IndexingManager.runProtected(Callable<T> operation)
Added refreshAllIndices(boolean fullRescan, boolean wait, FileObject... folders).
Added methods IndexingSupport.createDocument(FileObject) and IndexResult.getIndexable()
in order to allow CustomIndexers and BinaryIndexers to use
IndexingSupport.
Added a method for checking an index validity. The method should be called by IndexerFactories to check the index integrity and prevent exceptions during the run on the IDE when the index is broken (for example the IDE was killed during write to the index).
Added scanStarted and scanFinished methods for notifying indexers about start and finish of the indexing of given root. Refactored EmbeddingIndexerFactory and CustomIndexerFactory to move up common methods into super class SourceIndexerFactory.
|
The sources for the module are in the NetBeans Mercurial repositories.
XXX no answer for deploy-dependencies
Read more about the implementation in the answers to architecture questions.
|
org.netbeans.modules.parsing.api/1 1.26.0 2 | |||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||