Hidden Features

wiki

The Lua C API and standard libraries may contain some undocumented, unsupported, and/or experimental features. They are likely unsupported for a good reason, and may disappear or change at any time--use them at your own risk.

newproxy function

newproxy is an unsupported and undocumented function in the Lua base library. From Lua code, the setmetatable function may only be used on objects of table type. The newproxy function circumvents that limitation by creating a zero-size userdata and setting either a new, empty metatable on it or using the metatable of another newproxy instance. We are then free to modify the metatable from Lua. This is the only way to create a proxy object from Lua which honors certain metamethods, such as __len. Synopsis:

do

  local a = newproxy(true)  -- create proxy object with new metatable

  assert(type(a) == 'userdata')

  getmetatable(a).__len = function() return 5 end

  assert(#a == 5)

  local b = newproxy(a)     -- create proxy object with same metatable as another proxy

  assert(b ~= a)

  assert(getmetatable(b) == getmetatable(a))

  assert(#b == 5)

  local c = newproxy(false) -- create proxy object with no metatable

  assert(not getmetatable(c))



  local is_collected = false

  local o = newproxy(true)

  getmetatable(o).__gc = function() is_collected = true end  -- finalizer

  o = nil; collectgarbage()  -- clear all references to object and ensure finalizer called

  assert(is_collected)

end

The frontier pattern `%f`

See FrontierPattern concerning %f in patterns.

Closing a standard file

As of 5.1.3, it is not permitted to close a standard file (e.g. stdin, stdout, and stderr) due to a bug this can cause[1][4]:


> assert(io.stdout:close())

stdin:1: cannot close standard file

Here's a hack around that, which should be used with caution:


local f = assert(io.open '/dev/null') -- or possibly NUL on Windows

debug.setfenv(io.stdout, debug.getfenv(f))

f:close()

assert(io.stdout:close()) -- ok

package.config

LuaList:2006-07/msg00089.html (will be documentedin 5.2)

Old items

lua_pushliteral is now documented in 5.1.3: [5][6]