Scripting Guide

Overview

Mepo has extensible scripting capabilties through its JSON API by way of primarily two mechanisms: 1) via configuring scripts within the user configuration file and secondarily 2) by using the mepo's interactive STDIN to run arbitrary JSON API commands at runtime in a REPL-like fashion.

---

1. Scripting via the User Configuration File

The user configuration file (~/.config/mepo/config.json) can be used to bind scripts in various ways via the JSON API. Often the case is that you will use one of the bind_* commands and run some shellscript (or other script) you write via shellpipe_sync. This is done often in the default base configuration (which is a great example to study from), but may be done as well by end-users in their configuration as well.

The script or program to run for shellpipe_{sync,async} may be written in any language (though shellscript is simplest/best) and the only requirement is your script needs to write JSON plain text to STDOUT. To make this more practical, for example, to bind a keybinding for Control-j to set the crosshair size sequentially to 3 different sizes, you might in your user configuration file write:

[
  {
    "cmd": "bind_key",
    "args": {
      "mod": "c",
      "key": "j",
      "exps": [
        {
          "cmd": "shellpipe_sync",
          "args": {
            "shellcode": "crosshair.sh"
          }
        }
      ]
    }
  }
]

And then save in your $PATH, the script crosshair.sh as:

#!/usr/bin/env sh

echo '[{ "cmd": "prefset_n", "args": { "pref": "crosshair_size", "value": 30 } }]'
sleep 2
echo '[{ "cmd": "prefset_n", "args": { "pref": "crosshair_size", "value": 100 } }]'
sleep 2
echo '[{ "cmd": "prefset_n", "args": { "pref": "crosshair_size", "value": 15 } }]'

---

2. Scripting via Interactive STDIN

Mepo has the capability of being scripted interactively via feeding JSON API expressions continually into the application's STDIN filedescriptor. This functionality can be enabled via using the -i commandline flag which indicates to the application logic to continually read commands from STDIN (newline seperated).

One example might be:

echo '[{ "cmd": "prefset_n", "args": { "pref": "crosshair_size", "value": 200 } }]' | mepo -i

JSON with newlines also works, however ensure to delete all newlines except the last for the -i argument to parse correctly. A simple way to do this is to utilize paste -sd' ':

echo '
  [
    {
      "cmd": "prefset_n",
      "args": { "pref": "crosshair_size", "value": 200 }
    }
  ]
' | paste -sd' ' | mepo -i

Continually writing via a FIFO works as well:

mkfifo foo
cat foo | mepo -i &
echo "[{ "cmd": "prefset_n", "args": { "pref": "crosshair_size", "value": 200 } }]" > foo

Or you may use tee for interactive debugging similar to a REPL (note -e enables debug messages):

tee | mepo -i -e