read_only/
lib.rs

1//! Read-only field exposure macros.
2//!
3//! This crate intentionally combines two patterns:
4//!
5//! - [`cast`] is the classic cast-based readonly-field pattern, re-exported
6//!   from the [`readonly`] crate.
7//! - [`embed`] is this crate's safe composition-based alternative that builds a
8//!   dedicated `ReadOnly*` view struct and dereferences into it without unsafe
9//!   code in the generated access path.
10//!
11//! Two attributes are provided:
12//!
13//! - `#[cast]` (re-exported from the [`readonly`] crate) — generates a
14//!   `ReadOnly*` struct with the same fields and provides `Deref` via an unsafe
15//!   pointer cast. Fields remain writable within the defining module but become
16//!   read-only externally.
17//!
18//! - `#[embed]` — safe composition pattern. Fields annotated `#[readonly]` are
19//!   moved into a `ReadOnly*` struct embedded inside the owning struct. A safe
20//!   `Deref<Target=ReadOnly*>` impl is generated. Non-readonly fields stay on
21//!   the owning struct and are accessed directly.
22//!
23//! The default-enabled `docs` feature makes rustdoc render a docs-only outer
24//! struct for `#[embed]` so readonly fields appear directly in the documented
25//! field list.
26//!
27//! For `#[embed]`, writing `pub` on a `#[readonly]` field is optional: the
28//! generated readonly view promotes inherited visibility to the struct's
29//! visibility.
30//!
31//! # Choosing a Macro
32//!
33//! Use [`cast`] when you want the familiar `readonly` behavior and the smallest
34//! syntax change.
35//!
36//! Use [`embed`] when you want an explicit readonly view type and a safe
37//! composition-based implementation.
38//!
39//! # About `cast`
40//!
41//! [`cast`] is a re-export of [`readonly::make`]. This crate intentionally uses
42//! the upstream implementation and upstream item documentation for that macro.
43//! The crate-level docs and README provide the local framing for how `cast`
44//! fits beside [`embed`].
45//!
46//! # Examples
47//!
48//! See the runnable examples in:
49//!
50//! - `examples/basic.rs`
51//! - `examples/embed_deref.rs`
52
53#![doc(html_root_url = "https://docs.rs/read-only")]
54
55pub use read_only_derive::embed;
56pub use readonly::make as cast;
read_only/lib.rs

read_only/
lib.rs
