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}