5 releases (breaking)

0.5.0 May 16, 2023
0.4.0 Apr 18, 2023
0.3.0 Apr 13, 2023
0.2.0 Sep 17, 2022
0.1.0 Jul 29, 2022

#796 in #derive

Download history 12/week @ 2024-03-15 4/week @ 2024-03-22 15/week @ 2024-03-29 1/week @ 2024-04-05 63/week @ 2024-04-12 1/week @ 2024-04-19 3/week @ 2024-05-24 2/week @ 2024-05-31

83 downloads per month
Used in type_description

MPL-2.0 license

24KB
509 lines

type_description

Bors enabled docs.rs crates.io

This crate provides machine-readable descriptions for types.

For a general overview, please check out the guide.

The idea is to make types discoverable for users by explaining them in a way that a user can understand without knowing implementation details (a u16 is an "integer with 16 bit")

Example

One could make configuration types explained with this crate and show the explanation (in a GUI, web interface, some special config-editor) to the user.

use type_description::AsTypeDescription;
use type_description::TypeDescription;
use type_description::TypeKind;
use type_description::Sign;

/// A configuration
#[derive(TypeDescription)]
struct Config {
    /// The bind address
    addr: std::net::SocketAddr,

    /// The Port
    port: u16,
}

let desc = Config::as_type_description();

assert_eq!(desc.name(), "Config");
assert_eq!(desc.doc(), Some("A configuration"));
assert!(std::matches!(desc.kind(), TypeKind::Struct(_)));

match desc.kind() {
    TypeKind::Struct(v) => {
        let first_field = &v[0];
        assert_eq!(first_field.name(), "addr");
        assert_eq!(first_field.doc(), Some("The bind address"));
        assert_eq!(first_field.kind().name(), "String");
        assert_eq!(first_field.kind().doc(), Some("A socket address"));
        assert_eq!(*first_field.kind().kind(), type_description::TypeKind::String);

        let second_field = &v[1];
        assert_eq!(second_field.name(), "port");
        assert_eq!(second_field.doc(), Some("The Port"));
        assert_eq!(second_field.kind().name(), "Integer");
        assert_eq!(second_field.kind().doc(), Some("An unsigned integer with 16 bits"));
        assert_eq!(*second_field.kind().kind(), type_description::TypeKind::Integer { size: 16, sign: Sign::Unsigned });
    }
    _ => unreachable!()
}

Extra Types

This crate contains a AsTypeDescription implementation for various third party crates. The up to date list can be found on docs.rs.

Goals

  • Follow the serde model and be compatible with all serde::{Deserialize, Serialize} types
  • Produce machine-readable description for types implementing AsTypeDescription

Non-Goals

  • Allow constructing values through TypeDescription (serde::Deserialize should be preferred for that)
  • Any form of reflection

License

MPL-2.0

Dependencies

~1.5MB
~36K SLoC