[nongnu] elpa/sqlite3 96e1cdfaa8 34/62: Rewrote README in org

[ELPA Syncer]

branch: elpa/sqlite3
commit 96e1cdfaa89c8899bcdd474bcf9f678ef665e01e
Author: Uphill Battler <code@uphill.me>
Commit: Uphill Battler <code@uphill.me>

    Rewrote README in org
---
 README.md => README.org | 318 +++++++++++++++++++++++-------------------------
 1 file changed, 149 insertions(+), 169 deletions(-)

diff --git a/README.md b/README.org
similarity index 54%
rename from README.md
rename to README.org
index e06139e06b..942801d492 100644
--- a/README.md
+++ b/README.org
@@ -1,7 +1,8 @@
-# SQLite3 API for Emacs 25+
-`sqlite3-api` is a dynamic module for GNU Emacs 25+ that provides
+#+OPTIONS: ^:nil
+* SQLite3 API for Emacs 25+
+~sqlite3-api~ is a dynamic module for GNU Emacs 25+ that provides 
 direct access to the core SQLite3 C API from Emacs Lisp.
-~~~el
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (require 'sqlite3-api)
 
 (setq dbh (sqlite3-open "person.sqlite3" sqlite-open-readwrite 
sqlite-open-create))
@@ -21,89 +22,64 @@ direct access to the core SQLite3 C API from Emacs Lisp.
     (message "name: %s, age: %d" name age)))
 (sqlite3-finalize stmt)
 (sqlite3-close dbh)
-~~~
-While this module provides only 14 functions (vs [200+ in the C 
API](https://sqlite.org/c3ref/funclist.html)), it should satisfy most
+#+END_SRC
+
+While this module provides only 14 functions (vs 
[[https://sqlite.org/c3ref/funclist.html][200+ in the C API]]), it should 
satisfy most
 users' needs.
 
-The current version is v0.12.
+The current version is v0.13.
 
 This is an alpha release so it might crash your Emacs. Save your work before 
you try it out!
 
-* [Requirements](#1)
-* [Installation](#2)
-    * [Manual](#3)
-    * [Package](#4)
-* [API](#5)
-    * [sqlite3-open](#6)
-    * [sqlite3-close](#7)
-    * [sqlite3-prepare](#8)
-    * [sqlite3-finalize](#9)
-    * [sqlite3-step](#10)
-    * [sqlite3-changes](#11)
-    * [sqlite3-reset](#12)
-    * [sqlite3-last-insert-rowid](#13)
-    * [sqlite3-get-autocommit](#14)
-    * [sqlite3-exec](#15)
-    * [sqlite3-bind-*](#16)
-    * [sqlite3-bind-multi](#17)
-    * [sqlite3-column-*](#18)
-    * [sqlite3-fetch](#19)
-    * [sqlite3-fetch-alist](#20)
-* [Transaction Support](#21)
-* [Error Handling](#22)
-* [A Note on Garbage Collection](#23)
-* [Known Problems](#24)
-* [License](#25)
-* [Changelog](#26)
-* [Useful Links for Writing Dynamic Modules](#27)
-
-## <a name="1"/> Requirements
-- Emacs 25.1 or above, compiled with module support (`./configure 
--with-modules`)
+** Requirements
+- Emacs 25.1 or above, compiled with module support (~./configure 
--with-modules~)
 - SQLite3 v3.16.0 or above. Older versions might work but I have not 
personally tested those.
 - A C99 compiler
 
-It's been tested on macOS (Sierra) and CentOS 7.
-## <a name="2"/> Installation
-### <a name="3"/> Manual
-~~~sh
+It's been tested on macOS (Catalina) and CentOS 7.
+** Installation
+*** Manual
+#+BEGIN_SRC sh :eval no :exports code
 $ git co https://github.com/pekingduck/emacs-sqlite3-api
 $ cd emacs-sqlite3-api
 $ make
 $ cp sqlite3-api.so /your/elisp/load-path/
-~~~
+#+END_SRC
 
-### <a name="4"/> Package
-~~~sh
+*** Package
+#+BEGIN_SRC sh :eval no :exports code
 $ git co https://github.com/pekingduck/emacs-sqlite3-api
 $ cd emacs-sqlite3-api
 $ make module
-$
-~~~
-A tar archive called `sqlite3-api-X.Y.tar` will be created. Do a `M-x 
package-install-file` in Emacs to install that tar archive and
+#+END_SRC
+
+A tar archive called ~sqlite3-api-X.Y.tar~ will be created. Do a ~M-x 
package-install-file~ in Emacs to install that tar archive and 
 you'll all set.
 
 For Mac users:
-~~~sh
+#+BEGIN_SRC sh :eval no :exports code
 $ make HOMEBREW=1
-~~~
+#+END_SRC
 to build the module against sqlite3 installed by homebrew.
 
 If you have sqlite3 installed in a nonstandard location:
-~~~sh
+#+BEGIN_SRC sh :eval no :exports code
 $ make INC=/path/to/sqlite3/include LIB="-L/path/to/sqlite3/lib -lsqlite3"
-~~~
+#+END_SRC
+
 Currently there's no way to reload a dynamic module in Emacs
-(`unload-feature` doesn't seem to work for dynamic modules.)
+(~unload-feature~ doesn't seem to work for dynamic modules.)
 If you are updating from an older version, you'll need to restart Emacs
 for the new module to take effect.
 
-## <a name="5"/> API
-To load the package, put the following in your `.emacs`:
-~~~el
+** API
+To load the package, put the following in your ~.emacs~:
+
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (require 'sqlite3-api)
-~~~
+#+END_SRC
 
-An application will typically use sqlite3_open() to create a single database 
connection during initialization.
+An application will typically use sqlite3_open() to create a single database 
connection during initialization. 
 
 To run an SQL statement, the application follows these steps:
 
@@ -113,203 +89,207 @@ To run an SQL statement, the application follows these 
steps:
 1. Destroy the prepared statement using sqlite3_finalize().
 1. Close the database using sqlite3_close().
 
-[SQlite3 constants](https://www.sqlite.org/rescode.html), defined in 
sqlite3.h, are things such as numeric result codes from various interfaces (ex: 
`SQLITE_OK`) or flags passed into functions to control behavior (ex: 
`SQLITE_OPEN_READONLY`).
+[[https://www.sqlite.org/rescode.html][SQlite3 constants]], defined in 
sqlite3.h, are things such as numeric result codes from various interfaces (ex: 
~SQLITE_OK~) or flags passed into functions to control behavior (ex: 
~SQLITE_OPEN_READONLY~).
 
 In elisp they are in lowercase and words are separated by "-" instead of
-"_". For example, `SQLITE_OK` would be `sqlite-ok`.
+"_". For example, ~SQLITE_OK~ would be ~sqlite-ok~.
 
-[www.sqlite.org](https://www.sqlite.org) is always a good source of 
information, especially
-[An Introduction to the SQLite C/C++ 
Interface](https://www.sqlite.org/cintro.html) and [C/C++ API 
Reference](https://www.sqlite.org/c3ref/intro.html).
+[[https://www.sqlite.org][www.sqlite.org]] is always a good source of 
information, especially 
+[[https://www.sqlite.org/cintro.html][An Introduction to the SQLite C/C++ 
Interface]] and [[https://www.sqlite.org/c3ref/intro.html][C/C++ API 
Reference]].
 
-### <a name="6"/> sqlite3-open
-~~~el
+*** sqlite3-open
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-open "/path/to/data-file" flag1 flag2 ...)
-~~~
+#+END_SRC
 Open the database file and return a database handle.
 
-This function calls 
[`sqlite3_open_v2()`](https://www.sqlite.org/c3ref/open.html) internally and 
raises `'db-error` in case of error.
+This function calls 
[[https://www.sqlite.org/c3ref/open.html][~sqlite3_open_v2()~]] internally and 
raises ~'db-error~ in case of error.
 
 *flag1*, *flag2*.... will be ORed together.
-### <a name="7"/> sqlite3-close
-~~~el
+*** sqlite3-close
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-close database-handle)
-~~~
+#+END_SRC
 Close the database file.
-### <a name="8"/> sqlite3-prepare
-~~~el
+*** sqlite3-prepare
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-prepare database-handle sql-statement)
-~~~
+#+END_SRC
 Compile the supplied SQL statement and return a statement handle.
 
-This function calls 
[`sqlite3_prepare_v2()`](https://www.sqlite.org/c3ref/prepare.html) internally 
and raises 'sql-error in case of error.
-### <a name="9"/> sqlite3-finalize
-~~~el
+This function calls 
[[https://www.sqlite.org/c3ref/prepare.html][~sqlite3_prepare_v2()~]] 
internally and raises 'sql-error in case of error.
+*** sqlite3-finalize
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-finalize statement-handle1 statement-handle2 ...)
-~~~
+#+END_SRC
 Destroy prepared statements.
-### <a name="10"/> sqlite3-step
-~~~el
+*** sqlite3-step
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-step statement-handle)
-~~~
+#+END_SRC
 Execute a prepared SQL statement. Some of the return codes are:
 
-`sqlite-done` - the statement has finished executing successfully.
+~sqlite-done~ - the statement has finished executing successfully.
 
-`sqlite-row` - if the SQL statement being executed returns any data, then 
`sqlite-row` is returned each time a new row of data is ready for processing by 
the caller.
+~sqlite-row~ - if the SQL statement being executed returns any data, then 
~sqlite-row~ is returned each time a new row of data is ready for processing by 
the caller. 
 
-### <a name="11"/> sqlite3-changes
-~~~el
+*** sqlite3-changes
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-changes database-handle)
-~~~
+#+END_SRC
 Return the number of rows modified (for update/delete/insert statements)
 
-### <a name="12"/> sqlite3-reset
-~~~el
+*** sqlite3-reset
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-reset statement-handle)
-~~~
-Reset a prepared statement. Call this function if you want to re-bind
+#+END_SRC
+Reset a prepared statement. Call this function if you want to re-bind 
 the statement to new variables, or to re-execute the prepared statement
 from the start.
-### <a name="13"/> sqlite3-last-insert-rowid
-~~~el
+*** sqlite3-last-insert-rowid
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-last-insert-rowid database-handle)
-~~~
-Retrieve the last inserted rowid (64 bit).
+#+END_SRC
+Retrieve the last inserted rowid (64 bit). 
 
 Notes: Beware that Emacs only supports integers up to 61 bits.
-### <a name="14"/> sqlite3-get-autocommit
-~~~el
+*** sqlite3-get-autocommit
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-get-autocommit database-handle)
-~~~
+#+END_SRC
 Return 1 / 0 if auto-commit mode is ON / OFF.
-### <a name="15"/> sqlite3-exec
-~~~el
+*** sqlite3-exec
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-exec database-handle sql-statements &optional callback)
-~~~
+#+END_SRC
 The Swiss Army Knife of the API, you can execute multiple SQL statements
 (separated by ";") in a row with just one call.
 
 The callback function, if supplied, is invoked for *each row* and should 
accept 3
- parameters:
+ parameters: 
  1. the first parameter is the number of columns in the current row;
- 2. the second parameter is the actual data (as a list strings or nil in case 
of NULL);
- 3. the third one is a list of column names.
-
-To signal an error condition inside the callback, return `nil`.
-`sqlite3_exec()` will stop the execution and raise 'db-error.
+ 2. the second parameter is the actual data (as a list strings or nil in case 
of NULL); 
+ 3. the third one is a list of column names. 
+ 
+To signal an error condition inside the callback, return ~nil~.
+~sqlite3_exec()~ will stop the execution and raise 'db-error.
 
 Raises db-error in case of error.
 
 An example of a callback:
-~~~el
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (defun print-row (ncols data names)
   (cl-loop for i from 0 to (1- ncols) do
            (message "[Column %d/%d]%s=%s" (1+ i) ncols (elt names i) (elt data 
i)))
   (message "--------------------")
   t)
-
+  
 (sqlite3-exec dbh "select * from table_a; select * from table b"
               #'print-row)
-~~~
+#+END_SRC
 More examples:
-~~~el
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 ;; Update/delete/insert
 (sqlite3-exec dbh "delete from table") ;; delete returns no rows
 
 ;; Retrieve the metadata of columns in a table
 (sqlite3-exec dbh "pragma table_info(table)" #'print-row)
-~~~
-### <a name="16"/> sqlite3-bind-*
-~~~el
+#+END_SRC
+*** sqlite3-bind-*
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-bind-text statement-handle column-no value)
 (sqlite3-bind-int64 statement-handle column-no value)
 (sqlite3-bind-double statement-handle column-no value)
 (sqlite3-bind-null statement-handle column-no)
-~~~
+#+END_SRC
 The above four functions bind values to a compiled SQL statements.
 
 Please note that column number starts from 1, not 0!
-~~~el
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-bind-parameter-count statement-handle)
-~~~
-The above functions returns the number of SQL parameters of a prepared
+#+END_SRC
+The above functions returns the number of SQL parameters of a prepared 
 statement.
-### <a name="17"/> sqlite3-bind-multi
-~~~el
+*** sqlite3-bind-multi
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-bind-multi statement-handle &rest params)
-~~~
-`sqlite3-bind-multi` binds multiple parameters to a prepared SQL
-statement. It is not part of the official API but is provided for
+#+END_SRC
+~sqlite3-bind-multi~ binds multiple parameters to a prepared SQL 
+statement. It is not part of the official API but is provided for 
 convenience.
 
 Example:
-~~~el
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-bind-multi stmt 1234 "a" 1.555 nil) ;; nil for NULL
-~~~
-### <a name="18"/> sqlite3-column-*
+#+END_SRC
+*** sqlite3-column-*
 These column functions are used to retrieve the current row
 of the result set.
 
-~~~el
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-column-count statement-handle)
-~~~
+#+END_SRC
 Return number of columns in a result set.
-~~~e1
+#+END_SRCe1
 (sqlite3-column-type statement-handle column-no)
-~~~
-Return the type (`sqlite-integer`, `sqlite-float`, `sqlite3-text` or
-`sqlite-null`) of the specified column.
+#+END_SRC
+Return the type (~sqlite-integer~, ~sqlite-float~, ~sqlite3-text~ or
+~sqlite-null~) of the specified column. 
 
 Note: Column number starts from 0.
-~~~el
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-column-text statement-handle column-no)
 (sqlite3-column-int64 statement-handle column-no)
 (sqlite3-column-double statement-handle column-no)
-~~~
+#+END_SRC
 The above functions retrieve data of the specified column.
+#+BEGIN_SRC emacs-lisp :eval no :exports code
+(sqlite3-column-name statement-handle column-no)
+#+END_SRC
+This function returns the column name of the specified column.
 
-Note: You can call `sqlite3-column-xxx` on a column even
-if `sqlite3-column-type` returns `sqlite-yyy`: the SQLite3 engine will
+Note: You can call ~sqlite3-column-xxx~ on a column even 
+if ~sqlite3-column-type~ returns ~sqlite-yyy~: the SQLite3 engine will
 perform the necessary type conversion.
 
 Example:
-~~~el
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (setq stmt (sqlite3-prepare dbh "select * from temp"))
 (while (= sqlite-row (sqlite3-step stmt))
        (let ((name (sqlite3-column-text stmt 0))
              (age (sqlite3-column-int64 stmt 1)))
       (message "name: %s, age: %d" name age)))
-~~~
-### <a name="19"/> sqlite3-fetch
-~~~el
+#+END_SRC
+*** sqlite3-fetch
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-fetch statement-handle) ;; returns a list such as (123 56 "Peter 
Smith" nil)
-~~~
-`sqlite3-fetch` is not part of the official API but provided for
-convenience. It retrieves the current row as a
+#+END_SRC
+~sqlite3-fetch~ is not part of the official API but provided for 
+convenience. It retrieves the current row as a 
 list without having to deal with sqlite3-column-* explicitly.
 
-### <a name="20"/> sqlite3-fetch-alist
-~~~el
+*** sqlite3-fetch-alist
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-fetch-alist statement-handle)
-~~~
-`sqlite3-fetch-alist` is not part of the official API but provided for
+#+END_SRC
+~sqlite3-fetch-alist~ is not part of the official API but provided for 
 convenience. It retrieves the current row as an
-alist in the form of `(("col_name1" . value1) ("col_name2" . value2) ..)`
+alist in the form of ~(("col_name1" . value1) ("col_name2" . value2) ..)~
 
-## <a name="21"/> Transaction Support
-Use `sqlite3-exec` to start, commit and rollback a transaction:
-~~~el
+** Transaction Support
+Use ~sqlite3-exec~ to start, commit and rollback a transaction:
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (sqlite3-exec dbh "begin")
 (sqlite3-exec dbh "commit")
 (sqlite3-exec dbh "rollback")
-~~~
-See Error Handling below on how to use the 
[`condition-case`](https://www.gnu.org/software/emacs/manual/html_node/elisp/Handling-Errors.html)
 form to handle rollback.
-## <a name="22"/> Error Handling
-Currently two error symbols are defined in `sqlite3-api.el`:
-1. `sql-error` is raised by `sqlite3-prepare`
-2. `db-error` is raised by `sqlite3-open` and `sqlite3-exec`
-
-~~~el
+#+END_SRC
+See Error Handling below on how to use the 
[[https://www.gnu.org/software/emacs/manual/html_node/elisp/Handling-Errors.html][~condition-case~]]
 form to handle rollback.
+** Error Handling
+Currently two error symbols are defined in ~sqlite3-api.el~:
+1. ~sql-error~ is raised by ~sqlite3-prepare~
+2. ~db-error~ is raised by ~sqlite3-open~ and ~sqlite3-exec~
+
+#+BEGIN_SRC emacs-lisp :eval no :exports code
 (condition-case db-err
     (progn
       (sqlite3-exec dbh "begin")
@@ -318,39 +298,39 @@ Currently two error symbols are defined in 
`sqlite3-api.el`:
   (db-error
    (message "Symbol:%s, Message:%s, Error Code:%d" (elt db-err 0) (elt db-err 
1) (elt db-err 2))
    (sqlite3-exec dbh "rollback")))
-~~~
-`db-err` is a list containing the error symbol (`db-error` or `sql-error`), an 
error message and finally an error code returned from the
+#+END_SRC
+~db-err~ is a list containing the error symbol (~db-error~ or ~sql-error~), an 
error message and finally an error code returned from the 
 corresponding SQLite
 C API.
 
-## <a name="23"/> A Note on Garbage Collection
-Since Emacs's garbage collection is non-deterministic, it would be
-a good idea
+** A Note on Garbage Collection
+Since Emacs's garbage collection is non-deterministic, it would be 
+a good idea 
 to manually free database/statement handles once they are not needed.
 
-## <a name="24"/> Known Problems
+** Known Problems
 - SQLite3 supports 64 bit integers but Emacs integers are only 61 bits.
 For integers > 61 bits you can retrieve them as text as a workaround.
 - BLOB and TEXT columns with embedded NULLs are not supported.
 
-## <a name="25"/> License
-The code is licensed under the [GNU GPL 
v3](https://www.gnu.org/licenses/gpl-3.0.html).
+** License
+The code is licensed under the 
[[https://www.gnu.org/licenses/gpl-3.0.html][GNU GPL v3]].
 
-## <a name="26"/> Changelog
-*v0.12 - 2019-05-12
-- `sqlite3-fetch-alist` added
+** Changelog
+*v0.12 - 2019-05-12*
+- ~sqlite3-fetch-alist~ added
 - Fixed a compilation problem on macOS Mojave
 
 *v0.11 - 2017-09-14*
-- `sqlite3-finalize` now accepts multiple handles.
+- ~sqlite3-finalize~ now accepts multiple handles.
 
 *v0.1 - 2017-09-04*
 - Emacs Lisp code removed. The package is now pure C.
 
 *v0.0 - 2017-08-29*
-- Fixed a memory leak in `sql_api_exec()`
-- Changed `sqlite3_close()` to `sqlite3_close_v2()` in `sqlite_api_close()`
+- Fixed a memory leak in ~sql_api_exec()~
+- Changed ~sqlite3_close()~ to ~sqlite3_close_v2()~ in ~sqlite_api_close()~
 - Better error handling: Error code is returned along with error message
-## <a name="27"/> Useful Links for Writing Dynamic Modules
+** Useful Links for Writing Dynamic Modules
 - https://phst.github.io/emacs-modules
 - http://nullprogram.com/blog/2016/11/05/