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

--- a/crates/jrsonnet-evaluator/src/import.rs
+++ b/crates/jrsonnet-evaluator/src/import.rs
@@ -8,12 +8,23 @@
 use std::io::Read;
 use std::{any::Any, cell::RefCell, collections::HashMap, path::PathBuf, rc::Rc};
 
+/// 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)
 	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
 	unsafe fn as_any(&self) -> &dyn Any;
 }
 
+/// Dummy resolver, can't resolve/load any file
 pub struct DummyImportResolver;
 impl ImportResolver for DummyImportResolver {
 	fn resolve_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<PathBuf>> {
@@ -33,7 +44,11 @@
 	}
 }
 
+/// 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
 	pub library_paths: Vec<PathBuf>,
 }
 impl ImportResolver for FileImportResolver {
@@ -67,6 +82,8 @@
 }
 
 type ResolutionData = (PathBuf, PathBuf);
+
+/// Caches results of underlying resolver implementation
 pub struct CachingImportResolver {
 	resolution_cache: RefCell<HashMap<ResolutionData, Result<Rc<PathBuf>>>>,
 	loading_cache: RefCell<HashMap<PathBuf, Result<Rc<str>>>>,

311		Context::new().extend_unbound(new_bindings, None, None, None)311		Context::new().extend_unbound(new_bindings, None, None, None)
312	}312	}
313313
314	/// Executes code, creating new stack frame
314	pub fn push<T>(315	pub fn push<T>(
315		&self,316		&self,
316		e: ExprLocation,317		e: ExprLocation,
332		self.data_mut().stack.pop();333		self.data_mut().stack.pop();
333		result334		result
334	}335	}
335	pub fn print_stack_trace(&self) {336
336		for e in self.stack_trace().0 {337	/// Returns current stack trace
337			println!("{:?} - {:?}", e.0, e.1)
338		}
339	}
340	pub fn stack_trace(&self) -> StackTrace {338	pub fn stack_trace(&self) -> StackTrace {
341		StackTrace(339		StackTrace(
342			self.data()340			self.data()
349		)347		)
350	}348	}
349
350	/// Creates error with stack trace
351	pub fn error(&self, err: Error) -> LocError {351	pub fn error(&self, err: Error) -> LocError {
352		LocError(err, self.stack_trace())352		LocError(err, self.stack_trace())
353	}353	}
354354
355	/// Runs passed function in state (required, if function needs to modify stack trace)
355	pub fn run_in_state<T>(&self, f: impl FnOnce() -> T) -> T {356	pub fn run_in_state<T>(&self, f: impl FnOnce() -> T) -> T {
356		EVAL_STATE.with(|v| {357		EVAL_STATE.with(|v| {
357			let has_state = v.borrow().is_some();358			let has_state = v.borrow().is_some();
386						ExprLocation(Rc::new(PathBuf::from("test2.jsonnet")), 30, 40),387						ExprLocation(Rc::new(PathBuf::from("test2.jsonnet")), 30, 40),
387						"inner".to_owned(),388						"inner".to_owned(),
388						|| {389						|| {
389							state.print_stack_trace();
390							Ok(())390							Ok(())
391						},391						},
392					)?;392					)?;