Function Index

@required MyInterface func(::Foo, ::MyInterface)
@required MyInterface function func(::Foo, ::MyInterface) end
@required MyInterface begin
    foo(::B, ::MyInterface)
    bar(::A, ::MyInterface)
end

Marks all occurrences of MyInterface in the given function signatures as part of the interface MyInterface. Also defines fallback methods, which throw a NotImplementedError when called with an argument that doesn't implement this mandatory function.

Throws an ArgumentError if MyInterface is not an abstract type or the given expression doesn't conform to the three shown styles. The function body of the second style is expected to be empty - @required can't be used to mark fallback implementations as part of a user-implementable interface. Its sole purpose is marking parts of an API that a user needs to implement to be able to have functions expecting that interface work.

functions(i::Interface)

Returns the functions that are required by this interface.

getInterface(::Type{T}) -> Interface

Return the Interface described by the type T.

Throws a MethodError if the given type is not a registered interface.

interfaceType(i::Interface)

Return the (abstract) type associated with this interface.

isInterface(::Type{T}) -> Bool

Return whether the given (abstract) type is a recognized interface.

Throws an ArgumentError if the given type is not a registered interface.

methods(i::Interface)

Return the methods (i.e., functions and their signatures) required to be implemented by this interface.

See also functions.

Interface

A struct describing the notion of an (abstract-)type-based interface.

NotImplementedError(interface::String, method::String) <: Exception

Describes that a given method (in form of a String describing the signature) that's part of the given interface has not been implemented.

The given method should have the form method(..., ::T, ...), where ... are other arguments. The message displayed by this Exception refers to T directly, so there's no need to give any particular subtype here.

Compared to MethodError, a NotImplementedError communicates "there should be a method to call here, but it needs to be implemented by the developer making use of the interface". This is mostly used through the @required macro, which handles the message generation for you.

Examples

Note how MethodError in the example below indicates that the method isn't intended to be called.

julia> using RequiredInterfaces: NotImplementedError

julia> abstract type Foo end

julia> bar(::Foo, ::Int) = throw(NotImplementedError("Foo", "bar(::T, ::Int)"))
bar (generic function with 1 method)

julia> struct Baz <: Foo end

julia> bar(Baz(), 1)
ERROR: NotImplementedError: The called method is part of a fallback definition for the `Foo` interface.
Please implement `bar(::T, ::Int)` for your type `T <: Foo`.
Stacktrace:
 [1] bar(::Baz, ::Int64)
   @ Main ./none:1
 [2] top-level scope
   @ none:1

julia> bar(1, Baz())
ERROR: MethodError: no method matching bar(::Int64, ::Baz)
The function `bar` exists, but no method is defined for this combination of argument types.

Closest candidates are:
  bar(!Matched::Foo, !Matched::Int64)
   @ Main none:1

Stacktrace:
 [1] top-level scope
   @ none:1