Struct VaultPath 

pub struct VaultPath { /* private fields */ }

A logical, vault-internal path to a note or directory.

VaultPath is the core’s single currency for everything inside a vault: it never refers to a location outside the workspace, and it is portable across Windows, macOS, and Linux. Components are sanitized and lowercased on construction (see VaultPath::new) so that only characters valid on all three filesystems survive and equality is effectively case-insensitive. The separator is always PATH_SEPARATOR (/); translation to native OS paths happens only at the filesystem boundary in nfs.

A path may be absolute (rooted at the vault root, rendered with a leading /) or relative, and may contain ./.. components until flattened.

Implementations

impl VaultPath

pub fn new<S: AsRef<str>>(path: S) -> Self

Creates a new vault path, for every invalid character it gets replaced to an underscore _. If you want to validate the path first, either use the VaultPath::From trait or use VaultPath::is_valid()

pub fn is_valid<S: AsRef<str>>(path: S) -> bool

Returns true if path is already a clean vault path needing no sanitization: every component is valid on all three target filesystems and there are no doubled separators. Use this to validate caller-supplied strings up front; VaultPath::new will instead silently repair them.

use kimun_core::nfs::VaultPath;
assert!(VaultPath::is_valid("/projects/notes.md"));
assert!(!VaultPath::is_valid("bad?name"));

pub fn note_path_from<S: AsRef<str>>(path: S) -> Self

Builds a sanitized note path from path, ensuring it ends with the note extension. A trailing separator is dropped before the extension is added, so notes/ becomes notes.md. Unlike with_note_extension, the rest of the string is sanitized through VaultPath::new, so this is the correct constructor for real note paths (not search patterns).

use kimun_core::nfs::VaultPath;
assert_eq!(VaultPath::note_path_from("projects/todo").to_string(), "projects/todo.md");
assert_eq!(VaultPath::note_path_from("readme.md").to_string(), "readme.md");

pub fn root() -> Self

The vault root: an absolute path with no components, rendered as /.

use kimun_core::nfs::VaultPath;
assert_eq!(VaultPath::root().to_string(), "/");

pub fn empty() -> Self

The empty relative path: no components and not absolute, rendered as the empty string. Distinct from root, which is absolute.

use kimun_core::nfs::VaultPath;
assert_eq!(VaultPath::empty().to_string(), "");

pub fn is_root_or_empty(&self) -> bool

Returns true when the path has no components, i.e. it is either the vault root or the empty path.

pub fn get_name_on_conflict(&self) -> VaultPath

Returns a variant of this path with its final component’s name incremented to avoid a collision. A numeric _N suffix is added or bumped (e.g. note.md → note_0.md, note_0.md → note_1.md), preserving the note extension. Used to pick a fresh name when the desired one is taken.

pub fn get_clean_name(&self) -> String

Returns the final component’s name with the note extension stripped — the note’s display title as derived from its filename. For directories (no extension) this is just the directory name. Compare get_name, which keeps the extension.

use kimun_core::nfs::VaultPath;
assert_eq!(VaultPath::new("/projects/todo.md").get_clean_name(), "todo");

pub fn to_bare_string(&self) -> String

Returns the full vault path as a string with the note extension stripped. E.g. /projects/rust-notes.md → /projects/rust-notes If the path does not end with the note extension, returns it unchanged.

pub fn to_string_with_ext(&self) -> String

Returns the full vault path as a string, ensuring it ends with the note extension. E.g. /projects/rust-notes → /projects/rust-notes.md If the path already ends with the extension, returns it unchanged.

pub fn get_slices(&self) -> Vec<String>

Returns the path’s components as plain strings, after flattening (so no ./.. entries remain). Useful for walking the path level by level.

use kimun_core::nfs::VaultPath;
assert_eq!(VaultPath::new("/a/b/c.md").get_slices(), vec!["a", "b", "c.md"]);

pub fn to_pathbuf<P: AsRef<Path>>(&self, workspace_path: P) -> PathBuf

Joins this path onto workspace_path to produce the canonical on-disk PathBuf, mapping / to native separators and flattening first.

This is the canonical (lowercase) location only; it does not perform case-insensitive resolution, so an existing file stored under a different case will not be found. Use the nfs resolver for that.

pub fn flatten(&self) -> VaultPath

Returns a full path without any relative slices If it tries to go up beyond the current path, drops a warning

pub fn get_name(&self) -> String

Returns the last part of the path slices if it is a note, will return the note filename, if it is a directory, will return the directory name

pub fn relative_link_from_note(&self, note_path: &VaultPath) -> VaultPath

Returns the path of self written relative to a note file’s directory.

Markdown engines resolve relative links against the containing folder, not the note file itself. Linking from /notes/journal/today.md to /assets/img.png therefore produces ../../assets/img.png (two ..s — for journal/ and notes/), not three. This wraps Self::get_relative_to using the note’s parent path so callers get the markdown-correct result.

pub fn resolve_link_in_note(&self, note_path: &VaultPath) -> VaultPath

Resolve self as a link target written inside note_path.

Inverse of Self::relative_link_from_note: markdown links resolve against the directory containing the note, so a ../work/anton.md target in /journal/today.md resolves to /work/anton.md (flattened, absolute). Absolute targets are returned flattened as-is. A bare filename with no directory part (e.g. anton.md) is returned unchanged so callers can fall back to a vault-wide name lookup (wiki-style links).

pub fn get_relative_to(&self, reference_path: &VaultPath) -> VaultPath

Expresses this path relative to reference_path, walking up with .. for each component of the reference not shared with this path, then down into this path’s remaining components. The result is always relative.

Note reference_path is treated as a directory: every one of its trailing components becomes a ... To build a markdown link relative to a note file, use relative_link_from_note, which accounts for the note’s own filename.

use kimun_core::nfs::VaultPath;
let from = VaultPath::new("/main/path/first");
let target = VaultPath::new("/main/second");
assert_eq!(target.get_relative_to(&from).to_string(), "../../second");

pub fn from_path<P: AsRef<Path>, F: AsRef<Path>>( workspace_path: P, full_path: F, ) -> Result<Self, FSError>

Converts a real on-disk path back into an absolute vault path by stripping the workspace_path prefix. Returns FSError::InvalidPath if full_path does not live inside the workspace. Each OS component is run through VaultPath::new, so the result is sanitized and lowercased.

pub fn is_note_file(&self) -> bool

Returns true if this path is a bare note filename: a single, relative component ending in the note extension, with no directory part (e.g. anton.md). Such paths are the signal for a vault-wide, wiki-style name lookup rather than a directory-scoped path match.

use kimun_core::nfs::VaultPath;
assert!(VaultPath::new("anton.md").is_note_file());
assert!(!VaultPath::new("/work/anton.md").is_note_file());

pub fn is_note(&self) -> bool

Returns true if this path points at a note, i.e. its final component ends with the note extension. Unlike is_note_file, the path may have any number of directory components.

pub fn ensure_note(&self) -> Result<(), FSError>

Returns Ok if the path looks like a note path; otherwise an InvalidPath error.

pub fn ensure_directory(&self) -> Result<(), FSError>

Returns Ok if the path does not have a note extension; otherwise an InvalidPath error.

pub fn is_relative(&self) -> bool

Returns true if this path is relative (not rooted at the vault root).

pub fn is_absolute(&self) -> bool

Returns true if this path is absolute (rooted at the vault root).

pub fn to_absolute(&mut self)

Marks this path absolute in place.

pub fn absolute(self) -> Self

Consumes the path and returns it marked absolute (builder-style sibling of to_absolute).

pub fn to_relative(&mut self)

Marks this path relative in place.

pub fn get_parent_path(&self) -> (VaultPath, String)

Splits the path into its parent path and the final component’s name. The parent keeps this path’s absoluteness; the name is the empty string when the path has no components.

use kimun_core::nfs::VaultPath;
let (parent, name) = VaultPath::new("/a/b/c.md").get_parent_path();
assert_eq!(parent.to_string(), "/a/b");
assert_eq!(name, "c.md");

pub fn append(&self, path: &VaultPath) -> VaultPath

Appends path to this one. If path is absolute it wins outright and is returned as-is; otherwise its components are concatenated onto this path, keeping this path’s absoluteness. The result is not flattened, so any .. in path survives until flatten is called.

use kimun_core::nfs::VaultPath;
let base = VaultPath::new("/main/path");
let rel = VaultPath::new("sub/note.md");
assert_eq!(base.append(&rel).to_string(), "/main/path/sub/note.md");

pub fn is_like(&self, other: &VaultPath) -> bool

Compares two paths by components only, ignoring whether each is absolute or relative. So /a/b is “like” a/b.

use kimun_core::nfs::VaultPath;
assert!(VaultPath::new("/a/b").is_like(&VaultPath::new("a/b")));

Trait Implementations

impl Clone for VaultPath

fn clone(&self) -> VaultPath

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VaultPath

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for VaultPath

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for VaultPath

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for VaultPath

impl From<&VaultPath> for VaultPath

fn from(value: &VaultPath) -> Self

Converts to this type from the input type.

impl FromStr for VaultPath

type Err = FSError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for VaultPath

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for VaultPath

fn cmp(&self, other: &VaultPath) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for VaultPath

fn eq(&self, other: &VaultPath) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for VaultPath

fn partial_cmp(&self, other: &VaultPath) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for VaultPath

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for VaultPath

impl TryFrom<&String> for VaultPath

type Error = FSError

The type returned in the event of a conversion error.

fn try_from(value: &String) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&str> for VaultPath

type Error = FSError

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<String> for VaultPath

type Error = FSError

The type returned in the event of a conversion error.

fn try_from(value: String) -> Result<Self, Self::Error>

Performs the conversion.