fs/path: documentation and visibility adjustments

Author: phip1611

uefi/src/fs/file_system.rs

@@ -1,7 +1,7 @@
 //! Module for [`FileSystem`].
 
 use super::*;
-use crate::fs::path::validation::{validate_path, PathError};
+use crate::fs::path::{validate_path, PathError};
 use crate::proto::media::file::{FileAttribute, FileInfo, FileType};
 use crate::table::boot::ScopedProtocol;
 use alloc::boxed::Box;
@@ -21,7 +21,7 @@ pub enum FileSystemError {
     CantOpenVolume,
     /// The path is invalid because of the underlying [`PathError`].
     ///
-    /// [`PathError`]: path::validation::PathError
+    /// [`PathError`]: path::PathError
     IllegalPath(PathError),
     /// The file or directory was not found in the underlying volume.
     FileNotFound(String),

uefi/src/fs/mod.rs

@@ -1,14 +1,14 @@
-//! A high-level file system API for UEFI applications close to the `fs` module
-//! from Rust's standard library.
+//! A high-level file system API for UEFI applications close to the `std::fs`
+//! module from Rust's standard library. The main type by this module is
+//! [`FileSystem`].
 //!
 //! # Difference to typical File System Abstractions
 //! Users perform actions on dedicated volumes: For example, the boot volume,
 //! such as a CD-rom, USB-stick, or any other storage device.
 //!
 //! Unlike in the API of typical UNIX file system abstractions, there is
-//! no virtual file system.
-//!
-//! Unlike Windows, there is no way to access volumes by a dedicated name.
+//! no virtual file system. Unlike in Windows, there is no way to access volumes
+//! by a dedicated name.
 //!
 //! # Paths
 //! All paths are absolute and follow the FAT-like file system conventions for
@@ -17,7 +17,8 @@
 //! directory is always `/`, i.e., the root, of the opened volume.
 //!
 //! Symlinks or hard-links are not supported but only directories and regular
-//! files with plain linear paths to them.
+//! files with plain linear paths to them. For more information, see
+//! [`Path`] and [`PathBuf`].
 //!
 //! # API Hints
 //! There are no `File` and `Path` abstractions similar to those from `std` that

uefi/src/fs/path/mod.rs

@@ -15,12 +15,14 @@
 
 mod path;
 mod pathbuf;
-pub mod validation;
+mod validation;
 
 pub use path::Path;
 pub use pathbuf::PathBuf;
 
 use uefi::{CStr16, Char16};
+pub(super) use validation::validate_path;
+pub use validation::PathError;
 
 /// The default separator for paths.
 pub const SEPARATOR: char = '\\';
@@ -32,5 +34,20 @@ pub const SEPARATOR_STR: &str = "\\";
 /// [`SEPARATOR_STR`] but as useful UEFI type.
 pub const SEPARATOR_CSTR16: &CStr16 = uefi_macros::cstr16!("\\");
 
-/// Denied characters in a path component.
-pub const CHARACTER_DENY_LIST: [char; 10] = ['\0', '"', '*', '/', ':', '<', '>', '?', '\\', '|'];
+/// Deny list of characters for path components. UEFI supports FAT-like file
+/// systems. According to <https://en.wikipedia.org/wiki/Comparison_of_file_systems>,
+/// paths should not contain the following symbols.
+pub const CHARACTER_DENY_LIST: [Char16; 10] = unsafe {
+    [
+        Char16::from_u16_unchecked('\0' as u16),
+        Char16::from_u16_unchecked('"' as u16),
+        Char16::from_u16_unchecked('*' as u16),
+        Char16::from_u16_unchecked('/' as u16),
+        Char16::from_u16_unchecked(':' as u16),
+        Char16::from_u16_unchecked('<' as u16),
+        Char16::from_u16_unchecked('>' as u16),
+        Char16::from_u16_unchecked('?' as u16),
+        Char16::from_u16_unchecked('\\' as u16),
+        Char16::from_u16_unchecked('|' as u16),
+    ]
+};

uefi/src/fs/path/validation.rs

@@ -6,27 +6,10 @@
 //! [`fs`]: crate::fs
 
 use super::Path;
+use crate::fs::CHARACTER_DENY_LIST;
 use crate::Char16;
 use derive_more::Display;
 
-/// Deny list of characters for path components. UEFI supports FAT-like file
-/// systems. According to <https://en.wikipedia.org/wiki/Comparison_of_file_systems>,
-/// paths should not contain the following symbols.
-pub const CHARACTER_DENY_LIST: [Char16; 10] = unsafe {
-    [
-        Char16::from_u16_unchecked('\0' as u16),
-        Char16::from_u16_unchecked('"' as u16),
-        Char16::from_u16_unchecked('*' as u16),
-        Char16::from_u16_unchecked('/' as u16),
-        Char16::from_u16_unchecked(':' as u16),
-        Char16::from_u16_unchecked('<' as u16),
-        Char16::from_u16_unchecked('>' as u16),
-        Char16::from_u16_unchecked('?' as u16),
-        Char16::from_u16_unchecked('\\' as u16),
-        Char16::from_u16_unchecked('|' as u16),
-    ]
-};
-
 /// Errors related to file paths.
 #[derive(Debug, Clone, Eq, PartialEq, Display)]
 pub enum PathError {
@@ -73,21 +56,12 @@ mod tests {
 
     #[test]
     fn test_validate_path() {
-        let source: &CStr16 = cstr16!("hello\\foo\\bar");
-        let path: &Path = source.into();
-        // TODO why can't I just pass in a &Path ?!
-        validate_path(path.as_ref()).unwrap();
+        validate_path(cstr16!("hello\\foo\\bar")).unwrap();
 
-        let source: &CStr16 = cstr16!("hello\\f>oo\\bar");
-        let path: &Path = source.into();
-        // TODO why can't I just pass in a &Path ?!
-        let err = validate_path(path.as_ref()).unwrap_err();
+        let err = validate_path(cstr16!("hello\\f>oo\\bar")).unwrap_err();
         assert_eq!(err, PathError::IllegalChar(CHARACTER_DENY_LIST[6]));
 
-        let source: &CStr16 = cstr16!("hello\\\\bar");
-        let path: &Path = source.into();
-        // TODO why can't I just pass in a &Path ?!
-        let err = validate_path(path.as_ref()).unwrap_err();
+        let err = validate_path(cstr16!("hello\\\\bar")).unwrap_err();
         assert_eq!(err, PathError::EmptyComponent);
 
         let empty_cstring16 = CString16::try_from("").unwrap();