Müsli Documentation

The musli-zerocopy-macros crate provides the procedural macros required to implement zero-copy serialization and deserialization within the Müsli ecosystem.

To use these macros, you should primarily interact with the musli-zerocopy crate, which utilizes these macros to provide a high-performance, zero-copy interface. For detailed API documentation and usage patterns, refer to the official musli documentation on docs.rs.

The musli-web modules are organized by the version of the target crate they support. When importing, ensure you select the module matching your project's dependency versions:

• Use axum08 for Axum 0.8.x.
• Use yew022 for Yew 0.22.x.
• Use yew023 for Yew 0.23.x.
• Use web03 for web-sys 0.3.x.

You can use #[musli(skip)] to prevent a field from being encoded or decoded. When decoding a skipped field, Müsli will use Default::default() to construct the value unless a custom default is provided.

To provide a custom default, use #[musli(default = <path>)] where <path> is a function that returns the field's type. You can combine these with skip to ensure a field is always populated with a specific value during decoding even if it's missing from the input.

use musli::{Encode, Decode};

#[derive(Encode, Decode)]
struct Person {
    name: String,
    #[musli(skip)]
    age: Option<u32>, // Uses Default::default()
    #[musli(skip, default = default_country)]
    country: Option<String>, // Uses default_country()
}

fn default_country() -> Option<String> {
    Some(String::from("Earth"))
}

The #[musli(untagged)] attribute encodes enum variants without any identifying tag.

Decoding Behavior:

• Variants are attempted in the order they are declared.
• The first variant that successfully decodes is selected.

Requirements & Limitations:

• The decoder must implement Decoder::try_clone (or Decoder::decode_buffer if try_clone is unavailable).
• Warning: Standard decoders do not support Decoder::try_clone when decoding &mut &[u8] because exclusive references cannot be cloned. This may affect decoding performance or compatibility in certain buffer-based scenarios.

use musli::{Encode, Decode};

#[derive(Debug, PartialEq, Encode, Decode)]
#[musli(untagged)]
pub enum Untagged {
    Person {
        name: String,
        age: u32,
    },
    #[musli(transparent)]
    Numbers(Numbers),
}

Use meta attributes to limit the scope of other attributes to either the encoding or decoding phase. This is useful when a specific configuration is valid for one direction but not the other (e.g., certain packed formats that are supported for encoding but not for decoding enums).

• #[musli(encode_only)]: Attributes only apply when implementing Encode.
• #[musli(decode_only)]: Attributes only apply when implementing Decode.

use musli::mode::Binary;
use musli::{Decode, Encode};

enum Packed {}

#[derive(Encode, Decode)]
#[musli(mode = Packed, encode_only, untagged)]
enum Name<'a> {
    Full(&'a str),
    Given(&'a str),
}

Müsli provides a system of attributes to customize how Encode and Decode are implemented. Attributes are categorized by their scope:

• Meta attributes: Apply to the attribute itself to filter scope (e.g., encode_only or specifying a mode). These can be used on containers, variants, and fields.
• Container attributes: Apply to the entire struct or enum.
• Variant attributes: Apply to individual variants within an enum.
• Field attributes: Apply to individual fields within a struct or an enum variant.

The musli-macros crate contains the underlying macro implementations for Müsli, but its API is unstable and is not intended for direct use by end-users.

To use Müsli macros in your project, you should instead use the public APIs provided by the musli or musli_core crates. These crates re-export the necessary macros and provide a stable interface for your application.

/* Do NOT use musli-macros directly. 
   Use musli or musli_core instead. */

// Example of what you should do:
use musli::Serialize;
use musli_core::Deserialize;

You can define different behaviors for different serialization formats (modes) by using meta attributes. Sibling attributes will only apply when the specified mode is active.

Supported shorthand modes:

• #[musli(Binary)]
• #[musli(Text)]

For custom modes, use: #[musli(mode = <path>)].

This allows a single data structure to have multiple distinct Encode/Decode implementations (e.g., one for binary and one for text) defined in parallel.

use musli::{Encode, Decode};

#[derive(Encode, Decode)]
#[musli(Text, name(type = usize))]
struct Person<'a> {
    name: &'a str,
    age: u32,
}