cl-xdg

#+OPTIONS: toc:3

* cl-xdg

CL-XDG provides access to
[[https://www.freedesktop.org/wiki/Specifications/desktop-entry-spec/][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.


cl-sxml

cl-xmlspam

flexi-streams

parse-number

sb-posix

split-sequence

uiop

asdf

fiveam

cl-xdg-test

cl-xdg

Upstream URL

Author

License

cl-xdg

License:

Authors:

Dependencies:

cl-xdg-test

Dependencies:

Dependencies (7)

Dependents (0)