The german version of this tutorial is available here.

After this tutorial you will be able to write and use a simple Detector of Cultivate. For this purpose we are going to write a Detector which finds the occurrence of “;” without previous Statements. This Detector is already included in Cultivate as the NopSmell-Detector.

1. Eclipse and Cultivate should be installed and runable. The complete installation guide can be found on Development Environment.
2. Create a new project and include the following class

public class A {

  public void x() {
     ;;    
  }
}

1. Assign JTransformer and Prolog-Nature to this project.
2. Goto the project properties and assign the Cultivate-Nature (Cultivate→ [x] Cultivate Nature), this is only available after you assigned JTransformer-Nature.

1. Create a file named 'conventions.pl' in the main folder of the project with the following content:

   :- multifile detector_description/4.

1. Project specific Detectors, in external files, can be included in this file with

   :- consult('externalFile.pl').
   :- consult('inDirectory/anotherExternalFile.pl').

Now we are ready to write our first Detector! Add to the 'conventions.pl' file

      detector_description(myFirstDetector,'a short description',statement,unrated).
      detector_(myFirstDetector,occurrence,[(statement,CallID)],[]) :- 
                fail.    

The predicates used in this two lines are

1. The name of the Detector, this must be equal in both predicates.
2. A short description of the Detector
3. Name of the Role. A Detector returns references to code-elements (IDs) and relations between them. To each ID a role is assigned.
4. A RatingType, for simple Detectors 'unrated' is sufficient.

1. The name of the Detector, this must be equal in both predicates.
2. We are using the unrated RatingType, so all Ratings must be 'occurrence'
3. A list of IDs and their Roles. Here we are using only one Role 'statement' assigned to the ID 'CallID'.
4. The Relation between code-elements, can be empty ('[]').

After saving the 'conventions.pl' we need to refresh all detector definitions. Right Click the Project for the context menu and choose 'Refresh Detector Definitions'.

For viewing the Detector-Results goto Window/Show View/Other… and Cultivate/ Metrics and Detector Results. In the right top corner of this view clicking on the triangle will show a list of all available Detectors, including our new written one.

Currently our Detector should return no results, because we implemented it with a 'fail'. We will change this in the next section.

Substitute the detector_ predicate in the 'conventions.pl' file with the following code:

   detector_(myFirstDetector, occurrence, [(statement, CallID)], []) :- 
       nopT(CallID, _, _).

The nopT-predicate represents a single semicolon, just what we need. After saving the file don't forget to refresh the detector definitions. In the View you should see now two results, one for each single semicolon.

1. After saving the conventions.pl file no refresh of the detector definitions was done.
2. When using 'unrated' RatingType the Rating 'occurrence' must be used
3. Prolog errors in the code

1. If the Detector is not working, look into the output log of Eclipse and browse through the output. If this doesn't help look at the StackTrace and change the logging level.