@mapbox/expression-jamsession

0.5.0 • Public • Published

@mapbox/expression-jamsession

Build Status

Write Mapbox GL expressions in a more familiar, handwritable, spreadsheet-like, programming-like syntax. This library translates these handwritten formulas into valid spec-compliant Mapbox GL expressions that you can use in a Mapbox style.

Formula syntax features

  • Most expressions are represented like function invocations in programming, e.g. get("population"), log2(get("population")).
  • Symbolic math operators (+ - * / %) and parentheses work like in high school math, e.g. ((3 + 4) * 2) / 7. That is, the formula should contain 3 + 4 instead of +(3, 4).
  • Symbolic decision operators also work with operands on both sides, instead of like function invocations. So get("foo") != 4 instead of !=(get("foo"), 4).
  • Strings must always be wrapped in quotation marks, e.g. concat("egg", "s") not concat(egg, s).
  • & operator concatenates strings, as in spreadsheet programs.
// Input
2 + 2

// Output
["+", 2, 2]
// Input
max(3, log2(6))

// Output
["max", 3, ["log2", 6]]
// Input
((3 + get("num")) * 2) / 7

// Output
["/", ["*", ["+", 3, get("num")], 2], 7]
// Input
"name: " & get("name")

// Output
["concat", ["name ", ["get", "name"]]]

Usage

The module exports two functions so you can transform in both directions:

  • formulaToExpression transforms (string) formulas to (array) expressions.
  • expressionToFormula transforms expressions to formulas.
import jamsession from '@mapbox/expression-jamsession';

jamsession.formulaToExpression("3 + 4"); // ["+", 3, 4]

jamsession.expressionToFormula(["+", 3, 4]); // "3 + 4"

Browser compatibility

This library should work in IE11+. It uses a Set, so you might get it working in older browsers by adding a polyfill.

Caveats

  • You can use this library to create expressions that are syntactically acceptable but invalid as Mapbox GL expressions, e.g. get(true) outputs ["get", true], which fails.
  • You cannot use JSON object literal arguments to the literal expression. This is allowed in the spec; but objects are not supported by jsep and the use case for this type of expression is kind of an edge case — so it's probably not worth trying to adjust the parser to support this edge case. If you disagree, please consider filing an issue and/or PR.

Readme

Keywords

none

Package Sidebar

Install

npm i @mapbox/expression-jamsession

Weekly Downloads

373

Version

0.5.0

License

BSD-2-Clause

Unpacked Size

17.5 kB

Total Files

5

Last publish

Collaborators

  • mbx-npm-ci-production
  • mbx-npm-ci-staging
  • mbx-npm-advanced-actions-production
  • mbx-npm-advanced-actions-staging
  • mbx-npm-09-production
  • mbx-npm-08-production
  • mbx-npm-07-production
  • mbx-npm-06-production
  • mbx-npm-05-production
  • mbx-npm-04-production
  • mbx-npm-03-production
  • mbx-npm-02-production
  • mbx-npm-01-production
  • mbx-npm-02-staging
  • mapbox-npm-01
  • mapbox-npm-02
  • mapbox-npm-07
  • mapbox-npm-03
  • mapbox-npm-04
  • mapbox-npm-09
  • mapbox-npm-05
  • mapbox-npm-06
  • mapbox-npm-08
  • mapbox-npm-advanced-actions
  • mapbox-npm-ci
  • mapbox-npm
  • mapbox-admin
  • mapbox-machine-user