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

Usage:

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

Type ltn12

ltn12.filter	Contains #filter related functions.
ltn12.pump	Contains #pump related functions.
ltn12.sink	Contains #sink related functions.
ltn12.source	Contains #source related functions.

Type filter

filter.chain(...)	Returns a filter that passes all data it receives through each of a series of given filters.
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.

Type pump

pump.all(source, sink)	Pumps all data from a source to a sink.
pump.step(source, sink)	Pumps one chunk of data from a source to a sink.

Type sink

sink.chain(filter, sink)	Creates and returns a new sink that passes data through a filter before sending it to a given sink.
sink.error(message)	Creates and returns a sink that aborts transmission with the error message.
sink.file(handle, message)	Creates a sink that sends data to a file.
sink.null()	Returns a sink that ignores all data it receives.
sink.simplify(sink)	Creates and returns a simple sink given a fancy #sink.
sink.table(table)	Creates a sink that stores all chunks in a table.

Type source

source.cat(...)	Creates a new source that produces the concatenation of the data produced by a number of sources.
source.chain(source, filter)	Creates a new source that passes data through a filter before returning it.
source.empty()	Creates and returns an empty source.
source.error(message)	Creates and returns a source that aborts transmission with the error message.
source.file(handle, message)	Creates a source that produces the contents of a file.
source.simplify(source)	Creates and returns a simple source given a fancy source.
source.string(string)	Creates and returns a source that produces the contents of a string, chunk by chunk.

Type ltn12

LTN12 implementation.

Field(s)

#filter ltn12.filter

Contains #filter related functions.

#pump ltn12.pump

Contains #pump related functions.

#sink ltn12.sink

Contains #sink related functions.

#source ltn12.source

Contains #source related functions.

Type filter

Provides filters.

Field(s)

filter.chain(...)

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

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.

Parameter

• ... : 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)

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

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 pump

Provide pumps.

Field(s)

pump.all(source, sink)

Pumps all data from a source to a sink.

Parameters

• #source source : Source to pump.

• #sink 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)

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

Parameters

• #source source : Source to pump.

• #sink 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)

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

Parameters

• #filter filter :

• #sink sink :

sink.error(message)

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

Parameter

• #string message :

Return value

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

sink.file(handle, message)

Creates a sink that sends data to a file.

Parameters

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

• #string 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()

Returns a sink that ignores all data it receives.

Return value

A #sink that ignores all data it receives.

sink.simplify(sink)

Creates and returns a simple sink given a fancy #sink.

Parameter

• #sink sink : Fancy sink.

Return value

#sink: A simple #sink.

sink.table(table)

Creates a sink that stores all chunks in a table.

The chunks can later be efficiently concatenated into a single string.

Parameter

• #table 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(...)

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

Parameter

• ... : The original sources.

Return value

#source: The new #source.

source.chain(source, filter)

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

Parameters

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

• #filter filter :

Return value

#source: The new #source.

source.empty()

Creates and returns an empty source.

Return value

#source: An empty #source.

source.error(message)

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

Parameter

• #string message :

Return value

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

source.file(handle, message)

Creates a source that produces the contents of a file.

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

Parameters

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

• #string 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)

Creates and returns a simple source given a fancy source.

Parameter

• #source source : A fancy #source.

Return value

#source: A simple #source.

source.string(string)

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

Parameter

• #string string : Content of given #source.

Return value

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