Difference between revisions of "WriteTextFile"

(See also)
m
Line 6: Line 6:
 
== WriteTextFile(filename, text'', append, warn, sep, showDialog, encoding'') ==
 
== WriteTextFile(filename, text'', append, warn, sep, showDialog, encoding'') ==
  
Writes text to a file with name «filename».
+
Writes «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, it asks whether to create the file. If «append» is <code>False</code>, and the file exists, and «warn» is <code>True</code>, it gives a warning to ask if you want to overwrite 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> -- 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>.  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>"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] 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 23: Line 27:
 
==History==
 
==History==
 
Introduced in [[What's new in Analytica 4.0?|Analytica 4.0]].
 
Introduced in [[What's new in Analytica 4.0?|Analytica 4.0]].
 +
«encoding» parameter introduced in [[Analytica 4.5]].
  
 
== See also ==
 
== See also ==

Revision as of 19:42, 24 August 2020


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

Writes «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, it asks whether to create the file. If «append» is False, and the file exists, and «warn» is True, it gives a warning to ask if you want to overwrite 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 -- 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. 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.

History

Introduced in Analytica 4.0.

«encoding» parameter introduced in Analytica 4.5.

See also

Comments


You are not allowed to post comments.