inspect-core 0.1.0

//! The core [`Inspect`] trait.

use crate::{InspectCx, ValueRef};

/// Provides structured introspection of a Rust value.
///
/// This trait allows types to expose their structure and content in a way
/// that tools, debuggers, and renderers can consume without requiring
/// specific serialization formats or coupling to UI frameworks.
///
/// # Deriving
///
/// The recommended way to implement `Inspect` is via the derive macro:
///
/// ```ignore
/// use inspect_rs::Inspect;
///
/// #[derive(Inspect)]
/// struct User {
///     id: u64,
///     name: String,
/// }
/// ```
///
/// # Manual implementation
///
/// For types that need custom introspection logic:
///
/// ```
/// use inspect_core::{Inspect, InspectCx, ValueRef, Kind, TypeInfo};
///
/// struct Custom(u32);
///
/// impl Inspect for Custom {
///     fn inspect(&self, cx: &mut InspectCx<'_>) -> ValueRef<'_> {
///         ValueRef::with_type(
///             Kind::U32(self.0),
///             TypeInfo::new("Custom"),
///         )
///     }
/// }
/// ```
pub trait Inspect {
    /// Inspect this value and return a borrowed structured representation.
    ///
    /// # Parameters
    ///
    /// - `cx`: Inspection context containing configuration, limits, and state
    ///
    /// # Performance
    ///
    /// This method should be cheap to call. Avoid allocating entire trees
    /// or traversing large collections. Use lazy child enumeration instead.
    fn inspect(&self, cx: &mut InspectCx<'_>) -> ValueRef<'_>;
}