LuaCheia Logo  

LuaCheia Reference Manual

shelve

Synopsis

cheia.load “shelve”
 
file = shelve.open(“datafile”)
file.record = value
value = file.record

Description

The shelve module provides a straightforward mechansim for storing Lua objects in file-based databases using the GNU Gdbm or Ndbm libraries. The object representing a file opened by shelve behaves like a Lua table, but is backed by the database. That is, when you store a value in the table, that value is in fact saved to the database, and when you read a value, it is read from the database. shelve transparently encodes the data so that complex nested tables as well as scalar types may be stored.

Just as for a real table, a request for a record that is not in the database returns nil. Likewise, writing nil to a record deletes it.

To close a database, assign nil to it. It will be closed when it is garbage-collected.

It is worth noting that shelve does not provide a heirarchical database: it is not efficient to store large table hierarchies for random access using shelve (although it is efficient to store very large numbers of small hierarchies). Further, unlike conventional table assignment, shelve takes a ‘deep copy’ of the stored data: this means that if you store a table in the shelve database and then restore it, the recovered table will be identical component for component, but will not be ‘the same’ table, and nor will any child table. Similarly, changes to a table made after it has been stored are not reflected in the database.

shelve does not support cyclic table references, and will recurse infinitely if it encounters one.

Examples

Taken from the README:

-- Create data
my_table = {
          name = “This is a string within a table”,
          level= 1,
          is_at_level_one = true,
          another_table = {
                    name = “This is a nested table”,
                    level = 2,
                    is_at_level_one = false
               }
     }
 
-- Open a 'shelve' file
file = shelve.open(“datafile”)
 
-- This encodes & stores the above table
-- Dotted and bracketed syntax may be used interchangeably
file[“my_table”] = my_table
file.title = “File containing a string and a table”
 
-- Show contents of the file in (key, value) form
for key in file() do
     print(“(” .. key .. “, ” .. db[key] .. “)”)
end

Reference

Only one function is typically required:

shelve.open(filename, [access])

Opens or creates a shelve database.

Parameters:
     filename : string  

The name of the database file to open.

     access : string  

“r” means read-only. Any other value, or absent, means read-write.

Returns:
     userdata  

The ‘table’ representing the database.

Byte-streams

These functions encode and decode the byte-streams used by shelve to store data. They are not needed in normal shelve usage, but may be useful e.g. to encode Lua data for storage in a flat file or for transmission over a network.

shelve.marshal(data)

Encodes data, which may be a table or scalar.

Parameters:
     data : any  

The data to encode.

Returns:
     string  

The encoded data.

shelve.unmarshal(bytestream)

Decodes the bytestream, returning the original Lua object.

Parameters:
     bytestream : string  

The encoded data.

Returns:
     any  

The decodes data.

Issues

Doesn't handle cyclic references.

See also

None.

Revision history

Added in LuaCheia 5.0.

Credits

Written by Adrián Pérez de Castro.

Documentation for LuaCheia by Jamie Webb.

Return to main site

Introduction

 » Writing LuaCheia modules

Module Reference

 » bit
 » cgi
 » fuzzy
 » md5
 » pack
 » rex
 » SDL
 » shelve
 » sqlite

Appendices

 » Module path conventions
 » Module names
 » Application Binary Interface
 » Credits