Crate blather

A protocol and a communication library for a mostly line-based key/value protocol.

Communication buffers

blather defines a few buffers which it uses to send and receive information over its communication module.

Telegrams

The most central communication buffer is Telegram, which consists of a topic and zero or more key/value pairs, where each key must be unique.

use blather::Telegram;

let mut tg = Telegram::new("AddUser");

tg.add_param("Name", "Frank Foobar");
tg.add_param("Job", "Secret Agent");
tg.add_param("Age", "42");

assert_eq!(tg.get_topic(), "AddUser");
assert_eq!(tg.get_str("Name").unwrap(), "Frank Foobar");
assert_eq!(tg.get_fromstr::<u32, _>("Nonexistent").unwrap(), None);
assert_eq!(tg.get_fromstr::<u8, _>("Age").unwrap(), Some(42));

Params

These are simple key/value pairs, which can be seen as HashMap’s with some restrictions on key names.

use blather::Params;

let mut params = Params::new();

params.add_param("Name", "Frank Foobar");
params.add_param("Job", "Secret Agent");
params.add_param("Age", "42");

assert_eq!(params.get_str("Name").unwrap(), "Frank Foobar");
assert_eq!(params.get_fromstr::<u8, _>("Age").unwrap(), Some(42));

A set of “parameters”, represented by the Params struct, is a set of key/value pairs. They look similar to Telegrams because the Telegram’s implement their key/value paris using a Params buffer.

Communication

blather handles transmission using tokio-util’s Framed framework, by implementing its own Codec. It can be used to send and receive the various communication buffers supported by the crate.

Re-exports

pub use codec::Codec;

Modules

codec

A tokio_util::codec Codec that is used to encode and decode the blather protocol.

Structs

KVLines

Ordered list of key/value pairs, with no uniqueness constraint for the keys.

KeyValue

Representation of a key/value pair in KVLines.

Params

Key/value parameters storage with helper methods to make adding and getting common value types slightly more ergonomic and using a plain HashMap.

Telegram

Representation of a Telegram; a buffer which contains a topic and a set of key/value parameters.

Enums

Error

Error that blather can emit.

ParamError

Specifies whether a parameter key or value is invalid.