Wolfram Language & System Documentation Center

DefineInputStreamMethod

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

defines a custom input stream method with the specified name, allowing the Wolfram Language to call the stream functions fname_i for opening and reading from an input stream.

Details and Options

An input stream method can provide a new source of bytes, a way to filter a stream of bytes, or a combination of both.
The following stream functions can be provided:

	"NameTestFunction"	whether a stream of the given name can be opened
	"ConstructorFunction"	called when a new stream is opened
	"CloseFunction"	close the stream and release its resources
	"ReadFunction"	read bytes from the stream
	"EndOfFileQFunction"	indicate whether the stream has no more input to read
	"WaitForInputFunction"	wait until there is input to read
	"SeekFunction"	reposition the point in the stream from which input is read
	"StreamPositionFunction"	the current point in the stream from which input is read
	"StreamSizeFunction"	the number of bytes that can be read from the stream
	"SeekableQFunction"	indicate whether the stream method can reposition the point from which input is read
	"ErrorTextFunction"	indicate whether there has been an error
	"ClearErrorFunction"	clear the error indication
	"OptionChangesFunction"	modify the options returned by Options[stream]

Only the "ConstructorFunction" must be supplied to DefineInputStreamMethod. Other functions have a default definition if a function is not provided.
Each InputStream opened with a stream method has a current state. This is where a stream method can store information such as a handle to the underlying stream resource, the current stream position, the latest error message, and other information needed by the stream method functions. The initial state expression is returned by "ConstructorFunction". Other functions take the current state as a parameter and return a new state value.
If a function returning a new state value is not provided, the default definition returns the given state unmodified.
Functions for opening and closing an input stream are:

Name	Parameters	Return Value
"NameTestFunction"	{streamname}	True\|False
"ConstructorFunction"	{streamname,caller,opts}	{success,state}
"CloseFunction"	{state}	ignored

"NameTestFunction" is needed when the stream is opened with Method->Automatic, and the Wolfram Language needs to choose a stream method to use based on streamname. A stream method will be used if its "NameTestFunction" returns True. If no "NameTestFunction" is provided, the default behavior is to return False.
When a stream is opened for reading, the "ConstructorFunction" is called. It opens a stream indicated by streamname, which could be a file name, URL, or other resource identification appropriate to the stream method. The caller argument is a symbol for issuing messages. The calling function, such as OpenRead, will complete its creation of an InputStream if success is True. The state is used as the initial value of the stream method's state.
"CloseFunction" is used for a stream st when Close[st] is called. Resources allocated in the "ConstructorFunction" should be deallocated here. The default definition does nothing.
Functions for reading from the stream include:

Name	Parameters	Return Value
"ReadFunction"	{state,n}	{{byte₁,...,byte_n},newstate}
"EndOfFileQFunction"	{state}	{flag,newstate}
"WaitForInputFunction"	{state}	{ignored,newstate}

"ReadFunction" is the essential function for reading from the stream. It takes an argument n and returns a list of n bytes, integers ranging from 0 to 255. Fewer bytes may be returned if the stream is at the end of file, or if there is an error while reading. In that case, "EndOfFileQFunction" and "ErrorTextFunction" are used to determine the cause. If no "ReadFunction" is provided, the default definition returns an empty list of bytes.
"EndOfFileQFunction" is used in the process of reading from the stream, and a stream method should typically provide this function. This function should return True when the last byte of the stream has been returned by the "ReadFunction". The default definition returns True.
"WaitForInputFunction" is used in the process of reading from a stream. This method is useful for stream methods that read from a source where input may be available intermittently, such as from a pipe to another process. In such a case, a stream method's "ReadFunction" should ensure that it never waits for input and only returns as many bytes as available; "WaitForInputFunction" is the place where it waits for input. The default definition does nothing.
Functions for reading and setting the stream size and position are as follows:

Name	Parameters	Return Value
"StreamPositionFunction"	{state}	{position,newstate}
"StreamSizeFunction"	{state}	{size,newstate}
"SeekableQFunction"	{state}	{flag,newstate}
"SeekFunction"	{state,offset}	{success,newstate}

"StreamPositionFunction" is used to support StreamPosition. The position result is an integer that specifies the position of the current point in the open stream. A position of -1 indicates that the stream position is unknown. The default definition returns a position of -1.
"StreamSizeFunction" is used in the process of reading from the stream. A stream method that provides this function with an accurate stream size may perform faster than a stream method that does not. The size result is an integer that specifies the total number of bytes in the stream, or -1 if the size is unknown. The default definition returns a size of -1.
"SeekableQFunction" is used to support SetStreamPosition. A stream method that provides a "SeekFunction" should provide a "SeekableQFunction" that returns True. The default definition returns False.
"SeekFunction" is used to support SetStreamPosition. If a stream method does not support setting the stream position, this function does not need to be provided, but "SeekableQFunction" should return False. This function is called with offset, which is either a non-negative integer indicating a byte position relative to the start of the stream, or Infinity indicating the position at the end of the stream. This function should return True to indicate that the seek succeeded.
Functions for handling errors are as follows:
Name Parameters Return Value

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

"ClearErrorFunction" {state} {ignored,newstate}
"ErrorTextFunction" is used in the process of reading from the stream. It should return an error message String if there is an error condition and Null if there is no error. The Wolfram Language will call this function if other functions indicate failure, for example, if "ReadFunction" returns fewer bytes than requested and "EndOfFileQFunction" returns False. The default definition returns a result of Null.
"ClearErrorFunction" is called if "ErrorTextFunction" returned an error string and is called to clear the error state. After this, "ErrorTextFunction" should return Null until there is another error reading from the stream. The result of this function is ignored. It is recommended that a stream method providing an "ErrorTextFunction" should also provide a "ClearErrorFunction" definition.
"OptionChangesFunction" is used to edit the options for a stream st from the list returned by Options[st,Method]. For example, a stream method may take an option that includes a password or other piece of sensitive security data. By default, Options will return that setting. This function provides a way to remove that option field.
Function for changing options is as follows:
Name Parameters Return Value

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

Examples

open all close all

Basic Examples (1)

Define a stream method that takes its input from a list of bytes, passed as a method option "Bytes":

Open a stream to a list of bytes, which could have come from anywhere:

Read from the stream:

Close the stream:

Scope (1)

A stream method that does not define seek methods will work, but the kernel will need to use more memory to support certain operations. This shows that more and more bytes are read on successive read calls to fill a growing buffer: