---

Network support for the Lua language

home · download · installation · introduction · reference

---

LTN12

The ltn12 namespace implements the ideas described in LTN012, Filters sources and sinks. This manual simply describes the functions. Please refer to the LTN for a deeper explanation of the functionality provided by this module.

To obtain the ltn12 namespace, run:

-- loads the LTN21 module
local ltn12 = require("ltn12")

Filters

ltn12.filter.chain(filter₁, filter₂ [, ... filter_N])

Returns a filter that passes all data it receives through each of a series of given filters.

Filter₁ to filter_N are simple filters.

The function returns the chained filter.

The nesting of filters can be arbitrary. For instance, the useless filter below doesn't do anything but return the data that was passed to it, unaltered.

-- 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")
)

ltn12.filter.cycle(low [, ctx, extra])

Returns a high-level filter that cycles though a low-level filter by passing it each chunk and updating a context between calls.

Low is the low-level filter to be cycled, ctx is the initial context and extra is any extra argument the low-level filter might take.

The function returns the high-level filter.

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

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

Pumps

ltn12.pump.all(source, sink)

Pumps all data from a source to a sink.

If successful, the function returns a value that evaluates to true. In case of error, the function returns a false value, followed by an error message.

ltn12.pump.step(source, sink)

Pumps one chunk of data from a source to a sink.

If successful, the function returns a value that evaluates to true. In case of error, the function returns a false value, followed by an error message.

Sinks

ltn12.sink.chain(filter, sink)

Creates and returns a new sink that passes data through a filter before sending it to a given sink.

ltn12.sink.error(message)

Creates and returns a sink that aborts transmission with the error message.

ltn12.sink.file(handle, message)

Creates a sink that sends data to a file.

Handle is a file handle. If handle is nil, message should give the reason for failure.

The function returns 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

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

-- 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"))
)

ltn12.sink.null()

Returns a sink that ignores all data it receives.

ltn12.sink.simplify(sink)

Creates and returns a simple sink given a fancy sink.

ltn12.sink.table([table])

Creates a sink that stores all chunks in a table. The chunks can later be efficiently concatenated into a single string.

Table is used to hold the chunks. If nil, the function creates its own table.

The function returns the sink and the table used to store the chunks.

-- 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

Sources

ltn12.source.cat(source₁ [, source₂, ..., source_N])

Creates a new source that produces the concatenation of the data produced by a number of sources.

Source₁ to source_N are the original sources.

The function returns the new source.

ltn12.source.chain(source, filter)

Creates a new source that passes data through a filter before returning it.

The function returns the new source.

ltn12.source.empty()

Creates and returns an empty source.

ltn12.source.error(message)

Creates and returns a source that aborts transmission with the error message.

ltn12.source.file(handle, message)

Creates a source that produces the contents of a file.

Handle is a file handle. If handle is nil, message should give the reason for failure.

The function returns 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

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

-- 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"))
)

ltn12.source.simplify(source)

Creates and returns a simple source given a fancy source.

ltn12.source.string(string)

Creates and returns a source that produces the contents of a string, chunk by chunk.