forked from mtcontrib/colddb
add concept
This commit is contained in:
uleelx
parent
ec225bb6d7
commit
544ae720a5
298
README.md
298
README.md
|
|
@ -1,147 +1,161 @@
|
||||||
FlatDB
|
FlatDB
|
||||||
===========
|
===========
|
||||||
|
|
||||||
FlatDB is a lua library that implements a serverless, zero-configuration, NoSQL database engine.<br>
|
FlatDB is a lua library that implements a serverless, zero-configuration, NoSQL database engine.<br>
|
||||||
It provides a key-value storage system using plain Lua tables.
|
It provides a key-value storage system using plain Lua tables.
|
||||||
|
|
||||||
When To Use FlatDB
|
When To Use FlatDB
|
||||||
===========
|
===========
|
||||||
|
|
||||||
When you want to use SQLite to store data, just take a glance at FlatDB.<br>
|
When you want to use SQLite to store data, just take a glance at FlatDB.<br>
|
||||||
When Lua acts in your program as the major language or the embedded scripting language, just try using FlatDB.
|
When Lua acts in your program as the major language or the embedded scripting language, just try using FlatDB.
|
||||||
|
|
||||||
Usage
|
Concept
|
||||||
==========
|
==========
|
||||||
Copy *flatdb.lua* file to your project or where your lua libraries stored.<br>
|
|
||||||
Then write this in any Lua file where you want to use it:
|
| FlatDB | Disk | Lua |
|
||||||
```lua
|
|:--------------:|:-------------:|:--------------:|
|
||||||
local flatdb = require 'flatdb'
|
| Database | Directory | Table |
|
||||||
```
|
| Book | File | Table |
|
||||||
|
| Key-value pair | File content | Key-value pair |
|
||||||
|
|
||||||
|
Keys and values can be all Lua types except coroutines, userdata, cdata and C functions.
|
||||||
|
|
||||||
|
Usage
|
||||||
|
==========
|
||||||
|
|
||||||
|
Copy *flatdb.lua* file to your project or where your lua libraries stored.<br>
|
||||||
|
Then write this in any Lua file where you want to use it:
|
||||||
|
```lua
|
||||||
|
local flatdb = require 'flatdb'
|
||||||
|
```
|
||||||
|
|
||||||
1. Bind a directory as a database
|
1. Bind a directory as a database
|
||||||
|
|
||||||
```lua
|
```lua
|
||||||
local db = flatdb('./db')
|
local db = flatdb('./db')
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Open or create a book
|
2. Open or create a book
|
||||||
|
|
||||||
```lua
|
```lua
|
||||||
if not db.book then
|
if not db.book then
|
||||||
db.book = {}
|
db.book = {}
|
||||||
end
|
end
|
||||||
```
|
```
|
||||||
|
|
||||||
3. Store key-value items
|
3. Store key-value items
|
||||||
|
|
||||||
```lua
|
```lua
|
||||||
db.book.key = 'value'
|
db.book.key = 'value'
|
||||||
-- equivalent to db.book['key'] = 'value'
|
-- equivalent to db.book['key'] = 'value'
|
||||||
```
|
```
|
||||||
|
|
||||||
4. Retrieve items
|
4. Retrieve items
|
||||||
|
|
||||||
```lua
|
```lua
|
||||||
print(db.book.key) -- prints 'value'
|
print(db.book.key) -- prints 'value'
|
||||||
```
|
```
|
||||||
|
|
||||||
5. Save to file
|
5. Save to file
|
||||||
|
|
||||||
```lua
|
```lua
|
||||||
db:save()
|
db:save()
|
||||||
-- 'book' will be saved to './db/book'
|
-- 'book' will be saved to './db/book'
|
||||||
```
|
```
|
||||||
|
|
||||||
More usage can be found in the *cli.lua*(a Redis-like command line interface example using FlatDB).
|
More usage can be found in the *cli.lua*(a Redis-like command line interface example using FlatDB).
|
||||||
|
|
||||||
Quick Look
|
Quick Look
|
||||||
==========
|
==========
|
||||||
|
|
||||||
```lua
|
```lua
|
||||||
local flatdb = require("flatdb")
|
local flatdb = require("flatdb")
|
||||||
|
|
||||||
-- open a directory as a database, 'db' is just a plain empty Lua table that can contain books
|
-- open a directory as a database
|
||||||
local db = flatdb("./db")
|
-- 'db' is just a plain empty Lua table that can contain books
|
||||||
|
local db = flatdb("./db")
|
||||||
-- open or create a book named "default", it also a plain empty Lua table where key-value data stored in
|
|
||||||
if not db.default then
|
-- open or create a book named "default"
|
||||||
db.default = {}
|
-- it is also a plain empty Lua table where key-value pair stored in
|
||||||
end
|
if not db.default then
|
||||||
|
db.default = {}
|
||||||
-- extend db methods for getting values from 'default' book
|
end
|
||||||
flatdb.hack.get = function(db, key)
|
|
||||||
return db.default[key]
|
-- extend db methods for getting values from 'default' book
|
||||||
end
|
flatdb.hack.get = function(db, key)
|
||||||
|
return db.default[key]
|
||||||
-- extend db methods for setting values to 'default' book
|
end
|
||||||
flatdb.hack.set = function(db, key, value)
|
|
||||||
db.default[key] = value
|
-- extend db methods for setting values to 'default' book
|
||||||
end
|
flatdb.hack.set = function(db, key, value)
|
||||||
|
db.default[key] = value
|
||||||
-- extend db methods for watching new key
|
end
|
||||||
flatdb.hack.guard = function(db, f)
|
|
||||||
setmetatable(db.default, {__newindex = f})
|
-- extend db methods for watching new key
|
||||||
end
|
flatdb.hack.guard = function(db, f)
|
||||||
|
setmetatable(db.default, {__newindex = f})
|
||||||
-- get key-value data from 'default' book
|
end
|
||||||
print(db:get("hello"))
|
|
||||||
|
-- get key-value data from 'default' book
|
||||||
-- set key-value data to 'default' book
|
print(db:get("hello"))
|
||||||
db:set("hello", "world")
|
|
||||||
|
-- set key-value data to 'default' book
|
||||||
-- get key-value data from 'default' book
|
db:set("hello", "world")
|
||||||
print(db:get("hello"))
|
|
||||||
|
-- get key-value data from 'default' book
|
||||||
-- set guard function
|
print(db:get("hello"))
|
||||||
db:guard(function(book, key, value)
|
|
||||||
print("CREATE KEY permission denied!")
|
-- set guard function
|
||||||
end)
|
db:guard(function(book, key, value)
|
||||||
|
print("CREATE KEY permission denied!")
|
||||||
-- try creating new key-value data to 'default' book
|
end)
|
||||||
db:set("key1", 1)
|
|
||||||
db:set("key2", 2)
|
-- try creating new key-value pair to 'default' book
|
||||||
|
db:set("key1", 1)
|
||||||
-- update an existing key-value item
|
db:set("key2", 2)
|
||||||
db:set("hello", "bye")
|
|
||||||
|
-- update an existing key-value pair
|
||||||
print(db:get("key1")) -- prints nil
|
db:set("hello", "bye")
|
||||||
print(db:get("key2")) -- prints nil
|
|
||||||
print(db:get("hello")) -- prints 'bye'
|
print(db:get("key1")) -- prints nil
|
||||||
|
print(db:get("key2")) -- prints nil
|
||||||
-- store 'default' book to './db/default' file
|
print(db:get("hello")) -- prints 'bye'
|
||||||
db:save()
|
|
||||||
|
-- store 'default' book to './db/default' file
|
||||||
```
|
db:save()
|
||||||
|
|
||||||
API
|
```
|
||||||
==========
|
|
||||||
|
API
|
||||||
- **Functions**
|
==========
|
||||||
|
|
||||||
- **flatdb(dir) --> db**
|
- **Functions**
|
||||||
|
|
||||||
Bind a directory as a database, returns nil if 'dir' doesn't exists. Otherwise, it returns a 'db' obeject.
|
- **flatdb(dir) --> db**
|
||||||
|
|
||||||
- **db:save([book])**
|
Bind a directory as a database, returns nil if 'dir' doesn't exists. Otherwise, it returns a 'db' obeject.
|
||||||
|
|
||||||
Save all books or the given book(if specified) contained in db to file. The 'book' argument is a string, the book's name.
|
- **db:save([book])**
|
||||||
|
|
||||||
- **Tables**
|
Save all books or the given book(if specified) contained in db to file. The 'book' argument is a string, the book's name.
|
||||||
|
|
||||||
- **flatdb.hack**
|
- **Tables**
|
||||||
|
|
||||||
The 'hack' table contains db's methods. There is only one method 'save(db, book)' in it by default.
|
- **flatdb.hack**
|
||||||
It is usually used to extend db methods.
|
|
||||||
|
The 'hack' table contains db's methods. There is only one method 'save(db, book)' in it by default.
|
||||||
Dependencies
|
It is usually used to extend db methods.
|
||||||
=======
|
|
||||||
|
Dependencies
|
||||||
- [pp](https://github.com/luapower/pp)
|
=======
|
||||||
- [lfs](http://keplerproject.github.io/luafilesystem/)
|
|
||||||
|
- [pp](https://github.com/luapower/pp)
|
||||||
All above libraries can be found in [LuaPower](https://luapower.com/).
|
- [lfs](http://keplerproject.github.io/luafilesystem/)
|
||||||
|
|
||||||
License
|
All above libraries can be found in [LuaPower](https://luapower.com/).
|
||||||
=======
|
|
||||||
|
License
|
||||||
FlatDB is distributed under the MIT license.
|
=======
|
||||||
|
|
||||||
|
FlatDB is distributed under the MIT license.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue