~subsetpark/doozer

4a8e0e3e91283d2506d07e897fb16864624e00f8 — Zach Smith 1 year, 10 days ago e3c58a8 master v0.0.1
update docs
1 files changed, 108 insertions(+), 25 deletions(-)

M README.md
M README.md => README.md +108 -25
@@ 4,7 4,7 @@

*This software is currently Alpha quality and in heavy development!*

Doozer is a library, inspired by Elixir's [Ecto][ecto], which provides the
Doozer is a library, inspired by Elixir's [Ecto][ecto], which provides the
ability to write SQL queries using a convenient, idiomatic Janet DSL, which
are highly composable---that is, doozer produces data structures which should
be easy to combine in order to create new SQL queries.


@@ 32,15 32,15 @@ The basic flow of a doozer query is:
2. Render that into concrete SQL using the function `to-sql`
3. Evaluate the SQL using the library associated with a specific database

For instance, here's an entire session using SQLite:
For instance, here's an entire session using SQLite:

```
(use doozer)
(import sqlite3)

(def db (sqlite3/open "chinook.db"))
(def db (sqlite3/open "chinook.db"))

(def q (from "artists" a :select [name]))
(def q (from "artists" a :select [name]))
(def sql-and-params (to-sql q))

(sqlite3/eval ;sql-and-params)


@@ 121,14 121,14 @@ The backend for emitting PostgresQL source.
**table**  | [source][5]

```janet
@{:assemble-base <function assemble-base> :assemble-join-clauses <function assemble-join-clauses> :assemble-select-clauses <function assemble-select-clauses> :assemble-where-clauses <function assemble-where-clauses> :render-apply <function render-apply> :render-element <function render-expression-element> :render-function-arguments <function function-arguments> :render-join <function render-join> :render-limit <function render-limit> :render-operation <function render-operation> :render-subquery <function render-subquery>}
@{:assemble-base <function assemble-base> :assemble-join-clauses <function assemble-join-clauses> :assemble-select-clauses <function assemble-select-clauses> :assemble-where-clauses <function assemble-where-clauses> :render-apply <function render-apply> :render-as <function render-as> :render-element <function render-expression-element> :render-function-arguments <function function-arguments> :render-join <function render-join> :render-limit <function render-limit> :render-operation <function render-operation> :render-subquery <function render-subquery>}
```

The generic doozer backend for all SQL dialects. To be used as a
prototype to be overridden by implementation-specific backends (SQLite,
PostgresQL, etc.)

[5]: doozer/backends/sql.janet#L1
[5]: doozer/backends/sql.janet#L3

## doozer/backends/sqlite



@@ 160,13 160,57 @@ The backend for emitting SQLite3-compatible source.

[8]: doozer/backends/sqlite.janet#L17

## doozer/common

[make-alias](#make-alias), [operators](#operators)

## make-alias

**function**  | [source][9]

```janet
(make-alias &opt prefix)
```



[9]: doozer/common.janet#L1

## operators

**struct**  | [source][10]

```janet
{* "%s * %s" + "%s + %s" - "%s - %s" / "%s / %s" < "%s < %s" <= "%s <= %s" = "%s = %s" > "%s > %s" >= "%s >= %s" and "(%s AND %s)" between "%s BETWEEN %s AND %s" exists "EXISTS %s" glob "%s GLOB %s" in "%s IN %s" like "%s LIKE %s" mod "%s % %s" nil? "%s IS NULL" not "NOT %s" not-in "%s NOT IN %s" not= "%s <> %s" or "(%s OR %s)" string "%s || %s" unique "UNIQUE %s"}
```



[10]: doozer/common.janet#L10

## doozer/compose

[compose-query](#compose-query)

## compose-query

**function**  | [source][11]

```janet
(compose-query query-or-table binding {:where where :join join :select select})
```



[11]: doozer/compose.janet#L89

## doozer

[from](#from), [get-config](#get-config), [get-sources](#get-sources), [to-sql](#to-sql), [where](#where)
[from](#from), [get-config](#get-config), [get-sources](#get-sources), [join](#join), [select](#select), [to-sql](#to-sql), [where](#where)

## from

**macro**  | [source][9]
**macro**  | [source][12]

```janet
(from query-or-table & forms)


@@ 178,6 222,14 @@ Construct a new doozer query.
- A string, which should be the name of a table present in the database;
- A symbol bound to an existing query structure.

The query-or-table reference can be wrapped in an `as` s-expression, eg.:

```
(select (as "artists" "main_artists_table"))
```

to specify the table alias used in the query.

`forms` may be headed by an optional binding symbol, followed by any number
of s-expressions, each of which must be headed by one of the following
symbols:


@@ 231,7 283,8 @@ existing variable:
Which is equivalent to the SQL:

```sql
SELECT * FROM artists AS _0000e1 JOIN albums AS _0000e2 ON _0000e2.ArtistId = _0000e1.ArtistId
SELECT * FROM artists AS _0000e1
JOIN albums AS _0000e2 ON _0000e2.ArtistId = _0000e1.ArtistId
```

Join expressions can be written in two different ways. In addition to the


@@ 269,11 322,6 @@ The binding value in a join can be used in WHERE clauses:
`select` should be followed by a list of relation expressions (see Expression
API, below) to select.

### as

`as` can be followed by a string to be used as the alias for the main table
in the SELECT query.

## Query Composition

In addition to create new queries, `from` can be used to compose and reuse


@@ 312,12 360,11 @@ fragment will be **unsafely** interpolated into the SQL query. eg.,
larger expression. `query` here can either be a symbol bound to an existent
query structure, or a form constructing a new one.


[9]: doozer/from.janet#L294
[12]: doozer/from.janet#L175

## get-config

**function**  | [source][10]
**function**  | [source][13]

```janet
(get-config)


@@ 325,11 372,11 @@ query structure, or a form constructing a new one.



[10]: doozer.janet#L18
[13]: doozer.janet#L18

## get-sources

**function**  | [source][11]
**function**  | [source][14]

```janet
(get-sources query)


@@ 341,11 388,47 @@ This can be used, especially in interactive development, to determine if
there's an existing JOIN in `query` that can be reused in subsequent calls to
the `where` macro.

[11]: doozer.janet#L4
[14]: doozer.janet#L4

## join

**function**  | [source][15]

```janet
(join query join-expr)
```

Given an existing query, create a new query with an additional single
`join` clause.

Any unqualified symbol references will be treated, as in `from`, as
references to columns on the joined table. No new bindings can be created
with this function; however, existing named bindings can be referred to. See the
`:as` key in the `:join` section of the `from` documentation for details.

[15]: doozer/from.janet#L344

## select

**function**  | [source][16]

```janet
(select query & select-exprs)
```

Given an existing query, create a new query with an additional single
`select` clause.

Any unqualified symbol references will be treated, as in `from`, as
references to columns on the main query table. No new bindings can be created
with this function; however, existing named bindings can be referred to. See the
`:as` key in the `:join` section of the `from` documentation for details.

[16]: doozer/from.janet#L358

## to-sql

**function**  | [source][12]
**function**  | [source][17]

```janet
(to-sql query)


@@ 356,11 439,11 @@ Render `query` into SQL. Produces a two-tuple of [sql, parameters], where
a dictionary mapping those placeholders to the values that should be
interpolated into the query.

[12]: doozer/to-sql.janet#L88
[17]: doozer/to-sql.janet#L102

## where

**function**  | [source][13]
**function**  | [source][18]

```janet
(where query where-expr)


@@ 371,8 454,8 @@ Given an existing query, create a new query with an additional single

Any unqualified symbol references will be treated, as in `from`, as
references to columns on the main query table. No new bindings can be created
with this macro; however, existing named bindings can be referred to. See the
with this function; however, existing named bindings can be referred to. See the
`:as` key in the `:join` section of the `from` documentation for details.

[13]: doozer/from.janet#L446
[18]: doozer/from.janet#L330