From 42d74c0a367a3a15b72ef8751283be5630c1fbeb Mon Sep 17 00:00:00 2001
From: Qingping Hou <dave2008713@gmail.com>
Date: Sun, 13 Nov 2016 21:19:08 -0800
Subject: [PATCH] doc: add sqlite sample code

---
 README.md        |  2 +-
 doc/DataStore.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++
 doc/config.ld    |  2 +-
 3 files changed, 75 insertions(+), 2 deletions(-)
 create mode 100644 doc/DataStore.md

diff --git a/README.md b/README.md
index ec51b370a..a703be37c 100644
--- a/README.md
+++ b/README.md
@@ -283,7 +283,7 @@ http://ccache.samba.org
 
 
 [base-readme]:https://github.com/koreader/koreader-base/blob/master/README.md
-[nb-script]:https://github.com/koreader/koreader-misc/blob/master/koreader-nightlybuild/koreader-nightlybuild.sh
+[nb-script]:https://gitlab.com/koreader/nightly-builds/blob/master/build_release.sh
 [travis-badge]:https://travis-ci.org/koreader/koreader.svg?branch=master
 [travis-link]:https://travis-ci.org/koreader/koreader
 [travis-conf]:https://github.com/koreader/koreader-base/blob/master/.travis.yml
diff --git a/doc/DataStore.md b/doc/DataStore.md
new file mode 100644
index 000000000..e438b73a5
--- /dev/null
+++ b/doc/DataStore.md
@@ -0,0 +1,73 @@
+Data Store
+==========
+
+LuaSettings
+-----------
+
+TODO
+
+
+DocSettings
+-----------
+
+TODO
+
+
+SQLite3
+-------
+
+KOReader ships with the SQLite3 library, which is a great embedded database for
+desktop and mobile applications.
+
+[lua-ljsqlite3][ljsq3] is used to export SQLite3 C interfaces as LUA functions.
+Following is a quick example:
+
+```lua
+local SQ3 = require("lua-ljsqlite3/init")
+
+local conn = SQ3.open("/path/to/database.sqlite3")
+
+-- Execute SQL commands separated by the ';' character:
+conn:exec([[
+-- time is in unit of seconds
+CREATE TABLE IF NOT EXISTS page_read_time(page INTEGER, time INTEGER);
+CREATE TABLE IF NOT EXISTS book_property(title TEXT, author TEXT, language TEXT);
+]])
+
+-- Prepared statements are supported, with this you can bind different values
+-- to the same statement. Let's set the read time for the first 10 pages in the
+-- book to 5 seconds
+local stmt = conn:prepare("INSERT INTO page_read_time VALUES(?, ?)")
+for i=1,10 do
+  stmt:reset():bind(i, 5):step()
+end
+
+-- Now we can retrieve all read time stats for the first 10 pages:
+local results = conn:exec("SELECT * FROM page_read_time") -- Records are by column.
+-- Access to results via column numbers or names:
+assert(results[1] == results.page)
+assert(results[2] == results.time)
+-- Nested indexing corresponds to the record(row) number, access value for 4th page:
+assert(results[1][4] == 4)
+assert(results[2][4] == 5)
+-- access value for 2nd page:
+assert(results.page[2] == 2)
+assert(results.time[2] == 5)
+
+-- Convenience function returns multiple values for one record:
+local page, time = conn:rowexec("SELECT * FROM page_read_time WHERE page==3")
+print(page, time) --> 3 5
+
+-- We can also use builtin aggregate functions to do simple analytic task
+local total_time = conn:rowexec("SELECT SUM(time) FROM page_read_time")
+print(total_time) --> 50
+
+conn:close() -- Do not forget to close stmt after you are done
+```
+
+For more information on supported SQL quries, check out [SQLite3's official
+documentation][sq3-doc].
+
+
+[ljsq3]:http://scilua.org/ljsqlite3.html
+[sq3-doc]:https://www.sqlite.org/docs.html
diff --git a/doc/config.ld b/doc/config.ld
index c78c36fa1..bec363b48 100644
--- a/doc/config.ld
+++ b/doc/config.ld
@@ -5,7 +5,7 @@ title = 'KOReader Documentation'
 dir = 'html'
 style = '!fixed'
 use_markdown_titles = true
-topics = {'../README.md', './Hacking.md', './Events.md'}
+topics = {'../README.md', './Hacking.md', './Events.md', './DataStore.md'}
 package = ''
 format = 'markdown'
 sort_modules = true