The cl-xdg Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-xdg Reference Manual

This is the cl-xdg Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:09:38 2022 GMT+0.

Table of Contents


1 Introduction

#+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.


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-xdg

freedesktop.org standards handling

Author

Bob Uhl <bob.denver.co@gmail.com>

License

GNU General Public License

Dependencies
  • uiop (system).
  • split-sequence (system).
  • parse-number (system).
  • flexi-streams (system).
  • cl-sxml (system).
  • cl-xmlspam (system).
  • sb-posix (system).
Source

cl-xdg.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp   [Contents][Index]

3.1.1 cl-xdg/cl-xdg.asd

Source

cl-xdg.asd.

Parent Component

cl-xdg (system).

ASDF Systems

cl-xdg.


3.1.2 cl-xdg/package.lisp

Source

cl-xdg.asd.

Parent Component

cl-xdg (system).

Packages

3.1.3 cl-xdg/ordered-hash-table.lisp

Dependency

package.lisp (file).

Source

cl-xdg.asd.

Parent Component

cl-xdg (system).

Internals

3.1.4 cl-xdg/desktop.lisp

Dependency

ordered-hash-table.lisp (file).

Source

cl-xdg.asd.

Parent Component

cl-xdg (system).

Public Interface
Internals

Previous: , Up: Lisp   [Contents][Index]

3.1.5 cl-xdg/menus.lisp

Dependency

desktop.lisp (file).

Source

cl-xdg.asd.

Parent Component

cl-xdg (system).

Internals

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 cl-xdg/sxml

Source

package.lisp.


Previous: , Up: Packages   [Contents][Index]

4.2 cl-xdg

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: find-desktop-file-by-id (files id)

Find the desktop file with the given ID in FILES.

Package

cl-xdg.

Source

desktop.lisp.

Function: get-boolean-key (key file &key group)
Package

cl-xdg.

Source

desktop.lisp.

Function: get-locale-string-key (key file &key group locales)
Package

cl-xdg.

Source

desktop.lisp.

Function: get-locale-strings-key (key file &key group locales)
Package

cl-xdg.

Source

desktop.lisp.

Function: get-number-key (key file &key group)

PARSE-NUMBER:PARSE-NUMBER doesn’t _quite_ implement the semantics of strtod/sscanf, but it’s portable. The desktop file spec doesn’t define any standard number keys anyway.

Package

cl-xdg.

Source

desktop.lisp.

Function: get-string-key (key file &key group)
Package

cl-xdg.

Source

desktop.lisp.

Function: get-strings-key (key file &key group)
Package

cl-xdg.

Source

desktop.lisp.

Function: load-desktop-file (filespec)

Load the desktop file found in FILESPEC into a DESKTOP-FILE object.

Package

cl-xdg.

Source

desktop.lisp.

Function: load-desktop-files (&optional subdir)

Load desktop files from SUBDIR underneath $XDG_DATA_HOME and each of $XDG_DATA_DIRS. Desktop files found under #P"applications/" have IDs; files earlier in the search path take precedence over files later in the search path with the same ID.

Package

cl-xdg.

Source

desktop.lisp.


5.1.2 Generic functions

Generic Reader: id (object)
Package

cl-xdg.

Methods
Reader Method: id ((desktop-file desktop-file))

automatically generated reader method

Source

desktop.lisp.

Target Slot

id.

Generic Reader: path (object)
Package

cl-xdg.

Methods
Reader Method: path ((desktop-file desktop-file))

automatically generated reader method

Source

desktop.lisp.

Target Slot

path.


5.1.3 Classes

Class: desktop-file
Package

cl-xdg.

Source

desktop.lisp.

Direct methods
Direct slots
Slot: hash
Type

cl-xdg::ordered-hash-table

Initargs

:hash

Slot: id
Type

string

Initargs

:id

Readers

id.

Writers

This slot is read-only.

Slot: path
Type

pathname

Initargs

:path

Readers

path.

Writers

This slot is read-only.

Class: desktop-files
Package

cl-xdg.

Source

desktop.lisp.

Direct slots
Slot: files
Type

hash-table

Initargs

:files


5.2 Internals


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.1 Special variables

Special Variable: *menu-files-in-flight*
Package

cl-xdg.

Source

menus.lisp.


Next: , Previous: , Up: Internals   [Contents][Index]

5.2.2 Ordinary functions

Function: dont-resolve-entities (a b)
Package

cl-xdg.

Source

menus.lisp.

Function: dtd-resolver (public-id system-id)
Package

cl-xdg.

Source

menus.lisp.

Function: get-ordered-hash (key hash-table &optional default)
Package

cl-xdg.

Source

ordered-hash-table.lisp.

Function: (setf get-ordered-hash) (key hash-table)
Package

cl-xdg.

Source

ordered-hash-table.lisp.

Function: lc-messages-to-locales ()

Convert LC_MESSAGES to a preference-ordered list of locales.

Package

cl-xdg.

Source

desktop.lisp.

Function: make-ordered-hash-table (&key test size rehash-size rehash-threshold)
Package

cl-xdg.

Source

ordered-hash-table.lisp.

Function: map-ordered-hash (function hash-table)
Package

cl-xdg.

Source

ordered-hash-table.lisp.

Function: merge-dir (path)
Package

cl-xdg.

Source

menus.lisp.

Function: merge-file (element)
Package

cl-xdg.

Source

menus.lisp.

Function: merge-menus (element)

Process MergeFile, MergeDir and LegacyDir elements, and remove extraneous whitespace.

Package

cl-xdg.

Source

menus.lisp.

Function: merge-parent ()
Package

cl-xdg.

Source

menus.lisp.

Function: merge-path (path)
Package

cl-xdg.

Source

menus.lisp.

Function: parse-desktop-file-line (line current-group)

Given a line and the currently-active group, return a key and a value to store in the desktop file ordered hash. The possibilities are:

- comment: (GENSYM COMMENT)
- group: (GROUP NIL)
- key: ((GROUP KEY LOCALE) VALUE) or ((GROUP KEY) VALUE)

Package

cl-xdg.

Source

desktop.lisp.

Function: parse-locale (locale)
Package

cl-xdg.

Source

desktop.lisp.

Function: read-menu (filespec)
Package

cl-xdg.

Source

menus.lisp.

Function: rem-ordered-hash (key hash-table)
Package

cl-xdg.

Source

ordered-hash-table.lisp.

Function: replace-all (string part replacement &key test)

Returns a new string in which all the occurences of the part is replaced with replacement.

Package

cl-xdg.

Source

desktop.lisp.

Function: replace-escapes (str)
Package

cl-xdg.

Source

desktop.lisp.

Function: split-multi-string (str)
Package

cl-xdg.

Source

desktop.lisp.


5.2.3 Classes

Class: ordered-hash-table
Package

cl-xdg.

Source

ordered-hash-table.lisp.

Direct slots
Slot: hash
Type

hash-table

Initargs

:hash

Slot: keys
Type

(vector t 1)

Initargs

:keys


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (  
D   F   G   I   L   M   P   R   S  
Index Entry  Section

(
(setf get-ordered-hash): Private ordinary functions

D
dont-resolve-entities: Private ordinary functions
dtd-resolver: Private ordinary functions

F
find-desktop-file-by-id: Public ordinary functions
Function, (setf get-ordered-hash): Private ordinary functions
Function, dont-resolve-entities: Private ordinary functions
Function, dtd-resolver: Private ordinary functions
Function, find-desktop-file-by-id: Public ordinary functions
Function, get-boolean-key: Public ordinary functions
Function, get-locale-string-key: Public ordinary functions
Function, get-locale-strings-key: Public ordinary functions
Function, get-number-key: Public ordinary functions
Function, get-ordered-hash: Private ordinary functions
Function, get-string-key: Public ordinary functions
Function, get-strings-key: Public ordinary functions
Function, lc-messages-to-locales: Private ordinary functions
Function, load-desktop-file: Public ordinary functions
Function, load-desktop-files: Public ordinary functions
Function, make-ordered-hash-table: Private ordinary functions
Function, map-ordered-hash: Private ordinary functions
Function, merge-dir: Private ordinary functions
Function, merge-file: Private ordinary functions
Function, merge-menus: Private ordinary functions
Function, merge-parent: Private ordinary functions
Function, merge-path: Private ordinary functions
Function, parse-desktop-file-line: Private ordinary functions
Function, parse-locale: Private ordinary functions
Function, read-menu: Private ordinary functions
Function, rem-ordered-hash: Private ordinary functions
Function, replace-all: Private ordinary functions
Function, replace-escapes: Private ordinary functions
Function, split-multi-string: Private ordinary functions

G
Generic Function, id: Public generic functions
Generic Function, path: Public generic functions
get-boolean-key: Public ordinary functions
get-locale-string-key: Public ordinary functions
get-locale-strings-key: Public ordinary functions
get-number-key: Public ordinary functions
get-ordered-hash: Private ordinary functions
get-string-key: Public ordinary functions
get-strings-key: Public ordinary functions

I
id: Public generic functions
id: Public generic functions

L
lc-messages-to-locales: Private ordinary functions
load-desktop-file: Public ordinary functions
load-desktop-files: Public ordinary functions

M
make-ordered-hash-table: Private ordinary functions
map-ordered-hash: Private ordinary functions
merge-dir: Private ordinary functions
merge-file: Private ordinary functions
merge-menus: Private ordinary functions
merge-parent: Private ordinary functions
merge-path: Private ordinary functions
Method, id: Public generic functions
Method, path: Public generic functions

P
parse-desktop-file-line: Private ordinary functions
parse-locale: Private ordinary functions
path: Public generic functions
path: Public generic functions

R
read-menu: Private ordinary functions
rem-ordered-hash: Private ordinary functions
replace-all: Private ordinary functions
replace-escapes: Private ordinary functions

S
split-multi-string: Private ordinary functions

Jump to:   (  
D   F   G   I   L   M   P   R   S