Update README.md

Add a short tutorial on regexp and UDFs.

Author: Sean1708

README.md

@@ -73,3 +73,162 @@ A Julia interface to the SQLite library and support for operations on DataFrames
 * `drop(db::SQLiteDB,table::String)`
 
   `drop` is pretty self-explanatory. It's really just a convenience wrapper around `query` to execute a DROP TABLE command, while also calling "VACUUM" to clean out freed memory from the database.
+
+#### User Defined Functions
+
+##### SQLite Regular Expressions
+
+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. The function can be called in the following ways (examples using the [Chinook Database](http://chinookdatabase.codeplex.com/))
+
+```julia
+julia> using SQLite
+
+julia> db = SQLiteDB("Chinook_Sqlite.sqlite")
+
+julia> # using SQLite's in-built syntax
+
+julia> query(db, "SELECT FirstName, LastName FROM Employee WHERE LastName REGEXP 'e(?=a)'")
+1x2 ResultSet
+| Row | "FirstName" | "LastName" |
+|-----|-------------|------------|
+| 1   | "Jane"      | "Peacock"  |
+
+julia> # explicitly calling the regexp() function
+
+julia> query(db, "SELECT * FROM Genre WHERE regexp('e[trs]', Name)")
+6x2 ResultSet
+| Row | "GenreId" | "Name"               |
+|-----|-----------|----------------------|
+| 1   | 3         | "Metal"              |
+| 2   | 4         | "Alternative & Punk" |
+| 3   | 6         | "Blues"              |
+| 4   | 13        | "Heavy Metal"        |
+| 5   | 23        | "Alternative"        |
+| 6   | 25        | "Opera"              |
+
+julia> # you can even do strange things like this if you really want
+
+julia> query(db, "SELECT * FROM Genre ORDER BY GenreId LIMIT 2")
+2x2 ResultSet
+| Row | "GenreId" | "Name" |
+|-----|-----------|--------|
+| 1   | 1         | "Rock" |
+| 2   | 2         | "Jazz" |
+
+julia> query(db, "INSERT INTO Genre VALUES (regexp('^word', 'this is a string'), 'My Genre')")
+1x1 ResultSet
+| Row | "Rows Affected" |
+|-----|-----------------|
+| 1   | 0               |
+
+julia> query(db, "SELECT * FROM Genre ORDER BY GenreId LIMIT 2")
+2x2 ResultSet
+| Row | "GenreId" | "Name"     |
+|-----|-----------|------------|
+| 1   | 0         | "My Genre" |
+| 2   | 1         | "Rock"     |
+```
+
+Due to the heavy use of escape characters you may run into problems where julia parses out some backslashes in your query, for example `"\y"` simlpy becomes `"y"`. For example the following two queries are identical
+
+```julia
+julia> query(db, "SELECT * FROM MediaType WHERE Name REGEXP '-\d'")
+1x1 ResultSet
+| Row | "Rows Affected" |
+|-----|-----------------|
+| 1   | 0               |
+
+julia> query(db, "SELECT * FROM MediaType WHERE Name REGEXP '-d'")
+1x1 ResultSet
+| Row | "Rows Affected" |
+|-----|-----------------|
+| 1   | 0               |
+```
+
+This can be avoided in two ways. You can either escape each backslash yourself or you can use the sr"..." string literal that SQLite.jl exports. The previous query can then successfully be run like so
+
+```julia
+julia> # manually escaping backslashes
+
+julia> query(db, "SELECT * FROM MediaType WHERE Name REGEXP '-\\d'")
+1x2 ResultSet
+| Row | "MediaTypeId" | "Name"                        |
+|-----|---------------|-------------------------------|
+| 1   | 3             | "Protected MPEG-4 video file" |
+
+julia> # using sr"..."
+
+julia> query(db, sr"SELECT * FROM MediaType WHERE Name REGEXP '-\d'")
+1x2 ResultSet
+| Row | "MediaTypeId" | "Name"                        |
+|-----|---------------|-------------------------------|
+| 1   | 3             | "Protected MPEG-4 video file" |
+```
+
+The sr"..." currently escapes all special characters in a string but it may be changed in the future to escape only characters which are part of a regex.
+
+##### Custom Scalar Functions
+
+SQLite.jl also provides a way that you can implement your own [Scalar Functions](https://www.sqlite.org/lang_corefunc.html) (though [Aggregate Functions](https://www.sqlite.org/lang_aggfunc.html) are not currently supported). This is done using the `registerfunc` function and `@scalarfunc` macro.
+
+`@scalarfunc` takes an optional function name and a function and defines a new function which can be passed to `registerfunc`. It can be used with block function syntax
+
+```julia
+julia> @scalarfunc function add3(x)
+       x + 3
+       end
+add3 (generic function with 1 method)
+
+julia> @scalarfunc add5 function irrelevantfuncname(x)
+       x + 5
+       end
+add5 (generic function with 1 method)
+```
+
+inline function syntax
+
+```julia
+julia> @scalarfunc mult3(x) = 3 * x
+mult3 (generic function with 1 method)
+
+julia> @scalarfunc mult5 anotherirrelevantname(x) = 5 * x
+mult5 (generic function with 1 method)
+```
+
+and previously defined functions (note that name inference does not work with this method)
+
+```julia
+julia> @scalarfunc sin sin
+sin (generic function with 1 method)
+
+julia> @scalarfunc subtract -
+subtract (generic function with 1 method)
+```
+
+The function that is defined can then be passed to `registerfunc`. `registerfunc` takes three arguments; the database to which the function should be registered, the number of arguments that the function takes and the function itself. The function is registered to the database connection rather than the database itself so must be registered each time the database opens. Your function can not take more than 127 arguments unless it takes a variable number of arguments, if it does take a variable number of arguments then you must pass -1 as the second argument to `registerfunc`.
+
+The `@scalarfunc` macro uses the `sqlreturn` function to return your function's return value to SQLite. By default, `sqlreturn` maps the returned value to a [native SQLite type]() or, failing that, serializes the julia value and stores it as a `BLOB`. To change this behaviour simply define a new method for `sqlreturn` which then calls a previously defined method for `sqlreturn`. Methods which map to native SQLite types are
+
+```julia
+sqlreturn(context, ::NullType)
+sqlreturn(context, val::Int32)
+sqlreturn(context, val::Int64)
+sqlreturn(context, val::Float64)
+sqlreturn(context, val::UTF16String)
+sqlreturn(context, val::String)
+sqlreturn(context, val::Any)
+```
+
+As an example, say you would like `BigInt`s to be stored as `TEXT` rather than a `BLOB`. You would simply need to define the following method
+
+```julia
+sqlreturn(context, val::BigInt) = sqlreturn(context, string(val))
+```
+
+Another example is the `sqlreturn` used by the `regexp` function. For `regexp` to work correctly it must return it must return an `Int` (more specifically a `0` or `1`) but `ismatch` (used by `regexp`) returns a `Bool`. For this reason the following method was defined
+
+```julia
+sqlreturn(context, val::Bool) = sqlreturn(context, int(val))
+```
+
+Any new method defined for `sqlreturn` must take two arguments and must pass the first argument straight through as the first argument.