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

difftreelog

docs(evaluator) document public api

Лач2020-06-28parent: #12f7f36.patch.diff
in: master

2 files changed

modifiedcrates/jrsonnet-evaluator/src/import.rsdiffbeforeafterboth
8use std::io::Read;8use std::io::Read;
9use std::{any::Any, cell::RefCell, collections::HashMap, path::PathBuf, rc::Rc};9use std::{any::Any, cell::RefCell, collections::HashMap, path::PathBuf, rc::Rc};
1010
11/// Implements file resolution logic for `import` and `importStr`
11pub trait ImportResolver {12pub trait ImportResolver {
13 /// Resolve real file path, i.e
14 /// `(/home/user/manifests, b.libsonnet)` can resolve to both `/home/user/manifests/b.libsonnet` and to `/home/user/vendor/b.libsonnet`
15 /// (Where vendor is a library path)
12 fn resolve_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<PathBuf>>;16 fn resolve_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<PathBuf>>;
17 /// Reads file from filesystem, should be used only with path received from `resolve_file`
13 fn load_file_contents(&self, resolved: &PathBuf) -> Result<Rc<str>>;18 fn load_file_contents(&self, resolved: &PathBuf) -> Result<Rc<str>>;
19 /// # Safety
20 ///
21 /// For use in bindings, do not try to use it elsewhere
22 /// Implementations, which are not intended to be
23 /// used in bindings, should panic in this method
14 unsafe fn as_any(&self) -> &dyn Any;24 unsafe fn as_any(&self) -> &dyn Any;
15}25}
1626
27/// Dummy resolver, can't resolve/load any file
17pub struct DummyImportResolver;28pub struct DummyImportResolver;
18impl ImportResolver for DummyImportResolver {29impl ImportResolver for DummyImportResolver {
19 fn resolve_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<PathBuf>> {30 fn resolve_file(&self, from: &PathBuf, path: &PathBuf) -> Result<Rc<PathBuf>> {
33 }44 }
34}45}
3546
47/// File resolver, can load file from both FS and library paths
48#[derive(Default)]
36pub struct FileImportResolver {49pub struct FileImportResolver {
50 /// Library directories to search for file
51 /// In original jsonnet referred as jpath
37 pub library_paths: Vec<PathBuf>,52 pub library_paths: Vec<PathBuf>,
38}53}
39impl ImportResolver for FileImportResolver {54impl ImportResolver for FileImportResolver {
6883
69type ResolutionData = (PathBuf, PathBuf);84type ResolutionData = (PathBuf, PathBuf);
85
86/// Caches results of underlying resolver implementation
70pub struct CachingImportResolver {87pub struct CachingImportResolver {
71 resolution_cache: RefCell<HashMap<ResolutionData, Result<Rc<PathBuf>>>>,88 resolution_cache: RefCell<HashMap<ResolutionData, Result<Rc<PathBuf>>>>,
72 loading_cache: RefCell<HashMap<PathBuf, Result<Rc<str>>>>,89 loading_cache: RefCell<HashMap<PathBuf, Result<Rc<str>>>>,
modifiedcrates/jrsonnet-evaluator/src/lib.rsdiffbeforeafterboth
--- a/crates/jrsonnet-evaluator/src/lib.rs
+++ b/crates/jrsonnet-evaluator/src/lib.rs
@@ -311,6 +311,7 @@
 		Context::new().extend_unbound(new_bindings, None, None, None)
 	}
 
+	/// Executes code, creating new stack frame
 	pub fn push<T>(
 		&self,
 		e: ExprLocation,
@@ -332,11 +333,8 @@
 		self.data_mut().stack.pop();
 		result
 	}
-	pub fn print_stack_trace(&self) {
-		for e in self.stack_trace().0 {
-			println!("{:?} - {:?}", e.0, e.1)
-		}
-	}
+
+	/// Returns current stack trace
 	pub fn stack_trace(&self) -> StackTrace {
 		StackTrace(
 			self.data()
@@ -348,10 +346,13 @@
 				.collect(),
 		)
 	}
+
+	/// Creates error with stack trace
 	pub fn error(&self, err: Error) -> LocError {
 		LocError(err, self.stack_trace())
 	}
 
+	/// Runs passed function in state (required, if function needs to modify stack trace)
 	pub fn run_in_state<T>(&self, f: impl FnOnce() -> T) -> T {
 		EVAL_STATE.with(|v| {
 			let has_state = v.borrow().is_some();
@@ -386,7 +387,6 @@
 						ExprLocation(Rc::new(PathBuf::from("test2.jsonnet")), 30, 40),
 						"inner".to_owned(),
 						|| {
-							state.print_stack_trace();
 							Ok(())
 						},
 					)?;