qubit-fs 0.3.2

Provider-neutral synchronous and asynchronous filesystem abstraction for Rust
Documentation
// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Provider-neutral logical paths.

use std::fmt::Display;
use std::fmt::Formatter;
use std::fmt::Result as FmtResult;

use super::PathComponent;
use super::PathComponents;
use super::PathSemantics;
use super::RelativePath;
use crate::error::FsError;
use crate::error::FsOperation;
use crate::error::FsResult;

/// A validated logical path independent of any provider-native representation.
///
/// # Examples
/// ```rust
/// use qubit_fs::Path;
/// use qubit_fs::path::RelativePath;
/// let root = Path::parse("/reports")?;
/// let report = root.join(&RelativePath::parse("daily.csv")?);
/// assert_eq!("/reports/daily.csv", report.as_str());
/// assert!(report.is_absolute());
/// # Ok::<(), qubit_fs::FsError>(())
/// ```
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
pub struct Path {
    /// Whether this logical path starts at a provider root.
    absolute: bool,
    /// Canonical normalized or provider-literal text.
    text: String,
    /// Whether component iteration must preserve literal slash boundaries.
    literal: bool,
    /// Semantics used to validate this spelling.
    semantics: PathSemantics,
}

impl Path {
    /// Creates the canonical hierarchical root path.
    ///
    /// # Returns
    /// Returns the absolute hierarchical root path.
    #[inline]
    #[must_use]
    pub fn root() -> Self {
        Self {
            absolute: true,
            text: "/".to_owned(),
            literal: false,
            semantics: PathSemantics::Hierarchical,
        }
    }

    /// Constructs a hierarchical path from independently validated components.
    ///
    /// Each item is validated as one component without reparsing a joined path
    /// string. An empty absolute sequence produces the root; an empty relative
    /// sequence returns an invalid-path error.
    ///
    /// # Type Parameters
    /// - `I`: Iterator type yielding the component values.
    /// - `S`: Component value type borrowing string slices through `AsRef`.
    ///
    /// # Parameters
    /// - `absolute`: Whether the resulting path is rooted at the provider root.
    /// - `components`: Validated path-component text to join in order.
    ///
    /// # Returns
    /// Returns the validated path containing the joined components.
    ///
    /// # Errors
    /// Returns an invalid-path error when a component is empty, contains a
    /// separator or traversal marker, or when a relative sequence is empty.
    #[inline]
    pub fn from_components<I, S>(absolute: bool, components: I) -> FsResult<Self>
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        let components = components
            .into_iter()
            .map(|value| PathComponent::parse(value.as_ref()))
            .collect::<FsResult<Vec<_>>>()?;
        if !absolute && components.is_empty() {
            return Err(invalid_path());
        }
        let joined = components
            .iter()
            .map(PathComponent::as_str)
            .collect::<Vec<_>>()
            .join("/");
        Ok(Self {
            absolute,
            text: if absolute {
                if joined.is_empty() {
                    "/".to_owned()
                } else {
                    format!("/{joined}")
                }
            } else {
                joined
            },
            literal: false,
            semantics: PathSemantics::Hierarchical,
        })
    }

    /// Parses a hierarchical logical path using normalized semantics.
    ///
    /// Returns an invalid-path error for empty input, NUL, or root escape.
    ///
    /// # Errors
    /// Returns [`FsError`] with an invalid-path kind when `text` is empty,
    /// contains NUL, or escapes above the hierarchical root.
    ///
    /// # Parameters
    /// - `text`: Hierarchical path spelling to normalize and validate.
    ///
    /// # Returns
    /// Returns the normalized hierarchical path.
    #[inline]
    pub fn parse(text: &str) -> FsResult<Self> {
        Self::parse_with_semantics(text, PathSemantics::Hierarchical)
    }

    /// Parses a provider-literal path without interpreting separators or dots.
    ///
    /// Returns an invalid-path error for empty input or NUL.
    ///
    /// # Errors
    /// Returns [`FsError`] with an invalid-path kind when `text` is empty or
    /// contains NUL.
    ///
    /// # Parameters
    /// - `text`: Provider-literal path spelling to retain and validate.
    ///
    /// # Returns
    /// Returns the provider-literal path preserving `text`.
    #[inline]
    pub fn parse_literal(text: &str) -> FsResult<Self> {
        Self::parse_with_semantics(text, PathSemantics::ObjectKey)
    }

    /// Parses `text` according to explicitly selected provider semantics.
    ///
    /// Hierarchical values normalize empty and dot components and reject root
    /// escapes. Object-key and provider-specific values preserve their text.
    ///
    /// # Parameters
    /// - `text`: Provider path text to validate and normalize.
    /// - `semantics`: Path semantics controlling normalization and root rules.
    ///
    /// # Errors
    /// Returns an invalid-path error when `text` is empty, contains NUL, or
    /// escapes above the hierarchical root.
    ///
    /// # Returns
    /// Returns the path using the selected provider semantics.
    pub fn parse_with_semantics(text: &str, semantics: PathSemantics) -> FsResult<Self> {
        if text.is_empty() || text.contains('\0') {
            return Err(invalid_path());
        }
        if semantics != PathSemantics::Hierarchical {
            return Ok(Self {
                absolute: text.starts_with('/'),
                text: text.to_owned(),
                literal: true,
                semantics,
            });
        }
        let absolute = text.starts_with('/');
        let mut components = Vec::new();
        for component in text.split('/') {
            match component {
                "" | "." => {}
                ".." => {
                    if components.pop().is_none() {
                        return Err(invalid_path());
                    }
                }
                value => components.push(value),
            }
        }
        let text = if absolute {
            if components.is_empty() {
                "/".to_owned()
            } else {
                format!("/{}", components.join("/"))
            }
        } else {
            components.join("/")
        };
        if text.is_empty() {
            return Err(invalid_path());
        }
        Ok(Self {
            absolute,
            text,
            literal: false,
            semantics,
        })
    }

    /// Returns the validated logical path text.
    ///
    /// # Returns
    /// Returns the canonical or provider-literal spelling borrowed from this
    /// path.
    #[inline]
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.text
    }

    /// Returns the final non-empty path component, when one is present.
    ///
    /// A root path and a literal path ending in a separator have no file
    /// name. Hierarchical paths are canonicalized during parsing, so their
    /// final component is always non-empty.
    ///
    /// # Returns
    /// `Some` with the final non-empty component, or `None` for a root or a
    /// literal path ending in a separator.
    #[inline]
    pub fn file_name(&self) -> Option<&str> {
        if self.text == "/" || (self.literal && self.text.ends_with('/')) {
            return None;
        }
        self.text.rsplit('/').find(|component| !component.is_empty())
    }

    /// Returns whether this path is absolute.
    ///
    /// # Returns
    /// Returns `true` when this path starts at a provider root.
    #[inline]
    #[must_use]
    pub const fn is_absolute(&self) -> bool {
        self.absolute
    }

    /// Returns the semantics used to validate this logical path.
    ///
    /// # Returns
    /// Returns the semantics selected when this path was parsed or constructed.
    #[inline]
    #[must_use]
    pub const fn semantics(&self) -> PathSemantics {
        self.semantics
    }

    /// Iterates lexical component boundaries without using an empty root value.
    ///
    /// # Returns
    /// Returns an iterator over lexical components; literal paths preserve
    /// empty components between separators.
    #[inline]
    #[must_use]
    pub fn components(&self) -> PathComponents<'_> {
        PathComponents::new(&self.text, self.absolute, self.literal)
    }

    /// Appends one validated component without re-parsing provider text.
    ///
    /// # Parameters
    /// - `component`: Validated component to append.
    ///
    /// # Returns
    /// Returns a new path with `component` appended.
    #[inline]
    #[must_use]
    pub fn child(&self, component: &PathComponent) -> Self {
        self.append(component.as_str())
    }

    /// Appends a safe normalized relative path without re-parsing provider
    /// text.
    ///
    /// # Parameters
    /// - `relative`: Validated relative path to append.
    ///
    /// # Returns
    /// Returns a new path with `relative` appended.
    #[inline]
    #[must_use]
    pub fn join(&self, relative: &RelativePath) -> Self {
        self.append(relative.as_str())
    }

    /// Joins an already validated suffix to this path.
    ///
    /// # Parameters
    /// - `suffix`: Validated suffix text to append after a separator.
    fn append(&self, suffix: &str) -> Self {
        let hierarchical_root = self.semantics == PathSemantics::Hierarchical && !self.literal && self.text == "/";
        let text = if hierarchical_root {
            format!("/{suffix}")
        } else {
            format!("{}/{}", self.text, suffix)
        };
        Self {
            absolute: self.absolute,
            text,
            literal: self.literal,
            semantics: self.semantics,
        }
    }
}

impl Display for Path {
    /// Formats the validated logical spelling.
    ///
    /// # Parameters
    /// - `formatter`: Destination for the path spelling.
    #[inline]
    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
        formatter.write_str(self.as_str())
    }
}

impl AsRef<str> for Path {
    /// Returns the logical path text for generic text consumers.
    #[inline]
    fn as_ref(&self) -> &str {
        self.as_str()
    }
}

/// Builds the shared logical path validation failure.
fn invalid_path() -> FsError {
    FsError::invalid_path(
        FsOperation::ParsePath,
        "path must be non-empty, NUL-free, and remain within its root",
    )
}