Skip to main content

Crate file_desktop

Crate file_desktop 

Source
Expand description

§Desktop File Parser and Manager

A Rust crate for constructing, parsing, mutating, and serializing Desktop Entry files as defined by the XDG Desktop Entry Specification.

§Overview

The crate exposes owned document, group, entry, and key/value types for .desktop content. It supports creating new desktop entry documents in memory, parsing existing UTF-8 text with line-oriented parsing, mutating groups and entries, and formatting the result back into desktop-entry syntax.

§Core Features

  • Strongly typed representations of desktop entry documents, groups, keys, and values
  • Parsing through std::str::FromStr
  • Version-aware key filtering for Desktop Entry Specification versions 1.0 through 1.5
  • Explicit error types for parse and mutation failures
  • Comment normalization that prefixes non-blank lines with # and preserves blank lines

§Modules

  • desktop - Main DesktopFile struct and desktop entry management
  • entry - Core entry types: Entry, AnnotatedEntry, and LocalizedValue
  • entry_group - Entry group types: EntryGroup, GroupName, and KeyUniqueness
  • error - Error types for parsing and manipulation failures
  • key - Desktop Entry keys and specification version management
  • iter - Iterator adapters for key filtering by specification version

§Quick Start

use file_desktop::desktop::{DesktopFile, DesktopFileType};
use file_desktop::entry::{AnnotatedEntry, Entry};

let name = "MyApp".try_into().unwrap();
let mut desktop_file = DesktopFile::new(name, DesktopFileType::Application);

assert_eq!(
    desktop_file.to_string(),
    "[Desktop Entry]\nType=Application\nName=MyApp"
);

§Parsing

  • std::str::FromStr parses line-oriented input without trimming the full line first. It trims trailing whitespace from the key and leading whitespace from the value after splitting on the first =, but rejects lines that begin with a literal space character before classification.

The parser trims the key and value around the first = and requires a [Desktop Entry] group before returning success. It uses the original line for blank-line detection, so whitespace-only lines are rejected rather than normalized into empty lines.

§Example: Creating a Complete Desktop Entry

use file_desktop::desktop::{DesktopFile, DesktopFileType};
use file_desktop::entry::{AnnotatedEntry, Entry};

let name = "MyApp".try_into().unwrap();
let exec = "/usr/bin/myapp".try_into().unwrap();
let mut desktop_file = DesktopFile::new(name, DesktopFileType::Application);
desktop_file
    .try_add_entry("Desktop Entry", AnnotatedEntry::new(Entry::Exec(exec)))
    .unwrap();

assert_eq!(
    desktop_file.to_string(),
    "[Desktop Entry]\nType=Application\nName=MyApp\nExec=/usr/bin/myapp"
);

Modules§

desktop
Provides construction, mutation, parsing, and serialization support for XDG desktop entry files.
entry
Strongly typed domain types for Desktop Entry key-value pairs.
entry_group
Provides EntryGroup, GroupName, and KeyUniqueness for representing groups within Desktop Entry files.
error
Defines crate-wide error types for Desktop Entry parsing and mutation operations.
iter
Iterator adapters for Desktop Entry specification versions.
key
Desktop Entry keys, values, and specification versions.