Skip to content

Commit

Permalink
build based on d235e27
Browse files Browse the repository at this point in the history
  • Loading branch information
Documenter.jl committed Nov 2, 2023
1 parent df8a54c commit 613d0fe
Show file tree
Hide file tree
Showing 14 changed files with 1,165 additions and 0 deletions.
1 change: 1 addition & 0 deletions previews/PR37/.documenter-siteinfo.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-02T16:00:47","documenter_version":"1.1.2"}}
39 changes: 39 additions & 0 deletions previews/PR37/advanced/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Advanced · Interfaces.jl</title><meta name="title" content="Advanced · Interfaces.jl"/><meta property="og:title" content="Advanced · Interfaces.jl"/><meta property="twitter:title" content="Advanced · Interfaces.jl"/><meta name="description" content="Documentation for Interfaces.jl."/><meta property="og:description" content="Documentation for Interfaces.jl."/><meta property="twitter:description" content="Documentation for Interfaces.jl."/><meta property="og:url" content="https://rafaqz.github.io/Interfaces.jl/advanced/"/><meta property="twitter:url" content="https://rafaqz.github.io/Interfaces.jl/advanced/"/><link rel="canonical" href="https://rafaqz.github.io/Interfaces.jl/advanced/"/><script data-outdated-warner src="../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../search_index.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../">Interfaces.jl</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="../">Home</a></li><li><span class="tocitem">Examples</span><ul><li><a class="tocitem" href="../basic/">Basic</a></li><li class="is-active"><a class="tocitem" href>Advanced</a><ul class="internal"><li><a class="tocitem" href="#Definition"><span>Definition</span></a></li><li><a class="tocitem" href="#Implementation"><span>Implementation</span></a></li></ul></li></ul></li><li><a class="tocitem" href="../api/">API reference</a></li><li><a class="tocitem" href="../baseinterfaces/">BaseInterfaces.jl reference</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Examples</a></li><li class="is-active"><a href>Advanced</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Advanced</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/rafaqz/Interfaces.jl" title="View the repository on GitHub"><span class="docs-icon fa-brands"></span><span class="docs-label is-hidden-touch">GitHub</span></a><a class="docs-navbar-link" href="https://github.com/rafaqz/Interfaces.jl/blob/main/test/advanced.jl" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="Advanced"><a class="docs-heading-anchor" href="#Advanced">Advanced</a><a id="Advanced-1"></a><a class="docs-heading-anchor-permalink" href="#Advanced" title="Permalink"></a></h1><p>Here&#39;s an example of multi-argument interface using groups. For mathematicians, a group is just a set of objects where you can perform <code>multiplication</code> and <code>inversion</code>, such that an element multiplies by its inverse yields a <code>neutral</code> element.</p><div class="admonition is-warning"><header class="admonition-header">Warning</header><div class="admonition-body"><p>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!</p></div></div><pre><code class="language-julia hljs">using Interfaces</code></pre><h2 id="Definition"><a class="docs-heading-anchor" href="#Definition">Definition</a><a id="Definition-1"></a><a class="docs-heading-anchor-permalink" href="#Definition" title="Permalink"></a></h2><p>Unlike the <code>AnimalInterface</code>, 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.</p><p>For technical reasons, we provide a type called <code>Arguments</code> that you should use for this purpose. It behaves exactly like a <code>NamedTuple</code> but enables easier dispatch.</p><pre><code class="language-julia hljs">module Group

using Interfaces

function neutral end
function multiplication end
function inversion end

@interface GroupInterface Number (
mandatory = (;
neutral_check = (
&quot;neutral stable&quot; =&gt; a::Arguments -&gt; neutral(typeof(a.x)) isa typeof(a.x),
),
multiplication_check = (
&quot;multiplication stable&quot; =&gt; a::Arguments -&gt; multiplication(a.x, a.y) isa typeof(a.x),
),
inversion_check = (
&quot;inversion stable&quot; =&gt; a::Arguments -&gt; inversion(a.x) isa typeof(a.x),
&quot;inversion works&quot; =&gt; a::Arguments -&gt; multiplication(a.x, inversion(a.x)) ≈ neutral(typeof(a.x)),
),
),
optional = (;),
) &quot;&quot;&quot;
A group is a set of elements with a neutral element where you can perform multiplications and inversions.

The conditions checking the interface accept an `Arguments` object with two fields named `x` and `y`.
The type of the first field `x` must be the type you wish to declare as implementing `GroupInterface`.
&quot;&quot;&quot;

end;</code></pre><h2 id="Implementation"><a class="docs-heading-anchor" href="#Implementation">Implementation</a><a id="Implementation-1"></a><a class="docs-heading-anchor-permalink" href="#Implementation" title="Permalink"></a></h2><p>Let&#39;s try to see if our favorite number types do indeed behave like a group.</p><pre><code class="language-julia hljs">Group.neutral(::Type{N}) where {N&lt;:Number} = one(N)
Group.multiplication(x::Number, y::Number) = x * y
Group.inversion(x::Number) = inv(x)</code></pre><p>First, we check it for floating point numbers, giving a list of <code>Arguments</code> objects with the proper fields to the <code>test</code> function.</p><pre><code class="language-julia hljs">float_pairs = [Arguments(x = 2.0, y = 1.0)]
Interfaces.test(Group.GroupInterface, Float64, float_pairs)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">true</code></pre><p>We can thus declare proudly</p><pre><code class="language-julia hljs">@implements Group.GroupInterface Float64 [Arguments(x = 2.0, y = 1.0)]</code></pre><p>Now we check it for integer numbers. The reason it fails is because for an integer <code>x</code>, the inverse <code>1/x</code> is no longer an integer! Thus integer numbers are not a multiplicative group.</p><pre><code class="language-julia hljs">int_pairs = [Arguments(x = 2, y = 1)]
Interfaces.test(Group.GroupInterface, Int, int_pairs)</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">false</code></pre><p>What happens if we give an input whose field types (<code>Int</code>) are not coherent with the type we are testing (<code>Float64</code>)?</p><pre><code class="language-julia hljs">try
Interfaces.test(Group.GroupInterface, Float64, int_pairs)
catch e
print(e.msg)
end</code></pre><pre class="documenter-example-output"><code class="nohighlight hljs ansi">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.</code></pre><p>In summary, there are two things to remember:</p><ol><li>The anonymous functions in the interface conditions of <code>Interfaces.@interface</code> should accept a single object of type <code>Arguments</code> and then work with its named fields. These fields should be listed in the docstring.</li><li>The list of objects passed to <code>Interface.test</code> must all be of type <code>Arguments</code>, with the right named fields. At least one field must have the type you are testing.</li></ol><hr/><p><em>This page was generated using <a href="https://github.com/fredrikekre/Literate.jl">Literate.jl</a>.</em></p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../basic/">« Basic</a><a class="docs-footer-nextpage" href="../api/">API reference »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="auto">Automatic (OS)</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.1.2 on <span class="colophon-date" title="Thursday 2 November 2023 16:00">Thursday 2 November 2023</span>. Using Julia version 1.9.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
Loading

0 comments on commit 613d0fe

Please sign in to comment.