vdir

README

vdir

Go Package vdir implements RFC 2425 directory encoding with support for vCard and iCalendar profiles.

The directory blocks can be mapped to an arbitrary Go Value which is described in the Marshal and Unmarshal functions. In addition, the package provides conversions to/from a generalized Object representation which allows for detailed access and easier modification.

Install

go get "github.com/xconstruct/vdir"

Example

vcf := []byte("BEGIN:VCARD ...")

var c vdir.Card
err := vdir.Unmarshal(vcf, &c)
fmt.Println(c.FormattedName)
fmt.Println(c.Addresses[0].Street)

Documentation

Overview

Package vdir implements RFC 2425 directory encoding with support for vCard and iCalendar profiles.

The directory blocks can be mapped to an arbitrary Go Value which is described in the Marshal and Unmarshal functions. In addition, the package provides conversions to/from a generalized Object representation which allows for detailed access and easier modification.

Index

• Variables
• func FromObject(v interface{}, o *Object) error
• func Marshal(v interface{}) ([]byte, error)
• func ToObject(v interface{}, o *Object) error
• func Unmarshal(data []byte, v interface{}) error
• type Address
• type Alarm
• type Calendar
• type Card
• type ContentLine
• type DateTimeValue
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (dec *Decoder) Decode(v interface{}) error
  • func (dec *Decoder) ReadContentLine() (*ContentLine, error)
  • func (dec *Decoder) ReadObject() (o *Object, err error)
• type Encoder
  • func NewEncoder(w io.Writer) *Encoder
  • func (enc *Encoder) Encode(v interface{}) error
  • func (enc *Encoder) WriteContentLine(cl *ContentLine) error
  • func (enc *Encoder) WriteObject(o *Object) error
• type Event
• type FreeBusy
• type IMPP
• type Journal
• type Name
• type Object
  • func (o *Object) PropertyMap() map[string][]*ContentLine
• type Person
• type Photo
• type RecurrenceRule
• type StructuredValue
  • func (v StructuredValue) GetText() string
• type TimeZoneInfo
• type Timezone
• type Todo
• type TypedValue
• type Value
  • func (v Value) GetText() string

Variables

var (
	ErrEmpty = errors.New("Empty")
)

Functions

func FromObject

func FromObject(v interface{}, o *Object) error

FromObject converts an intermediate Object into a struct.

See the documentation for Unmarshal for details about the conversion of into a Go Value.

func Marshal

func Marshal(v interface{}) ([]byte, error)

Marshal returns the encoding of v.

Marshal expects a struct as value v and traverses it recursively, mapping its fields to properties and component objects.

Each struct field becomes a property of the object unless the fields tag is "-" or the field is empty. The tag value is the property name, otherwise the uppercase struct field name is used.

A special field tagged with ",profile" defines the profile type of the block, for example a tag "vcard,profile" designates the struct to be of type VCARD.

Fields of type string are mapped to single values, string slices to a comma-delimited value list.

Fields that contain a struct are stored as a structured property with optional parameters and components. If a struct fields tag contains a "param" option as second value, it is stored as a parameter of the property. Untagged fields are stored as semicolon-delimited component values based on their order of appearance in the struct.

Fields that have a tag with option "objects" as second value are converted to a new inner BEGIN:PROFILE-END object block.

func ToObject

func ToObject(v interface{}, o *Object) error

ToObject converts a struct v into an intermediate Object that can be written by an encoder.

See the documentation for Marshal for details about the conversion of a Go Value.

func Unmarshal

func Unmarshal(data []byte, v interface{}) error

Unmarshal parses a single directory block from data and stores the result in the value pointed to by v.

To unmarshal an object into a struct, Unmarshal matches incoming object properties and components to the keys used by Marshal (either the struct field name or its tag), accepting a case-insensitive match.

A property content line can be unmarshalled into a string for a single value, a string slice for a value list (delimited by commas) or a struct for structured values. Umarshalling into a struct first maps all struct fields with tag ",param" to the respective parameter values and fills the remaining fields in their index order with the respective semicolon-delimited value components.

Types

type Address

type Address struct {
	Type            []string `vdir:",param"`
	Label           string   `vdir:",param"`
	PostOfficeBox   string
	ExtendedAddress string
	Street          string
	Locality        string
	Region          string
	PostalCode      string
	CountryName     string
}

type Alarm

type Alarm struct {
	Profile     string `vdir:"valarm,profile"`
	Trigger     string
	Action      string
	Description string
	Repeat      string
	Duration    string
}

type Calendar

type Calendar struct {
	Profile  string `vdir:"vcalendar,profile"`
	Version  string
	ProdId   string
	Timezone []Timezone `vdir:"vtimezone,object"`
	Events   []Event    `vdir:"vevent,object"`
	ToDos    []Todo     `vdir:"vtodo,object"`
	Journals []Journal  `vdir:"vjournal,object"`
	FreeBusy []FreeBusy `vdir:"vfreebusy,object"`
}

Calendar is a iCalendar as defined in RFC 5545.

type Card

type Card struct {
	Profile       string `vdir:"vcard,profile"`
	Version       string
	FormattedName string `vdir:"fn"`
	Name          Name   `vdir:"n"`
	NickName      []string
	Birthday      string       `vdir:"bday"`
	Addresses     []Address    `vdir:"adr"`
	Telephones    []TypedValue `vdir:"tel"`
	Email         []TypedValue
	Url           []TypedValue
	Title         string
	Role          string
	Org           string
	Categories    []string
	Note          string
	URL           string
	Photo         Photo

	Rev    string
	ProdId string
	Uid    string

	XICQ   string `vdir:"x-icq"`
	XSkype string `vdir:"x-skype"`
	IMPP   []IMPP
}

Card is a vCard as defined in RFC 6350.

type ContentLine

type ContentLine struct {
	Group, Name string
	Params      map[string]Value
	Value       StructuredValue
}

ContentLine is a single named line with named parameters and values.

type DateTimeValue

type DateTimeValue struct {
	TZId  string `vdir:",param"`
	Type  string `vdir:"value,param"`
	Value string
}

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

A Decoder reads Directory Information Blocks from an input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

func (*Decoder) Decode

func (dec *Decoder) Decode(v interface{}) error

Decode reads the next object and stores it in the value pointed to by v.

See the documentation for Unmarshal for details about the conversion into a Go value.

func (*Decoder) ReadContentLine

func (dec *Decoder) ReadContentLine() (*ContentLine, error)

ReadContentLine reads the next content line and returns it.

func (*Decoder) ReadObject

func (dec *Decoder) ReadObject() (o *Object, err error)

ReadObject reads the next object block and returns it.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

An encoder writes Directory Information Blocks to an input stream.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) Encode

func (enc *Encoder) Encode(v interface{}) error

Encode writes the encoded block of v to the stream.

See the documentation for Marshal for details about the conversion of Go values.

func (*Encoder) WriteContentLine

func (enc *Encoder) WriteContentLine(cl *ContentLine) error

WriteContentLine writes a single content line to the stream.

func (*Encoder) WriteObject

func (enc *Encoder) WriteObject(o *Object) error

WriteObject writes an object to the stream.

type Event

type Event struct {
	Profile      string `vdir:"vevent,profile"`
	UID          string
	DTStamp      DateTimeValue
	Organizer    Person
	DTStart      DateTimeValue
	DTEnd        DateTimeValue
	Location     string
	Summary      string
	Categories   []string
	Description  string
	Method       string
	Status       string
	Class        string
	Sequence     string
	Created      string
	LastModified string  `vdir:"last-modified"`
	Alarms       []Alarm `vdir:",object"`
	RRule        RecurrenceRule
}

type FreeBusy

type FreeBusy struct {
	Profile   string `vdir:"vfreebusy,profile"`
	Organizer Person
	DTStart   DateTimeValue
	DTEnd     DateTimeValue
	FreeBusy  []string `vdir:",multiple"`
	Url       string
}

type IMPP

type IMPP struct {
	Type         []string `vdir:",param"`
	XServiceType string   `vdir:"x-service-type,param"`
	Value        string
}

type Journal

type Journal struct {
	Profile     string `vdir:"vjournal,profile"`
	DTStamp     DateTimeValue
	UID         string
	Organizer   Person
	Status      string
	Class       string
	Categories  []string
	Description string
}

type Name

type Name struct {
	FamilyName      []string
	GivenName       []string
	AdditionalNames []string
	HonorificNames  []string
	// contains filtered or unexported fields
}

type Object

type Object struct {
	Profile    string
	Properties []*ContentLine
	Objects    []*Object
}

Object is a generic Directory Information Block.

func (*Object) PropertyMap

func (o *Object) PropertyMap() map[string][]*ContentLine

PropertyMap returns all properties indexed by their name.

type Person

type Person struct {
	CommonName string `vdir:"cn"`
	Url        string
}

type Photo

type Photo struct {
	Encoding  string `vdir:",param"`
	MediaType string `vdir:",param"`
	Type      string `vdir:",param"`
	Value     string `vdir:",param"`
	Data      string
}

type RecurrenceRule

type RecurrenceRule struct {
	Rule1 string
	Rule2 string
	Rule3 string
	Rule4 string
	Rule5 string
}

type StructuredValue

type StructuredValue []Value

func (StructuredValue) GetText

func (v StructuredValue) GetText() string

GetText returns the first value of the first component.

type TimeZoneInfo

type TimeZoneInfo struct {
	TZOffsetFrom string
	TZOffsetTo   string
	TZName       string
	DTStart      string
	RRule        RecurrenceRule
}

type Timezone

type Timezone struct {
	Profile  string `vdir:"vtimezone,profile"`
	TZId     string
	Daylight []TimeZoneInfo `vdir:",object"`
	Standard []TimeZoneInfo `vdir:",object"`
}

type Todo

type Todo struct {
	Profile  string `vdir:"vtodo,profile"`
	DTStamp  DateTimeValue
	Sequence string
	UID      string
	Due      string
	Status   string
	Summary  string
	Alarms   []Alarm `vdir:",object"`
}

type TypedValue

type TypedValue struct {
	Type  []string `vdir:",param"`
	Value string
}

type Value

type Value []string

func (Value) GetText

func (v Value) GetText() string

GetText returns the first value.