itemis ANALYZE’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 text editor adapter supports selection propagation: If you select an element in ANALYZE, 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 ANALYZE.
Open the ANALYZE configuration with the ANALYZE configuration editor, and add a new data access as described in section "Data accesses". Select Text Editor as data access type.
Supported options:
Example:
resource *.txt
This configuration specifies that ANALYZE should load all files residing in the workspace whose filename extension is .txt.
Open the ANALYZE configuration with the ANALYZE 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”.
The Text File artifact type configuration supports the following keywords:
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.
ANALYZE 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.
ANALYZE 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, ANALYZE automatically updates the file as links are created, deleted, or updated in ANALYZE.
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
the text editor adapter assumes that a link and an artifact belong to each other in any of the following cases:
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.
When you create links in ANALYZE by using drag and drop or by using the ANALYZE Editor, the link texts will be added in the lines above the artifact. Each link text will have its own line. Note that ANALYZE 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 ANALYZE itself, so only manual modifications of the text file can create read-only links. In the sample code provided above, ANALYZE can delete just the links to
My Result 1 and
My Result 3. This example also illustrates the reason for this restriction: if ANALYZE 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:
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:
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.
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.
ANALYZE supports the creation of links by dragging elements from various ANALYZE views and dropping them into the text editor.
This functionality requires the following:
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.