example in C; always write `errored` in C API;

IN_PROG.md

@@ -213,4 +213,4 @@ We manually wrote the C++/Rust bindings for RocksDB with [cxx](https://cxx.rs/).
 ## Licensing
 
 The contents of this project are licensed under AGPL-3.0 or later, except 
-files under `cozorocks/` and `cozo-lib-c/`, which are licensed under MIT, or Apache-2.0, or BSD-3-Clause.
+files under `cozorocks/`, which are licensed under MIT, or Apache-2.0, or BSD-3-Clause.

cozo-lib-c/.gitignore

@@ -0,0 +1 @@
+example

cozo-lib-c/Cargo.toml

@@ -2,6 +2,11 @@
 name = "cozo_c"
 version = "0.1.1"
 edition = "2021"
+license = "AGPL-3.0-or-later"
+homepage = "https://github.com/cozodb/cozo"
+repository = "https://github.com/cozodb/cozo"
+documentation = "https://cozodb.github.io/current/manual"
+description = "C bindings for CozoDB"
 
 [lib]
 crate-type = ["cdylib", "staticlib"]

cozo-lib-c/LICENSE.txt

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2022 Ziyang Hu
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

cozo-lib-c/README.md

@@ -0,0 +1,3 @@
+```bash
+gcc -L../target/release/ -lcozo_c example.c -o example && ./example
+```

cozo-lib-c/cozo_c.h

@@ -48,7 +48,7 @@ bool cozo_close_db(int32_t id);
  * `errored`:    will point to `false` if the query is successful,
  *               `true` if an error occurred.
  *
- * Returns a UTF-8-encoded C-string that must be freed with `cozo_free_str`.
+ * Returns a UTF-8-encoded C-string that **must** be freed with `cozo_free_str`.
  * If `*errored` is false, then the string contains the JSON return value of the query.
  * If `*errored` is true, then the string contains the error message.
  */

cozo-lib-c/example.c

@@ -0,0 +1,36 @@
+#include <stdio.h>
+#include <stdint.h>
+#include <stdbool.h>
+#include "cozo_c.h"
+
+void run_query(int32_t db_id, const char* query) {
+    const char *empty_params = "{}";
+    bool errored;
+    char *res;
+    res = cozo_run_query(db_id, query, empty_params, &errored);
+
+    if (errored) {
+        printf("encountered an error:\n%s\n\n", res);
+    } else {
+        printf("query is successful with result:\n%s\n\n", res);
+    }
+    cozo_free_str(res);
+}
+
+int main() {
+    int32_t db_id;
+    char* err = cozo_open_db("_test_db", &db_id);
+
+    if (err) {
+        printf("%s", err);
+        cozo_free_str(err);
+        return -1;
+    }
+
+    run_query(db_id, "?[a, b, c] <- [[1, 2, 3]]");
+    run_query(db_id, "?[a] <- [[1, 2, 3]]");
+
+    cozo_close_db(db_id);
+
+    return 0;
+}

cozo-lib-c/src/lib.rs

@@ -76,7 +76,7 @@ pub unsafe extern "C" fn cozo_close_db(id: i32) -> bool {
 /// `errored`:    will point to `false` if the query is successful,
 ///               `true` if an error occurred.
 ///
-/// Returns a UTF-8-encoded C-string that must be freed with `cozo_free_str`.
+/// Returns a UTF-8-encoded C-string that **must** be freed with `cozo_free_str`.
 /// If `*errored` is false, then the string contains the JSON return value of the query.
 /// If `*errored` is true, then the string contains the error message.
 #[no_mangle]
@@ -136,6 +136,7 @@ pub unsafe extern "C" fn cozo_run_query(
     let result = db.run_script(script, &params_arg);
     match result {
         Ok(json) => {
+            *errored = false;
             let json_str = json.to_string();
             CString::new(json_str).unwrap().into_raw()
         }