qubit-fs 0.3.3

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

use crate::metadata::NonSensitiveMetadata;
use crate::metadata::UserMetadata;

/// Options controlling directory or collection creation.
///
/// # Examples
///
/// ```rust
/// use qubit_fs::directory::CreateDirectoryOptions;
///
/// assert!(!CreateDirectoryOptions::default().recursive());
/// ```
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq)]
pub struct CreateDirectoryOptions {
    /// Whether missing parent directories should be created.
    recursive: bool,
    /// Whether an existing directory should be accepted.
    exists_ok: bool,
    /// User-defined metadata with validated non-sensitive structural keys.
    user_metadata: NonSensitiveMetadata,
}

impl Default for CreateDirectoryOptions {
    /// Creates non-recursive options that reject an existing directory.
    ///
    /// # Returns
    /// Options with recursive creation and acceptance of an existing
    /// directory disabled, and with no user metadata.
    #[inline]
    fn default() -> Self {
        Self {
            recursive: false,
            exists_ok: false,
            user_metadata: NonSensitiveMetadata::new(),
        }
    }
}

impl CreateDirectoryOptions {
    /// Returns whether missing parent directories should be created.
    ///
    /// # Returns
    /// `true` when missing parent directories should be created.
    #[inline]
    #[must_use]
    pub const fn recursive(&self) -> bool {
        self.recursive
    }

    /// Returns whether an existing directory should be accepted.
    ///
    /// # Returns
    /// `true` when creating a directory that already exists is allowed.
    #[inline]
    #[must_use]
    pub const fn exists_ok(&self) -> bool {
        self.exists_ok
    }

    /// Returns validated user-defined metadata.
    ///
    /// # Returns
    /// The metadata associated with these creation options.
    #[inline]
    #[must_use]
    pub const fn user_metadata(&self) -> &NonSensitiveMetadata {
        &self.user_metadata
    }

    /// Replaces recursive parent creation.
    ///
    /// # Parameters
    /// `recursive` enables creation of missing parent directories when `true`.
    ///
    /// # Returns
    /// These options with recursive parent creation set to `recursive`.
    #[inline]
    #[must_use]
    pub const fn with_recursive(mut self, recursive: bool) -> Self {
        self.recursive = recursive;
        self
    }

    /// Replaces acceptance of an existing directory.
    ///
    /// # Parameters
    /// `exists_ok` enables accepting an already existing directory when `true`.
    ///
    /// # Returns
    /// These options with existing-directory acceptance set to `exists_ok`.
    #[inline]
    #[must_use]
    pub const fn with_exists_ok(mut self, exists_ok: bool) -> Self {
        self.exists_ok = exists_ok;
        self
    }

    /// Replaces user-defined metadata that has already passed key validation.
    ///
    /// # Parameters
    /// `metadata` is the validated metadata to associate with these options.
    ///
    /// # Returns
    /// These options with `metadata` wrapped as non-sensitive metadata.
    #[inline]
    #[must_use]
    pub fn with_user_metadata(mut self, metadata: UserMetadata) -> Self {
        self.user_metadata = NonSensitiveMetadata::from(metadata);
        self
    }
}