Skip to content

Scripting Razor Runner

Christian Surlykke edited this page Jul 21, 2013 · 4 revisions

Razor runner scripting

Note: This is feature is expected to be in Razor-qt 0.6.0, once it is released. Until then you can try i out by getting Razor from git

What is this?

Razor-runner is Razor-Qt''s application launcher. Out of the box, it will match what you type against installed desktop-applications, and show what it finds in a list, from where you can choose.

It is possible to extend what razor-runner suggest with scripts. Here we describe how.

How it works

A razor-runner script should read search-terms from standard input (line by line) - and write suggestions to standard out.

Here''s an example script. With this script added to razor-runner, razor-runner will suggest folders below your home directory. If you click one of the suggestions, the folder will open in you default file manager.

#!/usr/bin/env bash
cd $HOME
while read searchterm; do
    echo "---"
    if [[ ${#searchterm} -ge 3 ]]; then 
        find $HOME -maxdepth 3 -type d -iname "*${searchterm}*" | while read pathtodir; do
            dirname=`basename "$pathtodir"` 
            echo "- icon : folder"
            echo "  title : $dirname"
            echo "  comment: $pathtodir"
            echo "  tooltip : Open '$pathtodir' in filemanager" 
            echo "  command : xdg-open \"$pathtodir\""
    echo "..."

The script reads input, line by line, and searches from $HOME and 3 levels down for a folder with a matching name. For each folder it finds, it outputs data that can be used to form an item in razor-runner

If this script is run from the command line and given the input: 'razor-qt\n', it could output something like this:

- icon : folder
  title : backup-2013-04-28-razor-qt
  comment: /home/christian/projekter/backup-2013-04-28-razor-qt
  tooltip : Open '/home/christian/projekter/backup-2013-04-28-razor-qt' in filemanager
  command : xdg-open "/home/christian/projekter/backup-2013-04-28-razor-qt"
- icon : folder
  title : backup-razor-qt
  comment: /home/christian/projekter/backup-razor-qt
  tooltip : Open '/home/christian/projekter/backup-razor-qt' in filemanager
  command : xdg-open "/home/christian/projekter/backup-razor-qt"
- icon : folder
  title : razor-qt
  comment: /home/christian/projekter/razor-qt
  tooltip : Open '/home/christian/projekter/razor-qt' in filemanager
  command : xdg-open "/home/christian/projekter/razor-qt"
- icon : folder
  title : razor-qt-backup-2013-04-22
  comment: /home/christian/projekter/razor-qt-backup-2013-04-22
  tooltip : Open '/home/christian/projekter/razor-qt-backup-2013-04-22' in filemanager
  command : xdg-open "/home/christian/projekter/razor-qt-backup-2013-04-22"
- icon : folder
  title : razor-qt-sided
  comment: /home/christian/projekter/razor-qt-sided
  tooltip : Open '/home/christian/projekter/razor-qt-sided' in filemanager
  command : xdg-open "/home/christian/projekter/razor-qt-sided"
- icon : folder
  title : razor-qt-gem
  comment: /home/christian/projekter/razor-qt-gem
  tooltip : Open '/home/christian/projekter/razor-qt-gem' in filemanager
  command : xdg-open "/home/christian/projekter/razor-qt-gem"


  • The output is a YAML document, and it contains a list of maps.

  • Each map will become a line (or an item) in razor-runners drop-down list.

  • Each map contains: 'icon', 'title', 'comment', 'tooltip' and 'command'. The meaning of those are:

    • icon: The icon that is shown for the item in razor-runner's drop-down list. It can be an absolute path (i.e. /path/to/my/icon.png) or just an icon name, in which case it will be sought in the users icon-theme.
      • title: The short description of the item
      • comment: The long description of the item
      • tooltip: Shown in a bubble when the user puts the mouse-cursor over the item
      • command: The command that is executed if the item is selected (clicked).

Configuring scripts

To make razor-runner run a script, it has to be configured in razor-runner.conf. In our example, razor-runner.conf should contain a section like this:


The section 'external-providers' contains an array - one element for each script. Here we have one script, hence the key 'size' has value 1. Element number 1 has name=Folders which is used by razor-runner to reference the script. It has executable=/home/christian/projekter/RunnerPlugins/ which is the full path to the script.

We do not (yet) have an gui-application to do this configuration, so razor-runner.conf will have to be edited by hand.

The contract

  • Razor runner writes the search terms to the scripts standard-input. Every time the content of razor-runners search bar changes, the script will be fed a line containing the search term as it now looks.

So if the user types:


in the input-field, the script will get these 5 lines in standard input:

  • The script must produce a YAML document containing one list, containing maps. Each map must be string to string and should contain the five keys: icon, * title, comment, tooltip and command. The meaning of these are as explained above. The keys title and command are mandatory. icon, comment and tooltip may be omitted.
  • The maps can contain other keys. They will be ignored. In the future the set of keys recognized by razor-runner may be extended.
  • When the script has produced a document, the items of that document stays in razor-runners dropdown list until the script produces a new document. To eraze all items previously produced, the script can send an empty document (see below).
  • The YAML document must start with the line
    and end with the line
  • If the script has no suggestions to offer, it signals this with an empty YAML document:


More examples

Below are 2 more examples of what you can do with razor-runner scripting. One in bash and one in ruby. Of course you can use any programming language you wish.

Search google

#!/usr/bin/env bash
# If searchterm starts with 'g:' produce an item
# that offers search for whats after 'g:'
# Example: 'g:razor qt' --> search google for 'razor qt'
while read line; do
    echo "---"
    if [[ "g:" == ${line:0:2} && ${#line} -gt 2 ]]; then
        escaped_line=`echo "${line:2}" | sed -e 's/\s\s*/%20/g'`
        echo "- title: $line"
        echo "  comment: Search google for '${line:2}'"
        echo "  tooltip: Search google for '${line:2}'"
        echo "  command: xdg-open${escaped_line}"
        echo "  icon: /home/christian/projekter/RunnerPlugins/google.png"
    echo "..."

Search chromium history

#!/usr/bin/env ruby
# For this to work, sqlite3 must be installed (and chromium - obviously). It is assumed that 
# chromium keeps it's history in $HOME/.config/chromium/Default/History
# Oh, and you'll need ruby :-)

STDOUT.sync = true

require 'sqlite3'
require 'fileutils'
require 'yaml'
require 'set'

class HistorySearcher

    def establish_db_connection
        puts "Connecting..."

        @history_db.close if @history_db

        # This sucks. Chromium keeps a lock on it's history database while running, and I've not been
        # able to figure out a way to read it while that lock is on, so we have to make a full copy.
        dbfile = File.join(ENV['HOME'], '.config/chromium/Default/History')
        dbfilecopy = File.join(ENV['HOME'], '.cache/razor_runner_chromium_history_copy');
        FileUtils.copy(dbfile, dbfilecopy)

        @history_db =
        @connection_time =

    # Returns a list of items. If called with razor-qt, it could be something like:
    # [{ 'title' => '',
    #     'comment' => 'Razor-qt',
    #     'icon' => 'text-html',
    #     'tooltip' => 'open "" in browser',
    #     'command' => 'xdg-open "' },
    #  { 'title' => '',
    #     'comment' => 'Razor-qt: Download',
    #     'icon' => 'text-html',
    #     'tooltip' => "open '' in browser",
    #     'command' => "xdg-open ''" },
    #   .
    #   .
    #   . 
    # ]
    def searchForTerm(term) 
        listOfItems = [] 
        if term.length >= 3 
            # We look for urls in history containing term, ordering
            # so that shortest urls are preferred (putting very long urls that contain 
            # lots of query parameters behind) 

            query = <<-EndOfSelect
                SELECT DISTINCT title, url 
                FROM urls 
                WHERE url LIKE 'http://#{term}%' 
                OR url LIKE 'https://#{term}%'
                OR url LIKE 'http://www.#{term}%'
                OR url LIKE 'https://www.#{term}%'
                ORDER BY length(url) 
                LIMIT 5

            @history_db.execute(query).map do |title, url|
                puts url + "-->" + title.dump
                listOfItems << 
                        'title' => url.gsub(/^https?:\/\/(www.)?/, ""), # Strip leading http(s)://(www.) 
                        'comment' => title.gsub(/\n/, " "),
                        'icon' => 'text-html',
                        'tooltip' => "open '#{url}' in browser",
                        'command' => "xdg-open \"#{url}\""

        return listOfItems

    def main
        @connection_time = - 700; 

    while term = gets do
            establish_db_connection if ( - @connection_time) > 600 # Get a new copy of history-db every 10 minutes...

            # Ok with a db-copy in place and an open connection we're ready to consume input. 
            term = term.downcase.gsub(/\n$/, "")


            # Ruby YAML does not end documents with '...', but razor-runner needs that
            # as a syncronizing token, so we add it.
Something went wrong with that request. Please try again.