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
before · 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 stack frames60	pub max_stack: usize,61	/// Limit amount of stack trace items preserved62	pub max_trace: usize,63	/// Used for std.extVar64	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 now populated on unwind100	stack_depth: usize,101	/// Contains file source codes and evaluated results for imports and pretty102	/// printing stacktraces103	files: HashMap<Rc<PathBuf>, FileData>,104	str_files: HashMap<Rc<PathBuf>, Rc<str>>,105}106107pub struct FileData {108	source_code: Rc<str>,109	parsed: LocExpr,110	evaluated: Option<Val>,111}112#[derive(Default)]113pub struct EvaluationStateInternals {114	/// Internal state115	data: RefCell<EvaluationData>,116	/// Settings, safe to change at runtime117	settings: RefCell<EvaluationSettings>,118}119120thread_local! {121	/// Contains state for currently executing file122	/// Global state is fine there123	pub(crate) static EVAL_STATE: RefCell<Option<EvaluationState>> = RefCell::new(None)124}125pub(crate) fn with_state<T>(f: impl FnOnce(&EvaluationState) -> T) -> T {126	EVAL_STATE.with(|s| f(s.borrow().as_ref().unwrap()))127}128pub(crate) fn push<T>(129	e: &Option<ExprLocation>,130	frame_desc: impl FnOnce() -> String,131	f: impl FnOnce() -> Result<T>,132) -> Result<T> {133	if let Some(v) = e {134		with_state(|s| s.push(&v, frame_desc, f))135	} else {136		f()137	}138}139140/// Maintains stack trace and import resolution141#[derive(Default, Clone)]142pub struct EvaluationState(Rc<EvaluationStateInternals>);143144impl EvaluationState {145	/// Parses and adds file to loaded146	pub fn add_file(&self, path: Rc<PathBuf>, source_code: Rc<str>) -> Result<()> {147		self.add_parsed_file(148			path.clone(),149			source_code.clone(),150			parse(151				&source_code,152				&ParserSettings {153					file_name: path.clone(),154					loc_data: true,155				},156			)157			.map_err(|error| ImportSyntaxError {158				error: Box::new(error),159				path,160				source_code,161			})?,162		)?;163164		Ok(())165	}166167	/// Adds file by source code and parsed expr168	pub fn add_parsed_file(169		&self,170		name: Rc<PathBuf>,171		source_code: Rc<str>,172		parsed: LocExpr,173	) -> Result<()> {174		self.data_mut().files.insert(175			name,176			FileData {177				source_code,178				parsed,179				evaluated: None,180			},181		);182183		Ok(())184	}185	pub fn get_source(&self, name: &PathBuf) -> Option<Rc<str>> {186		let ro_map = &self.data().files;187		ro_map.get(name).map(|value| value.source_code.clone())188	}189	pub fn map_source_locations(&self, file: &PathBuf, locs: &[usize]) -> Vec<CodeLocation> {190		offset_to_location(&self.get_source(file).unwrap(), locs)191	}192193	pub(crate) fn import_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Val> {194		let file_path = self.resolve_file(from, path)?;195		{196			let files = &self.data().files;197			if files.contains_key(&file_path) {198				return self.evaluate_loaded_file_raw(&file_path);199			}200		}201		let contents = self.load_file_contents(&file_path)?;202		self.add_file(file_path.clone(), contents)?;203		self.evaluate_loaded_file_raw(&file_path)204	}205	pub(crate) fn import_file_str(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<str>> {206		let path = self.resolve_file(from, path)?;207		if !self.data().str_files.contains_key(&path) {208			let file_str = self.load_file_contents(&path)?;209			self.data_mut().str_files.insert(path.clone(), file_str);210		}211		Ok(self.data().str_files.get(&path).cloned().unwrap())212	}213214	fn evaluate_loaded_file_raw(&self, name: &PathBuf) -> Result<Val> {215		let expr: LocExpr = {216			let ro_map = &self.data().files;217			let value = ro_map218				.get(name)219				.unwrap_or_else(|| panic!("file not added: {:?}", name));220			if let Some(ref evaluated) = value.evaluated {221				return Ok(evaluated.clone());222			}223			value.parsed.clone()224		};225		let value = evaluate(self.create_default_context()?, &expr)?;226		{227			self.data_mut()228				.files229				.get_mut(name)230				.unwrap()231				.evaluated232				.replace(value.clone());233		}234		Ok(value)235	}236237	/// Adds standard library global variable (std) to this evaluator238	pub fn with_stdlib(&self) -> &Self {239		use jrsonnet_stdlib::STDLIB_STR;240		let std_path = Rc::new(PathBuf::from("std.jsonnet"));241		self.run_in_state(|| {242			self.add_parsed_file(243				std_path.clone(),244				STDLIB_STR.to_owned().into(),245				builtin::get_parsed_stdlib(),246			)247			.unwrap();248			let val = self.evaluate_loaded_file_raw(&std_path).unwrap();249			self.settings_mut().globals.insert("std".into(), val);250		});251		self252	}253254	/// Creates context with all passed global variables255	pub fn create_default_context(&self) -> Result<Context> {256		let globals = &self.settings().globals;257		let mut new_bindings: HashMap<Rc<str>, LazyBinding> = HashMap::new();258		for (name, value) in globals.iter() {259			new_bindings.insert(260				name.clone(),261				LazyBinding::Bound(resolved_lazy_val!(value.clone())),262			);263		}264		Context::new().extend_unbound(new_bindings, None, None, None)265	}266267	/// Executes code, creating new stack frame268	pub fn push<T>(269		&self,270		e: &ExprLocation,271		frame_desc: impl FnOnce() -> String,272		f: impl FnOnce() -> Result<T>,273	) -> Result<T> {274		{275			let mut data = self.data_mut();276			let stack_depth = &mut data.stack_depth;277			if *stack_depth > self.max_stack() {278				// Error creation uses data, so i drop guard here279				drop(data);280				throw!(StackOverflow);281			} else {282				*stack_depth += 1;283			}284		}285		let result = f();286		self.data_mut().stack_depth -= 1;287		if let Err(mut err) = result {288			err.trace_mut().0.push(StackTraceElement {289				location: e.clone(),290				desc: frame_desc(),291			});292			return Err(err);293		}294		result295	}296297	/// Runs passed function in state (required, if function needs to modify stack trace)298	pub fn run_in_state<T>(&self, f: impl FnOnce() -> T) -> T {299		EVAL_STATE.with(|v| {300			let has_state = v.borrow().is_some();301			if !has_state {302				v.borrow_mut().replace(self.clone());303			}304			let result = f();305			if !has_state {306				v.borrow_mut().take();307			}308			result309		})310	}311312	pub fn stringify_err(&self, e: &LocError) -> String {313		let mut out = String::new();314		self.settings()315			.trace_format316			.write_trace(&mut out, self, e)317			.unwrap();318		out319	}320321	pub fn manifest(&self, val: Val) -> Result<Rc<str>> {322		self.run_in_state(|| val.manifest(&self.manifest_format()))323	}324	pub fn manifest_multi(&self, val: Val) -> Result<Vec<(Rc<str>, Rc<str>)>> {325		self.run_in_state(|| val.manifest_multi(&self.manifest_format()))326	}327	pub fn manifest_stream(&self, val: Val) -> Result<Vec<Rc<str>>> {328		self.run_in_state(|| val.manifest_stream(&self.manifest_format()))329	}330331	/// If passed value is function - call with set TLA332	pub fn with_tla(&self, val: Val) -> Result<Val> {333		Ok(match val {334			Val::Func(func) => func.evaluate_map(335				self.create_default_context()?,336				&self.settings().tla_vars,337				true,338			)?,339			v => v,340		})341	}342}343344/// Internals345impl EvaluationState {346	fn data(&self) -> Ref<EvaluationData> {347		self.0.data.borrow()348	}349	fn data_mut(&self) -> RefMut<EvaluationData> {350		self.0.data.borrow_mut()351	}352	pub fn settings(&self) -> Ref<EvaluationSettings> {353		self.0.settings.borrow()354	}355	pub fn settings_mut(&self) -> RefMut<EvaluationSettings> {356		self.0.settings.borrow_mut()357	}358}359360/// Raw methods evaluates passed values, but not performs TLA execution361impl EvaluationState {362	pub fn evaluate_file_raw(&self, name: &PathBuf) -> Result<Val> {363		self.run_in_state(|| self.import_file(&std::env::current_dir().expect("cwd"), &name))364	}365	pub fn evaluate_file_raw_nocwd(&self, name: &PathBuf) -> Result<Val> {366		self.run_in_state(|| self.import_file(&PathBuf::from("."), &name))367	}368	/// Parses and evaluates snippet369	pub fn evaluate_snippet_raw(&self, source: Rc<PathBuf>, code: Rc<str>) -> Result<Val> {370		let parsed = parse(371			&code,372			&ParserSettings {373				file_name: source.clone(),374				loc_data: true,375			},376		)377		.unwrap();378		self.add_parsed_file(source, code, parsed.clone())?;379		self.evaluate_expr_raw(parsed)380	}381	/// Evaluates parsed expression382	pub fn evaluate_expr_raw(&self, code: LocExpr) -> Result<Val> {383		self.run_in_state(|| evaluate(self.create_default_context()?, &code))384	}385}386387/// Settings utilities388impl EvaluationState {389	pub fn add_ext_var(&self, name: Rc<str>, value: Val) {390		self.settings_mut().ext_vars.insert(name, value);391	}392	pub fn add_ext_str(&self, name: Rc<str>, value: Rc<str>) {393		self.add_ext_var(name, Val::Str(value));394	}395	pub fn add_ext_code(&self, name: Rc<str>, code: Rc<str>) -> Result<()> {396		let value =397			self.evaluate_snippet_raw(Rc::new(PathBuf::from(format!("ext_code {}", name))), code)?;398		self.add_ext_var(name, value);399		Ok(())400	}401402	pub fn add_tla(&self, name: Rc<str>, value: Val) {403		self.settings_mut().tla_vars.insert(name, value);404	}405	pub fn add_tla_str(&self, name: Rc<str>, value: Rc<str>) {406		self.add_tla(name, Val::Str(value));407	}408	pub fn add_tla_code(&self, name: Rc<str>, code: Rc<str>) -> Result<()> {409		let value =410			self.evaluate_snippet_raw(Rc::new(PathBuf::from(format!("tla_code {}", name))), code)?;411		self.add_ext_var(name, value);412		Ok(())413	}414415	pub fn resolve_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<PathBuf>> {416		Ok(self.settings().import_resolver.resolve_file(from, path)?)417	}418	pub fn load_file_contents(&self, path: &PathBuf) -> Result<Rc<str>> {419		Ok(self.settings().import_resolver.load_file_contents(path)?)420	}421422	pub fn import_resolver(&self) -> Ref<dyn ImportResolver> {423		Ref::map(self.settings(), |s| &*s.import_resolver)424	}425	pub fn set_import_resolver(&self, resolver: Box<dyn ImportResolver>) {426		self.settings_mut().import_resolver = resolver;427	}428429	pub fn add_native(&self, name: Rc<str>, cb: Rc<NativeCallback>) {430		self.settings_mut().ext_natives.insert(name, cb);431	}432433	pub fn manifest_format(&self) -> ManifestFormat {434		self.settings().manifest_format.clone()435	}436	pub fn set_manifest_format(&self, format: ManifestFormat) {437		self.settings_mut().manifest_format = format;438	}439440	pub fn trace_format(&self) -> Ref<dyn TraceFormat> {441		Ref::map(self.settings(), |s| &*s.trace_format)442	}443	pub fn set_trace_format(&self, format: Box<dyn TraceFormat>) {444		self.settings_mut().trace_format = format;445	}446447	pub fn max_trace(&self) -> usize {448		self.settings().max_trace449	}450	pub fn set_max_trace(&self, trace: usize) {451		self.settings_mut().max_trace = trace;452	}453454	pub fn max_stack(&self) -> usize {455		self.settings().max_stack456	}457	pub fn set_max_stack(&self, trace: usize) {458		self.settings_mut().max_stack = trace;459	}460}461462#[cfg(test)]463pub mod tests {464	use super::Val;465	use crate::{error::Error::*, primitive_equals, EvaluationState};466	use jrsonnet_parser::*;467	use std::{path::PathBuf, rc::Rc};468469	#[test]470	#[should_panic]471	fn eval_state_stacktrace() {472		let state = EvaluationState::default();473		state.run_in_state(|| {474			state475				.push(476					&ExprLocation(Rc::new(PathBuf::from("test1.jsonnet")), 10, 20),477					|| "outer".to_owned(),478					|| {479						state.push(480							&ExprLocation(Rc::new(PathBuf::from("test2.jsonnet")), 30, 40),481							|| "inner".to_owned(),482							|| Err(RuntimeError("".into()).into()),483						)?;484						Ok(())485					},486				)487				.unwrap();488		});489	}490491	#[test]492	fn eval_state_standard() {493		let state = EvaluationState::default();494		state.with_stdlib();495		assert!(primitive_equals(496			&state497				.evaluate_snippet_raw(498					Rc::new(PathBuf::from("raw.jsonnet")),499					r#"std.assertEqual(std.base64("test"), "dGVzdA==")"#.into()500				)501				.unwrap(),502			&Val::Bool(true),503		)504		.unwrap());505	}506507	macro_rules! eval {508		($str: expr) => {509			EvaluationState::default()510				.with_stdlib()511				.evaluate_snippet_raw(Rc::new(PathBuf::from("raw.jsonnet")), $str.into())512				.unwrap()513		};514	}515	macro_rules! eval_json {516		($str: expr) => {{517			let evaluator = EvaluationState::default();518			evaluator.with_stdlib();519			evaluator.run_in_state(|| {520				evaluator521					.evaluate_snippet_raw(Rc::new(PathBuf::from("raw.jsonnet")), $str.into())522					.unwrap()523					.to_json(0)524					.unwrap()525					.replace("\n", "")526				})527			}};528	}529530	/// Asserts given code returns `true`531	macro_rules! assert_eval {532		($str: expr) => {533			assert!(primitive_equals(&eval!($str), &Val::Bool(true)).unwrap())534		};535	}536537	/// Asserts given code returns `false`538	macro_rules! assert_eval_neg {539		($str: expr) => {540			assert!(primitive_equals(&eval!($str), &Val::Bool(false)).unwrap())541		};542	}543	macro_rules! assert_json {544		($str: expr, $out: expr) => {545			assert_eq!(eval_json!($str), $out.replace("\t", ""))546		};547	}548549	/// Sanity checking, before trusting to another tests550	#[test]551	fn equality_operator() {552		assert_eval!("2 == 2");553		assert_eval_neg!("2 != 2");554		assert_eval!("2 != 3");555		assert_eval_neg!("2 == 3");556		assert_eval!("'Hello' == 'Hello'");557		assert_eval_neg!("'Hello' != 'Hello'");558		assert_eval!("'Hello' != 'World'");559		assert_eval_neg!("'Hello' == 'World'");560	}561562	#[test]563	fn math_evaluation() {564		assert_eval!("2 + 2 * 2 == 6");565		assert_eval!("3 + (2 + 2 * 2) == 9");566	}567568	#[test]569	fn string_concat() {570		assert_eval!("'Hello' + 'World' == 'HelloWorld'");571		assert_eval!("'Hello' * 3 == 'HelloHelloHello'");572		assert_eval!("'Hello' + 'World' * 3 == 'HelloWorldWorldWorld'");573	}574575	#[test]576	fn faster_join() {577		assert_eval!("std.join([0,0], [[1,2],[3,4],[5,6]]) == [1,2,0,0,3,4,0,0,5,6]");578		assert_eval!("std.join(',', ['1','2','3','4']) == '1,2,3,4'");579	}580581	#[test]582	fn function_contexts() {583		assert_eval!(584			r#"585				local k = {586					t(name = self.h): [self.h, name],587					h: 3,588				};589				local f = {590					t: k.t(),591					h: 4,592				};593				f.t[0] == f.t[1]594			"#595		);596	}597598	#[test]599	fn local() {600		assert_eval!("local a = 2; local b = 3; a + b == 5");601		assert_eval!("local a = 1, b = a + 1; a + b == 3");602		assert_eval!("local a = 1; local a = 2; a == 2");603	}604605	#[test]606	fn object_lazyness() {607		assert_json!("local a = {a:error 'test'}; {}", r#"{}"#);608	}609610	#[test]611	fn object_inheritance() {612		assert_json!("{a: self.b} + {b:3}", r#"{"a": 3,"b": 3}"#);613	}614615	#[test]616	fn object_assertion_success() {617		eval!("{assert \"a\" in self} + {a:2}");618	}619620	#[test]621	fn object_assertion_error() {622		eval!("{assert \"a\" in self}");623	}624625	#[test]626	fn lazy_args() {627		eval!("local test(a) = 2; test(error '3')");628	}629630	#[test]631	#[should_panic]632	fn tailstrict_args() {633		eval!("local test(a) = 2; test(error '3') tailstrict");634	}635636	#[test]637	#[should_panic]638	fn no_binding_error() {639		eval!("a");640	}641642	#[test]643	fn test_object() {644		assert_json!("{a:2}", r#"{"a": 2}"#);645		assert_json!("{a:2+2}", r#"{"a": 4}"#);646		assert_json!("{a:2}+{b:2}", r#"{"a": 2,"b": 2}"#);647		assert_json!("{b:3}+{b:2}", r#"{"b": 2}"#);648		assert_json!("{b:3}+{b+:2}", r#"{"b": 5}"#);649		assert_json!("local test='a'; {[test]:2}", r#"{"a": 2}"#);650		assert_json!(651			r#"652				{653					name: "Alice",654					welcome: "Hello " + self.name + "!",655				}656			"#,657			r#"{"name": "Alice","welcome": "Hello Alice!"}"#658		);659		assert_json!(660			r#"661				{662					name: "Alice",663					welcome: "Hello " + self.name + "!",664				} + {665					name: "Bob"666				}667			"#,668			r#"{"name": "Bob","welcome": "Hello Bob!"}"#669		);670	}671672	#[test]673	fn functions() {674		assert_json!(r#"local a = function(b, c = 2) b + c; a(2)"#, "4");675		assert_json!(676			r#"local a = function(b, c = "Dear") b + c + d, d = "World"; a("Hello")"#,677			r#""HelloDearWorld""#678		);679	}680681	#[test]682	fn local_methods() {683		assert_json!(r#"local a(b, c = 2) = b + c; a(2)"#, "4");684		assert_json!(685			r#"local a(b, c = "Dear") = b + c + d, d = "World"; a("Hello")"#,686			r#""HelloDearWorld""#687		);688	}689690	#[test]691	fn object_locals() {692		assert_json!(r#"{local a = 3, b: a}"#, r#"{"b": 3}"#);693		assert_json!(r#"{local a = 3, local c = a, b: c}"#, r#"{"b": 3}"#);694		assert_json!(695			r#"{local a = function (b) {[b]:4}, test: a("test")}"#,696			r#"{"test": {"test": 4}}"#697		);698	}699700	#[test]701	fn object_comp() {702		assert_json!(703			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}"#,704			"{\"h1_2\": \"0a\",\"h1_3\": \"0a\",\"h1_4\": \"0a\",\"h2_3\": \"a1\",\"h2_4\": \"a1\",\"h3_2\": \"0a\",\"h3_4\": \"a1\"}"705		)706	}707708	#[test]709	fn direct_self() {710		println!(711			"{:#?}",712			eval!(713				r#"714					{715						local me = self,716						a: 3,717						b(): me.a,718					}719				"#720			)721		);722	}723724	#[test]725	fn indirect_self() {726		// `self` assigned to `me` was lost when being727		// referenced from field728		eval!(729			r#"{730				local me = self,731				a: 3,732				b: me.a,733			}.b"#734		);735	}736737	// We can't trust other tests (And official jsonnet testsuite), if assert is not working correctly738	#[test]739	fn std_assert_ok() {740		eval!("std.assertEqual(4.5 << 2, 16)");741	}742743	#[test]744	#[should_panic]745	fn std_assert_failure() {746		eval!("std.assertEqual(4.5 << 2, 15)");747	}748749	#[test]750	fn string_is_string() {751		assert!(primitive_equals(752			&eval!("local arr = 'hello'; (!std.isArray(arr)) && (!std.isString(arr))"),753			&Val::Bool(false),754		)755		.unwrap());756	}757758	#[test]759	fn base64_works() {760		assert_json!(r#"std.base64("test")"#, r#""dGVzdA==""#);761	}762763	#[test]764	fn utf8_chars() {765		assert_json!(766			r#"local c="😎";{c:std.codepoint(c),l:std.length(c)}"#,767			r#"{"c": 128526,"l": 1}"#768		)769	}770771	#[test]772	fn json() {773		assert_json!(774			r#"std.manifestJsonEx({a:3, b:4, c:6},"")"#,775			r#""{\n\"a\": 3,\n\"b\": 4,\n\"c\": 6\n}""#776		);777	}778779	#[test]780	fn test() {781		assert_json!(782			r#"[[a, b] for a in [1,2,3] for b in [4,5,6]]"#,783			"[[1,4],[1,5],[1,6],[2,4],[2,5],[2,6],[3,4],[3,5],[3,6]]"784		);785	}786787	#[test]788	fn sjsonnet() {789		eval!(790			r#"791			local x0 = {k: 1};792			local x1 = {k: x0.k + x0.k};793			local x2 = {k: x1.k + x1.k};794			local x3 = {k: x2.k + x2.k};795			local x4 = {k: x3.k + x3.k};796			local x5 = {k: x4.k + x4.k};797			local x6 = {k: x5.k + x5.k};798			local x7 = {k: x6.k + x6.k};799			local x8 = {k: x7.k + x7.k};800			local x9 = {k: x8.k + x8.k};801			local x10 = {k: x9.k + x9.k};802			local x11 = {k: x10.k + x10.k};803			local x12 = {k: x11.k + x11.k};804			local x13 = {k: x12.k + x12.k};805			local x14 = {k: x13.k + x13.k};806			local x15 = {k: x14.k + x14.k};807			local x16 = {k: x15.k + x15.k};808			local x17 = {k: x16.k + x16.k};809			local x18 = {k: x17.k + x17.k};810			local x19 = {k: x18.k + x18.k};811			local x20 = {k: x19.k + x19.k};812			local x21 = {k: x20.k + x20.k};813			x21.k814		"#815		);816	}817818	// This test is commented out by default, because of huge compilation slowdown819	// #[bench]820	// fn bench_codegen(b: &mut Bencher) {821	// 	b.iter(|| {822	// 		#[allow(clippy::all)]823	// 		let stdlib = {824	// 			use jrsonnet_parser::*;825	// 			include!(concat!(env!("OUT_DIR"), "/stdlib.rs"))826	// 		};827	// 		stdlib828	// 	})829	// }830831	/*832	#[bench]833	fn bench_serialize(b: &mut Bencher) {834		b.iter(|| {835			bincode::deserialize::<jrsonnet_parser::LocExpr>(include_bytes!(concat!(836				env!("OUT_DIR"),837				"/stdlib.bincode"838			)))839			.expect("deserialize stdlib")840		})841	}842843	#[bench]844	fn bench_parse(b: &mut Bencher) {845		b.iter(|| {846			jrsonnet_parser::parse(847				jrsonnet_stdlib::STDLIB_STR,848				&jrsonnet_parser::ParserSettings {849					loc_data: true,850					file_name: Rc::new(PathBuf::from("std.jsonnet")),851				},852			)853		})854	}855	*/856857	#[test]858	fn equality() {859		println!(860			"{:?}",861			jrsonnet_parser::parse(862				"{ x: 1, y: 2 } == { x: 1, y: 2 }",863				&ParserSettings::default()864			)865		);866		assert_eval!("{ x: 1, y: 2 } == { x: 1, y: 2 }")867	}868869	#[test]870	fn native_ext() -> crate::error::Result<()> {871		use super::native::NativeCallback;872		let evaluator = EvaluationState::default();873874		evaluator.with_stdlib();875		evaluator.settings_mut().ext_natives.insert(876			"native_add".into(),877			Rc::new(NativeCallback::new(878				ParamsDesc(Rc::new(vec![879					Param("a".into(), None),880					Param("b".into(), None),881				])),882				|args| match (&args[0], &args[1]) {883					(Val::Num(a), Val::Num(b)) => Ok(Val::Num(a + b)),884					(_, _) => todo!(),885				},886			)),887		);888		evaluator.evaluate_snippet_raw(889			Rc::new(PathBuf::from("test.jsonnet")),890			"std.assertEqual(std.native(\"native_add\")(1, 2), 3)".into(),891		)?;892		Ok(())893	}894}
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()?;