Difference between revisions of "ReadTextFile"

Latest revision as of 18:29, 3 June 2025

Release:	4.6 • 5.0 • 5.1 • 5.2 • 5.3 • 5.4 • 6.0 • 6.1 • 6.2 • 6.3 • 6.4 • 6.5 • 6.6

(Requires Analytica Enterprise, Optimizer, or Power Player)

ReadTextFile(filename, showDialog, title)

Returns the contents a text file «filename» as a text value. «filename» may be the name of a file in the Current Data Directory (initially, the directory containing the model), or a path relative to the Current Data Directory , or an absolute pathname.

If it can't find a file with that name, by default, it opens a file browser dialog to let the user select another file. Set optional parameter, «showDialog» to True (1) to show the file browser dialog, using «filename» as default, even if the file exists. Set «showDialog» to False (0) to never show it. If it can't find the file, it shows an error message.

You can specify the caption for the title bar of the file browser dialog titlebar in the optional «title» parameter.

ADE never shows the file browser dialog, no matter what the parameter values.

Treating End-of-line

There are three common standards in text-files to identify newlines:

Windows files usually use the two-character sequence CRLF -- Chr(10) Chr(13)
Unix files use a single LF character -- Chr(10)
Macintosh OS files use a single CR character -- Chr(13)

Occasional Windows-based programs use one of the other standards.

ReadTextFile insulates you from worrying about which standard is used by converting each to the Unix standard, a single LF -- Chr(10).

If a file contains inconsistent line breaks -- e.g. including more than one examples of LF, CRLF, and CR -- it converts LF and CRLF to a single LF, and leaves CR -- Chr(13) -- as is.

Getting the file name actually opened

Your code may want to know the file path for which file was actually opened. This may differ from «filename» when the specified file is not found, or when «showDialog» forces a dialog, allowing the user to select a different file. ReadTextFile returns the file path as a second return value, which you can optionally capture using, e.g.,

Local (contents, filepath) := ReadTextFile( ... );

A common pattern is that you may want to save the filename in a variable such that when the evaluation is repeated in the future, it can supply the file selected by the user to the «filename» parameter. This can be coded by supplying first a global variable to hold the filename defined using ComputedBy with the default filename as follows:

Variable TheFilename ::=

ComputedBy( TheFileContetns, "defaultFilename" )

Variable TheFileContents ::=

( , TheFilename ) := ReadTextFile( TheFilename )

The assignment to ( , TheFilename ) passes through the first parameter as the result of the assignment expression, but assigns the second return value the TheFilename. The assignment to TheFilename is a side-effect that is allowed only because TheFilename is defined as a ComputedBy. The assignment changes the value, but also rewrites the second parameter of the call to ComputedBy, thus permanently preserving the filename selected. The one line definition of TheFileContents is locally equivalent to:

Local (contents, filename ) := ReadTextFile( TheFilename );

TheFilename := filename;

contents

From ADE

When evaluated in the Analytica Decision Engine (ADE) and a dialog needs to be shown to the end-user, it calls IAdeUICallbacks::GetFilename(...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using CAEngine::SetCallbackObject( ). If it has not registered a callback and the file doesn't exist, returns an empty text.

Once the file read completes, it calls IAdeUICallbacks::FileOpenCompleted().

History

The «title» parameter was introduced in Analytica 4.6.

The callback in ADE was introduced in ADE 4.6.

@@ Line 2: / Line 2: @@
 [[category:Database Functions]]
 [[category:File system functions]]
+{{ReleaseBar}}
 ''(Requires Analytica Enterprise, Optimizer, or Power Player)''
@@ Line 42: / Line 44: @@
 The assignment to <code>( , TheFilename )</code> passes through the first parameter as the result of the assignment expression, but assigns the second return value the <code>TheFilename</code>. The assignment to <code>TheFilename</code> is a [[side-effect]] that is allowed only because <code>TheFilename</code> is defined as a [[ComputedBy]]. The assignment changes the value, but also rewrites the second parameter of the call to [[ComputedBy]], thus permanently preserving the filename selected. The one line definition of <code>TheFileContents</code> is locally equivalent to:
-:<code>[[Local]] (contents, filename ) := ReadTextFile]]( TheFilename );</code>
+:<code>[[Local]] (contents, filename ) := [[ReadTextFile]]( TheFilename );</code>
 :<code>TheFilename := filename;</code>
 :<code>contents</code>
+{{Release|1=6.6|2=|3=
+== Getting the file encoding ==
+(''New in [[Analytica 6.6]]'')
+A text file may include a Byte Mark Encoding (BOM) as the first few characters of the file. This can be captured as the fourth return value and will have one the the values:
+* [[Null]] : No BOM. Presumed to be ASCII.
+* <code>'UTF-8'</code>: Each character uses a variable number of bytes, from 1-6 depending on the character.
+* <code>'UTF-16be'</code>: 2 bytes per character, big-endian.
+* <code>'UTF-16le'</code>: 2 bytes per character, little-endian
+Example of capturing the encoding:
+:<code>[[Local]] ( contents, filepath, isUploaded, encoding ) := [[ReadTextFile]]( filename );</code>
+}}
 == From ADE ==
 When evaluated in [[ADE|the Analytica Decision Engine (ADE)]] and a dialog needs to be shown to the end-user, it calls [[IAdeUICallbacks::GetFilename]](...). From within that callback, the parent application can interact with the end-user to resolve the file path, and a web applications can instruct the end-user to upload a file. Once complete, the callback returns the full path to the file which is then read. To receive this callback, the parent application must have previously registered the callback with ADE using [[CAEngine::SetCallbackObject]]( ). If it has not registered a callback and the file doesn't exist, returns an empty text.
@@ Line 71: / Line 85: @@
 * [[NumberToText]]
 * [[Files and Editing]]
+* [[Returning multiple values]]