From f386c1705cdbaa929365e653299b4be579fa9e4e Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Mon, 15 Jul 2024 16:46:23 +0000 Subject: [PATCH] build based on 7a7dc67 --- previews/PR52/.documenter-siteinfo.json | 2 +- previews/PR52/advanced/index.html | 2 +- previews/PR52/api/index.html | 14 +++++++------- previews/PR52/baseinterfaces/index.html | 2 +- previews/PR52/basic/index.html | 2 +- previews/PR52/index.html | 2 +- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/previews/PR52/.documenter-siteinfo.json b/previews/PR52/.documenter-siteinfo.json index 0ff69c5..e23ec2f 100644 --- a/previews/PR52/.documenter-siteinfo.json +++ b/previews/PR52/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-15T16:40:43","documenter_version":"1.5.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-07-15T16:46:19","documenter_version":"1.5.0"}} \ No newline at end of file diff --git a/previews/PR52/advanced/index.html b/previews/PR52/advanced/index.html index becdee0..f667012 100644 --- a/previews/PR52/advanced/index.html +++ b/previews/PR52/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/PR52/api/index.html b/previews/PR52/api/index.html index eac703e..6fdecbc 100644 --- a/previews/PR52/api/index.html +++ b/previews/PR52/api/index.html @@ -1,16 +1,16 @@ -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; 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 only a Type is passed, all interfaces it implements 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, test_objects)
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, Interfaces
-@implements BaseInterfaces.IterationInterface{(:indexing,:reverse)} MyObject [MyObject(1:10), MyObject(10:-1:1)]
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 only a Type is passed, all interfaces it implements 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, test_objects)
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, Interfaces
+@implements BaseInterfaces.IterationInterface{(:indexing,:reverse)} MyObject [MyObject(1:10), MyObject(10:-1:1)]
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)),
@@ -19,4 +19,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/PR52/baseinterfaces/index.html b/previews/PR52/baseinterfaces/index.html index 72d5b26..89b6adb 100644 --- a/previews/PR52/baseinterfaces/index.html +++ b/previews/PR52/baseinterfaces/index.html @@ -1,2 +1,2 @@ -BaseInterfaces.jl reference · Interfaces.jl
GitHub

BaseInterfaces reference

BaseInterfaces.jl is a work-in-progress package to define the major base julia interfaces in Interfaces.jl syntax.

As many of these are not actually clarified yet, even in docstrings, this is a difficult task and can't be 100% reliable.

But at least trying is worthwhile to get the ball rolling.

If you would like this interface to be more useful, and actually registered, please contribute tests to the interface specs and new interface we have not yet defined.

Index

Docstrings

BaseInterfaces.ArrayInterface — Type
    ArrayInterface

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

Base Julia AbstractArray interface

Extended help

Mandatory keys:

  • eltype
  • ndims
  • size:
    • size(A) returns a tuple of Integer
    • length of size(A) matches ndims(A)
  • getindex:
    • Can index with begin/firstindex
    • Can index with end/lastindex
    • Can index with all indices in eachindex(A)
    • Can index with Int for multiple dimensions
    • Can index with Int for multiple dimensions and trailing ones
    • Can index with Int for multiple dimensions and trailing colons
    • Can index with CartesianIndex
    • Can index with CartesianIndex and trailing ones
    • Can index with CartesianIndices
    • Can index with CartesianIndices and trailing ones
    • Can index with CartesianIndices and trailing colons
    • Can index with UnitRange
    • Can index with UnitRange and trailing ones
    • Can index with UnitRange and trailing colons
    • Can index with StepRange
    • Can index with StepRange and trailing ones
    • Can index with StepRange and trailing colons
    • Can index with a Vector of Int
    • Can index with a Vector of Int32
    • Can index with a Vector of Int with trailing ones
    • Can index with a Vector of Int with trailing colons
  • indexstyle: IndexStyle returns IndexCartesian or IndexLinear

Optional keys:

  • logical:
    • Can index with logical indices
    • Can index with logical indices and trailing ones
    • Can index with logical indices and trailing colons
    • Can index with multidimensional logical indices
    • Can index with multidimensional logical indices and trailing ones
    • Can index with multidimensional logical indices and trailing colons
  • setindex!
  • similar_type: similar(A) returns an object the same type and size as A
  • similar_eltype: similar(A, T::Type) returns an object the same base type as A with eltype of T
  • similar_size: similar(A, s::NTuple{Int}) returns an object the same type as A with size s
  • similar_eltype_size: similar(A, T::Type, s::NTuple{Int}) returns an object the same type as A with eltype T and size s
source
BaseInterfaces.DictInterface — Type
    DictInterface

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

AbstractDict interface

Requires test data wrapped with Interfaces.Arguments, with

  • d = the_dict mandatory

When get! or setindex! is needed

  • k: any valid key not initially in d
  • v: any valid value

Extended help

Mandatory keys:

  • iterate: AbstractDict follows the IterationInterface
  • length: length is defined
  • eltype:
    • eltype is a Pair
    • the first value isa eltype
  • keytype: keytype is the same as the first type in eltype parameters
  • valtype: valtype is the same as the second type in eltype paremeters
  • keys: keys are all of type keytype
  • values: values are all of type valtype
  • getindex:
    • getindex of the first key is the first object in values
    • getindex of all keys match values

Optional keys:

  • setindex!:
    • test object d does not yet have test key k
    • can set key k to value v
  • get!:
    • test object d does not yet have test key k
    • can set and get key k to value v with using get!
  • delete!: can delete existing keys from the object
  • empty!: can empty the dictionary
source
BaseInterfaces.IterationInterface — Type
    IterationInterface

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

An interface for Base Julia iteration.

Test objects must not be empty, so that isempty(obj) == false.

Extended help

Mandatory keys:

  • isempty: test iterator is not empty
  • iterate:
    • iterate does not return nothing
    • iterate returns a Tuple
    • second iterate returns a Tuple or Nothing
  • isiterable
  • eltype
  • size
  • in: in returns true for all values in x

Optional keys:

  • reverse
  • indexing:
    • can call firstindex
    • can call lastindex
    • can call getindex
    • getindex matches iteration order
source
BaseInterfaces.SetInterface — Type
    SetInterface

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

The AbstractSet interface

Extended help

Mandatory keys:

  • isempty: defines isempty and testdata is not empty
  • eltype: elements eltype of set s are subtypes of eltype(s)
  • length: set defines length and test object has length larger than zero
  • iteration: follows the IterationInterface

Optional keys:

  • copy: creates an identical object with the same values, that is not the same object
  • empty:
    • returns an empty set able to hold elements of type U
    • returns an empty set able to hold elements of arbitrary types
  • hasfastin: hasfastin returns a Bool
  • setdiff:
    • setdiff with itself is an empty set of the same type
    • setdiff with an empty set is equal to itself
  • intersect:
    • intersect of set with itself is itself
    • intersect of set with an empty set is an empty set
  • union:
    • union of a set with itself equals itself
    • union of a set an empty set equals itself
  • copymutable: creates an identical mutable object with the same values, that is not the same object
  • emptymutable:
    • returns an empty set able to hold elements of type U
    • returns an empty set able to hold elements of arbitrary types
  • empty!: empty! removes all elements from the set
  • delete!: delete! removes element valued x of the set
  • push!: push! adds an element to the set
  • sizehint!: can set a size hint
source
BaseInterfaces.StringInterface — Type
    StringInterface

An Interfaces.jl Interface with mandatory components (:ncodeunits, :iterate, :codeunit, :isvalid, :eltype) and optional components (:length,).

AbstractString interface

Test objects must not be empty, so that isempty(obj) == false.

Extended help

Mandatory keys:

  • ncodeunits: ncodeunit returns an Int
  • iterate: AbstractString follows the IterationInterface
  • codeunit: the first codeunit is a UInt8/16/32
  • isvalid: isvalid returns a Bool
  • eltype: eltype returns a type <: AbatractChar

Optional keys:

  • length: length return an Int
source
+BaseInterfaces.jl reference · Interfaces.jl
GitHub

BaseInterfaces reference

BaseInterfaces.jl is a work-in-progress package to define the major base julia interfaces in Interfaces.jl syntax.

As many of these are not actually clarified yet, even in docstrings, this is a difficult task and can't be 100% reliable.

But at least trying is worthwhile to get the ball rolling.

If you would like this interface to be more useful, and actually registered, please contribute tests to the interface specs and new interface we have not yet defined.

Index

Docstrings

BaseInterfaces.ArrayInterface — Type
    ArrayInterface

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

Base Julia AbstractArray interface

Extended help

Mandatory keys:

  • eltype
  • ndims
  • size:
    • size(A) returns a tuple of Integer
    • length of size(A) matches ndims(A)
  • getindex:
    • Can index with begin/firstindex
    • Can index with end/lastindex
    • Can index with all indices in eachindex(A)
    • Can index with Int for multiple dimensions
    • Can index with Int for multiple dimensions and trailing ones
    • Can index with Int for multiple dimensions and trailing colons
    • Can index with CartesianIndex
    • Can index with CartesianIndex and trailing ones
    • Can index with CartesianIndices
    • Can index with CartesianIndices and trailing ones
    • Can index with CartesianIndices and trailing colons
    • Can index with UnitRange
    • Can index with UnitRange and trailing ones
    • Can index with UnitRange and trailing colons
    • Can index with StepRange
    • Can index with StepRange and trailing ones
    • Can index with StepRange and trailing colons
    • Can index with a Vector of Int
    • Can index with a Vector of Int32
    • Can index with a Vector of Int with trailing ones
    • Can index with a Vector of Int with trailing colons
  • indexstyle: IndexStyle returns IndexCartesian or IndexLinear

Optional keys:

  • logical:
    • Can index with logical indices
    • Can index with logical indices and trailing ones
    • Can index with logical indices and trailing colons
    • Can index with multidimensional logical indices
    • Can index with multidimensional logical indices and trailing ones
    • Can index with multidimensional logical indices and trailing colons
  • setindex!
  • similar_type: similar(A) returns an object the same type and size as A
  • similar_eltype: similar(A, T::Type) returns an object the same base type as A with eltype of T
  • similar_size: similar(A, s::NTuple{Int}) returns an object the same type as A with size s
  • similar_eltype_size: similar(A, T::Type, s::NTuple{Int}) returns an object the same type as A with eltype T and size s
source
BaseInterfaces.DictInterface — Type
    DictInterface

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

AbstractDict interface

Requires test data wrapped with Interfaces.Arguments, with

  • d = the_dict mandatory

When get! or setindex! is needed

  • k: any valid key not initially in d
  • v: any valid value

Extended help

Mandatory keys:

  • iterate: AbstractDict follows the IterationInterface
  • length: length is defined
  • eltype:
    • eltype is a Pair
    • the first value isa eltype
  • keytype: keytype is the same as the first type in eltype parameters
  • valtype: valtype is the same as the second type in eltype paremeters
  • keys: keys are all of type keytype
  • values: values are all of type valtype
  • getindex:
    • getindex of the first key is the first object in values
    • getindex of all keys match values

Optional keys:

  • setindex!:
    • test object d does not yet have test key k
    • can set key k to value v
  • get!:
    • test object d does not yet have test key k
    • can set and get key k to value v with using get!
  • delete!: can delete existing keys from the object
  • empty!: can empty the dictionary
source
BaseInterfaces.IterationInterface — Type
    IterationInterface

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

An interface for Base Julia iteration.

Test objects must not be empty, so that isempty(obj) == false.

Extended help

Mandatory keys:

  • isempty: test iterator is not empty
  • iterate:
    • iterate does not return nothing
    • iterate returns a Tuple
    • second iterate returns a Tuple or Nothing
  • isiterable
  • eltype
  • size
  • in: in returns true for all values in x

Optional keys:

  • reverse
  • indexing:
    • can call firstindex
    • can call lastindex
    • can call getindex
    • getindex matches iteration order
source
BaseInterfaces.SetInterface — Type
    SetInterface

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

The AbstractSet interface

Extended help

Mandatory keys:

  • isempty: defines isempty and testdata is not empty
  • eltype: elements eltype of set s are subtypes of eltype(s)
  • length: set defines length and test object has length larger than zero
  • iteration: follows the IterationInterface

Optional keys:

  • copy: creates an identical object with the same values, that is not the same object
  • empty:
    • returns an empty set able to hold elements of type U
    • returns an empty set able to hold elements of arbitrary types
  • hasfastin: hasfastin returns a Bool
  • setdiff:
    • setdiff with itself is an empty set of the same type
    • setdiff with an empty set is equal to itself
  • intersect:
    • intersect of set with itself is itself
    • intersect of set with an empty set is an empty set
  • union:
    • union of a set with itself equals itself
    • union of a set an empty set equals itself
  • copymutable: creates an identical mutable object with the same values, that is not the same object
  • emptymutable:
    • returns an empty set able to hold elements of type U
    • returns an empty set able to hold elements of arbitrary types
  • empty!: empty! removes all elements from the set
  • delete!: delete! removes element valued x of the set
  • push!: push! adds an element to the set
  • sizehint!: can set a size hint
source
BaseInterfaces.StringInterface — Type
    StringInterface

An Interfaces.jl Interface with mandatory components (:ncodeunits, :iterate, :codeunit, :isvalid, :eltype) and optional components (:length,).

AbstractString interface

Test objects must not be empty, so that isempty(obj) == false.

Extended help

Mandatory keys:

  • ncodeunits: ncodeunit returns an Int
  • iterate: AbstractString follows the IterationInterface
  • codeunit: the first codeunit is a UInt8/16/32
  • isvalid: isvalid returns a Bool
  • eltype: eltype returns a type <: AbatractChar

Optional keys:

  • length: length return an Int
source
diff --git a/previews/PR52/basic/index.html b/previews/PR52/basic/index.html index 8d3d609..9db7aaf 100644 --- a/previews/PR52/basic/index.html +++ b/previews/PR52/basic/index.html @@ -48,4 +48,4 @@ @test Interfaces.test(Duck) == true # Test all implemented interfaces for Duck @test Interfaces.test(Animals.AnimalInterface) == true # Test all implemented types for AnimalInterface - @test Interfaces.test_objects(Animals.AnimalInterface) == Dict(Duck => ducks)
Test Passed

This page was generated using Literate.jl.

+ @test Interfaces.test_objects(Animals.AnimalInterface) == Dict(Duck => ducks)
Test Passed

This page was generated using Literate.jl.

diff --git a/previews/PR52/index.html b/previews/PR52/index.html index 7936c0c..a5bf09d 100644 --- a/previews/PR52/index.html +++ b/previews/PR52/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.