file_desktop 0.1.0

Parse, inspect, and build XDG .desktop files in Rust
Documentation
// {── Module ──────────────────────────────────────────────────────────────────
//! Iterator adapters for Desktop Entry specification versions.
//!
//! This module provides iterator adapters for filtering Desktop Entry keys and
//! entries by the targeted Desktop Entry Specification version.
//!
//! # Overview
//!
//! Different versions of the Desktop Entry Specification support different sets of keys.
//! This module provides the [`VersionKeys`] iterator adapter and the [`EntryIter`] trait
//! for conveniently filtering keys by specification version.
//!
//! # Examples
//!
//! Filter keys to those available in Desktop Entry Specification 1.0:
//!
//! ```rust
//! use file_desktop::iter::EntryIter;
//! use file_desktop::key::Version;
//!
//! let keys: Vec<_> = ["Name", "DBusActivatable", "SingleMainWindow"]
//!     .iter()
//!     .copied()
//!     .version_keys(&Version::Ver1_0)
//!     .collect();
//!
//! assert!(keys.contains(&"Name"));
//! assert!(!keys.contains(&"DBusActivatable")); // added in v1.1
//! assert!(!keys.contains(&"SingleMainWindow")); // added in v1.5
//! ```

// }{── VersionKeys ────────────────────────────────────────────────────────────
//
use crate::entry::AnnotatedEntry;
use crate::key::{VERSION_EXCLUDES, Version};
use std::fmt::Display;

/// An iterator adapter that filters Desktop Entry keys by specification version.
///
/// `VersionKeys` filters an iterator of standard key names to include only the
/// keys available in a specific Desktop Entry Specification version.
///
/// # Created By
///
/// This struct is created by the [`version_keys`](EntryIter::version_keys) method on
/// the [`EntryIter`] trait.
///
/// # Type Parameters
///
/// * `I` - The underlying iterator type, which must yield `&'static str` values.
///
/// # Examples
///
/// Create a version-specific key iterator:
///
/// ```rust
/// use file_desktop::iter::EntryIter;
/// use file_desktop::key::Version;
///
/// let keys = ["Exec", "Keywords", "SingleMainWindow"]
///     .iter()
///     .copied()
///     .version_keys(&Version::Ver1_0);
/// let collected: Vec<_> = keys.collect();
/// // Keywords (v1.1) and SingleMainWindow (v1.5) are excluded
/// assert_eq!(collected, vec!["Exec"]);
/// ```
///
/// The iterator can be cloned and reused:
///
/// ```rust
/// use file_desktop::iter::EntryIter;
/// use file_desktop::key::Version;
///
/// let keys = ["Exec", "DBusActivatable"]
///     .iter()
///     .copied()
///     .version_keys(&Version::Ver1_4);
/// let keys_clone = keys.clone();
/// assert_eq!(keys.collect::<Vec<_>>(), keys_clone.collect::<Vec<_>>());
/// ```
#[derive(Debug, Clone)]
pub struct VersionKeys<I> {
    iter: I,
    keys: &'static [&'static str],
}

impl<I: Iterator> VersionKeys<I> {
    /// Creates a version-filtered iterator; called by [`EntryIter::version_keys`].
    ///
    /// Slices `VERSION_EXCLUDES` from the appropriate index for `version` to build
    /// the exclusion list used by `next`.
    pub(crate) fn new(iter: I, version: Version) -> Self {
        let keys = match version {
            Version::Ver1_0 => &VERSION_EXCLUDES[..],
            Version::Ver1_1 => &VERSION_EXCLUDES[3..],
            Version::Ver1_2 | Version::Ver1_3 => &VERSION_EXCLUDES[4..],
            Version::Ver1_4 => &VERSION_EXCLUDES[5..],
            Version::Ver1_5 => &[],
        };

        Self { iter, keys }
    }
}

impl<I> Iterator for VersionKeys<I>
where
    I: Iterator<Item = &'static str>,
{
    type Item = &'static str;

    fn next(&mut self) -> Option<Self::Item> {
        loop {
            let key = self.iter.next();
            if !self.keys.contains(&key?) {
                return key;
            }
        }
    }
}

// }{── EntryIter ──────────────────────────────────────────────────────────────

/// Extension trait that provides iterator adapters for Desktop Entry processing.
///
/// `EntryIter` is implemented for all iterators and provides convenient methods
/// for working with Desktop Entry keys across different specification versions.
///
/// # Methods
///
/// - [`version_keys`](Self::version_keys) - Filter keys by specification version
///
/// # Examples
///
/// Filter to keys available in version 1.2:
///
/// ```rust
/// use file_desktop::iter::EntryIter;
/// use file_desktop::key::Version;
///
/// let keys_v12: Vec<_> = ["Name", "PrefersNonDefaultGPU"]
///     .iter()
///     .copied()
///     .version_keys(&Version::Ver1_2)
///     .collect();
/// assert!(keys_v12.iter().all(|k| *k != "PrefersNonDefaultGPU"));
/// ```
pub trait EntryIter: Iterator {
    /// Returns an iterator over keys available in a specific specification version.
    ///
    /// Different versions of the Desktop Entry Specification support different sets of keys.
    /// This method filters the complete key list to only include keys that are valid
    /// for the specified version, maintaining the original key order.
    ///
    /// # Key Availability by Version
    ///
    /// | Version | Supported Keys | Excluded Keys |
    /// |---------|---|---|
    /// | 1.0 | 19 keys | `DBusActivatable`, `Actions`, `Keywords`, `Implements`, `PrefersNonDefaultGPU`, `SingleMainWindow` |
    /// | 1.1 | 22 keys | `Implements`, `PrefersNonDefaultGPU`, `SingleMainWindow` |
    /// | 1.2-1.3 | 23 keys | `PrefersNonDefaultGPU`, `SingleMainWindow` |
    /// | 1.4 | 24 keys | `SingleMainWindow` |
    /// | 1.5 | 25 keys | (none) |
    ///
    /// # Arguments
    ///
    /// * `version` - The Desktop Entry Specification version to target.
    ///
    /// # Examples
    ///
    /// Get all keys supported in version 1.0:
    ///
    /// ```rust
    /// use file_desktop::iter::EntryIter;
    /// use file_desktop::key::Version;
    ///
    /// let v1_0_keys: Vec<_> = ["DBusActivatable", "Exec", "Keywords"]
    ///     .iter().copied().version_keys(&Version::Ver1_0).collect();
    /// assert!(!v1_0_keys.contains(&"DBusActivatable"));
    /// assert!(!v1_0_keys.contains(&"Keywords"));
    /// assert!(v1_0_keys.contains(&"Exec"));
    /// ```
    ///
    /// Get keys for version 1.2:
    ///
    /// ```rust
    /// use file_desktop::iter::EntryIter;
    /// use file_desktop::key::Version;
    ///
    /// let v1_2_keys: Vec<_> = ["Implements", "PrefersNonDefaultGPU", "Exec"]
    ///     .iter().copied().version_keys(&Version::Ver1_2).collect();
    /// assert!(v1_2_keys.contains(&"Implements"));
    /// assert!(!v1_2_keys.contains(&"PrefersNonDefaultGPU"));
    /// ```
    ///
    /// Get keys including all available in the latest version:
    ///
    /// ```rust
    /// use file_desktop::iter::EntryIter;
    /// use file_desktop::key::Version;
    ///
    /// let v1_5_keys: Vec<_> = ["SingleMainWindow", "Exec"]
    ///     .iter().copied().version_keys(&Version::Ver1_5).collect();
    /// assert!(v1_5_keys.contains(&"SingleMainWindow"));
    /// assert_eq!(v1_5_keys.len(), 2);
    /// ```
    #[inline]
    fn version_keys(self, version: &Version) -> VersionKeys<Self>
    where
        Self: Sized + Iterator<Item = &'static str>,
    {
        VersionKeys::new(self, *version)
    }

    /// Creates a Desktop Entry template with one empty assignment per item.
    ///
    /// Each item is formatted with [`Display`] and appended after the
    /// `[Desktop Entry]` header as `key=`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use file_desktop::iter::EntryIter;
    ///
    /// let template = ["Name", "Exec"].iter().copied().template();
    /// assert_eq!(template, "[Desktop Entry]\nName=\nExec=");
    /// ```
    #[inline]
    fn template(self) -> String
    where
        Self: Sized,
        <Self as Iterator>::Item: Display,
    {
        self.fold("[Desktop Entry]".to_string(), |acc, x| {
            format!("{acc}\n{x}=")
        })
    }
}

impl<T: Iterator + ?Sized> EntryIter for T {}

// }{── Public AnnotatedEntry version-filter API  ──────────────────────────────

/// An iterator adapter that filters [`AnnotatedEntry`] items by specification version.
///
/// Entries whose key was introduced in a version later than the target version
/// are skipped.  Entries with no `version_introduced` (present since v1.0) are
/// always included.
///
/// # Examples
///
/// ```rust
/// use file_desktop::desktop::{DesktopFile, DesktopFileType};
/// use file_desktop::iter::EntryVersionFilter;
/// use file_desktop::key::Version;
/// use std::str::FromStr;
///
/// let desktop = DesktopFile::from_str(
///     "[Desktop Entry]\nName=MyApp\nType=Application\nDBusActivatable=false"
/// ).unwrap();
///
/// // Filter to v1.0: DBusActivatable was added in v1.1, so it is excluded.
/// let group = desktop.group("Desktop Entry").unwrap();
/// let v10: Vec<_> = group.entries().iter().filter_by_version(&Version::Ver1_0).collect();
/// assert!(!v10.iter().any(|ae| ae.key_name() == "DBusActivatable"));
/// ```
#[derive(Debug, Clone)]
pub struct VersionEntries<'a, I> {
    iter: I,
    version: &'a Version,
}

impl<'a, I: Iterator<Item = &'a AnnotatedEntry>> Iterator for VersionEntries<'a, I> {
    type Item = &'a AnnotatedEntry;

    fn next(&mut self) -> Option<Self::Item> {
        self.iter.find(|ae| match ae.version_introduced() {
            None => true,
            Some(v) => v <= *self.version,
        })
    }
}

// }{── EntryVersionFilter ─────────────────────────────────────────────────────
//
/// Extension trait that provides version-aware filtering for [`AnnotatedEntry`] iterators.
///
/// # Examples
///
/// ```rust
/// use file_desktop::desktop::{DesktopFile, DesktopFileType};
/// use file_desktop::iter::EntryVersionFilter;
/// use file_desktop::key::Version;
/// use std::str::FromStr;
///
/// let desktop = DesktopFile::from_str(
///     "[Desktop Entry]\nName=MyApp\nType=Application"
/// ).unwrap();
/// let group = desktop.group("Desktop Entry").unwrap();
/// let entries: Vec<_> = group.entries().iter().filter_by_version(&Version::Ver1_5).collect();
/// assert!(!entries.is_empty());
/// ```
pub trait EntryVersionFilter<'a>: Iterator<Item = &'a AnnotatedEntry> + Sized {
    /// Returns an iterator that yields only entries valid for `version`.
    ///
    /// # Arguments
    ///
    /// * `version` - The maximum Desktop Entry Specification version to include.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use file_desktop::entry::{AnnotatedEntry, Entry};
    /// use file_desktop::iter::EntryVersionFilter;
    /// use file_desktop::key::{Bool, Version};
    ///
    /// let entries = [AnnotatedEntry::new(Entry::DBusActivatable(Bool::new(false)))];
    /// let filtered: Vec<_> = entries.iter().filter_by_version(&Version::Ver1_0).collect();
    ///
    /// assert!(filtered.is_empty());
    /// ```
    fn filter_by_version(self, version: &'a Version) -> VersionEntries<'a, Self>;
}

impl<'a, I: Iterator<Item = &'a AnnotatedEntry>> EntryVersionFilter<'a> for I {
    #[inline]
    fn filter_by_version(self, version: &'a Version) -> VersionEntries<'a, Self> {
        VersionEntries {
            iter: self,
            version,
        }
    }
}