diff --git a/previews/PR27/.documenter-siteinfo.json b/previews/PR27/.documenter-siteinfo.json index 57b8ed6..bbea0d8 100644 --- a/previews/PR27/.documenter-siteinfo.json +++ b/previews/PR27/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-01T12:35:50","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-01T13:24:30","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/previews/PR27/advanced/index.html b/previews/PR27/advanced/index.html index 36f676a..e130dde 100644 --- a/previews/PR27/advanced/index.html +++ b/previews/PR27/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/previews/PR27/api/index.html b/previews/PR27/api/index.html index f5584f0..b421f68 100644 --- a/previews/PR27/api/index.html +++ b/previews/PR27/api/index.html @@ -1,12 +1,12 @@ -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.test — Method
test(::Type{<:Interface}, obj)
Test if an interface is implemented correctly for an object, returning true or false.
If no interface type is passed, Interfaces.jl will find all the interfaces available and test them.
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 — Method
test(::Type{<:Interface}, obj)
Test if an interface is implemented correctly for an object, returning true or false.
If no interface type is passed, Interfaces.jl will find all the interfaces available and test them.
source
Interfaces.@implements — Macro
@implements(interface, objtype)
 @implements(dev, 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.
Passing the keyword dev as the first argument lets us show test output during development. Do not use dev in production code, or output will appear during package precompilation.
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 = (
+@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)),
@@ -15,4 +15,4 @@
 )
 description = "A description of the interface"
 
-@interface MyInterface Any components description
source
Index

+@interface MyInterface Any components description
source

Index

diff --git a/previews/PR27/baseinterfaces/index.html b/previews/PR27/baseinterfaces/index.html index 3d20939..109e3ad 100644 --- a/previews/PR27/baseinterfaces/index.html +++ b/previews/PR27/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/previews/PR27/basic/index.html b/previews/PR27/basic/index.html index a2e6015..3728be7 100644 --- a/previews/PR27/basic/index.html +++ b/previews/PR27/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(),), 0x00000000000082f9))

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(),), 0x00000000000082f9))

This page was generated using Literate.jl.

diff --git a/previews/PR27/index.html b/previews/PR27/index.html index 90842c7..a915dba 100644 --- a/previews/PR27/index.html +++ b/previews/PR27/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.