Merge pull request #67 from JuliaDatabases/tb/julia_api

Improvements to new Julia API

Author: maleadt

README.md

@@ -22,7 +22,7 @@ LMDB.jl exposes the same database through three surfaces:
   `AbstractDict{K,V}` over a single LMDB file. Standard library
   machinery (`merge!`, `filter!`, `pairs`, iteration, …) works out
   of the box. Reach for this when you want a persistent `Dict`.
-- Julia wrappers: `Environment`, `Transaction`, `DBI`, `Cursor`.
+- Julia wrappers: `Environment`, `Transaction`, `Database`, `Cursor`.
   Julia-shaped wrappers around handles, transactions, and cursors,
   with finalizers, `do`-block forms, and so on. Use these when you
   want explicit transactions.

docs/src/index.md

@@ -18,7 +18,7 @@ LMDB.jl exposes the same database through three surfaces:
 | Surface | What it offers | When to use |
 |---------|----------------|-------------|
 | High-level interface | `LMDBDict <: AbstractDict{K,V}` | When you want a persistent `Dict`. |
-| Julia wrappers | `Environment`, `Transaction`, `DBI`, `Cursor` | When you want explicit transactions and cursors with Julia-shaped wrappers. |
+| Julia wrappers | `Environment`, `Transaction`, `Database`, `Cursor` | When you want explicit transactions and cursors with Julia-shaped wrappers. |
 | C API | `LMDB.mdb_*`, `LMDB.MDB_*` | Raw `ccall` bindings and status-code constants, for custom data layouts or when you want to skip allocations on hot paths. |
 
 `MDBValue`, `MDBArg`, and the [`MDBValueIO`](@ref LMDB.MDBValueIO)

docs/src/lib/cursors.md

@@ -4,14 +4,14 @@
 CurrentModule = LMDB
 ```
 
-A `Cursor` is a positioned iterator over the entries in a `DBI`. Cursors
+A `Cursor` is a positioned iterator over the entries in a `Database`. Cursors
 are bound to a transaction. Closing the txn invalidates the cursor.
 
 ## Construction
 
 ```@docs
 Cursor
-Base.open(::Transaction, ::DBI)
+Cursor(::Transaction, ::Database)
 Base.close(::Cursor)
 Base.isopen(::Cursor)
 renew(::Transaction, ::Cursor)

docs/src/lib/databases.md

@@ -1,32 +1,31 @@
-# [Databases](@id API-DBI)
+# [Databases](@id API-Database)
 
 ```@meta
 CurrentModule = LMDB
 ```
 
-A `DBI` (database identifier) is a handle to one B-tree inside an
+A `Database` (database identifier) is a handle to one B-tree inside an
 environment. By default an env has a single anonymous database (the
-"main DB"); pass `maxdbs > 0` to `Environment` and a name to `open` to
-work with multiple named sub-databases.
+"main DB"); pass `maxdbs > 0` to `Environment` and a name to the `Database`
+constructor to work with multiple named sub-databases.
 
 ## Construction
 
 ```@docs
-DBI
-Base.open(::Transaction, ::String)
-Base.close(::Environment, ::DBI)
-Base.isopen(::DBI)
+Database
+Database(::Transaction, ::AbstractString)
+Base.close(::Environment, ::Database)
+Base.isopen(::Database)
 flags
 drop
-Base.stat(::Transaction, ::DBI)
+Base.stat(::Transaction, ::Database)
 ```
 
 ## Reads
 
 ```@docs
-Base.get(::Transaction, ::DBI, ::Any, ::Type{T}) where T
-Base.get(::Transaction, ::DBI, ::Any, ::Type{T}, ::Any) where T
-tryget
+Base.get(::Transaction, ::Database, ::Any, ::Type{T}) where T
+Base.get(::Transaction, ::Database, ::Any, ::Type{T}, ::Any) where T
 ```
 
 `get(txn, dbi, key, T, default)` falls back to `default` if `key` is
@@ -35,11 +34,11 @@ missing, matching `Base.get(dict, key, default)`.
 ## Writes
 
 ```@docs
-Base.put!(::Transaction, ::DBI, ::Any, ::Any)
+Base.put!(::Transaction, ::Database, ::Any, ::Any)
 put_reserved!
-Base.delete!(::Transaction, ::DBI, ::Any)
-Base.replace!(::Transaction, ::DBI, ::Any, ::Any)
-Base.pop!(::Transaction, ::DBI, ::Any, ::Type)
+Base.delete!(::Transaction, ::Database, ::Any)
+Base.replace!(::Transaction, ::Database, ::Any, ::Any)
+Base.pop!(::Transaction, ::Database, ::Any, ::Type)
 ```
 
 ## Write flags

docs/src/lib/dict.md

@@ -32,7 +32,7 @@ Everything `AbstractDict` derives (`merge!`, `merge`, `mergewith!`,
 
 ## Lifecycle
 
-`close(::LMDBDict)` closes the underlying env (and the default DBI).
+`close(::LMDBDict)` closes the underlying env (and the default Database).
 Idempotent, and also called from the finalizer.
 
 ## Prefix-scan helpers

docs/src/lib/environments.md

@@ -13,14 +13,11 @@ cursor lives inside one env.
 ```@docs
 Environment
 Environment(::AbstractString)
-create
-environment
 ```
 
 ## Lifecycle
 
 ```@docs
-Base.open(::Environment, ::String)
 Base.close(::Environment)
 Base.isopen(::Environment)
 sync

docs/src/lib/errors.md

@@ -39,10 +39,10 @@ the `unchecked_*` companion returns the raw `Cint` so the caller can
 branch on `MDB_NOTFOUND`/`MDB_KEYEXIST` and friends.
 
 At the Julia wrappers, handle methods that wrap status-returning
-bindings let `LMDBError` propagate. `tryget` and `get(..., default)`
-swallow `MDB_NOTFOUND` and return `nothing` or `default`.
-`delete!(txn, dbi, key)` likewise swallows `MDB_NOTFOUND` and returns
-`false`.
+bindings let `LMDBError` propagate. `get(..., default)` swallows
+`MDB_NOTFOUND` and returns `default` (use `nothing` for the
+`Union{T,Nothing}` shape). `delete!(txn, dbi, key)` likewise swallows
+`MDB_NOTFOUND` and returns `false`.
 
 At the high-level interface, missing keys produce `KeyError` (matching
 `Base.Dict`), and `pop!(d)` on an empty dict throws `ArgumentError`.

docs/src/lib/lowlevel.md

@@ -39,7 +39,7 @@ since there is nothing to check.
 
 ## Customisation point: `MDBValueIO`
 
-`tryget`, `get`, `key`, `value`, `item`, typed `walk`, `pop!`, and
+`get`, `key`, `value`, `item`, typed `walk`, `pop!`, and
 `replace!` all go through `read(::MDBValueIO, T)` to decode an
 `MDB_val` into a Julia value. Define a `Base.read` method on
 `MDBValueIO` to plug in a custom representation. See [Cursors](@ref)
@@ -107,7 +107,7 @@ mdb_txn_reset
 mdb_txn_renew
 ```
 
-### Database (DBI)
+### Database (Database)
 
 ```julia
 mdb_dbi_open

docs/src/lib/transactions.md

@@ -12,7 +12,7 @@ concurrent readers but only one writer at a time.
 
 ```@docs
 Transaction
-start
+Transaction(::Environment)
 ```
 
 ## Lifecycle
@@ -36,7 +36,7 @@ renew(::Transaction)
 
 ## Sub-transactions
 
-Pass `parent = txn` to [`start`](@ref) to nest a child write transaction
-inside an open write transaction. The child sees the parent's uncommitted
-state; on `commit` the child's changes are folded into the parent, on
-`abort` they are discarded.
+Pass `parent = txn` to [`Transaction`](@ref) to nest a child write
+transaction inside an open write transaction. The child sees the
+parent's uncommitted state; on `commit` the child's changes are folded
+into the parent, on `abort` they are discarded.

docs/src/man/cursors.md

@@ -4,16 +4,16 @@
 CurrentModule = LMDB
 ```
 
-A `Cursor` is a positioned iterator over a `DBI`. Use it for ordered
+A `Cursor` is a positioned iterator over a `Database`. Use it for ordered
 scans, range queries, or to amortise the per-lookup overhead of
 `mdb_get` across many keys.
 
 ## Opening a cursor
 
 ```julia
-start(env; flags = LMDB.MDB_RDONLY) do txn
-    open(txn) do dbi
-        open(txn, dbi) do cur
+Transaction(env; flags = LMDB.MDB_RDONLY) do txn
+    Database(txn) do dbi
+        Cursor(txn, dbi) do cur
             # use cur
         end
     end
@@ -66,9 +66,9 @@ A typical pattern for "all keys with a given prefix":
 
 ```julia
 prefix = "users/"
-start(env; flags = LMDB.MDB_RDONLY) do txn
-    open(txn) do dbi
-        open(txn, dbi) do cur
+Transaction(env; flags = LMDB.MDB_RDONLY) do txn
+    Database(txn) do dbi
+        Cursor(txn, dbi) do cur
             k = seek_range!(cur, prefix, String)
             while k !== nothing && startswith(k, prefix)
                 v = LMDB.value(cur, String)
@@ -113,9 +113,10 @@ Use the untyped form when you want to inspect raw byte sizes, copy
 slices, or feed a custom decoder. The data pointers are into LMDB's
 mmap and are valid only inside the callback (and only for the
 surrounding txn). The typed form is the iteration analogue of
-`tryget(..., T)` and works for any `T` for which `Base.read(io::IO,
-::Type{T})` (or `Base.read(io::LMDB.MDBValueIO, ::Type{T})`) is
-defined. See [Custom value decoding](@ref).
+`get(..., T, nothing)` and works for any `T` for which
+`Base.read(io::IO, ::Type{T})` (or
+`Base.read(io::LMDB.MDBValueIO, ::Type{T})`) is defined. See
+[Custom value decoding](@ref).
 
 ## Cursor mutation
 
@@ -134,7 +135,7 @@ key (1 in non-DUPSORT databases).
 
 ## Custom value decoding
 
-`tryget`, `get`, `key`, `value`, `item`, and typed `walk` all funnel
+`get`, `key`, `value`, `item`, and typed `walk` all funnel
 through `Base.read(io::IO, ::Type{T})` against an
 [`MDBValueIO`](@ref LMDB.MDBValueIO). The defaults cover Base's
 primitive numeric types (`Int8`/…/`Float64`, `Bool`, `Char`, `Ptr`),
@@ -153,7 +154,7 @@ function Base.read(io::IO, ::Type{PrefixedBlob})
 end
 
 # now usable everywhere a value-type parameter is accepted:
-LMDB.tryget(txn, dbi, key, PrefixedBlob)
+LMDB.get(txn, dbi, key, PrefixedBlob, nothing)
 walk(cur, String, PrefixedBlob) do k, blob
     handle(k, blob)
 end
@@ -174,8 +175,8 @@ expensive. Park the txn with [`reset`](@ref Base.reset(::LMDB.Transaction))
 and refresh both the txn and the cursor with `renew(txn, cur)`:
 
 ```julia
-txn = start(env; flags = LMDB.MDB_RDONLY)
-cur = open(txn, dbi)
+txn = Transaction(env; flags = LMDB.MDB_RDONLY)
+cur = Cursor(txn, dbi)
 while running
     ...                # use cur
     reset(txn)