Advanced Source Code Editor for the SIT Language

}w
!"#$%&'()+,-./012345<yA|
M ASARYK U NIVERSITY
FACULTY OF I NFORMATICS
Advanced Source Code Editor
for the SIT Language
B ACHELOR ’ S THESIS
Andrej Podhradský
Brno, 2008
Declaration
Hereby I declare, that this paper is my original authorial work, which I have worked out by
my own. All sources, references and literature used or excerpted during elaboration of this
work are properly cited and listed in complete reference to the due source.
Advisor: RNDr. Vojtěch Řehák, Ph.D.
ii
Abstract
The main goals of this bachelor’s thesis are describing ways how to extend Eclipse IDE with
a view to text editors and creating an editor for the SIT (Siemens IP Test) language, which is
used for testing application protocols above the Internet Protocol.
iii
Keywords
Eclipse, plug-in, JFace, code editor, SIT
iv
Contents
1 Introduction . . . . . . . . . . . . . .
2 Eclipse . . . . . . . . . . . . . . . . .
2.1 What is Eclipse . . . . . . . . .
2.2 Eclipse architecture . . . . . . .
3 Eclipse extending . . . . . . . . . . .
3.1 Developing a plug-in . . . . . .
3.2 Plug-in installing . . . . . . . .
3.3 Workspace resources . . . . . .
3.4 Building text editors . . . . . .
3.4.1 TextEditor class . . . . .
3.4.2 Partitioning . . . . . . .
3.5 Editor features . . . . . . . . . .
3.5.1 Syntax highlighting . . .
3.5.2 Content assistant . . . .
3.5.3 Text hover . . . . . . . .
3.5.4 Resource markers . . . .
3.5.5 Code folding . . . . . .
4 SIT editor . . . . . . . . . . . . . . .
4.1 SIT language . . . . . . . . . . .
4.2 SIT editor installing and setting
4.3 Capabalities . . . . . . . . . . .
4.4 Implementation . . . . . . . . .
4.4.1 SIT partitioning . . . . .
4.4.2 Syntax highlighting . . .
4.4.3 Code completion . . . .
4.4.4 Hover help . . . . . . .
4.4.5 Syntax checking . . . . .
4.4.6 Code folding . . . . . .
5 Conclusion . . . . . . . . . . . . . . .
Bibliography . . . . . . . . . . . . . . . .
A CD content . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
3
3
3
5
5
7
8
10
12
12
14
14
15
16
17
18
21
21
21
23
25
25
26
26
28
28
29
31
32
33
v
Chapter 1
Introduction
The ANF DATA (daughter company of Siemens AG Österreich) within the scope of an applied research develops modern tools for special languages that are used in the Siemens
corporation. A part of this developing is creating an advanced source code editor for the SIT
language.
Source code editor is a text editor designed for writing and editing source code by programmers. Unlike the simple text editor, the source code editor provides features that will
simplify and speed up programming such as syntax highlighting, code completion or hover
help. It can also provides tools for compiling, interpreting or debugging a code. The source
code editor can be a standalone application or a part of an integrated development environment (IDE).
We choose the Eclipse as an IDE for developing the SIT editor. Eclipse IDE has open
source code and it is primary designed for extending. It provides special frameworks that
allow us to customize development environment in agreement with our requests. Another
reason for choosing Eclipse is its platform independence. Eclipse extending is done by adding
plug-ins, so we will create an editor plug-in for the SIT language. The SIT editor will include
features as follows:
•
syntax highlighting
highlight keywords to improve document readibility
•
code completion
complete words or show a pop-up window with proposals to speed up programming
•
text hover
show additional information over the text
•
syntax checking
check the syntax and mark eventual errors
•
code folding
hide parts of code for better readability
1
1. I NTRODUCTION
This bachelor’s thesis is divided into three chapters. The first one is about Eclipse and its
architecture. The second one describes Eclipse extending with a view to building text editors. We will describe how to develop plug-ins, how to build custom text editors and how to
implement particular editor features in general. Note that Eclipse extending supposes skills
in Java programming. With this knowledge we create the SIT editor, the own implementation of which is described in the Chapter 4, “SIT editor”. This chapter also decribes basic SIT
language characteristics essential for building the SIT editor.
2
Chapter 2
Eclipse
2.1
What is Eclipse
Eclipse [1] is an open source community that is interested in building an extensible platform, runtimes and application frameworks used in development of various software applications. The Eclipse community has several open source projects, but we will concentrate
only on the Eclipse Project, which comprises Eclipse Standard Development Toolkit (Eclipse
SDK). Eclipse is offered under the Common Public License (CPL), which is compliant with
the Open Source Initiative (OSI). This license is also designed to allow commercial interests.
Note that some components in an Eclipse release are not actually part of Eclipse and are
not governed by the CPL. They can be governed by other license agreements. Eclipse SDK
distribution is available from eclipse.org download site 1 . The latest version of Eclipse SDK
is 3.3.2. To run Eclipse is required Java Runtime Environment (JRE), Java 5 JRE or higher is
recommended, available from http://java.sun.com/javase/downloads/.
2.2
Eclipse architecture
As we mentioned, we will target only the Eclipse Project. The Eclipse project [6] as the whole
is generally divided into three subprojects:
•
The Eclipse platform itself, which forms the backbone of the whole application
•
The Java Development Toolkit (JDT) is used for developing, running and debugging
Java code
•
The plug-in development environment (PDE), which enables developing own tools
for Eclipse (plug-ins)
The JDT and PDE are plug-in tools for the Eclipse Platform. Together, these three pieces form
the Eclipse SDK. Other Eclipse subprojects are Equinox (an OSGi 2 framework) and Eclipse
Project Incubator. Each of subprojects are themselves divided into other subprojects. As you
can see, the main part of Eclipse Project is Eclipse Platfom. The Eclipse platform consists of
a several components:
1. http://www.eclipse.org/downloads/
2. Open Services Gateway initiative is an open standards organization
3
2.2. ECLIPSE ARCHITECTURE
•
Runtime
The Runtime or kernel’s task is to get everything started and to load all needed plugins. Except for the kernel, everything else is implemented as a plug-in.
•
Workspace
The workspace manages the user’s resources such as projects, folders and files.
•
Workbench
The workbench is graphical user interface, which is built using Eclipse’s own Standard
Widget Toolkit (SWT 3 ) and JFace (built on top of SWT).
Figure 2.1: Overview of the Eclipse architecture: taken from [7]
3. SWT is a low-level graphical and portable widget toolkit built upon the native operating system controls
4
Chapter 3
Eclipse extending
The main goal of this chapter is to describe extending the Eclipse and how to create custom
plug-in. We can create and customize our own views, dialogs, wizards, actions, help contents, perspectives and many other features, but this is outside the purpose of this thesis.
We will target especially building text editors and describing other parts of Eclipse that are
relevant to the text editor. Note that from this chapter we will use the term Eclipse as the
Eclipse SDK.
3.1
Developing a plug-in
The Eclipse Platform is primarily designed for extending its basic functionality and creating
new features. Eclipse as an powerful extensible IDE offers its own tools and frameworks
for extending. This is done by creating own plug-in including Java classes, which extend
Eclipse’s classes.
The Eclipse provides a plug-in development environment (PDE) for developing Eclipse
plug-ins, which is also a plug-in. It is a part of Eclipse SDK. PDE includes some plug-in
templates available from File > new > Project> Plug-in Development > Plug-in Project.
There can be found plug-in templates such as plug-in with an editor, a view or a simple
Hello World plug-in. To run a plug-in for testing, we do not have to repeatedly install it, just
execute it by Run > Run As > Eclipse application and Eclipse will start new Workbench
window with all plug-ins inside the workspace. The headstone of each plug-in is the XML
file plugin.xml (plug-in descriptor) as is shown in Example 3.1.1.
The plugin.xml is located in the root of the plug-in’s directory and is divided into
sections, beginning with element <plugin>, the main attributes of which are described in
the Table 3.1.
Plug-in often needs access to other plug-ins such as org.eclipse.core.runtime.
These dependent plug-ins must be declared in the section <requires>. Note that <plugin>
attributes and dependent plug-ins can be defined in the file MANIFEST.MF ( Example 3.1.2)
located in the directory META-INF.
The last eclipse plug-in description file build.properties is used for setting paths.
Fortunately, Eclipse has a Plug-in Manifest Editor that manages all these description files
and allows us to edit plug-in descriptors in an easier way. The next section <extension>
indicates the extension point used by the plug-in. The extension point is an identifier of some
part of Eclipse platform or even another plug-in, which the plug-in will contribute to, e.g.
5
3.1. DEVELOPING A PLUG-IN
1
2
3
4
5
6
7
8
9
11
12
13
14
15
16
17
18
19
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>
<plugin
id="cz.muni.fi.xpodhr.example"
name="My Plugin"
version="3.0.0"
class="cz.muni.fi.xpodhr.example.MyPlugin">
<requires>
<import plugin="org.eclipse.core.runtime"/>
<import plugin="org.eclipse.ui"/>
...
</requires>
<extension point="...">
...
</extension>
</plugin>
Example 3.1.1: Example of plugin.xml
Attribute
id
name
version
class (optional)
Purpose
defines a programmatic reference to the plug-in itself, Java
package naming convention recommended
is a label shown in some dialogs
current version of the plug-in
defines the Java class that will be notified of life cycle events
such as startup and shutdown once your plug-in is activated
Table 3.1: Attributes of the <plugin> element
org.eclipse.ui.editors. The whole list of Eclipse Platform Extension Points can be
found at http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.
platform.doc.isv/reference/extension-points/index.html.
Actually everything in Eclipse except kernel is a plug-in and in this way we are able to
extend and create new features in agreement with our ideas and requests. In Help > About
Eclipse SDK > Plug-in Details we can see all installed plug-ins. For managing plug-ins
such as disabling or uninstalling, Eclipse offers us a Configuration Manager. This manager
is available from Help > Software Updates > Manage Configuration. Note that any change
made in Configuration Manager takes effect after restarting the Eclipse.
6
3.2. PLUG-IN INSTALLING
1
2
3
4
5
6
7
8
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: My Plugin
Bundle-SymbolicName: MyPlugin; singleton:=true
Bundle-Version: 3.0.0
Require-Bundle: org.eclipse.core.runtime,
org.eclipse.ui,
...
Example 3.1.2: MANIFEST.MF example
3.2
Plug-in installing
As we mentioned, we can get a plug-in work by running new Eclipse Workbench from the
active one. To get our plug-in work immediately after Eclipse starts, we must create some
installation file and then install it. There are two ways how to install a plug-in.
•
Creating plug-in JAR files and copying them into the directory plugins
•
Using the install manager
Installing by copying JAR files
In the first way, we have to export our plug-in project into a JAR file by File > Export..
> Plug-in Development > Deployable plug-ins and fragments. Then we check particular
plug-in projects for exporting and define the destination directory where the projects export.
After creating JAR files, we just copy these files into <inst_dir>\eclipse\plugins,
where <inst_dir> is the directory of Eclipse installation. To get plug-ins work we must
restart Eclipse. Eclipse always at start up looks here for loading plug-ins; it is especially
looking for plugin.xml files.
Installing using a manager
The second way of installing a plug-in is using the update sites. The advantage of this
way is that using the Configuration Manager we can better manage plug-ins, such as disabling and uninstalling the plug-in or we can view installation history. It also allows us to
choose a plug-in installlation from either a local or a remote place.
At first, we must create Feature Project that maintains the plug-in projects and information about them. Next, we create Update Site Project that includes features. The whole
procedure is as follows:
1. File > New > Project > Plug-in Development > Feature Project
2. Type the name and choose projects for adding to this feature project
3. File > New > Project > Plug-in Development > Update Site Project
7
3.3. WORKSPACE RESOURCES
4. Finally, in the file site.xml add feature projects and build them
We can store the created Update Site Project with features on local or remote place. Installing
using update site is as follows:
1. Help > Software Updates > Find and install..
2. Check Search for new features to install and click next
3. Choose update sites from the menu, if the menu does not include the update site, add
it by clicking on New Remote/Local Site.. and click finish
4. The rest is the same as an ordinary installation of any software.
3.3
Workspace resources
In this section we will discuss resource model in Eclipse [5] and how Eclipse works with
these resources. For this purpose, Eclipse uses resource framework that is implemented by
the org.eclipse.core.resources. The ground part of the resource model is workspace,
which is a logical container of resources. In general, plug-ins have an acces to the resources
only inside the workspace. Although new Eclipse version 3.3 brings us new Eclipse File
System (EFS) that has a partial solution of this problem, there are still some problems. The
resource model is divided into a physical and a logical view. Eclipse uses workspace API for
working with the resources and their underlying capabilities of the resource model.
Physical view
In fact, the workspace is only a directory in the file system, but unlike a directory, it
contains the directory .metadata for storing private data. Eclipse can work with exactly
one workspace that can include four resource types:
•
Workspace root
There is excatly one root directory of a workspace, that always exists, can not be moved
or copied and is always local.
•
Project
It is similar to a folder, but project is a part of a workspace and contains the file .
project that maintains information about the project. This file is created by the resource framework org.eclipse.core.resources and it is readonly.
•
Folder
Folder is a container of files and other folders as we know from other file systems.
Note that a folder must be contained in a project or another folder.
8
3.3. WORKSPACE RESOURCES
•
File
Files are always contained in a folder or a project.
Figure 3.1: Physical view - workspace hierarchy
Logical view
Logical view of the resource model is especially represented by interfaces of each resource types. These interfaces are a part of workspace API and allow us to work with their
particular implementations, which means resource elements.
Figure 3.2: Logical view - interface hierarchy
As the Figure 3.2 shows, IResource is a generalized handler for all resource types. It
provides basic manipulation for all resources. For getting a particular resource, we use the
class ResourcePlugin that has the static method getWorkspace().
9
3.4. BUILDING TEXT EDITORS
1
2
3
4
5
IWorkspace workspace = ResourcesPlugin.getWorkspace().getRoot();
IWorkspaceRoot root = workspace.getRoot();
IPath path = new Path("...");
IProject project = root.getProject(path);
IFile file = root.getFile(path);
Example 3.3.1: Example how to get a particular resource
Note that paths are strings separated by a forward slash character (/). Paths can be absolute or relative as we know from an ordinary file system. All changes made by workspace
API are immediately reflected in the appropriate file system. On the other hand, we must
take into account that changes made directly in file system are not known for the workspace.
That is why the workspace must be refreshed to reflect these changes to keep workspace
and file system synchronized. There is defined a change listener for the file system in the
workspace that is responsible for this refreshing. Refreshing can be also invoked by the user.
3.4
Building text editors
We will generally describe how to create custom text editors for Eclipse IDE as an Eclipse
plug-in. An editor is basic part of any IDE and in Eclipse it is a key Workbench part. It has
its own extension point ( org.eclipse.ui.editors) that our plug-in must contribute to.
For this purpose, Eclipse has a built-in text editor framework called JFace Text.
JFace Text provides a framework for creating and editing text documents. Note that JFace
Text is domain-independent and extensible, so we can built various types of text editors in
it. Eclipse default text editor and Java editor are also built using the framework JFace Text.
Creating text editors with JFace Text is based on creating subclasses of the abstract classes
of JFace Text. As a learning inspiration, we can use sample Java editor, which is part of the
Eclipse Samples. Generally the text editor framework supports the following features:
•
Text editing
JFace Text supports standard editing operations such as cut/copy/paste, find/replace
•
Viewing
For visual representation of the document it uses SWT widget StyledText and JFace
TextViewer to control and handle the raw StyledText. StyledText is an user interface
object for displaying lines of text. Using StyledText, we can change and define text
styles such as font and text color.
•
Standard Workbench menu and toolbar
There is a close integration between the Workbench window and editor part that
shares common Workbench menu and toolbar. The JFace Text also manages all edi10
3.4. BUILDING TEXT EDITORS
tor action contributions such as refreshing resources from the file system or closing
projects.
•
Standard markers
JFace Text provides support for resource markers, sometimes called annotations, e.g.
tasks, bookmarks. Visual presentation of resource markers appears adjacent to the text
editing area in a widget called vertical ruler. Markers are persistent and are associated
with a particular resource.
For illustration we will create simple text editor using a plug-in template with an editor (File
> New > Plug-in Project > Plug-in with an editor). This will create new plug-in project
with a simple XML editor. This project contains the file plugin.xml and also the directory
META-INF with the file MANIFEST.MF. These two files form a plug-in descriptor. The file
plugin.xml defines only extension points with appropriate attributes and MANIFEST.MF
includes information about plug-in and required plug-ins.
1
2
3
4
5
7
8
9
10
11
12
13
14
15
16
17
18
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
<extension point="org.eclipse.ui.editors">
<editor
name="Sample XML Editor"
extensions="xml"
icon="icons/sample.gif"
contributorClass="org.eclipse.ui.texteditor
.BasicTextEditorActionContributor"
class="myplugin.editors.XMLEditor"
id="myplugin.editors.XMLEditor">
</editor>
</extension>
</plugin>
Example 3.4.1: XML editor - plugin.xml
Extension point of this plug-in is org.eclipse.ui.editors (Example 3.4.1, line 5),
which is used for adding new editors to the Workbench. In this case, the element <extension> must contains element <editor>. Table 3.4 only describes attributes of the element
<editor> that are most widely used for defining new editor. The most important attribute is
class, which defines the main class of the editor.
In this case, the class XMLEditor extends TextEditor which is a child of the parent class AbstractDecoratedTextEditor (sometimes used for primary extending). This
class extends in order StatusTextEditor, AbstractTextEditor and finally the class
EditorPart that implements the interface IEditorPart.
11
3.4. BUILDING TEXT EDITORS
name
extensions
icon
contributorClass
class
id
label name shown in the UI for this editor
defines file types for the editor with comma separator; optional attribute
relative path to the icon, which will be shown in the Workbench for the specified extensions. It is optional attribute.
It defines the class name, which implements the interface
IEditorActionBarContributor. This attribute should
be defined only if the class attribute is defined. This class is
used to add new actions to the Workbench menu and tool
bar, which reflect features of the editor.
This attribute defines the class that implements the interface IEditorPart, which is the main class of the editor
plug-in. It is optional attribute, but if this attribute is defined then contributorClass should be also defined.
unique identifier of the editor
Table 3.2: <editor> attributes
3.4.1 TextEditor class
TextEditor class is responsible for editor working and provides basic text editor’s features. By extending it, we are able to add some new features requested for the editor, sometimes called "add-ons". Figure 3.3 in general shows classes that are in a relationship with the
TextEditor (XMLEditor). In the following text we will write only these general classes
and appropriate classes for XML editor in parenthesis.
SourceViewerConfiguration (XMLConfiguration) is used for defining all addons such as source presentation, content assistant, text hover or annotations. TextEditor is
in relationship with SourceViewer (XML editor uses this one), which provides the text editor with a text viewer and allows explicit configuration. The editor works with the text representation of the document called IDocument. Document knows nothing about the resource
of the document (how it is stored), it just handles the content. Document provides support
for change listeners, manipulating with the text content and contains information about positions, lines and especially partition types that will be described later. This document is
connected to the editor by FileDocumentProvider (XMLDocumentProvider) that implements the interface IDocumentProvider. The editor uses IDocumentProvider as an
interface between the documents and input elements.
3.4.2 Partitioning
Documents are usually divided into partitions [8]. Partitions are sections with some semantic meaning and each partition has its content type, offset and length. Note that partitions
must be non-overlapping. Using partitioning, we can define different actions for different
12
3.4. BUILDING TEXT EDITORS
Figure 3.3: Text Editor class
partition types. If some change listener occurs, Eclipse will change (reconcile) only the partition in which the change occurred.
The FileDocumentProvider (XMLDocumentProvider) assigns the partitioning class
FastPartitioner (XML editor uses this one) to the document. FastPartitioner defines the implementation of the IPartitionTokenScanner (XMLPartitionScanner)
that divides the document into partitions. In our example, the XMLEditor recognizes partitions of a XML file as follows:
•
__xml_comment (for comments)
•
__xml_tag (for tag elements)
Recognizing is implemented by defining rules, MultiLineRule and TagRule. Note that a
13
3.5. EDITOR FEATURES
default partition in any editor is marked as __dftl_partition_content_type.
In the SourceViewerConfiguration we can define which partitions are in use by
overriding the method getConfiguredContentTypes. This method returns an array of
strings - partitions. By partitioning we can define some add-on only for a particular partition, so changing other partitions does not invoke the add-on, which will speed up overall
working with the editor. That is why the partitioning is very important to understand.
3.5
Editor features
Each of these editor features (or add-ons) is relevant to defined partition content types. Remember that all add-ons are declared in SourceViewerConfiguration.
3.5.1 Syntax highlighting
Highlighting words such as keywords or function names improves the readability of the
source code, especially in large programs. Syntax highlighting is based on dividing the document into partitions that can be next divided into other sections (subpartitions). In other
words, we have to parse the document and for each section we will define a token. A token
is represented by an instance of IToken. Now, it is clear why the document partitioning has
been introduced and why it is so important. Therefore we will define a particular scanner
for each partition content type. Using the scanner, we can divide the particular partition
into sections to which the scanner assigns the appropriate token. Note that a token does not
represent the section. Eclipse uses three models for syntax highlighting:
•
Damage (IPresentationDamager)
Represents the text for redisplaying
•
Repairer (IPresentationRepairer)
The method how to redisplay damaged text
•
Reconcile (IPresentationReconciler)
Defines and maintains the representation of a text viewer’s document in the presence of changes applied to the document. The IPresentationReconciler is an
ITextViewer add-on.
Every time the document is changed, the presentation reconciler determines which region of the visual presentation should be invalidated and how to repair it. The standard implementation of the IPresentationReconciler is the class PresentationReconciler
that must include a scanner (implementation of ITokenScanner). The implementations
of IPresentationDamager and IPresentationRepairer are joined together into the
class DefaultDamagerRepairer as it is shown in Example 3.5.1 The scanner implements
ITokenScanner and usually is implemented as a scanner based on rules or by defining a
push-down automaton with the method nextToken().
14
3.5. EDITOR FEATURES
1 IPresentationReconciler getPresentationReconciler(
2
ISourceViewer sourceViewer) {
3
PresentationReconciler reconciler = new PresentationReconciler();
4
5
DefaultDamagerRepairer dr = new DefaultDamagerRepairer(
6
getXMLTagScanner());
7
reconciler.setDamager(dr, XMLPartitionScanner.XML_TAG);
8
reconciler.setRepairer(dr, XMLPartitionScanner.XML_TAG);
9
...
10 }
Example 3.5.1: Example how to set syntax highlighting
3.5.2 Content assistant
Very useful editor feature is a content assitant [9] that can spend much time with writing
source code. In fact, content assistant is a pop-up menu with a list of possible syntax proposals. Thanks to the content assistant, a programmer or just a user is not obliged to write
long variables or remember all syntax keywords. The content assistant is defined by overriding the method in the SourceViewerConfiguration (Example 3.5.2).
1 IContentAssistant getContentAssistant(ISourceViewer sourceViewer) {
2
ContentAssistant assistent = new ContentAssistant();
3
4
assistent.setContentAssistProcessor(new ACompletionProcessor(),
5
IDocument.DEFAULT_CONTENT_TYPE);
6
assistent.setContentAssistProcessor(new BCompletionProcessor(),
7
OTHER_CONTENT_TYPE);
8
//content assist settings
9
10
return assistent;
11 }
Example 3.5.2: Example how to define content assistant
In Example 3.5.2 we use standard Eclipse implementation of IContentAssistant,
which is ContentAssistant. We can see how to define a particular completion processor for a partition content type. The completion processor must be an implementation of the
IContentAssistProcessor that includes especially methods for setting options of the
content assistant. Many programmers and users are accustomed to invoke content assistant
by pressing keyboard shortcut Ctrl+Space. In completion processor we are able to define
only activating chars, but for mentioned keyboard shortcut we have to override the method
createActions in the class TextEditor. In other words, we have to register content
assistant action with the editor. In Example 3.5.4 we use ContentAssistAction as the
15
3.5. EDITOR FEATURES
implementation of IAction. This class requires an instance of ResourceBundle, but this
is useful only for actions such as button or menu item.
1
2
3
4
5
6
7
8
9
protected void createActions() {
super.createActions();
ResourceBundle rb = ResourceBundle.getBundle("...");
IAction action = new ContentAssistAction(rb, "ContentAssist.", this);
// CTRL+Space key doesn’t work without making this call
action.setActionDefinitionId(
ITextEditorActionDefinitionIds.CONTENT_ASSIST_PROPOSALS);
setAction("ContentAssist", action);
}
Example 3.5.3: Registering a content assistant to the editor
1
2
3
4
5
## Actions ##
ContentAssist.label=Content [email protected]+SPACE
ContentAssist.tooltip=Content Assist
ContentAssist.image=
ContentAssist.description=Content Assist
Example 3.5.4: Example of the resource bundle
3.5.3 Text hover
Another helpful editor feature is text hovering. It is a small window that is invoked by
hovering a mouse cursor over a particular part of code, e.g. function. This window usually contains documentation or other description text. For implementing text hovering, we
must override the SourceViewerConfiguration method getTextHover so that it returns an implementation of the ITextHover. The idea is easy, by hovering over the text,
SourceViewerConfiguration calls the method ITextHover with TextViewer and
offset as arguments. This method returns a region implementing IRegion that is used
for calling the second method getHoverInfo. This method returns simple string, which
will be shown in a pop-up window over the text in the document. When the pop-up window is displayed, we can move and resize the current pop-up window after pressing F2.
Text hover described above will be shown as a simple string in a pop-up window. Another way of showing text hover is showing it as a HTML page, therefore we need a HTML
presenter. Fortunately, Eclipse offers HTMLTextPresenter in the package org.eclipse.
jface.internal.text.html. We must take into account that this class is available only
in Eclipse 3.3, because it has been moved from the package org.eclipse.jdt.internal.
ui.text in Eclipse 3.2.
To set the HTML presenter, the TextHover class must implement another interface,
16
3.5. EDITOR FEATURES
which is ITextHoverExtension that adds new method getHoverControlCreator.
Example 3.5.5 shows how to set the HTML presenter to our TextHover.
1 IInformationControlCreator getHoverControlCreator() {
2
return new IInformationControlCreator() {
3
public IInformationControl createInformationControl(
4
Shell parent) {
5
return new DefaultInformationControl(parent,
6
SWT.NONE, new HTMLTextPresenter(),
7
EditorsUI.getTooltipAffordanceString());
8
}
9
};
10 }
Example 3.5.5: Setting the HTML presenter
3.5.4 Resource markers
Markers are additional objects that we can associate with resources or even with particular
parts of a resource. Markers are not stored in a file, but they are stored as part of workspace
by resource framework. Markers can be displayed as annotations in a vertical ruler in the
editor. They can be also available from the appropriate view such as Problems and Tasks
view. The org.eclipse.core.resources plug-in defines five markers. Each marker is
designed for a particular purpose:
•
Marker
General marker
•
Problemmarker
Used for marking any problem such as error and warning. It also supports quick fix to
offer the user proposals how to fix an occurred problem. We can see problem markers
in Problems view.
•
Taskmarker
Used to mark resource as a to-do notice. This marker is shown in Tasks view.
•
Bookmarker
If there are important resources to remember, we can mark them by bookmarkers that
are displayed in Bookmarks view.
•
Textmarker
By this marker we can define a specific part of the resource.
17
3.5. EDITOR FEATURES
The following code shows how to create and set the marker. As we mentioned, markers
are associated with the resource that has the appropriate methods for working with markers such as creating, getting and deleting. For details see Eclipse documentation [2] of the
interface IMarker.
IMarker marker = resource.createMarker(IMarker.TASK);
marker.setAttribute(IMarker.PRIORITY, IMarker.PRIORITY_NORMAL);
marker.setAttribute(IMarker.MESSAGE, "This is task marker");
3.5.5 Code folding
Folding in Eclipse [4] is defined using a special kind of annotation that defines a particular
part of code for collapsing and expanding. This allows a user to concentrate on a source
code without any disturbing parts of code that are not interesting for him/her in the moment. Collapsing parts of code makes the code more readable. Generally, an editor uses a
document for holding the text and an appropriate text viewer for displaying the text in the
UI. The idea of code folding is that the document is divided into a master document and a
projection document (see Figure 3.4).
Figure 3.4: Projection model, taken from [4]
The master document is like the document without folding and the projection document
is attached to the master one and contains only parts of the master document for folding.
Because of this projection model, the editor creates ProjectionViewer for managing the
projection document, instead of the SourceViewer. For this purpose, we have to override
the TextEditor method createSourceViewer.
The editor also must install the ProjectionSupport on a view as it is shown in Example 3.5.7. This class controls display and configuration of all UI elements related to folding.
We have defined all necessary classes and their configuration. Now, we have to determine which regions of the code will be collapsible. After defining a method for computing folder structure, we must decide when the method will be called. It is good idea
to compute folding structure whenever a document is changed. Since this computing can
be time-consuming, we will processed it in a background thread, ideally in the method
SourceViewerConfiguration.getReconciler. The MonoReconciler is a returning
18
3.5. EDITOR FEATURES
1 ISourceViewer createSourceViewer(Composite parent,
2
IVerticalRuler ruler, int styles) {
3
fAnnotationAccess = createAnnotationAccess();
4
fOverviewRuler = createOverviewRuler(getSharedColors());
5
ISourceViewer viewer = new ProjectionViewer(parent, ruler,
6
getOverviewRuler(), isOverviewRulerVisible(), styles);
7
// ensure decoration support has been created and configured.
8
getSourceViewerDecorationSupport(viewer);
9
return viewer;
10 }
Example 3.5.6: Creating ProjectionViewer
value of this method and uses an implementation of IReconcilingStrategy. This implementation is the right place for calling our method for computing new folding structure.
1
2
3
4
5
6
7
8
void createPartControl(Composite parent) {
super.createPartControl(parent);
ProjectionViewer viewer = (ProjectionViewer) getSourceViewer();
fProjectionSupport = new ProjectionSupport(viewer,
getAnnotationAccess(), getSharedColors());
fProjectionSupport.install();
viewer.doOperation(ProjectionViewer.TOGGLE);
}
Example 3.5.7: Installing ProjectionSupport in the TextEditor
1
2
3
4
5
6
7
void updateFoldingStructure(List<Position> positions) {
ProjectionAnnotationModel model = (ProjectionAnnotationModel)
getAdapter(ProjectionAnnotationModel.class);
// compute deletions and aditions
...
model.modifyAnnotations(deletions, additions, null);
}
Example 3.5.8: Updating folding structure
Finally, new folding structure must take effect in the ProjectionViewer. Note that
a folding region is represented by the ProjectionAnnotation. These projection annotations are added to the projection model (ProjectionAnnotationModel). In the class
19
3.5. EDITOR FEATURES
TextEditor we define a method for updating folding structure (see Example 3.5.8) with
steps as follows:
•
compute new folding structure
•
compute differences with current ProjectionAnnotationModel (deletions and additions)
•
update the ProjectionAnnotationModel with the differences
20
Chapter 4
SIT editor
In this chapter we will describe basic characteristics of the SIT language that are needed in
building the SIT editor. The whole SIT documentation is described in a grammar that is on
the appended CD (Appendix A). Consequently, we will describe the SIT editor from a user
view and at the end the own implementation.
4.1
SIT language
The SIT abbreviation stands for Siemens IP Test client. It is a script language used for testing
application protocols above the Internet Protocol. The SIT language supports conditional
execution, scope of variables and the PCRE 1 .
A SIT script can consist of one or more files, while one of them is the main file and others
are included into it. Included files are defined by pre-processor keyword #include. There are
sometimes the variable __TAM_ROOT__ that occurs in a path of included files. It represents
the root directory of SIT scripts and is close specified by the time the scripts are compiled.
The SIT uses messages for sending and receiving between internet protocols. These messages are typically specified in special files, SIP files. Content of SIP files is a simple string,
which is in a SIT file enclosed by double quotes. Strings can contain also tags, variables or
PCRE. Tags are special SIT functions and that start with the character $. There are also functions defined by a programmer by the keyword DEFUN. These functions are called by tha
command FUN. Variables are defined by the action ASSIGN, which also assigns a value to
the variable.
The SIT language is based on actions such as DEFUN and ASSIGN. Actions are related
by ordinary characters && and ||, except the action DEFUN. Comments are followed by
semicolon that can be used for writing a documentation. The SIT scripts uses the ROBODoc,
which is an API documentation tool for various languages such as C, C++ or Java.
4.2
SIT editor installing and setting
Installation
At first, we have to install Eclipse SDK (the SIT plug-in was tested under versions 3.3.1
and 3.3.2), which is described in Section 2.1. Now, we are able to add the SIT editor plug-in.
1. Perl Compatible Regular Expressions
21
4.2. SIT EDITOR INSTALLING AND SETTING
There is a JAR file and an Update Site of the SIT editor on the appended CD. Note that the
SIT editor is released under LGPL 2 version 2.1.
We can choose one of two ways of installing the plug-in as was described in Section 3.2.
There is the JAR file cz.muni.fi.xpodhr.bc.siteditor_1.0.5.jar on the appended
CD in the directory Plug-in. We just copy this JAR file into Eclipse directory plugins. In
installation using the manager, we set Local Site to the directory Update Site located on
the CD.
Settings
We can customize SIT editor plug-in using the file settings.properties located
in the JAR archive cz.muni.fi.xpodhr.bc.siteditor_<version>.jar. Remember
that all plug-ins are stored in the directory <inst_dir>\eclipse\plugins\. This setting file with default values is shown in Example 4.2.1. This file maintains information about
colors used in syntax highlighting and information how often check the syntax of SIT/SIP
scripts. To edit this file we must edit the appropriate JAR archive. There are file system managers that allows us to edit JAR archives such as Servant Salamander or Midnight Commander. It is good idea to create a copy of the JAR file and edit this copy file. We can also use
some ZIP (RAR) archivator. The trick is in renaming the file extension .jar to .zip (.rar). Then
we extract the archive, edit settings.properties (in any text editor), add back to the
archive and rename back the extension.
Highlight constant
COMMENT
PREPROCESSOR
KEYWORD
STRING
FUNCTION
PARAM
PCRE
CONDITIONAL_OPERATOR
COMPLETION_BACKGROUND
DEFAULT
Description
comments
pre-processor instructions that follows the sharp (#)
character
keywords include actions and compare operators
strings that are enclosed by double quotes, string is also
a content of a SIP file
functions or in this case tags, they follows the dollar ($)
character
function (tag) parameters enclosed by braces ({, })
perl compatible regular expressions used in strings
operators that relate actions, only || and &&
background color of a pop-up window used in code
completion
default text color
Table 4.1: Highlight constants
Table 4.2 describes highlight constants used by the file settings.properties (Example 4.2.1) for syntax highlighting. The example shows highlight constants and syntax
2. GNU Lesser General Public License 2.1; http://www.gnu.org/licenses/lgpl-2.1.html
22
4.3. CAPABALITIES
checking options with their default values. Note that changes will take effect after restarting
Eclipse, because Eclipse loads plug-ins at startup.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
### Syntax highlighting ###
# Color is defined in hex format
SIT_COMMENT = 808080
SIT_PREPROCESSOR = 208020
SIT_KEYWORD = FF0000
SIT_STRING = A52A2A
SIT_FUNCTION = 0000FF
SIT_PARAM = 0000FF
SIT_PCRE = 00CD00
SIT_CONDITIONAL_OPERATOR = 008000
SIT_COMPLETION_BACKGROUND = FFFFFF
SIT_DEFAULT = 000000
### Syntax checking ###
# 0 - no checking
# 1 - checking after saving (default)
# 2 - checking always a document is changed
# Note that option 2 can slow down the performance
SYNTAX_CHECKING = 1
Example 4.2.1: settings.properties
The SIT editor is able to work only with files inside the workspace. So we have to import
the files to the workspace. Note that all files and directories must be in some Project. That is
why we must create a project (File > New > Other > General > Project) and import required
files and directories. (File > Import.. > General > File System). Some files can include other
files defined by the command #include, which can contain the variable __TAM_ROOT__
in the path. It can be set in the configuration file config.properties, which belongs to
the appropriate project. The format of the path is relative path from the workspace root
directory. The default value is set to <project_name>.
Figure 4.1 shows SIT project’s structure and how the config.properties is set. In the
project Test we set the variable __TAM_ROOT__ to Test, which means that all occurrences of
the variable __TAM_ROOT__ will be replaced by the string "./Test/" ("<workspace>/
Test/").
4.3
Capabalities
Syntax highlighting
The SIT editor in general highlights keywords (actions and comparison operators), tags
names with their parameters and strings. In string (enclosed by doble quotes or SIP file)
the editor recognizes also tags and PCRE. Highlighting colors can be set in settings.
properties (Section 4.2).
23
4.3. CAPABALITIES
Figure 4.1: Example of config.properties and SIT project’s structure
Code completion
Content assistant is invoked by the keyboard shortcut Ctrl+Space and is defined for code
partition content type. After the action FUN, the content assistant shows the list with all
functions declared by DEFUN in the current file and in all included files. After completing
any function, the hover help will be shown above the function. This hover help displays all
parameters of the function and highlights the current parameter. We can invoke this hover
help by setting the cursor at the end of the function and pressing Ctrl+Space. After choosing
the function the hover help will be displayed. In other places of the code partition it will
show the list with all variables declared by the action ASSIGN. By invoking the content
assistant in default partition content type, the list of action proposals will be displayed.
Text hover
Hover help is defined only for tags. This hover help is invoked by hovering a mouse
cursor over any tag. After doing this, the SIT editor begins looking in the current file and in
included files for the ROBODoc documentation that starts with the string ****f*, which is
followed by the name of the tag. After pressing F2 we can resize the window or copy text
from this window.
Syntax checking
The SIT editor provides syntax checking on action and tag names. This checking depends
on configuration in settings.properties (Section 4.2). When the SIT editor finds an
error, this occurred error will be shown in a Problem view. The error is also highlighted in
the document, which contains the error, by a ripple red underline.
Code folding
There are large comments that are uses for ROBODoc documentation in SIT scripts. To
hide particular comments, the editor supports code folding for these comments, the content
of which is more over 6 lines.
24
4.4. IMPLEMENTATION
4.4
Implementation
In this section we will describe the own implementation of the SIT editor, but not in details.
Note that the SIT editor project and its documentation is available from the appended CD.
We will focus especially on the implementation idea of particular features. This editor was
built using the knowledge described in Chapter 3, “Eclipse extending”. We also use JFace
Text framework. The main class is SITEditor that extends TextEditor. Remember that
all features are defined in the class SITSourceViewerConfiguration.
In fact, the SIT editor consists of two editors: one for SIT and another for SIP files. In
other words, we can say that SIP editor is a part of the SIT editor, because it uses SIT editor’s
classes. The only one difference is in processing files. Remember that the content of a SIP
file is a string. The plug-in project’s name is cz.muni.fi.xpodhr.bc.siteditor. All
classes and packages of the SIT editor are located the package in cz.muni.fi.xpodhr.
bc. This main package contains 4 subpackages:
•
sipeditor
Contains classes responsible for configuration and proper work of the SIP editor.
•
siteditor
Contains classes responsible for configuration and proper work of the SIT editor.
•
addons
Contains classes for defining new features or also called add-ons.
•
utils
Includes classes that have not direct connection with editor’s classes, especially they
are used for auxiliary processing.
4.4.1 SIT partitioning
Before working with the SIT documents we have to define how to partition these documents.
SIT partitions are recognized by the SITPartitionScanner class in the package addons.
This class divided a document into partitions as follows:
•
__sit_comment
This partition is defined for comments. Comments starts with a semicolon and ends at
the end of line.
•
__sit_preprocessor
Pre-processor directives starts with a sharp and ends at the end of line. There are five
pre-processor instructions in the SIT language: include, if, else, endif and fi.
25
4.4. IMPLEMENTATION
•
__sit_code
The last partition is the own code, which begins with an action or with a comparison
operators. This partition also ends at the end of line.
As we can see, all partitions start with particular character or characters and end at the end
of line. That is why we use the class EndOfLineRule to define a partition in the scanner.
The rest of code, which are not covered with these partitions, belongs to the default partition content type. This partition can consists only of the conditional operators, which are |
| and &&. If there are any other characters, it means that they belong to no one of defined
partitions and leads to a syntax error. This can happen when an action is spelled incorrectly,
it does not belong to any defined partition, so it belongs to the default partition. There is
the interface ISITSyntax in the package addons that defines all sections, the document is
divided into.
4.4.2 Syntax highlighting
For each partition content type is defined a particular scanner, which must implement the
interface ITokenScanner. There are four scanners in the package addons:
•
SITCommentScanner
•
SITPreprocessorScanner
•
SITDefaultScanner
•
SITCodeScanner
The first three scanners are simple, they only assign one color to the appropriate partition.
The most important scanner is the SITScanner that is defined on the code partition content
type. This scanner is an example of the ITokenScanner implementation that does not use
rule classes for recognizing sections. This class divides the code partition into six sections:
action keyword, tag name (function), tag parameter (param), pcre, string and default section.
SITScanner is implemented as a push-down automaton, it parses the characters one by
one.
pcre
def ault
z
}|
z
{
}|
param
{
z
}|
{
ASSIGN
{MY_PARAM} |{z}
"
| {z } MY_VAR "Text
| {z } (( )?) $EXIST
| {z }
action
string
f unction
string
Example 4.4.1: Example how the SITScanner parses the code partition
4.4.3 Code completion
Code completion or content assistant is defined in the source viewer configuration by overriding the method getContentAssistant. There are two completion processors:
26
4.4. IMPLEMENTATION
•
SITCompletionProcessor
This completion processor is defined for default partitions. It shows a list of actions.
•
SITCodeCompletionProcessor
It is defined for code partition content types. It shows a list of functions or variables
depending in the current position of invoke.
Both completion processors use SITCurrentWord from the package utils. This class
serves for detecting current word we are writing in the editor. This word is used for matching with all possible proposals and only matching proposals are shown in the content assistant.
The first one returns a list of actions as completion proposals. The other one is more
complicated, because it provides two lists of proposals, list of functions and list of variables.
This completion processor looks for proposals in the document and in all included files by
recursive searching. It looks for all functions defined by the action DEFUN to get function
proposals and for all variables defined by the action ASSIGN to get variable proposals.
With the proposal list of functions it also provides content information. It is a small information window with function parameters that is shown over the completed function. For
this purpose, we define an implementation of IContextInformation that we use in the
constructor of the class CompletionProposal (Example 4.4.2).
1 ICompletionProposal[] computeCompletionProposals(...) {
2
//find current word
3
//find all proposals
4
//match proposals with current word
5
for(String function: functions) {
6
IContextInformation info = new ContextInformation(
7
null, function);
8
proposals.add(new CompletionProposal(...), ..., info, null);
9
}
10
return proposals;
11 }
Example 4.4.2: Example how to set ContextInformation
We use default implementation of the interface IContextInformation, which is the
class ContextInformation and has two arguments, but only the second one is important
for us. It is a simple string that will by displayed in context information window. To get it
work we must also define an implementation of IContextInformationValidator. In
the SIT editor, it is Validator that can be found in SITCodeCompletionProcessor. By
this class we define a behaviour of the context information window such as highlighting
current parameter.
27
4.4. IMPLEMENTATION
The class Validator contains methods as follows:
•
install
sets text viewer, context information and offset
•
isContextInformationValid
returns if the context information will be still displayed
•
updatePresentation
returns if the presentation will be updated
4.4.4 Hover help
In the SIT editor, text hovering is supported by the class SITTextHover, which constructor
requires input file of the current displayed document. The constructor also sets a viewer presenter as a basic html browser (HTMLTextPresenter). After hovering over any text in the
editor, the method getHoverRegion is called. If the hovering is over any function (FUN
<function>), the method returns a region that includes this function. Finally, the method
getHoverInfo is calling to get a string for displaying in the hover window. This method
includes calling the most important method, findRobodoc. This method recursive looks
for ROBODoc documentation relevant to the function name in included files. If the robodoc
is not found, it returns null, otherwise it returns the appropriate robodoc with basic html formatting. This formatting only highlights robodoc items, indent attributes and avoid printing
redundant blank lines in the pop-up window.
4.4.5 Syntax checking
The SIT editor checks only action and tag names. For syntax checking is used the class
SITMarkingErrorHandler, the constructor of which is responsible for the whole document checking. It contains three static methods:
•
markError
Marks a particular part of the given resource as a SIT error which is shown in the
Problems view and in the document at the appropriate line as an error annotation.
•
deleteErrors
Deletes all error markers associated with the given resource.
•
findAndMarkErrors
Finds all SIT errors included in the given document and accociates them with the given
resource.
28
4.4. IMPLEMENTATION
The SIT editor uses the method findAndMarkErrors, the parameters of which are a file
(file), a document of the file (document) and boolean value if the file is SIP file (isSip).
The given document is associated with the given file, but we have already computed the
document, so it is worthless to compute it again. The document is not associated with a resource, so we need the file of this document to get the appropriate resource, because markers
are associated with resources. The last parameter isSip defines what kind of the document
it is, either SIT or SIP.
At first, the method deletes all errors associated with the given resource. Then it iterates
over all partitions and parses only default and code partition content types. In code partitions the SIT editor mathes actions functions with the correct ones. If any action or function
does not match with, it is marked as the SIT error. The other partitions can contain only characters || or &&, that are something like action separators, so if any other characters occurs,
they are considered as wrong spelled action and are marked as an error. Syntax checking is
calling depending on configuration in settings.properties. There are three options:
•
no checking (0)
SIT editor does not provide syntax checking.
•
checking after saving a document (1 - default)
Syntax is checked always a document is opened and after saving a document. These
two methods sre defined in SITEditor and also in SIPEditor class by overriding
the method doSetInput and in the method doSave.
•
checking always a document is changed (2)
This option checks the syntax like the ones before, but in addition the syntax is checked
whenever a document is changed. In this way, the syntax checking is processed in a
background thread using the method getReconciler in the SIT/SIP source viewer
configuration. This method uses (SIT/SIPReconcilingStrategy, which body includes calling the syntax checking. We must take into account a possible slowdown
performence of the editor in case of large documents.
Annotation hover
This feature is provided by the class SITAnnotationHover in the package addons. It
implements the interface IAnnotationHover that includes the method getHoverInfo,
which returns simple string. The method iterates over all errors relevant to the current document and selects only errors associated with the given line. These errors forms a result.
4.4.6 Code folding
Folding structure is computed always a document is changed. For this purpose, there is
the class SITReconcilingStrategy for computing new folding areas in the SIT editor.
Note that this class also includes calling for the syntax checking. This reconciling is done in a
29
4.4. IMPLEMENTATION
background thread by using the method getRecinciler defined in the source viewer configuration. This method returns MonoReconciler that uses the strategy class mentioned
above. The own structure computing is based on iterating over all partitions and only comment partition content types are parsed. Only comments exceeded 6 lines are taken into
folding structure.
After computing the folding structure, the method updateFoldingStructure is called
from the class SITEditor. This method updates projection annotation model with the new
folding structure.
30
Chapter 5
Conclusion
The main goals of this bachelor’s thesis were to describe developing text editors and with
this knowledge create an editor for the SIT language that will be multiplatform. Because of
this fact, the thesis is generally divided into two main parts.
For creating the SIT editor we chose the Eclipse as an powerful IDE that we can extend.
That is why the first part (Chapter 3, “Eclipse extending”) deals with Eclipse extending
and customizing it to meet our requests. We especially focused on building text editors with
JFace framework. We also described Eclipse resources such as resource’s model and resource
markers that are directly relevant to text editors. This part covers all widely used editor features and generally describes their particular implementations in Eclipse. There are no or
only a few materials for some feature’s implementations such as HTML presenter in text
hovering, so we had to look for them in source code of the JDT. The text includes examples
for better understanding adjacent problems. This chapter serves as a tutorial to create custom text editor and is separated from the SIT editor implementation. This makes the thesis
useful for everyone interested in Eclipse and its extending.
The second part (Chapter 4, “SIT editor”) describes the own implementation of the SIT
editor, the purpose of which is to simplify and speed up programming in the SIT language.
This editor is built as an Eclipse plug-in that extends basic text editor in Eclipse. In developing this plug-in we used the knowledge described in the previous chapter. This chapter
also contains a basic characteristics of the SIT language that we used in creating the SIT
editor. The language characteristics are especially described from a syntax view. The editor
supports all required features mentioned in the Chapter 1, “Introduction”.
The SIT editor was created as a joint project of ANF DATA company (http://www.
anfdata.cz) and the research center Institute for Theoretical Computer Science, Faculty
of Informatics, Masaryk University (http://iti.fi.muni.cz). This editor has been already tested by programmers from ANF DATA with a possitive response and it met all their
requests.
The SIT editor is a good sample of building a text editor with JFace Text framework.
Since the SIT editor is an open source project, anyone can see the source code and maybe get
it as an inspiration in creating another text editor.
31
Bibliography
[1] Eclipse Foundation, Inc.: Eclipse.org home, http://www.eclipse.org . 2.1
[2] Roy, D.: Eclipse documentation, http://www.eclipse.org/documentation .
3.5.4
[3] Eclipse Foundation, Inc.: Eclipsepedia, http://wiki.eclipse.org .
[4] Deva, P.: Folding in Eclipse Text Editors, http://www.eclipse.org/articles/
Article-Folding-in-Eclipse-Text-Editors/folding.html . 3.5.5, 3.4
[5] D’Anjou, J. and Fairbrother, S. and Kehn, D. and Kellerman, J. and McCarthy, P.: The
Java Developer’s Guide to Eclipse, Addison Wesley, August 2007, 0-321-02116-7. 3.3
[6] Holzner, S.: Eclipse - A Java Developer’s Guide, O’Reilly, April 2004, 0-596-00641-1.
2.2
[7] Guclu, K.: A First Look at Eclipse Plug-in Programming, February 2004, http://
www.developer.com/java/other/article.php/10936_3316241_2 . 2.1
[8] Zoio, P.: Realsolve - Building an Eclipse Text Editor with JFace Text, April 2006, http:
//www.realsolve.co.uk/site/tech/jface-text.php . 3.4.2
[9] Daum, B.: Equipping SWT applications with content assistants, November 2003,
http://www.ibm.com/developerworks/opensource/library/os-ecca/
?ca=dgr-eclipse-1 . 3.5.2
32
Appendix A
CD content
A compact disk is a part of this bachelor’s thesis and includes the following:
•
XML source code of this bachelor’s thesis and its PDF output
•
The plug-in project cz.muni.fi.xpodhr.bc.siteditor in a ZIP archive
•
JavaDoc documentation for the cz.muni.fi.xpodhr.bc.siteditor project
•
JAR file of the SIT editor plug-in for direct installation
•
Update site of the SIT editor plug-in for installation using the install manager
•
Grammar of the SIT language
33

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project