Crate planus

Source
Expand description

§Planus – alternative flatbuffer implementation

Build Status Rustc Version 1.70+ License Crates.io Rust Documentation Discord

Planus is an alternative compiler for flatbuffers, an efficient cross platform serialization library.

§Getting started

First, install the command line utility

cargo install planus-cli

Next, write a flatbuffers file (or use an existing one). Then you can generate code using the command

planus rust -o <output_path.rs> <input_file.fbs>

For a complete example, see examples/rust.

§Features

  • planus view: a TUI viewer for serialized flatbuffer files

Planus View

To use it you need to specify the .fbs file, the root type and the binary file:

planus view test/rust/test_files/alignment.fbs Root test/rust/test_files/alignment/serialize/alignment.bin

  • planus format: formatter for .fbs files

  • planus check: check validity of .fbs files with good error messages

  • planus dot: generate a DOT graph for .fbs files

  • planus rust: generate Rust bindings for .fbs files

§Goals

  • User experience: Our command-line interface has excellent error and help messages. We aim to output good error messages even for non-supported features.
  • Idiomatic code: We want to generate highly idiomatic code that should be very familiar to programmers of the target programming language.
  • Safety: Any undefined/unsafe behavior in the generated code is considered a critical bug.
  • Performance: We want to be at least as performant as the official implementation.
  • Modularity: We have written our code such that parsing, validation and translation are clearly separated. We hope this will make it easy to implement additional backends with full support.
  • Opinionated: We are in some cases more strict than the official implementation.
  • Developer tools: We want to build good developer tools using our library. This includes at least a schema formatter and a tool to output a DOT graph of the types in a schema.
  • Rust: By choosing to use Rust for our compiler, we are able to utilize excellent crates such as clap, LALRPOP and codespan as force multipliers.

§Non-goals

  • Full feature parity: Certain features are difficult to re-implement in a clean fashion.
  • API-level compatibility: We aim for binary-level compatibility, but the code we generate will not works directly with the APIs of the official implementation.
  • Language-specific extensions: We do not plan to support any extensions that break support between different languages.
  • Validation-free access: Validation-free access makes it very easy to shoot yourself in the foot. We will not provide such APIs.

§Languages supported

Currently we only support Rust, though we plan to add support for more languages in the future. Pull requests are welcome!

§Community

Before contributing or participating in discussions with the community, you should familiarize yourself with the Code of Conduct we follow in this project.

If you would like to contribute, please open an issue or pull request to discuss your idea.

For more more open-ended questions or complex decisions, feel free to open a Github Discussion or ping the developers on Discord.

§Status of the implementation

We support most of the base language, though some parts have not been tested in-depth.

Things we do not currently support:

  • rpc_service
  • file_extension, file_identifier and root_type
  • Fixed-size arrays
  • Vectors of unions
  • Any attribute besides required, deprecated, id or force_align.
  • Some of the more exotic literal values, like hexadecimal floats or unicode surrogate pair parsing.

Things we will probably never support:

  • native_includes
  • More than one namespace per file.
  • Flexbuffers.

§Minimum Supported Rust Version (MSRV)

Our current Minimum Supported Rust Version is 1.70.0. When adding features, we will follow these guidelines:

  • We will aim to support the latest five minor Rust versions. This gives you a 6 month window to upgrade your compiler.
  • Any change to the MSRV will be accompanied with a minor version bump

§I think I found a bug!

Please file an issue! We also consider poor error messages or unintuitive behavior to be high-priority bugs.

Re-exports§

pub use crate::errors::Error;
pub use crate::slice_helpers::ArrayWithStartOffset;
pub use crate::slice_helpers::SliceWithStartOffset;
pub use crate::vectors::Vector;

Modules§

errors
Error types for serialization/deserialization
vectors
Types for interacting with vectors in serialized data

Structs§

Builder
Builder for serializing flatbuffers.
Offset
An offset to a serialized value of type T inside a buffer currently being built.
UnionOffset
An offset to a serialized union value of type T inside a buffer currently being built.

Traits§

ReadAsRoot
Interface for getting a view into serialized data.
VectorRead
Trait used by generated code to read elements from vectors.
VectorWrite
Trait used by generated code to write elements to vectors.
WriteAs
Trait used by generated code to serialize primitive types.
WriteAsDefault
Trait used by generated code to serialize primitive types with default values.
WriteAsOffset
Trait used by generated code to serialize offsets to already serialized data.
WriteAsOptional
Trait used by generated code to serialize optional primitive types.
WriteAsOptionalUnion
Trait used by generated code to serialize offsets to optional unions.
WriteAsUnion
Trait used by generated code to serialize offsets to unions.

Type Aliases§

Result
A type alias for Result with a Planus error