ENH: Implement retrievals and update docstrings

docs/src/api.md

@@ -5,16 +5,24 @@ interface. You also find the documentation of the internal API which
 is meant for expert use only. Only use those if you know what you're
 doing.
 
+```@index
+Order = [:module, :function, :macro, :type, :constant]
+```
+
 ## Public API
 
 ```@autodocs
-Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity]
+Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, 
+	CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity, 
+	CaosDB.Transaction]
 Private=false
 ```
 
 ## Expert-use only API functions
 
 ```@autodocs
-Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity]
+Modules=[CaosDB, CaosDB.Exceptions, CaosDB.Info, CaosDB.Utility, 
+	CaosDB.Connection, CaosDB.Authentication, CaosDB.Entity, 
+	CaosDB.Transaction]
 Public=false
 ```

src/Transaction.jl

@@ -23,7 +23,7 @@
 
 module Transaction
 
-export create_transaction
+export create_transaction, add_retrieve_by_id, add_query
 
 using CaosDB
 
@@ -86,4 +86,84 @@ function create_transaction(connection::Ref{CaosDB.Connection._Connection})
     return transaction
 end
 
+"""
+    function add_retrieve_by_id(transaction::Ref{_Transaction}, id::AbstractString)
+
+Add a sub-request to retrieve a single entity by its `id` to the given
+`transaction`.
+
+!!! info
+
+    This does not execute the transaction.
+"""
+function add_retrieve_by_id(transaction::Ref{_Transaction}, id::AbstractString)
+
+    err_code = ccall(
+        (:caosdb_transaction_transaction_retrieve_by_id, CaosDB.library_name),
+        Cint,
+        (Ref{_Transaction}, Cstring),
+        transaction,
+        id,
+    )
+
+    CaosDB.Exceptions.evaluate_return_code(err_code)
+end
+
+"""
+    function add_retrieve_by_id(
+        transaction::Ref{_Transaction},
+        ids::Vector{T},
+    ) where {T<:AbstractString}
+
+Add a sub-request to retrieve several entities by their `ids` to the
+given `transaction`.
+
+!!! info
+
+    This does not execute the transaction.
+"""
+function add_retrieve_by_id(
+    transaction::Ref{_Transaction},
+    ids::Vector{T},
+) where {T<:AbstractString}
+
+    err_code = ccall(
+        (:caosdb_transaction_transaction_retrieve_by_ids, CaosDB.library_name),
+        Cint,
+        (Ref{_Transaction}, Ptr{Ptr{Cchar}}),
+        transaction,
+        ids,
+    )
+
+    CaosDB.Exceptions.evaluate_return_code(err_code)
+end
+
+
+"""
+    function add_query(transaction::Ref{_Transaction}, query::AbstractString)
+
+Add a query sub-request to the given `transaction`.
+
+!!! warning
+
+    Only COUNT queris and FIND queries (and no SELECT queries) are
+    currently supported.
+
+!!! info
+
+    This dows not execute the transaction
+"""
+function add_query(transaction::Ref{_Transaction}, query::AbstractString)
+
+    err_code = ccall(
+        (:caosdb_transaction_transaction_query, CaosDB.library_name),
+        Cint,
+        (Ref{_Transaction}, Cstring),
+        transaction,
+        query,
+    )
+
+    CaosDB.Exceptions.evaluate_return_code(err_code)
+end
+
 end # Transaction

test/runtests.jl

@@ -71,15 +71,16 @@ using CaosDB
         @test CaosDB.Transaction.create_transaction() != nothing
         @test CaosDB.Transaction.create_transaction("default") != nothing
         conn = CaosDB.Connection.get_connection()
-        @test CaosDB.Transaction.create_transaction != nothing
+        @test CaosDB.Transaction.create_transaction(conn) != nothing
 
         # Retrieval works by a single id, by a list of ids, or by querying
         trans1 = CaosDB.Transaction.create_transaction()
         @test CaosDB.Transaction.add_retrieve_by_id(trans1, "some_id") == nothing
         trans2 = CaosDB.Transaction.create_transaction()
-        @test CaosDB.Transaction.add_retrieve_by_id(["id1", "id2", "id3"]) == nothing
+        @test CaosDB.Transaction.add_retrieve_by_id(trans2, ["id1", "id2", "id3"]) ==
+              nothing
         trans3 = CaosDB.Transaction.create_transaction()
-        @test CaosDB.Transaction.add_query("FIND ENTITY WITH id=123") == nothing
+        @test CaosDB.Transaction.add_query(trans3, "FIND ENTITY WITH id=123") == nothing
 
     end