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 -->
-[[What's new in Analytica 4.0?]] >
+{{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 true, it appends the text to the file. If it doesn't exist, it asks whether to create it.
+=== Optional parameters ===
-If append is false, and the file exists, if warn is true, it gives a warning to ask if you want to overwrite the file.
-If
-(new to 4.0) The optional «showDialog» flag controls whether the file dialog displays.  If not specified, then the dialog appears if the indicated filename is a directory, a read-only file, or if it exists and warn is true.  When «showDialog» is true, the dialog displays, using the indicated filename as a default value but allowing the user to change it.  When false, 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.
-Setting «append» to true appends to the end of an existing file.
+«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.
-Setting «warn» to false suppresses the warning about the file already existing.
+«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.
-It uses «sep» as a line separator between elements when «text» is an array.
+«sep»:  (Default is a new line.) Character to use as a separator between elements when «text» is an array.
-If «showdialog» is true, it always opens a dialog before creating the file, so user can change file name and select folder. If false, it suppresses the dialog in all cases.
+«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.
+*<code> "-UTF-8"</code> : [http://en.wikipedia.org/wiki/UTF-8 UTF-8 encoding] without a BOM.
+* <code>"UTF-16"</code> : Two bytes per character, big endian, with BOM.
+* <code>"UTF-16le"</code> : Two bytes per character, little endian, with BOM.
-(new to [[Analytica 4.5|4.5]]) «Encoding» specifies the character encoding. Possible values are:
+{{Release|6.0||
-* "ANSI" : One byte per character, [http://en.wikipedia.org/wiki/8859 ISO-8859-1]. Extended characters (above ascii 255) are written as ?.
+«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». }}
-* "UTF-8" : [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.
-* "-UTF-8" : [http://en.wikipedia.org/wiki/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.
-= See also =
+==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]]
-* [[CurrentDataDirectory]]
+* [[Read and write text files]]
+* [[MakeCSV]]
+* [[MakeJSON]]
+* [[Text functions]]
+* [[WriteBinaryFile]]
+* [[CurrentDataFolder]]
+* [[Model File Character Encoding]]
+* [[Files and Editing]]