# FileAppend

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

    FileAppend Text , Filename, Options

## 参数

Text

  类型: 字符串或对象

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

  可以传递类似类缓冲的对象来附加文本二进制数据. 如果创建了一个文件, 只有在 选项 中指定了 "UTF-8" 或 "UTF-16" 时, 才会写入字节顺序标记(BOM). 不管 选项 是什么, 都会忽略默认编码, 对象所包含的数据按原样写入. 可以使用任何实现 Ptr 和 Size 属性的对象.

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

Filename

  类型: 字符串

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

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

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

  然而, 发送到标准输出的文本将不会出现在运行它的命令提示符中. 解决此问题的方法是 1) 使用 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

  在 Filename 指定两个星号(**) 可以把 Text 发送到标准错误输出(stderr).

Options

  类型: 字符串

  零个或多个以下字符串. 使用单个空格或制表符将每个选项与下一个选项分开. 例如: `"`n UTF-8"`

  Encoding: 如果文件缺少 UTF-8 或 UTF-16 字节顺序标记, 则指定 FileEncoding 接受的任何编码名称(不包括空字符串) 以使用该编码. 如果省略, 默认为 A_FileEncoding(除非 Text 是对象, 在这种情况下不写入字节顺序标记).

  RAW: 指定单词 RAW(不区分大小写) 按原样将 Text 包含的确切字节写入文件, 不进行任何转换. 此选项覆盖以前指定的任何编码, 反之亦然. 如果 Text 不是对象, 由于使用 UTF-16 字符串, 数据大小总是 2 字节的倍数.

  `n(换行符): 如果回车符不存在, 则在每个换行符(`n) 之前插入回车符(`r). 换句话说, 将转换 `n 为 `r`n. 这种转换通常不会影响性能. 如果不使用此选项, 则不会更改 Text 中的行尾.

## 错误处理

失败时抛出 OSError.

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

## 备注

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

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

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

## 相关

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

## 示例

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

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

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

    FileAppend "
    (
    一行文字.
    默认情况下, 前一行和这一行之间的硬回车(Enter) 将被写进文件.
    	这一行缩进了一个制表符; 默认情况下, 该制表符也将被写入文件.
    )", A_Desktop "\My File.txt"

演示如何使用操作系统内置的 FTP 命令自动进行 FTP 上传.

    FTPCommandFile := A_ScriptDir "\FTPCommands.txt"
    FTPLogFile := A_ScriptDir "\FTPLog.txt"
    try 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 Format('{1} /c ftp.exe -s:"{2}" >"{3}"', A_ComSpec, FTPCommandFile, FTPLogFile)
    FileDelete FTPCommandFile  ; 为确保安全进行删除.
    Run FTPLogFile  ; 显示日志进行复查.

dftg