documentation

Author: bramtayl

docs/src/index.md

@@ -2,6 +2,42 @@
 Modules = [QuerySQLite]
 ```
 
+QuerySQLite is an experimental package sponsored by Google Summer of Code. It's
+finally ready for public use. Although QuerySQLite is only tested on SQLite,
+it's been purposefully designed to easily incorporate other database software.
+
+Use [`Database`](@ref) to wrap an external database. Then, you can access its
+tables using `.`, and conduct most `Query` operations on them. In theory, most
+operations should "just work". There are a couple of exceptions.
+
+### Non-overloadable methods
+
+Functions like `ifelse` and `typeof` can't be overloaded. Instead, QuerySQLite
+exports the [`if_else`](@ref) and [`type_of`](@ref) functions and overloads them
+instead.
+
+### No SQL arguments
+
+If you would like to translate code to SQL, but you do not pass any SQL
+arguments, you will need use [`BySQL`](@ref) to pass a dummy SQL object instead.
+See the `BySQL` docstring for more information.
+
+## Developer notes
+
+QuerySQLite hijacks Julia's multiple dispatch to translate external database
+commands to SQL instead of evaluating them. To do this, it construct a
+"model_row" that represents the structure of a row of data. If you would like to
+support for a new function, there are only a few steps:
+
+- Use the `@code_instead` macro to specify the argument types for diversion
+into SQL translation.
+- If your function will modify the row structure of the
+table, define a `model_row_call` method.
+- Use the `@translate_default` macro to name the matching SQL function. If more
+involved processing is required, define a `translate_call` method instead.
+- If you would like to show your SQL expression in a non-standard way, edit the
+`show` method for `SQLExpression`s.
+
 ```@autodocs
 Modules = [QuerySQLite]
 ```

src/QuerySQLite.jl

@@ -1,6 +1,6 @@
 module QuerySQLite
 
-import Base: !, &, |, ==, !=, *, +, %, abs, Char, coalesce, collect, convert, eltype, getproperty, length,
+import Base: !, &, |, ==, !=, *, /, +, -, %, abs, Char, coalesce, collect, convert, eltype, getproperty, length,
 lowercase, in, isdone, isequal, isless, ismissing, iterate, IteratorSize, max, min,
 occursin, rand, replace, repr, round, show, showerror, startswith, string, strip, SubString, uppercase
 using Base: Generator, NamedTuple, RefValue, SizeUnknown, tail

src/code_instead.jl

@@ -9,6 +9,21 @@ end
 
 If you would like a statement to be evaluated by SQL, not Julia, and
 none of the arguments are SQL code, you can use BySQL to hack dispatch.
+
+```jldoctest
+julia> using QuerySQLite
+
+julia> using Query: @map
+
+julia> using DataValues: DataValue
+
+julia> database = Database(joinpath(pathof(QuerySQLite) |> dirname |> dirname, "test", "Chinook_Sqlite.sqlite"));
+
+julia> result = database.Track |> @map({a = rand(BySQL(_), Int)});
+
+julia> collect(result)[1].a isa DataValue{Int}
+true
+```
 """
 struct BySQL{Source}
     source::Source
@@ -119,10 +134,18 @@ end
 @code_instead (*) Any SourceCode
 @code_instead (*) SourceCode SourceCode
 
+@code_instead (-) SourceCode Any
+@code_instead (-) Any SourceCode
+@code_instead (-) SourceCode SourceCode
+
 @code_instead (+) SourceCode Any
 @code_instead (+) Any SourceCode
 @code_instead (+) SourceCode SourceCode
 
+@code_instead (/) SourceCode Any
+@code_instead (/) Any SourceCode
+@code_instead (/) SourceCode SourceCode
+
 @code_instead (%) SourceCode Any
 @code_instead (%) Any SourceCode
 @code_instead (%) SourceCode SourceCode

src/database.jl

@@ -1,7 +1,16 @@
 """
     get_table_names(source)::Tuple{Symbol}
 
-Get the names of the tables in `source`
+Get the names of the tables in `source`.
+
+```jldoctest
+julia> using QuerySQLite
+
+julia> database = Database(joinpath(pathof(QuerySQLite) |> dirname |> dirname, "test", "Chinook_Sqlite.sqlite"));
+
+julia> get_table_names(getfield(database, :source))
+(:Album, :Artist, :Customer, :Employee, :Genre, :Invoice, :InvoiceLine, :MediaType, :Playlist, :PlaylistTrack, :Track)
+```
 """
 function get_table_names(source::DB)
     as_symbols(tables(source).name)
@@ -11,7 +20,16 @@ export get_table_names
 """
     get_column_names(source, table_name)::Tuple{Symbol}
 
-Get the names of the columns in `table_name` in `source`
+Get the names of the columns in `table_name` in `source`.
+
+```jldoctest example
+julia> using QuerySQLite
+
+julia> database = Database(joinpath(pathof(QuerySQLite) |> dirname |> dirname, "test", "Chinook_Sqlite.sqlite"));
+
+julia> get_column_names(getfield(database, :source), :Album)
+(:AlbumId, :Title, :ArtistId)
+```
 """
 function get_column_names(source::DB, table_name)
     as_symbols(columns(source, String(table_name)).name)
@@ -21,19 +39,48 @@ export get_column_names
 """
     struct Database{Source}
 
-`source` need only support [`get_table_names`](@ref) and [`get_column_names`](@ref).
+A wrapper for an external database. `source` need only support
+[`get_table_names`](@ref) and [`get_column_names`](@ref).
+
+```jldoctest
+julia> using QuerySQLite
+
+julia> database = Database(joinpath(pathof(QuerySQLite) |> dirname |> dirname, "test", "Chinook_Sqlite.sqlite"));
+
+julia> database.Track
+?x9 SQLite query result
+TrackId │ Name                                      │ AlbumId │ MediaTypeId
+────────┼───────────────────────────────────────────┼─────────┼────────────
+1       │ "For Those About To Rock (We Salute You)" │ 1       │ 1
+2       │ "Balls to the Wall"                       │ 2       │ 2
+3       │ "Fast As a Shark"                         │ 3       │ 2
+4       │ "Restless and Wild"                       │ 3       │ 2
+5       │ "Princess of the Dawn"                    │ 3       │ 2
+6       │ "Put The Finger On You"                   │ 1       │ 1
+7       │ "Let's Get It Up"                         │ 1       │ 1
+8       │ "Inject The Venom"                        │ 1       │ 1
+9       │ "Snowballed"                              │ 1       │ 1
+10      │ "Evil Walks"                              │ 1       │ 1
+... with more rows, and 5 more columns: GenreId, Composer, Milliseconds, Bytes, UnitPrice
+```
 """
 struct Database{Source}
     source::Source
 end
 
+"""
+    Database(filename::AbstractString)
+
+Guess the database software from the filename.
+"""
 function Database(filename::AbstractString)
     if endswith(filename, ".sqlite")
         Database(SQLite.DB(filename))
     else
         throw(ArgumentError("Unsupported database type for $filename"))
     end
 end
+export Database
 
 get_source(source_tables::Database) = getfield(source_tables, :source)
 

src/show.jl

@@ -100,8 +100,12 @@ function show(io::IO, sql_expression::SQLExpression)
         infix(io, call, arguments...)
     elseif call === :*
         infix(io, call, arguments...)
+    elseif call === :/
+        infix(io, call, arguments...)
     elseif call === :+
         infix(io, call, arguments...)
+    elseif call === :-
+        infix(io, call, arguments...)
     elseif call === :%
         infix(io, call, arguments...)
     elseif call === :AND
@@ -164,3 +168,23 @@ end
 function finalize(something)
     something
 end
+
+"""
+    get_sql(it)
+
+Use `get_sql` if you would like to see the SQL code generated by an SQLite
+query.
+
+```jldoctest example
+julia> using QuerySQLite
+
+julia> database = Database(joinpath(pathof(QuerySQLite) |> dirname |> dirname, "test", "Chinook_Sqlite.sqlite"));
+
+julia> get_sql(database.Track)
+FROM (Track)
+```
+"""
+function get_sql(it)
+    translate(it.code)
+end
+export get_sql

src/translate.jl

@@ -55,8 +55,12 @@ end
 
 @translate_default ::typeof(*) :*
 
+@translate_default ::typeof(/) :/
+
 @translate_default ::typeof(+) :+
 
+@translate_default ::typeof(-) :-
+
 @translate_default ::typeof(%) :%
 
 @translate_default ::typeof(abs) :ABS

test/runtests.jl

@@ -136,7 +136,9 @@ result =
         and_test = _.zero & _.one,
         or_test = _.zero | _.one,
         times_test = _.zero * _.one,
+        divide_test = _.zero / _.one,
         plus_test = _.zero + _.one,
+        minus_test = _.one - _.zero,
         mod_test = _.zero % _.one,
         abs_test = abs(_.negative_one),
         in_test = _.zero in (0, 1),
@@ -183,7 +185,9 @@ result =
 @test result.and_test == 0
 @test result.or_test == 1
 @test result.times_test == 0
+@test result.divide_test == 0
 @test result.plus_test == 1
+@test result.minus_test == 1
 @test result.mod_test == 0
 @test result.abs_test == 1
 @test result.in_test == 1