CL-XDG provides access to freedesktop.org desktop entries.
standard-object
, t
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.
standard-object
, t
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.
find-desktop-file-by-id files id
files
- a DESKTOP-FILES object
id
- a string
find-desktop-file-by-id
returns the desktop file with a particular
ID (as documented under id
).
parse-desktop-file filespec → desktop-file
filespec
- a pathname designator
desktop-file
- an opaque object representing a parsed desktop file
load-desktop-file
reads a single desktop file from disk.
load-desktop-files &optional subdir → desktop-files
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
load-desktop-files
finds & parses all desktop files from subdir
underneath *xdg-data-home*
.
id file → id
file
- a
DESKTOP-FILE
id
- a string indicating the file’s ID, if any
Returns the calculated ID of FILE
. This consists of the subpath
beneath the particular search directory
(e.g. /usr/share/applications/
), with #\/
replaced with #\-
.
path file → pathname
file
- a
DESKTOP-FILE
id
- a pathname
Returns the path FILE
was loaded from.
get-string-key key file &key group → value
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
, ornil
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.
get-strings-key key file &key group → items
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
, ornil
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.
get-locale-string-key key file &key group locales → value
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
, ornil
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.
get-locale-strings-key key file &key group locales → items
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
, ornil
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.
get-boolean-key key file &key group → value
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
ornil
get-boolean-key
searches file
for the indicated key, which must
indicate a single boolean value (“true” or “false).
get-number-key key file &key group → value
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
get-number-key
searches file
for the indicated key, which must
indicate a single number value.
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.