Text editor

YAKINDU Traceability’s text editor adapter identifies fragments within plain text files as traceable artifacts, using configurable regular expressions. In a similar way, the adapter also recognizes link information in the very same text files. It operates invasively and is thus not only able to read links from text files, but it can also insert, modify, and delete them.

Elements are identified based on regular expressions:

  • The artifact type configuration specifies which text fragments should be recognized as artifacts.
  • The link type configuration specifies which text fragments should be recognized as links and how they are mapped to artifacts on the opposite side of the link.
  • Implicit rules define which artifact belongs to which link and thus to the artifact on the opposite side of the link.

The text editor adapter supports selection propagation: If you select an element in YT, the selected artifact will be opened in Eclipse’s default text editor, and if you select an element in Eclipse’s default text editor, it will be also selected in YT.

Data access

Configuration

Open the YT configuration with the YT configuration editor, and add a new data access as described in section "Data accesses". Select Text Editor as data access type.

Supported options:

  • resource – File filter pattern

Example:

resource *.txt

This configuration specifies that YT should load all files residing in the workspace whose filename extension is .txt.

Artifact type

Configuration

Open the YT configuration with the YT configuration editor, and add a new artifact type as described in section "Artifact types". Select your previously-configured Text Editor data access in the Data access drop-down list.

Example:

locate text where pattern matches "(?m)(REQ)(?<id>\\d{2})(\\s+)(?<txt>\\w+)" { 
	name group("$1") + "_ID_" + group("id") 
	identified by group("$2") 
	map { 
		attr to group("txt") 
	} 
}

This example shows an artifact type configuration for the text editor adapter. The pattern uses multi-line mode search ( ?m) to find all occurrences of specific text elements. Such a text element start with „REQ” ( REQ), followed by two digits ( ?<id>\\d{2}), followed by one or more spaces ( \\s+). The text element ends with a word consisting of several characters ( ?<txt>\\w+). Extracted artifacts are named according to the result of the first capture in the pattern ( $1), followed by a constant value which is the result of the capture named „id”. Artifacts are identified by the result of the second capture in the pattern. The custom attribute attr is mapped to the result of the capture named „txt”.

Keywords

The Text File artifact type configuration supports the following keywords:

  • locate text where pattern matches pattern – Looks up text matching the specified regular expression in the configured files. An artifact will be created for each text sequence matching the regular expression.
  • name expr – Specifies the name of the artifact as the value of the expression expr. By default, this is the text fragment matched by the pattern.
  • group( name) – Retrieves the match of the capture named name in the pattern.
  • identified by – An optional key for the matched artifact. If specified, it should return a value which uniquely identifies the artifact. If the same value is returned for more than one matching text elements, YT will create only a single artifact.
  • map – Starts a mapping block for specifying custom attributes.
  • metadata( name) – Evaluates to a string depending on the name parameter. Returns the artifact’s position for Identifier, its name for Name, or its resource for Resource.

Version

An artifact’s version is used for suspicious links validation. The version of an artifact of this type is evaluated as a JSON-like concatenation of all artifact custom attribute values.

YAKINDU Traceability is able to recognize link information in text files in the same way as it can recognize text artifacts: a configurable regular expression defines which parts of the text correspond to links. These links define to which other artifacts the text artifacts in the same file are linked.

YT supports link maintenance in two ways. On the one hand the user can create, delete, or update links by manually adding, removing, or changing the corresponding texts in the file. On the other hand, YT automatically updates the file as links are created, deleted, or updated in YT.

We will now introduce the configuration language, including its syntax, by an example. You can find a more detailed description of the configuration below.

Let’s assume that we want to identify links for artifacts in text files of a „text file” artifact type that we have configured previously. We have selected this artifact type as link end A of the link type. Now we also have to flesh this out in the link type configuration. We are doing so by starting the configuration with the line analyze files of A.

Let’s assume further that we want to identify artifacts in a text file according to the sample artifact type configuration that we used for the text file artifact type, with artifact texts like REQ10 SampleRequirement. Now we want to link these to tests that are represented by artifacts of the second artifact type. Let us assume that these artifacts are identified by an arbitrary sequence of words, separated by spaces, that ends with a number. An example would be My test 123.

Of course we somehow have to identify the start of such a sequence of words in the text file. So let’s add some unique „marker text” left from each such artifact identifier, for example, @Test. Thus, the text making up a link to an artifact with the above-mentioned identifier would be @TestMy test 123. This way, we don’t need to consider too much unrelated text left from a number as potential artifact identifiers.

To identify links as suggested above, we extend the configuration as follows:

analyze files of A
locate links by "(@Test(?<id>[a-zA-Z\\s]+[0-9]+))"{
    where { 
        group("id") = B.metadata(Identifier)
    }
} create links by { "@Test" + B.metadata(Identifier) }

The expression locate links by is followed by a regular expression specifying which patterns in the text should be regarded as links. The where block defines additional constraints that must be fulfilled such that a link is recognized. In this case, the where block contains one constraint: It requires that the part of the match that is right from @Test must match the identifier of any artifact for link end B.

We find this identifier within the matching text by using the matching group ?<id> in the regular expression and by later referencing it via group("id").

The block starting with create links by defines how new link texts are created. In this case the expression is straightforward: The newly-linked artifact’s identifier is appended to the above-mentioned prefix.

Let’s now assume that we want to map the text part and the numeric part of the requirement ID to different custom attributes of the link. We can achieve this by extending the configuration as follows:

analyze files of A
locate links by "(@Test(?<id>(?<text>[a-zA-Z\\s]+)(?<number>[0-9]+)))"{
	where { 
		group("id") = B.metadata(Identifier)
	}
} map {
	 testNumber to group("number") 
	 testText to group("text") 
} create links by {
	"@Test" + B.metadata(Identifier)
}

We are using the additional groups number and text to identify the desired parts of the matching text. The map block assigns the corresponding values to the link’s custom attributes.

Now we know which parts of the text correspond to links and which parts correspond to artifacts. However, which links do belong to which artifacts? The link text only specifies the artifact on the B side of the link; the artifact on the A side, i.e., „this” side, is one of the text fragments that have been recognized by the regular expression spelled out in the artifact configuration.

Considering all pairs of

  • text matches recognized as links and
  • text matches recognized as artifacts,

the text editor adapter assumes that a link and an artifact belong to each other in any of the following cases:

  • Artifact text and link text overlap.
  • The artifact text follows the link text somewhere on the same or the next line, possibly interspersed with some text that neither matches any link nor artifact regular expression.
  • An artifact can be preceded by multiple links and belong to all of them. These links must be arranged on consecutive lines, possibly interspersed with some text that neither matches any link nor artifact regular expression.

Please note: A consequence of these rules is that you can have an arbitrary sequence of links, interspersed by arbitrary text, and followed by an artifact. Links and artifacts can be distributed over several consecutive lines – with one restriction: Each of the lines must contain at least (part of) one link or (part of) the artifact. Any other line interrupts the sequence of links. Link texts preceding such a line are „lost”, i.e., they don’t belong to an artifact and thus don’t establish any links.

Consider the following example:

@TestMy Result 1
REQ01 SecondRequirement
@TestMy Result 2
Some Text
@TestMy Result 3
@TestMy Result 4 Some other text
@TestMy Result 5 REQ02 ThirdRequirement

In this example, the REQ01 artifact will be linked to My Result 1, REQ02 will be linked to My Result 3, My Result 4, and My Result 5. However, My Result 2 will not be linked to anything, because the line Some Text neither matches an artifact nor a link regular expression. However, it separates the block of link texts preceding it from the following link and artifact texts.

Eclipse editor drag-and-drop linking functionality

When you create links in YT by using drag and drop or by using the YT Editor, the link texts will be added in the lines above the artifact. Each link text will have its own line. Note that YT can delete a link only if its text is either contained in an artifact or it is the only text (except for whitespace) in the same line. This applies to all links created by YT itself, so only manual modifications of the text file can create read-only links. In the sample code provided above, YT can delete just the links to My Result 1 and My Result 3. This example also illustrates the reason for this restriction: if YT were to remove the text @TestMy Result 4 in order to delete the link to My Result 4, this would mean that My Result 3 wouldn’t be linked anymore. Removal of the complete line would also remove Some other text, i.e., other text which might contain valuable information.

This functionality requires the following:

  • A unique link type needs to be configured between the artifact type of the elements being dragged to the text editor and the artifact type of target elements in the text editor.
  • There must be only one writable mapping of type Text Editor for this link type, i.e., one with a create links by expression.

If these conditions are fulfilled, a link can be created by dragging an element and dropping it into the text editor. If one of the conditions required for this functionality is not fulfilled, dropping is prevented and a message is shown that indicates the reason.

The configuration has the following structure:

  • analyze files of … – Defines which text file artifact type selected as link end should be used when searching for links. Possible values are A and B. The adapter will link artifacts of the selected type according to link text matches that are found in files of the corresponding data access.
  • locate links by – A regular expression that defines the portions in text files representing links.
  • map { … } – As an option, it is possible to define link attributes and derive their values, similar to the identifier derivation specified by identified by in the of an artifact type configuration.
  • create links by … – This expression specifies how YT evaluates the text that represents a new link, which is to be created. The specification is a concatenation of static strings and artifact attribute values. Please make sure that links created according to this expression can be recognized by the pattern specified in the locate links by expression. YT itself does neither check nor guarantee this.
  • where – Specifies attributes that are relevant for identification of artifacts on the „other” side to be linked to a text file artifact.

In where sections, it is possible to add several rules to match groups in the regular expression specified by locate links by to attributes of the relevant artifacts. A rule is expressed by an equation of the form LeftHandSide = RightHandSide . The LeftHandSide is a concatenation of static strings and groups (accessed via the keyword group( name) in the same way as in the artifact type configuration) referring to the regular expression. The RightHandSide is a concatenation of static strings and values of artifact attributes and/or the artifacts metadata Identifier and Resource. For link creation, each of these expressions must match, i.e., they are linked by logical AND.

Links of this link type will never become suspicious.

Text editor drag-and-drop linking functionality

YT supports the creation of links by dragging elements from various YT views and dropping them into the text editor.

This functionality requires the following:

  • A unique link type needs to be configured between the type of artifacts being dragged to the text editor and the type of target artifacts in the text editor.
  • There must be only a single mapping of type Text editor for this link type. Additionally, this mapping needs to support link creation by inserting text into text files.

If these conditions are fulfilled, a link can be created by dragging an element and dropping it into the text editor. Link text is inserted at the beginning of the line that the element is dropped at, the modified contents of the text editor is saved to disk, and a link is created automatically. If one of the conditions required for this functionality is not met, a dialog indicating the failure reason is shown.