1cl-xdg

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

1.1API

1.1.1Class DESKTOP-FILE

1.1.1.1Class precedence list

standard-object, t

1.1.1.2Description

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

1.1.2Class DESKTOP-FILES

1.1.2.1Class precedence list

standard-object, t

1.1.2.2Description

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

1.1.3FUNCTION FIND-DESKTOP-FILE-BY-ID

1.1.3.1Syntax

find-desktop-file-by-id files id

1.1.3.2Arguments and values

files

a DESKTOP-FILES object

id

a string

1.1.3.3Description

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

1.1.4Function LOAD-DESKTOP-FILE

1.1.4.1Syntax

parse-desktop-file filespec → desktop-file

1.1.4.2Arguments and values

filespec

a pathname designator

desktop-file

an opaque object representing a parsed desktop file

1.1.4.3Description

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

1.1.5Function LOAD-DESKTOP-FILES

1.1.5.1Syntax

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

1.1.5.2Arguments and values

subdir

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

desktop-files

A DESKTOP-FILES object containing all parseddesktop files found

1.1.5.3Description

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

1.1.6Function ID

1.1.6.1Syntax

id file → id

1.1.6.2Arguments and values

file

a DESKTOP-FILE

id

a string indicating the file's ID, if any

1.1.6.3Description

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

1.1.7Function PATH

1.1.7.1Syntax

path file → pathname

1.1.7.2Arguments and values

file

a DESKTOP-FILE

id

a pathname

1.1.7.3Description

Returns the path FILE was loaded from.

1.1.8Function GET-STRING-KEY

1.1.8.1Syntax

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

1.1.8.2Arguments 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; thedefault is "Desktop Entry"

value

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

1.1.8.3Description

get-string-key searches file for the indicated key, which mustindicate a single string value. If found, any escape sequences arereplaced and the value is returned.

1.1.9Function GET-STRINGS-KEY

1.1.9.1Syntax

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

1.1.9.2Arguments 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; thedefault is "Desktop Entry"

items

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

1.1.9.3Description

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

1.1.10Function GET-LOCALE-STRING-KEY

1.1.10.1Syntax

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

1.1.10.2Arguments 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; thedefault is "Desktop Entry"

locales

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

value

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

1.1.10.3Description

get-locale-string-key searches file for the indicated key, whichmust indicate a single string value; it tries the most-specificpossible locale first, then the least-specific, and eventually fallsback to get-string-key. If found, any escape sequences arereplaced and the value is returned.

1.1.11Function GET-LOCALE-STRINGS-KEY

1.1.11.1Syntax

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

1.1.11.2Arguments 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; thedefault is "Desktop Entry"

locales

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

items

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

1.1.11.3Description

get-locale-strings-key searches file for the indicated key, which mustindicate a #\;-delimited string list; it tries the most-specificpossible locale first, then the least-specific, and eventually fallsback to get-string-key. If found, any escapesequences are replaced and the value is returned.

1.1.12Function GET-BOOLEAN-KEY

1.1.12.1Syntax

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

1.1.12.2Arguments 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; thedefault is "Desktop Entry"

value

t or nil

1.1.12.3Description

get-boolean-key searches file for the indicated key, which mustindicate a single boolean value ("true" or "false).

1.1.13Function GET-NUMBER-KEY

1.1.13.1Syntax

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

1.1.13.2Arguments 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; thedefault is "Desktop Entry"

value

a number

1.1.13.3Description

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

1.1.13.4Bugs

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