TPL file structure

This section describes the TPL file structure.

Typographical conventions

The description of the Pattern Language uses a number of typographical conventions to distinguish items, as follows:

• fixed pitch font — TPL code fragments.
• italic fixed pitch — Items to be replaced in code fragments.
• bold fixed pitch — TPL keywords.
• [items in square brackets] — optional items.

Pattern language files are simple flat text files, using UTF-8 character encoding.

TPL is a case sensitive language.

Comments are prefixed with two slash characters, as in C++ and Java:

  // This is a comment

The first non-blank, non-comment line must consist of a declaration of the form:

  tpl 1.n module module.name;

where module.name is a dot-separated name for the module in the module hierarchy. The 1.n specifies the version of TPL the module conforms to. See What's new in TPL for information on the latest version. Patterns can fail to activate if they use features that are not available in the version declared in the module.

Following the module declaration, there can be any number of the following kinds of declaration, in any order that satisfies references between declarations:

• Import statements are used to import referenced declarations from other files.
• Pattern declarations define patterns, which are responsible for identifying entities and building the model.
• Table declarations are used to create look-up tables to be used in patterns.
• Identify table declarations define active look-up tables that automatically set identifying attributes on matching nodes.
• Configuration declarations define end-user editable configuration items.
• Definitions blocks are used to specify integration queries.

The statements and declarations are described in detail in the following sections.

Common declarations

A number of kinds of declarations can occur throughout pattern files.

Strings

Literal strings can be declared in four ways:

• Started with a single quote character, terminated by an unescaped single quote; cannot contain newline characters.
• Started with a double quote character, terminated by an unescaped double quote; cannot contain newline characters.
• Started with three single quote characters, terminated by three unescaped single quotes; can include newline characters.
• Started with three double quote characters, terminated by three unescaped double quotes; can include newline characters.

Triple-quoted strings are often used for multi-line string literals, especially for description strings in declarations.

The escape character for strings is the backslash "\". A backslash preceding a quote prevents it from terminating a string.

Strings can be "qualified" by prefixing them with a single identifier. The supported identifiers are:

• No qualifier — characters prefixed with backslashes are converted to special characters using the same rules as Python unicode strings, as shown in String Escape Characters. String interpolation using % characters occurs, as described in section string interpolation.

• raw — backslashes do not create special characters, and string interpolation does not occur. Backslashes preceding a closing quote character still prevent closure of the string, but the backslash remains part of the string. i.e. in the string: raw 'test\'quote' both the backslash and the quote appear in the string value.

• regex — indicates that the string value is a regular expression. The contents are handled in the same way as raw strings.

• windows_cmd — the string contains the name of a Windows executable to be identified in a process command line. It turns into a suitable regular expression for identifying the process, formed by prefixing the given string with "(?i)\b" and suffixing it with "\.exe$".

• unix_cmd — the string contains the name of a UNIX executable to be identified in a process command line. It turns into a suitable regular expression for identifying the process, formed by prefixing the given string with "\b" and suffixing it with "$".

Numbers

Literal numbers are integers. Integers are in base 10 unless prefixed with 0x in which case they are hexadecimal. Integers are signed 64 bit values.

Booleans

Literal booleans are true and false.

None

The value none represents the absence of any other value.

void

Assigning this to an attribute in the model deletes the attributes. The statement node['attribute_name'] := void; is the equivalent of del node ['attribute_name']

Identifiers

Identifiers used for names of variables, patterns, tags, and so on are comprised of only ASCII characters. They start with a letter or underscore character and contain letters, underscores and numbers. Names starting with two underscore characters are reserved for the system.

If it is necessary to declare an identifier with a name that clashes with a keyword, the keyword can be used prefixed with a $ character.

Tags

Many declarations contain tags, used to classify them with arbitrary names. Tags are useful when searching for declarations. Tags have the format:

  tags tag_value [ , tag_value, ... ];

Tag values must be valid identifiers. No meaning is attached to tags by the pattern language.

Data types

All data values in TPL have a type, such as text strings and integers. Patterns must be careful to be consistent in the use of types. It is an execution-time error to attempt to add an integer to a text string, for example.

When attributes are set on datastore nodes and relationships, the attributes are set with the types of the supplied values, regardless of any type definitions in the taxonomy.

The types supported in TPL are: text string, integer, time, list and table. Each list or table member has its own type; usually each member has the same type, but lists and tables are permitted to have mixed-type members. List is a valid list member type, so lists can be arbitrarily nested.