Doc updates for 1.0

Author: quinnj

docs/src/index.md

@@ -30,21 +30,16 @@ SQLite.@sr_str
 SQLite.sqlreturn
 ```
 
-* `SQLite.sqlreturn(contex, val)`
-
-  This function should never be called explicitly. Instead it is exported so that it can be overloaded when necessary, see below.
-
-
 ## User Defined Functions
 
 ### [SQLite Regular Expressions](@id regex)
 
 SQLite provides syntax for calling
 the [`regexp` function](http://sqlite.org/lang_expr.html#regexp)
-from inside `WHERE` clauses.
-Unfortunately, however,
-SQLite does not provide a default implementation of the `regexp` function,
-so SQLite.jl creates one automatically when you open a database.
+from inside `WHERE` clauses. Unfortunately, however, sqlite does not provide
+a default implementation of the `regexp` function. It can be easily added,
+however, by calling `SQLite.@register db SQLite.regexp`
+
 The function can be called in the following ways
 (examples using the [Chinook Database](http://chinookdatabase.codeplex.com/))
 
@@ -55,15 +50,15 @@ julia> db = SQLite.DB("Chinook_Sqlite.sqlite")
 
 julia> # using SQLite's in-built syntax
 
-julia> SQLite.Query(db, "SELECT FirstName, LastName FROM Employee WHERE LastName REGEXP 'e(?=a)'") |> DataFrame
+julia> DBInterface.execute(db, "SELECT FirstName, LastName FROM Employee WHERE LastName REGEXP 'e(?=a)'") |> DataFrame
 1x2 ResultSet
 | Row | "FirstName" | "LastName" |
 |-----|-------------|------------|
 | 1   | "Jane"      | "Peacock"  |
 
 julia> # explicitly calling the regexp() function
 
-julia> SQLite.Query(db, "SELECT * FROM Genre WHERE regexp('e[trs]', Name)") |> DataFrame
+julia> DBInterface.execute(db, "SELECT * FROM Genre WHERE regexp('e[trs]', Name)") |> DataFrame
 6x2 ResultSet
 | Row | "GenreId" | "Name"               |
 |-----|-----------|----------------------|
@@ -76,20 +71,20 @@ julia> SQLite.Query(db, "SELECT * FROM Genre WHERE regexp('e[trs]', Name)") |> D
 
 julia> # you can even do strange things like this if you really want
 
-julia> SQLite.Query(db, "SELECT * FROM Genre ORDER BY GenreId LIMIT 2") |> DataFrame
+julia> DBInterface.execute(db, "SELECT * FROM Genre ORDER BY GenreId LIMIT 2") |> DataFrame
 2x2 ResultSet
 | Row | "GenreId" | "Name" |
 |-----|-----------|--------|
 | 1   | 1         | "Rock" |
 | 2   | 2         | "Jazz" |
 
-julia> SQLite.Query(db, "INSERT INTO Genre VALUES (regexp('^word', 'this is a string'), 'My Genre')") |> DataFrame
+julia> DBInterface.execute(db, "INSERT INTO Genre VALUES (regexp('^word', 'this is a string'), 'My Genre')") |> DataFrame
 1x1 ResultSet
 | Row | "Rows Affected" |
 |-----|-----------------|
 | 1   | 0               |
 
-julia> SQLite.Query(db, "SELECT * FROM Genre ORDER BY GenreId LIMIT 2") |> DataFrame
+julia> DBInterface.execute(db, "SELECT * FROM Genre ORDER BY GenreId LIMIT 2") |> DataFrame
 2x2 ResultSet
 | Row | "GenreId" | "Name"     |
 |-----|-----------|------------|
@@ -103,13 +98,13 @@ for example `"\y"` simply becomes `"y"`.
 For example, the following two queries are identical:
 
 ```julia
-julia> SQLite.Query(db, "SELECT * FROM MediaType WHERE Name REGEXP '-\d'") |> DataFrame
+julia> DBInterface.execute(db, "SELECT * FROM MediaType WHERE Name REGEXP '-\d'") |> DataFrame
 1x1 ResultSet
 | Row | "Rows Affected" |
 |-----|-----------------|
 | 1   | 0               |
 
-julia> SQLite.Query(db, "SELECT * FROM MediaType WHERE Name REGEXP '-d'") |> DataFrame
+julia> DBInterface.execute(db, "SELECT * FROM MediaType WHERE Name REGEXP '-d'") |> DataFrame
 1x1 ResultSet
 | Row | "Rows Affected" |
 |-----|-----------------|
@@ -124,15 +119,15 @@ The previous query can then successfully be run like so:
 ```julia
 julia> # manually escaping backslashes
 
-julia> SQLite.Query(db, "SELECT * FROM MediaType WHERE Name REGEXP '-\\d'") |> DataFrame
+julia> DBInterface.execute(db, "SELECT * FROM MediaType WHERE Name REGEXP '-\\d'") |> DataFrame
 1x2 ResultSet
 | Row | "MediaTypeId" | "Name"                        |
 |-----|---------------|-------------------------------|
 | 1   | 3             | "Protected MPEG-4 video file" |
 
 julia> # using sr"..."
 
-julia> SQLite.Query(db, sr"SELECT * FROM MediaType WHERE Name REGEXP '-\d'") |> DataFrame
+julia> DBInterface.execute(db, sr"SELECT * FROM MediaType WHERE Name REGEXP '-\d'") |> DataFrame
 1x2 ResultSet
 | Row | "MediaTypeId" | "Name"                        |
 |-----|---------------|-------------------------------|
@@ -147,27 +142,27 @@ but it may be changed in the future to escape only characters which are part of
 
 SQLite.jl also provides a way
 that you can implement your own [Scalar Functions](https://www.sqlite.org/lang_corefunc.html).
-This is done using the [`register`](@ref) function and  macro.
+This is done using the [`SQLite.register`](@ref) function and  macro.
 
-[`@register`](@ref) takes a [`SQLite.DB`](@ref) and a function.
+[`SQLite.@register`](@ref) takes a [`SQLite.DB`](@ref) and a function.
 The function can be in block syntax:
 
 ```julia
-julia> @register db function add3(x)
+julia> SQLite.@register db function add3(x)
        x + 3
        end
 ```
 
 inline function syntax:
 
 ```julia
-julia> @register db mult3(x) = 3 * x
+julia> SQLite.@register db mult3(x) = 3 * x
 ```
 
 and previously defined functions:
 
 ```julia
-julia> @register db sin
+julia> SQLite.@register db sin
 ```
 
 The [`SQLite.register`](@ref) function takes optional arguments;
@@ -213,8 +208,7 @@ For this reason the following method was defined:
 sqlreturn(context, val::Bool) = sqlreturn(context, int(val))
 ```
 
-Any new method defined for `sqlreturn`
-must take two arguments
+Any new method defined for `sqlreturn` must take two arguments
 and must pass the first argument straight through as the first argument.
 
 ### Custom Aggregate Functions

src/SQLite.jl

@@ -16,27 +16,22 @@ sqliteerror(db) = throw(SQLiteException(unsafe_string(sqlite3_errmsg(db.handle))
 sqliteexception(db) = SQLiteException(unsafe_string(sqlite3_errmsg(db.handle)))
 
 """
-Represents an SQLite database, either backed by an on-disk file or in-memory
+    `SQLite.DB()` => in-memory SQLite database
+    `SQLite.DB(file)` => file-based SQLite database
 
-Constructors:
+Constructors for a representation of an sqlite database, either backed by an on-disk file or in-memory.
 
-* `SQLite.DB()` => in-memory SQLite database
-* `SQLite.DB(file)` => file-based SQLite database
-
-`SQLite.DB(file::AbstractString)`
-
-`SQLite.DB` requires the `file` string argument
+`SQLite.DB` requires the `file` string argument in the 2nd definition
 as the name of either a pre-defined SQLite database to be opened,
 or if the file doesn't exist, a database will be created.
 Note that only sqlite 3.x version files are supported.
 
-The `SQLite.DB` object
-represents a single connection to an SQLite database.
+The `SQLite.DB` object represents a single connection to an SQLite database.
 All other SQLite.jl functions take an `SQLite.DB` as the first argument as context.
 
 To create an in-memory temporary database, call `SQLite.DB()`.
 
-The `SQLite.DB` will automatically closed/shutdown when it goes out of scope
+The `SQLite.DB` will be automatically closed/shutdown when it goes out of scope
 (i.e. the end of the Julia session, end of a function call wherein it was created, etc.)
 """
 mutable struct DB <: DBInterface.Connection
@@ -71,6 +66,8 @@ end
 Base.show(io::IO, db::SQLite.DB) = print(io, string("SQLite.DB(", "\"$(db.file)\"", ")"))
 
 """
+    SQLite.Stmt(db, sql) => SQL.Stmt
+
 Constructs and prepares (compiled by the SQLite library)
 an SQL statement in the context of the provided `db`.
 Note the SQL statement is not actually executed,
@@ -88,7 +85,7 @@ mutable struct Stmt <: DBInterface.Statement
     params::Dict{Int, Any}
     status::Int
 
-    function Stmt(db::DB,sql::AbstractString)
+    function Stmt(db::DB, sql::AbstractString)
         handle = Ref{Ptr{Cvoid}}()
         sqliteprepare(db, sql, handle, Ref{Ptr{Cvoid}}())
         stmt = new(db, handle[], Dict{Int, Any}(), 0)
@@ -111,9 +108,9 @@ include("UDF.jl")
 export @sr_str
 
 """
-`SQLite.clear!(stmt::SQLite.Stmt)`
+    SQLite.clear!(stmt::SQLite.Stmt)
 
-clears any bound values to a prepared SQL statement.
+Clears any bound values to a prepared SQL statement
 """
 function clear!(stmt::Stmt)
     sqlite3_clear_bindings(stmt.handle)
@@ -122,12 +119,12 @@ function clear!(stmt::Stmt)
 end
 
 """
-`SQLite.bind!(stmt::SQLite.Stmt, values)`
+    SQLite.bind!(stmt::SQLite.Stmt, values)
 
 bind `values` to parameters in a prepared [`SQLite.Stmt`](@ref). Values can be:
 
-* `Vector`; where each element will be bound to an SQL parameter by index order
-* `Dict`; where dict values will be bound to named SQL parameters by the dict key
+* `Vector` or `Tuple`: where each element will be bound to an SQL parameter by index order
+* `Dict` or `NamedTuple`; where values will be bound to named SQL parameters by the `Dict`/`NamedTuple` key
 
 Additional methods exist for working individual SQL parameters:
 
@@ -342,7 +339,7 @@ julia> db = SQLite.DB(mktemp()[1]);
 
 julia> tbl |> SQLite.load!(db, "temp");
 
-julia> SQLite.Query(db,"SELECT * FROM temp WHERE label IN ('a','b','c')") |> DataFrame
+julia> DBInterface.execute(db,"SELECT * FROM temp WHERE label IN ('a','b','c')") |> DataFrame
 4×2 DataFrame
 │ Row │ label   │ value    │
 │     │ String⍰ │ Float64⍰ │
@@ -354,7 +351,7 @@ julia> SQLite.Query(db,"SELECT * FROM temp WHERE label IN ('a','b','c')") |> Dat
 
 julia> q = ['a','b','c'];
 
-julia> SQLite.Query(db,"SELECT * FROM temp WHERE label IN (\$(SQLite.esc_id(q)))")
+julia> DBInterface.execute(db,"SELECT * FROM temp WHERE label IN (\$(SQLite.esc_id(q)))") |> DataFrame
 4×2 DataFrame
 │ Row │ label   │ value    │
 │     │ String⍰ │ Float64⍰ │
@@ -372,10 +369,8 @@ esc_id(X::AbstractVector{S}) where {S <: AbstractString} = join(map(esc_id, X),
 
 # Transaction-based commands
 """
-`SQLite.transaction(db, mode="DEFERRED")`
-
-`SQLite.transaction(func, db)`
-
+    SQLite.transaction(db, mode="DEFERRED")
+    SQLite.transaction(func, db)
 
 Begin a transaction in the specified `mode`, default = "DEFERRED".
 
@@ -414,10 +409,8 @@ end
 end
 
 """
-`SQLite.commit(db)`
-
-`SQLite.commit(db, name)`
-
+    SQLite.commit(db)
+    SQLite.commit(db, name)
 
 commit a transaction or named savepoint
 """
@@ -427,10 +420,8 @@ commit(db) = execute(db, "COMMIT TRANSACTION;")
 commit(db, name) = execute(db, "RELEASE SAVEPOINT $(name);")
 
 """
-`SQLite.rollback(db)`
-
-`SQLite.rollback(db, name)`
-
+    SQLite.rollback(db)
+    SQLite.rollback(db, name)
 
 rollback transaction or named savepoint
 """
@@ -440,7 +431,7 @@ rollback(db) = execute(db, "ROLLBACK TRANSACTION;")
 rollback(db, name) = execute(db, "ROLLBACK TRANSACTION TO SAVEPOINT $(name);")
 
 """
-`SQLite.drop!(db, table; ifexists::Bool=true)`
+    SQLite.drop!(db, table; ifexists::Bool=true)
 
 drop the SQLite table `table` from the database `db`; `ifexists=true` will prevent an error being thrown if `table` doesn't exist
 """
@@ -454,7 +445,7 @@ function drop!(db::DB, table::AbstractString; ifexists::Bool=false)
 end
 
 """
-`SQLite.dropindex!(db, index; ifexists::Bool=true)`
+    SQLite.dropindex!(db, index; ifexists::Bool=true)
 
 drop the SQLite index `index` from the database `db`; `ifexists=true` will not return an error if `index` doesn't exist
 """
@@ -467,6 +458,8 @@ function dropindex!(db::DB, index::AbstractString; ifexists::Bool=false)
 end
 
 """
+    SQLite.createindex!(db, table, index, cols; unique=true, ifnotexists=false)
+
 create the SQLite index `index` on the table `table` using `cols`,
 which may be a single column or vector of columns.
 `unique` specifies whether the index will be unique or not.
@@ -484,8 +477,9 @@ function createindex!(db::DB, table::AbstractString, index::AbstractString, cols
 end
 
 """
-Removes duplicate rows from `table`
-based on the values in `cols`, which is an array of column names.
+    SQLite.removeduplicates!(db, table, cols)
+
+Removes duplicate rows from `table` based on the values in `cols`, which is an array of column names.
 
 A convenience method for the common task of removing duplicate
 rows in a dataset according to some subset of columns that make up a "primary key".
@@ -506,35 +500,35 @@ function removeduplicates!(db, table::AbstractString, cols::AbstractArray{T}) wh
 include("tables.jl")
 
 """
-`SQLite.tables(db, sink=columntable)`
+    SQLite.tables(db, sink=columntable)
 
 returns a list of tables in `db`
 """
 tables(db::DB, sink=columntable) = DBInterface.execute(db, "SELECT name FROM sqlite_master WHERE type='table';") |> sink
 
 """
-`SQLite.indices(db, sink=columntable)`
+    SQLite.indices(db, sink=columntable)
 
 returns a list of indices in `db`
 """
 indices(db::DB, sink=columntable) = DBInterface.execute(db, "SELECT name FROM sqlite_master WHERE type='index';") |> sink
 
 """
-`SQLite.columns(db, table, sink=columntable)`
+    SQLite.columns(db, table, sink=columntable)
 
 returns a list of columns in `table`
 """
 columns(db::DB, table::AbstractString, sink=columntable) = DBInterface.execute(db, "PRAGMA table_info($(esc_id(table)))") |> sink
 
 """
-`SQLite.last_insert_rowid(db)`
+    SQLite.last_insert_rowid(db)
 
 returns the auto increment id of the last row
 """
 last_insert_rowid(db::DB) = sqlite3_last_insert_rowid(db.handle)
 
 """
-`SQLite.enable_load_extension(db, enable::Bool=true)`
+    SQLite.enable_load_extension(db, enable::Bool=true)
 
 Enables extension loading (off by default) on the sqlite database `db`. Pass `false` as the second argument to disable.
 """

src/UDF.jl

@@ -189,7 +189,7 @@ function finalfunc(init, func, fsym=Symbol(string(func)*"_final"))
 end
 
 """
-    @register db function
+    SQLite.@register db function
 
 User-facing macro for convenience in registering a simple function
 with no configurations needed
@@ -199,6 +199,9 @@ macro register(db, func)
 end
 
 """
+    SQLite.register(db, func)
+    SQLite.register(db, init, step_func, final_func; nargs=-1, name=string(step), isdeterm=true)
+
 Register a scalar (first method) or aggregate (second method) function
 with a [`SQLite.DB`](@ref).
 """