2 unstable releases

Uses new Rust 2021

0.2.0 Sep 17, 2022
0.1.0 Jul 29, 2022

#214 in #serde

24 downloads per month

MPL-2.0 license

26KB
471 lines

type_description

Bors enabled

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!()
}

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

~0.4–1.4MB
~30K SLoC