Add option to avoid specific geometries

[1ec5]

The Directions API recently overloaded the exclude query parameter with an option to specify a list of point geometries in WKT format. We should add support for this syntax to serve certain use cases that require arbitrary avoidance. This would also help us achieve platform parity with the Java SDK, which implemented the feature in mapbox/mapbox-java#1362. However, it should not be implemented until the new exclude syntax leaves beta and becomes a formal part of the API contract.

Design

The overloading of exclude is particularly problematic for this library, which has always exposed exclude as an option set. But now it can hold arbitrary geometry data, which needs to be typed as a Geometry. Unfortunately, an OptionSet struct can’t store associated values, so there’s no way for us to support this syntax without breaking backwards compatibility. Besides, a geometry is semantically different than a road class.

mapbox-directions-swift/Sources/MapboxDirections/RouteOptions.swift

Line 57 in 2b14b8c

case roadClassesToAvoid = "exclude"

mapbox-directions-swift/Sources/MapboxDirections/RouteOptions.swift

Lines 152 to 157 in 2b14b8c

	/**
	The route classes that the calculated routes will avoid.
	Currently, you can only specify a single road class to avoid.
	*/
	open var roadClassesToAvoid: RoadClasses = []

mapbox-directions-swift/Sources/MapboxDirections/RoadClasses.swift

Lines 3 to 6 in 2b14b8c

	/**
	Option set that contains attributes of a road segment.
	*/
	public struct RoadClasses: OptionSet, CustomStringConvertible {

Perhaps this conflation in the API can be revisited in light of the semantic awkwardness that becomes apparent in Swift. Regardless, we can implement a parallel property, shapeToAvoid, declared as type Geometry?, with the expectation of being set to a MultiPoint until more geometry types are implemented on the server side. RouteOptions’ Codable implementation can switch between roadClassesToAvoid and shapeToAvoid depending on the value. This feature depends on Turf adding support for converting between WKT and GeoJSON: mapbox/turf-swift#185.

Workaround

Until we’re able to formally add support for this syntax, a developer can hook into the beta parameter themselves:

/**
  Route options for avoiding known [pedestrian scrambles](https://en.wikipedia.org/wiki/Pedestrian_scramble).
 */
class UnscrambledRouteOptions: RouteOptions {
    /// The locations of some known pedestrian scrambles to avoid.
    let scrambles = MultiPoint([
        .init(latitude: 39.3184214, longitude: -84.3689036),
        .init(latitude: 39.3109335, longitude: -84.3798639),
        .init(latitude: 37.3383465, longitude: -121.8807453),
        .init(latitude: 37.3330494, longitude: -121.8796307),
    ])
    
    override var urlQueryItems: [URLQueryItem] {
        var items = super.urlQueryItems
        let wktToAvoid = scrambles.coordinates
            .map { "point(\($0.longitude) \($0.latitude)" }
            .joined(separator: ",")
        items.append(.init(name: "exclude", value: wktToAvoid))
        return items
    }
}

/cc @ShrayKhullarMX @Guardiola31337

[Guardiola31337]

cc @VysotskiVadim for visibility

[1ec5]

#748 introduced a CustomValueOptionSet protocol that makes it easier to specify a custom AttributeOptions that’s otherwise unsupported by this library. However, RoadClasses does not conform to this protocol, so the workaround above is still required until we implement this feature.

/cc @Udumft