Ξ
Δ
◄
►
¬
Ѕ
Filter
Directives
Built-in Variables
Built-in Functions
Control Flow Statements
Operators
Declarations
Commands
Sub-commands
Built-in Methods/Properties
Ahk2Exe Compiler
Highlight keywords
</head> <body> <h1>FileAppend</h1> <p>Writes text to the end of a file (first creating the file, if necessary).</p> <pre class="Syntax"><span class="func">FileAppend</span> <span class="optional">, Text, Filename, Encoding</span></pre> <h2 id="Parameters">Parameters</h2> <dl> <dt>Text</dt> <dd><p>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 <a href="../Scripts.htm#continuation">continuation section</a>.</p> <p>If <em>Text</em> is blank, <em>Filename</em> will be created as an empty file (but if the file already exists, its modification time will be updated).</p> <p>If <em>Text</em> is <a href="../misc/Clipboard.htm#ClipboardAll">%ClipboardAll%</a> or a variable that was previously assigned the value of ClipboardAll, <em>Filename</em> will be unconditionally overwritten with the entire contents of the clipboard (i.e. <a href="FileDelete.htm">FileDelete</a> is not necessary).</p></dd> <dt>Filename</dt> <dd><p>The name of the file to be appended, which is assumed to be in <a href="../Variables.htm#WorkingDir">%A_WorkingDir%</a> if an absolute path isn't specified. The destination directory must already exist.</p> <p><strong>End of line (EOL) translation</strong>: 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: <code>*C:\My Unix File.txt</code>.</p> <p>If the file is not already open (due to being inside a <a href="LoopReadFile.htm">file-reading loop</a>), EOL translation is automatically disabled if <em>Text</em> 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 <em>Text</em> contains `r`n improves performance because the program does not need to scan <em>Text</em> for `r`n.</p> <p id="stdout"><strong>Standard Output (stdout)</strong>: Specifying an asterisk (*) for <em>Filename</em> causes <em>Text</em> to be sent to standard output (stdout). Such text can be redirected to a file, piped to another EXE, or captured by <a href="_ErrorStdOut.htm">fancy text editors</a>. For example, the following would be valid if typed at a command prompt:</p> <pre class="no-highlight">"%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script.ahk" >"Error Log.txt"</pre> <p>However, text sent to stdout will not appear at the command prompt it was launched from. This can be worked around by 1) <span class="ver">[v1.1.33+]</span> compiling the script with the <a href="../misc/Ahk2ExeDirectives.htm#ConsoleApp">Ahk2Exe ConsoleApp directive</a>, or 2) piping a script's output to another command or program. For example:</p> <pre class="no-highlight">"%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script.ahk" |more</pre> <pre class="no-highlight">For /F "tokens=*" %L in ('""%ProgramFiles%\AutoHotkey\AutoHotkey.exe" "My Script .ahk""') do @Echo %L</pre> <p><span class="ver">[v1.1.20+]:</span> Specifying two asterisks (**) for <em>Filename</em> causes <em>Text</em> to be sent to the standard error stream (stderr).</p> </dd> <dt>Encoding</dt> <dd><p><span class="ver">[AHK_L 42+]:</span> Overrides the default encoding set by <a href="FileEncoding.htm">FileEncoding</a>, where <em>Encoding</em> follows the same format.</p></dd> </dl> <h2 id="Error_Handling">Error Handling</h2> <p><span class="ver">[v1.1.04+]</span>: This command is able to throw an exception on failure. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p> <p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 if there was a problem or 0 otherwise.</p> <p><a href="../Variables.htm#LastError">A_LastError</a> is set to the result of the operating system's GetLastError() function.</p> <h2 id="Remarks">Remarks</h2> <p>To overwrite an existing file, delete it with <a href="FileDelete.htm">FileDelete</a> prior to using FileAppend.</p> <p>The target file is automatically closed after the text is appended (except when FileAppend is used in its single-parameter mode inside a <a href="LoopReadFile.htm">file-reading/writing loop</a>).</p> <p><span class="ver">[AHK_L 42+]:</span> <a href="FileOpen.htm">FileOpen()</a> 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 <code>file.<a href="../objects/File.htm#Write">Write</a>(string)</code> to append the string. File objects also support binary I/O via <a href="../objects/File.htm#RawWrite">RawWrite</a>/<a href="../objects/File.htm#RawRead">RawRead</a> or <a href="../objects/File.htm#WriteNum">Write<i>Num</i></a>/<a href="../objects/File.htm#ReadNum">Read<i>Num</i></a>, whereas FileAppend supports only text.</p> <h2 id="Related">Related</h2> <p><a href="FileOpen.htm">FileOpen()</a> / <a href="../objects/File.htm">File Object</a>, <a href="FileRead.htm">FileRead</a>, <a href="LoopReadFile.htm">file-reading loop</a>, <a href="FileReadLine.htm">FileReadLine</a>, <a href="IniWrite.htm">IniWrite</a>, <a href="FileDelete.htm">FileDelete</a>, <a href="OutputDebug.htm">OutputDebug</a>, <a href="../Scripts.htm#continuation">continuation sections</a></p> <h2 id="Examples">Examples</h2> <div class="ex" id="ExBasic"> <p><a class="ex_number" href="#ExBasic"></a> Creates a file, if necessary, and appends a line.</p> <pre>FileAppend, Another line.`n, C:\My Documents\Test.txt</pre> </div> <div class="ex" id="ExContSect"> <p><a class="ex_number" href="#ExContSect"></a> Use a <a href="../Scripts.htm#continuation">continuation section</a> to enhance readability and maintainability.</p> <pre>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</pre> </div> <div class="ex" id="FTP"> <p><a class="ex_number" href="#FTP"></a> Demonstrates how to automate FTP uploading using the operating system's built-in FTP command. This script has been tested on Windows XP.</p> <pre>FTPCommandFile := A_ScriptDir "\FTPCommands.txt" FTPLogFile := A_ScriptDir "\FTPLog.txt" FileDelete %FTPCommandFile% <em>; In case previous run was terminated prematurely.</em> FileAppend, <em>; The comma is required in this case.</em> ( 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% <em>; Delete for security reasons.</em> Run %FTPLogFile% <em>; Display the log for review.</em></pre> </div> </body> </html>