introspect

A crate for performing introspection on Rust structs and enums.

Request Feature · Report Bug · ⭐ Consider starring the repo! ⭐

Note: currently, only the identifier name and the optional documentation for each supported entity and member are implemented. That was all that was needed at the time the crate was developed. However, we will implement requests and/or accept pull requests that add additional introspection—please just leave an issue on the issues page!

📚 Getting Started

You can add introspect as a dependency via the Github repository.

cargo add --git https://github.com/claymcleod/introspect.git introspect

You can then use the introspect::Introspected trait and related traits to pull out the information you wish. Typically, you will do with the introspect::Introspect derive macro like so.

use introspect::Entity;
use introspect::Introspect;
use introspect::IntrospectedEntity;
use introspect::IntrospectedMembers;
use introspect::Member;

/// This is the documentation for the [`Example`] enum.
///
/// We can add more text down here.
#[allow(dead_code)]
#[derive(Introspect)]
enum Example {
    /// The first variant.
    One,

    /// The second variant.
    ///
    /// And some more text.
    Two,
}

fn main() {
    // Access to the top-level entity characteristics.
    match Example::introspected_entity() {
        Entity::Enum(entity) => {
            dbg!(entity.identifier());
            dbg!(entity.documentation());
        }
        _ => unreachable!(),
    }

    // Access to the members of the entity.
    for member in Example::introspected_members() {
        match member {
            Member::Variant(member) => {
                dbg!(member.identifier());
                dbg!(member.documentation());
            }
            _ => unreachable!(),
        }
    }
}

Examples

You can also take a look at the examples to get a sense of the various ways you can use the crate.

🖥️ Development

To bootstrap a development environment, please use the following commands.

# Clone the repository
git clone git@github.com:claymcleod/introspect.git
cd introspect 

# Build the crate in release mode
cargo build --release

# List out the examples
cargo run --release --example

🚧️ Tests

Before submitting any pull requests, please make sure the code passes the following checks.

# Run the project's tests.
cargo test --all-features

# Ensure the project doesn't have any linting warnings.
cargo clippy --all-features

# Ensure the project passes `cargo fmt`.
cargo fmt --check

# Ensure the docs build successfully.
cargo doc

Minumum Supported Rust Version (MSRV)

This crate is designed to work with Rust version 1.74.0 or later. It may, by happenstance, work with earlier versions of Rust.

🤝 Contributing

Contributions, issues and feature requests are welcome! Feel free to check issues page.

📝 License

This project is licensed as either Apache 2.0 or MIT at your discretion.

Copyright © 2023-Present Clay McLeod.