git.delta.rocks / jrsonnet / refs/commits / 921b9905a568

--- a/bindings/jsonnet/Cargo.toml
+++ b/bindings/jsonnet/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "jsonnet"
+name = "libjsonnet"
 description = "Rust implementation of libjsonnet.so"
 version = "0.4.2"
 authors = ["Yaroslav Bolyukin <iam@lach.pw>"]
@@ -14,9 +14,11 @@
 jrsonnet-gcmodule = { version = "0.3.4" }
 
 [lib]
+name = "jsonnet"
 crate-type = ["cdylib"]
 
 [features]
+# Export additional functions for native integration, i.e ability to set custom trace format
 interop = []
 experimental = ["exp-preserve-order", "exp-destruct"]
 exp-preserve-order = ["jrsonnet-evaluator/exp-preserve-order"]

--- a/bindings/jsonnet/src/native.rs
+++ b/bindings/jsonnet/src/native.rs
@@ -12,6 +12,15 @@
 };
 use jrsonnet_gcmodule::Cc;
 
+/// The returned JsonnetJsonValue* should be allocated with jsonnet_realloc.  It will be cleaned up
+/// along with the objects rooted at argv by libjsonnet when no-longer needed.  Return a string upon
+/// failure, which will appear in Jsonnet as an error.  The argv pointer is an array whose size
+/// matches the array of parameters supplied when the native callback was originally registered.
+///
+/// - `ctx` User pointer, given in jsonnet_native_callback.
+/// - `argv` Array of arguments from Jsonnet code.
+/// - `param` success Set this byref param to 1 to indicate success and 0 for failure.
+/// Returns the content of the imported file, or an error message.
 type JsonnetNativeCallback = unsafe extern "C" fn(
 	ctx: *const c_void,
 	argv: *const *const Val,
@@ -44,13 +53,20 @@
 		if success == 1 {
 			Ok(v)
 		} else {
-			let e = IStr::from_untyped(v, s).expect("error msg");
+			let e = IStr::from_untyped(v, s).expect("error msg should be a string");
 			Err(Error::RuntimeError(e).into())
 		}
 	}
 }
 
+/// Callback to provide native extensions to Jsonnet.
+///
 /// # Safety
+///
+/// `vm` should be a vm allocated by `jsonnet_make`
+/// `cb` should be a correct function pointer
+/// `raw_params` should point to a NULL-terminated string array
+/// `name`, `raw_params` elements should be a \0-terminated strings
 #[no_mangle]
 pub unsafe extern "C" fn jsonnet_native_callback(
 	vm: &State,
@@ -59,13 +75,18 @@
 	ctx: *const c_void,
 	mut raw_params: *const *const c_char,
 ) {
-	let name = CStr::from_ptr(name).to_str().expect("utf8 name").into();
+	let name = CStr::from_ptr(name)
+		.to_str()
+		.expect("name is not utf-8")
+		.into();
 	let mut params = Vec::new();
 	loop {
 		if (*raw_params).is_null() {
 			break;
 		}
-		let param = CStr::from_ptr(*raw_params).to_str().expect("not utf8");
+		let param = CStr::from_ptr(*raw_params)
+			.to_str()
+			.expect("param name is not utf-8");
 		params.push(BuiltinParam {
 			name: param.into(),
 			has_default: false,

--- a/bindings/jsonnet/src/val_extract.rs
+++ b/bindings/jsonnet/src/val_extract.rs
@@ -7,6 +7,7 @@
 
 use jrsonnet_evaluator::{State, Val};
 
+/// If the value is a string, return it as UTF8 otherwise return NULL.
 #[no_mangle]
 pub extern "C" fn jsonnet_json_extract_string(_vm: &State, v: &Val) -> *mut c_char {
 	match v {
@@ -14,6 +15,8 @@
 		_ => std::ptr::null_mut(),
 	}
 }
+
+/// If the value is a number, return 1 and store the number in out, otherwise return 0.
 #[no_mangle]
 pub extern "C" fn jsonnet_json_extract_number(_vm: &State, v: &Val, out: &mut c_double) -> c_int {
 	match v {
@@ -24,6 +27,8 @@
 		_ => 0,
 	}
 }
+
+/// Return 0 if the value is false, 1 if it is true, and 2 if it is not a bool.
 #[no_mangle]
 pub extern "C" fn jsonnet_json_extract_bool(_vm: &State, v: &Val) -> c_int {
 	match v {
@@ -32,6 +37,8 @@
 		_ => 2,
 	}
 }
+
+/// Return 1 if the value is null, else 0.
 #[no_mangle]
 pub extern "C" fn jsonnet_json_extract_null(_vm: &State, v: &Val) -> c_int {
 	match v {

--- a/bindings/jsonnet/src/val_make.rs
+++ b/bindings/jsonnet/src/val_make.rs
@@ -8,37 +8,46 @@
 use jrsonnet_evaluator::{val::ArrValue, ObjValue, State, Val};
 use jrsonnet_gcmodule::Cc;
 
+/// Convert the given UTF8 string to a JsonnetJsonValue.
+///
 /// # Safety
 ///
-/// This function is safe, if received v is a pointer to normal C string
+/// `v` should be a \0-terminated string
 #[no_mangle]
-pub unsafe extern "C" fn jsonnet_json_make_string(_vm: &State, v: *const c_char) -> *mut Val {
-	let cstr = CStr::from_ptr(v);
-	let str = cstr.to_str().unwrap();
-	Box::into_raw(Box::new(Val::Str(str.into())))
+pub unsafe extern "C" fn jsonnet_json_make_string(_vm: &State, val: *const c_char) -> *mut Val {
+	let val = CStr::from_ptr(val);
+	let val = val.to_str().expect("string is not utf-8");
+	Box::into_raw(Box::new(Val::Str(val.into())))
 }
 
+/// Convert the given double to a JsonnetJsonValue.
 #[no_mangle]
 pub extern "C" fn jsonnet_json_make_number(_vm: &State, v: c_double) -> *mut Val {
 	Box::into_raw(Box::new(Val::Num(v)))
 }
 
+/// Convert the given bool (1 or 0) to a JsonnetJsonValue.
 #[no_mangle]
 pub extern "C" fn jsonnet_json_make_bool(_vm: &State, v: c_int) -> *mut Val {
-	assert!(v == 0 || v == 1);
+	assert!(v == 0 || v == 1, "bad boolean value");
 	Box::into_raw(Box::new(Val::Bool(v == 1)))
 }
 
+/// Make a JsonnetJsonValue representing null.
 #[no_mangle]
 pub extern "C" fn jsonnet_json_make_null(_vm: &State) -> *mut Val {
 	Box::into_raw(Box::new(Val::Null))
 }
 
+/// Make a JsonnetJsonValue representing an array.
+///
+/// Assign elements with jsonnet_json_array_append.
 #[no_mangle]
 pub extern "C" fn jsonnet_json_make_array(_vm: &State) -> *mut Val {
 	Box::into_raw(Box::new(Val::Arr(ArrValue::Eager(Cc::new(Vec::new())))))
 }
 
+/// Make a JsonnetJsonValue representing an object.
 #[no_mangle]
 pub extern "C" fn jsonnet_json_make_object(_vm: &State) -> *mut Val {
 	Box::into_raw(Box::new(Val::Obj(ObjValue::new_empty())))

--- a/bindings/jsonnet/src/val_modify.rs
+++ b/bindings/jsonnet/src/val_modify.rs
@@ -7,9 +7,12 @@
 use jrsonnet_evaluator::{val::ArrValue, State, Thunk, Val};
 use jrsonnet_gcmodule::Cc;
 
+/// Add value to the end of the array arr
+///
 /// # Safety
 ///
-/// Received arr value should be correct pointer to array allocated by make_array
+/// `arr` should be correct pointer to array value allocated by make_array, or returned by other library call
+/// `val` should be correct pointer to value allocated using this library
 #[no_mangle]
 pub unsafe extern "C" fn jsonnet_json_array_append(_vm: &State, arr: &mut Val, val: &Val) {
 	match arr {
@@ -26,9 +29,14 @@
 	}
 }
 
+/// Add the field to the object, bound to value.
+///
+/// This shadows any previous binding of the field.
+///
 /// # Safety
 ///
-/// This function is safe if passed name is ok
+/// `obj` should be pointer to object value allocated by make_object, or returned by other library call
+/// `name` should be \0-terminated string
 #[no_mangle]
 pub unsafe extern "C" fn jsonnet_json_object_append(
 	_vm: &State,

--- a/bindings/jsonnet/src/vars_tlas.rs
+++ b/bindings/jsonnet/src/vars_tlas.rs
@@ -4,52 +4,84 @@
 
 use jrsonnet_evaluator::State;
 
+/// Bind a Jsonnet external var to the given string.
+///
+/// Argument values are copied so memory should be managed by caller.
+///
 /// # Safety
+///
+/// Caller should pass correct pointers as `name` and `code`, they need to be \0-terminated strings
 #[no_mangle]
 pub unsafe extern "C" fn jsonnet_ext_var(vm: &State, name: *const c_char, value: *const c_char) {
 	let name = CStr::from_ptr(name);
 	let value = CStr::from_ptr(value);
 
-	let any_resolver = vm.context_initializer();
-	any_resolver
+	let any_initializer = vm.context_initializer();
+	any_initializer
 		.as_any()
 		.downcast_ref::<jrsonnet_stdlib::ContextInitializer>()
 		.expect("only stdlib context initializer supported")
 		.add_ext_str(
-			name.to_str().unwrap().into(),
-			value.to_str().unwrap().into(),
+			name.to_str().expect("name is not utf-8").into(),
+			value.to_str().expect("value is not utf-8").into(),
 		)
 }
 
+/// Bind a Jsonnet external var to the given code.
+///
+/// Argument values are copied so memory should be managed by caller.
+///
 /// # Safety
+///
+/// Caller should pass correct pointers as `name` and `code`, they need to be \0-terminated strings
 #[no_mangle]
-pub unsafe extern "C" fn jsonnet_ext_code(vm: &State, name: *const c_char, value: *const c_char) {
+pub unsafe extern "C" fn jsonnet_ext_code(vm: &State, name: *const c_char, code: *const c_char) {
 	let name = CStr::from_ptr(name);
-	let value = CStr::from_ptr(value);
+	let code = CStr::from_ptr(code);
 
-	let any_resolver = vm.context_initializer();
-	any_resolver
+	let any_initializer = vm.context_initializer();
+	any_initializer
 		.as_any()
 		.downcast_ref::<jrsonnet_stdlib::ContextInitializer>()
 		.expect("only stdlib context initializer supported")
-		.add_ext_code(name.to_str().unwrap(), value.to_str().unwrap())
-		.unwrap()
+		.add_ext_code(
+			name.to_str().expect("name is not utf-8"),
+			code.to_str().expect("code is not utf-8"),
+		)
+		.expect("can't parse ext code")
 }
+
+/// Bind a string top-level argument for a top-level parameter.
+///
+/// Argument values are copied so memory should be managed by caller.
+///
 /// # Safety
+///
+/// Caller should pass correct pointers as `name` and `value`, they need to be \0-terminated strings
 #[no_mangle]
 pub unsafe extern "C" fn jsonnet_tla_var(vm: &State, name: *const c_char, value: *const c_char) {
 	let name = CStr::from_ptr(name);
 	let value = CStr::from_ptr(value);
 	vm.add_tla_str(
-		name.to_str().unwrap().into(),
-		value.to_str().unwrap().into(),
+		name.to_str().expect("name is not utf-8").into(),
+		value.to_str().expect("value is not utf-8").into(),
 	)
 }
+
+/// Bind a code top-level argument for a top-level parameter.
+///
+/// Argument values are copied so memory should be managed by caller.
+///
 /// # Safety
+///
+/// Caller should pass correct pointers as `name` and `code`, they need to be \0-terminated strings
 #[no_mangle]
-pub unsafe extern "C" fn jsonnet_tla_code(vm: &State, name: *const c_char, value: *const c_char) {
+pub unsafe extern "C" fn jsonnet_tla_code(vm: &State, name: *const c_char, code: *const c_char) {
 	let name = CStr::from_ptr(name);
-	let value = CStr::from_ptr(value);
-	vm.add_tla_code(name.to_str().unwrap().into(), value.to_str().unwrap())
-		.unwrap()
+	let code = CStr::from_ptr(code);
+	vm.add_tla_code(
+		name.to_str().expect("name is not utf-8").into(),
+		code.to_str().expect("code is not utf-8"),
+	)
+	.expect("can't parse tla code")
 }