colddb/README.md

ColdDB
===========

ColdDB is a minetest mod that implements a serverless, asynchronous, NoSQL database engine.<br>
It provides a key or key-value storage system using plain Lua tables, also it can iterate through the keys.<br>

Usage
===========

Copy both *colddb.lua* and *async* files to your minetest mod or game. Copy the code from colddb's init file to your mods init file<br>
Write this code in your lua file.
1. create a directory and link it as a database.
```lua
coldbase = colddb.get_db("mydb")
```
2. add an extra folder to the directory. every new file will be added to the global tag(folder).
```lua
colddb.add_global_tag(coldbase,"ips")
```
3. store key item(this key has no value)
```lua
colddb.set_key(coldbase,"MyKey")
```
4. store key-value item
```lua
colddb.set(coldbase,"MyKeyAndValue","Hello world")
```
5. retrieve items (get_key's callback(arg) will return true, false, or nil)
```lua
colddb.get(coldbase,"MyKeyAndValue",nil,function(arg)
	if arg then
		minetest.log(string.format("value:%s",arg))
	end
end)
colddb.get_key(coldbase,"MyKey",nil,function(arg)
	if arg then
		minetest.log("Found key")
	else
		minetest.log("Key not found")
	end
end)
```
6. delete key(file) this function works on both keys and key-value keys.
```lua
colddb.remove(coldbase,"MyKeyAndValue")
```
7. if add_to_mem_pool is true(true by default). keys are stored in a weak lua table(memory) it will be removed by the gc if its not in-use. Storing data in memory is to prevent the database from constantly loading up data from files.
```lua
coldbase.add_to_mem_pool = true
```
8. if indexes is true(false by default). When a key file is created an indexing file stores the key for look-ups. this makes it possible to iterate through keys.
```lua
coldbase.indexes = true
```
9. only if coldbase.indexes is true. returns the amount of keys that are in the indexing file.
```lua
colddb.get_count(coldbase)
```
10. only if coldbase.indexes is true. iterates through the indexing file(breaks and ends if it reaches the end of the file).
```lua
colddb.iterate_index_table(coldbase,nil,func_list_keys,nil)
```
11. adds a folder which can be used in other functions that have tag_name arg.
```lua
colddb.add_tag(coldbase,"Extra_Folder",{"Extra","Folder"})
```
12. returns the tag name if the tag does not exists it creates one.
```lua
colddb.get_or_add_tag(coldbase,"Extra_Folder",{"Extra","Folder"})
```
13. remove tag by name.
```lua
colddb.remove_tag(coldbase,"Extra_Folder")
```

Quick Look
===========

```lua
-- create an directory(watchlist) and link it as a database.
ip_db = colddb.get_db("watchlist")
-- add an extra folder to the directory.
colddb.add_global_tag(ip_db,"ips")

-- return a recorded ip address from the data base.
function ip_db.find(player,callback)
	colddb.get(ip_db,player,nil,callback)
end

-- Key is the file and file name. Value is the content's within the file.
-- global tag(ips)--->key(Player name)--->value(ip address)
function ip_db.record_ip(player,ip)
	colddb.set(ip_db,player,ip)
end

function ip_db.delete(player)
	colddb.remove(db,player)
end

-- When ever a player join's his/her ip address is recorded to the database by player name.
minetest.register_on_prejoinplayer(function(name, ip)
	ip_db.record_ip(name,ip)
end)

minetest.register_chatcommand("ip", {
	params = "<player>",
	description = "Get an player's ip address.",
    func = function(name, param)
		-- Get the ip record asynchronously.
		colddb.get(ip_db,param,nil,function(record)
			-- If database contains the record data then send it to the player.
			if record then
				minetest.chat_send_player(name,string.format("%s:%s",param,record))
			else
				-- No record was found.
				minetest.chat_send_player(name,"Can not find ip record.")
			end
		end)
    end
})
```

Quick Look Notes
===========

In the example above we could also create a more complex ip database using tags. Creating tags named after the player then assigning the ip files to them.<br>
This way we could store many ips associated with the player instead of just one ip.

API
===========

- **Functions**

  - **colddb.get_db(directory) --> db**
  
  Creates an directory and links it as a database. Returns a 'db' obeject.
  
  - **colddb.add_global_tag(db,tag)**
  
  Adds an extra folder to the directory and advance the database to the added folder.
  
  - **colddb.add_tag(db,name,tag)**
  
  - Creates a folder from the given table in tag.
  
  - **colddb.get_or_add_tag(db,name,tag) --> tag_name**
  
  Returns a tag or creates a new one if does not exist.
  
  - **colddb.remove_tag(db,name)**
  
  Removes a tag.
  
  - **colddb.get_count(db,tag_name) --> count**
  
  Returns the count from the index table file.
  
  - **colddb.iterate_index_table(db,begin_func,func_on_iterate,end_func,args,tag_name)**
  
  - function iterates through the index table file.
    
	- **begin_func(args) --> args**
	
	- function that is ran before the loop begins.
	
	- **func_on_iterate(key,index,args)**
	
	- function that is ran in the for loop.
	
	- **end_func(args)**
	
	- end function that is ran after the for loop ends.
  
  - **colddb.set(db,name,_table,tag_name)**
  
  - Writes data to the database. Key-Value.
  
  - **colddb.set_key(db,name,tag_name)**
  
  - Writes data to the database. Key-nil.
  
  - **colddb.get(db,name,tag_name,callback(arg))**
  
  - Returns specified data from the database in a callback function.
  
  - **colddb.get_key(db,name,tag_name,callback(arg))**
  
  - Returns if the key exist in the database.
  
  - **colddb.remove(db,name,tag_name)**
  
  - Deletes the specified data from the database.
  
- **Database object fields**

  - **indexes**
  
  - If truth the database makes a indexing file for keys.
  
  - **add_to_mem_pool**
  
  - If truth when you get keys or values it gets cached in the memory for faster access next time.

License
===========

ColdDB is distributed under the LGPLv2.1+ license.