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