Crate sfv

Expand description

sfv is an implementation of Structured Field Values for HTTP, as specified in RFC 9651 for parsing and serializing 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 – an Integer, Decimal, String, Token, Byte Sequence, Boolean, Date, or Display String. It can have associated Parameters.
List – an array of zero or more members, each of which can be an Item or an InnerList, both of which can have Parameters.
Dictionary – an 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 have associated parameters. There can be zero or more members, and their names are unique in the scope of the Dictionary they occur within.

There are also a few lower-level types used to construct structured field values:

BareItem is 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 associated Parameters.
ListEntry represents either Item or InnerList as a member of List or as member-value in Dictionary.

§Examples

§Parsing

// Parsing a structured field value of Item type.
let input = "12.445;foo=bar";
let item: Item = Parser::new(input).parse()?;
println!("{:#?}", item);

// Parsing a structured field value of List type.
let input = r#"1;a=tok, ("foo" "bar");baz, ()"#;
let list: List = Parser::new(input).parse()?;
println!("{:#?}", list);

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

§Getting Parsed Value Members

let input = "u=2, n=(* foo 2)";
let dict: Dictionary = Parser::new(input).parse()?;

match dict.get("u") {
    Some(ListEntry::Item(item)) => match &item.bare_item {
        BareItem::Token(val) => { /* ... */ }
        BareItem::Integer(val) => { /* ... */ }
        BareItem::Boolean(val) => { /* ... */ }
        BareItem::Decimal(val) => { /* ... */ }
        BareItem::String(val) => { /* ... */ }
        BareItem::ByteSequence(val) => { /* ... */ }
        BareItem::Date(val) => { /* ... */ }
        BareItem::DisplayString(val) => { /* ... */ }
    },
    Some(ListEntry::InnerList(inner_list)) => { /* ... */ }
    None => { /* ... */ }
}

§Serialization

Serializes an Item:

use sfv::{Decimal, ItemSerializer, KeyRef, StringRef};

let serialized_item = ItemSerializer::new()
    .bare_item(StringRef::from_str("foo")?)
    .parameter(KeyRef::from_str("key")?, Decimal::try_from(13.45655)?)
    .finish();

assert_eq!(serialized_item, r#""foo";key=13.457"#);

Serializes a List:

use sfv::{KeyRef, ListSerializer, StringRef, TokenRef};

let mut ser = ListSerializer::new();

ser.bare_item(TokenRef::from_str("tok")?);

{
    let mut ser = ser.inner_list();

    ser.bare_item(99).parameter(KeyRef::from_str("key")?, false);

    ser.bare_item(StringRef::from_str("foo")?);

    ser.finish().parameter(KeyRef::from_str("bar")?, true);
}

assert_eq!(
    ser.finish().as_deref(),
    Some(r#"tok, (99;key=?0 "foo");bar"#),
);

Serializes a Dictionary:

use sfv::{DictSerializer, KeyRef, StringRef};

let mut ser = DictSerializer::new();

ser.bare_item(KeyRef::from_str("key1")?, StringRef::from_str("apple")?);

ser.bare_item(KeyRef::from_str("key2")?, true);

ser.bare_item(KeyRef::from_str("key3")?, false);

assert_eq!(
    ser.finish().as_deref(),
    Some(r#"key1="apple", key2, key3=?0"#),
);

§Crate features

parsed-types (enabled by default) – When enabled, exposes fully owned types Item, Dictionary, List, and their components, which can be obtained from Parser::parse_item, etc. These types are implemented using the indexmap crate, so disabling this feature can avoid that dependency if parsing using a visitor (Parser::parse_item_with_visitor, etc.) is sufficient.
arbitrary – Implements the Arbitrary trait for this crate’s types, making them easier to use with fuzzing.

Modules§

visitor: Contains traits for parsing structured-field values incrementally.

Structs§

Date: A structured field value date.
Decimal: A structured field value decimal.
DictSerializer: Serializes Dictionary field value components incrementally.
Error: An error that can occur in this crate.
InnerList: An array of Items with associated Parameters.
InnerListSerializer: Serializes inner lists incrementally.
Integer: A structured field value integer.
Item: An item-type structured field value.
ItemSerializer: Serializes Item field value components incrementally.
Key: An owned structured field value key.
KeyRef: A borrowed structured field value key.
ListSerializer: Serializes List field value components incrementally.
ParameterSerializer: Serializes parameters incrementally.
Parser: Exposes methods for parsing input into a structured field value.
String: An owned structured field value string.
StringRef: A borrowed structured field value string.
Token: An owned structured field value token.
TokenRef: A borrowed structured field value token.

Enums§

GenericBareItem: An abstraction over multiple kinds of ownership of a bare item.
ListEntry: A member of a List or Dictionary.
Version: A version for serialized structured field values.

Traits§

FieldType: A structured-field type, supporting parsing and serialization.

Functions§

integer: Creates an Integer, panicking if the value is out of range.
key_ref: Creates a &KeyRef, panicking if the value is invalid.
string_ref: Creates a &StringRef, panicking if the value is invalid.
token_ref: Creates a &TokenRef, panicking if the value is invalid.

Type Aliases§

BareItem: A bare item that owns its data.
BareItemFromInput: A bare item that borrows data from input when possible.
Dictionary: A dictionary-type structured field value.
List: A list-type structured field value.
Parameters: Parameters of an Item or InnerList.
RefBareItem: A bare item that borrows its data.

Crate sfvCopy item path