The cl-xdg Reference Manual

Table of Contents

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

The cl-xdg Reference Manual

This is the cl-xdg Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:37:07 2018 GMT+0.


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

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.


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

2 Systems

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


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

2.1 cl-xdg

Author

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

License

GNU General Public License

Description

freedesktop.org standards handling

Dependencies
Source

cl-xdg.asd (file)

Components

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

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 files   [Contents][Index]

3.1.1 cl-xdg.asd

Location

cl-xdg.asd

Systems

cl-xdg (system)


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

3.1.2 cl-xdg/package.lisp

Parent

cl-xdg (system)

Location

package.lisp

Packages

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

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

Dependency

package.lisp (file)

Parent

cl-xdg (system)

Location

ordered-hash-table.lisp

Internal Definitions

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

3.1.4 cl-xdg/desktop.lisp

Dependency

ordered-hash-table.lisp (file)

Parent

cl-xdg (system)

Location

desktop.lisp

Exported Definitions
Internal Definitions

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

3.1.5 cl-xdg/menus.lisp

Dependency

desktop.lisp (file)

Parent

cl-xdg (system)

Location

menus.lisp

Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 cl-xdg/sxml

Source

package.lisp (file)


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

4.2 cl-xdg

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 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 (file)

Function: get-boolean-key KEY FILE &key GROUP
Package

cl-xdg

Source

desktop.lisp (file)

Function: get-locale-string-key KEY FILE &key GROUP LOCALES
Package

cl-xdg

Source

desktop.lisp (file)

Function: get-locale-strings-key KEY FILE &key GROUP LOCALES
Package

cl-xdg

Source

desktop.lisp (file)

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 (file)

Function: get-string-key KEY FILE &key GROUP
Package

cl-xdg

Source

desktop.lisp (file)

Function: get-strings-key KEY FILE &key GROUP
Package

cl-xdg

Source

desktop.lisp (file)

Function: load-desktop-file FILESPEC

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

Package

cl-xdg

Source

desktop.lisp (file)

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Generic functions

Generic Function: id OBJECT
Package

cl-xdg

Methods
Method: id (DESKTOP-FILE desktop-file)

automatically generated reader method

Source

desktop.lisp (file)

Generic Function: path OBJECT
Package

cl-xdg

Methods
Method: path (DESKTOP-FILE desktop-file)

automatically generated reader method

Source

desktop.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Classes

Class: desktop-file ()
Package

cl-xdg

Source

desktop.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: hash
Type

cl-xdg::ordered-hash-table

Initargs

:hash

Slot: id
Type

string

Initargs

:id

Readers

id (generic function)

Slot: path
Type

pathname

Initargs

:path

Readers

path (generic function)

Class: desktop-files ()
Package

cl-xdg

Source

desktop.lisp (file)

Direct superclasses

standard-object (class)

Direct slots
Slot: files
Type

hash-table

Initargs

:files


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

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

cl-xdg

Source

menus.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: dont-resolve-entities A B
Package

cl-xdg

Source

menus.lisp (file)

Function: dtd-resolver PUBLIC-ID SYSTEM-ID
Package

cl-xdg

Source

menus.lisp (file)

Function: get-ordered-hash KEY HASH-TABLE &optional DEFAULT
Function: (setf get-ordered-hash) VALUE KEY HASH-TABLE
Package

cl-xdg

Source

ordered-hash-table.lisp (file)

Function: lc-messages-to-locales ()

Convert LC_MESSAGES to a preference-ordered list of locales.

Package

cl-xdg

Source

desktop.lisp (file)

Function: make-ordered-hash-table &key TEST SIZE REHASH-SIZE REHASH-THRESHOLD
Package

cl-xdg

Source

ordered-hash-table.lisp (file)

Function: map-ordered-hash FUNCTION HASH-TABLE
Package

cl-xdg

Source

ordered-hash-table.lisp (file)

Function: merge-dir PATH
Package

cl-xdg

Source

menus.lisp (file)

Function: merge-file ELEMENT
Package

cl-xdg

Source

menus.lisp (file)

Function: merge-menus ELEMENT

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

Package

cl-xdg

Source

menus.lisp (file)

Function: merge-parent ()
Package

cl-xdg

Source

menus.lisp (file)

Function: merge-path PATH
Package

cl-xdg

Source

menus.lisp (file)

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 (file)

Function: parse-locale LOCALE
Package

cl-xdg

Source

desktop.lisp (file)

Function: read-menu FILESPEC
Package

cl-xdg

Source

menus.lisp (file)

Function: rem-ordered-hash KEY HASH-TABLE
Package

cl-xdg

Source

ordered-hash-table.lisp (file)

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 (file)

Function: replace-escapes STR
Package

cl-xdg

Source

desktop.lisp (file)

Function: split-multi-string STR
Package

cl-xdg

Source

desktop.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Classes

Class: ordered-hash-table ()
Package

cl-xdg

Source

ordered-hash-table.lisp (file)

Direct superclasses

standard-object (class)

Direct slots
Slot: hash
Type

hash-table

Initargs

:hash

Slot: keys
Type

(vector t 1)

Initargs

:keys


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-xdg.asd: The cl-xdg<dot>asd file
cl-xdg/desktop.lisp: The cl-xdg/desktop<dot>lisp file
cl-xdg/menus.lisp: The cl-xdg/menus<dot>lisp file
cl-xdg/ordered-hash-table.lisp: The cl-xdg/ordered-hash-table<dot>lisp file
cl-xdg/package.lisp: The cl-xdg/package<dot>lisp file

F
File, Lisp, cl-xdg.asd: The cl-xdg<dot>asd file
File, Lisp, cl-xdg/desktop.lisp: The cl-xdg/desktop<dot>lisp file
File, Lisp, cl-xdg/menus.lisp: The cl-xdg/menus<dot>lisp file
File, Lisp, cl-xdg/ordered-hash-table.lisp: The cl-xdg/ordered-hash-table<dot>lisp file
File, Lisp, cl-xdg/package.lisp: The cl-xdg/package<dot>lisp file

L
Lisp File, cl-xdg.asd: The cl-xdg<dot>asd file
Lisp File, cl-xdg/desktop.lisp: The cl-xdg/desktop<dot>lisp file
Lisp File, cl-xdg/menus.lisp: The cl-xdg/menus<dot>lisp file
Lisp File, cl-xdg/ordered-hash-table.lisp: The cl-xdg/ordered-hash-table<dot>lisp file
Lisp File, cl-xdg/package.lisp: The cl-xdg/package<dot>lisp file

Jump to:   C   F   L  

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): Internal functions

D
dont-resolve-entities: Internal functions
dtd-resolver: Internal functions

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

G
Generic Function, id: Exported generic functions
Generic Function, path: Exported generic functions
get-boolean-key: Exported functions
get-locale-string-key: Exported functions
get-locale-strings-key: Exported functions
get-number-key: Exported functions
get-ordered-hash: Internal functions
get-string-key: Exported functions
get-strings-key: Exported functions

I
id: Exported generic functions
id: Exported generic functions

L
lc-messages-to-locales: Internal functions
load-desktop-file: Exported functions
load-desktop-files: Exported functions

M
make-ordered-hash-table: Internal functions
map-ordered-hash: Internal functions
merge-dir: Internal functions
merge-file: Internal functions
merge-menus: Internal functions
merge-parent: Internal functions
merge-path: Internal functions
Method, id: Exported generic functions
Method, path: Exported generic functions

P
parse-desktop-file-line: Internal functions
parse-locale: Internal functions
path: Exported generic functions
path: Exported generic functions

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

S
split-multi-string: Internal functions

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

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

A.3 Variables

Jump to:   *  
F   H   I   K   P   S  
Index Entry  Section

*
*menu-files-in-flight*: Internal special variables

F
files: Exported classes

H
hash: Exported classes
hash: Internal classes

I
id: Exported classes

K
keys: Internal classes

P
path: Exported classes

S
Slot, files: Exported classes
Slot, hash: Exported classes
Slot, hash: Internal classes
Slot, id: Exported classes
Slot, keys: Internal classes
Slot, path: Exported classes
Special Variable, *menu-files-in-flight*: Internal special variables

Jump to:   *  
F   H   I   K   P   S  

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

A.4 Data types

Jump to:   C   D   O   P   S  
Index Entry  Section

C
cl-xdg: The cl-xdg system
cl-xdg: The cl-xdg package
cl-xdg/sxml: The cl-xdg/sxml package
Class, desktop-file: Exported classes
Class, desktop-files: Exported classes
Class, ordered-hash-table: Internal classes

D
desktop-file: Exported classes
desktop-files: Exported classes

O
ordered-hash-table: Internal classes

P
Package, cl-xdg: The cl-xdg package
Package, cl-xdg/sxml: The cl-xdg/sxml package

S
System, cl-xdg: The cl-xdg system

Jump to:   C   D   O   P   S