Writing dlaunch plugins - AlxHnr/dlaunch GitHub Wiki

This tutorial will go trough all steps needed to create your first dlaunch plugin. It requires knowlege of the Scheme programming language and the CHICKEN Scheme implementation.

Overview

A dlaunch plugin is nothing more than a simple Scheme script. It will be compiled and loaded by dlaunch at runtime. A plugin can provide arbitrary sources and handler.

A source is a function which returns a list of strings.

A handler is a procedure, to which the users selection will be passed.

Introduction

The plugin which you will write in this tutorial will allow you to run commands from your bash history. First you need to create the directory ~/.config/dlaunch/plugins/ and also the file bash-history.scm inside it. This file is the main source file of your plugin.

Now you need to import dlaunch's plugin API from this file:

(import dlaunch-plugin-api)

It provides various useful functions, like registering a source or a handler.

Writing a source

We start by writing a function, which reads the contents of ~/.bash_history and returns it as a list of strings.

; Import and load the 'extras' unit for the function 'read-lines':
(use extras)

(define (get-bash-history)
  (read-lines
    (string-append (get-environment-variable "HOME") "/.bash_history")))

Thats it. The only thing left to do is to register this function as a source:

(register-source "bash-history" get-bash-history)

The next time you run dlaunch, it will notice this plugin and run it after successful compilation. To see whats going on, make sure to run dlaunch from the command line and pass the --compile flag. If it compiles without any errors, you can run dlaunch with the argument --sources=bash-history and search trough your bash history. Omitting this argument will cause dlaunch to search trough all available sources.

Sorting and ranking

You will notice, that your bash history is listed in the same order as in ~/.bash_history and is completely unsorted. This is because dlaunch itself only scores and sorts things which have been selected at least once. But it can't guess whats important in your source and which sorting criteria should be applied on its content. Thus we can help dlaunch a little bit, by presorting our sources content. A good rule of thumb is to sort strings by length, the shortest first. So if the user wants a longer and more complex match, he just continues typing until he finds what he needs. But this type of sorting may not be suited well for a bash history. Thats why we simply reverse the order of strings in the list, to ensure that more recent items will come first:

...
(reverse
  (read-lines
    (string-append (get-environment-variable "HOME") "/.bash_history")))
...

Writing a handler

Great. Now we can search trough our bash history. But selecting an item doesn't do anything but remembering it for subsequent invocations. Thus we must write a handler:

; Import and load the 'posix' unit for the function 'process-run':
(use posix)

(define (bash-history-handler selected-string source-name)
  ; Check if the selected string comes from our source:
  (if (equal? source-name "bash-history")
    (process-run selected-string)))

The last thing our plugin needs is to register this handler:

(register-handler bash-history-handler)

Other things to consider

To prevent plugins from cluttering and overwriting each others identifier, you should place your main code inside a let statement. CHICKEN provides its own module system which you can use.