Skip to main content

qubit_fs/temp/
temp_options.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Temporary resource creation options.
9
10use crate::path::Path;
11
12/// Options shared by temporary file and temporary directory creation.
13///
14/// # Examples
15///
16/// ```rust
17/// use qubit_fs::temp::TempOptions;
18///
19/// assert_eq!(TempOptions::default(), TempOptions::new());
20/// ```
21#[non_exhaustive]
22#[derive(Clone, Debug, Eq, PartialEq)]
23pub struct TempOptions {
24    /// Parent directory or prefix for the temporary resource.
25    parent: Option<Path>,
26    /// Generated resource name prefix.
27    prefix: String,
28    /// Generated resource name suffix.
29    suffix: String,
30    /// Whether a missing parent directory is created.
31    create_parent: bool,
32}
33
34impl TempOptions {
35    /// Creates empty temporary-resource options without parent creation.
36    #[inline]
37    #[must_use]
38    pub fn new() -> Self {
39        Self {
40            parent: None,
41            prefix: String::new(),
42            suffix: String::new(),
43            create_parent: false,
44        }
45    }
46
47    /// Returns the requested temporary-resource location, if any.
48    #[inline]
49    pub const fn parent(&self) -> Option<&Path> {
50        self.parent.as_ref()
51    }
52
53    /// Returns the generated resource name prefix.
54    #[inline]
55    #[must_use]
56    pub fn prefix(&self) -> &str {
57        &self.prefix
58    }
59
60    /// Returns the generated resource name suffix.
61    #[inline]
62    #[must_use]
63    pub fn suffix(&self) -> &str {
64        &self.suffix
65    }
66
67    /// Returns whether missing parent directories are created.
68    #[inline]
69    #[must_use]
70    pub const fn creates_parent(&self) -> bool {
71        self.create_parent
72    }
73
74    /// Replaces the requested temporary-resource location.
75    ///
76    /// When set, the facade requires hierarchical temporary paths to be strict
77    /// descendants of this path and object-key paths to retain its raw prefix.
78    /// A provider may return an absolute logical path for a relative
79    /// hierarchical parent when the exact component prefix is preserved.
80    /// Provider-specific path semantics remain provider-defined. When `None`,
81    /// the provider selects the location.
82    ///
83    /// # Parameters
84    /// - `parent`: Requested temporary-resource parent, or `None` to let the
85    ///   provider choose the location.
86    #[inline]
87    #[must_use]
88    pub fn with_parent(mut self, parent: Option<Path>) -> Self {
89        self.parent = parent;
90        self
91    }
92
93    /// Replaces the generated resource name prefix.
94    ///
95    /// # Parameters
96    /// - `prefix`: Name prefix converted into an owned string.
97    #[inline]
98    #[must_use]
99    pub fn with_prefix(mut self, prefix: impl Into<String>) -> Self {
100        self.prefix = prefix.into();
101        self
102    }
103
104    /// Replaces the generated resource name suffix.
105    ///
106    /// # Parameters
107    /// - `suffix`: Name suffix converted into an owned string.
108    #[inline]
109    #[must_use]
110    pub fn with_suffix(mut self, suffix: impl Into<String>) -> Self {
111        self.suffix = suffix.into();
112        self
113    }
114
115    /// Replaces whether missing parent directories are created.
116    ///
117    /// # Parameters
118    /// - `create`: Whether the provider should create a missing parent.
119    #[inline]
120    #[must_use]
121    pub const fn with_create_parent(mut self, create: bool) -> Self {
122        self.create_parent = create;
123        self
124    }
125}
126
127impl Default for TempOptions {
128    /// Creates empty temporary-resource options without parent creation.
129    #[inline]
130    fn default() -> Self {
131        Self::new()
132    }
133}