API

This document is the new proposed API structure. Once the re-factor is complete, it can be a temporary place for API docs till we get a better system.

core

This module is for various classes and utilities that don't need their own module.

core.Object

This is the most basic object in Luvit. It provides simple prototypal inheritance and inheritable constructors. All other objects inherit from this.

Object:new(...)

Creates a new instance and calls obj:initialize(...) if there is an initialize method one.

local Rectangle = Object:extend()
function Rectangle:initialize(w, h)
  self.w = w
  self.h = h
end
function Rectangle:getArea()
  return self.w * self.h
end
local rect = Rectangle:new(3, 4)
p(rect:getArea())

Object:extend()

Creates a new sub-class.

local Square = Rectangle:extend()
function Square:initialize(w)
  self.w = w
  self.h = h
end

core.Emitter

Inherits from core.Object

This class can be used directly whenever an event emitter is needed.

local emitter = Emitter:new()
emitter:on('foo', p)
emitter:emit('foo', 1, 2, 3)

Also it can easily be sub-classed.

local Custom = Emitter:extend()
local c = Custom:new()
c:on('bar', onBar)

Emitter:on(name, callback(...))

Adds an event listener (callback) for the named event name.

Emitter:once(name, callback(...))

Same as Emitter:on except it de-registers itself after the first event.

Emitter:emit(name, ...)

Emit a named event to all listeners with optional data argument(s).

Emitter:removeListener(name, callback(...))

Remove a listener so that it no longer catches events.

Emitter:wrap(name)

Utility that binds the named method self[name] for use as a callback. The first argument (err) is re-routed to the "error" event instead.

local Joystick = Emitter:extend()
function Joystick:initialize(device)
  self:wrap("onOpen")
  FS.open(device, self.onOpen)
end

function Joystick:onOpen(fd)
  -- and so forth
end

core.Handle

Inherits from core.Emitter

This class is never used directly, but is the inheritance chain of all libuv objects.

Handle:close()

Wrapper around uv_close. Closes a handle.

Handle:setHandler(name, callback(...))

Set or replace the handler for a native event. Usually Emitter:on() is what you want, not this.

Handle:addHandlerType(name)

This is used by Emitters to register with native events when the first listener is added.

core.Stream

Inherits from core.Handle

This is also never used directly. If you want to create a pure Lua stream, subclass or instantiate core.iStream.

Stream:shutdown()

Stream:listen(callback())

Stream:accept(otherStream)

Stream:readStart()

Stream:readStop()

Stream:write(chunk, callback())

Stream:pipe(otherStream)

core.Error

Inherits from core.Object

This is for code that wants structured error messages.

core.iStream

Inherits from core.Emitter

This is an abstract interface that works like core.Stream but doesn't actually contain a uv struct (it's pure lua)

http

This module is for creating http clients and servers

Properties:

• http.STATUS_CODES

http.createServer(callback(req, res))

http.request(options, callback(res))

http.ServerRequest

Inherits from core.iStream

This is req in http.createServer(callback(req, res))

Properties:

• req.socket - the actual underlying tcp.Tcp instance

http.ServerResponse

Inherits from core.iStream

This is res in http.createServer(callback(req, res))

Properties:

• res.socket - the actual underlying tcp.Tcp instance
• res.autoDate = true
• res.autoServer = true
• res.autoChunkedEncoding = true
• res.autoContentLength = true
• res.autoContentType = "text/html"

req:setCode(code)

res:setHeader(name, value)

res:addHeader(name, value)

res:unsetHeader(name)

res:flushHead(callback())

res:writeHead(code, headers, callback())

res:writeContinue(callback())

res:write(chunk, callback())

res:finish(chunk, callback())

http.ClientRequest

Inherits from core.iStream

This is req in res = http.request(options, callback(res))

http.ClientResponse

Inherits from core.iStream

This is req in res = http.request(options, callback(res))

http.Server

Inherits from core.Emitter

This is the return value of http.createServer(...)

tcp

This module is for TCP clients and servers

tcp.createServer(callback(socket))

tcp.connect(options, callback(socket))

tcp.Tcp

Inherits from core.Stream

This is the lua object wrapping uv_tcp

tcp.Server

Inherits from tcp.Tcp

This is a smart TCP server

tcp.Client

Inherits from tcp.Tcp

This is a smart TCP client

pipe

pipe.Pipe

Inherits from core.Stream

tty

tty.Tty

Inherits from core.Stream

process

process.spawn(command, args, options)

process.Process

Inherits from core.Handle