README_Lua.md

Install

To install, you'll need Lua (binary + library) and LuaRocks.

If you have Python and Pip, you can get Lua and LuaRocks using hererocks, written by Peter Melnichenko.

  pip install hererocks
  hererocks here --lua 5.1 --luarocks 2.2

This command installs Lua and LuaRocks locally to directory here. To activate it, add here/bin to PATH:

  export PATH="$(pwd)/here/bin/:$PATH"

Then you can use commands lua, luarocks, and tools installed by luarocks.

To build and install annoy, type:

  luarocks make

Background

See the main README.

Lua code example

local annoy = require "annoy"

local f = 3
local t = annoy.AnnoyIndex(f) -- Length of item vector that will be indexed
for i = 0, 999 do
  local v = {math.random(), math.random(), math.random()}
  t:add_item(i, v)
end

t:build(10) -- 10 trees
t:save('test.ann')

-- ...

local u = annoy.AnnoyIndex(f)
u:load('test.ann') -- super fast, will just mmap the file

-- find the 10 nearest neighbors
local neighbors = u:get_nns_by_item(0, 10)
for rank, i in ipairs(neighbors) do
  print("neighbor", rank, "is", i)
end

Full Lua API

Lua API closely resembles Python API, see main README. Lua binding does not support multithreaded build.

Tests

File test/annoy_test.lua is the literal translation of test/annoy_test.py from Python+Nosetests to Lua+Busted.

To run tests, you need Busted, Elegant Lua unit testing. To install it, type:

  luarocks install busted

To run tests, type:

  busted test/annoy_test.lua

It will take few minutes to execute.

Discuss

There might be some memory leaks if inputs are incorrect. Some functions allocate stack objects calling Lua functions throwing Lua errors (e.g., luaL_checkinteger). A Lua error may omit calling C++ destructors when unwinding the stack. (If it does, depends on the Lua implementation and platform being in use.)

Lua binding was written by Boris Nagaev. You can contact me via email (see https://github.com/starius).