Address Other Textblocks from EES

The first step necessary to address a different textblock is to define how to find it in relation to the textblock which is being analysed. This is done with a #scope directive.

Each scope has a name, which enables the script to refer to it later, and a sequence of rules that describe how to navigate within the document structure.

A simple example

#scope PreviousTextblock
prev-textblock
#

This directive defines a new scope called ‘PreviousTextblock’. The definition has a single instruction ‘prev-textblock’ which instructs the system to move from the current textblock to the one before it.

After a #scope has been defined, it can be used in an entity extraction script rule using the #with directive as follows:

#with name-of-scope
[matching pattern in the other textblock]
#
[matching pattern in the current textblock]
> [output]

Without the #with, matching pattern is always in the "current" textblock. If there is one or more #with, the matching pattern within applies to the other textblock. The #with directives can be before or after the main pattern.

A simple example

#scope PreviousTextblock
prev-textblock
#
#with PreviousTextblock
Token<text ()="CODE">
#
Token.number
> tag:Code

The above example has a main rule that matches any number and tags it as Code. However, the rule is executed with a #with condition that uses PreviousTextblock scope (defined above) and requires that the previous textblock matches a token with text "CODE".

This ensures that the only numbers marked up as tag:Code are the ones that have the correct header.

The output (here tag:Code) is only created on top of the main matching pattern. However, an output can be created on top of the #with pattern by using labels:

#with PreviousTextblock
Token<text ()="CODE"> = $heading
#
Token.number
> tag:Code
> $heading = tag:CodeHeading

However, no annotation can span more than one textblock, so there can't be an output that's on top of main and #with pattern at the same time.

To see how individual instructions of the #scope directive are executed:

1. Create and open an Entity Extraction Script configuration.
2. Create a #scope directive, such as the example above.



3. Click Save & Test.
4. Switch the Document Input Method to Document ID and enter the ID of an existing document to use as test. Using the ‘Enter Text’ method is not helpful because a practical test requires a full document structure.



5. Click Submit.
6. In the document view, find a textblock for which you would like to write an EES rule.
7. Right click on the magnifying glass icon.
8. Select ‘Test #scope from this textblock’.



A panel with the #scope testing tool is displayed.



The panel consists of the following parts:

• The dropdown is a selector for the #scope rule to debug. In this example there is only one rule called ‘PreviousTextblock’.
• ‘starting from’ shows which textblock was chosen as the starting point. You can click on the link to highlight it in document view.

The ‘location’ shows where the starting textblock is located in its document. In this example, the textblock belongs to a cell, which belongs to a row, table, and the document root. Those structures can be highlighted in document view by clicking on them.

The table that follows shows each instruction and the result of executing this instruction. In this example, there is only one instruction ‘prev-textblock’ and the result of executing it is a single textblock. You can click on this textblock to highlight it.

Finally, there is a list of textblocks that were matched by this #scope rule. If there is more than one textblock matched, the list will be tried in order from the textblock that is closest to the starting point, to the textblock that is furthest away. The list displayed here reflects this order.

For a more advanced example of a #scope directive, see ‘Full example’ below.

For a full list of instructions available in the #scope directive, see the reference table below.

The following table lists available instructions to use within #scope directive.

Textblock manipulation instructions

Textblock manipulation instructions match consecutive textblocks and ignore the structure.

All the textblocks matching instructions have shortcuts that follow this pattern:

Examples:

prev-textblock //a previous textblock
first-textblocks(2) //the first two textblocks
first-textblock(2) //the second textblock

Expand instruction

Example:

expand-structure(cell) //find the table cell that contains the current selection
expand-structure(table) //find the table that contains the current selection
expand-structure(list) //find the list that contains the current selection

The expand-structure instruction has the following shortcut:

Structure manipulation instructions

Structure manipulation instructions match consecutive structure elements.

All the structure matching instructions have shortcuts that follow this pattern:

Examples:

first-cell //first table cell
first-cells(3) //first three table cells
first-cell(3) //third table cell

Text matching instruction

Those instructions match up to one textblock. The pattern is a sub-string of the textblock, or the entire textblock. Matching is case-sensitive. If the pattern contains a quotation mark, use sequence \" instead. If it contains backslash use \\ instead.

Table manipulation instructions

Table manipulation instructions are dedicated to finding data within a table. Table is analysed with column spans taken into account, and the resulting match can be multiple cells of one column which are otherwise not direct neighbours.

Table column is not a structure within a document and as a result, selecting a column is actually implemented as a selection of individual table cells of that column.

Note that it's not possible to select multiple columns. As a result, instructions like first-column don't take a range of numbers, like first-structure would.

To avoid ambiguity when selecting columns, it's recommended to use those instructions when the current selection is one cell, or one textblock. If the current selection is made of multiple cells, the first selected cell is used to derive current column number.

allow-self instruction

The result of textblock matching can contain the initial textblock, which is used to match the main pattern. However, by default, that textblock is filtered-out.

If you include the instruction "allow-self" anywhere in the #scope directive, initial textblock is allowed.

Examples:

#scope MyCellButNotMyTextblock
expand-cell
#
#scope MyCell
expand-cell
allow-self
#

The following #scope shows how to markup text in table cells based on their column heading:

#scope MyHeading
expand-column // go from the current textblock to the entire column
top-cell // consider only the very first cell of this column
#
#with MyHeading
Token<text()="Project">
#
Token+
> tag:ProjectName

The following #scope shows how to access the header of a table:

#scope MyTableHeader
expand-table // expand to the full table
prev-textblock // get the textblock before current table
#
#with MyTableHeader
Token+ = $tableIdentifier
#
// match the single cell "Project"
>Node<isBreak=true>
Token<text()="Project">
Node<isBreak=true>
> @create<ns="tag", name=$tableIdentifier.text()>

The following #scope shows that this capability can be used to make links:

#scope MyRow
expand-row // find it anywhere in the same table row
#
#with MyRow
tag:ProjectName = $pro
#
tag:Priority = $prio
> @connect<project=$pro, priority=$prio> tag:PriorityLink