go-vcard – github.com/emersion/go-vcard Index | Examples | Files

package vcard

import "github.com/emersion/go-vcard"

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

Index

Examples

Constants 

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

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

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. 

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"
	         = "LOGO"
	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. 

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.

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) SetAddress 

func (c Card) SetAddress(address *Address)

SetAddress replaces the list of addresses with the single specified address.

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) SetName 

func (c Card) SetName(name *Name)

SetName replaces the list of names with the single specified name.

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

Code: 

{
	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))
	}
}

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

Code: 

{
	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 = make(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)
		}
	}
}

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"
)

Source Files

card.go decoder.go encoder.go v4.go

Version
v0.0.0-20241024213814-c9703dde27ff (latest)
Published
Oct 24, 2024
Platform
linux/amd64
Imports
7 packages
Last checked
2 months ago –

Tools for package owners.