Module jls.io.StreamHandler
Provides stream handler class and utility functions.
A stream handler provides a way to deal with an input stream asynchronously. Basicaly it consists in a function that will be called when data is available. If the stream ends then the data function is called with no data allowing to execute specific steps. If the stream has an issue then the error function is called.
Streams classes are mainly used by TCP and UDP protocols.
Usage:
local std = StreamHandler:new(function(_, data)
if data then
io.stdout:write(data)
end
end, function(_, err)
io.stderr:write(err or 'Stream error')
end)
-- or
local std = StreamHandler:new(function(err, data)
if err then
io.stderr:write(tostring(err))
elseif data then
io.stdout:write(data)
end
end)
Class StreamHandler
| StreamHandler:new ([onData[, onError]]) | Creates a stream handler. |
| streamHandler:onData (data, ...) | The specified data is available for this stream. |
| streamHandler:onError (err) | The specified error occured on this stream. |
| streamHandler:close () | Closes this stream handler. |
| streamHandler:toCallback () | Returns this stream handler as a callback function. |
| StreamHandler.ensureCallback (cb[, lazy]) | Returns a callback function. |
| StreamHandler.ensureStreamHandler (sh) | Returns a StreamHandler. |
| StreamHandler.fill (sh, data) | Fills the specified stream handler with the specified data. |
| StreamHandler.tee (first, second) | Creates a stream handler with two handlers. |
| StreamHandler.block ([handler[, size]]) | Creates a BlockStreamHandler that allows to pass fixed size blocks to the wrapped handler. |
| StreamHandler.buffer ([handler]) | Creates a BufferedStreamHandler that allows to buffer the stream to pass to the wrapped handler. |
| StreamHandler.fromFile (file, stream[, size]) | Reads the specified file using the stream handler. |
| StreamHandler.toFile (file[, overwrite]) | Creates a FileStreamHandler that allows to write a stream into a file. |
| StreamHandler.promise ([handler]) | Returns a Promise that resolves once the stream ends. |
| StreamHandler.promises () | Creates a StreamHandler with a read() method. |
| StreamHandler.std | The standard stream writing data to standard output and error to standard error. |
| StreamHandler.null | The null stream. |
Class StreamHandler
A StreamHandler class.
This class could be inherited to process a data stream.
- StreamHandler:new ([onData[, onError]])
-
Creates a stream handler.
The optional functions will be called with two parameters, this stream and the data or the error.
The callback function will be called with two parameters, the error or nil and the data.
Parameters:
- onData function a function to use when receiving data or callback if onError is not specified. (optional)
- onError function a function to use in case of error. (optional)
- streamHandler:onData (data, ...)
-
The specified data is available for this stream.
Parameters:
- data the new data to process, nil to indicate the end of the stream.
- ... the optional parameters
Returns:
-
an optional promise that will resolve when the data has been processed.
- streamHandler:onError (err)
-
The specified error occured on this stream.
Parameters:
- err the error that occured on this stream.
- streamHandler:close ()
- Closes this stream handler. Do nothing by default. Must support to be called multiple times.
- streamHandler:toCallback ()
-
Returns this stream handler as a callback function.
The callback function has two arguments: the error and the data.
The data could be nil indicating the end of the stream.
Returns:
-
function
the callback function
- StreamHandler.ensureCallback (cb[, lazy])
-
Returns a callback function.
Parameters:
- cb a callback function or a StreamHandler.
- lazy boolean true to indicate that nil values are valid. (optional)
Returns:
-
function
a callback function.
- StreamHandler.ensureStreamHandler (sh)
-
Returns a StreamHandler.
Parameters:
- sh a callback function or a StreamHandler.
Returns:
-
StreamHandler
a StreamHandler.
- StreamHandler.fill (sh, data)
-
Fills the specified stream handler with the specified data.
This is shortcut for sh:onData(data); sh:onData(nil)
Parameters:
- sh StreamHandler the StreamHandler to fill.
- data string the data to process.
Returns:
-
an optional promise that will resolve when the data has been processed.
- StreamHandler.tee (first, second)
-
Creates a stream handler with two handlers.
Parameters:
- first StreamHandler The first stream handler.
- second StreamHandler The second stream handler.
Returns:
-
StreamHandler
a StreamHandler.
- StreamHandler.block ([handler[, size]])
-
Creates a BlockStreamHandler that allows to pass fixed size blocks to the wrapped handler.
Parameters:
- handler StreamHandler the handler to wrap (optional)
- size number the block size, default to 512 (optional)
Returns:
-
StreamHandler
a StreamHandler.
- StreamHandler.buffer ([handler])
-
Creates a BufferedStreamHandler that allows to buffer the stream to pass to the wrapped handler.
The data will be pass to the wrapped handler once.
Parameters:
- handler StreamHandler the handler to wrap (optional)
Returns:
-
StreamHandler
a StreamHandler.
- StreamHandler.fromFile (file, stream[, size])
-
Reads the specified file using the stream handler.
Parameters:
- file The file to read.
- stream The stream handler to use with the file content.
- size number The read block size. (optional)
Returns:
-
a promise that resolves once the file has been fully read.
- StreamHandler.toFile (file[, overwrite])
-
Creates a FileStreamHandler that allows to write a stream into a file.
Parameters:
- file jls.io.File The file to write to
- overwrite boolean true to indicate that existing file must be re created (optional)
Returns:
-
StreamHandler
a StreamHandler.
- StreamHandler.promise ([handler])
-
Returns a Promise that resolves once the stream ends.
Parameters:
- handler StreamHandler the handler to wrap (optional)
Returns:
- jls.lang.Promise a promise that resolves once the stream ends.
- StreamHandler a StreamHandler.
- StreamHandler.promises ()
-
Creates a StreamHandler with a
read()method. Each call toreadreturns a promise that resolves to the next available data or nil if the stream ended. The promise is rejected if there is an error or the stream ended.Returns:
-
StreamHandler
a StreamHandler.
- StreamHandler.std
- The standard stream writing data to standard output and error to standard error.
- StreamHandler.null
- The null stream.