qcl 0.1.5

A Query Check Language written in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# C FFI

QCL provides a C-compatible shared library.

## Build

```bash
make ffi
# or directly:
cargo build --lib --features ffi --release
```

Output:
- Linux: `target/release/libqcl.so`
- macOS: `target/release/libqcl.dylib`

## API

### `qcl_eval_json`

```c
char* qcl_eval_json(const char* expression, const char* json_ctx);
```

Parse and evaluate a QCL expression against a JSON context. Returns a heap-allocated result string, or `NULL` on error. The caller must free the returned string with `qcl_free`.

### `qcl_check_json`

```c
int qcl_check_json(const char* expression, const char* json_ctx);
```

Evaluate and return a truthiness code:
- `1` — truthy (`true`, non-nil value)
- `0` — falsy (`false`, `nil`)
- `-1` — error (call `qcl_last_error` for details)

### `qcl_last_error`

```c
char* qcl_last_error(void);
```

Retrieve the last error message (thread-local). Returns `NULL` if no error. The returned string must be freed with `qcl_free`.

### `qcl_free`

```c
void qcl_free(char* ptr);
```

Free a string previously returned by any QCL function. Safe to call with `NULL`.

## Example

```c
#include <stdio.h>

// Declarations (or use a generated header)
extern char* qcl_eval_json(const char* expression, const char* json_ctx);
extern int   qcl_check_json(const char* expression, const char* json_ctx);
extern char* qcl_last_error(void);
extern void  qcl_free(char* ptr);

int main(void) {
    // Evaluate
    char* result = qcl_eval_json("@x + 1", "{\"x\": 2}");
    if (result) {
        printf("result: %s\n", result); // "3"
        qcl_free(result);
    } else {
        char* err = qcl_last_error();
        if (err) {
            fprintf(stderr, "error: %s\n", err);
            qcl_free(err);
        } else {
            fprintf(stderr, "error: unknown error\n");
        }
    }

    // Check
    int ok = qcl_check_json("@user.role == \"admin\"",
                            "{\"user\": {\"role\": \"admin\"}}");
    printf("check: %d\n", ok); // 1

    return 0;
}
```

Compile and link:

```bash
cc -o example example.c -L target/release -lqcl -Wl,-rpath,target/release
./example
```