lib/sqlite3: improve doc and customization of the iterator closing statements

[nit.git] / lib / sqlite3 / sqlite3.nit

diff --git a/lib/sqlite3/sqlite3.nit b/lib/sqlite3/sqlite3.nit
index e5695af..62fe8e5 100644 (file)
--- a/lib/sqlite3/sqlite3.nit
+++ b/lib/sqlite3/sqlite3.nit
@@ -112,13 +112,27 @@ class Sqlite3DB
        fun last_insert_rowid: Int do return native_connection.last_insert_rowid
 end
 
-# A prepared Sqlite3 statement, created from `Sqlite3DB::prepare` or `Sqlite3DB::select`
+# Prepared Sqlite3 statement
+#
+# Instances of this class are created from `Sqlite3DB::prepare` and
+# its shortcuts: `create_table`, `insert`, `replace` and `select`.
+# The results should be explored with an `iterator`,
+# and each call to `iterator` resets the request.
+# If `close_with_iterator` the iterator calls `close`
+# on this request upon finishing.
 class Statement
        private var native_statement: NativeStatement
 
        # Is this statement usable?
        var is_open = true
 
+       # Should any `iterator` close this statement on `Iterator::finish`?
+       #
+       # If `true`, the default, any `StatementIterator` created by calls to
+       # `iterator` invokes `close` on this request when finished iterating.
+       # Otherwise, `close` must be called manually.
+       var close_with_iterator = true is writable
+
        # Close and finalize this statement
        fun close
        do
@@ -281,7 +295,7 @@ class StatementIterator
                end
        end
 
-       redef fun finish do statement.close
+       redef fun finish do if statement.close_with_iterator then statement.close
 end
 
 # A data type supported by Sqlite3