Writing a Clipboard Manager

Reading Inputs

Raku was chosen⁵ for the ease of text manipulation and seamless interfacing with external programs. I learned it quite a while ago and has always been waiting for a chance to do something more practical with it, other than competitive programming which isn’t a good fit due to Rakudo’s poor performance. In Raku, the snippet from clipbuzz’s README becomes:

while run 'clipbuzz' {
    # do something with xclip or xsel
}

Out of all languages I know, this is by far the simplest way to run an external program. Most would require one to import something or do something with the call’s return value, and don’t even get me start on POSIX fork and exec model.

OK, now what are we gonna do with xclip? One obvious thing would be to read the current selection. Raku got you covered, fam:

my $selection = qx/xclip -out/;

Remember when I said Raku can seamlessly interact with external programs? qx is how you capture their standard output, it is really that simple. But wait, which selection is that? No worries, xclip supports both primary and clipboard:

my $primary = qx/xclip -out -selection primary/;
my $clipbroad = qx/xclip -out -selection clipboard/;

Cache Directory Setup

This is when we write those selection down for later use, right? Well, we need to figure out where to save them first. According to XDG Base Directory Specification, $XDG_CACHE_HOME shall falls back to $HOME/.cache:

my $XDG_CACHE_HOME = %*ENV<XDG_CACHE_HOME> // path $*HOME / '.cache':;

For convenience purposes, I defined the / operator as an alias for path concatination:

multi sub infix:</>($parent, $child) { add $parent: $child }

With $XDG_CACHE_HOME defined, we can prepare the base directory as follows:

my $base = $XDG_CACHE_HOME.IO / 'threa';
mkdir $base: unless $base.e;
die "thread: $base: File exists" when $base.f;

As a wise man once said,

As it often happens, writing an article ends up with a bug found in Rakudo.

In this case, there’s a bug in mkdir that makes it happily returns even if the target path is a file. I’m trying to fix it at the moment but a test is still failing. Update: it passed after a maintainer bumped the dependencies to the patched version.

Anyway, back to our clipboard manager. Here we are using flow controllers such as unless and when in the form of statement modifiers, which can sometimes be easier on eyes keeping the code flat. Existence checks like e (exists) and f (file) are also really handy. Next, we check on the order:

constant $ALNUM = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';

sub valid($path) {
    return False unless $path.f;
    so /^\w\w+$/ && .chars == .comb.unique given trim slurp $path
}

my $order = $base / 'order';
spurt $order, $ALNUM unless valid $order;

Instead of printable, we only allow alphanumerics and fallback to the uppercase ones (mainly because my screen can only fit as much vertically), unless $XDG_CACHE_HOME/threa/order is a file, contains at least two unique alphanumerics (exclusively). Reading and writing files in Raku is incredibly trivial, just slurp and spurt the path. Since we are not interested in whitespaces, they are trim’ed from order. Notice that Raku allows subroutines to be called without any parentheses—I love Lisp, but opening parenthesis after the function name always confuses me, especially when nested.

As you might have guessed, given is another statement modifier setting the topic variable that is particularly useful in pointfree programming, where regular expressions (e.g. /^\w\w+$/) are matched against directly and methods are called without specifying the object. Raku is also a weakly-typed language: .comb.unique (a list of unique characters) is coerced into an integer when compared to one (number of .chars).

Comparing and Saving Selections

What do we do with the order then? First we can determine the latest selection and compare it to the ones we got from xclip earlier to see which one is really new. We’ll also need to rotate the order, i.e. write the new selection to the $last file and move it in front of the others that we $keep as-is:

my ($first, $keep, $last) = do
    given trim slurp $order { .comb.first, .chop, .substr: *-1 }
my ($other, $content) = do given try slurp $base / $first or '' {
    when * ne $primary { 'clipboard', $primary }
    when * ne $clipboard { 'primary', $clipboard }
}

On the first few run, probably the cache files don’t exist just yet, so we fall them back to empty ones using try ... or .... We need to know the $other selection (outdated one) to later synchronize them both. In case of reselection, neither is updated and we simply skip this iteration:

next unless $other;

Otherwise, let’s go ahead, write down the $content, rotate $order and synchronize with the $other selection:

my $path = $base / $last;
spurt $path, $content;
spurt $order, $last ~ $keep;
run <xclip -in -selection>, $other, $path

That’s it, now put the daemon in $PATH and run it in ~/.xinitrc or something IDK. If you’re worried that some selection might be too big to read that you’ll the next event, asynchronize the qx calls by prefixing them with start, and await the results later on. It is that easy.

Command-Line Interface

Hol up, what if I want to store the cache elsewhere or use another set of characters? “Then you can go right ahead and have an intercourse with yourself, you ungrateful little piece of [redacted].” I would have said this were I to implement this in other languages, but luckily I got Raku, and Raku got sub MAIN:

sub MAIN(
  :$children where /^\w\w+$/ = $ALNUM, #= alphanumerics
  :$parent = $XDG_CACHE_HOME           #= cache path
) {
    my $snowflakes = $children.comb.unique.join;
    my $base = $parent.IO / 'threa';
    my $order = $base / 'order';

    while run 'clipbuzz' {
        ...
        spurt $order, $snowflakes unless valid $order;
        ...
    }
}

No matter how cool you think this is, it is cooler, I mean, look:

$ thread --help
Usage:
  thread [--children[=Str where { ... }]] [--parent=<Str>]
  
    --children[=Str where { ... }]    alphanumerics
    --parent=<Str>                    cache path

Back-End

Following the Unix™ philosophy, threac will do only one thing and do it well: it shall take the chosen selection and schedule it to move to the beginning:

my $XDG_CACHE_HOME = %*ENV<XDG_CACHE_HOME> // path add $*HOME: '.cache':;

sub MAIN(
   $choice where /^\w?$/,    #= alphanumeric
  :$parent = $XDG_CACHE_HOME #= cache path
) {
    my $base = $parent.IO.add: 'threa';
    my $order = add $base: 'order';
    spurt $order, S/$choice(.*)/$0$choice/ with $order.slurp;
    my $path = $base.add: $choice;
    run 'xclip', $path
}

The highlight here is the non-destructive substitution S///, which allow regex substitution in a pointfree and pure manner. Though, instead of moving $choice to top of the deque, we place it at the bottom and use xclip to trigger the daemon to do it and synchronize between selections.

Front-End

Note that threac does not give any output: selection history (by default) are stored in a standard and convenient location to be read by any front-end of choice. For awesome I made a menu whose each entry is wired to threac and xdotool (to simulate primary paste with S-Insert) and bind the whole thing to a keyboard shortcut.

local base = os.getenv("HOME") .. "/.cache/threa/"
local command = "threac %s && xdotool key shift+Insert"
local f = io.open(base .. "order")
local order = f:read("*a")
f:close()

local items = {}
for c in order:gmatch(".") do
  local f = io.open(base .. c)
  table.insert(items, {f:read("*a"):gsub("\n", " "), function ()
    awful.spawn.with_shell(command:format(c))
  end})
  f:close()
end
awful.menu{items = items, theme = {width = 911}}:show()