Simple expression language for mapbox-gl-js expressions

‼️ This is an experimental repository, if you find it useful or interesting please leave a comment. There is a general discussion issue in issue #1, leave any general thoughts there. Or open a new issue for bugs or to suggest new features.

The primary aim of this language is to support MapboxGL expressions, although it should also be generally useful.

This is a tiny functional language that gets converted into MapboxGL expressions. The idea behind the language is that it can be converted in a lossless way between MapboxGL expressions and back again.

Basically it's just a nicer way to write MapboxGL expressions. Here's an example, the following JSON

[
  "interpolate",
  ["linear"], ["get", "score"],
  0, ["rgb", 255, 0, 0],
  50, ["rgb", 0, 255, 0],
  100, ["rgb", 0, 0, 255]
]

Would be written as

interpolate(
  linear(), @score,
  0, rgb(255, 0, 0),
  50, rgb(0, 255, 0),
  100, rgb(0, 0, 255)
)

See it in action: https://orangemug.github.io/simple-expr

To install

npm install orangemug/simple-expr --save

You are only allowed to define a single top level expression.

Valid

rgb(255, 0, 0)

Invalid!

rgb(255, 0, 0)
rgb(0, 0, 255)

Although sub expressions are allowed

rgb(get("rank"), 0, 0)

There are 2 basic types

Any integer or decimal number not in quotes, for example

1
-1
+3
3.14
-1000
-9.8

Any characters surrounded in quotes, for example

"foo bar"

You can escape quotes with \ for example

"They said \"it couldn't be done\""

Functions are defined as

function_name(arg, arg, arg...)

Note that arguments can also be functions. This gets compiled into the MapboxGL expressions JSON format.

Lets see an example

rgb(get("rating"), 0, 0)

Will become

["rgb", ["get", "rating"], 0, 0]

As well as using the get function (see spec) there is also a shorthand to reference feature data. The following

rgb(@rating, 0, 0)

Is the same as

rgb(get("rating"), 0, 0)

NOTE: Not yet available

You can also define variables before the expressions. Variables are also allowed to define a single expression. A quick example

&r = interpolate(
  linear(), @score,
  1, 100
  22, 255
)

rgb(&r, 0, 0)

Variables must start with a & both in there definition and their usage.

You can parse, compile to JSON. It comes in 2 forms, the CLI (command line interface) and the JavaScript API

var simpleExpr = require("simple-expr");
var out = simpleExpr.compile('concat("hello", " ", "world")', {format: "json"})
assert.deepEqual(out, [
  "concat", "hello", " ", "world"
])

var simpleExpr = require("simple-expr");
var tokens = simpleExpr.tokenize('*(2,2)')
var ast = simpleExpr.parse(tokens);

The available CLI commands are

simple-expr parse examples/concat.expr > /tmp/concat.ast

simple-expr compile examples/concat.expr > /tmp/concat.json
## >>/tmp/concat.json
## [
##   "concat",
##   "Hello",
##   " ",
##   [
##     "get",
##     "name"
##   ]
## ]
## <<

simple-expr decompile examples/concat.json > /tmp/concat.expr
## >>/tmp/concat.expr
## concat("Hello"," ",@name)
## <<

simple-expr execute --feature-props name=Maputnik examples/concat.expr > /tmp/concat.log
## >>/tmp/concat.log
## Hello Maputnik
## <<

MIT