FileAppend

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

FileAppend , Text, Filename, Encoding

Parameters

Text

If blank or omitted, Filename will be created as an empty file (but if the file already exists, its modification time will be updated). Otherwise, specify 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.

If Text is %ClipboardAll% or a variable that was previously assigned the value of ClipboardAll, Filename will be unconditionally overwritten with the entire contents of the clipboard (i.e. FileDelete is not necessary).

Filename

If this and the Encoding parameter are omitted, the output file of the innermost enclosing file-reading loop will be used (if available). Otherwise, specify the name of the file to be appended, which is assumed to be in %A_WorkingDir% if an absolute path isn't specified. The destination directory must already exist.

End of line (EOL) translation: To disable EOL translation, prepend an asterisk to the filename. This causes each linefeed character (`n) to be written as a single linefeed (LF) rather than the Windows standard of CR+LF. For example: *C:\My Unix File.txt.

If the file is not already open (due to being inside a file-reading loop), EOL translation is automatically disabled if Text contains any carriage return and linefeed pairs (`r`n). In other words, the asterisk option described in the previous paragraph is put into effect automatically. However, specifying the asterisk when Text contains `r`n improves performance because the program does not need to scan Text for `r`n.

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 1) [v1.1.33+] compiling the script with the Ahk2Exe ConsoleApp directive, or 2) 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

[v1.1.20+]: Specifying two asterisks (**) for Filename causes Text to be sent to the standard error stream (stderr).

Encoding [AHK_L 42+]

If blank or omitted, the default encoding (as set by FileEncoding or CP0 otherwise) will be used. Otherwise, specify the encoding or code page, e.g. UTF-8, UTF-16 or CP936.

If the file contains a UTF-8 or UTF-16 byte order mark (BOM), this parameter and the default encoding will be ignored.

Error Handling

[v1.1.04+]: This command is able to throw an exception on failure. For more information, see Runtime Errors.

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).

[AHK_L 42+]: 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, whereas FileAppend supports only text.

FileEncoding, FileOpen() / File Object, FileRead, file-reading loop, FileReadLine, IniWrite, FileDelete, OutputDebug, continuation sections

Examples

Creates a file, if necessary, and appends a line.

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

Use 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.
Variable references such as %Var% are expanded by default.
), C:\My File.txt

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,  ; The comma is required in this case.
(
open host.domain.com
username
password
binary
cd htdocs
put %VarContainingNameOfTargetFile%
delete SomeOtherFile.htm
rename OldFileName.htm NewFileName.htm
ls -l
quit
), %FTPCommandFile%

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