Scanner

Successive Scanner statements can be used to analyze pretty much any kind of data. The function operates on the data in a field or a named variable.

You can choose to ignore whitespace characters and newline characters at the start of the field being scanned. When these characters are found, they are not retained when storing the result and do not affect the match process.

All text fields may contain any of the escape sequences described in Escape Sequences. With functions tat are text oriented, you can specify that the function is case insensitive.

Each of the supported scanning functions return true on success or false on failure. On success the specified results variable will contain the result of the successful match. The specified remainder variable will contain all text after the scanned item. On failure, the results variable will be empty and the remainder variable will be the same as the field value.

When executing stepwise the result of the scan is only true if each track's scan returned true. The result can optionally be negated via the Not option. You can specify that the result of the scan (after an optional Not) be copied to the action test state (Set, Anded or Ored into the existing value).

When operating on named variables the statement is only executed once, regardless of the current execution mode. When the source is a named variable the result and remainder fields must also be named variables.

The following scanning functions are available:

Scan Integer: Attempt to scan a positive or negative integer value. Note that on success the results variable may not exactly match the data as scanned. This is due to the fact that the integer is extracted as a binary value and is converted back to a string value. For example 0123 will be returned as 123. A result of true implies that an integer was scanned.
Scan Unsigned Integer: Same as Scan Integer except the value scanned must be greater than or equal to 0.
Scan Number: Attempt to scan a number which optionally contains a fractional component. Note that on success the results variable may not exactly match the data as scanned. This is due to the fact that the number is extracted as a binary value and is converted back to a string value. For example 123 will be returned as 123.0. A result of true implies that a number was scanned.
Scan Hexadecimal: Attempt to scan a hexadecimal value and save it as an integer. A result of true implies that a value was scanned. A leading 0x is optional.
Scan Integer or Hexadecimal: If the source starts with a 0x sequence a hexadecimal value will be scanned and saved as an integer. If the source does not start with a 0x sequence the function is identical to Scan Integer. A result of true implies that a value was scanned.
Scan Unsigned Integer or Hexadecimal: If the source starts with a 0x sequence a hexadecimal value will be scanned and saved as an integer. If the source does not start with a 0x sequence the function is identical to Scan Unsigned Integer. A result of true implies that a value was scanned.
Scan String: Attempt to scan a string specified in the qualifier field. A result of true implies that the qualifier string was found at the effective start of the source.
Scan up to String: Scan all characters up to a specified string specified in the qualifier field. If the qualifier field is not found all characters in the source will have been scanned. On success at least one character will have been scanned. This means that if the qualifier is at the effective start of the source, no characters will be scanned and the result will be false.
Scan Characters: Scan all characters which are specified in the effective set of characters. On success at least one character will have been scanned. The effective set of characters is the union of the characters specified in the qualifying string and any character sets selected by the gear button. Note that the case insensitive option is only applied to the characters in the qualifying string and not to any configured character sets. The character sets are defined in the help for the Trim statement. You can use the Inverted option to invert the effective set. For example if you select Alphanumeric and Inverted is enabled, the effective set is all characters except alphanumeric characters.
Scan up to Characters: The same as Scan Characters except that all characters up to the first character not in the effective set (or the end of the source) will be scanned.
Scan Roman Numeral: Attempt to scan a Roman numeral. Note that only valid Roman numerals will cause the scan to succeed.
Scan Roman Numeral as Integer: Attempt to scan a Roman numeral. Note that only valid Roman numerals will cause the scan to succeed. The Result field will contain the integer value of the scanner Roman numeral. eg. VI will return 6.
Scan Bracketed String: You can test for a string bracketed by the sample left and right delimiters or a different left and right delimiter. When using two delimiters, the qualifier field must contain a single default list delimiter (\~) sequence. The first item is treated as a left delimiter. The second as a right delimiter. Both delimiters must not be empty. The string being scanned must start with the left delimiter. The function returns all text bracketed by a balanced left and right delimiter. When two delimiters are supplied and they are not the same, nested left and right delimiters are handled correctly. For example a left delimiter of ( and a right delimiter of ) with a source of ((abc)def)ghi would return ((abc)def). When there is only one delimiter this is not the case. For example a single delimiter of " with a source of "test1"test2" will return "test1".
Scan Bracketed Content: This is identical to Scan Bracketed String except that the delimiters are not returned in the result.

You can choose to save the per file results to a track variable. This is not supported with named variable usage. When setting a track variable, the Set, And, Or semantics are applied, therefore cumulative tests will be saved as expected. Note that Not if specified is performed before the Set, And or Or. The result stored to a track variable will always be a 0 or 1.

Information on alternate means of parsing or scanning

File to Tag From Content