The dlaunch plugin API - AlxHnr/dlaunch GitHub Wiki

Dlaunch provides various functions for writing plugins. Here is an overview of all functions which can be imported by using (import dlaunch-plugin-api):

• Sources
  • register-source
  • source-exists?
  • count-sources
  • gather-sources
• Handler
  • register-handler
  • apply-handler
• dlaunch core functions
  • dlaunch
  • dlaunch-from-list
  • call-with-dmenu-output-pipe
• Ranking
  • get-score-alist
  • learn-selected-pair
• Base directories
  • get-config-path
  • get-cache-path
  • get-data-path
• Misc
  • get-formatted-count

Sources

(register-source source-name thunk #!key async)

Registers a source with the given name. thunk is a function, which returns the sources content as a list of strings. If a source with the given name already exists, dlaunch will terminate with an error. If the optional key value async is true, thunk will be executed by a background process and its results will be cached for subsequent runs. Only the first call to an async source will be blocking, since no cache is available.

(source-exists? source-name)

Returns true if a source with the given name was registered.

(count-sources)

Returns the amount of registered sources.

(gather-sources [source-list])

Gathers the contents of all specified sources and returns a list of sorted pairs. Each pair associates a string with its source name. This list is sorted by popularity and usage frequency, the most important items first. The optional parameter source-list is a list of source names, which specifies the sources that should be searched. If it is omitted or null, it will return the contents from all registered sources. Source-list must contain only registered source names or dlaunch will terminate with an error.

Handler

(register-handler proc)

Registers the given procedure as a handler. It must be a procedure which takes two arguments: the string selected by the user and the name of its source. If the user inserts a custom string that does not exist in any source, the second argument passed to proc will be #f.

(apply-handler selected-string source-name)

Calls all registered handler with the given arguments. See register-handler for more informations.

Dlaunch core functions

(dlaunch #!key sources dmenu-args)

Opens a dmenu prompt and lets the user select a string from the specified sources. It returns either a pair, or #f if the user aborts his selection. The returned pair contains the selected string and either its source name or #f. The optional key value sources is the same as in gather-sources. The key dmenu-args contains a list of strings which will be passed to dmenu. You can use it to override the users settings defined in ~/.config/dlaunch/dmenu-args.scm. This function will ensure that the users selection will be remembered for ranking.

(dlaunch-from-list lst #!key extra-args dmenu-args)

This is a more primitive version of dlaunch. It takes a list of strings from which the user can select. If the user aborts his selection, it will return false. The optional key values extra-args and dmenu-args are string lists containing arguments for dmenu. The arguments in extra-args can be overridden by arguments defined in ~/.config/dlaunch/dmenu-args.scm. The arguments in dmenu-args have the highest priority and override everything else.

(call-with-dmenu-output-pipe proc #!key extra-args dmenu-args)

A plain wrapper around dmenu. It opens an output pipe to dmenu and passes it to proc. This allows proc to write arbitrary lines to dmenu. The selected line will be returned. If the user aborts his selection it will return #f. The optional key parameter are the same as in dlaunch-from-list.

Ranking

(get-score-alist source-name)

Returns the list of score pairs associated with the given source. A score pair associates a string with its score in the range from 0 to 1. The returned list can be empty if the source has no scored pairs associated with it.

(learn-selected-pair selected-pair)

Learns the content of the given pair and updates the score file in the users data directory. The selected pair must contain two valid strings. The first string is the item selected by the user. The second string is the name of its source. Dlaunch doesn't learn strings which have no source.

Note: You don't need to call this function manually. But its still in the API for some edge cases which may require it.

Base directories

(get-config-path ...)

Takes an arbitrary amount of strings and appends them to the full path to dlaunch's config directory. This function respects the XDG base directory specification. You are encouraged to use this function if you want to store configuration files.

Example:

(define foo-config-path (get-config-path "foo/main.scm"))

(get-cache-path ...)

Similar to the function above, but returns the path to dlaunch's cache directory.

(get-data-path ...)

Similar to the function above, but returns the path to dlaunch's data directory.

Misc

(get-formatted-count lst)

Returns the formated count of elements in the given list as a string, with a dot separating the thousands.