vcard

package module
Version: v0.0.0-...-3445b91 Latest Latest
Warning

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

Go to latest
Published: May 21, 2021 License: MIT Imports: 7 Imported by: 13

README

go-vcard

godocs.io builds.sr.ht status

A Go library to parse and format vCard.

Usage

f, err := os.Open("cards.vcf")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

dec := vcard.NewDecoder(f)
for {
	card, err := dec.Decode()
	if err == io.EOF {
		break
	} else if err != nil {
		log.Fatal(err)
	}

	log.Println(card.PreferredValue(vcard.FieldFormattedName))
}

License

MIT

Documentation

Overview

Package vcard implements the vCard format, defined in RFC 6350.

Index

Examples

Constants

View Source
const (
	MIMEType  = "text/vcard"
	Extension = "vcf"
)

MIME type and file extension for VCard, defined in RFC 6350 section 10.1.

View Source
const (
	ParamLanguage      = "LANGUAGE"
	ParamValue         = "VALUE"
	ParamPreferred     = "PREF"
	ParamAltID         = "ALTID"
	ParamPID           = "PID"
	ParamType          = "TYPE"
	ParamMediaType     = "MEDIATYPE"
	ParamCalendarScale = "CALSCALE"
	ParamSortAs        = "SORT-AS"
	ParamGeolocation   = "GEO"
	ParamTimezone      = "TZ"
)

Card property parameters.

View Source
const (
	// General Properties
	FieldSource = "SOURCE"
	FieldKind   = "KIND"
	FieldXML    = "XML"

	// Identification Properties
	FieldFormattedName = "FN"
	FieldName          = "N"
	FieldNickname      = "NICKNAME"
	FieldPhoto         = "PHOTO"
	FieldBirthday      = "BDAY"
	FieldAnniversary   = "ANNIVERSARY"
	FieldGender        = "GENDER"

	// Delivery Addressing Properties
	FieldAddress = "ADR"

	// Communications Properties
	FieldTelephone = "TEL"
	FieldEmail     = "EMAIL"
	FieldIMPP      = "IMPP" // Instant Messaging and Presence Protocol
	FieldLanguage  = "LANG"

	// Geographical Properties
	FieldTimezone    = "TZ"
	FieldGeolocation = "GEO"

	// Organizational Properties
	FieldTitle        = "TITLE"
	FieldRole         = "ROLE"
	FieldOrganization = "ORG"
	FieldMember       = "MEMBER"
	FieldRelated      = "RELATED"

	// Explanatory Properties
	FieldCategories   = "CATEGORIES"
	FieldNote         = "NOTE"
	FieldProductID    = "PRODID"
	FieldRevision     = "REV"
	FieldSound        = "SOUND"
	FieldUID          = "UID"
	FieldClientPIDMap = "CLIENTPIDMAP"
	FieldURL          = "URL"
	FieldVersion      = "VERSION"

	// Security Properties
	FieldKey = "KEY"

	// Calendar Properties
	FieldFreeOrBusyURL      = "FBURL"
	FieldCalendarAddressURI = "CALADRURI"
	FieldCalendarURI        = "CALURI"
)

Card properties.

View Source
const (
	// Generic
	TypeHome = "home"
	TypeWork = "work"

	// For FieldTelephone
	TypeText      = "text"
	TypeVoice     = "voice" // Default
	TypeFax       = "fax"
	TypeCell      = "cell"
	TypeVideo     = "video"
	TypePager     = "pager"
	TypeTextPhone = "textphone"

	// For FieldRelated
	TypeContact      = "contact"
	TypeAcquaintance = "acquaintance"
	TypeFriend       = "friend"
	TypeMet          = "met"
	TypeCoWorker     = "co-worker"
	TypeColleague    = "colleague"
	TypeCoResident   = "co-resident"
	TypeNeighbor     = "neighbor"
	TypeChild        = "child"
	TypeParent       = "parent"
	TypeSibling      = "sibling"
	TypeSpouse       = "spouse"
	TypeKin          = "kin"
	TypeMuse         = "muse"
	TypeCrush        = "crush"
	TypeDate         = "date"
	TypeSweetheart   = "sweetheart"
	TypeMe           = "me"
	TypeAgent        = "agent"
	TypeEmergency    = "emergency"
)

Values for ParamType.

Variables

This section is empty.

Functions

func ToV4

func ToV4(card Card)

ToV4 converts a card to vCard version 4.

Types

type Address

type Address struct {
	*Field

	PostOfficeBox   string
	ExtendedAddress string // e.g., apartment or suite number
	StreetAddress   string
	Locality        string // e.g., city
	Region          string // e.g., state or province
	PostalCode      string
	Country         string
}

An Address is a delivery address.

type Card

type Card map[string][]*Field

A Card is an address book entry.

func (Card) Add

func (c Card) Add(k string, f *Field)

Add adds the k, f pair to the list of fields. It appends to any existing fields.

func (Card) AddAddress

func (c Card) AddAddress(address *Address)

AddAddress adds an address to the list of addresses.

func (Card) AddName

func (c Card) AddName(name *Name)

AddName adds the specified name to the list of names.

func (Card) AddValue

func (c Card) AddValue(k, v string)

AddValue adds the k, v pair to the list of field values. It appends to any existing values.

func (Card) Address

func (c Card) Address() *Address

Address returns the preferred address of the card. If it isn't specified, it returns nil.

func (Card) Addresses

func (c Card) Addresses() []*Address

Addresses returns addresses of the card.

func (Card) Categories

func (c Card) Categories() []string

Categories returns category information about the card, also known as "tags".

func (Card) FormattedNames

func (c Card) FormattedNames() []*Field

FormattedNames returns formatted names of the card. The length of the result is always greater or equal to 1.

func (Card) Gender

func (c Card) Gender() (sex Sex, identity string)

Gender returns this card's gender.

func (Card) Get

func (c Card) Get(k string) *Field

Get returns the first field of the card for the given property. If there is no such field, it returns nil.

func (Card) Kind

func (c Card) Kind() Kind

Kind returns the kind of the object represented by this card. If it isn't specified, it returns the default: KindIndividual.

func (Card) Name

func (c Card) Name() *Name

Name returns the preferred name of the card. If it isn't specified, it returns nil.

func (Card) Names

func (c Card) Names() []*Name

Names returns names of the card.

func (Card) Preferred

func (c Card) Preferred(k string) *Field

Preferred returns the preferred field of the card for the given property.

func (Card) PreferredValue

func (c Card) PreferredValue(k string) string

PreferredValue returns the preferred field value of the card.

func (Card) Revision

func (c Card) Revision() (time.Time, error)

Revision returns revision information about the current card.

func (Card) Set

func (c Card) Set(k string, f *Field)

Set sets the key k to the single field f. It replaces any existing field.

func (Card) SetCategories

func (c Card) SetCategories(categories []string)

SetCategories sets category information about the card.

func (Card) SetGender

func (c Card) SetGender(sex Sex, identity string)

SetGender sets this card's gender.

func (Card) SetKind

func (c Card) SetKind(kind Kind)

SetKind sets the kind of the object represented by this card.

func (Card) SetRevision

func (c Card) SetRevision(t time.Time)

SetRevision sets revision information about the current card.

func (Card) SetValue

func (c Card) SetValue(k, v string)

SetValue sets the field k to the single value v. It replaces any existing value.

func (Card) Value

func (c Card) Value(k string) string

Value returns the first field value of the card for the given property. If there is no such field, it returns an empty string.

func (Card) Values

func (c Card) Values(k string) []string

Values returns a list of values for a given property.

type Decoder

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

A Decoder parses cards.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder creates a new Decoder reading cards from an io.Reader.

Example
f, err := os.Open("cards.vcf")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

dec := vcard.NewDecoder(f)
for {
	card, err := dec.Decode()
	if err == io.EOF {
		break
	} else if err != nil {
		log.Fatal(err)
	}

	log.Println(card.PreferredValue(vcard.FieldFormattedName))
}
Output:

func (*Decoder) Decode

func (dec *Decoder) Decode() (Card, error)

Decode parses a single card.

type Encoder

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

An Encoder formats cards.

func NewEncoder

func NewEncoder(w io.Writer) *Encoder

NewEncoder creates a new Encoder that writes cards to w.

Example
destFile, err := os.Create("cards.vcf")
if err != nil {
	log.Fatal(err)
}
defer destFile.Close()

// data in order: first name, middle name, last name, telephone number
contacts := [][4]string{
	{"John", "Webber", "Maxwell", "(+1) 199 8714"},
	{"Donald", "", "Ron", "(+44) 421 8913"},
	{"Eric", "E.", "Peter", "(+37) 221 9903"},
	{"Nelson", "D.", "Patrick", "(+1) 122 8810"},
}

var (
	// card is a map of strings to []*vcard.Field objects
	card vcard.Card

	// destination where the vcard will be encoded to
	enc = vcard.NewEncoder(destFile)
)

for _, entry := range contacts {
	// set only the value of a field by using card.SetValue.
	// This does not set parameters
	card.SetValue(vcard.FieldFormattedName, strings.Join(entry[:3], " "))
	card.SetValue(vcard.FieldTelephone, entry[3])

	// set the value of a field and other parameters by using card.Set
	card.Set(vcard.FieldName, &vcard.Field{
		Value: strings.Join(entry[:3], ";"),
		Params: map[string][]string{
			vcard.ParamSortAs: []string{
				entry[0] + " " + entry[2],
			},
		},
	})

	// make the vCard version 4 compliant
	vcard.ToV4(card)
	err := enc.Encode(card)
	if err != nil {
		log.Fatal(err)
	}
}
Output:

func (*Encoder) Encode

func (enc *Encoder) Encode(c Card) error

Encode formats a card. The card must have a FieldVersion field.

type Field

type Field struct {
	Value  string
	Params Params
	Group  string
}

A field contains a value and some parameters.

type Kind

type Kind string

Kind is an object's kind.

const (
	KindIndividual   Kind = "individual"
	KindGroup        Kind = "group"
	KindOrganization Kind = "org"
	KindLocation     Kind = "location"
)

Values for FieldKind.

type Name

type Name struct {
	*Field

	FamilyName      string
	GivenName       string
	AdditionalName  string
	HonorificPrefix string
	HonorificSuffix string
}

Name contains an object's name components.

type Params

type Params map[string][]string

Params is a set of field parameters.

func (Params) Add

func (p Params) Add(k, v string)

Add adds the k, v pair to the list of parameters. It appends to any existing values.

func (Params) Get

func (p Params) Get(k string) string

Get returns the first value with the key k. It returns an empty string if there is no such value.

func (Params) HasType

func (p Params) HasType(t string) bool

HasType returns true if and only if the field have the provided type.

func (Params) Set

func (p Params) Set(k, v string)

Set sets the parameter k to the single value v. It replaces any existing value.

func (Params) Types

func (p Params) Types() []string

Types returns the field types.

type Sex

type Sex string

Sex is an object's biological sex.

const (
	SexUnspecified Sex = ""
	SexFemale      Sex = "F"
	SexMale        Sex = "M"
	SexOther       Sex = "O"
	SexNone        Sex = "N"
	SexUnknown     Sex = "U"
)

Jump to

Keyboard shortcuts

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