seal_the_deal/
_lib.rs

1//! [sealed]: `sealed`
2//! [with_seals]: `with_seals`
3#![doc = include_str!("../README.md")]
4#![no_std]
5#![forbid(unsafe_code)]
6#![doc(html_logo_url = "https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21")]
7#![cfg_attr(feature = "docs-rs", feature(doc_cfg))]
8
9/// Attribute required on the enscoping `trait` definition to enable usage of the
10/// <code>[#\[sealed\]][`sealed`]</code> attribute on its associated functions (with default impls).
11///
12/// See [the top-level docs][`crate`] for more info and examples.
13///
14/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
15/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
16/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
17/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
18/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
19/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
20/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
21/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
22/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
23/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
24/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
25/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
26/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
27/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
28/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
29/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
30/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
31/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
32/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
33/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
34/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
35/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
36/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
37/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
38/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
39/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
40/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
41/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
42/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
43/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
44/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
45/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
46/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
47/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
48/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
49/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
50/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
51/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
52/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
53/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
54/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
55/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
56/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
57/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
58/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
59/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
60/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
61/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
62/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
63/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
64/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
65/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
66/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
67/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
68/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
69/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
70/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
71/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
72/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
73/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
74/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
75/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
76/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
77/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
78/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
79/// <img height="150px" src="https://gist.github.com/user-attachments/assets/83e97064-6213-4287-9975-57ed98117a21"/>
80///
81pub use ::seal_the_deal_proc_macros::with_seals;
82
83/// Attribute to use on the `trait` methods (or associated functions) that you wish to "seal", a.k.a.,
84/// render them `final`.
85///
86/// # Usage
87///
88/// This is actually a phony attribute: **the <code>[#\[with_seals\]][with_seals]</code> attribute
89/// is required on the enscoping `trait`**.
90///
91/// Indeed, <code>[#\[with_seals\]][`with_seals`]</code> is the actual attribute doing the work:
92/// `#[sealed]` are just syntactical annotations / markers for it. Which is why the `#[sealed]`
93/// attribute does not need to be imported in practice.
94///
95/// # Attribute args
96///
97/// `#[sealed]` currently accepts _two_, optional, attribute args:
98///
99/// ## `#[sealed(airtight)]`
100///
101/// Switches the implementation used by `#[sealed]` from involving a generic lifetime parameter
102/// to involving more convoluted type-genericity tricks.
103///
104/// The author is positive this alternative method shall never allow users to override the method,
105/// no matter how smart the compiler might get, since doing so would require `fn` signatures to
106/// be capable of trait-resolution-fallback type inference.
107///
108/// The reason this alternative implementation is only opt-in, is because of a couple:
109///
110/// ### Caveats
111///
112///   - Since the method now uses a(n extra) generic type parameter, a previously `dyn`-compatible
113///     method would cease to be so.
114///
115///     Add `where Self : Sized` if you do not want the rest of the trait from becoming
116///     `dyn`-incompatible
117///
118///   - Uglier generated code.
119///
120///     Indeed, the return of the function [ends up wrapped in an ugly trait associated type][1].
121///
122///     While most code and users ought to remain blissfully oblivious to this fact, IDEs might
123///     reveal the ugly truth to users; moreover, the docs would be quite horrendous as well,
124///     which is why `#[sealed]` then defaults to hiding its shenanigans from the rendered docs, and
125///     [masquerading as non-`#[sealed] fn`][3] (but for the extra docstring appended to the method,
126///     of course!).
127///
128/// ## `#[sealed(doc(disguised = true/false))]`
129///
130/// Whether the attribute shall be using certain `cfg(doc)` shenanigans to disable itself when
131/// Rust documentation is being rendered, so as to hide the actual clutter/noise from said
132/// sheanigans.
133///
134///   - ### Default behavior
135///
136///       - For `#[sealed]`, it defaults to `false`: said sheanigans are deemed non-noisy enough
137///         not to warrant having to lie in docs;
138///
139///       - But for `#[sealed(airtight)]`, it defaults to `true`, since the return type of the
140///         method otherwise [ends up wrapped in an ugly trait associated type][1].
141///
142/// Note that no matter the choice of `doc(disguised)`, `#[sealed]` shall always unconditionally
143/// append a docstring to the method / associated function [telling users not to override it][2].
144///
145/// [1]: examples::AirtightDocDisguisedFalse::method()
146///
147/// [2]: examples::Basic::method()
148///
149/// [3]: examples::Airtight::method()
150///
151/// ---
152///
153/// See [the top-level docs][`crate`] for more info and examples.
154pub use ::seal_the_deal_proc_macros::sealed;
155
156#[doc = include_str!("compile_fail_tests.md")]
157mod _compile_fail_tests {}
158
159
160#[cfg_attr(feature = "docs-rs",
161    doc(cfg(doc_examples))
162)]
163#[cfg(doc_examples)]
164pub mod examples;