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.
|
