[−][src]Crate sfv

sfv crate is an implementation of IETF draft Structured Field Values for HTTP for parsing and serializing structured HTTP field values. It also exposes a set of types that might be useful for defining new structured fields.

Data Structures

There are three types of structured fields:

Item - can be an Integer, Decimal, String, Token, Byte Sequence, or Boolean. It can have associated Parameters.
List - array of zero or more members, each of which can be an Item or an InnerList, both of which can be Parameterized.
Dictionary - ordered map of name-value pairs, where the names are short textual strings and the values are Items or arrays of Items (represented with InnerList), both of which can be Parameterized. There can be zero or more members, and their names are unique in the scope of the Dictionary they occur within.

There's also a few primitive types used to construct structured field values:

BareItem used as Item's value or as a parameter value in Parameters.
Parameters are an ordered map of key-value pairs that are associated with an Item or InnerList. The keys are unique within the scope the Parameters they occur within, and the values are BareItem.
InnerList is an array of zero or more Items. Can have Parameters.
ListEntry represents either Item or InnerList as a member of List or as member-value in Dictionary.

Examples

Parsing

use sfv::Parser;

// Parsing structured field value of Item type
let item_header_input = "12.445;foo=bar";
let item = Parser::parse_item(item_header_input.as_bytes());
assert!(item.is_ok());
println!("{:#?}", item);

// Parsing structured field value of List type
let list_header_input = "1;a=tok, (\"foo\" \"bar\");baz, ()";
let list = Parser::parse_list(list_header_input.as_bytes());
assert!(list.is_ok());
println!("{:#?}", list);

// Parsing structured field value of Dictionary type
let dict_header_input = "a=?0, b, c; foo=bar, rating=1.5, fruits=(apple pear)";
let dict = Parser::parse_dictionary(dict_header_input.as_bytes());
assert!(dict.is_ok());
println!("{:#?}", dict);

Value Creation and Serialization

Create Item with empty parameters:

use sfv::{Item, BareItem, SerializeValue};

let str_item = Item::new(BareItem::String(String::from("foo")));
assert_eq!(str_item.serialize_value().unwrap(), "\"foo\"");

Create Item field value with parameters:

use sfv::{Item, BareItem, SerializeValue, Parameters, Decimal, FromPrimitive};

let mut params = Parameters::new();
let decimal = Decimal::from_f64(13.45655).unwrap();
params.insert("key".into(), decimal.into());
let int_item = Item::with_params(99.into(), params);
assert_eq!(int_item.serialize_value().unwrap(), "99;key=13.457");

Create List field value with Item and parametrized InnerList as members:

use sfv::{Item, BareItem, InnerList, List, SerializeValue, Parameters};

// Create Item
let tok_item = BareItem::Token("tok".into());

// Create InnerList members
let str_item = Item::new(BareItem::String(String::from("foo")));

let mut int_item_params = Parameters::new();
int_item_params.insert("key".into(), BareItem::Boolean(false));
let int_item = Item::with_params(99.into(), int_item_params);

// Create InnerList
let mut inner_list_params = Parameters::new();
inner_list_params.insert("bar".into(), BareItem::Boolean(true));
let inner_list = InnerList::with_params(vec![int_item, str_item], inner_list_params);


let list: List = vec![Item::new(tok_item).into(), inner_list.into()];
assert_eq!(
    list.serialize_value().unwrap(),
    "tok, (99;key=?0 \"foo\");bar"
);

Create Dictionary field value:

use sfv::{Parser, Item, BareItem, SerializeValue, ParseValue, Dictionary};

let member_value1 = Item::new(BareItem::String(String::from("apple")));
let member_value2 = Item::new(BareItem::Boolean(true));
let member_value3 = Item::new(BareItem::Boolean(false));

let mut dict = Dictionary::new();
dict.insert("key1".into(), member_value1.into());
dict.insert("key2".into(), member_value2.into());
dict.insert("key3".into(), member_value3.into());

assert_eq!(
    dict.serialize_value().unwrap(),
    "key1=\"apple\", key2, key3=?0"
);

Structs

Decimal	`Decimal` represents a 128 bit representation of a fixed-precision decimal number. The finite set of values of type `Decimal` are of the form m / 10^e, where m is an integer such that -2⁹⁶ < m < 2⁹⁶, and e is an integer between 0 and 28 inclusive.
InnerList	Array of `Items` with associated `Parameters`.
Item	Represents `Item` type structured field value. Can be used as a member of `List` or `Dictionary`.
Parser	Exposes methods for parsing input into structured field value.

Enums

BareItem	`BareItem` type is used to construct `Items` or `Parameters` values.
ListEntry	Represents a member of `List` or `Dictionary` structured field value.
Num	Used to represent either `Decimal` or `Integer` as `Numeric` variant of `BareItem`.

Traits

FromPrimitive	A generic trait for converting a number to a value.
FromStr	Parse a value from a string
ParseMore	If structured field value of List or Dictionary type is split into multiple lines, allows to parse more lines and merge them into already existing structure field value.
ParseValue	Implements parsing logic for each structured field value type.
SerializeValue	Serializes structured field value into String.

Type Definitions

Dictionary	Represents `Dictionary` type structured field value.
List	Represents `List` type structured field value.
Parameters	Parameters of `Item` or `InnerList`.