FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
]]--
+--[[
+ Changes made by LuCI project:
+ * Renamed to luci.ltn12 to avoid collisions with luasocket
+ * Added inline documentation
+]]--
-----------------------------------------------------------------------------
-- LTN12 - Filters, sources, sinks and pumps.
-- LuaSocket toolkit.
local string = require("string")
local table = require("table")
local base = _G
+
+--- Diego Nehab's LTN12 - Filters, sources, sinks and pumps.
+-- See http://lua-users.org/wiki/FiltersSourcesAndSinks for design concepts
module("luci.ltn12")
filter = {}
-----------------------------------------------------------------------------
-- Filter stuff
-----------------------------------------------------------------------------
--- returns a high level filter that cycles a low-level filter
+
+--- LTN12 Filter constructors
+-- @class module
+-- @name luci.ltn12.filter
+
+--- Return a high level filter that cycles a low-level filter
+-- by passing it each chunk and updating a context between calls.
+-- @param low Low-level filter
+-- @param ctx Context
+-- @param extra Extra argument passed to the low-level filter
+-- @return LTN12 filter
function filter.cycle(low, ctx, extra)
base.assert(low)
return function(chunk)
end
end
--- chains a bunch of filters together
+--- Chain a bunch of filters together.
-- (thanks to Wim Couwenberg)
+-- @param ... filters to be chained
+-- @return LTN12 filter
function filter.chain(...)
local n = table.getn(arg)
local top, index = 1, 1
-----------------------------------------------------------------------------
-- Source stuff
-----------------------------------------------------------------------------
+
+--- LTN12 Source constructors
+-- @class module
+-- @name luci.ltn12.source
+
-- create an empty source
local function empty()
return nil
end
+--- Create an empty source.
+-- @return LTN12 source
function source.empty()
return empty
end
--- returns a source that just outputs an error
+--- Return a source that just outputs an error.
+-- @param err Error object
+-- @return LTN12 source
function source.error(err)
return function()
return nil, err
end
end
--- creates a file source
+--- Create a file source.
+-- @param handle File handle ready for reading
+-- @param io_err IO error object
+-- @return LTN12 source
function source.file(handle, io_err)
if handle then
return function()
else return source.error(io_err or "unable to open file") end
end
--- turns a fancy source into a simple source
+--- Turn a fancy source into a simple source.
+-- @param src fancy source
+-- @return LTN12 source
function source.simplify(src)
base.assert(src)
return function()
end
end
--- creates string source
+--- Create a string source.
+-- @param s Data
+-- @return LTN12 source
function source.string(s)
if s then
local i = 1
else return source.empty() end
end
--- creates rewindable source
+--- Creates rewindable source.
+-- @param src LTN12 source to be made rewindable
+-- @return LTN12 source
function source.rewind(src)
base.assert(src)
local t = {}
if not chunk then return src()
else return chunk end
else
- table.insert(t, chunk)
+ t[#t+1] = chunk
end
end
end
+--- Chain a source and a filter together.
+-- @param src LTN12 source
+-- @param f LTN12 filter
+-- @return LTN12 source
function source.chain(src, f)
base.assert(src and f)
local last_in, last_out = "", ""
end
end
--- creates a source that produces contents of several sources, one after the
--- other, as if they were concatenated
+--- Create a source that produces contents of several sources.
+-- Sources will be used one after the other, as if they were concatenated
-- (thanks to Wim Couwenberg)
+-- @param ... LTN12 sources
+-- @return LTN12 source
function source.cat(...)
local src = table.remove(arg, 1)
return function()
-----------------------------------------------------------------------------
-- Sink stuff
-----------------------------------------------------------------------------
--- creates a sink that stores into a table
+
+--- LTN12 sink constructors
+-- @class module
+-- @name luci.ltn12.sink
+
+--- Create a sink that stores into a table.
+-- @param t output table to store into
+-- @return LTN12 sink
function sink.table(t)
t = t or {}
local f = function(chunk, err)
- if chunk then table.insert(t, chunk) end
+ if chunk then t[#t+1] = chunk end
return 1
end
return f, t
end
--- turns a fancy sink into a simple sink
+--- Turn a fancy sink into a simple sink.
+-- @param snk fancy sink
+-- @return LTN12 sink
function sink.simplify(snk)
base.assert(snk)
return function(chunk, err)
end
end
--- creates a file sink
+--- Create a file sink.
+-- @param handle file handle to write to
+-- @param io_err IO error
+-- @return LTN12 sink
function sink.file(handle, io_err)
if handle then
return function(chunk, err)
return 1
end
+--- Create a sink that discards data.
+-- @return LTN12 sink
function sink.null()
return null
end
--- creates a sink that just returns an error
+--- Create a sink that just returns an error.
+-- @param err Error object
+-- @return LTN12 sink
function sink.error(err)
return function()
return nil, err
end
end
--- chains a sink with a filter
+--- Chain a sink with a filter.
+-- @param f LTN12 filter
+-- @param snk LTN12 sink
+-- @return LTN12 sink
function sink.chain(f, snk)
base.assert(f and snk)
return function(chunk, err)
-----------------------------------------------------------------------------
-- Pump stuff
-----------------------------------------------------------------------------
--- pumps one chunk from the source to the sink
+
+--- LTN12 pump functions
+-- @class module
+-- @name luci.ltn12.pump
+
+--- Pump one chunk from the source to the sink.
+-- @param src LTN12 source
+-- @param snk LTN12 sink
+-- @return Chunk of data or nil if an error occured
+-- @return Error object
function pump.step(src, snk)
local chunk, src_err = src()
local ret, snk_err = snk(chunk, src_err)
else return nil, src_err or snk_err end
end
--- pumps all data from a source to a sink, using a step function
+--- Pump all data from a source to a sink, using a step function.
+-- @param src LTN12 source
+-- @param snk LTN12 sink
+-- @param step step function (optional)
+-- @return 1 if the operation succeeded otherwise nil
+-- @return Error object
function pump.all(src, snk, step)
base.assert(src and snk)
step = step or pump.step
projects / project / luci.git / blobdiff