vcard

package module
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Apr 3, 2025 License: MIT Imports: 13 Imported by: 2

Documentation

Overview

Package vcard implements the vCard format, as defined in RFC 6350. For usage examples refer to New to create a vCard and NewDecoder to read an existing vCard.

Basically, a vCard consists of a list of properties:

  • each Property has a name (see the `Property_` constants for the well-known names) and a PropertyValue
  • furthermore each Property can be refined by Parameters (to indicates metadata, see `Parameter_`)

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

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

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

View Source 
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"
	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.

View Source 
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.

Variables

This section is empty.

Functions

This section is empty.

Types

type Data 

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

Data represents a vCard

func New 

func New(version Version, properties ...Property) Data

New creates a new vCard (a ProductID property is added, if not provided)

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.Version3,
		vcard.Property{
			Name:  vcard.Property_FormattedName,
			Value: names.FormattedName(),
		},
		names.ToProperty(),
		vcard.Timestamp(time.Date(1996, 10, 22, 14, 00, 00, 0, time.UTC)).ToProperty(vcard.Property_Revision),
		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:3.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) Timestamp added in v0.6.0 

func (d Data) Timestamp(name string) (time.Time, bool)

Timestamp return the timestamp of the preferred property (like Property_Revision). rfc6350#section-6.7.4

func (Data) Validate 

func (d Data) Validate(extended bool) error

Validate checks if the properties fields have values that can be properly encoded into a vCard. If extended is true, more checks are performed (cardinality).

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 (Property) ParameterValues 

func (p Property) ParameterValues(name string) []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 (pv PropertyValue) Names() Names

func (PropertyValue) OrganizationLevels 

func (pv PropertyValue) OrganizationLevels() OrganizationLevels

func (PropertyValue) SplitTexts 

func (pv 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 (pv PropertyValue) String() string

String returns the raw value

func (PropertyValue) Timestamp 

func (pv 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) ToGenderProperty added in v0.5.0 

func (s Sex) ToGenderProperty(identity string) Property

rfc6350#section-6.2.7

type Timestamp added in v0.6.0 

type Timestamp time.Time

func (Timestamp) ToProperty added in v0.6.0 

func (t Timestamp) ToProperty(name string) Property

type Version 

type Version string
const (
	Version2_1 Version = "2.1"
	Version3   Version = "3.0" // recommended
	Version4   Version = "4.0" // iOS has encoding issues with 4.0 vcards (2025)
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.