ANML Documentation

Macro Reporting

This section describes the default reporting behavior of ANML macros.

Default Reporting Behavior

Report events are associated with the macro that contains the reporting elements.

For example, in an automata network containing only a single macro reference, and with that macro not instantiating any other macros, reporting occurs at the macro reference level. That is, suppose an STE within this macro generated a report event. That report event would not be associated with the STE. Rather, the report event would appear as a report event associated with macro instance that contains the STE. The same concept applies for counter and boolean elements contained within the macro. All report events are associated with the macro that contains the reporting elements.

Nested macros are allowed, and the same principle applies when a report event is generated at any hierarchical level within a set of nested macros. The report event will rise to the top of the macro hierarchy, and will be associated with the top-most macro that contains the element that generated the report event.

If multiple report events are generated within a macro hierarchy, all of these report events will aggregate together into a single report event associated with the top-most macro reference. This occurs even if the individual report events occur at different hierarchical levels within the macro hierarchy.

In effect, the default behavior of a macro reference is to aggregate together all child report events at all levels of depth in the hierarchy.

Overriding the Default Reporting Behavior

A report port—a type of port declaration in a macro definition—provides a way to capture report events within a macro and associate them with a port. When these report events are presented, they are specifically associated with the containing macro instance and the port to which they are connected.

Different reporting resources within a macro can be connected to different report ports, and therefore can be distinguished from each other rather than being grouped together under the generic macro reference.

Multiple reporting resources within a macro can be connected to the same report port (see Report Grouping for more details).

Mixed Reporting

Not all reporting elements within a macro need be connected to a report port. It is possible to have some elements that report but are not connected to a report port. Any reporting elements not connected to a report port take on the default behavior and report at the macro level, as described in the Default Reporting Behavior section.

Those connected to the report port will behave according to the report port description.

Report Grouping

In some instances it may be desirable to group different report nodes together. For example, consider salutations where you want an automata network that generates a report event when the text "cheers," "cordially," "respectfully," "sincerely," and so forth is detected. Specific automata could be constructed to search for each of these individual phrases; however, it would be helpful to group together all of the report events so that whenever a closing statement is found (regardless of which one) a single "closing statement found" report event is created.

Two methods are available for creating a grouping of report events:

  • Report codes
  • Macro report ports

Report Codes

A report code can be assigned to any reporting resource in an automata network. The report code is a number larger than 0x80000000. Multiple automata resources can be assigned the same report code.

Macro Report Ports

For resources within a macro, a report port can be used to group together different reporting resources. Any number of reporting resources can be connected to a single report port. When any of these resources generates a report event, the report event will be associated with the macro instance and the specific report port to which the reporting element is connected.

A report event is presented as a two-element list. The first item in the list is the reportcode. The second element in the list is the ID of the reporting element. In the case of a macro, this is a string of the format macro:report-port.

Table 1. Report Event Format
Non-macro reports ( [reportcode], id)
Macro reports ( [reportcode], macro reference id[:report-port id])

If there is no report code, that part of the two-element list will be empty. The second part of the two-element list will always be populated. In the case where a canonical resource is generating the report event, the ID of that resource will be the second element of the list. In the case where the reporting element is contained within a macro, the top-level macro ID will be the second element of the list. And if the reporting resource is connected to a report port, the macro ID will be followed by a semicolon, followed by the report port ID.

If there are reporting resources that are related to each other, they can all connect to the same report port. Therefore, the report port can aggregate together a set of reporting resources, and if any of them report, the report event will be associated with the containing macro reference and the port to which they are connected.

One pathological case is possible: Different reporting elements within a macro could be assigned different report codes, but they could all be tied to the same report port of that macro. (For instance, they all recognized the same input symbol, and that symbol was presented in the input stream.) All of these reporting elements would match the input symbol, and that would trigger the creation of a report event where the macro reference ID and the report-port were known, but the report code could legitimately be any one of the different report codes assigned to the different resources. In this case, the actual report code presented is undefined. This type of inconsistency should be avoided . However, having distinct report codes implies the designer wants to distinguish these report events separate from each other. But the designer has also tied all of the elements to the same report port in the macro, implying the reports should be grouped together.