[][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

Creates 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\"");

Creates 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(), BareItem::Decimal(decimal));
let int_item = Item::with_params(BareItem::Integer(99), params);
assert_eq!(int_item.serialize_value().unwrap(), "99;key=13.457");

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

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

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

// Creates Item.
let str_item = Item::new(BareItem::String(String::from("foo")));

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

// Creates 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"
);

Creates 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 / 10e, where m is an integer such that -296 < m < 296, 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.

RefDictSerializer

Serializes Dictionary field value components incrementally.

RefItemSerializer

Serializes Item field value components incrementally.

RefListSerializer

Serializes List field value components incrementally.

Enums

BareItem

BareItem type is used to construct Items or Parameters values.

ListEntry

Represents a member of List or Dictionary structured field value.

RefBareItem

Similar to BareItem, but used to serialize values via RefItemSerializer, RefListSerializer, RefDictSerializer.

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.