Parsing Arbitrary String Data
|Top Previous Next|
Parsing string data is accomplished using the String and StringTokenizer objects. The String object provides a Split method for dividing the string into parts, and the StringTokenizer object breaks the string into tokens which are separated by delimiters (a character or sequence of characters). This page covers the following topics:
Literal strings prefixed with the special character @ will be scanned for environment variables and escape sequences.
The supported escape sequences are as follows.
The following example demonstrates how to use the @ symbol to scan a literal string in a Report command for environment variables and escape sequences. The \t and \n sequences are translated to tabs and line feeds, and the backslash, dollar sign, and percent sign are escaped.
Environment variables can be evaluated at parse time inside of any literal string scanned using the @ character, using the syntax $(EnvironmentVariableName). This example shows how to report an environment variable called "myEnvironmentVariable" that has been defined on your system:
It is important to note that the value of the environment variable inside a scanned literal string will be evaluated when the Mission Plan is parsed. This means that if you were to change the value of the environment variable in your Mission Plan and then report it inside a scanned string, the original value would be reported; not your updated value. If you want to evaluate the environment variable at runtime, the FF_Preferences.GetEnvironmentVariable("EnvironmentVariableName") method can be used. In the following example, the user changes the value of "myEnvironmentVariable" at the beginning of the script, but the value that is reported in the scanned string will reflect the original value of the environment variable from when the Mission Plan was parsed. The value reported by the GetEnvironmentVariable() method will have the updated value that was specified in script.
The ability to access environment variables at parse time is important when the path to a Procedure is set using an environment variable. The Include command needs to evaluate the path to the Procedure when the Mission Plan is parsed. The example below shows how to use the @ symbol to tell FreeFlyer to scan the literal string in an Include statement for environment variables and escape sequences. The $() sequence indicates that the environment variable "myEnvironmentVariable" will be evaluated at parse time. The backslash in the path is escaped using a second backslash. In this example, if "myEnvironmentVariable" has been set to "C:\myDirectory\v1.3", then the Include command will evaluate to include "C:\myDirectory\v1.3\myProcedure.FFProcedure".
The StringTokenizer object allows you to split the contents of a String into a StringArray based on the specified delimiter. The following example uses a StringTokenizer object to parse a string and report out the resulting tokens.
The StringTokenizer supports multi-character delimiters. This means that you can have overlap between delimiters (e.g. "f" and "fish"). This also means that the StringTokenizer results may depend on the order that the delimiters are applied. The StringTokenizer looks for delimiters starting from the beginning of the string, and if more than one delimiter match is found at a location in the string, the delimiter that comes first in the delimiters array will be used at that location. For example, if you have two delimiters "f" and "fish" matching against "1fish2fish", there are two different possible results, depending on which delimiter appears first in the StringTokenizer.Delimiters property.
If "f" appears first:
If "fish" is first:
You can also use the StringTokenizer object to parse strings using regular expressions. Use the StringTokenizer.RegularExpression property to set the regular expression to use. FreeFlyer uses regular expressions similar to how Perl uses them. Below is a brief summary of some of the most common regular expressions used.
Regular expressions also use metacharacters, as described in the table below, to enable more complete delineation of the behavior of the regular expression when used as a delimiter. These characters typically get used alongside the expressions above to specify where a match should happen or how specific characters in the regular expression will be treated by the parser.
In addition to the metacharacters listed above, certain quantifiers exist that can be used to augment regular expressions by specifying how many of an occurrence to expect. These quantifers are captured in the table below.
The following script shows how a String can be parsed using only numbers as delimiters:
A good external resource for more information on the Perl scripting language and regular expressions is: http://perldoc.perl.org/perlre.html#Regular-Expressions
Example: Variable.IFormat Method
The following example converts the Integer values "9" and "32" to an ASCII tab character and space character using the Variable.IFormat method. These characters are then added as delimiters to a StringTokenizer Object.
For other ASCII conversion values, consider visiting: http://www.theasciicode.com.ar/
•String Properties and Methods
•StringTokenizer Properties and Methods
•Syntax and the FreeForm Script Editor: Inline Strings Section
•Interfacing with Files: Reading Arbitrary File Formats Section