Crate facet 

facet

facet provides reflection for Rust: it gives types a SHAPE associated const with details on the layout, fields, doc comments, attributes, etc.

It can be used for many things, from (de)serialization to pretty-printing, rich debuggers, CLI parsing, reflection in templating engines, code generation, etc.

See https://facet.rs for details.

Workspace contents

The main facet crate re-exports symbols from:

• facet-core, which defines the main components:
  • The Facet trait and implementations for foreign types (mostly libstd)
  • The Shape struct along with various vtables and the whole Def tree
  • Type-erased pointer helpers like PtrUninit, PtrConst, and Opaque
  • Autoderef specialization trick needed for facet-macros
• facet-macros, which implements the Facet derive attribute as a fast/light proc macro powered by unsynn

For struct manipulation and reflection, we have:

• facet-reflect, allows building values of arbitrary shapes in safe code, respecting invariants. It also allows peeking at existing values.

Internal crates include:

• facet-testhelpers a simple log logger and color-backtrace configured with the lightweight btparse backend

Ecosystem

Various crates live under the https://github.com/facet-rs umbrella, and their repositories are kept somewhat-consistent through facet-dev.

Crates are in various states of progress, buyer beware!

In terms of data formats, we have:

• facet-json: JSON format support
• facet-toml: TOML format support
• facet-yaml: YAML format support
• facet-msgpack: MessagePack deserialization
• facet-asn1: ASN.1 format support
• facet-xdr: XDR format support
• facet-kdl: KDL format support (non-functional so far)

Still adjacent to serialization/deserialization, we have:

• facet-urlencoded: URL-encoded form data deserialization
• facet-args: CLI arguments (a-la clap)

As far as utilities go:

• facet-pretty is able to pretty-print Facet types.
• facet-serialize provides generic iterative serialization facilities
• facet-deserialize provides generic iterative deserialization facilities

And the less developed:

• facet-inspect: Provide utilities to inspect the content of a Facet object.
• facet-diff: Provides diffing capabilities for Facet types.

Extended cinematic universe

Some crates are developed completely independently from the facet org:

• facet-v8 provides an experimental Facet/v8 integration
• facet-openapi (experimental) Generates OpenAPI definitions from types that implement Facet
• facet_generate reflects Facet types into Java, Swift and TypeScript
• multi-array-list provides an experimental MultiArrayList type

Sponsors

Thanks to all individual sponsors:

…along with corporate sponsors:

…without whom this work could not exist.

Special thanks

The facet logo was drawn by Misiasart.

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.

Re-exports

pub use static_assertions;

Modules

hacking

Hacking Guide to Facet

spez

Auto-deref specialization helpers for the Facet reflection system

Macros

debugreflect

Forwards to log::debug when the log feature is enabled

tracereflect

Forwards to log::trace when the log feature is enabled

value_vtable

Creates a ValueVTable for a given type.

value_vtable_unsized

Similar to value_vtable! macro but for !Sized types.

Structs

ArrayDef

Fields for array types

ArrayDefBuilder

Builder for ArrayDef

ArrayType

Describes a fixed-size array ([T; N])

ArrayVTable

Virtual table for an array

ArrayVTableBuilder

Builds a ArrayVTable

ConstTypeId

TypeId equivalent usable in const contexts.

EnumDefBuilder

Builder for EnumDef

EnumType

Fields for enum types

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

FieldIterreflect

An iterator over all the fields of a struct or enum. See HasFields::fields

FieldVTable

Vtable for field-specific operations

FieldVTableBuilder

Builder for FieldVTable

FieldsForSerializeIterreflect

An iterator over the fields of a struct or enum that should be serialized. See HasFields::fields_for_serialize

FunctionPointerDef

Common fields for function pointer types

FunctionPointerDefBuilder

Builder for FunctionPointerDef

Guardreflect

A guard structure to manage memory allocation and deallocation.

HasherProxy

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

HeapValuereflect

A type-erased value stored on the heap

IterVTable

VTable for an iterator

IterVTableBuilder

Builds an IterVTable

ListDef

Fields for list types

ListDefBuilder

Builder for ListDef

ListVTable

Virtual table for a list-like type (like Vec<T>)

ListVTableBuilder

Builds a ListVTable

LockGuardVTable

Functions for manipulating a guard

LockResult

Type-erased result of locking a mutex-like pointer

MapDef

Fields for map types

MapDefBuilder

Builder for MapDef

MapVTable

Virtual table for a Map<K, V>

MapVTableBuilder

Builds a MapVTable

MarkerTraits

Bitflags for common marker traits that a type may implement

NdArrayDef

Fields for n-dimensional array types

NdArrayDefBuilder

Builder for NdArrayDef

NdArrayVTable

Virtual table for a n-dimensional array type (like Matrix<T>, Tensor<T>, etc.)

NdArrayVTableBuilder

Builds a NdArrayVTable

Opaque

Helper type for opaque members

OptionDef

Describes an Option — including a vtable to query and alter its state, and the inner shape (the T in Option<T>).

OptionDefBuilder

Builder for OptionDef

OptionVTable

Virtual table for Option<T>

OptionVTableBuilder

Builds an OptionVTable

Partialreflect

A type-erased, heap-allocated, partially-initialized value.

Peekreflect

Lets you read from a value (implements read-only ValueVTable proxies)

PeekEnumreflect

Lets you read from an enum (implements read-only enum operations)

PeekListreflect

Lets you read from a list (implements read-only facet_core::ListVTable proxies)

PeekListIterreflect

Iterator over a PeekList

PeekListLikereflect

Lets you read from a list, array or slice

PeekListLikeIterreflect

Iterator over a PeekListLike

PeekMapreflect

Lets you read from a map (implements read-only facet_core::MapVTable proxies)

PeekMapIterreflect

Iterator over key-value pairs in a PeekMap

PeekNdArrayreflect

Lets you read from an n-dimensional array (implements read-only facet_core::NdArrayVTable proxies)

PeekOptionreflect

Lets you read from an option (implements read-only option operations)

PeekPointerreflect

Represents a pointer that can be peeked at during memory inspection.

PeekSetreflect

Lets you read from a set

PeekSetIterreflect

Iterator over values in a PeekSet

PeekStructreflect

Lets you read from a struct (implements read-only struct operations)

PeekTuplereflect

Lets you read from a tuple

PointerDef

Describes a pointer — including a vtable to query and alter its state, and the inner shape (the pointee type in the pointer).

PointerDefBuilder

Builder for creating a PointerDef.

PointerFlags

Flags to represent various characteristics of pointers

PointerVTable

Functions for interacting with a pointer

PointerVTableBuilder

Builder for creating a PointerVTable.

PtrConst

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

PtrConstWide

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

PtrMut

A type-erased pointer to an initialized value

PtrMutWide

A type-erased, mutable wide pointer to an initialized value.

PtrUninit

A type-erased pointer to an uninitialized value

PtrUninitWide

A type-erased, wide pointer to an uninitialized value.

Repr

Describes base representation of the type

SetDef

Fields for set types

SetDefBuilder

Builder for SetDef

SetVTable

Virtual table for a Set<T>

SetVTableBuilder

Builds a SetVTable

Shape

Schema for reflection of a type

ShapeBuilder

Builder for Shape

SliceBuilderVTable

Functions for creating and manipulating slice builders.

SliceBuilderVTableBuilder

Builder for creating a SliceBuilderVTable.

SliceDef

Fields for slice types

SliceDefBuilder

Builder for SliceDef

SliceType

Describes a slice ([T])

SliceVTable

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

SliceVTableBuilder

Builds a SliceVTable

StructBuilder

Builder for StructType

StructType

Common fields for struct-like types

TupleTypereflect

Local representation of a tuple type for peek operations

TypeNameOpts

Options for formatting the name of a type

TypeParam

Represents a lifetime parameter, e.g., 'a or 'a: 'b + 'c.

TypedPartialreflect

A typed wrapper around Partial, for when you want to statically ensure that build gives you the proper type.

TypedPtrUninit

A pointer to an uninitialized value with a lifetime.

UnionType

Common fields for union types

UnsizedError

Tried to get the Layout of an unsized type

VTableView

A typed view of a ValueVTable.

ValueIdreflect

A unique identifier for a peek value

ValuePointerType

Describes the raw/reference pointer

ValueVTableBuilder

Builds a ValueVTable

ValueVTableBuilderUnsized

Builds a ValueVTable for a !Sized type

ValueVTableSized

VTable for common operations that can be performed on any Sized shape

ValueVTableUnsized

VTable for common operations that can be performed on any !Sized shape

Variant

Describes a variant of an enum

VariantBuilder

Builder for Variant

Enums

BaseRepr

Underlying byte layout representation

Characteristic

A characteristic a shape can have

Def

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

EnumRepr

All possible representations for Rust enums — ie. the type/size of the discriminant

FieldAttribute

An attribute that can be set on a field

FieldError

Errors encountered when calling field_by_index or field_by_name

FunctionAbi

The calling ABI of a function pointer

GenericPtr

A generic wrapper for either a thin or wide constant pointer. This enables working with both sized and unsized types using a single enum.

KnownPointer

Represents common standard library pointer kinds

ListLikeDefreflect

Fields for types which act like lists

NumericType

Describes numeric types (integer/float)

ParseError

Error returned by ParseFn

PointerType

Describes all pointer types

PrimitiveType

Describes built-in primitives (u32, bool, str, etc.)

ReflectErrorreflect

Errors that can occur when reflecting on types.

ScalarTypereflect

All scalar types supported out of the box by peek and poke.

SequenceType

Describes built-in sequence type (array, slice)

ShapeAttribute

An attribute that can be applied to a shape

ShapeLayout

Layout of the shape

StrideErrorreflect

Error that can occur when trying to access an n-dimensional array as strided

StructKind

Describes the kind of struct (useful for deserializing)

TextualType

Describes textual types (char/string)

TrackerKindreflect

A kind-only version of Tracker

TryBorrowInnerError

Error type returned by TryBorrowInnerFn when attempting to borrow the inner value from a wrapper type.

TryFromError

Error type for TryFrom conversion failures

TryIntoInnerError

Error type returned by TryIntoInnerFn when attempting to extract the inner value from a wrapper type.

Type

The definition of a shape in accordance to rust reference:

UserType

User-defined types (structs, enums, unions)

ValueVTable

A vtable representing the operations that can be performed on a type, either for sized or unsized types.

VariantAttribute

An attribute that can be set on an enum variant

VariantErrorreflect

Error that can occur when trying to determine variant information

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.

HasFieldsreflect

Trait for types that have field methods

IterItem

A kind of item that an IterVTable returns

Functions

of

Create a TypeId for a type.

peek_enumreflect

Returns the enum definition if the shape represents an enum, None otherwise

peek_enum_reprreflect

Returns the enum representation if the shape represents an enum, None otherwise

peek_enum_variantsreflect

Returns the enum variants if the shape represents an enum, None otherwise

Type Aliases

ArrayAsMutPtrFn

Get mutable pointer to the data buffer of the array.

ArrayAsPtrFn

Get pointer to the data buffer of the array.

BorrowFn

Tries to obtain a reference to the inner value of the pointer.

CloneIntoFn

Function to clone a value into another already-allocated value

CloneIntoFnTyped

Function to clone a value into another already-allocated value

CmpFn

Function to compare two values and return their ordering

CmpFnTyped

Function to compare two values and return their ordering

CmpFnWide

Function to compare two values and return their ordering (wide pointer version)

DebugFn

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

DebugFnTyped

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

DebugFnWide

Function to format a value for debug (wide pointer version). If this returns None, the shape did not implement Debug (wide).

DefaultInPlaceFn

Function to set a value to its default in-place

DefaultInPlaceFnTyped

Function to set a value to its default in-place

DisplayFn

Function to format a value for display

DisplayFnTyped

Function to format a value for display

DisplayFnWide

Function to format a value for display (wide pointer version)

DowngradeIntoFn

Downgrades a strong pointer to a weak one.

DropInPlaceFn

Function to drop a value

DropInPlaceFnWide

Function to drop a value (wide pointer version)

HashFn

Function to hash a value

HashFnTyped

Function to hash a value

HashFnWide

Function to hash a value

HasherWriteFn

Function to write bytes to a hasher

HasherWriteFnTyped

Function to write bytes to a hasher

InvariantsFn

Function to validate the invariants of a value. If it returns false, the value is considered invalid.

InvariantsFnTyped

Function to validate the invariants of a value. If it returns false, the value is considered invalid.

InvariantsFnWide

Function to validate the invariants of a value. If it returns false, the value is considered invalid (wide pointer version).

IterDeallocFn

Deallocate the iterator

IterInitWithValueFn

Create a new iterator that iterates over the provided value

IterNextBackFn

Advance the iterator in reverse, returning the next value from the end of the iterator.

IterNextFn

Advance the iterator, returning the next value from the iterator

IterSizeHintFn

Return the lower and upper bounds of the iterator, if known.

ListAsMutPtrFn

Get mutable pointer to the data buffer of the list.

ListAsPtrFn

Get pointer to the data buffer of the list.

ListGetFn

Get pointer to the element at index in the list, or None if the index is out of bounds.

ListGetMutFn

Get mutable pointer to the element at index in the list, or None if the index is 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

LockFn

Acquires a lock on a mutex-like pointer

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

MapLenFn

Get the number of entries in the map

NdArrayAsMutPtrFn

Get mutable pointer to the data buffer of the array.

NdArrayAsPtrFn

Get pointer to the data buffer of the array.

NdArrayByteStrideFn

Get the i-th stride in the array in bytes, or None if the dimension index is out of bounds.

NdArrayCountFn

Get the total count of elements in the array.

NdArrayDimFn

Get the i-th dimension in the array, or None if the dimension index is out of bounds.

NdArrayGetFn

Get pointer to the element at index in the array, or None if the index is out of bounds.

NdArrayGetMutFn

Get mutable pointer to the element at index in the array, or None if the index is out of bounds.

NdArrayNDimFn

Get the number of dimensions in the array.

NewIntoFn

Creates a new pointer wrapping the given value.

OptionGetValueFn

Get the value contained in an option, if present

OptionInitNoneFn

Initialize an option with None

OptionInitSomeFn

Initialize an option with Some(value)

OptionIsSomeFn

Check if an option contains a value

OptionReplaceWithFn

Replace an existing option with a new value

ParseFn

Function to parse a value from a string.

ParseFnTyped

Function to parse a value from a string.

PartialEqFn

Function to check if two values are partially equal

PartialEqFnTyped

Function to check if two values are partially equal

PartialEqFnWide

Function to check if two values are partially equal (wide pointer version)

PartialOrdFn

Function to compare two values and return their ordering if comparable

PartialOrdFnTyped

Function to compare two values and return their ordering if comparable

PartialOrdFnWide

Function to compare two values and return their ordering if comparable (wide pointer version)

ReadFn

Acquires a read lock on a reader-writer lock-like pointer

SetContainsFn

Check if the set contains a value

SetInitInPlaceWithCapacityFn

Initialize a set in place with a given capacity

SetInsertFn

Insert a value in the set if not already contained, returning true if the value wasn’t present before

SetLenFn

Get the number of values in the set

SkipSerializingIfFn

A function that, if present, determines whether field should be included in the serialization step.

SliceAsMutPtrFn

Get mutable pointer to the data buffer of the slice

SliceAsPtrFn

Get pointer to the data buffer of the slice

SliceBuilderConvertFn

Converts a slice builder into a pointer. This takes ownership of the builder and frees the backing storage.

SliceBuilderFreeFn

Frees a slice builder without converting it into a pointer

SliceBuilderNewFn

Creates a new slice builder for a pointer: ie. for Arc<[u8]>, it builds a Vec<u8> internally, to which you can push, and then turn into an Arc<[u8]> at the last stage.

SliceBuilderPushFn

Pushes a value into a slice builder.

SliceLenFn

Get the number of items in the slice

TryBorrowInnerFn

Function to borrow the inner value from a transparent/newtype wrapper without copying.

TryBorrowInnerFnTyped

Function to borrow the inner value from a transparent/newtype wrapper without copying.

TryBorrowInnerFnWide

Function to borrow the inner value from a transparent/newtype wrapper without copying (wide pointer version).

TryFromFn

Function to try converting from another type

TryFromFnTyped

Function to try converting from another type

TryIntoInnerFn

Function to convert a transparent/newtype wrapper into its inner type.

TryIntoInnerFnTyped

Function to convert a transparent/newtype wrapper into its inner type.

TupleFieldreflect

Field index and associated peek value

TypeNameFn

A function that formats the name of a type.

UpgradeIntoFn

Tries to upgrade the weak pointer to a strong one.

WriteFn

Acquires a write lock on a reader-writer lock-like pointer

Derive Macros

Facet

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