draft of expressions examples doc #4836

nickidlugash · 2017-06-15T00:12:15Z

@anandthakker as discussed, here's a doc with some practical examples of expressions. If any of the syntax is incorrect please update 🙏

I wasn't sure where to put the file, so please move it if you wish.

* Add draft proposal for property expressions spec Developed in #4715 * Update spec proposal * Introduce `curve` expression, use it to cover zoom function `stops`. * Introduce object and array literals * Remove explicitly typed property lookup * Describe type system * Remove ["else"] * Minor edits

anandthakker

Thanks @nickidlugash! These are super helpful -- some comments inline.

anandthakker · 2017-06-19T13:34:31Z

docs/style-spec/expressions-examples.md

+	"icon-image": {
+		"expression" : [
+				"concat",["string", ["get", ["properties"], "shield"]], "-", ["string", ["get", ["properties"], "ref"]]
+		]


Is the after the "-" supposed to be wrapped in length, like ["length", ["string", ["get", ["properties"], "ref"]]?

oops, no – that property should be reflen, which is the same thing as ^, pre-calculated in the data, and with the exception that values of 1 become 2 (because we use the same icon for both). I don't know yet if we would consider dropping this property in favor of using length (since we have users of our tiles that don't use Mapbox GL), but I'll try rewriting this expression to use length anyway, as an example.

anandthakker · 2017-06-19T13:38:53Z

docs/style-spec/expressions-examples.md

+				"city-dot-small" 
+			]
+		]	
+	}


You could use a "step" curve here as well:

[ "curve", ["step"], 0, ["case", ["==", ["number", ["get", ["properties"], "capital"]], 2], "capital-city-dot-large", "city-dot-large" ], 2, ["case", ["==", ["number", ["get", ["properties"], "capital"]], 2], "capital-city-dot-medium", "city-dot-medium" ], 5, ["case", ["==", ["number", ["get", ["properties"], "capital"]], 2], "capital-city-dot-small", "city-dot-small" ] ]

Ah, except for one thing: as of now, step curves (like their predecessor, interval functions) use intervals that are inclusive of the left-hand boundary and exclusive of the right-hand one. We could make this configurable (["step", ">"] / ["step", ">="]), or we could just rely on a workaround like using 2.001 instead of 2 as the step value.

for this example (since the values are integers), I think the steps: 0, 3, 6 would be the same as the current case expression?

anandthakker · 2017-06-19T13:39:30Z

docs/style-spec/expressions-examples.md

+					["<=", ["number", ["get", ["properties"], "scalerank"]], 5],
+					9,
+					[">", ["number", ["get", ["properties"], "scalerank"]], 5],
+					6


Similarly, this case could be a step curve instead.

anandthakker · 2017-06-19T13:43:47Z

docs/style-spec/expressions-examples.md

+		"expression": [
+			"curve", "step", ["zoom"],
+				7, 
+				["match", ["get", ["properties"], "ldir"],


the ["get", ... here should be wrapped in a ["string", ...

anandthakker · 2017-06-19T13:44:28Z

docs/style-spec/expressions-examples.md

+					"S", "center",
+					"SW", "right",
+					"W", "right",
+					"NW", "right"


Needs a final output value in case ldir doesn't match one of these values.

@anandthakker ah, just realizing now that y_else is specified for match. Should I add a final output value to all the match expressions in this file? Is it an invalid expression if the final output value is not included?

Yah, it'll fail validation if not included

jfirebaugh · 2017-06-19T18:12:11Z

Thanks for these examples @nickidlugash -- very instructive to look at some real use cases. The first thing that jumps out at me is that while our current syntax enables a lot of flexibility, it leave a lot to be desired in terms of ergonomics and concision. It's never too early to begin thinking about how we could improve this, so here are the things that come to my mind:

Reverse the order of arguments to "has" and "get", and make ["properties"] the default for what becomes the final argument. So ["has", ["properties"], "foo"] ⇢ ["has", "foo"]. This simple change would probably halve the length of many of these examples.
As previously discussed, it's probably worthwhile to have a "coalesce" expression (returns the first non-error value in a sequence of subexpressions) as sugar for chained "has" inside "case".
We're almost certainly going to want to add local identifier bindings -- "let" -- at some point, so that common subexpressions don't have to be repeated within more complex expressions. This in turn may require us to relax the restriction on where ["zoom"] can appear. For example, in the city labels examples, you'd want to be able to write:
```
["let", "scalerank", ["number", ["get", ["properties"], "scalerank"]],
   ["curve", "exponential", 0.85, ["zoom"], ... expressions using "scalerank" ...]]
```

nickidlugash · 2017-06-19T18:14:52Z

docs/style-spec/expressions-examples.md

+					22,
+					[">", ["number", ["get", ["properties"], "scalerank"]], 5],
+					22
+				],


@anandthakker Can I drop this second case expression and just make this value: 14, 22 ? Will the renderers be able to calculate an exponential curve like this?

Ah hah -- yep! that should work!

…"case" expressions with comparisons to "step curves", adding final output values for all "match" expressions, adding missing type conversion, fixing highway shield icon-image example to use "length"

nickidlugash · 2017-06-19T20:04:00Z

Reverse the order of arguments to "has" and "get", and make ["properties"] the default for what becomes the final argument.

@anandthakker @jfirebaugh what are the other available options besides ["properties"] for these expressions?

it's probably worthwhile to have a "coalesce" expression (returns the first non-error value in a sequence of subexpressions) as sugar for chained "has" inside "case".

I anticipate that this will be a fairly commonly used syntax pattern for our core styles.

I'm happy to keep these examples updated as we make any improvements to the syntax. (@anandthakker up to you if you want to merge this in once all the expressions are valid/optimal according to the latest syntax definitions, or if you want to keep this separate for now). This exercise has been super helpful for me for thinking through the future of our core styles as well 🌅

anandthakker · 2017-06-19T20:16:05Z

what are the other available options besides ["properties"] for these expressions?

The only immediate example I know of would be if a feature property value were to be a nested object (technically possible in GeoJSON, and maybe in the future in vector tiles as well). E.g. {"properties": { "my_data": { "x": 1, "y": 2 } }, and something like ["get", ["object", ["get", ["properties"], "my_data"], "x"].

up to you if you want to merge this in once all the expressions are valid/optimal according to the latest syntax definitions, or if you want to keep this separate for now

I wonder if it would be worthwhile to make these into integration test cases like the ones added in 63e4c64. That would let us keep checking the syntax, and also to include expected input/output values to confirm that the functions really do behave the way we think.

nickidlugash · 2017-06-21T23:10:28Z

I wonder if it would be worthwhile to make these into integration test cases

Could be a good idea! Based on the master DDS-tracking ticket, some of the style properties used in this example page (text-anchor, text-justify) have not been ported to DDS yet though.

nickidlugash · 2017-07-24T23:04:48Z

some of the style properties used in this example page (text-anchor, text-justify) have not been ported to DDS yet though.

Noting that text-anchor and text-justify have now been ported to DDS. All of these examples should now be usable.

jfirebaugh · 2017-09-12T22:59:27Z

Closing; this was very useful as a design aid but I don't think we're planning to keep expressions.md around much longer.

anandthakker and others added 3 commits June 2, 2017 15:29

Small edits

c289e5f

draft of expressions examples doc

77e9dcf

nickidlugash requested a review from anandthakker June 15, 2017 00:12

anandthakker mentioned this pull request Jun 15, 2017

Project Arbex (Arbitrary Expressions) #4777

Merged

15 tasks

anandthakker reviewed Jun 19, 2017

View reviewed changes

nickidlugash commented Jun 19, 2017

View reviewed changes

edits to expressions examples based on feedback, including: changing …

f3ec1f8

…"case" expressions with comparisons to "step curves", adding final output values for all "match" expressions, adding missing type conversion, fixing highway shield icon-image example to use "length"

anandthakker mentioned this pull request Jun 20, 2017

JS arbex implementation: parse, typecheck, compile expressions #4841

Merged

19 tasks

1ec5 mentioned this pull request Jun 27, 2017

Reimplement MGLStyleValue atop NSExpression mapbox/mapbox-gl-native#8074

Closed

anandthakker force-pushed the feature/expressions branch 2 times, most recently from b75efe5 to c1c29cb Compare June 30, 2017 12:27

anandthakker force-pushed the feature/expressions branch from 2d82f1a to 3bc2561 Compare July 24, 2017 22:02

anandthakker force-pushed the feature/expressions branch 5 times, most recently from db7c15c to c37f1ea Compare August 5, 2017 03:14

anandthakker force-pushed the feature/expressions branch 2 times, most recently from ed3dd33 to 2c7658a Compare August 15, 2017 16:09

anandthakker force-pushed the feature/expressions branch from 6965f91 to 9ec03f0 Compare August 18, 2017 01:13

anandthakker force-pushed the feature/expressions branch 4 times, most recently from 75fcd51 to 73fff34 Compare August 29, 2017 22:33

anandthakker force-pushed the feature/expressions branch 2 times, most recently from d68949a to 9ee7362 Compare August 31, 2017 19:47

jfirebaugh closed this Sep 12, 2017

jfirebaugh deleted the expressions-examples branch September 21, 2017 17:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

draft of expressions examples doc #4836

draft of expressions examples doc #4836

nickidlugash commented Jun 15, 2017

anandthakker left a comment

anandthakker Jun 19, 2017

nickidlugash Jun 19, 2017

anandthakker Jun 19, 2017

anandthakker Jun 19, 2017

nickidlugash Jun 19, 2017

anandthakker Jun 19, 2017

anandthakker Jun 19, 2017

anandthakker Jun 19, 2017

nickidlugash Jun 19, 2017

anandthakker Jun 19, 2017

jfirebaugh commented Jun 19, 2017

nickidlugash Jun 19, 2017

anandthakker Jun 19, 2017

nickidlugash commented Jun 19, 2017

anandthakker commented Jun 19, 2017

nickidlugash commented Jun 21, 2017

nickidlugash commented Jul 24, 2017

jfirebaugh commented Sep 12, 2017

draft of expressions examples doc #4836

draft of expressions examples doc #4836

Conversation

nickidlugash commented Jun 15, 2017

anandthakker left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jfirebaugh commented Jun 19, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nickidlugash commented Jun 19, 2017

anandthakker commented Jun 19, 2017

nickidlugash commented Jun 21, 2017

nickidlugash commented Jul 24, 2017

jfirebaugh commented Sep 12, 2017