cyclone-attributes 0.1.0

The official Cyclone attributes: #[network] and #[codec] markers that cyclonec reads. No runtime, no encode, no codec generation.
Documentation
//! The official Cyclone **attributes**.
//!
//! ```text
//! cyclone-attributes  →  your source  →  cyclonec  →  generated code
//! ```
//!
//! This crate defines [`network`] and [`codec`], and does nothing with them. It
//! is the syntax half of Cyclone: the part that makes annotated Rust *compile*,
//! so that `cyclonec` has something to read.
//!
//! ```
//! use cyclone_attributes::*;
//!
//! #[network]
//! #[codec]
//! struct DeviceState {
//!     #[network(u32)]
//!     #[codec(edge, unity)]
//!     id: u32,
//!
//!     #[network(f32)]
//!     #[codec(edge)]
//!     temperature: f32,
//!
//!     #[network(string)]
//!     #[codec(unity)]
//!     display_name: String,
//! }
//! ```
//!
//! # What it does
//!
//! The attributes are **inert markers**. Applied to an item, they remove
//! themselves and every Cyclone attribute inside it, and hand back the item
//! otherwise untouched — same fields, same types, same derives, same doc
//! comments, same spans.
//!
//! That removal is the entire implementation, and it exists for one narrow
//! reason: Rust does not allow an attribute macro on a *field*, so
//! `#[network(u32)]` cannot compile on its own. An attribute on the struct is
//! what makes the ones on its fields legal, by consuming them.
//!
//! So the annotated struct above compiles to exactly:
//!
//! ```
//! struct DeviceState {
//!     id: u32,
//!     temperature: f32,
//!     display_name: String,
//! }
//! ```
//!
//! # What it does not do
//!
//! Everything else. There is no `Reader`, no `Writer`, no `Encode`, no
//! `Decode`, no registry, no reflection, no dynamic dispatch, and no generated
//! code of any kind. It reads no Cyclone type, validates no annotation, and
//! knows no codec name.
//!
//! `cyclonec` reads the annotations out of your **source**, not out of this
//! crate's expansion, and every semantic question belongs to it:
//!
//! - Whether `u32` names a Cyclone type.
//! - Whether a field declared `u64` may carry `#[network(u32)]`.
//! - What `edge` or `unity` mean, and which fields each one covers.
//!
//! On the last of those especially: a codec name is an identifier **you**
//! invent. This crate has no list of them, no default, and no opinion — `edge`,
//! `unity`, `server`, `orange_pi` are all the same to it, which is to say
//! nothing at all.
//!
//! # Scope
//!
//! This crate is not a serialization runtime and not a networking library. It is
//! two attributes and the code that takes them back off.

#![forbid(unsafe_code)]

use proc_macro::{Delimiter, Group, TokenStream, TokenTree};

/// Marks a struct as a Cyclone network model, and declares the Cyclone wire
/// type of a field.
///
/// # On a model
///
/// ```
/// # use cyclone_attributes::network;
/// #[network]
/// struct DeviceState {
///     #[network(u32)]
///     id: u32,
/// }
/// ```
///
/// # On a field
///
/// `#[network(TYPE)]` declares the field's Cyclone wire type. The declared type
/// is the schema: `cyclonec` believes the attribute and never infers a Cyclone
/// type from the Rust one, so this
///
/// ```
/// # use cyclone_attributes::network;
/// #[network]
/// struct Reading {
///     #[network(u32)]
///     value: u64,
/// }
/// ```
///
/// declares a `u32` on the wire, whatever the Rust field says. Whether the two
/// are compatible is a question for `cyclonec`'s validation, later, and not for
/// this crate at any point.
///
/// A field attribute is never expanded on its own — Rust does not permit that.
/// It is consumed by the attribute on the enclosing model, which is why a model
/// carrying annotated fields must itself be marked.
///
/// # Expansion
///
/// The item, with every Cyclone attribute removed and nothing else changed.
#[proc_macro_attribute]
pub fn network(_arguments: TokenStream, item: TokenStream) -> TokenStream {
    strip(item)
}

/// Marks a struct as taking part in codec generation, and declares which codec
/// profiles a field belongs to.
///
/// # On a model
///
/// ```
/// # use cyclone_attributes::codec;
/// #[codec]
/// struct DeviceState {
///     #[codec(edge)]
///     id: u32,
/// }
/// ```
///
/// # On a field
///
/// `#[codec(...)]` lists the profiles the field belongs to, in the order they
/// were written. A field may belong to one, or to many, and there is no limit:
///
/// ```
/// # use cyclone_attributes::codec;
/// #[codec]
/// struct DeviceState {
///     #[codec(edge, unity, admin)]
///     id: u32,
///
///     #[codec(edge)]
///     temperature: f32,
/// }
/// ```
///
/// A profile name is an identifier **you** invent. This crate holds no list of
/// them and gives none of them meaning: `edge`, `unity`, `server`, `client`,
/// `orange_pi` are identifiers and nothing more. Grouping fields by profile is
/// `cyclonec`'s job, done by reading your source.
///
/// # Expansion
///
/// The item, with every Cyclone attribute removed and nothing else changed.
#[proc_macro_attribute]
pub fn codec(_arguments: TokenStream, item: TokenStream) -> TokenStream {
    strip(item)
}

/// Removes every Cyclone attribute from a token stream, at any depth.
///
/// Both attributes do exactly this, which makes the pair order-independent and
/// idempotent: `#[network] #[codec]` and `#[codec] #[network]` produce the same
/// item, and so does either one alone. Whichever macro the compiler expands
/// first takes all of them off; the other, if it survives to run, finds nothing
/// left to do.
///
/// Everything that is not a Cyclone attribute is passed through untouched —
/// derives, `cfg`, doc comments, other macros' attributes — and every token
/// keeps its span, so an error in an annotated struct still points at the line
/// the user wrote.
fn strip(tokens: TokenStream) -> TokenStream {
    let mut out: Vec<TokenTree> = Vec::new();
    let mut tokens = tokens.into_iter().peekable();

    while let Some(token) = tokens.next() {
        // An outer attribute is `#` followed by a bracketed group. An inner one,
        // `#![...]`, has a `!` between them and is never a Cyclone attribute, so
        // the `#` falls through and the group is walked like any other.
        let is_cyclone_attribute = matches!(&token, TokenTree::Punct(punct) if punct.as_char() == '#')
            && matches!(
                tokens.peek(),
                Some(TokenTree::Group(group))
                    if group.delimiter() == Delimiter::Bracket && names_cyclone(group)
            );

        if is_cyclone_attribute {
            tokens.next();
            continue;
        }

        match token {
            // A struct's fields live inside its braces, so the walk has to go in.
            TokenTree::Group(group) => {
                let mut rebuilt = Group::new(group.delimiter(), strip(group.stream()));
                rebuilt.set_span(group.span());
                out.push(TokenTree::Group(rebuilt));
            }
            other => out.push(other),
        }
    }

    out.into_iter().collect()
}

/// Whether an attribute's contents name `network` or `codec`.
///
/// Only the path is read, and only its last segment, so `#[network(u32)]` and
/// `#[cyclone_attributes::network(u32)]` are both recognised. Anything else —
/// `#[derive(Debug)]`, `#[doc = "…"]`, `#[serde(rename = "network")]` — stops at
/// the first token that cannot be part of a path and is left alone.
fn names_cyclone(attribute: &Group) -> bool {
    let mut last_segment = None;

    for token in attribute.stream() {
        match token {
            TokenTree::Ident(ident) => last_segment = Some(ident.to_string()),
            TokenTree::Punct(punct) if punct.as_char() == ':' => {}
            _ => break,
        }
    }

    matches!(last_segment.as_deref(), Some("network") | Some("codec"))
}