libnickel.jl (19847B)
1 # Julia bindings for the Nickel C API (nickel-lang 2.0.0 / capi feature) 2 # 3 # Generated from deps/nickel_lang.h by Clang.jl (deps/generate_bindings.jl), 4 # with manual docstrings and minor type corrections applied. 5 # 6 # All functions reference `libnickel_lang` as the library symbol. 7 # The actual library path must be assigned to `libnickel_lang` before use. 8 9 module LibNickel 10 11 # Import library path from parent module (set in ffi.jl before include) 12 import ..libnickel_lang 13 14 # ── Enums ──────────────────────────────────────────────────────────────────── 15 16 """ 17 nickel_result 18 19 Return value for fallible C API functions. 20 21 - `NICKEL_RESULT_OK = 0` — success 22 - `NICKEL_RESULT_ERR = 1` — failure 23 """ 24 @enum nickel_result::UInt32 begin 25 NICKEL_RESULT_OK = 0 26 NICKEL_RESULT_ERR = 1 27 end 28 29 """ 30 nickel_error_format 31 32 Format selector for error diagnostics. 33 34 - `NICKEL_ERROR_FORMAT_TEXT = 0` — plain text 35 - `NICKEL_ERROR_FORMAT_ANSI_TEXT = 1` — text with ANSI color codes 36 - `NICKEL_ERROR_FORMAT_JSON = 2` — JSON 37 - `NICKEL_ERROR_FORMAT_YAML = 3` — YAML 38 - `NICKEL_ERROR_FORMAT_TOML = 4` — TOML 39 """ 40 @enum nickel_error_format::UInt32 begin 41 NICKEL_ERROR_FORMAT_TEXT = 0 42 NICKEL_ERROR_FORMAT_ANSI_TEXT = 1 43 NICKEL_ERROR_FORMAT_JSON = 2 44 NICKEL_ERROR_FORMAT_YAML = 3 45 NICKEL_ERROR_FORMAT_TOML = 4 46 end 47 48 # ── Opaque types ───────────────────────────────────────────────────────────── 49 # Opaque structs from C; only used via `Ptr{T}`. 50 51 mutable struct nickel_array end 52 mutable struct nickel_context end 53 mutable struct nickel_error end 54 mutable struct nickel_expr end 55 mutable struct nickel_number end 56 mutable struct nickel_record end 57 mutable struct nickel_string end 58 59 # ── Callback types ─────────────────────────────────────────────────────────── 60 # typedef uintptr_t (*nickel_write_callback)(void *context, const uint8_t *buf, uintptr_t len); 61 # typedef void (*nickel_flush_callback)(const void *context); 62 63 const nickel_write_callback = Ptr{Cvoid} 64 const nickel_flush_callback = Ptr{Cvoid} 65 66 # ── Context lifecycle ──────────────────────────────────────────────────────── 67 68 """ 69 nickel_context_alloc() -> Ptr{nickel_context} 70 71 Allocate a new context for evaluating Nickel expressions. 72 Must be freed with [`nickel_context_free`](@ref). 73 """ 74 function nickel_context_alloc() 75 @ccall libnickel_lang.nickel_context_alloc()::Ptr{nickel_context} 76 end 77 78 """ 79 nickel_context_free(ctx) 80 81 Free a context allocated with [`nickel_context_alloc`](@ref). 82 """ 83 function nickel_context_free(ctx) 84 @ccall libnickel_lang.nickel_context_free(ctx::Ptr{nickel_context})::Cvoid 85 end 86 87 # ── Context configuration ─────────────────────────────────────────────────── 88 89 """ 90 nickel_context_set_trace_callback(ctx, write, flush, user_data) 91 92 Provide a callback for `std.trace` output during evaluation. 93 """ 94 function nickel_context_set_trace_callback(ctx, write, flush, user_data) 95 @ccall libnickel_lang.nickel_context_set_trace_callback(ctx::Ptr{nickel_context}, write::nickel_write_callback, flush::nickel_flush_callback, user_data::Ptr{Cvoid})::Cvoid 96 end 97 98 """ 99 nickel_context_set_source_name(ctx, name) 100 101 Set a name for the main input program (used in error messages). 102 `name` must be a null-terminated UTF-8 C string; it is only borrowed temporarily. 103 """ 104 function nickel_context_set_source_name(ctx, name) 105 @ccall libnickel_lang.nickel_context_set_source_name(ctx::Ptr{nickel_context}, name::Ptr{Cchar})::Cvoid 106 end 107 108 # ── Evaluation ─────────────────────────────────────────────────────────────── 109 110 """ 111 nickel_context_eval_deep(ctx, src, out_expr, out_error) -> nickel_result 112 113 Evaluate Nickel source deeply (recursively evaluating records and arrays). 114 115 - `src`: null-terminated UTF-8 Nickel source code 116 - `out_expr`: allocated with `nickel_expr_alloc`, or `C_NULL` 117 - `out_error`: allocated with `nickel_error_alloc`, or `C_NULL` 118 119 Returns `NICKEL_RESULT_OK` on success, `NICKEL_RESULT_ERR` on failure. 120 """ 121 function nickel_context_eval_deep(ctx, src, out_expr, out_error) 122 @ccall libnickel_lang.nickel_context_eval_deep(ctx::Ptr{nickel_context}, src::Ptr{Cchar}, out_expr::Ptr{nickel_expr}, out_error::Ptr{nickel_error})::nickel_result 123 end 124 125 """ 126 nickel_context_eval_deep_for_export(ctx, src, out_expr, out_error) -> nickel_result 127 128 Like [`nickel_context_eval_deep`](@ref), but ignores fields marked `not_exported`. 129 """ 130 function nickel_context_eval_deep_for_export(ctx, src, out_expr, out_error) 131 @ccall libnickel_lang.nickel_context_eval_deep_for_export(ctx::Ptr{nickel_context}, src::Ptr{Cchar}, out_expr::Ptr{nickel_expr}, out_error::Ptr{nickel_error})::nickel_result 132 end 133 134 """ 135 nickel_context_eval_shallow(ctx, src, out_expr, out_error) -> nickel_result 136 137 Evaluate Nickel source to weak head normal form (WHNF). 138 Sub-expressions of records, arrays, and enum variants are left unevaluated. 139 Use [`nickel_context_eval_expr_shallow`](@ref) to evaluate them further. 140 """ 141 function nickel_context_eval_shallow(ctx, src, out_expr, out_error) 142 @ccall libnickel_lang.nickel_context_eval_shallow(ctx::Ptr{nickel_context}, src::Ptr{Cchar}, out_expr::Ptr{nickel_expr}, out_error::Ptr{nickel_error})::nickel_result 143 end 144 145 """ 146 nickel_context_eval_expr_shallow(ctx, expr, out_expr, out_error) -> nickel_result 147 148 Further evaluate an unevaluated expression to WHNF. Useful for evaluating 149 sub-expressions obtained from a shallow evaluation. 150 """ 151 function nickel_context_eval_expr_shallow(ctx, expr, out_expr, out_error) 152 @ccall libnickel_lang.nickel_context_eval_expr_shallow(ctx::Ptr{nickel_context}, expr::Ptr{nickel_expr}, out_expr::Ptr{nickel_expr}, out_error::Ptr{nickel_error})::nickel_result 153 end 154 155 # ── Expression lifecycle ───────────────────────────────────────────────────── 156 157 """ 158 nickel_expr_alloc() -> Ptr{nickel_expr} 159 160 Allocate a new expression. Must be freed with [`nickel_expr_free`](@ref). 161 Can be reused across multiple evaluations (overwritten in place). 162 """ 163 function nickel_expr_alloc() 164 @ccall libnickel_lang.nickel_expr_alloc()::Ptr{nickel_expr} 165 end 166 167 """ 168 nickel_expr_free(expr) 169 170 Free an expression allocated with [`nickel_expr_alloc`](@ref). 171 """ 172 function nickel_expr_free(expr) 173 @ccall libnickel_lang.nickel_expr_free(expr::Ptr{nickel_expr})::Cvoid 174 end 175 176 # ── Expression type checks ────────────────────────────────────────────────── 177 178 """ 179 nickel_expr_is_bool(expr) -> Cint 180 181 Returns non-zero if the expression is a boolean. 182 """ 183 function nickel_expr_is_bool(expr) 184 @ccall libnickel_lang.nickel_expr_is_bool(expr::Ptr{nickel_expr})::Cint 185 end 186 187 """ 188 nickel_expr_is_number(expr) -> Cint 189 190 Returns non-zero if the expression is a number. 191 """ 192 function nickel_expr_is_number(expr) 193 @ccall libnickel_lang.nickel_expr_is_number(expr::Ptr{nickel_expr})::Cint 194 end 195 196 """ 197 nickel_expr_is_str(expr) -> Cint 198 199 Returns non-zero if the expression is a string. 200 """ 201 function nickel_expr_is_str(expr) 202 @ccall libnickel_lang.nickel_expr_is_str(expr::Ptr{nickel_expr})::Cint 203 end 204 205 """ 206 nickel_expr_is_enum_tag(expr) -> Cint 207 208 Returns non-zero if the expression is an enum tag (no payload). 209 """ 210 function nickel_expr_is_enum_tag(expr) 211 @ccall libnickel_lang.nickel_expr_is_enum_tag(expr::Ptr{nickel_expr})::Cint 212 end 213 214 """ 215 nickel_expr_is_enum_variant(expr) -> Cint 216 217 Returns non-zero if the expression is an enum variant (tag with payload). 218 """ 219 function nickel_expr_is_enum_variant(expr) 220 @ccall libnickel_lang.nickel_expr_is_enum_variant(expr::Ptr{nickel_expr})::Cint 221 end 222 223 """ 224 nickel_expr_is_record(expr) -> Cint 225 226 Returns non-zero if the expression is a record. 227 """ 228 function nickel_expr_is_record(expr) 229 @ccall libnickel_lang.nickel_expr_is_record(expr::Ptr{nickel_expr})::Cint 230 end 231 232 """ 233 nickel_expr_is_array(expr) -> Cint 234 235 Returns non-zero if the expression is an array. 236 """ 237 function nickel_expr_is_array(expr) 238 @ccall libnickel_lang.nickel_expr_is_array(expr::Ptr{nickel_expr})::Cint 239 end 240 241 """ 242 nickel_expr_is_value(expr) -> Cint 243 244 Returns non-zero if the expression has been evaluated to a value 245 (null, bool, number, string, record, array, or enum). 246 Unevaluated sub-expressions from shallow eval return zero. 247 """ 248 function nickel_expr_is_value(expr) 249 @ccall libnickel_lang.nickel_expr_is_value(expr::Ptr{nickel_expr})::Cint 250 end 251 252 """ 253 nickel_expr_is_null(expr) -> Cint 254 255 Returns non-zero if the expression is null. 256 """ 257 function nickel_expr_is_null(expr) 258 @ccall libnickel_lang.nickel_expr_is_null(expr::Ptr{nickel_expr})::Cint 259 end 260 261 # ── Expression accessors ───────────────────────────────────────────────────── 262 263 """ 264 nickel_expr_as_bool(expr) -> Cint 265 266 Extract a boolean value. **Panics** (in Rust) if expr is not a bool. 267 """ 268 function nickel_expr_as_bool(expr) 269 @ccall libnickel_lang.nickel_expr_as_bool(expr::Ptr{nickel_expr})::Cint 270 end 271 272 """ 273 nickel_expr_as_str(expr, out_str) -> Csize_t 274 275 Extract a string value. Writes a pointer to the UTF-8 bytes (NOT null-terminated) 276 into `out_str`. Returns the byte length. 277 278 The string data borrows from `expr` and is invalidated on free/overwrite. 279 **Panics** (in Rust) if expr is not a string. 280 """ 281 function nickel_expr_as_str(expr, out_str) 282 @ccall libnickel_lang.nickel_expr_as_str(expr::Ptr{nickel_expr}, out_str::Ptr{Ptr{Cchar}})::Csize_t 283 end 284 285 """ 286 nickel_expr_as_number(expr) -> Ptr{nickel_number} 287 288 Extract a number reference. The returned pointer borrows from `expr`. 289 **Panics** (in Rust) if expr is not a number. 290 """ 291 function nickel_expr_as_number(expr) 292 @ccall libnickel_lang.nickel_expr_as_number(expr::Ptr{nickel_expr})::Ptr{nickel_number} 293 end 294 295 """ 296 nickel_expr_as_enum_tag(expr, out_str) -> Csize_t 297 298 Extract an enum tag string. Writes a pointer to the UTF-8 bytes (NOT null-terminated) 299 into `out_str`. Returns the byte length. 300 301 The string points to an interned string and will never be invalidated. 302 **Panics** (in Rust) if expr is not an enum tag. 303 """ 304 function nickel_expr_as_enum_tag(expr, out_str) 305 @ccall libnickel_lang.nickel_expr_as_enum_tag(expr::Ptr{nickel_expr}, out_str::Ptr{Ptr{Cchar}})::Csize_t 306 end 307 308 """ 309 nickel_expr_as_enum_variant(expr, out_str, out_expr) -> Csize_t 310 311 Extract an enum variant's tag string and payload. 312 313 - Writes tag string pointer to `out_str` (NOT null-terminated) 314 - Writes payload expression into `out_expr` (must be allocated) 315 - Returns the tag string byte length 316 317 **Panics** (in Rust) if expr is not an enum variant. 318 """ 319 function nickel_expr_as_enum_variant(expr, out_str, out_expr) 320 @ccall libnickel_lang.nickel_expr_as_enum_variant(expr::Ptr{nickel_expr}, out_str::Ptr{Ptr{Cchar}}, out_expr::Ptr{nickel_expr})::Csize_t 321 end 322 323 """ 324 nickel_expr_as_record(expr) -> Ptr{nickel_record} 325 326 Extract a record reference. The returned pointer borrows from `expr`. 327 **Panics** (in Rust) if expr is not a record. 328 """ 329 function nickel_expr_as_record(expr) 330 @ccall libnickel_lang.nickel_expr_as_record(expr::Ptr{nickel_expr})::Ptr{nickel_record} 331 end 332 333 """ 334 nickel_expr_as_array(expr) -> Ptr{nickel_array} 335 336 Extract an array reference. The returned pointer borrows from `expr`. 337 **Panics** (in Rust) if expr is not an array. 338 """ 339 function nickel_expr_as_array(expr) 340 @ccall libnickel_lang.nickel_expr_as_array(expr::Ptr{nickel_expr})::Ptr{nickel_array} 341 end 342 343 # ── Serialization (export) ─────────────────────────────────────────────────── 344 345 """ 346 nickel_context_expr_to_json(ctx, expr, out_string, out_err) -> nickel_result 347 348 Serialize an evaluated expression to JSON. Fails if the expression contains 349 enum variants or unevaluated sub-expressions. 350 """ 351 function nickel_context_expr_to_json(ctx, expr, out_string, out_err) 352 @ccall libnickel_lang.nickel_context_expr_to_json(ctx::Ptr{nickel_context}, expr::Ptr{nickel_expr}, out_string::Ptr{nickel_string}, out_err::Ptr{nickel_error})::nickel_result 353 end 354 355 """ 356 nickel_context_expr_to_yaml(ctx, expr, out_string, out_err) -> nickel_result 357 358 Serialize an evaluated expression to YAML. 359 """ 360 function nickel_context_expr_to_yaml(ctx, expr, out_string, out_err) 361 @ccall libnickel_lang.nickel_context_expr_to_yaml(ctx::Ptr{nickel_context}, expr::Ptr{nickel_expr}, out_string::Ptr{nickel_string}, out_err::Ptr{nickel_error})::nickel_result 362 end 363 364 """ 365 nickel_context_expr_to_toml(ctx, expr, out_string, out_err) -> nickel_result 366 367 Serialize an evaluated expression to TOML. 368 """ 369 function nickel_context_expr_to_toml(ctx, expr, out_string, out_err) 370 @ccall libnickel_lang.nickel_context_expr_to_toml(ctx::Ptr{nickel_context}, expr::Ptr{nickel_expr}, out_string::Ptr{nickel_string}, out_err::Ptr{nickel_error})::nickel_result 371 end 372 373 # ── Number accessors ───────────────────────────────────────────────────────── 374 375 """ 376 nickel_number_is_i64(num) -> Cint 377 378 Returns non-zero if the number is an integer within `Int64` range. 379 """ 380 function nickel_number_is_i64(num) 381 @ccall libnickel_lang.nickel_number_is_i64(num::Ptr{nickel_number})::Cint 382 end 383 384 """ 385 nickel_number_as_i64(num) -> Int64 386 387 Extract the integer value. **Panics** (in Rust) if not an in-range integer 388 (check with [`nickel_number_is_i64`](@ref) first). 389 """ 390 function nickel_number_as_i64(num) 391 @ccall libnickel_lang.nickel_number_as_i64(num::Ptr{nickel_number})::Int64 392 end 393 394 """ 395 nickel_number_as_f64(num) -> Cdouble 396 397 Extract the number as a `Float64`, rounding to nearest if necessary. 398 """ 399 function nickel_number_as_f64(num) 400 @ccall libnickel_lang.nickel_number_as_f64(num::Ptr{nickel_number})::Cdouble 401 end 402 403 """ 404 nickel_number_as_rational(num, out_numerator, out_denominator) 405 406 Extract the exact rational representation as decimal strings. 407 Both out-params must be allocated with [`nickel_string_alloc`](@ref). 408 """ 409 function nickel_number_as_rational(num, out_numerator, out_denominator) 410 @ccall libnickel_lang.nickel_number_as_rational(num::Ptr{nickel_number}, out_numerator::Ptr{nickel_string}, out_denominator::Ptr{nickel_string})::Cvoid 411 end 412 413 # ── Array accessors ────────────────────────────────────────────────────────── 414 415 """ 416 nickel_array_len(arr) -> Csize_t 417 418 Return the number of elements in the array. 419 A null pointer (empty array) returns 0. 420 """ 421 function nickel_array_len(arr) 422 @ccall libnickel_lang.nickel_array_len(arr::Ptr{nickel_array})::Csize_t 423 end 424 425 """ 426 nickel_array_get(arr, idx, out_expr) 427 428 Retrieve the element at 0-based index `idx` into `out_expr`. 429 `out_expr` must be allocated with [`nickel_expr_alloc`](@ref). 430 **Panics** (in Rust) if `idx` is out of bounds. 431 """ 432 function nickel_array_get(arr, idx, out_expr) 433 @ccall libnickel_lang.nickel_array_get(arr::Ptr{nickel_array}, idx::Csize_t, out_expr::Ptr{nickel_expr})::Cvoid 434 end 435 436 # ── Record accessors ───────────────────────────────────────────────────────── 437 438 """ 439 nickel_record_len(rec) -> Csize_t 440 441 Return the number of fields in the record. 442 A null pointer (empty record) returns 0. 443 """ 444 function nickel_record_len(rec) 445 @ccall libnickel_lang.nickel_record_len(rec::Ptr{nickel_record})::Csize_t 446 end 447 448 """ 449 nickel_record_key_value_by_index(rec, idx, out_key, out_key_len, out_expr) -> Cint 450 451 Retrieve the key and value at 0-based index `idx`. 452 453 - Writes key pointer to `out_key` (UTF-8, NOT null-terminated) 454 - Writes key byte length to `out_key_len` 455 - Writes value into `out_expr` if non-NULL (must be allocated) 456 - Returns 1 if the field has a value, 0 if it doesn't (shallow eval) 457 458 **Panics** (in Rust) if `idx` is out of range. 459 """ 460 function nickel_record_key_value_by_index(rec, idx, out_key, out_key_len, out_expr) 461 @ccall libnickel_lang.nickel_record_key_value_by_index(rec::Ptr{nickel_record}, idx::Csize_t, out_key::Ptr{Ptr{Cchar}}, out_key_len::Ptr{Csize_t}, out_expr::Ptr{nickel_expr})::Cint 462 end 463 464 """ 465 nickel_record_value_by_name(rec, key, out_expr) -> Cint 466 467 Look up a field by name. `key` must be a null-terminated C string. 468 Returns 1 if found and has a value, 0 otherwise. 469 """ 470 function nickel_record_value_by_name(rec, key, out_expr) 471 @ccall libnickel_lang.nickel_record_value_by_name(rec::Ptr{nickel_record}, key::Ptr{Cchar}, out_expr::Ptr{nickel_expr})::Cint 472 end 473 474 # ── String lifecycle and access ────────────────────────────────────────────── 475 476 """ 477 nickel_string_alloc() -> Ptr{nickel_string} 478 479 Allocate a new string. Must be freed with [`nickel_string_free`](@ref). 480 """ 481 function nickel_string_alloc() 482 @ccall libnickel_lang.nickel_string_alloc()::Ptr{nickel_string} 483 end 484 485 """ 486 nickel_string_free(s) 487 488 Free a string allocated with [`nickel_string_alloc`](@ref). 489 """ 490 function nickel_string_free(s) 491 @ccall libnickel_lang.nickel_string_free(s::Ptr{nickel_string})::Cvoid 492 end 493 494 """ 495 nickel_string_data(s, data, len) 496 497 Retrieve the contents of a string. Writes a pointer to the UTF-8 bytes 498 (NOT null-terminated) into `data`, and the byte length into `len`. 499 Data is invalidated when `s` is freed or overwritten. 500 """ 501 function nickel_string_data(s, data, len) 502 @ccall libnickel_lang.nickel_string_data(s::Ptr{nickel_string}, data::Ptr{Ptr{Cchar}}, len::Ptr{Csize_t})::Cvoid 503 end 504 505 # ── Error lifecycle and formatting ─────────────────────────────────────────── 506 507 """ 508 nickel_error_alloc() -> Ptr{nickel_error} 509 510 Allocate a new error. Must be freed with [`nickel_error_free`](@ref). 511 """ 512 function nickel_error_alloc() 513 @ccall libnickel_lang.nickel_error_alloc()::Ptr{nickel_error} 514 end 515 516 """ 517 nickel_error_free(err) 518 519 Free an error allocated with [`nickel_error_alloc`](@ref). 520 """ 521 function nickel_error_free(err) 522 @ccall libnickel_lang.nickel_error_free(err::Ptr{nickel_error})::Cvoid 523 end 524 525 """ 526 nickel_error_display(err, write, write_payload, format) -> nickel_result 527 528 Format an error via a write callback function. 529 """ 530 function nickel_error_display(err, write, write_payload, format) 531 @ccall libnickel_lang.nickel_error_display(err::Ptr{nickel_error}, write::nickel_write_callback, write_payload::Ptr{Cvoid}, format::nickel_error_format)::nickel_result 532 end 533 534 """ 535 nickel_error_format_as_string(err, out_string, format) -> nickel_result 536 537 Format an error into a [`nickel_string`](@ref). 538 `out_string` must be allocated with [`nickel_string_alloc`](@ref). 539 """ 540 function nickel_error_format_as_string(err, out_string, format) 541 @ccall libnickel_lang.nickel_error_format_as_string(err::Ptr{nickel_error}, out_string::Ptr{nickel_string}, format::nickel_error_format)::nickel_result 542 end 543 544 end # module LibNickel