path: root/src/Mapbox/Expression.elm

module Mapbox.Expression
    exposing
        ( Anchor
        , Auto
        , CameraExpression
        , Collator
        , Color
        , DataExpression
        , Expression
        , FormattedString
        , FormattedText
        , Interpolation(..)
        , LineCap
        , LineJoin
        , Object
        , Position
        , RasterResampling
        , SymbolPlacement
        , TextFit
        , TextJustify
        , TextTransform
        , abs
        , acos
        , all
        , anchorAuto
        , anchorMap
        , anchorViewport
        , any
        , append
        , asin
        , assertArray
        , assertArrayOfBools
        , assertArrayOfFloats
        , assertArrayOfStrings
        , assertBool
        , assertFloat
        , assertObject
        , assertString
        , at
        , atan
        , bool
        , ceil
        , coalesce
        , collator
        , conditionally
        , cos
        , count
        , defaultCollator
        , divideBy
        , downcase
        , e
        , encode
        , false
        , featureState
        , float
        , floats
        , floor
        , fontScaledBy
        , format
        , formatted
        , geometryType
        , get
        , getProperty
        , greaterThan
        , greaterThanOrEqual
        , greaterThanOrEqualWithCollator
        , greaterThanWithCollator
        , has
        , hasProperty
        , heatmapDensity
        , id
        , ifElse
        , int
        , interpolate
        , isEqual
        , isEqualWithCollator
        , isSupportedScript
        , length
        , lessThan
        , lessThanOrEqual
        , lessThanOrEqualWithCollator
        , lessThanWithCollator
        , lineCapButt
        , lineCapRound
        , lineCapSquare
        , lineJoinBevel
        , lineJoinMiter
        , lineJoinRound
        , lineProgress
        , ln
        , ln2
        , log10
        , log2
        , makeRGBAColor
        , makeRGBColor
        , matchesFloat
        , matchesStr
        , minus
        , modBy
        , multiply
        , not
        , notEqual
        , notEqualWithCollator
        , object
        , pi
        , plus
        , positionBottom
        , positionBottomLeft
        , positionBottomRight
        , positionCenter
        , positionLeft
        , positionRight
        , positionTop
        , positionTopLeft
        , positionTopRight
        , properties
        , raiseBy
        , rasterResamplingLinear
        , rasterResamplingNearest
        , resolvedLocale
        , rgba
        , rgbaChannels
        , round
        , sin
        , sqrt
        , step
        , str
        , strings
        , symbolPlacementLine
        , symbolPlacementLineCenter
        , symbolPlacementPoint
        , tan
        , textFitBoth
        , textFitHeight
        , textFitNone
        , textFitWidth
        , textJustifyCenter
        , textJustifyLeft
        , textJustifyRight
        , textTransformLowercase
        , textTransformNone
        , textTransformUppercase
        , toBool
        , toColor
        , toFloat
        , toString
        , true
        , typeof
        , upcase
        , withFont
        , zoom
        )

{-| Expressions form a little language that can be used to compute values for various layer properties.

It is recommended to import them in the following fashion:

    import Mapbox.Expression as E exposing (Expression, CameraExpression, DataExpression, str, float, int, true, false)

This way you can use the language without much syntactic fuss and you have easy access to the literals.


### Example

You'd like to adjust font size of a town based on the number of people who live there. In plain Elm, you might wright the following function:

    sizeByPopulation : Dict String Int -> Int
    sizeByPopulation properties =
        Dict.get "population" properties
            |> Maybe.withDefault 1000
            |> scale ( 0, 1000 ) ( 9, 20 )

In the expression language you can do this in a similar fassion:

    sizeByPopulation : Expression DataExpression Float
    sizeByPopulation =
        E.getProperty "population"
            |> E.toFloat 1000
            |> E.interpolate E.Linear
                [ ( 0, int 9 )
                , ( 1000, int 20 )
                ]

**Note**: If you are familiar with the JS version of the style spec,
we have made a few changes. Argument order has been switched for many functions to support using pipeline style more naturally. Some functions use overloading in the original, these have been renamed to
not be overloaded. Finally, we have chosen not to represent some parts of the spec that are superflous (especially when used from Elm), namely functions and let-in expressions.

@docs Expression, DataExpression, CameraExpression

@docs encode


### Types

All of the types used as expression results are phantom (i.e. they don't have any runtime values but are used purely for compile-time checking). As such we use a mix of standard elm types for their familiarty:

  - `Float`
  - `String`
  - `Array`
  - `Bool`

We introduce the following types:

@docs Color, Object, Collator, FormattedText

(And also a bunch of Enum types, that will be documented in the Enums section).

You can use the following functions to transfer Elm values into the Expression language:

@docs true, false, bool, int, float, str, rgba, floats, strings, object, collator, defaultCollator

In some cases, you will need to force the type system to cooperate.
The following assertions will force the type and cause a run-time error
if the type is wrong:

@docs assertArray, assertArrayOfStrings, assertArrayOfFloats, assertArrayOfBools, assertBool, assertFloat, assertObject, assertString

You can also use these functions to explicitly cast to a particular type:

@docs toBool, toColor, toFloat, toString

@docs typeof


### Lookup

@docs at, get, has, count, length


### Feature data

@docs featureState, geometryType, id, properties, getProperty, hasProperty


### Decision

The expressions in this section can be used to add conditional logic to your styles.

@docs isEqual, notEqual, lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual

Strings can be compared with a collator for locale specific comparisons:

@docs isEqualWithCollator, notEqualWithCollator, lessThanWithCollator, lessThanOrEqualWithCollator, greaterThanWithCollator, greaterThanOrEqualWithCollator

Logical operators:

@docs not, all, any

Control flow:

@docs ifElse, conditionally, matchesStr, matchesFloat, coalesce


### Ramps, scales, curves

@docs interpolate, Interpolation, step


### String

@docs append, downcase, upcase, isSupportedScript, resolvedLocale


### Formatted Text

@docs format, FormattedString, formatted, fontScaledBy, withFont


### Color

@docs makeRGBColor, makeRGBAColor, rgbaChannels


### Math

@docs minus, multiply, divideBy, modBy, plus, raiseBy, sqrt, abs, ceil, floor, round, cos, sin, tan, acos, asin, atan, e, pi, ln, ln2, log10, log2


### Zoom

@docs zoom


### Heatmap

@docs heatmapDensity, lineProgress


### Enums

These are required for various layer properties.

@docs Anchor, anchorMap, anchorViewport, anchorAuto, Auto, Position, positionCenter, positionLeft, positionRight, positionTop, positionBottom, positionTopLeft, positionTopRight, positionBottomLeft, positionBottomRight, TextFit, textFitNone, textFitWidth, textFitHeight, textFitBoth, LineCap, lineCapButt, lineCapRound, lineCapSquare, LineJoin, lineJoinBevel, lineJoinRound, lineJoinMiter, SymbolPlacement, symbolPlacementPoint, symbolPlacementLine, symbolPlacementLineCenter, TextJustify, textJustifyLeft, textJustifyCenter, textJustifyRight, TextTransform, textTransformNone, textTransformUppercase, textTransformLowercase, RasterResampling, rasterResamplingLinear, rasterResamplingNearest

-}

import Array exposing (Array)
import Json.Encode exposing (Value)


{-| Expressions are zero overhead wrappers over the underlying JSON language that attempt to provide some type safety.

Note however, that while being a strictly typed language, it has slighlty different semantics tham Elm:

  - There is only a single number type. I have denoted it `Float`. You will notice that the `int` function takes an Elm int
    value and converts it to an `Expression expr Float`.
  - All values may be `null`. There is no `Maybe` type. You can