From 9e32cd36f3ca27ee4e97004da87814b0648408a7 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sun, 16 Jun 2024 10:04:01 +0000 Subject: [PATCH] build based on c421e6d --- dev/.documenter-siteinfo.json | 2 +- dev/advanced/index.html | 4 +- dev/api/index.html | 14 +- dev/assets/documenter.js | 923 +++++++++++++++---------- dev/assets/themes/documenter-dark.css | 2 +- dev/assets/themes/documenter-light.css | 2 +- dev/baseinterfaces/index.html | 2 +- dev/basic/index.html | 2 +- dev/index.html | 2 +- dev/objects.inv | Bin 0 -> 582 bytes dev/search_index.js | 2 +- 11 files changed, 558 insertions(+), 397 deletions(-) create mode 100644 dev/objects.inv diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 3ecaddf..96d862a 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.1","generation_timestamp":"2024-02-26T15:25:48","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.4","generation_timestamp":"2024-06-16T10:03:58","documenter_version":"1.4.1"}} \ No newline at end of file diff --git a/dev/advanced/index.html b/dev/advanced/index.html index e33ab00..c88d53d 100644 --- a/dev/advanced/index.html +++ b/dev/advanced/index.html @@ -1,5 +1,5 @@ -Advanced · Interfaces.jl
GitHub

Advanced

Here's an example of multi-argument interface using groups. For mathematicians, a group is just a set of objects where you can perform multiplication and inversion, such that an element multiplies by its inverse yields a neutral element.

Warning

This functionality is still experimental and might evolve in the future. If you have feedback about it, open an issue to help us improve it!

using Interfaces

Definition

Unlike the AnimalInterface, this example involves functions with more than one argument. Such arguments need to be passed to the interface testing code, which means the interface definition must take them into account as well.

For technical reasons, we provide a type called Arguments that you should use for this purpose. It behaves exactly like a NamedTuple but enables easier dispatch.

module Group
+Advanced · Interfaces.jl
GitHub
Advanced
Here's an example of a multi-argument interface where we implement groups. For mathematicians, a group is just a set of objects where you can perform multiplication and inversion, such that an element multiplied by its inverse yields a neutral element.
Warning
This functionality is still experimental and might evolve in the future. If you have feedback about it, open an issue to help us improve it!
using Interfaces
Definition
Unlike the AnimalInterface, this example involves functions with more than one argument. Such arguments need to be passed to the interface testing code, which means the interface definition must take them into account as well.
For technical reasons, we provide a type called Arguments that you should use for this purpose. It behaves exactly like a NamedTuple but enables easier dispatch.
module Group
 
 using Interfaces
 
@@ -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 7a9ef99..f06eb19 100644 --- a/dev/api/index.html +++ b/dev/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/dev/assets/documenter.js b/dev/assets/documenter.js index f531160..c6562b5 100644 --- a/dev/assets/documenter.js +++ b/dev/assets/documenter.js @@ -4,7 +4,6 @@ requirejs.config({ 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia.min', 'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/headroom.min', 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min', - 'minisearch': 'https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min', 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/contrib/auto-render.min', 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min', 'headroom-jquery': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/jQuery.headroom.min', @@ -103,9 +102,10 @@ $(document).on("click", ".docstring header", function () { }); }); -$(document).on("click", ".docs-article-toggle-button", function () { +$(document).on("click", ".docs-article-toggle-button", function (event) { let articleToggleTitle = "Expand docstring"; let navArticleToggleTitle = "Expand all docstrings"; + let animationSpeed = event.noToggleAnimation ? 0 : 400; debounce(() => { if (isExpanded) { @@ -116,7 +116,7 @@ $(document).on("click", ".docs-article-toggle-button", function () { isExpanded = false; - $(".docstring section").slideUp(); + $(".docstring section").slideUp(animationSpeed); } else { $(this).removeClass("fa-chevron-down").addClass("fa-chevron-up"); $(".docstring-article-toggle-button") @@ -127,7 +127,7 @@ $(document).on("click", ".docs-article-toggle-button", function () { articleToggleTitle = "Collapse docstring"; navArticleToggleTitle = "Collapse all docstrings"; - $(".docstring section").slideDown(); + $(".docstring section").slideDown(animationSpeed); } $(this).prop("title", navArticleToggleTitle); @@ -224,224 +224,465 @@ $(document).ready(function () { }) //////////////////////////////////////////////////////////////////////////////// -require(['jquery', 'minisearch'], function($, minisearch) { - -// In general, most search related things will have "search" as a prefix. -// To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc +require(['jquery'], function($) { -let results = []; -let timer = undefined; +$(document).ready(function () { + let meta = $("div[data-docstringscollapsed]").data(); -let data = documenterSearchIndex["docs"].map((x, key) => { - x["id"] = key; // minisearch requires a unique for each object - return x; + if (meta?.docstringscollapsed) { + $("#documenter-article-toggle-button").trigger({ + type: "click", + noToggleAnimation: true, + }); + } }); -// list below is the lunr 2.1.3 list minus the intersect with names(Base) -// (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) -// ideally we'd just filter the original list but it's not available as a variable -const stopWords = new Set([ - "a", - "able", - "about", - "across", - "after", - "almost", - "also", - "am", - "among", - "an", - "and", - "are", - "as", - "at", - "be", - "because", - "been", - "but", - "by", - "can", - "cannot", - "could", - "dear", - "did", - "does", - "either", - "ever", - "every", - "from", - "got", - "had", - "has", - "have", - "he", - "her", - "hers", - "him", - "his", - "how", - "however", - "i", - "if", - "into", - "it", - "its", - "just", - "least", - "like", - "likely", - "may", - "me", - "might", - "most", - "must", - "my", - "neither", - "no", - "nor", - "not", - "of", - "off", - "often", - "on", - "or", - "other", - "our", - "own", - "rather", - "said", - "say", - "says", - "she", - "should", - "since", - "so", - "some", - "than", - "that", - "the", - "their", - "them", - "then", - "there", - "these", - "they", - "this", - "tis", - "to", - "too", - "twas", - "us", - "wants", - "was", - "we", - "were", - "what", - "when", - "who", - "whom", - "why", - "will", - "would", - "yet", - "you", - "your", -]); - -let index = new minisearch({ - fields: ["title", "text"], // fields to index for full-text search - storeFields: ["location", "title", "text", "category", "page"], // fields to return with search results - processTerm: (term) => { - let word = stopWords.has(term) ? null : term; - if (word) { - // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names - word = word - .replace(/^[^a-zA-Z0-9@!]+/, "") - .replace(/[^a-zA-Z0-9@!]+$/, ""); - } +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { - return word ?? null; - }, - // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not find anything if searching for "add!", only for the entire qualification - tokenize: (string) => string.split(/[\s\-\.]+/), - // options which will be applied during the search - searchOptions: { - boost: { title: 100 }, - fuzzy: 2, +/* +To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc + +PSEUDOCODE: + +Searching happens automatically as the user types or adjusts the selected filters. +To preserve responsiveness, as much as possible of the slow parts of the search are done +in a web worker. Searching and result generation are done in the worker, and filtering and +DOM updates are done in the main thread. The filters are in the main thread as they should +be very quick to apply. This lets filters be changed without re-searching with minisearch +(which is possible even if filtering is on the worker thread) and also lets filters be +changed _while_ the worker is searching and without message passing (neither of which are +possible if filtering is on the worker thread) + +SEARCH WORKER: + +Import minisearch + +Build index + +On message from main thread + run search + find the first 200 unique results from each category, and compute their divs for display + note that this is necessary and sufficient information for the main thread to find the + first 200 unique results from any given filter set + post results to main thread + +MAIN: + +Launch worker + +Declare nonconstant globals (worker_is_running, last_search_text, unfiltered_results) + +On text update + if worker is not running, launch_search() + +launch_search + set worker_is_running to true, set last_search_text to the search text + post the search query to worker + +on message from worker + if last_search_text is not the same as the text in the search field, + the latest search result is not reflective of the latest search query, so update again + launch_search() + otherwise + set worker_is_running to false + + regardless, display the new search results to the user + save the unfiltered_results as a global + update_search() + +on filter click + adjust the filter selection + update_search() + +update_search + apply search filters by looping through the unfiltered_results and finding the first 200 + unique results that match the filters + + Update the DOM +*/ + +/////// SEARCH WORKER /////// + +function worker_function(documenterSearchIndex, documenterBaseURL, filters) { + importScripts( + "https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min.js" + ); + + let data = documenterSearchIndex.map((x, key) => { + x["id"] = key; // minisearch requires a unique for each object + return x; + }); + + // list below is the lunr 2.1.3 list minus the intersect with names(Base) + // (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) + // ideally we'd just filter the original list but it's not available as a variable + const stopWords = new Set([ + "a", + "able", + "about", + "across", + "after", + "almost", + "also", + "am", + "among", + "an", + "and", + "are", + "as", + "at", + "be", + "because", + "been", + "but", + "by", + "can", + "cannot", + "could", + "dear", + "did", + "does", + "either", + "ever", + "every", + "from", + "got", + "had", + "has", + "have", + "he", + "her", + "hers", + "him", + "his", + "how", + "however", + "i", + "if", + "into", + "it", + "its", + "just", + "least", + "like", + "likely", + "may", + "me", + "might", + "most", + "must", + "my", + "neither", + "no", + "nor", + "not", + "of", + "off", + "often", + "on", + "or", + "other", + "our", + "own", + "rather", + "said", + "say", + "says", + "she", + "should", + "since", + "so", + "some", + "than", + "that", + "the", + "their", + "them", + "then", + "there", + "these", + "they", + "this", + "tis", + "to", + "too", + "twas", + "us", + "wants", + "was", + "we", + "were", + "what", + "when", + "who", + "whom", + "why", + "will", + "would", + "yet", + "you", + "your", + ]); + + let index = new MiniSearch({ + fields: ["title", "text"], // fields to index for full-text search + storeFields: ["location", "title", "text", "category", "page"], // fields to return with results processTerm: (term) => { let word = stopWords.has(term) ? null : term; if (word) { + // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names word = word .replace(/^[^a-zA-Z0-9@!]+/, "") .replace(/[^a-zA-Z0-9@!]+$/, ""); + + word = word.toLowerCase(); } return word ?? null; }, + // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not + // find anything if searching for "add!", only for the entire qualification tokenize: (string) => string.split(/[\s\-\.]+/), - }, -}); + // options which will be applied during the search + searchOptions: { + prefix: true, + boost: { title: 100 }, + fuzzy: 2, + }, + }); -index.addAll(data); + index.addAll(data); + + /** + * Used to map characters to HTML entities. + * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts + */ + const htmlEscapes = { + "&": "&", + "<": "<", + ">": ">", + '"': """, + "'": "'", + }; + + /** + * Used to match HTML entities and HTML characters. + * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts + */ + const reUnescapedHtml = /[&<>"']/g; + const reHasUnescapedHtml = RegExp(reUnescapedHtml.source); + + /** + * Escape function from lodash + * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts + */ + function escape(string) { + return string && reHasUnescapedHtml.test(string) + ? string.replace(reUnescapedHtml, (chr) => htmlEscapes[chr]) + : string || ""; + } -let filters = [...new Set(data.map((x) => x.category))]; -var modal_filters = make_modal_body_filters(filters); -var filter_results = []; + /** + * Make the result component given a minisearch result data object and the value + * of the search input as queryString. To view the result object structure, refer: + * https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult + * + * @param {object} result + * @param {string} querystring + * @returns string + */ + function make_search_result(result, querystring) { + let search_divider = `
`; + let display_link = + result.location.slice(Math.max(0), Math.min(50, result.location.length)) + + (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div + + if (result.page !== "") { + display_link += ` (${result.page})`; + } -$(document).on("keyup", ".documenter-search-input", function (event) { - // Adding a debounce to prevent disruptions from super-speed typing! - debounce(() => update_search(filter_results), 300); + let textindex = new RegExp(`${querystring}`, "i").exec(result.text); + let text = + textindex !== null + ? result.text.slice( + Math.max(textindex.index - 100, 0), + Math.min( + textindex.index + querystring.length + 100, + result.text.length + ) + ) + : ""; // cut-off text before and after from the match + + text = text.length ? escape(text) : ""; + + let display_result = text.length + ? "..." + + text.replace( + new RegExp(`${escape(querystring)}`, "i"), // For first occurrence + '$&' + ) + + "..." + : ""; // highlights the match + + let in_code = false; + if (!["page", "section"].includes(result.category.toLowerCase())) { + in_code = true; + } + + // We encode the full url to escape some special characters which can lead to broken links + let result_div = ` + +
+
${escape(result.title)}
+
${result.category}
+
+

+ ${display_result} +

+
+ ${display_link} +
+ + ${search_divider} + `; + + return result_div; + } + + self.onmessage = function (e) { + let query = e.data; + let results = index.search(query, { + filter: (result) => { + // Only return relevant results + return result.score >= 1; + }, + }); + + // Pre-filter to deduplicate and limit to 200 per category to the extent + // possible without knowing what the filters are. + let filtered_results = []; + let counts = {}; + for (let filter of filters) { + counts[filter] = 0; + } + let present = {}; + + for (let result of results) { + cat = result.category; + cnt = counts[cat]; + if (cnt < 200) { + id = cat + "---" + result.location; + if (present[id]) { + continue; + } + present[id] = true; + filtered_results.push({ + location: result.location, + category: cat, + div: make_search_result(result, query), + }); + } + } + + postMessage(filtered_results); + }; +} + +// `worker = Threads.@spawn worker_function(documenterSearchIndex)`, but in JavaScript! +const filters = [ + ...new Set(documenterSearchIndex["docs"].map((x) => x.category)), +]; +const worker_str = + "(" + + worker_function.toString() + + ")(" + + JSON.stringify(documenterSearchIndex["docs"]) + + "," + + JSON.stringify(documenterBaseURL) + + "," + + JSON.stringify(filters) + + ")"; +const worker_blob = new Blob([worker_str], { type: "text/javascript" }); +const worker = new Worker(URL.createObjectURL(worker_blob)); + +/////// SEARCH MAIN /////// + +// Whether the worker is currently handling a search. This is a boolean +// as the worker only ever handles 1 or 0 searches at a time. +var worker_is_running = false; + +// The last search text that was sent to the worker. This is used to determine +// if the worker should be launched again when it reports back results. +var last_search_text = ""; + +// The results of the last search. This, in combination with the state of the filters +// in the DOM, is used compute the results to display on calls to update_search. +var unfiltered_results = []; + +// Which filter is currently selected +var selected_filter = ""; + +$(document).on("input", ".documenter-search-input", function (event) { + if (!worker_is_running) { + launch_search(); + } }); +function launch_search() { + worker_is_running = true; + last_search_text = $(".documenter-search-input").val(); + worker.postMessage(last_search_text); +} + +worker.onmessage = function (e) { + if (last_search_text !== $(".documenter-search-input").val()) { + launch_search(); + } else { + worker_is_running = false; + } + + unfiltered_results = e.data; + update_search(); +}; + $(document).on("click", ".search-filter", function () { if ($(this).hasClass("search-filter-selected")) { - $(this).removeClass("search-filter-selected"); + selected_filter = ""; } else { - $(this).addClass("search-filter-selected"); + selected_filter = $(this).text().toLowerCase(); } - // Adding a debounce to prevent disruptions from crazy clicking! - debounce(() => get_filters(), 300); + // This updates search results and toggles classes for UI: + update_search(); }); -/** - * A debounce function, takes a function and an optional timeout in milliseconds - * - * @function callback - * @param {number} timeout - */ -function debounce(callback, timeout = 300) { - clearTimeout(timer); - timer = setTimeout(callback, timeout); -} - /** * Make/Update the search component - * - * @param {string[]} selected_filters */ -function update_search(selected_filters = []) { - let initial_search_body = ` -
Type something to get started!
- `; - +function update_search() { let querystring = $(".documenter-search-input").val(); if (querystring.trim()) { - results = index.search(querystring, { - filter: (result) => { - // Filtering results - if (selected_filters.length === 0) { - return result.score >= 1; - } else { - return ( - result.score >= 1 && selected_filters.includes(result.category) - ); - } - }, - }); + if (selected_filter == "") { + results = unfiltered_results; + } else { + results = unfiltered_results.filter((result) => { + return selected_filter == result.category.toLowerCase(); + }); + } let search_result_container = ``; + let modal_filters = make_modal_body_filters(); let search_divider = `
`; if (results.length) { @@ -449,19 +690,23 @@ function update_search(selected_filters = []) { let count = 0; let search_results = ""; - results.forEach(function (result) { - if (result.location) { - // Checking for duplication of results for the same page - if (!links.includes(result.location)) { - search_results += make_search_result(result, querystring); - count++; - } - + for (var i = 0, n = results.length; i < n && count < 200; ++i) { + let result = results[i]; + if (result.location && !links.includes(result.location)) { + search_results += result.div; + count++; links.push(result.location); } - }); + } - let result_count = `
${count} result(s)
`; + if (count == 1) { + count_str = "1 result"; + } else if (count == 200) { + count_str = "200+ results"; + } else { + count_str = count + " results"; + } + let result_count = `
${count_str}
`; search_result_container = `
@@ -490,125 +735,37 @@ function update_search(selected_filters = []) { $(".search-modal-card-body").html(search_result_container); } else { - filter_results = []; - modal_filters = make_modal_body_filters(filters, filter_results); - if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { $(".search-modal-card-body").addClass("is-justify-content-center"); } - $(".search-modal-card-body").html(initial_search_body); + $(".search-modal-card-body").html(` +
Type something to get started!
+ `); } } /** * Make the modal filter html * - * @param {string[]} filters - * @param {string[]} selected_filters * @returns string */ -function make_modal_body_filters(filters, selected_filters = []) { - let str = ``; - - filters.forEach((val) => { - if (selected_filters.includes(val)) { - str += `${val}`; - } else { - str += `${val}`; - } - }); +function make_modal_body_filters() { + let str = filters + .map((val) => { + if (selected_filter == val.toLowerCase()) { + return `${val}`; + } else { + return `${val}`; + } + }) + .join(""); - let filter_html = ` + return `
Filters: ${str} -
- `; - - return filter_html; -} - -/** - * Make the result component given a minisearch result data object and the value of the search input as queryString. - * To view the result object structure, refer: https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult - * - * @param {object} result - * @param {string} querystring - * @returns string - */ -function make_search_result(result, querystring) { - let search_divider = `
`; - let display_link = - result.location.slice(Math.max(0), Math.min(50, result.location.length)) + - (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div - - if (result.page !== "") { - display_link += ` (${result.page})`; - } - - let textindex = new RegExp(`\\b${querystring}\\b`, "i").exec(result.text); - let text = - textindex !== null - ? result.text.slice( - Math.max(textindex.index - 100, 0), - Math.min( - textindex.index + querystring.length + 100, - result.text.length - ) - ) - : ""; // cut-off text before and after from the match - - let display_result = text.length - ? "..." + - text.replace( - new RegExp(`\\b${querystring}\\b`, "i"), // For first occurrence - '$&' - ) + - "..." - : ""; // highlights the match - - let in_code = false; - if (!["page", "section"].includes(result.category.toLowerCase())) { - in_code = true; - } - - // We encode the full url to escape some special characters which can lead to broken links - let result_div = ` - -
-
${result.title}
-
${result.category}
-
-

- ${display_result} -

-
- ${display_link} -
- - ${search_divider} - `; - - return result_div; -} - -/** - * Get selected filters, remake the filter html and lastly update the search modal - */ -function get_filters() { - let ele = $(".search-filters .search-filter-selected").get(); - filter_results = ele.map((x) => $(x).text().toLowerCase()); - modal_filters = make_modal_body_filters(filters, filter_results); - update_search(filter_results); +
`; } }) @@ -635,103 +792,107 @@ $(document).ready(function () { //////////////////////////////////////////////////////////////////////////////// require(['jquery'], function($) { -let search_modal_header = ` -
-
-

- - - - -

-
-
- -
-
-`; - -let initial_search_body = ` -
Type something to get started!
-`; - -let search_modal_footer = ` - -`; - -$(document.body).append( - ` - + @test Interfaces.test(Animals.AnimalInterface) == true # Test all implemented types for AnimalInterface
Test Passed

This page was generated using Literate.jl.

diff --git a/dev/index.html b/dev/index.html index 5f4312b..9da472a 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.

diff --git a/dev/objects.inv b/dev/objects.inv new file mode 100644 index 0000000000000000000000000000000000000000..8be3d17ff5bbe21a0a602b02ee1b7658946586b2 GIT binary patch literal 582 zcmV-M0=fMoAX9K?X>NERX>N99Zgg*Qc_4OWa&u{KZXhxWBOp+6Z)#;@bUGkOZggdG zW?^Gxb1rIZ3L_v^WpZMd?av*PJAarPHb0B7E zY-J#6b0A}HZE$jBb8}^6Aa!$TZf78RY-wUH3V58IR9#QPFcf{~S2WSRF~N_-g!tgl z2lr+IK9ka3q`0-S>(qtt-)##k?c9>Z7r1TDJ?HfF0^<~ZP^svQ3WDNmgkD4rqctuW z@we^91kKIY2-7dj2~Z!<>`hQ|sz$hA0is~~@HIseHXuPmj0`ZYKyEOBvZd#pSYb%r z`f8VXENRG);WcE2j+|SI3CUx}9QL#<>CUjvbEI$C$6`{@tziyx7q_pb z1Go0Pds8ThWQAgaqg^)JRGiq_@djuGr5XTZd67X5T$KaBk7snetaQ0gcs)kV$H7qK zm`Ks|d%e-!wA~%u&vjRH^Az1ogW~?Vt=rTm*+reNMRrymCLfY$^&?G(fzU~7{+=08 zZfP`CT>$Eukw2}euCNJsXn)sB0bMDHnTp@IX4)SUSsupdRB1N5G?5(8_g2ptT0YEt z8@_rDYAa|*WIcj9wB?3+bV4J#Qi( U>m88(a9X!mz~J%z1%DJD{E2cEv;Y7A literal 0 HcmV?d00001 diff --git a/dev/search_index.js b/dev/search_index.js index e897780..71042c5 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"api/#API-reference","page":"API reference","title":"API reference","text":"","category":"section"},{"location":"api/#Docstrings","page":"API reference","title":"Docstrings","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"Modules = [Interfaces]","category":"page"},{"location":"api/#Interfaces.Interfaces","page":"API reference","title":"Interfaces.Interfaces","text":"Interfaces\n\nA Julia package for specifying and testing interfaces (conditions verified by a set of methods applied to a type).\n\n\n\n\n\n","category":"module"},{"location":"api/#Interfaces.Arguments","page":"API reference","title":"Interfaces.Arguments","text":"Arguments{names,T}\n\nArguments(; kw...)\nArguments(nt::NamedTuple)\n\nA wrapper for a NamedTuple.\n\n\n\n\n\n","category":"type"},{"location":"api/#Interfaces.Interface","page":"API reference","title":"Interfaces.Interface","text":"Interface{Components}\n\nAbstract supertype for all Interfaces.jl interfaces.\n\nComponents is an Tuple of Symbol.\n\n\n\n\n\n","category":"type"},{"location":"api/#Interfaces.components","page":"API reference","title":"Interfaces.components","text":"components(::Type{<:Interface})\n\nReturns the components of the interface, as a NamedTuple of NamedTuple.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.description","page":"API reference","title":"Interfaces.description","text":"description(::Type{<:Interface})\n\nReturns a String description of an interface.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.implemented_trait-Union{Tuple{T}, Tuple{Type{T}, Any}} where T<:Interfaces.Interface","page":"API reference","title":"Interfaces.implemented_trait","text":"implemented_trait(T::Type{<:Interface}, obj)\nimplemented_trait(T::Type{<:Interface{Option}}, obj)\n\nProvides a single type for using interface implementation as a trait.\n\nReturns Implemented{T}() or NotImplemented{T}().\n\n\n\n\n\n","category":"method"},{"location":"api/#Interfaces.implements","page":"API reference","title":"Interfaces.implements","text":"implements(::Type{<:Interface}, obj)\nimplements(::Type{<:Interface{Options}}, obj)\n\nReturns whether an object implements an interface, as a Bool.\n\nobj can be an be an object or a Type.\n\nOptions 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.\n\nWithout specifying Options, the return value specifies that at least all the mandatory components of the interace are implemented.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.optional_keys","page":"API reference","title":"Interfaces.optional_keys","text":"optional_keys(T::Type{<:Interface}, O::Type)\n\nGet the keys for the optional components of an Interface, as a tuple os Symbol.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.requiredtype","page":"API reference","title":"Interfaces.requiredtype","text":"requiredtype(::Type{<:Interface})\n\nReturns the supertype required for all interface implementations.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.test","page":"API reference","title":"Interfaces.test","text":"test(; kw...)\ntest(mod::Module; kw...)\ntest(::Type; kw...)\ntest(::Type{<:Interface}; kw...)\ntest(::Type{<:Interface}, mod::Module; kw...)\ntest(::Type{<:Interface}, type::Type, [test_objects]; kw...)\n\nTest if an interface is implemented correctly, returning true or false.\n\nThere are a number of ways to select implementations to test:\n\nWith no arguments, test all defined Interfaces currenty imported.\nIf a Module is passed, all Interface implementations defined in it will be tested. This is probably the best option to put in package tests.\nIf only an Interface is passed, all implementations of it are tested.\nIf only a Type is passed, all interfaces it implements are tested.\nIf both a Module and an Interface are passed, test the intersection. of implementations of the Interface for the Module.\nIf an Interface and Type are passed, the implementation for that type will be tested.\n\nIf no interface type is passed, Interfaces.jl will find all the interfaces available and test them.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.test_objects","page":"API reference","title":"Interfaces.test_objects","text":"test_objects(T::Type{<:Interface}, O::Type)\n\nGet the test object(s) for type O and interface T.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.@implements-Tuple{Any, Any, Any}","page":"API reference","title":"Interfaces.@implements","text":"@implements(interface, objtype, test_objects)\n\nDeclare that an interface implements an interface, or multipleinterfaces.\n\nThe macro can only be used once per module for any one type. To define multiple interfaces a type implements, combine them in square brackets.\n\nExample\n\nHere we implement the IterationInterface for Base julia, indicating with (:indexing, :reverse) that our object can be indexed and works with Iterators.reverse:\n\nusing BaseInterfaces, Interfaces\n@implements BaseInterfaces.IterationInterface{(:indexing,:reverse)} MyObject [MyObject(1:10), MyObject(10:-1:1)]\n\n\n\n\n\n","category":"macro"},{"location":"api/#Interfaces.@interface-Tuple{Symbol, Any, Any, Any}","page":"API reference","title":"Interfaces.@interface","text":"@interface(interfacename, components, [description])\n\nDefine an interface that can apply to types <: Any.\n\ncomponents = (\n mandatory = (\n length = x -> length(x) = prod(size(x)),\n ndims = x -> ndims(x) = length(size(x)),\n ),\n optional = (;)\n)\ndescription = \"A description of the interface\"\n\n@interface MyInterface Any components description\n\n\n\n\n\n","category":"macro"},{"location":"api/#Index","page":"API reference","title":"Index","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"EditURL = \"../../test/basic.jl\"","category":"page"},{"location":"basic/#Basic","page":"Basic","title":"Basic","text":"","category":"section"},{"location":"basic/","page":"Basic","title":"Basic","text":"Here's an example of single-argument interface using animals, and the implementation of a duck.","category":"page"},{"location":"basic/#Definition","page":"Basic","title":"Definition","text":"","category":"section"},{"location":"basic/","page":"Basic","title":"Basic","text":"First we define the interface methods, and a list of mandatory and optional properties of the interface, with conditions, using the @interface macro.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"The @interface macro takes three arguments:","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"The name of the interface, which should usully end with \"Interface\"\nThe mandatory and optional components of the interface written as a NamedTuple, with functions or tuple of functions that test them.\nThe interface docstring (the interface is represented as a type)","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"module Animals\n\nusing Interfaces\n\nabstract type Animal end\n\nfunction age end\nfunction walk end\nfunction talk end\nfunction dig end\n\ncomponents = (\n mandatory = (\n age = (\n \"all animals have a `Real` age\" => x -> age(x) isa Real,\n \"all animals have an age larger than zero\" => x -> age(x) >= 0,\n ),\n ),\n optional = (\n walk = \"this animal can walk\" => x -> walk(x) isa String,\n talk = \"this animal can talk\" => x -> talk(x) isa Symbol,\n dig = \"this animal can dig\" => x -> dig(x) isa String,\n )\n)\n\ndescription = \"\"\"\nDefines a generic interface for animals to do the things they do best.\n\"\"\"\n\n@interface AnimalInterface Animal components description\n\nend;\nnothing #hide","category":"page"},{"location":"basic/#Implementation","page":"Basic","title":"Implementation","text":"","category":"section"},{"location":"basic/","page":"Basic","title":"Basic","text":"using Interfaces, Test","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"Now we implement the AnimalInterface, for a Duck.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"struct Duck <: Animals.Animal\n age::Int\nend\n\nAnimals.age(duck::Duck) = duck.age\nAnimals.walk(::Duck) = \"waddle\"\nAnimals.talk(::Duck) = :quack","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"We then test that the interface is correctly implemented","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"ducks = [Duck(1), Duck(2)]\nInterfaces.test(Animals.AnimalInterface, Duck, ducks)","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"As well as two optional methods","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"Interfaces.test(Animals.AnimalInterface{(:walk,:talk)}, Duck, ducks)","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"Finally we declare it, so that the information can be used in static dispatch.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"The @implements macro takes two arguments.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"The interface type, with a tuple of optional components in its first type parameter.\nThe type for which the interface is implemented.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"@implements Animals.AnimalInterface{(:walk,:talk)} Duck [Duck(1), Duck(2)]","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"Now let's see what happens when the interface is not correctly implemented.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"struct Chicken <: Animals.Animal end","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"As expected, the tests fail","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"chickens = [Chicken()]\ntry\n Interfaces.test(Animals.AnimalInterface, Chicken, chickens)\ncatch e\n print(e)\nend\n\n\n\n @test Interfaces.test(Duck) == true # Test all implemented interfaces for Duck\n @test Interfaces.test(Animals.AnimalInterface) == true # Test all implemented types for AnimalInterface","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"This page was generated using Literate.jl.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"EditURL = \"../../test/advanced.jl\"","category":"page"},{"location":"advanced/#Advanced","page":"Advanced","title":"Advanced","text":"","category":"section"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Here's an example of multi-argument interface using groups. For mathematicians, a group is just a set of objects where you can perform multiplication and inversion, such that an element multiplies by its inverse yields a neutral element.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"warning: Warning\nThis functionality is still experimental and might evolve in the future. If you have feedback about it, open an issue to help us improve it!","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"using Interfaces","category":"page"},{"location":"advanced/#Definition","page":"Advanced","title":"Definition","text":"","category":"section"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Unlike the AnimalInterface, this example involves functions with more than one argument. Such arguments need to be passed to the interface testing code, which means the interface definition must take them into account as well.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"For technical reasons, we provide a type called Arguments that you should use for this purpose. It behaves exactly like a NamedTuple but enables easier dispatch.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"module Group\n\nusing Interfaces\n\nfunction neutral end\nfunction multiplication end\nfunction inversion end\n\n@interface GroupInterface Number (\n mandatory = (;\n neutral_check = (\n \"neutral stable\" => a::Arguments -> neutral(typeof(a.x)) isa typeof(a.x),\n ),\n multiplication_check = (\n \"multiplication stable\" => a::Arguments -> multiplication(a.x, a.y) isa typeof(a.x),\n ),\n inversion_check = (\n \"inversion stable\" => a::Arguments -> inversion(a.x) isa typeof(a.x),\n \"inversion works\" => a::Arguments -> multiplication(a.x, inversion(a.x)) ≈ neutral(typeof(a.x)),\n ),\n ),\n optional = (;),\n) \"\"\"\nA group is a set of elements with a neutral element where you can perform multiplications and inversions.\n\nThe conditions checking the interface accept an `Arguments` object with two fields named `x` and `y`.\nThe type of the first field `x` must be the type you wish to declare as implementing `GroupInterface`.\n\"\"\"\n\nend;\nnothing #hide","category":"page"},{"location":"advanced/#Implementation","page":"Advanced","title":"Implementation","text":"","category":"section"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Let's try to see if our favorite number types do indeed behave like a group.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Group.neutral(::Type{N}) where {N<:Number} = one(N)\nGroup.multiplication(x::Number, y::Number) = x * y\nGroup.inversion(x::Number) = inv(x)","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"First, we check it for floating point numbers, giving a list of Arguments objects with the proper fields to the test function.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"float_pairs = [Arguments(x = 2.0, y = 1.0)]\nInterfaces.test(Group.GroupInterface, Float64, float_pairs)","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"We can thus declare proudly","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"@implements Group.GroupInterface Float64 [Arguments(x = 2.0, y = 1.0)]","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Now we check it for integer numbers. The reason it fails is because for an integer x, the inverse 1/x is no longer an integer! Thus integer numbers are not a multiplicative group.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"int_pairs = [Arguments(x = 2, y = 1)]\nInterfaces.test(Group.GroupInterface, Int, int_pairs)","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"What happens if we give an input whose field types (Int) are not coherent with the type we are testing (Float64)?","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"try\n Interfaces.test(Group.GroupInterface, Float64, int_pairs)\ncatch e\n print(e.msg)\nend","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"In summary, there are two things to remember:","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"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.\nThe 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.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"This page was generated using Literate.jl.","category":"page"},{"location":"","page":"Home","title":"Home","text":"EditURL = \"https://github.com/rafaqz/Interfaces.jl/blob/main/README.md\"","category":"page"},{"location":"#Interfaces","page":"Home","title":"Interfaces","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"(Image: Stable) (Image: Dev) (Image: Build Status) (Image: Coverage)","category":"page"},{"location":"","page":"Home","title":"Home","text":"Macros for defining the required behaviours of Julia interfaces, and stating that an object implements them.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The goal is to get as much as possible out of defining an interface, specifically:","category":"page"},{"location":"","page":"Home","title":"Home","text":"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.\nTests: @implements declarations should be tested in package tests.\nDocs: interface documentation can be inserted into trait documentation.","category":"page"},{"location":"","page":"Home","title":"Home","text":"See the IterationInterface in BaseInterfaces.jl (a subpackage of this package) or the documentation for examples of @interface and @implements.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Note: the syntax here is likely to change as we work out the best ways to define interfaces","category":"page"},{"location":"","page":"Home","title":"Home","text":"If you think it should behave differently or there is better syntax, please make an issue.","category":"page"},{"location":"baseinterfaces/#BaseInterfaces-reference","page":"BaseInterfaces.jl reference","title":"BaseInterfaces reference","text":"","category":"section"},{"location":"baseinterfaces/#Docstrings","page":"BaseInterfaces.jl reference","title":"Docstrings","text":"","category":"section"},{"location":"baseinterfaces/","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.jl reference","text":"Modules = [BaseInterfaces]","category":"page"},{"location":"baseinterfaces/#BaseInterfaces.ArrayInterface","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.ArrayInterface","text":" ArrayInterface\n\nAn 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).\n\nBase Julia AbstractArray interface\n\n\n\n\n\n","category":"type"},{"location":"baseinterfaces/#BaseInterfaces.DictInterface","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.DictInterface","text":" DictInterface\n\nAn Interfaces.jl Interface with mandatory components (:iterate, :eltype, :keytype, :valtype, :keys, :values, :getindex) and optional components (:setindex!,).\n\nAbstractDict interface requires Arguments, with d = the_dict mandatory, and when setindex is needed, k = any_valid_key_not_in_d, v = any_valid_val\n\n\n\n\n\n","category":"type"},{"location":"baseinterfaces/#BaseInterfaces.IterationInterface","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.IterationInterface","text":" IterationInterface\n\nAn Interfaces.jl Interface with mandatory components (:iterate, :isiterable, :eltype, :size, :in) and optional components (:reverse, :indexing).\n\nAn interface for Base Julia iteration\n\n\n\n\n\n","category":"type"},{"location":"baseinterfaces/#BaseInterfaces.SetInterface","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.SetInterface","text":" SetInterface\n\nAn 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!).\n\nThe AbstractSet interface\n\n\n\n\n\n","category":"type"},{"location":"baseinterfaces/#Index","page":"BaseInterfaces.jl reference","title":"Index","text":"","category":"section"},{"location":"baseinterfaces/","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.jl reference","text":"","category":"page"}] +[{"location":"api/#API-reference","page":"API reference","title":"API reference","text":"","category":"section"},{"location":"api/#Docstrings","page":"API reference","title":"Docstrings","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"Modules = [Interfaces]","category":"page"},{"location":"api/#Interfaces.Interfaces","page":"API reference","title":"Interfaces.Interfaces","text":"Interfaces\n\nA Julia package for specifying and testing interfaces (conditions verified by a set of methods applied to a type).\n\n\n\n\n\n","category":"module"},{"location":"api/#Interfaces.Arguments","page":"API reference","title":"Interfaces.Arguments","text":"Arguments{names,T}\n\nArguments(; kw...)\nArguments(nt::NamedTuple)\n\nA wrapper for a NamedTuple.\n\n\n\n\n\n","category":"type"},{"location":"api/#Interfaces.Interface","page":"API reference","title":"Interfaces.Interface","text":"Interface{Components}\n\nAbstract supertype for all Interfaces.jl interfaces.\n\nComponents is an Tuple of Symbol.\n\n\n\n\n\n","category":"type"},{"location":"api/#Interfaces.components","page":"API reference","title":"Interfaces.components","text":"components(::Type{<:Interface})\n\nReturns the components of the interface, as a NamedTuple of NamedTuple.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.description","page":"API reference","title":"Interfaces.description","text":"description(::Type{<:Interface})\n\nReturns a String description of an interface.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.implemented_trait-Union{Tuple{T}, Tuple{Type{T}, Any}} where T<:Interfaces.Interface","page":"API reference","title":"Interfaces.implemented_trait","text":"implemented_trait(T::Type{<:Interface}, obj)\nimplemented_trait(T::Type{<:Interface{Option}}, obj)\n\nProvides a single type for using interface implementation as a trait.\n\nReturns Implemented{T}() or NotImplemented{T}().\n\n\n\n\n\n","category":"method"},{"location":"api/#Interfaces.implements","page":"API reference","title":"Interfaces.implements","text":"implements(::Type{<:Interface}, obj)\nimplements(::Type{<:Interface{Options}}, obj)\n\nReturns whether an object implements an interface, as a Bool.\n\nobj can be an be an object or a Type.\n\nOptions 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.\n\nWithout specifying Options, the return value specifies that at least all the mandatory components of the interace are implemented.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.optional_keys","page":"API reference","title":"Interfaces.optional_keys","text":"optional_keys(T::Type{<:Interface}, O::Type)\n\nGet the keys for the optional components of an Interface, as a tuple os Symbol.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.requiredtype","page":"API reference","title":"Interfaces.requiredtype","text":"requiredtype(::Type{<:Interface})\n\nReturns the supertype required for all interface implementations.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.test","page":"API reference","title":"Interfaces.test","text":"test(; kw...)\ntest(mod::Module; kw...)\ntest(::Type; kw...)\ntest(::Type{<:Interface}; kw...)\ntest(::Type{<:Interface}, mod::Module; kw...)\ntest(::Type{<:Interface}, type::Type, [test_objects]; kw...)\n\nTest if an interface is implemented correctly, returning true or false.\n\nThere are a number of ways to select implementations to test:\n\nWith no arguments, test all defined Interfaces currenty imported.\nIf a Module is passed, all Interface implementations defined in it will be tested. This is probably the best option to put in package tests.\nIf only an Interface is passed, all implementations of it are tested.\nIf only a Type is passed, all interfaces it implements are tested.\nIf both a Module and an Interface are passed, test the intersection. of implementations of the Interface for the Module.\nIf an Interface and Type are passed, the implementation for that type will be tested.\n\nIf no interface type is passed, Interfaces.jl will find all the interfaces available and test them.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.test_objects","page":"API reference","title":"Interfaces.test_objects","text":"test_objects(T::Type{<:Interface}, O::Type)\n\nGet the test object(s) for type O and interface T.\n\n\n\n\n\n","category":"function"},{"location":"api/#Interfaces.@implements-Tuple{Any, Any, Any}","page":"API reference","title":"Interfaces.@implements","text":"@implements(interface, objtype, test_objects)\n\nDeclare that an interface implements an interface, or multipleinterfaces.\n\nThe macro can only be used once per module for any one type. To define multiple interfaces a type implements, combine them in square brackets.\n\nExample\n\nHere we implement the IterationInterface for Base julia, indicating with (:indexing, :reverse) that our object can be indexed and works with Iterators.reverse:\n\nusing BaseInterfaces, Interfaces\n@implements BaseInterfaces.IterationInterface{(:indexing,:reverse)} MyObject [MyObject(1:10), MyObject(10:-1:1)]\n\n\n\n\n\n","category":"macro"},{"location":"api/#Interfaces.@interface-Tuple{Symbol, Any, Any, Any}","page":"API reference","title":"Interfaces.@interface","text":"@interface(interfacename, components, [description])\n\nDefine an interface that can apply to types <: Any.\n\ncomponents = (\n mandatory = (\n length = x -> length(x) = prod(size(x)),\n ndims = x -> ndims(x) = length(size(x)),\n ),\n optional = (;)\n)\ndescription = \"A description of the interface\"\n\n@interface MyInterface Any components description\n\n\n\n\n\n","category":"macro"},{"location":"api/#Index","page":"API reference","title":"Index","text":"","category":"section"},{"location":"api/","page":"API reference","title":"API reference","text":"","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"EditURL = \"../../test/basic.jl\"","category":"page"},{"location":"basic/#Basic","page":"Basic","title":"Basic","text":"","category":"section"},{"location":"basic/","page":"Basic","title":"Basic","text":"Here's an example of single-argument interface using animals, and the implementation of a duck.","category":"page"},{"location":"basic/#Definition","page":"Basic","title":"Definition","text":"","category":"section"},{"location":"basic/","page":"Basic","title":"Basic","text":"First we define the interface methods, and a list of mandatory and optional properties of the interface, with conditions, using the @interface macro.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"The @interface macro takes three arguments:","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"The name of the interface, which should usully end with \"Interface\"\nThe mandatory and optional components of the interface written as a NamedTuple, with functions or tuple of functions that test them.\nThe interface docstring (the interface is represented as a type)","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"module Animals\n\nusing Interfaces\n\nabstract type Animal end\n\nfunction age end\nfunction walk end\nfunction talk end\nfunction dig end\n\ncomponents = (\n mandatory = (\n age = (\n \"all animals have a `Real` age\" => x -> age(x) isa Real,\n \"all animals have an age larger than zero\" => x -> age(x) >= 0,\n ),\n ),\n optional = (\n walk = \"this animal can walk\" => x -> walk(x) isa String,\n talk = \"this animal can talk\" => x -> talk(x) isa Symbol,\n dig = \"this animal can dig\" => x -> dig(x) isa String,\n )\n)\n\ndescription = \"\"\"\nDefines a generic interface for animals to do the things they do best.\n\"\"\"\n\n@interface AnimalInterface Animal components description\n\nend;\nnothing #hide","category":"page"},{"location":"basic/#Implementation","page":"Basic","title":"Implementation","text":"","category":"section"},{"location":"basic/","page":"Basic","title":"Basic","text":"using Interfaces, Test","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"Now we implement the AnimalInterface, for a Duck.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"struct Duck <: Animals.Animal\n age::Int\nend\n\nAnimals.age(duck::Duck) = duck.age\nAnimals.walk(::Duck) = \"waddle\"\nAnimals.talk(::Duck) = :quack","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"We then test that the interface is correctly implemented","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"ducks = [Duck(1), Duck(2)]\nInterfaces.test(Animals.AnimalInterface, Duck, ducks)","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"As well as two optional methods","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"Interfaces.test(Animals.AnimalInterface{(:walk,:talk)}, Duck, ducks)","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"Finally we declare it, so that the information can be used in static dispatch.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"The @implements macro takes two arguments.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"The interface type, with a tuple of optional components in its first type parameter.\nThe type for which the interface is implemented.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"@implements Animals.AnimalInterface{(:walk,:talk)} Duck [Duck(1), Duck(2)]","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"Now let's see what happens when the interface is not correctly implemented.","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"struct Chicken <: Animals.Animal end","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"As expected, the tests fail","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"chickens = [Chicken()]\ntry\n Interfaces.test(Animals.AnimalInterface, Chicken, chickens)\ncatch e\n print(e)\nend\n\n\n\n @test Interfaces.test(Duck) == true # Test all implemented interfaces for Duck\n @test Interfaces.test(Animals.AnimalInterface) == true # Test all implemented types for AnimalInterface","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"","category":"page"},{"location":"basic/","page":"Basic","title":"Basic","text":"This page was generated using Literate.jl.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"EditURL = \"../../test/advanced.jl\"","category":"page"},{"location":"advanced/#Advanced","page":"Advanced","title":"Advanced","text":"","category":"section"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Here's an example of a multi-argument interface where we implement groups. For mathematicians, a group is just a set of objects where you can perform multiplication and inversion, such that an element multiplied by its inverse yields a neutral element.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"warning: Warning\nThis functionality is still experimental and might evolve in the future. If you have feedback about it, open an issue to help us improve it!","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"using Interfaces","category":"page"},{"location":"advanced/#Definition","page":"Advanced","title":"Definition","text":"","category":"section"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Unlike the AnimalInterface, this example involves functions with more than one argument. Such arguments need to be passed to the interface testing code, which means the interface definition must take them into account as well.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"For technical reasons, we provide a type called Arguments that you should use for this purpose. It behaves exactly like a NamedTuple but enables easier dispatch.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"module Group\n\nusing Interfaces\n\nfunction neutral end\nfunction multiplication end\nfunction inversion end\n\n@interface GroupInterface Number (\n mandatory = (;\n neutral_check = (\n \"neutral stable\" => a::Arguments -> neutral(typeof(a.x)) isa typeof(a.x),\n ),\n multiplication_check = (\n \"multiplication stable\" => a::Arguments -> multiplication(a.x, a.y) isa typeof(a.x),\n ),\n inversion_check = (\n \"inversion stable\" => a::Arguments -> inversion(a.x) isa typeof(a.x),\n \"inversion works\" => a::Arguments -> multiplication(a.x, inversion(a.x)) ≈ neutral(typeof(a.x)),\n ),\n ),\n optional = (;),\n) \"\"\"\nA group is a set of elements with a neutral element where you can perform multiplications and inversions.\n\nThe conditions checking the interface accept an `Arguments` object with two fields named `x` and `y`.\nThe type of the first field `x` must be the type you wish to declare as implementing `GroupInterface`.\n\"\"\"\n\nend;\nnothing #hide","category":"page"},{"location":"advanced/#Implementation","page":"Advanced","title":"Implementation","text":"","category":"section"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Let's try to see if our favorite number types do indeed behave like a group.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Group.neutral(::Type{N}) where {N<:Number} = one(N)\nGroup.multiplication(x::Number, y::Number) = x * y\nGroup.inversion(x::Number) = inv(x)","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"First, we check it for floating point numbers, giving a list of Arguments objects with the proper fields to the test function.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"float_pairs = [Arguments(x = 2.0, y = 1.0)]\nInterfaces.test(Group.GroupInterface, Float64, float_pairs)","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"We can thus declare proudly","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"@implements Group.GroupInterface Float64 [Arguments(x = 2.0, y = 1.0)]","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"Now we check it for integer numbers. The reason it fails is because for an integer x, the inverse 1/x is no longer an integer! Thus integer numbers are not a multiplicative group.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"int_pairs = [Arguments(x = 2, y = 1)]\nInterfaces.test(Group.GroupInterface, Int, int_pairs)","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"What happens if we give an input whose field types (Int) are not coherent with the type we are testing (Float64)?","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"try\n Interfaces.test(Group.GroupInterface, Float64, int_pairs)\ncatch e\n print(e.msg)\nend","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"In summary, there are two things to remember:","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"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.\nThe 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.","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"","category":"page"},{"location":"advanced/","page":"Advanced","title":"Advanced","text":"This page was generated using Literate.jl.","category":"page"},{"location":"","page":"Home","title":"Home","text":"EditURL = \"https://github.com/rafaqz/Interfaces.jl/blob/main/README.md\"","category":"page"},{"location":"#Interfaces","page":"Home","title":"Interfaces","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"(Image: Stable) (Image: Dev) (Image: Build Status) (Image: Coverage)","category":"page"},{"location":"","page":"Home","title":"Home","text":"Macros for defining the required behaviours of Julia interfaces, and stating that an object implements them.","category":"page"},{"location":"","page":"Home","title":"Home","text":"The goal is to get as much as possible out of defining an interface, specifically:","category":"page"},{"location":"","page":"Home","title":"Home","text":"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.\nTests: @implements declarations should be tested in package tests.\nDocs: interface documentation can be inserted into trait documentation.","category":"page"},{"location":"","page":"Home","title":"Home","text":"See the IterationInterface in BaseInterfaces.jl (a subpackage of this package) or the documentation for examples of @interface and @implements.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Note: the syntax here is likely to change as we work out the best ways to define interfaces","category":"page"},{"location":"","page":"Home","title":"Home","text":"If you think it should behave differently or there is better syntax, please make an issue.","category":"page"},{"location":"baseinterfaces/#BaseInterfaces-reference","page":"BaseInterfaces.jl reference","title":"BaseInterfaces reference","text":"","category":"section"},{"location":"baseinterfaces/#Docstrings","page":"BaseInterfaces.jl reference","title":"Docstrings","text":"","category":"section"},{"location":"baseinterfaces/","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.jl reference","text":"Modules = [BaseInterfaces]","category":"page"},{"location":"baseinterfaces/#BaseInterfaces.ArrayInterface","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.ArrayInterface","text":" ArrayInterface\n\nAn 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).\n\nBase Julia AbstractArray interface\n\n\n\n\n\n","category":"type"},{"location":"baseinterfaces/#BaseInterfaces.DictInterface","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.DictInterface","text":" DictInterface\n\nAn Interfaces.jl Interface with mandatory components (:iterate, :eltype, :keytype, :valtype, :keys, :values, :getindex) and optional components (:setindex!,).\n\nAbstractDict interface requires Arguments, with d = the_dict mandatory, and when setindex is needed, k = any_valid_key_not_in_d, v = any_valid_val\n\n\n\n\n\n","category":"type"},{"location":"baseinterfaces/#BaseInterfaces.IterationInterface","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.IterationInterface","text":" IterationInterface\n\nAn Interfaces.jl Interface with mandatory components (:iterate, :isiterable, :eltype, :size, :in) and optional components (:reverse, :indexing).\n\nAn interface for Base Julia iteration\n\n\n\n\n\n","category":"type"},{"location":"baseinterfaces/#BaseInterfaces.SetInterface","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.SetInterface","text":" SetInterface\n\nAn 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!).\n\nThe AbstractSet interface\n\n\n\n\n\n","category":"type"},{"location":"baseinterfaces/#Index","page":"BaseInterfaces.jl reference","title":"Index","text":"","category":"section"},{"location":"baseinterfaces/","page":"BaseInterfaces.jl reference","title":"BaseInterfaces.jl reference","text":"","category":"page"}] }