`c03b8a8`

core: add xbel parser for xdg recently-used files

Authored by mfwolffe <wolffemf@dukes.jmu.edu> 3 months ago

SHA: c03b8a8ef3d465ca701e852fe40a799ecd303945
Parents: bcc8d49
Tree: 273808e

1 changed file

Status	File	+	-
A	`garfield/src/core/recents.rs`	307	0

garfield/src/core/recents.rsadded

 +//! XDG Recently Used files manager.
 +//!
 +//! Parses and manages `~/.local/share/recently-used.xbel` (XBEL format).
 +//! This provides system-wide recently accessed files from any application.
++
 +use std::fs;
 +use std::io::BufReader;
 +use std::path::{Path, PathBuf};
 +use std::time::SystemTime;
++
 +use quick_xml::events::{BytesStart, Event};
 +use quick_xml::Reader;
 +use thiserror::Error;
++
 +/// Maximum number of recent entries to track.
 +const MAX_ENTRIES: usize = 25;
++
 +/// Errors from recents operations.
 +#[derive(Debug, Error)]
 +pub enum RecentsError {
 +    #[error("Failed to read xbel file: {0}")]
 +    Io(#[from] std::io::Error),
 +    #[error("XML parse error: {0}")]
 +    Xml(#[from] quick_xml::Error),
 +    #[error("Invalid timestamp format")]
 +    InvalidTimestamp,
 +}
++
 +/// A recently accessed file from the XDG recently-used.xbel file.
 +#[derive(Debug, Clone)]
 +pub struct RecentEntry {
 +    /// File path (decoded from file:// URI).
 +    pub path: PathBuf,
 +    /// MIME type (e.g., "image/png", "inode/directory").
 +    pub mime_type: Option<String>,
 +    /// Last visit timestamp.
 +    pub visited: SystemTime,
 +    /// Last modification timestamp.
 +    pub modified: SystemTime,
 +}
++
 +impl RecentEntry {
 +    /// Returns true if this entry is a directory.
 +    pub fn is_directory(&self) -> bool {
 +        self.mime_type
 +            .as_ref()
 +            .is_some_and(|m| m == "inode/directory")
 +    }
++
 +    /// Returns the file name.
 +    pub fn file_name(&self) -> Option<&str> {
 +        self.path.file_name().and_then(|n| n.to_str())
 +    }
++
 +    /// Returns the parent directory.
 +    pub fn parent_dir(&self) -> Option<&Path> {
 +        self.path.parent()
 +    }
 +}
++
 +/// Manager for XDG recently-used files.
 +pub struct RecentsManager {
 +    /// Path to recently-used.xbel file.
 +    xbel_path: PathBuf,
 +    /// Cached entries (sorted by visited time, most recent first).
 +    entries: Vec<RecentEntry>,
 +    /// Maximum entries to display.
 +    max_entries: usize,
 +}
++
 +impl RecentsManager {
 +    /// Create a new RecentsManager with default path.
 +    pub fn new() -> Self {
 +        let xbel_path = dirs::data_local_dir()
 +            .unwrap_or_else(|| PathBuf::from("~/.local/share"))
 +            .join("recently-used.xbel");
++
 +        Self {
 +            xbel_path,
 +            entries: Vec::new(),
 +            max_entries: MAX_ENTRIES,
 +        }
 +    }
++
 +    /// Load/refresh entries from ~/.local/share/recently-used.xbel
 +    pub fn load(&mut self) -> Result<(), RecentsError> {
 +        self.entries.clear();
++
 +        if !self.xbel_path.exists() {
 +            return Ok(());
 +        }
++
 +        let file = fs::File::open(&self.xbel_path)?;
 +        let reader = BufReader::new(file);
 +        let mut xml = Reader::from_reader(reader);
 +        xml.config_mut().trim_text(true);
++
 +        let mut buf = Vec::new();
 +        let mut current_bookmark: Option<PartialBookmark> = None;
 +        let mut in_metadata = false;
++
 +        loop {
 +            match xml.read_event_into(&mut buf) {
 +                Ok(Event::Start(ref e)) | Ok(Event::Empty(ref e)) => {
 +                    match e.name().as_ref() {
 +                        b"bookmark" => {
 +                            current_bookmark = Some(parse_bookmark_attrs(e));
 +                        }
 +                        b"mime:mime-type" if current_bookmark.is_some() && in_metadata => {
 +                            if let Some(ref mut bm) = current_bookmark {
 +                                bm.mime_type = get_attr(e, b"type");
 +                            }
 +                        }
 +                        b"metadata" => {
 +                            in_metadata = true;
 +                        }
 +                        _ => {}
 +                    }
++
 +                    // Handle empty elements (self-closing tags)
 +                    if matches!(xml.read_event_into(&mut buf), Ok(Event::End(_))) {
 +                        // This was actually a start tag, not empty
 +                    }
 +                }
 +                Ok(Event::End(ref e)) => match e.name().as_ref() {
 +                    b"bookmark" => {
 +                        if let Some(bm) = current_bookmark.take() {
 +                            if let Some(entry) = bm.into_entry() {
 +                                // Only include file:// entries that still exist
 +                                if entry.path.exists() {
 +                                    self.entries.push(entry);
 +                                }
 +                            }
 +                        }
 +                    }
 +                    b"metadata" => {
 +                        in_metadata = false;
 +                    }
 +                    _ => {}
 +                },
 +                Ok(Event::Eof) => break,
 +                Err(e) => return Err(RecentsError::Xml(e)),
 +                _ => {}
 +            }
 +            buf.clear();
 +        }
++
 +        // Sort by visited time, most recent first
 +        self.entries
 +            .sort_by(|a, b| b.visited.cmp(&a.visited));
++
 +        // Limit to max entries
 +        self.entries.truncate(self.max_entries);
++
 +        Ok(())
 +    }
++
 +    /// Get entries (files that still exist, limited to max_entries).
 +    pub fn entries(&self) -> &[RecentEntry] {
 +        &self.entries
 +    }
++
 +    /// Check if there are any entries.
 +    pub fn is_empty(&self) -> bool {
 +        self.entries.is_empty()
 +    }
++
 +    /// Get entry count.
 +    pub fn len(&self) -> usize {
 +        self.entries.len()
 +    }
++
 +    /// Add an entry when garfield opens a file (writes to xbel).
 +    /// This makes garfield a good citizen of the XDG ecosystem.
 +    pub fn add_entry(&mut self, path: &Path, mime_type: &str) -> Result<(), RecentsError> {
 +        // For now, just reload after external tools write
 +        // Full write support can be added later
 +        let _ = (path, mime_type);
 +        self.load()
 +    }
++
 +    /// Clear all cached entries (does not modify the file).
 +    pub fn clear_cache(&mut self) {
 +        self.entries.clear();
 +    }
 +}
++
 +impl Default for RecentsManager {
 +    fn default() -> Self {
 +        Self::new()
 +    }
 +}
++
 +/// Partial bookmark being parsed.
 +struct PartialBookmark {
 +    href: Option<String>,
 +    visited: Option<String>,
 +    modified: Option<String>,
 +    mime_type: Option<String>,
 +}
++
 +impl PartialBookmark {
 +    fn into_entry(self) -> Option<RecentEntry> {
 +        let href = self.href?;
++
 +        // Only handle file:// URIs
 +        if !href.starts_with("file://") {
 +            return None;
 +        }
++
 +        // Decode file:// URI to path
 +        let path_str = &href[7..]; // Strip "file://"
 +        let decoded = percent_decode(path_str);
 +        let path = PathBuf::from(decoded);
++
 +        let visited = parse_iso8601(&self.visited.unwrap_or_default())
 +            .unwrap_or(SystemTime::UNIX_EPOCH);
 +        let modified = parse_iso8601(&self.modified.unwrap_or_default())
 +            .unwrap_or(SystemTime::UNIX_EPOCH);
++
 +        Some(RecentEntry {
 +            path,
 +            mime_type: self.mime_type,
 +            visited,
 +            modified,
 +        })
 +    }
 +}
++
 +/// Parse bookmark element attributes.
 +fn parse_bookmark_attrs(e: &BytesStart) -> PartialBookmark {
 +    PartialBookmark {
 +        href: get_attr(e, b"href"),
 +        visited: get_attr(e, b"visited"),
 +        modified: get_attr(e, b"modified"),
 +        mime_type: None,
 +    }
 +}
++
 +/// Get an attribute value as String.
 +fn get_attr(e: &BytesStart, name: &[u8]) -> Option<String> {
 +    e.attributes()
 +        .filter_map(|a| a.ok())
 +        .find(|a| a.key.as_ref() == name)
 +        .and_then(|a| String::from_utf8(a.value.to_vec()).ok())
 +}
++
 +/// Percent-decode a URL path component.
 +fn percent_decode(s: &str) -> String {
 +    let mut result = String::with_capacity(s.len());
 +    let mut chars = s.chars().peekable();
++
 +    while let Some(c) = chars.next() {
 +        if c == '%' {
 +            // Try to parse the next two characters as hex
 +            let hex: String = chars.by_ref().take(2).collect();
 +            if hex.len() == 2 {
 +                if let Ok(byte) = u8::from_str_radix(&hex, 16) {
 +                    result.push(byte as char);
 +                    continue;
 +                }
 +            }
 +            // If parsing failed, keep the original
 +            result.push('%');
 +            result.push_str(&hex);
 +        } else {
 +            result.push(c);
 +        }
 +    }
++
 +    result
 +}
++
 +/// Parse ISO 8601 timestamp to SystemTime.
 +fn parse_iso8601(s: &str) -> Option<SystemTime> {
 +    // Format: 2026-01-12T11:08:52.375556Z
 +    // We'll use chrono for parsing
 +    use chrono::{DateTime, Utc};
++
 +    let dt: DateTime<Utc> = s.parse().ok()?;
 +    Some(SystemTime::from(dt))
 +}
++
 +#[cfg(test)]
 +mod tests {
 +    use super::*;
++
 +    #[test]
 +    fn test_percent_decode() {
 +        assert_eq!(percent_decode("hello%20world"), "hello world");
 +        assert_eq!(percent_decode("file%3A%2F%2F"), "file://");
 +        assert_eq!(percent_decode("no_encoding"), "no_encoding");
 +    }
++
 +    #[test]
 +    fn test_parse_iso8601() {
 +        let ts = parse_iso8601("2026-01-12T11:08:52.375556Z");
 +        assert!(ts.is_some());
 +    }
++
 +    #[test]
 +    fn test_recents_manager_new() {
 +        let manager = RecentsManager::new();
 +        assert!(manager.entries.is_empty());
 +        assert!(manager.xbel_path.ends_with("recently-used.xbel"));
 +    }
 +}