diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 883bca8..c985777 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-03T13:57:08","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-03T14:33:28","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/advanced/index.html b/dev/advanced/index.html index de992e4..d0ea7da 100644 --- a/dev/advanced/index.html +++ b/dev/advanced/index.html @@ -36,4 +36,4 @@ Interfaces.test(Group.GroupInterface, Float64, int_pairs) catch e print(e.msg) -end
Each tested object must either be an instance of `Float64` or an instance of `Arguments` whose field types include at least one subtype of `Float64`. You provided a `Arguments{(:x, :y), Tuple{Int64, Int64}}` instead.

In summary, there are two things to remember:

  1. The anonymous functions in the interface conditions of Interfaces.@interface should accept a single object of type Arguments and then work with its named fields. These fields should be listed in the docstring.
  2. The list of objects passed to Interface.test must all be of type Arguments, with the right named fields. At least one field must have the type you are testing.

This page was generated using Literate.jl.

+end
Each tested object must either be an instance of `Float64` or an instance of `Arguments` whose field types include at least one subtype of `Float64`. You provided a `Arguments{(:x, :y), Tuple{Int64, Int64}}` instead.

In summary, there are two things to remember:

  1. The anonymous functions in the interface conditions of Interfaces.@interface should accept a single object of type Arguments and then work with its named fields. These fields should be listed in the docstring.
  2. The list of objects passed to Interface.test must all be of type Arguments, with the right named fields. At least one field must have the type you are testing.

This page was generated using Literate.jl.

diff --git a/dev/api/index.html b/dev/api/index.html index e954d14..4dd008a 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -1,15 +1,15 @@ -API reference · Interfaces.jl
GitHub

API reference

Docstrings

Interfaces.Interfaces — Module
Interfaces

A Julia package for specifying and testing interfaces (conditions verified by a set of methods applied to a type).

source
Interfaces.Arguments — Type
Arguments{names,T}
+API reference · Interfaces.jl
GitHub
API reference
Docstrings
Interfaces.Interfaces — Module
Interfaces
A Julia package for specifying and testing interfaces (conditions verified by a set of methods applied to a type).
source
Interfaces.Interface — Type
Interface{Components}
Abstract supertype for all Interfaces.jl interfaces.
Components is an Tuple of Symbol.
source
Interfaces.components — Function
components(::Type{<:Interface})
Returns the components of the interface, as a NamedTuple of NamedTuple.
source
Interfaces.implemented_trait — Method
implemented_trait(T::Type{<:Interface}, obj)
-implemented_trait(T::Type{<:Interface{Option}}, obj)
Provides a single type for using interface implementation as a trait.
Returns Implemented{T}() or NotImplemented{T}().
source
Interfaces.implements — Function
implements(::Type{<:Interface}, obj)
-implements(::Type{<:Interface{Options}}, obj)
Returns whether an object implements an interface, as a Bool.
obj can be an be an object or a Type.
Options can be a Symbol or a Tuple of Symbol passed to the type parameter of the Interface, to check if optional interfaces are implemented by the obj.
Without specifying Options, the return value specifies that at least  all the mandatory components of the interace are implemented.
source
Interfaces.Interface — Type
Interface{Components}
Abstract supertype for all Interfaces.jl interfaces.
Components is an Tuple of Symbol.
source
Interfaces.components — Function
components(::Type{<:Interface})
Returns the components of the interface, as a NamedTuple of NamedTuple.
source
Interfaces.implemented_trait — Method
implemented_trait(T::Type{<:Interface}, obj)
+implemented_trait(T::Type{<:Interface{Option}}, obj)
Provides a single type for using interface implementation as a trait.
Returns Implemented{T}() or NotImplemented{T}().
source
Interfaces.implements — Function
implements(::Type{<:Interface}, obj)
+implements(::Type{<:Interface{Options}}, obj)
Returns whether an object implements an interface, as a Bool.
obj can be an be an object or a Type.
Options can be a Symbol or a Tuple of Symbol passed to the type parameter of the Interface, to check if optional interfaces are implemented by the obj.
Without specifying Options, the return value specifies that at least  all the mandatory components of the interace are implemented.
source
Interfaces.test — Function
test(; kw...)
 test(mod::Module; kw...)
 test(::Type{<:Interface}; kw...)
 test(::Type{<:Interface}, mod::Module; kw...)
-test(::Type{<:Interface}, type::Type, [test_objects]; kw...)
Test if an interface is implemented correctly, returning true or false.
There are a number of ways to select implementations to test:
  • With no arguments, test all defined Interfaces currenty imported.
  • If a Module is passed, all Interface implementations defined in it will be tested.    This is probably the best option to put in package tests.
  • If only an Interface is passed, all implementations of it are tested
  • If both a Module and an Interface are passed, test the intersection    of implementations of the Interface for the Module.
  • If an Interface and Type are passed, the implementation for that type will be tested.
If no interface type is passed, Interfaces.jl will find all the interfaces available and test them.
source
Interfaces.@implements — Macro
@implements(interface, objtype)
Declare that an interface implements an interface, or multipleinterfaces.
The macro can only be used once per module for any one type. To define multiple interfaces a type implements, combine them in square brackets.
Example
Here we implement the IterationInterface for Base julia, indicating with (:indexing, :reverse) that our object can be indexed and works with Iterators.reverse:
using BaseInterfaces
-@implements BaseInterfaces.IterationInterface{(:indexing,:reverse)} MyObject
source
Interfaces.@interface — Macro
@interface(interfacename, components, [description])
Define an interface that can apply to types <: Any.
components = (
+test(::Type{<:Interface}, type::Type, [test_objects]; kw...)
Test if an interface is implemented correctly, returning true or false.
There are a number of ways to select implementations to test:
  • With no arguments, test all defined Interfaces currenty imported.
  • If a Module is passed, all Interface implementations defined in it will be tested.    This is probably the best option to put in package tests.
  • If only an Interface is passed, all implementations of it are tested
  • If both a Module and an Interface are passed, test the intersection    of implementations of the Interface for the Module.
  • If an Interface and Type are passed, the implementation for that type will be tested.
If no interface type is passed, Interfaces.jl will find all the interfaces available and test them.
source
Interfaces.@implements — Macro
@implements(interface, objtype)
Declare that an interface implements an interface, or multipleinterfaces.
The macro can only be used once per module for any one type. To define multiple interfaces a type implements, combine them in square brackets.
Example
Here we implement the IterationInterface for Base julia, indicating with (:indexing, :reverse) that our object can be indexed and works with Iterators.reverse:
using BaseInterfaces
+@implements BaseInterfaces.IterationInterface{(:indexing,:reverse)} MyObject
source
Interfaces.@interface — Macro
@interface(interfacename, components, [description])
Define an interface that can apply to types <: Any.
components = (
     mandatory = (
         length = x -> length(x) = prod(size(x)),
         ndims = x -> ndims(x) = length(size(x)),
@@ -18,4 +18,4 @@
 )
 description = "A description of the interface"
 
-@interface MyInterface Any components description
source
Index

+@interface MyInterface Any components description
source

Index

diff --git a/dev/baseinterfaces/index.html b/dev/baseinterfaces/index.html index 427c72d..313b73d 100644 --- a/dev/baseinterfaces/index.html +++ b/dev/baseinterfaces/index.html @@ -1,2 +1,2 @@ -BaseInterfaces.jl reference · Interfaces.jl
GitHub

BaseInterfaces reference

Docstrings

BaseInterfaces.ArrayInterface — Type
    ArrayInterface

An Interfaces.jl Interface with mandatory components (:type, :eltype, :ndims, :size, :getindex, :indexstyle) and optional components (:setindex!, :similar_type, :similar_eltype, :similar_size, :similar_eltype_size).

Base Julia AbstractArray interface

source
BaseInterfaces.DictInterface — Type
    DictInterface

An Interfaces.jl Interface with mandatory components (:iterate, :eltype, :keytype, :valtype, :keys, :values, :getindex) and optional components (:setindex!,).

AbstractDict interface requires Arguments, with d = the_dict mandatory, and when setindex is needed, k = any_valid_key_not_in_d, v = any_valid_val

source
BaseInterfaces.IterationInterface — Type
    IterationInterface

An Interfaces.jl Interface with mandatory components (:iterate, :isiterable, :eltype, :size, :in) and optional components (:reverse, :indexing).

An interface for Base Julia iteration

source
BaseInterfaces.SetInterface — Type
    SetInterface

An Interfaces.jl Interface with mandatory components (:isempty, :eltype, :length, :iteration, :in) and optional components (:copy, :empty, :hasfastin, :setdiff, :intersect, :union, :copymutable, :emptymutable, :empty!, :delete!, :push!, :sizehint!).

The AbstractSet interface

source

Index

+BaseInterfaces.jl reference · Interfaces.jl
GitHub

BaseInterfaces reference

Docstrings

BaseInterfaces.ArrayInterface — Type
    ArrayInterface

An Interfaces.jl Interface with mandatory components (:type, :eltype, :ndims, :size, :getindex, :indexstyle) and optional components (:setindex!, :similar_type, :similar_eltype, :similar_size, :similar_eltype_size).

Base Julia AbstractArray interface

source
BaseInterfaces.DictInterface — Type
    DictInterface

An Interfaces.jl Interface with mandatory components (:iterate, :eltype, :keytype, :valtype, :keys, :values, :getindex) and optional components (:setindex!,).

AbstractDict interface requires Arguments, with d = the_dict mandatory, and when setindex is needed, k = any_valid_key_not_in_d, v = any_valid_val

source
BaseInterfaces.IterationInterface — Type
    IterationInterface

An Interfaces.jl Interface with mandatory components (:iterate, :isiterable, :eltype, :size, :in) and optional components (:reverse, :indexing).

An interface for Base Julia iteration

source
BaseInterfaces.SetInterface — Type
    SetInterface

An Interfaces.jl Interface with mandatory components (:isempty, :eltype, :length, :iteration, :in) and optional components (:copy, :empty, :hasfastin, :setdiff, :intersect, :union, :copymutable, :emptymutable, :empty!, :delete!, :push!, :sizehint!).

The AbstractSet interface

source

Index

diff --git a/dev/basic/index.html b/dev/basic/index.html index fd09d06..12e702d 100644 --- a/dev/basic/index.html +++ b/dev/basic/index.html @@ -44,4 +44,4 @@ print(e) end

 Testing AnimalInterface is implemented for Main.Chicken
-Interfaces.InterfaceError(Main.Animals.AnimalInterface, :age, 1, " \"all animals have a `Real` age\"", Main.Chicken(), MethodError(Main.Animals.age, (Main.Chicken(),), 0x00000000000082fb))

This page was generated using Literate.jl.

+Interfaces.InterfaceError(Main.Animals.AnimalInterface, :age, 1, " \"all animals have a `Real` age\"", Main.Chicken(), MethodError(Main.Animals.age, (Main.Chicken(),), 0x00000000000082fb))

This page was generated using Literate.jl.

diff --git a/dev/index.html b/dev/index.html index 839e354..d533203 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · Interfaces.jl
GitHub

Interfaces

Stable Dev Build Status Coverage

Macros for defining the required behaviours of Julia interfaces, and stating that an object implements them.

The goal is to get as much as possible out of defining an interface, specifically:

  • Traits: All @implements declarations produce compile-time traits that can be checked by other packages - for the whole interface and all of it's optional components.
  • Tests: @implements declarations should be tested in package tests.
  • Docs: interface documentation can be inserted into trait documentation.

See the IterationInterface in BaseInterfaces.jl (a subpackage of this package) or the documentation for examples of @interface and @implements.

Note: the syntax here is likely to change as we work out the best ways to define interfaces

If you think it should behave differently or there is better syntax, please make an issue.

+Home · Interfaces.jl
GitHub

Interfaces

Stable Dev Build Status Coverage

Macros for defining the required behaviours of Julia interfaces, and stating that an object implements them.

The goal is to get as much as possible out of defining an interface, specifically:

  • Traits: All @implements declarations produce compile-time traits that can be checked by other packages - for the whole interface and all of it's optional components.
  • Tests: @implements declarations should be tested in package tests.
  • Docs: interface documentation can be inserted into trait documentation.

See the IterationInterface in BaseInterfaces.jl (a subpackage of this package) or the documentation for examples of @interface and @implements.

Note: the syntax here is likely to change as we work out the best ways to define interfaces

If you think it should behave differently or there is better syntax, please make an issue.