add a boolean to the monad to be more flexible with error management

To optimize Sqlite3 queries, prepared statements are typically
kept instead of re-prepared so that they may be executed multiple
times. This allows for prepared statements to not be finalized on
destruction, allowing for reuse even when an error has occured.

1 files changed, 18 insertions, 4 deletions

diff --git a/src/letsqlite.mli b/src/letsqlite.mli
index c0ecc45..1449f31 100644
--- a/src/letsqlite.mli
+++ b/src/letsqlite.mli
@@ -5,9 +5,11 @@
 Types used for monad composition.
 *)
 
+type stmt_wrap = bool * Sqlite3.stmt
+
 type 'a stmt_m =
 | Failed of Sqlite3.Rc.t
-| Norm of ('a * Sqlite3.stmt)
+| Norm of ('a * stmt_wrap)
 
 (** The ['a] value in the [stmt_m] is referred to as the bundled value.
     A function may "fail with [e]", in which it returns [Failed e],
@@ -17,11 +19,15 @@ type 'a stmt_m =
     The bundled {!Sqlite.stmt} value is refered to as [S], and the
     value bundled is refered to as [V].
 
+    The boolean value is the {i preserve on failure} flag. When true,
+    monadic functions will not call {!Sqlite3.finalize} on the contained
+    statement. {b This will cause a memory leak if not handled correctly.}
+
     {i Never directly use [Failed].} You run the likelihood of leaking
-    memory.
+    memory or causing a crash.
 *)
 
-type ('a,'b) monad_fun = ('a * Sqlite3.stmt) -> 'b stmt_m
+type ('a,'b) monad_fun = ('a * stmt_wrap) -> 'b stmt_m
 
 type rowdata = (string, Sqlite3.Data.t) Hashtbl.t
 
@@ -49,6 +55,9 @@ val (>-$) : 'a stmt_m -> ('a,'b) monad_fun -> 'a stmt_m
     passes the original [V] through.
 *)
 
+val gs : stmt_wrap -> Sqlite3.stmt
+(** [gs s] returns the statment in an instance of [stmt_wrap]. *)
+
 (** {1 Non-Execution Functions}
 
 These functions do not execute any SQL queries. They exist to make dealing
@@ -67,7 +76,7 @@ val fail : Sqlite3.Rc.t -> ('a,'b) monad_fun
     of {!Sqlite3.finalize} otherwise.
 *)
 
-val stmtfail : Sqlite3.Rc.t -> Sqlite3.stmt -> unit stmt_m
+val stmtfail : Sqlite3.Rc.t -> stmt_wrap -> unit stmt_m
 (** [stmtfail e s] is equivalent to [fail] except it assembles a statement
     with unit type. *)
 
@@ -93,6 +102,11 @@ val prepare : Sqlite3.db -> string -> 'a -> 'a stmt_m
     the statement in [s].
 *)
 
+val prepare_keep : bool -> Sqlite3.db -> string -> 'a -> 'a stmt_m
+(** [prepare_keep b] is like [prepare], but [b] is the preserve-on-failure
+    file.
+*)
+
 val reprepare : Sqlite3.db -> string -> ('a,'a) monad_fun
 (** [reprepare db stmt] finalizes [S] and prepares [stmt] in
     its place. *)