Module jls.io.streams.StreamHandler
Base stream handler class.
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 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 ([onDataOrCallback[, 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.bi (firstStream, secondStream) | Creates a stream handler with two handlers. |
| StreamHandler.multiple (...) | Creates a stream handler with multiple handlers. |
| StreamHandler.std | The standard stream writing data to standard output and error to standard error. |
| StreamHandler.null | A null stream. |
Class StreamHandler
A StreamHandler class.
This class could be inherited to process a data stream.
- StreamHandler:new ([onDataOrCallback[, onError]])
-
Creates a stream handler.
The optional functions take two parameters, the stream and the data or the error
Parameters:
- onDataOrCallback 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.
Returns:
-
boolean
false to indicate that this handler has finish to process the stream.
- 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.
- StreamHandler.bi (firstStream, secondStream)
-
Creates a stream handler with two handlers.
Parameters:
- firstStream StreamHandler The first stream handlers.
- secondStream StreamHandler The second stream handlers.
Returns:
-
StreamHandler
a StreamHandler.
- StreamHandler.multiple (...)
-
Creates a stream handler with multiple handlers.
Parameters:
- ... StreamHandler The stream handlers.
Returns:
-
StreamHandler
a StreamHandler.
- StreamHandler.std
- The standard stream writing data to standard output and error to standard error.
- StreamHandler.null
- A null stream.