Crate freedesktop_entry_parser

Source
Expand description

A library for parsing FreeDesktop entry files. These files are used in the Desktop Entry files, Icon Theme index files, and Systemd unit files. They are similar to ini files but are distinct enough that an ini parse would not work.

§Struct of Freedesktop Entry Files

Freedesktop entry files are split up into section, each with a header in the form [NAME]. Each section has attributes, which are key value pairs, separated by and =. Some attributes have parameters. These are values between [] and the end of the attribute name. These are often use for localization.

Here is a snippet from firefox.desktop

ⓘ
[Desktop Entry]
Version=1.0
Name=Firefox
GenericName=Web Browser
GenericName[ar]=متصفح ويب
GenericName[ast]=Restolador Web
GenericName[bn]=ওয়েব ব্রাউজার
GenericName[ca]=Navegador web
Exec=/usr/lib/firefox/firefox %u
Icon=firefox

[Desktop Action new-window]
Name=New Window
Name[ach]=Dirica manyen
Name[af]=Nuwe venster
Name[an]=Nueva finestra
Exec=/usr/lib/firefox/firefox --new-window %u

The first section is called Desktop Entry. Is has many attributes including Name which is Firefox. The GenericName attributes has a param. The default value is in English but there are also values with a parameter for different locales.

§APIs

This library has two APIs, a high level api and a lower level byte oriented api. The main entry point for the high level API is Entry and the entry point for the lower level API is the parse_entry function.

§High Level API

As example input lets use the contents of sshd.service

ⓘ
[Unit]
Description=OpenSSH Daemon
Wants=sshdgenkeys.service
After=sshdgenkeys.service
After=network.target

[Service]
ExecStart=/usr/bin/sshd -D
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
Restart=always

[Install]
WantedBy=multi-user.target

For example, to print the start command we could do this:

use freedesktop_entry_parser::parse_entry;

let entry = parse_entry("./test_data/sshd.service")?;
let start_cmd = entry
    .section("Service")
    .attr("ExecStart")
    .expect("Attribute doesn't exist");
println!("{}", start_cmd);

There are more examples in the examples directory.

§Lower Level API

The lower level api is byte oriented and simply provides an iterator over the sections in the file as they appear. This API is faster and may be more suitable in certain circumstances.

Example:

use freedesktop_entry_parser::low_level::{parse_entry, SectionBytes, AttrBytes};

let file = b"[Desktop Entry]
Name=Firefox
Exec=firefox %u
Icon=firefox";

assert_eq!(parse_entry(file).next().unwrap()?, SectionBytes {
    title: b"Desktop Entry",
    attrs: vec![
        AttrBytes { name: b"Name", value: b"Firefox", param: None},
        AttrBytes { name: b"Exec", value: b"firefox %u", param: None},
        AttrBytes { name: b"Icon", value: b"firefox", param: None},
    ]
});

Re-exports§

Modules§

Structs§

  • Attr
    A single attribute and it’s value. Can also get attribute params is they exist.
  • AttrIter
    Iterates over attributes in a section
  • AttrParam
    Value of an attribute with a param.
  • AttrSelector
    Get attributes and their values from a given section.
  • Entry
    Parse a Freedesktop entry.
  • ParamIter
    Iterator over an attributes params.
  • SectionIter
    Iterate over the sections in an entry.

Functions§