[ios, macos] Update format expression documentation.

mapbox · Mar 14, 2019 · e6faefe · e6faefe
1 parent c9a363f
commit e6faefe
Show file tree

Hide file tree

Showing 8 changed files with 41 additions and 7 deletions.
diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
@@ -403,7 +403,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `zoom`                 | `NSExpression.zoomLevelVariableExpression` | `$zoomLevel`
 `heatmap-density`      | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity`
 `line-progress`        | `NSExpression.lineProgressVariableExpression` | `$lineProgress`
-`format`               | `mgl_attributed:` | `mgl_attributed({x, y, z})`
+`format`               | `+[NSExpression mgl_expressionForAttributedExpressions:]` or `mgl_attributed:`  | `mgl_attributed({x, y, z})`
 
 For operators that have no corresponding `NSExpression` symbol, use the
 `MGL_FUNCTION()` format string syntax.

diff --git a/platform/darwin/docs/guides/Predicates and Expressions.md b/platform/darwin/docs/guides/Predicates and Expressions.md
@@ -543,10 +543,11 @@ operator in the Mapbox Style Specification.
 <dd><code>mgl_attributed({x, y, z})</code></dd>
 </dl>
 
-Returns formatted text containing annotations for use in mixed-format `text-field`  entries.
+Concatenates and returns the array of `MGLAttributedExpression` objects, for use 
+with the `MGLSymbolStyleLayer.text` property.
 
 This function corresponds to the
-[`mgl_attributed`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-types-format)
+[`format`](https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-types-format)
 operator in the Mapbox Style Specification.
 
 ### `MGL_LET`

diff --git a/platform/darwin/src/MGLAttributedExpression.h b/platform/darwin/src/MGLAttributedExpression.h
@@ -8,8 +8,8 @@ FOUNDATION_EXTERN MGL_EXPORT MGLAttributedExpressionKey const MGLFontNamesAttrib
 FOUNDATION_EXTERN MGL_EXPORT MGLAttributedExpressionKey const MGLFontSizeAttribute;
 
 /**
- An `NSExpression` that has associated text formatting attibutes (such as font size or
- font names).
+ An `MGLAttributedExpression` object associates text formatting attibutes (such as font size or
+ font names) to an `NSExpression`.
  */
 MGL_EXPORT
 @interface MGLAttributedExpression : NSObject

diff --git a/platform/darwin/src/NSExpression+MGLAdditions.h b/platform/darwin/src/NSExpression+MGLAdditions.h
@@ -152,6 +152,14 @@ FOUNDATION_EXTERN MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionI
  */
 + (instancetype)mgl_expressionForMatchingExpression:(nonnull NSExpression *)inputExpression inDictionary:(nonnull NSDictionary<NSExpression *, NSExpression *> *)matchedExpressions defaultExpression:(nonnull NSExpression *)defaultExpression NS_SWIFT_NAME(init(forMGLMatchingKey:in:default:));
 
+/**
+ Returns an attributed function expression specifying an `MGLAttributedExpression` constant
+ expression array.
+ 
+ @param attributedExpressions The `MGLAttributedExpression` constant expression array.
+ */
++ (instancetype)mgl_expressionForAttributedExpressions:(nonnull NSArray<NSExpression *> *)attributedExpressions NS_SWIFT_NAME(init(forAttributedExpressions:));
+
 #pragma mark Concatenating String Expressions
 
 /**

diff --git a/platform/darwin/src/NSExpression+MGLAdditions.mm b/platform/darwin/src/NSExpression+MGLAdditions.mm
@@ -598,6 +598,10 @@ + (instancetype)mgl_expressionForMatchingExpression:(nonnull NSExpression *)inpu
                                      arguments:optionsArray];
 }
 
++ (instancetype)mgl_expressionForAttributedExpressions:(nonnull NSArray<NSExpression *> *)attributedExpressions {
+    return [NSExpression expressionWithFormat:@"mgl_attributed(%@)", attributedExpressions];
+}
+
 - (instancetype)mgl_expressionByAppendingExpression:(nonnull NSExpression *)expression {
     NSExpression *subexpression = [NSExpression expressionForAggregate:@[self, expression]];
     return [NSExpression expressionForFunction:@"mgl_join:" arguments:@[subexpression]];

diff --git a/platform/darwin/test/MGLExpressionTests.mm b/platform/darwin/test/MGLExpressionTests.mm
@@ -1046,6 +1046,27 @@ - (void)testFormatExpressionObject {
         XCTAssertEqualObjects(expression.mgl_jsonExpressionObject, jsonExpression);
         XCTAssertEqualObjects([NSExpression expressionWithMGLJSONObject:jsonExpression], expression);
     }
+    {
+        MGLAttributedExpression *attribute1 = [MGLAttributedExpression attributedExpression:[NSExpression expressionForConstantValue:@"foo"]
+                                                                                  fontNames:nil
+                                                                                   fontSize:@(1.2)];
+        MGLAttributedExpression *attribute2 = [MGLAttributedExpression attributedExpression:[NSExpression expressionForConstantValue:@"biz"]
+                                                                                  fontNames:nil
+                                                                                   fontSize:@(1.0)];
+        MGLAttributedExpression *attribute3 = [MGLAttributedExpression attributedExpression:[NSExpression expressionForConstantValue:@"bar"]
+                                                                                  fontNames:nil
+                                                                                   fontSize:@(0.8)];
+        MGLAttributedExpression *attribute4 = [MGLAttributedExpression attributedExpression:[NSExpression expressionForConstantValue:@"\n"]
+                                                                                  fontNames:@[]
+                                                                                   fontSize:nil];
+        NSExpression *expression = [NSExpression mgl_expressionForAttributedExpressions:@[MGLConstantExpression(attribute1),
+                                                                                          MGLConstantExpression(attribute4),
+                                                                                          MGLConstantExpression(attribute2),
+                                                                                          MGLConstantExpression(attribute3)]];
+        NSArray *jsonExpression = @[@"format", @"foo", @{@"font-scale": @1.2}, @"\n", @{}, @"biz", @{@"font-scale": @1.0}, @"bar", @{@"font-scale": @0.8}];
+        XCTAssertEqualObjects(expression.mgl_jsonExpressionObject, jsonExpression);
+        XCTAssertEqualObjects([NSExpression expressionWithMGLJSONObject:jsonExpression], expression);
+    }
 }
 
 - (void)testGenericExpressionObject {

diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md
@@ -390,7 +390,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `zoom`                 | `NSExpression.zoomLevelVariableExpression` | `$zoomLevel`
 `heatmap-density`      | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity`
 `line-progress`        | `NSExpression.lineProgressVariableExpression` | `$lineProgress`
-`format`               | `mgl_attributed:` | `mgl_attributed({x, y, z})`
+`format`               | `+[NSExpression mgl_expressionForAttributedExpressions:]` or `mgl_attributed:`  | `mgl_attributed({x, y, z})`
 
 For operators that have no corresponding `NSExpression` symbol, use the
 `MGL_FUNCTION()` format string syntax.

diff --git a/platform/macos/docs/guides/For Style Authors.md b/platform/macos/docs/guides/For Style Authors.md
@@ -383,7 +383,7 @@ In style specification | Method, function, or predicate type | Format string syn
 `zoom`                 | `NSExpression.zoomLevelVariableExpression` | `$zoomLevel`
 `heatmap-density`      | `NSExpression.heatmapDensityVariableExpression` | `$heatmapDensity`
 `line-progress`        | `NSExpression.lineProgressVariableExpression` | `$lineProgress`
-`format`               | `mgl_attributed:` | `mgl_attributed({x, y, z})`
+`format`               | `+[NSExpression mgl_expressionForAttributedExpressions:]` or `mgl_attributed:`  | `mgl_attributed({x, y, z})`
 
 For operators that have no corresponding `NSExpression` symbol, use the
 `MGL_FUNCTION()` format string syntax.