git.delta.rocks / jrsonnet / refs/commits / f44bc09e725c

difftreelog

docs cleanup evaluator's docs

progrm_jarvis2020-08-07parent: #e9a9036.patch.diff
in: master

7 files changed

modifiedcrates/jrsonnet-evaluator/src/builtin/stdlib.rsdiffbeforeafterboth
--- a/crates/jrsonnet-evaluator/src/builtin/stdlib.rs
+++ b/crates/jrsonnet-evaluator/src/builtin/stdlib.rs
@@ -2,7 +2,7 @@
 use std::{path::PathBuf, rc::Rc};
 
 thread_local! {
-	/// To avoid parsing again when issued from same thread
+	/// To avoid parsing again when issued from the same thread
 	#[allow(unreachable_code)]
 	static PARSED_STDLIB: LocExpr = {
 		#[cfg(feature = "codegenerated-stdlib")]
modifiedcrates/jrsonnet-evaluator/src/evaluate.rsdiffbeforeafterboth
--- a/crates/jrsonnet-evaluator/src/evaluate.rs
+++ b/crates/jrsonnet-evaluator/src/evaluate.rs
@@ -545,9 +545,9 @@
 			}
 			Val::Arr(Rc::new(out))
 		}
-		ArrComp(expr, compspecs) => Val::Arr(
-			// First compspec should be forspec, so no "None" possible here
-			Rc::new(evaluate_comp(context, &|ctx| evaluate(ctx, expr), compspecs)?.unwrap()),
+		ArrComp(expr, comp_specs) => Val::Arr(
+			// First comp_spec should be for_spec, so no "None" possible here
+			Rc::new(evaluate_comp(context, &|ctx| evaluate(ctx, expr), comp_specs)?.unwrap()),
 		),
 		Obj(body) => Val::Obj(evaluate_object(context, body)?),
 		ObjExtend(s, t) => evaluate_add_op(
@@ -564,7 +564,7 @@
 				|| "assertion condition".to_owned(),
 				|| {
 					evaluate(context.clone(), &value)?
-						.try_cast_bool("assertion condition should be boolean")
+						.try_cast_bool("assertion condition should be of type `boolean`")
 				},
 			)?;
 			if assertion_result {
@@ -580,7 +580,7 @@
 			|| "error statement".to_owned(),
 			|| {
 				throw!(RuntimeError(
-					evaluate(context, e)?.try_cast_str("error text should be string")?,
+					evaluate(context, e)?.try_cast_str("error text should be of type `string`")?,
 				))
 			},
 		)?,
@@ -590,7 +590,7 @@
 			cond_else,
 		} => {
 			if evaluate(context.clone(), &cond.0)?
-				.try_cast_bool("if condition should be boolean")?
+				.try_cast_bool("if condition should be of type `boolean`")?
 			{
 				evaluate(context, cond_then)?
 			} else {
@@ -603,7 +603,7 @@
 		Import(path) => {
 			let mut tmp = loc
 				.clone()
-				.expect("imports can't be used without loc_data")
+				.expect("imports cannot be used without loc_data")
 				.0;
 			let import_location = Rc::make_mut(&mut tmp);
 			import_location.pop();
@@ -616,7 +616,7 @@
 		ImportStr(path) => {
 			let mut tmp = loc
 				.clone()
-				.expect("imports can't be used without loc_data")
+				.expect("imports cannot be used without loc_data")
 				.0;
 			let import_location = Rc::make_mut(&mut tmp);
 			import_location.pop();
modifiedcrates/jrsonnet-evaluator/src/function.rsdiffbeforeafterboth
--- a/crates/jrsonnet-evaluator/src/function.rs
+++ b/crates/jrsonnet-evaluator/src/function.rs
@@ -7,13 +7,14 @@
 const NO_DEFAULT_CONTEXT: &str =
 	"no default context set for call with defined default parameter value";
 
-/// Creates correct [context](Context) for function body evaluation, returning error on invalid call
+/// Creates correct [context](Context) for function body evaluation returning error on invalid call.
 ///
-/// * `ctx` used for passed argument expressions execution, and for body execution (if `body_ctx` is not set)
-/// * `body_ctx` used for default parameter values execution, and for body execution (if set)
-/// * `params` function parameters definition
-/// * `args` passed function arguments
-/// * `tailstruct` if true - function arguments is eager executed, otherwise - lazy
+/// ## Parameters
+/// * `ctx`: used for passed argument expressions' execution and for body execution (if `body_ctx` is not set)
+/// * `body_ctx`: used for default parameter values' execution and for body execution (if set)
+/// * `params`: function parameters' definition
+/// * `args`: passed function arguments
+/// * `tailstrict`: if set to `true` function arguments are eagerly executed, otherwise - lazily
 pub fn parse_function_call(
 	ctx: Context,
 	body_ctx: Option<Context>,
modifiedcrates/jrsonnet-evaluator/src/import.rsdiffbeforeafterboth
--- a/crates/jrsonnet-evaluator/src/import.rs
+++ b/crates/jrsonnet-evaluator/src/import.rs
@@ -9,17 +9,19 @@
 
 /// Implements file resolution logic for `import` and `importStr`
 pub trait ImportResolver {
-	/// Resolve real file path, i.e
-	/// `(/home/user/manifests, b.libsonnet)` can resolve to both `/home/user/manifests/b.libsonnet` and to `/home/user/vendor/b.libsonnet`
-	/// (Where vendor is a library path)
+	/// Resolves real file path, e.g. `(/home/user/manifests, b.libjsonnet)` can correspond
+	/// both to `/home/user/manifests/b.libjsonnet` and to `/home/user/${vendor}/b.libjsonnet`
+	/// where `${vendor}` is a library path.
 	fn resolve_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<PathBuf>>;
+
 	/// Reads file from filesystem, should be used only with path received from `resolve_file`
 	fn load_file_contents(&self, resolved: &PathBuf) -> Result<Rc<str>>;
+
 	/// # Safety
 	///
-	/// For use in bindings, do not try to use it elsewhere
-	/// Implementations, which are not intended to be
-	/// used in bindings, should panic in this method
+	/// For use only in bindings, should not be used elsewhere.
+	/// Implementations which are not intended to be used in bindings
+	/// should panic on call to this method.
 	unsafe fn as_any(&self) -> &dyn Any;
 }
 
@@ -29,12 +31,14 @@
 	fn resolve_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<PathBuf>> {
 		throw!(ImportNotSupported(from.clone(), path.clone()))
 	}
+
 	fn load_file_contents(&self, _resolved: &PathBuf) -> Result<Rc<str>> {
 		// Can be only caused by library direct consumer, not by supplied jsonnet
 		panic!("dummy resolver can't load any file")
 	}
+
 	unsafe fn as_any(&self) -> &dyn Any {
-		panic!("this resolver can't be used as any")
+		panic!("`as_any($self)` is not supported by dummy resolver")
 	}
 }
 impl Default for Box<dyn ImportResolver> {
@@ -46,8 +50,8 @@
 /// File resolver, can load file from both FS and library paths
 #[derive(Default)]
 pub struct FileImportResolver {
-	/// Library directories to search for file
-	/// In original jsonnet referred as jpath
+	/// Library directories to search for file.
+	/// Referred to as `jpath` in original jsonnet implementation.
 	pub library_paths: Vec<PathBuf>,
 }
 impl ImportResolver for FileImportResolver {
@@ -81,7 +85,7 @@
 
 type ResolutionData = (PathBuf, PathBuf);
 
-/// Caches results of underlying resolver implementation
+/// Caches results of the underlying resolver
 pub struct CachingImportResolver {
 	resolution_cache: RefCell<HashMap<ResolutionData, Result<Rc<PathBuf>>>>,
 	loading_cache: RefCell<HashMap<PathBuf, Result<Rc<str>>>>,
@@ -95,6 +99,7 @@
 			.or_insert_with(|| self.inner.resolve_file(from, path))
 			.clone()
 	}
+
 	fn load_file_contents(&self, resolved: &PathBuf) -> Result<Rc<str>> {
 		self.loading_cache
 			.borrow_mut()
modifiedcrates/jrsonnet-evaluator/src/lib.rsdiffbeforeafterboth
after · crates/jrsonnet-evaluator/src/lib.rs
1#![cfg_attr(feature = "unstable", feature(stmt_expr_attributes))]2#![allow(macro_expanded_macro_exports_accessed_by_absolute_paths)]34mod builtin;5mod ctx;6mod dynamic;7pub mod error;8mod evaluate;9mod function;10mod import;11mod integrations;12mod map;13pub mod native;14mod obj;15pub mod trace;16mod val;1718pub use ctx::*;19pub use dynamic::*;20use error::{Error::*, LocError, Result, StackTraceElement};21pub use evaluate::*;22pub use function::parse_function_call;23pub use import::*;24use jrsonnet_parser::*;25use native::NativeCallback;26pub use obj::*;27use std::{28	cell::{Ref, RefCell, RefMut},29	collections::HashMap,30	fmt::Debug,31	path::PathBuf,32	rc::Rc,33};34use trace::{offset_to_location, CodeLocation, CompactFormat, TraceFormat};35pub use val::*;3637type BindableFn = dyn Fn(Option<ObjValue>, Option<ObjValue>) -> Result<LazyVal>;38#[derive(Clone)]39pub enum LazyBinding {40	Bindable(Rc<BindableFn>),41	Bound(LazyVal),42}4344impl Debug for LazyBinding {45	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {46		write!(f, "LazyBinding")47	}48}49impl LazyBinding {50	pub fn evaluate(&self, this: Option<ObjValue>, super_obj: Option<ObjValue>) -> Result<LazyVal> {51		match self {52			LazyBinding::Bindable(v) => v(this, super_obj),53			LazyBinding::Bound(v) => Ok(v.clone()),54		}55	}56}5758pub struct EvaluationSettings {59	/// Limits recursion by limiting the number of stack frames60	pub max_stack: usize,61	/// Limits amount of stack trace items preserved62	pub max_trace: usize,63	/// Used for s`td.extVar`64	pub ext_vars: HashMap<Rc<str>, Val>,65	/// Used for ext.native66	pub ext_natives: HashMap<Rc<str>, Rc<NativeCallback>>,67	/// TLA vars68	pub tla_vars: HashMap<Rc<str>, Val>,69	/// Global variables are inserted in default context70	pub globals: HashMap<Rc<str>, Val>,71	/// Used to resolve file locations/contents72	pub import_resolver: Box<dyn ImportResolver>,73	/// Used in manifestification functions74	pub manifest_format: ManifestFormat,75	/// Used for bindings76	pub trace_format: Box<dyn TraceFormat>,77}78impl Default for EvaluationSettings {79	fn default() -> Self {80		EvaluationSettings {81			max_stack: 200,82			max_trace: 20,83			globals: Default::default(),84			ext_vars: Default::default(),85			ext_natives: Default::default(),86			tla_vars: Default::default(),87			import_resolver: Box::new(DummyImportResolver),88			manifest_format: ManifestFormat::Json(4),89			trace_format: Box::new(CompactFormat {90				padding: 4,91				resolver: trace::PathResolver::Absolute,92			}),93		}94	}95}9697#[derive(Default)]98struct EvaluationData {99	/// Used for stack overflow detection, stacktrace is populated on unwind100	stack_depth: usize,101	/// Contains file source codes and evaluation results for imports and pretty-printed stacktraces102	files: HashMap<Rc<PathBuf>, FileData>,103	str_files: HashMap<Rc<PathBuf>, Rc<str>>,104}105106pub struct FileData {107	source_code: Rc<str>,108	parsed: LocExpr,109	evaluated: Option<Val>,110}111#[derive(Default)]112pub struct EvaluationStateInternals {113	/// Internal state114	data: RefCell<EvaluationData>,115	/// Settings, safe to change at runtime116	settings: RefCell<EvaluationSettings>,117}118119thread_local! {120	/// Contains the state for a currently executed file.121	/// Global state is fine here.122	pub(crate) static EVAL_STATE: RefCell<Option<EvaluationState>> = RefCell::new(None)123}124pub(crate) fn with_state<T>(f: impl FnOnce(&EvaluationState) -> T) -> T {125	EVAL_STATE.with(|s| f(s.borrow().as_ref().unwrap()))126}127pub(crate) fn push<T>(128	e: &Option<ExprLocation>,129	frame_desc: impl FnOnce() -> String,130	f: impl FnOnce() -> Result<T>,131) -> Result<T> {132	if let Some(v) = e {133		with_state(|s| s.push(&v, frame_desc, f))134	} else {135		f()136	}137}138139/// Maintains stack trace and import resolution140#[derive(Default, Clone)]141pub struct EvaluationState(Rc<EvaluationStateInternals>);142143impl EvaluationState {144	/// Parses and adds files as loaded145	pub fn add_file(&self, path: Rc<PathBuf>, source_code: Rc<str>) -> Result<()> {146		self.add_parsed_file(147			path.clone(),148			source_code.clone(),149			parse(150				&source_code,151				&ParserSettings {152					file_name: path.clone(),153					loc_data: true,154				},155			)156			.map_err(|error| ImportSyntaxError {157				error: Box::new(error),158				path,159				source_code,160			})?,161		)?;162163		Ok(())164	}165166	/// Adds file by source code and parsed expr167	pub fn add_parsed_file(168		&self,169		name: Rc<PathBuf>,170		source_code: Rc<str>,171		parsed: LocExpr,172	) -> Result<()> {173		self.data_mut().files.insert(174			name,175			FileData {176				source_code,177				parsed,178				evaluated: None,179			},180		);181182		Ok(())183	}184	pub fn get_source(&self, name: &PathBuf) -> Option<Rc<str>> {185		let ro_map = &self.data().files;186		ro_map.get(name).map(|value| value.source_code.clone())187	}188	pub fn map_source_locations(&self, file: &PathBuf, locs: &[usize]) -> Vec<CodeLocation> {189		offset_to_location(&self.get_source(file).unwrap(), locs)190	}191192	pub(crate) fn import_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Val> {193		let file_path = self.resolve_file(from, path)?;194		{195			let files = &self.data().files;196			if files.contains_key(&file_path) {197				return self.evaluate_loaded_file_raw(&file_path);198			}199		}200		let contents = self.load_file_contents(&file_path)?;201		self.add_file(file_path.clone(), contents)?;202		self.evaluate_loaded_file_raw(&file_path)203	}204	pub(crate) fn import_file_str(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<str>> {205		let path = self.resolve_file(from, path)?;206		if !self.data().str_files.contains_key(&path) {207			let file_str = self.load_file_contents(&path)?;208			self.data_mut().str_files.insert(path.clone(), file_str);209		}210		Ok(self.data().str_files.get(&path).cloned().unwrap())211	}212213	fn evaluate_loaded_file_raw(&self, name: &PathBuf) -> Result<Val> {214		let expr: LocExpr = {215			let ro_map = &self.data().files;216			let value = ro_map217				.get(name)218				.unwrap_or_else(|| panic!("file not added: {:?}", name));219			if let Some(ref evaluated) = value.evaluated {220				return Ok(evaluated.clone());221			}222			value.parsed.clone()223		};224		let value = evaluate(self.create_default_context()?, &expr)?;225		{226			self.data_mut()227				.files228				.get_mut(name)229				.unwrap()230				.evaluated231				.replace(value.clone());232		}233		Ok(value)234	}235236	/// Adds standard library global variable (std) to this evaluator237	pub fn with_stdlib(&self) -> &Self {238		use jrsonnet_stdlib::STDLIB_STR;239		let std_path = Rc::new(PathBuf::from("std.jsonnet"));240		self.run_in_state(|| {241			self.add_parsed_file(242				std_path.clone(),243				STDLIB_STR.to_owned().into(),244				builtin::get_parsed_stdlib(),245			)246			.unwrap();247			let val = self.evaluate_loaded_file_raw(&std_path).unwrap();248			self.settings_mut().globals.insert("std".into(), val);249		});250		self251	}252253	/// Creates context with all passed global variables254	pub fn create_default_context(&self) -> Result<Context> {255		let globals = &self.settings().globals;256		let mut new_bindings: HashMap<Rc<str>, LazyBinding> = HashMap::new();257		for (name, value) in globals.iter() {258			new_bindings.insert(259				name.clone(),260				LazyBinding::Bound(resolved_lazy_val!(value.clone())),261			);262		}263		Context::new().extend_unbound(new_bindings, None, None, None)264	}265266	/// Executes code creating a new stack frame267	pub fn push<T>(268		&self,269		e: &ExprLocation,270		frame_desc: impl FnOnce() -> String,271		f: impl FnOnce() -> Result<T>,272	) -> Result<T> {273		{274			let mut data = self.data_mut();275			let stack_depth = &mut data.stack_depth;276			if *stack_depth > self.max_stack() {277				// Error creation uses data, so i drop guard here278				drop(data);279				throw!(StackOverflow);280			} else {281				*stack_depth += 1;282			}283		}284		let result = f();285		self.data_mut().stack_depth -= 1;286		if let Err(mut err) = result {287			err.trace_mut().0.push(StackTraceElement {288				location: e.clone(),289				desc: frame_desc(),290			});291			return Err(err);292		}293		result294	}295296	/// Runs passed function in state (required if function needs to modify stack trace)297	pub fn run_in_state<T>(&self, f: impl FnOnce() -> T) -> T {298		EVAL_STATE.with(|v| {299			let has_state = v.borrow().is_some();300			if !has_state {301				v.borrow_mut().replace(self.clone());302			}303			let result = f();304			if !has_state {305				v.borrow_mut().take();306			}307			result308		})309	}310311	pub fn stringify_err(&self, e: &LocError) -> String {312		let mut out = String::new();313		self.settings()314			.trace_format315			.write_trace(&mut out, self, e)316			.unwrap();317		out318	}319320	pub fn manifest(&self, val: Val) -> Result<Rc<str>> {321		self.run_in_state(|| val.manifest(&self.manifest_format()))322	}323	pub fn manifest_multi(&self, val: Val) -> Result<Vec<(Rc<str>, Rc<str>)>> {324		self.run_in_state(|| val.manifest_multi(&self.manifest_format()))325	}326	pub fn manifest_stream(&self, val: Val) -> Result<Vec<Rc<str>>> {327		self.run_in_state(|| val.manifest_stream(&self.manifest_format()))328	}329330	/// If passed value is function then call with set TLA331	pub fn with_tla(&self, val: Val) -> Result<Val> {332		Ok(match val {333			Val::Func(func) => func.evaluate_map(334				self.create_default_context()?,335				&self.settings().tla_vars,336				true,337			)?,338			v => v,339		})340	}341}342343/// Internals344impl EvaluationState {345	fn data(&self) -> Ref<EvaluationData> {346		self.0.data.borrow()347	}348	fn data_mut(&self) -> RefMut<EvaluationData> {349		self.0.data.borrow_mut()350	}351	pub fn settings(&self) -> Ref<EvaluationSettings> {352		self.0.settings.borrow()353	}354	pub fn settings_mut(&self) -> RefMut<EvaluationSettings> {355		self.0.settings.borrow_mut()356	}357}358359/// Raw methods evaluate passed values but don't perform TLA execution360impl EvaluationState {361	pub fn evaluate_file_raw(&self, name: &PathBuf) -> Result<Val> {362		self.run_in_state(|| self.import_file(&std::env::current_dir().expect("cwd"), &name))363	}364	pub fn evaluate_file_raw_nocwd(&self, name: &PathBuf) -> Result<Val> {365		self.run_in_state(|| self.import_file(&PathBuf::from("."), &name))366	}367	/// Parses and evaluates the given snippet368	pub fn evaluate_snippet_raw(&self, source: Rc<PathBuf>, code: Rc<str>) -> Result<Val> {369		let parsed = parse(370			&code,371			&ParserSettings {372				file_name: source.clone(),373				loc_data: true,374			},375		)376		.unwrap();377		self.add_parsed_file(source, code, parsed.clone())?;378		self.evaluate_expr_raw(parsed)379	}380	/// Evaluates the parsed expression381	pub fn evaluate_expr_raw(&self, code: LocExpr) -> Result<Val> {382		self.run_in_state(|| evaluate(self.create_default_context()?, &code))383	}384}385386/// Settings utilities387impl EvaluationState {388	pub fn add_ext_var(&self, name: Rc<str>, value: Val) {389		self.settings_mut().ext_vars.insert(name, value);390	}391	pub fn add_ext_str(&self, name: Rc<str>, value: Rc<str>) {392		self.add_ext_var(name, Val::Str(value));393	}394	pub fn add_ext_code(&self, name: Rc<str>, code: Rc<str>) -> Result<()> {395		let value =396			self.evaluate_snippet_raw(Rc::new(PathBuf::from(format!("ext_code {}", name))), code)?;397		self.add_ext_var(name, value);398		Ok(())399	}400401	pub fn add_tla(&self, name: Rc<str>, value: Val) {402		self.settings_mut().tla_vars.insert(name, value);403	}404	pub fn add_tla_str(&self, name: Rc<str>, value: Rc<str>) {405		self.add_tla(name, Val::Str(value));406	}407	pub fn add_tla_code(&self, name: Rc<str>, code: Rc<str>) -> Result<()> {408		let value =409			self.evaluate_snippet_raw(Rc::new(PathBuf::from(format!("tla_code {}", name))), code)?;410		self.add_ext_var(name, value);411		Ok(())412	}413414	pub fn resolve_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<PathBuf>> {415		Ok(self.settings().import_resolver.resolve_file(from, path)?)416	}417	pub fn load_file_contents(&self, path: &PathBuf) -> Result<Rc<str>> {418		Ok(self.settings().import_resolver.load_file_contents(path)?)419	}420421	pub fn import_resolver(&self) -> Ref<dyn ImportResolver> {422		Ref::map(self.settings(), |s| &*s.import_resolver)423	}424	pub fn set_import_resolver(&self, resolver: Box<dyn ImportResolver>) {425		self.settings_mut().import_resolver = resolver;426	}427428	pub fn add_native(&self, name: Rc<str>, cb: Rc<NativeCallback>) {429		self.settings_mut().ext_natives.insert(name, cb);430	}431432	pub fn manifest_format(&self) -> ManifestFormat {433		self.settings().manifest_format.clone()434	}435	pub fn set_manifest_format(&self, format: ManifestFormat) {436		self.settings_mut().manifest_format = format;437	}438439	pub fn trace_format(&self) -> Ref<dyn TraceFormat> {440		Ref::map(self.settings(), |s| &*s.trace_format)441	}442	pub fn set_trace_format(&self, format: Box<dyn TraceFormat>) {443		self.settings_mut().trace_format = format;444	}445446	pub fn max_trace(&self) -> usize {447		self.settings().max_trace448	}449	pub fn set_max_trace(&self, trace: usize) {450		self.settings_mut().max_trace = trace;451	}452453	pub fn max_stack(&self) -> usize {454		self.settings().max_stack455	}456	pub fn set_max_stack(&self, trace: usize) {457		self.settings_mut().max_stack = trace;458	}459}460461#[cfg(test)]462pub mod tests {463	use super::Val;464	use crate::{error::Error::*, primitive_equals, EvaluationState};465	use jrsonnet_parser::*;466	use std::{path::PathBuf, rc::Rc};467468	#[test]469	#[should_panic]470	fn eval_state_stacktrace() {471		let state = EvaluationState::default();472		state.run_in_state(|| {473			state474				.push(475					&ExprLocation(Rc::new(PathBuf::from("test1.jsonnet")), 10, 20),476					|| "outer".to_owned(),477					|| {478						state.push(479							&ExprLocation(Rc::new(PathBuf::from("test2.jsonnet")), 30, 40),480							|| "inner".to_owned(),481							|| Err(RuntimeError("".into()).into()),482						)?;483						Ok(())484					},485				)486				.unwrap();487		});488	}489490	#[test]491	fn eval_state_standard() {492		let state = EvaluationState::default();493		state.with_stdlib();494		assert!(primitive_equals(495			&state496				.evaluate_snippet_raw(497					Rc::new(PathBuf::from("raw.jsonnet")),498					r#"std.assertEqual(std.base64("test"), "dGVzdA==")"#.into()499				)500				.unwrap(),501			&Val::Bool(true),502		)503		.unwrap());504	}505506	macro_rules! eval {507		($str: expr) => {508			EvaluationState::default()509				.with_stdlib()510				.evaluate_snippet_raw(Rc::new(PathBuf::from("raw.jsonnet")), $str.into())511				.unwrap()512		};513	}514	macro_rules! eval_json {515		($str: expr) => {{516			let evaluator = EvaluationState::default();517			evaluator.with_stdlib();518			evaluator.run_in_state(|| {519				evaluator520					.evaluate_snippet_raw(Rc::new(PathBuf::from("raw.jsonnet")), $str.into())521					.unwrap()522					.to_json(0)523					.unwrap()524					.replace("\n", "")525				})526			}};527	}528529	/// Asserts given code returns `true`530	macro_rules! assert_eval {531		($str: expr) => {532			assert!(primitive_equals(&eval!($str), &Val::Bool(true)).unwrap())533		};534	}535536	/// Asserts given code returns `false`537	macro_rules! assert_eval_neg {538		($str: expr) => {539			assert!(primitive_equals(&eval!($str), &Val::Bool(false)).unwrap())540		};541	}542	macro_rules! assert_json {543		($str: expr, $out: expr) => {544			assert_eq!(eval_json!($str), $out.replace("\t", ""))545		};546	}547548	/// Sanity checking, before trusting to another tests549	#[test]550	fn equality_operator() {551		assert_eval!("2 == 2");552		assert_eval_neg!("2 != 2");553		assert_eval!("2 != 3");554		assert_eval_neg!("2 == 3");555		assert_eval!("'Hello' == 'Hello'");556		assert_eval_neg!("'Hello' != 'Hello'");557		assert_eval!("'Hello' != 'World'");558		assert_eval_neg!("'Hello' == 'World'");559	}560561	#[test]562	fn math_evaluation() {563		assert_eval!("2 + 2 * 2 == 6");564		assert_eval!("3 + (2 + 2 * 2) == 9");565	}566567	#[test]568	fn string_concat() {569		assert_eval!("'Hello' + 'World' == 'HelloWorld'");570		assert_eval!("'Hello' * 3 == 'HelloHelloHello'");571		assert_eval!("'Hello' + 'World' * 3 == 'HelloWorldWorldWorld'");572	}573574	#[test]575	fn faster_join() {576		assert_eval!("std.join([0,0], [[1,2],[3,4],[5,6]]) == [1,2,0,0,3,4,0,0,5,6]");577		assert_eval!("std.join(',', ['1','2','3','4']) == '1,2,3,4'");578	}579580	#[test]581	fn function_contexts() {582		assert_eval!(583			r#"584				local k = {585					t(name = self.h): [self.h, name],586					h: 3,587				};588				local f = {589					t: k.t(),590					h: 4,591				};592				f.t[0] == f.t[1]593			"#594		);595	}596597	#[test]598	fn local() {599		assert_eval!("local a = 2; local b = 3; a + b == 5");600		assert_eval!("local a = 1, b = a + 1; a + b == 3");601		assert_eval!("local a = 1; local a = 2; a == 2");602	}603604	#[test]605	fn object_lazyness() {606		assert_json!("local a = {a:error 'test'}; {}", r#"{}"#);607	}608609	#[test]610	fn object_inheritance() {611		assert_json!("{a: self.b} + {b:3}", r#"{"a": 3,"b": 3}"#);612	}613614	#[test]615	fn object_assertion_success() {616		eval!("{assert \"a\" in self} + {a:2}");617	}618619	#[test]620	fn object_assertion_error() {621		eval!("{assert \"a\" in self}");622	}623624	#[test]625	fn lazy_args() {626		eval!("local test(a) = 2; test(error '3')");627	}628629	#[test]630	#[should_panic]631	fn tailstrict_args() {632		eval!("local test(a) = 2; test(error '3') tailstrict");633	}634635	#[test]636	#[should_panic]637	fn no_binding_error() {638		eval!("a");639	}640641	#[test]642	fn test_object() {643		assert_json!("{a:2}", r#"{"a": 2}"#);644		assert_json!("{a:2+2}", r#"{"a": 4}"#);645		assert_json!("{a:2}+{b:2}", r#"{"a": 2,"b": 2}"#);646		assert_json!("{b:3}+{b:2}", r#"{"b": 2}"#);647		assert_json!("{b:3}+{b+:2}", r#"{"b": 5}"#);648		assert_json!("local test='a'; {[test]:2}", r#"{"a": 2}"#);649		assert_json!(650			r#"651				{652					name: "Alice",653					welcome: "Hello " + self.name + "!",654				}655			"#,656			r#"{"name": "Alice","welcome": "Hello Alice!"}"#657		);658		assert_json!(659			r#"660				{661					name: "Alice",662					welcome: "Hello " + self.name + "!",663				} + {664					name: "Bob"665				}666			"#,667			r#"{"name": "Bob","welcome": "Hello Bob!"}"#668		);669	}670671	#[test]672	fn functions() {673		assert_json!(r#"local a = function(b, c = 2) b + c; a(2)"#, "4");674		assert_json!(675			r#"local a = function(b, c = "Dear") b + c + d, d = "World"; a("Hello")"#,676			r#""HelloDearWorld""#677		);678	}679680	#[test]681	fn local_methods() {682		assert_json!(r#"local a(b, c = 2) = b + c; a(2)"#, "4");683		assert_json!(684			r#"local a(b, c = "Dear") = b + c + d, d = "World"; a("Hello")"#,685			r#""HelloDearWorld""#686		);687	}688689	#[test]690	fn object_locals() {691		assert_json!(r#"{local a = 3, b: a}"#, r#"{"b": 3}"#);692		assert_json!(r#"{local a = 3, local c = a, b: c}"#, r#"{"b": 3}"#);693		assert_json!(694			r#"{local a = function (b) {[b]:4}, test: a("test")}"#,695			r#"{"test": {"test": 4}}"#696		);697	}698699	#[test]700	fn object_comp() {701		assert_json!(702			r#"{local t = "a", ["h"+i+"_"+z]: if "h"+(i-1)+"_"+z in self then t+1 else 0+t for i in [1,2,3] for z in [2,3,4] if z != i}"#,703			"{\"h1_2\": \"0a\",\"h1_3\": \"0a\",\"h1_4\": \"0a\",\"h2_3\": \"a1\",\"h2_4\": \"a1\",\"h3_2\": \"0a\",\"h3_4\": \"a1\"}"704		)705	}706707	#[test]708	fn direct_self() {709		println!(710			"{:#?}",711			eval!(712				r#"713					{714						local me = self,715						a: 3,716						b(): me.a,717					}718				"#719			)720		);721	}722723	#[test]724	fn indirect_self() {725		// `self` assigned to `me` was lost when being726		// referenced from field727		eval!(728			r#"{729				local me = self,730				a: 3,731				b: me.a,732			}.b"#733		);734	}735736	// We can't trust other tests (And official jsonnet testsuite), if assert is not working correctly737	#[test]738	fn std_assert_ok() {739		eval!("std.assertEqual(4.5 << 2, 16)");740	}741742	#[test]743	#[should_panic]744	fn std_assert_failure() {745		eval!("std.assertEqual(4.5 << 2, 15)");746	}747748	#[test]749	fn string_is_string() {750		assert!(primitive_equals(751			&eval!("local arr = 'hello'; (!std.isArray(arr)) && (!std.isString(arr))"),752			&Val::Bool(false),753		)754		.unwrap());755	}756757	#[test]758	fn base64_works() {759		assert_json!(r#"std.base64("test")"#, r#""dGVzdA==""#);760	}761762	#[test]763	fn utf8_chars() {764		assert_json!(765			r#"local c="😎";{c:std.codepoint(c),l:std.length(c)}"#,766			r#"{"c": 128526,"l": 1}"#767		)768	}769770	#[test]771	fn json() {772		assert_json!(773			r#"std.manifestJsonEx({a:3, b:4, c:6},"")"#,774			r#""{\n\"a\": 3,\n\"b\": 4,\n\"c\": 6\n}""#775		);776	}777778	#[test]779	fn test() {780		assert_json!(781			r#"[[a, b] for a in [1,2,3] for b in [4,5,6]]"#,782			"[[1,4],[1,5],[1,6],[2,4],[2,5],[2,6],[3,4],[3,5],[3,6]]"783		);784	}785786	#[test]787	fn sjsonnet() {788		eval!(789			r#"790			local x0 = {k: 1};791			local x1 = {k: x0.k + x0.k};792			local x2 = {k: x1.k + x1.k};793			local x3 = {k: x2.k + x2.k};794			local x4 = {k: x3.k + x3.k};795			local x5 = {k: x4.k + x4.k};796			local x6 = {k: x5.k + x5.k};797			local x7 = {k: x6.k + x6.k};798			local x8 = {k: x7.k + x7.k};799			local x9 = {k: x8.k + x8.k};800			local x10 = {k: x9.k + x9.k};801			local x11 = {k: x10.k + x10.k};802			local x12 = {k: x11.k + x11.k};803			local x13 = {k: x12.k + x12.k};804			local x14 = {k: x13.k + x13.k};805			local x15 = {k: x14.k + x14.k};806			local x16 = {k: x15.k + x15.k};807			local x17 = {k: x16.k + x16.k};808			local x18 = {k: x17.k + x17.k};809			local x19 = {k: x18.k + x18.k};810			local x20 = {k: x19.k + x19.k};811			local x21 = {k: x20.k + x20.k};812			x21.k813		"#814		);815	}816817	// This test is commented out by default, because of huge compilation slowdown818	// #[bench]819	// fn bench_codegen(b: &mut Bencher) {820	// 	b.iter(|| {821	// 		#[allow(clippy::all)]822	// 		let stdlib = {823	// 			use jrsonnet_parser::*;824	// 			include!(concat!(env!("OUT_DIR"), "/stdlib.rs"))825	// 		};826	// 		stdlib827	// 	})828	// }829830	/*831	#[bench]832	fn bench_serialize(b: &mut Bencher) {833		b.iter(|| {834			bincode::deserialize::<jrsonnet_parser::LocExpr>(include_bytes!(concat!(835				env!("OUT_DIR"),836				"/stdlib.bincode"837			)))838			.expect("deserialize stdlib")839		})840	}841842	#[bench]843	fn bench_parse(b: &mut Bencher) {844		b.iter(|| {845			jrsonnet_parser::parse(846				jrsonnet_stdlib::STDLIB_STR,847				&jrsonnet_parser::ParserSettings {848					loc_data: true,849					file_name: Rc::new(PathBuf::from("std.jsonnet")),850				},851			)852		})853	}854	*/855856	#[test]857	fn equality() {858		println!(859			"{:?}",860			jrsonnet_parser::parse(861				"{ x: 1, y: 2 } == { x: 1, y: 2 }",862				&ParserSettings::default()863			)864		);865		assert_eval!("{ x: 1, y: 2 } == { x: 1, y: 2 }")866	}867868	#[test]869	fn native_ext() -> crate::error::Result<()> {870		use super::native::NativeCallback;871		let evaluator = EvaluationState::default();872873		evaluator.with_stdlib();874		evaluator.settings_mut().ext_natives.insert(875			"native_add".into(),876			Rc::new(NativeCallback::new(877				ParamsDesc(Rc::new(vec![878					Param("a".into(), None),879					Param("b".into(), None),880				])),881				|args| match (&args[0], &args[1]) {882					(Val::Num(a), Val::Num(b)) => Ok(Val::Num(a + b)),883					(_, _) => todo!(),884				},885			)),886		);887		evaluator.evaluate_snippet_raw(888			Rc::new(PathBuf::from("test.jsonnet")),889			"std.assertEqual(std.native(\"native_add\")(1, 2), 3)".into(),890		)?;891		Ok(())892	}893}
modifiedcrates/jrsonnet-evaluator/src/trace/mod.rsdiffbeforeafterboth
--- a/crates/jrsonnet-evaluator/src/trace/mod.rs
+++ b/crates/jrsonnet-evaluator/src/trace/mod.rs
@@ -4,13 +4,13 @@
 pub use location::*;
 use std::path::PathBuf;
 
-/// How paths should be displayed
+/// The way paths should be displayed
 pub enum PathResolver {
-	/// Only filename will be shown
+	/// Only filename
 	FileName,
-	/// Absolute path of file
+	/// Absolute path
 	Absolute,
-	/// Relative path from base directory
+	/// Path relative to base directory
 	Relative(PathBuf),
 }
 
@@ -32,7 +32,7 @@
 	}
 }
 
-/// Implements trace to string pretty-printing
+/// Implements pretty-printing of traces
 pub trait TraceFormat {
 	fn write_trace(
 		&self,
@@ -73,7 +73,7 @@
 	Ok(())
 }
 
-/// vanilla jsonnet like formatting
+/// vanilla-like jsonnet formatting
 pub struct CompactFormat {
 	pub resolver: PathResolver,
 	pub padding: usize,
modifiedcrates/jrsonnet-evaluator/src/val.rsdiffbeforeafterboth
--- a/crates/jrsonnet-evaluator/src/val.rs
+++ b/crates/jrsonnet-evaluator/src/val.rs
@@ -225,7 +225,8 @@
 	};
 }
 impl Val {
-	/// Creates Val::Num after checking for overflow. As numbers are f64, we can just check for finity
+	/// Creates `Val::Num` after checking for numeric overflow.
+	/// As numbers are `f64`, we can just check for their finity.
 	pub fn new_checked_num(num: f64) -> Result<Val> {
 		if num.is_finite() {
 			Ok(Val::Num(num))
@@ -379,7 +380,7 @@
 		.map(|s| s.into())
 	}
 
-	/// Calls std.manifestJson
+	/// Calls `std.manifestJson`
 	#[cfg(feature = "faster")]
 	pub fn to_std_json(&self, padding: usize) -> Result<Rc<str>> {
 		manifest_json_ex(
@@ -392,7 +393,7 @@
 		.map(|s| s.into())
 	}
 
-	/// Calls std.manifestJson
+	/// Calls `std.manifestJson`
 	#[cfg(not(feature = "faster"))]
 	pub fn to_std_json(&self, padding: usize) -> Result<Rc<str>> {
 		with_state(|s| {
@@ -444,7 +445,7 @@
 	matches!(val, Val::Func(_))
 }
 
-/// Implements std.primitiveEquals builtin
+/// Native implementation of `std.primitiveEquals`
 pub fn primitive_equals(val_a: &Val, val_b: &Val) -> Result<bool> {
 	Ok(match (val_a.unwrap_if_lazy()?, val_b.unwrap_if_lazy()?) {
 		(Val::Bool(a), Val::Bool(b)) => a == b,
@@ -464,7 +465,7 @@
 	})
 }
 
-/// Native implementation of std.equals
+/// Native implementation of `std.equals`
 pub fn equals(val_a: &Val, val_b: &Val) -> Result<bool> {
 	let val_a = val_a.unwrap_if_lazy()?;
 	let val_b = val_b.unwrap_if_lazy()?;