Create a specific exception type for enforce (#319)

Author: asinghvi17

GeometryOpsCore/src/types/exceptions.jl

@@ -8,8 +8,16 @@ This makes it substantially easier to catch specific kinds of errors and show th
 For example, we can catch `WrongManifoldException` and show a nice error message,
 and error hinters can be specialized to that as well.
 
+We also have a custom error type for missing keywords in an algorithm,
+which could eventually be extended to have typo detection, et cetera.
+
 ```@docs; canonical=false
-GeometryOpsCore.WrongManifoldException
+WrongManifoldException
+MissingKeywordInAlgorithmException
+```
+
+```@meta
+CollapsedDocStrings = true
 ```
 =#
 
@@ -46,4 +54,60 @@ function Base.showerror(io::IO, e::WrongManifoldException{I,D,A}) where {I,D,A}
         print(io, "\n\n")
         print(io, e.description)
     end
+end
+
+
+"""
+    MissingKeywordInAlgorithmException{Alg, F} <: Exception
+
+An error type which is thrown when a keyword argument is missing from an algorithm.
+
+The `alg` argument is the algorithm struct, and the `keyword` argument is the keyword
+that was missing.
+
+This error message is used in the [`enforce`](@ref GeometryOps.enforce) method.
+
+## Usage
+
+This is of course not how you would actually use this error type, but it is
+how you construct and throw it.
+
+```julia
+throw(MissingKeywordInAlgorithmException(GEOS(; tokl = 1.0), my_function, :tol))
+```
+
+Real world usage will often look like this:
+
+```julia
+function my_function(alg::CLibraryPlanarAlgorithm, args...)
+    mykwarg = enforce(alg, :mykwarg, my_function) # this will throw an error if :mykwarg is not present in alg
+end
+```
+"""
+struct MissingKeywordInAlgorithmException{Alg, F} <: Base.Exception
+    alg::Alg
+    f::F
+    keyword::Symbol
+end
+
+_name_of(x::Any) = nameof(typeof(x))
+_name_of(x::Function) = nameof(x)
+_name_of(x::Type) = nameof(x)
+_name_of(s::String) = s
+
+# This is just the generic dispatch, different algorithms can choose to dispatch
+# on their own types to provide more specific or interesting error messages.
+function Base.showerror(io::IO, e::MissingKeywordInAlgorithmException)
+    algorithm_name = _name_of(typeof(e.alg))
+    function_name = _name_of(e.f)
+    print(io, "The ")
+    printstyled(io, e.keyword; color = :red)
+    print(io, " parameter is required for the ")
+    printstyled(io, algorithm_name; bold = true)
+    println(io, " algorithm in `$(function_name)`,")
+    println(io, "but it was not provided.")
+    println(io)
+    println(io, "Provide it to the algorithm at construction time, like so:")
+    println(io, "`$(algorithm_name)(; $(e.keyword) = ...)`")
+    println(io, "and pass that as the algorithm to `$(function_name)`, usually the first argument.")
 end

ext/GeometryOpsLibGEOSExt/GeometryOpsLibGEOSExt.jl

@@ -7,7 +7,7 @@ module GeometryOpsLibGEOSExt
 import GeometryOps as GO, LibGEOS as LG
 import GeoInterface as GI
 
-import GeometryOps: GEOS, enforce, True, False, booltype
+import GeometryOps: GEOS, enforce, True, False, booltype, booltype, WithTrait, TraitTarget
 
 using GeometryOps
 # The filter statement is required because in Julia, each module has its own versions of these

ext/GeometryOpsLibGEOSExt/simplify.jl

@@ -37,33 +37,18 @@ f
 ```
 
 =#
-GO._simplify(::GI.PointTrait, ::GO.GEOS, geom; kw...) = geom
-GO._simplify(::GI.MultiPointTrait, ::GO.GEOS, geom; kw...) = geom
 
-function GO._simplify(::GI.AbstractGeometryTrait, alg::GO.GEOS, geom; kwargs...)
+function GO.simplify(alg::GO.GEOS, data; kwargs...)
     method = get(alg, :method, :TopologyPreserve)
-    @assert haskey(alg.params, :tol) """
-        The `:tol` parameter is required for the GEOS algorithm in `simplify`, 
-        but it was not provided.  
-        
-        Provide it by passing `GEOS(; tol = ...,) as the algorithm.
-        """
-    tol = alg.params.tol
-    if method == :TopologyPreserve
-        return LG.topologyPreserveSimplify(GI.convert(LG, geom), tol)
+    tol = enforce(alg, :tol, GO.simplify)
+
+    functor = if method == :TopologyPreserve
+        (trait, geom) -> LG.topologyPreserveSimplify(GI.convert(LG.geointerface_geomtype(trait), trait, geom), tol)
     elseif method == :DouglasPeucker
-        return LG.simplify(GI.convert(LG, geom), tol)
+        (trait, geom) -> LG.simplify(GI.convert(LG.geointerface_geomtype(trait), trait, geom), tol)
     else
-        error("Invalid method passed to `GO.simplify(GEOS(...), ...)`: $method. Please use :TopologyPreserve or :DouglasPeucker")
+        error("Invalid method passed to `GO.simplify(GEOS(...), ...)`: $method. \nPlease use :TopologyPreserve or :DouglasPeucker")
     end
-end
 
-function GO._simplify(trait::GI.AbstractCurveTrait, alg::GO.GEOS, geom; kw...)
-    Base.invoke(
-        GO._simplify,
-        Tuple{GI.AbstractGeometryTrait, GO.GEOS, typeof(geom)},
-        trait, alg, geom; 
-        kw...
-    )
+    return GO.apply(WithTrait(functor), GO.TraitTarget{GI.AbstractGeometryTrait}(), data; kwargs...)
 end
-

src/transformations/reproject.jl

@@ -17,8 +17,8 @@ export reproject
 
 Reproject any GeoInterface.jl compatible `geometry` from `source_crs` to `target_crs`.
 
-The returned object will be constructed from `GeoInterface.WrapperGeometry`
-geometries, wrapping views of a `Vector{Proj.Point{D}}`, where `D` is the dimension.
+The returned object will be constructed from GeoInterface wrapper geometries,
+wrapping `Vector{NTuple{D, Float64}}`, where `D` is the dimension.
 
 !!! tip
     The `Proj.jl` package must be loaded for this method to work, 

src/transformations/simplify.jl

@@ -173,8 +173,8 @@ simplify(
 #= For each algorithm, apply simplification to all curves, multipoints, and
 points, reconstructing everything else around them. =#
 function _simplify(alg::Union{SimplifyAlg, GEOS}, data; prefilter_alg=nothing, kw...)
-    simplifier(geom) = _simplify(GI.trait(geom), alg, geom; prefilter_alg)
-    return apply(simplifier, _SIMPLIFY_TARGET, data; kw...)
+    simplifier(trait, geom) = _simplify(trait, alg, geom; prefilter_alg)
+    return apply(WithTrait(simplifier), _SIMPLIFY_TARGET, data; kw...)
 end
 
 

src/types.jl

@@ -95,7 +95,7 @@ function enforce(alg::CLibraryPlanarAlgorithm, kw::Symbol, f)
     if haskey(alg.params, kw)
         return alg.params[kw]
     else
-        error("$(f) requires a `$(kw)` keyword argument to the `GEOS` algorithm, which was not provided.")
+        throw(GeometryOpsCore.MissingKeywordInAlgorithmException(alg, f, kw))
     end
 end
 
@@ -180,7 +180,7 @@ function enforce(alg::PROJ, kw::Symbol, f)
     if haskey(alg.params, kw)
         return alg.params[kw]
     else
-        error("$(f) requires a `$(kw)` keyword argument to the `GEOS` algorithm, which was not provided.")
+        throw(GeometryOpsCore.MissingKeywordInAlgorithmException(alg, f, kw))
     end
 end
 

test/core/exceptions.jl

@@ -0,0 +1,20 @@
+using Test
+import GeometryOps as GO
+using GeometryOpsCore
+using GeometryOpsCore: MissingKeywordInAlgorithmException, WrongManifoldException
+
+# These tests are more testing the call sites than they are testing the exceptions themselves.
+# But this is also important to make sure that the whole pipeline works.
+@testset "WrongManifoldException" begin
+    @test_throws WrongManifoldException SingleManifoldAlgorithm{Planar}(Spherical())
+    @test_throws "Planar" SingleManifoldAlgorithm{Planar}(Spherical())
+    @test_throws "called with manifold Spherical" SingleManifoldAlgorithm{Planar}(Spherical())
+end
+
+@testset "MissingKeywordInAlgorithmException" begin
+    alg = GO.GEOS(; tol = 1.0)
+    @test_nowarn GO.enforce(alg, :tol, sum)
+    @test_throws MissingKeywordInAlgorithmException GO.enforce(alg, :stat, sum)
+    @test_throws "sum" GO.enforce(alg, :stat, sum)
+    @test_throws "`stat`" GO.enforce(alg, :stat, sum)
+end

test/types.jl

@@ -42,8 +42,8 @@ using GeometryOps: CLibraryPlanarAlgorithm, GEOS, TG, PROJ
     @test Base.get(alg, :c, 0) == 0
 
     # Test enforce method
-    @test_throws ErrorException enforce(alg, :a, "test")
-    @test_throws ErrorException enforce(alg, :c, "test")
+    @test_throws GeometryOpsCore.MissingKeywordInAlgorithmException enforce(alg, :a, "test")
+    @test_throws GeometryOpsCore.MissingKeywordInAlgorithmException enforce(alg, :c, "test")
 end
 
 @testset "GEOS" begin
@@ -76,7 +76,7 @@ end
 
     # Test enforce method
     @test enforce(alg, :a, "test") == 1
-    @test_throws ErrorException enforce(alg, :c, "test")
+    @test_throws GeometryOpsCore.MissingKeywordInAlgorithmException enforce(alg, :c, "test")
 end
 
 @testset "TG" begin
@@ -109,7 +109,7 @@ end
 
     # Test enforce method
     @test enforce(alg, :a, "test") == 1
-    @test_throws ErrorException enforce(alg, :c, "test")
+    @test_throws GeometryOpsCore.MissingKeywordInAlgorithmException enforce(alg, :c, "test")
 end
 
 @testset "PROJ" begin
@@ -144,5 +144,5 @@ end
 
     # Test enforce method
     @test enforce(alg1, :a, "test") == 1
-    @test_throws ErrorException enforce(alg1, :c, "test")
+    @test_throws GeometryOpsCore.MissingKeywordInAlgorithmException enforce(alg1, :c, "test")
 end