DefineInputStreamMethod

DefineInputStreamMethod["name",{"fname₁"function₁,"fname₂"function₂,… }]

定义一个具有指定名称的自定义输入流方法，使得 Wolfram 语言可以调用流函数 fname_i，用于打开和读取输入流.

更多信息和选项

输入流方法可以提供字节的新来源，一种对字节流过滤的新方法，或者两者兼具.
可以提供下列流函数：

	"NameTestFunction"	给定名称的流是否能被打开
	"ConstructorFunction"	当打开一个新的流时调用
	"CloseFunction"	关闭流并且释放它的资源
	"ReadFunction"	从流读取字节
	"EndOfFileQFunction"	表明流是否没有更多输入可以读取
	"WaitForInputFunction"	等待直至有输入可以读取
	"SeekFunction"	重新放置输入读取的流中的点
	"StreamPositionFunction"	输入读取的流中的当前点
	"StreamSizeFunction"	可以从流中读取的字节数目
	"SeekableQFunction"	表明流方法是否可以重新放置输入读取的点
	"ErrorTextFunction"	指明是否是一个错误
	"ClearErrorFunction"	清楚错误提示
	"OptionChangesFunction"	修改由 Options[stream] 返回的选项

只有 "ConstructorFunction" 必须提供给 DefineInputStreamMethod. 如果函数没有被提供，那么其他函数有一个默认的定义.
使用流方法打开的每个 InputStream 都有一个当前状态. 这里流方法可以把诸如句柄的信息存储到内在流资源、当前流为主、最新错误消息和流方法函数需要的其他信息. 初始状态表达式由 "ConstructorFunction" 返回. 其他函数将当前状态视为参数，并且返回新的状态值.
如果返回新状态值的函数没有提供，那么默认定义返回未修改的给定状态.
打开和关闭一个输入流的函数是：

名称	参数	返回值
"NameTestFunction"	{streamname}	True\|False
"ConstructorFunction"	{streamname,caller,opts}	{success,state}
"CloseFunction"	{state}	ignored

当流使用 Method->Automatic 打开时，需要"NameTestFunction"，而且 Wolfram 语言需要基于 streamname 选择使用的流方法. 如果 "NameTestFunction" 返回 True，则将使用流方法. 如果没有提供 "NameTestFunction"，默认的行为是返回 False.
当打开一个流用于读取时，调用 "ConstructorFunction". 它打开一个由 streamname 标志的流，它可以是一个文件名、URL 或者其他对流方法适当的资源识别. caller 参数是发出消息的符号. 如果 success 是 True 的话，调用函数，例如 OpenRead，将完成一个 InputStream 的创建. state 用作流方法状态的初始值.
当 Close[st] 被调用时，"CloseFunction" 用于流 st. "ConstructorFunction" 中分配的资源应该被释放. 默认定义不执行任何操作.
从流中读取的函数包括：

名称	参数	返回值
"ReadFunction"	{state,n}	{{byte₁,...,byte_n},newstate}
"EndOfFileQFunction"	{state}	{flag,newstate}
"WaitForInputFunction"	{state}	{ignored,newstate}

"ReadFunction" 是用于从流中读取的重要函数. 它使用参数 n 并且返回 n 个字节组成的列表，整数范围在 0 到 255 之间. 如果流在文件末尾或者读取中出现错误，返回很少的字节. 在那种情况下，"EndOfFileQFunction" 和 "ErrorTextFunction" 用于判断原因. 如果没有提供 "ReadFunction"，默认定义返回字节的空列表.
"EndOfFileQFunction" 用于从流中读取的过程，而流方法通常应该提供该函数. 当流的最后一个字节已经由 "ReadFunction" 返回时，该函数应该返回 True. 默认定义返回 True.
"WaitForInputFunction" 用于从流中读取的过程. 该方法对于从间断 (intermittently) 输入的资源中读取的流方法有用，例如到另一个过程的管道（pipe）. 在这种情况下，流方法的 "ReadFunction" 应该确保它永远不等待输入，并且只返回已有的字节；"WaitForInputFunction" 是它等待输入的位置. 默认定义不执行任何操作.
读取和设置流尺寸和位置的函数如下所示：

名称	参数	返回值
"StreamPositionFunction"	{state}	{position,newstate}
"StreamSizeFunction"	{state}	{size,newstate}
"SeekableQFunction"	{state}	{flag,newstate}
"SeekFunction"	{state,offset}	{success,newstate}

"StreamPositionFunction" 用于支持 StreamPosition. position 结果是指定打开的流中当前点的位置的整数. -1 的 position 表明流位置未知. 默认定义返回 -1 的 position.
"StreamSizeFunction" 用于从流中读取的过程. 提供该函数的具有准确流尺寸的流方法可能比没有的流方法性能更快. 尺寸结果是一个指定流中字节总数的整数，如果尺寸未知，则是 -1. 默认定义返回 -1 的 size.
"SeekableQFunction" 用于支持 SetStreamPosition. 提供 "SeekFunction" 的流方法应该提供返回 True 的 "SeekableQFunction". 默认定义返回 False.
"SeekFunction" 用于支持 SetStreamPosition. 如果一个流方法不支持流位置设置，该函数不用提供，但是 "SeekableQFunction" 应该返回 False. 该函数使用 offset 调用，它或者是一个非负整数，表明相对于流起始位置的字节位置，或者是 Infinity，表明流末尾的位置. 该函数应该返回 True，以表明搜寻成功.
处理错误的函数如下所示：
名称参数返回值

"ErrorTextFunction" {state,nbytes} {result,newstate}

"ClearErrorFunction" {state} {ignored,newstate}
"ErrorTextFunction" 用于从流中读取的过程. 如果存在错误条件，它应该返回一条错误消息 String，如果没有错误则是 Null. Wolfram 语言将调用该函数，如果其他函数表明出现错误，例如，如果 "ReadFunction" 返回比要求更少的字节，并且 "EndOfFileQFunction" 返回 False. 默认定义返回 Null 的 result.
如果 "ErrorTextFunction" 返回一个错误字符串，并且被调用来清除错误状态，那么调用"ClearErrorFunction". 然后，"ErrorTextFunction" 应该返回 Null 直至有另一个错误从流中读取. 忽略该函数的结果. 强烈推荐提供 "ErrorTextFunction" 的流方法也应该提供一个 "ClearErrorFunction" 方法.
"OptionChangesFunction" 用于编辑来自由 Options[st,Method] 返回的列表的流 st 的选项. 例如，流方法可能可以使用包含密码或者其他敏感安全数据的块作为选项. 默认情况下，Options 将返回该设置. 这个函数提供了删除该选项域的方法.
更改选项的函数如下：
名称参数返回值

"OptionChangesFunction" {state,options} {newoptions,newstate}