Allow packages to provide custom hints for Exceptions

NEWS.md

@@ -11,6 +11,12 @@ New language features
   macros and matrix constructors, which are whitespace sensitive, because expressions like
   `[a ±b]` now get parsed as `[a ±(b)]` instead of `[±(a, b)]`. ([#34200])
 
+* Packages can now provide custom hints for specific `MethodError`s to
+  help guide users. `push!` a pattern-matching function `hint(f,
+  argtypes, kwargs)`, returning a message string in case of a match
+  and `nothing` otherwise, to `Base.methoderror_hints`.
+  See `?Base.methoderror_hints` for more information. ([#35094])
+
 Language changes
 ----------------
 

base/errorshow.jl

@@ -208,6 +208,32 @@ function show_convert_error(io::IO, ex::MethodError, @nospecialize(arg_types_par
     end
 end
 
+"""
+    methoderror_hints
+
+Packages can provide hints about appropriate corrective actions for
+specific `MethodError`s with `push!(Base.methoderror_hints, hintmessage)`, where
+`hintmessage` should be a function like
+
+```julia
+function hintmessage(f, arg_types, kwargs)
+    # Test to see whether the call matches the specific pattern for this message
+    if f === myfunc && length(arg_types) == 1 && arg_types[1] <: SomeType
+        return "`myfunc(::SomeType)` is not defined, did you mean to call `otherfunc`?"
+    end
+    return nothing    # use `nothing` to indicate that f, arg_types, kwargs didn't match
+end
+```
+
+Packages should perform the `push!` onto `Base.methoderror_hints` from
+their `__init__` function.
+
+!!! compat "Julia 1.5"
+    Custom MethodError hints are available as of Julia 1.5.
+"""
+const methoderror_hints = []
+# Note: Base should not use `methoderror_hints`, it should inline
+# custom hints below to avoid the slight performance hit from `invokelatest`.
 function showerror(io::IO, ex::MethodError)
     # ex.args is a tuple type if it was thrown from `invoke` and is
     # a tuple of the arguments otherwise.
@@ -311,6 +337,12 @@ function showerror(io::IO, ex::MethodError)
                       "\nYou can convert to a column vector with the vec() function.")
         end
     end
+    for predicate in methoderror_hints
+        msg = Base.invokelatest(predicate, f, arg_types_param, kwargs)
+        if msg !== nothing
+            print(io, '\n', msg)
+        end
+    end
     try
         show_method_candidates(io, ex, kwargs)
     catch ex
@@ -731,4 +763,3 @@ function show(io::IO, ip::InterpreterIP)
         print(io, " in $(ip.code) at statement $(Int(ip.stmt))")
     end
 end
-

test/errorshow.jl

@@ -586,6 +586,28 @@ end
     end
 end
 
+# Custom hints
+struct HasNoOne end
+function recommend_oneunit(f, arg_types, kwargs)
+    if f === Base.one && length(arg_types) == 1 && arg_types[1] === HasNoOne
+        if isempty(kwargs)
+            return "HasNoOne does not support `one`; did you mean `oneunit`?"
+        else
+            return "`one` doesn't take keyword arguments, that would be silly"
+        end
+    end
+end
+push!(Base.methoderror_hints, recommend_oneunit)
+let err_str
+    err_str = @except_str one(HasNoOne()) MethodError
+    @test occursin(r"MethodError: no method matching one\(::.*HasNoOne\)", err_str)
+    @test occursin("HasNoOne does not support `one`; did you mean `oneunit`?", err_str)
+    err_str = @except_str one(HasNoOne(); value=2) MethodError
+    @test occursin(r"MethodError: no method matching one\(::.*HasNoOne; value=2\)", err_str)
+    @test occursin("`one` doesn't take keyword arguments, that would be silly", err_str)
+end
+pop!(Base.methoderror_hints)
+
 # issue #28442
 @testset "Long stacktrace printing" begin
     f28442(c) = g28442(c + 1)