FileAppend

Writes text or binary data to the end of a file (first creating the file, if necessary).

OutputVar := FileAppend(Text, Filename , Encoding)

Command  Example: FileAppend "text", A_ScriptDir "\MyFile.txt"
Function Example: Success := FileAppend("text",A_ScriptDir "\MyFile.txt")

Parameters

Text

The text to append to the file. This text may include linefeed characters (`n) to start new lines. In addition, a single long line can be broken up into several shorter ones by means of a continuation section.

Text can contain binary data if the RAW option is used, but in that case FileAppend will always append an even number of bytes (StrLen times two). This can be used to save clipboard data to file. File.RawWrite can be used to write an odd or even number of bytes.

If Text is blank, Filename will be created as an empty file (but if the file already exists, its modification time will be updated).

Filename

The name of the file to be appended, which is assumed to be in A_WorkingDir if an absolute path isn't specified.

Standard Output (stdout): Specifying an asterisk (*) for Filename causes Text to be sent to standard output (stdout). Such text can be redirected to a file, piped to another EXE, or captured by fancy text editors. For example, the following would be valid if typed at a command prompt:

"%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script.ahk" >"Error Log.txt"

However, text sent to stdout will not appear at the command prompt it was launched from. This can be worked around by piping a script's output to another command or program. For example:

"%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script.ahk" |more

For /F "tokens=*" %L in ('""%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script .ahk""') do @Echo %L

Specifying two asterisks (**) for Filename causes Text to be sent to the stderr stream.

Options

Zero or more of the following strings. Separate each option from the next with a single space or tab. For example: "`n UTF-8"

Encoding: Specify any of the encoding names accepted by FileEncoding (excluding the empty string) to use that encoding if the file lacks a UTF-8 or UTF-16 byte order mark. If omitted, it defaults to A_FileEncoding.

RAW: Specify the word RAW (case-insensitive) to write the exact bytes contained by Text to the file as-is, without any conversion. This option overrides any previously specified encoding and vice versa.

`n (a linefeed character): Inserts a carriage return (`r) before each linefeed (`n) if one is not already present. In other words, it translates from `n to `r`n. This translation typically does not affect performance. If this option is not used, line endings within Text are not changed.

ErrorLevel

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

A_LastError is set to the result of the operating system's GetLastError() function.

Remarks

To overwrite an existing file, delete it with FileDelete prior to using FileAppend.

The target file is automatically closed after the text is appended (except when FileAppend is used in its single-parameter mode inside a file-reading/writing loop).

FileOpen() in append mode provides more control than FileAppend and allows the file to be kept open rather than opening and closing it each time. Once a file is opened in append mode, use file.Write(string) to append the string. File objects also support binary I/O via RawWrite/RawRead or WriteNum/ReadNum.

Related

FileOpen/File Object, FileRead, file-reading loop, IniWrite, FileDelete, OutputDebug, continuation sections

Example

FileAppend "Another line.`n", "C:\My Documents\Test.txt"

; The following example uses a continuation section to enhance readability and maintainability:
FileAppend "
(
A line of text.
By default, the hard carriage return (Enter) between the previous line and this one will be written to the file.
	This line is indented with a tab; by default, that tab will also be written to the file.
)", A_Desktop "\My File.txt"

; The following example demonstrates how to automate FTP uploading using the operating 
; system's built-in FTP command. This script has been tested on Windows XP.

FTPCommandFile := A_ScriptDir "\FTPCommands.txt"
FTPLogFile := A_ScriptDir "\FTPLog.txt"
FileDelete FTPCommandFile  ; In case previous run was terminated prematurely.

FileAppend "
(Q
open host.domain.com
username
password
binary
cd htdocs
put " VarContainingNameOfTargetFile "
delete SomeOtherFile.htm
rename OldFileName.htm NewFileName.htm
ls -l
quit
)", FTPCommandFile

RunWait A_ComSpec ' /c ftp.exe -s:"' FTPCommandFile '" >"' FTPLogFile '"'
FileDelete FTPCommandFile  ; Delete for security reasons.
Run FTPLogFile  ; Display the log for review.