scala-ide/scala-ide — pull request #644 by afitz (2014-02-20 23:52:40+00:00)
Title: Fix for #1001989

This PR adds an ability to plug-in your own semantic highlighters to Scala IDE.

It uses existing extension (one for implicit highlighters) and provides you with some basic
scaffolding that allows easy plugin creation.

Main classes provided for this are instances of `TraverserDefinition` which provides a way to search
for certain pieces of code:
* `AllMethodsTraverserDefiniton` - searches for all method calls on given type (and it's subtypes)
* `MethodTraverserDefinition` - searches for all method calls of given method
* `AnnotationTrverserDefinition` - searches for all usages of methods annotated with given annotation

(all above by 'method' understands `val`s, `var`s, `def`s and/or `lazy val`s)

Those are then used to create `CustomSemanticAction`, `SemanticHighlightingReconciliation,
and `SemanticHighlightingReconciliationParticipant` (last one is plugged into Scala IDE).

---

For example to highlight all method usages on Scala mutable collections one has to create
a plugin with 2 classes inside, one that define traverser and highlihter:

```scala
package

object MutableCollectionHighlighter {

/** Id of annotation, used in plugin.xml */
lazy val ID = "annotations.demo.mutable"

/** Traverser that looks for all method calls on children of collection.mutable.Traversable */
lazy val traverser = AllMethodsTraverserDefinition(
id = TraverserId(ID),
message = "Method call on a mutable collection.",
typeDefinition = TypeDefinition("scala" :: "collection" :: "mutable" :: Nil, "Traversable"))

/** Preference page */
lazy val properties = MutableCollectionPreferencePage.properties

/** Highlighting actions */
lazy val actions: List[JavaSourceViewer => SemanticAction] =
List(viewer => new CustomSemanticAction(viewer, traverser, properties))
}

/**
* Custom highlihter for mutable collection methods.
*
* It's plugged to Scala IDE extension (see plugin.xml).
*/
class MutableCollectionHighlighter extends SemanticHighlightingReconciliationParticipant(
reconciler = new SemanticHighlightingReconciliation(actions))
```

And second with a preference page:

```scala
/**
* Prefererence page for mutable collections, plugs into extension.
*/
class MutableCollectionPreferencePage
extends CustomPreferencePage("Mutable collections", MutableCollectionPreferencePage.properties)

object MutableCollectionPreferencePage {
val BASE = "scala.tools.eclipse.ui.preferences.mutable."
val P_ACTIVE = BASE + "enabled"
val P_BOLD = BASE + "text.bold"
val P_ITALIC = BASE + "text.italic"

val properties = Properties(
active = MutableCollectionPreferencePage.P_ACTIVE,
bold = MutableCollectionPreferencePage.P_BOLD,
italic = MutableCollectionPreferencePage.P_ITALIC)
}

/**
* Initializer for custom highlighter, plugs into extension.
*/
class MutableCollectionPreferenceInitializer
extends CustomPagePreferenceInitializer(MutableCollectionPreferencePage.properties)
```

And plug them into Scala IDE:

```xml

```

Lastly, the below disclaimer is required by the lawyers:

THE FOLLOWING DISCLAIMER APPLIES TO ALL SOFTWARE CODE AND OTHER MATERIALS CONTRIBUTED IN CONNECTION WITH THIS SOFTWARE:
THIS SOFTWARE IS LICENSED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AND ANY WARRANTY OF NON-INFRINGEMENT, ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THIS SOFTWARE MAY BE REDISTRIBUTED TO OTHERS ONLY BY EFFECTIVELY USING THIS OR ANOTHER EQUIVALENT DISCLAIMER IN ADDITION TO ANY OTHER REQUIRED LICENSE TERMS.
ONLY THE SOFTWARE CODE AND OTHER MATERIALS CONTRIBUTED IN CONNECTION WITH THIS SOFTWARE, IF ANY, THAT ARE ATTACHED TO (OR OTHERWISE ACCOMPANY) THIS SUBMISSION (AND ORDINARY COURSE CONTRIBUTIONS OF FUTURES PATCHES THERETO) ARE TO BE CONSIDERED A CONTRIBUTION. NO OTHER SOFTWARE CODE OR MATERIALS ARE A CONTRIBUTION.