Syntax coloring

Syntax coloring is provided in the platform text framework using a model of damage, repair, and reconciling.
For
each change applied to a document, a presentation reconciler determines
which region of the visual presentation should be invalidated and how to
repair it. Different strategies can be used for different content
types in the document.

Implementing syntax coloring (and doing so with a presentation reconciler) is
optional. By default, SourceViewerConfigurationdoes not install a presentation reconciler since it does not know the
document model used for a particular editor, and has no generic behavior for
syntax highlighting.

In order to use the reconciling classes to implement syntax highlighting, your editor's source
viewer configuration must be configured
to define a presentation reconciler. Once again, we start with JavaSourceViewerConfiguration
to see how a presentation reconciler is defined for our editor.

To understand what a presentation reconciler does, we must first look at the
concepts of damage, repair, and reconciling.

Damage, repair, and reconciling

As the user modifies text in an editor, parts of the editor must be
redisplayed to show the changes. Computing the text that must be
redisplayed is known as computing damage. When syntax coloring is
involved, the amount of damage caused by an editing operation becomes more
extensive, since the presence or absence of a single character could change the
coloring of the text around it.

Damagers (IPresentationDamager)
determine the region of a document's presentation which must be rebuilt because
of a document change. A presentation damager is assumed to be specific to a
particular document content type (or region). It must be able to return a damage
region that is valid input for a presentation repairer (IPresentationRepairer).
A repairer must be able to derive all of the information
it needs from a damage region in order to successfully describe the repairs
that are needed for a particular content type.

Reconciling describes the overall process of
maintaining the presentation of a document as changes are made in the
editor. A presentation reconciler (IPresentationReconciler)
monitors changes to the text through its associated viewer. It uses the
document's regions to determine the content types affected by the change and
notifies a damager that is appropriate for the affected content type. Once
the damage is computed, it is passed to the appropriate repairer which will
construct repair descriptions that are applied to the viewer to put it back in
sync with the underlying content.

Presentation reconcilers should be provided with a repairer and
damager pair for each content type to be found in the document. It is up to each editor to determine the appropriate implementation for a
presentation reconciler. However, the platform provides support in org.eclipse.jface.text.rules
for using rule-based document scanners to compute and repair damage.
Default damagers and repairers are defined in this package. They can be
used along with the standard reconcilers in org.eclipse.jface.text.presentation
to implement syntax coloring by defining scanning rules for the document.

Rule based reconciling

Now we have enough background to look in detail at the creation of the
example presentation
reconciler. Recall that the Java editor example implements a JavaPartitionScanner
which partitions the document into content types representing javadoc, multi
line comments, and everything else.

The default content type is set up with a JavaCodeScanner so that
keywords can be detected and colored. The JavaCodeScanner builds
rules for detecting different kinds of tokens, such as single line comments,
white space, and words. It describes the colors that should be used for
words of different token types.

The other content types are set up with a SingleTokenScanner and given
a color to be used for tokens in these content types.

All of the details for damaging and repairing the proper parts of the
documents according to the scanning rules are handled by DefaultDamagerRepairer.
These details typically don't need to be understood by plug-in code. Your
plug-in should focus on building a set of rules that are appropriate for
partitioning and scanning its editor content.

Dynamically installing a reconciler

The Java editor example provides a subclass of SourceViewerConfiguration for installing the presentation reconciler as seen earlier. A
presentation reconciler can also be installed dynamically on a text viewer using
IPresentationReconciler
protocol. There is no
particular runtime benefit to doing it either way, but putting all of the
pluggable behavior overrides in a subclass of SourceViewerConfigurationprovides the advantage of consolidating all of the behavioral overrides in one place.
The dynamic protocol may be useful when different presentation reconcilers are
attached to a viewer throughout the life of an editor.