sfv

package module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 25, 2023 License: MIT Imports: 10 Imported by: 0

README

go-sfv

Go Reference Test

Go implementation for RFC 8941 Structured Field Values for HTTP (SFV). It also supports Dates and Display Strings defined by draft-ietf-httpbis-sfbis-03.

Synopsis

Decoding Structured Field Values
h := make(http.Header)
// Decoding Items
item, err := sfv.DecodeItem(h.Values("Example-Hdr"))
switch val := item.Value.(type) {
case int64:             // Integers
case float64:           // Decimals
case string:            // Strings
case sfv.Token:         // Tokens
case bool:              // Booleans
case time.Time:         // Dates
case sfv.DisplayString: // Display Strings
}

// Decoding Lists
list, err := sfv.DecodeList(h.Values("Example-Hdr"))

// Decoding Dictionaries
dict, err := sfv.DecodeDictionary(h.Values("Example-Hdr"))
Encoding Structured Field Values
// Encoding Items
val, err := sfv.EncodeItem(item)

// Encoding Lists
val, err := sfv.EncodeList(list)

// Encoding Dictionaries
val, err := sfv.EncodeDictionary(dict)

Supported Data Types

SFV types are mapped to Go types as described in this section. Note that only Lists(sfv.List), Dictionaries(sfv.Dictionary), and Items (sfv.Item) can be in a top-level.

Values of Items

The sfv.Value is defined as the following:

type Value interface{}

The actual type might be one of them:

Type of SFV Example of SFV Type in Go Example in Go
Integer 10 int64 int64(10)
Decimal 3.14 float64 float64(3.14)
String "hello" string "hello"
Token x sfv.Token sfv.Token("x")
Byte Seq :AQID: []byte []byte{1, 2, 3}
Boolean ?1 bool true
Date @1659578233 time.Time time.Unix(1659578233, 0)
DisplayString %"f%c3%bc%c3%bc" sfv.DisplayString sfv.DisplayString("füü")
Inner List (1 2) sfv.InnerList sfv.InnerList{}
Parameters of Items

Parameters are ordered map of key-value pairs, however Go's map types are unordered. So sfv.Parameters is defined by a slice of sfv.Parameter that is a key-value pair.

type Parameter struct {
	Key   string
	Value Value
}

type Parameters []Parameter
Lists

Lists are decoded to sfv.List.

type List []Item
Inner Lists

Inner Lists are decoded to sfv.InnerList.

type InnerList []Item

Note that sfv.InnerList can't contain sfv.InnerList itself.

// Encoding this will fail.
innerList := sfv.InnerList{
    {
        Value: sfv.InnerList{},
    },
}
Dictionaries

Dictionaries are ordered maps of key-value pairs, however Go's map types are unordered. So sfv.Dictionary is defined by a slice of sfv.DictMember that is a key-value pair.

type DictMember struct {
	Key  string
	Item Item
}

type Dictionary []DictMember

References

Documentation

Overview

Package sfv provides a parser and a serializer for Structured Field Values (SFV).

Index

Examples

Constants

View Source
const (
	// The range of Integers
	MaxInteger = 999_999_999_999_999
	MinInteger = -999_999_999_999_999

	// The range of Decimals
	MaxDecimal = 0x1.d1a94a1fffffbp+39  // = 999999999999.9993896484375
	MinDecimal = -0x1.d1a94a1fffffbp+39 // = -999999999999.9993896484375
)

Variables

This section is empty.

Functions

func EncodeDictionary

func EncodeDictionary(dict Dictionary) (string, error)

EncodeDictionary encodes the given dictionary to Structured Field Values.

Example
dict := sfv.Dictionary{
	{
		Key: "foo",
		Item: sfv.Item{
			Value: int64(1),
		},
	},
	{
		Key: "bar",
		Item: sfv.Item{
			Value: int64(2),
		},
	},
}

val, err := sfv.EncodeDictionary(dict)
if err != nil {
	panic(err)
}
fmt.Println(val)
Output:

foo=1, bar=2

func EncodeItem

func EncodeItem(item Item) (string, error)

EncodeItem encodes the given item to Structured Field Values.

Example
item := sfv.Item{
	Value: int64(2),
	Parameters: sfv.Parameters{
		{
			Key:   "foourl",
			Value: "https://foo.example.com/",
		},
	},
}
val, err := sfv.EncodeItem(item)
if err != nil {
	panic(err)
}
fmt.Println(val)
Output:

2;foourl="https://foo.example.com/"

func EncodeList

func EncodeList(list List) (string, error)

EncodeList encodes the given list to Structured Field Values.

Example
list := sfv.List{
	{
		Value: sfv.Token("foo"),
	},
	{
		Value: sfv.Token("bar"),
	},
}
val, err := sfv.EncodeList(list)
if err != nil {
	panic(err)
}
fmt.Println(val)
Output:

foo, bar

func IsValidString

func IsValidString(s string) bool

IsValidString returns whether the s has valid form.

Types

type DictMember

type DictMember struct {
	Key  string
	Item Item
}

DictMember is a key-value pair of Dictionary.

type Dictionary

type Dictionary []DictMember

Dictionary is an ordered map of key-value pairs defined in RFC 8941 Section 3.2. Dictionaries.

func DecodeDictionary

func DecodeDictionary(fields []string) (Dictionary, error)

DecodeDictionary decodes fields as Structured Field Values, and returns the result as a Dictionary.

Example
h := make(http.Header)
h.Add("Example-Hdr", "foo=1")
h.Add("Example-Hdr", "bar=2")

dict, err := sfv.DecodeDictionary(h.Values("Example-Hdr"))
if err != nil {
	panic(err)
}

for _, member := range dict {
	fmt.Println(member.Key, member.Item.Value)
}
Output:

foo 1
bar 2

func (Dictionary) Get

func (dict Dictionary) Get(key string) Item

Get returns the last item associated with the given key. If there are no items associated with the key, Get returns the zero value of Item.

Example
dict := sfv.Dictionary{
	{
		Key: "foo",
		Item: sfv.Item{
			Value: int64(1),
		},
	},
	{
		Key: "bar",
		Item: sfv.Item{
			Value: int64(2),
		},
	},
}

fmt.Println(dict.Get("foo").Value)
fmt.Println(dict.Get("bar").Value)
fmt.Println(dict.Get("baz").Value)
Output:

1
2
<nil>

func (Dictionary) Len

func (dict Dictionary) Len() int

Len returns the number of items in the dict.

Example
dict := sfv.Dictionary{
	{
		Key: "foo",
		Item: sfv.Item{
			Value: int64(1),
		},
	},
	{
		Key: "bar",
		Item: sfv.Item{
			Value: int64(2),
		},
	},
}

fmt.Println(dict.Len())
Output:

2

type DisplayString added in v0.3.0

type DisplayString string

DisplayString is a unicode string.

type InnerList

type InnerList []Item

InnerList is an array defined in RFC 8941 Section 3.1.1. Inner Lists.

type Item

type Item struct {
	Value      Value
	Parameters Parameters
}

Item is an item defined RFC 8941 Section 3.3. Items.

func DecodeItem

func DecodeItem(fields []string) (Item, error)

DecodeList decodes fields as Structured Field Values, and returns the result as an Item.

Example
item, err := sfv.DecodeItem([]string{`2; foourl="https://foo.example.com/"`})
if err != nil {
	panic(err)
}
fmt.Println(item.Value)
fmt.Println(item.Parameters.Get("foourl"))
Output:

2
https://foo.example.com/

type List

type List []Item

List is an array defined in RFC 8941 Section 3.1. Lists.

func DecodeList

func DecodeList(fields []string) (List, error)

DecodeList decodes fields as Structured Field Values, and returns the result as a List.

Example
h := make(http.Header)
h.Add("Example-Hdr", "foo")
h.Add("Example-Hdr", "bar")

list, err := sfv.DecodeList(h.Values("Example-Hdr"))
if err != nil {
	panic(err)
}

for _, item := range list {
	fmt.Println(item.Value)
}
Output:

foo
bar

type Parameter

type Parameter struct {
	// Key must match the following regular expression:
	//
	//     [a-z*][a-z0-9_.*-]
	Key string

	// Value is a bare item.
	Value Value
}

Parameter is a key-value pair of Parameters.

type Parameters

type Parameters []Parameter

Parameters are an ordered map of key-value pairs defined in RFC 8941 Section 3.1.2. Parameters.

func (Parameters) Get

func (param Parameters) Get(key string) Value

Get returns the last value associated with the given key. If there are no values associated with the key, Get returns Value(nil).

Example
params := sfv.Parameters{
	{
		Key:   "foo",
		Value: "bar",
	},
	{
		Key:   "baz",
		Value: "qux",
	},
}

fmt.Println(params.Get("foo"))
fmt.Println(params.Get("baz"))
fmt.Println(params.Get("quux"))
Output:

bar
qux
<nil>

func (Parameters) Len

func (param Parameters) Len() int

Len returns the number of items in the param.

Example
params := sfv.Parameters{
	{
		Key:   "foo",
		Value: "bar",
	},
	{
		Key:   "baz",
		Value: "qux",
	},
}

fmt.Println(params.Len())
Output:

2

type Token

type Token string

Token is a token defined in RFC 8941 Section 3.3.4. Tokens. The token must match the following regular expression:

[a-zA-Z*][a-zA-Z0-9:/!#$%&'*+_.^_`|~-]*

func (Token) Valid

func (t Token) Valid() bool

Valid returns whether the t has valid form.

type Value

type Value interface{}

Value is a bare item. It might be Integers, Decimals, Strings, Tokens, Byte Sequences, Booleans or Inner Lists. It's type is one of these:

int64 for Integers
float64 for Decimals
string for Strings
Token for Tokens
[]byte for Byte Sequences
bool for Booleans
time.Time for Date
DisplayString for Display Strings
InnerList for Inner Lists

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL