cl-xdg

2017-01-24

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 "enGB.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 "enGB.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.

Author
Bob Uhl <bob.denver.co@gmail.com>
License
GNU General Public License