liter_derive/

lib.rs

mod database;
mod sql;
mod table;
mod tuple;
mod value;

use proc_macro::TokenStream;

#[proc_macro_attribute]
pub fn database(attr: TokenStream, item: TokenStream) -> TokenStream {
	database::run(attr, item)
}

#[proc_macro_derive(Table, attributes(key, check, unique))]
pub fn derive_table(annotated_item: TokenStream) -> TokenStream {
	table::derive(annotated_item)
}

#[proc_macro_derive(Value)]
pub fn derive_value(annotated_item: TokenStream) -> TokenStream {
	value::derive(annotated_item)
}

/// Generate trait implementations for heterogeneous tuples
///
/// # Syntax
///
/// The attribute expects a range literal as an argument, and it can only be applied to a trait `impl` block.
/// The "range literal" must include start and end bounds, and they have to be integer literals.
/// Both `..` and `..=` forms are supported.
///
/// The trait `impl` block is a regular `impl` block that will be copied for each generated tuple implementation, with two important changes.
/// Firstly, the required generic type parameters will be declared for each generated `impl` block (starting from `A`, `B`, `C`, then onto `Aa`, `Ab`, `Ac` and so on).
/// Secondly, each `impl` block has access to the (pseudo-)macros `each!`, `Each!` and `Every!`.
///
/// For instance:
/// ```
/// use liter_derive::impl_tuple;
///
/// trait Thing {}
/// trait TupleOfThings {}
///
/// #[impl_tuple(2..=4)]
/// impl TupleOfThings for Each!(T) where Every!(T => T: Thing): '_ {}
/// ```
///
///
/// Generates:
/// ```
/// # trait Thing {}
/// # trait TupleOfThings {}
/// impl<A, B> TupleOfThings for (A, B)
/// where
///     A: Thing,
///     B: Thing,
/// {}
/// impl<A, B, C> TupleOfThings for (A, B, C)
/// where
///     A: Thing,
///     B: Thing,
///     C: Thing,
/// {}
/// impl<A, B, C, D> TupleOfThings for (A, B, C, D)
/// where
///     A: Thing,
///     B: Thing,
///     C: Thing,
///     D: Thing,
/// {}
/// ```
///
///
/// Inside the `impl` block, any provided item will be copied into the generated blocks, and special accommodation (in the form of macros) is made for `fn`, `const`, and `type` items.
/// Note that this excludes macro invocations in item position, which are copied over unchanged.
///
/// # Macros
///
/// The following example implements a trait to turn a reference to a tuple into a tuple of references, i.e. from `&(A, B, C)` to `(&A, &B, &C)`.
/// Though rather abstract, this can be useful for traits.
/// In any case, the example shows all three available (pseudo-)macros.
///
/// ```
/// use liter_derive::impl_tuple;
///
/// pub trait Tuple<'l> {
///     type Ref: 'l;
///     type Mut: 'l;
///     fn take_ref(&'l self) -> Self::Ref;
/// }
///
/// #[impl_tuple(2..=16)]
/// impl<'l> Tuple<'l> for Each!(T) where Every!(T => T: 'l): '_ {
///     type Ref = Each!(T => &'l T);
///     type Mut = Each!(T => &'l mut T);
///
///     /// `&(A, B, C)` → `(&A, &B, &C)`
///     fn take_ref(&'l self) -> Self::Ref {
///         each!{ref field => field}
///     }
/// }
/// ```
///
/// Only `each!` (lower-case) is a genuine "macro-by-example" macro as evaluated by the compiler proper.
/// The other two, which I term "pseudo-macros", count as macros syntactically, and they are used like macros, but they are "expanded" by `#[impl_tuple]` rather than the regular macro process.
/// As a consequence (among other things), they will not be suggested or understood by IDEs.
/// It's also not possible to nest them, or use them in the arguments to any other macro invocation.
///
/// ## `Each!` in Types & Expressions
///
/// `Each!` (a pseudo-macro) is made available in two distinct places: primarily, in "type positions", where it "expands" to a tuple type, and secondarily in expressions, where it allows accessing trait constants, for instance.
///
/// The simplest form is seen in the "self type" in the example: `impl<'l> Tuple<'l> for Each!(T)`.
/// `Each!(T)` is a shorthand for `Each!(T => T)`, which is the form used in the `type` item as `type Ref = Each!(T => &'l T);`.
/// That invocation, inside the `impl` block for the tuple `(A, B)`, would expand to `(&'l A, &'l B)`.
/// A tuple where, for each of the tuple's types, it replaces every `T` (or whatever identifier comes before the `=>`) with the corresponding type parameter.
/// Naturally, `Each!(T)` expands to just `(A, B)`.
///
/// `Each!` is also available in expressions (i.e. the "actual code" in `fn` item bodies, but also the expressions that define a `const` item).
/// There, it works almost exactly the same as in type positions (the shorthand without `=>` isn't available), at least textually.
/// The `T` (or whatever) is replaced in a [`syn::Expr`] instead of a type, yielding a tuple expression, instead of a tuple type.
/// This allows accessing items (e.g. `const`s) associated with the types.
///
/// ## `Every!` in Type Bounds
///
/// The pseudo-macro `Every!`, "expands" into a set of type bounds.
/// Unfortunately, even though this "expands" to both sides of the `:` in the [`syn::PredicateType`], syntactically it only "counts" as the left side.
/// Because of this, the invocation needs to be be followed by `: '_` (or something similar), like so: `Every!(T => T: Clone): '_`.
/// The `'_` or whatever else you choose to put there is discarded by the macro, so it only needs to be valid syntactically.
///
/// ## `each!` in `fn` Items
///
/// Inside `fn` items, the macro `each!` is made available.
/// It allows operating on *each* of the tuples fields individually, returning the results as a tuple.
/// ```
/// macro_rules! each {
///     ($b:expr) => { ... };
///     ($i:pat => $b:expr) => { ... };
///     (@$slf:expr, $i:pat => $b:expr) => { ... }
/// }
/// ```
///
/// This macro may take 3 forms.  
/// In the first form, `$b` is simply repeated as many times as the tuple has fields, such that it results in a tuple of the same length (i.e `($b, $b, $b, …, $b)`).  
/// The second form does this too, but gives `$b` access to a different field of the tuple each time (in order, obviously).
/// The field can be accessed under the identifier given to `$i`.
/// It expands to `({let $i = self.0; $b}, {let $i = self.1; $b}, …)`.
/// Note that `$i` is a pattern `pat` and not just an identifier `ident`, which allows not only destructuring assignments (convenient but could be done in the block `$b` too), but also because it may be necessary to specify the identifier you want to use as `ref thing` when you want to work on the tuple fields by reference.  
/// The third and final form is exactly like the second, except that it can give access to the fields of a tuple that isn't necessarily `self`, as long as it has the same number of fields (or more, theoretically).
/// It expands to `({let $i = $slf.0; $b}, {let $i = $slf.1; $b}, …)`.
///
/// The `macro_rules!` definition for `each!`, which is different for every generated `impl` block, is injected as the first statement into the body of every `fn` item and also every `const` item that's defined by a block expression (`{…; …; …}`).
#[proc_macro_attribute]
pub fn impl_tuple(attr: TokenStream, item: TokenStream) -> TokenStream {
	tuple::run(attr, item)
}