diff options
Diffstat (limited to 'subplotlib/src/steplibrary/datadir.rs')
| -rw-r--r-- | subplotlib/src/steplibrary/datadir.rs | 21 |
1 files changed, 21 insertions, 0 deletions
diff --git a/subplotlib/src/steplibrary/datadir.rs b/subplotlib/src/steplibrary/datadir.rs index 88e6375..91f5603 100644 --- a/subplotlib/src/steplibrary/datadir.rs +++ b/subplotlib/src/steplibrary/datadir.rs @@ -10,6 +10,14 @@ use std::path::{Component, Path, PathBuf}; pub use crate::prelude::*; +/// The `Datadir` is the context type which provides a directory for each scenario +/// and allows for the creation and testing of files within that directory. +/// +/// A few steps are provided as part of this step library, though in reality the +/// majority of steps which interact with the data directory are in the +/// [files][`crate::steplibrary::files`] step library, and commands which interact +/// with stuff in here are in the [runcmd][`crate::steplibrary::runcmd`] step library. +/// #[derive(Default)] pub struct Datadir { inner: Option<DatadirInner>, @@ -57,11 +65,16 @@ impl Datadir { /// Retrieve the base data directory path which can be used to store /// files etc. for this step. + /// + /// This is used by steps wishing to manipulate the content of the data directory. pub fn base_path(&self) -> &Path { self.inner().base.path() } /// Canonicalise a subpath into this dir + /// + /// This step **safely** joins the base path to the given subpath. This ensures that, + /// for example, the subpath is relative, does not contain `..` elements, etc. #[throws(StepError)] pub fn canonicalise_filename<S: AsRef<Path>>(&self, subpath: S) -> PathBuf { let mut ret = self.base_path().to_path_buf(); @@ -81,6 +94,8 @@ impl Datadir { } /// Open a file for writing + /// + /// This is a convenience function to open a file for writing at the given subpath. #[throws(StepError)] pub fn open_write<S: AsRef<Path>>(&self, subpath: S) -> File { let full_path = self.canonicalise_filename(subpath)?; @@ -92,6 +107,8 @@ impl Datadir { } /// Open a file for reading + /// + /// This is a convenience function to open a file for reading from the given subpath #[throws(StepError)] pub fn open_read<S: AsRef<Path>>(&self, subpath: S) -> File { let full_path = self.canonicalise_filename(subpath)?; @@ -102,6 +119,10 @@ impl Datadir { .open(full_path)? } + /// Make a directory tree + /// + /// Equivalent to `mkdir -p` this will create the full path to the given subpath + /// allowing subsequent step code to use that directory. #[throws(StepError)] pub fn create_dir_all<S: AsRef<Path>>(&self, subpath: S) { let full_path = self.canonicalise_filename(subpath)?; |