Difference between revisions of "WriteTextFile"

Latest revision as of 01:13, 4 March 2021

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

WriteTextFile(filename, text, append, warn, sep, showDialog, encoding, download)

Write «text» value to a file with name «filename».

Optional parameters

«append»: Default False. If the file exists and «append» is True, it appends the text to the end of the file. If it doesn't exist and «warn» is True , it asks whether to create the file.

«warn»: Default True. If «warn» is False, it suppresses the warning that the file already exists when «append» is false or that it does not exist when «append» is True.

«showDialog»: Default Undefined -- i.e. it shows a file browser dialog only if the indicated filename is a folder, a read-only file, or if it exists and «warn» is True, or if it does not exist and «append» is True. When «showDialog» is True, it always opens a dialog before with file name as the default to let the user change file name or folder. When False, it never shows a dialog but may generate an error when trying to overwrite an existing file with «append» False.

«sep»: (Default is a new line.) Character to use as a separator between elements when «text» is an array.

«encoding» (Default "ANSI".) Specifies how to encode characters in the file:

"ANSI" : One byte per character, ISO-8859-1. Extended characters (above ascii 255) are written as ?.
"UTF-8" : UTF-8 encoding with a byte order mark (BOM). The UTF-8 encoding uses one byte for comman characters, and 2-3 bytes for characters with ascii values above 127.
"-UTF-8" : UTF-8 encoding without a BOM.
"UTF-16" : Two bytes per character, big endian, with BOM.
"UTF-16le" : Two bytes per character, little endian, with BOM.

«download»: This is only used when running the model in ACP. When set to True, the «text» is downloaded onto the end-user's computer as a text file with the given «filename».

History

Introduced in Analytica 4.0.

«encoding» parameter introduced in Analytica 4.5.

«download» parameter introduced in Analytica 6.0.

@@ Line 1: / Line 1: @@
 [[category:System Functions]]
 [[category:Database Functions]]
+[[category:File system functions]]
 [[Category:Doc Status D]] <!-- For Lumina use, do not change -->
+{{ReleaseBar}}
-== WriteTextFile(filename, text'', append, warn, sep, showDialog, encoding'') ==
+== WriteTextFile(filename, text'', append, warn, sep, showDialog, encoding{{Release|6.0||, download}}'') ==
-Writes text to a file with name «filename».
+Write  «text» value to a file with name «filename».
-If the file exists, and «append» is <code>True</code>, it appends the text to the end of the file. If it doesn't exist, it asks whether to create it. If «append» is <code>False</code>, and the file exists, if «warn» is <code>True</code>, it gives a warning to ask if you want to overwrite the file. Setting «warn» to <code>False</code>, suppresses the warning about the file already existing.
+=== Optional parameters ===
-The optional «showDialog» flag controls whether the file dialog displays.  If not specified, then the dialog appears if the indicated filename is a folder, a read-only file, or if it exists and «warn» is <code>True</code>.  When «showDialog» parameter is <code>True</code>,  it always opens a dialog before creating the file, so user can change file name and select folder -- the dialog displays, using the indicated filename as a default value but allowing the user to change it.  When <code>False</code>, the dialog is suppressed in all cases (usually meaning an error is issued instead).
+«append»: Default  <code>False</code>. If the file exists and «append» is <code>True</code>, it appends the text to the end of the file. If it doesn't exist and «warn» is <code>True</code> , it asks whether to create the file.
-[[WriteTextFile]] uses «sep» as a line separator between elements when «text» is an array.
+«warn»: Default  <code>True</code>.  If «warn» is <code>False</code>, it suppresses the warning that the file already exists when «append» is false or that it does not exist when «append» is True.
-(new to [[Analytica 4.5]]) «encoding» parameter specifies the character encoding. Possible values are:
+«showDialog»:  Default  <code>Undefined</code> -- i.e.  it shows a file browser dialog only if the indicated filename is a folder, a read-only file, or if it exists and «warn» is <code>True</code>, or if it does not exist and «append» is <code>True</code>.  When «showDialog» is <code>True</code>,  it always opens a dialog before with file name as the default to let the user change file name or folder.  When <code>False</code>,  it never shows a dialog but may generate an error when trying to overwrite an existing file with «append» False.
+«sep»:  (Default is a new line.) Character to use as a separator between elements when «text» is an array.
+«encoding» (Default <code>"ANSI"</code>.) Specifies how to encode characters in the file:
 * <code>"ANSI"</code> : One byte per character, [http://en.wikipedia.org/wiki/8859 ISO-8859-1]. Extended characters (above ascii 255) are written as ?.
 * <code>"UTF-8"</code> : [http://en.wikipedia.org/wiki/UTF-8 UTF-8 encoding] with a [http://en.wikipedia.org/wiki/Byte_order_mark byte order mark] ([http://en.wikipedia.org/wiki/Byte_order_mark BOM]). The UTF-8 encoding uses one byte for comman characters, and 2-3 bytes for characters with ascii values above 127.
@@ Line 20: / Line 26: @@
 * <code>"UTF-16"</code> : Two bytes per character, big endian, with BOM.
 * <code>"UTF-16le"</code> : Two bytes per character, little endian, with BOM.
+{{Release|6.0||
+«download»: This is only used when running the model in [[ACP]]. When set to <code>True</code>, the «text» is downloaded onto the end-user's computer as a text file with the given «filename». }}
 ==History==
 Introduced in [[What's new in Analytica 4.0?|Analytica 4.0]].
+«encoding» parameter introduced in [[Analytica 4.5]].
+«download» parameter introduced in [[Analytica 6.0]].
 == See also ==
 * [[ReadTextFile]]
+* [[Read and write text files]]
+* [[MakeCSV]]
+* [[MakeJSON]]
+* [[Text functions]]
 * [[WriteBinaryFile]]
 * [[CurrentDataFolder]]
 * [[Model File Character Encoding]]
 * [[Files and Editing]]