Crate facet

facet

Thanks to all individual and corporate sponsors, without whom this work could not exist:

         

facet provides runtime reflection for Rust.

Any type that implements Facet trait returns a Shape, which describes:

• The memory layout of the type
• Its definition: struct fields, underlying type for newtypes, etc.
• How to drop it in place

The Poke type is able to allocate (or work from a &mut MaybeUninit<T>) any Facet type, and gradually initialize its fields — until the fully-built value is moved out of the partial.

The Peek type helps perform read operations on any Facet type.

It comes with a derive macro that uses unsynn for speed of compilation.

The core crates, facet-trait, facet-types etc. are nostd-friendly.

Ecosystem

The main facet crate re-exports symbols from:

• facet-trait, which defines the main Facet trait and implements it for foreign types (mostly libstd)
• facet-types, which defines the Shape struct, along with various vtables and the whole Def tree
• facet-opaque, which provides helpers around type-erased pointers like OpaqueUninit, OpaqueConst, Opaque
• facet-derive, which implements the Facet derive attribute as a fast/light proc macro powered by unsynn
• facet-spez, which implements an autoderef specialization trick needed for facet-derive
• facet-peek, which allows reading arbitrary Facet types
• facet-poke, which allows building/altering arbitrary Facet types

facet supports deserialization from multiple data formats through dedicated crates:

• facet-json: JSON deserialization
• facet-yaml: YAML deserialization
• facet-msgpack: MessagePack deserialization
• facet-urlencoded: URL-encoded form data deserialization

Additionally:

• facet-pretty is able to pretty-print Facet types.
• facet-codegen is internal and generates some of the code of facet-core

Example usage

facet-json is the one that gets updated first — look at it.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Modules

facet_spez

facet-spez

hacking

Hacking Guide to Facet

Macros

value_vtable

Creates a ValueVTable for a given type.

Structs

EnumDef

Fields for enum types

EnumDefBuilder

Builder for EnumDef

Field

Describes a field in a struct or tuple

FieldBuilder

Builder for Field

FieldFlags

Flags that can be applied to fields to modify their behavior

HasherProxy

Provides an implementation of core::hash::Hasher for a given hasher pointer and write function

ListDef

Fields for list types

ListDefBuilder

Builder for ListDef

ListVTable

Virtual table for a list-like type (like Vec<T>, but also HashSet<T>, etc.)

ListVTableBuilder

Builds a ListVTable

MapDef

Fields for map types

MapDefBuilder

Builder for MapDef

MapIterVTable

VTable for an iterator over a map

MapIterVTableBuilder

Builds a MapIterVTable

MapVTable

Virtual table for a Map<K, V>

MapVTableBuilder

Builds a MapVTable

MarkerTraits

Bitflags for common marker traits that a type may implement

Opaque

A type-erased pointer to an initialized value

OpaqueConst

A type-erased read-only pointer to an initialized value.

OpaqueUninit

A type-erased pointer to an uninitialized value

ScalarDef

Definition for scalar types

ScalarDefBuilder

Builder for ScalarDef

Shape

Schema for reflection of a type

ShapeBuilder

Builder for Shape

StructDef

Common fields for struct-like types

StructDefBuilder

Builder for StructDef

TypeNameOpts

Options for formatting the name of a type

ValueVTable

VTable for common operations that can be performed on any shape

ValueVTableBuilder

Builds a ValueVTable

Variant

Describes a variant of an enum

VariantBuilder

Builder for Variant

Enums

Characteristic

A characteristic a shape can have

Def

The definition of a shape: is it more like a struct, a map, a list?

EnumRepr

All possible representations for Rust enums

FieldError

Errors encountered when calling field_by_index or field_by_name

ParseError

Error returned by ParseFn

StructKind

Describes the kind of struct (useful for deserializing)

TryFromError

Error type for TryFrom conversion failures

VariantKind

Represents the different kinds of variants that can exist in a Rust enum

Traits

Facet

Allows querying the Shape of a type, which in turn lets us inspect any fields, build a value of this type progressively, etc.

ShapeExt

Extension trait to provide is_type and assert_type

Functions

clone_into_fn_for

Generates a [CloneInPlaceFn] for a concrete type

cmp_fn_for

Generates a CmpFn for a concrete type

debug_fn_for

Generates a DebugFn for a concrete type

default_in_place_fn_for

Generates a DefaultInPlaceFn for a concrete type

display_fn_for

Generates a DisplayFn for a concrete type

drop_in_place_fn_for

Generates a DropInPlaceFn for a concrete type

hash_fn_for

Generates a HashFn for a concrete type

parse_fn_for

Generates a ParseFn for a concrete type

partial_eq_fn_for

Generates a PartialEqFn for a concrete type

partial_ord_fn_for

Generates a PartialOrdFn for a concrete type

Type Aliases

CloneIntoFn

Function to clone a value into another already-allocated value

CmpFn

Function to compare two values and return their ordering

DebugFn

Function to format a value for debug. If this returns None, the shape did not implement Debug.

DefaultInPlaceFn

Function to set a value to its default in-place

DisplayFn

Function to format a value for display

DropInPlaceFn

Function to drop a value

HashFn

Function to hash a value

HasherWriteFn

Function to write bytes to a hasher

ListGetItemPtrFn

Get pointer to the item at the given index. Panics if out of bounds.

ListInitInPlaceWithCapacityFn

Initialize a list in place with a given capacity

ListLenFn

Get the number of items in the list

ListPushFn

Push an item to the list

MapContainsKeyFn

Check if the map contains a key

MapGetValuePtrFn

Get pointer to a value for a given key, returns None if not found

MapInitInPlaceWithCapacityFn

Initialize a map in place with a given capacity

MapInsertFn

Insert a key-value pair into the map

MapIterDeallocFn

Deallocate the iterator

MapIterFn

Get an iterator over the map

MapIterNextFn

Get the next key-value pair from the iterator

MapLenFn

Get the number of entries in the map

ParseFn

Function to parse a value from a string.

PartialEqFn

Function to check if two values are partially equal

PartialOrdFn

Function to compare two values and return their ordering if comparable

TryFromFn

Function to try converting from another type

TypeNameFn

A function that formats the name of a type.

Derive Macros

Facet

Derive the Facet trait for structs, tuple structs, and enums.