code.pfad.fr/gopim/vcard ↑

vcard package

import "code.pfad.fr/gopim/vcard"

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

For usage examples refer to New to create a vCard and NewDecoder to read a vCard.

License and credits

Code is available under the MIT license.

Large inspiration has been taken from the emersion/go-vcard package (available under MIT).

Index

Examples

Constants

❖ 
const (
	MIMETypeWithoutCharset = "text/vcard"
	MIMEType               = MIMETypeWithoutCharset + ";charset=UTF-8"
	Extension              = "vcf"
)

MIME type and file extension for vCard rfc6350#section-10.1

❖ 
const (
	// General Properties
	Property_Source = "SOURCE"
	Property_Kind   = "KIND"
	Property_XML    = "XML"

	// Identification Properties
	Property_FormattedName = "FN"
	Property_Name          = "N"
	Property_Nickname      = "NICKNAME"
	Property_Photo         = "PHOTO"
	Property_Birthday      = "BDAY"
	Property_Anniversary   = "ANNIVERSARY"
	Property_Gender        = "GENDER"

	// Delivery Addressing Properties
	Property_Address = "ADR"

	// Communications Properties
	Property_Telephone = "TEL"
	Property_Email     = "EMAIL"
	Property_IMPP      = "IMPP" // Instant Messaging and Presence Protocol
	Property_Language  = "LANG"

	// Geographical Properties
	Property_Timezone    = "TZ"
	Property_Geolocation = "GEO"

	// Organizational Properties
	Property_Title        = "TITLE"
	Property_Role         = "ROLE"
	         = "LOGO"
	Property_Organization = "ORG"
	Property_Member       = "MEMBER"
	Property_Related      = "RELATED"

	// Explanatory Properties
	Property_Categories   = "CATEGORIES"
	Property_Note         = "NOTE"
	Property_ProductID    = "PRODID"
	Property_Revision     = "REV"
	Property_Sound        = "SOUND"
	Property_UID          = "UID"
	Property_ClientPIDMap = "CLIENTPIDMAP"
	Property_URL          = "URL"

	// Security Properties
	Property_Key = "KEY"

	// Calendar Properties
	Property_FreeOrBusyURL      = "FBURL"
	Property_CalendarAddressURI = "CALADRURI"
	Property_CalendarURI        = "CALURI"
)

Card property names.

❖ 
const (
	Parameter_Language      = "LANGUAGE"
	Parameter_Value         = "VALUE"
	Parameter_Preference    = "PREF"
	Parameter_AltID         = "ALTID"
	Parameter_PID           = "PID"
	Parameter_Type          = "TYPE" // see [ParameterType]
	Parameter_MediaType     = "MEDIATYPE"
	Parameter_CalendarScale = "CALSCALE"
	Parameter_SortAs        = "SORT-AS" // values are case-sensitive
	Parameter_Geolocation   = "GEO"
	Parameter_Timezone      = "TZ"
)

Parameter names.

type Data

❖ 
type Data struct {
	Properties []Property
	// contains filtered or unexported fields
}

Data represents a vCard

func New

❖ 
func New(properties ...Property) Data

New creates a new vCard 4.0 (a ProductID property is added, if missing)

Example 
package main

import (
	"bytes"
	"fmt"
	"log"
	"strings"
	"time"

	"code.pfad.fr/gopim/vcard"
)

func main() {
	names := vcard.Names{}.
		WithFamilyName("Public").
		WithGivenName("John").
		WithAdditionalName("Quinlan", "Paul").
		WithHonorificPrefix("Mr.").
		WithHonorificSuffix("Esq.")
	d := vcard.New(
		vcard.Property{
			Name:  vcard.Property_FormattedName,
			Value: names.FormattedName(),
		},
		names.ToProperty(),
		vcard.Revision(time.Date(1996, 10, 22, 14, 00, 00, 0, time.UTC)),
		vcard.Property{
			Name:  vcard.Property_UID,
			Value: vcard.NewPropertyTexts("123"),
		},
		vcard.OrganizationLevels{"ABC, Inc.", "North American Division"}.ToProperty(),
		vcard.Property{
			Name:  vcard.Property_Email,
			Value: vcard.NewPropertyTexts("jqpublic@xyz.example.com"),
		}.WithType(vcard.ParameterType_Work),
		vcard.Property{
			Name:  vcard.Property_Telephone,
			Value: vcard.NewPropertyTexts("tel:+1-418-656-9254;ext=102"),
		}.WithValue("uri").WithType(vcard.ParameterType_Work, vcard.ParameterType_Voice).WithPreference(1),
		vcard.Property{
			Name:  vcard.Property_Telephone,
			Value: vcard.NewPropertyTexts("tel:+1-418-262-6501"),
		}.WithValue("uri").WithType(vcard.ParameterType_Work, vcard.ParameterType_Cell, vcard.ParameterType_Voice, vcard.ParameterType_Video, vcard.ParameterType_Text),
	)
	var buf bytes.Buffer
	err := vcard.NewEncoder(&buf).Encode(d)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(strings.ReplaceAll(buf.String(), "\r\n", "\n"))
}

Output:

BEGIN:VCARD
VERSION:4.0
FN:Mr. John Q. Public\, Esq.
N:Public;John;Quinlan,Paul;Mr.;Esq.
REV:19961022T140000Z
UID:123
ORG:ABC\, Inc.;North American Division
EMAIL;TYPE=work:jqpublic@xyz.example.com
TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102
TEL;VALUE=uri;TYPE="work,cell,voice,video,text":tel:+1-418-262-6501
PRODID:-//GoPim//code.pfad.fr/gopim/vcard (devel)//EN
END:VCARD

func (Data) Categories

❖ 
func (d Data) Categories() []string

Category information about the vCard, also known as "tags". rfc6350#section-6.7.1

func (Data) Gender

❖ 
func (d Data) Gender() (sex Sex, identity PropertyValue)

Sex and gender identity. rfc6350#section-6.2.7

func (Data) Kind

❖ 
func (d Data) Kind() Kind

Kind of object the vCard represents rfc6350#section-6.1.4

func (Data) Names

❖ 
func (d Data) Names() (n Names, ok bool)

Names returns the preferred names. rfc6350#section-6.2.2

func (*Data) PropertyDelete

❖ 
func (d *Data) PropertyDelete(name string)

PropertyDelete removes all properties with the given name

func (Data) PropertyFirst

❖ 
func (d Data) PropertyFirst(name string) (p Property, ok bool)

func (Data) PropertyPreferred

❖ 
func (d Data) PropertyPreferred(name string) (p Property, ok bool)

PropertyPreferred returns the property with the highest preference

func (Data) Revision

❖ 
func (d Data) Revision() time.Time

Revision information about the current vCard. rfc6350#section-6.7.4

func (Data) Validate

❖ 
func (d Data) Validate() (err error)

func (Data) Version

❖ 
func (d Data) Version() Version

type Decoder

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

A Decoder parses vcard.Data

func NewDecoder

❖ 
func NewDecoder(r io.Reader) Decoder

NewDecoder creates a new Decoder reading vcard.Data from an io.Reader.

Example 
package main

import (
	"fmt"
	"log"
	"os"

	"code.pfad.fr/gopim/vcard"
)

func main() {
	f, err := os.Open("testdata/rfc_example/7.2.4_boss.vcf")
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()
	d, err := vcard.NewDecoder(f).Decode()
	if err != nil {
		log.Fatal(err)
	}
	p, ok := d.PropertyPreferred(vcard.Property_FormattedName)
	fmt.Println(ok, p.Value.SplitTexts()[0])
	p, ok = d.PropertyPreferred(vcard.Property_Telephone)
	fmt.Println(ok, p.Value.SplitTexts()[0])
}

Output:

true J. Doe
true tel:+1-555-555-5555

func (Decoder) Decode

❖ 
func (dec Decoder) Decode() (Data, error)

Decode parses a single vcard.Data.

type Encoder

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

An Encoder encodes Data in the vCard format.

func NewEncoder

❖ 
func NewEncoder(w io.Writer) Encoder

NewEncoder creates a new Encoder. See New for a usage example.

func (Encoder) Encode

❖ 
func (enc Encoder) Encode(d Data) error

Encode write a single Data in the vCard format to the underlying io.Writer

type Kind

❖ 
type Kind string

Kind is a data kind.

❖ 
const (
	Kind_Individual   Kind = "individual"
	Kind_Group        Kind = "group"
	Kind_Organization Kind = "org"
	Kind_Location     Kind = "location"
)

func (Kind) IsKnown

❖ 
func (k Kind) IsKnown() bool

func (Kind) ToProperty

❖ 
func (k Kind) ToProperty() Property

type Names

❖ 
type Names struct {
	FamilyName      []string
	GivenName       []string
	AdditionalName  []string
	HonorificPrefix []string
	HonorificSuffix []string
}

func (Names) FormattedName

❖ 
func (n Names) FormattedName() PropertyValue

FormattedName returns a likely representation of the formatted name (skipping empty elements): 

HonorificPrefix[0] GivenName[0] AdditionalName[0][0]. FamilyName[0], HonorificSuffix[0]

func (Names) ToProperty

❖ 
func (n Names) ToProperty() Property

func (Names) WithAdditionalName

❖ 
func (n Names) WithAdditionalName(s ...string) Names

func (Names) WithFamilyName

❖ 
func (n Names) WithFamilyName(s ...string) Names

func (Names) WithGivenName

❖ 
func (n Names) WithGivenName(s ...string) Names

func (Names) WithHonorificPrefix

❖ 
func (n Names) WithHonorificPrefix(s ...string) Names

func (Names) WithHonorificSuffix

❖ 
func (n Names) WithHonorificSuffix(s ...string) Names

type OrganizationLevels

❖ 
type OrganizationLevels []string

func (OrganizationLevels) ToProperty

❖ 
func (ol OrganizationLevels) ToProperty() Property

type Parameter

❖ 
type Parameter struct {
	Name   string
	Values []string
}

type ParameterType

❖ 
type ParameterType string

ParameterType is for Parameter_Type.

❖ 
const (
	// Generic
	ParameterType_Home ParameterType = "home"
	ParameterType_Work ParameterType = "work"

	// For FieldTelephone
	ParameterType_Text      ParameterType = "text"
	ParameterType_Voice     ParameterType = "voice" // Default
	ParameterType_Fax       ParameterType = "fax"
	ParameterType_Cell      ParameterType = "cell"
	ParameterType_Video     ParameterType = "video"
	ParameterType_Pager     ParameterType = "pager"
	ParameterType_TextPhone ParameterType = "textphone"

	// For FieldRelated
	ParameterType_Contact      ParameterType = "contact"
	ParameterType_Acquaintance ParameterType = "acquaintance"
	ParameterType_Friend       ParameterType = "friend"
	ParameterType_Met          ParameterType = "met"
	ParameterType_CoWorker     ParameterType = "co-worker"
	ParameterType_Colleague    ParameterType = "colleague"
	ParameterType_CoResident   ParameterType = "co-resident"
	ParameterType_Neighbor     ParameterType = "neighbor"
	ParameterType_Child        ParameterType = "child"
	ParameterType_Parent       ParameterType = "parent"
	ParameterType_Sibling      ParameterType = "sibling"
	ParameterType_Spouse       ParameterType = "spouse"
	ParameterType_Kin          ParameterType = "kin"
	ParameterType_Muse         ParameterType = "muse"
	ParameterType_Crush        ParameterType = "crush"
	ParameterType_Date         ParameterType = "date"
	ParameterType_Sweetheart   ParameterType = "sweetheart"
	ParameterType_Me           ParameterType = "me"
	ParameterType_Agent        ParameterType = "agent"
	ParameterType_Emergency    ParameterType = "emergency"
)

Known parameter types

func (ParameterType) IsKnown

❖ 
func (p ParameterType) IsKnown() bool

type Property

❖ 
type Property struct {
	Group      string
	Name       string
	Value      PropertyValue
	Parameters []Parameter
}

func Revision

❖ 
func Revision(t time.Time) Property

func (Property) ParameterValues

❖ 
func (p Property) ParameterValues(name string) (values []string)

ParameterValues returns the parameter values, as stored.

Note that according to rfc6350: Parameter values that are not explicitly defined as being case-sensitive are case-insensitive. (only SORT-AS is defined as case-sensitive).

func (Property) Preference

❖ 
func (p Property) Preference() uint8

Preference indicate that the corresponding instance of a property is preferred by the vCard author. Lower values correspond to a higher level of preference, with 1 being most preferred. 101 indicates an error parsing the value, 102 indicates no value

func (Property) Types

❖ 
func (p Property) Types() []ParameterType

func (Property) WithPreference

❖ 
func (p Property) WithPreference(i uint8) Property

WithPreference sets the preference between 1 and 100. Lower values correspond to a higher level of preference, with 1 being most preferred.

func (Property) WithType

❖ 
func (p Property) WithType(pt ...ParameterType) Property

func (Property) WithValue

❖ 
func (p Property) WithValue(v string) Property

type PropertyValue

❖ 
type PropertyValue string

PropertyValue stores the raw value of a Property.

func NewPropertyTexts

❖ 
func NewPropertyTexts(texts ...string) PropertyValue

NewPropertyTexts creates a new PropertyValue after escaping each text (backslash, newline, comma) and joining by comma.

func (PropertyValue) Names

❖ 
func (fv PropertyValue) Names() Names

func (PropertyValue) OrganizationLevels

❖ 
func (fv PropertyValue) OrganizationLevels() OrganizationLevels

func (PropertyValue) SplitTexts

❖ 
func (fv PropertyValue) SplitTexts() []string

SplitTexts returns the value parts of a Property, split by comma (each part being unescaped). Guaranteed to have a len > 0

func (PropertyValue) String

❖ 
func (fv PropertyValue) String() string

String returns the raw value

func (PropertyValue) Timestamp

❖ 
func (fv PropertyValue) Timestamp() (time.Time, error)

type Sex

❖ 
type Sex string

Sex is an object's biological sex.

❖ 
const (
	Sex_Unspecified Sex = ""
	Sex_Female      Sex = "F"
	Sex_Male        Sex = "M"
	Sex_Other       Sex = "O"
	Sex_None        Sex = "N"
	Sex_Unknown     Sex = "U"
)

func (Sex) IsKnown

❖ 
func (s Sex) IsKnown() bool

func (Sex) ToProperty

❖ 
func (s Sex) ToProperty(identity PropertyValue) Property

type Version

❖ 
type Version string
❖ 
const (
	Version2_1 Version = "2.1"
	Version3   Version = "3.0"
	Version4   Version = "4.0"
)

Source Files

decoder.go encoder.go vcard.go

Forge

https://codeberg.org/pfad.fr/gopim-vcard

git clone 
https://codeberg.org/pfad.fr/gopim-vcard.git
git@codeberg.org:pfad.fr/gopim-vcard.git
code.pfad.fr/gopim/vcard
main