cl-xdg

CL-XDG provides access to freedesktop.org desktop entries.

API

Class DESKTOP-FILE

Class precedence list

standard-object, t

Description

A desktop file represents a single parsed desktop file, a collection of grouped keys and values. Keys are unique within a group. Keys may be strings, locale strings (i.e., they may have locale-specific string values), booleans or numbers.

Class DESKTOP-FILES

Class precedence list

standard-object, t

Description

An object of class DESKTOP-FILES represents a collection of precedence-ordered parsed desktop files. It will be possible to query such a collection to retrieve a particular desktop file.

FUNCTION FIND-DESKTOP-FILE-BY-ID

Syntax

find-desktop-file-by-id files id

Arguments and values

files

a DESKTOP-FILES object

id

a string

Description

find-desktop-file-by-id returns the desktop file with a particular ID (as documented under id).

Function LOAD-DESKTOP-FILE

Syntax

parse-desktop-file filespec → desktop-file

Arguments and values

filespec

a pathname designator

desktop-file

an opaque object representing a parsed desktop file

Description

load-desktop-file reads a single desktop file from disk.

Function LOAD-DESKTOP-FILES

Syntax

load-desktop-files &optional subdir → desktop-files

Arguments and values

subdir

A subdirectory underneath *xdg-data-home* to search; defaults to #P"applications/"​

desktop-files

A DESKTOP-FILES object containing all parsed desktop files found

Description

load-desktop-files finds & parses all desktop files from subdir underneath *xdg-data-home*.

Function ID

Syntax

id file → id

Arguments and values

file

a DESKTOP-FILE

id

a string indicating the file’s ID, if any

Description

Returns the calculated ID of FILE. This consists of the subpath beneath the particular search directory (e.g. /usr/share/applications/), with #\/ replaced with #\-.

Function PATH

Syntax

path file → pathname

Arguments and values

file

a DESKTOP-FILE

id

a pathname

Description

Returns the path FILE was loaded from.

Function GET-STRING-KEY

Syntax

get-string-key key file &key group → value

Arguments and values

key

a string

file

a desktop file, as returned from parse-desktop-file

group

a string indicating the group to find the key in; the default is “Desktop Entry”

value

a string containing the un-escaped value associated with key, or nil

Description

get-string-key searches file for the indicated key, which must indicate a single string value. If found, any escape sequences are replaced and the value is returned.

Function GET-STRINGS-KEY

Syntax

get-strings-key key file &key group → items

Arguments and values

key

a string

file

a desktop file, as returned from parse-desktop-file

group

a string indicating the group to find the key in; the default is “Desktop Entry”

items

a list of strings containing the un-escaped values associated with key, or nil

Description

get-strings-key searches file for the indicated key, which must indicate a #\;-delimited string list. If found, any escape sequences are replaced and the value is returned.

Function GET-LOCALE-STRING-KEY

Syntax

get-locale-string-key key file &key group locales → value

Arguments and values

key

a string

file

a desktop file, as returned from parse-desktop-file

group

a string indicating the group to find the key in; the default is “Desktop Entry”

locales

a list of each specific locale to search for; defaults to a sensible value based on $LC_MESSAGES, per the rules in the XDG Desktop Entry Specification, e.g. if $LC_MESSAGES is “en_GB.UTF-8@oxon” then the default is ("en_GB@oxon" "en_GB" "en@oxon" "en")

value

a string containing the un-escaped value associated with key, or nil

Description

get-locale-string-key searches file for the indicated key, which must indicate a single string value; it tries the most-specific possible locale first, then the least-specific, and eventually falls back to get-string-key. If found, any escape sequences are replaced and the value is returned.

Function GET-LOCALE-STRINGS-KEY

Syntax

get-locale-strings-key key file &key group locales → items

Arguments and values

key

a string

file

a desktop file, as returned from parse-desktop-file

group

a string indicating the group to find the key in; the default is “Desktop Entry”

locales

a list of each specific locale to search for; defaults to a sensible value based on $LC_MESSAGES, per the rules in the XDG Desktop Entry Specification, e.g. if $LC_MESSAGES is “en_GB.UTF-8@oxon” then the default is ("en_GB@oxon" "en_GB" "en@oxon" "en")

items

a list of strings containing the un-escaped values associated with key, or nil

Description

get-locale-strings-key searches file for the indicated key, which must indicate a #\;-delimited string list; it tries the most-specific possible locale first, then the least-specific, and eventually falls back to get-string-key. If found, any escape sequences are replaced and the value is returned.

Function GET-BOOLEAN-KEY

Syntax

get-boolean-key key file &key group → value

Arguments and values

key

a string

file

a desktop file, as returned from parse-desktop-file

group

a string indicating the group to find the key in; the default is “Desktop Entry”

value

t or nil

Description

get-boolean-key searches file for the indicated key, which must indicate a single boolean value (“true” or “false).

Function GET-NUMBER-KEY

Syntax

get-number-key key file &key group → value

Arguments and values

key

a string

file

a desktop file, as returned from parse-desktop-file

group

a string indicating the group to find the key in; the default is “Desktop Entry”

value

a number

Description

get-number-key searches file for the indicated key, which must indicate a single number value.

Bugs

Uses PARSE-NUMBER:PARSE-REAL-NUMBER rather than sscanf(3) or strtof(3), so the number format is not quite to spec. Supporting the POSIX C locale’s number format is hard to do portably.