# FileOpen() [AHK_L 42+]

打开文件, 从其中读取特定内容和/或将新内容写入其中.

    file := FileOpen(Filename, Flags , Encoding)

## 参数

Filename

  要打开文件的路径, 如果未指定绝对路径, 则假定在 A_WorkingDir 中.

  [v1.1.17+]: 如下所示, 指定一个(或两个) 星号来打开标准 输入(input)/输出(output)/错误(error) 流:

      FileOpen("*", "r")   ; 标准输入(stdin)
      FileOpen("*", "w")   ; 标准输出(stdout)
      FileOpen("**", "w")  ; 标准错误(stderr)

Flags

  在 [AHK_L 54+] 表示希望使用的访问模式的字符串, 后面跟着其他选项(中间可以含有空格或 tab); 或在 [AHK_L 42+] 数字标志的组合(总和). 下面的表格中描述了支持的值.

Encoding

  如果文件没有 UTF-8 或 UTF-16 字节顺序标记, 或者使用了 `h`(handle) 标志, 读写文件时使用的代码页(带字节顺序标记的文件 AutoHotkey 自动识别, 指定的 Encoding 无效). 如果省略本参数, 则使用 A_FileEncoding 的当前值.

## Flags

### 访问模式(互斥的)

Flag | Dec | Hex | 描述
--- | --- | --- | ---
r | 0 | 0x0 | 读取: 当文件不存在时失败.
w | 1 | 0x1 | 写入: 创建新文件, 若文件已存在则覆盖它们.
a | 2 | 0x2 | 追加: 如果文件不存在则创建新文件, 否则移动文件指针到文件末尾.
rw | 3 | 0x3 | 读取/写入: 当文件不存在时创建新文件.
h |  |  | 表示 Filename 是包装在对象中的文件句柄. 忽略共享模式标志. 当文件对象销毁时, 文件句柄 不会 自动关闭并且调用 Close 没有效果. 注意当 Filename 是非搜寻设备(例如管道或通信设备) 的句柄时不应该使用 Seek, Tell 和 Length.

### 共享模式标志

Flag | Dec | Hex | 描述
--- | --- | --- | ---
-rwd |  |  | 为读取, 写入和/或删除访问进行文件锁定. 可以使用 `r`, `w` 和 `d` 的任意组合. 指定 `-` 相当于指定 `-rwd`. 如果完全省略, 默认为共享所有访问.
| 0 | 0x0 | 如果 Flags 是数值的, 缺少共享模式标志会让文件被锁定.
| 256 | 0x100 | 共享 读取 访问.
| 512 | 0x200 | 共享 写入 访问.
| 1024 | 0x400 | 共享 删除 访问.

### 行结束符(EOL) 选项

Flag | Dec | Hex | 描述
--- | --- | --- | ---
`n | 4 | 0x4 | 读取时把 ``r`n` 替换为 ``n` 而写入时把 ``n` 替换为 ``r`n`.
`r | 8 | 0x8 | 读取时把单独的 ``r` 替换为 ``n`.

## 返回值

如果成功打开文件, 则返回值为文件对象.

如果函数失败, 则返回值为 0, 且在 [AHK_L 54+] A_LastError 包含错误码.

使用 `if file` 或 `IsObject(file)` 可以判断函数是否成功执行.

## 备注

当创建 UTF-8 或 UTF-16 文件时, 会写入字节顺序标记到文件中, 除非 Encoding(或当参数 Encoding 省略时, 则使用 A_FileEncoding) 包含 `UTF-8-RAW` 或 `UTF-16-RAW`.

当以读取方式打开含有 UTF-8 或 UTF-16 字节顺序标记(BOM) 的文件时, 会把文件指针放置到这个标志后, 来从输出中排除 BOM. 因此, 在刚刚打开这样的文件时 `File.Position` 可能为 3 或 2.

## 相关

FileEncoding, 文件对象, FileRead

## 示例

写入一些文本到文件, 然后从文件读取回内存(它提供了与此 DllCall 示例相同的功能).

    FileSelectFile, FileName, S16,, Create a new file:
    if (FileName = "")
    	return
    file := FileOpen(FileName, "w")
    if !IsObject(file)
    {
    	MsgBox Can't open "%FileName%" for writing.
    	return
    }
    TestString := "This is a test string.`r`n"  ; 通过这种方式写入内容到文件时, 要使用 `r`n 而不是 `n 来开始新行.
    file.Write(TestString)
    file.Close()

    ; 现在已经把内容写入文件了, 重新把它们读取回内存中.
    file := FileOpen(FileName, "r-d") ; 读取文件 ("r"), 共享除删除 ("-d") 外的所有访问权限
    if !IsObject(file)
    {
    	MsgBox Can't open "%FileName%" for reading.
    	return
    }
    CharsToRead := StrLen(TestString)
    TestString := file.Read(CharsToRead)
    file.Close()
    MsgBox The following string was read from the file: %TestString%

以只读模式打开脚本并读取它的首行.

    file := FileOpen(A_ScriptFullPath, "r")
    MsgBox % file.ReadLine()

演示标准 input/output 流的用法.

    ; 打开控制台窗口以进行此次演示.
    DllCall("AllocConsole")
    stdin  := FileOpen("*", "r `n")  ; 需要 [v1.1.17+]
    stdout := FileOpen("*", "w `n")
    ; 对于较旧的版本:
    ;  stdin  := FileOpen(DllCall("GetStdHandle", "int", -10, "ptr"), "h `n")
    ;  stdout := FileOpen(DllCall("GetStdHandle", "int", -11, "ptr"), "h `n")
    stdout.Write("Enter your query.`n\> ")
    stdout.Read(0) ; 清除写入缓冲区.
    query := RTrim(stdin.ReadLine(), "`n")
    stdout.WriteLine("Your query was '" query "'. Have a nice day.")
    stdout.Read(0) ; 清除写入缓冲区.
    Sleep 5000

dftg