extralite 2.7 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 377d86ec4649a083af81ee2958f14f2aa738eec05ae8730502738c090466f120
-  data.tar.gz: 47fad09e3cc2283065bc236ad43a2414bbe9b272173fc8a9e30c5a7ea74b5539
+  metadata.gz: 2cbb8c1507e23141a2b069306e31939b7cd5fea83e6941426972d7eeadc86ac0
+  data.tar.gz: e283cd0d2b18ed840020d73fb71d47696b64b8ff99c42a2a431928b6a25db189
 SHA512:
-  metadata.gz: 9638d918fb2c909db161757606493463dc5672535bba998db0f53f74b88bdd0f0c2bdd7ca0bfb31b068b6a9d1a3fdf8dda202446aa15ec32bae5b8ceaf9b0e3a
-  data.tar.gz: 1502f0be7681c2bd27b89351c4da138de9043453c2e21ecd1349f0cec9fa0f9d500e84eea6dc341d584a0819b1c11315a758c269138a19de0c342fb2a95aa3aa
+  metadata.gz: cbe1b66c813d0e35bd667a06e14bc68673655807d256771dac231ecb2f559660a05773267ef804e40f9d747482974d897b78c0df370340c55e7cfd290bdc4a41
+  data.tar.gz: 385b3ec651b1c2365392c7a1dddb0b7b63adddc6ade662f8ba7d72d6d49f025dff0b55490df6296181d361ac5792e888ed7db90c8b11b2129b5d6474fae2c8de

data/.yardopts

@@ -5,4 +5,4 @@
 --no-private
 --exclude sqlite3_constants.rb
 ./lib
-./ext/extralite
+./ext/extralite/*.c

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 2.7.1 2024-02-11
+
+- Fix API docs.
+
 # 2.7 2024-02-09
 
 - Improve progress handler API, add mode, period, tick options, global progress

data/README.md

@@ -891,7 +891,7 @@ above, calling `#interrupt` causes the query to raise a
 `Extralite::InterruptError` exception:
 
 ```ruby
-db.on_progress { db.interrupt }
+db.on_progress(period: 1) { db.interrupt }
 db.query('select 1')
 #=> Extralite::InterruptError!
 ```
@@ -900,7 +900,7 @@ You can also interrupt queries in progress by raising an exception. The query
 will be stopped, and the exception will propagate to the call site:
 
 ```ruby
-db.on_progress do
+db.on_progress(period: 1) do
   raise 'BOOM!'
 end
 
@@ -1003,7 +1003,7 @@ handler. This will work for switching between fibers using either Polyphony or
 any fiber scheduler gem, such as Async et al:
 
 ```ruby
-db.on_progress(100) { sleep(0) }
+db.on_progress { sleep(0) }
 ```
 
 For Polyphony-based apps, you can also call `snooze` to allow other fibers to
@@ -1011,7 +1011,7 @@ run while a query is progressing. If your Polyphony app is multi-threaded,
 you'll also need to call `Thread.pass` in order to allow other threads to run:
 
 ```ruby
-db.on_progress(100) do
+db.on_progress do
   snooze
   Thread.pass
 end
@@ -1022,7 +1022,7 @@ use the regular `#move_on_after` and `#cancel_after` methods to implement
 timeouts for queries:
 
 ```ruby
-db.on_progress(100) { snooze }
+db.on_progress { snooze }
 
 cancel_after(3) do
   db.query(long_running_query)

data/ext/extralite/database.c

@@ -721,15 +721,16 @@ static inline VALUE Database_prepare(int argc, VALUE *argv, VALUE self, VALUE mo
 }
 
 /* call-seq:
- *   db.prepare(sql) -> Extralite::Query
- *   db.prepare(sql, ...) -> Extralite::Query
- *   db.prepare(sql, ...) { ... } -> Extralite::Query
+ *   db.prepare(sql) -> query
+ *   db.prepare(sql, *params) -> query
+ *   db.prepare(sql, *params) { ... } -> query
  *
  * Creates a prepared query with the given SQL query in hash mode. If query
  * parameters are given, they are bound to the query. If a block is given, it is
  * used as a transform proc.
  * 
  * @param sql [String] SQL statement
+ * @param *params [Array<any>] parameters to bind
  * @return [Extralite::Query] prepared query
  */
 VALUE Database_prepare_hash(int argc, VALUE *argv, VALUE self) {
@@ -738,14 +739,15 @@ VALUE Database_prepare_hash(int argc, VALUE *argv, VALUE self) {
 
 /* call-seq:
  *   db.prepare_argv(sql) -> Extralite::Query
- *   db.prepare_argv(sql, ...) -> Extralite::Query
- *   db.prepare_argv(sql, ...) { ... } -> Extralite::Query
+ *   db.prepare_argv(sql, *params) -> Extralite::Query
+ *   db.prepare_argv(sql, *params) { ... } -> Extralite::Query
  *
  * Creates a prepared query with the given SQL query in argv mode. If query
  * parameters are given, they are bound to the query. If a block is given, it is
  * used as a transform proc.
  * 
  * @param sql [String] SQL statement
+ * @param *params [Array<any>] parameters to bind
  * @return [Extralite::Query] prepared query
  */
 VALUE Database_prepare_argv(int argc, VALUE *argv, VALUE self) {
@@ -754,14 +756,15 @@ VALUE Database_prepare_argv(int argc, VALUE *argv, VALUE self) {
 
 /* call-seq:
  *   db.prepare_ary(sql) -> Extralite::Query
- *   db.prepare_ary(sql, ...) -> Extralite::Query
- *   db.prepare_ary(sql, ...) { ... } -> Extralite::Query
+ *   db.prepare_ary(sql, *params) -> Extralite::Query
+ *   db.prepare_ary(sql, *params) { ... } -> Extralite::Query
  *
  * Creates a prepared query with the given SQL query in ary mode. If query
  * parameters are given, they are bound to the query. If a block is given, it is
  * used as a transform proc.
  * 
  * @param sql [String] SQL statement
+ * @param *params [Array<any>] parameters to bind
  * @return [Extralite::Query] prepared query
  */
 VALUE Database_prepare_ary(int argc, VALUE *argv, VALUE self) {
@@ -850,7 +853,11 @@ VALUE backup_cleanup(VALUE ptr) {
   return Qnil;
 }
 
-/* Creates a backup of the database to the given destination, which can be
+/* call-seq:
+ *   db.backup(dest, src_db_name = 'main', dst_db_name = 'main') { |remaining, total| ... } -> db
+ *
+ * 
+ * Creates a backup of the database to the given destination, which can be
  * either a filename or a database instance. In order to monitor the backup
  * progress you can pass a block that will be called periodically by the backup
  * method with two arguments: the remaining page count, and the total page
@@ -862,6 +869,8 @@ VALUE backup_cleanup(VALUE ptr) {
  *     end
  * 
  * @param dest [String, Extralite::Database] backup destination
+ * @param src_db_name [String] source database name (default: "main")
+ * @param dst_db_name [String] Destination database name (default: "main")
  * @return [Extralite::Database] source database
  */
 VALUE Database_backup(int argc, VALUE *argv, VALUE self) {
@@ -1030,7 +1039,10 @@ VALUE Database_trace(VALUE self) {
 }
 
 #ifdef EXTRALITE_ENABLE_CHANGESET
-/* Tracks changes to the database and returns a changeset. The changeset can
+/* call-seq:
+ *   db.track_changes(*tables) { ... } -> changeset
+ *
+ * Tracks changes to the database and returns a changeset. The changeset can
  * then be used to store the changes to a file, apply them to another database,
  * or undo the changes. The given table names specify which tables should be
  * tracked for changes. Passing a value of nil causes all tables to be tracked.
@@ -1041,7 +1053,7 @@ VALUE Database_trace(VALUE self) {
  * 
  *     File.open('my.changes', 'w+') { |f| f << changeset.to_blob }
  * 
- * @param table [String, Symbol] table to track
+ * @param *tables [Array<String, Symbol>] table(s) to track
  * @return [Extralite::Changeset] changeset
 */
 VALUE Database_track_changes(int argc, VALUE *argv, VALUE self) {
@@ -1185,7 +1197,7 @@ struct progress_handler parse_progress_handler_opts(VALUE opts) {
  * @option opts [Integer] :period period value (`1000` by default)
  * @option opts [Integer] :tick tick value (`10` by default)
  * @option opts [Symbol] :mode progress handler mode (`:normal` by default)
- * @returns [Extralite::Database] database
+ * @return [Extralite::Database] database
  */
 VALUE Database_on_progress(int argc, VALUE *argv, VALUE self) {
   Database_t *db = self_to_open_database(self);
@@ -1220,7 +1232,10 @@ VALUE Database_on_progress(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
-/* Installs or removes a global progress handler that will be executed
+/* call-seq:
+ *   Extralite.on_progress(**opts) { ... }
+ * 
+ * Installs or removes a global progress handler that will be executed
  * periodically while a query is running. This method can be used to support
  * switching between fibers and threads or implementing timeouts for running
  * queries.
@@ -1275,7 +1290,7 @@ VALUE Database_on_progress(int argc, VALUE *argv, VALUE self) {
  * @option opts [Integer] :period period value (`1000` by default)
  * @option opts [Integer] :tick tick value (`10` by default)
  * @option opts [Symbol] :mode progress handler mode (`:normal` by default)
- * @returns [Extralite::Database] database
+ * @return [Extralite::Database] database
  */
 VALUE Extralite_on_progress(int argc, VALUE *argv, VALUE self) {
   VALUE opts;
@@ -1361,7 +1376,7 @@ VALUE Database_gvl_release_threshold_get(VALUE self) {
  * A value of nil sets the threshold to the default value, which is
  * currently 1000.
  *
- * @param [Integer, nil] GVL release threshold
+ * @param threshold [Integer, nil] GVL release threshold
  * @return [Integer] GVL release threshold
  */
 VALUE Database_gvl_release_threshold_set(VALUE self, VALUE value) {
@@ -1398,63 +1413,61 @@ void Init_ExtraliteDatabase(void) {
   cDatabase = rb_define_class_under(mExtralite, "Database", rb_cObject);
   rb_define_alloc_func(cDatabase, Database_allocate);
 
-  #define DEF(s, f, a) rb_define_method(cDatabase, s, f, a)
-
-  DEF("backup",                 Database_backup, -1);
-  DEF("batch_execute",          Database_batch_execute, 2);
-  DEF("batch_query",            Database_batch_query, 2);
-  DEF("batch_query_ary",        Database_batch_query_ary, 2);
-  DEF("batch_query_argv",       Database_batch_query_argv, 2);
-  DEF("batch_query_hash",       Database_batch_query, 2);
-  DEF("busy_timeout=",          Database_busy_timeout_set, 1);
-  DEF("changes",                Database_changes, 0);
-  DEF("close",                  Database_close, 0);
-  DEF("closed?",                Database_closed_p, 0);
-  DEF("columns",                Database_columns, 1);
-  DEF("errcode",                Database_errcode, 0);
-  DEF("errmsg",                 Database_errmsg, 0);
+  rb_define_method(cDatabase, "backup",                 Database_backup, -1);
+  rb_define_method(cDatabase, "batch_execute",          Database_batch_execute, 2);
+  rb_define_method(cDatabase, "batch_query",            Database_batch_query, 2);
+  rb_define_method(cDatabase, "batch_query_ary",        Database_batch_query_ary, 2);
+  rb_define_method(cDatabase, "batch_query_argv",       Database_batch_query_argv, 2);
+  rb_define_method(cDatabase, "batch_query_hash",       Database_batch_query, 2);
+  rb_define_method(cDatabase, "busy_timeout=",          Database_busy_timeout_set, 1);
+  rb_define_method(cDatabase, "changes",                Database_changes, 0);
+  rb_define_method(cDatabase, "close",                  Database_close, 0);
+  rb_define_method(cDatabase, "closed?",                Database_closed_p, 0);
+  rb_define_method(cDatabase, "columns",                Database_columns, 1);
+  rb_define_method(cDatabase, "errcode",                Database_errcode, 0);
+  rb_define_method(cDatabase, "errmsg",                 Database_errmsg, 0);
 
   #ifdef HAVE_SQLITE3_ERROR_OFFSET
-  DEF("error_offset",           Database_error_offset, 0);
+  rb_define_method(cDatabase, "error_offset",           Database_error_offset, 0);
   #endif
 
-  DEF("execute",                Database_execute, -1);
-  DEF("filename",               Database_filename, -1);
-  DEF("gvl_release_threshold",  Database_gvl_release_threshold_get, 0);
-  DEF("gvl_release_threshold=", Database_gvl_release_threshold_set, 1);
-  DEF("initialize",             Database_initialize, -1);
-  DEF("inspect",                Database_inspect, 0);
-  DEF("interrupt",              Database_interrupt, 0);
-  DEF("last_insert_rowid",      Database_last_insert_rowid, 0);
-  DEF("limit",                  Database_limit, -1);
+  rb_define_method(cDatabase, "execute",                Database_execute, -1);
+  rb_define_method(cDatabase, "filename",               Database_filename, -1);
+  rb_define_method(cDatabase, "gvl_release_threshold",  Database_gvl_release_threshold_get, 0);
+  rb_define_method(cDatabase, "gvl_release_threshold=", Database_gvl_release_threshold_set, 1);
+  rb_define_method(cDatabase, "initialize",             Database_initialize, -1);
+  rb_define_method(cDatabase, "inspect",                Database_inspect, 0);
+  rb_define_method(cDatabase, "interrupt",              Database_interrupt, 0);
+  rb_define_method(cDatabase, "last_insert_rowid",      Database_last_insert_rowid, 0);
+  rb_define_method(cDatabase, "limit",                  Database_limit, -1);
 
   #ifdef HAVE_SQLITE3_LOAD_EXTENSION
-  DEF("load_extension",         Database_load_extension, 1);
+  rb_define_method(cDatabase, "load_extension",         Database_load_extension, 1);
   #endif
 
-  DEF("on_progress",            Database_on_progress, -1);
-  DEF("prepare",                Database_prepare_hash, -1);
-  DEF("prepare_argv",           Database_prepare_argv, -1);
-  DEF("prepare_ary",            Database_prepare_ary, -1);
-  DEF("prepare_hash",           Database_prepare_hash, -1);
-  DEF("query",                  Database_query, -1);
-  DEF("query_argv",             Database_query_argv, -1);
-  DEF("query_ary",              Database_query_ary, -1);
-  DEF("query_hash",             Database_query, -1);
-  DEF("query_single",           Database_query_single, -1);
-  DEF("query_single_ary",       Database_query_single_ary, -1);
-  DEF("query_single_argv",      Database_query_single_argv, -1);
-  DEF("query_single_hash",      Database_query_single, -1);
-  DEF("read_only?",             Database_read_only_p, 0);
-  DEF("status",                 Database_status, -1);
-  DEF("total_changes",          Database_total_changes, 0);
-  DEF("trace",                  Database_trace, 0);
+  rb_define_method(cDatabase, "on_progress",            Database_on_progress, -1);
+  rb_define_method(cDatabase, "prepare",                Database_prepare_hash, -1);
+  rb_define_method(cDatabase, "prepare_argv",           Database_prepare_argv, -1);
+  rb_define_method(cDatabase, "prepare_ary",            Database_prepare_ary, -1);
+  rb_define_method(cDatabase, "prepare_hash",           Database_prepare_hash, -1);
+  rb_define_method(cDatabase, "query",                  Database_query, -1);
+  rb_define_method(cDatabase, "query_argv",             Database_query_argv, -1);
+  rb_define_method(cDatabase, "query_ary",              Database_query_ary, -1);
+  rb_define_method(cDatabase, "query_hash",             Database_query, -1);
+  rb_define_method(cDatabase, "query_single",           Database_query_single, -1);
+  rb_define_method(cDatabase, "query_single_ary",       Database_query_single_ary, -1);
+  rb_define_method(cDatabase, "query_single_argv",      Database_query_single_argv, -1);
+  rb_define_method(cDatabase, "query_single_hash",      Database_query_single, -1);
+  rb_define_method(cDatabase, "read_only?",             Database_read_only_p, 0);
+  rb_define_method(cDatabase, "status",                 Database_status, -1);
+  rb_define_method(cDatabase, "total_changes",          Database_total_changes, 0);
+  rb_define_method(cDatabase, "trace",                  Database_trace, 0);
 
   #ifdef EXTRALITE_ENABLE_CHANGESET
-  DEF("track_changes",          Database_track_changes, -1);
+  rb_define_method(cDatabase, "track_changes",          Database_track_changes, -1);
   #endif
   
-  DEF("transaction_active?",    Database_transaction_active_p, 0);
+  rb_define_method(cDatabase, "transaction_active?",    Database_transaction_active_p, 0);
 
   cBlob           = rb_define_class_under(mExtralite, "Blob", rb_cString);
   cError          = rb_define_class_under(mExtralite, "Error", rb_eStandardError);

data/ext/extralite/iterator.c

@@ -50,7 +50,6 @@ static inline Iterator_t *self_to_iterator(VALUE obj) {
  *     ...
  *
  * @param query [Extralite::Query] associated query
- * @param mode [Symbol] iteration mode
  * @return [void]
  */
 VALUE Iterator_initialize(VALUE self, VALUE query) {

data/ext/extralite/query.c

@@ -593,9 +593,12 @@ VALUE Query_mode_get(VALUE self) {
   return query_mode_to_symbol(query->query_mode);
 }
 
-/* Sets the query mode. This can be one of `:hash`, `:argv`, `:ary`.
+/* call-seq:
+ *   query.mode = mode
+ * 
+ * Sets the query mode. This can be one of `:hash`, `:argv`, `:ary`.
  *
- * @param [Symbol] query mode
+ * @param mode [Symbol] query mode
  * @return [Symbol] query mode
  */
 VALUE Query_mode_set(VALUE self, VALUE mode) {
@@ -610,32 +613,30 @@ void Init_ExtraliteQuery(void) {
   cQuery = rb_define_class_under(mExtralite, "Query", rb_cObject);
   rb_define_alloc_func(cQuery, Query_allocate);
 
-  #define DEF(s, f, a) rb_define_method(cQuery, s, f, a)
-
-  DEF("bind",           Query_bind, -1);
-  DEF("close",          Query_close, 0);
-  DEF("closed?",        Query_closed_p, 0);
-  DEF("columns",        Query_columns, 0);
-  DEF("clone",          Query_clone, 0);
-  DEF("database",       Query_database, 0);
-  DEF("db",             Query_database, 0);
-  DEF("dup",            Query_clone, 0);
-  DEF("each",           Query_each, 0);
-  DEF("eof?",           Query_eof_p, 0);
-  DEF("execute",        Query_execute, -1);
-  DEF("<<",             Query_execute_chevrons, 1);
-  DEF("batch_execute",  Query_batch_execute, 1);
-  DEF("batch_query",    Query_batch_query, 1);
-  DEF("initialize",     Query_initialize, 3);
-  DEF("inspect",        Query_inspect, 0);
-  DEF("mode",           Query_mode_get, 0);
-  DEF("mode=",          Query_mode_set, 1);
-  DEF("next",           Query_next, -1);
-  DEF("reset",          Query_reset, 0);
-  DEF("sql",            Query_sql, 0);
-  DEF("status",         Query_status, -1);
-  DEF("to_a",           Query_to_a, 0);
-  DEF("transform",      Query_transform, 0);
+  rb_define_method(cQuery, "bind",           Query_bind, -1);
+  rb_define_method(cQuery, "close",          Query_close, 0);
+  rb_define_method(cQuery, "closed?",        Query_closed_p, 0);
+  rb_define_method(cQuery, "columns",        Query_columns, 0);
+  rb_define_method(cQuery, "clone",          Query_clone, 0);
+  rb_define_method(cQuery, "database",       Query_database, 0);
+  rb_define_method(cQuery, "db",             Query_database, 0);
+  rb_define_method(cQuery, "dup",            Query_clone, 0);
+  rb_define_method(cQuery, "each",           Query_each, 0);
+  rb_define_method(cQuery, "eof?",           Query_eof_p, 0);
+  rb_define_method(cQuery, "execute",        Query_execute, -1);
+  rb_define_method(cQuery, "<<",             Query_execute_chevrons, 1);
+  rb_define_method(cQuery, "batch_execute",  Query_batch_execute, 1);
+  rb_define_method(cQuery, "batch_query",    Query_batch_query, 1);
+  rb_define_method(cQuery, "initialize",     Query_initialize, 3);
+  rb_define_method(cQuery, "inspect",        Query_inspect, 0);
+  rb_define_method(cQuery, "mode",           Query_mode_get, 0);
+  rb_define_method(cQuery, "mode=",          Query_mode_set, 1);
+  rb_define_method(cQuery, "next",           Query_next, -1);
+  rb_define_method(cQuery, "reset",          Query_reset, 0);
+  rb_define_method(cQuery, "sql",            Query_sql, 0);
+  rb_define_method(cQuery, "status",         Query_status, -1);
+  rb_define_method(cQuery, "to_a",           Query_to_a, 0);
+  rb_define_method(cQuery, "transform",      Query_transform, 0);
 
   ID_inspect  = rb_intern("inspect");
   ID_slice    = rb_intern("slice");

data/lib/extralite/version.rb

@@ -1,4 +1,4 @@
 module Extralite
   # Extralite version
-  VERSION = '2.7'
+  VERSION = '2.7.1'
 end

data/lib/extralite.rb

@@ -29,7 +29,6 @@ module Extralite
   class ParameterError < Error
   end
 
-  # This class encapsulates an SQLite database connection.
   class Database
     # @!visibility private
     TABLES_SQL = (<<~SQL).freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: extralite
 version: !ruby/object:Gem::Version
-  version: '2.7'
+  version: 2.7.1
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-09 00:00:00.000000000 Z
+date: 2024-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler