# FileAppend

在文件末尾处追加(写入) 文本(如果有必要, 首先创建文件).

    FileAppend , Text, Filename, Encoding

## 参数

Text

  要追加到文件的文本. 此文本可以包含换行符(`n) 来开始新行. 此外, 一个长行可以使用延续片段的方法分成较短的几行.

  如果 Text 为空, 则创建一个文件名为 Filename 的空白文件(但如果文件已经存在, 则更新其修改时间).

  如果 Text 为 %ClipboardAll% 或之前接受了 ClipboardAll 赋值的变量, 则用剪贴板的全部内容无条件覆盖 Filename(即不需要 FileDelete).

Filename

  要追加内容的文件名, 如果未指定绝对路径, 则假定在 %A_WorkingDir% 中. 目标目录必须已经存在.

  行结束符(EOL) 转换: 在文件名前面加个星号可以阻止 EOL 转换. 这使得每个换行符(`n) 被写作单个换行符(LF) 而不是 Windows 标准的 CR+LF. 例如: `*C:\My Unix File.txt`

  如果文件尚未打开(由于在文件读取循环中), 且 Text 包含任意的回车和换行符对(`r`n), 则会自动禁用 EOL 转换. 换句话说, 前一段中描述的星号选项自动生效. 不过, 当 Text 包含 `r`n 如果指定星号可以改善性能, 因为程序不需要扫描 Text 检查其中是否包含 `r`n.

  标准输出(stdout): 在 Filename 指定星号(*) 可以把 Text 发送到标准输出(stdout). 这样文本可以重定向到文件, 指向另一个 EXE 的管道或被高级文本编辑器捕获. 例如, 在命令提示符中输入后面的例子是有效的:

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

  然而, 发送到标准输出的文本将不会出现在运行它的命令提示符中. 解决此问题的方法是 1) [v1.1.33+] 使用 Ahk2Exe ConsoleApp 指令编译脚本, 或 2) 把脚本的输出通过管道传递给另一个命令或程序. 例如:

      "%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+]: 在 Filename 指定两个星号(**) 可以把 Text 发送到标准错误输出(stderr).

Encoding

  [AHK_L 42+]: 覆盖 FileEncoding 的默认设置, 其中 Encoding 遵循相同的格式.

## 错误处理

[v1.1.04+]: 此命令失败时会抛出异常. 想了解更多信息, 请参阅运行时错误.

如果遇到问题则 ErrorLevel 被置为 1, 否则为 0.

A_LastError 被设置为操作系统 GetLastError() 函数返回的结果.

## 备注

要覆盖现有的文件, 请在使用 FileAppend 前用 FileDelete 删除它.

追加文本后目标文件会自动关闭(除非在文件读取/写入循环中以单参数模式使用 FileAppend 时).

[AHK_L 42+]: 追加模式的 FileOpen() 比 FileAppend 提供了更多的控制性并且允许文件保持打开状态而不是每次打开关闭文件. 一旦以追加模式打开文件后, 请使用 `file.Write(string)` 来追加字符串. 文件对象通过 RawWrite/RawRead 或 WriteNum/ReadNum 还支持二进制 I/O, 然而 FileAppend 仅支持文本.

## 相关

FileOpen() / 文件对象, FileRead, 文件读取循环, FileReadLine, IniWrite, FileDelete, OutputDebug, 延续片段

## 示例

必要时创建一个文件, 并附加一行.

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

使用延续片段来提高可读性和可维护性.

    FileAppend,
    (
    一行文字.
    默认情况下, 前一行和这一行之间的硬回车(Enter) 将被写进文件.
        这一行缩进了一个制表符; 默认情况下, 该制表符也将被写入文件.
    变量引用, 如 %Var% 默认情况下会被展开.
    ), C:\My File.txt

演示了如何使用操作系统内置的 FTP 命令自动进行 FTP 上传. 此脚本已经在 Windows XP 中测试通过.

    FTPCommandFile := A_ScriptDir "\FTPCommands.txt"
    FTPLogFile := A_ScriptDir "\FTPLog.txt"
    FileDelete %FTPCommandFile%  ; 避免之前运行意外中止带来的问题.

    FileAppend,  ; 这里需要逗号.
    (
    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%  ; 删除以避免安全问题.
    Run %FTPLogFile%  ; 显示日志进行复查.

dftg