lgdbm

NAME
SYNOPSIS

DESCRIPTION
FUNCTIONS

EXAMPLE
DOWNLOAD

AUTHOR
SEE ALSO

NAME

lgdbm - This is a Lua interface for gdbm, the GNU database manager.

SYNOPSIS

 local G = require "gdbm"
 print(G.version)
 local d = assert(G.open("/tmp/test.gdbm", "c"))
 d:insert("JAN", "January")
 d:insert("FEB", "February")
 if d:exists("JAN") then print("JAN exists :-)") end
 d:replace("JAN", "Janeiro")
 print("JAN is now", d:fetch("JAN"))
 d:close()  -- don't forget to do this!

This is a gdbm interface for Lua 5.2.
gdbm is the GNU database manager, a replacement of the UNIX dbm library, available at www.gnu.org/software/gdbm/
If you're running Linux, you probably already have gdbm installed.

The code is in the public domain.

FUNCTIONS

close, delete, exists, export, fetch, firstkey, import,
insert, nextkey, open, reorganize, replace, sync

db = G.open( filename, mode )

Returns a userdata representing the open database. The filename is the name of the file (the complete name; gdbm does not append any characters to this name).

The mode is a string, which must start with one of the following:
r GDBM_READER - reader
w GDBM_WRITER - writer
c GDBM_WRCREAT - if database does not exist create new one
n GDBM_NEWDB - create a new, empty, database
and the optional remaining characters can be any of the following:
L GDBM_NOLOCK
M GDBM_NOMMAP
S GDBM_SYNC
For the meanings of these parameters see man gdbm.
Be aware that n will delete any database which might already exist under that filename.

db:close() or G.close( db )

It is important that every database opened is also closed (this is needed to update the reader/writer count on the file).

db:delete( key ) or G.delete( db, key )

Deletes the key from the database, and returns nil if it wasn't there.

db:exists( key )

Returns true or false

db:export( outputfile )

Test for the existence of this routine before you try to use it ! It's not very portable; it only exists if the variable GDBM_VERSION_MAJOR was defined.

db:fetch( key )

Returns the value of the given key, or nil if it doesn't exist.

db:firstkey()

Returns the first key (in key order) in the database. This is used in conjunction with nextkey(key) to traverse the whole database.

db:import( inputdb [,replace] )

Test for the existence of this routine before you try to use it ! It's not very portable; it only exists if the variable GDBM_VERSION_MAJOR was defined.
replace is boolean.

db:insert( key, data )

Insert only; returns nil if the key exists already.

db:nextkey( key )

Returns the next key after the given key argument, or nil if it was the last. Starting from firstkey(), this will traverse the whole database (in key order).

db:reorganize()

This routine should be used very infrequently. If you have had a lot of deletions and would like to shrink the space used by the gdbm file, this routine will reorganize the database. Gdbm will not shorten the length of a database except by using this reorganization.

db:replace( key, data )

Replaces the contents, if the key exists, and returns nil otherwise.

db:sync()

Physically writes the current state of the database out to the disk file. It will not return until the disk file state is synchronized with the in-memory state of the database.

EXAMPLE

The following code from test.lua, by the module author Luiz Henrique de Figueiredo, creates table proxies for gdbm databases, and two "for" generators: "keys" and "entries", for convenient traversal of databases.

local gdbm = require "gdbm"
local M = {
  __index = function (t,k) return t.gdbm:fetch(k) end,
  __newindex = function (t,k,v)
    if v~=nil then t.gdbm:replace(k,v) else t.gdbm:delete(k) end
  end
}
function gdbm.proxy(t)
  return setmetatable({gdbm=t}, M)
end
local function keys(d,k)
  if k==nil then return d:firstkey() else return d:nextkey(k) end
end
function gdbm.keys(d)
 return keys,d
end
local function entries(d,k)
  local v
  if k==nil then k=d:firstkey() else k=d:nextkey(k) end
  if k==nil then v=nil else v=d:fetch(k) end
  return k,v
end
function gdbm.entries(d)
  return entries,d
end

local t = d:proxy()
t.JUL = "July"  -- proxy insert
t.JAN =  nil    -- proxy delete

if d.export and d.import then  -- check first!
  F="test.flat" -- testing export and import
  print("export  ",d:export(F))
  print("import store",d:import(F))
  print("import replace",d:import(F,true))
end

d:close()

DOWNLOAD

This module is available as a LuaRock in luarocks.org/modules/luarocks/lgdbm so you should be able to install it with the command:

 $ su
 Password:
 # luarocks install lgdbm

If this results in an error message such as:
Error: Could not find expected file libgdbm.a, or libgdbm.so, or libgdbm.so.* for GDBM -- you may have to install GDBM in your system and/or pass GDBM_DIR or GDBM_LIBDIR to the luarocks command. Example: luarocks install lgdbm GDBM_DIR=/usr/local then you need to find the appropriate directory with:
find /usr/lib -name 'libgdbm.*' -print and then invoke:
luarocks install lgdbm GDBM_LIBDIR=/usr/lib/i386-linux-gnu/ (or wherever) accordingly.

For detailed installation instructions, see also: www.tecgraf.puc-rio.br/~lhf/ftp/lua/install.html

AUTHOR

The Lua module is by Luiz Henrique de Figueiredo
Comments, suggestions, and bug reports to lhf@tecgraf.puc-rio.br

This manual page was put together by Peter Billam
See: www.pjb.com.au, www.pjb.com.au/comp/contact.html