Install aftermarket expression functions (#11472)

* [ios, macos] Introduced more ergonomic expression concatenation syntax

* [ios, macos] Fixed mgl_join:

* [ios, macos] Simplified expression document headings

* [ios, macos] Documented mgl_join:

* [ios, macos] Convert length operator to length: for strings

Only works for literal strings.

* [ios, macos] Implemented type conversion using CAST()

* [ios, macos] Aftermarket let expressions

* [ios, macos] Refactored aftermarket expression functions

Refactored the installation of aftermarket expression functions to use macros. It is no longer necessary to handwrite the type encoding of a function. Also added aftermarket functions for interpolating and stepping.

* [ios, macos] Updated documentation, tests, demo apps

* [ios, macos] Added generic expression function

* [ios, macos] Add MGL_MATCH function placeholder.

* [ios, macos] Add MGL_SWITCH expression operator.

* [ios, macos] Add mgl_coalesce: as expression function.

* [ios, macos] Update style documentation.

* [ios, macos] Add conventional custom function support.

* [ios, macos] Updated example code

* [ios, macos] Add mgl_coalesce conventional custom function support.

* [ios, macos] Add aftermarket function to 'has' operator.

* [ios, macos] Add documentation for lookup and feature operators.

* [ios, macos] Documented simple lookup

* [ios, macos] Renamed, reversed has expression

Renamed mgl_hasProperty:properties: to mgl_does:have: for better readability and consistency with the conventional mgl_has: function. Documented both forms of mgl_has:.

* [ios, macos] Restored OEM conditionals where available

This is the preferred syntax for simple conditionals on iOS 9 and above, because you can inline the predicate instead of wrapping it in a constant value expression, which means you can write a conditional in a single format string.

* [ios, macos] Update style docs.

Co-authored-by: Fabian Guerra <fabian.guerra@mapbox.com>

1 files changed, 22 insertions, 14 deletions

diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
index 2ba7757fdf..45cfa105b8 100644
--- a/platform/darwin/docs/guides/For Style Authors.md.ejs
+++ b/platform/darwin/docs/guides/For Style Authors.md.ejs
@@ -321,6 +321,11 @@ iOS.
 <% } -%>
 ### Expression operators
 
+Many expression operators defined in the style specification have corresponding
+symbols to be used with the `+[NSExpression expressionWithFormat:]`,
+`+[NSExpression expressionForFunction:arguments:]`, or
+`+[NSExpression expressionForFunction:selectorName:arguments:]` method:
+
 In style specification | Method, function, or predicate type | Format string syntax
 -----------------------|-------------------------------------|---------------------
 `array`                | |
@@ -330,15 +335,15 @@ In style specification | Method, function, or predicate type | Format string syn
 `string`               | |
 `to-boolean`           | `boolValue` |
 `to-color`             | |
-`to-number`            | `mgl_numberWithFallbackValues:` |
-`to-string`            | `stringValue` |
+`to-number`            | `mgl_numberWithFallbackValues:` | `CAST(zipCode, 'NSNumber')`
+`to-string`            | `stringValue` | `CAST(ele, 'NSString')`
 `typeof`               | |
-`geometry-type`        | |
-`id`                   | |
-`properties`           | |
-`at`                   | |
+`geometry-type`        | |`$mgl_geometryType`
+`id`                   | |`$mgl_featureIdentifier`
+`properties`           | |`$mgl_featureProperties`
+`at`                   | `objectFrom:withIndex:` | `array[n]`
 `get`                  | `+[NSExpression expressionForKeyPath:]` | Key path
-`has`                  | |
+`has`                  | `mgl_does:have:` | `mgl_does:have:(self, 'key')`
 `length`               | `count:` | `count({1, 2, 2, 3, 4, 7, 9})`
 `!`                    | `NSNotPredicateType` | `NOT (p0 OR … OR pn)`
 `!=`                   | `NSNotEqualToPredicateOperatorType` | `key != value`
@@ -349,14 +354,14 @@ In style specification | Method, function, or predicate type | Format string syn
 `>=`                   | `NSGreaterThanOrEqualToPredicateOperatorType` | `key >= value`
 `all`                  | `NSAndPredicateType` | `p0 AND … AND pn`
 `any`                  | `NSOrPredicateType` | `p0 OR … OR pn`
-`case`                 | `+[NSExpression expressionForConditional:trueExpression:falseExpression:]` | `TERNARY(condition, trueExpression, falseExpression)`
-`coalesce`             | |
-`match`                | |
-`interpolate`          | `mgl_interpolateWithCurveType:parameters:stops:` |
-`step`                 | `mgl_stepWithMinimum:stops:` |
-`let`                  | `mgl_expressionWithContext:` |
+`case`                 | `+[NSExpression expressionForConditional:trueExpression:falseExpression:]` or `MGL_IF` | `TERNARY(1 = 2, YES, NO)` or `MGL_IF(1 = 2, YES, 2 = 2, YES, NO)`
+`coalesce`             | `mgl_coalesce:` | `mgl_coalesce({x, y, z})`
+`match`                | `MGL_MATCH` | `MGL_MATCH(x, 0, 'zero match', 1, 'one match', 'two match', 'default')`
+`interpolate`          | `mgl_interpolate:withCurveType:parameters:stops:` |
+`step`                 | `mgl_step:withMinimum:stops:` |
+`let`                  | `mgl_expressionWithContext:` | `MGL_LET('ios', 11, 'macos', 10.13, $ios + $macos)`
 `var`                  | `+[NSExpression expressionForVariable:]` | `$variable`
-`concat`               | `stringByAppendingString:` |
+`concat`               | `mgl_join:` | `mgl_join({'Old', ' ', 'MacDonald'})`
 `downcase`             | `lowercase:` | `lowercase('DOWNTOWN')`
 `upcase`               | `uppercase:` | `uppercase('Elysian Fields')`
 <% if (macOS) { -%>
@@ -391,6 +396,9 @@ In style specification | Method, function, or predicate type | Format string syn
 `zoom`                 | | `$zoom`
 `heatmap-density`      | | `$heatmapDensity`
 
+For operators that have no corresponding `NSExpression` symbol, use the
+`MGL_FUNCTION()` format string syntax.
+
 ## Filtering sources
 
 You can filter a shape or vector source by setting the