orm: add function call based builder API for dynamic queries (fix #24178) (#24196)

Author: kbkpbot

cmd/tools/vtest-self.v

@@ -156,6 +156,7 @@ const skip_with_fsanitize_memory = [
 	'vlib/orm/orm_order_by_custom_field_test.v',
 	'vlib/orm/orm_serial_attribute_test.v',
 	'vlib/orm/orm_option_subselect_test.v',
+	'vlib/orm/orm_func_test.v',
 	'vlib/db/sqlite/sqlite_test.v',
 	'vlib/db/sqlite/sqlite_orm_test.v',
 	'vlib/db/sqlite/sqlite_comptime_field_test.v',
@@ -246,6 +247,7 @@ const skip_on_ubuntu_musl = [
 	'vlib/orm/orm_order_by_custom_field_test.v',
 	'vlib/orm/orm_serial_attribute_test.v',
 	'vlib/orm/orm_option_subselect_test.v',
+	'vlib/orm/orm_func_test.v',
 	'vlib/v/tests/orm_enum_test.v',
 	'vlib/v/tests/orm_sub_struct_test.v',
 	'vlib/v/tests/orm_sub_array_struct_test.v',

vlib/orm/README.md

@@ -38,6 +38,8 @@ struct Foo {
 - `[fkey: 'parent_id']` sets foreign key for an field which holds an array
 
 ## Usage
+> [!NOTE]
+> For using the Function Call API for `orm`, please check [`Function Call API`](#function-call-api).
 
 Here are a couple example structs showing most of the features outlined above.
 
@@ -246,3 +248,106 @@ fn main() {
 	}!
 }
 ```
+
+## Function Call API
+You can utilize the `Function Call API` to work with `ORM`. It provides the
+capability to dynamically construct SQL statements. The Function Call API
+supports common operations such as `Create Table`/`Drop Table`/`Insert`/`Delete`/`Update`/`Select`,
+and offers convenient yet powerful features for constructing `WHERE` clauses,
+`SET` clauses, `SELECT` clauses, and more.
+
+A complete example is available [here](https://github.com/vlang/v/blob/master/vlib/orm/orm_func_test.v).
+
+Below, we illustrate its usage through several examples.
+
+​​1. Define your struct​​ with the same method definitions as before:
+
+```v ignore
+@[table: 'sys_users']
+struct User {
+	id      int      @[primary;serial]
+	name    string
+	age     int
+	role    string
+	status  int
+	salary  int
+	title   string
+	score   int
+	created_at ?time.Time @[sql_type: 'TIMESTAMP']
+}
+```
+
+​​2. Create a database connection​​:
+
+```v ignore
+    mut db := sqlite.connect(':memory:')!
+    defer { db.close() or {} }
+```
+
+3. Create a `QueryBuilder`​​ (which also completes struct mapping):
+
+```v ignore
+	mut qb := orm.new_query[User](db)
+```
+
+4. Create a database table​​:
+
+```v ignore
+	qb.create()!
+```
+
+5. Insert multiple records​​ into the table:
+
+```v ignore
+	qb.insert_many(users)!
+```
+
+6. Delete records​​ (note: `delete()` must follow `where()`):
+
+```v ignore
+	qb.where('name = ?','John')!.delete()!
+```
+
+7. Query records​​ (you can specify fields of interest via `select`):
+
+```v ignore
+// Returns []User with only 'name' populated; other fields are zero values.
+	only_names := qb.select('name')!.query()!
+```
+
+8. Update records​​ (note: `update()` must be placed last):
+
+```v ignore
+	qb.set('age = ?, title = ?', 71, 'boss')!.where('name = ?','John')!.update()!
+```
+
+9. Drop the table​​:
+
+```v ignore
+	qb.drop()!
+```
+
+10. Chainable method calls​​:
+Most Function Call API support chainable calls, allowing easy method chaining:
+
+```v ignore
+	final_users :=
+	qb
+		.drop()!
+		.create()!
+		.insert_many(users)!
+		.set('name = ?', 'haha')!.where('name = ?', 'Tom')!.update()!
+		.where('age >= ?', 30)!.delete()!
+		.query()!
+```
+
+11. Writing complex nested `WHERE` clauses​​:
+The API includes a built-in parser to handle intricate `WHERE` clause conditions. For example:
+
+```v ignore
+	where('created_at IS NULL && ((salary > ? && age < ?) || (role LIKE ?))', 2000, 30, '%employee%')!
+```
+
+Note the use of placeholders `?`.
+The conditional expressions support logical operators including `AND`, `OR`, `||`, and `&&`.
+

vlib/orm/orm.v

@@ -131,7 +131,7 @@ fn (kind OrderType) to_str() string {
 // parentheses defines which fields will be inside ()
 // auto_fields are indexes of fields where db should generate a value when absent in an insert
 pub struct QueryData {
-pub:
+pub mut:
 	fields      []string
 	data        []Primitive
 	types       []int
@@ -149,7 +149,7 @@ pub:
 }
 
 pub struct TableField {
-pub:
+pub mut:
 	name        string
 	typ         int
 	nullable    bool
@@ -170,7 +170,7 @@ pub:
 // fields - Fields to select
 // types - Types to select
 pub struct SelectConfig {
-pub:
+pub mut:
 	table      string
 	is_count   bool
 	has_where  bool