capos_bitstruct/

lib.rs

use std::collections::HashMap;

use proc_macro::TokenStream;
use proc_macro2::Span;
use quote::{format_ident, quote};
use syn::parse::{Parse, ParseStream};
use syn::spanned::Spanned;
use syn::{
  braced, parse_macro_input, Attribute, Error, Expr, Generics, Ident, LitInt, Result, Token, Type,
  Visibility,
};

#[proc_macro]
pub fn bitstruct(input: TokenStream) -> TokenStream {
  let input = parse_macro_input!(input as BitstructInput);
  match expand_bitstruct(input) {
    Ok(tokens) => tokens.into(),
    Err(err) => err.to_compile_error().into(),
  }
}

fn expand_bitstruct(input: BitstructInput) -> Result<proc_macro2::TokenStream> {
  let BitstructInput {
    attrs,
    vis,
    ident,
    generics,
    fields,
  } = input;

  validate_name_collisions(&fields)?;

  let mut storage_fields = Vec::new();
  let mut methods = Vec::new();
  let mut field_initializers = Vec::new();

  for field in fields {
    let StructField {
      attrs,
      vis,
      name: field_name,
      ty,
      bitfields,
    } = field;
    let field_ident = field_name
      .as_ident()
      .expect("field names were validated before code generation");

    storage_fields.push(quote! {
      #(#attrs)*
      #field_ident: #ty,
    });

    let field_getter_name = field_ident.clone();
    let field_setter_name = format_ident!("set_{}", field_ident);
    let field_stream_setter_name = format_ident!("with_{}", field_ident);
    methods.push(quote! {
      #vis fn #field_getter_name(&self) -> &#ty {
        &self.#field_ident
      }

      #vis fn #field_setter_name(&mut self, value: #ty) {
        self.#field_ident = value;
      }

      #vis fn #field_stream_setter_name(&mut self, value: #ty) -> &mut Self {
        self.#field_setter_name(value);
        self
      }
    });

    let Some(bitfield_blocks) = bitfields else {
      continue;
    };

    let total_bits = integer_bit_width(&ty).ok_or_else(|| {
      Error::new(
        ty.span(),
        "bitfield containers must be primitive integer types (u8..u128, i8..i128, usize, isize)",
      )
    })?;
    let work_ty = integer_work_ty(&ty).ok_or_else(|| {
      Error::new(
        ty.span(),
        "bitfield containers must be primitive integer types (u8..u128, i8..i128, usize, isize)",
      )
    })?;
    let mut field_init_stmts = Vec::new();
    field_init_stmts.push(quote! {
      self.#field_ident = 0 as #ty;
    });

    for (block_index, block) in bitfield_blocks.into_iter().enumerate() {
      let mut block_offset: u16 = 0;
      for bitfield in block.bitfields {
        let BitField {
          attrs,
          name: bit_name,
          ty: value_ty,
          width,
          default,
        } = bitfield;
        let bit_name_str = bit_name.as_string();

        if width == 0 {
          return Err(Error::new(
            bit_name.span(),
            format!("bitfield '{}' must have a non-zero width", bit_name_str),
          ));
        }

        let start = block_offset;
        let end = start + width as u16 - 1;
        if end >= total_bits as u16 {
          return Err(Error::new(
            bit_name.span(),
            format!(
              "bitfield '{}' with width {} at computed offset {} exceeds container width {}",
              bit_name_str, width, start, total_bits
            ),
          ));
        }
        block_offset += width as u16;

        let is_undefined = bit_name_str == "UNDEFINED";
        let is_underscore = bit_name_str == "_";

        if is_bool(&value_ty) && width != 1 {
          return Err(Error::new(
            value_ty.span(),
            format!("bool bitfield '{}' must be exactly one bit", bit_name_str),
          ));
        }

        let start_lit = syn::LitInt::new(&start.to_string(), Span::call_site());
        let width_lit = syn::LitInt::new(&width.to_string(), Span::call_site());

        let value_mask_expr = if width == 128 {
          quote! { !0 as #work_ty }
        } else {
          quote! { ((1 as #work_ty) << #width_lit) - (1 as #work_ty) }
        };

        if block_index == 0 {
          if let Some(default_expr) = default {
            if is_undefined || is_underscore {
              let default_bits_expr = if is_bool(&value_ty) {
                quote! { if (#default_expr) { 1 as #work_ty } else { 0 as #work_ty } }
              } else {
                quote! { (<#work_ty as ::core::convert::From<#value_ty>>::from(#default_expr)) & #value_mask_expr }
              };
              field_init_stmts.push(quote! {
                {
                  let value_mask = #value_mask_expr;
                  let field_mask = value_mask << #start_lit;
                  let value_bits = #default_bits_expr;
                  let current = self.#field_ident as #work_ty;
                  let updated = (current & !field_mask) | ((value_bits << #start_lit) & field_mask);
                  self.#field_ident = updated as #ty;
                }
              });
            } else {
              let bit_ident = bit_name
                .as_ident()
                .expect("non-special bitfields must parse as identifiers");
              let setter_name_for_init = format_ident!("set_{}", bit_ident);
              field_init_stmts.push(quote! {
                self.#setter_name_for_init(#default_expr);
              });
            }
          }
        }

        if is_undefined || is_underscore {
          continue;
        }

        let bit_ident = bit_name
          .as_ident()
          .expect("non-underscore bitfields must parse as identifiers");
        let getter_name = bit_ident.clone();
        let setter_name = format_ident!("set_{}", bit_ident);
        let stream_setter_name = format_ident!("with_{}", bit_ident);

        let getter_body = if is_bool(&value_ty) {
          quote! {
            let raw = (self.#field_ident as #work_ty >> #start_lit) & #value_mask_expr;
            raw != 0
          }
        } else {
          quote! {
            let raw = (self.#field_ident as #work_ty >> #start_lit) & #value_mask_expr;
            <#value_ty as ::core::convert::TryFrom<#work_ty>>::try_from(raw)
              .ok()
              .expect("bitfield getter conversion failed")
          }
        };

        let value_bits_expr = if is_bool(&value_ty) {
          quote! { if value { 1 as #work_ty } else { 0 as #work_ty } }
        } else {
          quote! { (<#work_ty as ::core::convert::From<#value_ty>>::from(value)) & #value_mask_expr }
        };

        methods.push(quote! {
          #(#attrs)*
          #vis fn #getter_name(&self) -> #value_ty {
            #getter_body
          }

          #(#attrs)*
          #vis fn #setter_name(&mut self, value: #value_ty) {
            let value_mask = #value_mask_expr;
            let field_mask = value_mask << #start_lit;
            let value_bits = #value_bits_expr;
            let current = self.#field_ident as #work_ty;
            let updated = (current & !field_mask) | ((value_bits << #start_lit) & field_mask);
            self.#field_ident = updated as #ty;
          }

          #(#attrs)*
          #vis fn #stream_setter_name(&mut self, value: #value_ty) -> &mut Self {
            self.#setter_name(value);
            self
          }
        });
      }
    }

    field_initializers.push(quote! {
      #(#field_init_stmts)*
    });
  }

  let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();

  Ok(quote! {
    #(#attrs)*
    #vis struct #ident #generics {
      #(#storage_fields)*
    }

    impl #impl_generics #ident #ty_generics #where_clause {
      pub fn init_bitstruct(&mut self) {
        #(#field_initializers)*
      }

      #(#methods)*
    }
  })
}

fn validate_name_collisions(fields: &[StructField]) -> Result<()> {
  let mut field_names: HashMap<String, Span> = HashMap::new();
  for field in fields {
    let name = field.name.as_string();
    if is_disallowed_struct_field_name(&name) {
      return Err(Error::new(
        field.name.span(),
        format!("struct field name '{}' is reserved and cannot be used", name),
      ));
    }
    if field_names.insert(name.clone(), field.name.span()).is_some() {
      return Err(Error::new(
        field.name.span(),
        format!("duplicate struct field name '{}'", name),
      ));
    }
  }

  let mut bitfield_names: HashMap<String, Span> = HashMap::new();
  for field in fields {
    let Some(bitfield_blocks) = &field.bitfields else {
      continue;
    };

    for block in bitfield_blocks {
      for bitfield in &block.bitfields {
        let bit_name = bitfield.name.as_string();
        if is_exempt_bitfield_collision_name(&bit_name) {
          continue;
        }
        if !is_snake_case_name(&bit_name) {
          return Err(Error::new(
            bitfield.name.span(),
            format!("bitfield name '{}' must be snake_case", bit_name),
          ));
        }

        if field_names.contains_key(&bit_name) {
          return Err(Error::new(
            bitfield.name.span(),
            format!(
              "bitfield name '{}' collides with a struct field name",
              bit_name
            ),
          ));
        }

        if bitfield_names
          .insert(bit_name.clone(), bitfield.name.span())
          .is_some()
        {
          return Err(Error::new(
            bitfield.name.span(),
            format!("duplicate bitfield name '{}'", bit_name),
          ));
        }
      }
    }
  }

  Ok(())
}

fn is_disallowed_struct_field_name(name: &str) -> bool {
  matches!(name, "_" | "RESEREVED" | "UNDEFINED")
}

fn is_exempt_bitfield_collision_name(name: &str) -> bool {
  matches!(name, "_" | "RESEREVED" | "UNDEFINED")
}

fn is_snake_case_name(name: &str) -> bool {
  !name.is_empty()
    && name
      .bytes()
      .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'_')
}

fn integer_bit_width(ty: &Type) -> Option<u8> {
  let Type::Path(path) = ty else {
    return None;
  };
  if path.qself.is_some() {
    return None;
  }

  let seg = path.path.segments.last()?;
  if !seg.arguments.is_empty() {
    return None;
  }

  match seg.ident.to_string().as_str() {
    "u8" | "i8" => Some(8),
    "u16" | "i16" => Some(16),
    "u32" | "i32" => Some(32),
    "u64" | "i64" => Some(64),
    "u128" | "i128" => Some(128),
    "usize" | "isize" => Some((usize::BITS) as u8),
    _ => None,
  }
}

fn integer_work_ty(ty: &Type) -> Option<proc_macro2::TokenStream> {
  let Type::Path(path) = ty else {
    return None;
  };
  if path.qself.is_some() {
    return None;
  }

  let seg = path.path.segments.last()?;
  if !seg.arguments.is_empty() {
    return None;
  }

  match seg.ident.to_string().as_str() {
    "u8" | "i8" => Some(quote! { u8 }),
    "u16" | "i16" => Some(quote! { u16 }),
    "u32" | "i32" => Some(quote! { u32 }),
    "u64" | "i64" => Some(quote! { u64 }),
    "u128" | "i128" => Some(quote! { u128 }),
    "usize" | "isize" => Some(quote! { usize }),
    _ => None,
  }
}

fn is_bool(ty: &Type) -> bool {
  let Type::Path(path) = ty else {
    return false;
  };
  path.qself.is_none() && path.path.is_ident("bool")
}

struct BitstructInput {
  attrs: Vec<Attribute>,
  vis: Visibility,
  ident: Ident,
  generics: Generics,
  fields: Vec<StructField>,
}

impl Parse for BitstructInput {
  fn parse(input: ParseStream<'_>) -> Result<Self> {
    let attrs = input.call(Attribute::parse_outer)?;
    let vis = input.parse::<Visibility>()?;
    input.parse::<Token![struct]>()?;
    let ident = input.parse::<Ident>()?;
    let generics = input.parse::<Generics>()?;

    let content;
    braced!(content in input);

    let mut fields = Vec::new();
    while !content.is_empty() {
      fields.push(content.parse::<StructField>()?);
    }

    Ok(Self {
      attrs,
      vis,
      ident,
      generics,
      fields,
    })
  }
}

struct StructField {
  attrs: Vec<Attribute>,
  vis: Visibility,
  name: StructFieldName,
  ty: Type,
  bitfields: Option<Vec<BitFieldBlock>>,
}

enum StructFieldName {
  Ident(Ident),
  Underscore(Token![_]),
}

impl StructFieldName {
  fn as_ident(&self) -> Option<&Ident> {
    match self {
      Self::Ident(ident) => Some(ident),
      Self::Underscore(_) => None,
    }
  }

  fn as_string(&self) -> String {
    match self {
      Self::Ident(ident) => ident.to_string(),
      Self::Underscore(_) => "_".to_string(),
    }
  }

  fn span(&self) -> Span {
    match self {
      Self::Ident(ident) => ident.span(),
      Self::Underscore(token) => token.span(),
    }
  }
}

impl Parse for StructField {
  fn parse(input: ParseStream<'_>) -> Result<Self> {
    let attrs = input.call(Attribute::parse_outer)?;
    let vis = input.parse::<Visibility>()?;
    let name = if input.peek(Token![_]) {
      StructFieldName::Underscore(input.parse::<Token![_]>()?)
    } else {
      StructFieldName::Ident(input.parse::<Ident>()?)
    };
    input.parse::<Token![:]>()?;
    let ty = input.parse::<Type>()?;
    if input.peek(Token![=]) {
      return Err(Error::new(
        input.span(),
        "struct field initializers are not supported; use bitfield-level initializers",
      ));
    }

    let mut bitfield_blocks = Vec::new();
    let mut has_bitfields = false;
    let mut consumed_field_terminator = false;

    while input.peek(syn::token::Brace) {
      has_bitfields = true;
      let content;
      braced!(content in input);

      let mut bitfields = Vec::new();
      while !content.is_empty() {
        bitfields.push(content.parse::<BitField>()?);
      }
      bitfield_blocks.push(BitFieldBlock { bitfields });

      if input.peek(Token![,]) {
        let ahead = input.fork();
        ahead.parse::<Token![,]>()?;
        if ahead.peek(syn::token::Brace) {
          input.parse::<Token![,]>()?;
          continue;
        } else {
          input.parse::<Token![,]>()?;
          consumed_field_terminator = true;
          break;
        }
      }
    }

    if !consumed_field_terminator {
      input.parse::<Token![,]>()?;
    }

    let bitfields = if has_bitfields {
      Some(bitfield_blocks)
    } else {
      None
    };

    Ok(Self {
      attrs,
      vis,
      name,
      ty,
      bitfields,
    })
  }
}

struct BitFieldBlock {
  bitfields: Vec<BitField>,
}

struct BitField {
  attrs: Vec<Attribute>,
  name: BitFieldName,
  ty: Type,
  width: u8,
  default: Option<Expr>,
}

enum BitFieldName {
  Ident(Ident),
  Underscore(Token![_]),
}

impl BitFieldName {
  fn as_ident(&self) -> Option<&Ident> {
    match self {
      Self::Ident(ident) => Some(ident),
      Self::Underscore(_) => None,
    }
  }

  fn as_string(&self) -> String {
    match self {
      Self::Ident(ident) => ident.to_string(),
      Self::Underscore(_) => "_".to_string(),
    }
  }

  fn span(&self) -> Span {
    match self {
      Self::Ident(ident) => ident.span(),
      Self::Underscore(token) => token.span(),
    }
  }
}

impl Parse for BitField {
  fn parse(input: ParseStream<'_>) -> Result<Self> {
    let attrs = input.call(Attribute::parse_outer)?;
    let name = if input.peek(Token![_]) {
      BitFieldName::Underscore(input.parse::<Token![_]>()?)
    } else {
      BitFieldName::Ident(input.parse::<Ident>()?)
    };
    input.parse::<Token![:]>()?;
    let ty = input.parse::<Type>()?;

    let width_lit = input.parse::<LitInt>()?;
    let width = parse_width_literal(&width_lit)?;

    let default = if input.peek(Token![=]) {
      input.parse::<Token![=]>()?;
      Some(input.parse::<Expr>()?)
    } else {
      None
    };

    input.parse::<Token![,]>()?;

    Ok(Self {
      attrs,
      name,
      ty,
      width,
      default,
    })
  }
}

fn parse_width_literal(lit: &LitInt) -> Result<u8> {
  let raw = lit.to_string();
  let digits: String = raw.chars().take_while(|c| c.is_ascii_hexdigit() || *c == '_' || *c == 'x' || *c == 'o' || *c == 'b').collect();

  let cleaned: String = digits.chars().filter(|c| *c != '_').collect();
  let (radix, body) = if let Some(rest) = cleaned.strip_prefix("0x") {
    (16, rest)
  } else if let Some(rest) = cleaned.strip_prefix("0o") {
    (8, rest)
  } else if let Some(rest) = cleaned.strip_prefix("0b") {
    (2, rest)
  } else {
    (10, cleaned.as_str())
  };

  if body.is_empty() {
    return Err(Error::new(lit.span(), "bitfield width must be an integer literal"));
  }

  let value = u16::from_str_radix(body, radix)
    .map_err(|_| Error::new(lit.span(), "bitfield width is out of supported range"))?;

  if value > u8::MAX as u16 {
    return Err(Error::new(
      lit.span(),
      "bitfield width is too large; maximum supported value is 255",
    ));
  }

  Ok(value as u8)
}

#[cfg(test)]
mod tests {
  use super::*;
  use quote::quote;
  use syn::parse2;

  #[test]
  fn expands_readme_example() {
    let input = quote! {
      struct MultWordA {
        cw: u32 {
          swizzled: bool 1,
          typ: uint8 5,
          restrictions: uint8 5,
          _: uint8 2 = 0,
        },
        ordinary_field: AnyTypeYouChoose,
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("README example should parse");
    let expanded = expand_bitstruct(parsed).expect("README example should expand");
    let rendered = expanded.to_string();

    // Original struct fields are preserved.
    assert!(rendered.contains("struct MultWordA"));
    assert!(rendered.contains("cw : u32"));
    assert!(rendered.contains("ordinary_field : AnyTypeYouChoose"));
    assert!(!rendered.contains("pub cw : u32"));
    assert!(!rendered.contains("pub ordinary_field : AnyTypeYouChoose"));

    // Defaults method is generated and includes writes for defaulted bitfields.
    assert!(rendered.contains("fn init_bitstruct (& mut self)"));
    assert!(rendered.contains("self . cw = 0 as u32"));

    // Non-special bitfields get getters/setters.
    assert!(rendered.contains("fn swizzled (& self) -> bool"));
    assert!(rendered.contains("fn set_swizzled (& mut self , value : bool)"));
    assert!(rendered.contains("fn with_swizzled (& mut self , value : bool) -> & mut Self"));
    assert!(rendered.contains("fn typ (& self) -> uint8"));
    assert!(rendered.contains("fn set_typ (& mut self , value : uint8)"));
    assert!(rendered.contains("fn with_typ (& mut self , value : uint8) -> & mut Self"));

    // Struct fields also get getters/setters/stream setters.
    assert!(rendered.contains("fn cw (& self) -> & u32"));
    assert!(rendered.contains("fn set_cw (& mut self , value : u32)"));
    assert!(rendered.contains("fn with_cw (& mut self , value : u32) -> & mut Self"));
    assert!(rendered.contains("fn ordinary_field (& self) -> & AnyTypeYouChoose"));
    assert!(rendered.contains("fn set_ordinary_field (& mut self , value : AnyTypeYouChoose)"));
    assert!(rendered.contains("fn with_ordinary_field (& mut self , value : AnyTypeYouChoose) -> & mut Self"));

    // UNDEFINED and pad entries do not generate accessors.
    assert!(!rendered.contains("fn _ "));
    assert!(!rendered.contains("fn set__"));
    assert!(!rendered.contains("fn UNDEFINED"));
    assert!(!rendered.contains("fn set_UNDEFINED"));
  }

  #[test]
  fn rejects_bitfield_field_name_collision() {
    let input = quote! {
      struct NameCollision {
        flags: u32 {
          ordinary_field: bool 1,
        },
        ordinary_field: u32,
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let err = expand_bitstruct(parsed).expect_err("name collision should fail expansion");
    assert!(
      err
        .to_string()
        .contains("bitfield name 'ordinary_field' collides with a struct field name")
    );
  }

  #[test]
  fn rejects_duplicate_bitfield_names() {
    let input = quote! {
      struct DuplicateBitfields {
        left: u32 {
          mode: uint8 2,
        },
        right: u32 {
          mode: uint8 2,
        },
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let err = expand_bitstruct(parsed).expect_err("duplicate bitfield names should fail");
    assert!(err.to_string().contains("duplicate bitfield name 'mode'"));
  }

  #[test]
  fn accepts_bool_default_initializers() {
    let input = quote! {
      struct BoolDefaults {
        control_word: u32 {
          enabled: bool 1 = true,
          ready: bool 1 = false,
        },
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let expanded = expand_bitstruct(parsed).expect("bool defaults should expand");
    let rendered = expanded.to_string();

    assert!(rendered.contains("fn init_bitstruct (& mut self)"));
    assert!(rendered.contains("self . control_word = 0 as u32"));
    assert!(rendered.contains("self . set_enabled (true)"));
    assert!(rendered.contains("self . set_ready (false)"));
    let zero_pos = rendered
      .find("self . control_word = 0 as u32")
      .expect("zero initialization should be generated");
    let enabled_pos = rendered
      .find("self . set_enabled (true)")
      .expect("enabled initializer should be generated");
    let ready_pos = rendered
      .find("self . set_ready (false)")
      .expect("ready initializer should be generated");
    assert!(zero_pos < enabled_pos);
    assert!(enabled_pos < ready_pos);
  }

  #[test]
  fn generates_zero_init_without_first_block_bitfield_defaults() {
    let input = quote! {
      struct NoFirstBlockDefaults {
        control_word: u32 {
          enabled: bool 1,
          ready: bool 1,
        }, {
          alternate: u8 2 = 0x1,
        },
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let expanded = expand_bitstruct(parsed).expect("expansion should succeed");
    let rendered = expanded.to_string();

    assert!(rendered.contains("fn init_bitstruct (& mut self)"));
    assert!(rendered.contains("self . control_word = 0 as u32"));
    assert!(!rendered.contains("self . set_enabled (true)"));
    assert!(!rendered.contains("self . set_ready (true)"));
    assert!(!rendered.contains("self . set_ready (false)"));
    assert!(!rendered.contains("self . set_alternate (0x1)"));
  }

  #[test]
  fn propagates_doc_comments() {
    let input = quote! {
      /// Struct docs
      struct DocExample {
        /// Field docs
        pub flags: u32 {
          /// Enabled bit docs
          enabled: bool 1,
        },
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let expanded = expand_bitstruct(parsed).expect("doc comments should expand");
    let rendered = expanded.to_string();

    // Struct and container field docs are preserved on the emitted struct.
    assert!(rendered.contains("doc = r\" Struct docs\""));
    assert!(rendered.contains("struct DocExample"));
    assert!(rendered.contains("doc = r\" Field docs\""));
    assert!(rendered.contains("flags : u32"));
    assert!(!rendered.contains("pub flags : u32"));

    // Bitfield docs are emitted on all generated methods.
    assert!(rendered.contains("doc = r\" Enabled bit docs\""));
    assert!(rendered.contains("pub fn enabled (& self) -> bool"));
    assert!(rendered.contains("pub fn set_enabled (& mut self , value : bool)"));
    assert!(rendered.contains("pub fn with_enabled (& mut self , value : bool) -> & mut Self"));
    assert!(rendered.contains("pub fn flags (& self) -> & u32"));
    assert!(rendered.contains("pub fn set_flags (& mut self , value : u32)"));
    assert!(rendered.contains("pub fn with_flags (& mut self , value : u32) -> & mut Self"));
  }

  #[test]
  fn accepts_underscore_bitfield_without_methods() {
    let input = quote! {
      struct UnderscoreBitfield {
        flags: u32 {
          _: bool 1 = true,
          visible: bool 1,
        },
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let expanded = expand_bitstruct(parsed).expect("underscore bitfield should expand");
    let rendered = expanded.to_string();

    // underscore entry contributes to field initialization
    assert!(rendered.contains("self . flags = 0 as u32"));
    assert!(rendered.contains("if (true) { 1 as u32 } else { 0 as u32 }"));

    // underscore entry does not get accessor methods
    assert!(!rendered.contains("fn _ "));
    assert!(!rendered.contains("fn set__"));
    assert!(!rendered.contains("fn with__"));

    // normal bitfields still get methods
    assert!(rendered.contains("fn visible (& self) -> bool"));
    assert!(rendered.contains("fn set_visible (& mut self , value : bool)"));
    assert!(rendered.contains("fn with_visible (& mut self , value : bool) -> & mut Self"));
  }

  #[test]
  fn rejects_reserved_struct_field_names() {
    for disallowed in ["_", "RESEREVED", "UNDEFINED"] {
      let source = format!(
        "struct BadFieldName {{
          {}: u32,
        }}",
        disallowed
      );
      let parsed = syn::parse_str::<BitstructInput>(&source).expect("input should parse");
      let err = expand_bitstruct(parsed).expect_err("reserved struct field name should fail");
      assert!(
        err
          .to_string()
          .contains(&format!("struct field name '{}' is reserved and cannot be used", disallowed))
      );
    }
  }

  #[test]
  fn exempts_undefined_and_pad_names_from_collision_checks() {
    let input = quote! {
      struct SpecialBitfieldNames {
        value: u32 {
          _: bool 1,
          UNDEFINED: bool 1,
          RESEREVED: bool 1,
        },
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let _ = expand_bitstruct(parsed).expect("UNDEFINED/pad names should not trigger collisions");
  }

  #[test]
  fn rejects_reserved_name_as_bitfield() {
    let input = quote! {
      struct ReservedNameRejected {
        value: u32 {
          RESERVED: u32 1 = 1,
        },
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let err = expand_bitstruct(parsed).expect_err("RESERVED should be rejected");
    assert!(
      err
        .to_string()
        .contains("bitfield name 'RESERVED' must be snake_case")
    );
  }

  #[test]
  fn rejects_struct_field_initializer_with_bitfields() {
    let err = syn::parse_str::<BitstructInput>(
      "struct FieldInitRejected {
        flags: u32 = 0 {
          enabled: bool 1 = true,
        },
      }",
    )
    .err()
    .expect("struct field initializer should be rejected");
    assert!(err.to_string().contains(
      "struct field initializers are not supported; use bitfield-level initializers"
    ));
  }

  #[test]
  fn accepts_multiple_bitfield_blocks_per_field() {
    let input = quote! {
      struct MultiBlock {
        flags: u32 {
          low: uint8 4 = 0x5,
        }, {
          high: uint8 4 = 0xA,
        },
        other: u32,
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let expanded = expand_bitstruct(parsed).expect("multiple bitfield blocks should expand");
    let rendered = expanded.to_string();

    assert!(rendered.contains("fn low (& self) -> uint8"));
    assert!(rendered.contains("fn high (& self) -> uint8"));
    assert!(rendered.contains("fn init_bitstruct (& mut self)"));
    assert!(rendered.contains("self . flags = 0 as u32"));
    assert!(rendered.contains("self . set_low (0x5)"));
    assert!(!rendered.contains("self . set_high (0xA)"));
  }

  #[test]
  fn rejects_non_snake_case_bitfield_name() {
    let input = quote! {
      struct BadBitfieldName {
        flags: u32 {
          notSnakeCase: u32 1,
        },
      }
    };

    let parsed = parse2::<BitstructInput>(input).expect("input should parse");
    let err = expand_bitstruct(parsed).expect_err("non-snake-case bitfield name should fail");
    assert!(
      err
        .to_string()
        .contains("bitfield name 'notSnakeCase' must be snake_case")
    );
  }

}