Install aftermarket expression functions #11472

1ec5 · 2018-03-16T18:00:19Z

Install Mapbox-specific functions as first-class NSExpression functions, prefixed to avoid collisions with any additional functions that may be built into NSExpression in the future. Various functions need to be renamed because the aftermarket variant no longer takes an explicit operand.

The result of this PR is that nontrivial expression usage will be a lot more legible and easier to write by hand without frequently consulting a reference. For example, concatenating strings goes from:

[NSExpression expressionWithFormat:@"FUNCTION('Old', 'stringByAppendingString:', ' ', 'MacDonald')"]

to:

[NSExpression expressionWithFormat:@"mgl_join({'Old', ' ', 'MacDonald'})"]

Fixes #11015.

/cc @fabian-guerra @jmkiley @akitchen

1ec5 · 2018-03-19T17:18:01Z

f66b1ee converts length JSON expressions to length: NSExpressions for an expression that gets the length of a constant string, but not for an expression that gets the length of an expression that evaluates to a string.

fabian-guerra

Do you think that the following PRs are complementary to this PR?
#11464
#11450

To me seems like it and it would be good if we merge them.

1ec5 · 2018-03-23T08:53:36Z

Yes, they are complementary, but I don’t think they have to be coupled. We’re still going to need conventional functions, just in case the mechanism in this PR breaks for any reason. I’ve added items to the to-do list above for those PRs, in case I get to them first.

1ec5 · 2018-03-27T02:02:22Z

Thinking about this for a moment:

Safeguard against changes to NSExpression that render this approach ineffective

+[NSExpression mgl_expressionWithJSONObject:] uses the aftermarket functions to create the NSExpression object. This way the developer isn’t forced to work with the clunkier custom function syntax when using the style layer properties’ getters, and we can easily verify that expressions round-trip. But if the aftermarket installation mechanism fails for any reason, this is the code that’ll fail. I suppose we could catch the NSException that arises and use the custom function syntax in that case? I’m not keen on using a @try-@catch block, but exception handling is the roughest edge of NSExpression.

1ec5 · 2018-03-27T07:56:20Z

0203d2d819f3c335c84e7db932953b30ad5f773f implements a catch-all MGL_FUNCTION() function, replacing assertions that used to fail for unrecognized expression operators. Now it’s possible to represent the entire GL expression language within an NSExpression. (Not sure about the naming of this function; it could just as well be called NS_EXPRESSION().)

1ec5 · 2018-03-27T21:23:02Z

platform/darwin/src/NSExpression+MGLAdditions.mm


    // Install functions that resemble control structures, taking arbitrary
    // numbers of arguments. Vararg aftermarket functions need to be declared
    // with an explicit and implicit first argument.
    INSTALL_CONTROL_STRUCTURE(MGL_LET);
+    INSTALL_CONTROL_STRUCTURE(MGL_MATCH);
+    INSTALL_CONTROL_STRUCTURE(MGL_SWITCH);


I suggested MGL_MATCH and MGL_SWITCH as counterparts to mgl_match: and mgl_case:, respectively, but I think I got mixed up. MGL_SWITCH implies the same semantics as MGL_MATCH. I do think “case” would be problematic, as it makes it impossible to refer to the cases inside the expression. “Ternary” is also problematic because there can be multiple cases. Do you think MGL_CONDITION or MGL_IF could work?

I think MGL_IF will do the work. It's more descriptive to what the function actually does.

1ec5 · 2018-03-27T21:26:43Z

platform/darwin/src/NSExpression+MGLAdditions.mm

@@ -792,19 +820,19 @@ - (id)mgl_jsonExpressionObject {
                }

                return expressionObject;
-            } else if ([function isEqualToString:@"mgl_match:"]) {
-                NSMutableArray *expressionObject = [NSMutableArray arrayWithObjects:@"match", self.operand.mgl_jsonExpressionObject, nil];
+            } else if ([function isEqualToString:@"MGL_MATCH"]) {


This removes support for the conventional custom function mgl_match:. In this PR, I’ve left in support for those functions, just in case aftermarket expressions break with a new iOS SDK version. (I’ve equivocated about whether to remove public documentation about the conventional functions, but the implementations remain.) See the methods at the bottom of this file for an example of how to support both versions of the method simultaneously.

1ec5 · 2018-03-27T21:27:27Z

platform/darwin/docs/guides/For Style Authors.md.ejs

@@ -352,11 +357,11 @@ In style specification | Method, function, or predicate type | Format string syn
 `case`                 | `+[NSExpression expressionForConditional:trueExpression:falseExpression:]` | `TERNARY(condition, trueExpression, falseExpression)`
 `coalesce`             | |
 `match`                | |


These rows need to be updated.

1ec5 · 2018-03-27T21:28:03Z

platform/darwin/docs/guides/Predicates and Expressions.md

+`mgl_interpolate:withCurveType:parameters:stops:` | `mgl_interpolate:withCurveType:parameters:stops:(x, 'linear', nil, %@)` | Produces continuous, smooth results by interpolating between pairs of input and output values (“stops”). Compared to the `mgl_interpolateWithCurveType:parameters:stops:` custom function, the input expression (that function’s target) is instead passed in as the first argument to this function.
+`mgl_step:from:stops:` | `mgl_step:from:stops:(x, 11, %@)` |Produces discrete, stepped results by evaluating a piecewise-constant function defined by pairs of input and output values ("stops"). Compared to the `mgl_stepWithMinimum:stops:` custom function, the input expression (that function’s target) is instead passed in as the first argument to this function.
+`mgl_join:` | `mgl_join({'Old', 'MacDonald'})` | Returns the result of concatenating together all the elements of an array in order. Compared to the `stringByAppendingString:` custom function, this function takes only one argument, which is an aggregate expression containing the strings to concatenate.
+`MGL_LET` | `MGL_LET('age', uppercase('old'), 'name', uppercase('MacDonald'), mgl_join({$age, $name}))` | Any number of variable names interspersed with their assigned `NSExpression` values, followed by an `NSExpression` that may contain references to those variables. Compared to the `mgl_expressionWithContext:` custom function, this function takes the variable names and values inline before the expression that contains references to those variables.


Rows need to be added for MGL_MATCH, MGL_SWITCH, and mgl_coalesce:.

1ec5 · 2018-03-27T21:29:06Z

platform/ios/docs/guides/Using Style Functions at Runtime.md

@@ -111,7 +111,7 @@ let stops: [Float: UIColor] = [
    10: .white,
 ]

-layer.circleColor = NSExpression(format: "FUNCTION(mag, 'mgl_stepWithMinimum:stops:', %@, %@)",
+layer.circleColor = NSExpression(format: "mgl_step:from:stops:(mag, %@, %@)",
                                 UIColor.green, stops)
 ```



Right below here is an example that could potentially use MGL_MATCH. On the other hand, I do find the use of a dictionary with valueForKeyPath: to be somewhat elegant, so perhaps all it needs is a call to mgl_coalesce: to avoid the redundant valueForKeyPath: call.

1ec5 · 2018-03-28T22:20:34Z

But if the aftermarket installation mechanism fails for any reason, this is the code that’ll fail.

Per chat with @fabian-guerra, we’re going to consider this defensive approach for a followup release, possibly on hold until we know there’s going to be a problem with an upcoming version of iOS or macOS. The existing code is already resilient to minor changes like the private class being renamed, just not to more substantial, public-facing changes to NSExpression.

Only works for literal strings.

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:.

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.

1ec5 · 2018-03-29T11:25:44Z

platform/darwin/docs/guides/For Style Authors.md.ejs

@@ -343,7 +343,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `properties`           | |`$mgl_featureProperties`
 `at`                   | `objectFrom:withIndex:` | `array[n]`
 `get`                  | `+[NSExpression expressionForKeyPath:]` | Key path
-`has`                  | `mgl_hasProperty:properties:` |
+`has`                  | `mgl_does:have:` | `mgl_does:have:(self, 'key')`


I renamed and reordered this function. Instead of calling mgl_hasProperty:properties:('key', self), you call mgl_does:have:(self, 'key'). I think this reads better: “Does self have ‘key’?” It’s also consistent with the order when you call the conventional function: FUNCTION(self, 'mgl_has:', 'key').

1ec5 · 2018-03-29T11:27:55Z

platform/darwin/docs/guides/For Style Authors.md.ejs

@@ -354,7 +354,7 @@ 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`                 | `MGL_IF` | `MGL_IF(1 = 2, YES, 2 = 2, YES, NO)` 
+`case`                 | `+[NSExpression expressionForConditional:trueExpression:falseExpression:]` or `MGL_IF` | `TERNARY(1 = 2, YES, NO)` or `MGL_IF(1 = 2, YES, 2 = 2, YES, NO)`


I restored full support for +[NSExpression expressionForConditional:trueExpression:falseExpression:] where available, along with the tests for it. On iOS 9.0 and above, we convert case to TERNARY() when it has only one conditional. This is the preferred syntax, 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.

/cc @friedbunny

friedbunny · 2018-03-29T17:37:04Z

The code ticks in the table at platform/darwin/docs/guides/Predicates and Expressions.md#L195 aren’t converted automatically to <code>, so we’ll need to do some follow-up.

1ec5 added feature iOS Mapbox Maps SDK for iOS refactor macOS Mapbox Maps SDK for macOS ⚠️ DO NOT MERGE Work in progress, proof of concept, or on hold runtime styling labels Mar 16, 2018

1ec5 added this to the ios-v4.0.0 milestone Mar 16, 2018

1ec5 self-assigned this Mar 16, 2018

fabian-guerra mentioned this pull request Mar 19, 2018

[ios, macos] Add match expressions support. #11464

Merged

3 tasks

1ec5 mentioned this pull request Mar 21, 2018

Adds support for running Mapbox-gl-js expressions tests against the Objective-C expressions interface #11435

Closed

fabian-guerra reviewed Mar 22, 2018

View reviewed changes

1ec5 mentioned this pull request Mar 23, 2018

[ios, macos] Change the format for case expressions to a flat structure. #11450

Merged

4 tasks

1ec5 force-pushed the 1ec5-freedom-of-nsexpression-11015 branch from e82177e to 15bf3d0 Compare March 26, 2018 21:37

1ec5 force-pushed the 1ec5-freedom-of-nsexpression-11015 branch from c989d11 to 8df1e98 Compare March 27, 2018 06:00

1ec5 mentioned this pull request Mar 27, 2018

Crash calling -expressionValueWithObject:context: on vararg expression functions #11541

Open

1ec5 commented Mar 27, 2018

View reviewed changes

1ec5 assigned fabian-guerra Mar 27, 2018

1ec5 mentioned this pull request Mar 28, 2018

Add NSPredicate-specific operators to NSExpression #11013

Closed

3 tasks

1ec5 added 6 commits March 28, 2018 19:31

[ios, macos] Introduced more ergonomic expression concatenation syntax

09810d5

[ios, macos] Fixed mgl_join:

f10402d

[ios, macos] Simplified expression document headings

5ce7411

[ios, macos] Documented mgl_join:

3f02c5e

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

38c31dd

Only works for literal strings.

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

66648e5

1ec5 and others added 4 commits March 28, 2018 19:40

[ios, macos] Updated example code

8d19aaa

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

79844eb

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

0a9b7a0

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

a51ae90

fabian-guerra force-pushed the 1ec5-freedom-of-nsexpression-11015 branch from 8874184 to a51ae90 Compare March 29, 2018 01:40

1ec5 added 3 commits March 29, 2018 04:09

[ios, macos] Documented simple lookup

2625c7c

[ios, macos] Renamed, reversed has expression

72499da

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

9c70d38

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.

1ec5 commented Mar 29, 2018

View reviewed changes

1ec5 removed the ⚠️ DO NOT MERGE Work in progress, proof of concept, or on hold label Mar 29, 2018

1ec5 requested review from friedbunny and fabian-guerra March 29, 2018 11:28

[ios, macos] Update style docs.

5bb9ca2

fabian-guerra approved these changes Mar 29, 2018

View reviewed changes

1ec5 merged commit 8c5eb6c into release-boba Mar 29, 2018

1ec5 deleted the 1ec5-freedom-of-nsexpression-11015 branch March 29, 2018 17:25

1ec5 mentioned this pull request Mar 29, 2018

Convert length expression operator to length: function for non-constant strings #11558

Open

fabian-guerra mentioned this pull request Mar 29, 2018

Streamline custom function syntax for NSExpression #11015

Closed

friedbunny mentioned this pull request Mar 30, 2018

[ios, docs] Fix formatting in Predicates & Expressions guide #11574

Merged

This was referenced Apr 4, 2018

[WIP] V4.0.0 expressions mapbox/ios-sdk-examples#143

Merged

[ios, macos] Add predicate like expressions to NSExpression #11632

Merged

Add abs, round, floor, ceil operators #11653

Merged

This was referenced Apr 14, 2018

Add alternative variable reference syntax for NSExpression #11010

Closed

Remove mgl_ prefix from built-in expression variables #11683

Closed

Expression transformations #10944

Closed

1ec5 mentioned this pull request May 8, 2018

Bend NSExpression syntax to accomodate Studio expression syntax #11053

Closed

1ec5 mentioned this pull request Apr 18, 2020

Top-level aftermarket expression functions fail to parse mapbox/mapbox-gl-native-ios#271

Open

1ec5 mentioned this pull request Feb 17, 2023

Refactor NSExpression unit tests maplibre/maplibre-native#421

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Install aftermarket expression functions #11472

Install aftermarket expression functions #11472

1ec5 commented Mar 16, 2018 •

edited

Loading

1ec5 commented Mar 19, 2018

fabian-guerra left a comment

1ec5 commented Mar 23, 2018

1ec5 commented Mar 27, 2018

1ec5 commented Mar 27, 2018

1ec5 Mar 27, 2018

fabian-guerra Mar 27, 2018

1ec5 Mar 27, 2018

1ec5 Mar 27, 2018

1ec5 Mar 27, 2018

1ec5 Mar 27, 2018

1ec5 commented Mar 28, 2018 •

edited

Loading

1ec5 Mar 29, 2018

1ec5 Mar 29, 2018 •

edited

Loading

friedbunny commented Mar 29, 2018

Install aftermarket expression functions #11472

Install aftermarket expression functions #11472

Conversation

1ec5 commented Mar 16, 2018 • edited Loading

1ec5 commented Mar 19, 2018

fabian-guerra left a comment

Choose a reason for hiding this comment

1ec5 commented Mar 23, 2018

1ec5 commented Mar 27, 2018

1ec5 commented Mar 27, 2018

1ec5 Mar 27, 2018

Choose a reason for hiding this comment

fabian-guerra Mar 27, 2018

Choose a reason for hiding this comment

1ec5 Mar 27, 2018

Choose a reason for hiding this comment

1ec5 Mar 27, 2018

Choose a reason for hiding this comment

1ec5 Mar 27, 2018

Choose a reason for hiding this comment

1ec5 Mar 27, 2018

Choose a reason for hiding this comment

1ec5 commented Mar 28, 2018 • edited Loading

1ec5 Mar 29, 2018

Choose a reason for hiding this comment

1ec5 Mar 29, 2018 • edited Loading

Choose a reason for hiding this comment

friedbunny commented Mar 29, 2018

1ec5 commented Mar 16, 2018 •

edited

Loading

1ec5 commented Mar 28, 2018 •

edited

Loading

1ec5 Mar 29, 2018 •

edited

Loading