Update readme

README.md

@@ -1,4 +1,122 @@
 ColdDB
 ===========
 
-ColdDB is a lua library that implements a serverless, zero-configuration, NoSQL database engine.
+ColdDB is a lua library that implements a serverless, NoSQL database engine.<br>
+It provides a key or key-value storage system using plain Lua tables. It also can iterate through the keys.<br>
+It is not required to add this mod to secure.trusted_mods this mod will still work.
+
+Usage
+===========
+
+Copy *colddb.lua* file to your minetest mod or game. Copy the code from colddb's init file to your mods init file<br>
+Then create a lua file for handling database's or any file you like.<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. added 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 will return true, false, or nil)
+```lua
+local key_and_value = colddb.get(coldbase,"MyKeyAndValue")
+local key = colddb.get_key(coldbase,"MyKey")
+```
+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 lua table(memory) for 30 seconds or more depending on its use. This is to prevent the database from constantly loading up the data file.
+```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 == true. returns the amount of keys are in the indexing file.
+```lua
+colddb.get_count(coldbase)
+```
+10. only if coldbase.indexes == true. iterates through the indexing file 50 times per game tick(breaks and ends if it reached the end of the file).
+```lua
+colddb.iterate_index_table(coldbase,nil,func_list_keys,nil,50)
+```
+11. adds folders 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 creates it.
+```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)
+	local f = colddb.get(ip_db,player)
+	if f then
+		return f
+	end
+	return nil
+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)
+```
+
+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 it.<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.
+  
+  -
+
+License
+===========
+
+ColdDB is distributed under the LGPLv2.1+ license.

colddb.lua

@@ -85,6 +85,13 @@ function colddb.get_tag(db,name)
 	return ""
 end
 
+function colddb.get_or_add_tag(db,name,tag)
+	if not db.tags[name] then
+		colddb.add_tag(db,name,tag)
+	end
+	return name
+end
+
 function colddb.remove_tag(db,name)
 	if db.tags[name] then
 		local delete_path = string.format("%s%s",db.directory,db.tags[name])