DefineOutputStreamMethod

DefineOutputStreamMethod["name",{"fname1"function1,"fname2"function2,… }]

defines a custom output stream method with the specified name, allowing the Wolfram Language to call the stream functions for opening and writing to an output stream.

Details

  • An output stream method can provide a new destination for bytes, a way to filter a stream of bytes, or a combination of both.
  • Output stream method functions are as follows:
  • "NameTestFunction"whether a stream of the given name can be opened
    "ConstructorFunction"called when a stream is opened using this method
    "CloseFunction"close the stream and release its resources
    "WriteFunction"write bytes to the stream
    "FlushFunction"ensure that bytes buffered in memory are written to the stream
    "ErrorTextFunction"indicate whether there has been an error
    "ClearErrorFunction"clear the error indication
    "StreamPositionFunction"the number of bytes written
    "OptionChangesFunction"modify the options returned by Options[stream]
  • Only the "ConstructorFunction" must be supplied to DefineOutputStreamMethod. Other functions have a default behavior if a function is not provided.
  • Each OutputStream 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 output stream are:
  • NameParametersReturn Value
    "NameTestFunction"{streamname}True|False
    "ConstructorFunction"{streamname,isAppend,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 writing, the "ConstructorFunction" is called. It opens a stream indicated by streamname that could be a file name, URL, or other resource identification appropriate to the stream method. The isAppend argument is True if the stream was opened for appending and False if it was opened for writing a new resource. The caller argument is a symbol for issuing messages. The calling function, such as OpenWrite, will complete its creation of an OutputStream 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 writing to the stream include:
  • NameParametersReturn Value
    "WriteFunction"{state,{byte...}}{byteCount,newstate}
    "FlushFunction"{state}{ignored,newstate}
  • "WriteFunction" is the essential function for writing to the stream. The byteCount result is the number of bytes successfully written to the stream. The default definition returns a byteCount of 0.
  • "FlushFunction" is used to support the process of writing to a stream. It should ensure that any bytes passed to the "WriteFunction" are transferred from memory buffers to the stream. The result of this function is ignored. The format of this function is:
  • "FlushFunction"->Function[state,body;{result,newstate}]
  • If no "FlushFunction" is provided, the following definition is used:
  • "FlushFunction"->Function[state,{Null,state}]
  • Functions for handling errors are as follows:
  • NameParametersReturn Value
    "ErrorTextFunction"{state,nbytes}{result,newstate}
    "ClearErrorFunction"{state}{ignored,newstate}
  • "ErrorTextFunction" is used in the process of writing to 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 "WriteFunction" indicates that it wrote fewer bytes than requested. 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.
  • "StreamPositionFunction" is used to support StreamPosition. The position result is an integer that specifies the number of bytes written to the stream with "WriteFunction". The default definition returns -1.
  • "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:
  • NameParametersReturn Value
    "OptionChangesFunction"{state,options}{newoptions,newstate}

Examples

Basic Examples  (1)

Define a stream method that writes to a list of bytes, retrieved as a stream option:

Open a new stream using this method:

Use the stream:

Retrieve the byte list:

Wolfram Research (2012), DefineOutputStreamMethod, Wolfram Language function, https://reference.wolfram.com/language/ref/DefineOutputStreamMethod.html.

Text

Wolfram Research (2012), DefineOutputStreamMethod, Wolfram Language function, https://reference.wolfram.com/language/ref/DefineOutputStreamMethod.html.

CMS

Wolfram Language. 2012. "DefineOutputStreamMethod." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/DefineOutputStreamMethod.html.

APA

Wolfram Language. (2012). DefineOutputStreamMethod. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/DefineOutputStreamMethod.html

BibTeX

@misc{reference.wolfram_2024_defineoutputstreammethod, author="Wolfram Research", title="{DefineOutputStreamMethod}", year="2012", howpublished="\url{https://reference.wolfram.com/language/ref/DefineOutputStreamMethod.html}", note=[Accessed: 21-December-2024 ]}

BibLaTeX

@online{reference.wolfram_2024_defineoutputstreammethod, organization={Wolfram Research}, title={DefineOutputStreamMethod}, year={2012}, url={https://reference.wolfram.com/language/ref/DefineOutputStreamMethod.html}, note=[Accessed: 21-December-2024 ]}