tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[ios, macos] Revamp predicate and expression guide (#11741)

Browse Source 
* [ios, macos] Fact-checked expression guide

Corrected various factual inaccuracies in the “Predicates and Expressions” guide. Moved some explanation from the predicates section to the expressions section. Added sections for all the other expression types we support.

* [ios, macos] Reorganized custom function documentation

Reorganized the custom function documentation as a series of sections with headers and definition lists instead of a monolithic table. Copyedited various sections for accuracy. Linked references to custom functions. Added format string examples for all custom functions.

* [ios, macos] Made h3 more visible

* [ios, macos] Added Objective-C example of placeholders

* [ios, macos] Documented trig functions

* [ios, macos] Also increase h3 code size

* [ios, macos] Replaced Markdown with HTML in definition

* [ios, macos] Replaced Markdown with HTML in custom function documentation

* [ios, macos] Clarified stops

* [ios, macos] Cross-referenced functions

Each custom function definition cross-references the corresponding aftermarket function (or vice versa), the corresponding style specification expression operator, and any related NSExpression syntax.

* [ios, macos] Fixed links in predicate guide

* [ios, macos] Consolidated and documented NSExpression categories

Consolidated the NSExpression categories into a single category, with marks to separate different tasks. Documented the MGLAdditions category so that it shows up in the jazzy documentation.

* [ios, macos] Fixed NSExpression private category mixup
This commit is contained in:
Minh Nguyễn
2018-04-19 18:45:24 -07:00
committed by GitHub
parent f81f770741
commit 8a8709d2c7
4 changed files with 780 additions and 328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1014
platform/darwin/docs/guides/Predicates and Expressions.md
View File

File diff suppressed because it is too large Load Diff

7
platform/darwin/docs/theme/assets/css/jazzy.css.scss vendored
View File

@@ -113,7 +113,12 @@ h2 {
}
h3 {
@include heading(14px, 1em 0 0.3em);
@include heading(1.2rem, 1em 0 0.3em);
}
h3 > code {
font-weight: bold;
font-size: 1.2rem;
}
h4 {

40
platform/darwin/src/NSExpression+MGLAdditions.h
View File

@@ -16,7 +16,7 @@ typedef NSString *MGLExpressionInterpolationMode NS_TYPED_ENUM;
This attribute corresponds to the `linear` value in the
<a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-interpolate"><code>interpolate</code></a>
expression reference in the Mapbox Style Specification.
expression operator in the Mapbox Style Specification.
*/
extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolationModeLinear;
@@ -25,7 +25,7 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
This attribute corresponds to the `exponential` value in the
<a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-interpolate"><code>interpolate</code></a>
expression reference in the Mapbox Style Specification.
expression operator in the Mapbox Style Specification.
*/
extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolationModeExponential;
@@ -34,50 +34,55 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
This attribute corresponds to the `cubic-bezier` value in the
<a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-interpolate"><code>interpolate</code></a>
expression reference in the Mapbox Style Specification.
expression operator in the Mapbox Style Specification.
*/
extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolationModeCubicBezier;
@interface NSExpression (MGLVariableAdditions)
/**
Methods for creating expressions that use Mapbox-specific functionality and for
converting to and from the JSON format defined in the
<a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions">Mapbox Style Specification</a>.
*/
@interface NSExpression (MGLAdditions)
#pragma mark Creating Variable Expressions
/**
`NSExpression` variable that corresponds to the
<a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-zoom"><code>zoom</code></a>
expression reference in the Mapbox Style Specification.
expression operator in the Mapbox Style Specification.
*/
@property (class, nonatomic, readonly) NSExpression *zoomLevelVariableExpression;
/**
`NSExpression` variable that corresponds to the
<a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-heatmap-density"><code>heatmap-density</code></a>
expression reference in the Mapbox Style Specification.
expression operator in the Mapbox Style Specification.
*/
@property (class, nonatomic, readonly) NSExpression *heatmapDensityVariableExpression;
/**
`NSExpression` variable that corresponds to the
<a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#eexpressions-geometry-type"><code>geometry-type</code></a>
expression reference in the Mapbox Style Specification.
expression operator in the Mapbox Style Specification.
*/
@property (class, nonatomic, readonly) NSExpression *geometryTypeVariableExpression;
/**
`NSExpression` variable that corresponds to the
<a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-id"><code>id</code></a>
expression reference in the Mapbox Style Specification.
expression operator in the Mapbox Style Specification.
*/
@property (class, nonatomic, readonly) NSExpression *featureIdentifierVariableExpression;
/**
`NSExpression` variable that corresponds to the
<a href="https://www.mapbox.com/mapbox-gl-js/style-spec/#expressions-properties"><code>properties</code></a>
expression reference in the Mapbox Style Specification.
expression operator in the Mapbox Style Specification.
*/
@property (class, nonatomic, readonly) NSExpression *featurePropertiesVariableExpression;
@end
@interface NSExpression (MGLInitializerAdditions)
#pragma mark Creating Conditional Expressions
/**
Returns a conditional function expression specifying the string predicate, and
@@ -89,6 +94,8 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
*/
+ (instancetype)mgl_expressionForConditional:(nonnull NSPredicate *)conditionPredicate trueExpression:(nonnull NSExpression *)trueExpression falseExpresssion:(nonnull NSExpression *)falseExpression NS_SWIFT_NAME(init(forMGLConditional:trueExpression:falseExpression:));
#pragma mark Creating Ramp, Scale, and Curve Expressions
/**
Returns a step function expression specifying the stepping, from expression
and stops.
@@ -121,6 +128,9 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
@param defaultExpression The defaultValue expression to be used in case there is no match.
*/
+ (instancetype)mgl_expressionForMatchingExpression:(nonnull NSExpression *)inputExpression inDictionary:(nonnull NSDictionary<NSExpression *, NSExpression *> *)matchedExpressions defaultExpression:(nonnull NSExpression *)defaultExpression NS_SWIFT_NAME(init(forMGLMatchingKey:in:default:));
#pragma mark Concatenating String Expressions
/**
Returns a constant expression appending the passed expression.
@@ -131,9 +141,7 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
*/
- (instancetype)mgl_expressionByAppendingExpression:(nonnull NSExpression *)expression NS_SWIFT_NAME(mgl_appending(_:));
@end
@interface NSExpression (MGLAdditions)
#pragma mark Converting JSON Expressions
/**
Returns an expression equivalent to the given Foundation object deserialized
@@ -168,6 +176,8 @@ extern MGL_EXPORT const MGLExpressionInterpolationMode MGLExpressionInterpolatio
*/
@property (nonatomic, readonly) id mgl_jsonExpressionObject;
#pragma mark Localizing the Expression
/**
Returns a copy of the receiver localized into the given locale.

47
platform/darwin/src/NSExpression+MGLAdditions.mm
View File

@@ -621,7 +621,24 @@ NS_DICTIONARY_OF(NSNumber *, NSExpression *) *MGLStopDictionaryByReplacingTokens
}
@end
@implementation NSExpression (MGLVariableAdditions)
@implementation NSExpression (MGLExpressionAdditions)
- (NSExpression *)mgl_expressionWithContext:(NSDictionary<NSString *, NSExpression *> *)context {
[NSException raise:NSInternalInconsistencyException
format:@"Assignment expressions lack underlying Objective-C implementations."];
return self;
}
- (id)mgl_has:(id)element {
[NSException raise:NSInvalidArgumentException
format:@"Has expressions lack underlying Objective-C implementations."];
return nil;
}
@end
@implementation NSExpression (MGLAdditions)
+ (NSExpression *)zoomLevelVariableExpression {
return [NSExpression expressionForVariable:@"zoomLevel"];
@@ -643,10 +660,6 @@ NS_DICTIONARY_OF(NSNumber *, NSExpression *) *MGLStopDictionaryByReplacingTokens
return [NSExpression expressionForVariable:@"featureProperties"];
}
@end
@implementation NSExpression (MGLInitializerAdditions)
+ (instancetype)mgl_expressionForConditional:(nonnull NSPredicate *)conditionPredicate trueExpression:(nonnull NSExpression *)trueExpression falseExpresssion:(nonnull NSExpression *)falseExpression {
if (@available(iOS 9.0, *)) {
return [NSExpression expressionForConditional:conditionPredicate trueExpression:trueExpression falseExpression:falseExpression];
@@ -655,12 +668,12 @@ NS_DICTIONARY_OF(NSNumber *, NSExpression *) *MGLStopDictionaryByReplacingTokens
}
}
+ (instancetype)mgl_expressionForSteppingExpression:(nonnull NSExpression*)steppingExpression fromExpression:(nonnull NSExpression *)minimumExpression stops:(nonnull NSExpression*)stops {
+ (instancetype)mgl_expressionForSteppingExpression:(nonnull NSExpression *)steppingExpression fromExpression:(nonnull NSExpression *)minimumExpression stops:(nonnull NSExpression *)stops {
return [NSExpression expressionForFunction:@"mgl_step:from:stops:"
arguments:@[steppingExpression, minimumExpression, stops]];
}
+ (instancetype)mgl_expressionForInterpolatingExpression:(nonnull NSExpression*)inputExpression withCurveType:(nonnull MGLExpressionInterpolationMode)curveType parameters:(nullable NSExpression *)parameters stops:(nonnull NSExpression*)stops {
+ (instancetype)mgl_expressionForInterpolatingExpression:(nonnull NSExpression *)inputExpression withCurveType:(nonnull MGLExpressionInterpolationMode)curveType parameters:(nullable NSExpression *)parameters stops:(nonnull NSExpression *)stops {
NSExpression *sanitizeParams = parameters ? parameters : [NSExpression expressionForConstantValue:nil];
return [NSExpression expressionForFunction:@"mgl_interpolate:withCurveType:parameters:stops:"
arguments:@[inputExpression, [NSExpression expressionForConstantValue:curveType], sanitizeParams, stops]];
@@ -685,26 +698,6 @@ NS_DICTIONARY_OF(NSNumber *, NSExpression *) *MGLStopDictionaryByReplacingTokens
return [NSExpression expressionForFunction:@"mgl_join:" arguments:@[subexpression]];
}
@end
@implementation NSExpression (MGLExpressionAdditions)
- (NSExpression *)mgl_expressionWithContext:(NSDictionary<NSString *, NSExpression *> *)context {
[NSException raise:NSInternalInconsistencyException
format:@"Assignment expressions lack underlying Objective-C implementations."];
return self;
}
- (id)mgl_has:(id)element {
[NSException raise:NSInvalidArgumentException
format:@"Has expressions lack underlying Objective-C implementations."];
return nil;
}
@end
@implementation NSExpression (MGLAdditions)
static NSDictionary<NSString *, NSString *> *MGLFunctionNamesByExpressionOperator;
static NSDictionary<NSString *, NSString *> *MGLExpressionOperatorsByFunctionNames;