Skip to main content

Attributes

Attributes provide metadata for items, modules, and crates. Oxide uses @[...] syntax instead of Rust's #[...].

Outer Attributes​

Apply to the next item:

@[derive(Debug, Clone)]
struct Point(x: Int, y: Int)

@[inline]
fn fastFunction(): Int { 42 }

@[derive(Debug, PartialEq)]
enum Status {
    case active
    case inactive
}

Transpiles to:

#[derive(Debug, Clone)]
struct Point { x: isize, y: isize }

#[inline]
fn fast_function() -> isize { 42 }

#[derive(Debug, PartialEq)]
enum Status {
    active,
    inactive,
}

Inner Attributes​

Apply to the enclosing scope. Use explicit scope prefixes:

SyntaxScopeRust Equivalent
@file:[...]Current file only#![...] in module
@crate:[...]Entire crate#![...] in lib.rs/main.rs

File Attributes​

@file:[allow(unused_variables)]
@file:[warn(missing_docs)]

fn main() {
    let unused = 42  // No warning due to @file allow
}

Crate Attributes​

Place in main.ox or lib.ox:

@crate:[allow(dead_code)]
@crate:[feature(async_closure)]
@crate:[warn(rust_2021_compatibility)]

fn main() {
    // ...
}

Common Attributes​

Derive Attributes​

Auto-implement traits:

@[derive(Debug)]              // Debug printing
@[derive(Clone)]              // Cloning
@[derive(Copy, Clone)]        // Copy semantics
@[derive(PartialEq, Eq)]      // Equality comparison
@[derive(PartialOrd, Ord)]    // Ordering
@[derive(Hash)]               // Hashing
@[derive(Default)]            // Default values
struct Data(value: Int)

// Multiple derives
@[derive(Debug, Clone, PartialEq, Eq, Hash)]
struct Key(id: Int, name: String)

Conditional Compilation​

@[cfg(target_os = "linux")]
fn linuxOnly() {
    println!("Linux!")
}

@[cfg(feature = "advanced")]
fn advancedFeature() {
    // Only compiled when "advanced" feature is enabled
}

@[cfg(test)]
module tests {
    // Only compiled in test mode
}

Documentation​

/// This is a documented function.
///
/// # Examples
///
/// ```oxide
/// let result = add(2, 3)
/// assert!(result == 5)
/// ```
fn add(a: Int, b: Int): Int { a + b }

@[doc = "Alternative documentation syntax"]
fn alternative(): Int { 42 }

Inlining​

@[inline]
fn alwaysInline(): Int { 42 }

@[inline(always)]
fn forceInline(): Int { 42 }

@[inline(never)]
fn neverInline(): Int { 42 }

Deprecated​

@[deprecated]
fn oldFunction() { }

@[deprecated(since = "2.0", note = "Use newFunction instead")]
fn legacyFunction() { }

Must Use​

@[must_use]
fn importantResult(): Int { 42 }

@[must_use = "Ignoring this result is likely a bug"]
fn criticalOperation(): Result<(), Error> {
    Ok(())
}

Allow/Warn/Deny​

@[allow(unused_variables)]
fn withUnused() {
    let x = 42  // No warning
}

@[warn(dead_code)]
fn warnIfUnused() { }

@[deny(unsafe_code)]
module safeOnly {
    // Compiler error if any unsafe code
}

Representation​

Control memory layout:

@[repr(C)]
struct CCompatible(x: Int, y: Int)

@[repr(transparent)]
struct Wrapper(inner: Int)

@[repr(UInt8)]
enum SmallEnum {
    case a
    case b
    case c
}

Testing​

@[test]
fn testAddition() {
    assert!(1 + 1 == 2)
}

@[test]
@[should_panic]
fn testPanic() {
    panic!("expected")
}

@[test]
@[ignore]
fn slowTest() {
    // Skipped unless explicitly requested
}

@[bench]
fn benchmarkAddition(b: &var Bencher) {
    b.iter { 1 + 1 }
}

Oxide-Specific Attributes​

No Prelude​

Disable automatic stdlib prelude import:

@file:[no_prelude]

// Must manually import what you need
use oxide_stdlib::prelude::StringExt

Ignore Format​

Skip file during formatting:

@file:[ignore_format]

// This file won't be reformatted by oxfmt
fn   badlyFormatted  (  )  {  }

Multiple Attributes​

Apply multiple attributes:

@[derive(Debug, Clone)]
@[repr(C)]
@[allow(dead_code)]
struct Complex(
    real: Float64,
    imag: Float64
)

Or combine in one:

@[derive(Debug, Clone), repr(C), allow(dead_code)]
struct Complex(real: Float64, imag: Float64)

Attribute Arguments​

Various argument forms:

// No arguments
@[inline]

// Single value
@[repr(C)]

// Key-value
@[deprecated(since = "1.0")]

// Multiple values
@[derive(Debug, Clone)]

// Nested
@[cfg(all(target_os = "linux", feature = "special"))]

See Also​