Usage examples

Type filter

Type ltn12

Type pump

Type sink

Type source

Type filter

Provides filters.

Field(s)

filter.chain(vararg)

Parameter

• vararg : Simple filters.

Return value

The chained filter.

Usage:

-- load required modules
local ltn12 = require("ltn12")
local mime = require("mime")

-- create a silly identity filter
id = ltn12.filter.chain(
  mime.encode("quoted-printable"),
  mime.encode("base64"),
  mime.decode("base64"),
  mime.decode("quoted-printable")
)

filter.cycle(low, ctx, extra)

Parameters

• low : The low-level filter to be cycled.
• ctx : (optional) The initial context.
• extra : (optional) Any extra argument the low-level filter might take.

Return value

The high-level filter.

Usage:

-- load the ltn12 module
local ltn12 = require("ltn12")

-- the base64 mime filter factory
encodet['base64'] = function()
    return ltn12.filter.cycle(b64, "")
end

Type ltn12

LTN12 implementation.

Field(s)

#filter ltn12.filter

#pump ltn12.pump

#sink ltn12.sink

#source ltn12.source

Type pump

Provide pumps.

Field(s)

pump.all(source, sink)

Parameters

• source : Source to pump.
• sink : Sink to fill.

Return values

1. If successful, the function returns a value that evaluates to true.
2. #nil, #string: In case of error, the function returns a false value, followed by an error message.

pump.step(source, sink)

Parameters

• source : Source to pump.
• sink : Sink to fill.

Return values

1. If successful, the function returns a value that evaluates to true.
2. #nil, #string: In case of error, the function returns a false value, followed by an error message.

Type sink

Provides sinks.

Field(s)

sink.chain(filter, sink)

Parameters

• filter :
• sink :

sink.error(message)

Parameter

• message :

Return value

#sink: A #sink that aborts transmission with the error message.

sink.file(handle, message)

Parameters

• handle : A file handle. If handle is #nil, message should give the reason for failure.
• message : The reason for failure, when handle is #nil.

Return value

A #sink that sends all data to the given handle and closes the file when done, or a sink that aborts the transmission with the error message.

Usage:

-- load the ltn12 module
local ltn12 = require("ltn12")

-- copy a file
ltn12.pump.all(
  ltn12.source.file(io.open("original.png")),
  ltn12.sink.file(io.open("copy.png"))
)

sink.null()

Return value

A #sink that ignores all data it receives.

sink.simplify(sink)

Parameter

• sink : Fancy sink.

Return value

#sink: A simple #sink.

sink.table(table)

Parameter

• table : (optional) Used to hold the chunks. If #nil, the function creates its own table.

Return value

#sink, #table: The sink and the table used to store the chunks.

Usage:

-- load needed modules
local http = require("socket.http")
local ltn12 = require("ltn12")

-- a simplified http.get function
function http.get(u)
  local t = {}
  local respt = request{
    url = u,
    sink = ltn12.sink.table(t)
  }
  return table.concat(t), respt.headers, respt.code
end

Type source

Provides sources.

Field(s)

source.cat(vararg)

Parameter

• vararg : The original sources.

Return value

#source: The new #source.

source.chain(source, filter)

Parameters

• source : Passes data through a filter before returning it.
• filter :

Return value

#source: The new #source.

source.empty()

Return value

#source: An empty #source.

source.error(message)

Parameter

• message :

Return value

#source: A #source that aborts transmission with the error message.

source.file(handle, message)

In the following example, notice how the prototype is designed to fit nicely with the io.open function.

Parameters

• handle : A file handle. If handle is #nil, message should give the reason for failure.
• message : Gives the reason for failure, when handle is #nil.

Return value

#source: A #source that reads chunks of data from given handle and returns it to the user, closing the file when done, or a source that aborts the transmission with the error message.

source.simplify(source)

Parameter

• source : A fancy #source.

Return value

#source: A simple #source.

source.string(string)

Parameter

• string : Content of given #source.

Return value

#source: A #source that produces the contents of given string, chunk by chunk.