Mepolang

Overview

Mepolang is mepo's command language for runtime IPC and configuration. It takes the form of a plain-text DSL (domain-specific-language) with a number of commands. Mepolang makes configuration, customizing, and hacking on mepo simple. To test mepolang simply, you may run mepo with the -i argument which reads mepolang from STDIN. The most basic example might look like:

# Set the crosshair size to 200
echo "prefset_n crosshair_size 200;" | mepo -i

# Or load a custom mepolang file from the filesystem
echo "fileload /home/foo/my_mepolang_file;" | mepo -i

Within the filesystem, based on the default base configuration, the paths $XDG_CONFIG_HOME/mepo/config and $XDG_CONFIG_HOME/mepo/bookmarks are automatically loaded on boot; as such, for most end users, configuration simply may be placed in ~/.config/mepo/config.

The rest of this document describes the syntax rules, API commands, and preferences of mepolang. Note also that mepo by default runs with certain mepolang statement's applied by default, this is known as the base configuration. Advanced details on scripting and detailed practical examples of using mepolang may be viewed in the scripting guide which should be seen as a supplement to this document.

Syntax

Syntax rules are as follows:

  • Mepolang syntax is composed of statements.
  • Each statement is made up of multiple tokens and terminated by a semicolon.
  • Tokens are separated by whitespace.
  • The first token in a statement is always the command name.
  • Each token is either:
    • Text: Just plain text, by default assumed to be a single word. If you want to use a space within a token use [ square brackets ] to create a multiword token. If you want to have a text token that looks like a number, use square brackets like [-3].
    • Number: A floating point number, either decimal (e.g. 3.77) or whole (e.g. 3). Can be negative like -22.22 or positive like 22.22.

Example mepolang text:

commandname textarg [multi word arg] 2;
commandname2 arg 8.373 anothertextarg;

Version

This document was compiled against mepo version: 1.1.

The following sections for API, preferences, shellpipe env variables, and base configuration are dependent on / assume the above version of mepo this document was compiled against, you may check your version of mepo with mepo -v.

API

bind_button

Create a UI button which executes a mepolang action. UI buttons appear aligned in the bottom right of the screen or the top left alongside the pin details overlay (see first argument).

Arguments:

Name Datatype Description
visible_only_when_pin_active Number Set to 1 to only show button in top bar if there is a currently activated pin.
group_number Number Group number (0-9) to associate with button. A Colorbar will match group # and button will highlight when group active. Use -1 for no associated group.
button_text Text Text that will be shown on the button
mepolang_expression_click_single Text Mepolang expression to run on single clicking the button
mepolang_expression_click_hold Text Mepolang expression to run on holding the button

bind_click

Bind a particular number of successive clicks to run a mepolang action.

Arguments:

Name Datatype Description
button Number Mousebutton to bind (1 = left, 2 = right, 3 = middle)
clicks Number Number of successive clicks to trigger action
mepolang_expression Text Mepolang expression to run

bind_gesture

Bind a multitouch gesture event to execute a mepolang action.

Arguments:

Name Datatype Description
action Text Gesture action (set to either pan or rotate)
fingers Number Number of fingers to trigger expression
direction Number Direction for gesture (e.g. 1 for in or -1 for out)
mepolang_expression Text Mepolang expression to run

bind_key

Bind a key combination to execute a mepolang action.

Arguments:

Name Datatype Description
modifier Text Modifier combination (c=control, s=shift, a=alt); ex. cs would mean control and shift
key Text Key to bind; note case indiscriminate since modifier handled by modifier argument
mepolang_expression Text Mepolang expression to run

bind_signal

Bind a signal to execute a mepolang action.

Arguments:

Name Datatype Description
signal_name Text Signal name; can be USR1, USR2, TERM, or INT
mepolang_expression Text Mepolang expression to run

bind_timer

Bind a timer to execute a mepolang action at the given interval.

Arguments:

Name Datatype Description
interval_seconds Number Number of seconds between successive runs of given mepolang expression
mepolang_expression Text Mepolang expression to run

bind_quit

Bind a mepolang expression to run on quitting the application.

Arguments:

Name Datatype Description
mepolang_expression Text Mepolang expression to run

cache_dlbbox

Queue tiles for a bounding box to download to the cache in the background for the given zoom levels. Writes directly to filesystem cache (path determined by tile_cache_dir preference) as tiles are downloaded.

Arguments:

Name Datatype Description
a_lat Number Starting latitude
a_lon Number Starting longitude
b_lat Number Ending latitude
b_lon Number Ending longitude
zoom_min Number Minimum zoom level
zoom_max Number Maximum zoom level

cache_dlradius

Queue tiles for a bounding box to download to the cache in the background for the given zoom levels. Writes directly to filesystem cache (path determined by tile_cache_dir preference) as tiles are downloaded.

Arguments:

Name Datatype Description
lat Number Centerpoint latitude
lon Number Centerpoint longitude
zoom_min Number Minimum zoom level
zoom_max Number Maximum zoom level
km_radius Number Radius from centerpoint in kilometers to download tiles for

cache_queueclear

Clear any queued background downloading process queued with cache_dlbbox or cache_dlradius. Note this does not remove filesystem tiles, but simply stops in-progress downloading.

center_on_mouse

Center the map on the current position of the mouse.

center_on_pin

Center the map on the currently active pin.

clipcopy

Copy the current map coordinates to the clipboard; will be in format: lat lon.

clippaste

Extract clipboard contents and either center on coordinate (if clipboard content matches lat lon format); otherwise run clipboard contents as a mepolang expression.

fileload

Load mepolang from an arbitrary filesystem file.

Arguments:

Name Datatype Description
filepath Text Path to file to load

filedump

Save the current state of pins, preference, and/or bindings to a file as mepolang.

Arguments:

Name Datatype Description
datatypes Text Types of data to save (p = pins, r = preferences, b = bindings); ex. pr would save both pins and preferences but not bindings
filepath Text Path to file to save state to

move_relative

Move the map by a relative x/y amount.

Arguments:

Name Datatype Description
rel_x Number Relative x amount
rel_y Number Relative y amount

pin_activate

Activate a pin by its handle.

Arguments:

Name Datatype Description
group_number Number Group number
pin_handle Text Pin's handle to activate

pin_add

Add a pin to the map.

Arguments:

Name Datatype Description
group_number Number Group number
is_structural Number If set to 1, will be a 'structural' pin which is useful for curved paths and similar
lat Number Latitude
lon Number Longitude
handle Text Unique handle to refer to pin; can use this handle subsequently with pin_meta to update pin metadata

pin_cycle

Cycle the currently focused pin group pin.

Arguments:

Name Datatype Description
viewport_only Number Use 1 to only cycle between pins in viewport
delta Number Delta amount (positive or negative) for number of pins to skip

pin_deactivate

Deactivate currently active pin.

pin_groupactivate

Activate the pin group specified.

Arguments:

Name Datatype Description
group_number Number Group number

pin_delete

Delete a pin by its handle.

Arguments:

Name Datatype Description
group_number Number Group number or -1 to use the current pin group.
pin_handle Text Pin's handle to delete, or empty string [] to use the current pin handle

pin_meta

Update a pin's metadata.

Arguments:

Name Datatype Description
group_number Number Group number
pin_handle Text Pin handle
key Text Metadata key to update
value Text New value for metadata key

pin_transfer

Transfer a pin from one group to another.

Arguments:

Name Datatype Description
from_group_number Number Group number, or -1 for the current group number.
pin_handle Text Handle of the pin to transfer; or empty string [] will transfer the current pin. Use the string all for all pins in group.
to_group_number Number Group number

pin_purge

Purge all pins in the currently active pin group.

prefinc

Increase or decrease a preference by the given delta value.

Arguments:

Name Datatype Description
prefname Text Preference name
delta Number Delta value to increment/decrement (positive or negative)

prefset_n

Set a preference number value.

Arguments:

Name Datatype Description
prefname Text Preference name
prefvalue Number Preference number value

prefset_t

Set a preference text value.

Arguments:

Name Datatype Description
prefname Text Preference name
prefvalue Text Preference number value

preftoggle

Toggle a boolean number preference between 1 and 0.

Arguments:

Name Datatype Description
prefname Text Preference name

quit

Quit the application.

shellpipe_async

Run a system (shell) command and pipe asynchronously; STDOUT returned from command will be executed back as a mepolang expression.

Arguments:

Name Datatype Description
unique_handle_id Number Optional id to deduplicate individual async shellpipe requests
shell_statement Text Shell statement to execute

shellpipe_sync

Run a system (shell) command synchronously and pipe; STDOUT returned from command will be executed back as a mepolang expression.

Arguments:

Name Datatype Description
shell_statement Text Shell statement to execute

zoom_relative

Update the map's zoom level by a relative delta.

Arguments:

Name Datatype Description
zoom_delta Number Zoom level relative delta

Preferences

Internally mepo keeps track of a number of preferences which control all state for the application. These preferences can be set with the commands preset_n for numerical preferences and prefset_t for textual preferences. You can also use filedump to examine the current values of all preferences.

Below is an exhaustive list of all available preferences:

Name Description Datatype Min Max Default Value
lat Latitude of the map Number (float) -90 90 40.78392
lon Longitude of the map Number (float) -180 180 -73.96442
zoom Zoom level of the map (should be set between 0-19) Number (u8) 0 19 14
debug_message_enabled Whether debug overlay message should be shown in the UI Number (bool) 1
distance_unit_tf_km_mi Whether to show distance in km (0) or mi (1) Number (bool) 0
overlay_debugbar Whether to show the debug bar Number (bool) 1
help Whether to show the help overlay Number (bool) 0
overlay_pindetails Whether to show the pin detail overlay Number (bool) 1
overlay_pindetails_expanded Whether to show the pin detail overlay as expanded Number (bool) 1
crosshair_size Pixel size of the crosshairs Number (u8) 0 300 15
drag_scale Scale for dragging Number (u8) 1 200 2
fontsize_ui Size of the font in the UI Number (u8) 1 49 20
debug_stderr Send debug information to STDERR (note the commandline flag -e overrides this setting) Number (bool) 0
tile_cache_max_n_transfers Maximum number of concurrent transfers for curl Number (u8) 1 9999 20
tile_cache_expiry_seconds Number of seconds before a downloaded tiledata should be considered invalid Number (float) -1 99999999 -1
tile_cache_network Whether to download new tiledata from external servers; if 0 that means you're offline Number (bool) 1
tile_cache_dir Path of directory to store the downloaded tiles Text null
tile_cache_url URL source for the tiles, uses %1/%2/%3 to represent X/Y/Z Text null
pingroup_0_ordered Whether pingroup 0 should be ordered Number (bool) 0
pingroup_1_ordered Whether pingroup 1 should be ordered Number (bool) 0
pingroup_2_ordered Whether pingroup 2 should be ordered Number (bool) 0
pingroup_3_ordered Whether pingroup 3 should be ordered Number (bool) 0
pingroup_4_ordered Whether pingroup 4 should be ordered Number (bool) 0
pingroup_5_ordered Whether pingroup 5 should be ordered Number (bool) 0
pingroup_6_ordered Whether pingroup 6 should be ordered Number (bool) 0
pingroup_7_ordered Whether pingroup 7 should be ordered Number (bool) 0
pingroup_8_ordered Whether pingroup 8 should be ordered Number (bool) 0
pingroup_9_ordered Whether pingroup 9 should be ordered Number (bool) 0
pingroup_0_color Color to indicate pingroup 0 Number (u24) 0
pingroup_1_color Color to indicate pingroup 1 Number (u24) 0
pingroup_2_color Color to indicate pingroup 2 Number (u24) 0
pingroup_3_color Color to indicate pingroup 3 Number (u24) 0
pingroup_4_color Color to indicate pingroup 4 Number (u24) 0
pingroup_5_color Color to indicate pingroup 5 Number (u24) 0
pingroup_6_color Color to indicate pingroup 6 Number (u24) 0
pingroup_7_color Color to indicate pingroup 7 Number (u24) 0
pingroup_8_color Color to indicate pingroup 8 Number (u24) 0
pingroup_9_color Color to indicate pingroup 9 Number (u24) 0

Shellpipe ENV Variables

Both shellpipe_sync and shellpipe_async expose a number of ENV variables to the target script called. See below for the accessible ENV variables exposed.

  • MEPO_WIN_W: Width of the UI window
  • MEPO_WIN_H: Height of the UI window
  • MEPO_ZOOM: Current zoom level
  • MEPO_CENTER_LAT: Latitude of the center point of the screen
  • MEPO_CENTER_LON: Longitude of the center point of the screen
  • MEPO_TL_LAT: Latitude of the top left point on the screen
  • MEPO_TL_LON: Longitude of the top left point on the screen
  • MEPO_BR_LAT: Latitude of the bottom right point on the screen
  • MEPO_BR_LON: Longitude of the bottom right point on the screen
  • MEPO_CURSOR_LAT: Latitude of the cursor position
  • MEPO_CURSOR_LON: Longitude of the cursor position

Base Configuration

The following base configuration was built into Mepo as of the current release version. Note, preferences can be overridden directly for example with prefset_n and prefset_t. While there are not unbinding commands currently supported, you can forgo the default configuration by using the -ndc commandline flag.

 # UI Buttons;
 bind_button 0 -1 [Menu] [shellpipe_sync mepo_ui_central_menu.sh] [];
 bind_button 0 -1 [Center] [shellpipe_sync [mepo_ui_menu_user_pin_updater.sh droppinactivateandcenter]] [];
 bind_button 0 -1 [Relocate] [shellpipe_sync mepo_ui_menu_reposition_nominatim.sh] [];
 bind_button 0 -1 [Nm] [shellpipe_sync mepo_ui_menu_search_nominatim.sh] [];
 bind_button 0 -1 [Op] [shellpipe_sync mepo_ui_menu_search_overpass.sh] [];
 bind_button 0 -1 [Dl] [shellpipe_sync mepo_ui_menu_dbg_queuedownloadnoninteractive.sh] [];
 bind_button 1 -1 [~] [preftoggle overlay_pindetails_expanded] [];
 bind_button 1 -1 [Purge] [pin_purge] [];
 bind_button 1 -1 [Del] [pin_delete -1 []; pin_cycle 0 1; center_on_pin] [];
 bind_button 1 -1 [>] [pin_cycle 0 1; center_on_pin] [];
 bind_button 1 -1 [<] [pin_cycle 0 -1; center_on_pin] [];
 bind_button 1 9 [9] [pin_transfer -1 [] 9] [pin_transfer -1 [all] 9];
 bind_button 1 8 [8] [pin_transfer -1 [] 8] [pin_transfer -1 [all] 8];
 bind_button 1 7 [7] [pin_transfer -1 [] 7] [pin_transfer -1 [all] 7];
 bind_button 1 6 [6] [pin_transfer -1 [] 6] [pin_transfer -1 [all] 6];
 bind_button 1 5 [5] [pin_transfer -1 [] 5] [pin_transfer -1 [all] 5];
 bind_button 1 4 [4] [pin_transfer -1 [] 4] [pin_transfer -1 [all] 4];
 bind_button 1 3 [3] [pin_transfer -1 [] 3] [pin_transfer -1 [all] 3];
 bind_button 1 2 [2] [pin_transfer -1 [] 2] [pin_transfer -1 [all] 2];
 bind_button 1 1 [1] [pin_transfer -1 [] 1] [pin_transfer -1 [all] 1];
 bind_button 1 0 [0] [pin_transfer -1 [] 0] [pin_transfer -1 [all] 0];

 # Gestures;
 bind_gesture pan 2 1 [zoom_relative 1];
 bind_gesture pan 2 -1 [zoom_relative -1];
 bind_gesture rotate 3 1 [prefinc fontsize_ui 1];
 bind_gesture rotate 3 -1 [prefinc fontsize_ui -1];

 # Clickbindings;
 bind_click 1 -1 [shellpipe_sync mepo_ui_central_menu.sh];
 bind_click 1 2  [zoom_relative 1];
 bind_click 1 3  [zoom_relative -2];
 bind_click 2 1  [zoom_relative -1];

 # Keybindings;
 bind_key _ j [move_relative 0 10];
 bind_key s j [move_relative 0 100];
 bind_key _ k [move_relative 0 -10];
 bind_key s k [move_relative 0 -100];
 bind_key _ h [move_relative -10 0];
 bind_key s h [move_relative -100 0];
 bind_key _ l [move_relative 10 0];
 bind_key s l [move_relative 100 0];
 bind_key _ = [zoom_relative 1];
 bind_key _ - [zoom_relative -1];
 bind_key _ n [pin_cycle 1 1;];
 bind_key s n [pin_cycle 0 1; center_on_pin;];
 bind_key _ p [pin_cycle 1 -1;];
 bind_key s p [pin_cycle 0 -1; center_on_pin;];
 bind_key _ o [pin_deactivate];
 bind_key s o [pin_purge];
 bind_key _ w [cache_queueclear];
 bind_key c c [quit];
 bind_key _ y [clipcopy];
 bind_key s y [clippaste];
 bind_key c s [filedump rp $XDG_CACHE_HOME/mepo/savestate];
 bind_key cs s [fileload $XDG_CACHE_HOME/mepo/savestate];
 bind_key s = [prefinc fontsize_ui 1];
 bind_key s - [prefinc fontsize_ui -1];

 # Timers;
 bind_timer 20 [shellpipe_async 1 [mepo_ui_menu_user_pin_updater.sh droppin]];
 shellpipe_async 1 [mepo_ui_menu_user_pin_updater.sh droppin];

 # Scripts hotkeys;
 bind_key _ c [shellpipe_sync mepo_ui_central_menu.sh];
 bind_key _ f [shellpipe_async 0 mepo_ui_menu_pin_editor.sh];
 bind_key _ g [shellpipe_sync mepo_ui_menu_reposition_nominatim.sh];
 bind_key s g [shellpipe_sync mepo_ui_menu_search_nominatim.sh];
 bind_key _ b [shellpipe_sync mepo_ui_menu_search_overpass.sh];
 bind_key s r [shellpipe_sync mepo_ui_menu_route_overpassrelation.sh];
 bind_key _ r [shellpipe_sync mepo_ui_menu_route_graphhopper.sh];
 bind_key s z [shellpipe_sync mepo_ui_menu_pref_fontsize.sh];
 bind_key _ z [shellpipe_sync mepo_ui_menu_pref_zoom.sh];
 bind_key _ u [shellpipe_sync mepo_ui_menu_pref_url.sh];
 bind_key c f [shellpipe_sync  [DIM=h MULT=1  mepo_ui_helper_pref_pan.sh]];
 bind_key c b [shellpipe_sync  [DIM=h MULT=-1 mepo_ui_helper_pref_pan.sh]];
 bind_key cs f [shellpipe_sync [DIM=w MULT=1  mepo_ui_helper_pref_pan.sh]];
 bind_key cs b [shellpipe_sync [DIM=w MULT=-1 mepo_ui_helper_pref_pan.sh]];
 bind_key _ q [shellpipe_sync [mepo_ui_menu_dbg_queuedownloadinteractive.sh]];
 bind_key s q [shellpipe_sync [mepo_ui_menu_dbg_queuedownloadnoninteractive.sh]];
 bind_key _ x [shellpipe_sync [mepo_ui_menu_user_pin_updater.sh droppinactivateandcenter]];
 bind_key _ [1] [pin_groupactivate 0];
 bind_key _ [2] [pin_groupactivate 1];
 bind_key _ [3] [pin_groupactivate 2];
 bind_key _ [4] [pin_groupactivate 3];
 bind_key _ [5] [pin_groupactivate 4];
 bind_key _ [6] [pin_groupactivate 5];
 bind_key _ [7] [pin_groupactivate 6];
 bind_key _ [8] [pin_groupactivate 7];
 bind_key _ [9] [pin_groupactivate 8];
 bind_key _ [0] [pin_groupactivate 9];
 bind_key s [1] [pin_transfer -1 [] 0];
 bind_key s [2] [pin_transfer -1 [] 1];
 bind_key s [3] [pin_transfer -1 [] 2];
 bind_key s [4] [pin_transfer -1 [] 3];
 bind_key s [5] [pin_transfer -1 [] 4];
 bind_key s [6] [pin_transfer -1 [] 5];
 bind_key s [7] [pin_transfer -1 [] 6];
 bind_key s [8] [pin_transfer -1 [] 7];
 bind_key s [9] [pin_transfer -1 [] 8];
 bind_key s [0] [pin_transfer -1 [] 9];
 bind_key cs [1] [pin_transfer -1 [all] 0];
 bind_key cs [2] [pin_transfer -1 [all] 1];
 bind_key cs [3] [pin_transfer -1 [all] 2];
 bind_key cs [4] [pin_transfer -1 [all] 3];
 bind_key cs [5] [pin_transfer -1 [all] 4];
 bind_key cs [6] [pin_transfer -1 [all] 5];
 bind_key cs [7] [pin_transfer -1 [all] 6];
 bind_key cs [8] [pin_transfer -1 [all] 7];
 bind_key cs [9] [pin_transfer -1 [all] 8];
 bind_key cs [0] [pin_transfer -1 [all] 9];
 bind_key _ d [pin_delete -1 []; pin_cycle 0 1];
 bind_key s d [pin_purge];
 bind_key _ / [preftoggle help];
 bind_key _ e [preftoggle overlay_pindetails];
 bind_key _ s [preftoggle overlay_debugbar];
 bind_key _ m [preftoggle tile_cache_network];
 bind_key s c [center_on_mouse];

 # Signals;
 bind_signal USR1 [zoom_relative 1];
 bind_signal USR2 [zoom_relative -1];
 bind_signal TERM [quit];
 bind_signal INT  [quit];

 # Quit action;
 bind_quit [filedump rp $XDG_CACHE_HOME/mepo/savestate];

 # Prefs;
 prefset_n lat 40.78392;
 prefset_n lon -73.96442;
 prefset_n fontsize_ui 16;
 prefset_n distance_unit_tf_km_mi 1;
 prefset_n crosshair_size 15;
 prefset_n debug_message_enabled 1;
 prefset_n debug_stderr 0;
 prefset_n overlay_debugbar 1;
 prefset_n overlay_pindetails 1;
 prefset_n overlay_pindetails_expanded 1;
 prefset_n zoom 14;
 prefset_n tile_cache_network 1;
 prefset_n tile_cache_max_n_transfers 20;
 # E.g. default 30 day expiry: 60s * 60m * 24h * 30 days;
 prefset_n tile_cache_expiry_seconds 2592000;
 prefset_t tile_cache_dir $XDG_CACHE_HOME/mepo/tiles;
 prefset_t tile_cache_url https://tile.openstreetmap.org/%3$d/%1$d/%2$d.png;
 prefset_t pingroup_0_color #0000ff;
 prefset_t pingroup_1_color #116e0e;
 prefset_t pingroup_2_color #7502ab;
 prefset_t pingroup_3_color #cf0064;
 prefset_t pingroup_4_color #b89600;
 prefset_t pingroup_5_color #00b0aa;
 prefset_t pingroup_6_color #ff8308;
 prefset_t pingroup_7_color #004a0c;
 prefset_t pingroup_8_color #ff00a2;
 prefset_t pingroup_9_color #fff673;
 prefset_n pingroup_0_ordered 0;
 prefset_n pingroup_1_ordered 0;
 prefset_n pingroup_2_ordered 0;
 prefset_n pingroup_3_ordered 0;
 prefset_n pingroup_4_ordered 0;
 prefset_n pingroup_5_ordered 0;
 prefset_n pingroup_6_ordered 0;
 prefset_n pingroup_7_ordered 1;
 prefset_n pingroup_8_ordered 1;
 prefset_n pingroup_9_ordered 1;

 # User-customizable bookmarks / arbitrary mepolang file;
 fileload $XDG_CACHE_HOME/mepo/savestate;
 fileload $XDG_CONFIG_HOME/mepo/config;
 fileload $XDG_CONFIG_HOME/mepo/bookmarks;