cheadergen 0.2.4

//! Configure how `cheadergen` generates C/C++ headers from Rust.
//!
//! `cheadergen` generates C/C++ header files from Rust libraries that expose a
//! `pub extern "C"` API. Output is controlled in two complementary ways:
//!
//! - **[`cheadergen.toml`](config_reference)** — a project-wide TOML file that
//!   the CLI loads via `--config`. It sets the preamble, include guards, sort
//!   order, per-package opaque/skip rules, per-header overrides, and
//!   language-specific options. See the [config reference](config_reference)
//!   for the full schema.
//! - **Per-item attributes** — `#[cheadergen::config(...)]` on items and
//!   `#[cheadergen(...)]` on fields and variants, placed in your Rust source
//!   to control how an individual definition appears in the generated header.
//!   See the [`config`] macro for the directive reference.
//!
//! # Per-item attributes
//!
//! There are two attribute levels:
//!
//! - [`#[cheadergen::config(...)]`](config) — placed on items (structs, enums,
//!   unions, functions, statics, type aliases) to control their header
//!   representation.
//! - `#[cheadergen(...)]` — placed on fields and enum variants to control
//!   their individual representation within a parent item.
//!
//! ## Example
//!
//! ```ignore
//! #[cheadergen::config(export, rename = "CColor")]
//! #[repr(C)]
//! pub enum Color {
//!     #[cheadergen(rename = "COLOR_RED")]
//!     Red,
//!     Green,
//!     Blue,
//! }
//!
//! #[cheadergen::config(export, field_names(x, y))]
//! #[repr(C)]
//! pub struct Point2D(pub f64, pub f64);
//!
//! #[cheadergen::config(skip)]
//! #[unsafe(no_mangle)]
//! pub extern "C" fn internal_helper() {}
//! ```

/// Control how a Rust item appears in the generated C/C++ header.
///
/// # Example
///
/// ```ignore
/// #[cheadergen::config(export, rename = "CConfig")]
/// //                   ~~~~~~  ~~~~~~~~~~~~~~~~~~
/// //                   │       └ Override the C name
/// //                   └ Force inclusion in the header
/// #[repr(C)]
/// pub struct Config {
///     #[cheadergen(rename = "raw_width")]
///     //           ~~~~~~~~~~~~~~~~~~~~
///     //           └ Override the C field name
///     pub width: u32,
///     #[cheadergen(bitfield = 8)]
///     //           ~~~~~~~~~~~
///     //           └ Emit as a C bitfield with width 8
///     pub flags: u8,
///     #[cheadergen(const_ptr)]
///     //           ~~~~~~~~~
///     //           └ Emit a pointer field as a constant pointer
///     pub data: std::ptr::NonNull<u8>,
/// }
/// ```
///
/// # Directives
///
/// | Name | Applies to | Required |
/// |------|-----------|----------|
/// | [`export`](#export) | struct, enum, union, type alias | No |
/// | [`opaque`](#opaque) | struct, enum, union, type alias | No |
/// | [`skip`](#skip) | struct, enum, union, type alias, function, static | No |
/// | [`rename`](#rename) | struct, enum, union, type alias, function, static | No |
/// | [`prefix_with_name`](#prefix_with_name) | enum | No |
/// | [`field_names`](#field_names) | tuple struct | No |
/// | [`rename_all`](#rename_all) | struct, enum, union | No |
/// | [`rename_all_fields`](#rename_all_fields) | enum (with struct variant) | No |
///
/// ## `export`
///
/// Force the item to be included in the generated header. By default, `cheadergen` only includes
/// items that are reachable from `pub extern "C"` functions. Use `export` to include items that
/// are not directly reachable but should still appear in the header.
///
/// ```ignore
/// #[cheadergen::config(export)]
/// //                   ~~~~~~
/// //                   └ Include this struct in the header
/// #[repr(C)]
/// pub struct Config {
///     pub width: u32,
/// }
/// ```
///
/// Combine with [`opaque`](#opaque) to force inclusion as a forward declaration
/// without exposing the layout:
///
/// ```ignore
/// #[cheadergen::config(export, opaque)]
/// //                   ~~~~~~~~~~~~~~
/// //                   └ Force-include as an opaque (forward-declared) type
/// pub struct OpaqueHandle {
///     _inner: u64,
/// }
/// ```
///
/// Cannot be applied to functions or statics (they are included via `#[unsafe(no_mangle)]`).
/// Cannot be combined with [`skip`](#skip).
///
/// ## `opaque`
///
/// Emit the type as an opaque forward declaration whenever it appears in the
/// generated header — i.e. without exposing its fields or variants. On its own,
/// `opaque` is a hint: it does not force inclusion. The type is still subject
/// to the usual reachability rules and `skip` overrides.
///
/// ```ignore
/// #[cheadergen::config(opaque)]
/// //                   ~~~~~~
/// //                   └ If included, emit as a forward declaration
/// pub struct InternalHandle {
///     _inner: u64,
/// }
/// ```
///
/// Combine with [`export`](#export) to force inclusion as an opaque
/// forward declaration regardless of reachability.
///
/// Cannot be applied to functions, statics, or constants — opaque only makes
/// sense for types.
///
/// ## `skip`
///
/// Exclude the item from the generated header, even if it would otherwise be included.
///
/// ```ignore
/// #[cheadergen::config(skip)]
/// //                   ~~~~
/// //                   └ Exclude this function from the header
/// #[unsafe(no_mangle)]
/// pub extern "C" fn internal_helper() {}
/// ```
///
/// Cannot be combined with [`export`](#export).
///
/// ## `rename`
///
/// Override the C name of the item. By default, the Rust identifier is used as-is.
///
/// ```ignore
/// #[cheadergen::config(rename = "CPoint")]
/// //                   ~~~~~~~~~~~~~~~~~
/// //                   └ Use "CPoint" instead of "Point" in the header
/// #[repr(C)]
/// pub struct Point {
///     pub x: f64,
///     pub y: f64,
/// }
/// ```
///
/// ## `prefix_with_name`
///
/// Prefix each variant of a C enum with the enum's name, separated by an underscore.
/// This is common in C to avoid name collisions since C enums share a global namespace.
///
/// ```ignore
/// #[cheadergen::config(prefix_with_name)]
/// //                   ~~~~~~~~~~~~~~~~
/// //                   └ Variants become Status_Ok, Status_Error, ...
/// #[repr(C)]
/// pub enum Status {
///     Ok,
///     Error,
/// }
/// ```
///
/// Use `prefix_with_name = false` to explicitly disable the behavior (useful when overriding
/// a default configuration).
///
/// Can only be applied to enums.
///
/// ## `field_names`
///
/// Assign C field names to the fields of a tuple struct. The number of names must match
/// the number of fields.
///
/// ```ignore
/// #[cheadergen::config(field_names(x, y))]
/// //                   ~~~~~~~~~~~~~~~~~
/// //                   └ Name the two fields "x" and "y" in the C header
/// #[repr(C)]
/// pub struct Point2D(pub f64, pub f64);
/// ```
///
/// Can only be applied to tuple structs.
///
/// ## `rename_all`
///
/// Bulk-rename fields (struct/union) or variants (enum) using a casing rule. Mirrors serde's
/// directive of the same name. Accepted values (string literal, case-sensitive):
///
/// | Rule                      | Example: `max_value` / `MaxValue` becomes |
/// |---------------------------|--------------------------------------------|
/// | `"camelCase"`             | `maxValue`                                 |
/// | `"PascalCase"`            | `MaxValue`                                 |
/// | `"snake_case"`            | `max_value`                                |
/// | `"SCREAMING_SNAKE_CASE"`  | `MAX_VALUE`                                |
///
/// ```ignore
/// #[cheadergen::config(export, rename_all = "camelCase")]
/// //                           ~~~~~~~~~~~~~~~~~~~~~~~~
/// //                           └ Fields become maxValue, minValue
/// #[repr(C)]
/// pub struct Settings {
///     pub max_value: u32,
///     pub min_value: u32,
/// }
/// ```
///
/// A per-field/per-variant `#[cheadergen(rename = "...")]` always wins over the bulk rule.
///
/// When combined with [`prefix_with_name`](#prefix_with_name), the prefix (derived from the
/// enum name) is also cased so the resulting C identifier is consistent:
///
/// ```ignore
/// #[cheadergen::config(export, prefix_with_name, rename_all = "SCREAMING_SNAKE_CASE")]
/// #[repr(C)]
/// pub enum MyStatus {
///     OkResult,
///     ErrorCode,
/// }
/// // Variants emitted as `MY_STATUS_OK_RESULT`, `MY_STATUS_ERROR_CODE`.
/// ```
///
/// An explicit `rename = "..."` on the enum short-circuits the prefix casing — the explicit
/// C name is used verbatim as the prefix.
///
/// Cannot be applied to functions, statics, or type aliases.
///
/// ## `rename_all_fields`
///
/// On an enum, bulk-rename the fields inside every struct variant. Accepts the same casing
/// values as [`rename_all`](#rename_all). Variant names themselves are unaffected (use
/// `rename_all` for those).
///
/// ```ignore
/// #[cheadergen::config(export, rename_all_fields = "camelCase")]
/// //                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/// //                           └ Struct-variant fields become camelCase
/// #[repr(C)]
/// pub enum Message {
///     Plain,
///     WithBody {
///         message_text: u32, // -> messageText
///         sender_id: u32,    // -> senderId
///     },
/// }
/// ```
///
/// Can only be applied to enums that have at least one struct (named-fields) variant.
///
/// # Field and variant directives
///
/// Fields and enum variants use `#[cheadergen(...)]` (without `::config`).
///
/// | Name | Applies to | Required |
/// |------|-----------|----------|
/// | [`rename`](#field-rename) | field, variant | No |
/// | [`bitfield`](#bitfield) | field (not variant) | No |
/// | [`const_ptr`](#const_ptr) | field (not variant) | No |
///
/// ## `rename` (field) {#field-rename}
///
/// Override the C name of a struct field or enum variant.
///
/// ```ignore
/// #[cheadergen::config(export)]
/// #[repr(C)]
/// pub enum Color {
///     #[cheadergen(rename = "COLOR_RED")]
///     //           ~~~~~~~~~~~~~~~~~~~~
///     //           └ Use "COLOR_RED" instead of "Red"
///     Red,
///     Green,
/// }
/// ```
///
/// ## `bitfield`
///
/// Emit the field as a C bitfield with the given width in bits.
///
/// ```ignore
/// #[cheadergen::config(export)]
/// #[repr(C)]
/// pub struct Flags {
///     #[cheadergen(bitfield = 4)]
///     //           ~~~~~~~~~~~
///     //           └ Emit as a 4-bit bitfield
///     pub mode: u8,
/// }
/// ```
///
/// Cannot be applied to enum variants.
///
/// ## `const_ptr`
///
/// Qualify a pointer field as a constant pointer in the generated C header.
/// This is useful for Rust field types like `NonNull<T>`, which normally lower
/// to `T *` but may need to be exposed as `const T *` to C consumers.
///
/// ```ignore
/// use std::ptr::NonNull;
///
/// #[cheadergen::config(export)]
/// #[repr(C)]
/// pub struct View {
///     #[cheadergen(const_ptr)]
///     //           ~~~~~~~~~
///     //           └ Emit as `const uint8_t *data`
///     pub data: NonNull<u8>,
/// }
/// ```
///
/// The directive is checked after type simplification. If the field does not
/// resolve to a pointer type in C, header generation fails.
///
/// Cannot be applied to enum variants.
pub use cheadergen_macros::config;

pub mod config_reference;