# Read Text File

The Read Text File statement is used to read the contents of a file. The text is saved to a named variable.

Both of the supplied strings may contain any of the escape sequences described in Escape Sequences. The resultant file path may be absolute (/), relative to the Home folder (~/) or relative to the track's containing folder (./) or (../). Any path which does not exist or is invalid is ignored.

The typical method of reading a file is to let the OS determine the encoding. This encoding is represented as Automatic. If the OS cannot determine the encoding of a file and you want to explicitly specify it, you may choose an encoding from the available list.

While this statement is valid in all execution modes, it will typically be performed in stepwise mode so that the file is read only once. When run stepwise any track variables referenced in the supplied strings are taken from the first selected file and a relative path is relative to that same file.

If the file is successfully read the action test state will be set to true. If the contents cannot be saved, either because the file does not exist or cannot be converted to a text encoding, the destination named variable will be set to empty and the action test state will be set to false.

When a file is successfully read, the named variable Read Text File Encoding will be set to a human readable description of the encoding used to read the file. If the file could not be read due to an encoding issue, the Read Text File Encoding named variable will be set to Indeterminate. If the file cannot be read for any other reason, the Read Text File Encoding named variable will be empty.

# Special Considerations when reading plist files

plist files may be encoded as binary. If a plist file cannot be read as text, Yate will attempt to convert the file to text at a temporary location. If the conversion succeeds and the file can be read, the Read Text File Encoding named variable will be set to Binary plist.

plist files can be read directly into a container by means of the Read/Write Plist File statement.