Commite7228586Recorded25 Feb 2026Repositorysigil-sqlite
Add docstrings to (sigil sqlite) native procedures
Message
All 16 native SQLite functions now have documentation accessible via the API docs system.
Changed
src/sigil/sqlite.sgl | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 148 insertions(+), 1 deletion(-)Diff
src/sigil/sqlite.sglmodified
@@ -61,23 +61,170 @@
61
62
(begin 63
−64
;; ========== Native Procedure Specs ==========+64
;; ========== Native Procedure Documentation & Specs ========== 65
+66
;;; Check if a value is a SQLite database handle.+67
;;;+68
;;; ```scheme+69
;;; (sqlite-db? db) ; => #t+70
;;; (sqlite-db? "not a db") ; => #f+71
;;; ```+72
(%set-docstring! sqlite-db?) 73
(%set-spec! sqlite-db? '(any? -> boolean?))+74
+75
;;; Check if a value is a SQLite prepared statement.+76
;;;+77
;;; ```scheme+78
;;; (sqlite-stmt? stmt) ; => #t+79
;;; (sqlite-stmt? "not stmt") ; => #f+80
;;; ```+81
(%set-docstring! sqlite-stmt?) 82
(%set-spec! sqlite-stmt? '(any? -> boolean?))+83
+84
;;; Open a SQLite database file.+85
;;;+86
;;; Returns a database handle on success, or `#f` on failure.+87
;;; Creates the file if it does not exist. Use `":memory:"` for+88
;;; an in-memory database.+89
;;;+90
;;; ```scheme+91
;;; (sqlite-open "app.db") ; => #<sqlite-db>+92
;;; (sqlite-open ":memory:") ; => #<sqlite-db>+93
;;; ```+94
(%set-docstring! sqlite-open) 95
(%set-spec! sqlite-open '(string? -> (maybe sqlite-db?)))+96
+97
;;; Close a SQLite database handle.+98
;;;+99
;;; All prepared statements should be finalized before closing.+100
;;;+101
;;; ```scheme+102
;;; (sqlite-close db)+103
;;; ```+104
(%set-docstring! sqlite-close) 105
(%set-spec! sqlite-close '(sqlite-db? -> void?))+106
+107
;;; Execute a SQL string directly.+108
;;;+109
;;; Suitable for DDL statements and simple queries that don't need+110
;;; parameter binding. Returns `#t` on success, `#f` on error.+111
;;;+112
;;; ```scheme+113
;;; (sqlite-exec db "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")+114
;;; (sqlite-exec db "PRAGMA journal_mode=WAL")+115
;;; ```+116
(%set-docstring! sqlite-exec) 117
(%set-spec! sqlite-exec '(sqlite-db? string? -> boolean?))+118
+119
;;; Prepare a SQL statement for execution.+120
;;;+121
;;; Returns a prepared statement handle, or `#f` on error. Use+122
;;; `sqlite-bind` to set parameters and `sqlite-step` to execute.+123
;;;+124
;;; ```scheme+125
;;; (define stmt (sqlite-prepare db "SELECT * FROM users WHERE id = ?"))+126
;;; ```+127
(%set-docstring! sqlite-prepare) 128
(%set-spec! sqlite-prepare '(sqlite-db? string? -> (maybe sqlite-stmt?)))+129
+130
;;; Bind a value to a parameter in a prepared statement.+131
;;;+132
;;; Parameter indices are 1-based. Accepts strings, numbers,+133
;;; bytevectors, booleans, and `'null`. Returns `#t` on success.+134
;;;+135
;;; ```scheme+136
;;; (sqlite-bind stmt 1 "Alice")+137
;;; (sqlite-bind stmt 2 42)+138
;;; ```+139
(%set-docstring! sqlite-bind) 140
(%set-spec! sqlite-bind '(sqlite-stmt? integer? any? -> boolean?))+141
+142
;;; Step through a prepared statement.+143
;;;+144
;;; Returns `'row` if a result row is available (use `sqlite-column`+145
;;; to read values), `'done` when finished, or `#f` on error.+146
;;;+147
;;; ```scheme+148
;;; (sqlite-step stmt) ; => 'row, 'done, or #f+149
;;; ```+150
(%set-docstring! sqlite-step) 151
(%set-spec! sqlite-step '(sqlite-stmt? -> any?))+152
+153
;;; Reset a prepared statement to its initial state.+154
;;;+155
;;; Allows re-execution with new parameter bindings.+156
;;;+157
;;; ```scheme+158
;;; (sqlite-reset stmt)+159
;;; ```+160
(%set-docstring! sqlite-reset) 161
(%set-spec! sqlite-reset '(sqlite-stmt? -> void?))+162
+163
;;; Finalize a prepared statement and release its resources.+164
;;;+165
;;; Must be called when the statement is no longer needed.+166
;;;+167
;;; ```scheme+168
;;; (sqlite-finalize stmt)+169
;;; ```+170
(%set-docstring! sqlite-finalize) 171
(%set-spec! sqlite-finalize '(sqlite-stmt? -> void?))+172
+173
;;; Get the number of columns in a result set.+174
;;;+175
;;; ```scheme+176
;;; (sqlite-column-count stmt) ; => 3+177
;;; ```+178
(%set-docstring! sqlite-column-count) 179
(%set-spec! sqlite-column-count '(sqlite-stmt? -> integer?))+180
+181
;;; Get the name of a result column by index.+182
;;;+183
;;; Column indices are 0-based.+184
;;;+185
;;; ```scheme+186
;;; (sqlite-column-name stmt 0) ; => "id"+187
;;; (sqlite-column-name stmt 1) ; => "name"+188
;;; ```+189
(%set-docstring! sqlite-column-name) 190
(%set-spec! sqlite-column-name '(sqlite-stmt? integer? -> string?))+191
+192
;;; Get the value of a result column by index.+193
;;;+194
;;; Column indices are 0-based. Returns the appropriate Scheme type+195
;;; based on the SQLite column type (integer, real, text, blob, or null).+196
;;;+197
;;; ```scheme+198
;;; (sqlite-column stmt 0) ; => 1+199
;;; (sqlite-column stmt 1) ; => "Alice"+200
;;; ```+201
(%set-docstring! sqlite-column) 202
(%set-spec! sqlite-column '(sqlite-stmt? integer? -> any?))+203
+204
;;; Get the rowid of the last inserted row.+205
;;;+206
;;; ```scheme+207
;;; (sqlite-run db "INSERT INTO users (name) VALUES (?)" "Bob")+208
;;; (sqlite-last-insert-rowid db) ; => 5+209
;;; ```+210
(%set-docstring! sqlite-last-insert-rowid) 211
(%set-spec! sqlite-last-insert-rowid '(sqlite-db? -> integer?))+212
+213
;;; Get the number of rows changed by the last statement.+214
;;;+215
;;; ```scheme+216
;;; (sqlite-run db "UPDATE users SET name = ? WHERE id = ?" "Robert" 1)+217
;;; (sqlite-changes db) ; => 1+218
;;; ```+219
(%set-docstring! sqlite-changes) 220
(%set-spec! sqlite-changes '(sqlite-db? -> integer?))+221
+222
;;; Get the last error message from the database.+223
;;;+224
;;; ```scheme+225
;;; (sqlite-errmsg db) ; => "not an error"+226
;;; ```+227
(%set-docstring! sqlite-errmsg) 228
(%set-spec! sqlite-errmsg '(sqlite-db? -> string?)) 229
230
;; ========== High-Level API ==========