Struct Visitor 

pub struct Visitor {
    pub blackboard: Blackboard,
    pub flags: VisitorFlags,
    /* private fields */
}

Visitor is a tree-based serializer/deserializer with intermediate representation for stored data. When data is serialized, it will be transformed into an intermediate representation and only then will be dumped onto the disk. Deserialization is the same: the data (binary or text) is read and converted into an intermediate representation (IR). End users can use this IR to save or load their structures of pretty much any complexity.

Overview

Visitor uses a tree to create structured data storage. Basic unit is a node - it is a container for data fields. Each node has a name, handle to parent, set of handles to children nodes and a container for data fields. Data field is a pair of a name and a value, the value can be any of simple Rust types and some of the trivially copyable data structures (vectors, matrices, etc.). The main criteria of what could be the field and what not is the ability to be represented as a set of bytes.

Instead of calling visitor methods to read or write the visitor’s data, reading and writing happen in the Visit::visit method of a variable that will either store the read value or holds the value to be written.

For example, x.visit("MyValue", &mut visitor) will do one of:

1. Take the value of x and store it in visitor under the name “MyValue”, if visitor.is_reading() is false.
2. Read a value named “MyValue” from visitor and store it in x, if visitor.is_reading() is true.

Whether the value of x gets written into visitor or overwritten with a value from visitor is determined by whether Visitor::is_reading() returns true or false.

Fields

blackboard: Blackboard

A place to store whatever objects may be needed to help with reading and writing values.

flags: VisitorFlags

Flags that can activate special behavior in some Visit values, such as crate::variable::InheritableVariable.

Implementations

impl Visitor

pub const MAGIC_BINARY_CURRENT: &'static str = "FBAF"

Sequence of bytes that is automatically written at the start when a visitor is encoded into bytes. It is written by Visitor::save_binary_to_file, Visitor::save_binary_to_memory, and Visitor::save_binary_to_vec.

Visitor::load_binary_from_file will return an error if this sequence of bytes is not present at the beginning of the file, and Visitor::load_binary_from_memory will return an error of these bytes are not at the beginning of the given slice.

pub const MAGIC_ASCII_CURRENT: &'static str = "FTAX"

Sequence of bytes that is automatically written at the start when a visitor is encoded into ascii form. It is written by Visitor::save_ascii_to_file, Visitor::save_ascii_to_memory, and Visitor::save_ascii_to_string.

Visitor::load_ascii_from_file will return an error if this sequence of bytes is not present at the beginning of the file, and Visitor::load_ascii_from_memory will return an error of these bytes are not at the beginning of the given slice.

pub fn is_supported(src: &mut dyn Read) -> bool

Checks whether the given reader points to a supported file format or not.

pub fn detect_format(src: &mut dyn Read) -> Format

Tries to extract the information about the file format in the given reader.

pub fn detect_format_from_slice(data: &[u8]) -> Format

Tries to extract the information about the file format in the given slice.

pub fn new() -> Visitor

Creates a Visitor containing only a single node called “__ROOT__” which will be the current region of the visitor.

pub fn find_field(&mut self, name: &str) -> Option<&mut Field>

Tries to find a field by its name.

pub fn find_node(&self, name: &str) -> Option<&VisitorNode>

Tries to find a node by its name.

pub fn is_reading(&self) -> bool

True if this Visitor is changing the values that it visits. In other words, x.visit("MyValue", &mut visitor) will result in x being mutated to match whatever value is stored in visitor.

False if this visitor is copying and storing the values that it visits. In other words, x.visit("MyValue", &mut visitor) will result in x being unchanged, but visitor will be mutated to store the value of x under the name “MyValue”.

pub fn version(&self) -> u32

Returns version number of the visitor.

pub fn has_region(&self, name: &str) -> bool

Returns true of a region with the given name exists as a child of the current node. When reading, has_region returning true means that enter_region will succeed. When writing, has_region returning true means that enter_region will fail.

pub fn enter_region( &mut self, name: &str, ) -> Result<RegionGuard<'_>, VisitError>

If Visitor::is_reading, find a node with the given name that is a child of the current node, and return a Visitor for the found node. Return an error if no node with that name exists.

If not reading, create a node with the given name as a chld of the current node, and return a visitor for the new node. Return an error if a node with that name already exists.

pub fn breadcrumbs(&self) -> String

Return a string representing all the regions from the root to the current node.

pub fn current_region(&self) -> Result<&str, PoolError>

The name of the current region. This should never be None if the Visitor is operating normally, because there should be no way to leave the initial __ROOT__ region.

pub fn debug(&self) -> String

Get the content of the current node in human-readable form.

pub fn debug_to<W>(&self, w: &mut W) -> Result<(), VisitError>

where W: Write,

Write the content of the current node in human-readable form.

pub fn save_ascii_to_string(&self) -> String

Create a string containing all the data of this Visitor in ascii form. The string is formatted to be human-readable with each node on its own line and tabs to indent child nodes.

pub fn save_ascii_to_file( &self, path: impl AsRef<Path>, ) -> Result<(), VisitError>

Create a string containing all the data of this Visitor in ascii form and saves it to the given path. The string is formatted to be human-readable with each node on its own line and tabs to indent child nodes.

pub fn save_ascii_to_memory(&self, dest: impl Write) -> Result<(), VisitError>

Create a string containing all the data of this Visitor in ascii form and writes it to the given writer. The string is formatted to be human-readable with each node on its own line and tabs to indent child nodes.

pub fn load_ascii_from_memory(data: &[u8]) -> Result<Visitor, VisitError>

Tries to create a visitor from the given data. The returned instance can then be used to deserialize some data.

pub async fn load_ascii_from_file( path: impl AsRef<Path>, ) -> Result<Visitor, VisitError>

Tries to create a visitor from the given file. The returned instance can then be used to deserialize some data.

pub fn save_binary_to_memory(&self, dest: impl Write) -> Result<(), VisitError>

Write the data of this Visitor to the given writer. Begin by writing Visitor::MAGIC_BINARY_CURRENT.

pub fn save_binary_to_vec(&self) -> Result<Vec<u8>, VisitError>

Encode the data of this visitor into bytes and push the bytes into the given Vec<u8>. Begin by writing Visitor::MAGIC_BINARY_CURRENT.

pub fn save_binary_to_file( &self, path: impl AsRef<Path>, ) -> Result<(), VisitError>

Create a file at the given path and write the data of this visitor into that file in a non-human-readable binary format so that the data can be reconstructed using Visitor::load_binary_from_file. Begin by writing Visitor::MAGIC_BINARY_CURRENT.

pub async fn load_binary_from_file( path: impl AsRef<Path>, ) -> Result<Visitor, VisitError>

Create a visitor by reading data from the file at the given path, assuming that the file was created using Visitor::save_binary_to_file. Return a VisitError::NotSupportedFormat if Visitor::MAGIC_BINARY_CURRENT is not the first bytes read from the file.

pub fn load_binary_from_memory(data: &[u8]) -> Result<Visitor, VisitError>

Create a visitor by decoding data from the given byte slice, assuming that the bytes are in the format that would be produced by Visitor::save_binary_to_vec. Return a VisitError::NotSupportedFormat if Visitor::MAGIC_BINARY_CURRENT is not the first bytes read from the slice.

pub async fn load_from_file( path: impl AsRef<Path>, ) -> Result<Visitor, VisitError>

Tries to load a visitor from the given file. This method automatically detects a format of the incoming data (binary or ASCII) and tries to load it.

pub fn load_from_memory(data: &[u8]) -> Result<Visitor, VisitError>

Tries to load a visitor from the given data. This method automatically detects a format of the incoming data (binary or ASCII) and tries to load it.

Trait Implementations

impl Debug for Visitor

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Visitor

fn default() -> Visitor

Returns the “default value” for a type.