Refactor the file device

The major feature of this refactor is the creation of BedrockFilePath,
a type which can be losslessly converted into an operating-system
specific path or a Bedrock-style byte path. It also prevents file paths
which can't be represented as Bedrock-style byte paths from being
constructed, and allows the use of a base directory which acts as an
inescapable sandbox.

BedrockFilePath will support the creation of a virtual root directory
on Windows which will allow navigation between drive letters via the
standard hierarchical navigation ports.

This commit has been tested on Linux, but not yet Windows. Further work
is expected before the new code will work on Windows.

7 files changed, 332 insertions, 181 deletions

diff --git a/src/devices/file/bedrock_file_path.rs b/src/devices/file/bedrock_file_path.rs
new file mode 100644
index 0000000..c169a62
--- /dev/null
+++ b/src/devices/file/bedrock_file_path.rs
@@ -0,0 +1,205 @@
+use super::*;
+
+use std::cmp::Ordering;
+use std::ffi::OsString;
+
+#[cfg(target_family = "unix")]
+use std::os::unix::ffi::OsStringExt;
+#[cfg(target_family = "windows")]
+use std::os::windows::ffi::OsStringExt;
+
+
+#[derive(Clone)]
+pub struct BedrockFilePath {
+    base: PathBuf,
+    relative: PathBuf,
+    bytes: Vec<u8>,
+}
+
+impl BedrockFilePath {
+    pub fn from_buffer(buffer: [u8; 256], base: &Path) -> Option<Self> {
+        let base = base.to_path_buf();
+        let relative = buffer_to_path(buffer)?;
+        let bytes = path_to_bytes(&relative)?;
+        assert_path_is_safe(&relative)?;
+        Some(Self { base, relative, bytes })
+    }
+
+    /// Construct an instance from an absolute path and a prefix of that path.
+    pub fn from_path(path: &Path, base: &Path) -> Option<Self> {
+        let base = base.to_path_buf();
+        let relative = path.strip_prefix(&base).ok()?.to_path_buf();
+        let bytes = path_to_bytes(&relative)?;
+        assert_path_is_safe(&relative)?;
+        Some( Self { base, relative, bytes } )
+    }
+
+    /// Get the base path used by this path.
+    pub fn base(&self) -> &Path {
+        &self.base
+    }
+
+    /// Get this path as a Bedrock-style path, which can be passed to
+    /// a Bedrock program.
+    pub fn as_bytes(&self) -> &[u8] {
+        &self.bytes
+    }
+
+    /// Get this path as a byte buffer, from which a CircularPathBuffer
+    /// can be populated.
+    pub fn as_buffer(&self) -> [u8; 256] {
+        let mut buffer: [u8; 256] = [0; 256];
+        buffer[..self.bytes.len()].copy_from_slice(&self.bytes);
+        return buffer;
+    }
+
+    /// Get this path as an absolute operating-system path, which can
+    /// be used to open a file or directory.
+    pub fn as_path(&self) -> PathBuf {
+        self.base.join(&self.relative)
+    }
+
+    /// Get a path which represents the parent of this path.
+    pub fn parent(&self) -> Option<Self> {
+        let relative = self.relative.parent()?.to_path_buf();
+        let base = self.base.clone();
+        let bytes = path_to_bytes(&relative)?;
+        Some( Self { base, relative, bytes } )
+    }
+
+    pub fn directory_listing(&self) -> Option<DirectoryListing> {
+        DirectoryListing::from_path(&self)
+    }
+
+    /// Returns true if a dot character directly follows the final
+    /// forward-slash character in the relative path.
+    pub fn filename_is_dot_prefixed(&self) -> bool {
+        let bytes = self.as_bytes();
+        let mut dot_i = 0;
+        for (i, b) in bytes.iter().enumerate() {
+            if *b == b'/' {
+                // Guaranteed to be a valid index, bytes is null-terminated.
+                dot_i = i + 1;
+            } else if *b == 0x00 {
+                break;
+            }
+        }
+        return bytes[dot_i] == b'.';
+    }
+}
+
+
+/// Converts the contents of a CircularPathBuffer to a relative path.
+fn buffer_to_path(bytes: [u8; 256]) -> Option<PathBuf> {
+    // The buffer must be non-empty and slash-prefixed.
+    if bytes[0] != ('/' as u8) {
+        return None;
+    }
+
+    // Find the index of the first null byte.
+    let mut null_i = None;
+    for (i, b) in bytes.iter().enumerate() {
+        if *b == 0x00 {
+            null_i = Some(i);
+            break;
+        }
+    }
+    // Take a slice, excluding the leading slash, up to the trailing null.
+    let slice = &bytes[1..null_i?];
+
+    #[cfg(target_family = "unix")] {
+        let vec = Vec::from(slice);
+        return Some(OsString::from_vec(vec).into())
+    }
+    #[cfg(target_family = "windows")] {
+        let string = String::from_utf8_lossy(slice);
+        let utf16: Vec<u16> = string.replace(r"/", r"\").encode_utf16().collect();
+        return Some(OsString::from_wide(&utf16).into())
+    }
+}
+
+/// Convert an operating system path to a Bedrock-style byte path.
+///
+/// A byte path contains at most 255 bytes, and is not null-terminated.
+fn path_to_bytes(path: &Path) -> Option<Vec<u8>> {
+    let mut string = String::from("/");
+    #[cfg(target_family = "unix")]
+    string.push_str(path.as_os_str().to_str()?);
+    #[cfg(target_family = "windows")]
+    string.push_str(&path.as_os_str().to_str()?.replace(r"\", r"/"));
+
+    // Remove all trailing forward-slash characters.
+    let slice = string.trim_end_matches('/').as_bytes();
+
+    // Error if bytes does not fit into a CircularPathBuffer.
+    if slice.len() > 255 { return None; }
+
+    Some(Vec::from(slice))
+}
+
+/// Returns true if a path contains only normal components.
+fn assert_path_is_safe(relative: &Path) -> Option<()> {
+    // Error if path contains special components.
+    for component in relative.components() {
+        match component {
+            Component::Normal(_) => continue,
+            _ => return None,
+        }
+    }
+    return Some(());
+}
+
+
+// ---------------------------------------------------------------------------
+
+impl PartialEq for BedrockFilePath {
+    fn eq(&self, other: &Self) -> bool {
+        self.bytes == other.bytes
+    }
+}
+
+impl Eq for BedrockFilePath {}
+
+impl PartialOrd for BedrockFilePath {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for BedrockFilePath {
+    fn cmp(&self, other: &Self) -> Ordering {
+        compare_ascii_slices(&self.bytes, &other.bytes)
+    }
+}
+
+// Compare two ASCII byte-slices in case-agnostic alphabetic order.
+fn compare_ascii_slices(left: &[u8], right: &[u8]) -> Ordering {
+    let l = std::cmp::min(left.len(), right.len());
+    let lhs = &left[..l];
+    let rhs = &right[..l];
+
+    for i in 0..l {
+        let a = remap_ascii(lhs[i]);
+        let b = remap_ascii(rhs[i]);
+        match a.cmp(&b) {
+            Ordering::Equal => (),
+            non_eq => return non_eq,
+        }
+    }
+
+    left.len().cmp(&right.len())
+}
+
+// Remap ASCII values so that they sort in case-agnostic alphabetic order:
+//    !"#$%&'()*+,-./0123456789:;<=>?
+//   @`AaBbCcDdEeFfGgHhIiJjKkLlMmNnOo
+//   PpQqRrSsTtUuVvWwXxYyZz[{\|]}^~_
+fn remap_ascii(c: u8) -> u8 {
+    if 0x40 <= c && c <= 0x5F {
+        (c - 0x40) * 2 + 0x40
+    } else if 0x60 <= c && c <= 0x7F {
+        (c - 0x60) * 2 + 0x41
+    } else {
+        c
+    }
+}
diff --git a/src/devices/file/buffered_file.rs b/src/devices/file/buffered_file.rs
index 04fefbd..73d3536 100644
--- a/src/devices/file/buffered_file.rs
+++ b/src/devices/file/buffered_file.rs
@@ -3,27 +3,6 @@ use std::io::{BufReader, BufWriter};
 use std::io::{Read, Write};
 use std::io::{ErrorKind, Seek, SeekFrom};
 
-enum AccessMode {
-    Read(BufReader<File>),
-    Write(BufWriter<File>),
-    None,
-}
-
-impl AccessMode {
-    pub fn unwrap(self) -> File {
-        match self {
-            Self::Read(reader) => reader.into_inner(),
-            Self::Write(writer) => writer.into_inner().unwrap(),
-            Self::None => unreachable!(),
-        }
-    }
-}
-
-impl Default for AccessMode {
-    fn default() -> Self {
-        Self::None
-    }
-}
 
 pub struct BufferedFile {
     file: AccessMode,
@@ -135,3 +114,26 @@ impl BufferedFile {
         };
     }
 }
+
+
+enum AccessMode {
+    Read(BufReader<File>),
+    Write(BufWriter<File>),
+    None,
+}
+
+impl AccessMode {
+    pub fn unwrap(self) -> File {
+        match self {
+            Self::Read(reader) => reader.into_inner(),
+            Self::Write(writer) => writer.into_inner().unwrap(),
+            Self::None => unreachable!(),
+        }
+    }
+}
+
+impl Default for AccessMode {
+    fn default() -> Self {
+        Self::None
+    }
+}
diff --git a/src/devices/file/circular_path_buffer.rs b/src/devices/file/circular_path_buffer.rs
index e5d903b..9d1dea6 100644
--- a/src/devices/file/circular_path_buffer.rs
+++ b/src/devices/file/circular_path_buffer.rs
@@ -1,5 +1,3 @@
-use super::*;
-
 pub struct CircularPathBuffer {
     buffer: [u8; 256],
     pointer: u8,
@@ -10,29 +8,29 @@ impl CircularPathBuffer {
         Self { buffer: [0; 256] , pointer: 0 }
     }
 
-    pub fn clear(&mut self) {
-        self.buffer.fill(0);
+    /// Clear the buffer, returning the previous buffer contents.
+    pub fn clear(&mut self) -> [u8; 256] {
         self.pointer = 0;
+        std::mem::replace(&mut self.buffer, [0; 256])
     }
 
-    pub fn populate(&mut self, bytes: &[u8]) {
-        self.clear();
-        if bytes.len() > 255 {
-            unreachable!(
-                "Attempted to populate CircularPathBuffer with {} bytes: {:?}",
-                bytes.len(), String::from_utf8_lossy(bytes)
-            )
-        }
-        let self_slice = &mut self.buffer[..bytes.len()];
-        self_slice.copy_from_slice(&bytes);
+    /// Reset the pointer and hot-swap the byte buffer.
+    pub fn populate(&mut self, buffer: [u8; 256]) {
+        self.pointer = 0;
+        self.buffer = buffer;
     }
 
+    /// Move internal pointer to either the start of the path or the file name.
+    ///
+    /// If value is non-zero, the pointer will be moved to the byte
+    /// directly following the final forward-slash.
     pub fn set_pointer(&mut self, value: u8) {
         self.pointer = 0;
+        // Set the pointer to the start of the filename if value is truthy.
         if value != 0x00 {
             for (i, c) in self.buffer.iter().enumerate() {
                 match c {
-                    b'/' => self.pointer = (i + 1) as u8,
+                    b'/' => self.pointer = (i as u8).saturating_add(1),
                     0x00 => break,
                     _ => continue,
                 }
@@ -40,23 +38,22 @@ impl CircularPathBuffer {
         }
     }
 
+    /// Read a single byte from the buffer.
     pub fn read_byte(&mut self) -> u8 {
         let pointer = self.pointer as usize;
         self.pointer = self.pointer.wrapping_add(1);
         self.buffer[pointer]
     }
 
-    // Returns an unsanitized relative path.
-    pub fn push_byte(&mut self, value: u8) -> Option<PathBuf> {
-        if value == 0x00 {
-            let pointer = self.pointer as usize;
-            let path = bytes_to_path(&self.buffer[..pointer]);
-            self.clear();
-            Some(path)
+    /// Write a single byte to the buffer.
+    ///
+    /// If a null-byte is written, the buffer will be cleared and returned.
+    pub fn push_byte(&mut self, byte: u8) -> Option<[u8; 256]> {
+        if byte == 0x00 {
+            Some(self.clear())
         } else {
-            let pointer = self.pointer as usize;
+            self.buffer[self.pointer as usize] = byte;
             self.pointer = self.pointer.wrapping_add(1);
-            self.buffer[pointer] = value;
             None
         }
     }
diff --git a/src/devices/file/directory_child.rs b/src/devices/file/directory_child.rs
new file mode 100644
index 0000000..376ec7d
--- /dev/null
+++ b/src/devices/file/directory_child.rs
@@ -0,0 +1,35 @@
+use super::*;
+
+use std::cmp::Ordering;
+
+
+pub struct DirectoryChild {
+    pub path: BedrockFilePath,
+    pub entry_type: EntryType,
+}
+
+
+// ---------------------------------------------------------------------------
+
+impl PartialEq for DirectoryChild {
+    fn eq(&self, other: &Self) -> bool {
+        self.entry_type == other.entry_type && self.path == other.path
+    }
+}
+
+impl Eq for DirectoryChild {}
+
+impl PartialOrd for DirectoryChild {
+    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+        Some(self.cmp(other))
+    }
+}
+
+impl Ord for DirectoryChild {
+    fn cmp(&self, other: &Self) -> Ordering {
+        match self.entry_type.cmp(&other.entry_type) {
+            Ordering::Equal => self.path.cmp(&other.path),
+            ordering => ordering,
+        }
+    }
+}
diff --git a/src/devices/file/directory_entry.rs b/src/devices/file/directory_entry.rs
deleted file mode 100644
index 7f0e69b..0000000
--- a/src/devices/file/directory_entry.rs
+++ /dev/null
@@ -1,57 +0,0 @@
-use super::*;
-
-use std::cmp::Ordering;
-
-#[derive(PartialEq, Eq)]
-pub struct DirectoryChild {
-    pub byte_path: Vec<u8>,
-    pub entry_type: EntryType,
-}
-
-impl PartialOrd for DirectoryChild {
-    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
-        Some(self.cmp(other))
-    }
-}
-
-impl Ord for DirectoryChild {
-    fn cmp(&self, other: &Self) -> Ordering {
-        match self.entry_type.cmp(&other.entry_type) {
-            Ordering::Equal =>
-                compare_ascii_arrays(&self.byte_path,&other.byte_path),
-            other => other,
-        }
-    }
-}
-
-// Compare two ASCII arrays in case-agnostic alphabetic order.
-fn compare_ascii_arrays(left: &[u8], right: &[u8]) -> Ordering {
-    let l = std::cmp::min(left.len(), right.len());
-    let lhs = &left[..l];
-    let rhs = &right[..l];
-
-    for i in 0..l {
-        let a = remap_ascii(lhs[i]);
-        let b = remap_ascii(rhs[i]);
-        match a.cmp(&b) {
-            Ordering::Equal => (),
-            non_eq => return non_eq,
-        }
-    }
-
-    left.len().cmp(&right.len())
-}
-
-// Remap ASCII values so that they sort in case-agnostic alphabetic order:
-//    !"#$%&'()*+,-./0123456789:;<=>?
-//   @`AaBbCcDdEeFfGgHhIiJjKkLlMmNnOo
-//   PpQqRrSsTtUuVvWwXxYyZz[{\|]}^~_
-fn remap_ascii(c: u8) -> u8 {
-    if 0x40 <= c && c <= 0x5F {
-        (c - 0x40) * 2 + 0x40
-    } else if 0x60 <= c && c <= 0x7F {
-        (c - 0x60) * 2 + 0x41
-    } else {
-        c
-    }
-}
diff --git a/src/devices/file/directory_listing.rs b/src/devices/file/directory_listing.rs
index 341f353..0cbbde9 100644
--- a/src/devices/file/directory_listing.rs
+++ b/src/devices/file/directory_listing.rs
@@ -1,5 +1,6 @@
 use super::*;
 
+
 pub struct DirectoryListing {
     children: Vec<DirectoryChild>,
     length: u32,
@@ -8,51 +9,50 @@ pub struct DirectoryListing {
 }
 
 impl DirectoryListing {
-    pub fn from_path(path: &Path, base: &Path) -> Result<Self, ()> {
-        macro_rules! continue_on_err {
+    pub fn from_path(path: &BedrockFilePath) -> Option<Self> {
+        macro_rules! unres {
             ($result:expr) => { match $result { Ok(v) => v, Err(_) => continue} };
         }
+        macro_rules! unopt {
+            ($option:expr) => { match $option { Some(v) => v, None => continue} };
+        }
 
         let mut children = Vec::new();
-        if let Ok(iter_dir) = std::fs::read_dir(path) {
-            for (i, entry_result) in iter_dir.enumerate() {
-                if i == u16::MAX as usize {
-                    eprintln!("Warning, {path:?} contains more than 65536 entries.")
-                };
-                let entry = continue_on_err!(entry_result);
-                let path = continue_on_err!(remove_base(&entry.path(), &base));
-                #[cfg(target_family = "unix")]
-                let byte_path = path.as_os_str().as_bytes();
-                #[cfg(target_family = "windows")]
-                let byte_path = path.as_os_str().as_encoded_bytes();
-                if byte_path.len() > 255 {
+        let dir_listing = std::fs::read_dir(path.as_path()).ok()?;
+        for (i, entry_result) in dir_listing.enumerate() {
+            // Firebreak to prevent emulator from consuming an absurd amount
+            // of memory when opening too large of a directory.
+            if i == (u16::MAX as usize) {
+                break;
+            }
+
+            let entry = unres!(entry_result);
+            let entry_path = unopt!(BedrockFilePath::from_path(&entry.path(), path.base()));
+            if entry_path.filename_is_dot_prefixed() {
+                continue;
+            }
+            let metadata = unres!(std::fs::metadata(&entry.path()));
+            let entry_type =
+                if metadata.is_file() {
+                    EntryType::File
+                } else if metadata.is_dir() {
+                    EntryType::Directory
+                } else {
                     continue;
                 };
-                if filename_dot_prefixed(&path) {
-                    continue;
-                }
-                let metadata = continue_on_err!(std::fs::metadata(&entry.path()));
-                children.push( DirectoryChild {
-                    byte_path: Vec::from(byte_path),
-                    entry_type: if metadata.is_file() {
-                        EntryType::File
-                    } else if metadata.is_dir() {
-                        EntryType::Directory
-                    } else {
-                        continue;
-                    },
-                } )
-            }
-            children.sort_unstable();
-            let length = u32::try_from(children.len()).unwrap_or(u32::MAX);
-            let selected = None;
-            let name_buffer = CircularPathBuffer::new();
-            Ok(Self { children, length, selected, name_buffer } )
-        } else {
-            Err(())
+
+            let child = DirectoryChild { path: entry_path, entry_type };
+            children.push(child);
         }
+
+        children.sort();
+        let length = u32::try_from(children.len()).ok()?;
+        let selected = None;
+        let name_buffer = CircularPathBuffer::new();
+        Some( Self { children, length, selected, name_buffer } )
     }
 
+    /// Attempts to return a directory child by index.
     pub fn get(&self, index: u32) -> Option<&DirectoryChild> {
         self.children.get(index as usize)
     }
@@ -61,13 +61,16 @@ impl DirectoryListing {
         self.length
     }
 
+    /// Returns the index of the selected child, or zero if no child is selected.
     pub fn selected(&self) -> u32 {
         self.selected.unwrap_or(0)
     }
 
+    /// Attempts to select a child by index.
     pub fn set_selected(&mut self, index: u32) {
-        if let Some(info) = self.get(index) {
-            self.name_buffer.populate(&info.byte_path.clone());
+        if let Some(child) = self.get(index) {
+            let buffer = child.path.as_buffer();
+            self.name_buffer.populate(buffer);
             self.selected = Some(index);
         } else {
             self.name_buffer.clear();
@@ -83,46 +86,8 @@ impl DirectoryListing {
         self.selected.and_then(|s| self.get(s).and_then(|i| Some(i.entry_type)))
     }
 
-    pub fn child_path(&self) -> Option<PathBuf> {
-        self.selected.and_then(|s| self.get(s).and_then(|i| {
-            Some(bytes_to_path(&i.byte_path))
-        }))
-    }
-}
-
-pub fn remove_base(absolute_path: &Path, base_path: &Path) -> Result<PathBuf, ()> {
-    if let Ok(relative) = absolute_path.strip_prefix(base_path) {
-        let mut baseless_path = PathBuf::from("/");
-        for component in relative.components() {
-            match component {
-                Component::Normal(s) => baseless_path.push(s),
-                Component::ParentDir => return Err(()),
-                Component::CurDir => continue,
-                Component::RootDir => continue,
-                Component::Prefix(_) => continue,
-            }
-        }
-        return Ok(baseless_path);
+    pub fn child_path(&self) -> Option<BedrockFilePath> {
+        self.selected.and_then(|s| self.get(s).and_then(|i| Some(i.path.clone())))
     }
-    return Err(());
 }
 
-// Returns true if a dot character directly follows the right-most
-// forward-slash character in the path.
-fn filename_dot_prefixed(path: &Path) -> bool {
-    #[cfg(target_family = "unix")]
-    let bytes = path.as_os_str().as_bytes();
-    #[cfg(target_family = "windows")]
-    let bytes = path.as_os_str().as_encoded_bytes();
-    // Find position of final forward-slash byte.
-    let mut final_slash = None;
-    for (i, byte) in bytes.iter().enumerate() {
-        if *byte == b'/' { final_slash = Some(i) }
-    }
-    if let Some(i) = final_slash {
-        if let Some(b'.') = bytes.get(i+1) {
-            return true;
-        }
-    }
-    return false;
-}
diff --git a/src/devices/file/operations.rs b/src/devices/file/operations.rs
index f33509b..0593ac8 100644
--- a/src/devices/file/operations.rs
+++ b/src/devices/file/operations.rs
@@ -1,11 +1,13 @@
 use std::io::ErrorKind;
 use std::path::Path;
 
+
+/// Returns true if an entry already exists at the given path.
 pub fn entry_exists(source: &Path) -> bool {
     std::fs::metadata(source).is_ok()
 }
 
-// Delete a file or folder, returning true if successful.
+/// Delete an entry, returning true if successful.
 pub fn delete_entry(source: &Path) -> bool {
     match std::fs::remove_file(source) {
         Ok(_) => true,
@@ -23,6 +25,7 @@ pub fn delete_entry(source: &Path) -> bool {
     }
 }
 
+/// Move an entry from one location to another, returning true if successful.
 pub fn move_entry(source: &Path, destination: &Path) -> bool {
     if !entry_exists(source) || entry_exists(destination) {
         return false;
@@ -30,6 +33,7 @@ pub fn move_entry(source: &Path, destination: &Path) -> bool {
     std::fs::rename(source, destination).is_ok()
 }
 
+/// Create a new file if it doesn't already exist, returning true if successful.
 pub fn create_file(destination: &Path) -> bool {
     if entry_exists(destination) {
         false